@snaptrude/plugin-core 0.2.9 → 0.5.0

package/src/api/design/index.ts

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

package/src/api/design/lock.ts

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

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

@@ -0,0 +1,301 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { ComponentHandle, MaterialHandle } from "../../../handles"
+
+/**
+ * `snaptrude.design.materials` — the project material library + material assignment.
+ *
+ * Materials are {@linkcode MaterialHandle}s (entity-style, name-addressed). Reads return
+ * a {@linkcode MaterialHandle}/{@linkcode PluginMaterialInfo}; `apply`/`reset` mutate the
+ * scene (undoable via `save`, default `true`). `create` mints a material from a
+ * {@linkcode PluginMaterialSpec} (idempotent by name).
+ *
+ * Face-targeted apply, per-face reads (`listByFace`), and `copy` (needs an undo
+ * wrapper) land in a later pass.
+ */
+export abstract class PluginDesignMaterialsApi {
+  constructor() {}
+
+  /**
+   * List the project materials.
+   * @param scope Which library to list (optional)
+   * @returns The materials as {@linkcode MaterialHandle}`[]`
+   *
+   * @examplePrompt List all the materials in this project
+   * @examplePrompt What materials do I have available to apply?
+   * @examplePrompt Show me the preset materials library
+   * @examplePrompt Which finishes exist in this model?
+   * @examplePrompt Get every material in the project palette
+   *
+   * # Example
+   * ```ts
+   * const presets = await snaptrude.design.materials.list("preset")
+   * console.log(presets.length, "preset materials")
+   * ```
+   */
+  public abstract list(scope?: "project" | "preset"): PluginApiReturn<MaterialHandle[]>
+
+  /**
+   * Read a material's descriptor — its name, color, opacity, and texture
+   * (when it has one).
+   *
+   * @param material The material to read
+   * @returns The {@linkcode PluginMaterialInfo}, or `null` if the material is gone
+   *
+   * @examplePrompt What colour is the Brick material?
+   * @examplePrompt Show me the details of this material
+   * @examplePrompt Get the opacity of the glass finish
+   * @examplePrompt Which texture image does the wood material use?
+   *
+   * # Example
+   * ```ts
+   * const [material] = await snaptrude.design.materials.list()
+   * const info = await snaptrude.design.materials.getInfo(material)
+   * if (info) console.log(info.name, info.colorHex, info.alpha)
+   * ```
+   */
+  public abstract getInfo(material: MaterialHandle): PluginApiReturn<PluginMaterialInfo | null>
+
+  /**
+   * Apply a material to one or more components — an existing project material by
+   * handle, or a new one described inline as a {@linkcode PluginMaterialSpec}.
+   * Undoable when `save` is true (the default).
+   *
+   * @param targets Components to paint
+   * @param material Material handle, or an inline {@linkcode PluginMaterialSpec}
+   * @param save Commit as an undoable command (default `true`)
+   * @returns The number of targets the material was applied to
+   *
+   * @examplePrompt Paint the selected walls red
+   * @examplePrompt Apply the brick material to these walls
+   * @examplePrompt Put a wood finish on the floor
+   * @examplePrompt Change the colour of this room's walls to #ff8800
+   * @examplePrompt Add a concrete texture to the facade
+   *
+   * # Example
+   * ```ts
+   * const walls = await snaptrude.design.query.listWalls({ storeys: [1] })
+   * // inline spec — creates (or reuses by name) a project material, then applies it
+   * const { count } = await snaptrude.design.materials.apply(walls, { name: "Accent Red", color: "#b04a3a" })
+   * console.log("painted", count, "walls")
+   * ```
+   */
+  public abstract apply(
+    targets: ComponentHandle[],
+    material: MaterialHandle | PluginMaterialSpec,
+    save?: boolean
+  ): PluginApiReturn<PluginMaterialResult>
+
+  /**
+   * Reset one or more components back to the default material for their type,
+   * removing any applied finish. The inverse of `apply`; undoable when `save`
+   * is true (the default).
+   *
+   * @param components Components to reset
+   * @param save Commit as an undoable command (default `true`)
+   * @returns The number of components reset
+   *
+   * @examplePrompt Remove the paint from these walls
+   * @examplePrompt Reset the selected objects to their default material
+   * @examplePrompt Clear the custom finish on the floor
+   * @examplePrompt Restore the original colour of this roof
+   *
+   * # Example
+   * ```ts
+   * const selected = await snaptrude.design.selection.get()
+   * const { count } = await snaptrude.design.materials.reset(selected)
+   * console.log("reset", count, "components to their default material")
+   * ```
+   */
+  public abstract reset(
+    components: ComponentHandle[],
+    save?: boolean
+  ): PluginApiReturn<PluginMaterialResult>
+
+  /**
+   * Create a new material in the project from a spec — a color, texture URL,
+   * opacity, and/or name. Idempotent by name: creating with the name of an
+   * existing material returns that material instead of duplicating it.
+   *
+   * @param spec The material construction spec
+   * @returns The new material as a {@linkcode MaterialHandle}
+   *
+   * @examplePrompt Create a new red material called Accent
+   * @examplePrompt Make a material from this texture image URL
+   * @examplePrompt Add a semi-transparent glass material to the project
+   * @examplePrompt Define a dark grey concrete finish I can reuse
+   *
+   * # Example
+   * ```ts
+   * const glass = await snaptrude.design.materials.create({ name: "Frosted Glass", color: "#cfe4e8", alpha: 0.4 })
+   * const walls = await snaptrude.design.query.listWalls({ storeys: [1] })
+   * await snaptrude.design.materials.apply(walls, glass)
+   * ```
+   */
+  public abstract create(spec: PluginMaterialSpec): PluginApiReturn<MaterialHandle>
+
+  /**
+   * Get the default material for a component's type.
+   * @param component The component to look up
+   * @returns The default material as a {@linkcode MaterialHandle}, or `null`
+   *
+   * @examplePrompt What is the default material for walls?
+   * @examplePrompt Get the standard material this floor type uses
+   * @examplePrompt Which material would this roof have out of the box?
+   * @examplePrompt Find the default finish for the selected column
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const defaultMaterial = await snaptrude.design.materials.getDefault(wall)
+   * if (defaultMaterial) console.log(await snaptrude.design.materials.getInfo(defaultMaterial))
+   * ```
+   */
+  public abstract getDefault(component: ComponentHandle): PluginApiReturn<MaterialHandle | null>
+
+  /**
+   * Test whether a component carries its (type) default material.
+   * @param component The component to test
+   * @returns `true` if default, otherwise `false`
+   *
+   * @examplePrompt Is this wall still using its default material?
+   * @examplePrompt Has the material on this floor been changed?
+   * @examplePrompt Check if the selected object still has its original finish
+   * @examplePrompt Tell me whether this roof has been painted or is still standard
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const untouched = await snaptrude.design.materials.isDefault(wall)
+   * console.log(untouched ? "still default" : "has been painted")
+   * ```
+   */
+  public abstract isDefault(component: ComponentHandle): PluginApiReturn<boolean>
+
+  /**
+   * Test whether a component has a single (uniform) material across all faces.
+   * @param component The component to test
+   * @returns `true` if uniform, otherwise `false`
+   *
+   * @examplePrompt Does this wall have the same material on every face?
+   * @examplePrompt Is the floor finished uniformly or face by face?
+   * @examplePrompt Check if this column is a single material all over
+   * @examplePrompt Are any faces of the selected object painted differently?
+   *
+   * # Example
+   * ```ts
+   * const [selected] = await snaptrude.design.selection.get()
+   * const uniform = await snaptrude.design.materials.isUniform(selected)
+   * console.log(uniform ? "one material all over" : "painted per face")
+   * ```
+   */
+  public abstract isUniform(component: ComponentHandle): PluginApiReturn<boolean>
+
+  /**
+   * Test whether a material has a texture.
+   * @param material The material to test
+   * @returns `true` if it has a diffuse texture, otherwise `false`
+   *
+   * @examplePrompt Does this material have a texture image?
+   * @examplePrompt Is the brick material textured or just a flat colour?
+   * @examplePrompt Check whether the wood finish uses an image map
+   * @examplePrompt Tell me if this material is image-based or a plain colour
+   *
+   * # Example
+   * ```ts
+   * const [material] = await snaptrude.design.materials.list()
+   * const textured = await snaptrude.design.materials.hasTexture(material)
+   * console.log(textured ? "image-based" : "flat colour")
+   * ```
+   */
+  public abstract hasTexture(material: MaterialHandle): PluginApiReturn<boolean>
+}
+
+/**
+ * A material's descriptor.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | Material name (== the handle token) |
+ * | `id` | `string` | Engine material id |
+ * | `colorHex` | `string` | Diffuse color as `#rrggbb` |
+ * | `alpha` | `number` | Opacity `0..1` |
+ * | `materialType` | `string` | Material type tag (optional) |
+ * | `textureUrl` | `string` | Diffuse texture URL (optional) |
+ */
+export const PluginMaterialInfo = z.object({
+  name: z.string(),
+  id: z.string(),
+  colorHex: z.string(),
+  alpha: z.number(),
+  materialType: z.string().optional(),
+  textureUrl: z.string().optional(),
+})
+export type PluginMaterialInfo = z.infer<typeof PluginMaterialInfo>
+
+/**
+ * A material construction spec (input DTO — NOT a handle).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | Name (optional; generated if omitted) |
+ * | `color` | `string` | Diffuse color `#rrggbb` (optional) |
+ * | `textureUrl` | `string` | Diffuse texture URL (optional; wins over color) |
+ * | `alpha` | `number` | Opacity `0..1` (optional) |
+ * | `materialType` | `string` | Material type tag (optional) |
+ */
+export const PluginMaterialSpec = z.object({
+  name: z.string().optional(),
+  color: z.string().optional(),
+  textureUrl: z.string().optional(),
+  alpha: z.number().optional(),
+  materialType: z.string().optional(),
+})
+export type PluginMaterialSpec = z.infer<typeof PluginMaterialSpec>
+
+/** Result of a material mutation — the count of targets affected. */
+export const PluginMaterialResult = z.object({ count: z.number() })
+export type PluginMaterialResult = z.infer<typeof PluginMaterialResult>
+
+/** Arguments for {@linkcode PluginDesignMaterialsApi.list}. */
+export const PluginDesignMaterialsListArgs = z.object({
+  scope: z.enum(["project", "preset"]).optional(),
+})
+export type PluginDesignMaterialsListArgs = z.infer<typeof PluginDesignMaterialsListArgs>
+
+/** Arguments for {@linkcode PluginDesignMaterialsApi.getInfo} / `hasTexture`. */
+export const PluginDesignMaterialsGetInfoArgs = z.object({ material: MaterialHandle })
+export type PluginDesignMaterialsGetInfoArgs = z.infer<typeof PluginDesignMaterialsGetInfoArgs>
+
+/** Arguments for component-scoped predicates (`getDefault`/`isDefault`/`isUniform`). */
+export const PluginDesignMaterialsComponentArgs = z.object({ component: ComponentHandle })
+export type PluginDesignMaterialsComponentArgs = z.infer<
+  typeof PluginDesignMaterialsComponentArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginDesignMaterialsApi.apply}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `targets` | {@linkcode ComponentHandle}`[]` | Components to paint |
+ * | `material` | {@linkcode MaterialHandle} \| {@linkcode PluginMaterialSpec} | Material handle, or an inline spec |
+ * | `save` | `boolean` | Commit as an undoable command (default `true`) |
+ */
+export const PluginDesignMaterialsApplyArgs = z.object({
+  targets: z.array(ComponentHandle),
+  material: z.union([MaterialHandle, PluginMaterialSpec]),
+  save: z.boolean().optional(),
+})
+export type PluginDesignMaterialsApplyArgs = z.infer<typeof PluginDesignMaterialsApplyArgs>
+
+/** Arguments for {@linkcode PluginDesignMaterialsApi.reset}. */
+export const PluginDesignMaterialsResetArgs = z.object({
+  components: z.array(ComponentHandle),
+  save: z.boolean().optional(),
+})
+export type PluginDesignMaterialsResetArgs = z.infer<typeof PluginDesignMaterialsResetArgs>
+
+/** Arguments for {@linkcode PluginDesignMaterialsApi.create}. */
+export const PluginDesignMaterialsCreateArgs = z.object({ spec: PluginMaterialSpec })
+export type PluginDesignMaterialsCreateArgs = z.infer<typeof PluginDesignMaterialsCreateArgs>

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

@@ -0,0 +1,166 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../../types"
+import {
+  ComponentHandle,
+  BrepHandle,
+  ContourHandle,
+  CurveHandle,
+} from "../../../../handles"
+
+/**
+ * `snaptrude.design.query.geometry` — read the geometry of scene BIM entities.
+ *
+ * This is the bridge from the BIM/scene layer (`design.*`, keyed by
+ * {@linkcode ComponentHandle}) into the geometry kernel (`core.geom.query.*`,
+ * keyed by value/topology handles). {@linkcode PluginDesignQueryGeometryApi.getBrep}
+ * mints a {@linkcode BrepHandle} for a component's boundary-representation mesh;
+ * {@linkcode PluginDesignQueryGeometryApi.getBottomContour} mints a
+ * {@linkcode ContourHandle} for its footprint outline;
+ * {@linkcode PluginDesignQueryGeometryApi.getCenterline} mints a
+ * {@linkcode CurveHandle} for a wall's core curve.
+ *
+ * Returned handles are session-ephemeral and go stale on undo/redo/re-topologize
+ * — re-fetch a fresh one after edits.
+ */
+export abstract class PluginDesignQueryGeometryApi {
+  constructor() {}
+
+  /**
+   * Get the boundary representation (B-rep) of a scene component — the solid
+   * geometry (faces, edges, vertices) behind a wall, slab, room or any other
+   * scene entity, as a reusable {@linkcode BrepHandle} for the
+   * `core.geom.query.brep.*` reads.
+   *
+   * @param component - The scene component to read
+   * @returns The brep as a {@linkcode BrepHandle}, or `null` if the component has no brep geometry
+   *
+   * @examplePrompt Get the 3D solid geometry of the selected wall
+   * @examplePrompt How many faces does this mass have?
+   * @examplePrompt Inspect the mesh of this slab so I can look at its faces and edges
+   * @examplePrompt Read the vertices of the selected column's geometry
+   *
+   * @example
+   * ```ts
+   * const brep = await snaptrude.design.query.geometry.getBrep(component)
+   * if (brep) {
+   *   const faces = await snaptrude.core.geom.query.brep.listFaces(brep)
+   * }
+   * ```
+   */
+  public abstract getBrep(
+    component: ComponentHandle
+  ): PluginApiReturn<BrepHandle | null>
+
+  /**
+   * Get the **bottom-face contour** of a component — the footprint outline (outer
+   * profile + holes) of its lowest horizontal face, as a reusable
+   * {@linkcode ContourHandle}.
+   *
+   * Extracted from the component's B-rep; robust to inverted face normals. Read
+   * its geometry via `snaptrude.core.geom.query.contour.*`, or feed it back into
+   * `design.create.*` / `core.geom.*`.
+   *
+   * @param component - The scene component to read
+   * @returns the footprint {@linkcode ContourHandle}, or `null` if the component
+   *   has no extractable bottom face (e.g. it carries no B-rep)
+   *
+   * @examplePrompt Get the footprint of the selected mass
+   * @examplePrompt What is the plan outline of this building volume?
+   * @examplePrompt Trace the base profile of this wall
+   * @examplePrompt Find the ground-level outline of the slab, including any openings
+   * @examplePrompt Work out the footprint area of the selected component
+   *
+   * @example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const contour = await snaptrude.design.query.geometry.getBottomContour(wall)
+   * if (contour) {
+   *   const area = await snaptrude.core.geom.query.contour.getArea(contour)
+   * }
+   * ```
+   */
+  public abstract getBottomContour(
+    component: ComponentHandle
+  ): PluginApiReturn<ContourHandle | null>
+
+  /**
+   * Get the **centerline** (core curve) of a wall — the single curve running
+   * down the middle of the wall, as a reusable {@linkcode CurveHandle}
+   * (a `Line` for a straight wall, an `Arc` for a curved wall).
+   *
+   * For a parametric wall this is its stored core curve; otherwise it is
+   * derived from the wall's B-rep bottom face. Read its geometry via
+   * `snaptrude.core.geom.query.curve.*`, or feed it into `design.create.*`.
+   *
+   * Only walls have a centerline. As with all `get*` reads it never throws:
+   * a non-wall component, or a wall with no derivable centerline, yields `null`.
+   *
+   * @param component - The scene component to read (only walls yield a centerline)
+   * @returns the centerline {@linkcode CurveHandle}, or `null` if the component
+   *   is not a wall or the wall has no derivable centerline (e.g. it carries no
+   *   B-rep or has an unsupported profile)
+   *
+   * @examplePrompt Get the centerline of the selected wall
+   * @examplePrompt How long is this wall along its centre line?
+   * @examplePrompt Find the axis running down the middle of this wall
+   * @examplePrompt Give me the core curve of that curved wall
+   * @examplePrompt Where does the wall's centreline start and end?
+   *
+   * @example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const centerline = await snaptrude.design.query.geometry.getCenterline(wall)
+   * if (centerline) {
+   *   const length = await snaptrude.core.geom.query.curve.getLength(centerline)
+   * }
+   * ```
+   */
+  public abstract getCenterline(
+    component: ComponentHandle
+  ): PluginApiReturn<CurveHandle | null>
+}
+
+/**
+ * Arguments for {@linkcode PluginDesignQueryGeometryApi.getBrep}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `component` | {@linkcode ComponentHandle} | The scene component to read |
+ */
+export const PluginDesignQueryGeometryGetBrepArgs = z.object({
+  component: ComponentHandle,
+})
+
+export type PluginDesignQueryGeometryGetBrepArgs = z.infer<
+  typeof PluginDesignQueryGeometryGetBrepArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginDesignQueryGeometryApi.getBottomContour}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `component` | {@linkcode ComponentHandle} | The scene component to read |
+ */
+export const PluginDesignQueryGeometryGetBottomContourArgs = z.object({
+  component: ComponentHandle,
+})
+
+export type PluginDesignQueryGeometryGetBottomContourArgs = z.infer<
+  typeof PluginDesignQueryGeometryGetBottomContourArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginDesignQueryGeometryApi.getCenterline}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `component` | {@linkcode ComponentHandle} | The scene component to read |
+ */
+export const PluginDesignQueryGeometryGetCenterlineArgs = z.object({
+  component: ComponentHandle,
+})
+
+export type PluginDesignQueryGeometryGetCenterlineArgs = z.infer<
+  typeof PluginDesignQueryGeometryGetCenterlineArgs
+>