@snaptrude/plugin-core 0.9.16 → 0.9.18-edgesetbacks-20261021.1

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

@@ -1,1226 +1,1236 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../../types"
-import { ComponentHandle, BBoxComponents } from "../../../handles"
-import type { MassParametersRecord } from "../../../massParameters"
-import {
-  PluginSpaceType,
-  PluginMassType,
-  PluginDepartmentId,
-  PluginAreaClass,
-} from "../../entity/space"
-import { PluginStaircasePreset } from "../create"
-import { PluginDesignQueryGeometryApi } from "./geometry"
-import { PluginDesignQuerySpacesApi } from "./spaces"
-import { PluginDesignQueryReferenceLinesApi } from "./referenceLines"
-import { PluginDesignQueryGridsApi } from "./grids"
-
-// ---------------------------------------------------------------------------
-// Entity type vocabulary
-// ---------------------------------------------------------------------------
-
-/**
- * The kind of a BIM entity — the discovery/filter vocabulary for the whole
- * `design.query.*` surface. Values are clean `lowerCamel` tokens; the host maps
- * each to the engine's internal type (whose raw strings are case-inconsistent —
- * `"roof"`/`"slab"` lowercase, `"Wall"`/`"Door"` PascalCase — never surfaced here).
- *
- * | Value | Entity |
- * |---|---|
- * | `"wall"` | Wall |
- * | `"space"` | Space (a room mass) |
- * | `"mass"` | Generic mass (non-room) |
- * | `"door"` | Door |
- * | `"window"` | Window |
- * | `"floor"` | Floor |
- * | `"slab"` | Slab |
- * | `"roof"` | Roof |
- * | `"column"` | Column |
- * | `"beam"` | Beam |
- * | `"ceiling"` | Ceiling |
- * | `"staircase"` | Staircase |
- * | `"furniture"` | Furniture |
- * | `"referenceLine"` | Reference line |
- * | `"curtainWall"` | Parametric curtain wall |
- * | `"mullion"` | Curtain-wall mullion |
- * | `"panel"` | Curtain-wall panel |
- * | `"parametricComponent"` | A placed parametric family instance (native or Revit-imported). Its geometry is rebuilt from `design.family` parameters, so read and drive it through `design.family.getParameters` / `setParameters` rather than editing its meshes. |
- * | `"grid"` | Structural grid group |
- */
-export const PluginEntityType = z.enum([
-  "wall",
-  "space",
-  "mass",
-  "door",
-  "window",
-  "floor",
-  "slab",
-  "roof",
-  "column",
-  "beam",
-  "ceiling",
-  "staircase",
-  "furniture",
-  "referenceLine",
-  "curtainWall",
-  "mullion",
-  "panel",
-  "parametricComponent",
-  "grid",
-])
-export type PluginEntityType = z.infer<typeof PluginEntityType>
-
-// ---------------------------------------------------------------------------
-// The shared filter — one options object, every list* method
-// ---------------------------------------------------------------------------
-
-/**
- * `EntityFilterOptions` — the **single filter** shared by every `design.query.list*`
- * method, so filtering is identical across all BIM object types. Every field is
- * optional and **AND-combined**: a component must satisfy all provided fields.
- * Plural fields are arrays (match any of); singular fields are scalars. A field
- * that names a type-specific dimension (`massTypes`/`spaceTypes`/`departmentId`)
- * excludes components that lack that dimension.
- *
- * | Field | Type | Keeps components where |
- * |---|---|---|
- * | `types` | {@linkcode PluginEntityType}`[]` | entity kind ∈ `types` (ignored by per-type `list*` — the method fixes the kind) |
- * | `storeys` | `number[]` | storey/floor level ∈ `storeys` (negative = basement) |
- * | `buildingIds` | `string[]` | building ∈ `buildingIds` |
- * | `structureIds` | `string[]` | structure ∈ `structureIds` |
- * | `label` | `string` | label (`room_type` ?? mesh label) === `label` |
- * | `massTypes` | {@linkcode PluginMassType}`[]` | mass-type ∈ (masses only) |
- * | `spaceTypes` | {@linkcode PluginSpaceType}`[]` | space-type ∈ (spaces only) |
- * | `departmentId` | {@linkcode PluginDepartmentId} | department === |
- * | `isSelected` | `boolean` | current selection state === |
- * | `isLocked` | `boolean` | lock flag === |
- * | `isHidden` | `boolean` | user-hidden flag === |
- * | `within` | {@linkcode BBoxComponents} | the entity's bounding box intersects the region |
- * | `overlaps` | {@linkcode ComponentHandle} | the entity's plan footprint overlaps the given space's bottom-face footprint — non-zero intersection area, so fully-inside, boundary-nested, and partially-overhanging entities all match; edge-touching with zero interior overlap does not. Exact polygon intersection (holes respected). Tested in plan — storey height is ignored; compose with `storeys` to scope a floor. Hidden entities are excluded by default — pass `isHidden` explicitly to override. The reference space itself is never returned. Throws on an unknown id. Entities without a brep footprint use their bounding-box plan rectangle. |
- * | `ids` | {@linkcode ComponentHandle}`[]` | id ∈ `ids` (restrict to a known set) |
- */
-export const PluginEntityFilter = z.object({
-  types: z.array(PluginEntityType).optional(),
-  storeys: z.array(z.number()).optional(),
-  buildingIds: z.array(z.string()).optional(),
-  structureIds: z.array(z.string()).optional(),
-  label: z.string().optional(),
-  massTypes: z.array(PluginMassType).optional(),
-  spaceTypes: z.array(PluginSpaceType).optional(),
-  departmentId: PluginDepartmentId.optional(),
-  isSelected: z.boolean().optional(),
-  isLocked: z.boolean().optional(),
-  isHidden: z.boolean().optional(),
-  within: BBoxComponents.optional(),
-  overlaps: ComponentHandle.optional(),
-  ids: z.array(ComponentHandle).optional(),
-})
-export type PluginEntityFilter = z.infer<typeof PluginEntityFilter>
-
-/**
- * Arguments for {@linkcode PluginDesignQueryApi.listByType} — a required entity
- * `type` plus every {@linkcode PluginEntityFilter} field.
- */
-export const PluginDesignQueryListByTypeArgs = PluginEntityFilter.extend({
-  type: PluginEntityType,
-})
-export type PluginDesignQueryListByTypeArgs = z.infer<
-  typeof PluginDesignQueryListByTypeArgs
->
-
-// ---------------------------------------------------------------------------
-// Single-entity argument shapes
-// ---------------------------------------------------------------------------
-
-/** Arguments for methods that read one entity by its {@linkcode ComponentHandle}. */
-export const PluginDesignQueryComponentArgs = z.object({
-  component: ComponentHandle,
-})
-export type PluginDesignQueryComponentArgs = z.infer<
-  typeof PluginDesignQueryComponentArgs
->
-
-/** Arguments for methods that look an entity up by id. */
-export const PluginDesignQueryIdArgs = z.object({
-  id: ComponentHandle,
-})
-export type PluginDesignQueryIdArgs = z.infer<typeof PluginDesignQueryIdArgs>
-
-/** Arguments for methods over a set of entities (e.g. the union bounding box). */
-export const PluginDesignQueryComponentsArgs = z.object({
-  components: z.array(ComponentHandle),
-})
-export type PluginDesignQueryComponentsArgs = z.infer<
-  typeof PluginDesignQueryComponentsArgs
->
-
-// ---------------------------------------------------------------------------
-// Read records
-// ---------------------------------------------------------------------------
-
-/**
- * The common property record returned by {@linkcode PluginDesignQueryApi.getProperties} —
- * a **partial** object (a field is present only when it applies to the entity).
- * Type-specific and geometry reads live on {@linkcode PluginDesignQueryApi.measure}
- * and `design.query.geometry.*`, keeping this record generic across every type.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `id` | `string` | The entity id |
- * | `type` | {@linkcode PluginEntityType} | Entity kind |
- * | `label` | `string` | `room_type` ?? mesh label ?? `""` |
- * | `storey` | `number` | Storey/floor level |
- * | `buildingId` | `string` | Owning building |
- * | `structureId` | `string` | Owning structure |
- * | `massType` | `string` | Mass-type (masses only) |
- * | `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 |
- * | `boundingBox` | {@linkcode BBoxComponents} | World-space AABB |
- * | `adjacency` | `{ spaceId: string; value: number }[]` | Adjacency relationships (spaces/masses only). `value`: `2` = Direct (required), `1` = Indirect or physical contact, `-1` = Restricted; `0` entries are filtered out. `[]` when adjacency has never been computed — see `program.adjacency.compute`. |
- */
-export const PluginEntityProperties = z
-  .object({
-    id: z.string(),
-    type: PluginEntityType,
-    label: z.string(),
-    storey: z.number(),
-    buildingId: z.string(),
-    structureId: z.string(),
-    massType: z.string(),
-    spaceType: PluginSpaceType,
-    areaClass: PluginAreaClass,
-    departmentId: z.string(),
-    buildingType: z.string(),
-    isLocked: z.boolean(),
-    isHidden: z.boolean(),
-    isSelected: z.boolean(),
-    boundingBox: BBoxComponents,
-    adjacency: z.array(z.object({ spaceId: z.string(), value: z.number() })),
-  })
-  .partial()
-export type PluginEntityProperties = z.infer<typeof PluginEntityProperties>
-
-/**
- * The multi-metric bundle returned by {@linkcode PluginDesignQueryApi.measure}.
- * `boundingBox` is always present; the numeric metrics appear only when the
- * 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
-// ---------------------------------------------------------------------------
-
-/**
- * `design.query.*` — read-only enumeration + inspection of scene-committed BIM
- * entities (all-handle model, §11). No query mutates the scene.
- *
- * Every `list*` returns a snapshot {@linkcode ComponentHandle}`[]` (`[]`, never
- * `null`) filtered by the shared {@linkcode PluginEntityFilter}; per-entity reads
- * take a {@linkcode ComponentHandle} and return primitive records / child handles
- * or `null` when the entity is gone. Resolve details of a returned handle with
- * {@linkcode PluginDesignQueryApi.getProperties} / {@linkcode PluginDesignQueryApi.measure}
- * / `design.query.geometry.*`.
- *
- * Accessed via `snaptrude.design.query`.
- */
-export abstract class PluginDesignQueryApi {
-  /** Entity-geometry reads (brep, bottom contour). See {@linkcode PluginDesignQueryGeometryApi}. */
-  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
-  /** Structural-grid-specific reads. See {@linkcode PluginDesignQueryGridsApi}. */
-  public abstract grids: PluginDesignQueryGridsApi
-
-  constructor() {}
-
-  // ── enumeration ───────────────────────────────────────────────────────────
-
-  /**
-   * List **all** BIM entities in the project matching the filter.
-   *
-   * @param filter - an optional {@linkcode PluginEntityFilter}
-   * @returns matching entities as {@linkcode ComponentHandle}`[]` (`[]` if none)
-   *
-   * @examplePrompt Show me everything in the model
-   * @examplePrompt How many objects are on the ground floor?
-   * @examplePrompt List all the doors and windows on level 2
-   * @examplePrompt What elements are currently selected?
-   * @examplePrompt Find every hidden object in the project
-   *
-   * # Example
-   * ```ts
-   * // Doors and windows on the ground storey (fields AND-combine)
-   * const doorsAndWindows = await snaptrude.design.query.listEntities({
-   *   types: ["door", "window"],
-   *   storeys: [1],
-   * })
-   *
-   * // Everything the user currently has selected
-   * const selected = await snaptrude.design.query.listEntities({ isSelected: true })
-   *
-   * // Everything inside a world-space region (axis-aligned box, Snaptrude units)
-   * const inRegion = await snaptrude.design.query.listEntities({
-   *   within: { min: { x: 0, y: 0, z: 0 }, max: { x: 10, y: 4, z: 8 } },
-   * })
-   * ```
-   */
-  public abstract listEntities(
-    filter?: PluginEntityFilter,
-  ): PluginApiReturn<ComponentHandle[]>
-
-  /**
-   * List all entities of one BIM object type — wall, door, slab, panel, and so
-   * on — optionally narrowed by the shared filter.
-   *
-   * @param type - the {@linkcode PluginEntityType} to list
-   * @param filter - an optional {@linkcode PluginEntityFilter}
-   * @returns matching entities as {@linkcode ComponentHandle}`[]`
-   *
-   * @examplePrompt List all the curtain walls in the project
-   * @examplePrompt Show every curtain wall panel on this storey
-   * @examplePrompt Get all the elements of a single type, like columns
-   * @examplePrompt Find all the locked slabs in the model
-   *
-   * # Example
-   * ```ts
-   * const lockedSlabs = await snaptrude.design.query.listByType("slab", { isLocked: true })
-   *
-   * // Curtain-wall panels on storeys 2-3 of one building
-   * const panels = await snaptrude.design.query.listByType("panel", {
-   *   storeys: [2, 3],
-   *   buildingIds: ["bld_1"],
-   * })
-   * ```
-   */
-  public abstract listByType(
-    type: PluginEntityType,
-    filter?: PluginEntityFilter,
-  ): PluginApiReturn<ComponentHandle[]>
-
-  /**
-   * List all the walls in the project, optionally filtered by storey, building,
-   * label, selection state, or region.
-   *
-   * The `types` field of the filter is ignored (this method fixes the kind).
-   *
-   * @param filter - an optional {@linkcode PluginEntityFilter}
-   * @returns wall {@linkcode ComponentHandle}`[]`
-   *
-   * @examplePrompt How many walls are in the project?
-   * @examplePrompt List all the walls on the ground floor
-   * @examplePrompt Which walls are currently selected?
-   * @examplePrompt Find the walls on level 2 of building A
-   * @examplePrompt Show me every hidden wall
-   *
-   * # Example
-   * ```ts
-   * const groundFloorWalls = await snaptrude.design.query.listWalls({ storeys: [1] })
-   * ```
-   */
-  public abstract listWalls(
-    filter?: PluginEntityFilter,
-  ): PluginApiReturn<ComponentHandle[]>
-
-  /**
-   * List all the spaces (rooms) in the project, optionally filtered by storey,
-   * department, space type, label, selection state, or region.
-   *
-   * @param filter - an optional {@linkcode PluginEntityFilter}
-   * @returns space {@linkcode ComponentHandle}`[]`
-   *
-   * @examplePrompt How many rooms are in this project?
-   * @examplePrompt List all the spaces on the second storey
-   * @examplePrompt Which rooms are in the Bedrooms department?
-   * @examplePrompt Find every room labelled Kitchen
-   * @examplePrompt Show the spaces that are currently selected
-   *
-   * # Example
-   * ```ts
-   * // Balconies and decks on storey 2 (`label` is an exact match on room_type)
-   * const outdoor = await snaptrude.design.query.listSpaces({
-   *   storeys: [2],
-   *   spaceTypes: ["Balcony", "Deck"],
-   * })
-   *
-   * // Rooms in a department: resolve its id first, then filter and total the area
-   * const { departments } = await snaptrude.program.departments.list()
-   * const bedrooms = departments.find((d) => d.name === "Bedrooms")
-   * if (bedrooms) {
-   *   const rooms = await snaptrude.design.query.listSpaces({ departmentId: bedrooms.id })
-   *   let total = 0
-   *   for (const room of rooms) {
-   *     const m = await snaptrude.design.query.measure(room)
-   *     total += m?.area ?? 0
-   *   }
-   * }
-   * ```
-   */
-  public abstract listSpaces(
-    filter?: PluginEntityFilter,
-  ): PluginApiReturn<ComponentHandle[]>
-
-  /**
-   * List all the generic masses (non-room massing volumes) in the project,
-   * optionally filtered by storey, building, label, mass type, or region.
-   *
-   * @param filter - an optional {@linkcode PluginEntityFilter}
-   * @returns mass {@linkcode ComponentHandle}`[]`
-   *
-   * @examplePrompt List all the masses in the model
-   * @examplePrompt How many massing blocks are on the site?
-   * @examplePrompt Show the generic masses on level 1
-   * @examplePrompt Find every mass that isn't a room
-   *
-   * # Example
-   * ```ts
-   * // Only certain mass kinds — massTypes matches any of the given values
-   * const massing = await snaptrude.design.query.listMasses({
-   *   massTypes: ["Generic mass", "Plinth"],
-   * })
-   * ```
-   */
-  public abstract listMasses(
-    filter?: PluginEntityFilter,
-  ): PluginApiReturn<ComponentHandle[]>
-
-  /**
-   * List all the doors in the project, optionally filtered by storey, building,
-   * selection state, or region.
-   *
-   * @param filter - an optional {@linkcode PluginEntityFilter}
-   * @returns door {@linkcode ComponentHandle}`[]`
-   *
-   * @examplePrompt How many doors are in the project?
-   * @examplePrompt List all the doors on the ground floor
-   * @examplePrompt Which doors are currently selected?
-   * @examplePrompt Find every door in building B
-   *
-   * # Example
-   * ```ts
-   * // Ground-floor doors, then read each one's width via design.doors.*
-   * const doors = await snaptrude.design.query.listDoors({ storeys: [1] })
-   * for (const door of doors) {
-   *   const width = await snaptrude.design.doors.getWidth(door)
-   * }
-   * ```
-   */
-  public abstract listDoors(
-    filter?: PluginEntityFilter,
-  ): PluginApiReturn<ComponentHandle[]>
-
-  /**
-   * List all the windows in the project, optionally filtered by storey,
-   * building, selection state, or region.
-   *
-   * @param filter - an optional {@linkcode PluginEntityFilter}
-   * @returns window {@linkcode ComponentHandle}`[]`
-   *
-   * @examplePrompt How many windows does this building have?
-   * @examplePrompt List every window on level 3
-   * @examplePrompt Which windows are on the ground floor?
-   * @examplePrompt Show all the windows that are currently selected
-   *
-   * # Example
-   * ```ts
-   * const level3Windows = await snaptrude.design.query.listWindows({ storeys: [3] })
-   * ```
-   */
-  public abstract listWindows(
-    filter?: PluginEntityFilter,
-  ): PluginApiReturn<ComponentHandle[]>
-
-  /**
-   * List all the floor elements (floor plates / finishes) in the project,
-   * optionally filtered by storey, building, lock state, or region.
-   *
-   * @param filter - an optional {@linkcode PluginEntityFilter}
-   * @returns floor {@linkcode ComponentHandle}`[]`
-   *
-   * @examplePrompt List all the floor elements in the model
-   * @examplePrompt How many floor plates are on the second storey?
-   * @examplePrompt Which floors are locked?
-   * @examplePrompt Show the floor finishes on level 0
-   *
-   * # Example
-   * ```ts
-   * const lockedFloors = await snaptrude.design.query.listFloors({ isLocked: true })
-   * ```
-   */
-  public abstract listFloors(
-    filter?: PluginEntityFilter,
-  ): PluginApiReturn<ComponentHandle[]>
-
-  /**
-   * List all the slabs in the project, optionally filtered by storey, building,
-   * lock state, or region.
-   *
-   * @param filter - an optional {@linkcode PluginEntityFilter}
-   * @returns slab {@linkcode ComponentHandle}`[]`
-   *
-   * @examplePrompt List all the slabs in the project
-   * @examplePrompt How many slabs are on level 2?
-   * @examplePrompt Which slabs are locked?
-   * @examplePrompt Show the slabs in the selected building
-   *
-   * # Example
-   * ```ts
-   * const storey2Slabs = await snaptrude.design.query.listSlabs({ storeys: [2] })
-   * ```
-   */
-  public abstract listSlabs(
-    filter?: PluginEntityFilter,
-  ): PluginApiReturn<ComponentHandle[]>
-
-  /**
-   * List all the roofs in the project, optionally filtered by storey, building,
-   * visibility, or region.
-   *
-   * @param filter - an optional {@linkcode PluginEntityFilter}
-   * @returns roof {@linkcode ComponentHandle}`[]`
-   *
-   * @examplePrompt How many roofs does the model have?
-   * @examplePrompt List all the roof elements
-   * @examplePrompt Show the roofs on the top storey
-   * @examplePrompt Find every hidden roof
-   *
-   * # Example
-   * ```ts
-   * const hiddenRoofs = await snaptrude.design.query.listRoofs({ isHidden: true })
-   * ```
-   */
-  public abstract listRoofs(
-    filter?: PluginEntityFilter,
-  ): PluginApiReturn<ComponentHandle[]>
-
-  /**
-   * List all the columns in the project, optionally filtered by storey,
-   * building, selection state, or region.
-   *
-   * @param filter - an optional {@linkcode PluginEntityFilter}
-   * @returns column {@linkcode ComponentHandle}`[]`
-   *
-   * @examplePrompt How many columns are on the ground floor?
-   * @examplePrompt List all the columns in building A
-   * @examplePrompt Show every column on level 3
-   * @examplePrompt Which columns are currently selected?
-   *
-   * # Example
-   * ```ts
-   * const groundFloorColumns = await snaptrude.design.query.listColumns({ storeys: [1] })
-   * ```
-   */
-  public abstract listColumns(
-    filter?: PluginEntityFilter,
-  ): PluginApiReturn<ComponentHandle[]>
-
-  /**
-   * List all the beams in the project, optionally filtered by storey, building,
-   * lock state, or region.
-   *
-   * @param filter - an optional {@linkcode PluginEntityFilter}
-   * @returns beam {@linkcode ComponentHandle}`[]`
-   *
-   * @examplePrompt List all the beams in the project
-   * @examplePrompt How many beams are on the second storey?
-   * @examplePrompt Show the beams in this structure
-   * @examplePrompt Find every locked beam
-   *
-   * # Example
-   * ```ts
-   * const storey2Beams = await snaptrude.design.query.listBeams({ storeys: [2] })
-   * ```
-   */
-  public abstract listBeams(
-    filter?: PluginEntityFilter,
-  ): PluginApiReturn<ComponentHandle[]>
-
-  /**
-   * List all the ceilings in the project, optionally filtered by storey,
-   * building, visibility, or region.
-   *
-   * @param filter - an optional {@linkcode PluginEntityFilter}
-   * @returns ceiling {@linkcode ComponentHandle}`[]`
-   *
-   * @examplePrompt List all the ceilings in the model
-   * @examplePrompt How many ceilings are on level 1?
-   * @examplePrompt Which ceilings are hidden?
-   * @examplePrompt Show the ceilings in building B
-   *
-   * # Example
-   * ```ts
-   * const hiddenCeilings = await snaptrude.design.query.listCeilings({ isHidden: true })
-   * ```
-   */
-  public abstract listCeilings(
-    filter?: PluginEntityFilter,
-  ): PluginApiReturn<ComponentHandle[]>
-
-  /**
-   * List all the staircases in the project, optionally filtered by storey,
-   * building, selection state, or region.
-   *
-   * @param filter - an optional {@linkcode PluginEntityFilter}
-   * @returns staircase {@linkcode ComponentHandle}`[]`
-   *
-   * @examplePrompt How many staircases are in the building?
-   * @examplePrompt List all the stairs in the project
-   * @examplePrompt Show the staircases on the ground floor
-   * @examplePrompt Which stairs are currently selected?
-   *
-   * # Example
-   * ```ts
-   * const groundFloorStairs = await snaptrude.design.query.listStaircases({ storeys: [1] })
-   * ```
-   */
-  public abstract listStaircases(
-    filter?: PluginEntityFilter,
-  ): PluginApiReturn<ComponentHandle[]>
-
-  /**
-   * List all the furniture in the project, optionally filtered by storey,
-   * building, label, selection state, or region.
-   *
-   * @param filter - an optional {@linkcode PluginEntityFilter}
-   * @returns furniture {@linkcode ComponentHandle}`[]`
-   *
-   * @examplePrompt List all the furniture in the project
-   * @examplePrompt How many furniture items are on this floor?
-   * @examplePrompt Show the furniture inside the selected room
-   * @examplePrompt Which furniture is on storey 2?
-   *
-   * # Example
-   * ```ts
-   * // Furniture whose plan footprint overlaps a room (`overlaps` is plan-only —
-   * // scope the storey too, or furniture stacked on other floors matches)
-   * const [kitchen] = await snaptrude.design.query.listSpaces({ label: "Kitchen" })
-   * if (kitchen) {
-   *   const inKitchen = await snaptrude.design.query.listFurniture({
-   *     overlaps: kitchen,
-   *     storeys: [1],
-   *   })
-   * }
-   * ```
-   */
-  public abstract listFurniture(
-    filter?: PluginEntityFilter,
-  ): PluginApiReturn<ComponentHandle[]>
-
-  /**
-   * List all the reference lines in the project, optionally filtered by storey,
-   * building, or region.
-   *
-   * @param filter - an optional {@linkcode PluginEntityFilter}
-   * @returns reference-line {@linkcode ComponentHandle}`[]`
-   *
-   * @examplePrompt List all the reference lines in the model
-   * @examplePrompt Show the guide lines on the ground floor
-   * @examplePrompt How many reference lines are on this storey?
-   * @examplePrompt Find the setting-out lines in building A
-   *
-   * # Example
-   * ```ts
-   * const groundFloorRefLines = await snaptrude.design.query.listReferenceLines({ storeys: [1] })
-   * ```
-   */
-  public abstract listReferenceLines(
-    filter?: PluginEntityFilter,
-  ): PluginApiReturn<ComponentHandle[]>
-
-  /**
-   * List all the curtain-wall mullions in the project, optionally filtered by
-   * storey, building, selection state, or region.
-   *
-   * @param filter - an optional {@linkcode PluginEntityFilter}
-   * @returns mullion {@linkcode ComponentHandle}`[]`
-   *
-   * @examplePrompt List all the mullions in the curtain wall
-   * @examplePrompt How many mullions are on the facade?
-   * @examplePrompt Show every curtain wall mullion on level 5
-   * @examplePrompt Which mullions are currently selected?
-   *
-   * # Example
-   * ```ts
-   * const level5Mullions = await snaptrude.design.query.listMullions({ storeys: [5] })
-   * ```
-   */
-  public abstract listMullions(
-    filter?: PluginEntityFilter,
-  ): PluginApiReturn<ComponentHandle[]>
-
-  /**
-   * List all the structural grids (grid groups) in the project, optionally
-   * filtered by storey, building, selection state, or region.
-   *
-   * @param filter - an optional {@linkcode PluginEntityFilter}
-   * @returns grid-group {@linkcode ComponentHandle}`[]`
-   *
-   * @examplePrompt List all the structural grids in the model
-   * @examplePrompt How many grids are on the ground floor?
-   * @examplePrompt Show the grids on this storey
-   * @examplePrompt Which grids are currently selected?
-   *
-   * # Example
-   * ```ts
-   * const groundFloorGrids = await snaptrude.design.query.listGrids({ storeys: [1] })
-   * ```
-   */
-  public abstract listGrids(
-    filter?: PluginEntityFilter,
-  ): PluginApiReturn<ComponentHandle[]>
-
-  // ── single-entity access & identity ─────────────────────────────────────────
-
-  /**
-   * Look an entity up by id — returns the same handle if it still resolves live,
-   * else `null`. A cheap validity probe (distinct from {@linkcode PluginDesignQueryApi.exists}).
-   *
-   * @param id - the entity id ({@linkcode ComponentHandle}) to look up
-   * @returns the {@linkcode ComponentHandle}, or `null` if it no longer resolves
-   *
-   * @examplePrompt Look up an object by its id
-   * @examplePrompt Does id cmp_42 still point to something in the model?
-   * @examplePrompt Fetch the element with this id
-   * @examplePrompt Check if this saved element id is still valid
-   *
-   * # Example
-   * ```ts
-   * // Persistence round-trip: save a ref now, revalidate it in a later run
-   * const [wall] = await snaptrude.design.query.listWalls()
-   * const savedRef = await snaptrude.design.query.getEntityRef(wall)
-   *
-   * // ...later (savedRef restored from plugin storage)...
-   * const stillThere = await snaptrude.design.query.getById(savedRef)
-   * if (stillThere) {
-   *   const props = await snaptrude.design.query.getProperties(stillThere)
-   * }
-   * ```
-   */
-  public abstract getById(
-    id: ComponentHandle,
-  ): PluginApiReturn<ComponentHandle | null>
-
-  /**
-   * Test whether an entity id resolves to a live scene entity.
-   * @param id - the entity id ({@linkcode ComponentHandle}) to look up
-   * @returns `true` if it exists, otherwise `false`
-   *
-   * @examplePrompt Does this element still exist in the scene?
-   * @examplePrompt Check whether the wall I stored earlier is still there
-   * @examplePrompt Is id cmp_42 still valid?
-   * @examplePrompt Verify the object wasn't deleted
-   *
-   * # Example
-   * ```ts
-   * // Guard before acting on a handle that may have been deleted or undone
-   * if (await snaptrude.design.query.exists(wall)) {
-   *   const dx = await snaptrude.core.math.vec3.new(5, 0, 0)
-   *   await snaptrude.design.transform.move([wall], dx)
-   * }
-   * ```
-   */
-  public abstract exists(id: ComponentHandle): PluginApiReturn<boolean>
-
-  /**
-   * Get the kind of BIM entity a handle refers to — wall, door, space, slab,
-   * and so on (its {@linkcode PluginEntityType}).
-   * @param component - the entity's {@linkcode ComponentHandle}
-   * @returns the kind, or `null` if the entity is gone / its type is unknown
-   *
-   * @examplePrompt What kind of element is this?
-   * @examplePrompt Is the selected object a wall or a mass?
-   * @examplePrompt Tell me the type of this component
-   * @examplePrompt What am I looking at — a door, a window, or a panel?
-   *
-   * # Example
-   * ```ts
-   * // Dispatch on what the user selected
-   * const selection = await snaptrude.design.selection.get()
-   * for (const component of selection) {
-   *   const kind = await snaptrude.design.query.getEntityType(component)
-   *   if (kind === "wall") {
-   *     // wall-specific handling
-   *   } else if (kind === "space") {
-   *     // room-specific handling
-   *   }
-   * }
-   * ```
-   */
-  public abstract getEntityType(
-    component: ComponentHandle,
-  ): PluginApiReturn<PluginEntityType | null>
-
-  /**
-   * Get an entity's human label (`room_type` for spaces/masses, else the mesh
-   * label; `""` when unlabelled). The write side is `design.update` (`setLabel`).
-   * @param component - the entity's {@linkcode ComponentHandle}
-   * @returns the label string
-   *
-   * @examplePrompt What is this room called?
-   * @examplePrompt Get the name of the selected object
-   * @examplePrompt Show the label on this wall
-   * @examplePrompt What's the room type of this space?
-   *
-   * # Example
-   * ```ts
-   * // Fuzzy label search (the `label` filter field is exact-match; for
-   * // case-insensitive or partial matches, read labels and compare yourself)
-   * const spaces = await snaptrude.design.query.listSpaces()
-   * const kitchens: typeof spaces = []
-   * for (const space of spaces) {
-   *   const label = await snaptrude.design.query.getLabel(space)
-   *   if (label.toLowerCase().includes("kitchen")) kitchens.push(space)
-   * }
-   * ```
-   */
-  public abstract getLabel(component: ComponentHandle): PluginApiReturn<string>
-
-  /**
-   * Get a serializable, persistable reference to an entity. Under the all-handle
-   * model a {@linkcode ComponentHandle} already IS the ref (raw `Component.id`),
-   * so this is the identity passthrough — provided for API completeness.
-   * @param component - the entity's {@linkcode ComponentHandle}
-   * @returns the entity's {@linkcode ComponentHandle}
-   *
-   * @examplePrompt Give me a reference I can save for this element
-   * @examplePrompt Get a persistent id for the selected wall
-   * @examplePrompt Store a handle to this room so I can find it later
-   *
-   * # Example
-   * ```ts
-   * const [wall] = await snaptrude.design.query.listWalls()
-   * const savedRef = await snaptrude.design.query.getEntityRef(wall)
-   * // savedRef is a plain string — persist it, then revalidate in a later run
-   * // with snaptrude.design.query.getById(savedRef)
-   * ```
-   */
-  public abstract getEntityRef(
-    component: ComponentHandle,
-  ): PluginApiReturn<ComponentHandle>
-
-  /**
-   * List an entity's direct child entities — for example the doors and windows
-   * hosted in a wall.
-   * @param component - the entity's {@linkcode ComponentHandle}
-   * @returns child {@linkcode ComponentHandle}`[]` (`[]` if none)
-   *
-   * @examplePrompt What's inside this wall — list its doors and windows
-   * @examplePrompt Show the child elements of the selected object
-   * @examplePrompt Which openings belong to this wall?
-   * @examplePrompt List everything nested under this mass
-   *
-   * # Example
-   * ```ts
-   * // Count the openings hosted in a wall, split by kind
-   * const children = await snaptrude.design.query.listChildren(wall)
-   * let doors = 0
-   * let windows = 0
-   * for (const child of children) {
-   *   const kind = await snaptrude.design.query.getEntityType(child)
-   *   if (kind === "door") doors++
-   *   if (kind === "window") windows++
-   * }
-   * ```
-   */
-  public abstract listChildren(
-    component: ComponentHandle,
-  ): PluginApiReturn<ComponentHandle[]>
-
-  /**
-   * Get an entity's host/parent entity (e.g. the wall a door is cut into).
-   * @param component - the entity's {@linkcode ComponentHandle}
-   * @returns the host {@linkcode ComponentHandle}, or `null` if top-level
-   *
-   * @examplePrompt Which wall is this door in?
-   * @examplePrompt Find the parent of the selected window
-   * @examplePrompt What is this element attached to?
-   * @examplePrompt Which wall hosts this window?
-   *
-   * # Example
-   * ```ts
-   * // From a door up to its host wall, then measure the wall
-   * const [door] = await snaptrude.design.query.listDoors({ isSelected: true })
-   * const hostWall = door ? await snaptrude.design.query.getHost(door) : null
-   * if (hostWall) {
-   *   const m = await snaptrude.design.query.measure(hostWall)
-   *   console.log("wall length:", m?.length)
-   * }
-   * ```
-   */
-  public abstract getHost(
-    component: ComponentHandle,
-  ): PluginApiReturn<ComponentHandle | null>
-
-  // ── property & metric reads ─────────────────────────────────────────────────
-
-  /**
-   * 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`). 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
-   *
-   * # Example
-   * ```ts
-   * const [wall] = await snaptrude.design.query.listWalls()
-   * const props = await snaptrude.design.query.getProperties(wall)
-   * console.log(props.type, props.storey, props.boundingBox)
-   *
-   * // The record is partial — type-specific fields exist only where they apply
-   * const [room] = await snaptrude.design.query.listSpaces()
-   * const p = await snaptrude.design.query.getProperties(room)
-   * if (p.spaceType === "Room" && p.areaClass === "NET") {
-   *   for (const adj of p.adjacency ?? []) {
-   *     // adj.value: 2 = direct, 1 = indirect/contact, -1 = restricted
-   *     console.log(adj.spaceId, adj.value)
-   *   }
-   * }
-   * ```
-   */
-  public abstract getProperties(
-    component: ComponentHandle,
-  ): PluginApiReturn<PluginEntityProperties>
-
-  /**
-   * 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?
-   *
-   * # Example
-   * ```ts
-   * 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>
-
-  /**
-   * Read a mass's creation-parameter record — the recipe it was built from
-   * (`kind` plus the values that constructor was called with). Present on
-   * masses committed from a `core.geom.create` brep constructor that carries a
-   * recipe: {@linkcode MassParametersRecord} covers the four primitives
-   * (sphere, cylinder, cone, torus), extrusions, revolutions, lofts and sweeps.
-   *
-   * A fillet, chamfer, shell or offset of a recorded solid keeps the record
-   * too: `kind` stays the base constructor and the operation is appended to the
-   * record's `operations` list. Edit any of it with `design.update.parameters`.
-   *
-   * `null` for everything else — drawn masses, imported geometry, booleans,
-   * split parts, `brepFromFaces` / `brepFromMesh`, and results built on a
-   * source that carried no record — and for a mass whose record no longer
-   * matches what is on
-   * screen (a later free-form edit dropped the recipe, or the mass carries a
-   * baked scale). `null` too when the recipe was not recordable: the record
-   * schema has its own caps (a sweep path of at most 512 points, a loft of at
-   * most 32 sections, at most 8 chained `operations`, at most 256 curves in one
-   * profile loop and 64 holes in one contour), and a mass built past one of
-   * them — through a route that does not enforce the matching creator cap —
-   * commits as ordinary geometry carrying no record. The `operations` cap is
-   * the one an agent can walk into by accident: a 9th chained
-   * fillet/chamfer/shell/offset drops the record silently, so the result
-   * commits as ordinary geometry and reads back `null` here. A record is never
-   * reported unless it is still the truth.
-   *
-   * Points and axes come back in **world** coordinates. Pure read — nothing is
-   * created or modified.
-   *
-   * @param component - the mass's {@linkcode ComponentHandle}
-   * @returns the {@linkcode MassParametersRecord}, or `null`
-   *
-   * @examplePrompt What radius is this sphere?
-   * @examplePrompt Is this mass parametric?
-   * @examplePrompt Read back the dome's creation parameters
-   * @examplePrompt How tall was this cylinder made?
-   *
-   * # Example
-   * ```ts
-   * const [mass] = await snaptrude.design.query.listMasses({ isSelected: true })
-   * const params = await snaptrude.design.query.getParameters(mass)
-   * if (params?.kind === "sphere") console.log("radius:", params.values.radius)
-   * ```
-   */
-  public abstract getParameters(
-    component: ComponentHandle,
-  ): PluginApiReturn<MassParametersRecord | null>
-
-  /**
-   * Get the **union** axis-aligned bounding box enclosing a set of entities.
-   *
-   * @param components - the set of entity {@linkcode ComponentHandle}s
-   * @returns the union {@linkcode BBoxComponents}, or `null` if the set is empty /
-   *   none resolve
-   *
-   * @examplePrompt Get the bounding box around the selected objects
-   * @examplePrompt What is the overall extent of these walls?
-   * @examplePrompt How big is the region these elements cover together?
-   * @examplePrompt Find the combined extents of everything on level 2
-   *
-   * # Example
-   * ```ts
-   * const walls = await snaptrude.design.query.listWalls()
-   * const box = await snaptrude.design.query.getBoundingBox(walls)
-   *
-   * // Compose with the `within` filter: everything in the selection's extents
-   * const selection = await snaptrude.design.selection.get()
-   * const extents = await snaptrude.design.query.getBoundingBox(selection)
-   * if (extents) {
-   *   const nearby = await snaptrude.design.query.listEntities({ within: extents })
-   *   const width = extents.max.x - extents.min.x
-   * }
-   * ```
-   */
-  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"
-export * from "./grids"
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { ComponentHandle, BBoxComponents } from "../../../handles"
+import type { MassParametersRecord } from "../../../massParameters"
+import {
+  PluginSpaceType,
+  PluginMassType,
+  PluginDepartmentId,
+  PluginAreaClass,
+} from "../../entity/space"
+import { PluginStaircasePreset } from "../create"
+import { PluginDesignQueryGeometryApi } from "./geometry"
+import { PluginDesignQuerySpacesApi } from "./spaces"
+import { PluginDesignQueryReferenceLinesApi } from "./referenceLines"
+import { PluginDesignQueryGridsApi } from "./grids"
+
+// ---------------------------------------------------------------------------
+// Entity type vocabulary
+// ---------------------------------------------------------------------------
+
+/**
+ * The kind of a BIM entity — the discovery/filter vocabulary for the whole
+ * `design.query.*` surface. Values are clean `lowerCamel` tokens; the host maps
+ * each to the engine's internal type (whose raw strings are case-inconsistent —
+ * `"roof"`/`"slab"` lowercase, `"Wall"`/`"Door"` PascalCase — never surfaced here).
+ *
+ * | Value | Entity |
+ * |---|---|
+ * | `"wall"` | Wall |
+ * | `"space"` | Space (a room mass) |
+ * | `"mass"` | Generic mass (non-room) |
+ * | `"door"` | Door |
+ * | `"window"` | Window |
+ * | `"floor"` | Floor |
+ * | `"slab"` | Slab |
+ * | `"roof"` | Roof |
+ * | `"column"` | Column |
+ * | `"beam"` | Beam |
+ * | `"ceiling"` | Ceiling |
+ * | `"staircase"` | Staircase |
+ * | `"furniture"` | Furniture |
+ * | `"referenceLine"` | Reference line |
+ * | `"curtainWall"` | Parametric curtain wall |
+ * | `"mullion"` | Curtain-wall mullion |
+ * | `"panel"` | Curtain-wall panel |
+ * | `"parametricComponent"` | A placed parametric family instance (native or Revit-imported). Its geometry is rebuilt from `design.family` parameters, so read and drive it through `design.family.getParameters` / `setParameters` rather than editing its meshes. |
+ * | `"grid"` | Structural grid group |
+ */
+export const PluginEntityType = z.enum([
+  "wall",
+  "space",
+  "mass",
+  "door",
+  "window",
+  "floor",
+  "slab",
+  "roof",
+  "column",
+  "beam",
+  "ceiling",
+  "staircase",
+  "furniture",
+  "referenceLine",
+  "curtainWall",
+  "mullion",
+  "panel",
+  "parametricComponent",
+  "grid",
+])
+export type PluginEntityType = z.infer<typeof PluginEntityType>
+
+// ---------------------------------------------------------------------------
+// The shared filter — one options object, every list* method
+// ---------------------------------------------------------------------------
+
+/**
+ * `EntityFilterOptions` — the **single filter** shared by every `design.query.list*`
+ * method, so filtering is identical across all BIM object types. Every field is
+ * optional and **AND-combined**: a component must satisfy all provided fields.
+ * Plural fields are arrays (match any of); singular fields are scalars. A field
+ * that names a type-specific dimension (`massTypes`/`spaceTypes`/`departmentId`)
+ * excludes components that lack that dimension.
+ *
+ * | Field | Type | Keeps components where |
+ * |---|---|---|
+ * | `types` | {@linkcode PluginEntityType}`[]` | entity kind ∈ `types` (ignored by per-type `list*` — the method fixes the kind) |
+ * | `storeys` | `number[]` | storey/floor level ∈ `storeys` (negative = basement) |
+ * | `buildingIds` | `string[]` | building ∈ `buildingIds` |
+ * | `structureIds` | `string[]` | structure ∈ `structureIds` |
+ * | `label` | `string` | label (`room_type` ?? mesh label) === `label` |
+ * | `massTypes` | {@linkcode PluginMassType}`[]` | mass-type ∈ (masses only) |
+ * | `spaceTypes` | {@linkcode PluginSpaceType}`[]` | space-type ∈ (spaces only) |
+ * | `departmentId` | {@linkcode PluginDepartmentId} | department === |
+ * | `isSelected` | `boolean` | current selection state === |
+ * | `isLocked` | `boolean` | lock flag === |
+ * | `isHidden` | `boolean` | user-hidden flag === |
+ * | `within` | {@linkcode BBoxComponents} | the entity's bounding box intersects the region |
+ * | `overlaps` | {@linkcode ComponentHandle} | the entity's plan footprint overlaps the given space's bottom-face footprint — non-zero intersection area, so fully-inside, boundary-nested, and partially-overhanging entities all match; edge-touching with zero interior overlap does not. Exact polygon intersection (holes respected). Tested in plan — storey height is ignored; compose with `storeys` to scope a floor. Hidden entities are excluded by default — pass `isHidden` explicitly to override. The reference space itself is never returned. Throws on an unknown id. Entities without a brep footprint use their bounding-box plan rectangle. |
+ * | `ids` | {@linkcode ComponentHandle}`[]` | id ∈ `ids` (restrict to a known set) |
+ */
+export const PluginEntityFilter = z.object({
+  types: z.array(PluginEntityType).optional(),
+  storeys: z.array(z.number()).optional(),
+  buildingIds: z.array(z.string()).optional(),
+  structureIds: z.array(z.string()).optional(),
+  label: z.string().optional(),
+  massTypes: z.array(PluginMassType).optional(),
+  spaceTypes: z.array(PluginSpaceType).optional(),
+  departmentId: PluginDepartmentId.optional(),
+  isSelected: z.boolean().optional(),
+  isLocked: z.boolean().optional(),
+  isHidden: z.boolean().optional(),
+  within: BBoxComponents.optional(),
+  overlaps: ComponentHandle.optional(),
+  ids: z.array(ComponentHandle).optional(),
+})
+export type PluginEntityFilter = z.infer<typeof PluginEntityFilter>
+
+/**
+ * Arguments for {@linkcode PluginDesignQueryApi.listByType} — a required entity
+ * `type` plus every {@linkcode PluginEntityFilter} field.
+ */
+export const PluginDesignQueryListByTypeArgs = PluginEntityFilter.extend({
+  type: PluginEntityType,
+})
+export type PluginDesignQueryListByTypeArgs = z.infer<
+  typeof PluginDesignQueryListByTypeArgs
+>
+
+// ---------------------------------------------------------------------------
+// Single-entity argument shapes
+// ---------------------------------------------------------------------------
+
+/** Arguments for methods that read one entity by its {@linkcode ComponentHandle}. */
+export const PluginDesignQueryComponentArgs = z.object({
+  component: ComponentHandle,
+})
+export type PluginDesignQueryComponentArgs = z.infer<
+  typeof PluginDesignQueryComponentArgs
+>
+
+/** Arguments for methods that look an entity up by id. */
+export const PluginDesignQueryIdArgs = z.object({
+  id: ComponentHandle,
+})
+export type PluginDesignQueryIdArgs = z.infer<typeof PluginDesignQueryIdArgs>
+
+/** Arguments for methods over a set of entities (e.g. the union bounding box). */
+export const PluginDesignQueryComponentsArgs = z.object({
+  components: z.array(ComponentHandle),
+})
+export type PluginDesignQueryComponentsArgs = z.infer<
+  typeof PluginDesignQueryComponentsArgs
+>
+
+// ---------------------------------------------------------------------------
+// Read records
+// ---------------------------------------------------------------------------
+
+/**
+ * The common property record returned by {@linkcode PluginDesignQueryApi.getProperties} —
+ * a **partial** object (a field is present only when it applies to the entity).
+ * Type-specific and geometry reads live on {@linkcode PluginDesignQueryApi.measure}
+ * and `design.query.geometry.*`, keeping this record generic across every type.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The entity id |
+ * | `type` | {@linkcode PluginEntityType} | Entity kind |
+ * | `label` | `string` | `room_type` ?? mesh label ?? `""` |
+ * | `storey` | `number` | Storey/floor level |
+ * | `buildingId` | `string` | Owning building |
+ * | `structureId` | `string` | Owning structure |
+ * | `massType` | `string` | Mass-type (masses only) |
+ * | `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 |
+ * | `boundingBox` | {@linkcode BBoxComponents} | World-space AABB |
+ * | `adjacency` | `{ spaceId: string; value: number }[]` | Adjacency relationships (spaces/masses only). `value`: `2` = Direct (required), `1` = Indirect or physical contact, `-1` = Restricted; `0` entries are filtered out. `[]` when adjacency has never been computed — see `program.adjacency.compute`. |
+ */
+export const PluginEntityProperties = z
+  .object({
+    id: z.string(),
+    type: PluginEntityType,
+    label: z.string(),
+    storey: z.number(),
+    buildingId: z.string(),
+    structureId: z.string(),
+    massType: z.string(),
+    spaceType: PluginSpaceType,
+    areaClass: PluginAreaClass,
+    departmentId: z.string(),
+    buildingType: z.string(),
+    isLocked: z.boolean(),
+    isHidden: z.boolean(),
+    isSelected: z.boolean(),
+    boundingBox: BBoxComponents,
+    adjacency: z.array(z.object({ spaceId: z.string(), value: z.number() })),
+  })
+  .partial()
+export type PluginEntityProperties = z.infer<typeof PluginEntityProperties>
+
+/**
+ * The multi-metric bundle returned by {@linkcode PluginDesignQueryApi.measure}.
+ * `boundingBox` is always present; the numeric metrics appear only when the
+ * 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
+// ---------------------------------------------------------------------------
+
+/**
+ * `design.query.*` — read-only enumeration + inspection of scene-committed BIM
+ * entities (all-handle model, §11). No query mutates the scene.
+ *
+ * Every `list*` returns a snapshot {@linkcode ComponentHandle}`[]` (`[]`, never
+ * `null`) filtered by the shared {@linkcode PluginEntityFilter}; per-entity reads
+ * take a {@linkcode ComponentHandle} and return primitive records / child handles
+ * or `null` when the entity is gone. Resolve details of a returned handle with
+ * {@linkcode PluginDesignQueryApi.getProperties} / {@linkcode PluginDesignQueryApi.measure}
+ * / `design.query.geometry.*`.
+ *
+ * Accessed via `snaptrude.design.query`.
+ */
+export abstract class PluginDesignQueryApi {
+  /** Entity-geometry reads (brep, bottom contour). See {@linkcode PluginDesignQueryGeometryApi}. */
+  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
+  /** Structural-grid-specific reads. See {@linkcode PluginDesignQueryGridsApi}. */
+  public abstract grids: PluginDesignQueryGridsApi
+
+  constructor() {}
+
+  // ── enumeration ───────────────────────────────────────────────────────────
+
+  /**
+   * List **all** BIM entities in the project matching the filter.
+   *
+   * @param filter - an optional {@linkcode PluginEntityFilter}
+   * @returns matching entities as {@linkcode ComponentHandle}`[]` (`[]` if none)
+   *
+   * @examplePrompt Show me everything in the model
+   * @examplePrompt How many objects are on the ground floor?
+   * @examplePrompt List all the doors and windows on level 2
+   * @examplePrompt What elements are currently selected?
+   * @examplePrompt Find every hidden object in the project
+   *
+   * # Example
+   * ```ts
+   * // Doors and windows on the ground storey (fields AND-combine)
+   * const doorsAndWindows = await snaptrude.design.query.listEntities({
+   *   types: ["door", "window"],
+   *   storeys: [1],
+   * })
+   *
+   * // Everything the user currently has selected
+   * const selected = await snaptrude.design.query.listEntities({ isSelected: true })
+   *
+   * // Everything inside a world-space region (axis-aligned box, Snaptrude units)
+   * const inRegion = await snaptrude.design.query.listEntities({
+   *   within: { min: { x: 0, y: 0, z: 0 }, max: { x: 10, y: 4, z: 8 } },
+   * })
+   * ```
+   */
+  public abstract listEntities(
+    filter?: PluginEntityFilter,
+  ): PluginApiReturn<ComponentHandle[]>
+
+  /**
+   * List all entities of one BIM object type — wall, door, slab, panel, and so
+   * on — optionally narrowed by the shared filter.
+   *
+   * `"mass"` includes voids; a mass whose `design.query.getHost` is a slab,
+   * floor, roof or ceiling is a void (made by `design.create.void`).
+   *
+   * @param type - the {@linkcode PluginEntityType} to list
+   * @param filter - an optional {@linkcode PluginEntityFilter}
+   * @returns matching entities as {@linkcode ComponentHandle}`[]`
+   *
+   * @examplePrompt List all the curtain walls in the project
+   * @examplePrompt Show every curtain wall panel on this storey
+   * @examplePrompt Get all the elements of a single type, like columns
+   * @examplePrompt Find all the locked slabs in the model
+   *
+   * # Example
+   * ```ts
+   * const lockedSlabs = await snaptrude.design.query.listByType("slab", { isLocked: true })
+   *
+   * // Curtain-wall panels on storeys 2-3 of one building
+   * const panels = await snaptrude.design.query.listByType("panel", {
+   *   storeys: [2, 3],
+   *   buildingIds: ["bld_1"],
+   * })
+   * ```
+   */
+  public abstract listByType(
+    type: PluginEntityType,
+    filter?: PluginEntityFilter,
+  ): PluginApiReturn<ComponentHandle[]>
+
+  /**
+   * List all the walls in the project, optionally filtered by storey, building,
+   * label, selection state, or region.
+   *
+   * The `types` field of the filter is ignored (this method fixes the kind).
+   *
+   * @param filter - an optional {@linkcode PluginEntityFilter}
+   * @returns wall {@linkcode ComponentHandle}`[]`
+   *
+   * @examplePrompt How many walls are in the project?
+   * @examplePrompt List all the walls on the ground floor
+   * @examplePrompt Which walls are currently selected?
+   * @examplePrompt Find the walls on level 2 of building A
+   * @examplePrompt Show me every hidden wall
+   *
+   * # Example
+   * ```ts
+   * const groundFloorWalls = await snaptrude.design.query.listWalls({ storeys: [1] })
+   * ```
+   */
+  public abstract listWalls(
+    filter?: PluginEntityFilter,
+  ): PluginApiReturn<ComponentHandle[]>
+
+  /**
+   * List all the spaces (rooms) in the project, optionally filtered by storey,
+   * department, space type, label, selection state, or region.
+   *
+   * @param filter - an optional {@linkcode PluginEntityFilter}
+   * @returns space {@linkcode ComponentHandle}`[]`
+   *
+   * @examplePrompt How many rooms are in this project?
+   * @examplePrompt List all the spaces on the second storey
+   * @examplePrompt Which rooms are in the Bedrooms department?
+   * @examplePrompt Find every room labelled Kitchen
+   * @examplePrompt Show the spaces that are currently selected
+   *
+   * # Example
+   * ```ts
+   * // Balconies and decks on storey 2 (`label` is an exact match on room_type)
+   * const outdoor = await snaptrude.design.query.listSpaces({
+   *   storeys: [2],
+   *   spaceTypes: ["Balcony", "Deck"],
+   * })
+   *
+   * // Rooms in a department: resolve its id first, then filter and total the area
+   * const { departments } = await snaptrude.program.departments.list()
+   * const bedrooms = departments.find((d) => d.name === "Bedrooms")
+   * if (bedrooms) {
+   *   const rooms = await snaptrude.design.query.listSpaces({ departmentId: bedrooms.id })
+   *   let total = 0
+   *   for (const room of rooms) {
+   *     const m = await snaptrude.design.query.measure(room)
+   *     total += m?.area ?? 0
+   *   }
+   * }
+   * ```
+   */
+  public abstract listSpaces(
+    filter?: PluginEntityFilter,
+  ): PluginApiReturn<ComponentHandle[]>
+
+  /**
+   * List all the generic masses (non-room massing volumes) in the project,
+   * optionally filtered by storey, building, label, mass type, or region.
+   *
+   * Includes voids; a mass whose `design.query.getHost` is a slab, floor, roof
+   * or ceiling is a void (made by `design.create.void`).
+   *
+   * @param filter - an optional {@linkcode PluginEntityFilter}
+   * @returns mass {@linkcode ComponentHandle}`[]`
+   *
+   * @examplePrompt List all the masses in the model
+   * @examplePrompt How many massing blocks are on the site?
+   * @examplePrompt Show the generic masses on level 1
+   * @examplePrompt Find every mass that isn't a room
+   *
+   * # Example
+   * ```ts
+   * // Only certain mass kinds — massTypes matches any of the given values
+   * const massing = await snaptrude.design.query.listMasses({
+   *   massTypes: ["Generic mass", "Plinth"],
+   * })
+   * ```
+   */
+  public abstract listMasses(
+    filter?: PluginEntityFilter,
+  ): PluginApiReturn<ComponentHandle[]>
+
+  /**
+   * List all the doors in the project, optionally filtered by storey, building,
+   * selection state, or region.
+   *
+   * @param filter - an optional {@linkcode PluginEntityFilter}
+   * @returns door {@linkcode ComponentHandle}`[]`
+   *
+   * @examplePrompt How many doors are in the project?
+   * @examplePrompt List all the doors on the ground floor
+   * @examplePrompt Which doors are currently selected?
+   * @examplePrompt Find every door in building B
+   *
+   * # Example
+   * ```ts
+   * // Ground-floor doors, then read each one's width via design.doors.*
+   * const doors = await snaptrude.design.query.listDoors({ storeys: [1] })
+   * for (const door of doors) {
+   *   const width = await snaptrude.design.doors.getWidth(door)
+   * }
+   * ```
+   */
+  public abstract listDoors(
+    filter?: PluginEntityFilter,
+  ): PluginApiReturn<ComponentHandle[]>
+
+  /**
+   * List all the windows in the project, optionally filtered by storey,
+   * building, selection state, or region.
+   *
+   * @param filter - an optional {@linkcode PluginEntityFilter}
+   * @returns window {@linkcode ComponentHandle}`[]`
+   *
+   * @examplePrompt How many windows does this building have?
+   * @examplePrompt List every window on level 3
+   * @examplePrompt Which windows are on the ground floor?
+   * @examplePrompt Show all the windows that are currently selected
+   *
+   * # Example
+   * ```ts
+   * const level3Windows = await snaptrude.design.query.listWindows({ storeys: [3] })
+   * ```
+   */
+  public abstract listWindows(
+    filter?: PluginEntityFilter,
+  ): PluginApiReturn<ComponentHandle[]>
+
+  /**
+   * List all the floor elements (floor plates / finishes) in the project,
+   * optionally filtered by storey, building, lock state, or region.
+   *
+   * @param filter - an optional {@linkcode PluginEntityFilter}
+   * @returns floor {@linkcode ComponentHandle}`[]`
+   *
+   * @examplePrompt List all the floor elements in the model
+   * @examplePrompt How many floor plates are on the second storey?
+   * @examplePrompt Which floors are locked?
+   * @examplePrompt Show the floor finishes on level 0
+   *
+   * # Example
+   * ```ts
+   * const lockedFloors = await snaptrude.design.query.listFloors({ isLocked: true })
+   * ```
+   */
+  public abstract listFloors(
+    filter?: PluginEntityFilter,
+  ): PluginApiReturn<ComponentHandle[]>
+
+  /**
+   * List all the slabs in the project, optionally filtered by storey, building,
+   * lock state, or region.
+   *
+   * @param filter - an optional {@linkcode PluginEntityFilter}
+   * @returns slab {@linkcode ComponentHandle}`[]`
+   *
+   * @examplePrompt List all the slabs in the project
+   * @examplePrompt How many slabs are on level 2?
+   * @examplePrompt Which slabs are locked?
+   * @examplePrompt Show the slabs in the selected building
+   *
+   * # Example
+   * ```ts
+   * const storey2Slabs = await snaptrude.design.query.listSlabs({ storeys: [2] })
+   * ```
+   */
+  public abstract listSlabs(
+    filter?: PluginEntityFilter,
+  ): PluginApiReturn<ComponentHandle[]>
+
+  /**
+   * List all the roofs in the project, optionally filtered by storey, building,
+   * visibility, or region.
+   *
+   * @param filter - an optional {@linkcode PluginEntityFilter}
+   * @returns roof {@linkcode ComponentHandle}`[]`
+   *
+   * @examplePrompt How many roofs does the model have?
+   * @examplePrompt List all the roof elements
+   * @examplePrompt Show the roofs on the top storey
+   * @examplePrompt Find every hidden roof
+   *
+   * # Example
+   * ```ts
+   * const hiddenRoofs = await snaptrude.design.query.listRoofs({ isHidden: true })
+   * ```
+   */
+  public abstract listRoofs(
+    filter?: PluginEntityFilter,
+  ): PluginApiReturn<ComponentHandle[]>
+
+  /**
+   * List all the columns in the project, optionally filtered by storey,
+   * building, selection state, or region.
+   *
+   * @param filter - an optional {@linkcode PluginEntityFilter}
+   * @returns column {@linkcode ComponentHandle}`[]`
+   *
+   * @examplePrompt How many columns are on the ground floor?
+   * @examplePrompt List all the columns in building A
+   * @examplePrompt Show every column on level 3
+   * @examplePrompt Which columns are currently selected?
+   *
+   * # Example
+   * ```ts
+   * const groundFloorColumns = await snaptrude.design.query.listColumns({ storeys: [1] })
+   * ```
+   */
+  public abstract listColumns(
+    filter?: PluginEntityFilter,
+  ): PluginApiReturn<ComponentHandle[]>
+
+  /**
+   * List all the beams in the project, optionally filtered by storey, building,
+   * lock state, or region.
+   *
+   * @param filter - an optional {@linkcode PluginEntityFilter}
+   * @returns beam {@linkcode ComponentHandle}`[]`
+   *
+   * @examplePrompt List all the beams in the project
+   * @examplePrompt How many beams are on the second storey?
+   * @examplePrompt Show the beams in this structure
+   * @examplePrompt Find every locked beam
+   *
+   * # Example
+   * ```ts
+   * const storey2Beams = await snaptrude.design.query.listBeams({ storeys: [2] })
+   * ```
+   */
+  public abstract listBeams(
+    filter?: PluginEntityFilter,
+  ): PluginApiReturn<ComponentHandle[]>
+
+  /**
+   * List all the ceilings in the project, optionally filtered by storey,
+   * building, visibility, or region.
+   *
+   * @param filter - an optional {@linkcode PluginEntityFilter}
+   * @returns ceiling {@linkcode ComponentHandle}`[]`
+   *
+   * @examplePrompt List all the ceilings in the model
+   * @examplePrompt How many ceilings are on level 1?
+   * @examplePrompt Which ceilings are hidden?
+   * @examplePrompt Show the ceilings in building B
+   *
+   * # Example
+   * ```ts
+   * const hiddenCeilings = await snaptrude.design.query.listCeilings({ isHidden: true })
+   * ```
+   */
+  public abstract listCeilings(
+    filter?: PluginEntityFilter,
+  ): PluginApiReturn<ComponentHandle[]>
+
+  /**
+   * List all the staircases in the project, optionally filtered by storey,
+   * building, selection state, or region.
+   *
+   * @param filter - an optional {@linkcode PluginEntityFilter}
+   * @returns staircase {@linkcode ComponentHandle}`[]`
+   *
+   * @examplePrompt How many staircases are in the building?
+   * @examplePrompt List all the stairs in the project
+   * @examplePrompt Show the staircases on the ground floor
+   * @examplePrompt Which stairs are currently selected?
+   *
+   * # Example
+   * ```ts
+   * const groundFloorStairs = await snaptrude.design.query.listStaircases({ storeys: [1] })
+   * ```
+   */
+  public abstract listStaircases(
+    filter?: PluginEntityFilter,
+  ): PluginApiReturn<ComponentHandle[]>
+
+  /**
+   * List all the furniture in the project, optionally filtered by storey,
+   * building, label, selection state, or region.
+   *
+   * @param filter - an optional {@linkcode PluginEntityFilter}
+   * @returns furniture {@linkcode ComponentHandle}`[]`
+   *
+   * @examplePrompt List all the furniture in the project
+   * @examplePrompt How many furniture items are on this floor?
+   * @examplePrompt Show the furniture inside the selected room
+   * @examplePrompt Which furniture is on storey 2?
+   *
+   * # Example
+   * ```ts
+   * // Furniture whose plan footprint overlaps a room (`overlaps` is plan-only —
+   * // scope the storey too, or furniture stacked on other floors matches)
+   * const [kitchen] = await snaptrude.design.query.listSpaces({ label: "Kitchen" })
+   * if (kitchen) {
+   *   const inKitchen = await snaptrude.design.query.listFurniture({
+   *     overlaps: kitchen,
+   *     storeys: [1],
+   *   })
+   * }
+   * ```
+   */
+  public abstract listFurniture(
+    filter?: PluginEntityFilter,
+  ): PluginApiReturn<ComponentHandle[]>
+
+  /**
+   * List all the reference lines in the project, optionally filtered by storey,
+   * building, or region.
+   *
+   * @param filter - an optional {@linkcode PluginEntityFilter}
+   * @returns reference-line {@linkcode ComponentHandle}`[]`
+   *
+   * @examplePrompt List all the reference lines in the model
+   * @examplePrompt Show the guide lines on the ground floor
+   * @examplePrompt How many reference lines are on this storey?
+   * @examplePrompt Find the setting-out lines in building A
+   *
+   * # Example
+   * ```ts
+   * const groundFloorRefLines = await snaptrude.design.query.listReferenceLines({ storeys: [1] })
+   * ```
+   */
+  public abstract listReferenceLines(
+    filter?: PluginEntityFilter,
+  ): PluginApiReturn<ComponentHandle[]>
+
+  /**
+   * List all the curtain-wall mullions in the project, optionally filtered by
+   * storey, building, selection state, or region.
+   *
+   * @param filter - an optional {@linkcode PluginEntityFilter}
+   * @returns mullion {@linkcode ComponentHandle}`[]`
+   *
+   * @examplePrompt List all the mullions in the curtain wall
+   * @examplePrompt How many mullions are on the facade?
+   * @examplePrompt Show every curtain wall mullion on level 5
+   * @examplePrompt Which mullions are currently selected?
+   *
+   * # Example
+   * ```ts
+   * const level5Mullions = await snaptrude.design.query.listMullions({ storeys: [5] })
+   * ```
+   */
+  public abstract listMullions(
+    filter?: PluginEntityFilter,
+  ): PluginApiReturn<ComponentHandle[]>
+
+  /**
+   * List all the structural grids (grid groups) in the project, optionally
+   * filtered by storey, building, selection state, or region.
+   *
+   * @param filter - an optional {@linkcode PluginEntityFilter}
+   * @returns grid-group {@linkcode ComponentHandle}`[]`
+   *
+   * @examplePrompt List all the structural grids in the model
+   * @examplePrompt How many grids are on the ground floor?
+   * @examplePrompt Show the grids on this storey
+   * @examplePrompt Which grids are currently selected?
+   *
+   * # Example
+   * ```ts
+   * const groundFloorGrids = await snaptrude.design.query.listGrids({ storeys: [1] })
+   * ```
+   */
+  public abstract listGrids(
+    filter?: PluginEntityFilter,
+  ): PluginApiReturn<ComponentHandle[]>
+
+  // ── single-entity access & identity ─────────────────────────────────────────
+
+  /**
+   * Look an entity up by id — returns the same handle if it still resolves live,
+   * else `null`. A cheap validity probe (distinct from {@linkcode PluginDesignQueryApi.exists}).
+   *
+   * @param id - the entity id ({@linkcode ComponentHandle}) to look up
+   * @returns the {@linkcode ComponentHandle}, or `null` if it no longer resolves
+   *
+   * @examplePrompt Look up an object by its id
+   * @examplePrompt Does id cmp_42 still point to something in the model?
+   * @examplePrompt Fetch the element with this id
+   * @examplePrompt Check if this saved element id is still valid
+   *
+   * # Example
+   * ```ts
+   * // Persistence round-trip: save a ref now, revalidate it in a later run
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const savedRef = await snaptrude.design.query.getEntityRef(wall)
+   *
+   * // ...later (savedRef restored from plugin storage)...
+   * const stillThere = await snaptrude.design.query.getById(savedRef)
+   * if (stillThere) {
+   *   const props = await snaptrude.design.query.getProperties(stillThere)
+   * }
+   * ```
+   */
+  public abstract getById(
+    id: ComponentHandle,
+  ): PluginApiReturn<ComponentHandle | null>
+
+  /**
+   * Test whether an entity id resolves to a live scene entity.
+   * @param id - the entity id ({@linkcode ComponentHandle}) to look up
+   * @returns `true` if it exists, otherwise `false`
+   *
+   * @examplePrompt Does this element still exist in the scene?
+   * @examplePrompt Check whether the wall I stored earlier is still there
+   * @examplePrompt Is id cmp_42 still valid?
+   * @examplePrompt Verify the object wasn't deleted
+   *
+   * # Example
+   * ```ts
+   * // Guard before acting on a handle that may have been deleted or undone
+   * if (await snaptrude.design.query.exists(wall)) {
+   *   const dx = await snaptrude.core.math.vec3.new(5, 0, 0)
+   *   await snaptrude.design.transform.move([wall], dx)
+   * }
+   * ```
+   */
+  public abstract exists(id: ComponentHandle): PluginApiReturn<boolean>
+
+  /**
+   * Get the kind of BIM entity a handle refers to — wall, door, space, slab,
+   * and so on (its {@linkcode PluginEntityType}).
+   * @param component - the entity's {@linkcode ComponentHandle}
+   * @returns the kind, or `null` if the entity is gone / its type is unknown
+   *
+   * @examplePrompt What kind of element is this?
+   * @examplePrompt Is the selected object a wall or a mass?
+   * @examplePrompt Tell me the type of this component
+   * @examplePrompt What am I looking at — a door, a window, or a panel?
+   *
+   * # Example
+   * ```ts
+   * // Dispatch on what the user selected
+   * const selection = await snaptrude.design.selection.get()
+   * for (const component of selection) {
+   *   const kind = await snaptrude.design.query.getEntityType(component)
+   *   if (kind === "wall") {
+   *     // wall-specific handling
+   *   } else if (kind === "space") {
+   *     // room-specific handling
+   *   }
+   * }
+   * ```
+   */
+  public abstract getEntityType(
+    component: ComponentHandle,
+  ): PluginApiReturn<PluginEntityType | null>
+
+  /**
+   * Get an entity's human label (`room_type` for spaces/masses, else the mesh
+   * label; `""` when unlabelled). The write side is `design.update` (`setLabel`).
+   * @param component - the entity's {@linkcode ComponentHandle}
+   * @returns the label string
+   *
+   * @examplePrompt What is this room called?
+   * @examplePrompt Get the name of the selected object
+   * @examplePrompt Show the label on this wall
+   * @examplePrompt What's the room type of this space?
+   *
+   * # Example
+   * ```ts
+   * // Fuzzy label search (the `label` filter field is exact-match; for
+   * // case-insensitive or partial matches, read labels and compare yourself)
+   * const spaces = await snaptrude.design.query.listSpaces()
+   * const kitchens: typeof spaces = []
+   * for (const space of spaces) {
+   *   const label = await snaptrude.design.query.getLabel(space)
+   *   if (label.toLowerCase().includes("kitchen")) kitchens.push(space)
+   * }
+   * ```
+   */
+  public abstract getLabel(component: ComponentHandle): PluginApiReturn<string>
+
+  /**
+   * Get a serializable, persistable reference to an entity. Under the all-handle
+   * model a {@linkcode ComponentHandle} already IS the ref (raw `Component.id`),
+   * so this is the identity passthrough — provided for API completeness.
+   * @param component - the entity's {@linkcode ComponentHandle}
+   * @returns the entity's {@linkcode ComponentHandle}
+   *
+   * @examplePrompt Give me a reference I can save for this element
+   * @examplePrompt Get a persistent id for the selected wall
+   * @examplePrompt Store a handle to this room so I can find it later
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const savedRef = await snaptrude.design.query.getEntityRef(wall)
+   * // savedRef is a plain string — persist it, then revalidate in a later run
+   * // with snaptrude.design.query.getById(savedRef)
+   * ```
+   */
+  public abstract getEntityRef(
+    component: ComponentHandle,
+  ): PluginApiReturn<ComponentHandle>
+
+  /**
+   * List an entity's direct child entities — for example the doors and windows
+   * hosted in a wall, or the voids (holes, shafts, openings) cut in a slab,
+   * floor, roof or ceiling by `design.create.void`.
+   * @param component - the entity's {@linkcode ComponentHandle}
+   * @returns child {@linkcode ComponentHandle}`[]` (`[]` if none)
+   *
+   * @examplePrompt What's inside this wall — list its doors and windows
+   * @examplePrompt Show the child elements of the selected object
+   * @examplePrompt Which openings belong to this wall?
+   * @examplePrompt List everything nested under this mass
+   * @examplePrompt List all holes in this slab
+   *
+   * # Example
+   * ```ts
+   * // Count the openings hosted in a wall, split by kind
+   * const children = await snaptrude.design.query.listChildren(wall)
+   * let doors = 0
+   * let windows = 0
+   * for (const child of children) {
+   *   const kind = await snaptrude.design.query.getEntityType(child)
+   *   if (kind === "door") doors++
+   *   if (kind === "window") windows++
+   * }
+   * ```
+   */
+  public abstract listChildren(
+    component: ComponentHandle,
+  ): PluginApiReturn<ComponentHandle[]>
+
+  /**
+   * Get an entity's host/parent entity (e.g. the wall a door is cut into, or
+   * the slab, floor, roof or ceiling a void is cut through).
+   * @param component - the entity's {@linkcode ComponentHandle}
+   * @returns the host {@linkcode ComponentHandle}, or `null` if top-level
+   *
+   * @examplePrompt Which wall is this door in?
+   * @examplePrompt Find the parent of the selected window
+   * @examplePrompt What is this element attached to?
+   * @examplePrompt Which wall hosts this window?
+   * @examplePrompt Which slab is this shaft in?
+   *
+   * # Example
+   * ```ts
+   * // From a door up to its host wall, then measure the wall
+   * const [door] = await snaptrude.design.query.listDoors({ isSelected: true })
+   * const hostWall = door ? await snaptrude.design.query.getHost(door) : null
+   * if (hostWall) {
+   *   const m = await snaptrude.design.query.measure(hostWall)
+   *   console.log("wall length:", m?.length)
+   * }
+   * ```
+   */
+  public abstract getHost(
+    component: ComponentHandle,
+  ): PluginApiReturn<ComponentHandle | null>
+
+  // ── property & metric reads ─────────────────────────────────────────────────
+
+  /**
+   * 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`). 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
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const props = await snaptrude.design.query.getProperties(wall)
+   * console.log(props.type, props.storey, props.boundingBox)
+   *
+   * // The record is partial — type-specific fields exist only where they apply
+   * const [room] = await snaptrude.design.query.listSpaces()
+   * const p = await snaptrude.design.query.getProperties(room)
+   * if (p.spaceType === "Room" && p.areaClass === "NET") {
+   *   for (const adj of p.adjacency ?? []) {
+   *     // adj.value: 2 = direct, 1 = indirect/contact, -1 = restricted
+   *     console.log(adj.spaceId, adj.value)
+   *   }
+   * }
+   * ```
+   */
+  public abstract getProperties(
+    component: ComponentHandle,
+  ): PluginApiReturn<PluginEntityProperties>
+
+  /**
+   * 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?
+   *
+   * # Example
+   * ```ts
+   * 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>
+
+  /**
+   * Read a mass's creation-parameter record — the recipe it was built from
+   * (`kind` plus the values that constructor was called with). Present on
+   * masses committed from a `core.geom.create` brep constructor that carries a
+   * recipe: {@linkcode MassParametersRecord} covers the four primitives
+   * (sphere, cylinder, cone, torus), extrusions, revolutions, lofts and sweeps.
+   *
+   * A fillet, chamfer, shell or offset of a recorded solid keeps the record
+   * too: `kind` stays the base constructor and the operation is appended to the
+   * record's `operations` list. Edit any of it with `design.update.parameters`.
+   *
+   * `null` for everything else — drawn masses, imported geometry, booleans,
+   * split parts, `brepFromFaces` / `brepFromMesh`, and results built on a
+   * source that carried no record — and for a mass whose record no longer
+   * matches what is on
+   * screen (a later free-form edit dropped the recipe, or the mass carries a
+   * baked scale). `null` too when the recipe was not recordable: the record
+   * schema has its own caps (a sweep path of at most 512 points, a loft of at
+   * most 32 sections, at most 8 chained `operations`, at most 256 curves in one
+   * profile loop and 64 holes in one contour), and a mass built past one of
+   * them — through a route that does not enforce the matching creator cap —
+   * commits as ordinary geometry carrying no record. The `operations` cap is
+   * the one an agent can walk into by accident: a 9th chained
+   * fillet/chamfer/shell/offset drops the record silently, so the result
+   * commits as ordinary geometry and reads back `null` here. A record is never
+   * reported unless it is still the truth.
+   *
+   * Points and axes come back in **world** coordinates. Pure read — nothing is
+   * created or modified.
+   *
+   * @param component - the mass's {@linkcode ComponentHandle}
+   * @returns the {@linkcode MassParametersRecord}, or `null`
+   *
+   * @examplePrompt What radius is this sphere?
+   * @examplePrompt Is this mass parametric?
+   * @examplePrompt Read back the dome's creation parameters
+   * @examplePrompt How tall was this cylinder made?
+   *
+   * # Example
+   * ```ts
+   * const [mass] = await snaptrude.design.query.listMasses({ isSelected: true })
+   * const params = await snaptrude.design.query.getParameters(mass)
+   * if (params?.kind === "sphere") console.log("radius:", params.values.radius)
+   * ```
+   */
+  public abstract getParameters(
+    component: ComponentHandle,
+  ): PluginApiReturn<MassParametersRecord | null>
+
+  /**
+   * Get the **union** axis-aligned bounding box enclosing a set of entities.
+   *
+   * @param components - the set of entity {@linkcode ComponentHandle}s
+   * @returns the union {@linkcode BBoxComponents}, or `null` if the set is empty /
+   *   none resolve
+   *
+   * @examplePrompt Get the bounding box around the selected objects
+   * @examplePrompt What is the overall extent of these walls?
+   * @examplePrompt How big is the region these elements cover together?
+   * @examplePrompt Find the combined extents of everything on level 2
+   *
+   * # Example
+   * ```ts
+   * const walls = await snaptrude.design.query.listWalls()
+   * const box = await snaptrude.design.query.getBoundingBox(walls)
+   *
+   * // Compose with the `within` filter: everything in the selection's extents
+   * const selection = await snaptrude.design.selection.get()
+   * const extents = await snaptrude.design.query.getBoundingBox(selection)
+   * if (extents) {
+   *   const nearby = await snaptrude.design.query.listEntities({ within: extents })
+   *   const width = extents.max.x - extents.min.x
+   * }
+   * ```
+   */
+  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"
+export * from "./grids"