@pixerate/editor 0.139.1 → 0.140.0

package/README.md

@@ -193,7 +193,9 @@ registerImportAdapter({
 
 ## Agent tool registry
 
-`ToolRegistry` (`@pixerate/editor/agent`) collects MCP-shaped tools from live providers, for example one per mounted editor or spreadsheet. `listTools()` and `callTool()` return MCP `tools/list` / `tools/call` result shapes, arguments are validated against each tool's `inputSchema`, and `onListChanged` fires (coalesced) when providers come and go. Colliding names are namespaced as `<providerId>__<name>`.
+`ToolRegistry` (`@pixerate/editor/agent`) collects MCP-shaped tools from live providers, for example one per mounted editor or spreadsheet. `listTools()` and `callTool()` return MCP `tools/list` / `tools/call` result shapes, arguments are validated against each tool's `inputSchema`, and `onListChanged` fires (coalesced) when providers come and go.
+
+Each provider is a toolset. Its tools are exposed as `<namespace>__<name>`, where the namespace is the provider's `namespace` or else its `id` (`doc__get_text`, `sheet__set_range`), so a name never changes when another editor mounts. `callTool`, `hasTool` and `getTool` also take the bare name when only one tool has it. Pass `namespace: ''` on a provider for bare names (prefixed with the id only on a collision), or `new ToolRegistry({ namespaces: 'on-collision' })` for that across the registry. Providers also carry a `title`, `description` and `skill`, which `registry.toolsets()` reports.
 
 ```ts
 import { ToolRegistry, createRichTextToolProvider, createSpreadsheetToolProvider } from "@pixerate/editor/agent";
@@ -203,14 +205,33 @@ const unregister = registry.register(createRichTextToolProvider(controller, { id
 registry.register(createSpreadsheetToolProvider(sheet, { id: "sheet", namespace: "sheet" }));
 registry.onListChanged((tools) => server.sendToolListChanged());
 
-await registry.callTool("insert_text", { text: "Hello" }); // { content: [...], structuredContent }
+await registry.callTool("doc__insert_text", { text: "Hello" }); // { content: [...], structuredContent }
 ```
 
+### Large catalogues: scoped views and discovery
+
+With every editor mounted the registry holds hundreds of tools, which costs a model context and makes the right one harder to pick. `registry.view(options)` is a filtered tool source to serve instead:
+
+- `toolsets: ['chart']` (or a predicate) shows only those toolsets; call `view.setToolsets()` as the user switches editors.
+- `readOnly: true` shows only tools annotated `readOnlyHint`. Tools outside a view are refused with the reason.
+- `discovery: { skills }` lists only `list_toolsets`, `search_tools`, `enable_tools`, `disable_tools` and (with skill files) `get_skill` at first. The agent searches by task, enables the tools it needs, and the view announces each change through `onListChanged`. `searchTools(tools, toolsets, query)` is the ranking `search_tools` uses.
+
+```ts
+import { createMcpServer, toolsetInstructions } from "@pixerate/editor/tools";
+import { loadSkillFiles } from "@pixerate/editor/bridge"; // Node; in a browser import the .md files as text
+
+const skills = loadSkillFiles();
+const view = registry.view({ discovery: { skills } });
+const server = createMcpServer(view, { name: "my-app", version: "1.0.0", instructions: toolsetInstructions, skills, send });
+```
+
+`createMcpServer({ skills })` also serves the skills as MCP prompts and `skill://<name>/SKILL.md` resources. `useToolRegistryView` (React and Svelte) makes a view for a component's lifetime, and `useToolBridge` accepts one.
+
 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`. |
+| `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`, `format_text` (inline marks: bold, italic, links, colour…), `set_block_type` (paragraph, heading, lists, quote, code block), `set_text_align` (each as far as the schema supports it), `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`, `merge_cells`, `unmerge_cells`, `transpose_range` (on an A1 range, not the user's selection) |
 | `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 |
@@ -221,7 +242,7 @@ Tool `inputSchema`s are validated by `validateJsonSchema`, which supports `type`
 
 ### 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.
+`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`, with `skills` `resources/list` / `resources/read` / `prompts/list` / `prompts/get`, 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";

package/dist/agent/formatTools.d.cts

@@ -0,0 +1,15 @@
+import type { Editor } from '@tiptap/core';
+import type { AgentTool } from '../tools/registry.cjs';
+/**
+ * The formatting tools for a rich-text editor: `format_text` (inline marks), `set_block_type`
+ * (paragraphs, headings, lists, quotes, code blocks) and `set_text_align`, each listed only when
+ * the editor's schema has something for it to do. Each call is one undo step, leaves the
+ * user's selection where it was, and returns the range it changed with its formatting after.
+ */
+export declare function createDocumentFormatTools(editor: () => Editor, changed: (ranges: Array<{
+    from: number;
+    to: number;
+}>) => void): {
+    /** The formatting tools this editor's schema supports. */
+    tools(ed: Editor): AgentTool[];
+};

package/dist/agent/formatTools.d.ts

@@ -0,0 +1,15 @@
+import type { Editor } from '@tiptap/core';
+import type { AgentTool } from '../tools/registry.js';
+/**
+ * The formatting tools for a rich-text editor: `format_text` (inline marks), `set_block_type`
+ * (paragraphs, headings, lists, quotes, code blocks) and `set_text_align`, each listed only when
+ * the editor's schema has something for it to do. Each call is one undo step, leaves the
+ * user's selection where it was, and returns the range it changed with its formatting after.
+ */
+export declare function createDocumentFormatTools(editor: () => Editor, changed: (ranges: Array<{
+    from: number;
+    to: number;
+}>) => void): {
+    /** The formatting tools this editor's schema supports. */
+    tools(ed: Editor): AgentTool[];
+};