@snaptrude/plugin-core 1.1.0-dev.20261025.1 → 1.1.0-pbr-20261028.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snaptrude/plugin-core",
-  "version": "1.1.0-dev.20261025.1",
+  "version": "1.1.0-pbr-20261028.1",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

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

@@ -48,16 +48,20 @@ export abstract class PluginDesignMaterialsApi {
 
   /**
    * 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
+   * shows: the deployment PBR catalogue plus the server library and workspace uploads.
+   * Library entries are **not** scene materials and carry no {@linkcode MaterialHandle}.
+   * PBR names include an identity-qualified suffix `[catalogId@catalogVersion]`:
+   * preserve the EXACT returned name and pass `{ name: preset.name }` to create/apply.
+   * The host resolves all authored PBR maps, physical coverage and glass properties;
+   * do not strip the suffix, substitute an image-only finish, or override color/alpha.
+   * Scalar paints and clear glass can have an empty textureUrl and are still valid.
+   * For legacy image entries, feed the returned record 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)
+   * @returns The library as {@linkcode PluginPresetMaterial}`[]`. Missing/malformed
+   * deployment PBR data rejects; the legacy server library may return `[]` on failure.
    *
    * @examplePrompt Show me the preset materials library
    * @examplePrompt What wood finishes are available in the material library?
@@ -167,6 +171,25 @@ export abstract class PluginDesignMaterialsApi {
     save?: boolean,
   ): PluginApiReturn<PluginMaterialResult>
 
+  /**
+   * Paint only glazing or frame slots, never the whole window/door. This preserves
+   * clear panes when painting metal frames. Families change with their linked copies;
+   * legacy instanced types change every instance of that type. BREP components are
+   * refused (use applyToFaces), as are locked targets or locked linked/type members.
+   * Slot roles come from the authored appearance, not a previously applied paint.
+   * Always one undo step. Catalogue selectors use the exact listPresets name.
+   * @param components Components whose family/type slots to paint
+   * @param slot Authored glazing slots or every other (frame/hardware) slot
+   * @param material Existing handle or inline spec, e.g. `{ name: preset.name }`
+   * @returns Count of targets whose family/type had at least one matching slot
+   * @examplePrompt Paint only the window frames with a catalogue metal finish
+   */
+  public abstract applyToSlot(
+    components: ComponentHandle[],
+    slot: "glazing" | "frame",
+    material: MaterialHandle | PluginMaterialSpec,
+  ): 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`
@@ -425,6 +448,7 @@ export abstract class PluginDesignMaterialsApi {
  * | `alpha` | `number` | Opacity `0..1` |
  * | `materialType` | `string` | Material type tag (optional) |
  * | `textureUrl` | `string` | Diffuse texture URL (optional) |
+ * | `transmission` | `number` | Diffuse transmission `0..1` (optional; absent when none) |
  */
 export const PluginMaterialInfo = z.object({
   name: z.string(),
@@ -433,6 +457,7 @@ export const PluginMaterialInfo = z.object({
   alpha: z.number(),
   materialType: z.string().optional(),
   textureUrl: z.string().optional(),
+  transmission: z.number().optional(),
 })
 export type PluginMaterialInfo = z.infer<typeof PluginMaterialInfo>
 
@@ -441,11 +466,12 @@ export type PluginMaterialInfo = z.infer<typeof PluginMaterialInfo>
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `name` | `string` | Name (optional; generated if omitted) |
+ * | `name` | `string` | Name (optional; generated if omitted); an exact identity-qualified listPresets name selects the full authored PBR finish |
  * | `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) |
+ * | `transmission` | `number` | Diffuse transmission `0..1` (optional; stored on the material's PBR data). Not combinable with a catalog (listPresets) name |
  */
 export const PluginMaterialSpec = z.object({
   name: z.string().optional(),
@@ -453,6 +479,7 @@ export const PluginMaterialSpec = z.object({
   textureUrl: z.string().optional(),
   alpha: z.number().optional(),
   materialType: z.string().optional(),
+  transmission: z.number().min(0).max(1).optional(),
 })
 export type PluginMaterialSpec = z.infer<typeof PluginMaterialSpec>
 
@@ -544,6 +571,16 @@ export type PluginDesignMaterialsApplyArgs = z.infer<
   typeof PluginDesignMaterialsApplyArgs
 >
 
+/** Arguments for the existing host slot-paint contract. */
+export const PluginDesignMaterialsApplyToSlotArgs = z.object({
+  components: z.array(ComponentHandle),
+  slot: z.enum(["glazing", "frame"]),
+  material: z.union([MaterialHandle, PluginMaterialSpec]),
+})
+export type PluginDesignMaterialsApplyToSlotArgs = z.infer<
+  typeof PluginDesignMaterialsApplyToSlotArgs
+>
+
 /** Arguments for {@linkcode PluginDesignMaterialsApi.reset}. */
 export const PluginDesignMaterialsResetArgs = z.object({
   components: z.array(ComponentHandle),

package/src/api/design/networks.ts

@@ -1,6 +1,5 @@
 import * as z from "zod"
 import type { PluginApiReturn } from "../../types"
-import { Vec3Handle } from "../../handles"
 
 const id = z.string().regex(/^[A-Za-z][A-Za-z0-9_-]{0,79}$/)
 const vector = z.tuple([
@@ -413,47 +412,6 @@ export const NetworkCreateArgs = NetworkValidateArgs.extend({
   requestId: z.string().uuid(),
 })
 export const NetworkGetArgs = z.object({ graphId: z.string().uuid() }).strict()
-/** Displacement components are world millimetres, Y up, not Snaptrude units. */
-export const NetworkMoveEdgeArgs = NetworkGetArgs.extend({
-  expectedRevision: z.number().int().positive(),
-  edgeId: id,
-  displacement: Vec3Handle,
-  requestId: z.string().uuid(),
-}).strict()
-export type NetworkMoveEdgeArgs = z.input<typeof NetworkMoveEdgeArgs>
-
-export const NetworkMoveEdgeResult = z.object({
-  graphId: z.string().uuid(),
-  revision: z.number().int().positive(),
-  affectedComponentIds: z.array(z.string().min(1)),
-  alreadyApplied: z.boolean(),
-  /** Queue acceptance does not acknowledge durable storage. */
-  saveStatus: z.enum(["queued", "existing"]),
-}).strict()
-export type NetworkMoveEdgeResult = z.infer<typeof NetworkMoveEdgeResult>
-
-/** Immutable receipts survive undo. Retrying a move never executes it again. */
-export const NetworkEditReceipt = z.object({
-  requestId: z.string().uuid(),
-  fingerprint: z.string().max(1000),
-  revision: z.number().int().positive(),
-  affectedComponentIds: z.array(z.string().min(1)).max(1000),
-}).strict()
-export type NetworkEditReceipt = z.infer<typeof NetworkEditReceipt>
-
-/** Each intentional apply/undo/redo has its own identity. Retries reuse it. */
-export const NetworkTransition = z.object({
-  id: z.string().uuid(),
-  expectedRevision: z.number().int().positive(),
-  forward: z.boolean(),
-}).strict()
-export type NetworkTransition = z.infer<typeof NetworkTransition>
-
-export const NetworkTransitionReceipt = NetworkTransition.extend({
-  requestId: z.string().uuid(),
-  revision: z.number().int().positive(),
-}).strict()
-export type NetworkTransitionReceipt = z.infer<typeof NetworkTransitionReceipt>
 export const NetworkContextArgs = z
   .object({
     offset: z.number().int().nonnegative().default(0),
@@ -516,12 +474,10 @@ export type NetworkComponentBinding = z.infer<typeof NetworkComponentBinding>
 export interface SavedNetworkGraph {
   id: string
   domain: NetworkDomain
-  revision: number
+  revision: 1
   requestId: string
   document: NetworkGraphDocument
   components: NetworkComponentBinding[]
-  edits?: NetworkEditReceipt[]
-  transitions?: NetworkTransitionReceipt[]
 }
 export interface NetworkCreateResult {
   graphId: string
@@ -646,22 +602,6 @@ export abstract class PluginDomainNetworkApi {
 /** Electrical equipment, physical routes and logical circuits, constructed from agent-authored intent. */
 export abstract class PluginElectricalApi extends PluginDomainNetworkApi {}
 /** Plumbing equipment and routed pipe networks, constructed from agent-authored intent. */
-export abstract class PluginPlumbingApi extends PluginDomainNetworkApi {
-  /** Offset one straight pipe perpendicular to its axis between two rigid 90-degree elbows.
-   * Resize adjacent pipes through instance length parameters. Out-of-plane offsets add
-   * one pinned elbow and straight pipe per affected end, preserving fixed outer ports
-   * and existing component identities. Rigid fittings only rotate and translate.
-   * Reject axial sliding, moving tees, constrained fittings,
-   * scene drift, stale revisions, and infeasible family geometry before mutation.
-   * @param args Graph/edge identity, current revision, displacement handle in world mm,
-   * and a unique retry identity. Identical retries return the original receipt after undo too.
-   * @returns Affected component IDs and revision in one undoable, queued transaction.
-   * @example
-   * const displacement = await snaptrude.core.math.vec3.new(0, 300, 0)
-   * await snaptrude.design.plumbing.moveEdge({ graphId, edgeId, expectedRevision,
-   *   displacement, requestId: crypto.randomUUID() })
-   */
-  abstract moveEdge(args: NetworkMoveEdgeArgs): PluginApiReturn<NetworkMoveEdgeResult>
-}
+export abstract class PluginPlumbingApi extends PluginDomainNetworkApi {}
 /** Family-backed air-side HVAC networks. The agent authors engineering intent; the host constructs it. */
 export abstract class PluginMechanicalApi extends PluginDomainNetworkApi {}

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

@@ -1,8 +1,9 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../../types"
-import { ComponentHandle } from "../../../handles"
+import { ComponentHandle, MaterialHandle } from "../../../handles"
 import { PluginDesignChangeResult } from "../lock"
 import { PluginObjectCatalogGroup, PluginObjectCatalogItem } from "../doors"
+import { PluginMaterialSpec } from "../materials"
 
 /**
  * `snaptrude.design.windows` — window-specific reads. Creation lives at
@@ -22,6 +23,33 @@ import { PluginObjectCatalogGroup, PluginObjectCatalogItem } from "../doors"
 export abstract class PluginDesignWindowsApi {
   constructor() {}
 
+  /**
+   * Paint only the window's authored glazing, preserving its frame. Families change
+   * with linked copies; legacy catalogue types change every instance of that type.
+   * Undoable; refuses locked linked/type members or out-of-proposal targets.
+   * @param window Window whose glazing to paint
+   * @param material Handle or spec; preserve the exact listPresets name for PBR glass
+   * @returns Components affected, including linked/type instances
+   * @examplePrompt Use clear glass for this window without changing its frame
+   */
+  public abstract setGlazing(
+    window: ComponentHandle,
+    material: MaterialHandle | PluginMaterialSpec,
+  ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Paint only non-glazing slots (frames, sashes, hardware), never the clear panes.
+   * Scope, locking and undo match setGlazing and design.materials.applyToSlot.
+   * @param window Window whose frame to paint
+   * @param material Handle or spec, e.g. `{ name: preset.name }` from listPresets
+   * @returns Components affected, including linked/type instances
+   * @examplePrompt Use brushed metal for this window's frame without changing the glass
+   */
+  public abstract setFrame(
+    window: ComponentHandle,
+    material: MaterialHandle | PluginMaterialSpec,
+  ): PluginApiReturn<PluginDesignChangeResult>
+
   /**
    * Get the type name of a window — the label that identifies which kind of
    * window the instance is, as shown in its properties.
@@ -310,6 +338,15 @@ export type PluginDesignWindowSetHeightArgs = z.infer<
   typeof PluginDesignWindowSetHeightArgs
 >
 
+/** Arguments for setGlazing / setFrame; both preserve the other authored slot kind. */
+export const PluginDesignWindowSetSlotArgs = z.object({
+  window: ComponentHandle,
+  material: z.union([MaterialHandle, PluginMaterialSpec]),
+})
+export type PluginDesignWindowSetSlotArgs = z.infer<
+  typeof PluginDesignWindowSetSlotArgs
+>
+
 // ---------------------------------------------------------------------------
 // catalog (shared DTOs defined in ../doors, re-exported here for symmetry)
 // ---------------------------------------------------------------------------