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

package/src/api/core/layers.ts

@@ -1,540 +1,540 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../types"
-import { ComponentHandle } from "../../handles"
-
-/**
- * Layers — the layers in the **Layers panel** in the left sidebar (the panel
- * with the "+" add-layer button and one row per layer, such as "Default" or
- * "BIM layer"; the radio mark is the active layer).
- *
- * A layer is a named group of objects. Every object is on exactly one layer, and
- * new objects land on the active layer. Each row can be renamed, locked, hidden
- * and deleted, and objects can be moved between layers.
- *
- * These are **not** each storey's sketch surfaces and imported underlays (ids
- * like `ly_5`); those are {@linkcode PluginCoreStoreysLayersApi}
- * (`core.storeys.layers`, formerly `core.layers`). They are also not wall/floor
- * construction-assembly material layers.
- *
- * Each design option ({@linkcode PluginCoreProposalsApi}) owns a set of layers;
- * `core.proposals` records refer to these ids as `bucketIds` and
- * `defaultBucketId`. `list` and every write are scoped to the **active** design
- * option, like the panel; on legacy projects without design options every layer
- * is in scope. Reads never throw for a missing layer (`get` and `getActive`
- * return `null`).
- *
- * **Compatibility.** Before 0.9.15 this namespace was the storey sketch-surface
- * API that is now {@linkcode PluginCoreStoreysLayersApi}. Calls in that shape
- * keep working here and are routed to it: `list(storeyId)`, `getActive(storeyId)`,
- * and `get` / `setActive` / `update(layerId, hidden)` with a storey-layer id
- * (`ly_*`). They are deprecated: new code calls `core.storeys.layers` directly.
- *
- * Accessed via `snaptrude.core.layers`.
- */
-export abstract class PluginCoreLayersApi {
-  constructor() {}
-
-  /**
-   * List the layers in the Layers panel: the active design option's layers,
-   * default layer first, then in creation order.
-   *
-   * @returns A {@linkcode PluginCoreLayersListResult} with a `layers` array.
-   *
-   * @examplePrompt List all the layers in the Layers panel
-   * @examplePrompt Show me the layers in the left sidebar
-   * @examplePrompt What layers does this project have?
-   * @examplePrompt Show every layer with whether it is locked or hidden
-   * @examplePrompt Which layer is the default layer?
-   * @examplePrompt Which layers are empty?
-   *
-   * # Example
-   * ```ts
-   * const { layers } = await snaptrude.core.layers.list()
-   * for (const l of layers) console.log(l.name, l.objectCount, l.locked, l.hidden)
-   * ```
-   */
-  public abstract list(): PluginApiReturn<PluginCoreLayersListResult>
-
-  /**
-   * Get one Layers-panel layer by id, including layers owned by other design
-   * options.
-   *
-   * @param layerId - The id of the layer to read.
-   * @returns The matching {@linkcode PluginCoreLayer}, or `null` if no layer has
-   *   that id.
-   *
-   * @examplePrompt Get the Layers-panel layer with id 3f2a…
-   * @examplePrompt Is the Furniture layer locked or hidden?
-   * @examplePrompt How many objects are on layer 3f2a…?
-   *
-   * # Example
-   * ```ts
-   * const layer = await snaptrude.core.layers.get(layerId)
-   * if (layer) console.log(layer.name, layer.objectCount)
-   * ```
-   */
-  public abstract get(
-    layerId: string,
-  ): PluginApiReturn<PluginCoreLayersGetResult>
-
-  /**
-   * Get the active Layers-panel layer: the one new objects land on.
-   *
-   * @returns The active {@linkcode PluginCoreLayer}, or `null` if none is set.
-   *
-   * @examplePrompt Which layer is active?
-   * @examplePrompt Which layer in the Layers panel is active?
-   * @examplePrompt What layer will new objects go on?
-   * @examplePrompt Which layer are new walls and masses being added to?
-   *
-   * # Example
-   * ```ts
-   * const active = await snaptrude.core.layers.getActive()
-   * if (active) console.log(active.name)
-   * ```
-   */
-  public abstract getActive(): PluginApiReturn<PluginCoreLayersGetActiveResult>
-
-  /**
-   * Create a new layer in the Layers panel (the panel's "Add new layer" button
-   * followed by naming it).
-   *
-   * The layer is added to the active design option and is **not** made active;
-   * call {@linkcode PluginCoreLayersApi.setActive} to put new objects on it.
-   * Names are trimmed, 1-40 characters, and must be unique across all layers
-   * (case-insensitive). **Undoable.**
-   *
-   * @param name - The new layer's name.
-   * @returns The created {@linkcode PluginCoreLayer}.
-   * @throws `VALIDATION` for an empty name or one longer than 40 characters;
-   *   `PRECONDITION_FAILED` if a layer with that name already exists.
-   *
-   * @examplePrompt Create a new layer called Furniture
-   * @examplePrompt Add a layer called Landscape
-   * @examplePrompt Add a layer named Landscape to the Layers panel
-   * @examplePrompt Make a new layer for the facade elements
-   * @examplePrompt Create layers named Structure and Services
-   *
-   * # Example
-   * ```ts
-   * const layer = await snaptrude.core.layers.create("Furniture")
-   * await snaptrude.core.layers.setActive(layer.id)
-   * ```
-   */
-  public abstract create(
-    name: string,
-  ): PluginApiReturn<PluginCoreLayersCreateResult>
-
-  /**
-   * Rename a layer (the panel row's "Rename layer").
-   *
-   * Names are trimmed, 1-40 characters, and must be unique across all layers
-   * (case-insensitive; changing only the case of the layer's own name is
-   * allowed). The default layer cannot be renamed. **Not undoable.**
-   *
-   * @param layerId - The id of the layer to rename.
-   * @param name - The new name.
-   * @returns The updated {@linkcode PluginCoreLayer}.
-   * @throws `VALIDATION` for a bad name; `HANDLE_INVALID` for an unknown
-   *   `layerId`; `PRECONDITION_FAILED` if the layer is the default layer, is
-   *   outside the active design option, or the name is already used;
-   *   `OPERATION_FAILED` if the app refuses the rename.
-   *
-   * @examplePrompt Rename the Furniture layer to Loose furniture
-   * @examplePrompt Rename layer 3f2a… to Existing building
-   * @examplePrompt Change the name of the Landscape layer
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.core.layers.rename(layerId, "Loose furniture")
-   * ```
-   */
-  public abstract rename(
-    layerId: string,
-    name: string,
-  ): PluginApiReturn<PluginCoreLayersRenameResult>
-
-  /**
-   * Lock/unlock or show/hide a layer (the panel row's padlock and eye).
-   *
-   * A **sparse** update: omitted fields are unchanged. `hidden` is **per-user**:
-   * it hides the layer for you, not for collaborators. Locking and hiding block
-   * interactive drawing in the app; plugin creates are not blocked (see
-   * {@linkcode PluginCoreLayersApi.setActive}). **Undoable**, one undo step per
-   * changed field.
-   *
-   * @param layerId - The id of the layer to update.
-   * @param options - `{ locked?, hidden? }`; omitted fields are unchanged.
-   * @returns The updated {@linkcode PluginCoreLayer}.
-   * @throws `VALIDATION` for any option other than `locked` / `hidden` (to
-   *   rename, use {@linkcode PluginCoreLayersApi.rename}); `HANDLE_INVALID` for
-   *   an unknown `layerId`; `PRECONDITION_FAILED` if the layer is outside the
-   *   active design option, or `hidden` is changed with no signed-in user.
-   *
-   * @examplePrompt Lock the Default layer
-   * @examplePrompt Lock the Structure layer
-   * @examplePrompt Hide the Landscape layer in the Layers panel
-   * @examplePrompt Unlock layer 3f2a… and show it again
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.core.layers.update(layerId, { locked: true, hidden: false })
-   * ```
-   */
-  public abstract update(
-    layerId: string,
-    options?: { locked?: boolean; hidden?: boolean },
-  ): PluginApiReturn<PluginCoreLayersUpdateResult>
-
-  /**
-   * Make a layer the active layer (clicking its row in the Layers panel).
-   *
-   * New objects, whether drawn in the app or created by plugins with
-   * `design.create.*`, land on the active layer. When the active layer is locked
-   * or hidden the app blocks interactive drawing, but plugin creates still land
-   * on it: objects created on a hidden layer are invisible, and objects on a
-   * locked layer cannot be edited. Unlock or show the layer first
-   * ({@linkcode PluginCoreLayersApi.update}). **Not undoable.**
-   *
-   * @param layerId - The id of the layer to activate.
-   * @returns The id of the now-active layer.
-   * @throws `HANDLE_INVALID` for an unknown `layerId`; `PRECONDITION_FAILED` if
-   *   the layer is outside the active design option.
-   *
-   * @examplePrompt Put new objects on the Furniture layer
-   * @examplePrompt Make the Structure layer the active layer in the Layers panel
-   * @examplePrompt Switch the active layer to Landscape
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.core.layers.setActive(layerId)
-   * ```
-   */
-  public abstract setActive(
-    layerId: string,
-  ): PluginApiReturn<PluginCoreLayersSetActiveResult>
-
-  /**
-   * Delete a layer (the panel row's "Delete layer").
-   *
-   * Choose **exactly one** disposition, mirroring the delete dialog:
-   *
-   * - `{ deleteObjects: true }` destroys the objects on the layer.
-   * - `{ targetLayerId }` moves them to another layer of the active design
-   *   option first, then deletes the emptied layer.
-   *
-   * A bare `delete(layerId)` is **rejected**: the engine would drop the layer
-   * and leave its objects on a missing layer. Refused for the default layer, the
-   * last layer, a locked layer, a layer shared with other design options
-   * (`proposalIds.length > 1`; unshare it in the app first), and, with
-   * `deleteObjects`, when any object on it is locked. The server checks that no
-   * collaborator is using the layer (needs a live connection; times out after
-   * ~10 s). If the layer was active, the active design option's default layer
-   * becomes active.
-   *
-   * **Treat as permanent.** `core.history.undo` restores the layer in this
-   * session only; the server does not re-link it to its design option, so after
-   * a reload it is missing from the panel.
-   *
-   * @param layerId - The id of the layer to delete.
-   * @param options - Exactly one disposition: `{ deleteObjects: true }` or
-   *   `{ targetLayerId }`.
-   * @returns Confirmation that the layer was deleted.
-   * @throws `VALIDATION` for no disposition, both, or `targetLayerId` equal to
-   *   `layerId`; `HANDLE_INVALID` for an unknown `layerId` or
-   *   `targetLayerId`; `PRECONDITION_FAILED` for the refusals above or a layer
-   *   or target outside the active design option; `OPERATION_FAILED` if the
-   *   server refuses (a collaborator is using it), the connection is down, or
-   *   the check times out.
-   *
-   * @examplePrompt Delete the Furniture layer and everything on it
-   * @examplePrompt Delete the Furniture layer and move its objects to Default
-   * @examplePrompt Remove layer 3f2a… and move its objects to the default layer
-   * @examplePrompt Merge the Services layer into Structure and delete it
-   * @examplePrompt Delete every empty layer
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.core.layers.delete(layerId, { deleteObjects: true })
-   * const { layers } = await snaptrude.core.layers.list()
-   * const def = layers.find((l) => l.isDefault)!
-   * await snaptrude.core.layers.delete(otherId, { targetLayerId: def.id })
-   * ```
-   */
-  public abstract delete(
-    layerId: string,
-    options:
-      | { deleteObjects: true; targetLayerId?: never }
-      | { deleteObjects?: false; targetLayerId: string },
-  ): PluginApiReturn<PluginCoreLayersDeleteResult>
-
-  /**
-   * Move objects onto a layer (picking a layer in the object properties panel).
-   *
-   * Doors, windows and voids hosted by a moved wall (and a terrain's
-   * neighbourhood buildings) move with it; if any of those is locked, the parent
-   * is skipped as `locked`. Locked objects, unknown ids and objects outside the
-   * active design option are returned in `skipped`, never silently dropped. The target layer's own lock
-   * does not block the move. An object is always on exactly one layer, so there
-   * is no `unassign`: assign to another layer instead. **Undoable** (one step).
-   *
-   * @param componentIds - The objects to move.
-   * @param layerId - The target layer.
-   * @returns A {@linkcode PluginCoreLayersAssignResult} splitting `assigned`
-   *   from `skipped`.
-   * @throws `VALIDATION` for an empty `componentIds`; `HANDLE_INVALID` for an
-   *   unknown `layerId`; `PRECONDITION_FAILED` if the target is outside the
-   *   active design option.
-   *
-   * @examplePrompt Move the selected objects to the BIM layer
-   * @examplePrompt Move the selected objects to the Furniture layer
-   * @examplePrompt Assign the generated walls to the Structure layer
-   * @examplePrompt Put these masses on layer 3f2a…
-   *
-   * # Example
-   * ```ts
-   * const { assigned, skipped } = await snaptrude.core.layers.assign(ids, layerId)
-   * ```
-   */
-  public abstract assign(
-    componentIds: ComponentHandle[],
-    layerId: string,
-  ): PluginApiReturn<PluginCoreLayersAssignResult>
-}
-
-/**
- * A layer in the Layers panel.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `id` | `string` | Layer id (the ids `core.proposals` records list) |
- * | `name` | `string` | Display name (1-40 characters, unique case-insensitively) |
- * | `isDefault` | `boolean` | The design option's default layer: cannot be renamed or deleted |
- * | `isActive` | `boolean` | Whether new objects land on this layer |
- * | `locked` | `boolean` | Whether the layer is locked (its objects cannot be edited) |
- * | `hidden` | `boolean` | Whether the layer is hidden **for the current user** |
- * | `proposalIds` | `string[]` | Design options that own the layer (more than one = shared) |
- * | `objectCount` | `number` | Objects currently on the layer (0 = empty) |
- */
-export const PluginCoreLayer = z.object({
-  id: z.string(),
-  name: z.string(),
-  isDefault: z.boolean(),
-  isActive: z.boolean(),
-  locked: z.boolean(),
-  hidden: z.boolean(),
-  proposalIds: z.array(z.string()),
-  objectCount: z.number().int(),
-})
-export type PluginCoreLayer = z.infer<typeof PluginCoreLayer>
-
-/** A layer name: trimmed, 1-40 characters (the panel input's limit). */
-export const PluginCoreLayerName = z.string().trim().min(1).max(40)
-
-/**
- * Result of {@linkcode PluginCoreLayersApi.list}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `layers` | {@linkcode PluginCoreLayer}`[]` | The active design option's layers, default first |
- */
-export const PluginCoreLayersListResult = z.object({
-  layers: z.array(PluginCoreLayer),
-})
-export type PluginCoreLayersListResult = z.infer<
-  typeof PluginCoreLayersListResult
->
-
-/**
- * Arguments for {@linkcode PluginCoreLayersApi.get}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `layerId` | `string` | The id of the layer to read |
- */
-export const PluginCoreLayersGetArgs = z.object({ layerId: z.string() })
-export type PluginCoreLayersGetArgs = z.infer<typeof PluginCoreLayersGetArgs>
-
-/** Result of {@linkcode PluginCoreLayersApi.get}: the layer, or `null`. */
-export const PluginCoreLayersGetResult = PluginCoreLayer.nullable()
-export type PluginCoreLayersGetResult = z.infer<
-  typeof PluginCoreLayersGetResult
->
-
-/** Result of {@linkcode PluginCoreLayersApi.getActive}: the active layer, or `null`. */
-export const PluginCoreLayersGetActiveResult = PluginCoreLayer.nullable()
-export type PluginCoreLayersGetActiveResult = z.infer<
-  typeof PluginCoreLayersGetActiveResult
->
-
-/**
- * Arguments for {@linkcode PluginCoreLayersApi.create}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `name` | `string` | The new layer's name (trimmed, 1-40 characters) |
- */
-export const PluginCoreLayersCreateArgs = z.object({
-  name: PluginCoreLayerName,
-})
-export type PluginCoreLayersCreateArgs = z.infer<
-  typeof PluginCoreLayersCreateArgs
->
-
-/** Result of {@linkcode PluginCoreLayersApi.create}: the created layer. */
-export const PluginCoreLayersCreateResult = PluginCoreLayer
-export type PluginCoreLayersCreateResult = z.infer<
-  typeof PluginCoreLayersCreateResult
->
-
-/**
- * Arguments for {@linkcode PluginCoreLayersApi.rename}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `layerId` | `string` | The id of the layer to rename |
- * | `name` | `string` | The new name (trimmed, 1-40 characters) |
- */
-export const PluginCoreLayersRenameArgs = z.object({
-  layerId: z.string(),
-  name: PluginCoreLayerName,
-})
-export type PluginCoreLayersRenameArgs = z.infer<
-  typeof PluginCoreLayersRenameArgs
->
-
-/** Result of {@linkcode PluginCoreLayersApi.rename}: the updated layer. */
-export const PluginCoreLayersRenameResult = PluginCoreLayer
-export type PluginCoreLayersRenameResult = z.infer<
-  typeof PluginCoreLayersRenameResult
->
-
-/**
- * Arguments for {@linkcode PluginCoreLayersApi.update}. Sparse: only the
- * provided fields are changed.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `layerId` | `string` | The id of the layer to update |
- * | `locked` | `boolean \| undefined` | New locked state (unchanged if omitted) |
- * | `hidden` | `boolean \| undefined` | New hidden state for the current user (unchanged if omitted) |
- */
-export const PluginCoreLayersUpdateArgs = z.object({
-  layerId: z.string(),
-  locked: z.boolean().optional(),
-  hidden: z.boolean().optional(),
-}).strict()
-export type PluginCoreLayersUpdateArgs = z.infer<
-  typeof PluginCoreLayersUpdateArgs
->
-
-/** Result of {@linkcode PluginCoreLayersApi.update}: the updated layer. */
-export const PluginCoreLayersUpdateResult = PluginCoreLayer
-export type PluginCoreLayersUpdateResult = z.infer<
-  typeof PluginCoreLayersUpdateResult
->
-
-/**
- * Arguments for {@linkcode PluginCoreLayersApi.setActive}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `layerId` | `string` | The id of the layer to activate |
- */
-export const PluginCoreLayersSetActiveArgs = z.object({ layerId: z.string() })
-export type PluginCoreLayersSetActiveArgs = z.infer<
-  typeof PluginCoreLayersSetActiveArgs
->
-
-/**
- * Result of {@linkcode PluginCoreLayersApi.setActive}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `layerId` | `string` | The id of the now-active layer |
- */
-export const PluginCoreLayersSetActiveResult = z.object({
-  layerId: z.string(),
-})
-export type PluginCoreLayersSetActiveResult = z.infer<
-  typeof PluginCoreLayersSetActiveResult
->
-
-/**
- * Arguments for {@linkcode PluginCoreLayersApi.delete}. Exactly one
- * disposition is required: `deleteObjects: true` XOR `targetLayerId` (a
- * **different** layer).
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `layerId` | `string` | The id of the layer to delete |
- * | `deleteObjects` | `boolean \| undefined` | `true` destroys the layer's objects (exclusive with `targetLayerId`) |
- * | `targetLayerId` | `string \| undefined` | Move the layer's objects to this layer, then delete (exclusive with `deleteObjects`) |
- */
-export const PluginCoreLayersDeleteArgs = z
-  .object({
-    layerId: z.string(),
-    deleteObjects: z.boolean().optional(),
-    targetLayerId: z.string().optional(),
-  })
-  .refine((v) => (v.deleteObjects === true) !== (v.targetLayerId != null), {
-    message:
-      "Provide exactly one disposition: deleteObjects: true (destroy the layer's objects) or targetLayerId (move them to that layer, then delete)",
-  })
-  .refine((v) => v.targetLayerId == null || v.targetLayerId !== v.layerId, {
-    message: "targetLayerId must be a different layer than layerId",
-  })
-export type PluginCoreLayersDeleteArgs = z.infer<
-  typeof PluginCoreLayersDeleteArgs
->
-
-/**
- * Result of {@linkcode PluginCoreLayersApi.delete}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `deleted` | `true` | The layer was deleted |
- */
-export const PluginCoreLayersDeleteResult = z.object({
-  deleted: z.literal(true),
-})
-export type PluginCoreLayersDeleteResult = z.infer<
-  typeof PluginCoreLayersDeleteResult
->
-
-/**
- * Arguments for {@linkcode PluginCoreLayersApi.assign}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `componentIds` | `string[]` | The objects to move (at least one) |
- * | `layerId` | `string` | The target layer |
- */
-export const PluginCoreLayersAssignArgs = z.object({
-  componentIds: z.array(ComponentHandle).min(1),
-  layerId: z.string(),
-})
-export type PluginCoreLayersAssignArgs = z.infer<
-  typeof PluginCoreLayersAssignArgs
->
-
-/**
- * Result of {@linkcode PluginCoreLayersApi.assign}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `assigned` | `string[]` | Ids of the objects that were moved |
- * | `skipped` | `{ id: string; reason: "not-found" \| "locked" \| "outside-proposal" }[]` | Objects that were not moved, each with a reason |
- */
-export const PluginCoreLayersAssignResult = z.object({
-  assigned: z.array(ComponentHandle),
-  skipped: z.array(
-    z.object({
-      id: ComponentHandle,
-      reason: z.enum(["not-found", "locked", "outside-proposal"]),
-    }),
-  ),
-})
-export type PluginCoreLayersAssignResult = z.infer<
-  typeof PluginCoreLayersAssignResult
->
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import { ComponentHandle } from "../../handles"
+
+/**
+ * Layers — the layers in the **Layers panel** in the left sidebar (the panel
+ * with the "+" add-layer button and one row per layer, such as "Default" or
+ * "BIM layer"; the radio mark is the active layer).
+ *
+ * A layer is a named group of objects. Every object is on exactly one layer, and
+ * new objects land on the active layer. Each row can be renamed, locked, hidden
+ * and deleted, and objects can be moved between layers.
+ *
+ * These are **not** each storey's sketch surfaces and imported underlays (ids
+ * like `ly_5`); those are {@linkcode PluginCoreStoreysLayersApi}
+ * (`core.storeys.layers`, formerly `core.layers`). They are also not wall/floor
+ * construction-assembly material layers.
+ *
+ * Each design option ({@linkcode PluginCoreProposalsApi}) owns a set of layers;
+ * `core.proposals` records refer to these ids as `bucketIds` and
+ * `defaultBucketId`. `list` and every write are scoped to the **active** design
+ * option, like the panel; on legacy projects without design options every layer
+ * is in scope. Reads never throw for a missing layer (`get` and `getActive`
+ * return `null`).
+ *
+ * **Compatibility.** Before 0.9.15 this namespace was the storey sketch-surface
+ * API that is now {@linkcode PluginCoreStoreysLayersApi}. Calls in that shape
+ * keep working here and are routed to it: `list(storeyId)`, `getActive(storeyId)`,
+ * and `get` / `setActive` / `update(layerId, hidden)` with a storey-layer id
+ * (`ly_*`). They are deprecated: new code calls `core.storeys.layers` directly.
+ *
+ * Accessed via `snaptrude.core.layers`.
+ */
+export abstract class PluginCoreLayersApi {
+  constructor() {}
+
+  /**
+   * List the layers in the Layers panel: the active design option's layers,
+   * default layer first, then in creation order.
+   *
+   * @returns A {@linkcode PluginCoreLayersListResult} with a `layers` array.
+   *
+   * @examplePrompt List all the layers in the Layers panel
+   * @examplePrompt Show me the layers in the left sidebar
+   * @examplePrompt What layers does this project have?
+   * @examplePrompt Show every layer with whether it is locked or hidden
+   * @examplePrompt Which layer is the default layer?
+   * @examplePrompt Which layers are empty?
+   *
+   * # Example
+   * ```ts
+   * const { layers } = await snaptrude.core.layers.list()
+   * for (const l of layers) console.log(l.name, l.objectCount, l.locked, l.hidden)
+   * ```
+   */
+  public abstract list(): PluginApiReturn<PluginCoreLayersListResult>
+
+  /**
+   * Get one Layers-panel layer by id, including layers owned by other design
+   * options.
+   *
+   * @param layerId - The id of the layer to read.
+   * @returns The matching {@linkcode PluginCoreLayer}, or `null` if no layer has
+   *   that id.
+   *
+   * @examplePrompt Get the Layers-panel layer with id 3f2a…
+   * @examplePrompt Is the Furniture layer locked or hidden?
+   * @examplePrompt How many objects are on layer 3f2a…?
+   *
+   * # Example
+   * ```ts
+   * const layer = await snaptrude.core.layers.get(layerId)
+   * if (layer) console.log(layer.name, layer.objectCount)
+   * ```
+   */
+  public abstract get(
+    layerId: string,
+  ): PluginApiReturn<PluginCoreLayersGetResult>
+
+  /**
+   * Get the active Layers-panel layer: the one new objects land on.
+   *
+   * @returns The active {@linkcode PluginCoreLayer}, or `null` if none is set.
+   *
+   * @examplePrompt Which layer is active?
+   * @examplePrompt Which layer in the Layers panel is active?
+   * @examplePrompt What layer will new objects go on?
+   * @examplePrompt Which layer are new walls and masses being added to?
+   *
+   * # Example
+   * ```ts
+   * const active = await snaptrude.core.layers.getActive()
+   * if (active) console.log(active.name)
+   * ```
+   */
+  public abstract getActive(): PluginApiReturn<PluginCoreLayersGetActiveResult>
+
+  /**
+   * Create a new layer in the Layers panel (the panel's "Add new layer" button
+   * followed by naming it).
+   *
+   * The layer is added to the active design option and is **not** made active;
+   * call {@linkcode PluginCoreLayersApi.setActive} to put new objects on it.
+   * Names are trimmed, 1-40 characters, and must be unique across all layers
+   * (case-insensitive). **Undoable.**
+   *
+   * @param name - The new layer's name.
+   * @returns The created {@linkcode PluginCoreLayer}.
+   * @throws `VALIDATION` for an empty name or one longer than 40 characters;
+   *   `PRECONDITION_FAILED` if a layer with that name already exists.
+   *
+   * @examplePrompt Create a new layer called Furniture
+   * @examplePrompt Add a layer called Landscape
+   * @examplePrompt Add a layer named Landscape to the Layers panel
+   * @examplePrompt Make a new layer for the facade elements
+   * @examplePrompt Create layers named Structure and Services
+   *
+   * # Example
+   * ```ts
+   * const layer = await snaptrude.core.layers.create("Furniture")
+   * await snaptrude.core.layers.setActive(layer.id)
+   * ```
+   */
+  public abstract create(
+    name: string,
+  ): PluginApiReturn<PluginCoreLayersCreateResult>
+
+  /**
+   * Rename a layer (the panel row's "Rename layer").
+   *
+   * Names are trimmed, 1-40 characters, and must be unique across all layers
+   * (case-insensitive; changing only the case of the layer's own name is
+   * allowed). The default layer cannot be renamed. **Not undoable.**
+   *
+   * @param layerId - The id of the layer to rename.
+   * @param name - The new name.
+   * @returns The updated {@linkcode PluginCoreLayer}.
+   * @throws `VALIDATION` for a bad name; `HANDLE_INVALID` for an unknown
+   *   `layerId`; `PRECONDITION_FAILED` if the layer is the default layer, is
+   *   outside the active design option, or the name is already used;
+   *   `OPERATION_FAILED` if the app refuses the rename.
+   *
+   * @examplePrompt Rename the Furniture layer to Loose furniture
+   * @examplePrompt Rename layer 3f2a… to Existing building
+   * @examplePrompt Change the name of the Landscape layer
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.layers.rename(layerId, "Loose furniture")
+   * ```
+   */
+  public abstract rename(
+    layerId: string,
+    name: string,
+  ): PluginApiReturn<PluginCoreLayersRenameResult>
+
+  /**
+   * Lock/unlock or show/hide a layer (the panel row's padlock and eye).
+   *
+   * A **sparse** update: omitted fields are unchanged. `hidden` is **per-user**:
+   * it hides the layer for you, not for collaborators. Locking and hiding block
+   * interactive drawing in the app; plugin creates are not blocked (see
+   * {@linkcode PluginCoreLayersApi.setActive}). **Undoable**, one undo step per
+   * changed field.
+   *
+   * @param layerId - The id of the layer to update.
+   * @param options - `{ locked?, hidden? }`; omitted fields are unchanged.
+   * @returns The updated {@linkcode PluginCoreLayer}.
+   * @throws `VALIDATION` for any option other than `locked` / `hidden` (to
+   *   rename, use {@linkcode PluginCoreLayersApi.rename}); `HANDLE_INVALID` for
+   *   an unknown `layerId`; `PRECONDITION_FAILED` if the layer is outside the
+   *   active design option, or `hidden` is changed with no signed-in user.
+   *
+   * @examplePrompt Lock the Default layer
+   * @examplePrompt Lock the Structure layer
+   * @examplePrompt Hide the Landscape layer in the Layers panel
+   * @examplePrompt Unlock layer 3f2a… and show it again
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.layers.update(layerId, { locked: true, hidden: false })
+   * ```
+   */
+  public abstract update(
+    layerId: string,
+    options?: { locked?: boolean; hidden?: boolean },
+  ): PluginApiReturn<PluginCoreLayersUpdateResult>
+
+  /**
+   * Make a layer the active layer (clicking its row in the Layers panel).
+   *
+   * New objects, whether drawn in the app or created by plugins with
+   * `design.create.*`, land on the active layer. When the active layer is locked
+   * or hidden the app blocks interactive drawing, but plugin creates still land
+   * on it: objects created on a hidden layer are invisible, and objects on a
+   * locked layer cannot be edited. Unlock or show the layer first
+   * ({@linkcode PluginCoreLayersApi.update}). **Not undoable.**
+   *
+   * @param layerId - The id of the layer to activate.
+   * @returns The id of the now-active layer.
+   * @throws `HANDLE_INVALID` for an unknown `layerId`; `PRECONDITION_FAILED` if
+   *   the layer is outside the active design option.
+   *
+   * @examplePrompt Put new objects on the Furniture layer
+   * @examplePrompt Make the Structure layer the active layer in the Layers panel
+   * @examplePrompt Switch the active layer to Landscape
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.layers.setActive(layerId)
+   * ```
+   */
+  public abstract setActive(
+    layerId: string,
+  ): PluginApiReturn<PluginCoreLayersSetActiveResult>
+
+  /**
+   * Delete a layer (the panel row's "Delete layer").
+   *
+   * Choose **exactly one** disposition, mirroring the delete dialog:
+   *
+   * - `{ deleteObjects: true }` destroys the objects on the layer.
+   * - `{ targetLayerId }` moves them to another layer of the active design
+   *   option first, then deletes the emptied layer.
+   *
+   * A bare `delete(layerId)` is **rejected**: the engine would drop the layer
+   * and leave its objects on a missing layer. Refused for the default layer, the
+   * last layer, a locked layer, a layer shared with other design options
+   * (`proposalIds.length > 1`; unshare it in the app first), and, with
+   * `deleteObjects`, when any object on it is locked. The server checks that no
+   * collaborator is using the layer (needs a live connection; times out after
+   * ~10 s). If the layer was active, the active design option's default layer
+   * becomes active.
+   *
+   * **Treat as permanent.** `core.history.undo` restores the layer in this
+   * session only; the server does not re-link it to its design option, so after
+   * a reload it is missing from the panel.
+   *
+   * @param layerId - The id of the layer to delete.
+   * @param options - Exactly one disposition: `{ deleteObjects: true }` or
+   *   `{ targetLayerId }`.
+   * @returns Confirmation that the layer was deleted.
+   * @throws `VALIDATION` for no disposition, both, or `targetLayerId` equal to
+   *   `layerId`; `HANDLE_INVALID` for an unknown `layerId` or
+   *   `targetLayerId`; `PRECONDITION_FAILED` for the refusals above or a layer
+   *   or target outside the active design option; `OPERATION_FAILED` if the
+   *   server refuses (a collaborator is using it), the connection is down, or
+   *   the check times out.
+   *
+   * @examplePrompt Delete the Furniture layer and everything on it
+   * @examplePrompt Delete the Furniture layer and move its objects to Default
+   * @examplePrompt Remove layer 3f2a… and move its objects to the default layer
+   * @examplePrompt Merge the Services layer into Structure and delete it
+   * @examplePrompt Delete every empty layer
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.layers.delete(layerId, { deleteObjects: true })
+   * const { layers } = await snaptrude.core.layers.list()
+   * const def = layers.find((l) => l.isDefault)!
+   * await snaptrude.core.layers.delete(otherId, { targetLayerId: def.id })
+   * ```
+   */
+  public abstract delete(
+    layerId: string,
+    options:
+      | { deleteObjects: true; targetLayerId?: never }
+      | { deleteObjects?: false; targetLayerId: string },
+  ): PluginApiReturn<PluginCoreLayersDeleteResult>
+
+  /**
+   * Move objects onto a layer (picking a layer in the object properties panel).
+   *
+   * Doors, windows and voids hosted by a moved wall (and a terrain's
+   * neighbourhood buildings) move with it; if any of those is locked, the parent
+   * is skipped as `locked`. Locked objects, unknown ids and objects outside the
+   * active design option are returned in `skipped`, never silently dropped. The target layer's own lock
+   * does not block the move. An object is always on exactly one layer, so there
+   * is no `unassign`: assign to another layer instead. **Undoable** (one step).
+   *
+   * @param componentIds - The objects to move.
+   * @param layerId - The target layer.
+   * @returns A {@linkcode PluginCoreLayersAssignResult} splitting `assigned`
+   *   from `skipped`.
+   * @throws `VALIDATION` for an empty `componentIds`; `HANDLE_INVALID` for an
+   *   unknown `layerId`; `PRECONDITION_FAILED` if the target is outside the
+   *   active design option.
+   *
+   * @examplePrompt Move the selected objects to the BIM layer
+   * @examplePrompt Move the selected objects to the Furniture layer
+   * @examplePrompt Assign the generated walls to the Structure layer
+   * @examplePrompt Put these masses on layer 3f2a…
+   *
+   * # Example
+   * ```ts
+   * const { assigned, skipped } = await snaptrude.core.layers.assign(ids, layerId)
+   * ```
+   */
+  public abstract assign(
+    componentIds: ComponentHandle[],
+    layerId: string,
+  ): PluginApiReturn<PluginCoreLayersAssignResult>
+}
+
+/**
+ * A layer in the Layers panel.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Layer id (the ids `core.proposals` records list) |
+ * | `name` | `string` | Display name (1-40 characters, unique case-insensitively) |
+ * | `isDefault` | `boolean` | The design option's default layer: cannot be renamed or deleted |
+ * | `isActive` | `boolean` | Whether new objects land on this layer |
+ * | `locked` | `boolean` | Whether the layer is locked (its objects cannot be edited) |
+ * | `hidden` | `boolean` | Whether the layer is hidden **for the current user** |
+ * | `proposalIds` | `string[]` | Design options that own the layer (more than one = shared) |
+ * | `objectCount` | `number` | Objects currently on the layer (0 = empty) |
+ */
+export const PluginCoreLayer = z.object({
+  id: z.string(),
+  name: z.string(),
+  isDefault: z.boolean(),
+  isActive: z.boolean(),
+  locked: z.boolean(),
+  hidden: z.boolean(),
+  proposalIds: z.array(z.string()),
+  objectCount: z.number().int(),
+})
+export type PluginCoreLayer = z.infer<typeof PluginCoreLayer>
+
+/** A layer name: trimmed, 1-40 characters (the panel input's limit). */
+export const PluginCoreLayerName = z.string().trim().min(1).max(40)
+
+/**
+ * Result of {@linkcode PluginCoreLayersApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `layers` | {@linkcode PluginCoreLayer}`[]` | The active design option's layers, default first |
+ */
+export const PluginCoreLayersListResult = z.object({
+  layers: z.array(PluginCoreLayer),
+})
+export type PluginCoreLayersListResult = z.infer<
+  typeof PluginCoreLayersListResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreLayersApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `layerId` | `string` | The id of the layer to read |
+ */
+export const PluginCoreLayersGetArgs = z.object({ layerId: z.string() })
+export type PluginCoreLayersGetArgs = z.infer<typeof PluginCoreLayersGetArgs>
+
+/** Result of {@linkcode PluginCoreLayersApi.get}: the layer, or `null`. */
+export const PluginCoreLayersGetResult = PluginCoreLayer.nullable()
+export type PluginCoreLayersGetResult = z.infer<
+  typeof PluginCoreLayersGetResult
+>
+
+/** Result of {@linkcode PluginCoreLayersApi.getActive}: the active layer, or `null`. */
+export const PluginCoreLayersGetActiveResult = PluginCoreLayer.nullable()
+export type PluginCoreLayersGetActiveResult = z.infer<
+  typeof PluginCoreLayersGetActiveResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreLayersApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | The new layer's name (trimmed, 1-40 characters) |
+ */
+export const PluginCoreLayersCreateArgs = z.object({
+  name: PluginCoreLayerName,
+})
+export type PluginCoreLayersCreateArgs = z.infer<
+  typeof PluginCoreLayersCreateArgs
+>
+
+/** Result of {@linkcode PluginCoreLayersApi.create}: the created layer. */
+export const PluginCoreLayersCreateResult = PluginCoreLayer
+export type PluginCoreLayersCreateResult = z.infer<
+  typeof PluginCoreLayersCreateResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreLayersApi.rename}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `layerId` | `string` | The id of the layer to rename |
+ * | `name` | `string` | The new name (trimmed, 1-40 characters) |
+ */
+export const PluginCoreLayersRenameArgs = z.object({
+  layerId: z.string(),
+  name: PluginCoreLayerName,
+})
+export type PluginCoreLayersRenameArgs = z.infer<
+  typeof PluginCoreLayersRenameArgs
+>
+
+/** Result of {@linkcode PluginCoreLayersApi.rename}: the updated layer. */
+export const PluginCoreLayersRenameResult = PluginCoreLayer
+export type PluginCoreLayersRenameResult = z.infer<
+  typeof PluginCoreLayersRenameResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreLayersApi.update}. Sparse: only the
+ * provided fields are changed.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `layerId` | `string` | The id of the layer to update |
+ * | `locked` | `boolean \| undefined` | New locked state (unchanged if omitted) |
+ * | `hidden` | `boolean \| undefined` | New hidden state for the current user (unchanged if omitted) |
+ */
+export const PluginCoreLayersUpdateArgs = z.object({
+  layerId: z.string(),
+  locked: z.boolean().optional(),
+  hidden: z.boolean().optional(),
+}).strict()
+export type PluginCoreLayersUpdateArgs = z.infer<
+  typeof PluginCoreLayersUpdateArgs
+>
+
+/** Result of {@linkcode PluginCoreLayersApi.update}: the updated layer. */
+export const PluginCoreLayersUpdateResult = PluginCoreLayer
+export type PluginCoreLayersUpdateResult = z.infer<
+  typeof PluginCoreLayersUpdateResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreLayersApi.setActive}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `layerId` | `string` | The id of the layer to activate |
+ */
+export const PluginCoreLayersSetActiveArgs = z.object({ layerId: z.string() })
+export type PluginCoreLayersSetActiveArgs = z.infer<
+  typeof PluginCoreLayersSetActiveArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreLayersApi.setActive}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `layerId` | `string` | The id of the now-active layer |
+ */
+export const PluginCoreLayersSetActiveResult = z.object({
+  layerId: z.string(),
+})
+export type PluginCoreLayersSetActiveResult = z.infer<
+  typeof PluginCoreLayersSetActiveResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreLayersApi.delete}. Exactly one
+ * disposition is required: `deleteObjects: true` XOR `targetLayerId` (a
+ * **different** layer).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `layerId` | `string` | The id of the layer to delete |
+ * | `deleteObjects` | `boolean \| undefined` | `true` destroys the layer's objects (exclusive with `targetLayerId`) |
+ * | `targetLayerId` | `string \| undefined` | Move the layer's objects to this layer, then delete (exclusive with `deleteObjects`) |
+ */
+export const PluginCoreLayersDeleteArgs = z
+  .object({
+    layerId: z.string(),
+    deleteObjects: z.boolean().optional(),
+    targetLayerId: z.string().optional(),
+  })
+  .refine((v) => (v.deleteObjects === true) !== (v.targetLayerId != null), {
+    message:
+      "Provide exactly one disposition: deleteObjects: true (destroy the layer's objects) or targetLayerId (move them to that layer, then delete)",
+  })
+  .refine((v) => v.targetLayerId == null || v.targetLayerId !== v.layerId, {
+    message: "targetLayerId must be a different layer than layerId",
+  })
+export type PluginCoreLayersDeleteArgs = z.infer<
+  typeof PluginCoreLayersDeleteArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreLayersApi.delete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `deleted` | `true` | The layer was deleted |
+ */
+export const PluginCoreLayersDeleteResult = z.object({
+  deleted: z.literal(true),
+})
+export type PluginCoreLayersDeleteResult = z.infer<
+  typeof PluginCoreLayersDeleteResult
+>
+
+/**
+ * Arguments for {@linkcode PluginCoreLayersApi.assign}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `componentIds` | `string[]` | The objects to move (at least one) |
+ * | `layerId` | `string` | The target layer |
+ */
+export const PluginCoreLayersAssignArgs = z.object({
+  componentIds: z.array(ComponentHandle).min(1),
+  layerId: z.string(),
+})
+export type PluginCoreLayersAssignArgs = z.infer<
+  typeof PluginCoreLayersAssignArgs
+>
+
+/**
+ * Result of {@linkcode PluginCoreLayersApi.assign}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `assigned` | `string[]` | Ids of the objects that were moved |
+ * | `skipped` | `{ id: string; reason: "not-found" \| "locked" \| "outside-proposal" }[]` | Objects that were not moved, each with a reason |
+ */
+export const PluginCoreLayersAssignResult = z.object({
+  assigned: z.array(ComponentHandle),
+  skipped: z.array(
+    z.object({
+      id: ComponentHandle,
+      reason: z.enum(["not-found", "locked", "outside-proposal"]),
+    }),
+  ),
+})
+export type PluginCoreLayersAssignResult = z.infer<
+  typeof PluginCoreLayersAssignResult
+>