@snaptrude/plugin-core 0.9.17 → 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 (213) hide show
  1. package/AGENTS.md +231 -231
  2. package/CHANGELOG.md +408 -408
  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 +32 -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/shapes.d.ts +2 -2
  59. package/dist/api/presentation/sheets.d.ts +175 -19
  60. package/dist/api/presentation/sheets.d.ts.map +1 -1
  61. package/dist/api/presentation/viewPresets.d.ts +222 -0
  62. package/dist/api/presentation/viewPresets.d.ts.map +1 -0
  63. package/dist/api/presentation/views.d.ts +103 -5
  64. package/dist/api/presentation/views.d.ts.map +1 -1
  65. package/dist/api/presentation/walkthroughs.d.ts +6 -6
  66. package/dist/errors/codes.d.ts +3 -1
  67. package/dist/errors/codes.d.ts.map +1 -1
  68. package/dist/index.cjs +3732 -2383
  69. package/dist/index.cjs.map +1 -1
  70. package/dist/index.js +3607 -2383
  71. package/dist/index.js.map +1 -1
  72. package/package.json +42 -42
  73. package/scripts/check-dist-fresh.mjs +22 -22
  74. package/scripts/generate-manifest.mjs +243 -238
  75. package/scripts/generate-manifest.test.mjs +303 -303
  76. package/src/api/analysis/daylight.ts +470 -470
  77. package/src/api/analysis/heatmaps.ts +683 -683
  78. package/src/api/analysis/illuminance.ts +155 -155
  79. package/src/api/analysis/index.ts +61 -61
  80. package/src/api/analysis/shadows.ts +183 -183
  81. package/src/api/analysis/solar.ts +237 -237
  82. package/src/api/analysis/sunlightHours.ts +211 -211
  83. package/src/api/analysis/sunpath.ts +83 -83
  84. package/src/api/analysis/weather.ts +179 -179
  85. package/src/api/core/buildings.ts +485 -485
  86. package/src/api/core/camera/index.ts +696 -667
  87. package/src/api/core/comment/index.ts +376 -376
  88. package/src/api/core/geom/create/index.ts +2139 -2133
  89. package/src/api/core/geom/delete/index.ts +84 -84
  90. package/src/api/core/geom/index.ts +35 -35
  91. package/src/api/core/geom/query/arc.ts +169 -169
  92. package/src/api/core/geom/query/brep.ts +621 -621
  93. package/src/api/core/geom/query/circle.ts +404 -404
  94. package/src/api/core/geom/query/contour.ts +540 -540
  95. package/src/api/core/geom/query/curve.ts +1102 -1102
  96. package/src/api/core/geom/query/edge.ts +130 -130
  97. package/src/api/core/geom/query/face.ts +508 -508
  98. package/src/api/core/geom/query/halfedge.ts +210 -210
  99. package/src/api/core/geom/query/index.ts +63 -63
  100. package/src/api/core/geom/query/profile.ts +473 -473
  101. package/src/api/core/geom/query/vertex.ts +205 -205
  102. package/src/api/core/geom/update/contour.ts +323 -317
  103. package/src/api/core/geom/update/curve.ts +209 -209
  104. package/src/api/core/geom/update/index.ts +29 -29
  105. package/src/api/core/geom/update/profile.ts +379 -379
  106. package/src/api/core/groups.ts +521 -521
  107. package/src/api/core/handles/index.ts +234 -234
  108. package/src/api/core/history/index.ts +84 -84
  109. package/src/api/core/index.ts +99 -99
  110. package/src/api/core/io/export/index.ts +126 -126
  111. package/src/api/core/io/import/index.ts +504 -504
  112. package/src/api/core/io/index.ts +42 -42
  113. package/src/api/core/io/job/index.ts +140 -140
  114. package/src/api/core/io/query/index.ts +71 -71
  115. package/src/api/core/io/terrain/index.ts +360 -360
  116. package/src/api/core/io/underlay/index.ts +705 -705
  117. package/src/api/core/layers.ts +540 -540
  118. package/src/api/core/math/index.ts +20 -20
  119. package/src/api/core/math/quat.ts +172 -172
  120. package/src/api/core/math/vec3.ts +179 -179
  121. package/src/api/core/mode/index.ts +108 -108
  122. package/src/api/core/project/index.ts +479 -479
  123. package/src/api/core/proposals/index.ts +570 -570
  124. package/src/api/core/storeys/index.ts +308 -308
  125. package/src/api/core/storeys/layers.ts +339 -339
  126. package/src/api/core/tags.ts +911 -911
  127. package/src/api/core/units/index.ts +164 -164
  128. package/src/api/core/user.ts +46 -46
  129. package/src/api/core/zoom/index.ts +64 -51
  130. package/src/api/design/bim.ts +121 -0
  131. package/src/api/design/boolean/index.ts +181 -179
  132. package/src/api/design/catalog.ts +203 -0
  133. package/src/api/design/create/bulk-items.ts +294 -254
  134. package/src/api/design/create/grids.ts +137 -137
  135. package/src/api/design/create/index.ts +2148 -1980
  136. package/src/api/design/create/opening-fields.ts +40 -37
  137. package/src/api/design/delete/index.ts +75 -74
  138. package/src/api/design/dimensions.ts +453 -453
  139. package/src/api/design/doors/index.ts +516 -500
  140. package/src/api/design/edit/index.ts +54 -54
  141. package/src/api/design/erase/index.ts +151 -151
  142. package/src/api/design/family.ts +1334 -704
  143. package/src/api/design/furniture/index.ts +319 -319
  144. package/src/api/design/grids.ts +237 -237
  145. package/src/api/design/index.ts +304 -274
  146. package/src/api/design/lock.ts +69 -69
  147. package/src/api/design/materials/index.ts +608 -608
  148. package/src/api/design/networks.ts +667 -0
  149. package/src/api/design/query/geometry/index.ts +319 -319
  150. package/src/api/design/query/grids.ts +197 -197
  151. package/src/api/design/query/index.ts +1236 -1226
  152. package/src/api/design/query/referenceLines.ts +52 -52
  153. package/src/api/design/query/spaces.ts +275 -275
  154. package/src/api/design/selection/index.ts +273 -273
  155. package/src/api/design/shared.ts +40 -40
  156. package/src/api/design/transform/index.ts +254 -254
  157. package/src/api/design/types/index.ts +163 -156
  158. package/src/api/design/update/index.ts +1024 -983
  159. package/src/api/design/visibility.ts +143 -143
  160. package/src/api/design/windows/index.ts +351 -333
  161. package/src/api/entity/buildableEnvelope.ts +322 -322
  162. package/src/api/entity/index.ts +30 -30
  163. package/src/api/entity/referenceLine.ts +235 -235
  164. package/src/api/entity/space.ts +612 -612
  165. package/src/api/entity/story.ts +517 -517
  166. package/src/api/index.ts +47 -47
  167. package/src/api/presentation/aiInspiration.ts +1116 -1116
  168. package/src/api/presentation/annotate.ts +417 -385
  169. package/src/api/presentation/camera.ts +289 -289
  170. package/src/api/presentation/diagrams.ts +194 -194
  171. package/src/api/presentation/drawingContract.ts +70 -0
  172. package/src/api/presentation/drawings.ts +1179 -0
  173. package/src/api/presentation/export.ts +134 -108
  174. package/src/api/presentation/import.ts +159 -159
  175. package/src/api/presentation/index.ts +160 -135
  176. package/src/api/presentation/placedViews.ts +1211 -1120
  177. package/src/api/presentation/sections.ts +420 -420
  178. package/src/api/presentation/shapes.ts +274 -274
  179. package/src/api/presentation/sheets.ts +746 -585
  180. package/src/api/presentation/slideshow.ts +134 -134
  181. package/src/api/presentation/tables.ts +84 -84
  182. package/src/api/presentation/viewPresets.ts +241 -0
  183. package/src/api/presentation/views.ts +713 -673
  184. package/src/api/presentation/walkthroughs.ts +1201 -1201
  185. package/src/api/program/adjacency.ts +164 -164
  186. package/src/api/program/areas.ts +408 -408
  187. package/src/api/program/classification.ts +138 -138
  188. package/src/api/program/cores.ts +83 -83
  189. package/src/api/program/departments.ts +517 -517
  190. package/src/api/program/index.ts +73 -73
  191. package/src/api/program/labels.ts +332 -332
  192. package/src/api/program/layout.ts +422 -422
  193. package/src/api/program/metadata.ts +364 -364
  194. package/src/api/program/metrics.ts +120 -120
  195. package/src/api/program/site.ts +748 -748
  196. package/src/api/program/spreadsheet.ts +2698 -2698
  197. package/src/api/workspace/index.ts +612 -612
  198. package/src/errors/codes.ts +143 -136
  199. package/src/errors/envelope.ts +75 -75
  200. package/src/errors/index.ts +21 -21
  201. package/src/errors/plugin-error.ts +134 -134
  202. package/src/handles.ts +297 -297
  203. package/src/host-utils.ts +67 -67
  204. package/src/index.ts +7 -7
  205. package/src/massParameters.ops.ts +246 -246
  206. package/src/massParameters.ts +427 -427
  207. package/src/types.ts +16 -16
  208. package/test/drawingContract.test.mjs +288 -0
  209. package/test/errors.test.mjs +185 -184
  210. package/test/massParameters.test.mjs +952 -952
  211. package/tsconfig.json +22 -22
  212. package/tsup.config.ts +12 -12
  213. package/api-manifest.json +0 -9711
@@ -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
+ >