snapshot of https://github.com/tldraw/tldraw.git (main, 2026-09-23; blobs > 131072B omitted)

packages/driver/README.md

@@ -0,0 +1,125 @@
+# @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. |
+
+## Documentation
+
+Documentation for the most recent release can be found on [tldraw.dev/docs](https://tldraw.dev/docs), including [reference docs](https://tldraw.dev/reference/editor/Editor). Our release notes can be found [here](https://tldraw.dev/releases).
+
+For more agent-friendly docs, see our [LLMs.txt](https://tldraw.dev/llms.txt).
+
+## License
+
+See [LICENSE.md](../../LICENSE.md).