@snaptrude/plugin-core 0.9.14 → 0.9.16

package/src/api/core/layers.ts

@@ -1,24 +1,33 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../types"
+import { ComponentHandle } from "../../handles"
 
 /**
- * Layers — read and toggle the drawing/reference layers of a storey.
+ * 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).
  *
- * These are the **drawing/reference** layers shown in the storey's Layers panel —
- * the surfaces you sketch on and the imported underlays (CAD, PDF, images,
- * terrain). They are **not** wall/floor construction-assembly material layers,
- * which are a property of the built element, not this namespace.
+ * 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.
  *
- * Reads return plain records and never throw for a missing layer (`get` and
- * `getActive` return `null`, `list` returns `[]`).
+ * 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.
  *
- * v1 exposes reads plus visibility edits and the active-layer switch.
- * Creating and deleting layers are intentionally not part of this contract yet.
+ * 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`).
  *
- * 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).
+ * **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`.
  */
@@ -26,45 +35,42 @@ export abstract class PluginCoreLayersApi {
   constructor() {}
 
   /**
-   * List the drawing layers of a storey.
+   * List the layers in the Layers panel: the active design option's layers,
+   * default layer first, then in creation order.
    *
-   * Optionally filter to a single {@linkcode PluginCoreLayerType}.
+   * @returns A {@linkcode PluginCoreLayersListResult} with a `layers` array.
    *
-   * @param storeyId - The storey whose layers to read.
-   * @param layerType - Optional {@linkcode PluginCoreLayerType} filter.
-   * @returns A {@linkcode PluginCoreLayersListResult} with a `layers` array
-   *   (empty when the storey is missing or has no matching layers).
-   *
-   * @examplePrompt List the drawing layers on this storey
-   * @examplePrompt Show all the PDF underlays on storey st_2
-   * @examplePrompt What CAD layers are on the ground floor?
+   * @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("st_2")
-   * for (const l of layers) console.log(l.name, l.layerType, l.hidden)
+   * 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(
-    storeyId: string,
-    layerType?: PluginCoreLayerType,
-  ): PluginApiReturn<PluginCoreLayersListResult>
+  public abstract list(): PluginApiReturn<PluginCoreLayersListResult>
 
   /**
-   * Get a single drawing layer by id.
+   * 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 drawing layer with id ly_5
-   * @examplePrompt Is layer ly_5 hidden or locked?
-   * @examplePrompt Look up a single drawing layer by its 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("ly_5")
-   * if (layer) console.log(layer.name, layer.hidden, layer.locked)
+   * const layer = await snaptrude.core.layers.get(layerId)
+   * if (layer) console.log(layer.name, layer.objectCount)
    * ```
    */
   public abstract get(
@@ -72,160 +78,265 @@ export abstract class PluginCoreLayersApi {
   ): PluginApiReturn<PluginCoreLayersGetResult>
 
   /**
-   * Get the active drawing layer of a storey.
-   *
-   * The active layer is the one new sketch geometry is drawn onto. Paired with
-   * {@linkcode PluginCoreLayersApi.setActive}.
+   * Get the active Layers-panel layer: the one new objects land on.
    *
-   * @param storeyId - The storey whose active layer to read.
-   * @returns The active {@linkcode PluginCoreLayer}, or `null` if the storey is
-   *   missing or has no active layer.
+   * @returns The active {@linkcode PluginCoreLayer}, or `null` if none is set.
    *
-   * @examplePrompt Which drawing layer is active on this storey?
-   * @examplePrompt Get the current layer on storey st_2
-   * @examplePrompt What layer am I drawing on?
+   * @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("st_2")
+   * const active = await snaptrude.core.layers.getActive()
    * if (active) console.log(active.name)
    * ```
    */
-  public abstract getActive(
-    storeyId: string,
-  ): PluginApiReturn<PluginCoreLayersGetActiveResult>
+  public abstract getActive(): PluginApiReturn<PluginCoreLayersGetActiveResult>
 
   /**
-   * Make a drawing layer the active layer of its storey.
+   * Create a new layer in the Layers panel (the panel's "Add new layer" button
+   * followed by naming it).
    *
-   * Paired with {@linkcode PluginCoreLayersApi.getActive}.
+   * 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 layerId - The id of the layer to activate.
-   * @returns The id of the now-active layer.
-   * @throws If no layer has the given id.
+   * @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 Draw on layer ly_5
-   * @examplePrompt Make this the active layer
-   * @examplePrompt Switch the active layer to the CAD underlay
+   * @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
-   * await snaptrude.core.layers.setActive("ly_5")
+   * const layer = await snaptrude.core.layers.create("Furniture")
+   * await snaptrude.core.layers.setActive(layer.id)
    * ```
    */
-  public abstract setActive(
+  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,
-  ): PluginApiReturn<PluginCoreLayersSetActiveResult>
+    name: string,
+  ): PluginApiReturn<PluginCoreLayersRenameResult>
 
   /**
-   * Update a drawing layer's visibility.
+   * Lock/unlock or show/hide a layer (the panel row's padlock and eye).
    *
-   * A **sparse** update: omit `hidden` to leave it unchanged. This edit is **not
-   * undoable**. Locking and renaming are not exposed — layer `locked` is a
-   * read-only status here (setting it at runtime does not lock the live meshes or
-   * flip the panel padlock until a reload), and a rename cascades to every member
-   * mesh's `layerName`, a corruption hazard.
+   * 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 hidden - New hidden state (unchanged if omitted).
+   * @param options - `{ locked?, hidden? }`; omitted fields are unchanged.
    * @returns The updated {@linkcode PluginCoreLayer}.
-   * @throws If no layer has the given id.
+   * @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 Hide the PDF underlay layer
-   * @examplePrompt Show the CAD layer again
-   * @examplePrompt Hide layer ly_5
+   * @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
-   * const layer = await snaptrude.core.layers.update("ly_5", true)
+   * await snaptrude.core.layers.update(layerId, { locked: true, hidden: false })
    * ```
    */
   public abstract update(
     layerId: string,
-    hidden?: boolean,
+    options?: { locked?: boolean; hidden?: boolean },
   ): PluginApiReturn<PluginCoreLayersUpdateResult>
-}
 
-/**
- * The kind of a drawing layer.
- *
- * Author-drawable kinds (`floor`, `wall`, `ceiling`, `rough`, `default`) plus
- * read-only imported underlays (`image`, `cad`, `pdf`, `terrain`, `buildings`).
- */
-export const PluginCoreLayerType = z.enum([
-  "floor",
-  "wall",
-  "ceiling",
-  "rough",
-  "default",
-  "image",
-  "cad",
-  "pdf",
-  "terrain",
-  "buildings",
-])
-export type PluginCoreLayerType = z.infer<typeof PluginCoreLayerType>
+  /**
+   * 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 drawing/reference layer on a storey.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `id` | `string` | Stable public layer id (e.g. `"ly_5"`) |
- * | `name` | `string` | Display name |
- * | `layerType` | {@linkcode PluginCoreLayerType} | The layer's kind |
- * | `storeyId` | `string` | The stable id of the storey this layer belongs to |
- * | `buildingId` | `string` | The stable id of the building this layer belongs to |
- * | `hidden` | `boolean` | Whether the layer is hidden |
- * | `locked` | `boolean` | Whether the layer is locked against edits |
- * | `contentSummary` | `object` | A summary of what the layer holds (see below) |
- *
- * `contentSummary`:
+ * A layer in the Layers panel.
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `hasFloorplan` | `boolean` | Whether the layer holds drawn floorplan geometry |
- * | `pdfCount` | `number` | Number of PDF underlays on the layer |
- * | `hasTerrain` | `boolean` | Whether the layer holds terrain |
+ * | `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(),
-  layerType: PluginCoreLayerType,
-  storeyId: z.string(),
-  buildingId: z.string(),
-  hidden: z.boolean(),
+  isDefault: z.boolean(),
+  isActive: z.boolean(),
   locked: z.boolean(),
-  contentSummary: z.object({
-    hasFloorplan: z.boolean(),
-    pdfCount: z.number().int(),
-    hasTerrain: z.boolean(),
-  }),
+  hidden: z.boolean(),
+  proposalIds: z.array(z.string()),
+  objectCount: z.number().int(),
 })
 export type PluginCoreLayer = z.infer<typeof PluginCoreLayer>
 
-/**
- * Arguments for {@linkcode PluginCoreLayersApi.list}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `storeyId` | `string` | The storey whose layers to read |
- * | `layerType` | {@linkcode PluginCoreLayerType}` \| undefined` | Optional layer-type filter |
- */
-export const PluginCoreLayersListArgs = z.object({
-  storeyId: z.string(),
-  layerType: PluginCoreLayerType.optional(),
-})
-export type PluginCoreLayersListArgs = z.infer<
-  typeof PluginCoreLayersListArgs
->
+/** 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 storey's drawing layers (empty when missing or none match) |
+ * | `layers` | {@linkcode PluginCoreLayer}`[]` | The active design option's layers, default first |
  */
 export const PluginCoreLayersListResult = z.object({
   layers: z.array(PluginCoreLayer),
@@ -241,43 +352,86 @@ export type PluginCoreLayersListResult = z.infer<
  * |---|---|---|
  * | `layerId` | `string` | The id of the layer to read |
  */
-export const PluginCoreLayersGetArgs = z.object({
-  layerId: z.string(),
-})
-export type PluginCoreLayersGetArgs = z.infer<
-  typeof PluginCoreLayersGetArgs
->
+export const PluginCoreLayersGetArgs = z.object({ layerId: z.string() })
+export type PluginCoreLayersGetArgs = z.infer<typeof PluginCoreLayersGetArgs>
 
-/**
- * Result of {@linkcode PluginCoreLayersApi.get} — the layer, or `null`
- * when no layer has the given id.
- */
+/** 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.getActive}.
+ * Arguments for {@linkcode PluginCoreLayersApi.create}.
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `storeyId` | `string` | The storey whose active layer to read |
+ * | `name` | `string` | The new layer's name (trimmed, 1-40 characters) |
  */
-export const PluginCoreLayersGetActiveArgs = z.object({
-  storeyId: z.string(),
+export const PluginCoreLayersCreateArgs = z.object({
+  name: PluginCoreLayerName,
 })
-export type PluginCoreLayersGetActiveArgs = z.infer<
-  typeof PluginCoreLayersGetActiveArgs
+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
 >
 
 /**
- * Result of {@linkcode PluginCoreLayersApi.getActive} — the active layer,
- * or `null` when the storey is missing or has no active layer.
+ * 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 PluginCoreLayersGetActiveResult = PluginCoreLayer.nullable()
-export type PluginCoreLayersGetActiveResult = z.infer<
-  typeof PluginCoreLayersGetActiveResult
+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
 >
 
 /**
@@ -287,16 +441,13 @@ export type PluginCoreLayersGetActiveResult = z.infer<
  * |---|---|---|
  * | `layerId` | `string` | The id of the layer to activate |
  */
-export const PluginCoreLayersSetActiveArgs = z.object({
-  layerId: z.string(),
-})
+export const PluginCoreLayersSetActiveArgs = z.object({ layerId: z.string() })
 export type PluginCoreLayersSetActiveArgs = z.infer<
   typeof PluginCoreLayersSetActiveArgs
 >
 
 /**
- * Result of {@linkcode PluginCoreLayersApi.setActive} — the now-active
- * layer's id.
+ * Result of {@linkcode PluginCoreLayersApi.setActive}.
  *
  * | Property | Type | Description |
  * |---|---|---|
@@ -310,24 +461,80 @@ export type PluginCoreLayersSetActiveResult = z.infer<
 >
 
 /**
- * Arguments for {@linkcode PluginCoreLayersApi.update}. Sparse — only the
- * provided fields are changed.
+ * 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 update |
- * | `hidden` | `boolean \| undefined` | New hidden state (unchanged if omitted) |
+ * | `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 PluginCoreLayersUpdateArgs = z.object({
+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(),
-  hidden: z.boolean().optional(),
 })
-export type PluginCoreLayersUpdateArgs = z.infer<
-  typeof PluginCoreLayersUpdateArgs
+export type PluginCoreLayersAssignArgs = z.infer<
+  typeof PluginCoreLayersAssignArgs
 >
 
-/** Result of {@linkcode PluginCoreLayersApi.update} — the updated layer. */
-export const PluginCoreLayersUpdateResult = PluginCoreLayer
-export type PluginCoreLayersUpdateResult = z.infer<
-  typeof PluginCoreLayersUpdateResult
+/**
+ * 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
 >