@pixerate/editor 0.139.1 → 0.140.0

package/dist/tools/skills.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Agent skill files (`skills/<name>/SKILL.md` plus its `references/*.md`), keyed by
+ * path relative to the skills directory: `pixerate-chart/SKILL.md`,
+ * `pixerate-vector/references/commands.md`. In Node, `loadSkillFiles()` from
+ * `@pixerate/editor/bridge` reads the ones shipped with the package; in a browser,
+ * import them as text (with Vite, `import.meta.glob('…/skills/**\/*.md', { query: '?raw', import: 'default', eager: true })`).
+ */
+export type SkillFiles = Readonly<Record<string, string>>;
+export interface SkillInfo {
+    /** Skill name (its directory), e.g. `pixerate-chart`. */
+    name: string;
+    /** The frontmatter `description`: what the skill covers and when to use it. */
+    description: string;
+    /** Other files of the skill relative to its directory, e.g. `references/commands.md`. */
+    references: string[];
+}
+/** Reads `name` and `description` from a SKILL.md's YAML frontmatter. */
+export declare function parseSkillFrontmatter(markdown: string): {
+    name?: string;
+    description?: string;
+    body: string;
+};
+/** The skills in a set of skill files, sorted by name. */
+export declare function listSkills(files: SkillFiles): SkillInfo[];
+/** One file of a skill (`SKILL.md` by default), or `undefined` if there is none. */
+export declare function readSkillFile(files: SkillFiles, skill: string, file?: string): string | undefined;

package/dist/tools/view.d.cts

@@ -0,0 +1,95 @@
+import type { McpListToolsResult, McpToolDefinition, McpToolResult, ToolSource, ToolsetInfo } from './registry.cjs';
+import { type SkillFiles } from './skills.cjs';
+export interface ToolDiscoveryOptions {
+    /** Toolsets listed from the start (default none: the agent enables what it needs). */
+    enabled?: readonly string[];
+    /** Skill files `get_skill` serves (see {@link SkillFiles}). Without them there is no `get_skill`. */
+    skills?: SkillFiles;
+    /** Default and maximum number of `search_tools` results (default 10, at most 50). */
+    searchLimit?: number;
+}
+export interface ToolViewOptions {
+    /**
+     * Toolsets the agent may see and call (names from `registry.toolsets()`), or a
+     * predicate. Default: all. Change it later with `setToolsets`, e.g. to follow
+     * the focused editor.
+     */
+    toolsets?: readonly string[] | ((toolset: ToolsetInfo) => boolean);
+    /** Only expose tools annotated `readOnlyHint: true`; write tools are refused with the reason. */
+    readOnly?: boolean;
+    /**
+     * Serve discovery tools (`list_toolsets`, `search_tools`, `enable_tools`,
+     * `disable_tools` and, with skills, `get_skill`) and list only the toolsets
+     * and tools that are enabled, so a large catalogue costs the agent a handful
+     * of tool definitions until it asks for more. Tools that are allowed but not
+     * enabled can still be called by name.
+     */
+    discovery?: boolean | ToolDiscoveryOptions;
+}
+/** Names of the tools a discovery view adds. */
+export declare const TOOL_DISCOVERY_TOOLS: readonly ["list_toolsets", "search_tools", "enable_tools", "disable_tools", "get_skill"];
+/**
+ * A filtered view of a {@link ToolSource} (usually a `ToolRegistry`, from
+ * `registry.view()`) that is itself a `ToolSource`, so `createMcpServer`,
+ * `connectToolBridge` and further views accept it.
+ *
+ * - **Scope** an agent to some toolsets (`toolsets`) or to read tools
+ *   (`readOnly`). Tools outside the scope are neither listed nor callable.
+ * - **Discover** (`discovery`): list only what the agent enabled, plus tools to
+ *   browse and search the rest and to enable it. `listChanged` fires whenever
+ *   the listing changes.
+ */
+export declare class ToolRegistryView implements ToolSource {
+    private readonly source;
+    readonly capabilities: {
+        readonly tools: {
+            readonly listChanged: true;
+        };
+    };
+    private allow;
+    private readonly readOnly;
+    private readonly discovery;
+    private readonly enabledSets;
+    private readonly enabledTools;
+    private readonly listeners;
+    private readonly meta;
+    private unsubscribe;
+    private lastSignature;
+    constructor(source: ToolSource, options?: ToolViewOptions);
+    /** Changes which toolsets the agent may use (`undefined`: all). Fires `listChanged` if the listing changes. */
+    setToolsets(toolsets: ToolViewOptions['toolsets']): void;
+    /**
+     * Lists more tools in a discovery view, as the `enable_tools` tool does.
+     * Throws for names the view does not allow. Returns the tool names newly listed.
+     */
+    enableTools(selection: {
+        tools?: readonly string[];
+        toolsets?: readonly string[];
+    }): string[];
+    /** Stops listing tools in a discovery view, as `disable_tools` does. Returns the tool names no longer listed. */
+    disableTools(selection: {
+        tools?: readonly string[];
+        toolsets?: readonly string[];
+    }): string[];
+    /** Allowed toolsets, each with only its allowed tools. */
+    toolsets(): ToolsetInfo[];
+    listTools(): McpListToolsResult;
+    hasTool(name: string): boolean;
+    getTool(name: string): McpToolDefinition | undefined;
+    callTool(name: string, args?: Record<string, unknown>, options?: {
+        signal?: AbortSignal;
+    }): Promise<McpToolResult>;
+    onListChanged(listener: (tools: McpToolDefinition[]) => void): () => void;
+    /** Stops following the source and drops every listener. */
+    dispose(): void;
+    private changed;
+    private signature;
+    private allowsSet;
+    private catalogue;
+    private listed;
+    /** Resolves an exposed or unique bare name among the allowed tools, or explains why it isn't one. */
+    private find;
+    /** Normalizes names to exposed tool and toolset names, or throws naming every unknown one. */
+    private checkSelection;
+    private createDiscoveryTools;
+}

package/dist/tools/view.d.ts

@@ -0,0 +1,95 @@
+import type { McpListToolsResult, McpToolDefinition, McpToolResult, ToolSource, ToolsetInfo } from './registry.js';
+import { type SkillFiles } from './skills.js';
+export interface ToolDiscoveryOptions {
+    /** Toolsets listed from the start (default none: the agent enables what it needs). */
+    enabled?: readonly string[];
+    /** Skill files `get_skill` serves (see {@link SkillFiles}). Without them there is no `get_skill`. */
+    skills?: SkillFiles;
+    /** Default and maximum number of `search_tools` results (default 10, at most 50). */
+    searchLimit?: number;
+}
+export interface ToolViewOptions {
+    /**
+     * Toolsets the agent may see and call (names from `registry.toolsets()`), or a
+     * predicate. Default: all. Change it later with `setToolsets`, e.g. to follow
+     * the focused editor.
+     */
+    toolsets?: readonly string[] | ((toolset: ToolsetInfo) => boolean);
+    /** Only expose tools annotated `readOnlyHint: true`; write tools are refused with the reason. */
+    readOnly?: boolean;
+    /**
+     * Serve discovery tools (`list_toolsets`, `search_tools`, `enable_tools`,
+     * `disable_tools` and, with skills, `get_skill`) and list only the toolsets
+     * and tools that are enabled, so a large catalogue costs the agent a handful
+     * of tool definitions until it asks for more. Tools that are allowed but not
+     * enabled can still be called by name.
+     */
+    discovery?: boolean | ToolDiscoveryOptions;
+}
+/** Names of the tools a discovery view adds. */
+export declare const TOOL_DISCOVERY_TOOLS: readonly ["list_toolsets", "search_tools", "enable_tools", "disable_tools", "get_skill"];
+/**
+ * A filtered view of a {@link ToolSource} (usually a `ToolRegistry`, from
+ * `registry.view()`) that is itself a `ToolSource`, so `createMcpServer`,
+ * `connectToolBridge` and further views accept it.
+ *
+ * - **Scope** an agent to some toolsets (`toolsets`) or to read tools
+ *   (`readOnly`). Tools outside the scope are neither listed nor callable.
+ * - **Discover** (`discovery`): list only what the agent enabled, plus tools to
+ *   browse and search the rest and to enable it. `listChanged` fires whenever
+ *   the listing changes.
+ */
+export declare class ToolRegistryView implements ToolSource {
+    private readonly source;
+    readonly capabilities: {
+        readonly tools: {
+            readonly listChanged: true;
+        };
+    };
+    private allow;
+    private readonly readOnly;
+    private readonly discovery;
+    private readonly enabledSets;
+    private readonly enabledTools;
+    private readonly listeners;
+    private readonly meta;
+    private unsubscribe;
+    private lastSignature;
+    constructor(source: ToolSource, options?: ToolViewOptions);
+    /** Changes which toolsets the agent may use (`undefined`: all). Fires `listChanged` if the listing changes. */
+    setToolsets(toolsets: ToolViewOptions['toolsets']): void;
+    /**
+     * Lists more tools in a discovery view, as the `enable_tools` tool does.
+     * Throws for names the view does not allow. Returns the tool names newly listed.
+     */
+    enableTools(selection: {
+        tools?: readonly string[];
+        toolsets?: readonly string[];
+    }): string[];
+    /** Stops listing tools in a discovery view, as `disable_tools` does. Returns the tool names no longer listed. */
+    disableTools(selection: {
+        tools?: readonly string[];
+        toolsets?: readonly string[];
+    }): string[];
+    /** Allowed toolsets, each with only its allowed tools. */
+    toolsets(): ToolsetInfo[];
+    listTools(): McpListToolsResult;
+    hasTool(name: string): boolean;
+    getTool(name: string): McpToolDefinition | undefined;
+    callTool(name: string, args?: Record<string, unknown>, options?: {
+        signal?: AbortSignal;
+    }): Promise<McpToolResult>;
+    onListChanged(listener: (tools: McpToolDefinition[]) => void): () => void;
+    /** Stops following the source and drops every listener. */
+    dispose(): void;
+    private changed;
+    private signature;
+    private allowsSet;
+    private catalogue;
+    private listed;
+    /** Resolves an exposed or unique bare name among the allowed tools, or explains why it isn't one. */
+    private find;
+    /** Normalizes names to exposed tool and toolset names, or throws naming every unknown one. */
+    private checkSelection;
+    private createDiscoveryTools;
+}

package/dist/vector/effect-tools.d.cts

@@ -9,7 +9,7 @@ import type { VectorEditorController } from './controller.cjs';
 export interface VectorEffectsToolProviderOptions {
     /** Provider id (unique per registry). Default `vector-effects`. */
     id?: string;
-    /** Always prefix tool names with `<namespace>__`. */
+    /** Tool-name prefix (`<namespace>__<name>`); defaults to the provider id, `''` for bare names. */
     namespace?: string;
     /** The document cannot be edited: write tools are hidden. A string is the reason. */
     readOnly?: boolean | string | (() => boolean | string);

package/dist/vector/effect-tools.d.ts

@@ -9,7 +9,7 @@ import type { VectorEditorController } from './controller.js';
 export interface VectorEffectsToolProviderOptions {
     /** Provider id (unique per registry). Default `vector-effects`. */
     id?: string;
-    /** Always prefix tool names with `<namespace>__`. */
+    /** Tool-name prefix (`<namespace>__<name>`); defaults to the provider id, `''` for bare names. */
     namespace?: string;
     /** The document cannot be edited: write tools are hidden. A string is the reason. */
     readOnly?: boolean | string | (() => boolean | string);

package/dist/vector/index.cjs

@@ -541,7 +541,7 @@ var _chunkNM3G4VQTcjs = require('../chunk-NM3G4VQT.cjs');
 
 
 
-var _chunk3V746PF4cjs = require('../chunk-3V746PF4.cjs');
+var _chunkRUZQMYXHcjs = require('../chunk-RUZQMYXH.cjs');
 require('../chunk-WOFXZ3XU.cjs');
 
 
@@ -7968,7 +7968,7 @@ var VectorEditorController = (_class7 = class _VectorEditorController {
   }
   // --- Provider effects ---
   /** The effects provider slot (see `setEffectsProvider`). */
-  __init59() {this.effects = new (0, _chunk3V746PF4cjs.EffectsSlot)()}
+  __init59() {this.effects = new (0, _chunkRUZQMYXHcjs.EffectsSlot)()}
   /** The registered effects provider, or `null`. */
   get effectsProvider() {
     return this.effects.provider;
@@ -7992,10 +7992,10 @@ var VectorEditorController = (_class7 = class _VectorEditorController {
   /** The effect's picture as group children, scaled into `box` (an affine fit). */
   async vectorEffectPicture(effect, values) {
     const provider = this.effects.require();
-    if (!provider.applyVectorEffect) throw new (0, _chunk3V746PF4cjs.EffectUnsupportedError)(`${provider.name} has no vector effects.`);
+    if (!provider.applyVectorEffect) throw new (0, _chunkRUZQMYXHcjs.EffectUnsupportedError)(`${provider.name} has no vector effects.`);
     const d = await provider.describe(effect);
-    if (d.kind !== "vector") throw new (0, _chunk3V746PF4cjs.EffectUnsupportedError)(`"${d.id}" (${d.name}) is a ${d.kind} effect; the vector editor adds vector effects, which bring their own picture${d.kind === "motion" ? " (apply motion in the animation editor)" : ""}.`, d.id);
-    const resolved = _chunk3V746PF4cjs.resolveEffectValues.call(void 0, d, values);
+    if (d.kind !== "vector") throw new (0, _chunkRUZQMYXHcjs.EffectUnsupportedError)(`"${d.id}" (${d.name}) is a ${d.kind} effect; the vector editor adds vector effects, which bring their own picture${d.kind === "motion" ? " (apply motion in the animation editor)" : ""}.`, d.id);
+    const resolved = _chunkRUZQMYXHcjs.resolveEffectValues.call(void 0, d, values);
     const motion = await provider.applyVectorEffect(d.id, this.toSvg(), resolved);
     const parsed = _chunkRCUX6CT2cjs.parseVectorSvg.call(void 0, motion.svg);
     if (!parsed.nodes.length) throw new Error(`"${d.name}" drew no shapes the editor can read.`);
@@ -18396,7 +18396,10 @@ function createVectorGenerationToolProvider(controller, options) {
   };
   return {
     id: _nullishCoalesce(options.id, () => ( "vector-generation")),
-    ...options.namespace ? { namespace: options.namespace } : {},
+    ...options.namespace !== void 0 ? { namespace: options.namespace } : {},
+    title: "Vector generation",
+    description: "Generate vector art from a prompt with a configured model, and regenerate it.",
+    skill: "pixerate-vector",
     tools: () => readOnly() ? [list] : [list, generate, regenerate],
     // The write tools come and go with a read-only state that can change.
     ...typeof options.readOnly === "function" ? { subscribe: (notify) => controller.subscribe(() => notify()) } : {}
@@ -18551,9 +18554,12 @@ function createVectorEffectsToolProvider(controller, options = {}) {
     const effects = _optionalChain([g, 'optionalAccess', _753 => _753.providerEffect]) ? [info(g)] : [];
     return { target: id, effect: _nullishCoalesce(removed, () => ( effects[0])), effects };
   };
-  return _chunk3V746PF4cjs.createEffectToolProvider.call(void 0, {
+  return _chunkRUZQMYXHcjs.createEffectToolProvider.call(void 0, {
     id: _nullishCoalesce(options.id, () => ( "vector-effects")),
     namespace: options.namespace,
+    title: "Vector effects",
+    description: "Provider effects placed in the vector document as effect groups.",
+    skill: "pixerate-vector",
     target: { noun: "group", id: `For apply_effect: "document" for the top level, or a group id to put the picture in. For update_effect and remove_effect: the effect group's id from list_applied_effects.` },
     applyUses: ["title", "overlay", "generator", "interactive"],
     applyDetails: `Only vector effects (kind vector: lower thirds, stickers, loaders, badges) can be added: the effect's SVG at rest becomes a group of editable shapes, fitted into the middle half of the document and selected; move or scale it like any group. Its motion plays in the animation editor (add_vector_effect there). update_effect with effect "picture" draws it again with new values; remove_effect keeps the shapes as a plain group. index, enabled and opacity do not apply.`,

package/dist/vector/index.js

@@ -541,7 +541,7 @@ import {
   EffectsSlot,
   createEffectToolProvider,
   resolveEffectValues
-} from "../chunk-KHMVB3SJ.js";
+} from "../chunk-7KWJEYIK.js";
 import "../chunk-V2ZCJRDM.js";
 import {
   GRAIN_PATTERNS
@@ -18396,7 +18396,10 @@ function createVectorGenerationToolProvider(controller, options) {
   };
   return {
     id: options.id ?? "vector-generation",
-    ...options.namespace ? { namespace: options.namespace } : {},
+    ...options.namespace !== void 0 ? { namespace: options.namespace } : {},
+    title: "Vector generation",
+    description: "Generate vector art from a prompt with a configured model, and regenerate it.",
+    skill: "pixerate-vector",
     tools: () => readOnly() ? [list] : [list, generate, regenerate],
     // The write tools come and go with a read-only state that can change.
     ...typeof options.readOnly === "function" ? { subscribe: (notify) => controller.subscribe(() => notify()) } : {}
@@ -18554,6 +18557,9 @@ function createVectorEffectsToolProvider(controller, options = {}) {
   return createEffectToolProvider({
     id: options.id ?? "vector-effects",
     namespace: options.namespace,
+    title: "Vector effects",
+    description: "Provider effects placed in the vector document as effect groups.",
+    skill: "pixerate-vector",
     target: { noun: "group", id: `For apply_effect: "document" for the top level, or a group id to put the picture in. For update_effect and remove_effect: the effect group's id from list_applied_effects.` },
     applyUses: ["title", "overlay", "generator", "interactive"],
     applyDetails: `Only vector effects (kind vector: lower thirds, stickers, loaders, badges) can be added: the effect's SVG at rest becomes a group of editable shapes, fitted into the middle half of the document and selected; move or scale it like any group. Its motion plays in the animation editor (add_vector_effect there). update_effect with effect "picture" draws it again with new values; remove_effect keeps the shapes as a plain group. index, enabled and opacity do not apply.`,

package/dist/video-editor/effect-tools.d.cts

@@ -11,7 +11,7 @@ import { type VideoClip } from './types.cjs';
 export interface VideoEffectsToolProviderOptions {
     /** Provider id (unique per registry). Default `video-effects`. */
     id?: string;
-    /** Always prefix tool names with `<namespace>__`. */
+    /** Tool-name prefix (`<namespace>__<name>`); defaults to the provider id, `''` for bare names. */
     namespace?: string;
     /** The project cannot be edited: write tools are hidden. A string is the reason. */
     readOnly?: boolean | string | (() => boolean | string);

package/dist/video-editor/effect-tools.d.ts

@@ -11,7 +11,7 @@ import { type VideoClip } from './types.js';
 export interface VideoEffectsToolProviderOptions {
     /** Provider id (unique per registry). Default `video-effects`. */
     id?: string;
-    /** Always prefix tool names with `<namespace>__`. */
+    /** Tool-name prefix (`<namespace>__<name>`); defaults to the provider id, `''` for bare names. */
     namespace?: string;
     /** The project cannot be edited: write tools are hidden. A string is the reason. */
     readOnly?: boolean | string | (() => boolean | string);