@snaptrude/plugin-core 0.0.0-dev-20260708130115 → 0.0.0-dev-20260827135706

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 (261) hide show
  1. package/CHANGELOG.md +152 -1
  2. package/api-manifest.json +3620 -276
  3. package/dist/api/analysis/daylight.d.ts +603 -0
  4. package/dist/api/analysis/daylight.d.ts.map +1 -0
  5. package/dist/api/analysis/heatmaps.d.ts +658 -0
  6. package/dist/api/analysis/heatmaps.d.ts.map +1 -0
  7. package/dist/api/analysis/illuminance.d.ts +145 -0
  8. package/dist/api/analysis/illuminance.d.ts.map +1 -0
  9. package/dist/api/analysis/index.d.ts +59 -0
  10. package/dist/api/analysis/index.d.ts.map +1 -0
  11. package/dist/api/analysis/shadows.d.ts +165 -0
  12. package/dist/api/analysis/shadows.d.ts.map +1 -0
  13. package/dist/api/analysis/solar.d.ts +249 -0
  14. package/dist/api/analysis/solar.d.ts.map +1 -0
  15. package/dist/api/analysis/sunlightHours.d.ts +208 -0
  16. package/dist/api/analysis/sunlightHours.d.ts.map +1 -0
  17. package/dist/api/analysis/sunpath.d.ts +80 -0
  18. package/dist/api/analysis/sunpath.d.ts.map +1 -0
  19. package/dist/api/analysis/weather.d.ts +193 -0
  20. package/dist/api/analysis/weather.d.ts.map +1 -0
  21. package/dist/api/core/camera/index.d.ts +261 -0
  22. package/dist/api/core/camera/index.d.ts.map +1 -0
  23. package/dist/api/core/comment/index.d.ts +105 -2
  24. package/dist/api/core/comment/index.d.ts.map +1 -1
  25. package/dist/api/core/geom/create/index.d.ts +840 -14
  26. package/dist/api/core/geom/create/index.d.ts.map +1 -1
  27. package/dist/api/core/geom/delete/index.d.ts +8 -2
  28. package/dist/api/core/geom/delete/index.d.ts.map +1 -1
  29. package/dist/api/core/geom/query/arc.d.ts +5 -5
  30. package/dist/api/core/geom/query/brep.d.ts +130 -18
  31. package/dist/api/core/geom/query/brep.d.ts.map +1 -1
  32. package/dist/api/core/geom/query/circle.d.ts +18 -18
  33. package/dist/api/core/geom/query/contour.d.ts +20 -20
  34. package/dist/api/core/geom/query/curve.d.ts +49 -49
  35. package/dist/api/core/geom/query/edge.d.ts +5 -5
  36. package/dist/api/core/geom/query/face.d.ts +16 -16
  37. package/dist/api/core/geom/query/halfedge.d.ts +8 -8
  38. package/dist/api/core/geom/query/profile.d.ts +19 -19
  39. package/dist/api/core/geom/query/vertex.d.ts +8 -8
  40. package/dist/api/core/geom/update/contour.d.ts +14 -14
  41. package/dist/api/core/geom/update/curve.d.ts +7 -7
  42. package/dist/api/core/geom/update/profile.d.ts +16 -16
  43. package/dist/api/core/handles/index.d.ts +210 -0
  44. package/dist/api/core/handles/index.d.ts.map +1 -0
  45. package/dist/api/core/index.d.ts +34 -0
  46. package/dist/api/core/index.d.ts.map +1 -1
  47. package/dist/api/core/io/export/index.d.ts +134 -0
  48. package/dist/api/core/io/export/index.d.ts.map +1 -0
  49. package/dist/api/core/io/import/index.d.ts +453 -0
  50. package/dist/api/core/io/import/index.d.ts.map +1 -0
  51. package/dist/api/core/io/index.d.ts +40 -0
  52. package/dist/api/core/io/index.d.ts.map +1 -0
  53. package/dist/api/core/io/job/index.d.ts +139 -0
  54. package/dist/api/core/io/job/index.d.ts.map +1 -0
  55. package/dist/api/core/io/query/index.d.ts +74 -0
  56. package/dist/api/core/io/query/index.d.ts.map +1 -0
  57. package/dist/api/core/io/terrain/index.d.ts +341 -0
  58. package/dist/api/core/io/terrain/index.d.ts.map +1 -0
  59. package/dist/api/core/io/underlay/index.d.ts +805 -0
  60. package/dist/api/core/io/underlay/index.d.ts.map +1 -0
  61. package/dist/api/core/layers.d.ts +7 -7
  62. package/dist/api/core/mode/index.d.ts +99 -0
  63. package/dist/api/core/mode/index.d.ts.map +1 -0
  64. package/dist/api/core/project/index.d.ts +68 -1
  65. package/dist/api/core/project/index.d.ts.map +1 -1
  66. package/dist/api/core/proposals/index.d.ts +531 -0
  67. package/dist/api/core/proposals/index.d.ts.map +1 -0
  68. package/dist/api/core/storeys/index.d.ts +265 -0
  69. package/dist/api/core/storeys/index.d.ts.map +1 -0
  70. package/dist/api/core/tags.d.ts +24 -0
  71. package/dist/api/core/tags.d.ts.map +1 -1
  72. package/dist/api/core/user.d.ts +44 -0
  73. package/dist/api/core/user.d.ts.map +1 -0
  74. package/dist/api/core/zoom/index.d.ts +4 -0
  75. package/dist/api/core/zoom/index.d.ts.map +1 -1
  76. package/dist/api/design/boolean/index.d.ts +4 -4
  77. package/dist/api/design/create/index.d.ts +568 -45
  78. package/dist/api/design/create/index.d.ts.map +1 -1
  79. package/dist/api/design/delete/index.d.ts +3 -0
  80. package/dist/api/design/delete/index.d.ts.map +1 -1
  81. package/dist/api/design/doors/index.d.ts +195 -0
  82. package/dist/api/design/doors/index.d.ts.map +1 -1
  83. package/dist/api/design/edit/index.d.ts +1 -1
  84. package/dist/api/design/erase/index.d.ts +2 -2
  85. package/dist/api/design/family.d.ts +349 -0
  86. package/dist/api/design/family.d.ts.map +1 -0
  87. package/dist/api/design/furniture/index.d.ts +181 -8
  88. package/dist/api/design/furniture/index.d.ts.map +1 -1
  89. package/dist/api/design/index.d.ts +98 -0
  90. package/dist/api/design/index.d.ts.map +1 -1
  91. package/dist/api/design/lock.d.ts +26 -0
  92. package/dist/api/design/lock.d.ts.map +1 -1
  93. package/dist/api/design/materials/index.d.ts +270 -16
  94. package/dist/api/design/materials/index.d.ts.map +1 -1
  95. package/dist/api/design/query/geometry/index.d.ts +112 -0
  96. package/dist/api/design/query/geometry/index.d.ts.map +1 -1
  97. package/dist/api/design/query/index.d.ts +282 -11
  98. package/dist/api/design/query/index.d.ts.map +1 -1
  99. package/dist/api/design/query/referenceLines.d.ts +45 -0
  100. package/dist/api/design/query/referenceLines.d.ts.map +1 -0
  101. package/dist/api/design/query/spaces.d.ts +181 -8
  102. package/dist/api/design/query/spaces.d.ts.map +1 -1
  103. package/dist/api/design/selection/index.d.ts +144 -0
  104. package/dist/api/design/selection/index.d.ts.map +1 -1
  105. package/dist/api/design/transform/index.d.ts +172 -10
  106. package/dist/api/design/transform/index.d.ts.map +1 -1
  107. package/dist/api/design/types/index.d.ts +181 -0
  108. package/dist/api/design/types/index.d.ts.map +1 -0
  109. package/dist/api/design/update/index.d.ts +553 -2
  110. package/dist/api/design/update/index.d.ts.map +1 -1
  111. package/dist/api/design/visibility.d.ts +126 -0
  112. package/dist/api/design/visibility.d.ts.map +1 -0
  113. package/dist/api/design/windows/index.d.ts +113 -2
  114. package/dist/api/design/windows/index.d.ts.map +1 -1
  115. package/dist/api/entity/buildableEnvelope.d.ts +4 -0
  116. package/dist/api/entity/buildableEnvelope.d.ts.map +1 -1
  117. package/dist/api/entity/referenceLine.d.ts +10 -2
  118. package/dist/api/entity/referenceLine.d.ts.map +1 -1
  119. package/dist/api/entity/space.d.ts +21 -21
  120. package/dist/api/entity/story.d.ts +242 -15
  121. package/dist/api/entity/story.d.ts.map +1 -1
  122. package/dist/api/index.d.ts +10 -0
  123. package/dist/api/index.d.ts.map +1 -1
  124. package/dist/api/presentation/aiInspiration.d.ts +25 -25
  125. package/dist/api/presentation/annotate.d.ts +467 -0
  126. package/dist/api/presentation/annotate.d.ts.map +1 -0
  127. package/dist/api/presentation/diagrams.d.ts +111 -8
  128. package/dist/api/presentation/diagrams.d.ts.map +1 -1
  129. package/dist/api/presentation/export.d.ts +108 -0
  130. package/dist/api/presentation/export.d.ts.map +1 -0
  131. package/dist/api/presentation/import.d.ts +55 -4
  132. package/dist/api/presentation/import.d.ts.map +1 -1
  133. package/dist/api/presentation/index.d.ts +58 -1
  134. package/dist/api/presentation/index.d.ts.map +1 -1
  135. package/dist/api/presentation/placedViews.d.ts +1139 -0
  136. package/dist/api/presentation/placedViews.d.ts.map +1 -0
  137. package/dist/api/presentation/shapes.d.ts +481 -0
  138. package/dist/api/presentation/shapes.d.ts.map +1 -0
  139. package/dist/api/presentation/sheets.d.ts +452 -13
  140. package/dist/api/presentation/sheets.d.ts.map +1 -1
  141. package/dist/api/presentation/slideshow.d.ts +125 -0
  142. package/dist/api/presentation/slideshow.d.ts.map +1 -0
  143. package/dist/api/presentation/tables.d.ts +81 -0
  144. package/dist/api/presentation/tables.d.ts.map +1 -0
  145. package/dist/api/presentation/views.d.ts +367 -7
  146. package/dist/api/presentation/views.d.ts.map +1 -1
  147. package/dist/api/program/areas.d.ts +102 -12
  148. package/dist/api/program/areas.d.ts.map +1 -1
  149. package/dist/api/program/cores.d.ts +3 -99
  150. package/dist/api/program/cores.d.ts.map +1 -1
  151. package/dist/api/program/index.d.ts +7 -15
  152. package/dist/api/program/index.d.ts.map +1 -1
  153. package/dist/api/program/layout.d.ts +346 -11
  154. package/dist/api/program/layout.d.ts.map +1 -1
  155. package/dist/api/program/site.d.ts +469 -13
  156. package/dist/api/program/site.d.ts.map +1 -1
  157. package/dist/api/program/spreadsheet.d.ts +365 -41
  158. package/dist/api/program/spreadsheet.d.ts.map +1 -1
  159. package/dist/api/workspace/index.d.ts +505 -0
  160. package/dist/api/workspace/index.d.ts.map +1 -0
  161. package/dist/errors/codes.d.ts +34 -0
  162. package/dist/errors/codes.d.ts.map +1 -0
  163. package/dist/errors/envelope.d.ts +56 -0
  164. package/dist/errors/envelope.d.ts.map +1 -0
  165. package/dist/errors/index.d.ts +6 -0
  166. package/dist/errors/index.d.ts.map +1 -0
  167. package/dist/errors/plugin-error.d.ts +69 -0
  168. package/dist/errors/plugin-error.d.ts.map +1 -0
  169. package/dist/handles.d.ts +97 -25
  170. package/dist/handles.d.ts.map +1 -1
  171. package/dist/host-utils.d.ts +4 -0
  172. package/dist/host-utils.d.ts.map +1 -1
  173. package/dist/index.cjs +4582 -1422
  174. package/dist/index.cjs.map +1 -1
  175. package/dist/index.d.ts +1 -0
  176. package/dist/index.d.ts.map +1 -1
  177. package/dist/index.js +4171 -1411
  178. package/dist/index.js.map +1 -1
  179. package/package.json +4 -2
  180. package/scripts/generate-manifest.mjs +45 -0
  181. package/scripts/generate-manifest.test.mjs +103 -4
  182. package/src/api/analysis/daylight.ts +470 -0
  183. package/src/api/analysis/heatmaps.ts +683 -0
  184. package/src/api/analysis/illuminance.ts +155 -0
  185. package/src/api/analysis/index.ts +61 -0
  186. package/src/api/analysis/shadows.ts +183 -0
  187. package/src/api/analysis/solar.ts +237 -0
  188. package/src/api/analysis/sunlightHours.ts +211 -0
  189. package/src/api/analysis/sunpath.ts +83 -0
  190. package/src/api/analysis/weather.ts +179 -0
  191. package/src/api/core/camera/index.ts +268 -0
  192. package/src/api/core/comment/index.ts +120 -2
  193. package/src/api/core/geom/create/index.ts +912 -1
  194. package/src/api/core/geom/delete/index.ts +6 -0
  195. package/src/api/core/geom/query/brep.ts +119 -0
  196. package/src/api/core/handles/index.ts +233 -0
  197. package/src/api/core/index.ts +34 -0
  198. package/src/api/core/io/export/index.ts +126 -0
  199. package/src/api/core/io/import/index.ts +496 -0
  200. package/src/api/core/io/index.ts +42 -0
  201. package/src/api/core/io/job/index.ts +140 -0
  202. package/src/api/core/io/query/index.ts +71 -0
  203. package/src/api/core/io/terrain/index.ts +360 -0
  204. package/src/api/core/io/underlay/index.ts +705 -0
  205. package/src/api/core/mode/index.ts +96 -0
  206. package/src/api/core/project/index.ts +62 -1
  207. package/src/api/core/proposals/index.ts +569 -0
  208. package/src/api/core/storeys/index.ts +294 -0
  209. package/src/api/core/tags.ts +27 -0
  210. package/src/api/core/user.ts +46 -0
  211. package/src/api/core/zoom/index.ts +4 -0
  212. package/src/api/design/create/index.ts +670 -30
  213. package/src/api/design/delete/index.ts +3 -0
  214. package/src/api/design/doors/index.ts +208 -0
  215. package/src/api/design/erase/index.ts +1 -1
  216. package/src/api/design/family.ts +388 -0
  217. package/src/api/design/furniture/index.ts +197 -8
  218. package/src/api/design/index.ts +102 -0
  219. package/src/api/design/lock.ts +27 -0
  220. package/src/api/design/materials/index.ts +334 -27
  221. package/src/api/design/query/geometry/index.ts +125 -3
  222. package/src/api/design/query/index.ts +217 -7
  223. package/src/api/design/query/referenceLines.ts +52 -0
  224. package/src/api/design/query/spaces.ts +143 -0
  225. package/src/api/design/selection/index.ts +129 -0
  226. package/src/api/design/transform/index.ts +170 -9
  227. package/src/api/design/types/index.ts +156 -0
  228. package/src/api/design/update/index.ts +631 -3
  229. package/src/api/design/visibility.ts +143 -0
  230. package/src/api/design/windows/index.ts +128 -2
  231. package/src/api/entity/buildableEnvelope.ts +4 -0
  232. package/src/api/entity/referenceLine.ts +8 -0
  233. package/src/api/entity/story.ts +259 -15
  234. package/src/api/index.ts +10 -0
  235. package/src/api/presentation/annotate.ts +385 -0
  236. package/src/api/presentation/diagrams.ts +118 -8
  237. package/src/api/presentation/export.ts +108 -0
  238. package/src/api/presentation/import.ts +51 -4
  239. package/src/api/presentation/index.ts +66 -1
  240. package/src/api/presentation/placedViews.ts +1120 -0
  241. package/src/api/presentation/shapes.ts +274 -0
  242. package/src/api/presentation/sheets.ts +400 -13
  243. package/src/api/presentation/slideshow.ts +134 -0
  244. package/src/api/presentation/tables.ts +84 -0
  245. package/src/api/presentation/views.ts +376 -8
  246. package/src/api/program/areas.ts +88 -15
  247. package/src/api/program/cores.ts +3 -91
  248. package/src/api/program/index.ts +7 -15
  249. package/src/api/program/layout.ts +365 -11
  250. package/src/api/program/site.ts +435 -13
  251. package/src/api/program/spreadsheet.ts +376 -35
  252. package/src/api/workspace/index.ts +563 -0
  253. package/src/errors/codes.ts +136 -0
  254. package/src/errors/envelope.ts +75 -0
  255. package/src/errors/index.ts +21 -0
  256. package/src/errors/plugin-error.ts +134 -0
  257. package/src/handles.ts +123 -13
  258. package/src/host-utils.ts +4 -0
  259. package/src/index.ts +1 -0
  260. package/test/errors.test.mjs +184 -0
  261. package/tsconfig.json +7 -2
@@ -8,8 +8,31 @@ import { PluginApiReturn } from "../../types";
8
8
  * three of the space-planning workflow that starts with
9
9
  * {@linkcode PluginProgramAdjacencyApi} (`program.adjacency`).
10
10
  *
11
- * _(Authored ahead both methods are optional until the host lands them in
12
- * the next increment, and are kept out of the discovery manifest until then.)_
11
+ * Both {@linkcode PluginProgramLayoutApi.arrange} and
12
+ * {@linkcode PluginProgramLayoutApi.pack} run as an **asynchronous backend
13
+ * job** on the space-solver service:
14
+ *
15
+ * 1. `arrange` / `pack` start the job and **return immediately** — they do
16
+ * not wait for the layout.
17
+ * 2. Poll {@linkcode PluginProgramLayoutApi.getState} until `status` is no
18
+ * longer `"running"` — a run can take up to 20 minutes.
19
+ * 3. {@linkcode PluginProgramLayoutApi.cancel} aborts an in-flight run.
20
+ *
21
+ * `arrange` produces several candidate layouts. By default it **auto-commits
22
+ * the first solution** as one undoable edit; pass `autoCommit: false` to hold
23
+ * the candidates for review instead — `getState` then reports
24
+ * `status: "pendingReview"` with `totalSolutions`, and
25
+ * {@linkcode PluginProgramLayoutApi.applySolution} commits the one you pick
26
+ * (the headless counterpart of the product's "Solution N of M → Apply" bar).
27
+ * `pack` re-shapes and applies its single result directly. Both are
28
+ * **Pro-plan-gated**, matching the product UI.
29
+ *
30
+ * {@linkcode PluginProgramLayoutApi.stack} is the **cross-storey** action —
31
+ * the product's *Pack in envelope* / auto-stack. It splits the building
32
+ * envelope by storey and packs each storey's departments into its slice as one
33
+ * undoable edit. Unlike `arrange` / `pack`, it is **not** the async-job model:
34
+ * it resolves inline when the whole multi-storey pack is done (no `getState`
35
+ * polling) and returns the storeys it had to skip. It is Pro-gated too.
13
36
  *
14
37
  * Accessed via `snaptrude.program.layout`.
15
38
  */
@@ -17,22 +40,83 @@ export declare abstract class PluginProgramLayoutApi {
17
40
  constructor();
18
41
  /**
19
42
  * Arrange the spaces inside the envelope using the computed adjacency data.
20
- * _(Authored ahead — optional until the host lands.)_
43
+ *
44
+ * Starts the backend job and **returns immediately** — poll
45
+ * {@linkcode PluginProgramLayoutApi.getState} until `status` leaves
46
+ * `"running"` (a run can take up to 20 minutes). The solver produces
47
+ * several candidate layouts; by default this **auto-commits the first
48
+ * solution** as one undoable edit. Pass `autoCommit: false` to review them
49
+ * instead: the run finishes with `status: "pendingReview"` and
50
+ * `totalSolutions` in `getState`, and
51
+ * {@linkcode PluginProgramLayoutApi.applySolution} commits the candidate you
52
+ * pick ({@linkcode PluginProgramLayoutApi.cancel} discards them). An
53
+ * arrange **without an envelope** applies directly (there is nothing to
54
+ * review) regardless of `autoCommit`. Starting a run while one is in flight
55
+ * replaces it; while solutions are pending review, new runs are refused —
56
+ * apply or cancel first.
57
+ *
58
+ * With no `options`, operates on the eligible Room/Department masses on the
59
+ * active storey and auto-detects the single buildable envelope there.
60
+ *
61
+ * @param options - Optional {@linkcode PluginProgramLayoutRunArgs} — the
62
+ * space / department masses to arrange and the envelope to fit them in.
63
+ * Omitted fields fall back to the active-storey defaults.
64
+ * @returns A {@linkcode PluginProgramLayoutRunResult} — `{ success: true }`
65
+ * when the job was started. Solver failures surface through
66
+ * {@linkcode PluginProgramLayoutApi.getState} (`status: "inactive"`), not
67
+ * as a rejected call.
68
+ * @throws When the project is not on a Pro plan.
69
+ * @throws When a `spaceId` / `departmentId` / `envelopeId` does not resolve.
70
+ * @throws When more than one envelope is on the active storey and none was
71
+ * given (ambiguous).
72
+ * @throws When arrange solutions are pending review (apply or cancel them
73
+ * first).
74
+ * @throws When plugin writes are disabled.
21
75
  *
22
76
  * @examplePrompt Arrange the rooms in the envelope
23
77
  * @examplePrompt Lay out the departments inside the building envelope
24
78
  * @examplePrompt Auto-arrange the program spaces
79
+ * @examplePrompt Arrange the rooms but let me pick the solution
25
80
  *
26
81
  * # Example
27
82
  * ```ts
28
83
  * const { success, error } = await snaptrude.program.layout.arrange()
29
- * if (!success) console.log("Arrange failed:", error)
84
+ * if (!success) throw new Error(error)
85
+ * // poll until the layout is applied
86
+ * let job = await snaptrude.program.layout.getState()
87
+ * while (job?.status === "running") {
88
+ * await new Promise((r) => setTimeout(r, 5000))
89
+ * job = await snaptrude.program.layout.getState()
90
+ * }
30
91
  * ```
31
92
  */
32
- arrange?: () => PluginApiReturn<PluginProgramLayoutRunResult>;
93
+ abstract arrange(options?: PluginProgramLayoutRunArgs): PluginApiReturn<PluginProgramLayoutRunResult>;
33
94
  /**
34
95
  * Pack the spaces into the envelope (a tighter fit than arrange).
35
- * _(Authored ahead — optional until the host lands.)_
96
+ *
97
+ * Like {@linkcode PluginProgramLayoutApi.arrange}, this starts the backend
98
+ * job and **returns immediately** — poll
99
+ * {@linkcode PluginProgramLayoutApi.getState} until `status` leaves
100
+ * `"running"` (up to 20 minutes). Pack re-shapes mass geometry to fit and
101
+ * **applies its single result directly** (no solution review). Starting a
102
+ * run while one is in flight replaces it.
103
+ *
104
+ * With no `options`, operates on the eligible Room/Department masses on the
105
+ * active storey and auto-detects the single buildable envelope there.
106
+ *
107
+ * @param options - Optional {@linkcode PluginProgramLayoutRunArgs} — same
108
+ * shape as `arrange`; omitted fields fall back to the active-storey
109
+ * defaults.
110
+ * @returns A {@linkcode PluginProgramLayoutRunResult} — `{ success: true }`
111
+ * when the job was started. Solver failures surface through
112
+ * {@linkcode PluginProgramLayoutApi.getState} (`status: "inactive"`).
113
+ * @throws When the project is not on a Pro plan.
114
+ * @throws When a `spaceId` / `departmentId` / `envelopeId` does not resolve.
115
+ * @throws When more than one envelope is on the active storey and none was
116
+ * given (ambiguous).
117
+ * @throws When arrange solutions are pending review (apply or cancel them
118
+ * first).
119
+ * @throws When plugin writes are disabled.
36
120
  *
37
121
  * @examplePrompt Pack the rooms into the envelope
38
122
  * @examplePrompt Fit the program spaces tightly into the building
@@ -40,19 +124,181 @@ export declare abstract class PluginProgramLayoutApi {
40
124
  *
41
125
  * # Example
42
126
  * ```ts
43
- * const { success, error } = await snaptrude.program.layout.pack()
44
- * if (!success) console.log("Pack failed:", error)
127
+ * const { success } = await snaptrude.program.layout.pack({ envelopeId: "be_..." })
128
+ * let job = await snaptrude.program.layout.getState()
129
+ * while (job?.status === "running") {
130
+ * await new Promise((r) => setTimeout(r, 5000))
131
+ * job = await snaptrude.program.layout.getState()
132
+ * }
133
+ * ```
134
+ */
135
+ abstract pack(options?: PluginProgramLayoutRunArgs): PluginApiReturn<PluginProgramLayoutRunResult>;
136
+ /**
137
+ * Apply one of the pending arrange solutions.
138
+ *
139
+ * The headless counterpart of the product's **"Solution N of M → Apply"**
140
+ * review bar: after an {@linkcode PluginProgramLayoutApi.arrange} run
141
+ * started with `autoCommit: false` finishes with `status: "pendingReview"`,
142
+ * this commits the candidate at `index` (0-based,
143
+ * `0 ≤ index < totalSolutions` from
144
+ * {@linkcode PluginProgramLayoutApi.getState}) as **one undoable edit** and
145
+ * discards the other candidates. `getState` then reports
146
+ * `status: "active"`.
147
+ *
148
+ * @param index - 0-based index of the pending solution to apply.
149
+ * @returns A {@linkcode PluginProgramLayoutApplyResult} —
150
+ * `{ success: true }` when the solution was applied.
151
+ * @throws When no arrange solutions are pending review (no
152
+ * `arrange({ autoCommit: false })` run has finished, or its solutions were
153
+ * already applied / cancelled).
154
+ * @throws When `index` is out of range for the pending solutions.
155
+ * @throws When plugin writes are disabled.
156
+ *
157
+ * @examplePrompt Apply the second arrange solution
158
+ * @examplePrompt Pick layout solution 3 and commit it
159
+ * @examplePrompt Apply the arrange solution I chose
160
+ *
161
+ * # Example
162
+ * ```ts
163
+ * await snaptrude.program.layout.arrange({ autoCommit: false })
164
+ * let job = await snaptrude.program.layout.getState()
165
+ * while (job?.status === "running") {
166
+ * await new Promise((r) => setTimeout(r, 5000))
167
+ * job = await snaptrude.program.layout.getState()
168
+ * }
169
+ * if (job?.status === "pendingReview") {
170
+ * console.log(`${job.totalSolutions} candidate layouts`)
171
+ * await snaptrude.program.layout.applySolution(1) // commit the second one
172
+ * }
173
+ * ```
174
+ */
175
+ abstract applySolution(index: number): PluginApiReturn<PluginProgramLayoutApplyResult>;
176
+ /**
177
+ * Stack the program across **every storey** of the building — the product's
178
+ * *Pack in envelope* / auto-stack.
179
+ *
180
+ * Splits the building envelope massing into per-storey envelope slices, then
181
+ * packs each storey's departments into its slice, applying the whole
182
+ * multi-storey result as **one undoable edit**.
183
+ *
184
+ * Unlike {@linkcode PluginProgramLayoutApi.arrange} /
185
+ * {@linkcode PluginProgramLayoutApi.pack}, this **is not** the async-job
186
+ * model: `await` it and it resolves when the stack is done — there is no
187
+ * `getState` polling. It operates on the whole active model (no id / envelope
188
+ * arguments): it auto-discovers the departments and envelope on each storey.
189
+ *
190
+ * Storeys that have departments but **no envelope** are reported in
191
+ * `skippedStoreys` (nothing was packed there). A storey's departments must
192
+ * already be on that storey — `stack` does not move departments between
193
+ * floors, it lays out each floor's program into that floor's envelope.
194
+ *
195
+ * @returns A {@linkcode PluginProgramLayoutStackResult} — `success: true`
196
+ * with the (possibly empty) `skippedStoreys` when the stack was applied, or
197
+ * `success: false` with an `error` when the run failed (e.g. the adjacency
198
+ * service was unreachable).
199
+ * @throws When the project is not on a Pro plan.
200
+ * @throws When plugin writes are disabled.
201
+ * @throws When an `arrange` / `pack` run, or another `stack`, is already in
202
+ * flight, or arrange solutions are pending review (finish, apply, or
203
+ * `cancel` first).
204
+ *
205
+ * @examplePrompt Stack the program across all floors
206
+ * @examplePrompt Auto-stack the departments into the envelope on every storey
207
+ * @examplePrompt Pack the whole building's program into its envelope
208
+ *
209
+ * # Example
210
+ * ```ts
211
+ * const { success, skippedStoreys, error } = await snaptrude.program.layout.stack()
212
+ * if (!success) throw new Error(error)
213
+ * if (skippedStoreys.length)
214
+ * console.warn(`No envelope on storeys: ${skippedStoreys.join(", ")}`)
215
+ * ```
216
+ */
217
+ abstract stack(): PluginApiReturn<PluginProgramLayoutStackResult>;
218
+ /**
219
+ * Get the state of the layout run.
220
+ *
221
+ * The polling read for the async job started by
222
+ * {@linkcode PluginProgramLayoutApi.arrange} /
223
+ * {@linkcode PluginProgramLayoutApi.pack}. `status` values:
224
+ *
225
+ * | Status | Meaning |
226
+ * |---|---|
227
+ * | `"running"` | A run is in flight — keep polling |
228
+ * | `"active"` | The run finished and its layout is applied to the model |
229
+ * | `"inactive"` | A run finished without applying a layout (the solver failed or found no solution) |
230
+ * | `"pendingReview"` | An `arrange({ autoCommit: false })` run finished and its candidates await {@linkcode PluginProgramLayoutApi.applySolution} / {@linkcode PluginProgramLayoutApi.cancel} |
231
+ *
232
+ * While `status` is `"pendingReview"` the state also carries
233
+ * `totalSolutions` — the number of candidate layouts to pick from.
234
+ *
235
+ * @returns A {@linkcode PluginProgramLayoutStateResult} with the run
236
+ * `status`, or `null` when no run result is available (never ran or was
237
+ * cancelled).
238
+ *
239
+ * @examplePrompt Is the arrange done?
240
+ * @examplePrompt Check the status of the layout run
241
+ * @examplePrompt Did the pack finish?
242
+ *
243
+ * # Example
244
+ * ```ts
245
+ * const job = await snaptrude.program.layout.getState()
246
+ * if (job?.status === "active") console.log("layout applied")
247
+ * ```
248
+ */
249
+ abstract getState(): PluginApiReturn<PluginProgramLayoutStateResult>;
250
+ /**
251
+ * Cancel the in-flight layout run.
252
+ *
253
+ * Aborts the backend job and discards any pending solution. Also discards
254
+ * a finished run's **pending-review** solutions (after
255
+ * `arrange({ autoCommit: false })`) without applying one. A no-op (returns
256
+ * `false`) when nothing is running and nothing is pending.
257
+ *
258
+ * @returns `true` when a run was cancelled or pending solutions were
259
+ * discarded, `false` when there was nothing to cancel.
260
+ * @throws When plugin writes are disabled.
261
+ *
262
+ * @examplePrompt Cancel the arrange
263
+ * @examplePrompt Stop the running layout job
264
+ * @examplePrompt Abort the pack in envelope
265
+ *
266
+ * # Example
267
+ * ```ts
268
+ * await snaptrude.program.layout.cancel()
45
269
  * ```
46
270
  */
47
- pack?: () => PluginApiReturn<PluginProgramLayoutRunResult>;
271
+ abstract cancel(): PluginApiReturn<boolean>;
48
272
  }
273
+ /**
274
+ * Arguments for {@linkcode PluginProgramLayoutApi.arrange} /
275
+ * {@linkcode PluginProgramLayoutApi.pack}. All fields are optional — omitted
276
+ * fields fall back to the eligible masses and the single envelope on the
277
+ * active storey.
278
+ *
279
+ * | Property | Type | Description |
280
+ * |---|---|---|
281
+ * | `spaceIds` | `string[] \| undefined` | Component ids of the Room masses to lay out |
282
+ * | `departmentIds` | `string[] \| undefined` | Component ids of the Department masses to lay out |
283
+ * | `envelopeId` | `string \| undefined` | The envelope to fit into — a mass component id or a buildable-envelope handle (`be_…`); omit to auto-detect the single envelope on the active storey |
284
+ * | `autoCommit` | `boolean \| undefined` | `arrange` only — `true` / omitted (default) auto-commits the first candidate solution; `false` holds the candidates for review via {@linkcode PluginProgramLayoutApi.applySolution}. Ignored by `pack` (it applies its single result directly) |
285
+ */
286
+ export declare const PluginProgramLayoutRunArgs: z.ZodObject<{
287
+ spaceIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
288
+ departmentIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
289
+ envelopeId: z.ZodOptional<z.ZodString>;
290
+ autoCommit: z.ZodOptional<z.ZodBoolean>;
291
+ }, z.core.$strip>;
292
+ export type PluginProgramLayoutRunArgs = z.infer<typeof PluginProgramLayoutRunArgs>;
49
293
  /**
50
294
  * Result of {@linkcode PluginProgramLayoutApi.arrange} /
51
- * {@linkcode PluginProgramLayoutApi.pack}.
295
+ * {@linkcode PluginProgramLayoutApi.pack} — reports whether the run was
296
+ * **started**, not whether the layout finished (poll
297
+ * {@linkcode PluginProgramLayoutApi.getState} for completion).
52
298
  *
53
299
  * | Property | Type | Description |
54
300
  * |---|---|---|
55
- * | `success` | `boolean` | Whether the layout run completed |
301
+ * | `success` | `boolean` | Whether the layout run was started |
56
302
  * | `error` | `string \| undefined` | Failure reason when `success` is `false` |
57
303
  */
58
304
  export declare const PluginProgramLayoutRunResult: z.ZodObject<{
@@ -60,4 +306,93 @@ export declare const PluginProgramLayoutRunResult: z.ZodObject<{
60
306
  error: z.ZodOptional<z.ZodString>;
61
307
  }, z.core.$strip>;
62
308
  export type PluginProgramLayoutRunResult = z.infer<typeof PluginProgramLayoutRunResult>;
309
+ /**
310
+ * The status of a layout run.
311
+ *
312
+ * | Value | Meaning |
313
+ * |---|---|
314
+ * | `"running"` | A run is in flight — keep polling |
315
+ * | `"active"` | The run finished and its layout is applied to the model |
316
+ * | `"inactive"` | A run finished without applying a layout (the solver failed or found no solution) |
317
+ * | `"pendingReview"` | An `arrange({ autoCommit: false })` run finished and its candidate solutions await {@linkcode PluginProgramLayoutApi.applySolution} / {@linkcode PluginProgramLayoutApi.cancel} |
318
+ */
319
+ export declare const PluginProgramLayoutJobStatus: z.ZodEnum<{
320
+ running: "running";
321
+ active: "active";
322
+ inactive: "inactive";
323
+ pendingReview: "pendingReview";
324
+ }>;
325
+ export type PluginProgramLayoutJobStatus = z.infer<typeof PluginProgramLayoutJobStatus>;
326
+ /**
327
+ * The state of a layout run.
328
+ *
329
+ * | Property | Type | Description |
330
+ * |---|---|---|
331
+ * | `status` | {@linkcode PluginProgramLayoutJobStatus} | `"running"` \| `"active"` \| `"inactive"` \| `"pendingReview"` |
332
+ * | `totalSolutions` | `number \| undefined` | Number of candidate solutions awaiting review — present only while `status` is `"pendingReview"` |
333
+ */
334
+ export declare const PluginProgramLayoutJobState: z.ZodObject<{
335
+ status: z.ZodEnum<{
336
+ running: "running";
337
+ active: "active";
338
+ inactive: "inactive";
339
+ pendingReview: "pendingReview";
340
+ }>;
341
+ totalSolutions: z.ZodOptional<z.ZodNumber>;
342
+ }, z.core.$strip>;
343
+ export type PluginProgramLayoutJobState = z.infer<typeof PluginProgramLayoutJobState>;
344
+ /**
345
+ * Result of {@linkcode PluginProgramLayoutApi.getState} — the run state, or
346
+ * `null` when no run result is available (never ran or was cancelled).
347
+ */
348
+ export declare const PluginProgramLayoutStateResult: z.ZodNullable<z.ZodObject<{
349
+ status: z.ZodEnum<{
350
+ running: "running";
351
+ active: "active";
352
+ inactive: "inactive";
353
+ pendingReview: "pendingReview";
354
+ }>;
355
+ totalSolutions: z.ZodOptional<z.ZodNumber>;
356
+ }, z.core.$strip>>;
357
+ export type PluginProgramLayoutStateResult = z.infer<typeof PluginProgramLayoutStateResult>;
358
+ /**
359
+ * Arguments for {@linkcode PluginProgramLayoutApi.applySolution}.
360
+ *
361
+ * | Property | Type | Description |
362
+ * |---|---|---|
363
+ * | `index` | `number` | 0-based index of the pending solution to apply (`0 ≤ index < totalSolutions`) |
364
+ */
365
+ export declare const PluginProgramLayoutApplySolutionArgs: z.ZodObject<{
366
+ index: z.ZodNumber;
367
+ }, z.core.$strip>;
368
+ export type PluginProgramLayoutApplySolutionArgs = z.infer<typeof PluginProgramLayoutApplySolutionArgs>;
369
+ /**
370
+ * Result of {@linkcode PluginProgramLayoutApi.applySolution}.
371
+ *
372
+ * | Property | Type | Description |
373
+ * |---|---|---|
374
+ * | `success` | `boolean` | Whether the chosen solution was applied |
375
+ * | `error` | `string \| undefined` | Failure reason when `success` is `false` |
376
+ */
377
+ export declare const PluginProgramLayoutApplyResult: z.ZodObject<{
378
+ success: z.ZodBoolean;
379
+ error: z.ZodOptional<z.ZodString>;
380
+ }, z.core.$strip>;
381
+ export type PluginProgramLayoutApplyResult = z.infer<typeof PluginProgramLayoutApplyResult>;
382
+ /**
383
+ * Result of {@linkcode PluginProgramLayoutApi.stack} — reports whether the
384
+ * cross-storey stack was applied and which storeys were skipped.
385
+ *
386
+ * | Property | Type | Description |
387
+ * |---|---|---|
388
+ * | `success` | `boolean` | Whether the stack was applied |
389
+ * | `skippedStoreys` | `number[]` | Storey values that had departments but no envelope, so nothing was packed there |
390
+ * | `error` | `string \| undefined` | Failure reason when `success` is `false` |
391
+ */
392
+ export declare const PluginProgramLayoutStackResult: z.ZodObject<{
393
+ success: z.ZodBoolean;
394
+ skippedStoreys: z.ZodArray<z.ZodNumber>;
395
+ error: z.ZodOptional<z.ZodString>;
396
+ }, z.core.$strip>;
397
+ export type PluginProgramLayoutStackResult = z.infer<typeof PluginProgramLayoutStackResult>;
63
398
  //# sourceMappingURL=layout.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../../src/api/program/layout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7C;;;;;;;;;;;;GAYG;AACH,8BAAsB,sBAAsB;;IAG1C;;;;;;;;;;;;;OAaG;IACI,OAAO,CAAC,EAAE,MAAM,eAAe,CAAC,4BAA4B,CAAC,CAAA;IAEpE;;;;;;;;;;;;;OAaG;IACI,IAAI,CAAC,EAAE,MAAM,eAAe,CAAC,4BAA4B,CAAC,CAAA;CAClE;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B;;;iBAGvC,CAAA;AACF,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAChD,OAAO,4BAA4B,CACpC,CAAA"}
1
+ {"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../../src/api/program/layout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,8BAAsB,sBAAsB;;IAG1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmDG;aACa,OAAO,CACrB,OAAO,CAAC,EAAE,0BAA0B,GACnC,eAAe,CAAC,4BAA4B,CAAC;IAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;aACa,IAAI,CAClB,OAAO,CAAC,EAAE,0BAA0B,GACnC,eAAe,CAAC,4BAA4B,CAAC;IAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;aACa,aAAa,CAC3B,KAAK,EAAE,MAAM,GACZ,eAAe,CAAC,8BAA8B,CAAC;IAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;aACa,KAAK,IAAI,eAAe,CAAC,8BAA8B,CAAC;IAExE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;aACa,QAAQ,IAAI,eAAe,CAAC,8BAA8B,CAAC;IAE3E;;;;;;;;;;;;;;;;;;;;OAoBG;aACa,MAAM,IAAI,eAAe,CAAC,OAAO,CAAC;CACnD;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,0BAA0B;;;;;iBAKrC,CAAA;AACF,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAC9C,OAAO,0BAA0B,CAClC,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B;;;iBAGvC,CAAA;AACF,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAChD,OAAO,4BAA4B,CACpC,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,4BAA4B;;;;;EAKvC,CAAA;AACF,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAChD,OAAO,4BAA4B,CACpC,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;iBAGtC,CAAA;AACF,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAC/C,OAAO,2BAA2B,CACnC,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,8BAA8B;;;;;;;;kBACH,CAAA;AACxC,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,KAAK,CAClD,OAAO,8BAA8B,CACtC,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oCAAoC;;iBAE/C,CAAA;AACF,MAAM,MAAM,oCAAoC,GAAG,CAAC,CAAC,KAAK,CACxD,OAAO,oCAAoC,CAC5C,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,8BAA8B;;;iBAGzC,CAAA;AACF,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,KAAK,CAClD,OAAO,8BAA8B,CACtC,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,8BAA8B;;;;iBAIzC,CAAA;AACF,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,KAAK,CAClD,OAAO,8BAA8B,CACtC,CAAA"}