@snaptrude/plugin-core 0.9.16 → 0.9.18-edgesetbacks-20261021.1

package/src/api/core/buildings.ts

@@ -1,485 +1,485 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../types"
-
-/**
- * Buildings — read and edit the buildings of the active project.
- *
- * A **building** is the top of the project's spatial hierarchy: a named container
- * of storeys, positioned by its base elevation. This namespace reads a building's
- * identity and base elevation and lists the storeys it holds; storey detail is
- * read through the entity story surface (`snaptrude.entity.story`).
- *
- * Reads return plain records and never throw for a missing building (`get` and
- * `getActive` return `null`, `list` returns `[]`). Ids are stable public strings.
- *
- * Sub-namespace members typed as optional (`?`) are **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 them (at which point they are promoted
- * to required `abstract` members).
- *
- * Accessed via `snaptrude.core.buildings`.
- */
-export abstract class PluginCoreBuildingsApi {
-  constructor() {}
-
-  /**
-   * List the buildings in the active project.
-   *
-   * @returns A {@linkcode PluginCoreBuildingsListResult} with a `buildings` array
-   *   (empty when the project has none).
-   *
-   * @examplePrompt List all the buildings in my project
-   * @examplePrompt How many buildings are in this model?
-   * @examplePrompt Show every building with its base elevation
-   *
-   * # Example
-   * ```ts
-   * const { buildings } = await snaptrude.core.buildings.list()
-   * for (const b of buildings) console.log(b.name, b.baseElevation)
-   * ```
-   */
-  public abstract list(): PluginApiReturn<PluginCoreBuildingsListResult>
-
-  /**
-   * Get a single building by id.
-   *
-   * @param buildingId - The id of the building to read.
-   * @returns The matching {@linkcode PluginCoreBuildingRef}, or `null` if no
-   *   building has that id.
-   *
-   * @examplePrompt Get the building with id blg_1
-   * @examplePrompt Look up a single building by its id
-   * @examplePrompt What is the base elevation of building blg_2?
-   *
-   * # Example
-   * ```ts
-   * const building = await snaptrude.core.buildings.get("blg_1")
-   * if (building) console.log(building.name, building.baseElevation)
-   * ```
-   */
-  public abstract get(
-    buildingId: string,
-  ): PluginApiReturn<PluginCoreBuildingsGetResult>
-
-  /**
-   * List the storeys of a building.
-   *
-   * Returns the building's storeys as stable storey ids, in the project's storey
-   * order. Read each storey's detail through `snaptrude.entity.story`.
-   *
-   * @param buildingId - The id of the building whose storeys to list.
-   * @returns A {@linkcode PluginCoreBuildingsListStoreysResult} with a `storeyIds`
-   *   array (empty when the building is missing or has no storeys).
-   *
-   * @examplePrompt List the storeys in building blg_1
-   * @examplePrompt How many floors does this building have?
-   * @examplePrompt Get the storey ids of the active building
-   *
-   * # Example
-   * ```ts
-   * const { storeyIds } = await snaptrude.core.buildings.listStoreys("blg_1")
-   * console.log(`${storeyIds.length} storeys`)
-   * ```
-   */
-  public abstract listStoreys(
-    buildingId: string,
-  ): PluginApiReturn<PluginCoreBuildingsListStoreysResult>
-
-  /**
-   * Get the active building.
-   *
-   * The active building is the one new storeys and edits target. Paired with
-   * {@linkcode PluginCoreBuildingsApi.setActive}.
-   *
-   * @returns A {@linkcode PluginCoreBuildingsGetActiveResult} with the active
-   *   `buildingId`, or `null` if there is no active building.
-   *
-   * @examplePrompt Which building is active?
-   * @examplePrompt Get the current building
-   * @examplePrompt What building am I working in?
-   *
-   * # Example
-   * ```ts
-   * const active = await snaptrude.core.buildings.getActive()
-   * if (active) console.log(active.buildingId)
-   * ```
-   */
-  public abstract getActive(): PluginApiReturn<PluginCoreBuildingsGetActiveResult>
-
-  /**
-   * Make a building the active building.
-   *
-   * Paired with {@linkcode PluginCoreBuildingsApi.getActive}.
-   *
-   * @param buildingId - The id of the building to activate.
-   * @returns The id of the now-active building.
-   * @throws If no building has the given id.
-   *
-   * @examplePrompt Switch to building blg_2
-   * @examplePrompt Make this building the active one
-   * @examplePrompt Set the active building to blg_1
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.core.buildings.setActive("blg_2")
-   * ```
-   */
-  public abstract setActive(
-    buildingId: string,
-  ): PluginApiReturn<PluginCoreBuildingsSetActiveResult>
-
-  /**
-   * Create a new building.
-   *
-   * Adds a named building at the given base elevation (defaults to `0`). The new
-   * building starts empty — add storeys through the storeys namespace.
-   *
-   * @param name - Display name of the new building.
-   * @param baseElevation - Base elevation in meters (defaults to `0`).
-   * @returns The new building's id (read the full record back with
-   *   {@linkcode PluginCoreBuildingsApi.get}).
-   * @throws If the building could not be created.
-   *
-   * @examplePrompt Create a building called Tower B
-   * @examplePrompt Add a new building at elevation 12 meters
-   * @examplePrompt Make a second building named Annex
-   *
-   * # Example
-   * ```ts
-   * const { buildingId } = await snaptrude.core.buildings.create("Tower B", 0)
-   * ```
-   */
-  public abstract create(
-    name: string,
-    baseElevation?: number,
-  ): PluginApiReturn<PluginCoreBuildingsCreateResult>
-
-  /**
-   * Update a building's name and/or base elevation.
-   *
-   * A **sparse** update: omitted fields are left unchanged.
-   *
-   * @param buildingId - The id of the building to update.
-   * @param options - Any of `name`, `baseElevation`; omitted fields are left
-   *   unchanged.
-   * @returns The updated {@linkcode PluginCoreBuildingRef}.
-   * @throws If no building has the given id.
-   *
-   * @examplePrompt Rename building blg_1 to Tower A
-   * @examplePrompt Move the building up to elevation 6 meters
-   * @examplePrompt Change the base elevation of blg_2
-   *
-   * # Example
-   * ```ts
-   * const building = await snaptrude.core.buildings.update("blg_1", { name: "Tower A" })
-   * ```
-   */
-  public abstract update(
-    buildingId: string,
-    options?: { name?: string; baseElevation?: number },
-  ): PluginApiReturn<PluginCoreBuildingsUpdateResult>
-
-  /**
-   * Copy a building.
-   *
-   * Copies the building — its storeys, components, and drawing layers — into a new
-   * building. `asInstances` controls the copy's geometry: `true` shares the source
-   * geometry as instances (low memory), `false` makes independent editable copies
-   * (the host defaults to `true`). Optionally override the copy's `name` and
-   * `baseElevation`.
-   *
-   * @param buildingId - The id of the building to copy.
-   * @param options - Optional `name`, `baseElevation`, `asInstances` overrides
-   *   for the copy.
-   * @returns The new building's id.
-   * @throws If no building has the given id.
-   *
-   * @examplePrompt Copy building blg_1
-   * @examplePrompt Make an independent editable copy of this building
-   * @examplePrompt Copy Tower A as instances to save memory
-   *
-   * # Example
-   * ```ts
-   * const { buildingId } = await snaptrude.core.buildings.copy("blg_1", {
-   *   name: "Tower A Copy",
-   *   asInstances: false,
-   * })
-   * ```
-   */
-  public abstract copy(
-    buildingId: string,
-    options?: { name?: string; baseElevation?: number; asInstances?: boolean },
-  ): PluginApiReturn<PluginCoreBuildingsCopyResult>
-
-  /**
-   * Delete a building.
-   *
-   * **Gated and destructive.** Deleting a building cascades through its meshes,
-   * storeys, and the building itself, and removes its saved views — **saved views
-   * are not restored on undo.** The project's only remaining building cannot be
-   * deleted.
-   *
-   * @param buildingId - The id of the building to delete.
-   * @returns Confirmation that the building was deleted.
-   * @throws If no building has the given id, or it is the only building.
-   *
-   * @examplePrompt Delete building blg_2
-   * @examplePrompt Remove the Annex building and everything in it
-   * @examplePrompt Delete this building
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.core.buildings.delete("blg_2")
-   * ```
-   */
-  public abstract delete(
-    buildingId: string,
-  ): PluginApiReturn<PluginCoreBuildingsDeleteResult>
-}
-
-/**
- * A building in the active project.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `id` | `string` | Stable public building id (e.g. `"blg_1"`) |
- * | `name` | `string` | Display name |
- * | `baseElevation` | `number` | Base elevation in meters, positive up (default `0`) |
- */
-export const PluginCoreBuildingRef = z.object({
-  id: z.string(),
-  name: z.string(),
-  baseElevation: z.number(),
-})
-export type PluginCoreBuildingRef = z.infer<typeof PluginCoreBuildingRef>
-
-/**
- * Result of {@linkcode PluginCoreBuildingsApi.list}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `buildings` | {@linkcode PluginCoreBuildingRef}`[]` | Every building in the active project |
- */
-export const PluginCoreBuildingsListResult = z.object({
-  buildings: z.array(PluginCoreBuildingRef),
-})
-export type PluginCoreBuildingsListResult = z.infer<
-  typeof PluginCoreBuildingsListResult
->
-
-/**
- * Arguments for {@linkcode PluginCoreBuildingsApi.get}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `buildingId` | `string` | The id of the building to read |
- */
-export const PluginCoreBuildingsGetArgs = z.object({
-  buildingId: z.string(),
-})
-export type PluginCoreBuildingsGetArgs = z.infer<
-  typeof PluginCoreBuildingsGetArgs
->
-
-/**
- * Result of {@linkcode PluginCoreBuildingsApi.get} — the building, or `null` when
- * no building has the given id.
- */
-export const PluginCoreBuildingsGetResult = PluginCoreBuildingRef.nullable()
-export type PluginCoreBuildingsGetResult = z.infer<
-  typeof PluginCoreBuildingsGetResult
->
-
-/**
- * Arguments for {@linkcode PluginCoreBuildingsApi.listStoreys}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `buildingId` | `string` | The id of the building whose storeys to list |
- */
-export const PluginCoreBuildingsListStoreysArgs = z.object({
-  buildingId: z.string(),
-})
-export type PluginCoreBuildingsListStoreysArgs = z.infer<
-  typeof PluginCoreBuildingsListStoreysArgs
->
-
-/**
- * Result of {@linkcode PluginCoreBuildingsApi.listStoreys}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `storeyIds` | `string[]` | The building's storey ids in storey order (empty when missing or none) |
- */
-export const PluginCoreBuildingsListStoreysResult = z.object({
-  storeyIds: z.array(z.string()),
-})
-export type PluginCoreBuildingsListStoreysResult = z.infer<
-  typeof PluginCoreBuildingsListStoreysResult
->
-
-/**
- * Result of {@linkcode PluginCoreBuildingsApi.getActive} — the active building's
- * id, or `null` when there is no active building.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `buildingId` | `string` | The id of the active building |
- */
-export const PluginCoreBuildingsGetActiveResult = z
-  .object({
-    buildingId: z.string(),
-  })
-  .nullable()
-export type PluginCoreBuildingsGetActiveResult = z.infer<
-  typeof PluginCoreBuildingsGetActiveResult
->
-
-/**
- * Arguments for {@linkcode PluginCoreBuildingsApi.setActive}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `buildingId` | `string` | The id of the building to activate |
- */
-export const PluginCoreBuildingsSetActiveArgs = z.object({
-  buildingId: z.string(),
-})
-export type PluginCoreBuildingsSetActiveArgs = z.infer<
-  typeof PluginCoreBuildingsSetActiveArgs
->
-
-/**
- * Result of {@linkcode PluginCoreBuildingsApi.setActive} — the now-active
- * building's id.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `buildingId` | `string` | The id of the now-active building |
- */
-export const PluginCoreBuildingsSetActiveResult = z.object({
-  buildingId: z.string(),
-})
-export type PluginCoreBuildingsSetActiveResult = z.infer<
-  typeof PluginCoreBuildingsSetActiveResult
->
-
-/**
- * Arguments for {@linkcode PluginCoreBuildingsApi.create}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `name` | `string` | Display name of the new building |
- * | `baseElevation` | `number \| undefined` | Base elevation in meters (defaults to `0`) |
- */
-export const PluginCoreBuildingsCreateArgs = z.object({
-  name: z.string(),
-  baseElevation: z.number().optional(),
-})
-export type PluginCoreBuildingsCreateArgs = z.infer<
-  typeof PluginCoreBuildingsCreateArgs
->
-
-/**
- * Result of {@linkcode PluginCoreBuildingsApi.create} — the id of the new
- * building.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `buildingId` | `string` | The id of the newly created building |
- */
-export const PluginCoreBuildingsCreateResult = z.object({
-  buildingId: z.string(),
-})
-export type PluginCoreBuildingsCreateResult = z.infer<
-  typeof PluginCoreBuildingsCreateResult
->
-
-/**
- * Arguments for {@linkcode PluginCoreBuildingsApi.update}. Sparse — only the
- * provided fields are changed.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `buildingId` | `string` | The id of the building to update |
- * | `name` | `string \| undefined` | New display name (unchanged if omitted) |
- * | `baseElevation` | `number \| undefined` | New base elevation in meters (unchanged if omitted) |
- */
-export const PluginCoreBuildingsUpdateArgs = z.object({
-  buildingId: z.string(),
-  name: z.string().optional(),
-  baseElevation: z.number().optional(),
-})
-export type PluginCoreBuildingsUpdateArgs = z.infer<
-  typeof PluginCoreBuildingsUpdateArgs
->
-
-/** Result of {@linkcode PluginCoreBuildingsApi.update} — the updated record. */
-export const PluginCoreBuildingsUpdateResult = PluginCoreBuildingRef
-export type PluginCoreBuildingsUpdateResult = z.infer<
-  typeof PluginCoreBuildingsUpdateResult
->
-
-/**
- * Arguments for {@linkcode PluginCoreBuildingsApi.copy}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `buildingId` | `string` | The id of the building to copy |
- * | `name` | `string \| undefined` | Name for the copy (auto-generated if omitted) |
- * | `baseElevation` | `number \| undefined` | Base elevation for the copy in meters (source's if omitted) |
- * | `asInstances` | `boolean \| undefined` | `true` shares source geometry as instances; `false` makes independent copies (host default `true`) |
- */
-export const PluginCoreBuildingsCopyArgs = z.object({
-  buildingId: z.string(),
-  name: z.string().optional(),
-  baseElevation: z.number().optional(),
-  asInstances: z.boolean().optional(),
-})
-export type PluginCoreBuildingsCopyArgs = z.infer<
-  typeof PluginCoreBuildingsCopyArgs
->
-
-/**
- * Result of {@linkcode PluginCoreBuildingsApi.copy} — the id of the new
- * building.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `buildingId` | `string` | The id of the copied building |
- */
-export const PluginCoreBuildingsCopyResult = z.object({
-  buildingId: z.string(),
-})
-export type PluginCoreBuildingsCopyResult = z.infer<
-  typeof PluginCoreBuildingsCopyResult
->
-
-/**
- * Arguments for {@linkcode PluginCoreBuildingsApi.delete}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `buildingId` | `string` | The id of the building to delete |
- */
-export const PluginCoreBuildingsDeleteArgs = z.object({
-  buildingId: z.string(),
-})
-export type PluginCoreBuildingsDeleteArgs = z.infer<
-  typeof PluginCoreBuildingsDeleteArgs
->
-
-/**
- * Result of {@linkcode PluginCoreBuildingsApi.delete} — confirmation that the
- * building was deleted.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `deleted` | `true` | Always `true` on success |
- */
-export const PluginCoreBuildingsDeleteResult = z.object({
-  deleted: z.literal(true),
-})
-export type PluginCoreBuildingsDeleteResult = z.infer<
-  typeof PluginCoreBuildingsDeleteResult
->
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+
+/**
+ * Buildings — read and edit the buildings of the active project.
+ *
+ * A **building** is the top of the project's spatial hierarchy: a named container
+ * of storeys, positioned by its base elevation. This namespace reads a building's
+ * identity and base elevation and lists the storeys it holds; storey detail is
+ * read through the entity story surface (`snaptrude.entity.story`).
+ *
+ * Reads return plain records and never throw for a missing building (`get` and
+ * `getActive` return `null`, `list` returns `[]`). Ids are stable public strings.
+ *
+ * Sub-namespace members typed as optional (`?`) are **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 them (at which point they are promoted
+ * to required `abstract` members).
+ *
+ * Accessed via `snaptrude.core.buildings`.
+ */
+export abstract class PluginCoreBuildingsApi {
+  constructor() {}
+
+  /**
+   * List the buildings in the active project.
+   *
+   * @returns A {@linkcode PluginCoreBuildingsListResult} with a `buildings` array
+   *   (empty when the project has none).
+   *
+   * @examplePrompt List all the buildings in my project
+   * @examplePrompt How many buildings are in this model?
+   * @examplePrompt Show every building with its base elevation
+   *
+   * # Example
+   * ```ts
+   * const { buildings } = await snaptrude.core.buildings.list()
+   * for (const b of buildings) console.log(b.name, b.baseElevation)
+   * ```
+   */
+  public abstract list(): PluginApiReturn<PluginCoreBuildingsListResult>
+
+  /**
+   * Get a single building by id.
+   *
+   * @param buildingId - The id of the building to read.
+   * @returns The matching {@linkcode PluginCoreBuildingRef}, or `null` if no
+   *   building has that id.
+   *
+   * @examplePrompt Get the building with id blg_1
+   * @examplePrompt Look up a single building by its id
+   * @examplePrompt What is the base elevation of building blg_2?
+   *
+   * # Example
+   * ```ts
+   * const building = await snaptrude.core.buildings.get("blg_1")
+   * if (building) console.log(building.name, building.baseElevation)
+   * ```
+   */
+  public abstract get(
+    buildingId: string,
+  ): PluginApiReturn<PluginCoreBuildingsGetResult>
+
+  /**
+   * List the storeys of a building.
+   *
+   * Returns the building's storeys as stable storey ids, in the project's storey
+   * order. Read each storey's detail through `snaptrude.entity.story`.
+   *
+   * @param buildingId - The id of the building whose storeys to list.
+   * @returns A {@linkcode PluginCoreBuildingsListStoreysResult} with a `storeyIds`
+   *   array (empty when the building is missing or has no storeys).
+   *
+   * @examplePrompt List the storeys in building blg_1
+   * @examplePrompt How many floors does this building have?
+   * @examplePrompt Get the storey ids of the active building
+   *
+   * # Example
+   * ```ts
+   * const { storeyIds } = await snaptrude.core.buildings.listStoreys("blg_1")
+   * console.log(`${storeyIds.length} storeys`)
+   * ```
+   */
+  public abstract listStoreys(
+    buildingId: string,
+  ): PluginApiReturn<PluginCoreBuildingsListStoreysResult>
+
+  /**
+   * Get the active building.
+   *
+   * The active building is the one new storeys and edits target. Paired with
+   * {@linkcode PluginCoreBuildingsApi.setActive}.
+   *
+   * @returns A {@linkcode PluginCoreBuildingsGetActiveResult} with the active
+   *   `buildingId`, or `null` if there is no active building.
+   *
+   * @examplePrompt Which building is active?
+   * @examplePrompt Get the current building
+   * @examplePrompt What building am I working in?
+   *
+   * # Example
+   * ```ts
+   * const active = await snaptrude.core.buildings.getActive()
+   * if (active) console.log(active.buildingId)
+   * ```
+   */
+  public abstract getActive(): PluginApiReturn<PluginCoreBuildingsGetActiveResult>
+
+  /**
+   * Make a building the active building.
+   *
+   * Paired with {@linkcode PluginCoreBuildingsApi.getActive}.
+   *
+   * @param buildingId - The id of the building to activate.
+   * @returns The id of the now-active building.
+   * @throws If no building has the given id.
+   *
+   * @examplePrompt Switch to building blg_2
+   * @examplePrompt Make this building the active one
+   * @examplePrompt Set the active building to blg_1
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.buildings.setActive("blg_2")
+   * ```
+   */
+  public abstract setActive(
+    buildingId: string,
+  ): PluginApiReturn<PluginCoreBuildingsSetActiveResult>
+
+  /**
+   * Create a new building.
+   *
+   * Adds a named building at the given base elevation (defaults to `0`). The new
+   * building starts empty — add storeys through the storeys namespace.
+   *
+   * @param name - Display name of the new building.
+   * @param baseElevation - Base elevation in meters (defaults to `0`).
+   * @returns The new building's id (read the full record back with
+   *   {@linkcode PluginCoreBuildingsApi.get}).
+   * @throws If the building could not be created.
+   *
+   * @examplePrompt Create a building called Tower B
+   * @examplePrompt Add a new building at elevation 12 meters
+   * @examplePrompt Make a second building named Annex
+   *
+   * # Example
+   * ```ts
+   * const { buildingId } = await snaptrude.core.buildings.create("Tower B", 0)
+   * ```
+   */
+  public abstract create(
+    name: string,
+    baseElevation?: number,
+  ): PluginApiReturn<PluginCoreBuildingsCreateResult>
+
+  /**
+   * Update a building's name and/or base elevation.
+   *
+   * A **sparse** update: omitted fields are left unchanged.
+   *
+   * @param buildingId - The id of the building to update.
+   * @param options - Any of `name`, `baseElevation`; omitted fields are left
+   *   unchanged.
+   * @returns The updated {@linkcode PluginCoreBuildingRef}.
+   * @throws If no building has the given id.
+   *
+   * @examplePrompt Rename building blg_1 to Tower A
+   * @examplePrompt Move the building up to elevation 6 meters
+   * @examplePrompt Change the base elevation of blg_2
+   *
+   * # Example
+   * ```ts
+   * const building = await snaptrude.core.buildings.update("blg_1", { name: "Tower A" })
+   * ```
+   */
+  public abstract update(
+    buildingId: string,
+    options?: { name?: string; baseElevation?: number },
+  ): PluginApiReturn<PluginCoreBuildingsUpdateResult>
+
+  /**
+   * Copy a building.
+   *
+   * Copies the building — its storeys, components, and drawing layers — into a new
+   * building. `asInstances` controls the copy's geometry: `true` shares the source
+   * geometry as instances (low memory), `false` makes independent editable copies
+   * (the host defaults to `true`). Optionally override the copy's `name` and
+   * `baseElevation`.
+   *
+   * @param buildingId - The id of the building to copy.
+   * @param options - Optional `name`, `baseElevation`, `asInstances` overrides
+   *   for the copy.
+   * @returns The new building's id.
+   * @throws If no building has the given id.
+   *
+   * @examplePrompt Copy building blg_1
+   * @examplePrompt Make an independent editable copy of this building
+   * @examplePrompt Copy Tower A as instances to save memory
+   *
+   * # Example
+   * ```ts
+   * const { buildingId } = await snaptrude.core.buildings.copy("blg_1", {
+   *   name: "Tower A Copy",
+   *   asInstances: false,
+   * })
+   * ```
+   */
+  public abstract copy(
+    buildingId: string,
+    options?: { name?: string; baseElevation?: number; asInstances?: boolean },
+  ): PluginApiReturn<PluginCoreBuildingsCopyResult>
+
+  /**
+   * Delete a building.
+   *
+   * **Gated and destructive.** Deleting a building cascades through its meshes,
+   * storeys, and the building itself, and removes its saved views — **saved views
+   * are not restored on undo.** The project's only remaining building cannot be
+   * deleted.
+   *
+   * @param buildingId - The id of the building to delete.
+   * @returns Confirmation that the building was deleted.
+   * @throws If no building has the given id, or it is the only building.
+   *
+   * @examplePrompt Delete building blg_2
+   * @examplePrompt Remove the Annex building and everything in it
+   * @examplePrompt Delete this building
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.buildings.delete("blg_2")
+   * ```
+   */
+  public abstract delete(
+    buildingId: string,
+  ): PluginApiReturn<PluginCoreBuildingsDeleteResult>
+}
+
+/**
+ * A building in the active project.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Stable public building id (e.g. `"blg_1"`) |
+ * | `name` | `string` | Display name |
+ * | `baseElevation` | `number` | Base elevation in meters, positive up (default `0`) |
+ */
+export const PluginCoreBuildingRef = z.object({
+  id: z.string(),
+  name: z.string(),
+  baseElevation: z.number(),
+})
+export type PluginCoreBuildingRef = z.infer<typeof PluginCoreBuildingRef>
+
+/**
+ * Result of {@linkcode PluginCoreBuildingsApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildings` | {@linkcode PluginCoreBuildingRef}`[]` | Every building in the active project |
+ */
+export const PluginCoreBuildingsListResult = z.object({
+  buildings: z.array(PluginCoreBuildingRef),
+})
+export type PluginCoreBuildingsListResult = z.infer<
+  typeof PluginCoreBuildingsListResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreBuildingsApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildingId` | `string` | The id of the building to read |
+ */
+export const PluginCoreBuildingsGetArgs = z.object({
+  buildingId: z.string(),
+})
+export type PluginCoreBuildingsGetArgs = z.infer<
+  typeof PluginCoreBuildingsGetArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreBuildingsApi.get} — the building, or `null` when
+ * no building has the given id.
+ */
+export const PluginCoreBuildingsGetResult = PluginCoreBuildingRef.nullable()
+export type PluginCoreBuildingsGetResult = z.infer<
+  typeof PluginCoreBuildingsGetResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreBuildingsApi.listStoreys}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildingId` | `string` | The id of the building whose storeys to list |
+ */
+export const PluginCoreBuildingsListStoreysArgs = z.object({
+  buildingId: z.string(),
+})
+export type PluginCoreBuildingsListStoreysArgs = z.infer<
+  typeof PluginCoreBuildingsListStoreysArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreBuildingsApi.listStoreys}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storeyIds` | `string[]` | The building's storey ids in storey order (empty when missing or none) |
+ */
+export const PluginCoreBuildingsListStoreysResult = z.object({
+  storeyIds: z.array(z.string()),
+})
+export type PluginCoreBuildingsListStoreysResult = z.infer<
+  typeof PluginCoreBuildingsListStoreysResult
+>
+
+/**
+ * Result of {@linkcode PluginCoreBuildingsApi.getActive} — the active building's
+ * id, or `null` when there is no active building.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildingId` | `string` | The id of the active building |
+ */
+export const PluginCoreBuildingsGetActiveResult = z
+  .object({
+    buildingId: z.string(),
+  })
+  .nullable()
+export type PluginCoreBuildingsGetActiveResult = z.infer<
+  typeof PluginCoreBuildingsGetActiveResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreBuildingsApi.setActive}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildingId` | `string` | The id of the building to activate |
+ */
+export const PluginCoreBuildingsSetActiveArgs = z.object({
+  buildingId: z.string(),
+})
+export type PluginCoreBuildingsSetActiveArgs = z.infer<
+  typeof PluginCoreBuildingsSetActiveArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreBuildingsApi.setActive} — the now-active
+ * building's id.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildingId` | `string` | The id of the now-active building |
+ */
+export const PluginCoreBuildingsSetActiveResult = z.object({
+  buildingId: z.string(),
+})
+export type PluginCoreBuildingsSetActiveResult = z.infer<
+  typeof PluginCoreBuildingsSetActiveResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreBuildingsApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | Display name of the new building |
+ * | `baseElevation` | `number \| undefined` | Base elevation in meters (defaults to `0`) |
+ */
+export const PluginCoreBuildingsCreateArgs = z.object({
+  name: z.string(),
+  baseElevation: z.number().optional(),
+})
+export type PluginCoreBuildingsCreateArgs = z.infer<
+  typeof PluginCoreBuildingsCreateArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreBuildingsApi.create} — the id of the new
+ * building.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildingId` | `string` | The id of the newly created building |
+ */
+export const PluginCoreBuildingsCreateResult = z.object({
+  buildingId: z.string(),
+})
+export type PluginCoreBuildingsCreateResult = z.infer<
+  typeof PluginCoreBuildingsCreateResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreBuildingsApi.update}. Sparse — only the
+ * provided fields are changed.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildingId` | `string` | The id of the building to update |
+ * | `name` | `string \| undefined` | New display name (unchanged if omitted) |
+ * | `baseElevation` | `number \| undefined` | New base elevation in meters (unchanged if omitted) |
+ */
+export const PluginCoreBuildingsUpdateArgs = z.object({
+  buildingId: z.string(),
+  name: z.string().optional(),
+  baseElevation: z.number().optional(),
+})
+export type PluginCoreBuildingsUpdateArgs = z.infer<
+  typeof PluginCoreBuildingsUpdateArgs
+>
+
+/** Result of {@linkcode PluginCoreBuildingsApi.update} — the updated record. */
+export const PluginCoreBuildingsUpdateResult = PluginCoreBuildingRef
+export type PluginCoreBuildingsUpdateResult = z.infer<
+  typeof PluginCoreBuildingsUpdateResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreBuildingsApi.copy}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildingId` | `string` | The id of the building to copy |
+ * | `name` | `string \| undefined` | Name for the copy (auto-generated if omitted) |
+ * | `baseElevation` | `number \| undefined` | Base elevation for the copy in meters (source's if omitted) |
+ * | `asInstances` | `boolean \| undefined` | `true` shares source geometry as instances; `false` makes independent copies (host default `true`) |
+ */
+export const PluginCoreBuildingsCopyArgs = z.object({
+  buildingId: z.string(),
+  name: z.string().optional(),
+  baseElevation: z.number().optional(),
+  asInstances: z.boolean().optional(),
+})
+export type PluginCoreBuildingsCopyArgs = z.infer<
+  typeof PluginCoreBuildingsCopyArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreBuildingsApi.copy} — the id of the new
+ * building.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildingId` | `string` | The id of the copied building |
+ */
+export const PluginCoreBuildingsCopyResult = z.object({
+  buildingId: z.string(),
+})
+export type PluginCoreBuildingsCopyResult = z.infer<
+  typeof PluginCoreBuildingsCopyResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreBuildingsApi.delete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `buildingId` | `string` | The id of the building to delete |
+ */
+export const PluginCoreBuildingsDeleteArgs = z.object({
+  buildingId: z.string(),
+})
+export type PluginCoreBuildingsDeleteArgs = z.infer<
+  typeof PluginCoreBuildingsDeleteArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreBuildingsApi.delete} — confirmation that the
+ * building was deleted.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `deleted` | `true` | Always `true` on success |
+ */
+export const PluginCoreBuildingsDeleteResult = z.object({
+  deleted: z.literal(true),
+})
+export type PluginCoreBuildingsDeleteResult = z.infer<
+  typeof PluginCoreBuildingsDeleteResult
+>