@snaptrude/plugin-core 0.7.1 → 0.9.0

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

@@ -9,6 +9,12 @@ import {
   PluginSpaceUpdateResult,
 } from "../../entity/space"
 import { PluginDesignChangeResult } from "../lock"
+import {
+  PluginBuildableEnvelopePolygonVertex,
+  PluginBuildableEnvelopeSetbackTier,
+  PluginBuildableEnvelopeVerticalCap,
+  PluginBuildableEnvelopeUpdateResult,
+} from "../../entity/buildableEnvelope"
 
 /**
  * Sparse property updates for a space. Only provided fields change.
@@ -28,14 +34,18 @@ export const PluginSpacePropertyUpdates = z.object({
   areaClass: PluginAreaClass.optional(),
   departmentId: PluginDepartmentId.optional(),
 })
-export type PluginSpacePropertyUpdates = z.infer<typeof PluginSpacePropertyUpdates>
+export type PluginSpacePropertyUpdates = z.infer<
+  typeof PluginSpacePropertyUpdates
+>
 
 /** Geometry replacement for a space — re-extrude a profile. */
 export const PluginSpaceGeometryUpdate = z.object({
   profile: ProfileHandle,
   extrudeHeight: z.number(),
 })
-export type PluginSpaceGeometryUpdate = z.infer<typeof PluginSpaceGeometryUpdate>
+export type PluginSpaceGeometryUpdate = z.infer<
+  typeof PluginSpaceGeometryUpdate
+>
 
 /** One space to update via {@linkcode PluginDesignUpdateApi.spaces}. */
 export const PluginUpdateSpaceItem = z.object({
@@ -106,7 +116,9 @@ export const PluginStaircaseParamUpdates = z
     message:
       "PluginStaircaseParamUpdates requires at least one field to change",
   })
-export type PluginStaircaseParamUpdates = z.infer<typeof PluginStaircaseParamUpdates>
+export type PluginStaircaseParamUpdates = z.infer<
+  typeof PluginStaircaseParamUpdates
+>
 
 /**
  * Arguments for {@linkcode PluginDesignUpdateApi.staircase}.
@@ -120,7 +132,111 @@ export const PluginDesignUpdateStaircaseArgs = z.object({
   staircases: z.array(ComponentHandle),
   params: PluginStaircaseParamUpdates,
 })
-export type PluginDesignUpdateStaircaseArgs = z.infer<typeof PluginDesignUpdateStaircaseArgs>
+export type PluginDesignUpdateStaircaseArgs = z.infer<
+  typeof PluginDesignUpdateStaircaseArgs
+>
+
+/**
+ * Sparse edits for a wall (all optional; at least one required). Only the
+ * fields you provide change. Dimensions are in **engine units** (the same
+ * convention as `design.doors.setWidth`). Consumed by
+ * {@linkcode PluginDesignUpdateApi.wall}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `thickness` | `number`? | Wall thickness, engine units (> 0) |
+ * | `height` | `number`? | Wall height, engine units (> 0) |
+ * | `type` | `string`? | Convert the wall to another wall type — a name (or `wall:`-prefixed id) from `design.types.list("wall")` |
+ */
+export const PluginWallUpdates = z
+  .object({
+    thickness: z.number().positive().optional(),
+    height: z.number().positive().optional(),
+    type: z.string().trim().min(1).optional(),
+  })
+  .refine((p) => Object.keys(p).length > 0, {
+    message: "PluginWallUpdates requires at least one field to change",
+  })
+export type PluginWallUpdates = z.infer<typeof PluginWallUpdates>
+
+/**
+ * Sparse dimension edits for a slab-family element (slab / floor / roof /
+ * ceiling). All values are engine units, the same convention as
+ * `design.doors.setWidth`. Consumed by {@linkcode PluginDesignUpdateApi.slab},
+ * `floor`, `roof`, and `ceiling`.
+ *
+ * `overhang` is only available on **slabs and roofs** (the panel's Overhang
+ * slider) — floors and ceilings reject it with `PRECONDITION_FAILED`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `thickness` | `number`? | Element thickness, engine units (> 0) |
+ * | `overhang` | `number`? | Absolute overhang offset, engine units (slab / roof only) |
+ */
+export const PluginSlabUpdates = z
+  .object({
+    thickness: z.number().positive().optional(),
+    overhang: z.number().optional(),
+  })
+  .refine((p) => Object.keys(p).length > 0, {
+    message: "PluginSlabUpdates requires at least one field to change",
+  })
+export type PluginSlabUpdates = z.infer<typeof PluginSlabUpdates>
+
+/** Arguments for {@linkcode PluginDesignUpdateApi.wall}. */
+export const PluginDesignUpdateWallArgs = z.object({
+  component: ComponentHandle,
+  updates: PluginWallUpdates,
+})
+export type PluginDesignUpdateWallArgs = z.infer<
+  typeof PluginDesignUpdateWallArgs
+>
+
+/**
+ * Arguments for the slab-family updaters —
+ * {@linkcode PluginDesignUpdateApi.slab}, `floor`, `roof`, `ceiling`.
+ */
+export const PluginDesignUpdateSlabArgs = z.object({
+  component: ComponentHandle,
+  updates: PluginSlabUpdates,
+})
+export type PluginDesignUpdateSlabArgs = z.infer<
+  typeof PluginDesignUpdateSlabArgs
+>
+
+/** Arguments for {@linkcode PluginDesignUpdateApi.setElevation}. */
+export const PluginDesignSetElevationArgs = z.object({
+  component: ComponentHandle,
+  elevation: z.number(),
+})
+export type PluginDesignSetElevationArgs = z.infer<
+  typeof PluginDesignSetElevationArgs
+>
+
+/** Arguments for {@linkcode PluginDesignUpdateApi.setBaseOffset}. */
+export const PluginDesignSetBaseOffsetArgs = z.object({
+  component: ComponentHandle,
+  offset: z.number(),
+})
+export type PluginDesignSetBaseOffsetArgs = z.infer<
+  typeof PluginDesignSetBaseOffsetArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginDesignUpdateApi.setStorey}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode ComponentHandle}`[]` | The components to reassign |
+ * | `storey` | `number` | Target integer storey number (`entity.story` convention; must exist) |
+ */
+export const PluginDesignSetStoreyArgs = z.object({
+  components: z.array(ComponentHandle),
+  storey: z.number().int(),
+})
+export type PluginDesignSetStoreyArgs = z.infer<
+  typeof PluginDesignSetStoreyArgs
+>
 
 /**
  * `snaptrude.design.update` — edit existing scene entities (properties + geometry).
@@ -169,7 +285,10 @@ export abstract class PluginDesignUpdateApi {
    * }
    * ```
    */
-  public abstract setLabel(component: ComponentHandle, label: string): PluginApiReturn<boolean>
+  public abstract setLabel(
+    component: ComponentHandle,
+    label: string,
+  ): PluginApiReturn<boolean>
 
   /**
    * Update a single space (room) — change its properties (room label, space
@@ -187,6 +306,9 @@ export abstract class PluginDesignUpdateApi {
    * @examplePrompt Move this space into the Circulation department
    * @examplePrompt Exclude this room from the area calculations
    *
+   * @performance For MORE THAN ONE space, call `design.update.spaces(items[])` — the whole
+   *   batch is one host round-trip. Looping this single-space updater is N round-trips.
+   *
    * # Example
    * ```ts
    * await snaptrude.design.update.space("space-id", { properties: { room_type: "Office" } })
@@ -217,6 +339,9 @@ export abstract class PluginDesignUpdateApi {
    * @examplePrompt Bulk-assign these spaces to the Service department
    * @examplePrompt Mark all of these rooms as excluded from area in one update
    *
+   * @performance Bulk update — the whole batch is ONE host round-trip. Prefer over looping
+   *   `design.update.space`: build the `items[]` array first, then make one call.
+   *
    * # Example
    * ```ts
    * // Re-label every selected room and mark it NET area — one undoable bulk update
@@ -231,7 +356,9 @@ export abstract class PluginDesignUpdateApi {
    * console.log(results.map((r) => r.spaceId))
    * ```
    */
-  public abstract spaces(items: PluginUpdateSpaceItem[]): PluginApiReturn<PluginSpaceUpdateResult[]>
+  public abstract spaces(
+    items: PluginUpdateSpaceItem[],
+  ): PluginApiReturn<PluginSpaceUpdateResult[]>
 
   /**
    * Update the parameters of one or more staircases — riser, tread, width,
@@ -281,4 +408,338 @@ export abstract class PluginDesignUpdateApi {
     staircases: ComponentHandle[],
     params: PluginStaircaseParamUpdates,
   ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Edit a **wall** — its thickness and/or height (the same command the
+   * properties panel's Thickness/Height fields drive) and/or its **wall type**
+   * (the panel's Wall Types dropdown: converts the wall to another type,
+   * rebuilding its layer stack and materials). Sparse: only the fields you
+   * provide change. Undoable; the geometry rebuilds and any dimension lines
+   * refresh. Stacked-wall companions and hosted fenestration are handled
+   * exactly as the panel does.
+   *
+   * Thickness/height are in **engine units** (the same convention as
+   * `design.doors.setWidth`) and must be `> 0`. Shrinking a wall past its
+   * openings is rejected by the engine (the wall is skipped with no change).
+   * `type` accepts a type name from `design.types.list("wall")` (or its
+   * `wall:`-prefixed id); when combined with dimensions, the type conversion
+   * is applied first so an explicit thickness/height wins over the type's
+   * defaults. Re-applying the wall's current type is a no-op.
+   *
+   * Throws when the handle is not a wall, when the wall is locked, when the
+   * handle is gone/forged, when `type` names an unknown wall type, when the
+   * engine rejects the conversion (e.g. a curved wall thinner than the new
+   * type's minimum thickness), or when no field is provided.
+   *
+   * A type conversion (and a thickness edit on a parametric wall) REBUILDS the
+   * wall, replacing it with a new component: the input handle is then dead
+   * (further calls throw HANDLE_INVALID) and `affected[0]` carries the
+   * replacement's handle — use it for any follow-up calls.
+   *
+   * @param component - The wall to edit
+   * @param updates - Sparse {@linkcode PluginWallUpdates} (at least one field)
+   * @returns the affected wall — after a rebuild, the REPLACEMENT wall's handle
+   *
+   * @examplePrompt Make this wall 230mm thick
+   * @examplePrompt Set the selected wall's height to 3 metres
+   * @examplePrompt Thicken every exterior wall to 300
+   * @examplePrompt Change this wall to a Glass Wall
+   * @examplePrompt Convert all the partitions on this floor to Brick Wall
+   *
+   * # Example
+   * ```ts
+   * // Convert every wall on storey 1 to the first listed wall type
+   * const [wallType] = await snaptrude.design.types.list("wall")
+   * const walls = await snaptrude.design.query.listWalls({ storeys: [1] })
+   * for (const wall of walls) {
+   *   await snaptrude.design.update.wall(wall, { type: wallType.id })
+   * }
+   * ```
+   */
+  public abstract wall(
+    component: ComponentHandle,
+    updates: PluginWallUpdates,
+  ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Edit a **slab's** thickness and/or overhang — the same commands the
+   * properties panel's Thickness field and Overhang slider drive. Sparse: only
+   * the fields you provide change. Undoable; the slab rebuilds and dimension
+   * lines refresh. Both values are in **engine units** (the same convention as
+   * `design.doors.setWidth`); thickness must be `> 0`, overhang is an absolute
+   * offset (negative insets the slab) and re-applying the current overhang is
+   * a no-op.
+   *
+   * Throws when the handle is not a slab, when it is locked, when the handle is
+   * gone/forged, when `overhang` is set on a slab that has no overhang (plinth /
+   * basement slabs, or overhang disabled), or when no field is provided.
+   *
+   * @param component - The slab to edit
+   * @param updates - Sparse {@linkcode PluginSlabUpdates} (at least one field)
+   * @returns the affected slab
+   *
+   * @examplePrompt Set this slab's thickness to 250mm
+   * @examplePrompt Make the floor slab 300 thick
+   * @examplePrompt Give this slab a 200 overhang
+   * @examplePrompt Remove the overhang on every slab on level 2
+   *
+   * # Example
+   * ```ts
+   * const [slab] = await snaptrude.design.query.listSlabs()
+   * await snaptrude.design.update.slab(slab, { thickness: 250, overhang: 200 })
+   * ```
+   */
+  public abstract slab(
+    component: ComponentHandle,
+    updates: PluginSlabUpdates,
+  ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Edit a **floor's** thickness — the slab-family updater for floors (shares
+   * the slab thickness command). Undoable. Thickness is in **engine units**
+   * (the `design.doors.setWidth` convention) and must be `> 0`. Floors have no
+   * Overhang control, so `overhang` is rejected with `PRECONDITION_FAILED`.
+   *
+   * Throws when the handle is not a floor, when it is locked, when the handle
+   * is gone/forged, when `overhang` is provided, or when no field is provided.
+   *
+   * @param component - The floor to edit
+   * @param updates - {@linkcode PluginSlabUpdates} (a `thickness`)
+   * @returns the affected floor
+   *
+   * @examplePrompt Make this floor 200mm thick
+   * @examplePrompt Set every floor to a 250 thickness
+   * @examplePrompt Thicken the ground floor slab to 300
+   *
+   * # Example
+   * ```ts
+   * const [floor] = await snaptrude.design.query.listFloors()
+   * await snaptrude.design.update.floor(floor, { thickness: 200 })
+   * ```
+   */
+  public abstract floor(
+    component: ComponentHandle,
+    updates: PluginSlabUpdates,
+  ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Edit a **roof's** thickness and/or overhang — the same commands the roof
+   * panel's Thickness field and Overhang slider drive (shares the slab-family
+   * machinery). Sparse: only the fields you provide change. Undoable. Both
+   * values are in **engine units** (the `design.doors.setWidth` convention);
+   * thickness must be `> 0`, overhang is an absolute offset (negative insets
+   * the roof) and re-applying the current overhang is a no-op.
+   *
+   * Throws when the handle is not a roof, when it is locked, when the handle is
+   * gone/forged, when `overhang` is set on a roof whose overhang is disabled,
+   * or when no field is provided.
+   *
+   * @param component - The roof to edit
+   * @param updates - Sparse {@linkcode PluginSlabUpdates} (at least one field)
+   * @returns the affected roof
+   *
+   * @examplePrompt Make this roof 300mm thick
+   * @examplePrompt Set the roof slab thickness to 250
+   * @examplePrompt Give the roof a 600 overhang
+   * @examplePrompt Pull the roof overhang back to 0
+   *
+   * # Example
+   * ```ts
+   * const [roof] = await snaptrude.design.query.listRoofs()
+   * await snaptrude.design.update.roof(roof, { overhang: 600 })
+   * ```
+   */
+  public abstract roof(
+    component: ComponentHandle,
+    updates: PluginSlabUpdates,
+  ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Edit a **ceiling's** thickness — the slab-family updater for ceilings
+   * (shares the slab thickness command). Undoable. Thickness is in **engine
+   * units** (the `design.doors.setWidth` convention) and must be `> 0`.
+   * Ceilings have no Overhang control, so `overhang` is rejected with
+   * `PRECONDITION_FAILED`.
+   *
+   * Throws when the handle is not a ceiling, when it is locked, when the handle
+   * is gone/forged, when `overhang` is provided, or when no field is provided.
+   *
+   * @param component - The ceiling to edit
+   * @param updates - {@linkcode PluginSlabUpdates} (a `thickness`)
+   * @returns the affected ceiling
+   *
+   * @examplePrompt Make this ceiling 150mm thick
+   * @examplePrompt Set every ceiling to a 100 thickness
+   * @examplePrompt Thicken the ceiling to 200
+   *
+   * # Example
+   * ```ts
+   * const [ceiling] = await snaptrude.design.query.listCeilings()
+   * await snaptrude.design.update.ceiling(ceiling, { thickness: 150 })
+   * ```
+   */
+  public abstract ceiling(
+    component: ComponentHandle,
+    updates: PluginSlabUpdates,
+  ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Set a component's **absolute world elevation** — moves it vertically so its
+   * base (the bounding-box bottom, world Y) lands at `elevation`. Composed over
+   * the canonical command-backed move machinery, so it is undoable and persisted
+   * exactly like dragging the element up or down; per-type invariants (e.g. a
+   * staircase's base offset) stay in sync. `elevation` is in **engine units**
+   * (the `design.doors.setWidth` convention). Re-applying the current elevation
+   * is a no-op.
+   *
+   * Throws when the component is locked or the handle is gone/forged.
+   *
+   * @param component - The component to move vertically
+   * @param elevation - Target world elevation of the component's base (engine units)
+   * @returns the affected component
+   *
+   * @examplePrompt Set this element's elevation to 3000
+   * @examplePrompt Raise this mass so its base sits at 3 metres
+   * @examplePrompt Drop the selected slab to elevation 0
+   * @examplePrompt Put this staircase's base at 3200
+   *
+   * # Example
+   * ```ts
+   * // Sit the roof slab exactly at the top of a 3m storey
+   * const [roof] = await snaptrude.design.query.listRoofs()
+   * await snaptrude.design.update.setElevation(roof, 3000)
+   * ```
+   */
+  public abstract setElevation(
+    component: ComponentHandle,
+    elevation: number,
+  ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Set a component's **base offset** — its vertical distance above its own
+   * storey's base level. Moves the component so its base lands at
+   * `storeyBase + offset`, composed over the same command-backed move machinery
+   * as {@linkcode setElevation} (undoable, persisted, per-type invariants kept
+   * in sync). Use this instead of {@linkcode setElevation} when you want an
+   * offset relative to the storey rather than an absolute world height.
+   * `offset` is in **engine units** (the `design.doors.setWidth` convention);
+   * `0` sits the base flush with the storey base. Re-applying the current
+   * offset is a no-op.
+   *
+   * Throws when the component is locked, when it has no storey to offset from,
+   * or when the handle is gone/forged.
+   *
+   * @param component - The component to offset
+   * @param offset - Distance of the component's base above its storey base (engine units)
+   * @returns the affected component
+   *
+   * @examplePrompt Lift this element 300 above its floor
+   * @examplePrompt Set this staircase's base offset to 0
+   * @examplePrompt Raise the selected mass 500 off the storey base
+   * @examplePrompt Offset this slab 150 above the floor level
+   *
+   * # Example
+   * ```ts
+   * const [stair] = await snaptrude.design.query.listStaircases()
+   * await snaptrude.design.update.setBaseOffset(stair, 0)
+   * ```
+   */
+  public abstract setBaseOffset(
+    component: ComponentHandle,
+    offset: number,
+  ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Reassign one or more components to another **storey** — the same operation
+   * as the properties panel's Story dropdown, and it works across element kinds
+   * exactly like the panel (walls, slabs, masses, furniture, staircases, ...).
+   * Each component is moved vertically to the target storey's level (per-kind
+   * placement rules — e.g. a slab sits at the storey base, a wall on it) and
+   * its storey assignment, children, and dimension lines update together as
+   * **one undoable operation**.
+   *
+   * `storey` is an integer storey number in the `entity.story` convention
+   * (`1` is the ground storey, `-1` the first basement; `0` does not exist)
+   * and **must already exist** in each component's building — this call never
+   * creates storeys (use `core.storeys.create` first). Components already on
+   * the target storey are skipped (no-op) and are not echoed in `affected`.
+   *
+   * Throws when the target storey does not exist, when any component is
+   * locked, or when a handle is gone/forged — all before anything moves
+   * (all-or-nothing).
+   *
+   * @param components - The components to reassign
+   * @param storey - Target storey number (integer, `entity.story` convention)
+   * @returns the components actually reassigned
+   *
+   * @examplePrompt Move this sofa to storey 2
+   * @examplePrompt Put the selected walls on the first basement level
+   * @examplePrompt Send everything on this storey up one level
+   * @examplePrompt Reassign these slabs to storey 3
+   *
+   * # Example
+   * ```ts
+   * // Move the current selection up to storey 2
+   * const selection = await snaptrude.design.selection.get()
+   * const { affected } = await snaptrude.design.update.setStorey(selection, 2)
+   * console.log("moved", affected.length, "components")
+   * ```
+   */
+  public abstract setStorey(
+    components: ComponentHandle[],
+    storey: number,
+  ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Update an existing parametric buildable envelope — regenerate the zoning
+   * volume from a revised site polygon, setbacks, vertical cap, or FAR and
+   * lot-coverage limits, keeping the same envelope id. Canonical home of the
+   * update formerly at `entity.buildableEnvelope.update` (now deprecated).
+   *
+   * @param buildableEnvelopeId - Existing envelope ID to update; non-empty and
+   *   must match an existing envelope on the canvas.
+   * @param sitePolygon - Site polygon vertices in `lengthUnit`; minimum 3 vertices.
+   * @param lengthUnit - Unit used by all length fields (`"ft" | "m"`).
+   * @param setbacks - Setback profile, ground tier first; minimum 1 tier.
+   * @param verticalCap - Maximum height or floor count.
+   * @param floorToFloor - Required floor-to-floor height in `lengthUnit`.
+   * @param farRatio - Optional FAR value, positive when provided.
+   * @param lotCoverageMaxPct - Optional lot coverage cap, `0..100`.
+   * @returns A {@linkcode PluginBuildableEnvelopeUpdateResult} with the
+   *   `buildableEnvelopeId` of the updated envelope.
+   * @throws If validation fails, the envelope does not exist, or generation
+   *   produces no renderable geometry.
+   *
+   * @examplePrompt Change the envelope's height limit to 175 feet
+   * @examplePrompt Update the setbacks on the buildable envelope
+   * @examplePrompt Regenerate the zoning envelope with a new site boundary
+   * @examplePrompt Increase the FAR on the buildable volume
+   *
+   * # Example
+   * ```ts
+   * const { buildableEnvelopeId } = await snaptrude.design.update.buildableEnvelope(
+   *   existingId,
+   *   [
+   *     { x: 0, z: 0 },
+   *     { x: 100, z: 0 },
+   *     { x: 100, z: 80 },
+   *     { x: 0, z: 80 },
+   *   ],
+   *   "ft",
+   *   [{ aboveHeight: 0, front: 10, side: 5, rear: 10 }],
+   *   { kind: "max_height", maxHeight: 175 },
+   *   12,
+   * )
+   * ```
+   */
+  public abstract buildableEnvelope(
+    buildableEnvelopeId: string,
+    sitePolygon: PluginBuildableEnvelopePolygonVertex[],
+    lengthUnit: "ft" | "m",
+    setbacks: PluginBuildableEnvelopeSetbackTier[],
+    verticalCap: PluginBuildableEnvelopeVerticalCap,
+    floorToFloor: number,
+    farRatio?: number,
+    lotCoverageMaxPct?: number,
+  ): PluginApiReturn<PluginBuildableEnvelopeUpdateResult>
 }

package/src/api/design/visibility.ts

@@ -0,0 +1,109 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import { ComponentHandle } from "../../handles"
+import { PluginDesignChangeResult } from "./lock"
+
+/**
+ * `snaptrude.design.visibility.*` — hide, isolate, and reveal scene entities.
+ *
+ * Visibility is a per-component user flag (the same one the "Hide" / "Isolate" /
+ * "Show All" toolbar and right-click actions toggle). Every method here commits
+ * an undoable command and echoes the affected entities as
+ * {@linkcode PluginDesignChangeResult}.
+ *
+ * Accessed via `snaptrude.design.visibility`.
+ */
+export abstract class PluginDesignVisibilityApi {
+  constructor() {}
+
+  /**
+   * Hide entities from the viewport — the same as the "Hide" action. Undoable.
+   * Hosted door/window/void children ride along with their wall. Already-hidden
+   * entities stay hidden.
+   *
+   * @param components Entities to hide
+   * @returns The affected entities (echoing the input handles)
+   *
+   * @examplePrompt Hide the selected walls
+   * @examplePrompt Conceal these masses so I can see behind them
+   * @examplePrompt Hide every column on this floor
+   * @examplePrompt Make this furniture disappear from view
+   *
+   * # Example
+   * ```ts
+   * const walls = await snaptrude.design.query.listWalls({ storeys: [1] })
+   * const { affected } = await snaptrude.design.visibility.hide(walls)
+   * ```
+   */
+  public abstract hide(
+    components: ComponentHandle[],
+  ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Isolate entities — hide everything else so only the given entities remain
+   * visible (the "Isolate" / solo action). Undoable. Reverse it with
+   * {@linkcode PluginDesignVisibilityApi.showAll}.
+   *
+   * @param components Entities to keep visible; everything else is hidden
+   * @returns The isolated entities (echoing the input handles)
+   *
+   * @examplePrompt Isolate the selected room so I can focus on it
+   * @examplePrompt Show only these walls and hide the rest
+   * @examplePrompt Solo this mass
+   * @examplePrompt Hide everything except the staircase
+   *
+   * # Example
+   * ```ts
+   * const [room] = await snaptrude.design.selection.get()
+   * await snaptrude.design.visibility.isolate([room])
+   * ```
+   */
+  public abstract isolate(
+    components: ComponentHandle[],
+  ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Reveal everything hidden on the active story — the "Show All" action, which
+   * also exits an isolate. Undoable.
+   *
+   * @returns The entities that were made visible
+   *
+   * @examplePrompt Show everything again
+   * @examplePrompt Unhide all the hidden objects
+   * @examplePrompt Exit isolate mode
+   * @examplePrompt Reveal everything I hid earlier
+   *
+   * # Example
+   * ```ts
+   * const { affected } = await snaptrude.design.visibility.showAll()
+   * console.log(`Revealed ${affected.length} entities`)
+   * ```
+   */
+  public abstract showAll(): PluginApiReturn<PluginDesignChangeResult>
+}
+
+/**
+ * Arguments for {@linkcode PluginDesignVisibilityApi.hide}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode ComponentHandle}`[]` | Entities to hide |
+ */
+export const PluginDesignVisibilityHideArgs = z.object({
+  components: z.array(ComponentHandle),
+})
+export type PluginDesignVisibilityHideArgs = z.infer<typeof PluginDesignVisibilityHideArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignVisibilityApi.isolate}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode ComponentHandle}`[]` | Entities to keep visible |
+ */
+export const PluginDesignVisibilityIsolateArgs = z.object({
+  components: z.array(ComponentHandle),
+})
+export type PluginDesignVisibilityIsolateArgs = z.infer<
+  typeof PluginDesignVisibilityIsolateArgs
+>

package/src/api/entity/buildableEnvelope.ts

@@ -54,6 +54,8 @@ export abstract class PluginBuildableEnvelopeApi {
    *   12,
    * )
    * ```
+   *
+   * @deprecated Use `design.create.buildableEnvelope`
    */
   public abstract create(
     sitePolygon: PluginBuildableEnvelopePolygonVertex[],
@@ -106,6 +108,8 @@ export abstract class PluginBuildableEnvelopeApi {
    *   12,
    * )
    * ```
+   *
+   * @deprecated Use `design.update.buildableEnvelope`
    */
   public abstract update(
     buildableEnvelopeId: string,

package/src/api/entity/referenceLine.ts

@@ -49,6 +49,8 @@ export abstract class PluginReferenceLineApi {
    *
    * const { referenceLineIds } = await snaptrude.entity.referenceLine.createMulti(profile)
    * ```
+   *
+   * @deprecated Use `design.create.referenceLines`
    */
   public abstract createMulti(
     profile: ProfileHandle
@@ -78,6 +80,8 @@ export abstract class PluginReferenceLineApi {
    * // result.curve is an opaque CurveHandle; a dedicated curve read API for its
    * // coordinates is exposed separately via `snaptrude.core.geom.curve`.
    * ```
+   *
+   * @deprecated Use `design.query.referenceLines.get`
    */
   public abstract get(
     referenceLineId: string,
@@ -104,6 +108,8 @@ export abstract class PluginReferenceLineApi {
    * const { referenceLineIds } = await snaptrude.entity.referenceLine.getAll()
    * console.log(`Project has ${referenceLineIds.length} reference lines`)
    * ```
+   *
+   * @deprecated Use `design.query.listReferenceLines`
    */
   public abstract getAll(): PluginApiReturn<PluginReferenceLineGetAllResult>
 
@@ -125,6 +131,8 @@ export abstract class PluginReferenceLineApi {
    * ```ts
    * await snaptrude.entity.referenceLine.delete("some-ref-line-id")
    * ```
+   *
+   * @deprecated Use `design.delete.entities`
    */
   public abstract delete(
     referenceLineId: string