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

package/src/api/core/storeys/index.ts

@@ -1,308 +1,311 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../../types"
-import { ComponentHandle } from "../../../handles"
-import {
-  PluginStoryGetProperty,
-  PluginStoryGetResult,
-  PluginStoryGetAllResult,
-  PluginStoryCreateResult,
-  PluginStoryUpdateResult,
-  PluginStorySetActiveResult,
-  PluginStoryDeleteResult,
-  PluginStoryDuplicateResult,
-} from "../../entity/story"
-import { PluginCoreStoreysLayersApi } from "./layers"
-
-/**
- * Storey (floor) management.
- *
- * A storey represents a building floor in the Snaptrude project. Storeys are
- * identified by their integer **storey value** (e.g. `1` for the ground floor,
- * `2` for the first floor, `-1` for a basement).
- *
- * This is the canonical home for storey operations; it shares its implementation
- * and schemas with the deprecated `entity.story` surface. All methods are **host
- * API calls** that return Promises and support undo/redo via Snaptrude's command
- * system (except {@linkcode PluginCoreStoreysApi.setActive}, a view change).
- *
- * - {@linkcode PluginCoreStoreysApi.layers} — each storey's sketch surfaces
- *   (Wall, Rough) and imported underlays (CAD, PDF, image, terrain): list, get,
- *   active layer get/set, show/hide. Not the Layers panel; that is `core.layers`.
- *
- * Accessed via `snaptrude.core.storeys`.
- */
-export abstract class PluginCoreStoreysApi {
-  constructor() {}
-
-  /**
-   * Storey layers — each storey's sketch surfaces and imported underlays (ids
-   * like `ly_5`), formerly `core.layers`. Not the layers in the Layers panel;
-   * use `core.layers` for those. See {@linkcode PluginCoreStoreysLayersApi}.
-   */
-  public abstract layers: PluginCoreStoreysLayersApi
-
-  /**
-   * Get properties of a storey by its storey number.
-   *
-   * Only the properties listed in `properties` are returned — unlisted
-   * properties will be `undefined` in the result.
-   *
-   * @param storyValue - Integer storey number
-   *   (e.g. `1` for ground floor, `2` for first floor, `-1` for basement)
-   * @param properties - Array of property names to retrieve. See
-   *   {@linkcode PluginStoryGetProperty} for available values.
-   * @returns A partial {@linkcode PluginStoryGetResult} containing only the requested properties
-   * @throws If the storey with the given value does not exist
-   *
-   * @examplePrompt What is the height of the ground floor?
-   * @examplePrompt How many rooms are on the second storey?
-   * @examplePrompt Get the total floor area of level 3
-   * @examplePrompt Is the first floor hidden in the viewport?
-   * @examplePrompt Show me the name and height of storey 2
-   *
-   * # Example
-   * ```ts
-   * const info = await snaptrude.core.storeys.get(1, ["height", "name", "spacesCount"])
-   * console.log(info.name, info.height, info.spacesCount)
-   * ```
-   */
-  public abstract get(
-    storyValue: number,
-    properties: PluginStoryGetProperty[],
-  ): PluginApiReturn<PluginStoryGetResult>
-
-  /**
-   * List all storeys in the current project.
-   *
-   * Returns basic identification data for every storey. Storeys are sorted
-   * from **top to bottom** (highest storey value first).
-   *
-   * @returns A {@linkcode PluginCoreStoreysListResult} with a `storeys` array,
-   *   each entry containing `value`, `id`, and `name`
-   *
-   * @examplePrompt How many floors does this building have?
-   * @examplePrompt List all the storeys in the project
-   * @examplePrompt Show me every level with its name
-   * @examplePrompt Which storeys exist in this model?
-   *
-   * # Example
-   * ```ts
-   * const { storeys } = await snaptrude.core.storeys.list()
-   * for (const s of storeys) {
-   *   console.log(`Storey ${s.value}: ${s.name} (id: ${s.id})`)
-   * }
-   * ```
-   */
-  public abstract list(): PluginApiReturn<PluginCoreStoreysListResult>
-
-  /**
-   * Create a new storey (floor) in the project.
-   *
-   * The new storey is inserted at the position specified by `storyValue`. This
-   * operation is undoable.
-   *
-   * @param storyValue - Integer storey number
-   *   to create (e.g. `3` to add a third floor)
-   * @param height - Optional height in Babylon
-   *   units. If omitted, the project's default storey height is used.
-   * @returns A {@linkcode PluginStoryCreateResult} with `storyId` and `storyValue`
-   * @throws If a storey with the given value already exists or creation fails
-   *
-   * @examplePrompt Add a third floor to the building
-   * @examplePrompt Create a new storey above the second floor
-   * @examplePrompt Add a basement level to this project
-   * @examplePrompt Insert a new level with a custom floor height
-   *
-   * # Example
-   * ```ts
-   * // Create a new third floor with custom height
-   * const { storyId } = await snaptrude.core.storeys.create(3, 4.5)
-   * ```
-   */
-  public abstract create(
-    storyValue: number,
-    height?: number,
-  ): PluginApiReturn<PluginStoryCreateResult>
-
-  /**
-   * Update a storey's floor-to-floor `height` and/or `name`.
-   *
-   * **Height** is the same operation as editing the height in the Storeys panel:
-   * the walls, columns, and masses on the storey are **stretched** to the new
-   * height, every storey **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 storey in the Storeys panel: it is
-   * persisted immediately 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 storey to update
-   * @param height - New floor-to-floor height in
-   *   Babylon units. Omit to leave the height unchanged.
-   * @param options - `name` (new display name for the storey)
-   * @returns A {@linkcode PluginStoryUpdateResult} with the storey's
-   *   `storyValue`, `height`, and `name` after the update
-   * @throws `PRECONDITION_FAILED` if no storey has the given value;
-   *   `VALIDATION` if neither `height` nor `options.name` is supplied;
-   *   `STORY_HEIGHT_REJECTED` if the engine rejects the height;
-   *   `STORY_UPDATE_FAILED` if the storey 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
-   *
-   * # Example
-   * ```ts
-   * // 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.core.storeys.update(1, 5)
-   * // Rename only, leaving the height untouched.
-   * await snaptrude.core.storeys.update(1, undefined, { name: "Lobby" })
-   * ```
-   */
-  public abstract update(
-    storyValue: number,
-    height?: number,
-    options?: { name?: string },
-  ): PluginApiReturn<PluginStoryUpdateResult>
-
-  /**
-   * Get the active storey's value. Paired with {@linkcode PluginCoreStoreysApi.setActive}.
-   *
-   * @returns The active storey value, in the same numbering `list` and `get` use.
-   *
-   * @examplePrompt Which storey am I on?
-   * @examplePrompt What is the current storey?
-   *
-   * # Example
-   * ```ts
-   * const storey = await snaptrude.core.storeys.getActive()
-   * ```
-   */
-  public abstract getActive(): PluginApiReturn<number>
-
-  /**
-   * Make a storey the active storey — the same as clicking it in the storey/layer
-   * panel. Subsequent draws and creates target this storey, 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 storey 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 storey 2, then draw a wall — it lands on storey 2.
-   * await snaptrude.core.storeys.setActive(2)
-   * ```
-   */
-  public abstract setActive(
-    storyValue: number,
-  ): PluginApiReturn<PluginStorySetActiveResult>
-
-  /**
-   * Delete a storey and everything on it — the same as removing it from the
-   * storey panel. Every element placed on the storey (walls, floors, masses, …)
-   * is deleted with it, the remaining storeys are re-stacked, and the active
-   * storey 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 storey 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.core.storeys.delete(3)
-   * console.log(`Deleted storey 3; now on storey ${newActiveStory}`)
-   * ```
-   */
-  public abstract delete(
-    storyValue: number,
-  ): PluginApiReturn<PluginStoryDeleteResult>
-
-  /**
-   * Copy a storey into the adjacent level, up or down.
-   *
-   * By default the **whole storey** is copied: every eligible element on the
-   * active storey (walls, floors, roofs, masses, columns, beams, staircases,
-   * ceilings, parametric curtain walls, and furniture) is copied into the storey
-   * one level `"up"` or `"down"`. Pass `options.components` to copy only a subset
-   * instead. The target storey is **created automatically** if it does not yet
-   * exist, inheriting the source storey'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 copied 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 copy into the storey above, `"down"` for below
-   * @param options - `components` (restrict to a subset of the storey's elements;
-   *   omit for the whole storey) 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 storeys generated to receive them, and the
-   *   `skipped` count of ineligible elements
-   * @throws `NO_ACTIVE_STRUCTURE` if there is no active structure to copy into;
-   *   `NO_ELIGIBLE_ELEMENTS` if nothing on the source storey (or in
-   *   `options.components`) is copyable; `HANDLE_INVALID` for a stale or foreign
-   *   supplied handle; or if plugin writes are disabled
-   *
-   * @examplePrompt Copy 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 Copy just the selected walls onto the next floor up
-   *
-   * # Example
-   * ```ts
-   * // Copy the whole active storey one level up (instanced copies).
-   * const { targetStories, created, skipped } =
-   *   await snaptrude.core.storeys.copy("up")
-   * console.log(`Copied ${created.length} elements onto storey ${targetStories}`)
-   * if (skipped) console.log(`${skipped} elements were skipped`)
-   * ```
-   */
-  public abstract copy(
-    direction: "up" | "down",
-    options?: { components?: ComponentHandle[]; unique?: boolean },
-  ): PluginApiReturn<PluginStoryDuplicateResult>
-}
-
-/**
- * Result of {@linkcode PluginCoreStoreysApi.list} — the {@linkcode PluginStoryGetAllResult}
- * shape with the array field renamed `stories` → `storeys`. Each entry shares the
- * same element type: `{ value, id, name }`, sorted top to bottom.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `storeys` | `Array<{ value, id, name }>` | All storeys, sorted top to bottom |
- */
-export const PluginCoreStoreysListResult = z.object({
-  storeys: PluginStoryGetAllResult.shape.stories,
-})
-
-export type PluginCoreStoreysListResult = z.infer<
-  typeof PluginCoreStoreysListResult
->
-
-export * from "./layers"
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { ComponentHandle } from "../../../handles"
+import {
+  PluginStoryGetProperty,
+  PluginStoryGetResult,
+  PluginStoryGetAllResult,
+  PluginStoryCreateResult,
+  PluginStoryUpdateResult,
+  PluginStorySetActiveResult,
+  PluginStoryDeleteResult,
+  PluginStoryDuplicateResult,
+} from "../../entity/story"
+import { PluginCoreStoreysLayersApi } from "./layers"
+
+/**
+ * Storey (floor) management.
+ *
+ * A storey represents a building floor in the Snaptrude project. Storeys are
+ * identified by their integer **storey value** (e.g. `1` for the ground floor,
+ * `2` for the first floor, `-1` for a basement).
+ *
+ * This is the canonical home for storey operations; it shares its implementation
+ * and schemas with the deprecated `entity.story` surface. All methods are **host
+ * API calls** that return Promises and support undo/redo via Snaptrude's command
+ * system (except {@linkcode PluginCoreStoreysApi.setActive}, a view change).
+ *
+ * - {@linkcode PluginCoreStoreysApi.layers} — each storey's sketch surfaces
+ *   (Wall, Rough) and imported underlays (CAD, PDF, image, terrain): list, get,
+ *   active layer get/set, show/hide. Not the Layers panel; that is `core.layers`.
+ *
+ * Accessed via `snaptrude.core.storeys`.
+ */
+export abstract class PluginCoreStoreysApi {
+  constructor() {}
+
+  /**
+   * Storey layers — each storey's sketch surfaces and imported underlays (ids
+   * like `ly_5`), formerly `core.layers`. Not the layers in the Layers panel;
+   * use `core.layers` for those. See {@linkcode PluginCoreStoreysLayersApi}.
+   */
+  public abstract layers: PluginCoreStoreysLayersApi
+
+  /**
+   * Get properties of a storey by its storey number.
+   *
+   * Only the properties listed in `properties` are returned — unlisted
+   * properties will be `undefined` in the result.
+   *
+   * @param storyValue - Integer storey number
+   *   (e.g. `1` for ground floor, `2` for first floor, `-1` for basement)
+   * @param properties - Array of property names to retrieve. See
+   *   {@linkcode PluginStoryGetProperty} for available values.
+   * @returns A partial {@linkcode PluginStoryGetResult} containing only the requested properties
+   * @throws If the storey with the given value does not exist
+   *
+   * @examplePrompt What is the height of the ground floor?
+   * @examplePrompt How many rooms are on the second storey?
+   * @examplePrompt Get the total floor area of level 3
+   * @examplePrompt Is the first floor hidden in the viewport?
+   * @examplePrompt Show me the name and height of storey 2
+   *
+   * # Example
+   * ```ts
+   * const info = await snaptrude.core.storeys.get(1, ["height", "name", "spacesCount"])
+   * console.log(info.name, info.height, info.spacesCount)
+   * ```
+   */
+  public abstract get(
+    storyValue: number,
+    properties: PluginStoryGetProperty[],
+  ): PluginApiReturn<PluginStoryGetResult>
+
+  /**
+   * List all storeys in the current project.
+   *
+   * Returns basic identification data for every storey. Storeys are sorted
+   * from **top to bottom** (highest storey value first).
+   *
+   * @returns A {@linkcode PluginCoreStoreysListResult} with a `storeys` array,
+   *   each entry containing `value`, `id`, and `name`
+   *
+   * @examplePrompt How many floors does this building have?
+   * @examplePrompt List all the storeys in the project
+   * @examplePrompt Show me every level with its name
+   * @examplePrompt Which storeys exist in this model?
+   *
+   * # Example
+   * ```ts
+   * const { storeys } = await snaptrude.core.storeys.list()
+   * for (const s of storeys) {
+   *   console.log(`Storey ${s.value}: ${s.name} (id: ${s.id})`)
+   * }
+   * ```
+   */
+  public abstract list(): PluginApiReturn<PluginCoreStoreysListResult>
+
+  /**
+   * Create a new storey (floor) in the project.
+   *
+   * The new storey is inserted at the position specified by `storyValue`. This
+   * operation is undoable.
+   *
+   * @param storyValue - Integer storey number
+   *   to create (e.g. `3` to add a third floor)
+   * @param height - Optional height in Babylon
+   *   units. If omitted, the project's default storey height is used.
+   * @returns A {@linkcode PluginStoryCreateResult} with `storyId` and `storyValue`
+   * @throws If a storey with the given value already exists or creation fails
+   *
+   * @examplePrompt Add a third floor to the building
+   * @examplePrompt Create a new storey above the second floor
+   * @examplePrompt Add a basement level to this project
+   * @examplePrompt Insert a new level with a custom floor height
+   *
+   * # Example
+   * ```ts
+   * // Create a new third floor with custom height
+   * const { storyId } = await snaptrude.core.storeys.create(3, 4.5)
+   * ```
+   */
+  public abstract create(
+    storyValue: number,
+    height?: number,
+  ): PluginApiReturn<PluginStoryCreateResult>
+
+  /**
+   * Update a storey's floor-to-floor `height` and/or `name`.
+   *
+   * **Height** is the same operation as editing the height in the Storeys panel:
+   * the walls, columns, and masses on the storey are **stretched** to the new
+   * height, every storey **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 storey in the Storeys panel: it is
+   * persisted immediately 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 storey to update
+   * @param height - New floor-to-floor height in
+   *   Babylon units. Omit to leave the height unchanged.
+   * @param options - `name` (new display name for the storey)
+   * @returns A {@linkcode PluginStoryUpdateResult} with the storey's
+   *   `storyValue`, `height`, and `name` after the update
+   * @throws `PRECONDITION_FAILED` if no storey has the given value;
+   *   `VALIDATION` if neither `height` nor `options.name` is supplied;
+   *   `STORY_HEIGHT_REJECTED` if the engine rejects the height;
+   *   `STORY_UPDATE_FAILED` if the storey 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
+   *
+   * # Example
+   * ```ts
+   * // 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.core.storeys.update(1, 5)
+   * // Rename only, leaving the height untouched.
+   * await snaptrude.core.storeys.update(1, undefined, { name: "Lobby" })
+   * ```
+   */
+  public abstract update(
+    storyValue: number,
+    height?: number,
+    options?: { name?: string },
+  ): PluginApiReturn<PluginStoryUpdateResult>
+
+  /**
+   * Get the active storey's value. Paired with {@linkcode PluginCoreStoreysApi.setActive}.
+   *
+   * @returns The active storey value, in the same numbering `list` and `get` use.
+   *
+   * @examplePrompt Which storey am I on?
+   * @examplePrompt What is the current storey?
+   *
+   * # Example
+   * ```ts
+   * const storey = await snaptrude.core.storeys.getActive()
+   * ```
+   */
+  public abstract getActive(): PluginApiReturn<number>
+
+  /**
+   * Make a storey the active storey — the same as clicking it in the storey/layer
+   * panel. Subsequent draws and creates target this storey, and in 2D the
+   * viewport switches to that storey's plan (and its cut range), unless the
+   * active view is already a plan on 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 storey has the given value, or in 2D if
+   *   the storey has no plan
+   *
+   * @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 storey 2, then draw a wall — it lands on storey 2.
+   * await snaptrude.core.storeys.setActive(2)
+   * ```
+   */
+  public abstract setActive(
+    storyValue: number,
+  ): PluginApiReturn<PluginStorySetActiveResult>
+
+  /**
+   * Delete a storey and everything on it — the same as removing it from the
+   * storey panel. Every element placed on the storey (walls, floors, masses, …)
+   * is deleted with it, the remaining storeys are re-stacked, and the active
+   * storey 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 storey 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.core.storeys.delete(3)
+   * console.log(`Deleted storey 3; now on storey ${newActiveStory}`)
+   * ```
+   */
+  public abstract delete(
+    storyValue: number,
+  ): PluginApiReturn<PluginStoryDeleteResult>
+
+  /**
+   * Copy a storey into the adjacent level, up or down.
+   *
+   * By default the **whole storey** is copied: every eligible element on the
+   * active storey (walls, floors, roofs, masses, columns, beams, staircases,
+   * ceilings, parametric curtain walls, and furniture) is copied into the storey
+   * one level `"up"` or `"down"`. Pass `options.components` to copy only a subset
+   * instead. The target storey is **created automatically** if it does not yet
+   * exist, inheriting the source storey'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 copied 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 copy into the storey above, `"down"` for below
+   * @param options - `components` (restrict to a subset of the storey's elements;
+   *   omit for the whole storey) 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 storeys generated to receive them, and the
+   *   `skipped` count of ineligible elements
+   * @throws `NO_ACTIVE_STRUCTURE` if there is no active structure to copy into;
+   *   `NO_ELIGIBLE_ELEMENTS` if nothing on the source storey (or in
+   *   `options.components`) is copyable; `HANDLE_INVALID` for a stale or foreign
+   *   supplied handle; or if plugin writes are disabled
+   *
+   * @examplePrompt Copy 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 Copy just the selected walls onto the next floor up
+   *
+   * # Example
+   * ```ts
+   * // Copy the whole active storey one level up (instanced copies).
+   * const { targetStories, created, skipped } =
+   *   await snaptrude.core.storeys.copy("up")
+   * console.log(`Copied ${created.length} elements onto storey ${targetStories}`)
+   * if (skipped) console.log(`${skipped} elements were skipped`)
+   * ```
+   */
+  public abstract copy(
+    direction: "up" | "down",
+    options?: { components?: ComponentHandle[]; unique?: boolean },
+  ): PluginApiReturn<PluginStoryDuplicateResult>
+}
+
+/**
+ * Result of {@linkcode PluginCoreStoreysApi.list} — the {@linkcode PluginStoryGetAllResult}
+ * shape with the array field renamed `stories` → `storeys`. Each entry shares the
+ * same element type: `{ value, id, name }`, sorted top to bottom.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storeys` | `Array<{ value, id, name }>` | All storeys, sorted top to bottom |
+ */
+export const PluginCoreStoreysListResult = z.object({
+  storeys: PluginStoryGetAllResult.shape.stories,
+})
+
+export type PluginCoreStoreysListResult = z.infer<
+  typeof PluginCoreStoreysListResult
+>
+
+export * from "./layers"