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

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

@@ -1,319 +1,319 @@
-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.
- * {@linkcode PluginDesignQueryGeometryApi.getTriangulatedMeshes} is the
- * handle-free exception: it returns `{ meshes }` — the triangulated render
- * meshes as plain world-space arrays, wrapped in an object, never bare.
- *
- * 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.
-   *
-   * **Frame.** By default the brep comes back in the component's own LOCAL frame
-   * (its vertices are relative to the mesh origin, exactly as stored). This is
-   * the long-standing default, and existing callers rely on it. Pass
-   * `{ frame: "world" }` to get the same solid placed where it sits in the
-   * scene (world coordinates, like
-   * `getBottomContour` / `getTriangulatedMeshes` and every `design.query.measure`
-   * read). Use `"world"` whenever the handle will be COMBINED with other scene
-   * geometry or committed back beside its source: booleans between two scene
-   * masses, `brepFromFillet` / `brepFromShell` / `brepFromOffset` /
-   * `brepFromChamfer` on a scene mass followed by `massFromBrep`, or comparing
-   * its vertices with a bounding box. A world-frame handle from a parametrically
-   * live mass also carries that mass's recipe, so an operation result keeps an
-   * editable record.
-   *
-   * @param component - The scene component to read
-   * @param options - `frame`: `"local"` (default, mesh-local coordinates) or `"world"` (scene coordinates)
-   * @returns The brep as a {@linkcode BrepHandle}, or `null` if the component has no brep geometry — also `null` for a parametric family: read `design.family.getParameters({ component }).parts[].brep`
-   *
-   * @examplePrompt Get the 3D solid geometry of the selected wall
-   * @examplePrompt Round the top rim of this column and put it back where it is
-   * @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)
-   * }
-   *
-   * // Operate on a scene mass and commit the result where the mass sits:
-   * const placed = await snaptrude.design.query.geometry.getBrep(mass, { frame: "world" })
-   * const rounded = await snaptrude.core.geom.create.brepFromFillet(placed, edges, 0.2)
-   * await snaptrude.design.create.massFromBrep(rounded, "Rounded")
-   * ```
-   */
-  public abstract getBrep(
-    component: ComponentHandle,
-    options?: PluginDesignQueryGeometryGetBrepOptions,
-  ): 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>
-
-  /**
-   * Get the **triangulated render meshes** of scene components as plain,
-   * serializable arrays — flat world-space vertex `positions` (`[x0, y0, z0,
-   * x1, …]`) and triangle `indices` (three per triangle), one record per
-   * requested component. The result is `{ meshes }`, not a bare array —
-   * destructure it before iterating.
-   *
-   * Unlike the other `geometry.*` reads this does NOT mint kernel handles — the
-   * raw arrays cross the boundary directly, ready for export, custom analysis,
-   * or feeding an external renderer. Positions are **always world-space**
-   * (instance/transform baked in; there is no local-coordinates mode) in plan
-   * units — no conversion needed. Raw doubles, unrounded.
-   *
-   * With `includeMaterialIds: true` each record also carries `materialIds`: one
-   * entry **per triangle** (`indices.length / 3` entries), the material *name*
-   * painted on that triangle, or `null` for unpainted/default faces.
-   *
-   * With `includeFaceIndices: true` each record also carries `faceIds`: one
-   * entry **per triangle** (input order), the B-rep face index owning that
-   * triangle (same ids as {@linkcode getBrep} faces), or `null` where there is
-   * no provenance. Non-B-rep meshes (Revit imports, generic models, furniture)
-   * yield all-`null` rather than an error.
-   *
-   * A resolvable component with no readable mesh geometry yields
-   * `{ id, positions: [], indices: [] }` — nothing is silently omitted.
-   *
-   * The call is capped at **500 000 triangles total**; over the cap it throws a
-   * `VALIDATION` error whose message includes the actual total — split the
-   * component list into smaller batches and call again.
-   *
-   * @param components - The scene components to triangulate
-   * @param options - `includeMaterialIds` adds the per-triangle material names;
-   *   `includeFaceIndices` adds the per-triangle B-rep face indices
-   * @returns `{ meshes }` — one {@linkcode PluginTriangulatedMesh} per requested
-   *   component, in input order
-   * @throws `HANDLE_INVALID` if any component handle is gone/forged;
-   *   `VALIDATION` if the combined mesh exceeds 500 000 triangles
-   *
-   * @examplePrompt Export the selected masses as a triangle mesh
-   * @examplePrompt Get the raw vertices and triangles of this wall in world coordinates
-   * @examplePrompt Give me the triangulated geometry of every space with its materials
-   * @examplePrompt Compute the surface area of this roof from its triangles
-   *
-   * @example
-   * ```ts
-   * const spaces = await snaptrude.design.query.listSpaces()
-   * const { meshes } = await snaptrude.design.query.geometry.getTriangulatedMeshes(spaces, {
-   *   includeMaterialIds: true,
-   * })
-   * for (const mesh of meshes) {
-   *   const triangleCount = mesh.indices.length / 3
-   *   console.log(mesh.id, triangleCount, mesh.materialIds?.[0])
-   * }
-   * ```
-   */
-  public abstract getTriangulatedMeshes(
-    components: ComponentHandle[],
-    options?: PluginDesignQueryGeometryGetTriangulatedMeshesArgs["options"],
-  ): PluginApiReturn<PluginDesignQueryGeometryGetTriangulatedMeshesResult>
-}
-
-/**
- * Arguments for {@linkcode PluginDesignQueryGeometryApi.getBrep}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `component` | {@linkcode ComponentHandle} | The scene component to read |
- */
-/** Options for {@linkcode PluginDesignQueryGeometryApi.getBrep}: `frame` defaults to `"local"`. */
-export type PluginDesignQueryGeometryGetBrepOptions = { frame?: "local" | "world" }
-export const PluginDesignQueryGeometryGetBrepOptions: z.ZodType<
-  PluginDesignQueryGeometryGetBrepOptions,
-  PluginDesignQueryGeometryGetBrepOptions
-> = z.object({ frame: z.enum(["local", "world"]).optional() })
-
-export const PluginDesignQueryGeometryGetBrepArgs = z.object({
-  component: ComponentHandle,
-  options: PluginDesignQueryGeometryGetBrepOptions.optional(),
-})
-
-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
->
-
-/**
- * One component's triangulated world-space mesh, as plain serializable arrays
- * (no handles).
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `id` | `string` | The component's id (its {@linkcode ComponentHandle} token) |
- * | `positions` | `number[]` | Flat world-space vertex coordinates `[x0, y0, z0, x1, …]`, plan units, raw doubles |
- * | `indices` | `number[]` | Triangle vertex indices, three per triangle, into `positions / 3` |
- * | `materialIds` | `(string \| null)[]` _(optional)_ | One entry per triangle: the painted material's name, `null` for unpainted/default faces. Present only when requested via `includeMaterialIds` |
- * | `faceIds` | `(number \| null)[]` _(optional)_ | One entry per triangle: the B-rep face index owning it (same ids as {@linkcode PluginDesignQueryGeometryApi.getBrep} faces), `null` where there is no provenance (non-B-rep mesh). Present only when requested via `includeFaceIndices` |
- */
-export const PluginTriangulatedMesh = z.object({
-  id: z.string(),
-  positions: z.array(z.number()),
-  indices: z.array(z.number()),
-  materialIds: z.array(z.string().nullable()).optional(),
-  faceIds: z.array(z.number().nullable()).optional(),
-})
-
-export type PluginTriangulatedMesh = z.infer<typeof PluginTriangulatedMesh>
-
-/**
- * Arguments for {@linkcode PluginDesignQueryGeometryApi.getTriangulatedMeshes}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `components` | {@linkcode ComponentHandle}`[]` | The scene components to triangulate |
- * | `options.includeMaterialIds` | `boolean` _(optional)_ | Also return the per-triangle material names |
- * | `options.includeFaceIndices` | `boolean` _(optional)_ | Also return the per-triangle B-rep face indices |
- */
-export const PluginDesignQueryGeometryGetTriangulatedMeshesArgs = z.object({
-  components: z.array(ComponentHandle),
-  options: z
-    .object({
-      includeMaterialIds: z.boolean().optional(),
-      includeFaceIndices: z.boolean().optional(),
-    })
-    .optional(),
-})
-
-export type PluginDesignQueryGeometryGetTriangulatedMeshesArgs = z.infer<
-  typeof PluginDesignQueryGeometryGetTriangulatedMeshesArgs
->
-
-/**
- * Result of {@linkcode PluginDesignQueryGeometryApi.getTriangulatedMeshes}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `meshes` | {@linkcode PluginTriangulatedMesh}`[]` | One record per requested component, in input order |
- */
-export const PluginDesignQueryGeometryGetTriangulatedMeshesResult = z.object({
-  meshes: z.array(PluginTriangulatedMesh),
-})
-
-export type PluginDesignQueryGeometryGetTriangulatedMeshesResult = z.infer<
-  typeof PluginDesignQueryGeometryGetTriangulatedMeshesResult
->
+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.
+ * {@linkcode PluginDesignQueryGeometryApi.getTriangulatedMeshes} is the
+ * handle-free exception: it returns `{ meshes }` — the triangulated render
+ * meshes as plain world-space arrays, wrapped in an object, never bare.
+ *
+ * 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.
+   *
+   * **Frame.** By default the brep comes back in the component's own LOCAL frame
+   * (its vertices are relative to the mesh origin, exactly as stored). This is
+   * the long-standing default, and existing callers rely on it. Pass
+   * `{ frame: "world" }` to get the same solid placed where it sits in the
+   * scene (world coordinates, like
+   * `getBottomContour` / `getTriangulatedMeshes` and every `design.query.measure`
+   * read). Use `"world"` whenever the handle will be COMBINED with other scene
+   * geometry or committed back beside its source: booleans between two scene
+   * masses, `brepFromFillet` / `brepFromShell` / `brepFromOffset` /
+   * `brepFromChamfer` on a scene mass followed by `massFromBrep`, or comparing
+   * its vertices with a bounding box. A world-frame handle from a parametrically
+   * live mass also carries that mass's recipe, so an operation result keeps an
+   * editable record.
+   *
+   * @param component - The scene component to read
+   * @param options - `frame`: `"local"` (default, mesh-local coordinates) or `"world"` (scene coordinates)
+   * @returns The brep as a {@linkcode BrepHandle}, or `null` if the component has no brep geometry — also `null` for a parametric family: read `design.family.getParameters({ component }).parts[].brep`
+   *
+   * @examplePrompt Get the 3D solid geometry of the selected wall
+   * @examplePrompt Round the top rim of this column and put it back where it is
+   * @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)
+   * }
+   *
+   * // Operate on a scene mass and commit the result where the mass sits:
+   * const placed = await snaptrude.design.query.geometry.getBrep(mass, { frame: "world" })
+   * const rounded = await snaptrude.core.geom.create.brepFromFillet(placed, edges, 0.2)
+   * await snaptrude.design.create.massFromBrep(rounded, "Rounded")
+   * ```
+   */
+  public abstract getBrep(
+    component: ComponentHandle,
+    options?: PluginDesignQueryGeometryGetBrepOptions,
+  ): 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>
+
+  /**
+   * Get the **triangulated render meshes** of scene components as plain,
+   * serializable arrays — flat world-space vertex `positions` (`[x0, y0, z0,
+   * x1, …]`) and triangle `indices` (three per triangle), one record per
+   * requested component. The result is `{ meshes }`, not a bare array —
+   * destructure it before iterating.
+   *
+   * Unlike the other `geometry.*` reads this does NOT mint kernel handles — the
+   * raw arrays cross the boundary directly, ready for export, custom analysis,
+   * or feeding an external renderer. Positions are **always world-space**
+   * (instance/transform baked in; there is no local-coordinates mode) in plan
+   * units — no conversion needed. Raw doubles, unrounded.
+   *
+   * With `includeMaterialIds: true` each record also carries `materialIds`: one
+   * entry **per triangle** (`indices.length / 3` entries), the material *name*
+   * painted on that triangle, or `null` for unpainted/default faces.
+   *
+   * With `includeFaceIndices: true` each record also carries `faceIds`: one
+   * entry **per triangle** (input order), the B-rep face index owning that
+   * triangle (same ids as {@linkcode getBrep} faces), or `null` where there is
+   * no provenance. Non-B-rep meshes (Revit imports, generic models, furniture)
+   * yield all-`null` rather than an error.
+   *
+   * A resolvable component with no readable mesh geometry yields
+   * `{ id, positions: [], indices: [] }` — nothing is silently omitted.
+   *
+   * The call is capped at **500 000 triangles total**; over the cap it throws a
+   * `VALIDATION` error whose message includes the actual total — split the
+   * component list into smaller batches and call again.
+   *
+   * @param components - The scene components to triangulate
+   * @param options - `includeMaterialIds` adds the per-triangle material names;
+   *   `includeFaceIndices` adds the per-triangle B-rep face indices
+   * @returns `{ meshes }` — one {@linkcode PluginTriangulatedMesh} per requested
+   *   component, in input order
+   * @throws `HANDLE_INVALID` if any component handle is gone/forged;
+   *   `VALIDATION` if the combined mesh exceeds 500 000 triangles
+   *
+   * @examplePrompt Export the selected masses as a triangle mesh
+   * @examplePrompt Get the raw vertices and triangles of this wall in world coordinates
+   * @examplePrompt Give me the triangulated geometry of every space with its materials
+   * @examplePrompt Compute the surface area of this roof from its triangles
+   *
+   * @example
+   * ```ts
+   * const spaces = await snaptrude.design.query.listSpaces()
+   * const { meshes } = await snaptrude.design.query.geometry.getTriangulatedMeshes(spaces, {
+   *   includeMaterialIds: true,
+   * })
+   * for (const mesh of meshes) {
+   *   const triangleCount = mesh.indices.length / 3
+   *   console.log(mesh.id, triangleCount, mesh.materialIds?.[0])
+   * }
+   * ```
+   */
+  public abstract getTriangulatedMeshes(
+    components: ComponentHandle[],
+    options?: PluginDesignQueryGeometryGetTriangulatedMeshesArgs["options"],
+  ): PluginApiReturn<PluginDesignQueryGeometryGetTriangulatedMeshesResult>
+}
+
+/**
+ * Arguments for {@linkcode PluginDesignQueryGeometryApi.getBrep}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `component` | {@linkcode ComponentHandle} | The scene component to read |
+ */
+/** Options for {@linkcode PluginDesignQueryGeometryApi.getBrep}: `frame` defaults to `"local"`. */
+export type PluginDesignQueryGeometryGetBrepOptions = { frame?: "local" | "world" }
+export const PluginDesignQueryGeometryGetBrepOptions: z.ZodType<
+  PluginDesignQueryGeometryGetBrepOptions,
+  PluginDesignQueryGeometryGetBrepOptions
+> = z.object({ frame: z.enum(["local", "world"]).optional() })
+
+export const PluginDesignQueryGeometryGetBrepArgs = z.object({
+  component: ComponentHandle,
+  options: PluginDesignQueryGeometryGetBrepOptions.optional(),
+})
+
+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
+>
+
+/**
+ * One component's triangulated world-space mesh, as plain serializable arrays
+ * (no handles).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The component's id (its {@linkcode ComponentHandle} token) |
+ * | `positions` | `number[]` | Flat world-space vertex coordinates `[x0, y0, z0, x1, …]`, plan units, raw doubles |
+ * | `indices` | `number[]` | Triangle vertex indices, three per triangle, into `positions / 3` |
+ * | `materialIds` | `(string \| null)[]` _(optional)_ | One entry per triangle: the painted material's name, `null` for unpainted/default faces. Present only when requested via `includeMaterialIds` |
+ * | `faceIds` | `(number \| null)[]` _(optional)_ | One entry per triangle: the B-rep face index owning it (same ids as {@linkcode PluginDesignQueryGeometryApi.getBrep} faces), `null` where there is no provenance (non-B-rep mesh). Present only when requested via `includeFaceIndices` |
+ */
+export const PluginTriangulatedMesh = z.object({
+  id: z.string(),
+  positions: z.array(z.number()),
+  indices: z.array(z.number()),
+  materialIds: z.array(z.string().nullable()).optional(),
+  faceIds: z.array(z.number().nullable()).optional(),
+})
+
+export type PluginTriangulatedMesh = z.infer<typeof PluginTriangulatedMesh>
+
+/**
+ * Arguments for {@linkcode PluginDesignQueryGeometryApi.getTriangulatedMeshes}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode ComponentHandle}`[]` | The scene components to triangulate |
+ * | `options.includeMaterialIds` | `boolean` _(optional)_ | Also return the per-triangle material names |
+ * | `options.includeFaceIndices` | `boolean` _(optional)_ | Also return the per-triangle B-rep face indices |
+ */
+export const PluginDesignQueryGeometryGetTriangulatedMeshesArgs = z.object({
+  components: z.array(ComponentHandle),
+  options: z
+    .object({
+      includeMaterialIds: z.boolean().optional(),
+      includeFaceIndices: z.boolean().optional(),
+    })
+    .optional(),
+})
+
+export type PluginDesignQueryGeometryGetTriangulatedMeshesArgs = z.infer<
+  typeof PluginDesignQueryGeometryGetTriangulatedMeshesArgs
+>
+
+/**
+ * Result of {@linkcode PluginDesignQueryGeometryApi.getTriangulatedMeshes}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `meshes` | {@linkcode PluginTriangulatedMesh}`[]` | One record per requested component, in input order |
+ */
+export const PluginDesignQueryGeometryGetTriangulatedMeshesResult = z.object({
+  meshes: z.array(PluginTriangulatedMesh),
+})
+
+export type PluginDesignQueryGeometryGetTriangulatedMeshesResult = z.infer<
+  typeof PluginDesignQueryGeometryGetTriangulatedMeshesResult
+>