@snaptrude/plugin-core 0.0.0-bimsvg-20260928124803

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

@@ -0,0 +1,608 @@
+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). `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`).
+ *
+ * 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 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 Which finishes exist in this model?
+   * @examplePrompt Get every material in the project palette
+   *
+   * # Example
+   * ```ts
+   * const materials = await snaptrude.design.materials.list()
+   * console.log(materials.length, "materials in the project")
+   * ```
+   */
+  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
+   * (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>
+
+  /**
+   * 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
+   * 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>
+
+  /**
+   * 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
+   * 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>
+
+/**
+ * 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 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
+>
+
+/** 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
+>
+
+/**
+ * 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
+>