@snaptrude/plugin-core 0.9.17 → 0.9.18-networks-20261016.1

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

@@ -1,319 +1,319 @@
-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) 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() {}
-
-  /**
-   * 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 Show me the bedroom furniture I can place
-   *
-   * # Example
-   * ```ts
-   * 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",
-    category?: string
-  ): PluginApiReturn<PluginFurnitureCatalogItem[]>
-
-  /**
-   * Get a single 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 furniture item from the library
-   * @examplePrompt Look up the catalog entry for this chair id
-   * @examplePrompt What is the cost of this furniture item?
-   * @examplePrompt Show me the family name of the sofa in the catalog
-   *
-   * # Example
-   * ```ts
-   * const [entry] = await snaptrude.design.furniture.listCatalog()
-   * const item = await snaptrude.design.furniture.getCatalogItem(entry.id)
-   * if (item) console.log(item.name, item.source, item.familyName)
-   * ```
-   */
-  public abstract getCatalogItem(
-    id: string
-  ): PluginApiReturn<PluginFurnitureCatalogItem | null>
-
-  /**
-   * Test whether a catalog item exists for the given library id.
-   * @param id The catalog library id
-   * @returns `true` if it exists, otherwise `false`
-   *
-   * @examplePrompt Is this furniture item still in the library?
-   * @examplePrompt Check whether a catalog item with this id exists
-   * @examplePrompt Does my team library have this chair?
-   * @examplePrompt Verify the sofa is available in the catalog before placing it
-   *
-   * # Example
-   * ```ts
-   * const [entry] = await snaptrude.design.furniture.listCatalog()
-   * const stillAvailable = await snaptrude.design.furniture.exists(entry.id)
-   * console.log(stillAvailable ? "safe to place" : "removed from library")
-   * ```
-   */
-  public abstract exists(id: string): PluginApiReturn<boolean>
-}
-
-/**
- * A placeable furniture catalog item (value record — not a scene entity/handle).
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `id` | `string` | Library id (team `_id` or general `fullName`) — pass to `design.create.furniture` |
- * | `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) |
- */
-export const PluginFurnitureCatalogItem = z.object({
-  id: z.string(),
-  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(),
-})
-export type PluginFurnitureCatalogItem = z.infer<typeof PluginFurnitureCatalogItem>
-
-/**
- * Arguments for {@linkcode PluginDesignFurnitureApi.listCatalog}.
- *
- * | 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
->
-
-/**
- * Arguments for {@linkcode PluginDesignFurnitureApi.getCatalogItem} / {@linkcode PluginDesignFurnitureApi.exists}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `id` | `string` | The catalog library id |
- */
-export const PluginDesignFurnitureGetCatalogItemArgs = z.object({
-  id: z.string(),
-})
-export type PluginDesignFurnitureGetCatalogItemArgs = z.infer<
-  typeof PluginDesignFurnitureGetCatalogItemArgs
->
-
-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
->
+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) 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() {}
+
+  /**
+   * 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 Show me the bedroom furniture I can place
+   *
+   * # Example
+   * ```ts
+   * 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",
+    category?: string
+  ): PluginApiReturn<PluginFurnitureCatalogItem[]>
+
+  /**
+   * Get a single 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 furniture item from the library
+   * @examplePrompt Look up the catalog entry for this chair id
+   * @examplePrompt What is the cost of this furniture item?
+   * @examplePrompt Show me the family name of the sofa in the catalog
+   *
+   * # Example
+   * ```ts
+   * const [entry] = await snaptrude.design.furniture.listCatalog()
+   * const item = await snaptrude.design.furniture.getCatalogItem(entry.id)
+   * if (item) console.log(item.name, item.source, item.familyName)
+   * ```
+   */
+  public abstract getCatalogItem(
+    id: string
+  ): PluginApiReturn<PluginFurnitureCatalogItem | null>
+
+  /**
+   * Test whether a catalog item exists for the given library id.
+   * @param id The catalog library id
+   * @returns `true` if it exists, otherwise `false`
+   *
+   * @examplePrompt Is this furniture item still in the library?
+   * @examplePrompt Check whether a catalog item with this id exists
+   * @examplePrompt Does my team library have this chair?
+   * @examplePrompt Verify the sofa is available in the catalog before placing it
+   *
+   * # Example
+   * ```ts
+   * const [entry] = await snaptrude.design.furniture.listCatalog()
+   * const stillAvailable = await snaptrude.design.furniture.exists(entry.id)
+   * console.log(stillAvailable ? "safe to place" : "removed from library")
+   * ```
+   */
+  public abstract exists(id: string): PluginApiReturn<boolean>
+}
+
+/**
+ * A placeable furniture catalog item (value record — not a scene entity/handle).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Library id (team `_id` or general `fullName`) — pass to `design.create.furniture` |
+ * | `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) |
+ */
+export const PluginFurnitureCatalogItem = z.object({
+  id: z.string(),
+  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(),
+})
+export type PluginFurnitureCatalogItem = z.infer<typeof PluginFurnitureCatalogItem>
+
+/**
+ * Arguments for {@linkcode PluginDesignFurnitureApi.listCatalog}.
+ *
+ * | 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
+>
+
+/**
+ * Arguments for {@linkcode PluginDesignFurnitureApi.getCatalogItem} / {@linkcode PluginDesignFurnitureApi.exists}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The catalog library id |
+ */
+export const PluginDesignFurnitureGetCatalogItemArgs = z.object({
+  id: z.string(),
+})
+export type PluginDesignFurnitureGetCatalogItemArgs = z.infer<
+  typeof PluginDesignFurnitureGetCatalogItemArgs
+>
+
+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
+>