@snaptrude/plugin-core 0.0.0-dev-20260708130115 → 0.0.0-dev-20260827194031

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

@@ -1,38 +1,156 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../../types"
+import { ComponentHandle } from "../../../handles"
+import { PluginDesignChangeResult } from "../lock"
+import { PluginObjectCatalogGroup } from "../doors"
 
 /**
  * `snaptrude.design.furniture` — the placeable furniture **catalog** (a library of
- * source items, NOT scene entities). Placement lives at `design.create.furniture`
- * (returns a {@linkcode ComponentHandle}); reads of placed furniture live at
- * `design.query.listFurniture`/`getProperties`.
+ * source items, NOT scene entities) plus dimension reads/edits of PLACED furniture.
+ * Placement lives at `design.create.furniture` (returns a {@linkcode ComponentHandle});
+ * generic reads of placed furniture live at `design.query.listFurniture`/`getProperties`.
  *
  * Catalog items are plain value records ({@linkcode PluginFurnitureCatalogItem}) keyed
  * by a library id (team `_id` or general `fullName`) — not handles. Reads are async
  * (network-backed) but carry no `Async` suffix (§6.6).
+ *
+ * {@linkcode PluginDesignFurnitureApi.getDimensions} / {@linkcode PluginDesignFurnitureApi.setDimensions}
+ * target a PLACED furniture {@linkcode ComponentHandle} (not a catalog id) — `length`
+ * along the object, `width` across it, `height` up. Values are engine units, matching
+ * the length/width/height fields the furniture properties panel shows.
  */
 export abstract class PluginDesignFurnitureApi {
   constructor() {}
 
   /**
-   * List the placeable furniture catalog (team + general libraries).
+   * Get the dimensions of a PLACED furniture item — `length` (along the object),
+   * `width` (across it) and `height` (vertical), in engine units. Mirrors the
+   * Length/Width/Height fields of the furniture properties panel.
+   *
+   * @param item The placed furniture to query
+   * @returns The dimensions, or `null` if the geometry is degenerate
+   *
+   * @examplePrompt How big is this sofa?
+   * @examplePrompt What are the dimensions of the selected furniture?
+   * @examplePrompt Measure the length, width and height of this table
+   * @examplePrompt Get the size of the chair I just placed
+   *
+   * # Example
+   * ```ts
+   * const [item] = await snaptrude.design.query.listFurniture({ isSelected: true })
+   * const dims = await snaptrude.design.furniture.getDimensions(item)
+   * if (dims) console.log(dims.length, dims.width, dims.height)
+   * ```
+   */
+  public abstract getDimensions(
+    item: ComponentHandle
+  ): PluginApiReturn<PluginFurnitureDimensions | null>
+
+  /**
+   * Resize a PLACED furniture item along one or more axes — `length`, `width`
+   * and/or `height` (engine units). Omitted axes are left unchanged. Each supplied
+   * axis is an undoable command, mirroring editing the furniture properties panel.
+   *
+   * @param item The placed furniture to resize
+   * @param dimensions New `length` / `width` / `height` (each optional, engine units)
+   * @returns The affected furniture
+   *
+   * @examplePrompt Make this table 1.8m long
+   * @examplePrompt Resize the selected sofa to 2000 wide
+   * @examplePrompt Set this furniture to 800mm tall
+   * @examplePrompt Change the desk to 1500 long and 700 deep
+   *
+   * # Example
+   * ```ts
+   * const [item] = await snaptrude.design.query.listFurniture({ isSelected: true })
+   * const { affected } = await snaptrude.design.furniture.setDimensions(item, {
+   *   length: 1800,
+   *   height: 750
+   * })
+   * ```
+   */
+  public abstract setDimensions(
+    item: ComponentHandle,
+    dimensions: PluginFurnitureDimensionUpdates
+  ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * 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")
+   * ```
+   *
+   * @deprecated Use `design.furniture.listCatalogGroups` — the same name
+   * `design.doors` and `design.windows` use. Still supported.
+   */
+  public abstract listCategories(): PluginApiReturn<string[]>
+
+  /**
+   * List the furniture catalog's groups. Matches
+   * {@linkcode PluginDesignDoorsApi.listCatalogGroups} and
+   * {@linkcode PluginDesignWindowsApi.listCatalogGroups}, so all three catalog
+   * surfaces are named alike.
+   *
+   * `source` is `"default"` for the built-in picker groups and `"team"` for the
+   * sub-types of THIS project's team library — exactly the split
+   * {@linkcode PluginDesignFurnitureApi.listCatalog}'s `source` filter uses, so
+   * every `"team"` group is guaranteed to match at least one team item here.
+   * For furniture the group token and its label are the same string (the
+   * category), so `dbType === label`; `design.doors`/`design.windows` have a
+   * distinct engine `dbType`.
+   *
+   * @returns The catalog groups as {@linkcode PluginObjectCatalogGroup}`[]`
+   *   (`[]` when empty). Pass a group's `dbType` (=== `label`) to
+   *   {@linkcode PluginDesignFurnitureApi.listCatalog}'s `category` filter to
+   *   list its items.
+   *
+   * @examplePrompt What furniture groups are available?
+   * @examplePrompt List the furniture categories in this project
+   *
+   * # Example
+   * ```ts
+   * const groups = await snaptrude.design.furniture.listCatalogGroups()
+   * for (const g of groups) console.log(g.dbType, g.label, g.source)
+   * ```
+   */
+  public abstract listCatalogGroups(): PluginApiReturn<PluginObjectCatalogGroup[]>
+
+  /**
+   * 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 +203,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 +213,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 +226,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
@@ -128,3 +252,68 @@ export type PluginDesignFurnitureGetCatalogItemArgs = z.infer<
 
 export const PluginDesignFurnitureExistsArgs = PluginDesignFurnitureGetCatalogItemArgs
 export type PluginDesignFurnitureExistsArgs = z.infer<typeof PluginDesignFurnitureExistsArgs>
+
+// ---------------------------------------------------------------------------
+// placed-furniture dimensions
+// ---------------------------------------------------------------------------
+
+/**
+ * A placed furniture item's dimensions (engine units).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `length` | `number` | Along the object (panel "Length") |
+ * | `width` | `number` | Across the object (panel "Width") |
+ * | `height` | `number` | Vertical (panel "Height") |
+ */
+export const PluginFurnitureDimensions = z.object({
+  length: z.number(),
+  width: z.number(),
+  height: z.number(),
+})
+export type PluginFurnitureDimensions = z.infer<typeof PluginFurnitureDimensions>
+
+/**
+ * Arguments for {@linkcode PluginDesignFurnitureApi.getDimensions}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `item` | {@linkcode ComponentHandle} | The placed furniture to query |
+ */
+export const PluginDesignFurnitureItemArgs = z.object({
+  item: ComponentHandle,
+})
+export type PluginDesignFurnitureItemArgs = z.infer<typeof PluginDesignFurnitureItemArgs>
+
+/**
+ * A partial dimension patch — each axis is optional; omitted axes are unchanged.
+ * Every supplied axis must be a positive engine-unit length.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `length` | `number`? | New length along the object (engine units, > 0) |
+ * | `width` | `number`? | New width across the object (engine units, > 0) |
+ * | `height` | `number`? | New height (engine units, > 0) |
+ */
+export const PluginFurnitureDimensionUpdates = z.object({
+  length: z.number().positive().optional(),
+  width: z.number().positive().optional(),
+  height: z.number().positive().optional(),
+})
+export type PluginFurnitureDimensionUpdates = z.infer<typeof PluginFurnitureDimensionUpdates>
+
+/**
+ * Arguments for {@linkcode PluginDesignFurnitureApi.setDimensions}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `item` | {@linkcode ComponentHandle} | The placed furniture to resize |
+ * | `dimensions` | {@linkcode PluginFurnitureDimensionUpdates} | The axes to change (each optional) |
+ */
+export const PluginDesignFurnitureSetDimensionsArgs = z.object({
+  item: ComponentHandle,
+  dimensions: PluginFurnitureDimensionUpdates,
+})
+export type PluginDesignFurnitureSetDimensionsArgs = z.infer<
+  typeof PluginDesignFurnitureSetDimensionsArgs
+>

package/src/api/design/index.ts

@@ -13,6 +13,9 @@ import { PluginDesignBooleanApi } from "./boolean"
 import { PluginDesignTransformApi } from "./transform"
 import { PluginDesignEditApi } from "./edit"
 import { PluginDesignUpdateApi } from "./update"
+import { PluginDesignVisibilityApi } from "./visibility"
+import { PluginDesignTypesApi } from "./types"
+import { PluginDesignFamilyApi } from "./family"
 import { PluginDesignChangeResult } from "./lock"
 
 /**
@@ -27,7 +30,11 @@ import { PluginDesignChangeResult } from "./lock"
  * - {@linkcode PluginDesignApi.boolean} — CSG boolean ops (union / subtract / intersect)
  * - {@linkcode PluginDesignApi.erase} — plan-level adjacency-edge erase (NOT hard delete)
  * - {@linkcode PluginDesignApi.delete} — hard entity removal
+ * - {@linkcode PluginDesignApi.visibility} — hide / isolate / reveal entities
+ * - {@linkcode PluginDesignApi.types} — read-only building type / assembly reference
+ * - {@linkcode PluginDesignApi.family} — author parametric families from a JSON spec
  * - {@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.
  */
@@ -58,6 +65,12 @@ export abstract class PluginDesignApi {
   public abstract edit: PluginDesignEditApi
   /** Update existing entities — properties + geometry. See {@linkcode PluginDesignUpdateApi}. */
   public abstract update: PluginDesignUpdateApi
+  /** Hide / isolate / reveal entities. See {@linkcode PluginDesignVisibilityApi}. */
+  public abstract visibility: PluginDesignVisibilityApi
+  /** Read-only building type / assembly reference. See {@linkcode PluginDesignTypesApi}. */
+  public abstract types: PluginDesignTypesApi
+  /** Author parametric families from a JSON spec. See {@linkcode PluginDesignFamilyApi}. */
+  public abstract family: PluginDesignFamilyApi
 
   /**
    * Lock entities so they cannot be edited. Undoable. Cascades to void/door/window
@@ -142,6 +155,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() {}
 }
 
@@ -160,3 +259,6 @@ export * from "./boolean"
 export * from "./transform"
 export * from "./edit"
 export * from "./update"
+export * from "./visibility"
+export * from "./types"
+export * from "./family"

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>