@snaptrude/plugin-core 0.0.0-dev-20260708130115 → 0.0.0-dev-20260827135706

package/src/api/entity/story.ts

@@ -1,5 +1,6 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../types"
+import { ComponentHandle } from "../../handles"
 
 /**
  * Story (floor/storey) management.
@@ -40,6 +41,8 @@ export abstract class PluginStoryApi {
    * const info = await snaptrude.entity.story.get(1, ["height", "name", "spacesCount"])
    * console.log(info.name, info.height, info.spacesCount)
    * ```
+   *
+   * @deprecated Use `core.storeys.get`
    */
   public abstract get(
     storyValue: number,
@@ -67,6 +70,8 @@ export abstract class PluginStoryApi {
    *   console.log(`Story ${s.value}: ${s.name} (id: ${s.id})`)
    * }
    * ```
+   *
+   * @deprecated Use `core.storeys.list`
    */
   public abstract getAll(): PluginApiReturn<PluginStoryGetAllResult>
 
@@ -94,6 +99,8 @@ export abstract class PluginStoryApi {
    * // Create a new third floor with custom height
    * const { storyId } = await snaptrude.entity.story.create(3, 4.5)
    * ```
+   *
+   * @deprecated Use `core.storeys.create`
    */
   public abstract create(
     storyValue: number,
@@ -101,33 +108,171 @@ export abstract class PluginStoryApi {
   ): PluginApiReturn<PluginStoryCreateResult>
 
   /**
-   * Update a story's height.
+   * Update a story's floor-to-floor `height` and/or `name`.
    *
-   * Changes the floor-to-floor height of the specified story. This
-   * operation is undoable.
+   * **Height** 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 height cascade is committed as
+   * **one undo step**. Height-locked elements are left untouched.
+   *
+   * **Name** is the same as renaming the story in the Stories panel: it is
+   * persisted immediately (saved to the project) but, mirroring the panel, is
+   * **not** part of the height undo step.
+   *
+   * At least one of `height` or `options.name` must be supplied. Omitting the
+   * `height` argument (e.g. for a rename-only update) leaves the height
+   * untouched.
    *
    * @param storyValue - Integer storey number
    *   identifying the story to update
-   * @param height - New height value in Babylon
-   *   units
-   * @returns A {@linkcode PluginStoryUpdateResult} with the updated `storyValue` and `height`
-   * @throws If the story does not exist or the update fails
+   * @param height - New floor-to-floor height in
+   *   Babylon units. Omit to leave the height unchanged.
+   * @param options - `name` (new display name for the story)
+   * @returns A {@linkcode PluginStoryUpdateResult} with the story's
+   *   `storyValue`, `height`, and `name` after the update
+   * @throws `PRECONDITION_FAILED` if no story has the given value;
+   *   `VALIDATION` if neither `height` nor `options.name` is supplied;
+   *   `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
+   * @examplePrompt Rename the ground floor to "Lobby"
    * @examplePrompt Set the floor-to-floor height of level 1
-   * @examplePrompt Increase the height of the third floor
+   * @examplePrompt Rename storey 2 and make it taller in one go
    *
    * # 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)
+   * // Rename only, leaving the height untouched.
+   * await snaptrude.entity.story.update(1, undefined, { name: "Lobby" })
    * ```
+   *
+   * @deprecated Use `core.storeys.update`
    */
   public abstract update(
     storyValue: number,
-    height: number,
+    height?: number,
+    options?: { name?: string },
   ): PluginApiReturn<PluginStoryUpdateResult>
+
+  /**
+   * Make a story the active story — the same as clicking it in the storey/layer
+   * panel. Subsequent draws and creates target this story, and in 2D the
+   * viewport switches to it. This is a view/navigation change: it is **not**
+   * undoable and commits nothing to the model.
+   *
+   * @param storyValue - Integer storey number to activate
+   * @returns A {@linkcode PluginStorySetActiveResult} echoing the now-active `storyValue`
+   * @throws `PRECONDITION_FAILED` if no story has the given value
+   *
+   * @examplePrompt Switch to the second floor
+   * @examplePrompt Make the ground storey active
+   * @examplePrompt Go to the basement level
+   * @examplePrompt Set level 3 as the current storey
+   *
+   * # Example
+   * ```ts
+   * // Activate story 2, then draw a wall — it lands on story 2.
+   * await snaptrude.entity.story.setActive(2)
+   * ```
+   *
+   * @deprecated Use `core.storeys.setActive`
+   */
+  public abstract setActive(
+    storyValue: number,
+  ): PluginApiReturn<PluginStorySetActiveResult>
+
+  /**
+   * Delete a story and everything on it — the same as removing it from the
+   * storey panel. Every element placed on the story (walls, floors, masses, …)
+   * is deleted with it, the remaining stories are re-stacked, and the active
+   * story falls back to an adjacent one. Committed as a single undo step.
+   *
+   * @param storyValue - Integer storey number to delete
+   * @returns A {@linkcode PluginStoryDeleteResult} with the deleted `storyValue`
+   *   and the `newActiveStory` the editor fell back to
+   * @throws `PRECONDITION_FAILED` if no story has the given value; or if plugin
+   *   writes are disabled
+   *
+   * @examplePrompt Delete the top floor
+   * @examplePrompt Remove the basement level
+   * @examplePrompt Get rid of storey 3
+   * @examplePrompt Delete the second floor and everything on it
+   *
+   * # Example
+   * ```ts
+   * const { newActiveStory } = await snaptrude.entity.story.delete(3)
+   * console.log(`Deleted story 3; now on story ${newActiveStory}`)
+   * ```
+   *
+   * @deprecated Use `core.storeys.delete`
+   */
+  public abstract delete(
+    storyValue: number,
+  ): PluginApiReturn<PluginStoryDeleteResult>
+
+  /**
+   * 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
+   *
+   * @performance For storeys that share a layout, duplicate the storey instead of recreating
+   *   its contents floor by floor — this copies every eligible element in one call, and the
+   *   default instanced copies keep the floors linked. To stack many identical floors, either
+   *   call this per level or capture the storey's component ids and
+   *   `design.create.copy(ids, oneFloorRise, { count })` to lay them all down in a single call.
+   *
+   * # 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`)
+   * ```
+   *
+   * @deprecated Use `core.storeys.copy`
+   */
+  public abstract duplicate(
+    direction: "up" | "down",
+    options?: { components?: ComponentHandle[]; unique?: boolean },
+  ): PluginApiReturn<PluginStoryDuplicateResult>
 }
 
 /**
@@ -243,31 +388,130 @@ export const PluginStoryCreateResult = z.object({
 export type PluginStoryCreateResult = z.infer<typeof PluginStoryCreateResult>
 
 /**
- * Arguments for {@linkcode PluginStoryApi.update}.
+ * Arguments for {@linkcode PluginStoryApi.update}. At least one of `height` or
+ * `name` must be supplied.
  *
  * | Property | Type | Description |
  * |---|---|---|
  * | `storyValue` | `number` (int) | Storey number of the story to update |
- * | `height` | `number` | New height in Babylon units |
+ * | `height` | `number?` | New height in Babylon units (omit to leave unchanged) |
+ * | `name` | `string?` | New display name for the story (omit to leave unchanged) |
  */
 export const PluginStoryUpdateArgs = z.object({
   storyValue: z.number().int(),
-  height: z.number(),
+  height: z.number().optional(),
+  name: z.string().optional(),
 })
 
 export type PluginStoryUpdateArgs = z.infer<typeof PluginStoryUpdateArgs>
 
 /**
- * Result of {@linkcode PluginStoryApi.update}.
+ * Result of {@linkcode PluginStoryApi.update} — the story's state after the update.
  *
  * | Property | Type | Description |
  * |---|---|---|
  * | `storyValue` | `number` | The storey number of the updated story |
- * | `height` | `number` | The new height after the update |
+ * | `height` | `number` | The height after the update |
+ * | `name` | `string` | The name after the update |
  */
 export const PluginStoryUpdateResult = z.object({
   storyValue: z.number(),
   height: z.number(),
+  name: z.string(),
 })
 
 export type PluginStoryUpdateResult = z.infer<typeof PluginStoryUpdateResult>
+
+/**
+ * Arguments for {@linkcode PluginStoryApi.setActive}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storyValue` | `number` (int) | Storey number to activate |
+ */
+export const PluginStorySetActiveArgs = z.object({
+  storyValue: z.number().int(),
+})
+
+export type PluginStorySetActiveArgs = z.infer<typeof PluginStorySetActiveArgs>
+
+/**
+ * Result of {@linkcode PluginStoryApi.setActive}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storyValue` | `number` | The storey number that is now active |
+ */
+export const PluginStorySetActiveResult = z.object({
+  storyValue: z.number(),
+})
+
+export type PluginStorySetActiveResult = z.infer<typeof PluginStorySetActiveResult>
+
+/**
+ * Arguments for {@linkcode PluginStoryApi.delete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storyValue` | `number` (int) | Storey number to delete |
+ */
+export const PluginStoryDeleteArgs = z.object({
+  storyValue: z.number().int(),
+})
+
+export type PluginStoryDeleteArgs = z.infer<typeof PluginStoryDeleteArgs>
+
+/**
+ * Result of {@linkcode PluginStoryApi.delete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storyValue` | `number` | The storey number that was deleted |
+ * | `newActiveStory` | `number` | The storey the editor fell back to as active |
+ */
+export const PluginStoryDeleteResult = z.object({
+  storyValue: z.number(),
+  newActiveStory: z.number(),
+})
+
+export type PluginStoryDeleteResult = z.infer<typeof PluginStoryDeleteResult>
+
+/**
+ * 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 const PluginStoryDuplicateArgs = z.object({
+  direction: z.enum(["up", "down"]),
+  components: z.array(ComponentHandle).optional(),
+  unique: z.boolean().optional(),
+})
+
+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 const PluginStoryDuplicateResult = z.object({
+  sourceStory: z.number(),
+  targetStories: z.array(z.number()),
+  created: z.array(ComponentHandle),
+  createdStoryValues: z.array(z.number()),
+  skipped: z.number(),
+})
+
+export type PluginStoryDuplicateResult = z.infer<
+  typeof PluginStoryDuplicateResult
+>

package/src/api/index.ts

@@ -3,6 +3,8 @@ import { PluginDesignApi } from "./design"
 import { PluginEntityApi } from "./entity"
 import { PluginProgramApi } from "./program"
 import { PluginPresentationApi } from "./presentation"
+import { PluginAnalysisApi } from "./analysis"
+import { PluginWorkspaceApi } from "./workspace"
 
 /**
  * Root API surface for Snaptrude plugins.
@@ -14,6 +16,8 @@ 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)
+ * - {@linkcode PluginApi.workspace} — Dashboard surface: projects and teams
  */
 export abstract class PluginApi {
   /** Core math, geometry, history, and units primitives. See {@linkcode PluginCoreApi}. */
@@ -26,6 +30,10 @@ export abstract class PluginApi {
   public abstract program: PluginProgramApi
   /** Presentation preparation reads — saved views. See {@linkcode PluginPresentationApi}. */
   public abstract presentation: PluginPresentationApi
+  /** Sustainability analysis — sun & daylight studies. See {@linkcode PluginAnalysisApi}. */
+  public abstract analysis: PluginAnalysisApi
+  /** Dashboard surface — projects and teams. See {@linkcode PluginWorkspaceApi}. */
+  public abstract workspace: PluginWorkspaceApi
 
   constructor() {}
 }
@@ -35,3 +43,5 @@ export * from "./design"
 export * from "./entity"
 export * from "./program"
 export * from "./presentation"
+export * from "./analysis"
+export * from "./workspace"