@datalayer/reactor-excalidraw 0.0.0 → 1.3.10

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,107 @@
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
+ ## Two 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 between existing shapes is bound
102
+ at both ends and listed in both shapes' `boundElements`, so it follows them
103
+ when they move.
104
+
105
+ ## Testing
106
+
107
+ 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,94 @@
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.
23
+ *
24
+ * @module handlers
25
+ */
26
+ import type { ExcalidrawConverters, ExcalidrawDrawingHost } from './host';
27
+ import { type ExcalidrawElementData, type ExcalidrawScene } from './scene';
28
+ /** One handler: the validated arguments of a call, and its answer. */
29
+ export type ExcalidrawToolHandler = (args: Record<string, unknown>) => Promise<unknown>;
30
+ /**
31
+ * Turn the tool's element shape into the one Excalidraw's converter takes.
32
+ *
33
+ * The tool's shape is flatter on purpose — `label` instead of
34
+ * `label: {text}`, `startId` instead of `start: {id}` — because a flat
35
+ * parameter is one a model gets right first time. This is where that is
36
+ * traded back.
37
+ */
38
+ export declare function toSkeleton(element: Record<string, any>, id: string): Record<string, any>;
39
+ /**
40
+ * Where a line from `from` to `towards` leaves `from`'s box.
41
+ *
42
+ * Excalidraw recomputes this itself the moment anybody drags either shape;
43
+ * what it needs from us is a starting geometry that already looks right, so
44
+ * the drawing is correct before it is ever touched.
45
+ */
46
+ export declare function edgePoint(from: ExcalidrawElementData, towards: {
47
+ x: number;
48
+ y: number;
49
+ }): {
50
+ x: number;
51
+ y: number;
52
+ };
53
+ /**
54
+ * Bind an arrow to the two elements it runs between, in the live scene.
55
+ *
56
+ * Both halves: the arrow's `startBinding`/`endBinding`, and each shape's
57
+ * `boundElements`. Excalidraw needs both — the first is how the arrow finds
58
+ * its shapes, the second is how a shape knows to drag its arrows along.
59
+ */
60
+ export declare function bindArrow(scene: ExcalidrawScene, arrow: ExcalidrawElementData, fromId: string, toId: string): ExcalidrawElementData;
61
+ /**
62
+ * Add elements to a scene, binding the arrows whose ends are shapes already
63
+ * in it. Answers the ids made, in the order asked.
64
+ */
65
+ export declare function addToScene(scene: ExcalidrawScene, asked: Record<string, any>[], converters: ExcalidrawConverters): string[];
66
+ /**
67
+ * Change elements by id. Refuses the whole batch when an id is wrong: half a
68
+ * batch is a drawing nobody asked for.
69
+ */
70
+ export declare function updateInScene(scene: ExcalidrawScene, updates: Record<string, any>[]): void;
71
+ /**
72
+ * Remove elements by id, with the text bound inside them, detaching the
73
+ * arrows that pointed at them. Answers how many elements went.
74
+ */
75
+ export declare function deleteFromScene(scene: ExcalidrawScene, elementIds: string[]): number;
76
+ /** Draw a bound arrow between two elements. Answers the arrow's id. */
77
+ export declare function connectInScene(scene: ExcalidrawScene, args: {
78
+ fromId: string;
79
+ toId: string;
80
+ label?: string;
81
+ strokeColor?: string;
82
+ strokeStyle?: string;
83
+ }, converters: ExcalidrawConverters): string;
84
+ /** Set the canvas: its colour, and its grid (0 turns it off). */
85
+ export declare function setCanvas(scene: ExcalidrawScene, args: {
86
+ viewBackgroundColor?: string;
87
+ gridSize?: number;
88
+ }): void;
89
+ /**
90
+ * Every Excalidraw handler, keyed by the operation the executor looks up,
91
+ * over one host.
92
+ */
93
+ export declare function createExcalidrawToolHandlers(host: ExcalidrawDrawingHost, converters: ExcalidrawConverters): Record<string, ExcalidrawToolHandler>;
94
+ //# sourceMappingURL=handlers.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../src/handlers.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;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;AAWD;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,eAAe,EACtB,KAAK,EAAE,qBAAqB,EAC5B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,qBAAqB,CAoCvB;AAMD;;;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,CAuCV;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,IAAI,CA6C1F;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,CAsBR;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;AAkCD;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,qBAAqB,EAC3B,UAAU,EAAE,oBAAoB,GAC/B,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAoJvC"}