@pixerate/editor 0.44.0 → 0.46.0

package/README.md

@@ -206,7 +206,32 @@ registry.onListChanged((tools) => server.sendToolListChanged());
 await registry.callTool("insert_text", { text: "Hello" }); // { content: [...], structuredContent }
 ```
 
-`createEditorMcpToolProvider` exposes the static tools (`get_editor_state`, `edit_canvas`, `edit_prompt`, `view_editor`) through the registry, and `planToolCall` turns any tool call into planner steps (`step:tool_call` for registry tools).
+Built-in providers:
+
+| Provider | Tools |
+| :--- | :--- |
+| `createRichTextToolProvider(editor, { id })` | `get_text` (`format`, `blocks: true` for every paragraph's positions), `find_text`, `insert_text`, `replace_text` (all matches or the n-th, one undo step), `replace_range`, `replace_selection`, `set_selection`, `edit_table` (when tables are on). Read-only editors get `get_text` and `find_text`. |
+| `createSpreadsheetToolProvider(controller, { id })` | `get_range`, `set_cell`, `set_range` (2D block, one undo step, refuses read-only targets), `insert_rows`, `delete_rows`, `insert_columns`, `delete_columns` |
+| `createEditorMcpToolProvider({ id, getSnapshot, applySteps })` | `get_editor_state`, `canvas_add_node`, `canvas_remove_nodes`, `canvas_connect`, `canvas_update_node`, `canvas_layout`, `canvas_select`, `canvas_highlight`, `prompt_insert_text`, `prompt_replace_range`, `prompt_set_variable`, `prompt_select`, `view_editor` (with `captureView`) |
+| `createCanvasComponentToolProvider`, `createCommandToolProvider`, `createImageEditorToolProvider`, `createGenerationToolProvider` | See the canvas, commands, image editor and generation docs |
+
+Text tools take ProseMirror document positions, not plain-text offsets: `find_text` and `get_text { blocks: true }` return them. The canvas tools check node ids against `getSnapshot()` (unknown ids, an id that already exists, self-edges and unordered ranges are tool errors the model can fix) and return what they created: `{ applied, steps, created: { nodes: [{ id, position }], edges: [{ id, source, target }] } }`. Pass `toolStyle: "combined"` for the older `edit_canvas` / `edit_prompt` tools with an `operation` argument, and `surfaces: { canvas: false }` to expose only the prompt tools. `planToolCall` turns any tool call into planner steps (`step:tool_call` for registry tools), and `validateAgentCommand` runs the same checks for hosts that drive the planner directly.
+
+Tool `inputSchema`s are validated by `validateJsonSchema`, which supports `type`, `enum`, `const`, `properties`, `required`, `additionalProperties`, `items`, `minItems` / `maxItems`, `uniqueItems`, `minimum` / `maximum`, `exclusiveMinimum` / `exclusiveMaximum`, `multipleOf`, `minLength` / `maxLength`, `pattern`, `anyOf`, `oneOf`, `allOf`, `not` and local `$ref`s (`#/$defs/...`). Other keywords are ignored.
+
+### Serving the registry over MCP
+
+`createMcpServer(registry, { name, version, send })` (in `/tools`, no dependencies) answers MCP JSON-RPC messages from any transport: stdio lines, a WebSocket, `postMessage` or an HTTP handler. It handles `initialize` (protocol version negotiation), `ping`, `tools/list`, `tools/call` and `notifications/cancelled` (aborts the call's `signal`), and sends `notifications/tools/list_changed` through `send` once the client is initialized.
+
+```ts
+import { createMcpServer } from "@pixerate/editor/tools";
+
+const server = createMcpServer(registry, { name: "my-app", version: "1.0.0", send: (msg) => socket.send(JSON.stringify(msg)) });
+socket.onmessage = async (event) => {
+  const response = await server.handle(event.data);
+  if (response) socket.send(JSON.stringify(response));
+};
+```
 
 ### Without TipTap: `@pixerate/editor/tools`
 
@@ -223,7 +248,7 @@ const list = registry.listTools(); // MCP tools/list result
 const result = await registry.callTool(name, args); // MCP tools/call result
 ```
 
-It exports `ToolRegistry`, `createToolRegistry`, `ToolRegistryError`, the tool types (`AgentTool`, `AgentToolProvider`, `AgentToolHandler`, `ToolCallContext`, `McpToolDefinition`, `McpToolResult`, `McpListToolsResult`, `ToolCallError`), `validateJsonSchema` / `SchemaValidationError`, and the static `EDITOR_MCP_TOOLS` definitions. `/agent` re-exports all of it, so existing imports keep working. `createEditorMcpToolProvider` stays in `/agent` because its `layout` operation runs dagre.
+It exports `ToolRegistry`, `createToolRegistry`, `ToolRegistryError`, the tool types (`AgentTool`, `AgentToolProvider`, `AgentToolHandler`, `ToolCallContext`, `McpToolDefinition`, `McpToolResult`, `McpListToolsResult`, `ToolCallError`), `validateJsonSchema` / `SchemaValidationError`, the static tool definitions (`EDITOR_MCP_TOOLS`, `EDITOR_CANVAS_TOOLS`, `EDITOR_PROMPT_TOOLS`) and `createMcpServer`. `/agent` re-exports all of it, so existing imports keep working. `createEditorMcpToolProvider` stays in `/agent` because its `layout` operation runs dagre.
 
 ## Commands, shortcuts and the command palette
 
@@ -427,9 +452,10 @@ Each module is also available as a subpath import:
 | `@pixerate/editor/export` | Word export: `exportDocx`, `exportDocxBlob`, `createDocxParts`, `DocxExportController`, plus the zip writer and XML escapers it uses (no third-party imports; also re-exported from the root entry) |
 | `@pixerate/editor/tokens` | Design tokens: collections, modes, aliases, `TokenStore`, `resolveToken`, W3C Design Tokens JSON and CSS custom-property export (no third-party imports) |
 | `@pixerate/editor/vector` | Headless vector editor: `VectorDocument` (Bézier paths with corner / smooth / symmetric anchors, groups, gradients), `VectorEditorController` (select, direct select, pen, pencil and shape tools driven by pointer / key events; transforms, booleans, align, group, undo, viewport), scene and overlay render data, DOM-free `parseVectorSvg` / `vectorDocumentToSvg` and `createVectorCommands` for agents (no third-party imports; see [the vector editor guide](../../docs/vector-editor.md)) |
+| `@pixerate/editor/chart` | Headless chart editor: `ChartSpec` (bar, line, area, scatter, pie, donut, combos, stacking) with `normalizeChartSpec`, the DOM-free `layoutChart` scene (drawing primitives with click targets), `ChartController` (data and presentation edits, selection, drag gestures, undo), `chartToSvg`, CSV / table import and `createChartCommands` for agents (no third-party imports; see [the chart editor guide](../../docs/chart-editor.md)) |
 | `@pixerate/editor/parameters` | Schema-driven parameters editor for effects, shaders, generators and component props: `ParameterSchema` (number, int, boolean, choice, color, vector, image and text fields; groups; `showIf`), `ParametersController` (validation, undo with merged slider gestures, reset, randomize, presets, keyframe hooks), `createParameterCommands` for agents and `parameterSchemaFromShaderControls` (no third-party imports) |
 
-The root entry (`@pixerate/editor`) re-exports everything except animation, canvas, agent, commands, persistence, generation, tokens, parameters, vector and image editor, including TipTap. Import from the narrowest subpath you need: `grammar`, `history`, `animation`, `spreadsheet`, `commands`, `persistence` and `image-editor` have no third-party imports, so a spreadsheet-only app bundles no TipTap, markdown or dagre code. The package is marked `sideEffects: false`, so unused root exports are also tree-shaken.
+The root entry (`@pixerate/editor`) re-exports everything except animation, canvas, agent, commands, persistence, generation, tokens, parameters, vector, chart and image editor, including TipTap. Import from the narrowest subpath you need: `grammar`, `history`, `animation`, `spreadsheet`, `commands`, `persistence` and `image-editor` have no third-party imports, so a spreadsheet-only app bundles no TipTap, markdown or dagre code. The package is marked `sideEffects: false`, so unused root exports are also tree-shaken.
 
 ## Keyframe animation without the canvas