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

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

@@ -8,32 +8,77 @@ import { ComponentHandle, MaterialHandle } from "../../../handles"
  * 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).
+ * {@linkcode PluginMaterialSpec} (idempotent by name). `list` reads the materials loaded
+ * in the project; `listPresets` reads the browsable preset/library catalog (handle-less
+ * {@linkcode PluginPresetMaterial} records that become materials via `create`/`apply`).
  *
- * Face-targeted apply, per-face reads (`listByFace`), and `copy` (needs an undo
- * wrapper) land in a later pass.
+ * Per-face assignment — {@linkcode PluginDesignMaterialsApi.applyToFaces} /
+ * {@linkcode PluginDesignMaterialsApi.resetFaces} plus per-face reads
+ * ({@linkcode PluginDesignMaterialsApi.getByFace} / {@linkcode PluginDesignMaterialsApi.listByFace})
+ * — targets **BREP faces by durable face index** and is **BREP-only** (furniture,
+ * doors/windows, and Revit imports are rejected) and **visual-only** in v1 (the
+ * per-face finish is not carried into BIM schedules / cost layers). A face index
+ * is durable only while the component's BREP topology (face count/order) is unchanged.
+ *
+ * `copy` (needs an undo wrapper) lands in a later pass.
  */
 export abstract class PluginDesignMaterialsApi {
   constructor() {}
 
   /**
-   * List the project materials.
-   * @param scope Which library to list (optional)
+   * List the materials loaded in the project — every named material in the live
+   * scene (applied finishes, plugin-created materials, and type defaults in use).
+   * For the browsable preset/library catalog (finishes not yet in the project),
+   * use {@linkcode PluginDesignMaterialsApi.listPresets}.
+   *
    * @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")
+   * const materials = await snaptrude.design.materials.list()
+   * console.log(materials.length, "materials in the project")
    * ```
    */
-  public abstract list(scope?: "project" | "preset"): PluginApiReturn<MaterialHandle[]>
+  public abstract list(): PluginApiReturn<MaterialHandle[]>
+
+  /**
+   * List the preset material library — the catalog the app's material browser
+   * shows (the built-in finishes plus the workspace's uploaded materials),
+   * fetched from the material library service. Library entries are **not**
+   * scene materials and carry no {@linkcode MaterialHandle}; each is a named
+   * texture record. To use one, feed it to
+   * {@linkcode PluginDesignMaterialsApi.create} /
+   * {@linkcode PluginDesignMaterialsApi.apply} as a
+   * {@linkcode PluginMaterialSpec}: `{ name, textureUrl, materialType: category }`.
+   *
+   * @returns The library as {@linkcode PluginPresetMaterial}`[]` (`[]` when the
+   * library service is unreachable)
+   *
+   * @examplePrompt Show me the preset materials library
+   * @examplePrompt What wood finishes are available in the material library?
+   * @examplePrompt Browse the material catalog and apply a brick texture
+   * @examplePrompt Which preset materials can I choose from?
+   *
+   * # Example
+   * ```ts
+   * const presets = await snaptrude.design.materials.listPresets()
+   * const brick = presets.find((p) => p.category.toLowerCase().includes("brick"))
+   * if (brick) {
+   *   const walls = await snaptrude.design.query.listWalls()
+   *   await snaptrude.design.materials.apply(walls, {
+   *     name: brick.name,
+   *     textureUrl: brick.textureUrl,
+   *     materialType: brick.category,
+   *   })
+   * }
+   * ```
+   */
+  public abstract listPresets(): PluginApiReturn<PluginPresetMaterial[]>
 
   /**
    * Read a material's descriptor — its name, color, opacity, and texture
@@ -54,7 +99,43 @@ export abstract class PluginDesignMaterialsApi {
    * if (info) console.log(info.name, info.colorHex, info.alpha)
    * ```
    */
-  public abstract getInfo(material: MaterialHandle): PluginApiReturn<PluginMaterialInfo | null>
+  public abstract getInfo(
+    material: MaterialHandle,
+  ): PluginApiReturn<PluginMaterialInfo | null>
+
+  /**
+   * Read the material applied to a component **as a whole** — the eyedropper. For a
+   * uniformly-painted component this is that single material; for a per-face-painted
+   * component it is the material on the component's base/first face. Use
+   * {@linkcode PluginDesignMaterialsApi.getByFace} /
+   * {@linkcode PluginDesignMaterialsApi.listByFace} for the per-face breakdown.
+   *
+   * @param component The component to sample
+   * @returns The whole-object material as a {@linkcode PluginComponentMaterial} — its
+   * handle (chain it into `apply` / `getInfo`), engine id, name, and whether the
+   * component carries its type `default` or an explicitly `applied` finish — or `null`
+   * if the component carries no material
+   *
+   * @examplePrompt What material is on this wall?
+   * @examplePrompt Eyedrop the finish of the selected object
+   * @examplePrompt Which material does this slab use?
+   * @examplePrompt Read the material on this column so I can paint others with it
+   * @examplePrompt Is this component painted, and with what?
+   *
+   * # Example
+   * ```ts
+   * const [component] = await snaptrude.design.selection.get()
+   * const sampled = await snaptrude.design.materials.get(component)
+   * if (sampled) {
+   *   console.log(sampled.name, sampled.source) // e.g. "Brick Red" "applied"
+   *   const info = await snaptrude.design.materials.getInfo(sampled.material)
+   *   console.log(info?.colorHex)
+   * }
+   * ```
+   */
+  public abstract get(
+    component: ComponentHandle,
+  ): PluginApiReturn<PluginComponentMaterial | null>
 
   /**
    * Apply a material to one or more components — an existing project material by
@@ -83,7 +164,7 @@ export abstract class PluginDesignMaterialsApi {
   public abstract apply(
     targets: ComponentHandle[],
     material: MaterialHandle | PluginMaterialSpec,
-    save?: boolean
+    save?: boolean,
   ): PluginApiReturn<PluginMaterialResult>
 
   /**
@@ -109,9 +190,123 @@ export abstract class PluginDesignMaterialsApi {
    */
   public abstract reset(
     components: ComponentHandle[],
-    save?: boolean
+    save?: boolean,
+  ): PluginApiReturn<PluginMaterialResult>
+
+  /**
+   * Paint specific **BREP faces** of a component with a material — an existing
+   * project material by handle, or a new one described inline as a
+   * {@linkcode PluginMaterialSpec}. Faces are addressed by **durable BREP face
+   * index** (their 0-based position in the component's BREP face list).
+   * Undoable when `save` is true (the default).
+   *
+   * Per-face materials are **BREP-only** (walls, floors, slabs, roofs, masses,
+   * columns, beams; furniture, doors/windows, and Revit imports are rejected) and
+   * **visual-only in v1** — the finish is not carried into BIM schedules / cost
+   * layers. A face index is durable only while the BREP topology (face count/order)
+   * is unchanged; a face index at or beyond the face count is rejected.
+   *
+   * @param component The (BREP) component to paint
+   * @param faces BREP face indices to paint (nonnegative integers)
+   * @param material Material handle, or an inline {@linkcode PluginMaterialSpec}
+   * @param save Commit as an undoable command (default `true`)
+   * @returns The number of faces painted
+   *
+   * @examplePrompt Paint the top face of this slab red
+   * @examplePrompt Apply the brick material to faces 0 and 2 of this wall
+   * @examplePrompt Put a wood finish on just the front face of this column
+   * @examplePrompt Colour face 4 of the selected mass with #ff8800
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls({ storeys: [1] })
+   * // faces are addressed by durable 0-based BREP face index
+   * const { count } = await snaptrude.design.materials.applyToFaces(wall, [0, 1], { name: "Accent", color: "#b04a3a" })
+   * console.log("painted", count, "faces")
+   * ```
+   */
+  public abstract applyToFaces(
+    component: ComponentHandle,
+    faces: number[],
+    material: MaterialHandle | PluginMaterialSpec,
+    save?: boolean,
+  ): PluginApiReturn<PluginMaterialResult>
+
+  /**
+   * Reset specific BREP faces of a component back to the component/type default,
+   * removing any per-face finish. The inverse of
+   * {@linkcode PluginDesignMaterialsApi.applyToFaces}; undoable when `save` is true
+   * (the default). BREP-only (see `applyToFaces`).
+   *
+   * @param component The (BREP) component
+   * @param faces BREP face indices to reset (nonnegative integers)
+   * @param save Commit as an undoable command (default `true`)
+   * @returns The number of faces reset
+   *
+   * @examplePrompt Remove the paint from the top face of this slab
+   * @examplePrompt Reset faces 0 and 2 of this wall to their default material
+   * @examplePrompt Clear the custom finish on the front face of this column
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls({ storeys: [1] })
+   * const { count } = await snaptrude.design.materials.resetFaces(wall, [0, 1])
+   * console.log("reset", count, "faces")
+   * ```
+   */
+  public abstract resetFaces(
+    component: ComponentHandle,
+    faces: number[],
+    save?: boolean,
   ): PluginApiReturn<PluginMaterialResult>
 
+  /**
+   * Read the material applied to a single BREP face.
+   *
+   * @param component The (BREP) component
+   * @param face The BREP face index (a nonnegative integer)
+   * @returns The face's material as a {@linkcode MaterialHandle}, or `null` if the
+   * face carries no explicit per-face material (or the component has no BREP)
+   *
+   * @examplePrompt What material is on the top face of this slab?
+   * @examplePrompt Get the finish applied to face 2 of this wall
+   * @examplePrompt Which material is painted on the front face of this column?
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const material = await snaptrude.design.materials.getByFace(wall, 0)
+   * if (material) console.log(await snaptrude.design.materials.getInfo(material))
+   * ```
+   */
+  public abstract getByFace(
+    component: ComponentHandle,
+    face: number,
+  ): PluginApiReturn<MaterialHandle | null>
+
+  /**
+   * List the per-face materials of a component — one entry per BREP face, in face
+   * index order. A face carrying no explicit per-face material reports `null`.
+   *
+   * @param component The (BREP) component
+   * @returns The per-face materials as {@linkcode PluginFaceMaterial}`[]` (`[]` for a
+   * component with no BREP)
+   *
+   * @examplePrompt List the material on every face of this wall
+   * @examplePrompt Show me which faces of this slab are painted and with what
+   * @examplePrompt Break down the per-face finishes of the selected mass
+   *
+   * # Example
+   * ```ts
+   * const [wall] = await snaptrude.design.query.listWalls()
+   * const faces = await snaptrude.design.materials.listByFace(wall)
+   * for (const f of faces) console.log(f.faceIndex, f.material ?? "(default)")
+   * ```
+   */
+  public abstract listByFace(
+    component: ComponentHandle,
+  ): PluginApiReturn<PluginFaceMaterial[]>
+
   /**
    * 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
@@ -132,7 +327,9 @@ export abstract class PluginDesignMaterialsApi {
    * await snaptrude.design.materials.apply(walls, glass)
    * ```
    */
-  public abstract create(spec: PluginMaterialSpec): PluginApiReturn<MaterialHandle>
+  public abstract create(
+    spec: PluginMaterialSpec,
+  ): PluginApiReturn<MaterialHandle>
 
   /**
    * Get the default material for a component's type.
@@ -151,7 +348,9 @@ export abstract class PluginDesignMaterialsApi {
    * if (defaultMaterial) console.log(await snaptrude.design.materials.getInfo(defaultMaterial))
    * ```
    */
-  public abstract getDefault(component: ComponentHandle): PluginApiReturn<MaterialHandle | null>
+  public abstract getDefault(
+    component: ComponentHandle,
+  ): PluginApiReturn<MaterialHandle | null>
 
   /**
    * Test whether a component carries its (type) default material.
@@ -170,7 +369,9 @@ export abstract class PluginDesignMaterialsApi {
    * console.log(untouched ? "still default" : "has been painted")
    * ```
    */
-  public abstract isDefault(component: ComponentHandle): PluginApiReturn<boolean>
+  public abstract isDefault(
+    component: ComponentHandle,
+  ): PluginApiReturn<boolean>
 
   /**
    * Test whether a component has a single (uniform) material across all faces.
@@ -189,7 +390,9 @@ export abstract class PluginDesignMaterialsApi {
    * console.log(uniform ? "one material all over" : "painted per face")
    * ```
    */
-  public abstract isUniform(component: ComponentHandle): PluginApiReturn<boolean>
+  public abstract isUniform(
+    component: ComponentHandle,
+  ): PluginApiReturn<boolean>
 
   /**
    * Test whether a material has a texture.
@@ -257,18 +460,68 @@ export type PluginMaterialSpec = z.infer<typeof PluginMaterialSpec>
 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(),
+/**
+ * A single component face's material assignment (value record — not a handle).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `faceIndex` | `number` | Durable BREP face index (0-based position in the face list) |
+ * | `material` | {@linkcode MaterialHandle} \| `null` | The applied material, or `null` for the default |
+ */
+export const PluginFaceMaterial = z.object({
+  faceIndex: z.number().int().nonnegative(),
+  material: MaterialHandle.nullable(),
+})
+export type PluginFaceMaterial = z.infer<typeof PluginFaceMaterial>
+
+/**
+ * The material on a component **as a whole** — the eyedropper read returned by
+ * {@linkcode PluginDesignMaterialsApi.get} (value record, plus a reusable handle).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `material` | {@linkcode MaterialHandle} | The whole-object material — chain into `apply` / `getInfo` |
+ * | `id` | `string` | Engine material id |
+ * | `name` | `string` | Material name (== the handle token) |
+ * | `source` | `"default" \| "applied"` | Whether it is the component's type default or an explicitly-applied finish |
+ */
+export const PluginComponentMaterial = z.object({
+  material: MaterialHandle,
+  id: z.string(),
+  name: z.string(),
+  source: z.enum(["default", "applied"]),
+})
+export type PluginComponentMaterial = z.infer<typeof PluginComponentMaterial>
+
+/**
+ * A preset material library entry (value record — NOT a handle), returned by
+ * {@linkcode PluginDesignMaterialsApi.listPresets}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | Display name of the library entry |
+ * | `category` | `string` | Library category (camelCase, e.g. `"wood"`, `"colors"`, `"brick"`) |
+ * | `textureUrl` | `string` | Texture/swatch image URL — feed to {@linkcode PluginMaterialSpec}`.textureUrl` |
+ */
+export const PluginPresetMaterial = z.object({
+  name: z.string(),
+  category: z.string(),
+  textureUrl: z.string(),
 })
-export type PluginDesignMaterialsListArgs = z.infer<typeof PluginDesignMaterialsListArgs>
+export type PluginPresetMaterial = z.infer<typeof PluginPresetMaterial>
 
 /** Arguments for {@linkcode PluginDesignMaterialsApi.getInfo} / `hasTexture`. */
-export const PluginDesignMaterialsGetInfoArgs = z.object({ material: MaterialHandle })
-export type PluginDesignMaterialsGetInfoArgs = z.infer<typeof PluginDesignMaterialsGetInfoArgs>
+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 const PluginDesignMaterialsComponentArgs = z.object({
+  component: ComponentHandle,
+})
 export type PluginDesignMaterialsComponentArgs = z.infer<
   typeof PluginDesignMaterialsComponentArgs
 >
@@ -287,15 +540,69 @@ export const PluginDesignMaterialsApplyArgs = z.object({
   material: z.union([MaterialHandle, PluginMaterialSpec]),
   save: z.boolean().optional(),
 })
-export type PluginDesignMaterialsApplyArgs = z.infer<typeof PluginDesignMaterialsApplyArgs>
+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>
+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>
+export const PluginDesignMaterialsCreateArgs = z.object({
+  spec: PluginMaterialSpec,
+})
+export type PluginDesignMaterialsCreateArgs = z.infer<
+  typeof PluginDesignMaterialsCreateArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginDesignMaterialsApi.applyToFaces}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `component` | {@linkcode ComponentHandle} | The (BREP) component to paint |
+ * | `faces` | `number[]` | BREP face indices to paint (nonnegative integers) |
+ * | `material` | {@linkcode MaterialHandle} \| {@linkcode PluginMaterialSpec} | Material handle, or an inline spec |
+ * | `save` | `boolean` | Commit as an undoable command (default `true`) |
+ */
+export const PluginDesignMaterialsApplyToFacesArgs = z.object({
+  component: ComponentHandle,
+  faces: z.array(z.number().int().nonnegative()),
+  material: z.union([MaterialHandle, PluginMaterialSpec]),
+  save: z.boolean().optional(),
+})
+export type PluginDesignMaterialsApplyToFacesArgs = z.infer<
+  typeof PluginDesignMaterialsApplyToFacesArgs
+>
+
+/** Arguments for {@linkcode PluginDesignMaterialsApi.resetFaces}. */
+export const PluginDesignMaterialsResetFacesArgs = z.object({
+  component: ComponentHandle,
+  faces: z.array(z.number().int().nonnegative()),
+  save: z.boolean().optional(),
+})
+export type PluginDesignMaterialsResetFacesArgs = z.infer<
+  typeof PluginDesignMaterialsResetFacesArgs
+>
+
+/** Arguments for {@linkcode PluginDesignMaterialsApi.getByFace}. */
+export const PluginDesignMaterialsGetByFaceArgs = z.object({
+  component: ComponentHandle,
+  face: z.number().int().nonnegative(),
+})
+export type PluginDesignMaterialsGetByFaceArgs = z.infer<
+  typeof PluginDesignMaterialsGetByFaceArgs
+>
+
+/** Arguments for {@linkcode PluginDesignMaterialsApi.listByFace} (component only). */
+export const PluginDesignMaterialsListByFaceArgs =
+  PluginDesignMaterialsComponentArgs
+export type PluginDesignMaterialsListByFaceArgs = z.infer<
+  typeof PluginDesignMaterialsListByFaceArgs
+>

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

@@ -18,6 +18,9 @@ import {
  * {@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 the triangulated render meshes as plain
+ * world-space arrays.
  *
  * Returned handles are session-ephemeral and go stale on undo/redo/re-topologize
  * — re-fetch a fresh one after edits.
@@ -48,7 +51,7 @@ export abstract class PluginDesignQueryGeometryApi {
    * ```
    */
   public abstract getBrep(
-    component: ComponentHandle
+    component: ComponentHandle,
   ): PluginApiReturn<BrepHandle | null>
 
   /**
@@ -80,7 +83,7 @@ export abstract class PluginDesignQueryGeometryApi {
    * ```
    */
   public abstract getBottomContour(
-    component: ComponentHandle
+    component: ComponentHandle,
   ): PluginApiReturn<ContourHandle | null>
 
   /**
@@ -116,8 +119,67 @@ export abstract class PluginDesignQueryGeometryApi {
    * ```
    */
   public abstract getCenterline(
-    component: ComponentHandle
+    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.
+   *
+   * 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>
 }
 
 /**
@@ -164,3 +226,63 @@ export const PluginDesignQueryGeometryGetCenterlineArgs = z.object({
 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
+>