@snaptrude/plugin-core 0.5.0 → 0.7.0

package/dist/api/entity/story.d.ts

@@ -1,5 +1,6 @@
 import * as z from "zod";
 import { PluginApiReturn } from "../../types";
+import { ComponentHandle } from "../../handles";
 /**
  * Story (floor/storey) management.
  *
@@ -90,17 +91,25 @@ export declare abstract class PluginStoryApi {
      */
     abstract create(storyValue: number, height?: number): PluginApiReturn<PluginStoryCreateResult>;
     /**
-     * Update a story's height.
+     * Update a story's floor-to-floor height, cascading the full geometry change.
      *
-     * Changes the floor-to-floor height of the specified story. This
-     * operation is undoable.
+     * This is the same operation as editing the height in the Stories panel: the
+     * walls, columns, and masses on the story are **stretched** to the new height,
+     * every story **above shifts up/down** by the delta so the stack stays
+     * contiguous, and coupled elements (staircases, parametric curtain walls,
+     * furniture offsets) are re-fitted. The whole cascade is committed as **one
+     * undo step**. Height-locked elements are left untouched.
      *
      * @param storyValue - Integer storey number
      *   identifying the story to update
-     * @param height - New height value in Babylon
-     *   units
+     * @param height - New floor-to-floor height in
+     *   Babylon units
      * @returns A {@linkcode PluginStoryUpdateResult} with the updated `storyValue` and `height`
-     * @throws If the story does not exist or the update fails
+     * @throws `PRECONDITION_FAILED` if no story has the given value;
+     *   `STORY_HEIGHT_REJECTED` if the engine rejects the height (e.g. out of
+     *   range — the change silently reverts host-side and is surfaced as this
+     *   error); `STORY_UPDATE_FAILED` if the story cannot be re-read after the
+     *   update
      *
      * @examplePrompt Change the ground floor height to 3.5 metres
      * @examplePrompt Make the second storey taller
@@ -109,11 +118,59 @@ export declare abstract class PluginStoryApi {
      *
      * # Example
      * ```ts
-     * // Set ground floor height to 5 Babylon units
+     * // Set ground floor height to 5 Babylon units — walls stretch and the
+     * // floors above move up to match, all in a single undo step.
      * const result = await snaptrude.entity.story.update(1, 5)
      * ```
      */
     abstract update(storyValue: number, height: number): PluginApiReturn<PluginStoryUpdateResult>;
+    /**
+     * Duplicate a story into the adjacent level, up or down.
+     *
+     * By default the **whole story** is duplicated: every eligible element on the
+     * active story (walls, floors, roofs, masses, columns, beams, staircases,
+     * ceilings, parametric curtain walls, and furniture) is copied into the story
+     * one level `"up"` or `"down"`. Pass `options.components` to duplicate only a
+     * subset instead. The target story is **created automatically** if it does not
+     * yet exist, inheriting the source story's height.
+     *
+     * Copies are **instanced** by default (`unique: false`) — they share geometry
+     * with the source, so later edits propagate. Set `unique: true` for independent
+     * geometry. Doors and windows are never duplicated on their own; they ride along
+     * with their host wall. Locked, throw-away, and unsupported elements are skipped
+     * and counted in `skipped`. The whole operation is a single undo step.
+     *
+     * @param direction - `"up"` to duplicate into the story above, `"down"` for below
+     * @param options - `components` (restrict to a subset of the story's elements;
+     *   omit for the whole story) and `unique` (default `false` = instanced copies;
+     *   `true` = independent geometry)
+     * @returns A {@linkcode PluginStoryDuplicateResult} with the `sourceStory`, the
+     *   `targetStories` the copies landed on, the `created` component handles, the
+     *   `createdStoryValues` for any stories generated to receive them, and the
+     *   `skipped` count of ineligible elements
+     * @throws `NO_ACTIVE_STRUCTURE` if there is no active structure to duplicate
+     *   into; `NO_ELIGIBLE_ELEMENTS` if nothing on the source story (or in
+     *   `options.components`) is duplicable; `HANDLE_INVALID` for a stale or
+     *   foreign supplied handle; or if plugin writes are disabled
+     *
+     * @examplePrompt Duplicate this floor to the storey above
+     * @examplePrompt Copy the ground floor down into a new basement
+     * @examplePrompt Repeat this level upwards with its own independent geometry
+     * @examplePrompt Duplicate just the selected walls onto the next floor up
+     *
+     * # Example
+     * ```ts
+     * // Duplicate the whole active story one level up (instanced copies).
+     * const { targetStories, created, skipped } =
+     *   await snaptrude.entity.story.duplicate("up")
+     * console.log(`Copied ${created.length} elements onto story ${targetStories}`)
+     * if (skipped) console.log(`${skipped} elements were skipped`)
+     * ```
+     */
+    abstract duplicate(direction: "up" | "down", options?: {
+        components?: ComponentHandle[];
+        unique?: boolean;
+    }): PluginApiReturn<PluginStoryDuplicateResult>;
 }
 /**
  * Available properties that can be queried on a story.
@@ -246,4 +303,41 @@ export declare const PluginStoryUpdateResult: z.ZodObject<{
     height: z.ZodNumber;
 }, z.core.$strip>;
 export type PluginStoryUpdateResult = z.infer<typeof PluginStoryUpdateResult>;
+/**
+ * Arguments for {@linkcode PluginStoryApi.duplicate} (options flattened).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `direction` | `'up' \| 'down'` | Which adjacent story to duplicate into |
+ * | `components` | {@linkcode ComponentHandle}`[]?` | Restrict to a subset; omit for the whole story |
+ * | `unique` | `boolean?` | `false` (default) = instanced copies; `true` = independent geometry |
+ */
+export declare const PluginStoryDuplicateArgs: z.ZodObject<{
+    direction: z.ZodEnum<{
+        up: "up";
+        down: "down";
+    }>;
+    components: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>>>;
+    unique: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type PluginStoryDuplicateArgs = z.infer<typeof PluginStoryDuplicateArgs>;
+/**
+ * Result of {@linkcode PluginStoryApi.duplicate}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sourceStory` | `number` | Storey value the copies were duplicated from |
+ * | `targetStories` | `number[]` | Storey values the copies landed on |
+ * | `created` | {@linkcode ComponentHandle}`[]` | Handles of the newly created components |
+ * | `createdStoryValues` | `number[]` | Storey values that were generated to receive the copies |
+ * | `skipped` | `number` | Count of ineligible elements that were skipped |
+ */
+export declare const PluginStoryDuplicateResult: z.ZodObject<{
+    sourceStory: z.ZodNumber;
+    targetStories: z.ZodArray<z.ZodNumber>;
+    created: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>>;
+    createdStoryValues: z.ZodArray<z.ZodNumber>;
+    skipped: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginStoryDuplicateResult = z.infer<typeof PluginStoryDuplicateResult>;
 //# sourceMappingURL=story.d.ts.map

package/dist/api/entity/story.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"story.d.ts","sourceRoot":"","sources":["../../../src/api/entity/story.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7C;;;;;;;;;;;GAWG;AACH,8BAAsB,cAAc;;IAGlC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;aACa,GAAG,CACjB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,sBAAsB,EAAE,GACnC,eAAe,CAAC,oBAAoB,CAAC;IAExC;;;;;;;;;;;;;;;;;;;;;OAqBG;aACa,MAAM,IAAI,eAAe,CAAC,uBAAuB,CAAC;IAElE;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;aACa,MAAM,CACpB,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,MAAM,GACd,eAAe,CAAC,uBAAuB,CAAC;IAE3C;;;;;;;;;;;;;;;;;;;;;;;OAuBG;aACa,MAAM,CACpB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,GACb,eAAe,CAAC,uBAAuB,CAAC;CAC5C;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;EASjC,CAAA;AAEF,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAE3E;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;iBAG7B,CAAA;AAEF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAA;AAEnE;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;iBAWrB,CAAA;AAEZ,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAEvE;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB;;;;;;iBAQlC,CAAA;AAEF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAE7E;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB;;;iBAGhC,CAAA;AAEF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAEzE;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB;;;iBAGlC,CAAA;AAEF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAE7E;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB;;;iBAGhC,CAAA;AAEF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAEzE;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB;;;iBAGlC,CAAA;AAEF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAA"}
+{"version":3,"file":"story.d.ts","sourceRoot":"","sources":["../../../src/api/entity/story.ts"],"names":[],"mappings":"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"}

package/dist/api/index.d.ts

@@ -3,6 +3,7 @@ import { PluginDesignApi } from "./design";
 import { PluginEntityApi } from "./entity";
 import { PluginProgramApi } from "./program";
 import { PluginPresentationApi } from "./presentation";
+import { PluginAnalysisApi } from "./analysis";
 /**
  * Root API surface for Snaptrude plugins.
  *
@@ -13,6 +14,7 @@ import { PluginPresentationApi } from "./presentation";
  * - {@linkcode PluginApi.entity} — CRUD operations on Snaptrude entities (spaces, stories)
  * - {@linkcode PluginApi.program} — Program-mode planning reads (departments, metrics)
  * - {@linkcode PluginApi.presentation} — Presentation preparation (views, AI Inspiration)
+ * - {@linkcode PluginApi.analysis} — Sustainability analysis (sunpath, shadows, sunlight/illuminance heatmaps)
  */
 export declare abstract class PluginApi {
     /** Core math, geometry, history, and units primitives. See {@linkcode PluginCoreApi}. */
@@ -25,6 +27,8 @@ export declare abstract class PluginApi {
     abstract program: PluginProgramApi;
     /** Presentation preparation reads — saved views. See {@linkcode PluginPresentationApi}. */
     abstract presentation: PluginPresentationApi;
+    /** Sustainability analysis — sun & daylight studies. See {@linkcode PluginAnalysisApi}. */
+    abstract analysis: PluginAnalysisApi;
     constructor();
 }
 export * from "./core";
@@ -32,4 +36,5 @@ export * from "./design";
 export * from "./entity";
 export * from "./program";
 export * from "./presentation";
+export * from "./analysis";
 //# sourceMappingURL=index.d.ts.map

package/dist/api/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA;AACtC,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAC5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AAEtD;;;;;;;;;;GAUG;AACH,8BAAsB,SAAS;IAC7B,yFAAyF;IACzF,SAAgB,IAAI,EAAE,aAAa,CAAA;IACnC,0EAA0E;IAC1E,SAAgB,MAAM,EAAE,eAAe,CAAA;IACvC,8EAA8E;IAC9E,SAAgB,MAAM,EAAE,eAAe,CAAA;IACvC,oGAAoG;IACpG,SAAgB,OAAO,EAAE,gBAAgB,CAAA;IACzC,2FAA2F;IAC3F,SAAgB,YAAY,EAAE,qBAAqB,CAAA;;CAGpD;AAED,cAAc,QAAQ,CAAA;AACtB,cAAc,UAAU,CAAA;AACxB,cAAc,UAAU,CAAA;AACxB,cAAc,WAAW,CAAA;AACzB,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA;AACtC,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAC5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAE9C;;;;;;;;;;;GAWG;AACH,8BAAsB,SAAS;IAC7B,yFAAyF;IACzF,SAAgB,IAAI,EAAE,aAAa,CAAA;IACnC,0EAA0E;IAC1E,SAAgB,MAAM,EAAE,eAAe,CAAA;IACvC,8EAA8E;IAC9E,SAAgB,MAAM,EAAE,eAAe,CAAA;IACvC,oGAAoG;IACpG,SAAgB,OAAO,EAAE,gBAAgB,CAAA;IACzC,2FAA2F;IAC3F,SAAgB,YAAY,EAAE,qBAAqB,CAAA;IACnD,2FAA2F;IAC3F,SAAgB,QAAQ,EAAE,iBAAiB,CAAA;;CAG5C;AAED,cAAc,QAAQ,CAAA;AACtB,cAAc,UAAU,CAAA;AACxB,cAAc,UAAU,CAAA;AACxB,cAAc,WAAW,CAAA;AACzB,cAAc,gBAAgB,CAAA;AAC9B,cAAc,YAAY,CAAA"}

package/dist/api/presentation/import.d.ts

@@ -3,9 +3,10 @@ import { PluginApiReturn } from "../../types";
 /**
  * Presentation import — bring external reference assets onto the Present canvas.
  *
- * `import.image` places a reference image and `import.pdf` places a PDF (each
- * page vectorized to SVG) onto the current Present sheet, returning the created
- * canvas shape ids. Requires Present mode to be open.
+ * `import.image` places a reference image, `import.pdf` places a PDF (each
+ * page vectorized to SVG), and `import.svg` places a validated SVG onto
+ * the current Present sheet, returning the created canvas shape ids. Requires
+ * Present mode to be open.
  *
  * The host engine takes a browser `File`, which a plugin worker cannot supply,
  * so these accept a `url`/`dataUrl` that the host adapts into a `File`.
@@ -79,10 +80,54 @@ export declare abstract class PluginPresentationImportApi {
             y: number;
         };
     }): PluginApiReturn<PluginPresentationImportResult>;
+    /**
+     * Import an SVG onto the current Present sheet as a vector asset.
+     *
+     * An SVG-validating variant of {@linkcode PluginPresentationImportApi.image}:
+     * `import.image` already passes SVG sources through, but this method first
+     * validates that the source really is an SVG and forces the vector mime
+     * type. Throws if the source is not an SVG.
+     *
+     * **Rendering is vector up to a complexity cap.** Simple SVGs (up to ~1500
+     * SVG element nodes and ~2 MB) render true-vector and stay crisp at every
+     * zoom. Beyond that cap the shared canvas renderer **intentionally falls
+     * back to a 1920px raster** to protect canvas performance, so very complex
+     * SVGs can look rasterized when zoomed in. The stored asset is the original
+     * SVG either way; only the on-canvas rendering falls back.
+     *
+     * @param source - The SVG to import: exactly one of `url` or `dataUrl`.
+     * @param options - Optional `position` — where to place the SVG on the sheet.
+     * @returns A {@linkcode PluginPresentationImportResult} with the created
+     *   `shapeIds`.
+     * @throws If Present mode is not open, the source is not an SVG, or it cannot
+     *   be loaded.
+     *
+     * @examplePrompt Import this SVG diagram onto the present canvas
+     * @examplePrompt Add a vector logo to my presentation board
+     * @examplePrompt Place this SVG floor plan on the current sheet as vectors
+     * @examplePrompt Bring a crisp vector graphic into Present mode
+     *
+     * # Example
+     * ```ts
+     * const { shapeIds } = await snaptrude.presentation.import.svg({
+     *   url: "https://example.com/diagram.svg",
+     * })
+     * ```
+     */
+    abstract svg(source: {
+        url?: string;
+        dataUrl?: string;
+    }, options?: {
+        position?: {
+            x: number;
+            y: number;
+        };
+    }): PluginApiReturn<PluginPresentationImportResult>;
 }
 /**
  * Arguments for {@linkcode PluginPresentationImportApi.image} /
- * {@linkcode PluginPresentationImportApi.pdf}. Provide exactly one source.
+ * {@linkcode PluginPresentationImportApi.pdf} /
+ * {@linkcode PluginPresentationImportApi.svg}. Provide exactly one source.
  *
  * | Property | Type | Description |
  * |---|---|---|

package/dist/api/presentation/import.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"import.d.ts","sourceRoot":"","sources":["../../../src/api/presentation/import.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7C;;;;;;;;;;;GAWG;AACH,8BAAsB,2BAA2B;;IAG/C;;;;;;;;;;;;;;;;;;;;;;OAsBG;aACa,KAAK,CACnB,MAAM,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,EAC1C,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GAChD,eAAe,CAAC,8BAA8B,CAAC;IAElD;;;;;;;;;;;;;;;;;;;;;;;OAuBG;aACa,GAAG,CACjB,MAAM,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,EAC1C,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GAChD,eAAe,CAAC,8BAA8B,CAAC;CACnD;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,4BAA4B;;;;;;;iBAQrC,CAAA;AACJ,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAChD,OAAO,4BAA4B,CACpC,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,8BAA8B;;iBAEzC,CAAA;AACF,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,KAAK,CAClD,OAAO,8BAA8B,CACtC,CAAA"}
+{"version":3,"file":"import.d.ts","sourceRoot":"","sources":["../../../src/api/presentation/import.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7C;;;;;;;;;;;;GAYG;AACH,8BAAsB,2BAA2B;;IAG/C;;;;;;;;;;;;;;;;;;;;;;OAsBG;aACa,KAAK,CACnB,MAAM,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,EAC1C,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GAChD,eAAe,CAAC,8BAA8B,CAAC;IAElD;;;;;;;;;;;;;;;;;;;;;;;OAuBG;aACa,GAAG,CACjB,MAAM,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,EAC1C,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GAChD,eAAe,CAAC,8BAA8B,CAAC;IAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;aACa,GAAG,CACjB,MAAM,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,EAC1C,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GAChD,eAAe,CAAC,8BAA8B,CAAC;CACnD;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B;;;;;;;iBAQrC,CAAA;AACJ,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAChD,OAAO,4BAA4B,CACpC,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,8BAA8B;;iBAEzC,CAAA;AACF,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,KAAK,CAClD,OAAO,8BAA8B,CACtC,CAAA"}

package/dist/api/presentation/views.d.ts

@@ -5,12 +5,12 @@ import { PluginApiReturn } from "../../types";
  *
  * A **view** is a saved camera/plan: a sheet-ready 2D plan or a saved 3D view.
  * A plugin can list and read views, capture them to images, activate one (move
- * the camera to it), and save the current camera as a new view.
+ * the camera to it), save the current camera as a new view, and read/update a
+ * view's display settings (background, color mode, axis, edges, labels).
  *
- * `list`/`get`/`getActive`/`capture` are reads; `setActive`/`create` are writes
- * (a view is a camera bookmark — not geometry). Members typed optional (`?`) are
- * authored ahead of the host: declared for plugins/codegen but not yet on the
- * live discovery surface until the host lands them.
+ * `list`/`get`/`getActive`/`capture`/`getSettings` are reads;
+ * `setActive`/`create`/`updateSettings` are writes (a view is a camera bookmark
+ * — not geometry).
  *
  * Accessed via `snaptrude.presentation.views`.
  */
@@ -141,6 +141,78 @@ export declare abstract class PluginPresentationViewsApi {
     abstract create(name?: string, options?: {
         kind?: "view" | "sitePlan";
     }): PluginApiReturn<PluginPresentationViewsCreateResult>;
+    /**
+     * Read a saved view's display settings (background, color mode, axis, edges,
+     * labels).
+     *
+     * @param viewId - The id of the view to read settings for.
+     * @returns The view's {@linkcode PluginPresentationViewSettings}, or `null` if
+     *   no view has that id.
+     *
+     * @examplePrompt What color mode is the Ground Floor view using?
+     * @examplePrompt Get the display settings for this view
+     * @examplePrompt Does the site plan view show axes and labels?
+     * @examplePrompt Read the background color of the active view
+     *
+     * # Example
+     * ```ts
+     * const settings = await snaptrude.presentation.views.getSettings("view_123")
+     * if (settings) console.log(settings.colorMode, settings.backgroundColor)
+     * ```
+     */
+    abstract getSettings(viewId: string): PluginApiReturn<PluginPresentationViewsGetSettingsResult>;
+    /**
+     * Update a saved view's display settings (partial patch — only the fields you
+     * pass change).
+     *
+     * Persists and broadcasts the change; if the view is currently active, the
+     * scene updates live. **Not Ctrl+Z-undoable** — view-metadata edits publish
+     * directly and do not land on the local undo stack; this matches how the
+     * product's own view-settings UI behaves.
+     *
+     * Label patch semantics (mirroring the product, which stores no label
+     * selection while labels are off):
+     *
+     * - `{ showLabels: true }` alone turns labels on; if the view has no stored
+     *   selection, the product defaults (`objectLabels`, `areas`) are applied —
+     *   labels are never "on" with an empty selection (the product has no such
+     *   state; labels render only while the selection is non-empty).
+     * - `{ labels: [...] }` alone sets the selection **and turns labels on**.
+     * - `{ showLabels: false }` turns labels off and **clears the stored
+     *   selection** — a later read returns `labels: []`.
+     * - `{ showLabels: false, labels: [...] }` with a non-empty list is
+     *   contradictory and **rejected** (nothing is silently discarded).
+     * - `{ showLabels: true, labels: [] }` is likewise contradictory and
+     *   **rejected** — pass a non-empty list, or omit `labels` to get the
+     *   defaults.
+     *
+     * `colorMode` accepts the `tag:<categoryId>` scheme strings returned by
+     * {@linkcode PluginPresentationViewsApi.getSettings}, so read-then-write
+     * round-trips a tag-based color scheme unchanged.
+     *
+     * @param viewId - The id of the view to update.
+     * @param settings - A partial {@linkcode PluginPresentationViewSettings}; any
+     *   omitted field is left unchanged.
+     * @returns The updated view's `id`.
+     * @throws If writes are disabled, no view has the given id, or the patch is
+     *   contradictory (`showLabels: false` with a non-empty `labels`, or
+     *   `showLabels: true` with an explicitly empty `labels` list).
+     *
+     * @examplePrompt Switch this view to monochrome color mode
+     * @examplePrompt Turn off the axis in the Ground Floor view
+     * @examplePrompt Set the background of the active view to white
+     * @examplePrompt Show area labels on this view
+     * @examplePrompt Enable hidden-line mode for the section view
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.presentation.views.updateSettings("view_123", {
+     *   colorMode: "monochrome",
+     *   showAxis: false,
+     * })
+     * ```
+     */
+    abstract updateSettings(viewId: string, settings: Partial<PluginPresentationViewSettings>): PluginApiReturn<PluginPresentationViewsUpdateSettingsResult>;
 }
 /**
  * The kind of a saved view: a 2D plan view or a 3D view.
@@ -293,4 +365,137 @@ export declare const PluginPresentationViewsCreateResult: z.ZodObject<{
     isActive: z.ZodBoolean;
 }, z.core.$strip>;
 export type PluginPresentationViewsCreateResult = z.infer<typeof PluginPresentationViewsCreateResult>;
+/**
+ * How the scene is colored in a view.
+ *
+ * | Value | Meaning |
+ * |---|---|
+ * | `monochrome` | Flat single-tone shading |
+ * | `texture` | Material textures/colors |
+ * | `department` | Colored by department |
+ * | `tag:<categoryId>` | Colored by a project tag category (e.g. `tag:ZONE`) |
+ *
+ * The `tag:<categoryId>` form carries the product's tag-based color schemes
+ * losslessly — reading a view that uses one returns the `tag:` string as-is,
+ * and writing it back preserves the scheme (read-then-write is safe).
+ */
+export declare const PluginPresentationViewColorMode: z.ZodUnion<readonly [z.ZodEnum<{
+    department: "department";
+    monochrome: "monochrome";
+    texture: "texture";
+}>, z.ZodTemplateLiteral<`tag:${string}`>]>;
+export type PluginPresentationViewColorMode = z.infer<typeof PluginPresentationViewColorMode>;
+/**
+ * A category of on-canvas labels a view can show.
+ *
+ * | Value | Meaning |
+ * |---|---|
+ * | `objectLabels` | Per-object name labels |
+ * | `areas` | Area/room labels |
+ * | `department` | Department labels |
+ */
+export declare const PluginPresentationViewLabel: z.ZodEnum<{
+    department: "department";
+    objectLabels: "objectLabels";
+    areas: "areas";
+}>;
+export type PluginPresentationViewLabel = z.infer<typeof PluginPresentationViewLabel>;
+/**
+ * A view's display settings.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `backgroundColor` | `string` | Canvas background as a hex color (e.g. `#ffffff`) |
+ * | `colorMode` | {@linkcode PluginPresentationViewColorMode} | How the scene is colored (including `tag:<categoryId>` schemes) |
+ * | `showAxis` | `boolean` | Whether the X/Y/Z axes are shown |
+ * | `showEdges` | `boolean` | Whether edges are shown; `false` = hidden-line rendering |
+ * | `showLabels` | `boolean` | Master label switch — whether on-canvas labels are shown at all. `true` always pairs with a non-empty `labels` selection (labels render only while the selection is non-empty; there is no labels-on-with-empty-selection state) |
+ * | `labels` | {@linkcode PluginPresentationViewLabel}`[]` | Which label categories are selected. When `showLabels` is `false` the view stores no selection and this reads `[]` |
+ */
+export declare const PluginPresentationViewSettings: z.ZodObject<{
+    backgroundColor: z.ZodString;
+    colorMode: z.ZodUnion<readonly [z.ZodEnum<{
+        department: "department";
+        monochrome: "monochrome";
+        texture: "texture";
+    }>, z.ZodTemplateLiteral<`tag:${string}`>]>;
+    showAxis: z.ZodBoolean;
+    showEdges: z.ZodBoolean;
+    showLabels: z.ZodBoolean;
+    labels: z.ZodArray<z.ZodEnum<{
+        department: "department";
+        objectLabels: "objectLabels";
+        areas: "areas";
+    }>>;
+}, z.core.$strip>;
+export type PluginPresentationViewSettings = z.infer<typeof PluginPresentationViewSettings>;
+/**
+ * Arguments for {@linkcode PluginPresentationViewsApi.getSettings}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The id of the view to read settings for |
+ */
+export declare const PluginPresentationViewsGetSettingsArgs: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+export type PluginPresentationViewsGetSettingsArgs = z.infer<typeof PluginPresentationViewsGetSettingsArgs>;
+/**
+ * Result of {@linkcode PluginPresentationViewsApi.getSettings} — the settings,
+ * or `null` when no view has that id.
+ */
+export declare const PluginPresentationViewsGetSettingsResult: z.ZodNullable<z.ZodObject<{
+    backgroundColor: z.ZodString;
+    colorMode: z.ZodUnion<readonly [z.ZodEnum<{
+        department: "department";
+        monochrome: "monochrome";
+        texture: "texture";
+    }>, z.ZodTemplateLiteral<`tag:${string}`>]>;
+    showAxis: z.ZodBoolean;
+    showEdges: z.ZodBoolean;
+    showLabels: z.ZodBoolean;
+    labels: z.ZodArray<z.ZodEnum<{
+        department: "department";
+        objectLabels: "objectLabels";
+        areas: "areas";
+    }>>;
+}, z.core.$strip>>;
+export type PluginPresentationViewsGetSettingsResult = z.infer<typeof PluginPresentationViewsGetSettingsResult>;
+/**
+ * Arguments for {@linkcode PluginPresentationViewsApi.updateSettings}. The
+ * `settings` patch is partial — any omitted field is left unchanged. A patch
+ * pairing `showLabels: false` with a non-empty `labels` list, or
+ * `showLabels: true` with an explicitly empty `labels` list, is rejected as
+ * contradictory (see the method JSDoc for the full label patch semantics).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The id of the view to update |
+ * | `settings` | `Partial<`{@linkcode PluginPresentationViewSettings}`>` | The fields to change |
+ */
+export declare const PluginPresentationViewsUpdateSettingsArgs: z.ZodObject<{
+    id: z.ZodString;
+    settings: z.ZodObject<{
+        backgroundColor: z.ZodOptional<z.ZodString>;
+        colorMode: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+            department: "department";
+            monochrome: "monochrome";
+            texture: "texture";
+        }>, z.ZodTemplateLiteral<`tag:${string}`>]>>;
+        showAxis: z.ZodOptional<z.ZodBoolean>;
+        showEdges: z.ZodOptional<z.ZodBoolean>;
+        showLabels: z.ZodOptional<z.ZodBoolean>;
+        labels: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            department: "department";
+            objectLabels: "objectLabels";
+            areas: "areas";
+        }>>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type PluginPresentationViewsUpdateSettingsArgs = z.infer<typeof PluginPresentationViewsUpdateSettingsArgs>;
+/** Result of {@linkcode PluginPresentationViewsApi.updateSettings} — the updated view's id. */
+export declare const PluginPresentationViewsUpdateSettingsResult: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+export type PluginPresentationViewsUpdateSettingsResult = z.infer<typeof PluginPresentationViewsUpdateSettingsResult>;
 //# sourceMappingURL=views.d.ts.map

package/dist/api/presentation/views.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"views.d.ts","sourceRoot":"","sources":["../../../src/api/presentation/views.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"views.d.ts","sourceRoot":"","sources":["../../../src/api/presentation/views.ts"],"names":[],"mappings":"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"}

package/dist/api/program/areas.d.ts

@@ -10,15 +10,25 @@ import { ComponentHandle } from "../../handles";
  * department-allocation lens (targets vs allocated area per department); this
  * namespace is the whole-program area/FAR summary and its groupings.
  *
+ * **Net vs gross:** the `carpet` / `builtUp` / `excluded` figures are the three
+ * area *classes* — every space's whole footprint lands in exactly one, chosen
+ * by its `areaClass` (see {@linkcode PluginProgramAreaMember.areaClass}). In UI
+ * terms `carpet` is the **Net Internal Area** (Σ of `NET`-classed spaces), and
+ * `builtUp` is the **Gross External Area** (Σ of `GROSS`-classed spaces) — so
+ * "net" and "gross" are the plain-English synonyms for `carpet` and `builtUp`.
+ * These are not wall-thickness carpet-vs-super-built-up; there is no common-area
+ * math. Note the summary also folds in non-mass elements (floors count as NET,
+ * slabs as GROSS), so **summing `listMembers` spaces does not reconcile to the
+ * summary totals**.
+ *
  * `achievedFar` is **derived and read-only** — computed from built-up area and
  * site area. `targetFar` is the goal you set (via {@linkcode
  * PluginProgramAreasApi.update}); the two are the same ratio, one measured and
  * one intended. The surface speaks **FAR only** — there is no FSI alias.
  *
- * Reads return plain records and never throw. The write member typed as optional
- * (`?`) is **authored ahead of the host** — declared so plugins and codegen can
- * see the shape, but kept out of the discovery manifest until the host lands it
- * (at which point it is promoted to a required `abstract` member).
+ * Reads return plain records and never throw. The only write —
+ * {@linkcode PluginProgramAreasApi.update} — is a non-undoable settings write
+ * for the FAR inputs.
  *
  * Accessed via `snaptrude.program.areas`.
  */
@@ -35,6 +45,8 @@ export declare abstract class PluginProgramAreasApi {
      *
      * @examplePrompt What's my FAR right now?
      * @examplePrompt Give me the program area summary
+     * @examplePrompt What is my net internal area vs gross external area?
+     * @examplePrompt How much net and gross area do I have?
      * @examplePrompt How much built-up area have I used against the site area?
      * @examplePrompt Am I within my FAR target?
      *
@@ -58,6 +70,7 @@ export declare abstract class PluginProgramAreasApi {
      *   (empty when the program has no spaces).
      *
      * @examplePrompt Break down the area by storey
+     * @examplePrompt Break down net vs gross area by storey
      * @examplePrompt Show the area rollup per department
      * @examplePrompt Group the built-up area by building
      *
@@ -84,6 +97,7 @@ export declare abstract class PluginProgramAreasApi {
      *   array (empty when the group is missing or empty).
      *
      * @examplePrompt List the spaces on this storey with their areas
+     * @examplePrompt Which spaces are net and which are gross on this storey?
      * @examplePrompt What rooms are in the Bedrooms department bucket?
      * @examplePrompt Break the storey area down into individual spaces
      *
@@ -130,9 +144,9 @@ export declare abstract class PluginProgramAreasApi {
  * |---|---|---|
  * | `count` | `number` | Number of spaces in the program (a count, not an area) |
  * | `hiddenCount` | `number` | Number of those spaces that are currently hidden |
- * | `carpet` | `number` | Total carpet area in `areaUnit` |
- * | `builtUp` | `number` | Total built-up area in `areaUnit` |
- * | `excluded` | `number` | Total excluded area in `areaUnit` |
+ * | `carpet` | `number` | Total **Net Internal Area** ("net") — Σ `NET`-classed spaces + floors — in `areaUnit` |
+ * | `builtUp` | `number` | Total **Gross External Area** ("gross") — Σ `GROSS`-classed spaces + slabs — in `areaUnit` |
+ * | `excluded` | `number` | Total **Excluded Area** — Σ `EXCLUDED`-classed spaces — in `areaUnit` |
  * | `farBuiltUp` | `number` | Built-up area that counts toward FAR, in `areaUnit` |
  * | `siteArea` | `number` | Site/plot area in `areaUnit` |
  * | `achievedFar` | `number \| null` | Derived FAR (`farBuiltUp / siteArea`); `null` when site area or target FAR is unset |
@@ -167,8 +181,8 @@ export type PluginProgramAreaSummary = z.infer<typeof PluginProgramAreaSummary>;
  * | `groupId` | `string` | Stable id of the group (e.g. storey id, department id) |
  * | `name` | `string` | Display name of the group |
  * | `color` | `string` | CSS hex color string for the group |
- * | `carpet` | `number` | Carpet area for this group |
- * | `builtUp` | `number` | Built-up area for this group |
+ * | `carpet` | `number` | Net Internal Area ("net") for this group |
+ * | `builtUp` | `number` | Gross External Area ("gross") for this group |
  * | `excluded` | `number` | Excluded area for this group |
  * | `count` | `number` | Number of spaces in this group |
  * | `targetArea` | `number` | Target area for this group, in `targetUnit` |
@@ -193,18 +207,29 @@ export type PluginProgramAreaGroup = z.infer<typeof PluginProgramAreaGroup>;
  * A single space within an area group. Area figures are in the program's area
  * unit (see {@linkcode PluginProgramAreaSummary.areaUnit}).
  *
+ * `areaClass` is the space's effective classification — it decides which of the
+ * three buckets the space's whole footprint lands in: `NET` → `carpet` ("net"),
+ * `GROSS` → `builtUp` ("gross"), `EXCLUDED` → `excluded`. So for any one member
+ * exactly one of `carpet` / `builtUp` / `excluded` is non-zero.
+ *
  * | Property | Type | Description |
  * |---|---|---|
  * | `id` | `ComponentHandle` | `Component.id` of the space (never a mesh handle) |
  * | `label` | `string` | Display label of the space |
- * | `carpet` | `number` | Carpet area of the space |
- * | `builtUp` | `number` | Built-up area of the space |
- * | `excluded` | `number` | Excluded area of the space |
+ * | `areaClass` | {@linkcode PluginAreaClass} | Effective area class — `"NET"` (→ `carpet`), `"GROSS"` (→ `builtUp`), or `"EXCLUDED"` |
+ * | `carpet` | `number` | Net area of the space (non-zero when `areaClass` is `"NET"`) |
+ * | `builtUp` | `number` | Gross area of the space (non-zero when `areaClass` is `"GROSS"`) |
+ * | `excluded` | `number` | Excluded area of the space (non-zero when `areaClass` is `"EXCLUDED"`) |
  * | `isVisible` | `boolean` | Whether the space is currently visible |
  */
 export declare const PluginProgramAreaMember: z.ZodObject<{
     id: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
     label: z.ZodString;
+    areaClass: z.ZodEnum<{
+        NET: "NET";
+        GROSS: "GROSS";
+        EXCLUDED: "EXCLUDED";
+    }>;
     carpet: z.ZodNumber;
     builtUp: z.ZodNumber;
     excluded: z.ZodNumber;
@@ -313,6 +338,11 @@ export declare const PluginProgramAreasListMembersResult: z.ZodObject<{
     members: z.ZodArray<z.ZodObject<{
         id: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
         label: z.ZodString;
+        areaClass: z.ZodEnum<{
+            NET: "NET";
+            GROSS: "GROSS";
+            EXCLUDED: "EXCLUDED";
+        }>;
         carpet: z.ZodNumber;
         builtUp: z.ZodNumber;
         excluded: z.ZodNumber;