@datalayer/reactor-excalidraw 0.0.0 → 1.3.11

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/LICENSE ADDED
@@ -0,0 +1,29 @@
1
+ BSD 3-Clause License
2
+
3
+ Copyright (c) 2026, Datalayer, Inc.
4
+ All rights reserved.
5
+
6
+ Redistribution and use in source and binary forms, with or without
7
+ modification, are permitted provided that the following conditions are met:
8
+
9
+ 1. Redistributions of source code must retain the above copyright notice, this
10
+ list of conditions and the following disclaimer.
11
+
12
+ 2. Redistributions in binary form must reproduce the above copyright notice,
13
+ this list of conditions and the following disclaimer in the documentation
14
+ and/or other materials provided with the distribution.
15
+
16
+ 3. Neither the name of the copyright holder nor the names of its
17
+ contributors may be used to endorse or promote products derived from
18
+ this software without specific prior written permission.
19
+
20
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
23
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
24
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
26
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
27
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
package/README.md CHANGED
@@ -1 +1,113 @@
1
- # @datalayer/reactor-excalidraw\n\nPlaceholder. See https://github.com/datalayer/reactor/tree/main/plugins/excalidraw
1
+ [![Datalayer](https://images.datalayer.io/legacy/datalayer-25.svg)](https://datalayer.ai)
2
+
3
+ # 🖌️ `@datalayer/reactor-excalidraw`
4
+
5
+ Excalidraw drawings as tools an AI agent draws with, for any application built
6
+ on `@datalayer/reactor`.
7
+
8
+ ## What is in it
9
+
10
+ - **Eleven tools** (`ToolDefinition`s from `@datalayer/reactor/tools`), each
11
+ with its Zod schema and the operation that validates a call:
12
+
13
+ | Tool | What it does |
14
+ | --- | --- |
15
+ | `excalidrawInsertNode` | a new drawing, optionally with its shapes |
16
+ | `excalidrawFromMermaid` | Mermaid source turned into real, editable shapes |
17
+ | `excalidrawListDrawings` | the drawings there are, with what each holds |
18
+ | `excalidrawReadScene` | every element of one drawing, with its id |
19
+ | `excalidrawAddElements` | shapes added, arrows bound to shapes already there |
20
+ | `excalidrawUpdateElements` | move, resize, recolour, relabel by element id |
21
+ | `excalidrawConnectElements` | a bound arrow between two shapes |
22
+ | `excalidrawDeleteElements` | shapes removed, with their labels, arrows detached |
23
+ | `excalidrawSetAppState` | the canvas colour and grid |
24
+ | `excalidrawResize` | how large the drawing is rendered |
25
+ | `excalidrawClearScene` | the drawing emptied, kept |
26
+
27
+ Each is named `datalayer_<tool>` for the model.
28
+
29
+ - **A pure scene model** (`parseScene`, `serializeScene`, `describeScene`,
30
+ `withBoundText`, `touchElement`…) and pure scene changes (`addToScene`,
31
+ `updateInScene`, `deleteFromScene`, `connectInScene`, `setCanvas`): plain
32
+ objects in, plain objects out, no editor, no browser.
33
+
34
+ - **Handlers over a host.** `createExcalidrawToolHandlers(host, converters)`
35
+ runs the tools against whatever keeps the drawings. A host is five methods:
36
+ list, read, write, insert, resize. `createMemoryDrawingHost()` is one, for a
37
+ page with a canvas or two.
38
+
39
+ - **The reactor plugin.** `ExcalidrawPlugin` registers each tool's operation as
40
+ a command, `excalidraw.<operation>`, and contributes the `AgentTools` bundle
41
+ `excalidraw` that names them, so a host that mounts the plugin hands an
42
+ agent the tools without declaring any.
43
+
44
+ ## Excalidraw itself is handed in
45
+
46
+ The package does not depend on `@excalidraw/excalidraw`, a browser bundle
47
+ several megabytes wide. The host that renders drawings has it already, and
48
+ passes the two conversions the tools need:
49
+
50
+ ```ts
51
+ import { convertToExcalidrawElements } from '@excalidraw/excalidraw';
52
+ import { parseMermaidToExcalidraw } from '@excalidraw/mermaid-to-excalidraw';
53
+ ```
54
+
55
+ `parseMermaidToExcalidraw` is optional. Without it, `excalidrawFromMermaid`
56
+ says the host does not convert Mermaid.
57
+
58
+ ## Using it
59
+
60
+ As a reactor plugin:
61
+
62
+ ```ts
63
+ import { buildReactorFromPlugins, configurePlugin } from '@datalayer/reactor';
64
+ import { ExcalidrawPlugin, createMemoryDrawingHost } from '@datalayer/reactor-excalidraw';
65
+
66
+ const drawings = createMemoryDrawingHost({ onChange: (id) => redraw(id) });
67
+ const reactor = buildReactorFromPlugins([
68
+ configurePlugin(ExcalidrawPlugin, {
69
+ host: drawings,
70
+ converters: { convertToExcalidrawElements, parseMermaidToExcalidraw },
71
+ }),
72
+ ]);
73
+ ```
74
+
75
+ Or directly, without a platform, in a host with its own tool registry:
76
+
77
+ ```ts
78
+ import {
79
+ excalidrawTools,
80
+ createExcalidrawToolHandlers,
81
+ createExcalidrawExecutor,
82
+ } from '@datalayer/reactor-excalidraw';
83
+
84
+ const executor = createExcalidrawExecutor(createExcalidrawToolHandlers(myHost, converters));
85
+ await excalidrawTools.operations.excalidrawReadScene.execute(
86
+ { blockId: 'drawing-1' },
87
+ { executor, documentId: 'page' },
88
+ );
89
+ ```
90
+
91
+ `@datalayer/jupyter-lexical` is such a host: its drawings are
92
+ `ExcalidrawNode`s in a Lexical document, its host maps a drawing's id to the
93
+ node's key, and the node, the editor extension and the components stay in
94
+ Lexical as the editor-side binding over these operations.
95
+
96
+ ## Three rules the handlers keep
97
+
98
+ - **Ids are the contract.** Every skeleton gets an explicit id and is
99
+ converted with `regenerateIds: false`, so an id a caller chose, or read back
100
+ from a scene, keeps working in the next call.
101
+ - **Bindings are not decoration.** An arrow is bound at each end that names a
102
+ shape, one or both, and listed in that shape's `boundElements`; a free end
103
+ keeps the point it was asked for. Its label sits on the arrow as it finally
104
+ runs. A shape that moves or changes size brings its label and its arrows
105
+ along in the same edit.
106
+ - **One edit of a drawing at a time.** Each read-change-write waits for the
107
+ ones asked before it on the same drawing of the same host, so two parallel
108
+ calls both land. A host that builds a new host object per call should keep
109
+ one per document, as the queue is the host's.
110
+
111
+ ## Testing
112
+
113
+ From the repository root: `npm run test:ts` runs `plugins/excalidraw/__tests__`.
@@ -0,0 +1,30 @@
1
+ /**
2
+ * What the model is told the Excalidraw tools do.
3
+ *
4
+ * These descriptions are the whole of the model's knowledge of the feature,
5
+ * so they carry the two things it cannot work out for itself: that a drawing
6
+ * is addressed by its id (`blockId`), and that shapes are addressed
7
+ * by an element id that only comes from reading the scene. Everything else —
8
+ * how to draw a flowchart, what a sensible arrow looks like — it already
9
+ * knows.
10
+ *
11
+ * @module definitions
12
+ */
13
+ import { type ToolDefinition } from '@datalayer/reactor/tools';
14
+ export declare const excalidrawInsertNodeTool: ToolDefinition;
15
+ export declare const excalidrawListDrawingsTool: ToolDefinition;
16
+ export declare const excalidrawReadSceneTool: ToolDefinition;
17
+ export declare const excalidrawAddElementsTool: ToolDefinition;
18
+ export declare const excalidrawUpdateElementsTool: ToolDefinition;
19
+ export declare const excalidrawDeleteElementsTool: ToolDefinition;
20
+ export declare const excalidrawConnectElementsTool: ToolDefinition;
21
+ export declare const excalidrawSetAppStateTool: ToolDefinition;
22
+ export declare const excalidrawResizeTool: ToolDefinition;
23
+ export declare const excalidrawClearSceneTool: ToolDefinition;
24
+ export declare const excalidrawFromMermaidTool: ToolDefinition;
25
+ /**
26
+ * Every Excalidraw tool, in the order a reader meets them: make one, find
27
+ * one, read one, change one.
28
+ */
29
+ export declare const excalidrawToolDefinitions: ToolDefinition[];
30
+ //# sourceMappingURL=definitions.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../src/definitions.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAuB,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AA4BpF,eAAO,MAAM,wBAAwB,EAAE,cAiBtC,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,cAUxC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,cAUrC,CAAC;AAEF,eAAO,MAAM,yBAAyB,EAAE,cAcvC,CAAC;AAEF,eAAO,MAAM,4BAA4B,EAAE,cAU1C,CAAC;AAEF,eAAO,MAAM,4BAA4B,EAAE,cAiB1C,CAAC;AAEF,eAAO,MAAM,6BAA6B,EAAE,cAU3C,CAAC;AAEF,eAAO,MAAM,yBAAyB,EAAE,cAUvC,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,cAUlC,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,cAgBtC,CAAC;AAEF,eAAO,MAAM,yBAAyB,EAAE,cAmBvC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAE,cAAc,EAYrD,CAAC"}
@@ -0,0 +1,186 @@
1
+ /*
2
+ * Copyright (c) 2026-Present Datalayer, Inc.
3
+ *
4
+ * BSD 3-Clause License
5
+ */
6
+ /**
7
+ * What the model is told the Excalidraw tools do.
8
+ *
9
+ * These descriptions are the whole of the model's knowledge of the feature,
10
+ * so they carry the two things it cannot work out for itself: that a drawing
11
+ * is addressed by its id (`blockId`), and that shapes are addressed
12
+ * by an element id that only comes from reading the scene. Everything else —
13
+ * how to draw a flowchart, what a sensible arrow looks like — it already
14
+ * knows.
15
+ *
16
+ * @module definitions
17
+ */
18
+ import { zodToToolParameters } from '@datalayer/reactor/tools';
19
+ import { excalidrawAddElementsParamsSchema, excalidrawClearSceneParamsSchema, excalidrawConnectElementsParamsSchema, excalidrawDeleteElementsParamsSchema, excalidrawFromMermaidParamsSchema, excalidrawInsertNodeParamsSchema, excalidrawListDrawingsParamsSchema, excalidrawReadSceneParamsSchema, excalidrawResizeParamsSchema, excalidrawSetAppStateParamsSchema, excalidrawUpdateElementsParamsSchema, } from './schemas.js';
20
+ /** The vendor prefix every Datalayer tool name carries. */
21
+ const NAME = (tool) => `datalayer_${tool}`;
22
+ /** Shared by everything that only rearranges a drawing nobody is looking at. */
23
+ const QUIET = {
24
+ requiresConfirmation: false,
25
+ canBeReferencedInPrompt: true,
26
+ priority: 'medium',
27
+ };
28
+ const TAGS = ['excalidraw', 'drawing', 'diagram'];
29
+ export const excalidrawInsertNodeTool = {
30
+ name: NAME('excalidrawInsertNode'),
31
+ displayName: 'Insert Drawing',
32
+ toolReferenceName: 'excalidrawInsertNode',
33
+ description: 'Insert an Excalidraw drawing, optionally with its contents. This is how you draw a diagram: give the elements you want and they are laid out as you place them, in scene coordinates where x grows right and y grows down. Give a shape an `id` and a later arrow can bind to it with `startId`/`endId`, so the arrow follows the shape when it moves. Put text on a shape with `label` rather than positioning a separate text element on top of it. Returns the blockId of the new drawing — keep it, every other excalidraw tool needs it. Omit `elements` to insert an empty canvas for a person to draw on themselves.',
34
+ parameters: zodToToolParameters(excalidrawInsertNodeParamsSchema),
35
+ operation: 'excalidrawInsertNode',
36
+ config: {
37
+ confirmationMessage: (params) => `Insert a drawing of ${params.elements?.length ?? 0} element(s)?`,
38
+ invocationMessage: () => 'Drawing',
39
+ requiresConfirmation: true,
40
+ canBeReferencedInPrompt: true,
41
+ priority: 'high',
42
+ },
43
+ tags: [...TAGS, 'insert'],
44
+ };
45
+ export const excalidrawListDrawingsTool = {
46
+ name: NAME('excalidrawListDrawings'),
47
+ displayName: 'List Drawings',
48
+ toolReferenceName: 'excalidrawListDrawings',
49
+ description: 'List the Excalidraw drawings on the page or in the open document, with the blockId of each and a one-line description of what it holds. Call this first when asked to change "the diagram" and you do not already know its blockId.',
50
+ parameters: zodToToolParameters(excalidrawListDrawingsParamsSchema),
51
+ operation: 'excalidrawListDrawings',
52
+ config: { ...QUIET, invocationMessage: () => 'Looking for drawings' },
53
+ tags: [...TAGS, 'read'],
54
+ };
55
+ export const excalidrawReadSceneTool = {
56
+ name: NAME('excalidrawReadScene'),
57
+ displayName: 'Read Drawing',
58
+ toolReferenceName: 'excalidrawReadScene',
59
+ description: "Read what is inside one drawing: every element with its id, type, position, size and text. The element ids are the only way to address a shape, so read the scene before updating, deleting or connecting anything. The default 'summary' detail is what you want; 'full' returns the raw Excalidraw elements and is large.",
60
+ parameters: zodToToolParameters(excalidrawReadSceneParamsSchema),
61
+ operation: 'excalidrawReadScene',
62
+ config: { ...QUIET, invocationMessage: () => 'Reading the drawing' },
63
+ tags: [...TAGS, 'read'],
64
+ };
65
+ export const excalidrawAddElementsTool = {
66
+ name: NAME('excalidrawAddElements'),
67
+ displayName: 'Add to Drawing',
68
+ toolReferenceName: 'excalidrawAddElements',
69
+ description: "Add elements to a drawing that already exists, leaving what is there alone. Same element format as excalidrawInsertNode. To attach a new arrow to a shape already in the drawing, pass that shape's existing element id as `startId` or `endId`. Read the scene first if you need to know where there is room.",
70
+ parameters: zodToToolParameters(excalidrawAddElementsParamsSchema),
71
+ operation: 'excalidrawAddElements',
72
+ config: {
73
+ ...QUIET,
74
+ invocationMessage: () => 'Adding to the drawing',
75
+ priority: 'high',
76
+ },
77
+ tags: [...TAGS, 'edit'],
78
+ };
79
+ export const excalidrawUpdateElementsTool = {
80
+ name: NAME('excalidrawUpdateElements'),
81
+ displayName: 'Update Drawing Elements',
82
+ toolReferenceName: 'excalidrawUpdateElements',
83
+ description: 'Change elements already in a drawing — move them, resize them, recolour them, or rewrite their text. Address each one by the element id from excalidrawReadScene. Fields you leave out are kept as they are. Setting `text` on a shape rewrites the label bound inside it rather than replacing the shape.',
84
+ parameters: zodToToolParameters(excalidrawUpdateElementsParamsSchema),
85
+ operation: 'excalidrawUpdateElements',
86
+ config: { ...QUIET, invocationMessage: () => 'Changing the drawing' },
87
+ tags: [...TAGS, 'edit'],
88
+ };
89
+ export const excalidrawDeleteElementsTool = {
90
+ name: NAME('excalidrawDeleteElements'),
91
+ displayName: 'Delete Drawing Elements',
92
+ toolReferenceName: 'excalidrawDeleteElements',
93
+ description: 'Remove elements from a drawing by their element ids. Deleting a shape also removes the text bound inside it and detaches any arrows that pointed at it, so the drawing stays consistent.',
94
+ parameters: zodToToolParameters(excalidrawDeleteElementsParamsSchema),
95
+ operation: 'excalidrawDeleteElements',
96
+ config: {
97
+ confirmationMessage: (params) => `Delete ${params.elementIds?.length ?? 0} element(s) from the drawing?`,
98
+ invocationMessage: () => 'Removing from the drawing',
99
+ requiresConfirmation: true,
100
+ canBeReferencedInPrompt: true,
101
+ priority: 'medium',
102
+ },
103
+ tags: [...TAGS, 'edit', 'delete'],
104
+ };
105
+ export const excalidrawConnectElementsTool = {
106
+ name: NAME('excalidrawConnectElements'),
107
+ displayName: 'Connect Drawing Elements',
108
+ toolReferenceName: 'excalidrawConnectElements',
109
+ description: 'Draw an arrow from one element to another and bind it to both, so it follows them when either moves. Excalidraw works out where the arrow should meet each shape. Use this rather than adding an arrow with hand-computed points whenever both ends are existing shapes.',
110
+ parameters: zodToToolParameters(excalidrawConnectElementsParamsSchema),
111
+ operation: 'excalidrawConnectElements',
112
+ config: { ...QUIET, invocationMessage: () => 'Connecting two shapes' },
113
+ tags: [...TAGS, 'edit'],
114
+ };
115
+ export const excalidrawSetAppStateTool = {
116
+ name: NAME('excalidrawSetAppState'),
117
+ displayName: 'Set Drawing Canvas',
118
+ toolReferenceName: 'excalidrawSetAppState',
119
+ description: 'Set the canvas behind a drawing: its background colour and its grid. This is about the canvas, not the shapes on it — use excalidrawUpdateElements to recolour a shape.',
120
+ parameters: zodToToolParameters(excalidrawSetAppStateParamsSchema),
121
+ operation: 'excalidrawSetAppState',
122
+ config: { ...QUIET, invocationMessage: () => 'Setting up the canvas' },
123
+ tags: [...TAGS, 'edit'],
124
+ };
125
+ export const excalidrawResizeTool = {
126
+ name: NAME('excalidrawResize'),
127
+ displayName: 'Resize Drawing',
128
+ toolReferenceName: 'excalidrawResize',
129
+ description: 'Set how large the drawing is rendered. This scales the picture on the page; it does not move or resize anything inside it. Omit width and height to go back to sizing by content.',
130
+ parameters: zodToToolParameters(excalidrawResizeParamsSchema),
131
+ operation: 'excalidrawResize',
132
+ config: { ...QUIET, invocationMessage: () => 'Resizing the drawing' },
133
+ tags: [...TAGS, 'edit'],
134
+ };
135
+ export const excalidrawClearSceneTool = {
136
+ name: NAME('excalidrawClearScene'),
137
+ displayName: 'Clear Drawing',
138
+ toolReferenceName: 'excalidrawClearScene',
139
+ description: 'Empty a drawing, keeping it so it can be drawn into again. In a document, to remove the drawing altogether, use deleteBlocks with its blockId.',
140
+ parameters: zodToToolParameters(excalidrawClearSceneParamsSchema),
141
+ operation: 'excalidrawClearScene',
142
+ config: {
143
+ confirmationMessage: () => 'Empty this drawing?',
144
+ invocationMessage: () => 'Emptying the drawing',
145
+ requiresConfirmation: true,
146
+ canBeReferencedInPrompt: true,
147
+ priority: 'low',
148
+ },
149
+ tags: [...TAGS, 'edit', 'delete'],
150
+ };
151
+ export const excalidrawFromMermaidTool = {
152
+ name: NAME('excalidrawFromMermaid'),
153
+ displayName: 'Draw from Mermaid',
154
+ toolReferenceName: 'excalidrawFromMermaid',
155
+ description: 'Turn Mermaid source into a real Excalidraw drawing — shapes and arrows that can then be moved, recoloured and edited like anything else you drew. This is the fastest way to produce a flowchart, sequence diagram or class diagram: write the Mermaid and let the layout be worked out for you, rather than placing boxes by hand. Give blockId to replace an existing drawing, or afterId to insert a new one.',
156
+ parameters: zodToToolParameters(excalidrawFromMermaidParamsSchema),
157
+ operation: 'excalidrawFromMermaid',
158
+ config: {
159
+ confirmationMessage: (params) => params.blockId
160
+ ? 'Replace this drawing with the Mermaid diagram?'
161
+ : 'Insert the Mermaid diagram as a drawing?',
162
+ invocationMessage: () => 'Drawing the Mermaid diagram',
163
+ requiresConfirmation: true,
164
+ canBeReferencedInPrompt: true,
165
+ priority: 'high',
166
+ },
167
+ tags: [...TAGS, 'insert', 'mermaid'],
168
+ };
169
+ /**
170
+ * Every Excalidraw tool, in the order a reader meets them: make one, find
171
+ * one, read one, change one.
172
+ */
173
+ export const excalidrawToolDefinitions = [
174
+ excalidrawInsertNodeTool,
175
+ excalidrawFromMermaidTool,
176
+ excalidrawListDrawingsTool,
177
+ excalidrawReadSceneTool,
178
+ excalidrawAddElementsTool,
179
+ excalidrawUpdateElementsTool,
180
+ excalidrawConnectElementsTool,
181
+ excalidrawDeleteElementsTool,
182
+ excalidrawSetAppStateTool,
183
+ excalidrawResizeTool,
184
+ excalidrawClearSceneTool,
185
+ ];
186
+ //# sourceMappingURL=definitions.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"definitions.js","sourceRoot":"","sources":["../src/definitions.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,128 @@
1
+ /**
2
+ * The half of the Excalidraw tools that changes a drawing.
3
+ *
4
+ * An operation in `operations.ts` validates what it was given and hands it to
5
+ * the executor; the executor finds these handlers, built for the host that
6
+ * keeps the drawings. Each one reads a scene from the host, changes it as
7
+ * plain data, and writes it back.
8
+ *
9
+ * Two rules shape everything here.
10
+ *
11
+ * **Ids are the contract.** Excalidraw's own converter regenerates element
12
+ * ids by default, which would mean the ids a caller wrote in one call meant
13
+ * nothing in the next. Every skeleton is given an explicit id before
14
+ * conversion and converted with `regenerateIds: false`, so an id a caller
15
+ * chose — or read back from a scene — keeps working.
16
+ *
17
+ * **Bindings are not decoration.** An arrow between two shapes in Excalidraw
18
+ * is not a line that happens to touch them: it is bound at both ends, and
19
+ * each shape lists it in `boundElements`. Get that wrong and the arrow looks
20
+ * right until somebody drags a box, at which point it stays behind. So
21
+ * arrows between existing elements go through `bindArrow`, which writes both
22
+ * halves of the relationship and computes the geometry — at both ends, or at
23
+ * the one end an arrow names — and lays the arrow's label out on it. A shape
24
+ * that moves or changes size takes its label and its arrows along in the
25
+ * same edit.
26
+ *
27
+ * And one drawing is changed by one call at a time: each read-change-write
28
+ * waits for the ones asked before it on the same drawing
29
+ * (`serializeDrawingEdit`), so two parallel calls both land.
30
+ *
31
+ * @module handlers
32
+ */
33
+ import type { ExcalidrawConverters, ExcalidrawDrawingHost } from './host';
34
+ import { type ExcalidrawElementData, type ExcalidrawScene } from './scene';
35
+ /** One handler: the validated arguments of a call, and its answer. */
36
+ export type ExcalidrawToolHandler = (args: Record<string, unknown>) => Promise<unknown>;
37
+ /**
38
+ * Turn the tool's element shape into the one Excalidraw's converter takes.
39
+ *
40
+ * The tool's shape is flatter on purpose — `label` instead of
41
+ * `label: {text}`, `startId` instead of `start: {id}` — because a flat
42
+ * parameter is one a model gets right first time. This is where that is
43
+ * traded back.
44
+ */
45
+ export declare function toSkeleton(element: Record<string, any>, id: string): Record<string, any>;
46
+ /**
47
+ * Where a line from `from` to `towards` leaves `from`'s box.
48
+ *
49
+ * Excalidraw recomputes this itself the moment anybody drags either shape;
50
+ * what it needs from us is a starting geometry that already looks right, so
51
+ * the drawing is correct before it is ever touched.
52
+ */
53
+ export declare function edgePoint(from: ExcalidrawElementData, towards: {
54
+ x: number;
55
+ y: number;
56
+ }): {
57
+ x: number;
58
+ y: number;
59
+ };
60
+ /**
61
+ * Put the text bound inside a container where it belongs: centred in a
62
+ * shape's box, or on the middle of an arrow as it now runs.
63
+ *
64
+ * Every change that moves a container calls it, with the container as it
65
+ * now is (not yet written back to the scene), so the label never sits where
66
+ * the container used to be.
67
+ */
68
+ export declare function layoutBoundText(scene: ExcalidrawScene, container: ExcalidrawElementData): void;
69
+ /**
70
+ * Bind an arrow to the elements it runs between, in the live scene: both,
71
+ * or the one it names.
72
+ *
73
+ * Both halves of each binding: the arrow's `startBinding`/`endBinding`, and
74
+ * the shape's `boundElements`. Excalidraw needs both — the first is how the
75
+ * arrow finds its shapes, the second is how a shape knows to drag its arrows
76
+ * along. A free end keeps the point it was asked for; a bound end meets its
77
+ * shape's edge on the way to the other end. The arrow's own label is laid
78
+ * out on the arrow as it finally runs.
79
+ */
80
+ export declare function bindArrow(scene: ExcalidrawScene, arrow: ExcalidrawElementData, ends: {
81
+ fromId?: string;
82
+ toId?: string;
83
+ }): ExcalidrawElementData;
84
+ /**
85
+ * Add elements to a scene, binding the arrows whose ends are shapes already
86
+ * in it. Answers the ids made, in the order asked.
87
+ */
88
+ export declare function addToScene(scene: ExcalidrawScene, asked: Record<string, any>[], converters: ExcalidrawConverters): string[];
89
+ /**
90
+ * Change elements by id. Refuses the whole batch when an id is wrong: half a
91
+ * batch is a drawing nobody asked for.
92
+ */
93
+ export declare function updateInScene(scene: ExcalidrawScene, updates: Record<string, any>[]): void;
94
+ /**
95
+ * Remove elements by id, with the text bound inside them, detaching the
96
+ * arrows that pointed at them. Answers how many elements went.
97
+ */
98
+ export declare function deleteFromScene(scene: ExcalidrawScene, elementIds: string[]): number;
99
+ /** Draw a bound arrow between two elements. Answers the arrow's id. */
100
+ export declare function connectInScene(scene: ExcalidrawScene, args: {
101
+ fromId: string;
102
+ toId: string;
103
+ label?: string;
104
+ strokeColor?: string;
105
+ strokeStyle?: string;
106
+ }, converters: ExcalidrawConverters): string;
107
+ /** Set the canvas: its colour, and its grid (0 turns it off). */
108
+ export declare function setCanvas(scene: ExcalidrawScene, args: {
109
+ viewBackgroundColor?: string;
110
+ gridSize?: number;
111
+ }): void;
112
+ /**
113
+ * Run one read-change-write of a drawing once the edits asked before it on
114
+ * the same drawing of the same host are done.
115
+ *
116
+ * Two calls on one drawing at once (a model's parallel tool calls) would
117
+ * otherwise both read the same scene, and the second write would silently
118
+ * drop the first one's change. Queued by host, not by handler set, so the
119
+ * handlers a host builds per call still wait for each other; a host that
120
+ * builds a new host object per call keeps one per document instead.
121
+ */
122
+ export declare function serializeDrawingEdit<T>(host: ExcalidrawDrawingHost, blockId: string, work: () => Promise<T>): Promise<T>;
123
+ /**
124
+ * Every Excalidraw handler, keyed by the operation the executor looks up,
125
+ * over one host.
126
+ */
127
+ export declare function createExcalidrawToolHandlers(host: ExcalidrawDrawingHost, converters: ExcalidrawConverters): Record<string, ExcalidrawToolHandler>;
128
+ //# sourceMappingURL=handlers.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../src/handlers.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,QAAQ,CAAC;AAC1E,OAAO,EAKL,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACrB,MAAM,SAAS,CAAC;AAKjB,sEAAsE;AACtE,MAAM,MAAM,qBAAqB,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAuBxF;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAiCxF;AA4CD;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,qBAAqB,EAC3B,OAAO,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAe1B;AA8BD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,qBAAqB,GAAG,IAAI,CAiB9F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,eAAe,EACtB,KAAK,EAAE,qBAAqB,EAC5B,IAAI,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACvC,qBAAqB,CA4CvB;AAiBD;;;GAGG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,eAAe,EACtB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,EAC5B,UAAU,EAAE,oBAAoB,GAC/B,MAAM,EAAE,CAwCV;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,IAAI,CAgE1F;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,CAoCpF;AAED,uEAAuE;AACvE,wBAAgB,cAAc,CAC5B,KAAK,EAAE,eAAe,EACtB,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,EAClG,UAAU,EAAE,oBAAoB,GAC/B,MAAM,CAyBR;AAED,iEAAiE;AACjE,wBAAgB,SAAS,CACvB,KAAK,EAAE,eAAe,EACtB,IAAI,EAAE;IAAE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACxD,IAAI,CASN;AAqCD;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,IAAI,EAAE,qBAAqB,EAC3B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACrB,OAAO,CAAC,CAAC,CAAC,CAmBZ;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,qBAAqB,EAC3B,UAAU,EAAE,oBAAoB,GAC/B,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAuJvC"}