@snaptrude/plugin-core 1.0.2-plainpoint-20261026.2 → 1.1.0-pbr-20261026.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (95) hide show
  1. package/dist/api/core/camera/index.d.ts +4 -12
  2. package/dist/api/core/camera/index.d.ts.map +1 -1
  3. package/dist/api/core/comment/index.d.ts +3 -7
  4. package/dist/api/core/comment/index.d.ts.map +1 -1
  5. package/dist/api/core/geom/create/index.d.ts +21 -69
  6. package/dist/api/core/geom/create/index.d.ts.map +1 -1
  7. package/dist/api/core/geom/query/circle.d.ts +11 -31
  8. package/dist/api/core/geom/query/circle.d.ts.map +1 -1
  9. package/dist/api/core/geom/query/contour.d.ts +7 -19
  10. package/dist/api/core/geom/query/contour.d.ts.map +1 -1
  11. package/dist/api/core/geom/query/curve.d.ts +24 -72
  12. package/dist/api/core/geom/query/curve.d.ts.map +1 -1
  13. package/dist/api/core/geom/query/profile.d.ts +7 -19
  14. package/dist/api/core/geom/query/profile.d.ts.map +1 -1
  15. package/dist/api/core/geom/update/contour.d.ts +12 -36
  16. package/dist/api/core/geom/update/contour.d.ts.map +1 -1
  17. package/dist/api/core/geom/update/curve.d.ts +5 -13
  18. package/dist/api/core/geom/update/curve.d.ts.map +1 -1
  19. package/dist/api/core/geom/update/profile.d.ts +12 -36
  20. package/dist/api/core/geom/update/profile.d.ts.map +1 -1
  21. package/dist/api/core/io/import/index.d.ts +3 -7
  22. package/dist/api/core/io/import/index.d.ts.map +1 -1
  23. package/dist/api/core/math/quat.d.ts +2 -2
  24. package/dist/api/core/math/quat.d.ts.map +1 -1
  25. package/dist/api/core/math/vec3.d.ts +15 -15
  26. package/dist/api/core/math/vec3.d.ts.map +1 -1
  27. package/dist/api/design/boolean/index.d.ts +4 -20
  28. package/dist/api/design/boolean/index.d.ts.map +1 -1
  29. package/dist/api/design/create/bulk-items.d.ts +4 -20
  30. package/dist/api/design/create/bulk-items.d.ts.map +1 -1
  31. package/dist/api/design/create/index.d.ts +27 -67
  32. package/dist/api/design/create/index.d.ts.map +1 -1
  33. package/dist/api/design/delete/index.d.ts +7 -14
  34. package/dist/api/design/delete/index.d.ts.map +1 -1
  35. package/dist/api/design/dimensions.d.ts +6 -14
  36. package/dist/api/design/dimensions.d.ts.map +1 -1
  37. package/dist/api/design/edit/index.d.ts +3 -7
  38. package/dist/api/design/edit/index.d.ts.map +1 -1
  39. package/dist/api/design/erase/index.d.ts +2 -10
  40. package/dist/api/design/erase/index.d.ts.map +1 -1
  41. package/dist/api/design/family.d.ts +12 -5
  42. package/dist/api/design/family.d.ts.map +1 -1
  43. package/dist/api/design/index.d.ts +5 -0
  44. package/dist/api/design/index.d.ts.map +1 -1
  45. package/dist/api/design/lights/index.d.ts +504 -0
  46. package/dist/api/design/lights/index.d.ts.map +1 -0
  47. package/dist/api/design/lock.d.ts +0 -3
  48. package/dist/api/design/lock.d.ts.map +1 -1
  49. package/dist/api/design/materials/index.d.ts +63 -7
  50. package/dist/api/design/materials/index.d.ts.map +1 -1
  51. package/dist/api/design/transform/index.d.ts +8 -28
  52. package/dist/api/design/transform/index.d.ts.map +1 -1
  53. package/dist/api/design/windows/index.d.ts +34 -1
  54. package/dist/api/design/windows/index.d.ts.map +1 -1
  55. package/dist/api/entity/space.d.ts +6 -30
  56. package/dist/api/entity/space.d.ts.map +1 -1
  57. package/dist/api/presentation/drawings.d.ts +1 -1
  58. package/dist/handles.d.ts +0 -8
  59. package/dist/handles.d.ts.map +1 -1
  60. package/dist/index.cjs +2570 -2428
  61. package/dist/index.cjs.map +1 -1
  62. package/dist/index.js +2553 -2427
  63. package/dist/index.js.map +1 -1
  64. package/package.json +13 -13
  65. package/src/api/core/camera/index.ts +5 -5
  66. package/src/api/core/comment/index.ts +3 -3
  67. package/src/api/core/geom/create/index.ts +25 -25
  68. package/src/api/core/geom/query/circle.ts +11 -11
  69. package/src/api/core/geom/query/contour.ts +6 -7
  70. package/src/api/core/geom/query/curve.ts +25 -25
  71. package/src/api/core/geom/query/profile.ts +6 -7
  72. package/src/api/core/geom/update/contour.ts +11 -12
  73. package/src/api/core/geom/update/curve.ts +5 -5
  74. package/src/api/core/geom/update/profile.ts +11 -12
  75. package/src/api/core/io/import/index.ts +2 -3
  76. package/src/api/core/math/quat.ts +2 -2
  77. package/src/api/core/math/vec3.ts +16 -16
  78. package/src/api/design/boolean/index.ts +2 -2
  79. package/src/api/design/create/bulk-items.ts +2 -3
  80. package/src/api/design/create/index.ts +26 -27
  81. package/src/api/design/delete/index.ts +7 -14
  82. package/src/api/design/dimensions.ts +4 -5
  83. package/src/api/design/edit/index.ts +3 -3
  84. package/src/api/design/erase/index.ts +2 -2
  85. package/src/api/design/family.ts +12 -2
  86. package/src/api/design/index.ts +5 -0
  87. package/src/api/design/lights/index.ts +406 -0
  88. package/src/api/design/lock.ts +0 -6
  89. package/src/api/design/materials/index.ts +58 -7
  90. package/src/api/design/transform/index.ts +7 -15
  91. package/src/api/design/windows/index.ts +38 -1
  92. package/src/api/entity/space.ts +4 -5
  93. package/src/handles.ts +0 -11
  94. package/api-manifest.json +0 -10607
  95. package/test/handles.test.mjs +0 -36
@@ -5,7 +5,6 @@ import {
5
5
  DimensionHandle,
6
6
  Vec3Components,
7
7
  Vec3Handle,
8
- Vec3Input,
9
8
  } from "../../handles"
10
9
 
11
10
  /**
@@ -95,8 +94,8 @@ export abstract class PluginDesignDimensionsApi {
95
94
  * ```
96
95
  */
97
96
  public abstract create(
98
- from: Vec3Input,
99
- to: Vec3Input,
97
+ from: Vec3Handle,
98
+ to: Vec3Handle,
100
99
  anchor: ComponentHandle,
101
100
  options?: { anchorTo?: ComponentHandle; offset?: number },
102
101
  ): PluginApiReturn<DimensionHandle>
@@ -363,8 +362,8 @@ export type PluginDimensionsChangeResult = z.infer<
363
362
  * TRANSPORT: positional args — validated host-side as this object.
364
363
  */
365
364
  export const PluginDesignDimensionsCreateArgs = z.object({
366
- from: Vec3Input,
367
- to: Vec3Input,
365
+ from: Vec3Handle,
366
+ to: Vec3Handle,
368
367
  anchor: ComponentHandle,
369
368
  anchorTo: ComponentHandle.optional(),
370
369
  offset: z.number().finite().optional(),
@@ -1,6 +1,6 @@
1
1
  import * as z from "zod"
2
2
  import { PluginApiReturn } from "../../../types"
3
- import { ComponentHandle, Vec3Input } from "../../../handles"
3
+ import { ComponentHandle, Vec3Handle } from "../../../handles"
4
4
  import { OffsetSplitOutcome } from "../shared"
5
5
 
6
6
  /**
@@ -41,7 +41,7 @@ export abstract class PluginDesignEditApi {
41
41
  public abstract offsetSplit(
42
42
  component: ComponentHandle,
43
43
  offsetDistance: number,
44
- options?: { profilePickPoint?: Vec3Input },
44
+ options?: { profilePickPoint?: Vec3Handle },
45
45
  ): PluginApiReturn<OffsetSplitOutcome>
46
46
  }
47
47
 
@@ -49,6 +49,6 @@ export abstract class PluginDesignEditApi {
49
49
  export const PluginDesignOffsetSplitArgs = z.object({
50
50
  component: ComponentHandle,
51
51
  offsetDistance: z.number(),
52
- profilePickPoint: Vec3Input.optional(),
52
+ profilePickPoint: Vec3Handle.optional(),
53
53
  })
54
54
  export type PluginDesignOffsetSplitArgs = z.infer<typeof PluginDesignOffsetSplitArgs>
@@ -1,6 +1,6 @@
1
1
  import * as z from "zod"
2
2
  import { PluginApiReturn } from "../../../types"
3
- import { ComponentHandle, Vec3Input } from "../../../handles"
3
+ import { ComponentHandle, Vec3Handle } from "../../../handles"
4
4
 
5
5
  /**
6
6
  * The erase strategies exposed to plugins. `SplitAndUnion` is *enumerable* but
@@ -38,7 +38,7 @@ export const ErasableEdgeRef = z.object({
38
38
  /** The components this edge is incident to — one for external (DirectDelete); two or more for internal (DirectUnion; 3+ at T-junctions where several masses share the edge). */
39
39
  components: z.array(ComponentHandle),
40
40
  /** A representative point on the edge (its head endpoint). Diagnostic only. */
41
- snapPoint: Vec3Input,
41
+ snapPoint: Vec3Handle,
42
42
  })
43
43
  export type ErasableEdgeRef = z.infer<typeof ErasableEdgeRef>
44
44
 
@@ -5,7 +5,6 @@ import {
5
5
  ComponentHandle,
6
6
  Vec3Components,
7
7
  Vec3Handle,
8
- Vec3Input,
9
8
  } from "../../handles"
10
9
  import { NetworkFamilyContract } from "./networks"
11
10
 
@@ -19,6 +18,17 @@ import { NetworkFamilyContract } from "./networks"
19
18
  * compiles that into a live parametric definition the user can place, flex and
20
19
  * save to their library.
21
20
  *
21
+ * New light fittings use schema 1.3, category `Lighting Fixtures`, and
22
+ * `root.fixture.emitters`. A tube declaration generates its no-cap cylindrical emitting side
23
+ * and physical light together: key, kind:"tube", expression-valued center/axis/length/radius/
24
+ * luminousFluxLm, optional colorTemperatureK/enabled; optional numeric tint and material key.
25
+ * Read getReference() for exact grammar and a runnable example. A glowing finish alone is
26
+ * not an emitter and incomplete 1.2 fixture definitions fail before scene mutation. Existing
27
+ * 1.0/1.1 retain legacy semantics; changing only the marker is not a conversion.
28
+ * Per-instance lights.setEnabled overrides survive flex/save/reload; set/reset reject generated
29
+ * sources. Edit geometry/output using setParameters. V1 excludes end-cap emission, rectangles,
30
+ * elliptical/sheared transforms, and complete transport through a surrounding shade.
31
+ *
22
32
  * ## Generic component workflow
23
33
  *
24
34
  * ```
@@ -1320,7 +1330,7 @@ export type PluginDesignFamilyDeleteArgs = z.infer<
1320
1330
  export const PluginDesignFamilyPlaceArgs = z.object({
1321
1331
  id: z.string().optional(),
1322
1332
  version: z.number().int().positive().optional(),
1323
- position: z.union([Vec3Input, Vec3Components]).optional(),
1333
+ position: z.union([Vec3Handle, Vec3Components]).optional(),
1324
1334
  rotation: z.number().optional(),
1325
1335
  values: z.record(z.string(), z.union([z.number(), z.string()])).optional(),
1326
1336
  storey: z.number().int().optional(),
@@ -7,6 +7,7 @@ import { PluginDesignDoorsApi } from "./doors"
7
7
  import { PluginDesignWindowsApi } from "./windows"
8
8
  import { PluginDesignFurnitureApi } from "./furniture"
9
9
  import { PluginDesignMaterialsApi } from "./materials"
10
+ import { PluginDesignLightsApi } from "./lights"
10
11
  import { PluginDesignEraseApi } from "./erase"
11
12
  import { PluginDesignDeleteApi } from "./delete"
12
13
  import { PluginDesignBooleanApi } from "./boolean"
@@ -36,6 +37,7 @@ import {
36
37
  * - {@linkcode PluginDesignApi.doors} / {@linkcode PluginDesignApi.windows} — fenestration reads + edits
37
38
  * - {@linkcode PluginDesignApi.furniture} — furniture catalog reads
38
39
  * - {@linkcode PluginDesignApi.materials} — material library + assignment
40
+ * - {@linkcode PluginDesignApi.lights} — physical point/spot lights on furniture and family containers
39
41
  * - {@linkcode PluginDesignApi.boolean} — CSG boolean ops (union / subtract / intersect)
40
42
  * - {@linkcode PluginDesignApi.erase} — plan-level adjacency-edge erase (NOT hard delete)
41
43
  * - {@linkcode PluginDesignApi.delete} — hard entity removal
@@ -63,6 +65,8 @@ export abstract class PluginDesignApi {
63
65
  public abstract furniture: PluginDesignFurnitureApi
64
66
  /** Material library + assignment. See {@linkcode PluginDesignMaterialsApi}. */
65
67
  public abstract materials: PluginDesignMaterialsApi
68
+ /** Physical lights attached to furniture and family containers. See {@linkcode PluginDesignLightsApi}. */
69
+ public abstract lights: PluginDesignLightsApi
66
70
  /** Plan-level adjacency-edge erase (NOT hard delete). See {@linkcode PluginDesignEraseApi}. */
67
71
  public abstract erase: PluginDesignEraseApi
68
72
  /** Hard entity removal. See {@linkcode PluginDesignDeleteApi}. */
@@ -286,6 +290,7 @@ export * from "./doors"
286
290
  export * from "./windows"
287
291
  export * from "./furniture"
288
292
  export * from "./materials"
293
+ export * from "./lights"
289
294
  export * from "./lock"
290
295
  export * from "./erase"
291
296
  export * from "./delete"
@@ -0,0 +1,406 @@
1
+ import * as z from "zod"
2
+ import { PluginApiReturn } from "../../../types"
3
+ import { ComponentHandle } from "../../../handles"
4
+ import { PluginDesignChangeResult } from "../lock"
5
+
6
+ /**
7
+ * Most lights one component can store. This is a **storage quota**, enforced by the host:
8
+ * a well-formed list longer than this is refused with `RESOURCE_QUOTA_EXCEEDED` (it is not
9
+ * a schema rule, so the schemas below do not reject it as malformed `VALIDATION`). How many
10
+ * lights the renderer shades in a frame (and how many shadow layers it can afford) is a
11
+ * separate, renderer-wide budget; lights over that budget are simply not drawn, they are
12
+ * never rejected here.
13
+ */
14
+ export const PLUGIN_MAX_COMPONENT_LIGHTS = 64
15
+
16
+ /** A light's `key`: 1-32 characters, lower-case start, unique within its component. */
17
+ export const PLUGIN_LIGHT_KEY_PATTERN = /^[a-z][a-z0-9_-]{0,31}$/
18
+
19
+ const finite = z.number().refine(Number.isFinite, "must be a finite number")
20
+
21
+ /**
22
+ * A light's strength. Exactly one of:
23
+ * - `{ luminousFluxLm }` — total luminous flux in lumens. For a spot this is the flux of
24
+ * the whole shaded cone (full intensity inside the inner cone, smooth falloff to zero
25
+ * at the outer cone), not the flux of a uniform cone.
26
+ * - `{ luminousIntensityCd }` — on-axis luminous intensity in candela (a spot's peak).
27
+ *
28
+ * Values are physical (not unit-converted): `[0, 10_000_000]`.
29
+ */
30
+ export const PluginLightIntensity = z.union([
31
+ z.strictObject({ luminousFluxLm: finite.min(0).max(1e7) }),
32
+ z.strictObject({ luminousIntensityCd: finite.min(0).max(1e7) }),
33
+ ])
34
+ export type PluginLightIntensity = z.infer<typeof PluginLightIntensity>
35
+
36
+ /**
37
+ * A spot's cone in degrees. `outerHalfAngleDeg` is in `(0, 90)`; `innerHalfAngleDeg`
38
+ * (default 70 % of the outer) is where full intensity ends, in `[0, outerHalfAngleDeg]`.
39
+ */
40
+ export const PluginLightCone = z.strictObject({
41
+ outerHalfAngleDeg: finite.gt(0).lt(90),
42
+ innerHalfAngleDeg: finite.min(0).optional(),
43
+ }).refine(
44
+ (c) => c.innerHalfAngleDeg === undefined || c.innerHalfAngleDeg <= c.outerHalfAngleDeg,
45
+ { message: "innerHalfAngleDeg must not exceed outerHalfAngleDeg" }
46
+ )
47
+ export type PluginLightCone = z.infer<typeof PluginLightCone>
48
+
49
+ const Vec3 = z.tuple([finite, finite, finite])
50
+
51
+ /**
52
+ * One light stored on a component (a family container or a furniture item).
53
+ *
54
+ * The light lives in the component's **local frame** and follows its host transform:
55
+ * moving, rotating, scaling, mirroring or copying the component carries the light, the
56
+ * offset scales with the component, and a spot's direction is rotated/mirrored by the
57
+ * full host transform. Photometric values are physical; lengths are metres, never
58
+ * engine units.
59
+ *
60
+ * | Property | Type | Description |
61
+ * |---|---|---|
62
+ * | `key` | `string` | Unique within the component; `^[a-z][a-z0-9_-]{0,31}$`. Names this light in `setEnabled`. |
63
+ * | `kind` | `"point" \| "spot"` | A point radiates in all directions; a spot needs a `cone`. |
64
+ * | `offsetMeters` | `[x, y, z]` | Position in the component's local frame, metres. |
65
+ * | `directionLocal` | `[x, y, z]` | Spot axis in the local frame (default straight down `[0, -1, 0]`); need not be unit length. |
66
+ * | `intensity` | {@linkcode PluginLightIntensity} | `{ luminousFluxLm }` or `{ luminousIntensityCd }`. |
67
+ * | `colorTemperatureK` | `number` | 1000-40000 K (default 2700). |
68
+ * | `tint` | `[r, g, b]` | Linear multipliers in `[0, 4]` on the temperature colour (default white). |
69
+ * | `cone` | {@linkcode PluginLightCone} | Required for a spot. |
70
+ * | `sourceRadiusMeters` | `number` | `[0, 1]` m (default 0.02): soft-shadow penumbra and highlight size. |
71
+ * | `castShadow` | `boolean` | Default `true`; `false` lets light pass through walls. |
72
+ * | `enabled` | `boolean` | Default `true`; `false` is lamp-off without losing the description. |
73
+ */
74
+ const PointSpotLight = z
75
+ .strictObject({
76
+ key: z.string().regex(PLUGIN_LIGHT_KEY_PATTERN, "key must match ^[a-z][a-z0-9_-]{0,31}$"),
77
+ kind: z.enum(["point", "spot"]),
78
+ offsetMeters: Vec3,
79
+ directionLocal: Vec3.optional(),
80
+ intensity: PluginLightIntensity,
81
+ colorTemperatureK: finite.min(1000).max(40000).optional(),
82
+ tint: z.tuple([finite.min(0).max(4), finite.min(0).max(4), finite.min(0).max(4)]).optional(),
83
+ cone: PluginLightCone.optional(),
84
+ sourceRadiusMeters: finite.min(0).max(1).optional(),
85
+ castShadow: z.boolean().optional(),
86
+ enabled: z.boolean().optional(),
87
+ })
88
+ .superRefine((light, ctx) => {
89
+ if (light.kind === "spot" && !light.cone) {
90
+ ctx.addIssue({ code: "custom", path: ["cone"], message: "a spot needs a cone" })
91
+ }
92
+ if (light.directionLocal && Math.hypot(...light.directionLocal) < 1e-6) {
93
+ ctx.addIssue({
94
+ code: "custom",
95
+ path: ["directionLocal"],
96
+ message: "directionLocal must be a non-zero vector",
97
+ })
98
+ }
99
+ })
100
+ /** An outward-emitting circular cylindrical SIDE, never a point with a wider highlight.
101
+ * End caps do not emit. Dimensions are local metres; the host preserves final total lumens
102
+ * under circular radial/axial scale and reflection. Shear/elliptical transforms are unsupported.
103
+ * Tube tint is chromaticity: normalized after tint so output remains luminousFluxLm. A zero
104
+ * tint is invalid; use enabled=false for lamp-off. Surrounding shade transport is not solved.
105
+ * Prefer schema 1.3 family.fixture.emitters: creation then owns side geometry and light together.
106
+ */
107
+ export const PluginFixtureTube = z.strictObject({
108
+ key: z.string().regex(PLUGIN_LIGHT_KEY_PATTERN),
109
+ kind: z.literal("tube"),
110
+ offsetMeters: Vec3,
111
+ directionLocal: Vec3.refine((v) => Math.hypot(...v) >= 1e-6, "tube axis must be nonzero"),
112
+ lengthMeters: finite.gt(0),
113
+ radiusMeters: finite.gt(0),
114
+ intensity: z.strictObject({ luminousFluxLm: finite.min(0).max(1e7) }),
115
+ colorTemperatureK: finite.min(1000).max(40000).optional(),
116
+ tint: z.tuple([finite.min(0).max(4), finite.min(0).max(4), finite.min(0).max(4)])
117
+ .refine((v) => v.some((channel) => channel > 0), "tube tint must have nonzero luminance").optional(),
118
+ castShadow: z.boolean().optional(),
119
+ enabled: z.boolean().optional(),
120
+ })
121
+ export type PluginFixtureTube = z.infer<typeof PluginFixtureTube>
122
+
123
+ /** Stored authored light, discriminated by kind; tube geometry and flux cannot be omitted. */
124
+ export const PluginFixtureLight = z.union([PointSpotLight, PluginFixtureTube])
125
+ export type PluginFixtureLight = z.infer<typeof PluginFixtureLight>
126
+
127
+ /**
128
+ * A component's whole light list, replace-all, unique keys. Its length is not limited here:
129
+ * the {@linkcode PLUGIN_MAX_COMPONENT_LIGHTS} quota is the host's to enforce and report as
130
+ * `RESOURCE_QUOTA_EXCEEDED`.
131
+ */
132
+ export const PluginFixtureLightList = z.array(PluginFixtureLight).superRefine((lights, ctx) => {
133
+ const seen = new Set<string>()
134
+ lights.forEach((l, i) => {
135
+ if (seen.has(l.key)) {
136
+ ctx.addIssue({
137
+ code: "custom",
138
+ path: [i, "key"],
139
+ message: `duplicate light key "${l.key}"`,
140
+ })
141
+ }
142
+ seen.add(l.key)
143
+ })
144
+ })
145
+ export type PluginFixtureLightList = z.infer<typeof PluginFixtureLightList>
146
+
147
+ /**
148
+ * Arguments for {@linkcode PluginDesignLightsApi.set}.
149
+ *
150
+ * | Property | Type | Description |
151
+ * |---|---|---|
152
+ * | `component` | {@linkcode ComponentHandle} | A furniture item or family container |
153
+ * | `lights` | {@linkcode PluginFixtureLight}`[]` | The complete new list (replaces the old one); at most 64 |
154
+ */
155
+ export const PluginDesignLightsSetArgs = z.object({
156
+ component: ComponentHandle,
157
+ lights: PluginFixtureLightList,
158
+ })
159
+ export type PluginDesignLightsSetArgs = z.infer<typeof PluginDesignLightsSetArgs>
160
+
161
+ /**
162
+ * Arguments for {@linkcode PluginDesignLightsApi.setEnabled}.
163
+ *
164
+ * | Property | Type | Description |
165
+ * |---|---|---|
166
+ * | `component` | {@linkcode ComponentHandle} | The component that owns the light |
167
+ * | `key` | `string` | The light's key |
168
+ * | `enabled` | `boolean` | `true` = on, `false` = off |
169
+ */
170
+ export const PluginDesignLightsSetEnabledArgs = z.object({
171
+ component: ComponentHandle,
172
+ key: z.string().regex(PLUGIN_LIGHT_KEY_PATTERN),
173
+ enabled: z.boolean(),
174
+ })
175
+ export type PluginDesignLightsSetEnabledArgs = z.infer<typeof PluginDesignLightsSetEnabledArgs>
176
+
177
+ /** Arguments for {@linkcode PluginDesignLightsApi.reset}: the components to clear. */
178
+ export const PluginDesignLightsResetArgs = z.object({
179
+ components: z.array(ComponentHandle),
180
+ })
181
+ export type PluginDesignLightsResetArgs = z.infer<typeof PluginDesignLightsResetArgs>
182
+
183
+ /**
184
+ * Options for {@linkcode PluginDesignLightsApi.list}.
185
+ *
186
+ * | Property | Type | Description |
187
+ * |---|---|---|
188
+ * | `includeDisabled` | `boolean` | Keep lights whose `enabled` is `false` (default `true`). `false` drops them, and components left with none. |
189
+ */
190
+ export const PluginDesignLightsListOptions = z.object({
191
+ includeDisabled: z.boolean().optional(),
192
+ })
193
+ export type PluginDesignLightsListOptions = z.infer<typeof PluginDesignLightsListOptions>
194
+
195
+ /** One entry of {@linkcode PluginDesignLightsApi.list}: a component and its lights. */
196
+ export const PluginComponentLights = z.object({
197
+ component: ComponentHandle,
198
+ lights: z.array(PluginFixtureLight),
199
+ })
200
+ export type PluginComponentLights = z.infer<typeof PluginComponentLights>
201
+
202
+ /**
203
+ * The kind of light fitting a component is recognised as, which gives it default lights while it
204
+ * has no stored list (see {@linkcode PluginDesignLightsApi.effective}).
205
+ */
206
+ export const PluginLightFitting = z.enum([
207
+ "floor-lamp",
208
+ "table-lamp",
209
+ "pendant",
210
+ "pendant-cluster",
211
+ "downlight",
212
+ "linear-batten",
213
+ "wall-sconce",
214
+ "luminaire",
215
+ ])
216
+ export type PluginLightFitting = z.infer<typeof PluginLightFitting>
217
+
218
+ /**
219
+ * What a component lights the model with ({@linkcode PluginDesignLightsApi.effective}).
220
+ *
221
+ * | Property | Type | Description |
222
+ * |---|---|---|
223
+ * | `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 |
224
+ * | `fitting` | {@linkcode PluginLightFitting} `\| null` | The fitting it is recognised as, or `null` |
225
+ * | `lights` | {@linkcode PluginFixtureLight}`[]` | The lights it lights with |
226
+ */
227
+ export const PluginEffectiveLights = z.object({
228
+ source: z.enum(["stored", "default", "none"]),
229
+ fitting: PluginLightFitting.nullable(),
230
+ lights: z.array(PluginFixtureLight),
231
+ })
232
+ export type PluginEffectiveLights = z.infer<typeof PluginEffectiveLights>
233
+
234
+ /**
235
+ * `snaptrude.design.lights` — physical point, spot and cylindrical-side tube sources.
236
+ * New fixtures should be schema 1.3 families with fixture.emitters, not glow-only meshes.
237
+ * Generated source geometry and output are one recipe: set/reset reject recipe-owned lights
238
+ * with PRECONDITION_FAILED. Edit family parameters instead. setEnabled stores a keyed override
239
+ * surviving flex/save/reload; removed recipe keys lose the override, and undo restores it.
240
+ *
241
+ * A light belongs to a **furniture item or a parametric family container** and is
242
+ * stored with it: it is saved, reloaded, copied, pasted and restored by undo with the
243
+ * component, and follows its transform (offsets scale with the component, a spot's
244
+ * direction follows the full rotation/mirroring). Build a light fitting as a family
245
+ * (or place a furniture item), then attach its lights to the returned
246
+ * {@linkcode ComponentHandle}. Other kinds (walls, masses, spaces) are rejected with
247
+ * `PRECONDITION_FAILED`.
248
+ *
249
+ * Light fittings (lamps, pendants, downlights, battens, sconces) light by **default** while
250
+ * nothing is stored on them; {@linkcode PluginDesignLightsApi.effective} reads those defaults.
251
+ *
252
+ * Lists are **replace-all**: {@linkcode PluginDesignLightsApi.set} sends the whole list.
253
+ * `get` and `list` return exactly what was stored (no defaults are filled in). Each mutation is one
254
+ * undo step; writing the value already stored is a no-op. A component holds at most 64
255
+ * lights (more is `RESOURCE_QUOTA_EXCEEDED`, not `VALIDATION`); how many the renderer draws in one frame is a separate budget and never
256
+ * rejects a write.
257
+ *
258
+ * Errors: bad light data → `VALIDATION` (`details` lists the issues); unknown/stale
259
+ * handle → `HANDLE_INVALID`; unsupported component kind, locked component or missing
260
+ * geometry → `PRECONDITION_FAILED`; more than 64 lights → `RESOURCE_QUOTA_EXCEEDED`.
261
+ */
262
+ export abstract class PluginDesignLightsApi {
263
+ constructor() {}
264
+
265
+ /**
266
+ * Read the lights stored on a component, exactly as written (`[]` when it has none).
267
+ *
268
+ * @param component The furniture item or family container
269
+ * @returns The component's {@linkcode PluginFixtureLight}`[]`
270
+ *
271
+ * @examplePrompt What lights does this lamp have?
272
+ * @examplePrompt Show me the light settings on the pendant I just built
273
+ * @examplePrompt Is there a light attached to this fixture?
274
+ * @examplePrompt Read the lighting of the selected furniture
275
+ *
276
+ * # Example
277
+ * ```ts
278
+ * const lights = await snaptrude.design.lights.get(lamp)
279
+ * console.log(lights.map((l) => l.key))
280
+ * ```
281
+ */
282
+ public abstract get(component: ComponentHandle): PluginApiReturn<PluginFixtureLight[]>
283
+
284
+ /**
285
+ * Read what a component lights the model with: its stored lights when it has a stored list
286
+ * (an empty one included), else the default lights of the light fitting it is (a floor lamp,
287
+ * a pendant, a downlight...), else none. Defaults are derived, never stored. Read-only.
288
+ *
289
+ * @param component The furniture item or family container
290
+ * @returns {@linkcode PluginEffectiveLights}
291
+ *
292
+ * @examplePrompt Does this lamp light the room?
293
+ * @examplePrompt What light does the pendant give off by default?
294
+ * @examplePrompt Which lights in this room come from the fittings' defaults?
295
+ * @examplePrompt Show the effective lighting of the selected fixture
296
+ *
297
+ * # Example
298
+ * ```ts
299
+ * const { source, fitting, lights } = await snaptrude.design.lights.effective(lamp)
300
+ * console.log(source, fitting, lights.length)
301
+ * ```
302
+ */
303
+ public abstract effective(component: ComponentHandle): PluginApiReturn<PluginEffectiveLights>
304
+
305
+ /**
306
+ * List every component that has lights, with its lights. Disabled lights are included
307
+ * unless `includeDisabled` is `false`.
308
+ *
309
+ * @param options Optional {@linkcode PluginDesignLightsListOptions}
310
+ * @returns {@linkcode PluginComponentLights}`[]`
311
+ *
312
+ * @examplePrompt Which fixtures in the model have lights?
313
+ * @examplePrompt List all the lamps that are switched on
314
+ * @examplePrompt How many lights are in this project?
315
+ * @examplePrompt Show every light fixture and its settings
316
+ *
317
+ * # Example
318
+ * ```ts
319
+ * const lit = await snaptrude.design.lights.list({ includeDisabled: false })
320
+ * console.log(lit.length, "components are lighting the model")
321
+ * ```
322
+ */
323
+ public abstract list(
324
+ options?: PluginDesignLightsListOptions
325
+ ): PluginApiReturn<PluginComponentLights[]>
326
+
327
+ /**
328
+ * Replace a component's lights with `lights` (replace-all; `[]` removes them all).
329
+ * Recipe-owned fixture sources reject this operation; edit the family parameters instead.
330
+ * One undo step. Writing the list already stored does nothing. The whole list is
331
+ * validated first; on any problem nothing changes.
332
+ *
333
+ * @param component The furniture item or family container to light
334
+ * @param lights The complete new list, at most 64, unique keys
335
+ * @returns The affected component
336
+ *
337
+ * @examplePrompt Add a warm 1600 lumen bulb to the pendant lamp
338
+ * @examplePrompt Put a 38 degree downlight spot in this ceiling fixture
339
+ * @examplePrompt Make this lamp glow at 3000K
340
+ * @examplePrompt Give the table lamp a shadow-casting point light
341
+ *
342
+ * # Example
343
+ * ```ts
344
+ * await snaptrude.design.lights.set(pendant, [
345
+ * {
346
+ * key: "bulb",
347
+ * kind: "point",
348
+ * offsetMeters: [0, -0.3, 0],
349
+ * intensity: { luminousFluxLm: 1600 },
350
+ * colorTemperatureK: 2700,
351
+ * },
352
+ * ])
353
+ * ```
354
+ */
355
+ public abstract set(
356
+ component: ComponentHandle,
357
+ lights: PluginFixtureLight[]
358
+ ): PluginApiReturn<PluginDesignChangeResult>
359
+
360
+ /**
361
+ * Switch one light on or off without resending its description. One undo step; a
362
+ * no-op when it already has that state.
363
+ *
364
+ * @param component The component that owns the light
365
+ * @param key The light's `key`
366
+ * @param enabled `true` = on, `false` = off
367
+ * @returns The affected component
368
+ *
369
+ * @examplePrompt Turn off the bulb in this lamp
370
+ * @examplePrompt Switch the downlight back on
371
+ * @examplePrompt Dim the room by turning off the pendant light
372
+ * @examplePrompt Toggle the lamp
373
+ *
374
+ * # Example
375
+ * ```ts
376
+ * await snaptrude.design.lights.setEnabled(pendant, "bulb", false)
377
+ * ```
378
+ */
379
+ public abstract setEnabled(
380
+ component: ComponentHandle,
381
+ key: string,
382
+ enabled: boolean
383
+ ): PluginApiReturn<PluginDesignChangeResult>
384
+
385
+ /**
386
+ * Remove all lights from the given components. Every component is checked first and
387
+ * recipe-owned fixture sources reject the entire batch before any component changes.
388
+ * nothing changes if any is invalid; components without lights are skipped. One undo
389
+ * step for the whole call.
390
+ *
391
+ * @param components The components to clear
392
+ * @returns The components that were affected
393
+ *
394
+ * @examplePrompt Remove the lights from this fixture
395
+ * @examplePrompt Clear all the lamps' lighting
396
+ * @examplePrompt Take the light off the selected pendants
397
+ * @examplePrompt Reset the lights on these components
398
+ *
399
+ * # Example
400
+ * ```ts
401
+ * const lit = await snaptrude.design.lights.list()
402
+ * await snaptrude.design.lights.reset(lit.map((e) => e.component))
403
+ * ```
404
+ */
405
+ public abstract reset(components: ComponentHandle[]): PluginApiReturn<PluginDesignChangeResult>
406
+ }
@@ -9,12 +9,6 @@ import { ComponentHandle } from "../../handles"
9
9
  */
10
10
  export const PluginDesignChangeResult = z.object({
11
11
  affected: z.array(ComponentHandle),
12
- /** Derived BIM (walls/floors/slabs) the parametric engine removed with its host. Delete only. */
13
- cascaded: z.array(ComponentHandle).optional(),
14
- /** Handles that no longer resolved when the call ran and were skipped. Delete only. */
15
- missing: z.array(ComponentHandle).optional(),
16
- /** Handles the engine accepted but left standing; delete them again or report them. Delete only. */
17
- rejected: z.array(ComponentHandle).optional(),
18
12
  })
19
13
  export type PluginDesignChangeResult = z.infer<typeof PluginDesignChangeResult>
20
14