@snaptrude/plugin-core 0.9.16 → 0.9.18-edgesetbacks-20261021.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 (221) hide show
  1. package/AGENTS.md +231 -231
  2. package/CHANGELOG.md +408 -402
  3. package/CLAUDE.md +11 -11
  4. package/api-manifest.json +1510 -701
  5. package/dist/api/analysis/daylight.d.ts +5 -5
  6. package/dist/api/analysis/solar.d.ts +2 -2
  7. package/dist/api/core/camera/index.d.ts +29 -0
  8. package/dist/api/core/camera/index.d.ts.map +1 -1
  9. package/dist/api/core/geom/create/index.d.ts +7 -1
  10. package/dist/api/core/geom/create/index.d.ts.map +1 -1
  11. package/dist/api/core/geom/update/contour.d.ts +8 -2
  12. package/dist/api/core/geom/update/contour.d.ts.map +1 -1
  13. package/dist/api/core/storeys/index.d.ts +5 -2
  14. package/dist/api/core/storeys/index.d.ts.map +1 -1
  15. package/dist/api/core/zoom/index.d.ts +13 -0
  16. package/dist/api/core/zoom/index.d.ts.map +1 -1
  17. package/dist/api/design/bim.d.ts +299 -0
  18. package/dist/api/design/bim.d.ts.map +1 -0
  19. package/dist/api/design/boolean/index.d.ts +2 -0
  20. package/dist/api/design/boolean/index.d.ts.map +1 -1
  21. package/dist/api/design/catalog.d.ts +320 -0
  22. package/dist/api/design/catalog.d.ts.map +1 -0
  23. package/dist/api/design/create/bulk-items.d.ts +65 -25
  24. package/dist/api/design/create/bulk-items.d.ts.map +1 -1
  25. package/dist/api/design/create/index.d.ts +299 -100
  26. package/dist/api/design/create/index.d.ts.map +1 -1
  27. package/dist/api/design/create/opening-fields.d.ts +13 -12
  28. package/dist/api/design/create/opening-fields.d.ts.map +1 -1
  29. package/dist/api/design/delete/index.d.ts +1 -0
  30. package/dist/api/design/delete/index.d.ts.map +1 -1
  31. package/dist/api/design/doors/index.d.ts +18 -24
  32. package/dist/api/design/doors/index.d.ts.map +1 -1
  33. package/dist/api/design/family.d.ts +813 -35
  34. package/dist/api/design/family.d.ts.map +1 -1
  35. package/dist/api/design/index.d.ts +16 -0
  36. package/dist/api/design/index.d.ts.map +1 -1
  37. package/dist/api/design/networks.d.ts +1703 -0
  38. package/dist/api/design/networks.d.ts.map +1 -0
  39. package/dist/api/design/query/grids.d.ts +2 -2
  40. package/dist/api/design/query/index.d.ts +42 -32
  41. package/dist/api/design/query/index.d.ts.map +1 -1
  42. package/dist/api/design/selection/index.d.ts +10 -10
  43. package/dist/api/design/types/index.d.ts +40 -24
  44. package/dist/api/design/types/index.d.ts.map +1 -1
  45. package/dist/api/design/update/index.d.ts +111 -6
  46. package/dist/api/design/update/index.d.ts.map +1 -1
  47. package/dist/api/design/windows/index.d.ts +8 -8
  48. package/dist/api/design/windows/index.d.ts.map +1 -1
  49. package/dist/api/entity/buildableEnvelope.d.ts +84 -2
  50. package/dist/api/entity/buildableEnvelope.d.ts.map +1 -1
  51. package/dist/api/presentation/aiInspiration.d.ts +10 -10
  52. package/dist/api/presentation/annotate.d.ts +38 -22
  53. package/dist/api/presentation/annotate.d.ts.map +1 -1
  54. package/dist/api/presentation/drawingContract.d.ts +32 -0
  55. package/dist/api/presentation/drawingContract.d.ts.map +1 -0
  56. package/dist/api/presentation/drawings.d.ts +3523 -0
  57. package/dist/api/presentation/drawings.d.ts.map +1 -0
  58. package/dist/api/presentation/export.d.ts +23 -5
  59. package/dist/api/presentation/export.d.ts.map +1 -1
  60. package/dist/api/presentation/index.d.ts +41 -12
  61. package/dist/api/presentation/index.d.ts.map +1 -1
  62. package/dist/api/presentation/placedViews.d.ts +106 -6
  63. package/dist/api/presentation/placedViews.d.ts.map +1 -1
  64. package/dist/api/presentation/sections.d.ts +461 -0
  65. package/dist/api/presentation/sections.d.ts.map +1 -0
  66. package/dist/api/presentation/shapes.d.ts +2 -2
  67. package/dist/api/presentation/sheets.d.ts +175 -19
  68. package/dist/api/presentation/sheets.d.ts.map +1 -1
  69. package/dist/api/presentation/viewPresets.d.ts +222 -0
  70. package/dist/api/presentation/viewPresets.d.ts.map +1 -0
  71. package/dist/api/presentation/views.d.ts +141 -8
  72. package/dist/api/presentation/views.d.ts.map +1 -1
  73. package/dist/api/presentation/walkthroughs.d.ts +6 -6
  74. package/dist/errors/codes.d.ts +3 -1
  75. package/dist/errors/codes.d.ts.map +1 -1
  76. package/dist/index.cjs +3883 -2385
  77. package/dist/index.cjs.map +1 -1
  78. package/dist/index.js +3744 -2385
  79. package/dist/index.js.map +1 -1
  80. package/package.json +1 -1
  81. package/scripts/check-dist-fresh.mjs +22 -22
  82. package/scripts/generate-manifest.mjs +243 -238
  83. package/scripts/generate-manifest.test.mjs +303 -303
  84. package/src/api/analysis/daylight.ts +470 -470
  85. package/src/api/analysis/heatmaps.ts +683 -683
  86. package/src/api/analysis/illuminance.ts +155 -155
  87. package/src/api/analysis/index.ts +61 -61
  88. package/src/api/analysis/shadows.ts +183 -183
  89. package/src/api/analysis/solar.ts +237 -237
  90. package/src/api/analysis/sunlightHours.ts +211 -211
  91. package/src/api/analysis/sunpath.ts +83 -83
  92. package/src/api/analysis/weather.ts +179 -179
  93. package/src/api/core/buildings.ts +485 -485
  94. package/src/api/core/camera/index.ts +696 -667
  95. package/src/api/core/comment/index.ts +376 -376
  96. package/src/api/core/geom/create/index.ts +2139 -2133
  97. package/src/api/core/geom/delete/index.ts +84 -84
  98. package/src/api/core/geom/index.ts +35 -35
  99. package/src/api/core/geom/query/arc.ts +169 -169
  100. package/src/api/core/geom/query/brep.ts +621 -621
  101. package/src/api/core/geom/query/circle.ts +404 -404
  102. package/src/api/core/geom/query/contour.ts +540 -540
  103. package/src/api/core/geom/query/curve.ts +1102 -1102
  104. package/src/api/core/geom/query/edge.ts +130 -130
  105. package/src/api/core/geom/query/face.ts +508 -508
  106. package/src/api/core/geom/query/halfedge.ts +210 -210
  107. package/src/api/core/geom/query/index.ts +63 -63
  108. package/src/api/core/geom/query/profile.ts +473 -473
  109. package/src/api/core/geom/query/vertex.ts +205 -205
  110. package/src/api/core/geom/update/contour.ts +323 -317
  111. package/src/api/core/geom/update/curve.ts +209 -209
  112. package/src/api/core/geom/update/index.ts +29 -29
  113. package/src/api/core/geom/update/profile.ts +379 -379
  114. package/src/api/core/groups.ts +521 -521
  115. package/src/api/core/handles/index.ts +234 -234
  116. package/src/api/core/history/index.ts +84 -84
  117. package/src/api/core/index.ts +99 -99
  118. package/src/api/core/io/export/index.ts +126 -126
  119. package/src/api/core/io/import/index.ts +504 -504
  120. package/src/api/core/io/index.ts +42 -42
  121. package/src/api/core/io/job/index.ts +140 -140
  122. package/src/api/core/io/query/index.ts +71 -71
  123. package/src/api/core/io/terrain/index.ts +360 -360
  124. package/src/api/core/io/underlay/index.ts +705 -705
  125. package/src/api/core/layers.ts +540 -540
  126. package/src/api/core/math/index.ts +20 -20
  127. package/src/api/core/math/quat.ts +172 -172
  128. package/src/api/core/math/vec3.ts +179 -179
  129. package/src/api/core/mode/index.ts +108 -108
  130. package/src/api/core/project/index.ts +479 -479
  131. package/src/api/core/proposals/index.ts +570 -570
  132. package/src/api/core/storeys/index.ts +311 -308
  133. package/src/api/core/storeys/layers.ts +339 -339
  134. package/src/api/core/tags.ts +911 -911
  135. package/src/api/core/units/index.ts +164 -164
  136. package/src/api/core/user.ts +46 -46
  137. package/src/api/core/zoom/index.ts +64 -51
  138. package/src/api/design/bim.ts +210 -0
  139. package/src/api/design/boolean/index.ts +181 -179
  140. package/src/api/design/catalog.ts +203 -0
  141. package/src/api/design/create/bulk-items.ts +294 -254
  142. package/src/api/design/create/grids.ts +137 -137
  143. package/src/api/design/create/index.ts +2178 -1980
  144. package/src/api/design/create/opening-fields.ts +40 -37
  145. package/src/api/design/delete/index.ts +75 -74
  146. package/src/api/design/dimensions.ts +453 -453
  147. package/src/api/design/doors/index.ts +516 -500
  148. package/src/api/design/edit/index.ts +54 -54
  149. package/src/api/design/erase/index.ts +151 -151
  150. package/src/api/design/family.ts +1342 -704
  151. package/src/api/design/furniture/index.ts +319 -319
  152. package/src/api/design/grids.ts +237 -237
  153. package/src/api/design/index.ts +304 -274
  154. package/src/api/design/lock.ts +69 -69
  155. package/src/api/design/materials/index.ts +608 -608
  156. package/src/api/design/networks.ts +607 -0
  157. package/src/api/design/query/geometry/index.ts +319 -319
  158. package/src/api/design/query/grids.ts +197 -197
  159. package/src/api/design/query/index.ts +1236 -1226
  160. package/src/api/design/query/referenceLines.ts +52 -52
  161. package/src/api/design/query/spaces.ts +275 -275
  162. package/src/api/design/selection/index.ts +273 -273
  163. package/src/api/design/shared.ts +40 -40
  164. package/src/api/design/transform/index.ts +254 -254
  165. package/src/api/design/types/index.ts +163 -156
  166. package/src/api/design/update/index.ts +1096 -983
  167. package/src/api/design/visibility.ts +143 -143
  168. package/src/api/design/windows/index.ts +351 -333
  169. package/src/api/entity/buildableEnvelope.ts +397 -322
  170. package/src/api/entity/index.ts +30 -30
  171. package/src/api/entity/referenceLine.ts +235 -235
  172. package/src/api/entity/space.ts +612 -612
  173. package/src/api/entity/story.ts +517 -517
  174. package/src/api/index.ts +47 -47
  175. package/src/api/presentation/aiInspiration.ts +1116 -1116
  176. package/src/api/presentation/annotate.ts +417 -385
  177. package/src/api/presentation/camera.ts +289 -289
  178. package/src/api/presentation/diagrams.ts +194 -194
  179. package/src/api/presentation/drawingContract.ts +70 -0
  180. package/src/api/presentation/drawings.ts +1179 -0
  181. package/src/api/presentation/export.ts +134 -108
  182. package/src/api/presentation/import.ts +159 -159
  183. package/src/api/presentation/index.ts +160 -126
  184. package/src/api/presentation/placedViews.ts +1211 -1120
  185. package/src/api/presentation/sections.ts +420 -0
  186. package/src/api/presentation/shapes.ts +274 -274
  187. package/src/api/presentation/sheets.ts +746 -585
  188. package/src/api/presentation/slideshow.ts +134 -134
  189. package/src/api/presentation/tables.ts +84 -84
  190. package/src/api/presentation/viewPresets.ts +241 -0
  191. package/src/api/presentation/views.ts +742 -673
  192. package/src/api/presentation/walkthroughs.ts +1201 -1201
  193. package/src/api/program/adjacency.ts +164 -164
  194. package/src/api/program/areas.ts +408 -408
  195. package/src/api/program/classification.ts +138 -138
  196. package/src/api/program/cores.ts +83 -83
  197. package/src/api/program/departments.ts +517 -517
  198. package/src/api/program/index.ts +73 -73
  199. package/src/api/program/labels.ts +332 -332
  200. package/src/api/program/layout.ts +422 -422
  201. package/src/api/program/metadata.ts +364 -364
  202. package/src/api/program/metrics.ts +120 -120
  203. package/src/api/program/site.ts +748 -748
  204. package/src/api/program/spreadsheet.ts +2698 -2698
  205. package/src/api/workspace/index.ts +612 -612
  206. package/src/errors/codes.ts +143 -136
  207. package/src/errors/envelope.ts +75 -75
  208. package/src/errors/index.ts +21 -21
  209. package/src/errors/plugin-error.ts +134 -134
  210. package/src/handles.ts +297 -297
  211. package/src/host-utils.ts +67 -67
  212. package/src/index.ts +7 -7
  213. package/src/massParameters.ops.ts +246 -246
  214. package/src/massParameters.ts +427 -427
  215. package/src/types.ts +16 -16
  216. package/test/drawingContract.test.mjs +288 -0
  217. package/test/errors.test.mjs +185 -184
  218. package/test/massParameters.test.mjs +952 -952
  219. package/test/presentationViewSettings.test.mjs +85 -0
  220. package/tsconfig.json +22 -22
  221. package/tsup.config.ts +12 -12
@@ -1,289 +1,289 @@
1
- import * as z from "zod"
2
- import { PluginApiReturn } from "../../types"
3
- import { PluginPresentationImageFormat } from "./views"
4
-
5
- /**
6
- * The Present-mode canvas camera — the Present-mode twin of
7
- * {@linkcode PluginCameraApi} (`core.camera`).
8
- *
9
- * Present mode lays sheets out on an infinite 2D canvas; its camera is a pan
10
- * (`x`, `y`) and a `zoom`. A plugin can screenshot what that canvas currently
11
- * shows, read the camera, pan/zoom it, or frame all sheets or one shape.
12
- *
13
- * These are transient VIEW-STATE changes: not model edits, so they are not
14
- * write-gated and not undoable. Every method requires **Present mode to be
15
- * open** (the documentation editor) and throws `PRECONDITION_FAILED` when it is
16
- * closed. `capture` is the Present-mode counterpart of
17
- * {@linkcode PluginPresentationViewsApi.capture}, which shoots the Design
18
- * (3D) canvas; for whole sheets at their own size use
19
- * {@linkcode PluginPresentationApi.export}.
20
- *
21
- * Coordinates are Present canvas page units (pixels at 100% zoom), the same
22
- * space `sheets`, `placedViews` and `shapes` report positions in. `zoom` is a
23
- * factor: `1` = 100%, `0.5` = zoomed out to half size.
24
- *
25
- * Accessed via `snaptrude.presentation.camera`.
26
- */
27
- export abstract class PluginPresentationCameraApi {
28
- constructor() {}
29
-
30
- /**
31
- * Screenshot what the Present canvas currently shows.
32
- *
33
- * Captures exactly the visible area — the canvas as clipped by the window,
34
- * minus the strip under the floating left sidebar — at the current pan and
35
- * zoom, rendered
36
- * through the same pipeline as the Present-mode Export dialog, so sheets,
37
- * placed views, text, annotations and imported images look as they do on
38
- * screen. Selection handles, cursors and the UI itself are not part of the
39
- * image. Nothing on screen still yields an image (the export backdrop).
40
- * Export-pipeline details, as in the Export dialog: sheet frames themselves
41
- * are not drawn (no paper, margin guides or name label — editor chrome), the
42
- * backdrop is tldraw's near-white export backdrop rather than the on-screen
43
- * canvas grey, and with exactly one sheet in view it is white. Only the left
44
- * sidebar is subtracted from the view; floating right-hand panels are not.
45
- *
46
- * @param options - All optional: `format` (`"png"` default, or `"jpeg"`),
47
- * `pixelRatio` (output pixels per screen pixel, `1`–`4`, default `1`;
48
- * `2` for a retina-sharp image).
49
- * @returns A {@linkcode PluginPresentationCameraCaptureResult}: the base64
50
- * data URL and its pixel size.
51
- * @throws If Present mode is not open.
52
- *
53
- * @examplePrompt Take a screenshot of the Present canvas
54
- * @examplePrompt Capture what I am looking at in Present mode
55
- * @examplePrompt Screenshot the presentation canvas as a JPEG
56
- * @examplePrompt Grab a high-res image of the current sheet view
57
- *
58
- * # Example
59
- * ```ts
60
- * const { image, width, height } = await snaptrude.presentation.camera.capture({
61
- * format: "png",
62
- * pixelRatio: 2,
63
- * })
64
- * ```
65
- */
66
- public abstract capture(options?: {
67
- format?: PluginPresentationImageFormat
68
- pixelRatio?: number
69
- }): PluginApiReturn<PluginPresentationCameraCaptureResult>
70
-
71
- /**
72
- * Read the Present camera: pan, zoom, the visible page-space rectangle and
73
- * the sheet under the centre of the view.
74
- *
75
- * @returns The current {@linkcode PluginPresentationCameraState}.
76
- * @throws If Present mode is not open.
77
- *
78
- * @examplePrompt Where is the Present canvas camera?
79
- * @examplePrompt What zoom level is Present mode at?
80
- * @examplePrompt Which sheet is on screen right now?
81
- * @examplePrompt Read the visible area of the presentation canvas
82
- *
83
- * # Example
84
- * ```ts
85
- * const { zoom, sheetId } = await snaptrude.presentation.camera.get()
86
- * ```
87
- */
88
- public abstract get(): PluginApiReturn<PluginPresentationCameraState>
89
-
90
- /**
91
- * Pan and/or zoom the Present canvas. Fields left out keep their current
92
- * value, so `{ zoom: 2 }` changes only the zoom (the page point at the
93
- * viewport's top-left corner stays put) and `{ x, y }` pans at the current
94
- * zoom. `zoom` is clamped to the editor's range (1% to 1000%); the requested
95
- * `x`/`y` are always honoured. Immediate (no animation). View-state only —
96
- * not undoable.
97
- *
98
- * `x`/`y` are the camera offset in page units: the page point that lands at
99
- * the viewport's top-left corner is `(-x, -y)`. Read them back from
100
- * {@linkcode PluginPresentationCameraApi.get} to reproduce a framing later.
101
- *
102
- * @param camera - Any of `x`, `y`, `zoom` ({@linkcode PluginPresentationCameraSetArgs}); at least one.
103
- * @returns The resulting {@linkcode PluginPresentationCameraState}.
104
- * @throws If Present mode is not open, or another Present-mode control has
105
- * locked the camera (an open style dropdown, AI Inspiration's layout mode).
106
- *
107
- * @examplePrompt Zoom the Present canvas to 50%
108
- * @examplePrompt Pan the presentation canvas to the right
109
- * @examplePrompt Restore the Present camera I saved earlier
110
- * @examplePrompt Set the Present zoom to 200% without moving
111
- *
112
- * # Example
113
- * ```ts
114
- * const saved = await snaptrude.presentation.camera.get()
115
- * await snaptrude.presentation.camera.set({ zoom: 0.5 })
116
- * // …later, restore the exact framing
117
- * await snaptrude.presentation.camera.set({ x: saved.x, y: saved.y, zoom: saved.zoom })
118
- * ```
119
- */
120
- public abstract set(camera: {
121
- x?: number
122
- y?: number
123
- zoom?: number
124
- }): PluginApiReturn<PluginPresentationCameraState>
125
-
126
- /**
127
- * Frame everything on the Present canvas — every sheet and loose shape — the
128
- * Present-mode "zoom to fit". View-state only — not undoable.
129
- *
130
- * @returns The resulting {@linkcode PluginPresentationCameraState}.
131
- * @throws If Present mode is not open, or the camera is locked.
132
- *
133
- * @examplePrompt Zoom out to see all the sheets
134
- * @examplePrompt Fit the whole presentation in the Present view
135
- * @examplePrompt Zoom to fit in Present mode
136
- *
137
- * # Example
138
- * ```ts
139
- * await snaptrude.presentation.camera.zoomToFit()
140
- * ```
141
- */
142
- public abstract zoomToFit(): PluginApiReturn<PluginPresentationCameraState>
143
-
144
- /**
145
- * Frame one shape on the Present canvas: a sheet, a placed view, a keyed
146
- * shape or an annotation — any id the other `presentation` namespaces hand
147
- * out. Pair with {@linkcode PluginPresentationCameraApi.capture} to
148
- * screenshot a single sheet or placed view as it appears on screen.
149
- * Immediate, unlike `sheets.setActive`, which animates its move over half a
150
- * second. View-state only — not undoable.
151
- *
152
- * @param shapeId - The id of the sheet or shape to frame.
153
- * @returns The resulting {@linkcode PluginPresentationCameraState}.
154
- * @throws If Present mode is not open, the id is unknown, or the camera is locked.
155
- *
156
- * @examplePrompt Zoom in on sheet 2 in Present mode
157
- * @examplePrompt Frame this placed view on the Present canvas
158
- * @examplePrompt Go to the cover sheet and screenshot it
159
- * @examplePrompt Centre the presentation view on that table
160
- *
161
- * # Example
162
- * ```ts
163
- * const { sheets } = await snaptrude.presentation.sheets.list()
164
- * await snaptrude.presentation.camera.zoomTo(sheets[1].id)
165
- * const { image } = await snaptrude.presentation.camera.capture()
166
- * ```
167
- */
168
- public abstract zoomTo(
169
- shapeId: string,
170
- ): PluginApiReturn<PluginPresentationCameraState>
171
- }
172
-
173
- /**
174
- * The visible area of the Present canvas in page units — the canvas as
175
- * clipped by the window, minus the strip under the floating left sidebar.
176
- *
177
- * | Property | Type | Description |
178
- * |---|---|---|
179
- * | `x` | `number` | Left edge (page units) |
180
- * | `y` | `number` | Top edge (page units) |
181
- * | `width` | `number` | Width (page units) |
182
- * | `height` | `number` | Height (page units) |
183
- */
184
- export const PluginPresentationCameraViewport = z.object({
185
- x: z.number().finite(),
186
- y: z.number().finite(),
187
- width: z.number().finite().nonnegative(),
188
- height: z.number().finite().nonnegative(),
189
- })
190
- export type PluginPresentationCameraViewport = z.infer<
191
- typeof PluginPresentationCameraViewport
192
- >
193
-
194
- /**
195
- * The Present canvas camera as returned by every
196
- * {@linkcode PluginPresentationCameraApi} method.
197
- *
198
- * | Property | Type | Description |
199
- * |---|---|---|
200
- * | `x` | `number` | Camera pan offset (page units): the page point at the tldraw viewport's top-left corner (under the sidebar) is `(-x, -y)` |
201
- * | `y` | `number` | Camera pan offset (page units) |
202
- * | `zoom` | `number` | Zoom factor, `1` = 100% |
203
- * | `viewport` | {@linkcode PluginPresentationCameraViewport} | The visible page-space rectangle |
204
- * | `sheetId` | `string \| null` | The sheet under the centre of the view, or `null` when none |
205
- */
206
- export const PluginPresentationCameraState = z.object({
207
- x: z.number().finite(),
208
- y: z.number().finite(),
209
- zoom: z.number().finite().positive(),
210
- viewport: PluginPresentationCameraViewport,
211
- sheetId: z.string().nullable(),
212
- })
213
- export type PluginPresentationCameraState = z.infer<
214
- typeof PluginPresentationCameraState
215
- >
216
-
217
- /**
218
- * Arguments for {@linkcode PluginPresentationCameraApi.set}. All optional, at
219
- * least one required; omitted fields keep their current value.
220
- *
221
- * | Property | Type | Description |
222
- * |---|---|---|
223
- * | `x` | `number \| undefined` | Camera pan offset (page units) |
224
- * | `y` | `number \| undefined` | Camera pan offset (page units) |
225
- * | `zoom` | `number \| undefined` | Zoom factor, `> 0` (`1` = 100%); clamped to the editor's range (`0.01`–`10`), `x`/`y` still honoured |
226
- */
227
- export const PluginPresentationCameraSetArgs = z
228
- .object({
229
- x: z.number().finite().optional(),
230
- y: z.number().finite().optional(),
231
- zoom: z.number().finite().positive().optional(),
232
- })
233
- .refine(
234
- (c) => c.x !== undefined || c.y !== undefined || c.zoom !== undefined,
235
- {
236
- message: "Pass at least one of x, y, zoom",
237
- },
238
- )
239
- export type PluginPresentationCameraSetArgs = z.infer<
240
- typeof PluginPresentationCameraSetArgs
241
- >
242
-
243
- /**
244
- * Arguments for {@linkcode PluginPresentationCameraApi.zoomTo}.
245
- *
246
- * | Property | Type | Description |
247
- * |---|---|---|
248
- * | `shapeId` | `string` | The sheet or shape to frame |
249
- */
250
- export const PluginPresentationCameraZoomToArgs = z.object({
251
- shapeId: z.string().min(1),
252
- })
253
- export type PluginPresentationCameraZoomToArgs = z.infer<
254
- typeof PluginPresentationCameraZoomToArgs
255
- >
256
-
257
- /**
258
- * Arguments for {@linkcode PluginPresentationCameraApi.capture}. All optional.
259
- *
260
- * | Property | Type | Description |
261
- * |---|---|---|
262
- * | `format` | `"png" \| "jpeg" \| undefined` | Output image format (default `"png"`) |
263
- * | `pixelRatio` | `number \| undefined` | Output pixels per screen pixel, `1`–`4` (default `1`) |
264
- */
265
- export const PluginPresentationCameraCaptureArgs = z.object({
266
- format: PluginPresentationImageFormat.optional(),
267
- pixelRatio: z.number().finite().min(1).max(4).optional(),
268
- })
269
- export type PluginPresentationCameraCaptureArgs = z.infer<
270
- typeof PluginPresentationCameraCaptureArgs
271
- >
272
-
273
- /**
274
- * Result of {@linkcode PluginPresentationCameraApi.capture}.
275
- *
276
- * | Property | Type | Description |
277
- * |---|---|---|
278
- * | `image` | `string` | The screenshot as a base64 data URL (`data:image/png;base64,…`) |
279
- * | `width` | `number` | Image width in pixels |
280
- * | `height` | `number` | Image height in pixels |
281
- */
282
- export const PluginPresentationCameraCaptureResult = z.object({
283
- image: z.string(),
284
- width: z.number().int().nonnegative(),
285
- height: z.number().int().nonnegative(),
286
- })
287
- export type PluginPresentationCameraCaptureResult = z.infer<
288
- typeof PluginPresentationCameraCaptureResult
289
- >
1
+ import * as z from "zod"
2
+ import { PluginApiReturn } from "../../types"
3
+ import { PluginPresentationImageFormat } from "./views"
4
+
5
+ /**
6
+ * The Present-mode canvas camera — the Present-mode twin of
7
+ * {@linkcode PluginCameraApi} (`core.camera`).
8
+ *
9
+ * Present mode lays sheets out on an infinite 2D canvas; its camera is a pan
10
+ * (`x`, `y`) and a `zoom`. A plugin can screenshot what that canvas currently
11
+ * shows, read the camera, pan/zoom it, or frame all sheets or one shape.
12
+ *
13
+ * These are transient VIEW-STATE changes: not model edits, so they are not
14
+ * write-gated and not undoable. Every method requires **Present mode to be
15
+ * open** (the documentation editor) and throws `PRECONDITION_FAILED` when it is
16
+ * closed. `capture` is the Present-mode counterpart of
17
+ * {@linkcode PluginPresentationViewsApi.capture}, which shoots the Design
18
+ * (3D) canvas; for whole sheets at their own size use
19
+ * {@linkcode PluginPresentationApi.export}.
20
+ *
21
+ * Coordinates are Present canvas page units (pixels at 100% zoom), the same
22
+ * space `sheets`, `placedViews` and `shapes` report positions in. `zoom` is a
23
+ * factor: `1` = 100%, `0.5` = zoomed out to half size.
24
+ *
25
+ * Accessed via `snaptrude.presentation.camera`.
26
+ */
27
+ export abstract class PluginPresentationCameraApi {
28
+ constructor() {}
29
+
30
+ /**
31
+ * Screenshot what the Present canvas currently shows.
32
+ *
33
+ * Captures exactly the visible area — the canvas as clipped by the window,
34
+ * minus the strip under the floating left sidebar — at the current pan and
35
+ * zoom, rendered
36
+ * through the same pipeline as the Present-mode Export dialog, so sheets,
37
+ * placed views, text, annotations and imported images look as they do on
38
+ * screen. Selection handles, cursors and the UI itself are not part of the
39
+ * image. Nothing on screen still yields an image (the export backdrop).
40
+ * Export-pipeline details, as in the Export dialog: sheet frames themselves
41
+ * are not drawn (no paper, margin guides or name label — editor chrome), the
42
+ * backdrop is tldraw's near-white export backdrop rather than the on-screen
43
+ * canvas grey, and with exactly one sheet in view it is white. Only the left
44
+ * sidebar is subtracted from the view; floating right-hand panels are not.
45
+ *
46
+ * @param options - All optional: `format` (`"png"` default, or `"jpeg"`),
47
+ * `pixelRatio` (output pixels per screen pixel, `1`–`4`, default `1`;
48
+ * `2` for a retina-sharp image).
49
+ * @returns A {@linkcode PluginPresentationCameraCaptureResult}: the base64
50
+ * data URL and its pixel size.
51
+ * @throws If Present mode is not open.
52
+ *
53
+ * @examplePrompt Take a screenshot of the Present canvas
54
+ * @examplePrompt Capture what I am looking at in Present mode
55
+ * @examplePrompt Screenshot the presentation canvas as a JPEG
56
+ * @examplePrompt Grab a high-res image of the current sheet view
57
+ *
58
+ * # Example
59
+ * ```ts
60
+ * const { image, width, height } = await snaptrude.presentation.camera.capture({
61
+ * format: "png",
62
+ * pixelRatio: 2,
63
+ * })
64
+ * ```
65
+ */
66
+ public abstract capture(options?: {
67
+ format?: PluginPresentationImageFormat
68
+ pixelRatio?: number
69
+ }): PluginApiReturn<PluginPresentationCameraCaptureResult>
70
+
71
+ /**
72
+ * Read the Present camera: pan, zoom, the visible page-space rectangle and
73
+ * the sheet under the centre of the view.
74
+ *
75
+ * @returns The current {@linkcode PluginPresentationCameraState}.
76
+ * @throws If Present mode is not open.
77
+ *
78
+ * @examplePrompt Where is the Present canvas camera?
79
+ * @examplePrompt What zoom level is Present mode at?
80
+ * @examplePrompt Which sheet is on screen right now?
81
+ * @examplePrompt Read the visible area of the presentation canvas
82
+ *
83
+ * # Example
84
+ * ```ts
85
+ * const { zoom, sheetId } = await snaptrude.presentation.camera.get()
86
+ * ```
87
+ */
88
+ public abstract get(): PluginApiReturn<PluginPresentationCameraState>
89
+
90
+ /**
91
+ * Pan and/or zoom the Present canvas. Fields left out keep their current
92
+ * value, so `{ zoom: 2 }` changes only the zoom (the page point at the
93
+ * viewport's top-left corner stays put) and `{ x, y }` pans at the current
94
+ * zoom. `zoom` is clamped to the editor's range (1% to 1000%); the requested
95
+ * `x`/`y` are always honoured. Immediate (no animation). View-state only —
96
+ * not undoable.
97
+ *
98
+ * `x`/`y` are the camera offset in page units: the page point that lands at
99
+ * the viewport's top-left corner is `(-x, -y)`. Read them back from
100
+ * {@linkcode PluginPresentationCameraApi.get} to reproduce a framing later.
101
+ *
102
+ * @param camera - Any of `x`, `y`, `zoom` ({@linkcode PluginPresentationCameraSetArgs}); at least one.
103
+ * @returns The resulting {@linkcode PluginPresentationCameraState}.
104
+ * @throws If Present mode is not open, or another Present-mode control has
105
+ * locked the camera (an open style dropdown, AI Inspiration's layout mode).
106
+ *
107
+ * @examplePrompt Zoom the Present canvas to 50%
108
+ * @examplePrompt Pan the presentation canvas to the right
109
+ * @examplePrompt Restore the Present camera I saved earlier
110
+ * @examplePrompt Set the Present zoom to 200% without moving
111
+ *
112
+ * # Example
113
+ * ```ts
114
+ * const saved = await snaptrude.presentation.camera.get()
115
+ * await snaptrude.presentation.camera.set({ zoom: 0.5 })
116
+ * // …later, restore the exact framing
117
+ * await snaptrude.presentation.camera.set({ x: saved.x, y: saved.y, zoom: saved.zoom })
118
+ * ```
119
+ */
120
+ public abstract set(camera: {
121
+ x?: number
122
+ y?: number
123
+ zoom?: number
124
+ }): PluginApiReturn<PluginPresentationCameraState>
125
+
126
+ /**
127
+ * Frame everything on the Present canvas — every sheet and loose shape — the
128
+ * Present-mode "zoom to fit". View-state only — not undoable.
129
+ *
130
+ * @returns The resulting {@linkcode PluginPresentationCameraState}.
131
+ * @throws If Present mode is not open, or the camera is locked.
132
+ *
133
+ * @examplePrompt Zoom out to see all the sheets
134
+ * @examplePrompt Fit the whole presentation in the Present view
135
+ * @examplePrompt Zoom to fit in Present mode
136
+ *
137
+ * # Example
138
+ * ```ts
139
+ * await snaptrude.presentation.camera.zoomToFit()
140
+ * ```
141
+ */
142
+ public abstract zoomToFit(): PluginApiReturn<PluginPresentationCameraState>
143
+
144
+ /**
145
+ * Frame one shape on the Present canvas: a sheet, a placed view, a keyed
146
+ * shape or an annotation — any id the other `presentation` namespaces hand
147
+ * out. Pair with {@linkcode PluginPresentationCameraApi.capture} to
148
+ * screenshot a single sheet or placed view as it appears on screen.
149
+ * Immediate, unlike `sheets.setActive`, which animates its move over half a
150
+ * second. View-state only — not undoable.
151
+ *
152
+ * @param shapeId - The id of the sheet or shape to frame.
153
+ * @returns The resulting {@linkcode PluginPresentationCameraState}.
154
+ * @throws If Present mode is not open, the id is unknown, or the camera is locked.
155
+ *
156
+ * @examplePrompt Zoom in on sheet 2 in Present mode
157
+ * @examplePrompt Frame this placed view on the Present canvas
158
+ * @examplePrompt Go to the cover sheet and screenshot it
159
+ * @examplePrompt Centre the presentation view on that table
160
+ *
161
+ * # Example
162
+ * ```ts
163
+ * const { sheets } = await snaptrude.presentation.sheets.list()
164
+ * await snaptrude.presentation.camera.zoomTo(sheets[1].id)
165
+ * const { image } = await snaptrude.presentation.camera.capture()
166
+ * ```
167
+ */
168
+ public abstract zoomTo(
169
+ shapeId: string,
170
+ ): PluginApiReturn<PluginPresentationCameraState>
171
+ }
172
+
173
+ /**
174
+ * The visible area of the Present canvas in page units — the canvas as
175
+ * clipped by the window, minus the strip under the floating left sidebar.
176
+ *
177
+ * | Property | Type | Description |
178
+ * |---|---|---|
179
+ * | `x` | `number` | Left edge (page units) |
180
+ * | `y` | `number` | Top edge (page units) |
181
+ * | `width` | `number` | Width (page units) |
182
+ * | `height` | `number` | Height (page units) |
183
+ */
184
+ export const PluginPresentationCameraViewport = z.object({
185
+ x: z.number().finite(),
186
+ y: z.number().finite(),
187
+ width: z.number().finite().nonnegative(),
188
+ height: z.number().finite().nonnegative(),
189
+ })
190
+ export type PluginPresentationCameraViewport = z.infer<
191
+ typeof PluginPresentationCameraViewport
192
+ >
193
+
194
+ /**
195
+ * The Present canvas camera as returned by every
196
+ * {@linkcode PluginPresentationCameraApi} method.
197
+ *
198
+ * | Property | Type | Description |
199
+ * |---|---|---|
200
+ * | `x` | `number` | Camera pan offset (page units): the page point at the tldraw viewport's top-left corner (under the sidebar) is `(-x, -y)` |
201
+ * | `y` | `number` | Camera pan offset (page units) |
202
+ * | `zoom` | `number` | Zoom factor, `1` = 100% |
203
+ * | `viewport` | {@linkcode PluginPresentationCameraViewport} | The visible page-space rectangle |
204
+ * | `sheetId` | `string \| null` | The sheet under the centre of the view, or `null` when none |
205
+ */
206
+ export const PluginPresentationCameraState = z.object({
207
+ x: z.number().finite(),
208
+ y: z.number().finite(),
209
+ zoom: z.number().finite().positive(),
210
+ viewport: PluginPresentationCameraViewport,
211
+ sheetId: z.string().nullable(),
212
+ })
213
+ export type PluginPresentationCameraState = z.infer<
214
+ typeof PluginPresentationCameraState
215
+ >
216
+
217
+ /**
218
+ * Arguments for {@linkcode PluginPresentationCameraApi.set}. All optional, at
219
+ * least one required; omitted fields keep their current value.
220
+ *
221
+ * | Property | Type | Description |
222
+ * |---|---|---|
223
+ * | `x` | `number \| undefined` | Camera pan offset (page units) |
224
+ * | `y` | `number \| undefined` | Camera pan offset (page units) |
225
+ * | `zoom` | `number \| undefined` | Zoom factor, `> 0` (`1` = 100%); clamped to the editor's range (`0.01`–`10`), `x`/`y` still honoured |
226
+ */
227
+ export const PluginPresentationCameraSetArgs = z
228
+ .object({
229
+ x: z.number().finite().optional(),
230
+ y: z.number().finite().optional(),
231
+ zoom: z.number().finite().positive().optional(),
232
+ })
233
+ .refine(
234
+ (c) => c.x !== undefined || c.y !== undefined || c.zoom !== undefined,
235
+ {
236
+ message: "Pass at least one of x, y, zoom",
237
+ },
238
+ )
239
+ export type PluginPresentationCameraSetArgs = z.infer<
240
+ typeof PluginPresentationCameraSetArgs
241
+ >
242
+
243
+ /**
244
+ * Arguments for {@linkcode PluginPresentationCameraApi.zoomTo}.
245
+ *
246
+ * | Property | Type | Description |
247
+ * |---|---|---|
248
+ * | `shapeId` | `string` | The sheet or shape to frame |
249
+ */
250
+ export const PluginPresentationCameraZoomToArgs = z.object({
251
+ shapeId: z.string().min(1),
252
+ })
253
+ export type PluginPresentationCameraZoomToArgs = z.infer<
254
+ typeof PluginPresentationCameraZoomToArgs
255
+ >
256
+
257
+ /**
258
+ * Arguments for {@linkcode PluginPresentationCameraApi.capture}. All optional.
259
+ *
260
+ * | Property | Type | Description |
261
+ * |---|---|---|
262
+ * | `format` | `"png" \| "jpeg" \| undefined` | Output image format (default `"png"`) |
263
+ * | `pixelRatio` | `number \| undefined` | Output pixels per screen pixel, `1`–`4` (default `1`) |
264
+ */
265
+ export const PluginPresentationCameraCaptureArgs = z.object({
266
+ format: PluginPresentationImageFormat.optional(),
267
+ pixelRatio: z.number().finite().min(1).max(4).optional(),
268
+ })
269
+ export type PluginPresentationCameraCaptureArgs = z.infer<
270
+ typeof PluginPresentationCameraCaptureArgs
271
+ >
272
+
273
+ /**
274
+ * Result of {@linkcode PluginPresentationCameraApi.capture}.
275
+ *
276
+ * | Property | Type | Description |
277
+ * |---|---|---|
278
+ * | `image` | `string` | The screenshot as a base64 data URL (`data:image/png;base64,…`) |
279
+ * | `width` | `number` | Image width in pixels |
280
+ * | `height` | `number` | Image height in pixels |
281
+ */
282
+ export const PluginPresentationCameraCaptureResult = z.object({
283
+ image: z.string(),
284
+ width: z.number().int().nonnegative(),
285
+ height: z.number().int().nonnegative(),
286
+ })
287
+ export type PluginPresentationCameraCaptureResult = z.infer<
288
+ typeof PluginPresentationCameraCaptureResult
289
+ >