@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.
- package/AGENTS.md +231 -231
- package/CHANGELOG.md +408 -402
- package/CLAUDE.md +11 -11
- package/api-manifest.json +1510 -701
- package/dist/api/analysis/daylight.d.ts +5 -5
- package/dist/api/analysis/solar.d.ts +2 -2
- package/dist/api/core/camera/index.d.ts +29 -0
- package/dist/api/core/camera/index.d.ts.map +1 -1
- package/dist/api/core/geom/create/index.d.ts +7 -1
- package/dist/api/core/geom/create/index.d.ts.map +1 -1
- package/dist/api/core/geom/update/contour.d.ts +8 -2
- package/dist/api/core/geom/update/contour.d.ts.map +1 -1
- package/dist/api/core/storeys/index.d.ts +5 -2
- package/dist/api/core/storeys/index.d.ts.map +1 -1
- package/dist/api/core/zoom/index.d.ts +13 -0
- package/dist/api/core/zoom/index.d.ts.map +1 -1
- package/dist/api/design/bim.d.ts +299 -0
- package/dist/api/design/bim.d.ts.map +1 -0
- package/dist/api/design/boolean/index.d.ts +2 -0
- package/dist/api/design/boolean/index.d.ts.map +1 -1
- package/dist/api/design/catalog.d.ts +320 -0
- package/dist/api/design/catalog.d.ts.map +1 -0
- package/dist/api/design/create/bulk-items.d.ts +65 -25
- package/dist/api/design/create/bulk-items.d.ts.map +1 -1
- package/dist/api/design/create/index.d.ts +299 -100
- package/dist/api/design/create/index.d.ts.map +1 -1
- package/dist/api/design/create/opening-fields.d.ts +13 -12
- package/dist/api/design/create/opening-fields.d.ts.map +1 -1
- package/dist/api/design/delete/index.d.ts +1 -0
- package/dist/api/design/delete/index.d.ts.map +1 -1
- package/dist/api/design/doors/index.d.ts +18 -24
- package/dist/api/design/doors/index.d.ts.map +1 -1
- package/dist/api/design/family.d.ts +813 -35
- package/dist/api/design/family.d.ts.map +1 -1
- package/dist/api/design/index.d.ts +16 -0
- package/dist/api/design/index.d.ts.map +1 -1
- package/dist/api/design/networks.d.ts +1703 -0
- package/dist/api/design/networks.d.ts.map +1 -0
- package/dist/api/design/query/grids.d.ts +2 -2
- package/dist/api/design/query/index.d.ts +42 -32
- package/dist/api/design/query/index.d.ts.map +1 -1
- package/dist/api/design/selection/index.d.ts +10 -10
- package/dist/api/design/types/index.d.ts +40 -24
- package/dist/api/design/types/index.d.ts.map +1 -1
- package/dist/api/design/update/index.d.ts +111 -6
- package/dist/api/design/update/index.d.ts.map +1 -1
- package/dist/api/design/windows/index.d.ts +8 -8
- package/dist/api/design/windows/index.d.ts.map +1 -1
- package/dist/api/entity/buildableEnvelope.d.ts +84 -2
- package/dist/api/entity/buildableEnvelope.d.ts.map +1 -1
- package/dist/api/presentation/aiInspiration.d.ts +10 -10
- package/dist/api/presentation/annotate.d.ts +38 -22
- package/dist/api/presentation/annotate.d.ts.map +1 -1
- package/dist/api/presentation/drawingContract.d.ts +32 -0
- package/dist/api/presentation/drawingContract.d.ts.map +1 -0
- package/dist/api/presentation/drawings.d.ts +3523 -0
- package/dist/api/presentation/drawings.d.ts.map +1 -0
- package/dist/api/presentation/export.d.ts +23 -5
- package/dist/api/presentation/export.d.ts.map +1 -1
- package/dist/api/presentation/index.d.ts +41 -12
- package/dist/api/presentation/index.d.ts.map +1 -1
- package/dist/api/presentation/placedViews.d.ts +106 -6
- package/dist/api/presentation/placedViews.d.ts.map +1 -1
- package/dist/api/presentation/sections.d.ts +461 -0
- package/dist/api/presentation/sections.d.ts.map +1 -0
- package/dist/api/presentation/shapes.d.ts +2 -2
- package/dist/api/presentation/sheets.d.ts +175 -19
- package/dist/api/presentation/sheets.d.ts.map +1 -1
- package/dist/api/presentation/viewPresets.d.ts +222 -0
- package/dist/api/presentation/viewPresets.d.ts.map +1 -0
- package/dist/api/presentation/views.d.ts +141 -8
- package/dist/api/presentation/views.d.ts.map +1 -1
- package/dist/api/presentation/walkthroughs.d.ts +6 -6
- package/dist/errors/codes.d.ts +3 -1
- package/dist/errors/codes.d.ts.map +1 -1
- package/dist/index.cjs +3883 -2385
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +3744 -2385
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
- package/scripts/check-dist-fresh.mjs +22 -22
- package/scripts/generate-manifest.mjs +243 -238
- package/scripts/generate-manifest.test.mjs +303 -303
- package/src/api/analysis/daylight.ts +470 -470
- package/src/api/analysis/heatmaps.ts +683 -683
- package/src/api/analysis/illuminance.ts +155 -155
- package/src/api/analysis/index.ts +61 -61
- package/src/api/analysis/shadows.ts +183 -183
- package/src/api/analysis/solar.ts +237 -237
- package/src/api/analysis/sunlightHours.ts +211 -211
- package/src/api/analysis/sunpath.ts +83 -83
- package/src/api/analysis/weather.ts +179 -179
- package/src/api/core/buildings.ts +485 -485
- package/src/api/core/camera/index.ts +696 -667
- package/src/api/core/comment/index.ts +376 -376
- package/src/api/core/geom/create/index.ts +2139 -2133
- package/src/api/core/geom/delete/index.ts +84 -84
- package/src/api/core/geom/index.ts +35 -35
- package/src/api/core/geom/query/arc.ts +169 -169
- package/src/api/core/geom/query/brep.ts +621 -621
- package/src/api/core/geom/query/circle.ts +404 -404
- package/src/api/core/geom/query/contour.ts +540 -540
- package/src/api/core/geom/query/curve.ts +1102 -1102
- package/src/api/core/geom/query/edge.ts +130 -130
- package/src/api/core/geom/query/face.ts +508 -508
- package/src/api/core/geom/query/halfedge.ts +210 -210
- package/src/api/core/geom/query/index.ts +63 -63
- package/src/api/core/geom/query/profile.ts +473 -473
- package/src/api/core/geom/query/vertex.ts +205 -205
- package/src/api/core/geom/update/contour.ts +323 -317
- package/src/api/core/geom/update/curve.ts +209 -209
- package/src/api/core/geom/update/index.ts +29 -29
- package/src/api/core/geom/update/profile.ts +379 -379
- package/src/api/core/groups.ts +521 -521
- package/src/api/core/handles/index.ts +234 -234
- package/src/api/core/history/index.ts +84 -84
- package/src/api/core/index.ts +99 -99
- package/src/api/core/io/export/index.ts +126 -126
- package/src/api/core/io/import/index.ts +504 -504
- package/src/api/core/io/index.ts +42 -42
- package/src/api/core/io/job/index.ts +140 -140
- package/src/api/core/io/query/index.ts +71 -71
- package/src/api/core/io/terrain/index.ts +360 -360
- package/src/api/core/io/underlay/index.ts +705 -705
- package/src/api/core/layers.ts +540 -540
- package/src/api/core/math/index.ts +20 -20
- package/src/api/core/math/quat.ts +172 -172
- package/src/api/core/math/vec3.ts +179 -179
- package/src/api/core/mode/index.ts +108 -108
- package/src/api/core/project/index.ts +479 -479
- package/src/api/core/proposals/index.ts +570 -570
- package/src/api/core/storeys/index.ts +311 -308
- package/src/api/core/storeys/layers.ts +339 -339
- package/src/api/core/tags.ts +911 -911
- package/src/api/core/units/index.ts +164 -164
- package/src/api/core/user.ts +46 -46
- package/src/api/core/zoom/index.ts +64 -51
- package/src/api/design/bim.ts +210 -0
- package/src/api/design/boolean/index.ts +181 -179
- package/src/api/design/catalog.ts +203 -0
- package/src/api/design/create/bulk-items.ts +294 -254
- package/src/api/design/create/grids.ts +137 -137
- package/src/api/design/create/index.ts +2178 -1980
- package/src/api/design/create/opening-fields.ts +40 -37
- package/src/api/design/delete/index.ts +75 -74
- package/src/api/design/dimensions.ts +453 -453
- package/src/api/design/doors/index.ts +516 -500
- package/src/api/design/edit/index.ts +54 -54
- package/src/api/design/erase/index.ts +151 -151
- package/src/api/design/family.ts +1342 -704
- package/src/api/design/furniture/index.ts +319 -319
- package/src/api/design/grids.ts +237 -237
- package/src/api/design/index.ts +304 -274
- package/src/api/design/lock.ts +69 -69
- package/src/api/design/materials/index.ts +608 -608
- package/src/api/design/networks.ts +607 -0
- package/src/api/design/query/geometry/index.ts +319 -319
- package/src/api/design/query/grids.ts +197 -197
- package/src/api/design/query/index.ts +1236 -1226
- package/src/api/design/query/referenceLines.ts +52 -52
- package/src/api/design/query/spaces.ts +275 -275
- package/src/api/design/selection/index.ts +273 -273
- package/src/api/design/shared.ts +40 -40
- package/src/api/design/transform/index.ts +254 -254
- package/src/api/design/types/index.ts +163 -156
- package/src/api/design/update/index.ts +1096 -983
- package/src/api/design/visibility.ts +143 -143
- package/src/api/design/windows/index.ts +351 -333
- package/src/api/entity/buildableEnvelope.ts +397 -322
- package/src/api/entity/index.ts +30 -30
- package/src/api/entity/referenceLine.ts +235 -235
- package/src/api/entity/space.ts +612 -612
- package/src/api/entity/story.ts +517 -517
- package/src/api/index.ts +47 -47
- package/src/api/presentation/aiInspiration.ts +1116 -1116
- package/src/api/presentation/annotate.ts +417 -385
- package/src/api/presentation/camera.ts +289 -289
- package/src/api/presentation/diagrams.ts +194 -194
- package/src/api/presentation/drawingContract.ts +70 -0
- package/src/api/presentation/drawings.ts +1179 -0
- package/src/api/presentation/export.ts +134 -108
- package/src/api/presentation/import.ts +159 -159
- package/src/api/presentation/index.ts +160 -126
- package/src/api/presentation/placedViews.ts +1211 -1120
- package/src/api/presentation/sections.ts +420 -0
- package/src/api/presentation/shapes.ts +274 -274
- package/src/api/presentation/sheets.ts +746 -585
- package/src/api/presentation/slideshow.ts +134 -134
- package/src/api/presentation/tables.ts +84 -84
- package/src/api/presentation/viewPresets.ts +241 -0
- package/src/api/presentation/views.ts +742 -673
- package/src/api/presentation/walkthroughs.ts +1201 -1201
- package/src/api/program/adjacency.ts +164 -164
- package/src/api/program/areas.ts +408 -408
- package/src/api/program/classification.ts +138 -138
- package/src/api/program/cores.ts +83 -83
- package/src/api/program/departments.ts +517 -517
- package/src/api/program/index.ts +73 -73
- package/src/api/program/labels.ts +332 -332
- package/src/api/program/layout.ts +422 -422
- package/src/api/program/metadata.ts +364 -364
- package/src/api/program/metrics.ts +120 -120
- package/src/api/program/site.ts +748 -748
- package/src/api/program/spreadsheet.ts +2698 -2698
- package/src/api/workspace/index.ts +612 -612
- package/src/errors/codes.ts +143 -136
- package/src/errors/envelope.ts +75 -75
- package/src/errors/index.ts +21 -21
- package/src/errors/plugin-error.ts +134 -134
- package/src/handles.ts +297 -297
- package/src/host-utils.ts +67 -67
- package/src/index.ts +7 -7
- package/src/massParameters.ops.ts +246 -246
- package/src/massParameters.ts +427 -427
- package/src/types.ts +16 -16
- package/test/drawingContract.test.mjs +288 -0
- package/test/errors.test.mjs +185 -184
- package/test/massParameters.test.mjs +952 -952
- package/test/presentationViewSettings.test.mjs +85 -0
- package/tsconfig.json +22 -22
- 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
|
+
>
|