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