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

package/dist/api/design/materials/index.d.ts

@@ -7,31 +7,75 @@ 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 declare 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")
+     * ```
+     */
+    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,
+     *   })
+     * }
      * ```
      */
-    abstract list(scope?: "project" | "preset"): PluginApiReturn<MaterialHandle[]>;
+    abstract listPresets(): PluginApiReturn<PluginPresetMaterial[]>;
     /**
      * Read a material's descriptor — its name, color, opacity, and texture
      * (when it has one).
@@ -52,6 +96,37 @@ export declare abstract class PluginDesignMaterialsApi {
      * ```
      */
     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)
+     * }
+     * ```
+     */
+    abstract get(component: ComponentHandle): PluginApiReturn<PluginComponentMaterial | 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}.
@@ -99,6 +174,102 @@ export declare abstract class PluginDesignMaterialsApi {
      * ```
      */
     abstract reset(components: ComponentHandle[], 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")
+     * ```
+     */
+    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")
+     * ```
+     */
+    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))
+     * ```
+     */
+    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)")
+     * ```
+     */
+    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
@@ -238,14 +409,56 @@ export declare const PluginMaterialResult: z.ZodObject<{
     count: z.ZodNumber;
 }, z.core.$strip>;
 export type PluginMaterialResult = z.infer<typeof PluginMaterialResult>;
-/** Arguments for {@linkcode PluginDesignMaterialsApi.list}. */
-export declare const PluginDesignMaterialsListArgs: z.ZodObject<{
-    scope: z.ZodOptional<z.ZodEnum<{
-        preset: "preset";
-        project: "project";
-    }>>;
+/**
+ * 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 declare const PluginFaceMaterial: z.ZodObject<{
+    faceIndex: z.ZodNumber;
+    material: z.ZodNullable<z.ZodPipe<z.ZodString, z.ZodTransform<MaterialHandle, string>>>;
 }, z.core.$strip>;
-export type PluginDesignMaterialsListArgs = z.infer<typeof PluginDesignMaterialsListArgs>;
+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 declare const PluginComponentMaterial: z.ZodObject<{
+    material: z.ZodPipe<z.ZodString, z.ZodTransform<MaterialHandle, string>>;
+    id: z.ZodString;
+    name: z.ZodString;
+    source: z.ZodEnum<{
+        default: "default";
+        applied: "applied";
+    }>;
+}, z.core.$strip>;
+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 declare const PluginPresetMaterial: z.ZodObject<{
+    name: z.ZodString;
+    category: z.ZodString;
+    textureUrl: z.ZodString;
+}, z.core.$strip>;
+export type PluginPresetMaterial = z.infer<typeof PluginPresetMaterial>;
 /** Arguments for {@linkcode PluginDesignMaterialsApi.getInfo} / `hasTexture`. */
 export declare const PluginDesignMaterialsGetInfoArgs: z.ZodObject<{
     material: z.ZodPipe<z.ZodString, z.ZodTransform<MaterialHandle, string>>;
@@ -294,4 +507,45 @@ export declare const PluginDesignMaterialsCreateArgs: z.ZodObject<{
     }, z.core.$strip>;
 }, z.core.$strip>;
 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 declare const PluginDesignMaterialsApplyToFacesArgs: z.ZodObject<{
+    component: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+    faces: z.ZodArray<z.ZodNumber>;
+    material: z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<MaterialHandle, string>>, z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        color: z.ZodOptional<z.ZodString>;
+        textureUrl: z.ZodOptional<z.ZodString>;
+        alpha: z.ZodOptional<z.ZodNumber>;
+        materialType: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>;
+    save: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type PluginDesignMaterialsApplyToFacesArgs = z.infer<typeof PluginDesignMaterialsApplyToFacesArgs>;
+/** Arguments for {@linkcode PluginDesignMaterialsApi.resetFaces}. */
+export declare const PluginDesignMaterialsResetFacesArgs: z.ZodObject<{
+    component: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+    faces: z.ZodArray<z.ZodNumber>;
+    save: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type PluginDesignMaterialsResetFacesArgs = z.infer<typeof PluginDesignMaterialsResetFacesArgs>;
+/** Arguments for {@linkcode PluginDesignMaterialsApi.getByFace}. */
+export declare const PluginDesignMaterialsGetByFaceArgs: z.ZodObject<{
+    component: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+    face: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginDesignMaterialsGetByFaceArgs = z.infer<typeof PluginDesignMaterialsGetByFaceArgs>;
+/** Arguments for {@linkcode PluginDesignMaterialsApi.listByFace} (component only). */
+export declare const PluginDesignMaterialsListByFaceArgs: z.ZodObject<{
+    component: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+}, z.core.$strip>;
+export type PluginDesignMaterialsListByFaceArgs = z.infer<typeof PluginDesignMaterialsListByFaceArgs>;
 //# sourceMappingURL=index.d.ts.map

package/dist/api/design/materials/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/api/design/materials/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/api/design/materials/index.ts"],"names":[],"mappings":"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"}

package/dist/api/design/query/geometry/index.d.ts

@@ -12,6 +12,9 @@ import { ComponentHandle, BrepHandle, ContourHandle, CurveHandle } from "../../.
  * {@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.
@@ -103,6 +106,61 @@ export declare abstract class PluginDesignQueryGeometryApi {
      * ```
      */
     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.
+     *
+     * 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])
+     * }
+     * ```
+     */
+    abstract getTriangulatedMeshes(components: ComponentHandle[], options?: PluginDesignQueryGeometryGetTriangulatedMeshesArgs["options"]): PluginApiReturn<PluginDesignQueryGeometryGetTriangulatedMeshesResult>;
 }
 /**
  * Arguments for {@linkcode PluginDesignQueryGeometryApi.getBrep}.
@@ -137,4 +195,58 @@ export declare const PluginDesignQueryGeometryGetCenterlineArgs: z.ZodObject<{
     component: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
 }, z.core.$strip>;
 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 declare const PluginTriangulatedMesh: z.ZodObject<{
+    id: z.ZodString;
+    positions: z.ZodArray<z.ZodNumber>;
+    indices: z.ZodArray<z.ZodNumber>;
+    materialIds: z.ZodOptional<z.ZodArray<z.ZodNullable<z.ZodString>>>;
+    faceIds: z.ZodOptional<z.ZodArray<z.ZodNullable<z.ZodNumber>>>;
+}, z.core.$strip>;
+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 declare const PluginDesignQueryGeometryGetTriangulatedMeshesArgs: z.ZodObject<{
+    components: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>>;
+    options: z.ZodOptional<z.ZodObject<{
+        includeMaterialIds: z.ZodOptional<z.ZodBoolean>;
+        includeFaceIndices: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+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 declare const PluginDesignQueryGeometryGetTriangulatedMeshesResult: z.ZodObject<{
+    meshes: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        positions: z.ZodArray<z.ZodNumber>;
+        indices: z.ZodArray<z.ZodNumber>;
+        materialIds: z.ZodOptional<z.ZodArray<z.ZodNullable<z.ZodString>>>;
+        faceIds: z.ZodOptional<z.ZodArray<z.ZodNullable<z.ZodNumber>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginDesignQueryGeometryGetTriangulatedMeshesResult = z.infer<typeof PluginDesignQueryGeometryGetTriangulatedMeshesResult>;
 //# sourceMappingURL=index.d.ts.map

package/dist/api/design/query/geometry/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/api/design/query/geometry/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,EACL,eAAe,EACf,UAAU,EACV,aAAa,EACb,WAAW,EACZ,MAAM,qBAAqB,CAAA;AAE5B;;;;;;;;;;;;;;GAcG;AACH,8BAAsB,4BAA4B;;IAGhD;;;;;;;;;;;;;;;;;;;;;OAqBG;aACa,OAAO,CACrB,SAAS,EAAE,eAAe,GACzB,eAAe,CAAC,UAAU,GAAG,IAAI,CAAC;IAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;aACa,gBAAgB,CAC9B,SAAS,EAAE,eAAe,GACzB,eAAe,CAAC,aAAa,GAAG,IAAI,CAAC;IAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;aACa,aAAa,CAC3B,SAAS,EAAE,eAAe,GACzB,eAAe,CAAC,WAAW,GAAG,IAAI,CAAC;CACvC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oCAAoC;;iBAE/C,CAAA;AAEF,MAAM,MAAM,oCAAoC,GAAG,CAAC,CAAC,KAAK,CACxD,OAAO,oCAAoC,CAC5C,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,6CAA6C;;iBAExD,CAAA;AAEF,MAAM,MAAM,6CAA6C,GAAG,CAAC,CAAC,KAAK,CACjE,OAAO,6CAA6C,CACrD,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,0CAA0C;;iBAErD,CAAA;AAEF,MAAM,MAAM,0CAA0C,GAAG,CAAC,CAAC,KAAK,CAC9D,OAAO,0CAA0C,CAClD,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/api/design/query/geometry/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,EACL,eAAe,EACf,UAAU,EACV,aAAa,EACb,WAAW,EACZ,MAAM,qBAAqB,CAAA;AAE5B;;;;;;;;;;;;;;;;;GAiBG;AACH,8BAAsB,4BAA4B;;IAGhD;;;;;;;;;;;;;;;;;;;;;OAqBG;aACa,OAAO,CACrB,SAAS,EAAE,eAAe,GACzB,eAAe,CAAC,UAAU,GAAG,IAAI,CAAC;IAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;aACa,gBAAgB,CAC9B,SAAS,EAAE,eAAe,GACzB,eAAe,CAAC,aAAa,GAAG,IAAI,CAAC;IAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;aACa,aAAa,CAC3B,SAAS,EAAE,eAAe,GACzB,eAAe,CAAC,WAAW,GAAG,IAAI,CAAC;IAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqDG;aACa,qBAAqB,CACnC,UAAU,EAAE,eAAe,EAAE,EAC7B,OAAO,CAAC,EAAE,kDAAkD,CAAC,SAAS,CAAC,GACtE,eAAe,CAAC,oDAAoD,CAAC;CACzE;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oCAAoC;;iBAE/C,CAAA;AAEF,MAAM,MAAM,oCAAoC,GAAG,CAAC,CAAC,KAAK,CACxD,OAAO,oCAAoC,CAC5C,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,6CAA6C;;iBAExD,CAAA;AAEF,MAAM,MAAM,6CAA6C,GAAG,CAAC,CAAC,KAAK,CACjE,OAAO,6CAA6C,CACrD,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,0CAA0C;;iBAErD,CAAA;AAEF,MAAM,MAAM,0CAA0C,GAAG,CAAC,CAAC,KAAK,CAC9D,OAAO,0CAA0C,CAClD,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB;;;;;;iBAMjC,CAAA;AAEF,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAE3E;;;;;;;;GAQG;AACH,eAAO,MAAM,kDAAkD;;;;;;iBAQ7D,CAAA;AAEF,MAAM,MAAM,kDAAkD,GAAG,CAAC,CAAC,KAAK,CACtE,OAAO,kDAAkD,CAC1D,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oDAAoD;;;;;;;;iBAE/D,CAAA;AAEF,MAAM,MAAM,oDAAoD,GAAG,CAAC,CAAC,KAAK,CACxE,OAAO,oDAAoD,CAC5D,CAAA"}