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

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

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

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

@@ -1,275 +1,275 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../../types"
-import { ComponentHandle, ContourHandle } from "../../../handles"
-import { PluginSpaceGetProperty, PluginSpaceGetResult } from "../../entity/space"
-
-/**
- * `design.query.spaces.*` — space-specific reads (a space is a room mass).
- *
- * Only the space queries feasible against the engine today are exposed here.
- * `getFloor` / `listBoundingWalls` (space↔wall topology) are deferred — they need
- * engine work that does not exist yet. `listAdjacent` stays deferred because the
- * shipped surfaces already answer it with value semantics: per-space via the
- * `adjacency` field of `design.query.getProperties`, in bulk via
- * `program.adjacency.getMatrix`.
- *
- * Accessed via `snaptrude.design.query.spaces`.
- */
-export abstract class PluginDesignQuerySpacesApi {
-  constructor() {}
-
-  /**
-   * Get selected properties of a space — the selective multi-property read.
-   *
-   * Only the properties listed in `properties` are returned — unlisted
-   * properties will be `undefined` in the result. This is the canonical home of
-   * the read formerly at `entity.space.get` (now deprecated). Adjacency is not
-   * part of this read — it is an entity property: read it via the `adjacency`
-   * field of {@linkcode PluginDesignQueryApi.getProperties}.
-   *
-   * @param space - The space (room mass) to read
-   * @param properties - Array of property names to retrieve. See
-   *   {@linkcode PluginDesignQuerySpacesGetProperty} for available values.
-   * @returns A partial {@linkcode PluginDesignQuerySpacesGetResult} containing only
-   *   the requested properties
-   * @throws If the space does not exist or the component is not a space/mass
-   *
-   * @examplePrompt What is the area of this room?
-   * @examplePrompt Get the name, storey and height of the selected space
-   * @examplePrompt Which department does this room belong to?
-   * @examplePrompt Where is this space positioned on the plan?
-   * @examplePrompt Read the room type and dimensions of the selected room
-   *
-   * # Example
-   * ```ts
-   * const [space] = await snaptrude.design.query.listSpaces()
-   * const info = await snaptrude.design.query.spaces.get(space, ["name", "area", "position"])
-   * console.log(info.name, info.area, info.position)
-   * ```
-   */
-  public abstract get(
-    space: ComponentHandle,
-    properties: PluginDesignQuerySpacesGetArgs["properties"],
-  ): PluginApiReturn<PluginDesignQuerySpacesGetResult>
-
-  /**
-   * Get the **footprint** of a space — its bottom-face contour (outer profile +
-   * holes) as a reusable {@linkcode ContourHandle}. Equivalent to
-   * {@linkcode PluginDesignQueryGeometryApi.getBottomContour} narrowed to spaces.
-   *
-   * @param space - The space (room mass) to read
-   * @returns the footprint {@linkcode ContourHandle}, or `null` if the space has
-   *   no extractable footprint
-   *
-   * @examplePrompt Get the footprint of this room
-   * @examplePrompt Trace the floor outline of the selected space
-   * @examplePrompt What is the plan boundary of this room, including any holes?
-   * @examplePrompt Give me the base profile of the selected room mass
-   *
-   * # Example
-   * ```ts
-   * const [space] = await snaptrude.design.query.listSpaces()
-   * const footprint = await snaptrude.design.query.spaces.getFootprint(space)
-   * ```
-   */
-  public abstract getFootprint(
-    space: ComponentHandle,
-  ): PluginApiReturn<ContourHandle | null>
-
-  /**
-   * Get the **enclosure** of a space — the floor and ceiling that cap it, the
-   * bounding walls around it (with each wall's door/window openings), and the
-   * neighbouring spaces it shares a boundary with.
-   *
-   * **Geometric v1 — best effort.** The engine has no persisted space→surface
-   * topology, so this read is derived purely from *plan geometry*: the space
-   * footprint is matched against the plan footprints/baselines of the slabs and
-   * walls on the same storey. Consequences a caller must account for:
-   *
-   * - `faceIndices` is **always `[]`**. The triangle→B-rep-face provenance that
-   *   would populate it is a separate engine capability that does not exist yet;
-   *   read a surface's full geometry via
-   *   {@linkcode PluginDesignQueryGeometryApi.getBrep} on its `component` instead.
-   * - After heavy edits (move / stretch / boolean) or on imported models the plan
-   *   match can miss or mis-attribute a surface — treat the result as advisory,
-   *   not authoritative.
-   * - `adjacentSpaces` comes from the same adjacency data as
-   *   {@linkcode PluginProgramAdjacencyApi.getMatrix} (so the two agree on which
-   *   spaces neighbour). `sharedEdgeLength` is `0` because that data exposes no
-   *   edge length, and `sharedSurface` is the common boundary wall only when one
-   *   is found geometrically (else `null`).
-   *
-   * Read-only; never mutates the model.
-   *
-   * @param space - The space (room mass) to read
-   * @returns the {@linkcode PluginSpaceEnclosure}, or `null` when `space` is not a
-   *   space (room mass) or has no extractable plan footprint
-   *
-   * @examplePrompt What walls, floor and ceiling enclose this room?
-   * @examplePrompt Which of this room's walls are external?
-   * @examplePrompt List the doors and windows around the selected space
-   * @examplePrompt Which spaces are adjacent to this room, and through which wall?
-   *
-   * # Example
-   * ```ts
-   * const [space] = await snaptrude.design.query.listSpaces()
-   * const enclosure = await snaptrude.design.query.spaces.getEnclosure(space)
-   * if (enclosure) {
-   *   const walls = enclosure.surfaces.filter((s) => s.role === "wall")
-   *   const external = walls.filter((s) => s.isExternal)
-   *   console.log(`${walls.length} walls, ${external.length} external`)
-   * }
-   * ```
-   */
-  public abstract getEnclosure(
-    space: ComponentHandle,
-  ): PluginApiReturn<PluginSpaceEnclosure | null>
-}
-
-/**
- * Arguments for {@linkcode PluginDesignQuerySpacesApi.getFootprint}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `space` | {@linkcode ComponentHandle} | The space (room mass) to read |
- */
-export const PluginDesignQueryGetFootprintArgs = z.object({
-  space: ComponentHandle,
-})
-export type PluginDesignQueryGetFootprintArgs = z.infer<
-  typeof PluginDesignQueryGetFootprintArgs
->
-
-/**
- * Property names readable via {@linkcode PluginDesignQuerySpacesApi.get} — the
- * legacy {@linkcode PluginSpaceGetProperty} set minus `"adjacency"` (adjacency is
- * an entity property: see the `adjacency` field of
- * {@linkcode PluginDesignQueryApi.getProperties}).
- */
-export const PluginDesignQuerySpacesGetProperty =
-  PluginSpaceGetProperty.exclude(["adjacency"])
-export type PluginDesignQuerySpacesGetProperty = z.infer<
-  typeof PluginDesignQuerySpacesGetProperty
->
-
-/**
- * Arguments for {@linkcode PluginDesignQuerySpacesApi.get}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `space` | {@linkcode ComponentHandle} | The space (room mass) to read |
- * | `properties` | {@linkcode PluginDesignQuerySpacesGetProperty}`[]` | Properties to retrieve |
- */
-export const PluginDesignQuerySpacesGetArgs = z.object({
-  space: ComponentHandle,
-  properties: z.array(PluginDesignQuerySpacesGetProperty),
-})
-export type PluginDesignQuerySpacesGetArgs = z.infer<
-  typeof PluginDesignQuerySpacesGetArgs
->
-
-/**
- * Result of {@linkcode PluginDesignQuerySpacesApi.get} — the legacy
- * {@linkcode PluginSpaceGetResult} record minus `adjacency`. Partial: only the
- * requested properties are present.
- */
-export const PluginDesignQuerySpacesGetResult = PluginSpaceGetResult.omit({
-  adjacency: true,
-})
-export type PluginDesignQuerySpacesGetResult = z.infer<
-  typeof PluginDesignQuerySpacesGetResult
->
-
-/**
- * Arguments for {@linkcode PluginDesignQuerySpacesApi.getEnclosure}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `space` | {@linkcode ComponentHandle} | The space (room mass) to read |
- */
-export const PluginDesignQuerySpacesGetEnclosureArgs = z.object({
-  space: ComponentHandle,
-})
-export type PluginDesignQuerySpacesGetEnclosureArgs = z.infer<
-  typeof PluginDesignQuerySpacesGetEnclosureArgs
->
-
-/**
- * The role a bounding surface plays in a {@linkcode PluginSpaceEnclosure}:
- * `"floor"` (slab below), `"ceiling"` (slab/roof above), or `"wall"`.
- */
-export const PluginEnclosureRole = z.enum(["floor", "ceiling", "wall"])
-export type PluginEnclosureRole = z.infer<typeof PluginEnclosureRole>
-
-/** The kind of opening hosted in a bounding wall. */
-export const PluginEnclosureOpeningKind = z.enum(["door", "window", "void"])
-export type PluginEnclosureOpeningKind = z.infer<
-  typeof PluginEnclosureOpeningKind
->
-
-/**
- * One opening (door / window / void) in a bounding wall.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `kind` | {@linkcode PluginEnclosureOpeningKind} | `"door"`, `"window"`, or `"void"` |
- * | `component` | {@linkcode ComponentHandle} | The opening entity |
- */
-export const PluginEnclosureOpening = z.object({
-  kind: PluginEnclosureOpeningKind,
-  component: ComponentHandle,
-})
-export type PluginEnclosureOpening = z.infer<typeof PluginEnclosureOpening>
-
-/**
- * One bounding surface of a space's enclosure.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `role` | {@linkcode PluginEnclosureRole} | `"floor"`, `"ceiling"`, or `"wall"` |
- * | `component` | {@linkcode ComponentHandle} | The wall / slab / roof entity |
- * | `faceIndices` | `number[]` | B-rep face indices facing the space. **Always `[]` in geometric v1** (no triangle→face provenance yet) |
- * | `isExternal` | `boolean` | No space on the other side — for a wall, no other room bounds it; for a floor/ceiling, no room caps the storey below/above |
- * | `openings` | {@linkcode PluginEnclosureOpening}`[]` | Doors/windows/voids in the surface (walls only; `[]` for floor/ceiling in v1) |
- */
-export const PluginEnclosureSurface = z.object({
-  role: PluginEnclosureRole,
-  component: ComponentHandle,
-  faceIndices: z.array(z.number()),
-  isExternal: z.boolean(),
-  openings: z.array(PluginEnclosureOpening),
-})
-export type PluginEnclosureSurface = z.infer<typeof PluginEnclosureSurface>
-
-/**
- * A space that neighbours the queried space.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `space` | {@linkcode ComponentHandle} | The neighbouring space |
- * | `sharedSurface` | {@linkcode ComponentHandle}` \| null` | The common boundary wall when one is found geometrically, else `null` (e.g. an open-plan or non-physical adjacency) |
- * | `sharedEdgeLength` | `number` | Plan-unit length of the shared boundary — **always `0` in geometric v1** (the adjacency data exposes no edge length) |
- */
-export const PluginAdjacentSpace = z.object({
-  space: ComponentHandle,
-  sharedSurface: ComponentHandle.nullable(),
-  sharedEdgeLength: z.number(),
-})
-export type PluginAdjacentSpace = z.infer<typeof PluginAdjacentSpace>
-
-/**
- * Result of {@linkcode PluginDesignQuerySpacesApi.getEnclosure} — the geometric
- * v1 enclosure of a space.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `space` | {@linkcode ComponentHandle} | The queried space |
- * | `surfaces` | {@linkcode PluginEnclosureSurface}`[]` | Floor + ceiling + bounding walls, as a flat list (any of the three may be absent when no plan match is found) |
- * | `adjacentSpaces` | {@linkcode PluginAdjacentSpace}`[]` | Neighbouring spaces from the adjacency data (`[]` when adjacency was never computed) |
- */
-export const PluginSpaceEnclosure = z.object({
-  space: ComponentHandle,
-  surfaces: z.array(PluginEnclosureSurface),
-  adjacentSpaces: z.array(PluginAdjacentSpace),
-})
-export type PluginSpaceEnclosure = z.infer<typeof PluginSpaceEnclosure>
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { ComponentHandle, ContourHandle } from "../../../handles"
+import { PluginSpaceGetProperty, PluginSpaceGetResult } from "../../entity/space"
+
+/**
+ * `design.query.spaces.*` — space-specific reads (a space is a room mass).
+ *
+ * Only the space queries feasible against the engine today are exposed here.
+ * `getFloor` / `listBoundingWalls` (space↔wall topology) are deferred — they need
+ * engine work that does not exist yet. `listAdjacent` stays deferred because the
+ * shipped surfaces already answer it with value semantics: per-space via the
+ * `adjacency` field of `design.query.getProperties`, in bulk via
+ * `program.adjacency.getMatrix`.
+ *
+ * Accessed via `snaptrude.design.query.spaces`.
+ */
+export abstract class PluginDesignQuerySpacesApi {
+  constructor() {}
+
+  /**
+   * Get selected properties of a space — the selective multi-property read.
+   *
+   * Only the properties listed in `properties` are returned — unlisted
+   * properties will be `undefined` in the result. This is the canonical home of
+   * the read formerly at `entity.space.get` (now deprecated). Adjacency is not
+   * part of this read — it is an entity property: read it via the `adjacency`
+   * field of {@linkcode PluginDesignQueryApi.getProperties}.
+   *
+   * @param space - The space (room mass) to read
+   * @param properties - Array of property names to retrieve. See
+   *   {@linkcode PluginDesignQuerySpacesGetProperty} for available values.
+   * @returns A partial {@linkcode PluginDesignQuerySpacesGetResult} containing only
+   *   the requested properties
+   * @throws If the space does not exist or the component is not a space/mass
+   *
+   * @examplePrompt What is the area of this room?
+   * @examplePrompt Get the name, storey and height of the selected space
+   * @examplePrompt Which department does this room belong to?
+   * @examplePrompt Where is this space positioned on the plan?
+   * @examplePrompt Read the room type and dimensions of the selected room
+   *
+   * # Example
+   * ```ts
+   * const [space] = await snaptrude.design.query.listSpaces()
+   * const info = await snaptrude.design.query.spaces.get(space, ["name", "area", "position"])
+   * console.log(info.name, info.area, info.position)
+   * ```
+   */
+  public abstract get(
+    space: ComponentHandle,
+    properties: PluginDesignQuerySpacesGetArgs["properties"],
+  ): PluginApiReturn<PluginDesignQuerySpacesGetResult>
+
+  /**
+   * Get the **footprint** of a space — its bottom-face contour (outer profile +
+   * holes) as a reusable {@linkcode ContourHandle}. Equivalent to
+   * {@linkcode PluginDesignQueryGeometryApi.getBottomContour} narrowed to spaces.
+   *
+   * @param space - The space (room mass) to read
+   * @returns the footprint {@linkcode ContourHandle}, or `null` if the space has
+   *   no extractable footprint
+   *
+   * @examplePrompt Get the footprint of this room
+   * @examplePrompt Trace the floor outline of the selected space
+   * @examplePrompt What is the plan boundary of this room, including any holes?
+   * @examplePrompt Give me the base profile of the selected room mass
+   *
+   * # Example
+   * ```ts
+   * const [space] = await snaptrude.design.query.listSpaces()
+   * const footprint = await snaptrude.design.query.spaces.getFootprint(space)
+   * ```
+   */
+  public abstract getFootprint(
+    space: ComponentHandle,
+  ): PluginApiReturn<ContourHandle | null>
+
+  /**
+   * Get the **enclosure** of a space — the floor and ceiling that cap it, the
+   * bounding walls around it (with each wall's door/window openings), and the
+   * neighbouring spaces it shares a boundary with.
+   *
+   * **Geometric v1 — best effort.** The engine has no persisted space→surface
+   * topology, so this read is derived purely from *plan geometry*: the space
+   * footprint is matched against the plan footprints/baselines of the slabs and
+   * walls on the same storey. Consequences a caller must account for:
+   *
+   * - `faceIndices` is **always `[]`**. The triangle→B-rep-face provenance that
+   *   would populate it is a separate engine capability that does not exist yet;
+   *   read a surface's full geometry via
+   *   {@linkcode PluginDesignQueryGeometryApi.getBrep} on its `component` instead.
+   * - After heavy edits (move / stretch / boolean) or on imported models the plan
+   *   match can miss or mis-attribute a surface — treat the result as advisory,
+   *   not authoritative.
+   * - `adjacentSpaces` comes from the same adjacency data as
+   *   {@linkcode PluginProgramAdjacencyApi.getMatrix} (so the two agree on which
+   *   spaces neighbour). `sharedEdgeLength` is `0` because that data exposes no
+   *   edge length, and `sharedSurface` is the common boundary wall only when one
+   *   is found geometrically (else `null`).
+   *
+   * Read-only; never mutates the model.
+   *
+   * @param space - The space (room mass) to read
+   * @returns the {@linkcode PluginSpaceEnclosure}, or `null` when `space` is not a
+   *   space (room mass) or has no extractable plan footprint
+   *
+   * @examplePrompt What walls, floor and ceiling enclose this room?
+   * @examplePrompt Which of this room's walls are external?
+   * @examplePrompt List the doors and windows around the selected space
+   * @examplePrompt Which spaces are adjacent to this room, and through which wall?
+   *
+   * # Example
+   * ```ts
+   * const [space] = await snaptrude.design.query.listSpaces()
+   * const enclosure = await snaptrude.design.query.spaces.getEnclosure(space)
+   * if (enclosure) {
+   *   const walls = enclosure.surfaces.filter((s) => s.role === "wall")
+   *   const external = walls.filter((s) => s.isExternal)
+   *   console.log(`${walls.length} walls, ${external.length} external`)
+   * }
+   * ```
+   */
+  public abstract getEnclosure(
+    space: ComponentHandle,
+  ): PluginApiReturn<PluginSpaceEnclosure | null>
+}
+
+/**
+ * Arguments for {@linkcode PluginDesignQuerySpacesApi.getFootprint}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `space` | {@linkcode ComponentHandle} | The space (room mass) to read |
+ */
+export const PluginDesignQueryGetFootprintArgs = z.object({
+  space: ComponentHandle,
+})
+export type PluginDesignQueryGetFootprintArgs = z.infer<
+  typeof PluginDesignQueryGetFootprintArgs
+>
+
+/**
+ * Property names readable via {@linkcode PluginDesignQuerySpacesApi.get} — the
+ * legacy {@linkcode PluginSpaceGetProperty} set minus `"adjacency"` (adjacency is
+ * an entity property: see the `adjacency` field of
+ * {@linkcode PluginDesignQueryApi.getProperties}).
+ */
+export const PluginDesignQuerySpacesGetProperty =
+  PluginSpaceGetProperty.exclude(["adjacency"])
+export type PluginDesignQuerySpacesGetProperty = z.infer<
+  typeof PluginDesignQuerySpacesGetProperty
+>
+
+/**
+ * Arguments for {@linkcode PluginDesignQuerySpacesApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `space` | {@linkcode ComponentHandle} | The space (room mass) to read |
+ * | `properties` | {@linkcode PluginDesignQuerySpacesGetProperty}`[]` | Properties to retrieve |
+ */
+export const PluginDesignQuerySpacesGetArgs = z.object({
+  space: ComponentHandle,
+  properties: z.array(PluginDesignQuerySpacesGetProperty),
+})
+export type PluginDesignQuerySpacesGetArgs = z.infer<
+  typeof PluginDesignQuerySpacesGetArgs
+>
+
+/**
+ * Result of {@linkcode PluginDesignQuerySpacesApi.get} — the legacy
+ * {@linkcode PluginSpaceGetResult} record minus `adjacency`. Partial: only the
+ * requested properties are present.
+ */
+export const PluginDesignQuerySpacesGetResult = PluginSpaceGetResult.omit({
+  adjacency: true,
+})
+export type PluginDesignQuerySpacesGetResult = z.infer<
+  typeof PluginDesignQuerySpacesGetResult
+>
+
+/**
+ * Arguments for {@linkcode PluginDesignQuerySpacesApi.getEnclosure}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `space` | {@linkcode ComponentHandle} | The space (room mass) to read |
+ */
+export const PluginDesignQuerySpacesGetEnclosureArgs = z.object({
+  space: ComponentHandle,
+})
+export type PluginDesignQuerySpacesGetEnclosureArgs = z.infer<
+  typeof PluginDesignQuerySpacesGetEnclosureArgs
+>
+
+/**
+ * The role a bounding surface plays in a {@linkcode PluginSpaceEnclosure}:
+ * `"floor"` (slab below), `"ceiling"` (slab/roof above), or `"wall"`.
+ */
+export const PluginEnclosureRole = z.enum(["floor", "ceiling", "wall"])
+export type PluginEnclosureRole = z.infer<typeof PluginEnclosureRole>
+
+/** The kind of opening hosted in a bounding wall. */
+export const PluginEnclosureOpeningKind = z.enum(["door", "window", "void"])
+export type PluginEnclosureOpeningKind = z.infer<
+  typeof PluginEnclosureOpeningKind
+>
+
+/**
+ * One opening (door / window / void) in a bounding wall.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `kind` | {@linkcode PluginEnclosureOpeningKind} | `"door"`, `"window"`, or `"void"` |
+ * | `component` | {@linkcode ComponentHandle} | The opening entity |
+ */
+export const PluginEnclosureOpening = z.object({
+  kind: PluginEnclosureOpeningKind,
+  component: ComponentHandle,
+})
+export type PluginEnclosureOpening = z.infer<typeof PluginEnclosureOpening>
+
+/**
+ * One bounding surface of a space's enclosure.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `role` | {@linkcode PluginEnclosureRole} | `"floor"`, `"ceiling"`, or `"wall"` |
+ * | `component` | {@linkcode ComponentHandle} | The wall / slab / roof entity |
+ * | `faceIndices` | `number[]` | B-rep face indices facing the space. **Always `[]` in geometric v1** (no triangle→face provenance yet) |
+ * | `isExternal` | `boolean` | No space on the other side — for a wall, no other room bounds it; for a floor/ceiling, no room caps the storey below/above |
+ * | `openings` | {@linkcode PluginEnclosureOpening}`[]` | Doors/windows/voids in the surface (walls only; `[]` for floor/ceiling in v1) |
+ */
+export const PluginEnclosureSurface = z.object({
+  role: PluginEnclosureRole,
+  component: ComponentHandle,
+  faceIndices: z.array(z.number()),
+  isExternal: z.boolean(),
+  openings: z.array(PluginEnclosureOpening),
+})
+export type PluginEnclosureSurface = z.infer<typeof PluginEnclosureSurface>
+
+/**
+ * A space that neighbours the queried space.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `space` | {@linkcode ComponentHandle} | The neighbouring space |
+ * | `sharedSurface` | {@linkcode ComponentHandle}` \| null` | The common boundary wall when one is found geometrically, else `null` (e.g. an open-plan or non-physical adjacency) |
+ * | `sharedEdgeLength` | `number` | Plan-unit length of the shared boundary — **always `0` in geometric v1** (the adjacency data exposes no edge length) |
+ */
+export const PluginAdjacentSpace = z.object({
+  space: ComponentHandle,
+  sharedSurface: ComponentHandle.nullable(),
+  sharedEdgeLength: z.number(),
+})
+export type PluginAdjacentSpace = z.infer<typeof PluginAdjacentSpace>
+
+/**
+ * Result of {@linkcode PluginDesignQuerySpacesApi.getEnclosure} — the geometric
+ * v1 enclosure of a space.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `space` | {@linkcode ComponentHandle} | The queried space |
+ * | `surfaces` | {@linkcode PluginEnclosureSurface}`[]` | Floor + ceiling + bounding walls, as a flat list (any of the three may be absent when no plan match is found) |
+ * | `adjacentSpaces` | {@linkcode PluginAdjacentSpace}`[]` | Neighbouring spaces from the adjacency data (`[]` when adjacency was never computed) |
+ */
+export const PluginSpaceEnclosure = z.object({
+  space: ComponentHandle,
+  surfaces: z.array(PluginEnclosureSurface),
+  adjacentSpaces: z.array(PluginAdjacentSpace),
+})
+export type PluginSpaceEnclosure = z.infer<typeof PluginSpaceEnclosure>