@snaptrude/plugin-core 0.6.0 → 0.7.0

package/src/api/design/create/index.ts

@@ -24,6 +24,13 @@ import {
  * Footprint objects take a {@linkcode ContourHandle} (outer profile + holes);
  * build one with `snaptrude.core.geom.create.contourFromProfile(s)`.
  *
+ * `door`/`window` place a catalog item into a host wall (the world point is
+ * projected onto the wall face to locate the opening; the wall is re-cut in one
+ * undo entry) and throw if the point projects outside the wall. `smartLayout` is
+ * the one creator returning a grouped {@linkcode PluginSmartLayoutResult} rather
+ * than a handle — it clones an in-scene template into one or more target spaces,
+ * merging every target into a single undo batch (see its JSDoc).
+ *
  * Accessed via `snaptrude.design.create`.
  */
 export abstract class PluginDesignCreateApi {
@@ -433,6 +440,142 @@ export abstract class PluginDesignCreateApi {
     options?: { label?: string; createNewSourceMesh?: boolean },
   ): PluginApiReturn<ComponentHandle>
 
+  /**
+   * Place a **door** from the catalog into a host wall.
+   *
+   * Identified by a **catalog (library) id** — the team object's stable `_id`
+   * or the general library's `fullName`. Discover ids with
+   * {@linkcode PluginDesignDoorsApi.listCatalog}. The world `position` is
+   * projected onto the host wall's face to locate the opening; the wall is
+   * re-cut and the door hosted in a single undo entry. Placement is
+   * asynchronous (the source mesh is fetched if not cached).
+   *
+   * @param catalogId - Library id: team `_id` or general `fullName`
+   * @param hostWall - The wall to host the door
+   * @param position - World point projected onto the wall to locate the opening
+   * @param options - Optional placement options: `label` — instance name
+   * @returns the {@linkcode ComponentHandle} of the placed door
+   * @throws if the catalog id is unknown, the host is not a wall, the source
+   *   mesh fails to load, or the projected point falls **outside** the host wall
+   *
+   * @examplePrompt Add a door to this wall here
+   * @examplePrompt Place a sliding door on the selected wall
+   * @examplePrompt Put a door from the catalog at this point on the wall
+   * @examplePrompt Insert the entrance door into this wall
+   * @examplePrompt Add a door to the wall and call it Entry-01
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls({ isSelected: true })
+   * const [entry] = await snaptrude.design.doors.listCatalog()
+   * const door = await snaptrude.design.create.door(
+   *   entry.id,
+   *   wall,
+   *   await snaptrude.core.math.vec3.new(3, 0, 5),
+   *   { label: "Entry-01" },
+   * )
+   * ```
+   */
+  public abstract door(
+    catalogId: string,
+    hostWall: ComponentHandle,
+    position: Vec3Handle,
+    options?: { label?: string },
+  ): PluginApiReturn<ComponentHandle>
+
+  /**
+   * Place a **window** from the catalog into a host wall.
+   *
+   * Identified by a **catalog (library) id** — the team object's stable `_id`
+   * or the general library's `fullName`. Discover ids with
+   * {@linkcode PluginDesignWindowsApi.listCatalog}. The world `position` is
+   * projected onto the host wall's face to locate the opening; the wall is
+   * re-cut and the window hosted in a single undo entry. Placement is
+   * asynchronous (the source mesh is fetched if not cached).
+   *
+   * @param catalogId - Library id: team `_id` or general `fullName`
+   * @param hostWall - The wall to host the window
+   * @param position - World point projected onto the wall to locate the opening
+   * @param options - Optional placement options: `label` — instance name
+   * @returns the {@linkcode ComponentHandle} of the placed window
+   * @throws if the catalog id is unknown, the host is not a wall, the source
+   *   mesh fails to load, or the projected point falls **outside** the host wall
+   *
+   * @examplePrompt Add a window to this wall here
+   * @examplePrompt Place a casement window on the selected wall
+   * @examplePrompt Put a window from the catalog at this point on the wall
+   * @examplePrompt Insert a window into the living room wall
+   * @examplePrompt Add a window to the wall and name it Win-01
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls({ isSelected: true })
+   * const [entry] = await snaptrude.design.windows.listCatalog()
+   * const window = await snaptrude.design.create.window(
+   *   entry.id,
+   *   wall,
+   *   await snaptrude.core.math.vec3.new(3, 0, 5),
+   *   { label: "Win-01" },
+   * )
+   * ```
+   */
+  public abstract window(
+    catalogId: string,
+    hostWall: ComponentHandle,
+    position: Vec3Handle,
+    options?: { label?: string },
+  ): PluginApiReturn<ComponentHandle>
+
+  /**
+   * Place a **smart layout** — clone an in-scene template cluster (walls,
+   * furniture, doors, windows, floors) into one or more target ROOM/DEPARTMENT
+   * spaces, adapting orientation and fit to each target.
+   *
+   * Supply the template as **exactly one** of `templateGroup` (a group **id**
+   * from `snaptrude.core.groups.list` — groups are string-id entities, not
+   * component handles) or
+   * `templateComponents` (an explicit component set); every target in `targets`
+   * (≥1) receives its own placement. By default the target spaces are hidden
+   * after placement (`hideTargets`, mirroring the product) — pass `false` to keep
+   * them visible.
+   *
+   * The whole operation — every wall/opening/furniture/floor across every target,
+   * plus the target-hide — is committed as a **single undo step**. Because all
+   * targets merge into one creation batch, the created entities are returned
+   * **flat, grouped by kind** ({@linkcode PluginSmartLayoutResult}), NOT attributed
+   * per target (per-target attribution would break the single-undo guarantee).
+   * `skippedWalls` is the interior-optimizer's best-candidate count of walls it
+   * could not place. Synchronous and heavy — many targets can jank the main thread.
+   *
+   * @param options - {@linkcode PluginSmartLayoutArgs}: template source, targets, and `hideTargets`
+   * @returns a {@linkcode PluginSmartLayoutResult} — created entities grouped by kind + `skippedWalls`
+   * @throws if smart layout is not enabled, the template group is invalid, there
+   *   is no template / no targets / no valid mappings, or component creation fails
+   *
+   * @examplePrompt Copy this room's layout into the selected rooms
+   * @examplePrompt Apply this furniture arrangement to the other offices
+   * @examplePrompt Replicate this template into these two spaces
+   * @examplePrompt Place this desk cluster into every meeting room
+   * @examplePrompt Use this room as a template for the rooms I selected but keep them visible
+   *
+   * # Example
+   * ```ts
+   * const [templateRoom, ...targets] = await snaptrude.design.query.listSpaces({ isSelected: true })
+   * const result = await snaptrude.design.create.smartLayout({
+   *   templateComponents: [templateRoom],
+   *   targets,
+   * })
+   * console.log("placed walls:", result.created.walls.length, "skipped:", result.skippedWalls)
+   *
+   * // …or clone a saved group by its id (from core.groups.list)
+   * const { groups } = await snaptrude.core.groups.list()
+   * await snaptrude.design.create.smartLayout({ templateGroup: groups[0].id, targets })
+   * ```
+   */
+  public abstract smartLayout(
+    options: PluginSmartLayoutArgs,
+  ): PluginApiReturn<PluginSmartLayoutResult>
+
   /**
    * **Copy** existing entities, offsetting each copy by `displacement * i` (i = 1…count),
    * source positions preserved. Migrated from the removed `tools.copy`. In `"instance"`
@@ -804,6 +947,112 @@ export type PluginDesignCreateFurnitureArgs = z.infer<
 // TRANSPORT: positional signature shipped —
 //   furniture(catalogId: string, position: Vec3Handle, options?: { label?, createNewSourceMesh? })
 
+// ---------------------------------------------------------------------------
+// door
+// ---------------------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginDesignCreateApi.door}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `catalogId` | `string` | Library id: team `_id` or general `fullName` |
+ * | `hostWall` | {@linkcode ComponentHandle} | The wall to host the door |
+ * | `position` | {@linkcode Vec3Handle} | World point projected onto the wall |
+ * | `label` | `string`? | Instance name (optional) |
+ */
+export const PluginDesignCreateDoorArgs = z.object({
+  catalogId: z.string().min(1),
+  hostWall: ComponentHandle,
+  position: Vec3Handle,
+  label: z.string().optional(),
+})
+export type PluginDesignCreateDoorArgs = z.infer<typeof PluginDesignCreateDoorArgs>
+// TRANSPORT: positional signature shipped —
+//   door(catalogId: string, hostWall: ComponentHandle, position: Vec3Handle, options?: { label? })
+
+// ---------------------------------------------------------------------------
+// window
+// ---------------------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginDesignCreateApi.window}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `catalogId` | `string` | Library id: team `_id` or general `fullName` |
+ * | `hostWall` | {@linkcode ComponentHandle} | The wall to host the window |
+ * | `position` | {@linkcode Vec3Handle} | World point projected onto the wall |
+ * | `label` | `string`? | Instance name (optional) |
+ */
+export const PluginDesignCreateWindowArgs = z.object({
+  catalogId: z.string().min(1),
+  hostWall: ComponentHandle,
+  position: Vec3Handle,
+  label: z.string().optional(),
+})
+export type PluginDesignCreateWindowArgs = z.infer<typeof PluginDesignCreateWindowArgs>
+// TRANSPORT: positional signature shipped —
+//   window(catalogId: string, hostWall: ComponentHandle, position: Vec3Handle, options?: { label? })
+
+// ---------------------------------------------------------------------------
+// smartLayout
+// ---------------------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginDesignCreateApi.smartLayout}. Provide **exactly
+ * one** template source: `templateGroup` or a non-empty `templateComponents`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `templateGroup` | `string`? | Id of the group to clone as the template (a group id from `snaptrude.core.groups.list`, NOT a component handle) |
+ * | `templateComponents` | {@linkcode ComponentHandle}`[]`? | Explicit component set to clone as the template |
+ * | `targets` | {@linkcode ComponentHandle}`[]` | ROOM/DEPARTMENT spaces to place into (≥1) |
+ * | `hideTargets` | `boolean`? | Hide the target spaces after placement (default `true`) |
+ */
+export const PluginSmartLayoutArgs = z
+  .object({
+    templateGroup: z.string().min(1).optional(),
+    templateComponents: z.array(ComponentHandle).optional(),
+    targets: z.array(ComponentHandle).min(1),
+    hideTargets: z.boolean().optional(),
+  })
+  .refine(
+    (v) =>
+      (v.templateGroup != null) !== ((v.templateComponents?.length ?? 0) > 0),
+    {
+      message:
+        "Provide exactly one template source: templateGroup or a non-empty templateComponents",
+    },
+  )
+export type PluginSmartLayoutArgs = z.infer<typeof PluginSmartLayoutArgs>
+
+/**
+ * Result of {@linkcode PluginDesignCreateApi.smartLayout} — the entities the run
+ * created, grouped by kind (flat across all targets; see the method JSDoc for why
+ * this is not attributed per target).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `created.walls` | {@linkcode ComponentHandle}`[]` | Created walls |
+ * | `created.furniture` | {@linkcode ComponentHandle}`[]` | Created furniture |
+ * | `created.doors` | {@linkcode ComponentHandle}`[]` | Created doors |
+ * | `created.windows` | {@linkcode ComponentHandle}`[]` | Created windows |
+ * | `created.floors` | {@linkcode ComponentHandle}`[]` | Created floors |
+ * | `skippedWalls` | `number` | Walls the interior optimizer could not place |
+ */
+export const PluginSmartLayoutResult = z.object({
+  created: z.object({
+    walls: z.array(ComponentHandle),
+    furniture: z.array(ComponentHandle),
+    doors: z.array(ComponentHandle),
+    windows: z.array(ComponentHandle),
+    floors: z.array(ComponentHandle),
+  }),
+  skippedWalls: z.number(),
+})
+export type PluginSmartLayoutResult = z.infer<typeof PluginSmartLayoutResult>
+
 // ---------------------------------------------------------------------------
 // referenceLines
 // ---------------------------------------------------------------------------

package/src/api/design/doors/index.ts

@@ -12,6 +12,13 @@ import { PluginDesignChangeResult } from "../lock"
  * mesh reflection state. `mirror` reflects the door across an axis (undoable, one
  * command); `setType` is intentionally absent (the engine has no in-place re-type —
  * it would require delete+recreate).
+ *
+ * The **catalog** reads (`listCatalogGroups`/`listCatalog`/`getCatalogItem`/`exists`)
+ * browse the placeable door library — plain value records keyed by a library id
+ * (team `_id` or general `fullName`), NOT handles — and feed `design.create.door`.
+ * They are network-backed but carry no `Async` suffix (§6.6) and never throw
+ * (`[]`/`null`). The {@linkcode PluginObjectCatalogGroup} / {@linkcode PluginObjectCatalogItem}
+ * DTOs are shared with `design.windows`.
  */
 export abstract class PluginDesignDoorsApi {
   constructor() {}
@@ -224,6 +231,90 @@ export abstract class PluginDesignDoorsApi {
     doors: ComponentHandle[],
     height: number
   ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * List the door catalog **groups** — the placement families (Swing, Sliding,
+   * Folding, Pivot, …), built-in groups merged with any team-custom types.
+   *
+   * @returns The groups as {@linkcode PluginObjectCatalogGroup}`[]` (`[]` when empty)
+   *
+   * @examplePrompt What kinds of doors can I place?
+   * @examplePrompt List the door groups in the catalog
+   * @examplePrompt Show me the door families available in this project
+   * @examplePrompt Which door types does this project support?
+   *
+   * # Example
+   * ```ts
+   * const groups = await snaptrude.design.doors.listCatalogGroups()
+   * for (const g of groups) console.log(g.dbType, g.label, g.source)
+   * ```
+   */
+  public abstract listCatalogGroups(): PluginApiReturn<PluginObjectCatalogGroup[]>
+
+  /**
+   * List the placeable door catalog (team + general libraries), optionally
+   * restricted to one group by its `dbType` token.
+   *
+   * @param group Restrict to one group's `dbType` (optional; e.g. `"singleDoor"`)
+   * @returns The catalog as {@linkcode PluginObjectCatalogItem}`[]` (`[]` when empty)
+   *
+   * @examplePrompt What doors can I place in this project?
+   * @examplePrompt List every door in the library
+   * @examplePrompt Show me the sliding doors I can add
+   * @examplePrompt Browse the door catalog
+   *
+   * # Example
+   * ```ts
+   * const [group] = await snaptrude.design.doors.listCatalogGroups()
+   * const items = await snaptrude.design.doors.listCatalog(group?.dbType)
+   * for (const item of items) console.log(item.id, item.name, item.thumbnailUrl)
+   * ```
+   */
+  public abstract listCatalog(
+    group?: string
+  ): PluginApiReturn<PluginObjectCatalogItem[]>
+
+  /**
+   * Get a single door catalog item by its library id.
+   *
+   * @param id The catalog library id
+   * @returns The item, or `null` if no catalog item matches
+   *
+   * @examplePrompt Get the details of this door from the library
+   * @examplePrompt Look up the catalog entry for this door id
+   * @examplePrompt What is the cost of this door item?
+   * @examplePrompt Show me the family name of this door in the catalog
+   *
+   * # Example
+   * ```ts
+   * const [entry] = await snaptrude.design.doors.listCatalog()
+   * const item = await snaptrude.design.doors.getCatalogItem(entry.id)
+   * if (item) console.log(item.name, item.source, item.dbType)
+   * ```
+   */
+  public abstract getCatalogItem(
+    id: string
+  ): PluginApiReturn<PluginObjectCatalogItem | null>
+
+  /**
+   * Test whether a door catalog item exists for the given library id.
+   *
+   * @param id The catalog library id
+   * @returns `true` if it exists, otherwise `false`
+   *
+   * @examplePrompt Is this door still in the library?
+   * @examplePrompt Check whether a door catalog item with this id exists
+   * @examplePrompt Does my team library have this door?
+   * @examplePrompt Verify the door is available before placing it
+   *
+   * # Example
+   * ```ts
+   * const [entry] = await snaptrude.design.doors.listCatalog()
+   * const stillAvailable = await snaptrude.design.doors.exists(entry.id)
+   * console.log(stillAvailable ? "safe to place" : "removed from library")
+   * ```
+   */
+  public abstract exists(id: string): PluginApiReturn<boolean>
 }
 
 /**
@@ -283,3 +374,80 @@ export const PluginDesignDoorSetHeightArgs = z.object({
   height: z.number(),
 })
 export type PluginDesignDoorSetHeightArgs = z.infer<typeof PluginDesignDoorSetHeightArgs>
+
+// ---------------------------------------------------------------------------
+// catalog (shared by doors + windows)
+// ---------------------------------------------------------------------------
+
+/**
+ * A door/window catalog **group** — a placement family (e.g. Swing, Sliding,
+ * Casement). Shared by `design.doors` and `design.windows`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `dbType` | `string` | Stable engine token (e.g. `singleDoor`, `casementDouble`) |
+ * | `label` | `string` | Human-readable group label (e.g. `"Swing - 1 Shutter"`) |
+ * | `source` | `'default' \| 'team'` | Built-in group or a team-custom type |
+ */
+export const PluginObjectCatalogGroup = z.object({
+  dbType: z.string(),
+  label: z.string(),
+  source: z.enum(["default", "team"]),
+})
+export type PluginObjectCatalogGroup = z.infer<typeof PluginObjectCatalogGroup>
+
+/**
+ * A placeable door/window catalog **item** (value record — not a scene
+ * entity/handle). Shared by `design.doors` and `design.windows`; symmetric with
+ * {@linkcode PluginFurnitureCatalogItem}. The raw mesh (`.babylon`) URL is never
+ * exposed — only `thumbnailUrl`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Library id (team `_id` or general `fullName`) — pass to `design.create.door`/`window` |
+ * | `name` | `string` | Display name |
+ * | `source` | `'team' \| 'general'` | Which library it came from |
+ * | `dbType` | `string` | The group token it belongs to (e.g. `singleDoor`) |
+ * | `subType` | `string`? | Engine sub-type (optional) |
+ * | `thumbnailUrl` | `string`? | Preview thumbnail URL (optional) |
+ * | `cost` | `number`? | Cost (optional; team items) |
+ * | `familyName` | `string`? | Family name (optional) |
+ */
+export const PluginObjectCatalogItem = z.object({
+  id: z.string(),
+  name: z.string(),
+  source: z.enum(["team", "general"]),
+  dbType: z.string(),
+  subType: z.string().optional(),
+  thumbnailUrl: z.string().optional(),
+  cost: z.number().optional(),
+  familyName: z.string().optional(),
+})
+export type PluginObjectCatalogItem = z.infer<typeof PluginObjectCatalogItem>
+
+/**
+ * Arguments for {@linkcode PluginDesignDoorsApi.listCatalog}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `group` | `string`? | Restrict to one group's `dbType` token (optional) |
+ */
+export const PluginDesignDoorListCatalogArgs = z.object({
+  group: z.string().optional(),
+})
+export type PluginDesignDoorListCatalogArgs = z.infer<typeof PluginDesignDoorListCatalogArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignDoorsApi.getCatalogItem} / {@linkcode PluginDesignDoorsApi.exists}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The catalog library id |
+ */
+export const PluginDesignDoorGetCatalogItemArgs = z.object({
+  id: z.string(),
+})
+export type PluginDesignDoorGetCatalogItemArgs = z.infer<typeof PluginDesignDoorGetCatalogItemArgs>
+
+export const PluginDesignDoorExistsArgs = PluginDesignDoorGetCatalogItemArgs
+export type PluginDesignDoorExistsArgs = z.infer<typeof PluginDesignDoorExistsArgs>

package/src/api/design/furniture/index.ts

@@ -15,24 +15,49 @@ export abstract class PluginDesignFurnitureApi {
   constructor() {}
 
   /**
-   * List the placeable furniture catalog (team + general libraries).
+   * List the categories (Living, Bedroom, Kitchen, …) that organize the
+   * furniture catalog — the picker taxonomy, merged from built-in categories,
+   * team types, and backend user types. Pass a value to
+   * {@linkcode PluginDesignFurnitureApi.listCatalog}'s `category` filter.
+   * @returns The category names (`[]` when empty)
+   *
+   * @examplePrompt What furniture categories are available?
+   * @examplePrompt List the furniture categories
+   * @examplePrompt Show me the furniture groups like living and bedroom
+   * @examplePrompt Which furniture categories can I filter by?
+   *
+   * # Example
+   * ```ts
+   * const categories = await snaptrude.design.furniture.listCategories()
+   * const [first] = categories
+   * const items = await snaptrude.design.furniture.listCatalog(undefined, first)
+   * console.log(first, "→", items.length, "items")
+   * ```
+   */
+  public abstract listCategories(): PluginApiReturn<string[]>
+
+  /**
+   * List the placeable furniture catalog (team + general libraries),
+   * optionally filtered by library `source` and/or `category`.
    * @param source Restrict to one library (optional)
+   * @param category Restrict to one category (optional; see {@linkcode PluginDesignFurnitureApi.listCategories})
    * @returns The catalog as {@linkcode PluginFurnitureCatalogItem}`[]` (`[]` when empty)
    *
    * @examplePrompt What furniture can I place in this project?
    * @examplePrompt Show me all the furniture available in the library
    * @examplePrompt List the chairs and tables I can add to the model
    * @examplePrompt Which furniture items are in my team's library?
-   * @examplePrompt Browse the furniture catalog
+   * @examplePrompt Show me the bedroom furniture I can place
    *
    * # Example
    * ```ts
-   * const teamItems = await snaptrude.design.furniture.listCatalog("team")
-   * for (const item of teamItems) console.log(item.id, item.name, item.cost)
+   * const bedroom = await snaptrude.design.furniture.listCatalog("team", "bedroom")
+   * for (const item of bedroom) console.log(item.id, item.name, item.thumbnailUrl)
    * ```
    */
   public abstract listCatalog(
-    source?: "team" | "general"
+    source?: "team" | "general",
+    category?: string
   ): PluginApiReturn<PluginFurnitureCatalogItem[]>
 
   /**
@@ -85,6 +110,8 @@ export abstract class PluginDesignFurnitureApi {
  * | `name` | `string` | Display name |
  * | `source` | `'team' \| 'general'` | Which library it came from |
  * | `subType` | `string` | Sub-type (optional) |
+ * | `category` | `string` | Category the item belongs to (optional) |
+ * | `thumbnailUrl` | `string` | Preview thumbnail URL (optional; never the mesh URL) |
  * | `cost` | `number` | Cost (optional; team items) |
  * | `familyName` | `string` | Family name (optional) |
  */
@@ -93,6 +120,8 @@ export const PluginFurnitureCatalogItem = z.object({
   name: z.string(),
   source: z.enum(["team", "general"]),
   subType: z.string().optional(),
+  category: z.string().optional(),
+  thumbnailUrl: z.string().optional(),
   cost: z.number().optional(),
   familyName: z.string().optional(),
 })
@@ -104,9 +133,11 @@ export type PluginFurnitureCatalogItem = z.infer<typeof PluginFurnitureCatalogIt
  * | Property | Type | Description |
  * |---|---|---|
  * | `source` | `'team' \| 'general'` | Restrict to one library (optional) |
+ * | `category` | `string` | Restrict to one category (optional) |
  */
 export const PluginDesignFurnitureListCatalogArgs = z.object({
   source: z.enum(["team", "general"]).optional(),
+  category: z.string().optional(),
 })
 export type PluginDesignFurnitureListCatalogArgs = z.infer<
   typeof PluginDesignFurnitureListCatalogArgs

package/src/api/design/index.ts

@@ -28,6 +28,7 @@ import { PluginDesignChangeResult } from "./lock"
  * - {@linkcode PluginDesignApi.erase} — plan-level adjacency-edge erase (NOT hard delete)
  * - {@linkcode PluginDesignApi.delete} — hard entity removal
  * - {@linkcode PluginDesignApi.lock} / {@linkcode PluginDesignApi.unlock} / {@linkcode PluginDesignApi.isLocked} / {@linkcode PluginDesignApi.listLocked} — lock state (top-level design verbs, §2A.1)
+ * - {@linkcode PluginDesignApi.lockArea} / {@linkcode PluginDesignApi.unlockArea} / {@linkcode PluginDesignApi.isAreaLocked} / {@linkcode PluginDesignApi.listAreaLocked} — footprint-area lock for Room/Department spaces
  *
  * Transform and edit operation namespaces land here in later waves.
  */
@@ -142,6 +143,92 @@ export abstract class PluginDesignApi {
    */
   public abstract listLocked(): PluginApiReturn<ComponentHandle[]>
 
+  /**
+   * Lock the **footprint area** of one or more Room / Department mass spaces —
+   * geometry edits that would change the bottom-face area are then refused or
+   * auto-resized to preserve it. Distinct from {@linkcode PluginDesignApi.lock}
+   * (which freezes the whole object): this locks only the area. Cascades to the
+   * space's instances and its source mass. Undoable.
+   *
+   * Only Room / Department masses are area-lockable; any other handle throws.
+   * Requires the `area_lock` feature to be enabled — when it is off this throws.
+   *
+   * @param spaces Room / Department mass spaces to area-lock
+   * @returns The affected spaces (post-cascade, echoing the input handles)
+   *
+   * @examplePrompt Lock the floor area of the selected rooms
+   * @examplePrompt Freeze the footprint area of this department so its size can't drift
+   * @examplePrompt Area-lock every room on this storey
+   * @examplePrompt Pin the area of this space while I edit its walls
+   *
+   * # Example
+   * ```ts
+   * const rooms = await snaptrude.design.selection.get()
+   * const { affected } = await snaptrude.design.lockArea(rooms)
+   * console.log("area-locked", affected.length, "spaces")
+   * ```
+   */
+  public abstract lockArea(spaces: ComponentHandle[]): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Unlock the footprint area of previously area-locked spaces so their area can
+   * change again. Paired with {@linkcode PluginDesignApi.lockArea}; cascades to
+   * instances + source; undoable. Requires the `area_lock` feature (throws if off).
+   *
+   * @param spaces Room / Department mass spaces to area-unlock
+   * @returns The affected spaces (post-cascade)
+   *
+   * @examplePrompt Unlock the area of the selected rooms
+   * @examplePrompt Remove the footprint-area lock from this department
+   * @examplePrompt Let me resize this space again by unlocking its area
+   * @examplePrompt Area-unlock everything I locked earlier
+   *
+   * # Example
+   * ```ts
+   * const locked = await snaptrude.design.listAreaLocked()
+   * const { affected } = await snaptrude.design.unlockArea(locked)
+   * ```
+   */
+  public abstract unlockArea(spaces: ComponentHandle[]): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Test whether a space's footprint area is locked. A read — never throws;
+   * returns `false` for non-space handles and when the `area_lock` feature is off.
+   *
+   * @param space The space to test
+   * @returns `true` if the space's area is locked, otherwise `false`
+   *
+   * @examplePrompt Is the area of this room locked?
+   * @examplePrompt Check whether this department's footprint is pinned
+   * @examplePrompt Tell me if the selected space has its area locked
+   *
+   * # Example
+   * ```ts
+   * const [room] = await snaptrude.design.selection.get()
+   * const locked = await snaptrude.design.isAreaLocked(room)
+   * console.log(locked ? "area is locked" : "area is free")
+   * ```
+   */
+  public abstract isAreaLocked(space: ComponentHandle): PluginApiReturn<boolean>
+
+  /**
+   * List the spaces whose footprint area is locked. A read — never throws; returns
+   * `[]` when the `area_lock` feature is off.
+   *
+   * @returns The area-locked spaces as {@linkcode ComponentHandle}`[]`
+   *
+   * @examplePrompt Which spaces have their area locked?
+   * @examplePrompt List every room with a locked footprint
+   * @examplePrompt Show me all the area-locked departments
+   *
+   * # Example
+   * ```ts
+   * const locked = await snaptrude.design.listAreaLocked()
+   * console.log(locked.length, "area-locked spaces")
+   * ```
+   */
+  public abstract listAreaLocked(): PluginApiReturn<ComponentHandle[]>
+
   constructor() {}
 }
 

package/src/api/design/lock.ts

@@ -40,3 +40,30 @@ export const PluginDesignIsLockedArgs = z.object({
   includeInherited: z.boolean().optional(),
 })
 export type PluginDesignIsLockedArgs = z.infer<typeof PluginDesignIsLockedArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignApi.lockArea} / {@linkcode PluginDesignApi.unlockArea}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `spaces` | {@linkcode ComponentHandle}`[]` | Room / Department mass spaces to area-lock / unlock |
+ */
+export const PluginDesignLockAreaArgs = z.object({
+  spaces: z.array(ComponentHandle),
+})
+export type PluginDesignLockAreaArgs = z.infer<typeof PluginDesignLockAreaArgs>
+
+export const PluginDesignUnlockAreaArgs = PluginDesignLockAreaArgs
+export type PluginDesignUnlockAreaArgs = z.infer<typeof PluginDesignUnlockAreaArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignApi.isAreaLocked}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `space` | {@linkcode ComponentHandle} | The space to test |
+ */
+export const PluginDesignIsAreaLockedArgs = z.object({
+  space: ComponentHandle,
+})
+export type PluginDesignIsAreaLockedArgs = z.infer<typeof PluginDesignIsAreaLockedArgs>