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

package/package.json

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

package/src/api/design/family.ts

@@ -18,6 +18,17 @@ import { NetworkFamilyContract } from "./networks"
  * compiles that into a live parametric definition the user can place, flex and
  * save to their library.
  *
+ * New light fittings use schema 1.3, category `Lighting Fixtures`, and
+ * `root.fixture.emitters`. A tube declaration generates its no-cap cylindrical emitting side
+ * and physical light together: key, kind:"tube", expression-valued center/axis/length/radius/
+ * luminousFluxLm, optional colorTemperatureK/enabled; optional numeric tint and material key.
+ * Read getReference() for exact grammar and a runnable example. A glowing finish alone is
+ * not an emitter and incomplete 1.2 fixture definitions fail before scene mutation. Existing
+ * 1.0/1.1 retain legacy semantics; changing only the marker is not a conversion.
+ * Per-instance lights.setEnabled overrides survive flex/save/reload; set/reset reject generated
+ * sources. Edit geometry/output using setParameters. V1 excludes end-cap emission, rectangles,
+ * elliptical/sheared transforms, and complete transport through a surrounding shade.
+ *
  * ## Generic component workflow
  *
  * ```

package/src/api/design/index.ts

@@ -7,6 +7,7 @@ import { PluginDesignDoorsApi } from "./doors"
 import { PluginDesignWindowsApi } from "./windows"
 import { PluginDesignFurnitureApi } from "./furniture"
 import { PluginDesignMaterialsApi } from "./materials"
+import { PluginDesignLightsApi } from "./lights"
 import { PluginDesignEraseApi } from "./erase"
 import { PluginDesignDeleteApi } from "./delete"
 import { PluginDesignBooleanApi } from "./boolean"
@@ -36,6 +37,7 @@ import {
  * - {@linkcode PluginDesignApi.doors} / {@linkcode PluginDesignApi.windows} — fenestration reads + edits
  * - {@linkcode PluginDesignApi.furniture} — furniture catalog reads
  * - {@linkcode PluginDesignApi.materials} — material library + assignment
+ * - {@linkcode PluginDesignApi.lights} — physical point/spot lights on furniture and family containers
  * - {@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
@@ -63,6 +65,8 @@ export abstract class PluginDesignApi {
   public abstract furniture: PluginDesignFurnitureApi
   /** Material library + assignment. See {@linkcode PluginDesignMaterialsApi}. */
   public abstract materials: PluginDesignMaterialsApi
+  /** Physical lights attached to furniture and family containers. See {@linkcode PluginDesignLightsApi}. */
+  public abstract lights: PluginDesignLightsApi
   /** Plan-level adjacency-edge erase (NOT hard delete). See {@linkcode PluginDesignEraseApi}. */
   public abstract erase: PluginDesignEraseApi
   /** Hard entity removal. See {@linkcode PluginDesignDeleteApi}. */
@@ -286,6 +290,7 @@ export * from "./doors"
 export * from "./windows"
 export * from "./furniture"
 export * from "./materials"
+export * from "./lights"
 export * from "./lock"
 export * from "./erase"
 export * from "./delete"

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

@@ -0,0 +1,406 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { ComponentHandle } from "../../../handles"
+import { PluginDesignChangeResult } from "../lock"
+
+/**
+ * Most lights one component can store. This is a **storage quota**, enforced by the host:
+ * a well-formed list longer than this is refused with `RESOURCE_QUOTA_EXCEEDED` (it is not
+ * a schema rule, so the schemas below do not reject it as malformed `VALIDATION`). How many
+ * lights the renderer shades in a frame (and how many shadow layers it can afford) is a
+ * separate, renderer-wide budget; lights over that budget are simply not drawn, they are
+ * never rejected here.
+ */
+export const PLUGIN_MAX_COMPONENT_LIGHTS = 64
+
+/** A light's `key`: 1-32 characters, lower-case start, unique within its component. */
+export const PLUGIN_LIGHT_KEY_PATTERN = /^[a-z][a-z0-9_-]{0,31}$/
+
+const finite = z.number().refine(Number.isFinite, "must be a finite number")
+
+/**
+ * A light's strength. Exactly one of:
+ * - `{ luminousFluxLm }` — total luminous flux in lumens. For a spot this is the flux of
+ *   the whole shaded cone (full intensity inside the inner cone, smooth falloff to zero
+ *   at the outer cone), not the flux of a uniform cone.
+ * - `{ luminousIntensityCd }` — on-axis luminous intensity in candela (a spot's peak).
+ *
+ * Values are physical (not unit-converted): `[0, 10_000_000]`.
+ */
+export const PluginLightIntensity = z.union([
+  z.strictObject({ luminousFluxLm: finite.min(0).max(1e7) }),
+  z.strictObject({ luminousIntensityCd: finite.min(0).max(1e7) }),
+])
+export type PluginLightIntensity = z.infer<typeof PluginLightIntensity>
+
+/**
+ * A spot's cone in degrees. `outerHalfAngleDeg` is in `(0, 90)`; `innerHalfAngleDeg`
+ * (default 70 % of the outer) is where full intensity ends, in `[0, outerHalfAngleDeg]`.
+ */
+export const PluginLightCone = z.strictObject({
+  outerHalfAngleDeg: finite.gt(0).lt(90),
+  innerHalfAngleDeg: finite.min(0).optional(),
+}).refine(
+  (c) => c.innerHalfAngleDeg === undefined || c.innerHalfAngleDeg <= c.outerHalfAngleDeg,
+  { message: "innerHalfAngleDeg must not exceed outerHalfAngleDeg" }
+)
+export type PluginLightCone = z.infer<typeof PluginLightCone>
+
+const Vec3 = z.tuple([finite, finite, finite])
+
+/**
+ * One light stored on a component (a family container or a furniture item).
+ *
+ * The light lives in the component's **local frame** and follows its host transform:
+ * moving, rotating, scaling, mirroring or copying the component carries the light, the
+ * offset scales with the component, and a spot's direction is rotated/mirrored by the
+ * full host transform. Photometric values are physical; lengths are metres, never
+ * engine units.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `key` | `string` | Unique within the component; `^[a-z][a-z0-9_-]{0,31}$`. Names this light in `setEnabled`. |
+ * | `kind` | `"point" \| "spot"` | A point radiates in all directions; a spot needs a `cone`. |
+ * | `offsetMeters` | `[x, y, z]` | Position in the component's local frame, metres. |
+ * | `directionLocal` | `[x, y, z]` | Spot axis in the local frame (default straight down `[0, -1, 0]`); need not be unit length. |
+ * | `intensity` | {@linkcode PluginLightIntensity} | `{ luminousFluxLm }` or `{ luminousIntensityCd }`. |
+ * | `colorTemperatureK` | `number` | 1000-40000 K (default 2700). |
+ * | `tint` | `[r, g, b]` | Linear multipliers in `[0, 4]` on the temperature colour (default white). |
+ * | `cone` | {@linkcode PluginLightCone} | Required for a spot. |
+ * | `sourceRadiusMeters` | `number` | `[0, 1]` m (default 0.02): soft-shadow penumbra and highlight size. |
+ * | `castShadow` | `boolean` | Default `true`; `false` lets light pass through walls. |
+ * | `enabled` | `boolean` | Default `true`; `false` is lamp-off without losing the description. |
+ */
+const PointSpotLight = z
+  .strictObject({
+    key: z.string().regex(PLUGIN_LIGHT_KEY_PATTERN, "key must match ^[a-z][a-z0-9_-]{0,31}$"),
+    kind: z.enum(["point", "spot"]),
+    offsetMeters: Vec3,
+    directionLocal: Vec3.optional(),
+    intensity: PluginLightIntensity,
+    colorTemperatureK: finite.min(1000).max(40000).optional(),
+    tint: z.tuple([finite.min(0).max(4), finite.min(0).max(4), finite.min(0).max(4)]).optional(),
+    cone: PluginLightCone.optional(),
+    sourceRadiusMeters: finite.min(0).max(1).optional(),
+    castShadow: z.boolean().optional(),
+    enabled: z.boolean().optional(),
+  })
+  .superRefine((light, ctx) => {
+    if (light.kind === "spot" && !light.cone) {
+      ctx.addIssue({ code: "custom", path: ["cone"], message: "a spot needs a cone" })
+    }
+    if (light.directionLocal && Math.hypot(...light.directionLocal) < 1e-6) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["directionLocal"],
+        message: "directionLocal must be a non-zero vector",
+      })
+    }
+  })
+/** An outward-emitting circular cylindrical SIDE, never a point with a wider highlight.
+ * End caps do not emit. Dimensions are local metres; the host preserves final total lumens
+ * under circular radial/axial scale and reflection. Shear/elliptical transforms are unsupported.
+ * Tube tint is chromaticity: normalized after tint so output remains luminousFluxLm. A zero
+ * tint is invalid; use enabled=false for lamp-off. Surrounding shade transport is not solved.
+ * Prefer schema 1.3 family.fixture.emitters: creation then owns side geometry and light together.
+ */
+export const PluginFixtureTube = z.strictObject({
+  key: z.string().regex(PLUGIN_LIGHT_KEY_PATTERN),
+  kind: z.literal("tube"),
+  offsetMeters: Vec3,
+  directionLocal: Vec3.refine((v) => Math.hypot(...v) >= 1e-6, "tube axis must be nonzero"),
+  lengthMeters: finite.gt(0),
+  radiusMeters: finite.gt(0),
+  intensity: z.strictObject({ luminousFluxLm: finite.min(0).max(1e7) }),
+  colorTemperatureK: finite.min(1000).max(40000).optional(),
+  tint: z.tuple([finite.min(0).max(4), finite.min(0).max(4), finite.min(0).max(4)])
+    .refine((v) => v.some((channel) => channel > 0), "tube tint must have nonzero luminance").optional(),
+  castShadow: z.boolean().optional(),
+  enabled: z.boolean().optional(),
+})
+export type PluginFixtureTube = z.infer<typeof PluginFixtureTube>
+
+/** Stored authored light, discriminated by kind; tube geometry and flux cannot be omitted. */
+export const PluginFixtureLight = z.union([PointSpotLight, PluginFixtureTube])
+export type PluginFixtureLight = z.infer<typeof PluginFixtureLight>
+
+/**
+ * A component's whole light list, replace-all, unique keys. Its length is not limited here:
+ * the {@linkcode PLUGIN_MAX_COMPONENT_LIGHTS} quota is the host's to enforce and report as
+ * `RESOURCE_QUOTA_EXCEEDED`.
+ */
+export const PluginFixtureLightList = z.array(PluginFixtureLight).superRefine((lights, ctx) => {
+    const seen = new Set<string>()
+    lights.forEach((l, i) => {
+      if (seen.has(l.key)) {
+        ctx.addIssue({
+          code: "custom",
+          path: [i, "key"],
+          message: `duplicate light key "${l.key}"`,
+        })
+      }
+      seen.add(l.key)
+    })
+  })
+export type PluginFixtureLightList = z.infer<typeof PluginFixtureLightList>
+
+/**
+ * Arguments for {@linkcode PluginDesignLightsApi.set}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `component` | {@linkcode ComponentHandle} | A furniture item or family container |
+ * | `lights` | {@linkcode PluginFixtureLight}`[]` | The complete new list (replaces the old one); at most 64 |
+ */
+export const PluginDesignLightsSetArgs = z.object({
+  component: ComponentHandle,
+  lights: PluginFixtureLightList,
+})
+export type PluginDesignLightsSetArgs = z.infer<typeof PluginDesignLightsSetArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignLightsApi.setEnabled}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `component` | {@linkcode ComponentHandle} | The component that owns the light |
+ * | `key` | `string` | The light's key |
+ * | `enabled` | `boolean` | `true` = on, `false` = off |
+ */
+export const PluginDesignLightsSetEnabledArgs = z.object({
+  component: ComponentHandle,
+  key: z.string().regex(PLUGIN_LIGHT_KEY_PATTERN),
+  enabled: z.boolean(),
+})
+export type PluginDesignLightsSetEnabledArgs = z.infer<typeof PluginDesignLightsSetEnabledArgs>
+
+/** Arguments for {@linkcode PluginDesignLightsApi.reset}: the components to clear. */
+export const PluginDesignLightsResetArgs = z.object({
+  components: z.array(ComponentHandle),
+})
+export type PluginDesignLightsResetArgs = z.infer<typeof PluginDesignLightsResetArgs>
+
+/**
+ * Options for {@linkcode PluginDesignLightsApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `includeDisabled` | `boolean` | Keep lights whose `enabled` is `false` (default `true`). `false` drops them, and components left with none. |
+ */
+export const PluginDesignLightsListOptions = z.object({
+  includeDisabled: z.boolean().optional(),
+})
+export type PluginDesignLightsListOptions = z.infer<typeof PluginDesignLightsListOptions>
+
+/** One entry of {@linkcode PluginDesignLightsApi.list}: a component and its lights. */
+export const PluginComponentLights = z.object({
+  component: ComponentHandle,
+  lights: z.array(PluginFixtureLight),
+})
+export type PluginComponentLights = z.infer<typeof PluginComponentLights>
+
+/**
+ * The kind of light fitting a component is recognised as, which gives it default lights while it
+ * has no stored list (see {@linkcode PluginDesignLightsApi.effective}).
+ */
+export const PluginLightFitting = z.enum([
+  "floor-lamp",
+  "table-lamp",
+  "pendant",
+  "pendant-cluster",
+  "downlight",
+  "linear-batten",
+  "wall-sconce",
+  "luminaire",
+])
+export type PluginLightFitting = z.infer<typeof PluginLightFitting>
+
+/**
+ * What a component lights the model with ({@linkcode PluginDesignLightsApi.effective}).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `source` | `'stored' \| 'default' \| 'none'` | `stored`: its stored list (an empty list included: explicitly no lights). `default`: nothing stored and it is a light fitting, so it lights with its fitting's defaults. `none`: neither |
+ * | `fitting` | {@linkcode PluginLightFitting} `\| null` | The fitting it is recognised as, or `null` |
+ * | `lights` | {@linkcode PluginFixtureLight}`[]` | The lights it lights with |
+ */
+export const PluginEffectiveLights = z.object({
+  source: z.enum(["stored", "default", "none"]),
+  fitting: PluginLightFitting.nullable(),
+  lights: z.array(PluginFixtureLight),
+})
+export type PluginEffectiveLights = z.infer<typeof PluginEffectiveLights>
+
+/**
+ * `snaptrude.design.lights` — physical point, spot and cylindrical-side tube sources.
+ * New fixtures should be schema 1.3 families with fixture.emitters, not glow-only meshes.
+ * Generated source geometry and output are one recipe: set/reset reject recipe-owned lights
+ * with PRECONDITION_FAILED. Edit family parameters instead. setEnabled stores a keyed override
+ * surviving flex/save/reload; removed recipe keys lose the override, and undo restores it.
+ *
+ * A light belongs to a **furniture item or a parametric family container** and is
+ * stored with it: it is saved, reloaded, copied, pasted and restored by undo with the
+ * component, and follows its transform (offsets scale with the component, a spot's
+ * direction follows the full rotation/mirroring). Build a light fitting as a family
+ * (or place a furniture item), then attach its lights to the returned
+ * {@linkcode ComponentHandle}. Other kinds (walls, masses, spaces) are rejected with
+ * `PRECONDITION_FAILED`.
+ *
+ * Light fittings (lamps, pendants, downlights, battens, sconces) light by **default** while
+ * nothing is stored on them; {@linkcode PluginDesignLightsApi.effective} reads those defaults.
+ *
+ * Lists are **replace-all**: {@linkcode PluginDesignLightsApi.set} sends the whole list.
+ * `get` and `list` return exactly what was stored (no defaults are filled in). Each mutation is one
+ * undo step; writing the value already stored is a no-op. A component holds at most 64
+ * lights (more is `RESOURCE_QUOTA_EXCEEDED`, not `VALIDATION`); how many the renderer draws in one frame is a separate budget and never
+ * rejects a write.
+ *
+ * Errors: bad light data → `VALIDATION` (`details` lists the issues); unknown/stale
+ * handle → `HANDLE_INVALID`; unsupported component kind, locked component or missing
+ * geometry → `PRECONDITION_FAILED`; more than 64 lights → `RESOURCE_QUOTA_EXCEEDED`.
+ */
+export abstract class PluginDesignLightsApi {
+  constructor() {}
+
+  /**
+   * Read the lights stored on a component, exactly as written (`[]` when it has none).
+   *
+   * @param component The furniture item or family container
+   * @returns The component's {@linkcode PluginFixtureLight}`[]`
+   *
+   * @examplePrompt What lights does this lamp have?
+   * @examplePrompt Show me the light settings on the pendant I just built
+   * @examplePrompt Is there a light attached to this fixture?
+   * @examplePrompt Read the lighting of the selected furniture
+   *
+   * # Example
+   * ```ts
+   * const lights = await snaptrude.design.lights.get(lamp)
+   * console.log(lights.map((l) => l.key))
+   * ```
+   */
+  public abstract get(component: ComponentHandle): PluginApiReturn<PluginFixtureLight[]>
+
+  /**
+   * Read what a component lights the model with: its stored lights when it has a stored list
+   * (an empty one included), else the default lights of the light fitting it is (a floor lamp,
+   * a pendant, a downlight...), else none. Defaults are derived, never stored. Read-only.
+   *
+   * @param component The furniture item or family container
+   * @returns {@linkcode PluginEffectiveLights}
+   *
+   * @examplePrompt Does this lamp light the room?
+   * @examplePrompt What light does the pendant give off by default?
+   * @examplePrompt Which lights in this room come from the fittings' defaults?
+   * @examplePrompt Show the effective lighting of the selected fixture
+   *
+   * # Example
+   * ```ts
+   * const { source, fitting, lights } = await snaptrude.design.lights.effective(lamp)
+   * console.log(source, fitting, lights.length)
+   * ```
+   */
+  public abstract effective(component: ComponentHandle): PluginApiReturn<PluginEffectiveLights>
+
+  /**
+   * List every component that has lights, with its lights. Disabled lights are included
+   * unless `includeDisabled` is `false`.
+   *
+   * @param options Optional {@linkcode PluginDesignLightsListOptions}
+   * @returns {@linkcode PluginComponentLights}`[]`
+   *
+   * @examplePrompt Which fixtures in the model have lights?
+   * @examplePrompt List all the lamps that are switched on
+   * @examplePrompt How many lights are in this project?
+   * @examplePrompt Show every light fixture and its settings
+   *
+   * # Example
+   * ```ts
+   * const lit = await snaptrude.design.lights.list({ includeDisabled: false })
+   * console.log(lit.length, "components are lighting the model")
+   * ```
+   */
+  public abstract list(
+    options?: PluginDesignLightsListOptions
+  ): PluginApiReturn<PluginComponentLights[]>
+
+  /**
+   * Replace a component's lights with `lights` (replace-all; `[]` removes them all).
+   * Recipe-owned fixture sources reject this operation; edit the family parameters instead.
+   * One undo step. Writing the list already stored does nothing. The whole list is
+   * validated first; on any problem nothing changes.
+   *
+   * @param component The furniture item or family container to light
+   * @param lights The complete new list, at most 64, unique keys
+   * @returns The affected component
+   *
+   * @examplePrompt Add a warm 1600 lumen bulb to the pendant lamp
+   * @examplePrompt Put a 38 degree downlight spot in this ceiling fixture
+   * @examplePrompt Make this lamp glow at 3000K
+   * @examplePrompt Give the table lamp a shadow-casting point light
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.design.lights.set(pendant, [
+   *   {
+   *     key: "bulb",
+   *     kind: "point",
+   *     offsetMeters: [0, -0.3, 0],
+   *     intensity: { luminousFluxLm: 1600 },
+   *     colorTemperatureK: 2700,
+   *   },
+   * ])
+   * ```
+   */
+  public abstract set(
+    component: ComponentHandle,
+    lights: PluginFixtureLight[]
+  ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Switch one light on or off without resending its description. One undo step; a
+   * no-op when it already has that state.
+   *
+   * @param component The component that owns the light
+   * @param key The light's `key`
+   * @param enabled `true` = on, `false` = off
+   * @returns The affected component
+   *
+   * @examplePrompt Turn off the bulb in this lamp
+   * @examplePrompt Switch the downlight back on
+   * @examplePrompt Dim the room by turning off the pendant light
+   * @examplePrompt Toggle the lamp
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.design.lights.setEnabled(pendant, "bulb", false)
+   * ```
+   */
+  public abstract setEnabled(
+    component: ComponentHandle,
+    key: string,
+    enabled: boolean
+  ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Remove all lights from the given components. Every component is checked first and
+   * recipe-owned fixture sources reject the entire batch before any component changes.
+   * nothing changes if any is invalid; components without lights are skipped. One undo
+   * step for the whole call.
+   *
+   * @param components The components to clear
+   * @returns The components that were affected
+   *
+   * @examplePrompt Remove the lights from this fixture
+   * @examplePrompt Clear all the lamps' lighting
+   * @examplePrompt Take the light off the selected pendants
+   * @examplePrompt Reset the lights on these components
+   *
+   * # Example
+   * ```ts
+   * const lit = await snaptrude.design.lights.list()
+   * await snaptrude.design.lights.reset(lit.map((e) => e.component))
+   * ```
+   */
+  public abstract reset(components: ComponentHandle[]): PluginApiReturn<PluginDesignChangeResult>
+}

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

@@ -21,6 +21,12 @@ import { ComponentHandle, MaterialHandle } from "../../../handles"
  * is durable only while the component's BREP topology (face count/order) is unchanged.
  *
  * `copy` (needs an undo wrapper) lands in a later pass.
+ *
+ * A material is a reusable finish, not a fixture source. Emissive appearance alone does not
+ * create a physical light. Author new fixtures through schema 1.3 family.fixture.emitters:
+ * generated side geometry, total lumens, temperature and enabled state belong to the placed
+ * fixture, not its shared material. Its visible emission is derived from the same photometry
+ * used by direct and DDGI lighting. Repainting a source must not change output or another lamp.
  */
 export abstract class PluginDesignMaterialsApi {
   constructor() {}
@@ -48,16 +54,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 +177,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`
@@ -319,9 +348,11 @@ export abstract class PluginDesignMaterialsApi {
    * @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
+   * @examplePrompt Make the lampshade a linen that glows when the lamp is on
    *
    * # Example
    * ```ts
+   * const linen = await snaptrude.design.materials.create({ name: "Linen Shade", color: "#efe6d4", transmission: 0.3 })
    * 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)
@@ -425,6 +456,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 +465,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 +474,18 @@ 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): the share of a fixture light the material passes through, scattered |
+ *
+ * `transmission` is for lampshades and lenses: a fabric or paper shade (linen ~0.3, paper ~0.5)
+ * or an opal diffuser (~0.6). A component painted with it glows from the fixture lights
+ * (`design.lights`) behind it and passes that share of their light into the room. Fixture
+ * lights only: daylight does not pass. Leave it out for opaque finishes. Not combinable with a
+ * catalog (listPresets) name.
  */
 export const PluginMaterialSpec = z.object({
   name: z.string().optional(),
@@ -453,6 +493,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 +585,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),