@snaptrude/plugin-core 0.3.0 → 0.5.0

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

@@ -0,0 +1,67 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { ComponentHandle } from "../../../handles"
+import { PluginDesignChangeResult } from "../lock"
+
+/**
+ * Arguments for {@linkcode PluginDesignDeleteApi.entities}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode ComponentHandle}`[]` | Entities to delete. Unknown/forged handles reject the whole call (fail-fast). |
+ *
+ * `.min(1)` is deliberately stricter than the shipped `PluginDesignLockArgs`
+ * (which allows an empty array) — an empty delete is a caller error, not a no-op.
+ *
+ * TRANSPORT: positional args — validated host-side as `{ components }`.
+ */
+export const PluginDesignDeleteEntitiesArgs = z.object({
+  components: z.array(ComponentHandle).min(1),
+})
+export type PluginDesignDeleteEntitiesArgs = z.infer<typeof PluginDesignDeleteEntitiesArgs>
+
+/**
+ * `snaptrude.design.delete.*` — **hard removal** of scene BIM entities.
+ *
+ * This is hard entity delete — distinct from `design.erase.edge` (a plan-level
+ * adjacency-edge topology op) and `design.boolean.subtract` (a CSG geometry
+ * delete). The constitution forbids `erase`/`clear`/`remove` as synonyms for
+ * `delete`; these are three separate operations.
+ *
+ * TRANSPORT: positional args per method.
+ */
+export abstract class PluginDesignDeleteApi {
+  constructor() {}
+
+  /**
+   * Delete one or more entities. Generic hard delete (backed by the same batched,
+   * undoable path as `entity.space.delete`). Cascade is opinionated by the engine:
+   * children are removed and linked-list neighbours are fixed up — not caller-tunable
+   * in v1. Undoable — commits as a **single** undo entry.
+   *
+   * @param components - Entities to delete. Unknown/forged handles reject the whole call (fail-fast).
+   * @returns The entities that were deleted, as {@linkcode ComponentHandle}`[]`
+   *   (echoed host-side from the resolved+deleted set — the engine returns no ids).
+   *   Deleted handles are **stale** afterwards: re-resolving one throws `HANDLE_INVALID`.
+   * @throws If any supplied handle is unknown/forged (`HANDLE_INVALID`) — the whole
+   *   call rejects before anything is deleted (all-or-nothing resolution).
+   *
+   * @examplePrompt Delete the selected objects
+   * @examplePrompt Remove these walls from the model
+   * @examplePrompt Get rid of this mass entirely
+   * @examplePrompt Delete all the furniture I picked
+   * @examplePrompt Remove the door and window I just created
+   *
+   * # Example
+   * ```ts
+   * // Hard-delete every furniture item on storey 2 (a single undo entry)
+   * const furniture = await snaptrude.design.query.listFurniture({ storeys: [2] })
+   * if (furniture.length > 0) {
+   *   const { affected } = await snaptrude.design.delete.entities(furniture)
+   * }
+   * ```
+   */
+  public abstract entities(
+    components: ComponentHandle[],
+  ): PluginApiReturn<PluginDesignChangeResult>
+}

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

@@ -0,0 +1,285 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { ComponentHandle } from "../../../handles"
+import { PluginDesignChangeResult } from "../lock"
+
+/**
+ * `snaptrude.design.doors` — door-specific reads + edits. Creation lives at
+ * `design.create.door`; generic reads (`listDoors`/`getHost`/`getProperties`) live at
+ * `design.query.*`. Door targets are {@linkcode ComponentHandle}s.
+ *
+ * `getSwingDirection` is a DERIVED read (no persisted field) — computed from the door
+ * 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).
+ */
+export abstract class PluginDesignDoorsApi {
+  constructor() {}
+
+  /**
+   * Get the type name of a door — the label that identifies which kind of door
+   * the instance is, as shown in its properties.
+   *
+   * @param door The door to query
+   * @returns The type as a `string`, or `null`
+   *
+   * @examplePrompt What type of door is this?
+   * @examplePrompt Tell me the door type of the selected door
+   * @examplePrompt Is this a single or a double door?
+   * @examplePrompt Check what kind of door is on this wall
+   *
+   * # Example
+   * ```ts
+   * const [door] = await snaptrude.design.query.listDoors({ isSelected: true })
+   * const type = await snaptrude.design.doors.getType(door)
+   * if (type) console.log("door type:", type)
+   * ```
+   */
+  public abstract getType(door: ComponentHandle): PluginApiReturn<string | null>
+
+  /**
+   * Get the family name of a door — the Revit or native family the door
+   * instance comes from.
+   *
+   * @param door The door to query
+   * @returns The family as a `string`, or `null`
+   *
+   * @examplePrompt Which family does this door belong to?
+   * @examplePrompt What's the Revit family of the selected door?
+   * @examplePrompt Show the family name for this door
+   * @examplePrompt Find out which door family the imported door uses
+   *
+   * # Example
+   * ```ts
+   * const [door] = await snaptrude.design.query.listDoors()
+   * const family = await snaptrude.design.doors.getFamily(door)
+   * if (family) console.log("family:", family)
+   * ```
+   */
+  public abstract getFamily(door: ComponentHandle): PluginApiReturn<string | null>
+
+  /**
+   * Get the width of a door — how wide its opening is along the host wall.
+   *
+   * @param door The door to query
+   * @returns The width as a `number`, or `null`
+   *
+   * @examplePrompt How wide is this door?
+   * @examplePrompt What's the width of the selected door?
+   * @examplePrompt Measure the width of the entrance door
+   * @examplePrompt Check whether this door is 900mm wide
+   *
+   * # Example
+   * ```ts
+   * const [door] = await snaptrude.design.query.listDoors({ isSelected: true })
+   * const width = await snaptrude.design.doors.getWidth(door)
+   * if (width !== null) console.log("door width:", width)
+   * ```
+   */
+  public abstract getWidth(door: ComponentHandle): PluginApiReturn<number | null>
+
+  /**
+   * Get the height of a door — how tall its opening is from base to head.
+   *
+   * @param door The door to query
+   * @returns The height as a `number`, or `null`
+   *
+   * @examplePrompt How tall is this door?
+   * @examplePrompt What's the height of the selected door?
+   * @examplePrompt Check the door height for this opening
+   * @examplePrompt Is the front door 2100mm high?
+   *
+   * # Example
+   * ```ts
+   * const [door] = await snaptrude.design.query.listDoors()
+   * const height = await snaptrude.design.doors.getHeight(door)
+   * if (height !== null) console.log("door height:", height)
+   * ```
+   */
+  public abstract getHeight(door: ComponentHandle): PluginApiReturn<number | null>
+
+  /**
+   * Get the floor a door is hosted on — the storey/level component that
+   * supports the door.
+   *
+   * @param door The door to query
+   * @returns The support floor {@linkcode ComponentHandle}, or `null`
+   *
+   * @examplePrompt Which floor is this door on?
+   * @examplePrompt What storey does the selected door belong to?
+   * @examplePrompt Find the level that hosts this door
+   * @examplePrompt Tell me which floor the entrance door sits on
+   *
+   * # Example
+   * ```ts
+   * const [door] = await snaptrude.design.query.listDoors({ isSelected: true })
+   * const floor = await snaptrude.design.doors.getSupportFloor(door)
+   * if (floor) {
+   *   const props = await snaptrude.design.query.getProperties(floor)
+   *   console.log("hosted on storey:", props.storey)
+   * }
+   * ```
+   */
+  public abstract getSupportFloor(door: ComponentHandle): PluginApiReturn<ComponentHandle | null>
+
+  /**
+   * Get a door's swing (hinge) handedness — whether it opens as a left-hand or
+   * right-hand door. Derived from the door mesh's reflection state, not a
+   * persisted field.
+   *
+   * @param door The door to query
+   * @returns `'left'` / `'right'`, or `null` if indeterminate
+   *
+   * @examplePrompt Which way does this door swing?
+   * @examplePrompt Is the selected door left-handed or right-handed?
+   * @examplePrompt Check the hinge side of this door
+   * @examplePrompt Does the entrance door open to the left or the right?
+   *
+   * # Example
+   * ```ts
+   * const [door] = await snaptrude.design.query.listDoors({ isSelected: true })
+   * const swing = await snaptrude.design.doors.getSwingDirection(door)
+   * if (swing) console.log("opens as a", swing, "hand door")
+   * ```
+   */
+  public abstract getSwingDirection(
+    door: ComponentHandle
+  ): PluginApiReturn<"left" | "right" | null>
+
+  /**
+   * Mirror a door across an axis, flipping its swing so it opens from the
+   * other side. Undoable as a single command.
+   *
+   * @param door The door to mirror
+   * @param axis Reflection axis (optional; default `'x'` — the swing-flip axis)
+   * @returns The affected door(s)
+   *
+   * @examplePrompt Flip this door's swing
+   * @examplePrompt Mirror the selected door
+   * @examplePrompt Make this door open the other way
+   * @examplePrompt Reverse the hinge side of the entrance door
+   * @examplePrompt Change the door to swing from the other side
+   *
+   * # Example
+   * ```ts
+   * // Flip the selected door's swing — axis defaults to "x" (the swing-flip
+   * // axis); pass "y" or "z" to reflect across a different axis
+   * const [door] = await snaptrude.design.query.listDoors({ isSelected: true })
+   * const { affected } = await snaptrude.design.doors.mirror(door)
+   * ```
+   */
+  public abstract mirror(
+    door: ComponentHandle,
+    axis?: PluginMirrorAxis
+  ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Set the width of one or more doors, resizing each opening and re-cutting
+   * the host wall. Width is in engine units; the change is undoable.
+   *
+   * @param doors The doors to resize
+   * @param width New width (engine units)
+   * @returns The affected doors
+   *
+   * @examplePrompt Make this door 900mm wide
+   * @examplePrompt Widen the selected doors to 1 metre
+   * @examplePrompt Change the door width to 3 feet
+   * @examplePrompt Resize all the bathroom doors to 750 wide
+   * @examplePrompt Narrow the entrance door a bit
+   *
+   * # Example
+   * ```ts
+   * // Resize every ground-floor door to a common width (engine units)
+   * const doors = await snaptrude.design.query.listDoors({ storeys: [1] })
+   * const { affected } = await snaptrude.design.doors.setWidth(doors, 900)
+   * console.log("resized", affected.length, "doors")
+   * ```
+   */
+  public abstract setWidth(
+    doors: ComponentHandle[],
+    width: number
+  ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Set the height of one or more doors, resizing each opening and re-cutting
+   * the host wall. Height is in engine units; the change is undoable.
+   *
+   * @param doors The doors to resize
+   * @param height New height (engine units)
+   * @returns The affected doors
+   *
+   * @examplePrompt Make this door 2100mm tall
+   * @examplePrompt Change the door height to 7 feet
+   * @examplePrompt Raise the selected doors to 2.4m high
+   * @examplePrompt Set all the doors on this storey to 2100 high
+   *
+   * # Example
+   * ```ts
+   * // setHeight takes an array — wrap a single door
+   * const [door] = await snaptrude.design.query.listDoors({ isSelected: true })
+   * await snaptrude.design.doors.setHeight([door], 2100)
+   * ```
+   */
+  public abstract setHeight(
+    doors: ComponentHandle[],
+    height: number
+  ): PluginApiReturn<PluginDesignChangeResult>
+}
+
+/**
+ * Arguments for the single-door read methods.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `door` | {@linkcode ComponentHandle} | The door to query |
+ */
+export const PluginDesignDoorArgs = z.object({
+  door: ComponentHandle,
+})
+export type PluginDesignDoorArgs = z.infer<typeof PluginDesignDoorArgs>
+
+/** Mirror axis — tokens mirror the engine `FlipDirection` verbatim (§6.1). */
+export const PluginMirrorAxis = z.enum(["x", "y", "z"])
+export type PluginMirrorAxis = z.infer<typeof PluginMirrorAxis>
+
+/**
+ * Arguments for {@linkcode PluginDesignDoorsApi.mirror}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `door` | {@linkcode ComponentHandle} | The door to mirror |
+ * | `axis` | {@linkcode PluginMirrorAxis} | Reflection axis (optional; default `'x'` — the swing-flip axis) |
+ */
+export const PluginDesignDoorMirrorArgs = z.object({
+  door: ComponentHandle,
+  axis: PluginMirrorAxis.optional(),
+})
+export type PluginDesignDoorMirrorArgs = z.infer<typeof PluginDesignDoorMirrorArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignDoorsApi.setWidth}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `doors` | {@linkcode ComponentHandle}`[]` | The doors to resize |
+ * | `width` | `number` | New width (engine units) |
+ */
+export const PluginDesignDoorSetWidthArgs = z.object({
+  doors: z.array(ComponentHandle),
+  width: z.number(),
+})
+export type PluginDesignDoorSetWidthArgs = z.infer<typeof PluginDesignDoorSetWidthArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignDoorsApi.setHeight}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `doors` | {@linkcode ComponentHandle}`[]` | The doors to resize |
+ * | `height` | `number` | New height (engine units) |
+ */
+export const PluginDesignDoorSetHeightArgs = z.object({
+  doors: z.array(ComponentHandle),
+  height: z.number(),
+})
+export type PluginDesignDoorSetHeightArgs = z.infer<typeof PluginDesignDoorSetHeightArgs>

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

@@ -0,0 +1,54 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { ComponentHandle, Vec3Handle } from "../../../handles"
+import { OffsetSplitOutcome } from "../shared"
+
+/**
+ * STAGED (LLD Wave 2) — abstract shell only. NOT yet wired into `PluginDesignApi`
+ * and has no host implementation. `offsetSplit` migrates off `tools.offset` (adding
+ * the previously-dropped `offsetValue` to the result).
+ *
+ * `snaptrude.design.edit` — non-create geometry edits (offset-split, and later
+ * push-pull / topology edits). Undoable.
+ *
+ * TRANSPORT: positional args per method.
+ */
+export abstract class PluginDesignEditApi {
+  constructor() {}
+
+  /**
+   * Offset the top profile of a component by a distance and split the face along
+   * the offset curve. Positive distances offset outward, negative inward.
+   * Single-component only (the engine rejects batches).
+   * @param component - The component whose top profile is offset-split.
+   * @param offsetDistance - Offset distance; positive = outward, negative = inward.
+   * @param options - Optional settings: `profilePickPoint` picks the profile when ambiguous.
+   * @returns {@linkcode OffsetSplitOutcome} `{ createdIds, deletedIds, offsetValue }`
+   *
+   * @examplePrompt Offset the top face of this mass inward by 2 metres and split it
+   * @examplePrompt Create a 1m setback border on top of the selected mass
+   * @examplePrompt Split the roof profile with a 500mm inward offset
+   * @examplePrompt Offset-split the slab's top profile outward by 3 feet
+   *
+   * # Example
+   * ```ts
+   * // Offset the top profile inward by 2 units and split the face along it
+   * const [mass] = await snaptrude.design.query.listMasses()
+   * const { createdIds, offsetValue } = await snaptrude.design.edit.offsetSplit(mass, -2)
+   * // offsetValue is the post-clamp distance the engine actually applied
+   * ```
+   */
+  public abstract offsetSplit(
+    component: ComponentHandle,
+    offsetDistance: number,
+    options?: { profilePickPoint?: Vec3Handle },
+  ): PluginApiReturn<OffsetSplitOutcome>
+}
+
+// Positional target: offsetSplit(component, offsetDistance, options?)
+export const PluginDesignOffsetSplitArgs = z.object({
+  component: ComponentHandle,
+  offsetDistance: z.number(),
+  profilePickPoint: Vec3Handle.optional(),
+})
+export type PluginDesignOffsetSplitArgs = z.infer<typeof PluginDesignOffsetSplitArgs>

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

@@ -0,0 +1,151 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { ComponentHandle, Vec3Handle } from "../../../handles"
+
+/**
+ * The erase strategies exposed to plugins. `SplitAndUnion` is *enumerable* but
+ * NOT committable via {@linkcode PluginDesignEraseApi.edge} (it needs an
+ * interactive screen-space re-pick); `SplitAndDelete` is reserved in the engine
+ * and intentionally omitted. Derived host-side by the engine's `decideStrategy`.
+ */
+export const EraseStrategy = z.enum(["DirectDelete", "DirectUnion", "SplitAndUnion"])
+export type EraseStrategy = z.infer<typeof EraseStrategy>
+
+/** Default enumerated strategies — the two the scripted `edge()` can commit. */
+export const DEFAULT_ERASE_STRATEGIES: readonly EraseStrategy[] = ["DirectDelete", "DirectUnion"]
+
+/**
+ * A **transient** reference to one erasable edge in the current plan's
+ * bottom-adjacency graph.
+ *
+ * ⚠️ **Lifetime**: valid ONLY until the next geometry-modifying operation. Any
+ * mutation (erase, boolean, transform, create, delete, …) rebuilds the adjacency
+ * graph and invalidates every previously-returned ref. Passing a stale ref to
+ * {@linkcode PluginDesignEraseApi.edge} throws `NO_STRATEGY_FOR_PICK_INFO`.
+ * Always re-list after a mutation.
+ *
+ * This is a by-value record (round-trip it back to `edge()` unmodified), NOT a
+ * registry handle. `components` and `snapPoint` are the marshalled public forms
+ * of the engine's raw `mesh.uniqueId` numbers / by-value point.
+ */
+export const ErasableEdgeRef = z.object({
+  /** Opaque bottom-graph edge id (engine form `"e-<n>"`). Do not mutate. Pass verbatim to {@linkcode PluginDesignEraseApi.edge}. */
+  id: z.string().min(1),
+  /** What erasing this edge would do: `DirectDelete` drops a mass; `DirectUnion` merges two adjacent masses. */
+  strategy: EraseStrategy,
+  /** Bottom-graph edge weight: `1` = external boundary edge, `>=2` = internal edge shared between components. */
+  edgeWeight: z.number(),
+  /** The components this edge is incident to — one for external (DirectDelete), two for internal (DirectUnion). */
+  components: z.array(ComponentHandle),
+  /** A representative point on the edge (its head endpoint). Diagnostic only. */
+  snapPoint: Vec3Handle,
+})
+export type ErasableEdgeRef = z.infer<typeof ErasableEdgeRef>
+
+/**
+ * Options for {@linkcode PluginDesignEraseApi.listErasableEdges}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode ComponentHandle}`[]?` | Restrict to edges adjacent to at least one of these entities |
+ * | `strategies` | {@linkcode EraseStrategy}`[]?` | Restrict to these strategies. Default `["DirectDelete","DirectUnion"]` (hides interactive-only `SplitAndUnion`) |
+ *
+ * TRANSPORT: positional now — `listErasableEdges(options?)`; this schema is
+ * retained for host-side validation.
+ */
+export const PluginDesignListErasableEdgesArgs = z.object({
+  components: z.array(ComponentHandle).optional(),
+  strategies: z.array(EraseStrategy).optional(),
+})
+export type PluginDesignListErasableEdgesArgs = z.infer<typeof PluginDesignListErasableEdgesArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignEraseApi.edge}.
+ *
+ * TRANSPORT: positional now — `edge(edge: ErasableEdgeRef)`; this schema is
+ * retained for host-side validation.
+ */
+export const PluginDesignEraseEdgeArgs = z.object({
+  edge: ErasableEdgeRef,
+})
+export type PluginDesignEraseEdgeArgs = z.infer<typeof PluginDesignEraseEdgeArgs>
+
+/** Result of {@linkcode PluginDesignEraseApi.edge} — success sentinel; the engine yields no survivor id. */
+export const PluginDesignEraseEdgeResult = z.object({ ok: z.literal(true) })
+export type PluginDesignEraseEdgeResult = z.infer<typeof PluginDesignEraseEdgeResult>
+
+/**
+ * `snaptrude.design.erase` — **adjacency-edge erase** (plan-level topology op).
+ *
+ * Erase is NOT delete. The erase tool operates on an **edge**, and the effect is
+ * derived from that edge: erasing an internal edge between two masses **unions**
+ * them (`DirectUnion`); erasing an external boundary edge of a single mass
+ * **drops** it behind the edge (`DirectDelete`). For hard entity removal use
+ * `design.delete.entities`; for CSG geometry delete use `design.boolean.subtract`.
+ *
+ * Two-step: {@linkcode listErasableEdges} to enumerate, then {@linkcode edge} to
+ * commit one ref (single undo entry). Scoped to **2D plan adjacency edges** in v1.
+ *
+ * TRANSPORT: positional args per method.
+ */
+export abstract class PluginDesignEraseApi {
+  constructor() {}
+
+  /**
+   * Enumerate every erasable edge in the current plan's bottom-adjacency graph
+   * (one {@linkcode ErasableEdgeRef} per edge). Pure read — no scene mutation, no
+   * command, not undoable. Erase-ineligible components (locked, hidden, off-storey)
+   * are filtered out.
+   *
+   * ⚠️ Returned refs are **transient** — see {@linkcode ErasableEdgeRef}. Re-list
+   * after any geometry mutation.
+   *
+   * @param options - {@linkcode PluginDesignListErasableEdgesArgs} — optional filters (`components`, `strategies`)
+   * @returns The erasable edges (`[]` when none) — never `null`.
+   *
+   * @examplePrompt Which edges in my floor plan can be erased?
+   * @examplePrompt List the erasable edges on this storey
+   * @examplePrompt Show me the shared edges I could erase to merge rooms
+   * @examplePrompt What edges between these two spaces can be removed?
+   *
+   * # Example
+   * ```ts
+   * const edges = await snaptrude.design.erase.listErasableEdges()
+   * const union = edges.find((e) => e.strategy === "DirectUnion")
+   * if (union) await snaptrude.design.erase.edge(union)
+   * ```
+   */
+  public abstract listErasableEdges(
+    options?: PluginDesignListErasableEdgesArgs,
+  ): PluginApiReturn<ErasableEdgeRef[]>
+
+  /**
+   * Commit the erase for one edge. `DirectUnion` merges the two adjacent masses;
+   * `DirectDelete` drops the single mass behind the boundary edge. Single undo entry.
+   *
+   * Pass an {@linkcode ErasableEdgeRef} from {@linkcode listErasableEdges}
+   * unmodified. A stale ref (graph rebuilt by a prior mutation) or a `SplitAndUnion`
+   * edge throws.
+   *
+   * @param edge - The {@linkcode ErasableEdgeRef} to erase, from {@linkcode listErasableEdges} unmodified
+   * @returns `{ ok: true }` on success (the engine yields no survivor id today).
+   * @throws when the ref is stale, its components are all erase-ineligible, or the
+   *   strategy is not committable via the scripted path.
+   *
+   * @examplePrompt Erase the edge between these two rooms so they merge
+   * @examplePrompt Remove the shared boundary between the kitchen and the dining space
+   * @examplePrompt Merge the two adjacent rooms by erasing their common edge
+   * @examplePrompt Knock through the partition line between these spaces
+   * @examplePrompt Erase this boundary edge from the plan
+   *
+   * # Example
+   * ```ts
+   * // Merge two adjacent rooms by erasing an internal edge they share
+   * const edges = await snaptrude.design.erase.listErasableEdges({ strategies: ["DirectUnion"] })
+   * if (edges.length > 0) {
+   *   const { ok } = await snaptrude.design.erase.edge(edges[0])
+   * }
+   * ```
+   */
+  public abstract edge(edge: ErasableEdgeRef): PluginApiReturn<PluginDesignEraseEdgeResult>
+}

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

@@ -0,0 +1,130 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+
+/**
+ * `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`.
+ *
+ * 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).
+ */
+export abstract class PluginDesignFurnitureApi {
+  constructor() {}
+
+  /**
+   * List the placeable furniture catalog (team + general libraries).
+   * @param source Restrict to one library (optional)
+   * @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
+   *
+   * # Example
+   * ```ts
+   * const teamItems = await snaptrude.design.furniture.listCatalog("team")
+   * for (const item of teamItems) console.log(item.id, item.name, item.cost)
+   * ```
+   */
+  public abstract listCatalog(
+    source?: "team" | "general"
+  ): 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) |
+ * | `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(),
+  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) |
+ */
+export const PluginDesignFurnitureListCatalogArgs = z.object({
+  source: z.enum(["team", "general"]).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>