@snaptrude/plugin-core 0.3.0 → 0.5.0

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

@@ -0,0 +1,123 @@
+import * as z from "zod";
+import { PluginApiReturn } from "../../../types";
+/**
+ * `snaptrude.design.furniture` — the placeable furniture **catalog** (a library of
+ * source items, NOT scene entities). Placement lives at `design.create.furniture`
+ * (returns a {@linkcode ComponentHandle}); reads of placed furniture live at
+ * `design.query.listFurniture`/`getProperties`.
+ *
+ * Catalog items are plain value records ({@linkcode PluginFurnitureCatalogItem}) keyed
+ * by a library id (team `_id` or general `fullName`) — not handles. Reads are async
+ * (network-backed) but carry no `Async` suffix (§6.6).
+ */
+export declare abstract class PluginDesignFurnitureApi {
+    constructor();
+    /**
+     * List the placeable furniture catalog (team + general libraries).
+     * @param source Restrict to one library (optional)
+     * @returns The catalog as {@linkcode PluginFurnitureCatalogItem}`[]` (`[]` when empty)
+     *
+     * @examplePrompt What furniture can I place in this project?
+     * @examplePrompt Show me all the furniture available in the library
+     * @examplePrompt List the chairs and tables I can add to the model
+     * @examplePrompt Which furniture items are in my team's library?
+     * @examplePrompt Browse the furniture catalog
+     *
+     * # Example
+     * ```ts
+     * const teamItems = await snaptrude.design.furniture.listCatalog("team")
+     * for (const item of teamItems) console.log(item.id, item.name, item.cost)
+     * ```
+     */
+    abstract listCatalog(source?: "team" | "general"): PluginApiReturn<PluginFurnitureCatalogItem[]>;
+    /**
+     * Get a single catalog item by its library id.
+     * @param id The catalog library id
+     * @returns The item, or `null` if no catalog item matches
+     *
+     * @examplePrompt Get the details of this furniture item from the library
+     * @examplePrompt Look up the catalog entry for this chair id
+     * @examplePrompt What is the cost of this furniture item?
+     * @examplePrompt Show me the family name of the sofa in the catalog
+     *
+     * # Example
+     * ```ts
+     * const [entry] = await snaptrude.design.furniture.listCatalog()
+     * const item = await snaptrude.design.furniture.getCatalogItem(entry.id)
+     * if (item) console.log(item.name, item.source, item.familyName)
+     * ```
+     */
+    abstract getCatalogItem(id: string): PluginApiReturn<PluginFurnitureCatalogItem | null>;
+    /**
+     * Test whether a catalog item exists for the given library id.
+     * @param id The catalog library id
+     * @returns `true` if it exists, otherwise `false`
+     *
+     * @examplePrompt Is this furniture item still in the library?
+     * @examplePrompt Check whether a catalog item with this id exists
+     * @examplePrompt Does my team library have this chair?
+     * @examplePrompt Verify the sofa is available in the catalog before placing it
+     *
+     * # Example
+     * ```ts
+     * const [entry] = await snaptrude.design.furniture.listCatalog()
+     * const stillAvailable = await snaptrude.design.furniture.exists(entry.id)
+     * console.log(stillAvailable ? "safe to place" : "removed from library")
+     * ```
+     */
+    abstract exists(id: string): PluginApiReturn<boolean>;
+}
+/**
+ * A placeable furniture catalog item (value record — not a scene entity/handle).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Library id (team `_id` or general `fullName`) — pass to `design.create.furniture` |
+ * | `name` | `string` | Display name |
+ * | `source` | `'team' \| 'general'` | Which library it came from |
+ * | `subType` | `string` | Sub-type (optional) |
+ * | `cost` | `number` | Cost (optional; team items) |
+ * | `familyName` | `string` | Family name (optional) |
+ */
+export declare const PluginFurnitureCatalogItem: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    source: z.ZodEnum<{
+        team: "team";
+        general: "general";
+    }>;
+    subType: z.ZodOptional<z.ZodString>;
+    cost: z.ZodOptional<z.ZodNumber>;
+    familyName: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginFurnitureCatalogItem = z.infer<typeof PluginFurnitureCatalogItem>;
+/**
+ * Arguments for {@linkcode PluginDesignFurnitureApi.listCatalog}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `source` | `'team' \| 'general'` | Restrict to one library (optional) |
+ */
+export declare const PluginDesignFurnitureListCatalogArgs: z.ZodObject<{
+    source: z.ZodOptional<z.ZodEnum<{
+        team: "team";
+        general: "general";
+    }>>;
+}, z.core.$strip>;
+export type PluginDesignFurnitureListCatalogArgs = z.infer<typeof PluginDesignFurnitureListCatalogArgs>;
+/**
+ * Arguments for {@linkcode PluginDesignFurnitureApi.getCatalogItem} / {@linkcode PluginDesignFurnitureApi.exists}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The catalog library id |
+ */
+export declare const PluginDesignFurnitureGetCatalogItemArgs: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+export type PluginDesignFurnitureGetCatalogItemArgs = z.infer<typeof PluginDesignFurnitureGetCatalogItemArgs>;
+export declare const PluginDesignFurnitureExistsArgs: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+export type PluginDesignFurnitureExistsArgs = z.infer<typeof PluginDesignFurnitureExistsArgs>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/api/design/furniture/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAEhD;;;;;;;;;GASG;AACH,8BAAsB,wBAAwB;;IAG5C;;;;;;;;;;;;;;;;OAgBG;aACa,WAAW,CACzB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,GAC1B,eAAe,CAAC,0BAA0B,EAAE,CAAC;IAEhD;;;;;;;;;;;;;;;;OAgBG;aACa,cAAc,CAC5B,EAAE,EAAE,MAAM,GACT,eAAe,CAAC,0BAA0B,GAAG,IAAI,CAAC;IAErD;;;;;;;;;;;;;;;;OAgBG;aACa,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC;CAC7D;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;iBAOrC,CAAA;AACF,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAA;AAEnF;;;;;;GAMG;AACH,eAAO,MAAM,oCAAoC;;;;;iBAE/C,CAAA;AACF,MAAM,MAAM,oCAAoC,GAAG,CAAC,CAAC,KAAK,CACxD,OAAO,oCAAoC,CAC5C,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,uCAAuC;;iBAElD,CAAA;AACF,MAAM,MAAM,uCAAuC,GAAG,CAAC,CAAC,KAAK,CAC3D,OAAO,uCAAuC,CAC/C,CAAA;AAED,eAAO,MAAM,+BAA+B;;iBAA0C,CAAA;AACtF,MAAM,MAAM,+BAA+B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAA"}

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

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

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

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

package/dist/api/design/lock.d.ts

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

package/dist/api/design/lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../../src/api/design/lock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAE/C;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;iBAEnC,CAAA;AACF,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAA;AAE/E;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB;;iBAE/B,CAAA;AACF,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAEvE,eAAO,MAAM,sBAAsB;;iBAAuB,CAAA;AAC1D,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAE3E;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB;;;iBAGnC,CAAA;AACF,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAA"}

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

@@ -0,0 +1,297 @@
+import * as z from "zod";
+import { PluginApiReturn } from "../../../types";
+import { ComponentHandle, MaterialHandle } from "../../../handles";
+/**
+ * `snaptrude.design.materials` — the project material library + material assignment.
+ *
+ * Materials are {@linkcode MaterialHandle}s (entity-style, name-addressed). Reads return
+ * a {@linkcode MaterialHandle}/{@linkcode PluginMaterialInfo}; `apply`/`reset` mutate the
+ * scene (undoable via `save`, default `true`). `create` mints a material from a
+ * {@linkcode PluginMaterialSpec} (idempotent by name).
+ *
+ * Face-targeted apply, per-face reads (`listByFace`), and `copy` (needs an undo
+ * wrapper) land in a later pass.
+ */
+export declare abstract class PluginDesignMaterialsApi {
+    constructor();
+    /**
+     * List the project materials.
+     * @param scope Which library to list (optional)
+     * @returns The materials as {@linkcode MaterialHandle}`[]`
+     *
+     * @examplePrompt List all the materials in this project
+     * @examplePrompt What materials do I have available to apply?
+     * @examplePrompt Show me the preset materials library
+     * @examplePrompt Which finishes exist in this model?
+     * @examplePrompt Get every material in the project palette
+     *
+     * # Example
+     * ```ts
+     * const presets = await snaptrude.design.materials.list("preset")
+     * console.log(presets.length, "preset materials")
+     * ```
+     */
+    abstract list(scope?: "project" | "preset"): PluginApiReturn<MaterialHandle[]>;
+    /**
+     * Read a material's descriptor — its name, color, opacity, and texture
+     * (when it has one).
+     *
+     * @param material The material to read
+     * @returns The {@linkcode PluginMaterialInfo}, or `null` if the material is gone
+     *
+     * @examplePrompt What colour is the Brick material?
+     * @examplePrompt Show me the details of this material
+     * @examplePrompt Get the opacity of the glass finish
+     * @examplePrompt Which texture image does the wood material use?
+     *
+     * # Example
+     * ```ts
+     * const [material] = await snaptrude.design.materials.list()
+     * const info = await snaptrude.design.materials.getInfo(material)
+     * if (info) console.log(info.name, info.colorHex, info.alpha)
+     * ```
+     */
+    abstract getInfo(material: MaterialHandle): PluginApiReturn<PluginMaterialInfo | null>;
+    /**
+     * Apply a material to one or more components — an existing project material by
+     * handle, or a new one described inline as a {@linkcode PluginMaterialSpec}.
+     * Undoable when `save` is true (the default).
+     *
+     * @param targets Components to paint
+     * @param material Material handle, or an inline {@linkcode PluginMaterialSpec}
+     * @param save Commit as an undoable command (default `true`)
+     * @returns The number of targets the material was applied to
+     *
+     * @examplePrompt Paint the selected walls red
+     * @examplePrompt Apply the brick material to these walls
+     * @examplePrompt Put a wood finish on the floor
+     * @examplePrompt Change the colour of this room's walls to #ff8800
+     * @examplePrompt Add a concrete texture to the facade
+     *
+     * # Example
+     * ```ts
+     * const walls = await snaptrude.design.query.listWalls({ storeys: [1] })
+     * // inline spec — creates (or reuses by name) a project material, then applies it
+     * const { count } = await snaptrude.design.materials.apply(walls, { name: "Accent Red", color: "#b04a3a" })
+     * console.log("painted", count, "walls")
+     * ```
+     */
+    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")
+     * ```
+     */
+    abstract reset(components: ComponentHandle[], save?: boolean): PluginApiReturn<PluginMaterialResult>;
+    /**
+     * Create a new material in the project from a spec — a color, texture URL,
+     * opacity, and/or name. Idempotent by name: creating with the name of an
+     * existing material returns that material instead of duplicating it.
+     *
+     * @param spec The material construction spec
+     * @returns The new material as a {@linkcode MaterialHandle}
+     *
+     * @examplePrompt Create a new red material called Accent
+     * @examplePrompt Make a material from this texture image URL
+     * @examplePrompt Add a semi-transparent glass material to the project
+     * @examplePrompt Define a dark grey concrete finish I can reuse
+     *
+     * # Example
+     * ```ts
+     * const glass = await snaptrude.design.materials.create({ name: "Frosted Glass", color: "#cfe4e8", alpha: 0.4 })
+     * const walls = await snaptrude.design.query.listWalls({ storeys: [1] })
+     * await snaptrude.design.materials.apply(walls, glass)
+     * ```
+     */
+    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))
+     * ```
+     */
+    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")
+     * ```
+     */
+    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")
+     * ```
+     */
+    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")
+     * ```
+     */
+    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 declare const PluginMaterialInfo: z.ZodObject<{
+    name: z.ZodString;
+    id: z.ZodString;
+    colorHex: z.ZodString;
+    alpha: z.ZodNumber;
+    materialType: z.ZodOptional<z.ZodString>;
+    textureUrl: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+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 declare const PluginMaterialSpec: 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>;
+export type PluginMaterialSpec = z.infer<typeof PluginMaterialSpec>;
+/** Result of a material mutation — the count of targets affected. */
+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";
+    }>>;
+}, z.core.$strip>;
+export type PluginDesignMaterialsListArgs = z.infer<typeof PluginDesignMaterialsListArgs>;
+/** Arguments for {@linkcode PluginDesignMaterialsApi.getInfo} / `hasTexture`. */
+export declare const PluginDesignMaterialsGetInfoArgs: z.ZodObject<{
+    material: z.ZodPipe<z.ZodString, z.ZodTransform<MaterialHandle, string>>;
+}, z.core.$strip>;
+export type PluginDesignMaterialsGetInfoArgs = z.infer<typeof PluginDesignMaterialsGetInfoArgs>;
+/** Arguments for component-scoped predicates (`getDefault`/`isDefault`/`isUniform`). */
+export declare const PluginDesignMaterialsComponentArgs: z.ZodObject<{
+    component: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+}, z.core.$strip>;
+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 declare const PluginDesignMaterialsApplyArgs: z.ZodObject<{
+    targets: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>>;
+    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 PluginDesignMaterialsApplyArgs = z.infer<typeof PluginDesignMaterialsApplyArgs>;
+/** Arguments for {@linkcode PluginDesignMaterialsApi.reset}. */
+export declare const PluginDesignMaterialsResetArgs: z.ZodObject<{
+    components: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>>;
+    save: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type PluginDesignMaterialsResetArgs = z.infer<typeof PluginDesignMaterialsResetArgs>;
+/** Arguments for {@linkcode PluginDesignMaterialsApi.create}. */
+export declare const PluginDesignMaterialsCreateArgs: z.ZodObject<{
+    spec: 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>;
+}, z.core.$strip>;
+export type PluginDesignMaterialsCreateArgs = z.infer<typeof PluginDesignMaterialsCreateArgs>;
+//# sourceMappingURL=index.d.ts.map

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

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