@snaptrude/plugin-core 0.9.16 → 0.9.18-networks-20261016.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 (215) hide show
  1. package/AGENTS.md +231 -231
  2. package/CHANGELOG.md +408 -402
  3. package/CLAUDE.md +11 -11
  4. package/dist/api/analysis/daylight.d.ts +5 -5
  5. package/dist/api/analysis/solar.d.ts +2 -2
  6. package/dist/api/core/camera/index.d.ts +29 -0
  7. package/dist/api/core/camera/index.d.ts.map +1 -1
  8. package/dist/api/core/geom/create/index.d.ts +7 -1
  9. package/dist/api/core/geom/create/index.d.ts.map +1 -1
  10. package/dist/api/core/geom/update/contour.d.ts +8 -2
  11. package/dist/api/core/geom/update/contour.d.ts.map +1 -1
  12. package/dist/api/core/zoom/index.d.ts +13 -0
  13. package/dist/api/core/zoom/index.d.ts.map +1 -1
  14. package/dist/api/design/bim.d.ts +209 -0
  15. package/dist/api/design/bim.d.ts.map +1 -0
  16. package/dist/api/design/boolean/index.d.ts +2 -0
  17. package/dist/api/design/boolean/index.d.ts.map +1 -1
  18. package/dist/api/design/catalog.d.ts +320 -0
  19. package/dist/api/design/catalog.d.ts.map +1 -0
  20. package/dist/api/design/create/bulk-items.d.ts +65 -25
  21. package/dist/api/design/create/bulk-items.d.ts.map +1 -1
  22. package/dist/api/design/create/index.d.ts +272 -99
  23. package/dist/api/design/create/index.d.ts.map +1 -1
  24. package/dist/api/design/create/opening-fields.d.ts +13 -12
  25. package/dist/api/design/create/opening-fields.d.ts.map +1 -1
  26. package/dist/api/design/delete/index.d.ts +1 -0
  27. package/dist/api/design/delete/index.d.ts.map +1 -1
  28. package/dist/api/design/doors/index.d.ts +18 -24
  29. package/dist/api/design/doors/index.d.ts.map +1 -1
  30. package/dist/api/design/family.d.ts +797 -27
  31. package/dist/api/design/family.d.ts.map +1 -1
  32. package/dist/api/design/index.d.ts +16 -0
  33. package/dist/api/design/index.d.ts.map +1 -1
  34. package/dist/api/design/networks.d.ts +1763 -0
  35. package/dist/api/design/networks.d.ts.map +1 -0
  36. package/dist/api/design/query/index.d.ts +42 -32
  37. package/dist/api/design/query/index.d.ts.map +1 -1
  38. package/dist/api/design/selection/index.d.ts +10 -10
  39. package/dist/api/design/types/index.d.ts +40 -24
  40. package/dist/api/design/types/index.d.ts.map +1 -1
  41. package/dist/api/design/update/index.d.ts +43 -3
  42. package/dist/api/design/update/index.d.ts.map +1 -1
  43. package/dist/api/design/windows/index.d.ts +8 -8
  44. package/dist/api/design/windows/index.d.ts.map +1 -1
  45. package/dist/api/presentation/aiInspiration.d.ts +10 -10
  46. package/dist/api/presentation/annotate.d.ts +38 -22
  47. package/dist/api/presentation/annotate.d.ts.map +1 -1
  48. package/dist/api/presentation/drawingContract.d.ts +32 -0
  49. package/dist/api/presentation/drawingContract.d.ts.map +1 -0
  50. package/dist/api/presentation/drawings.d.ts +3523 -0
  51. package/dist/api/presentation/drawings.d.ts.map +1 -0
  52. package/dist/api/presentation/export.d.ts +23 -5
  53. package/dist/api/presentation/export.d.ts.map +1 -1
  54. package/dist/api/presentation/index.d.ts +41 -12
  55. package/dist/api/presentation/index.d.ts.map +1 -1
  56. package/dist/api/presentation/placedViews.d.ts +106 -6
  57. package/dist/api/presentation/placedViews.d.ts.map +1 -1
  58. package/dist/api/presentation/sections.d.ts +461 -0
  59. package/dist/api/presentation/sections.d.ts.map +1 -0
  60. package/dist/api/presentation/shapes.d.ts +2 -2
  61. package/dist/api/presentation/sheets.d.ts +175 -19
  62. package/dist/api/presentation/sheets.d.ts.map +1 -1
  63. package/dist/api/presentation/viewPresets.d.ts +222 -0
  64. package/dist/api/presentation/viewPresets.d.ts.map +1 -0
  65. package/dist/api/presentation/views.d.ts +103 -5
  66. package/dist/api/presentation/views.d.ts.map +1 -1
  67. package/dist/api/presentation/walkthroughs.d.ts +6 -6
  68. package/dist/errors/codes.d.ts +3 -1
  69. package/dist/errors/codes.d.ts.map +1 -1
  70. package/dist/index.cjs +3788 -2328
  71. package/dist/index.cjs.map +1 -1
  72. package/dist/index.js +3650 -2328
  73. package/dist/index.js.map +1 -1
  74. package/package.json +42 -42
  75. package/scripts/check-dist-fresh.mjs +22 -22
  76. package/scripts/generate-manifest.mjs +243 -238
  77. package/scripts/generate-manifest.test.mjs +303 -303
  78. package/src/api/analysis/daylight.ts +470 -470
  79. package/src/api/analysis/heatmaps.ts +683 -683
  80. package/src/api/analysis/illuminance.ts +155 -155
  81. package/src/api/analysis/index.ts +61 -61
  82. package/src/api/analysis/shadows.ts +183 -183
  83. package/src/api/analysis/solar.ts +237 -237
  84. package/src/api/analysis/sunlightHours.ts +211 -211
  85. package/src/api/analysis/sunpath.ts +83 -83
  86. package/src/api/analysis/weather.ts +179 -179
  87. package/src/api/core/buildings.ts +485 -485
  88. package/src/api/core/camera/index.ts +696 -667
  89. package/src/api/core/comment/index.ts +376 -376
  90. package/src/api/core/geom/create/index.ts +2139 -2133
  91. package/src/api/core/geom/delete/index.ts +84 -84
  92. package/src/api/core/geom/index.ts +35 -35
  93. package/src/api/core/geom/query/arc.ts +169 -169
  94. package/src/api/core/geom/query/brep.ts +621 -621
  95. package/src/api/core/geom/query/circle.ts +404 -404
  96. package/src/api/core/geom/query/contour.ts +540 -540
  97. package/src/api/core/geom/query/curve.ts +1102 -1102
  98. package/src/api/core/geom/query/edge.ts +130 -130
  99. package/src/api/core/geom/query/face.ts +508 -508
  100. package/src/api/core/geom/query/halfedge.ts +210 -210
  101. package/src/api/core/geom/query/index.ts +63 -63
  102. package/src/api/core/geom/query/profile.ts +473 -473
  103. package/src/api/core/geom/query/vertex.ts +205 -205
  104. package/src/api/core/geom/update/contour.ts +323 -317
  105. package/src/api/core/geom/update/curve.ts +209 -209
  106. package/src/api/core/geom/update/index.ts +29 -29
  107. package/src/api/core/geom/update/profile.ts +379 -379
  108. package/src/api/core/groups.ts +521 -521
  109. package/src/api/core/handles/index.ts +234 -234
  110. package/src/api/core/history/index.ts +84 -84
  111. package/src/api/core/index.ts +99 -99
  112. package/src/api/core/io/export/index.ts +126 -126
  113. package/src/api/core/io/import/index.ts +504 -504
  114. package/src/api/core/io/index.ts +42 -42
  115. package/src/api/core/io/job/index.ts +140 -140
  116. package/src/api/core/io/query/index.ts +71 -71
  117. package/src/api/core/io/terrain/index.ts +360 -360
  118. package/src/api/core/io/underlay/index.ts +705 -705
  119. package/src/api/core/layers.ts +540 -540
  120. package/src/api/core/math/index.ts +20 -20
  121. package/src/api/core/math/quat.ts +172 -172
  122. package/src/api/core/math/vec3.ts +179 -179
  123. package/src/api/core/mode/index.ts +108 -108
  124. package/src/api/core/project/index.ts +479 -479
  125. package/src/api/core/proposals/index.ts +570 -570
  126. package/src/api/core/storeys/index.ts +308 -308
  127. package/src/api/core/storeys/layers.ts +339 -339
  128. package/src/api/core/tags.ts +911 -911
  129. package/src/api/core/units/index.ts +164 -164
  130. package/src/api/core/user.ts +46 -46
  131. package/src/api/core/zoom/index.ts +64 -51
  132. package/src/api/design/bim.ts +121 -0
  133. package/src/api/design/boolean/index.ts +181 -179
  134. package/src/api/design/catalog.ts +203 -0
  135. package/src/api/design/create/bulk-items.ts +294 -254
  136. package/src/api/design/create/grids.ts +137 -137
  137. package/src/api/design/create/index.ts +2148 -1980
  138. package/src/api/design/create/opening-fields.ts +40 -37
  139. package/src/api/design/delete/index.ts +75 -74
  140. package/src/api/design/dimensions.ts +453 -453
  141. package/src/api/design/doors/index.ts +516 -500
  142. package/src/api/design/edit/index.ts +54 -54
  143. package/src/api/design/erase/index.ts +151 -151
  144. package/src/api/design/family.ts +1334 -704
  145. package/src/api/design/furniture/index.ts +319 -319
  146. package/src/api/design/grids.ts +237 -237
  147. package/src/api/design/index.ts +304 -274
  148. package/src/api/design/lock.ts +69 -69
  149. package/src/api/design/materials/index.ts +608 -608
  150. package/src/api/design/networks.ts +667 -0
  151. package/src/api/design/query/geometry/index.ts +319 -319
  152. package/src/api/design/query/grids.ts +197 -197
  153. package/src/api/design/query/index.ts +1236 -1226
  154. package/src/api/design/query/referenceLines.ts +52 -52
  155. package/src/api/design/query/spaces.ts +275 -275
  156. package/src/api/design/selection/index.ts +273 -273
  157. package/src/api/design/shared.ts +40 -40
  158. package/src/api/design/transform/index.ts +254 -254
  159. package/src/api/design/types/index.ts +163 -156
  160. package/src/api/design/update/index.ts +1024 -983
  161. package/src/api/design/visibility.ts +143 -143
  162. package/src/api/design/windows/index.ts +351 -333
  163. package/src/api/entity/buildableEnvelope.ts +322 -322
  164. package/src/api/entity/index.ts +30 -30
  165. package/src/api/entity/referenceLine.ts +235 -235
  166. package/src/api/entity/space.ts +612 -612
  167. package/src/api/entity/story.ts +517 -517
  168. package/src/api/index.ts +47 -47
  169. package/src/api/presentation/aiInspiration.ts +1116 -1116
  170. package/src/api/presentation/annotate.ts +417 -385
  171. package/src/api/presentation/camera.ts +289 -289
  172. package/src/api/presentation/diagrams.ts +194 -194
  173. package/src/api/presentation/drawingContract.ts +70 -0
  174. package/src/api/presentation/drawings.ts +1179 -0
  175. package/src/api/presentation/export.ts +134 -108
  176. package/src/api/presentation/import.ts +159 -159
  177. package/src/api/presentation/index.ts +160 -126
  178. package/src/api/presentation/placedViews.ts +1211 -1120
  179. package/src/api/presentation/sections.ts +420 -0
  180. package/src/api/presentation/shapes.ts +274 -274
  181. package/src/api/presentation/sheets.ts +746 -585
  182. package/src/api/presentation/slideshow.ts +134 -134
  183. package/src/api/presentation/tables.ts +84 -84
  184. package/src/api/presentation/viewPresets.ts +241 -0
  185. package/src/api/presentation/views.ts +713 -673
  186. package/src/api/presentation/walkthroughs.ts +1201 -1201
  187. package/src/api/program/adjacency.ts +164 -164
  188. package/src/api/program/areas.ts +408 -408
  189. package/src/api/program/classification.ts +138 -138
  190. package/src/api/program/cores.ts +83 -83
  191. package/src/api/program/departments.ts +517 -517
  192. package/src/api/program/index.ts +73 -73
  193. package/src/api/program/labels.ts +332 -332
  194. package/src/api/program/layout.ts +422 -422
  195. package/src/api/program/metadata.ts +364 -364
  196. package/src/api/program/metrics.ts +120 -120
  197. package/src/api/program/site.ts +748 -748
  198. package/src/api/program/spreadsheet.ts +2698 -2698
  199. package/src/api/workspace/index.ts +612 -612
  200. package/src/errors/codes.ts +143 -136
  201. package/src/errors/envelope.ts +75 -75
  202. package/src/errors/index.ts +21 -21
  203. package/src/errors/plugin-error.ts +134 -134
  204. package/src/handles.ts +297 -297
  205. package/src/host-utils.ts +67 -67
  206. package/src/index.ts +7 -7
  207. package/src/massParameters.ops.ts +246 -246
  208. package/src/massParameters.ts +427 -427
  209. package/src/types.ts +16 -16
  210. package/test/drawingContract.test.mjs +288 -0
  211. package/test/errors.test.mjs +185 -184
  212. package/test/massParameters.test.mjs +952 -952
  213. package/tsconfig.json +22 -22
  214. package/tsup.config.ts +12 -12
  215. package/api-manifest.json +0 -9618
@@ -1,333 +1,351 @@
1
- import * as z from "zod"
2
- import { PluginApiReturn } from "../../../types"
3
- import { ComponentHandle } from "../../../handles"
4
- import { PluginDesignChangeResult } from "../lock"
5
- import { PluginObjectCatalogGroup, PluginObjectCatalogItem } from "../doors"
6
-
7
- /**
8
- * `snaptrude.design.windows` — window-specific reads. Creation lives at
9
- * `design.create.window`; generic reads (`listWindows`/`getHost`/`getProperties`) live
10
- * at `design.query.*`. Window targets are {@linkcode ComponentHandle}s.
11
- *
12
- * The **catalog** reads (`listCatalogGroups`/`listCatalog`/`getCatalogItem`/`exists`)
13
- * browse the placeable window library — plain value records keyed by a library id
14
- * (team `_id` or general `fullName`), NOT handles — and feed `design.create.window`.
15
- * They are network-backed but carry no `Async` suffix (§6.6) and never throw
16
- * (`[]`/`null`). The {@linkcode PluginObjectCatalogGroup} / {@linkcode PluginObjectCatalogItem}
17
- * DTOs are shared with `design.doors` (defined there, re-exported here).
18
- *
19
- * `getSillHeight` (bounds-derived) and the command-wired `mirror` land in a later pass.
20
- */
21
- export abstract class PluginDesignWindowsApi {
22
- constructor() {}
23
-
24
- /**
25
- * Get the type name of a window — the label that identifies which kind of
26
- * window the instance is, as shown in its properties.
27
- *
28
- * @param window The window to query
29
- * @returns The type as a `string`, or `null`
30
- *
31
- * @examplePrompt What type of window is this?
32
- * @examplePrompt Is the selected window a casement or a slider?
33
- * @examplePrompt Tell me the window type used on this wall
34
- * @examplePrompt Check what kind of window the living room has
35
- *
36
- * # Example
37
- * ```ts
38
- * const [win] = await snaptrude.design.query.listWindows({ isSelected: true })
39
- * const type = await snaptrude.design.windows.getType(win)
40
- * if (type) console.log("window type:", type)
41
- * ```
42
- */
43
- public abstract getType(window: ComponentHandle): PluginApiReturn<string | null>
44
-
45
- /**
46
- * Get the width of a window — how wide its opening is along the host wall.
47
- *
48
- * @param window The window to query
49
- * @returns The width as a `number`, or `null`
50
- *
51
- * @examplePrompt How wide is this window?
52
- * @examplePrompt What's the width of the selected window?
53
- * @examplePrompt Measure the width of the kitchen window
54
- * @examplePrompt Check whether this window is 1200mm wide
55
- *
56
- * # Example
57
- * ```ts
58
- * const [win] = await snaptrude.design.query.listWindows()
59
- * const width = await snaptrude.design.windows.getWidth(win)
60
- * if (width !== null) console.log("window width:", width)
61
- * ```
62
- */
63
- public abstract getWidth(window: ComponentHandle): PluginApiReturn<number | null>
64
-
65
- /**
66
- * Get the height of a window — how tall its opening is on the host wall.
67
- *
68
- * @param window The window to query
69
- * @returns The height as a `number`, or `null`
70
- *
71
- * @examplePrompt How tall is this window?
72
- * @examplePrompt What's the height of the selected window?
73
- * @examplePrompt Check the window height on this wall
74
- * @examplePrompt Is the bedroom window 1.5m high?
75
- *
76
- * # Example
77
- * ```ts
78
- * const [win] = await snaptrude.design.query.listWindows()
79
- * const height = await snaptrude.design.windows.getHeight(win)
80
- * if (height !== null) console.log("window height:", height)
81
- * ```
82
- */
83
- public abstract getHeight(window: ComponentHandle): PluginApiReturn<number | null>
84
-
85
- /**
86
- * Get a window's full dimensions in one call — width along the wall, vertical
87
- * height, and thickness through the wall — measured in the window's local
88
- * oriented space.
89
- *
90
- * @param window The window to query
91
- * @returns The dimensions, or `null`
92
- *
93
- * @examplePrompt What are the dimensions of this window?
94
- * @examplePrompt How big is the selected window?
95
- * @examplePrompt Give me the width, height and depth of this window
96
- * @examplePrompt Measure the living room window
97
- * @examplePrompt Get the window size including its thickness through the wall
98
- *
99
- * # Example
100
- * ```ts
101
- * const [win] = await snaptrude.design.query.listWindows({ isSelected: true })
102
- * const dims = await snaptrude.design.windows.getDimensions(win)
103
- * if (dims) console.log(dims.width, dims.height, dims.thickness)
104
- * ```
105
- */
106
- public abstract getDimensions(
107
- window: ComponentHandle
108
- ): PluginApiReturn<PluginWindowDimensions | null>
109
-
110
- /**
111
- * Set the width of a window, resizing its opening and re-cutting the host
112
- * wall. Width is in engine units; the change is undoable.
113
- *
114
- * @param window The window to resize
115
- * @param width New width (engine units)
116
- * @returns The affected window
117
- *
118
- * @examplePrompt Make this window 1200mm wide
119
- * @examplePrompt Widen the selected window to 4 feet
120
- * @examplePrompt Change the window width to 1.5m
121
- * @examplePrompt Resize the kitchen window to 900 wide
122
- *
123
- * # Example
124
- * ```ts
125
- * // Takes a single window (unlike design.doors.setWidth, which takes an array)
126
- * const [win] = await snaptrude.design.query.listWindows({ isSelected: true })
127
- * const { affected } = await snaptrude.design.windows.setWidth(win, 1200)
128
- * ```
129
- */
130
- public abstract setWidth(
131
- window: ComponentHandle,
132
- width: number
133
- ): PluginApiReturn<PluginDesignChangeResult>
134
-
135
- /**
136
- * Set the height of a window, resizing its opening and re-cutting the host
137
- * wall. Height is in engine units; the change is undoable.
138
- *
139
- * @param window The window to resize
140
- * @param height New height (engine units)
141
- * @returns The affected window
142
- *
143
- * @examplePrompt Make this window 1.5m tall
144
- * @examplePrompt Change the window height to 4 feet
145
- * @examplePrompt Shorten the selected window to 900mm high
146
- * @examplePrompt Set the bedroom window height to 1200
147
- *
148
- * # Example
149
- * ```ts
150
- * const [win] = await snaptrude.design.query.listWindows({ isSelected: true })
151
- * await snaptrude.design.windows.setHeight(win, 1500)
152
- * ```
153
- */
154
- public abstract setHeight(
155
- window: ComponentHandle,
156
- height: number
157
- ): PluginApiReturn<PluginDesignChangeResult>
158
-
159
- /**
160
- * List the window catalog **groups** — the placement families (Fixed,
161
- * Casement, Sliding, Folding, …), built-in groups merged with any
162
- * team-custom types.
163
- *
164
- * @returns The groups as {@linkcode PluginObjectCatalogGroup}`[]` (`[]` when empty)
165
- *
166
- * @examplePrompt What kinds of windows can I place?
167
- * @examplePrompt List the window groups in the catalog
168
- * @examplePrompt Show me the window families available in this project
169
- * @examplePrompt Which window types does this project support?
170
- *
171
- * # Example
172
- * ```ts
173
- * const groups = await snaptrude.design.windows.listCatalogGroups()
174
- * for (const g of groups) console.log(g.dbType, g.label, g.source)
175
- * ```
176
- */
177
- public abstract listCatalogGroups(): PluginApiReturn<PluginObjectCatalogGroup[]>
178
-
179
- /**
180
- * List the placeable window catalog (team + general libraries), optionally
181
- * restricted to one group by its `dbType` token.
182
- *
183
- * @param group Restrict to one group's `dbType` (optional; e.g. `"casementDouble"`)
184
- * @returns The catalog as {@linkcode PluginObjectCatalogItem}`[]` (`[]` when empty)
185
- *
186
- * @examplePrompt What windows can I place in this project?
187
- * @examplePrompt List every window in the library
188
- * @examplePrompt Show me the casement windows I can add
189
- * @examplePrompt Browse the window catalog
190
- *
191
- * # Example
192
- * ```ts
193
- * const [group] = await snaptrude.design.windows.listCatalogGroups()
194
- * const items = await snaptrude.design.windows.listCatalog(group?.dbType)
195
- * for (const item of items) console.log(item.id, item.name, item.thumbnailUrl)
196
- * ```
197
- */
198
- public abstract listCatalog(
199
- group?: string
200
- ): PluginApiReturn<PluginObjectCatalogItem[]>
201
-
202
- /**
203
- * Get a single window catalog item by its library id.
204
- *
205
- * @param id The catalog library id
206
- * @returns The item, or `null` if no catalog item matches
207
- *
208
- * @examplePrompt Get the details of this window from the library
209
- * @examplePrompt Look up the catalog entry for this window id
210
- * @examplePrompt What is the cost of this window item?
211
- * @examplePrompt Show me the family name of this window in the catalog
212
- *
213
- * # Example
214
- * ```ts
215
- * const [entry] = await snaptrude.design.windows.listCatalog()
216
- * const item = await snaptrude.design.windows.getCatalogItem(entry.id)
217
- * if (item) console.log(item.name, item.source, item.dbType)
218
- * ```
219
- */
220
- public abstract getCatalogItem(
221
- id: string
222
- ): PluginApiReturn<PluginObjectCatalogItem | null>
223
-
224
- /**
225
- * Test whether a window catalog item exists for the given library id.
226
- *
227
- * @param id The catalog library id
228
- * @returns `true` if it exists, otherwise `false`
229
- *
230
- * @examplePrompt Is this window still in the library?
231
- * @examplePrompt Check whether a window catalog item with this id exists
232
- * @examplePrompt Does my team library have this window?
233
- * @examplePrompt Verify the window is available before placing it
234
- *
235
- * # Example
236
- * ```ts
237
- * const [entry] = await snaptrude.design.windows.listCatalog()
238
- * const stillAvailable = await snaptrude.design.windows.exists(entry.id)
239
- * console.log(stillAvailable ? "safe to place" : "removed from library")
240
- * ```
241
- */
242
- public abstract exists(id: string): PluginApiReturn<boolean>
243
- }
244
-
245
- /**
246
- * Arguments for the single-window read methods.
247
- *
248
- * | Property | Type | Description |
249
- * |---|---|---|
250
- * | `window` | {@linkcode ComponentHandle} | The window to query |
251
- */
252
- export const PluginDesignWindowArgs = z.object({
253
- window: ComponentHandle,
254
- })
255
- export type PluginDesignWindowArgs = z.infer<typeof PluginDesignWindowArgs>
256
-
257
- /**
258
- * A window's dimensions.
259
- *
260
- * | Property | Type | Description |
261
- * |---|---|---|
262
- * | `width` | `number` | Along the wall |
263
- * | `height` | `number` | Vertical |
264
- * | `thickness` | `number` | Through the wall (engine `length` axis) |
265
- */
266
- export const PluginWindowDimensions = z.object({
267
- width: z.number(),
268
- height: z.number(),
269
- thickness: z.number(),
270
- })
271
- export type PluginWindowDimensions = z.infer<typeof PluginWindowDimensions>
272
-
273
- /**
274
- * Arguments for {@linkcode PluginDesignWindowsApi.setWidth}.
275
- *
276
- * | Property | Type | Description |
277
- * |---|---|---|
278
- * | `window` | {@linkcode ComponentHandle} | The window to resize |
279
- * | `width` | `number` | New width (engine units) |
280
- */
281
- export const PluginDesignWindowSetWidthArgs = z.object({
282
- window: ComponentHandle,
283
- width: z.number(),
284
- })
285
- export type PluginDesignWindowSetWidthArgs = z.infer<typeof PluginDesignWindowSetWidthArgs>
286
-
287
- /**
288
- * Arguments for {@linkcode PluginDesignWindowsApi.setHeight}.
289
- *
290
- * | Property | Type | Description |
291
- * |---|---|---|
292
- * | `window` | {@linkcode ComponentHandle} | The window to resize |
293
- * | `height` | `number` | New height (engine units) |
294
- */
295
- export const PluginDesignWindowSetHeightArgs = z.object({
296
- window: ComponentHandle,
297
- height: z.number(),
298
- })
299
- export type PluginDesignWindowSetHeightArgs = z.infer<typeof PluginDesignWindowSetHeightArgs>
300
-
301
- // ---------------------------------------------------------------------------
302
- // catalog (shared DTOs defined in ../doors, re-exported here for symmetry)
303
- // ---------------------------------------------------------------------------
304
-
305
- // Re-export the shared catalog DTOs imported at the top of this file.
306
- export { PluginObjectCatalogGroup, PluginObjectCatalogItem }
307
-
308
- /**
309
- * Arguments for {@linkcode PluginDesignWindowsApi.listCatalog}.
310
- *
311
- * | Property | Type | Description |
312
- * |---|---|---|
313
- * | `group` | `string`? | Restrict to one group's `dbType` token (optional) |
314
- */
315
- export const PluginDesignWindowListCatalogArgs = z.object({
316
- group: z.string().optional(),
317
- })
318
- export type PluginDesignWindowListCatalogArgs = z.infer<typeof PluginDesignWindowListCatalogArgs>
319
-
320
- /**
321
- * Arguments for {@linkcode PluginDesignWindowsApi.getCatalogItem} / {@linkcode PluginDesignWindowsApi.exists}.
322
- *
323
- * | Property | Type | Description |
324
- * |---|---|---|
325
- * | `id` | `string` | The catalog library id |
326
- */
327
- export const PluginDesignWindowGetCatalogItemArgs = z.object({
328
- id: z.string(),
329
- })
330
- export type PluginDesignWindowGetCatalogItemArgs = z.infer<typeof PluginDesignWindowGetCatalogItemArgs>
331
-
332
- export const PluginDesignWindowExistsArgs = PluginDesignWindowGetCatalogItemArgs
333
- export type PluginDesignWindowExistsArgs = z.infer<typeof PluginDesignWindowExistsArgs>
1
+ import * as z from "zod"
2
+ import { PluginApiReturn } from "../../../types"
3
+ import { ComponentHandle } from "../../../handles"
4
+ import { PluginDesignChangeResult } from "../lock"
5
+ import { PluginObjectCatalogGroup, PluginObjectCatalogItem } from "../doors"
6
+
7
+ /**
8
+ * `snaptrude.design.windows` — window-specific reads. Creation lives at
9
+ * `design.create.window`; generic reads (`listWindows`/`getHost`/`getProperties`) live
10
+ * at `design.query.*`. Window targets are {@linkcode ComponentHandle}s.
11
+ *
12
+ * The **catalog** reads (`listCatalogGroups`/`listCatalog`/`getCatalogItem`/`exists`)
13
+ * browse saved hosted window families, keyed by definition ID, and feed design.create.window.
14
+ * They reject if saved definitions cannot be loaded completely. A missing item returns null.
15
+ * The {@linkcode PluginObjectCatalogGroup} / {@linkcode PluginObjectCatalogItem}
16
+ * DTOs are shared with `design.doors` (defined there, re-exported here).
17
+ *
18
+ * PC-only: dimensions read the evaluated opening and host thickness in SU. Setters
19
+ * write declared width/height parameters, never mesh scale. Missing or derived
20
+ * controls reject. Use design.family.setParameters for sill and other controls.
21
+ */
22
+ export abstract class PluginDesignWindowsApi {
23
+ constructor() {}
24
+
25
+ /**
26
+ * Get the type name of a window — the label that identifies which kind of
27
+ * window the instance is, as shown in its properties.
28
+ *
29
+ * @param window The window to query
30
+ * @returns The type as a `string`, or `null`
31
+ *
32
+ * @examplePrompt What type of window is this?
33
+ * @examplePrompt Is the selected window a casement or a slider?
34
+ * @examplePrompt Tell me the window type used on this wall
35
+ * @examplePrompt Check what kind of window the living room has
36
+ *
37
+ * # Example
38
+ * ```ts
39
+ * const [win] = await snaptrude.design.query.listWindows({ isSelected: true })
40
+ * const type = await snaptrude.design.windows.getType(win)
41
+ * if (type) console.log("window type:", type)
42
+ * ```
43
+ */
44
+ public abstract getType(
45
+ window: ComponentHandle,
46
+ ): PluginApiReturn<string | null>
47
+
48
+ /**
49
+ * Get the width of a window — how wide its opening is along the host wall.
50
+ *
51
+ * @param window The window to query
52
+ * @returns The width as a `number`, or `null`
53
+ *
54
+ * @examplePrompt How wide is this window?
55
+ * @examplePrompt What's the width of the selected window?
56
+ * @examplePrompt Measure the width of the kitchen window
57
+ * @examplePrompt Check whether this window is 1200mm wide
58
+ *
59
+ * # Example
60
+ * ```ts
61
+ * const [win] = await snaptrude.design.query.listWindows()
62
+ * const width = await snaptrude.design.windows.getWidth(win)
63
+ * if (width !== null) console.log("window width:", width)
64
+ * ```
65
+ */
66
+ public abstract getWidth(
67
+ window: ComponentHandle,
68
+ ): PluginApiReturn<number | null>
69
+
70
+ /**
71
+ * Get the height of a window — how tall its opening is on the host wall.
72
+ *
73
+ * @param window The window to query
74
+ * @returns The height as a `number`, or `null`
75
+ *
76
+ * @examplePrompt How tall is this window?
77
+ * @examplePrompt What's the height of the selected window?
78
+ * @examplePrompt Check the window height on this wall
79
+ * @examplePrompt Is the bedroom window 1.5m high?
80
+ *
81
+ * # Example
82
+ * ```ts
83
+ * const [win] = await snaptrude.design.query.listWindows()
84
+ * const height = await snaptrude.design.windows.getHeight(win)
85
+ * if (height !== null) console.log("window height:", height)
86
+ * ```
87
+ */
88
+ public abstract getHeight(
89
+ window: ComponentHandle,
90
+ ): PluginApiReturn<number | null>
91
+
92
+ /**
93
+ * Get evaluated opening width/height and host thickness in Snaptrude units.
94
+ * The opening can differ from the width/height input parameters.
95
+ *
96
+ * @param window The window to query
97
+ * @returns The dimensions, or `null`
98
+ *
99
+ * @examplePrompt What are the dimensions of this window?
100
+ * @examplePrompt How big is the selected window?
101
+ * @examplePrompt Give me the width, height and depth of this window
102
+ * @examplePrompt Measure the living room window
103
+ * @examplePrompt Get the window size including its thickness through the wall
104
+ *
105
+ * # Example
106
+ * ```ts
107
+ * const [win] = await snaptrude.design.query.listWindows({ isSelected: true })
108
+ * const dims = await snaptrude.design.windows.getDimensions(win)
109
+ * if (dims) console.log(dims.width, dims.height, dims.thickness)
110
+ * ```
111
+ */
112
+ public abstract getDimensions(
113
+ window: ComponentHandle,
114
+ ): PluginApiReturn<PluginWindowDimensions | null>
115
+
116
+ /**
117
+ * Set the width of a window, resizing its opening and re-cutting the host
118
+ * wall. Width is in engine units; the change is undoable.
119
+ *
120
+ * @param window The window to resize
121
+ * @param width New width (engine units)
122
+ * @returns The affected window
123
+ *
124
+ * @examplePrompt Make this window 1200mm wide
125
+ * @examplePrompt Widen the selected window to 4 feet
126
+ * @examplePrompt Change the window width to 1.5m
127
+ * @examplePrompt Resize the kitchen window to 900 wide
128
+ *
129
+ * # Example
130
+ * ```ts
131
+ * // Takes a single window (unlike design.doors.setWidth, which takes an array)
132
+ * const [win] = await snaptrude.design.query.listWindows({ isSelected: true })
133
+ * const { affected } = await snaptrude.design.windows.setWidth(win, 1200)
134
+ * ```
135
+ */
136
+ public abstract setWidth(
137
+ window: ComponentHandle,
138
+ width: number,
139
+ ): PluginApiReturn<PluginDesignChangeResult>
140
+
141
+ /**
142
+ * Set the height of a window, resizing its opening and re-cutting the host
143
+ * wall. Height is in engine units; the change is undoable.
144
+ *
145
+ * @param window The window to resize
146
+ * @param height New height (engine units)
147
+ * @returns The affected window
148
+ *
149
+ * @examplePrompt Make this window 1.5m tall
150
+ * @examplePrompt Change the window height to 4 feet
151
+ * @examplePrompt Shorten the selected window to 900mm high
152
+ * @examplePrompt Set the bedroom window height to 1200
153
+ *
154
+ * # Example
155
+ * ```ts
156
+ * const [win] = await snaptrude.design.query.listWindows({ isSelected: true })
157
+ * await snaptrude.design.windows.setHeight(win, 1500)
158
+ * ```
159
+ */
160
+ public abstract setHeight(
161
+ window: ComponentHandle,
162
+ height: number,
163
+ ): PluginApiReturn<PluginDesignChangeResult>
164
+
165
+ /**
166
+ * List the window catalog **groups** — the placement families (Fixed,
167
+ * Casement, Sliding, Folding, …), built-in groups merged with any
168
+ * team-custom types.
169
+ *
170
+ * @returns The groups as {@linkcode PluginObjectCatalogGroup}`[]` (`[]` when empty)
171
+ *
172
+ * @examplePrompt What kinds of windows can I place?
173
+ * @examplePrompt List the window groups in the catalog
174
+ * @examplePrompt Show me the window families available in this project
175
+ * @examplePrompt Which window types does this project support?
176
+ *
177
+ * # Example
178
+ * ```ts
179
+ * const groups = await snaptrude.design.windows.listCatalogGroups()
180
+ * for (const g of groups) console.log(g.dbType, g.label, g.source)
181
+ * ```
182
+ */
183
+ public abstract listCatalogGroups(): PluginApiReturn<
184
+ PluginObjectCatalogGroup[]
185
+ >
186
+
187
+ /**
188
+ * List the placeable window catalog (team + general libraries), optionally
189
+ * restricted to one group by its `dbType` token.
190
+ *
191
+ * @param group Restrict to one group's `dbType` (optional; e.g. `"casementDouble"`)
192
+ * @returns The catalog as {@linkcode PluginObjectCatalogItem}`[]` (`[]` when empty)
193
+ *
194
+ * @examplePrompt What windows can I place in this project?
195
+ * @examplePrompt List every window in the library
196
+ * @examplePrompt Show me the casement windows I can add
197
+ * @examplePrompt Browse the window catalog
198
+ *
199
+ * # Example
200
+ * ```ts
201
+ * const [group] = await snaptrude.design.windows.listCatalogGroups()
202
+ * const items = await snaptrude.design.windows.listCatalog(group?.dbType)
203
+ * for (const item of items) console.log(item.id, item.name, item.thumbnailUrl)
204
+ * ```
205
+ */
206
+ public abstract listCatalog(
207
+ group?: string,
208
+ ): PluginApiReturn<PluginObjectCatalogItem[]>
209
+
210
+ /**
211
+ * Get a single window catalog item by its library id.
212
+ *
213
+ * @param id The catalog library id
214
+ * @returns The item, or `null` if no catalog item matches
215
+ *
216
+ * @examplePrompt Get the details of this window from the library
217
+ * @examplePrompt Look up the catalog entry for this window id
218
+ * @examplePrompt What is the cost of this window item?
219
+ * @examplePrompt Show me the family name of this window in the catalog
220
+ *
221
+ * # Example
222
+ * ```ts
223
+ * const [entry] = await snaptrude.design.windows.listCatalog()
224
+ * const item = await snaptrude.design.windows.getCatalogItem(entry.id)
225
+ * if (item) console.log(item.name, item.source, item.dbType)
226
+ * ```
227
+ */
228
+ public abstract getCatalogItem(
229
+ id: string,
230
+ ): PluginApiReturn<PluginObjectCatalogItem | null>
231
+
232
+ /**
233
+ * Test whether a window catalog item exists for the given library id.
234
+ *
235
+ * @param id The catalog library id
236
+ * @returns `true` if it exists, otherwise `false`
237
+ *
238
+ * @examplePrompt Is this window still in the library?
239
+ * @examplePrompt Check whether a window catalog item with this id exists
240
+ * @examplePrompt Does my team library have this window?
241
+ * @examplePrompt Verify the window is available before placing it
242
+ *
243
+ * # Example
244
+ * ```ts
245
+ * const [entry] = await snaptrude.design.windows.listCatalog()
246
+ * const stillAvailable = await snaptrude.design.windows.exists(entry.id)
247
+ * console.log(stillAvailable ? "safe to place" : "removed from library")
248
+ * ```
249
+ */
250
+ public abstract exists(id: string): PluginApiReturn<boolean>
251
+ }
252
+
253
+ /**
254
+ * Arguments for the single-window read methods.
255
+ *
256
+ * | Property | Type | Description |
257
+ * |---|---|---|
258
+ * | `window` | {@linkcode ComponentHandle} | The window to query |
259
+ */
260
+ export const PluginDesignWindowArgs = z.object({
261
+ window: ComponentHandle,
262
+ })
263
+ export type PluginDesignWindowArgs = z.infer<typeof PluginDesignWindowArgs>
264
+
265
+ /**
266
+ * A window's dimensions.
267
+ *
268
+ * | Property | Type | Description |
269
+ * |---|---|---|
270
+ * | `width` | `number` | Along the wall |
271
+ * | `height` | `number` | Vertical |
272
+ * | `thickness` | `number` | Through the wall (engine `length` axis) |
273
+ */
274
+ export const PluginWindowDimensions = z.object({
275
+ width: z.number(),
276
+ height: z.number(),
277
+ thickness: z.number(),
278
+ })
279
+ export type PluginWindowDimensions = z.infer<typeof PluginWindowDimensions>
280
+
281
+ /**
282
+ * Arguments for {@linkcode PluginDesignWindowsApi.setWidth}.
283
+ *
284
+ * | Property | Type | Description |
285
+ * |---|---|---|
286
+ * | `window` | {@linkcode ComponentHandle} | The window to resize |
287
+ * | `width` | `number` | New width (engine units) |
288
+ */
289
+ export const PluginDesignWindowSetWidthArgs = z.object({
290
+ window: ComponentHandle,
291
+ width: z.number(),
292
+ })
293
+ export type PluginDesignWindowSetWidthArgs = z.infer<
294
+ typeof PluginDesignWindowSetWidthArgs
295
+ >
296
+
297
+ /**
298
+ * Arguments for {@linkcode PluginDesignWindowsApi.setHeight}.
299
+ *
300
+ * | Property | Type | Description |
301
+ * |---|---|---|
302
+ * | `window` | {@linkcode ComponentHandle} | The window to resize |
303
+ * | `height` | `number` | New height (engine units) |
304
+ */
305
+ export const PluginDesignWindowSetHeightArgs = z.object({
306
+ window: ComponentHandle,
307
+ height: z.number(),
308
+ })
309
+ export type PluginDesignWindowSetHeightArgs = z.infer<
310
+ typeof PluginDesignWindowSetHeightArgs
311
+ >
312
+
313
+ // ---------------------------------------------------------------------------
314
+ // catalog (shared DTOs defined in ../doors, re-exported here for symmetry)
315
+ // ---------------------------------------------------------------------------
316
+
317
+ // Re-export the shared catalog DTOs imported at the top of this file.
318
+ export { PluginObjectCatalogGroup, PluginObjectCatalogItem }
319
+
320
+ /**
321
+ * Arguments for {@linkcode PluginDesignWindowsApi.listCatalog}.
322
+ *
323
+ * | Property | Type | Description |
324
+ * |---|---|---|
325
+ * | `group` | `string`? | Restrict to one group's `dbType` token (optional) |
326
+ */
327
+ export const PluginDesignWindowListCatalogArgs = z.object({
328
+ group: z.string().optional(),
329
+ })
330
+ export type PluginDesignWindowListCatalogArgs = z.infer<
331
+ typeof PluginDesignWindowListCatalogArgs
332
+ >
333
+
334
+ /**
335
+ * Arguments for {@linkcode PluginDesignWindowsApi.getCatalogItem} / {@linkcode PluginDesignWindowsApi.exists}.
336
+ *
337
+ * | Property | Type | Description |
338
+ * |---|---|---|
339
+ * | `id` | `string` | The catalog library id |
340
+ */
341
+ export const PluginDesignWindowGetCatalogItemArgs = z.object({
342
+ id: z.string(),
343
+ })
344
+ export type PluginDesignWindowGetCatalogItemArgs = z.infer<
345
+ typeof PluginDesignWindowGetCatalogItemArgs
346
+ >
347
+
348
+ export const PluginDesignWindowExistsArgs = PluginDesignWindowGetCatalogItemArgs
349
+ export type PluginDesignWindowExistsArgs = z.infer<
350
+ typeof PluginDesignWindowExistsArgs
351
+ >