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

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

@@ -7,8 +7,10 @@ import {
   PluginDepartmentId,
   PluginAreaClass,
 } from "../../entity/space"
+import { PluginStaircasePreset } from "../create"
 import { PluginDesignQueryGeometryApi } from "./geometry"
 import { PluginDesignQuerySpacesApi } from "./spaces"
+import { PluginDesignQueryReferenceLinesApi } from "./referenceLines"
 
 // ---------------------------------------------------------------------------
 // Entity type vocabulary
@@ -167,6 +169,7 @@ export type PluginDesignQueryComponentsArgs = z.infer<
  * | `spaceType` | {@linkcode PluginSpaceType} | Space-type (spaces only) |
  * | `areaClass` | {@linkcode PluginAreaClass} | Area classification (spaces only) |
  * | `departmentId` | `string` | Department (masses only) |
+ * | `buildingType` | `string` | Assigned building type NAME (walls / slabs / floors / roofs / ceilings only) — the Object Properties panel's Wall/Slab/Floor/Roof/Ceiling Type dropdown value, matching the names from `design.types.list(kind)` |
  * | `isLocked` | `boolean` | Lock flag |
  * | `isHidden` | `boolean` | User-hidden flag |
  * | `isSelected` | `boolean` | Current selection state |
@@ -185,6 +188,7 @@ export const PluginEntityProperties = z
     spaceType: PluginSpaceType,
     areaClass: PluginAreaClass,
     departmentId: z.string(),
+    buildingType: z.string(),
     isLocked: z.boolean(),
     isHidden: z.boolean(),
     isSelected: z.boolean(),
@@ -200,21 +204,82 @@ export type PluginEntityProperties = z.infer<typeof PluginEntityProperties>
  * entity's type computes them (area: floors/masses/slabs/roofs/beams/columns;
  * volume: all; length: walls/beams).
  *
+ * `thickness` and `height` are the Object Properties panel's dimension reads
+ * (the same engine source `design.update.wall` / `design.update.slab` etc.
+ * write through), in engine units. `thickness`: walls (the plan thickness —
+ * present only for straight orthogonal walls, exactly when the panel shows it)
+ * and slabs/floors/roofs/ceilings (the vertical extent the panel calls
+ * Thickness). `height`: walls only.
+ *
  * | Property | Type | Description |
  * |---|---|---|
  * | `area` | `number`? | Bottom-face area |
  * | `volume` | `number`? | Solid volume |
  * | `length` | `number`? | Running length (linear elements) |
+ * | `thickness` | `number`? | Panel Thickness — walls (straight orthogonal only) and the slab family |
+ * | `height` | `number`? | Panel Height — walls only |
  * | `boundingBox` | {@linkcode BBoxComponents} | World-space AABB (always present) |
  */
 export const PluginEntityMeasurements = z.object({
   area: z.number().optional(),
   volume: z.number().optional(),
   length: z.number().optional(),
+  thickness: z.number().optional(),
+  height: z.number().optional(),
   boundingBox: BBoxComponents,
 })
 export type PluginEntityMeasurements = z.infer<typeof PluginEntityMeasurements>
 
+/**
+ * The parametric properties of a staircase — the same editable fields the
+ * staircase properties panel exposes. Returned by
+ * {@linkcode PluginDesignQueryApi.getStaircaseParams}; the write side is
+ * `design.update.staircase`. Engine internals (block schema, min well size,
+ * square-well padding) are deliberately excluded.
+ *
+ * All dimensions are in **engine units** (the same convention as
+ * `design.doors.getWidth`); `steps` is a unitless count. The invariant
+ * `staircaseHeight = steps × riser` is governed by the two lock booleans — see
+ * `design.update.staircase`. Type-specific fields (`wellSize`, `landingWidth`,
+ * `flightStartDistAfterTurn`) are present only when the preset uses them.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `staircaseType` | {@linkcode PluginStaircasePreset} | Base staircase type |
+ * | `staircasePreset` | {@linkcode PluginStaircasePreset} | Named parametric preset |
+ * | `staircaseHeight` | `number` | Total rise (engine units) |
+ * | `steps` | `number` | Step count (unitless) |
+ * | `riser` | `number` | Riser height (engine units) |
+ * | `tread` | `number` | Tread depth (engine units) |
+ * | `width` | `number` | Flight width (engine units) |
+ * | `depth` | `number` | Slab/waist thickness (engine units) |
+ * | `wellSize` | `number`? | Stairwell gap (dogLegged / openWell / square) |
+ * | `landingWidth` | `number`? | Landing depth (straight / dogLegged) |
+ * | `flightStartDistAfterTurn` | `number`? | Flight offset after a turn (dogLegged / lShaped / square) |
+ * | `baseOffset` | `number` | Vertical offset from the storey base (engine units) |
+ * | `isStoreyHeightUnlocked` | `boolean` | When `false`, height is tied to the storey height |
+ * | `isStaircaseHeightUnlocked` | `boolean` | When `false`, height recomputes from steps × riser |
+ * | `storey` | `number` | Storey/floor level the staircase sits on |
+ */
+export const PluginStaircaseParams = z.object({
+  staircaseType: PluginStaircasePreset,
+  staircasePreset: PluginStaircasePreset,
+  staircaseHeight: z.number(),
+  steps: z.number(),
+  riser: z.number(),
+  tread: z.number(),
+  width: z.number(),
+  depth: z.number(),
+  wellSize: z.number().optional(),
+  landingWidth: z.number().optional(),
+  flightStartDistAfterTurn: z.number().optional(),
+  baseOffset: z.number(),
+  isStoreyHeightUnlocked: z.boolean(),
+  isStaircaseHeightUnlocked: z.boolean(),
+  storey: z.number(),
+})
+export type PluginStaircaseParams = z.infer<typeof PluginStaircaseParams>
+
 // ---------------------------------------------------------------------------
 // The query API
 // ---------------------------------------------------------------------------
@@ -237,6 +302,8 @@ export abstract class PluginDesignQueryApi {
   public abstract geometry: PluginDesignQueryGeometryApi
   /** Space-specific reads (footprint, …). See {@linkcode PluginDesignQuerySpacesApi}. */
   public abstract spaces: PluginDesignQuerySpacesApi
+  /** Reference-line-specific reads. See {@linkcode PluginDesignQueryReferenceLinesApi}. */
+  public abstract referenceLines: PluginDesignQueryReferenceLinesApi
 
   constructor() {}
 
@@ -704,9 +771,7 @@ export abstract class PluginDesignQueryApi {
    * }
    * ```
    */
-  public abstract exists(
-    id: ComponentHandle,
-  ): PluginApiReturn<boolean>
+  public abstract exists(id: ComponentHandle): PluginApiReturn<boolean>
 
   /**
    * Get the kind of BIM entity a handle refers to — wall, door, space, slab,
@@ -760,9 +825,7 @@ export abstract class PluginDesignQueryApi {
    * }
    * ```
    */
-  public abstract getLabel(
-    component: ComponentHandle,
-  ): PluginApiReturn<string>
+  public abstract getLabel(component: ComponentHandle): PluginApiReturn<string>
 
   /**
    * Get a serializable, persistable reference to an entity. Under the all-handle
@@ -846,13 +909,16 @@ export abstract class PluginDesignQueryApi {
    * Read an entity's common properties as a {@linkcode PluginEntityProperties}
    * record (only applicable fields are present). For spaces/masses this includes
    * `adjacency` — the per-entity adjacency read (bulk form:
-   * `program.adjacency.getMatrix`).
+   * `program.adjacency.getMatrix`). For walls and the slab family (slab / floor
+   * / roof / ceiling) this includes `buildingType` — the assigned building type
+   * NAME the panel's type dropdown shows, matching `design.types.list(kind)`.
    *
    * @param component - the entity's {@linkcode ComponentHandle}
    * @returns the property record
    *
    * @examplePrompt Show me all the details of the selected object
    * @examplePrompt What storey is this wall on?
+   * @examplePrompt Which wall type is assigned to this wall?
    * @examplePrompt Which department does this room belong to?
    * @examplePrompt Is this element locked or hidden?
    * @examplePrompt Get the adjacencies of this space
@@ -882,11 +948,20 @@ export abstract class PluginDesignQueryApi {
    * Measure an entity — read its area, volume, and/or running length (whichever
    * its type supports) together with its world-space bounding box in one call.
    *
+   * For walls and the slab family this also carries the Object Properties
+   * panel's dimension reads in engine units: `thickness` (walls — straight
+   * orthogonal only, exactly when the panel shows it; slabs / floors / roofs /
+   * ceilings — the vertical extent the panel calls Thickness) and `height`
+   * (walls). These are the read side of `design.update.wall` /
+   * `design.update.slab` / `.floor` / `.roof` / `.ceiling`.
+   *
    * @param component - the entity's {@linkcode ComponentHandle}
    * @returns a {@linkcode PluginEntityMeasurements}, or `null` if the entity is gone
    *
    * @examplePrompt What's the area of this room?
    * @examplePrompt How long is the selected wall?
+   * @examplePrompt How thick is this wall?
+   * @examplePrompt Get the thickness of the slab on level 2
    * @examplePrompt Get the volume of this mass
    * @examplePrompt Give me the dimensions of the selected element
    * @examplePrompt What's the floor area of the kitchen?
@@ -896,12 +971,47 @@ export abstract class PluginDesignQueryApi {
    * const [space] = await snaptrude.design.query.listSpaces()
    * const m = await snaptrude.design.query.measure(space)
    * console.log(m?.area, m?.volume)
+   *
+   * // wall dimensions — the panel's Thickness / Height, in engine units
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const wm = await snaptrude.design.query.measure(wall)
+   * console.log(wm?.thickness, wm?.height)
    * ```
    */
   public abstract measure(
     component: ComponentHandle,
   ): PluginApiReturn<PluginEntityMeasurements | null>
 
+  /**
+   * Read a staircase's parametric properties — its preset, dimensions, step
+   * count, base offset, and height-lock state — as a
+   * {@linkcode PluginStaircaseParams} record. The paired write is
+   * `design.update.staircase`.
+   *
+   * All dimensions are in **engine units** (the same convention as
+   * `design.doors.getWidth`); `steps` is a unitless count. A read — never
+   * throws: returns `null` for a handle that is not a staircase or no longer
+   * resolves.
+   *
+   * @param staircase - the staircase's {@linkcode ComponentHandle}
+   * @returns the {@linkcode PluginStaircaseParams} record, or `null`
+   *
+   * @examplePrompt What's the riser height of this staircase?
+   * @examplePrompt How many steps does the selected stair have?
+   * @examplePrompt Show me the tread and width of this staircase
+   * @examplePrompt Read all the parameters of the stairs on level 1
+   *
+   * # Example
+   * ```ts
+   * const [stair] = await snaptrude.design.query.listStaircases({ isSelected: true })
+   * const params = stair ? await snaptrude.design.query.getStaircaseParams(stair) : null
+   * if (params) console.log(params.steps, params.riser, params.tread)
+   * ```
+   */
+  public abstract getStaircaseParams(
+    staircase: ComponentHandle,
+  ): PluginApiReturn<PluginStaircaseParams | null>
+
   /**
    * Get the **union** axis-aligned bounding box enclosing a set of entities.
    *
@@ -931,7 +1041,107 @@ export abstract class PluginDesignQueryApi {
   public abstract getBoundingBox(
     components: ComponentHandle[],
   ): PluginApiReturn<BBoxComponents | null>
+
+  /**
+   * Compute the plan **outline of what is built on a storey** — the union of
+   * the storey's wall (by default) footprints as polygons-with-holes. This is
+   * the footprint-from-the-built-model query: by the time slabs are needed the
+   * walls exist, and the engine's own solids (snapped, joined and mitred at
+   * creation) are the cleanest wall network available — no CAD re-tracing.
+   *
+   * Semantics: the union of wall solids is the wall *material* — a ring-shaped
+   * polygon. The **outer ring is the OUTSIDE wall face** (the slab boundary);
+   * every enclosed region — rooms AND courtyards — appears as a hole. When the
+   * largest hole is ~zero the walls don't enclose anything: the footprint
+   * reports `enclosed: false` (an open wall network), never a garbage outline.
+   * Detached buildings come back as separate footprints.
+   *
+   * A read — nothing is created. Feed a footprint's `outline` to
+   * `core.geom.create.profileFromLinePoints` → `design.create.slab` to build
+   * the floor/roof plate. Coordinates are world-space plan (x, z) in Snaptrude
+   * internal units; `areaSq` values are in squared internal units.
+   *
+   * @param options - storey / included kinds / debris filter; see
+   *   {@linkcode PluginStoreyOutlineOptions}.
+   * @returns the storey's footprints (possibly several for detached buildings)
+   *   plus pieces discarded by `minArea` (`footprints: []` when nothing matches).
+   *
+   * @examplePrompt What is the building footprint on the ground floor?
+   * @examplePrompt Create a floor slab covering the whole storey
+   * @examplePrompt Get the outline of the walls on storey 1
+   * @examplePrompt How much area do the ground-floor walls enclose?
+   *
+   * # Example
+   * ```ts
+   * const r = await snaptrude.design.query.storeyOutline({ storey: 1 })
+   * const main = r.footprints.find((f) => f.enclosed)
+   * if (main) {
+   *   const profile = await snaptrude.core.geom.create.profileFromLinePoints(
+   *     main.outline.map((p) => ({ x: p.x, y: 0, z: p.z })),
+   *   )
+   *   // → design.create.slab with the profile's contour
+   * }
+   * ```
+   */
+  public abstract storeyOutline(
+    options?: PluginStoreyOutlineOptions,
+  ): PluginApiReturn<PluginStoreyOutlineResult>
 }
 
+
+/** A point in the world-space plan (x, z) projection, Snaptrude internal units. */
+export const PluginOutlinePlanPoint = z.object({ x: z.number(), z: z.number() })
+export type PluginOutlinePlanPoint = z.infer<typeof PluginOutlinePlanPoint>
+
+/**
+ * Options for {@link PluginDesignQueryApi.storeyOutline}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storey` | `number`? | Only components on this storey (default: all storeys) |
+ * | `include` | {@link PluginEntityType}`[]`? | Component kinds to union (default `["wall"]`) |
+ * | `minArea` | `number`? | Drop union pieces below this plan area, squared internal units (default `1`) |
+ */
+export const PluginStoreyOutlineOptions = z.object({
+  storey: z.number().int().optional(),
+  include: z.array(PluginEntityType).nonempty().default(["wall"]),
+  minArea: z.number().nonnegative().default(1),
+})
+export type PluginStoreyOutlineOptions = z.input<
+  typeof PluginStoreyOutlineOptions
+>
+
+/**
+ * One connected footprint from {@link PluginDesignQueryApi.storeyOutline}.
+ * `outline` traces the OUTSIDE wall face; `holes` are the enclosed regions
+ * (rooms and courtyards). `enclosed` is `false` when the wall network does not
+ * close around any region (open C-shape) — don't slab an unenclosed outline
+ * without checking it.
+ */
+export const PluginStoreyFootprint = z.object({
+  outline: z.array(PluginOutlinePlanPoint),
+  holes: z.array(
+    z.object({
+      ring: z.array(PluginOutlinePlanPoint),
+      areaSq: z.number().nonnegative(),
+    }),
+  ),
+  areaSq: z.number().nonnegative(),
+  enclosed: z.boolean(),
+})
+export type PluginStoreyFootprint = z.infer<typeof PluginStoreyFootprint>
+
+/** Result of {@link PluginDesignQueryApi.storeyOutline}. */
+export const PluginStoreyOutlineResult = z.object({
+  footprints: z.array(PluginStoreyFootprint),
+  discarded: z.array(
+    z.object({ areaSq: z.number().nonnegative(), reason: z.string() }),
+  ),
+})
+export type PluginStoreyOutlineResult = z.infer<
+  typeof PluginStoreyOutlineResult
+>
+
 export * from "./geometry"
 export * from "./spaces"
+export * from "./referenceLines"

package/src/api/design/query/referenceLines.ts

@@ -0,0 +1,52 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import {
+  PluginReferenceLineGetProperty,
+  PluginReferenceLineGetResult,
+} from "../../entity/referenceLine"
+
+/**
+ * `design.query.referenceLines.*` — reference-line-specific reads.
+ *
+ * A **reference line** is a 2D guide line (or arc) in the scene, typically used
+ * for grid lines and alignment guides. Enumerate reference lines with
+ * `design.query.listReferenceLines`; read an individual line's properties here.
+ * This is the canonical home of the read formerly at `entity.referenceLine.get`
+ * (now deprecated).
+ *
+ * Accessed via `snaptrude.design.query.referenceLines`.
+ */
+export abstract class PluginDesignQueryReferenceLinesApi {
+  constructor() {}
+
+  /**
+   * Get properties of a reference line by its ID.
+   *
+   * Only the properties listed in `properties` are returned — unlisted
+   * properties will be `undefined` in the result.
+   *
+   * @param referenceLineId - The unique reference line ID
+   * @param properties - Array of property names to retrieve. See
+   *   {@linkcode PluginReferenceLineGetProperty}.
+   * @returns A partial {@linkcode PluginReferenceLineGetResult} containing only the
+   *   requested properties
+   * @throws If the reference line does not exist
+   *
+   * @examplePrompt Get the curve geometry of this reference line
+   * @examplePrompt Where does this grid line run?
+   * @examplePrompt Read the geometry of a guide line by its id
+   * @examplePrompt Look up the curve of the selected reference line
+   *
+   * # Example
+   * ```ts
+   * const [refLine] = await snaptrude.design.query.listReferenceLines()
+   * const result = await snaptrude.design.query.referenceLines.get(refLine, ["curve"])
+   * // result.curve is an opaque CurveHandle; read its coordinates via
+   * // `snaptrude.core.geom.curve`.
+   * ```
+   */
+  public abstract get(
+    referenceLineId: string,
+    properties: z.infer<typeof PluginReferenceLineGetProperty>[],
+  ): PluginApiReturn<PluginReferenceLineGetResult>
+}

package/src/api/design/query/spaces.ts

@@ -75,6 +75,55 @@ export abstract class PluginDesignQuerySpacesApi {
   public abstract getFootprint(
     space: ComponentHandle,
   ): PluginApiReturn<ContourHandle | null>
+
+  /**
+   * Get the **enclosure** of a space — the floor and ceiling that cap it, the
+   * bounding walls around it (with each wall's door/window openings), and the
+   * neighbouring spaces it shares a boundary with.
+   *
+   * **Geometric v1 — best effort.** The engine has no persisted space→surface
+   * topology, so this read is derived purely from *plan geometry*: the space
+   * footprint is matched against the plan footprints/baselines of the slabs and
+   * walls on the same storey. Consequences a caller must account for:
+   *
+   * - `faceIndices` is **always `[]`**. The triangle→B-rep-face provenance that
+   *   would populate it is a separate engine capability that does not exist yet;
+   *   read a surface's full geometry via
+   *   {@linkcode PluginDesignQueryGeometryApi.getBrep} on its `component` instead.
+   * - After heavy edits (move / stretch / boolean) or on imported models the plan
+   *   match can miss or mis-attribute a surface — treat the result as advisory,
+   *   not authoritative.
+   * - `adjacentSpaces` comes from the same adjacency data as
+   *   {@linkcode PluginProgramAdjacencyApi.getMatrix} (so the two agree on which
+   *   spaces neighbour). `sharedEdgeLength` is `0` because that data exposes no
+   *   edge length, and `sharedSurface` is the common boundary wall only when one
+   *   is found geometrically (else `null`).
+   *
+   * Read-only; never mutates the model.
+   *
+   * @param space - The space (room mass) to read
+   * @returns the {@linkcode PluginSpaceEnclosure}, or `null` when `space` is not a
+   *   space (room mass) or has no extractable plan footprint
+   *
+   * @examplePrompt What walls, floor and ceiling enclose this room?
+   * @examplePrompt Which of this room's walls are external?
+   * @examplePrompt List the doors and windows around the selected space
+   * @examplePrompt Which spaces are adjacent to this room, and through which wall?
+   *
+   * # Example
+   * ```ts
+   * const [space] = await snaptrude.design.query.listSpaces()
+   * const enclosure = await snaptrude.design.query.spaces.getEnclosure(space)
+   * if (enclosure) {
+   *   const walls = enclosure.surfaces.filter((s) => s.role === "wall")
+   *   const external = walls.filter((s) => s.isExternal)
+   *   console.log(`${walls.length} walls, ${external.length} external`)
+   * }
+   * ```
+   */
+  public abstract getEnclosure(
+    space: ComponentHandle,
+  ): PluginApiReturn<PluginSpaceEnclosure | null>
 }
 
 /**
@@ -130,3 +179,97 @@ export const PluginDesignQuerySpacesGetResult = PluginSpaceGetResult.omit({
 export type PluginDesignQuerySpacesGetResult = z.infer<
   typeof PluginDesignQuerySpacesGetResult
 >
+
+/**
+ * Arguments for {@linkcode PluginDesignQuerySpacesApi.getEnclosure}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `space` | {@linkcode ComponentHandle} | The space (room mass) to read |
+ */
+export const PluginDesignQuerySpacesGetEnclosureArgs = z.object({
+  space: ComponentHandle,
+})
+export type PluginDesignQuerySpacesGetEnclosureArgs = z.infer<
+  typeof PluginDesignQuerySpacesGetEnclosureArgs
+>
+
+/**
+ * The role a bounding surface plays in a {@linkcode PluginSpaceEnclosure}:
+ * `"floor"` (slab below), `"ceiling"` (slab/roof above), or `"wall"`.
+ */
+export const PluginEnclosureRole = z.enum(["floor", "ceiling", "wall"])
+export type PluginEnclosureRole = z.infer<typeof PluginEnclosureRole>
+
+/** The kind of opening hosted in a bounding wall. */
+export const PluginEnclosureOpeningKind = z.enum(["door", "window", "void"])
+export type PluginEnclosureOpeningKind = z.infer<
+  typeof PluginEnclosureOpeningKind
+>
+
+/**
+ * One opening (door / window / void) in a bounding wall.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `kind` | {@linkcode PluginEnclosureOpeningKind} | `"door"`, `"window"`, or `"void"` |
+ * | `component` | {@linkcode ComponentHandle} | The opening entity |
+ */
+export const PluginEnclosureOpening = z.object({
+  kind: PluginEnclosureOpeningKind,
+  component: ComponentHandle,
+})
+export type PluginEnclosureOpening = z.infer<typeof PluginEnclosureOpening>
+
+/**
+ * One bounding surface of a space's enclosure.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `role` | {@linkcode PluginEnclosureRole} | `"floor"`, `"ceiling"`, or `"wall"` |
+ * | `component` | {@linkcode ComponentHandle} | The wall / slab / roof entity |
+ * | `faceIndices` | `number[]` | B-rep face indices facing the space. **Always `[]` in geometric v1** (no triangle→face provenance yet) |
+ * | `isExternal` | `boolean` | No space on the other side — for a wall, no other room bounds it; for a floor/ceiling, no room caps the storey below/above |
+ * | `openings` | {@linkcode PluginEnclosureOpening}`[]` | Doors/windows/voids in the surface (walls only; `[]` for floor/ceiling in v1) |
+ */
+export const PluginEnclosureSurface = z.object({
+  role: PluginEnclosureRole,
+  component: ComponentHandle,
+  faceIndices: z.array(z.number()),
+  isExternal: z.boolean(),
+  openings: z.array(PluginEnclosureOpening),
+})
+export type PluginEnclosureSurface = z.infer<typeof PluginEnclosureSurface>
+
+/**
+ * A space that neighbours the queried space.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `space` | {@linkcode ComponentHandle} | The neighbouring space |
+ * | `sharedSurface` | {@linkcode ComponentHandle}` \| null` | The common boundary wall when one is found geometrically, else `null` (e.g. an open-plan or non-physical adjacency) |
+ * | `sharedEdgeLength` | `number` | Plan-unit length of the shared boundary — **always `0` in geometric v1** (the adjacency data exposes no edge length) |
+ */
+export const PluginAdjacentSpace = z.object({
+  space: ComponentHandle,
+  sharedSurface: ComponentHandle.nullable(),
+  sharedEdgeLength: z.number(),
+})
+export type PluginAdjacentSpace = z.infer<typeof PluginAdjacentSpace>
+
+/**
+ * Result of {@linkcode PluginDesignQuerySpacesApi.getEnclosure} — the geometric
+ * v1 enclosure of a space.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `space` | {@linkcode ComponentHandle} | The queried space |
+ * | `surfaces` | {@linkcode PluginEnclosureSurface}`[]` | Floor + ceiling + bounding walls, as a flat list (any of the three may be absent when no plan match is found) |
+ * | `adjacentSpaces` | {@linkcode PluginAdjacentSpace}`[]` | Neighbouring spaces from the adjacency data (`[]` when adjacency was never computed) |
+ */
+export const PluginSpaceEnclosure = z.object({
+  space: ComponentHandle,
+  surfaces: z.array(PluginEnclosureSurface),
+  adjacentSpaces: z.array(PluginAdjacentSpace),
+})
+export type PluginSpaceEnclosure = z.infer<typeof PluginSpaceEnclosure>

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

@@ -3,6 +3,91 @@ import { PluginApiReturn } from "../../../types"
 import { ComponentHandle } from "../../../handles"
 import { PluginDesignChangeResult } from "../lock"
 
+/**
+ * The entity kinds {@linkcode PluginDesignSelectionApi.setByFilter} can select —
+ * the union of the editor's "Filter selection" menus (Design tab + BIM tab).
+ * Tokens mirror {@linkcode PluginEntityType} where a kind exists on the query
+ * surface; the rest are selection-only kinds the query surface cannot reach
+ * (layer-backed and annotation objects).
+ *
+ * | Value | Entity (menu label) |
+ * |---|---|
+ * | `"wall"` | Wall |
+ * | `"slab"` | Floor slab |
+ * | `"floor"` | Flooring |
+ * | `"door"` | Door |
+ * | `"window"` | Window |
+ * | `"beam"` | Beam |
+ * | `"column"` | Column |
+ * | `"ceiling"` | Ceiling |
+ * | `"roof"` | Roof |
+ * | `"staircase"` | Staircase |
+ * | `"furniture"` | Furniture |
+ * | `"pergola"` | Pergola |
+ * | `"sunshade"` | Sunshade |
+ * | `"referenceLine"` | Reference line |
+ * | `"space"` | Space (room mass) |
+ * | `"site"` | Site |
+ * | `"terrain"` | Terrain |
+ * | `"cad"` | CAD import |
+ * | `"pdf"` | PDF import |
+ * | `"image"` | Image import |
+ * | `"dimensionLine"` | Dimension line |
+ * | `"model3d"` | Imported 3D model |
+ * | `"neighborhoodBuilding"` | Neighborhood building |
+ * | `"programBlock"` | Program block (department mass) |
+ */
+export const PluginSelectionEntityType = z.enum([
+  "wall",
+  "slab",
+  "floor",
+  "door",
+  "window",
+  "beam",
+  "column",
+  "ceiling",
+  "roof",
+  "staircase",
+  "furniture",
+  "pergola",
+  "sunshade",
+  "referenceLine",
+  "space",
+  "site",
+  "terrain",
+  "cad",
+  "pdf",
+  "image",
+  "dimensionLine",
+  "model3d",
+  "neighborhoodBuilding",
+  "programBlock",
+])
+export type PluginSelectionEntityType = z.infer<typeof PluginSelectionEntityType>
+
+/**
+ * The filter for {@linkcode PluginDesignSelectionApi.setByFilter}. At least one
+ * field must be non-empty (to empty the selection use
+ * {@linkcode PluginDesignSelectionApi.clear}). Fields **AND**-combine; values
+ * within a field **OR**-combine — `{ storeys: [2], types: ["furniture"] }`
+ * selects only the furniture on storey 2.
+ *
+ * | Field | Type | Selects entities where |
+ * |---|---|---|
+ * | `storeys` | `number[]` | storey/floor level ∈ `storeys` (negative = basement) |
+ * | `types` | {@linkcode PluginSelectionEntityType}`[]` | entity kind ∈ `types` |
+ */
+export const PluginSelectionFilter = z
+  .object({
+    storeys: z.array(z.number()).optional(),
+    types: z.array(PluginSelectionEntityType).optional(),
+  })
+  .refine((f) => (f.storeys?.length ?? 0) + (f.types?.length ?? 0) > 0, {
+    message:
+      "PluginSelectionFilter requires at least one non-empty field (storeys or types); use design.selection.clear() to deselect everything",
+  })
+export type PluginSelectionFilter = z.infer<typeof PluginSelectionFilter>
+
 /**
  * `snaptrude.design.selection` — read and mutate the current scene selection.
  *
@@ -123,6 +208,50 @@ export abstract class PluginDesignSelectionApi {
    * ```
    */
   public abstract clear(): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Replace the selection with every visible entity of the active building that
+   * matches the filter — the programmatic equivalent of the editor's
+   * **Story selection** (`storeys`) and **Filter selection** (`types`) menus
+   * under the select tool, including their combination (fields AND, values
+   * within a field OR). Reaches selection-only kinds the query surface cannot
+   * (sites, terrain, CAD/PDF/image imports, dimension lines, 3D models,
+   * neighborhood buildings) and selects whole groups the way the editor does.
+   *
+   * This is a one-shot bulk select, not a persistent mode: the user's next
+   * canvas click resets the underlying filter state (the selection it made
+   * stays until changed). Results honor the ambient view — active building,
+   * hidden objects/buckets, and in 2D the active storey.
+   *
+   * @param filter Which entities to select — {@linkcode PluginSelectionFilter};
+   *   at least one field must be non-empty
+   * @returns The resulting selection snapshot
+   *
+   * @examplePrompt Select everything on storey 2
+   * @examplePrompt Select all the walls and doors
+   * @examplePrompt Story selection: select the ground floor and first floor
+   * @examplePrompt Filter selection: select all furniture in the model
+   * @examplePrompt Select only the furniture on the second storey
+   * @examplePrompt Select all the spaces so I can recolor them
+   *
+   * # Example
+   * ```ts
+   * // "Story selection": everything on storeys 1 and 2
+   * await snaptrude.design.selection.setByFilter({ storeys: [1, 2] })
+   *
+   * // "Filter selection": all walls and doors
+   * await snaptrude.design.selection.setByFilter({ types: ["wall", "door"] })
+   *
+   * // Combined: only the furniture on storey 2
+   * const { affected } = await snaptrude.design.selection.setByFilter({
+   *   storeys: [2],
+   *   types: ["furniture"],
+   * })
+   * ```
+   */
+  public abstract setByFilter(
+    filter: PluginSelectionFilter
+  ): PluginApiReturn<PluginDesignChangeResult>
 }
 
 /**