@snaptrude/plugin-core 0.7.0 → 0.8.0

package/src/api/presentation/views.ts

@@ -6,12 +6,14 @@ 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), save the current camera as a new view, and read/update a
- * view's display settings (background, color mode, axis, edges, labels).
+ * the camera to it), save the current camera as a new view, rename or delete a
+ * saved view, and read/update a view's display settings (background, color
+ * mode, view mode, axis, edges, labels). Each view carries the `storey` it was
+ * saved on.
  *
  * `list`/`get`/`getActive`/`capture`/`getSettings` are reads;
- * `setActive`/`create`/`updateSettings` are writes (a view is a camera bookmark
- * — not geometry).
+ * `setActive`/`create`/`rename`/`delete`/`updateSettings` are writes (a view is
+ * a camera bookmark — not geometry).
  *
  * Accessed via `snaptrude.presentation.views`.
  */
@@ -135,28 +137,35 @@ export abstract class PluginPresentationViewsApi {
    * Creates a camera bookmark (not geometry) from where the camera is now.
    *
    * @param name - Name for the new view (a default is used when omitted).
-   * @param options - Optional `kind`: what kind of view to save (default `"view"`).
+   * @param options - Optional `kind` (what kind of view to save, default
+   *   `"view"`) and `storey` (save the view on a specific storey — the storey is
+   *   activated first, matching the storey the view is captured on; when omitted
+   *   the current active storey is used).
    * @returns The newly created {@linkcode PluginPresentationView}.
-   * @throws If the view could not be saved.
+   * @throws If `storey` is given but no such storey exists, or the view could
+   *   not be saved.
    *
    * @examplePrompt Save the current view as Lobby Perspective
    * @examplePrompt Create a new saved view from where I'm looking
    * @examplePrompt Bookmark this camera angle
    * @examplePrompt Save the current 2D plan as a view
+   * @examplePrompt Save a view on the second storey
    *
    * # Example
    * ```ts
    * const view = await snaptrude.presentation.views.create("Lobby")
+   * // …or capture the view on a specific storey
+   * const level2 = await snaptrude.presentation.views.create("Level 2", { storey: 2 })
    * ```
    */
   public abstract create(
     name?: string,
-    options?: { kind?: "view" | "sitePlan" },
+    options?: { kind?: "view" | "sitePlan"; storey?: number },
   ): PluginApiReturn<PluginPresentationViewsCreateResult>
 
   /**
-   * Read a saved view's display settings (background, color mode, axis, edges,
-   * labels).
+   * Read a saved view's display settings (background, color mode, view mode,
+   * axis, edges, labels).
    *
    * @param viewId - The id of the view to read settings for.
    * @returns The view's {@linkcode PluginPresentationViewSettings}, or `null` if
@@ -206,19 +215,30 @@ export abstract class PluginPresentationViewsApi {
    * {@linkcode PluginPresentationViewsApi.getSettings}, so read-then-write
    * round-trips a tag-based color scheme unchanged.
    *
+   * `viewMode` (`"perspective"` | `"isometric"`) applies to **3D views only** —
+   * a 2D plan is always orthographic, so a `viewMode: "perspective"` patch on a
+   * 2D view is rejected. `"isometric"` on a 2D plan is accepted as a no-op (the
+   * plan is already orthographic), so writing back exactly what
+   * {@linkcode PluginPresentationViewsApi.getSettings} returned is always a
+   * no-op. On the active view the camera switches projection live (the same
+   * toggle the view-settings modal runs); on other views the mode is applied
+   * the next time the view is activated.
+   *
    * @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
+   * @throws If writes are disabled, no view has the given id, the patch is
    *   contradictory (`showLabels: false` with a non-empty `labels`, or
-   *   `showLabels: true` with an explicitly empty `labels` list).
+   *   `showLabels: true` with an explicitly empty `labels` list), or
+   *   `viewMode: "perspective"` is patched on a 2D plan view.
    *
    * @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
+   * @examplePrompt Make the 3D view orthographic instead of perspective
    *
    * # Example
    * ```ts
@@ -226,12 +246,70 @@ export abstract class PluginPresentationViewsApi {
    *   colorMode: "monochrome",
    *   showAxis: false,
    * })
+   * // switch a 3D view to an isometric (orthographic) projection
+   * await snaptrude.presentation.views.updateSettings("view_123", {
+   *   viewMode: "isometric",
+   * })
    * ```
    */
   public abstract updateSettings(
     viewId: string,
     settings: Partial<PluginPresentationViewSettings>,
   ): PluginApiReturn<PluginPresentationViewsUpdateSettingsResult>
+
+  /**
+   * Rename a saved view.
+   *
+   * Sets the view's display name — the same label the views panel shows and
+   * that `list`/`get` read back. Names must be unique within the proposal and
+   * cannot contain the characters `\ : { } [ ] | ; < > ? ~`.
+   *
+   * @param viewId - The id of the view to rename.
+   * @param name - The new display name (non-empty after trimming).
+   * @returns The updated {@linkcode PluginPresentationView}.
+   * @throws If writes are disabled, no view has the given id, the name is
+   *   empty/invalid, or another view in the proposal already has that name.
+   *
+   * @examplePrompt Rename the view Lobby to Entrance Lobby
+   * @examplePrompt Call this view Ground Floor Plan
+   * @examplePrompt Change the active view's name to Final
+   *
+   * # Example
+   * ```ts
+   * const view = await snaptrude.presentation.views.rename("view_123", "Entrance")
+   * ```
+   */
+  public abstract rename(
+    viewId: string,
+    name: string,
+  ): PluginApiReturn<PluginPresentationViewsRenameResult>
+
+  /**
+   * Delete a saved view.
+   *
+   * Removes the view from the project and the views panel (the panel's own
+   * delete action). If the deleted view was active, the product falls back to
+   * the default plan/3D view. Default views (the built-in plan/3D/site-plan
+   * entries) cannot be deleted.
+   *
+   * @param viewId - The id of the view to delete.
+   * @returns The id of the deleted view
+   *   (a {@linkcode PluginPresentationViewsDeleteResult}).
+   * @throws If writes are disabled, no view has the given id, or the view is a
+   *   default view.
+   *
+   * @examplePrompt Delete the view named Old Draft
+   * @examplePrompt Remove this saved view
+   * @examplePrompt Get rid of the Lobby camera bookmark
+   *
+   * # Example
+   * ```ts
+   * const { id } = await snaptrude.presentation.views.delete("view_123")
+   * ```
+   */
+  public abstract delete(
+    viewId: string,
+  ): PluginApiReturn<PluginPresentationViewsDeleteResult>
 }
 
 /**
@@ -251,12 +329,14 @@ export type PluginPresentationViewType = z.infer<
  * | `name` | `string` | Display name |
  * | `type` | `"2d" \| "3d"` | Whether this is a 2D plan view or a 3D view |
  * | `isActive` | `boolean` | Whether this view is the currently active view |
+ * | `storey` | `number \| null` | The storey this view was saved on (`null` on older views saved without one) |
  */
 export const PluginPresentationView = z.object({
   id: z.string(),
   name: z.string(),
   type: PluginPresentationViewType,
   isActive: z.boolean(),
+  storey: z.number().nullable(),
 })
 export type PluginPresentationView = z.infer<typeof PluginPresentationView>
 
@@ -366,10 +446,12 @@ export type PluginPresentationViewsSetActiveResult = z.infer<
  * |---|---|---|
  * | `name` | `string \| undefined` | Name for the new view (a default is used when omitted) |
  * | `kind` | `"view" \| "sitePlan" \| undefined` | What kind of view to save (default `"view"`). `"plan"` is not offered — the host cannot create a plan view without a `planId` this API does not carry. |
+ * | `storey` | `number \| undefined` | Save the view on this storey (activated before capture); defaults to the current active storey |
  */
 export const PluginPresentationViewsCreateArgs = z.object({
   name: z.string().optional(),
   kind: z.enum(["view", "sitePlan"]).optional(),
+  storey: z.number().optional(),
 })
 export type PluginPresentationViewsCreateArgs = z.infer<
   typeof PluginPresentationViewsCreateArgs
@@ -421,6 +503,22 @@ export type PluginPresentationViewLabel = z.infer<
   typeof PluginPresentationViewLabel
 >
 
+/**
+ * A view's camera projection: perspective, or isometric (orthographic).
+ *
+ * | Value | Meaning |
+ * |---|---|
+ * | `perspective` | Perspective projection (vanishing points) |
+ * | `isometric` | Orthographic projection (no perspective distortion) |
+ *
+ * Applies to 3D views; a 2D plan view is always orthographic and reads
+ * `"isometric"`.
+ */
+export const PluginPresentationViewMode = z.enum(["perspective", "isometric"])
+export type PluginPresentationViewMode = z.infer<
+  typeof PluginPresentationViewMode
+>
+
 /**
  * A view's display settings.
  *
@@ -428,6 +526,7 @@ export type PluginPresentationViewLabel = z.infer<
  * |---|---|---|
  * | `backgroundColor` | `string` | Canvas background as a hex color (e.g. `#ffffff`) |
  * | `colorMode` | {@linkcode PluginPresentationViewColorMode} | How the scene is colored (including `tag:<categoryId>` schemes) |
+ * | `viewMode` | {@linkcode PluginPresentationViewMode} | Camera projection — `"perspective"` or `"isometric"` (orthographic). Writable on 3D views only; a 2D plan always reads `"isometric"` and accepts only `"isometric"` (a no-op) |
  * | `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) |
@@ -436,6 +535,7 @@ export type PluginPresentationViewLabel = z.infer<
 export const PluginPresentationViewSettings = z.object({
   backgroundColor: z.string(),
   colorMode: PluginPresentationViewColorMode,
+  viewMode: PluginPresentationViewMode,
   showAxis: z.boolean(),
   showEdges: z.boolean(),
   showLabels: z.boolean(),
@@ -488,7 +588,9 @@ export const PluginPresentationViewsUpdateSettingsArgs = z
   })
   .refine(
     (v) =>
-      !(v.settings.showLabels === false && (v.settings.labels?.length ?? 0) > 0),
+      !(
+        v.settings.showLabels === false && (v.settings.labels?.length ?? 0) > 0
+      ),
     {
       message:
         "Contradictory patch: labels cannot be set while showLabels is false",
@@ -517,3 +619,53 @@ export const PluginPresentationViewsUpdateSettingsResult = z.object({
 export type PluginPresentationViewsUpdateSettingsResult = z.infer<
   typeof PluginPresentationViewsUpdateSettingsResult
 >
+
+/**
+ * Arguments for {@linkcode PluginPresentationViewsApi.rename}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The id of the view to rename |
+ * | `name` | `string` | New display name (non-empty after trimming) |
+ */
+export const PluginPresentationViewsRenameArgs = z.object({
+  id: z.string(),
+  name: z.string().trim().min(1),
+})
+export type PluginPresentationViewsRenameArgs = z.infer<
+  typeof PluginPresentationViewsRenameArgs
+>
+
+/** Result of {@linkcode PluginPresentationViewsApi.rename} — the renamed view. */
+export const PluginPresentationViewsRenameResult = PluginPresentationView
+export type PluginPresentationViewsRenameResult = z.infer<
+  typeof PluginPresentationViewsRenameResult
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationViewsApi.delete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The id of the view to delete |
+ */
+export const PluginPresentationViewsDeleteArgs = z.object({
+  id: z.string(),
+})
+export type PluginPresentationViewsDeleteArgs = z.infer<
+  typeof PluginPresentationViewsDeleteArgs
+>
+
+/**
+ * Result of {@linkcode PluginPresentationViewsApi.delete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Id of the deleted view |
+ */
+export const PluginPresentationViewsDeleteResult = z.object({
+  id: z.string(),
+})
+export type PluginPresentationViewsDeleteResult = z.infer<
+  typeof PluginPresentationViewsDeleteResult
+>

package/src/api/program/areas.ts

@@ -29,9 +29,14 @@ import { ComponentHandle } from "../../handles"
  * 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 only write —
- * {@linkcode PluginProgramAreasApi.update} — is a non-undoable settings write
- * for the FAR inputs.
+ * Reads return plain records and never throw. Because the engine only recomputes
+ * the breakdown live while the Area sidebar is open, a headless plugin should call
+ * {@linkcode PluginProgramAreasApi.refresh} first to guarantee the reads are fresh.
+ * The only write — {@linkcode PluginProgramAreasApi.update} — is a non-undoable
+ * settings write for the FAR inputs. With an active design option (proposal),
+ * those inputs are per-option: `update` writes and the reads report the active
+ * option's own target FAR / site area / deviation, matching the product's Area
+ * settings dialog.
  *
  * Accessed via `snaptrude.program.areas`.
  */
@@ -129,6 +134,13 @@ export abstract class PluginProgramAreasApi {
    * area, and the allowed deviation. This is a **non-undoable settings write**
    * (persisted with the project). `achievedFar` recomputes from these.
    *
+   * **Design options:** when a design option (proposal) is active, the FAR
+   * inputs are **scoped to that design option** — exactly like the product's
+   * Area settings dialog. `update` writes the active option's settings (each
+   * option keeps its own target FAR / site area / deviation) and the reads
+   * ({@linkcode PluginProgramAreasApi.get} etc.) report that same scope.
+   * Without design options there is a single project-wide set of FAR inputs.
+   *
    * @param options - Any of `targetFar`, `siteArea`, `deviation`; omitted fields
    *   are left unchanged.
    * @returns The recomputed {@linkcode PluginProgramAreaSummary}.
@@ -144,9 +156,39 @@ export abstract class PluginProgramAreasApi {
    * console.log(s.achievedFar, s.targetFar)
    * ```
    */
-  public abstract update(
-    options?: { targetFar?: number; siteArea?: number; deviation?: number },
-  ): PluginApiReturn<PluginProgramAreasUpdateResult>
+  public abstract update(options?: {
+    targetFar?: number
+    siteArea?: number
+    deviation?: number
+  }): PluginApiReturn<PluginProgramAreasUpdateResult>
+
+  /**
+   * Force the area breakdown to recompute, then return the fresh summary.
+   *
+   * The engine recomputes the carpet / built-up / FAR totals live **only while the
+   * Area sidebar is open**. A plugin running with the sidebar closed can therefore
+   * read a stale — or never-computed — snapshot from {@linkcode
+   * PluginProgramAreasApi.get} / {@linkcode PluginProgramAreasApi.list}. Call
+   * `refresh` first to guarantee those reads reflect the current model. It is a
+   * read (no write gate) — it recomputes derived totals, it does not change the model.
+   *
+   * **Cost:** a full pass over every space, floor and mass in the active structure.
+   * Not free on large models — call it once before a batch of reads, not per read.
+   *
+   * @returns The freshly-recomputed {@linkcode PluginProgramAreaSummary}.
+   *
+   * @examplePrompt Recompute the area totals before I read them
+   * @examplePrompt Refresh the FAR numbers
+   * @examplePrompt Make sure the area breakdown is up to date
+   *
+   * # Example
+   * ```ts
+   * const s = await snaptrude.program.areas.refresh()
+   * const { groups } = await snaptrude.program.areas.list("storeys") // now fresh
+   * console.log(s.builtUp, groups.length)
+   * ```
+   */
+  public abstract refresh(): PluginApiReturn<PluginProgramAreasRefreshResult>
 }
 
 /**
@@ -355,3 +397,12 @@ export const PluginProgramAreasUpdateResult = PluginProgramAreaSummary
 export type PluginProgramAreasUpdateResult = z.infer<
   typeof PluginProgramAreasUpdateResult
 >
+
+/**
+ * Result of {@linkcode PluginProgramAreasApi.refresh} — the freshly-recomputed
+ * program area summary.
+ */
+export const PluginProgramAreasRefreshResult = PluginProgramAreaSummary
+export type PluginProgramAreasRefreshResult = z.infer<
+  typeof PluginProgramAreasRefreshResult
+>

package/src/api/program/cores.ts

@@ -5,13 +5,9 @@ import { PluginApiReturn } from "../../types"
  * Program cores — the building's vertical-circulation cores (lift / stair / shaft
  * shells).
  *
- * Read the cores in the scene, test whether a space is a core, and trigger core
- * generation from a layout. `create` is a **thin trigger**: the program hands a
- * core layout to the core-generation engine, which authors the geometry — the
- * core geometry itself is owned by the geometry layer, not here (the exact
- * layout ↔ engine payload is coordinated with the geometry owner).
- *
- * `list`/`isCore` are reads; `create` triggers generation.
+ * Read the cores in the scene and test whether a space is a core. Both are reads;
+ * there is no core-generation trigger on this surface (core geometry is owned by
+ * the geometry layer, not here).
  *
  * Accessed via `snaptrude.program.cores`.
  */
@@ -52,37 +48,6 @@ export abstract class PluginProgramCoresApi {
    * ```
    */
   public abstract isCore(id: string): PluginApiReturn<boolean>
-
-  /**
-   * Generate core geometry from a layout (thin trigger).
-   *
-   * Hands the core layout to the core-generation engine and returns how many core
-   * elements were created. The geometry is authored by the engine, not here.
-   * _(Authored ahead — optional until the host's geometry adapter lands; the
-   * reads {@linkcode PluginProgramCoresApi.list}/{@linkcode PluginProgramCoresApi.isCore}
-   * are live.)_
-   *
-   * @param cores - The {@linkcode PluginProgramCoreSpec} layout of cores to
-   *   generate.
-   * @param lengthUnit - Unit of the spec dimensions (default project unit).
-   * @returns A {@linkcode PluginProgramCoresCreateResult} with the created count.
-   * @throws If the layout could not be realized.
-   *
-   * @examplePrompt Generate the building cores from this layout
-   * @examplePrompt Place the elevator and stair cores
-   * @examplePrompt Create the service core shells
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.program.cores.create([
-   *   { type: "lift", position: { x: 0, y: 0, z: 0 }, width: 3, depth: 4 },
-   * ])
-   * ```
-   */
-  public create?: (
-    cores: PluginProgramCoreSpec[],
-    lengthUnit?: "mm" | "m" | "ft",
-  ) => PluginApiReturn<PluginProgramCoresCreateResult>
 }
 
 /**
@@ -116,56 +81,3 @@ export const PluginProgramCoresIsCoreArgs = z.object({
 export type PluginProgramCoresIsCoreArgs = z.infer<
   typeof PluginProgramCoresIsCoreArgs
 >
-
-/**
- * One core to generate. The geometry layer interprets this layout (the exact
- * fields are coordinated with the geometry owner).
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `type` | `string \| undefined` | Core kind (e.g. `"lift"`, `"stair"`, `"shaft"`) |
- * | `position` | `{ x; y; z }` | Base position of the core |
- * | `width` | `number` | Core width, in `lengthUnit` |
- * | `depth` | `number` | Core depth, in `lengthUnit` |
- * | `fromStorey` | `number \| undefined` | First storey the core spans |
- * | `toStorey` | `number \| undefined` | Last storey the core spans |
- */
-export const PluginProgramCoreSpec = z.object({
-  type: z.string().optional(),
-  position: z.object({ x: z.number(), y: z.number(), z: z.number() }),
-  width: z.number(),
-  depth: z.number(),
-  fromStorey: z.number().optional(),
-  toStorey: z.number().optional(),
-})
-export type PluginProgramCoreSpec = z.infer<typeof PluginProgramCoreSpec>
-
-/**
- * Arguments for {@linkcode PluginProgramCoresApi.create}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `cores` | {@linkcode PluginProgramCoreSpec}`[]` | The cores to generate |
- * | `lengthUnit` | `"mm" \| "m" \| "ft" \| undefined` | Unit of the spec dimensions (default project unit) |
- */
-export const PluginProgramCoresCreateArgs = z.object({
-  cores: z.array(PluginProgramCoreSpec),
-  lengthUnit: z.enum(["mm", "m", "ft"]).optional(),
-})
-export type PluginProgramCoresCreateArgs = z.infer<
-  typeof PluginProgramCoresCreateArgs
->
-
-/**
- * Result of {@linkcode PluginProgramCoresApi.create}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `createdCount` | `number` | Number of core elements created |
- */
-export const PluginProgramCoresCreateResult = z.object({
-  createdCount: z.number(),
-})
-export type PluginProgramCoresCreateResult = z.infer<
-  typeof PluginProgramCoresCreateResult
->

package/src/api/program/index.ts

@@ -24,7 +24,7 @@ import { PluginProgramAreasApi } from "./areas"
  * - {@linkcode PluginProgramApi.areas} — FAR / built-up-area rollup and groupings
  * - {@linkcode PluginProgramApi.spreadsheet} — Render program data to sheets and read it back
  * - {@linkcode PluginProgramApi.site} — Read the site/plot planning context
- * - {@linkcode PluginProgramApi.cores} — Read & trigger vertical-circulation cores
+ * - {@linkcode PluginProgramApi.cores} — Read & predicate vertical-circulation cores (reads only)
  * - {@linkcode PluginProgramApi.classification} — Classification catalog + display tags
  *
  * Accessed via `snaptrude.program`.
@@ -44,7 +44,7 @@ export abstract class PluginProgramApi {
   public abstract spreadsheet: PluginProgramSpreadsheetApi
   /** Site/plot planning context — total area, parcel footprints, geo rings. See {@linkcode PluginProgramSiteApi}. */
   public abstract site: PluginProgramSiteApi
-  /** Vertical-circulation cores — read & predicate (live); generation trigger is optional. See {@linkcode PluginProgramCoresApi}. */
+  /** Vertical-circulation cores — read & predicate (reads only). See {@linkcode PluginProgramCoresApi}. */
   public abstract cores: PluginProgramCoresApi
   /** Classification catalog (space/area/mass types) + display tags. See {@linkcode PluginProgramClassificationApi}. */
   public abstract classification: PluginProgramClassificationApi