@tldraw/driver 4.5.0-canary.84ac7a331515

package/README.md

@@ -0,0 +1,119 @@
+# @tldraw/driver
+
+Imperative API for driving the tldraw editor programmatically. Useful for scripting, automation, REPL usage, and testing.
+
+## Installation
+
+```bash
+npm install @tldraw/driver
+```
+
+## Quick start
+
+```ts
+import { Driver } from '@tldraw/driver'
+
+const driver = new Driver(editor)
+
+// Simulate user interactions
+driver.click(100, 200).pointerDown(300, 400).pointerMove(500, 600).pointerUp()
+
+// Keyboard input
+driver.keyPress('a')
+driver.keyDown('Shift')
+driver.keyUp('Shift')
+
+// Clipboard
+driver.copy()
+driver.paste({ x: 100, y: 100 })
+
+// Selection manipulation
+driver.translateSelection(50, 0)
+driver.rotateSelection(Math.PI / 4)
+driver.resizeSelection({ scaleX: 2 }, 'bottom_right')
+
+// Camera
+driver.pan({ x: 100, y: 0 })
+driver.wheel(0, -100)
+
+// Cleanup
+driver.dispose()
+```
+
+## API
+
+### Constructor
+
+#### `new Driver(editor: Editor)`
+
+Wraps an existing `Editor` instance. All methods use only public Editor APIs.
+
+### Input events
+
+All input methods return `this` for fluent chaining. Coordinates are in screen space.
+
+| Method                                        | Description                            |
+| --------------------------------------------- | -------------------------------------- |
+| `pointerDown(x?, y?, options?, modifiers?)`   | Dispatch a pointer down event          |
+| `pointerMove(x?, y?, options?, modifiers?)`   | Dispatch a pointer move event          |
+| `pointerUp(x?, y?, options?, modifiers?)`     | Dispatch a pointer up event            |
+| `click(x?, y?, options?, modifiers?)`         | Pointer down + up                      |
+| `rightClick(x?, y?, options?, modifiers?)`    | Right-click (button 2) down + up       |
+| `doubleClick(x?, y?, options?, modifiers?)`   | Double-click sequence                  |
+| `keyDown(key, options?)`                      | Dispatch a key down event              |
+| `keyUp(key, options?)`                        | Dispatch a key up event                |
+| `keyPress(key, options?)`                     | Key down + up                          |
+| `keyRepeat(key, options?)`                    | Dispatch a key repeat event            |
+| `wheel(dx, dy, options?)`                     | Dispatch a wheel/scroll event          |
+| `pinchStart(x?, y?, z, dx, dy, dz, options?)` | Begin a pinch gesture                  |
+| `pinchTo(x?, y?, z, dx, dy, dz, options?)`    | Continue a pinch gesture               |
+| `pinchEnd(x?, y?, z, dx, dy, dz, options?)`   | End a pinch gesture                    |
+| `forceTick(count?)`                           | Emit tick events to advance the editor |
+
+### Clipboard
+
+| Method          | Description                                         |
+| --------------- | --------------------------------------------------- |
+| `copy(ids?)`    | Copy shapes to the driver's clipboard               |
+| `cut(ids?)`     | Cut shapes (copy + delete)                          |
+| `paste(point?)` | Paste from the driver's clipboard                   |
+| `clipboard`     | The current clipboard content (`TLContent \| null`) |
+
+### Selection manipulation
+
+These methods work in page coordinates and handle the screen-space conversion internally.
+
+| Method                                      | Description                                 |
+| ------------------------------------------- | ------------------------------------------- |
+| `translateSelection(dx, dy, options?)`      | Move the selection by a page-space delta    |
+| `rotateSelection(angle, options?)`          | Rotate the selection by an angle in radians |
+| `resizeSelection(scale?, handle, options?)` | Resize the selection via a handle           |
+
+### Queries
+
+| Method                         | Description                                 |
+| ------------------------------ | ------------------------------------------- |
+| `getViewportPageCenter()`      | Center of the viewport in page coordinates  |
+| `getSelectionPageCenter()`     | Center of the selection in page coordinates |
+| `getPageCenter(shape)`         | Center of a shape in page coordinates       |
+| `getPageRotation(shape)`       | Rotation of a shape in page space (radians) |
+| `getPageRotationById(id)`      | Rotation of a shape by ID (radians)         |
+| `getArrowsBoundTo(shapeId)`    | All arrows bound to a shape                 |
+| `getLastCreatedShape()`        | The most recently created shape             |
+| `getLastCreatedShapes(count?)` | The last N created shapes                   |
+
+### Camera
+
+| Method        | Description                           |
+| ------------- | ------------------------------------- |
+| `pan(offset)` | Pan the camera by a page-space offset |
+
+### Lifecycle
+
+| Method      | Description                                  |
+| ----------- | -------------------------------------------- |
+| `dispose()` | Remove side-effect handlers. Call when done. |
+
+## License
+
+See [LICENSE.md](../../LICENSE.md).

package/dist-cjs/index.d.ts

@@ -0,0 +1,270 @@
+import { Editor } from '@tldraw/editor';
+import { RotateCorner } from '@tldraw/editor';
+import { SelectionHandle } from '@tldraw/editor';
+import { TLArrowShape } from '@tldraw/editor';
+import { TLContent } from '@tldraw/editor';
+import { TLKeyboardEventInfo } from '@tldraw/editor';
+import { TLPageId } from '@tldraw/editor';
+import { TLPinchEventInfo } from '@tldraw/editor';
+import { TLPointerEventInfo } from '@tldraw/editor';
+import { TLShape } from '@tldraw/editor';
+import { TLShapeId } from '@tldraw/editor';
+import { TLWheelEventInfo } from '@tldraw/editor';
+import { Vec } from '@tldraw/editor';
+import { VecLike } from '@tldraw/editor';
+
+/**
+ * Driver wraps an Editor instance and provides an imperative API for driving it
+ * programmatically. Useful for scripting, automation, REPL usage, and testing.
+ *
+ * All methods use only public Editor APIs and return `this` for fluent chaining.
+ *
+ * @public
+ */
+export declare class Driver {
+    readonly editor: Editor;
+    /** The underlying Editor instance. */
+    private _cleanup;
+    constructor(editor: Editor);
+    /** Remove all registered side-effect handlers. Call when this controller is no longer needed. */
+    dispose(): void;
+    /** Local clipboard content. Used by copy, cut, and paste. */
+    clipboard: null | TLContent;
+    private _lastCreatedShapes;
+    /**
+     * Get the last created shapes.
+     * @param count - The number of shapes to get.
+     */
+    getLastCreatedShapes(count?: number): TLShape[];
+    /**
+     * Get the last created shape.
+     */
+    getLastCreatedShape<T extends TLShape>(): T;
+    /**
+     * Creates a shape ID from a string.
+     * @param id - The string to convert to a shape ID.
+     */
+    createShapeID(id: string): TLShapeId;
+    /**
+     * Creates a page ID from a string.
+     * @param id - The string to convert to a page ID.
+     */
+    createPageID(id: string): TLPageId;
+    /**
+     * Copies the given shapes to the controller clipboard. Defaults to the current selection.
+     * @param ids - Shape IDs to copy. Defaults to the current selection.
+     */
+    copy(ids?: TLShapeId[]): this;
+    /**
+     * Cuts the given shapes (copy to clipboard, then delete). Defaults to the current selection.
+     * @param ids - Shape IDs to cut. Defaults to the current selection.
+     */
+    cut(ids?: TLShapeId[]): this;
+    /**
+     * Pastes content from the controller clipboard. If shift is held, uses current pointer. Otherwise uses the given point.
+     * @param point - Page coordinates for paste location. If omitted and shift is not held, placement may vary.
+     */
+    paste(point?: VecLike): this;
+    /** Returns the center of the viewport in page coordinates. */
+    getViewportPageCenter(): Vec;
+    /** Returns the center of the current selection in page coordinates, or null if nothing is selected. */
+    getSelectionPageCenter(): null | Vec;
+    /**
+     * Returns the center of a shape in page coordinates, or null if the shape has no page transform.
+     * @param shape - The shape to get the center of.
+     */
+    getPageCenter(shape: TLShape): null | Vec;
+    /**
+     * Returns the rotation of a shape in page space by ID, in radians.
+     * @param id - The shape ID.
+     */
+    getPageRotationById(id: TLShapeId): number;
+    /**
+     * Returns the rotation of a shape in page space, in radians.
+     * @param shape - The shape to get the rotation of.
+     */
+    getPageRotation(shape: TLShape): number;
+    /**
+     * Returns all arrow shapes bound to the given shape.
+     * @param shapeId - The shape ID to find arrows bound to.
+     */
+    getArrowsBoundTo(shapeId: TLShapeId): TLArrowShape[];
+    /**
+     * Builds a TLPointerEventInfo object for input simulation.
+     * @param x - Screen x coordinate. Defaults to current pointer.
+     * @param y - Screen y coordinate. Defaults to current pointer.
+     * @param options - Target shape/selection or partial event info.
+     * @param modifiers - Override shift, ctrl, or alt key state.
+     */
+    private getPointerEventInfo;
+    /**
+     * Builds a TLKeyboardEventInfo object for input simulation.
+     * @param key - The key being pressed.
+     * @param name - The event name (key_down, key_up, key_repeat).
+     * @param options - Partial event info overrides.
+     */
+    private getKeyboardEventInfo;
+    /**
+     * Emits tick events to advance the editor by the given number of frames (default 1).
+     * @param count - Number of tick events to emit. Defaults to 1.
+     */
+    forceTick(count?: number): this;
+    /**
+     * Dispatches a pointer move event at the given screen coordinates.
+     * @param x - Screen x coordinate. Defaults to current pointer.
+     * @param y - Screen y coordinate. Defaults to current pointer.
+     * @param options - Target shape/selection or partial event info.
+     * @param modifiers - Override shift, ctrl, or alt key state.
+     */
+    pointerMove(x?: number, y?: number, options?: PointerEventInit_2, modifiers?: EventModifiers): this;
+    /**
+     * Dispatches a pointer down event at the given screen coordinates.
+     * @param x - Screen x coordinate. Defaults to current pointer.
+     * @param y - Screen y coordinate. Defaults to current pointer.
+     * @param options - Target shape/selection or partial event info.
+     * @param modifiers - Override shift, ctrl, or alt key state.
+     */
+    pointerDown(x?: number, y?: number, options?: PointerEventInit_2, modifiers?: EventModifiers): this;
+    /**
+     * Dispatches a pointer up event at the given screen coordinates.
+     * @param x - Screen x coordinate. Defaults to current pointer.
+     * @param y - Screen y coordinate. Defaults to current pointer.
+     * @param options - Target shape/selection or partial event info.
+     * @param modifiers - Override shift, ctrl, or alt key state.
+     */
+    pointerUp(x?: number, y?: number, options?: PointerEventInit_2, modifiers?: EventModifiers): this;
+    /**
+     * Dispatches a pointer down followed by pointer up at the given screen coordinates.
+     * @param x - Screen x coordinate. Defaults to current pointer.
+     * @param y - Screen y coordinate. Defaults to current pointer.
+     * @param options - Target shape/selection or partial event info.
+     * @param modifiers - Override shift, ctrl, or alt key state.
+     */
+    click(x?: number, y?: number, options?: PointerEventInit_2, modifiers?: EventModifiers): this;
+    /**
+     * Dispatches a right-click (button 2) down and up at the given screen coordinates.
+     * @param x - Screen x coordinate. Defaults to current pointer.
+     * @param y - Screen y coordinate. Defaults to current pointer.
+     * @param options - Target shape/selection or partial event info.
+     * @param modifiers - Override shift, ctrl, or alt key state.
+     */
+    rightClick(x?: number, y?: number, options?: PointerEventInit_2, modifiers?: EventModifiers): this;
+    /**
+     * Dispatches a double-click sequence at the given screen coordinates.
+     * @param x - Screen x coordinate. Defaults to current pointer.
+     * @param y - Screen y coordinate. Defaults to current pointer.
+     * @param options - Target shape/selection or partial event info.
+     * @param modifiers - Override shift, ctrl, or alt key state.
+     */
+    doubleClick(x?: number, y?: number, options?: PointerEventInit_2, modifiers?: EventModifiers): this;
+    /**
+     * Dispatches a key down followed by key up for the given key.
+     * @param key - The key to press (e.g. 'a', 'Enter', 'Shift').
+     * @param options - Partial keyboard event overrides.
+     */
+    keyPress(key: string, options?: Partial<Omit<TLKeyboardEventInfo, "key">>): this;
+    /**
+     * Dispatches a key down event for the given key.
+     * @param key - The key to press (e.g. 'a', 'Enter', 'Shift').
+     * @param options - Partial keyboard event overrides.
+     */
+    keyDown(key: string, options?: Partial<Omit<TLKeyboardEventInfo, "key">>): this;
+    /**
+     * Dispatches a key repeat event for the given key.
+     * @param key - The key that is repeating (e.g. 'a', 'ArrowDown').
+     * @param options - Partial keyboard event overrides.
+     */
+    keyRepeat(key: string, options?: Partial<Omit<TLKeyboardEventInfo, "key">>): this;
+    /**
+     * Dispatches a key up event for the given key.
+     * @param key - The key to release (e.g. 'a', 'Enter', 'Shift').
+     * @param options - Partial keyboard event overrides.
+     */
+    keyUp(key: string, options?: Partial<Omit<TLKeyboardEventInfo, "key">>): this;
+    /**
+     * Dispatches a wheel event with the given delta values.
+     * @param dx - Horizontal scroll delta.
+     * @param dy - Vertical scroll delta.
+     * @param options - Partial wheel event overrides.
+     */
+    wheel(dx: number, dy: number, options?: Partial<Omit<TLWheelEventInfo, "delta">>): this;
+    /**
+     * Pans the camera by the given offset (in page coordinates). Does nothing if camera is locked.
+     * @param offset - The pan delta (x, y) in page coordinates.
+     */
+    pan(offset: VecLike): this;
+    /**
+     * Dispatches a pinch start event.
+     * @param x - Screen x coordinate. Defaults to current pointer.
+     * @param y - Screen y coordinate. Defaults to current pointer.
+     * @param z - Pinch scale/factor.
+     * @param dx - Delta x for pinch.
+     * @param dy - Delta y for pinch.
+     * @param dz - Delta z for pinch.
+     * @param options - Partial pinch event overrides.
+     */
+    pinchStart(x: number | undefined, y: number | undefined, z: number, dx: number, dy: number, dz: number, options?: Partial<Omit<TLPinchEventInfo, "delta" | "offset" | "point">>): this;
+    /**
+     * Dispatches a pinch move event (pinch_to).
+     * @param x - Screen x coordinate. Defaults to current pointer.
+     * @param y - Screen y coordinate. Defaults to current pointer.
+     * @param z - Pinch scale/factor.
+     * @param dx - Delta x for pinch.
+     * @param dy - Delta y for pinch.
+     * @param dz - Delta z for pinch.
+     * @param options - Partial pinch event overrides.
+     */
+    pinchTo(x: number | undefined, y: number | undefined, z: number, dx: number, dy: number, dz: number, options?: Partial<Omit<TLPinchEventInfo, "delta" | "offset" | "point">>): this;
+    /**
+     * Dispatches a pinch end event.
+     * @param x - Screen x coordinate. Defaults to current pointer.
+     * @param y - Screen y coordinate. Defaults to current pointer.
+     * @param z - Pinch scale/factor.
+     * @param dx - Delta x for pinch.
+     * @param dy - Delta y for pinch.
+     * @param dz - Delta z for pinch.
+     * @param options - Partial pinch event overrides.
+     */
+    pinchEnd(x: number | undefined, y: number | undefined, z: number, dx: number, dy: number, dz: number, options?: Partial<Omit<TLPinchEventInfo, "delta" | "offset" | "point">>): this;
+    /**
+     * Converts a point from page coordinates to screen coordinates.
+     * Pointer events operate in screen space, so page-space points must be
+     * converted before being passed to pointerDown/Move/Up.
+     */
+    private pageToScreen;
+    /**
+     * Simulates rotating the current selection by the given angle in radians via the rotation handle.
+     * @param angleRadians - Rotation angle in radians.
+     * @param options - Optional handle and shiftKey. handle defaults to 'top_left_rotate'.
+     */
+    rotateSelection(angleRadians: number, options?: {
+        handle?: RotateCorner;
+        shiftKey?: boolean;
+    }): this;
+    /**
+     * Simulates translating the current selection by the given delta in page coordinates.
+     * @param dx - Horizontal delta in page coordinates.
+     * @param dy - Vertical delta in page coordinates.
+     * @param options - Partial pointer event overrides (e.g. altKey for center-based scaling).
+     */
+    translateSelection(dx: number, dy: number, options?: Partial<TLPointerEventInfo>): this;
+    /**
+     * Simulates resizing the current selection via the given handle, with optional scale factors.
+     * @param scale - Scale factors for x and y. Defaults to `\{ scaleX: 1, scaleY: 1 \}`.
+     * @param handle - The selection handle to drag (e.g. 'top', 'bottom_right').
+     * @param options - Partial pointer event overrides (e.g. altKey to scale from center).
+     */
+    resizeSelection(scale: {
+        scaleX?: number | undefined;
+        scaleY?: number | undefined;
+    } | undefined, handle: SelectionHandle, options?: Partial<TLPointerEventInfo>): this;
+}
+
+/** Modifier keys for events. @public */
+export declare type EventModifiers = Partial<Pick<TLPointerEventInfo, 'altKey' | 'ctrlKey' | 'shiftKey'>>;
+
+/** Options for pointer events. Either partial pointer event info or a shape ID to target. @public */
+declare type PointerEventInit_2 = Partial<TLPointerEventInfo> | TLShapeId;
+export { PointerEventInit_2 as PointerEventInit }
+
+export { }

package/dist-cjs/index.js

@@ -0,0 +1,31 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var index_exports = {};
+__export(index_exports, {
+  Driver: () => import_Driver.Driver
+});
+module.exports = __toCommonJS(index_exports);
+var import_utils = require("@tldraw/utils");
+var import_Driver = require("./lib/Driver");
+(0, import_utils.registerTldrawLibraryVersion)(
+  "@tldraw/driver",
+  "4.5.0-canary.84ac7a331515",
+  "cjs"
+);
+//# sourceMappingURL=index.js.map

package/dist-cjs/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "sourcesContent": ["import { registerTldrawLibraryVersion } from '@tldraw/utils'\n\nexport { Driver } from './lib/Driver'\nexport type { EventModifiers, PointerEventInit } from './lib/Driver'\n\nregisterTldrawLibraryVersion(\n\t(globalThis as any).TLDRAW_LIBRARY_NAME,\n\t(globalThis as any).TLDRAW_LIBRARY_VERSION,\n\t(globalThis as any).TLDRAW_LIBRARY_MODULES\n)\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,mBAA6C;AAE7C,oBAAuB;AAAA,IAGvB;AAAA,EACE;AAAA,EACA;AAAA,EACA;AACF;",
+  "names": []
+}