@snaptrude/plugin-core 0.0.0-bimsvg-20260928124803

package/src/api/design/index.ts

@@ -0,0 +1,274 @@
+import { PluginApiReturn } from "../../types"
+import { ComponentHandle } from "../../handles"
+import { PluginDesignCreateApi } from "./create"
+import { PluginDesignQueryApi } from "./query"
+import { PluginDesignSelectionApi } from "./selection"
+import { PluginDesignDoorsApi } from "./doors"
+import { PluginDesignWindowsApi } from "./windows"
+import { PluginDesignFurnitureApi } from "./furniture"
+import { PluginDesignMaterialsApi } from "./materials"
+import { PluginDesignEraseApi } from "./erase"
+import { PluginDesignDeleteApi } from "./delete"
+import { PluginDesignBooleanApi } from "./boolean"
+import { PluginDesignTransformApi } from "./transform"
+import { PluginDesignEditApi } from "./edit"
+import { PluginDesignUpdateApi } from "./update"
+import { PluginDesignVisibilityApi } from "./visibility"
+import { PluginDesignDimensionsApi } from "./dimensions"
+import { PluginDesignTypesApi } from "./types"
+import { PluginDesignFamilyApi } from "./family"
+import { PluginDesignGridsApi } from "./grids"
+import { PluginDesignChangeResult } from "./lock"
+
+/**
+ * `snaptrude.design.*` — author, query & edit BIM geometry.
+ *
+ * - {@linkcode PluginDesignApi.create} — new BIM entities
+ * - {@linkcode PluginDesignApi.query} — read entities + their geometry
+ * - {@linkcode PluginDesignApi.selection} — read/mutate the scene selection
+ * - {@linkcode PluginDesignApi.doors} / {@linkcode PluginDesignApi.windows} — fenestration reads + edits
+ * - {@linkcode PluginDesignApi.furniture} — furniture catalog reads
+ * - {@linkcode PluginDesignApi.materials} — material library + assignment
+ * - {@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.dimensions} — dimension lines (Measuring Tape): create / list / delete / hide
+ * - {@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.
+ */
+export abstract class PluginDesignApi {
+  /** Author new scene-committed BIM entities. See {@linkcode PluginDesignCreateApi}. */
+  public abstract create: PluginDesignCreateApi
+  /** Read scene entities and their geometry. See {@linkcode PluginDesignQueryApi}. */
+  public abstract query: PluginDesignQueryApi
+  /** Read/mutate the current selection. See {@linkcode PluginDesignSelectionApi}. */
+  public abstract selection: PluginDesignSelectionApi
+  /** Door-specific reads + edits. See {@linkcode PluginDesignDoorsApi}. */
+  public abstract doors: PluginDesignDoorsApi
+  /** Window-specific reads. See {@linkcode PluginDesignWindowsApi}. */
+  public abstract windows: PluginDesignWindowsApi
+  /** Furniture catalog reads. See {@linkcode PluginDesignFurnitureApi}. */
+  public abstract furniture: PluginDesignFurnitureApi
+  /** Material library + assignment. See {@linkcode PluginDesignMaterialsApi}. */
+  public abstract materials: PluginDesignMaterialsApi
+  /** Plan-level adjacency-edge erase (NOT hard delete). See {@linkcode PluginDesignEraseApi}. */
+  public abstract erase: PluginDesignEraseApi
+  /** Hard entity removal. See {@linkcode PluginDesignDeleteApi}. */
+  public abstract delete: PluginDesignDeleteApi
+  /** CSG boolean ops (union / subtract / intersect). See {@linkcode PluginDesignBooleanApi}. */
+  public abstract boolean: PluginDesignBooleanApi
+  /** Rigid transforms — move / rotate. See {@linkcode PluginDesignTransformApi}. */
+  public abstract transform: PluginDesignTransformApi
+  /** Non-create geometry edits — offset-split. See {@linkcode PluginDesignEditApi}. */
+  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
+  /** Dimension lines (Measuring Tape). See {@linkcode PluginDesignDimensionsApi}. */
+  public abstract dimensions: PluginDesignDimensionsApi
+  /** 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
+
+  /** Structural edits on a grid's line structure. See {@linkcode PluginDesignGridsApi}. */
+  public abstract grids: PluginDesignGridsApi
+
+  /**
+   * Lock entities so they cannot be edited. Undoable. Cascades to void/door/window
+   * children, stacked-wall companions, and terrain neighborhood; skips
+   * active-group members.
+   * @param components Entities to lock
+   * @returns The affected entities (post-cascade)
+   *
+   * @examplePrompt Lock the selected walls so they can't be edited
+   * @examplePrompt Freeze these masses so nobody moves them by accident
+   * @examplePrompt Lock everything on the ground floor
+   * @examplePrompt Protect this room from further changes
+   *
+   * # Example
+   * ```ts
+   * // Lock every wall on the ground storey
+   * const walls = await snaptrude.design.query.listWalls({ storeys: [1] })
+   * const { affected } = await snaptrude.design.lock(walls)
+   * // affected is post-cascade: hosted doors/windows are included
+   * ```
+   */
+  public abstract lock(components: ComponentHandle[]): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Unlock previously locked entities so they can be edited again. Undoable.
+   * Paired with {@linkcode PluginDesignApi.lock}.
+   * @param components Entities to unlock
+   * @returns The affected entities
+   *
+   * @examplePrompt Unlock the selected objects
+   * @examplePrompt Make this locked wall editable again
+   * @examplePrompt Unfreeze the masses I locked earlier
+   * @examplePrompt Remove the lock from these doors
+   *
+   * # Example
+   * ```ts
+   * // Unlock everything that is explicitly locked
+   * const locked = await snaptrude.design.listLocked()
+   * const { affected } = await snaptrude.design.unlock(locked)
+   * ```
+   */
+  public abstract unlock(components: ComponentHandle[]): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Test whether an entity is locked (folds group + bucket lock unless `includeInherited: false`).
+   * @param component The entity to test
+   * @param includeInherited Fold group + bucket lock (default `true`); `false` reads the own flag only
+   * @returns `true` if locked, otherwise `false`
+   *
+   * @examplePrompt Is this wall locked?
+   * @examplePrompt Check whether the selected mass is locked or editable
+   * @examplePrompt Why can't I move this object? Check if it is locked
+   * @examplePrompt Tell me if this room is locked, counting locks inherited from its group
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const locked = await snaptrude.design.isLocked(wall)
+   * // Own flag only — ignore locks inherited from the group / bucket
+   * const ownLock = await snaptrude.design.isLocked(wall, false)
+   * ```
+   */
+  public abstract isLocked(
+    component: ComponentHandle,
+    includeInherited?: boolean,
+  ): PluginApiReturn<boolean>
+
+  /**
+   * List the explicitly-locked entities (excludes purely group/bucket-inherited locks).
+   * @returns The locked entities as {@linkcode ComponentHandle}`[]`
+   *
+   * @examplePrompt Which objects in the model are locked?
+   * @examplePrompt List all the locked entities in this project
+   * @examplePrompt Show everything that has been locked
+   * @examplePrompt Are there any locked walls or masses in the scene?
+   *
+   * # Example
+   * ```ts
+   * const locked = await snaptrude.design.listLocked()
+   * console.log(locked.length, "explicitly locked entities")
+   * ```
+   */
+  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() {}
+}
+
+export * from "./create"
+export * from "./query"
+export * from "./selection"
+export * from "./doors"
+export * from "./windows"
+export * from "./furniture"
+export * from "./materials"
+export * from "./lock"
+export * from "./erase"
+export * from "./delete"
+export * from "./shared"
+export * from "./boolean"
+export * from "./transform"
+export * from "./edit"
+export * from "./update"
+export * from "./visibility"
+export * from "./dimensions"
+export * from "./types"
+export * from "./family"
+export * from "./grids"

package/src/api/design/lock.ts

@@ -0,0 +1,69 @@
+import * as z from "zod"
+import { ComponentHandle } from "../../handles"
+
+/**
+ * Shared result for scene-state change mutations (lock/unlock, selection, visibility)
+ * — echoes the handles actually affected (post-cascade for lock). Errors throw
+ * (RPC rejects); there is no `Result<>` monad in the SDK (consistent with
+ * `design.create.*` returning a handle directly).
+ */
+export const PluginDesignChangeResult = z.object({
+  affected: z.array(ComponentHandle),
+})
+export type PluginDesignChangeResult = z.infer<typeof PluginDesignChangeResult>
+
+/**
+ * Arguments for {@linkcode PluginDesignApi.lock} / {@linkcode PluginDesignApi.unlock}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode ComponentHandle}`[]` | Entities to lock / unlock |
+ */
+export const PluginDesignLockArgs = z.object({
+  components: z.array(ComponentHandle),
+})
+export type PluginDesignLockArgs = z.infer<typeof PluginDesignLockArgs>
+
+export const PluginDesignUnlockArgs = PluginDesignLockArgs
+export type PluginDesignUnlockArgs = z.infer<typeof PluginDesignUnlockArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignApi.isLocked}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `component` | {@linkcode ComponentHandle} | The entity to test |
+ * | `includeInherited` | `boolean` | Fold group + bucket lock (default `true`); `false` reads the own flag only |
+ */
+export const PluginDesignIsLockedArgs = z.object({
+  component: ComponentHandle,
+  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>