@pixerate/editor 0.148.0 → 0.150.0

package/dist/paint-editor/index.js

@@ -53,7 +53,7 @@ import {
   PresenceStore,
   realPresenceClock,
   tweenPresenceCursor
-} from "../chunk-PEEP2YR7.js";
+} from "../chunk-O2ANJFUF.js";
 import "../chunk-FLOGD3QB.js";
 import {
   BRUSH_ID,
@@ -6046,7 +6046,7 @@ function withPaintPlayback(provider, options) {
   const tools = provider.tools;
   return {
     ...provider,
-    playbackSurface: provider.playbackSurface ?? options.surface ?? "paint",
+    playbackSurface: options.surface ?? provider.playbackSurface ?? "paint",
     tools: typeof tools === "function" ? () => tools().map(plan) : tools.map(plan)
   };
 }
@@ -7836,7 +7836,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
     description: "Natural-media painting: paper and grain, dry and wet brushes, the brush library, strokes as data, pigment mixing, stencils, guides, layers and export.",
     skill: "pixerate-paint-editor",
     tools
-  }, { director: !!options.director });
+  }, { director: !!options.director, surface: options.playbackSurface });
 }
 
 // src/paint-editor/ui.ts
@@ -8554,7 +8554,7 @@ function createPaintEffectsToolProvider(controller, options = {}) {
         }
       }
     ]
-  }), { director: false });
+  }), { director: false, surface: options.playbackSurface });
 }
 export {
   BLEND_MENU_GROUPS,

package/dist/paint-editor/playback.d.cts

@@ -7,8 +7,8 @@ export declare function paintPlaybackPanel(tool: string): PaintPlaybackPanel | n
 /** The cursor steps for one paint tool call (by bare name), or null to fall back to the ids it names. */
 export declare function planPaintToolPlayback(tool: string, _args: Record<string, any>): PlaybackStep[] | null;
 /**
- * Gives a paint tool provider agent playback on `surface` (default `paint`, where `PaintEditor`
- * attaches). With a director, strokes, fills and replays play through it (`playback: 'self'`).
+ * Gives a paint tool provider agent playback on `surface`. An explicit `surface` wins over the
+ * provider's own `playbackSurface`; with neither, it is `paint` (where `PaintEditor` attaches). With a director, strokes, fills and replays play through it (`playback: 'self'`).
  */
 export declare function withPaintPlayback(provider: AgentToolProvider, options: {
     director: boolean;

package/dist/paint-editor/playback.d.ts

@@ -7,8 +7,8 @@ export declare function paintPlaybackPanel(tool: string): PaintPlaybackPanel | n
 /** The cursor steps for one paint tool call (by bare name), or null to fall back to the ids it names. */
 export declare function planPaintToolPlayback(tool: string, _args: Record<string, any>): PlaybackStep[] | null;
 /**
- * Gives a paint tool provider agent playback on `surface` (default `paint`, where `PaintEditor`
- * attaches). With a director, strokes, fills and replays play through it (`playback: 'self'`).
+ * Gives a paint tool provider agent playback on `surface`. An explicit `surface` wins over the
+ * provider's own `playbackSurface`; with neither, it is `paint` (where `PaintEditor` attaches). With a director, strokes, fills and replays play through it (`playback: 'self'`).
  */
 export declare function withPaintPlayback(provider: AgentToolProvider, options: {
     director: boolean;

package/dist/paint-editor/tools.d.cts

@@ -20,6 +20,11 @@ export interface PaintEditorToolProviderOptions {
     director?: PaintDirector;
     /** The agent's cursor (default `{ id: 'agent', name: 'Agent' }`). */
     actor?: PresenceActorInfo;
+    /**
+     * The agent playback surface its calls are acted out on (default `paint`, where `PaintEditor` attaches).
+     * Set it when one registry holds several editors of this kind, each attached under its own surface id.
+     */
+    playbackSurface?: string;
 }
 /** Agent tools for one paint editor. */
 export declare function createPaintEditorToolProvider(controller: PaintEditorController, options?: PaintEditorToolProviderOptions): AgentToolProvider;

package/dist/paint-editor/tools.d.ts

@@ -20,6 +20,11 @@ export interface PaintEditorToolProviderOptions {
     director?: PaintDirector;
     /** The agent's cursor (default `{ id: 'agent', name: 'Agent' }`). */
     actor?: PresenceActorInfo;
+    /**
+     * The agent playback surface its calls are acted out on (default `paint`, where `PaintEditor` attaches).
+     * Set it when one registry holds several editors of this kind, each attached under its own surface id.
+     */
+    playbackSurface?: string;
 }
 /** Agent tools for one paint editor. */
 export declare function createPaintEditorToolProvider(controller: PaintEditorController, options?: PaintEditorToolProviderOptions): AgentToolProvider;

package/dist/tools/index.cjs

@@ -2,7 +2,7 @@
 
 
 
-var _chunkAG2EXVCRcjs = require('../chunk-AG2EXVCR.cjs');
+var _chunkERAGQL2Ncjs = require('../chunk-ERAGQL2N.cjs');
 
 
 
@@ -38,7 +38,9 @@ var _chunkY4BWZB6Jcjs = require('../chunk-Y4BWZB6J.cjs');
 
 
 
-var _chunkD2ENR3LBcjs = require('../chunk-D2ENR3LB.cjs');
+
+
+var _chunkGMWNBSBScjs = require('../chunk-GMWNBSBS.cjs');
 
 
 
@@ -88,7 +90,8 @@ var _chunk2BSBFBOAcjs = require('../chunk-2BSBFBOA.cjs');
 
 
 
-var _chunkUJGAA6AKcjs = require('../chunk-UJGAA6AK.cjs');
+
+var _chunkSWTUM32Hcjs = require('../chunk-SWTUM32H.cjs');
 
 
 var _chunkWOFXZ3XUcjs = require('../chunk-WOFXZ3XU.cjs');
@@ -171,4 +174,7 @@ var _chunkWOFXZ3XUcjs = require('../chunk-WOFXZ3XU.cjs');
 
 
 
-exports.AgentPlayback = _chunkD2ENR3LBcjs.AgentPlayback; exports.CAPTURE_EXCLUDE_SELECTOR = _chunkSVFEVKLFcjs.CAPTURE_EXCLUDE_SELECTOR; exports.CAPTURE_OVERLAY_SELECTORS = _chunkSVFEVKLFcjs.CAPTURE_OVERLAY_SELECTORS; exports.EDITOR_CANVAS_TOOLS = _chunkSVFEVKLFcjs.EDITOR_CANVAS_TOOLS; exports.EDITOR_MCP_TOOLS = _chunkSVFEVKLFcjs.EDITOR_MCP_TOOLS; exports.EDITOR_PROMPT_TOOLS = _chunkSVFEVKLFcjs.EDITOR_PROMPT_TOOLS; exports.EDIT_OPERATION_REQUIRED_ARGUMENTS = _chunkSVFEVKLFcjs.EDIT_OPERATION_REQUIRED_ARGUMENTS; exports.EXPORT_EXCLUDED_SELECTORS = _chunkSVFEVKLFcjs.EXPORT_EXCLUDED_SELECTORS; exports.JSON_RPC_ERRORS = _chunkY4BWZB6Jcjs.JSON_RPC_ERRORS; exports.MCP_PROTOCOL_VERSIONS = _chunkY4BWZB6Jcjs.MCP_PROTOCOL_VERSIONS; exports.MCP_TOOL_CANVAS_ADD_NODE = _chunkSVFEVKLFcjs.MCP_TOOL_CANVAS_ADD_NODE; exports.MCP_TOOL_CANVAS_CONNECT = _chunkSVFEVKLFcjs.MCP_TOOL_CANVAS_CONNECT; exports.MCP_TOOL_CANVAS_HIGHLIGHT = _chunkSVFEVKLFcjs.MCP_TOOL_CANVAS_HIGHLIGHT; exports.MCP_TOOL_CANVAS_LAYOUT = _chunkSVFEVKLFcjs.MCP_TOOL_CANVAS_LAYOUT; exports.MCP_TOOL_CANVAS_REMOVE_NODES = _chunkSVFEVKLFcjs.MCP_TOOL_CANVAS_REMOVE_NODES; exports.MCP_TOOL_CANVAS_SELECT = _chunkSVFEVKLFcjs.MCP_TOOL_CANVAS_SELECT; exports.MCP_TOOL_CANVAS_UPDATE_NODE = _chunkSVFEVKLFcjs.MCP_TOOL_CANVAS_UPDATE_NODE; exports.MCP_TOOL_EDIT_CANVAS = _chunkSVFEVKLFcjs.MCP_TOOL_EDIT_CANVAS; exports.MCP_TOOL_EDIT_PROMPT = _chunkSVFEVKLFcjs.MCP_TOOL_EDIT_PROMPT; exports.MCP_TOOL_GET_EDITOR_STATE = _chunkSVFEVKLFcjs.MCP_TOOL_GET_EDITOR_STATE; exports.MCP_TOOL_PROMPT_INSERT_TEXT = _chunkSVFEVKLFcjs.MCP_TOOL_PROMPT_INSERT_TEXT; exports.MCP_TOOL_PROMPT_REPLACE_RANGE = _chunkSVFEVKLFcjs.MCP_TOOL_PROMPT_REPLACE_RANGE; exports.MCP_TOOL_PROMPT_SELECT = _chunkSVFEVKLFcjs.MCP_TOOL_PROMPT_SELECT; exports.MCP_TOOL_PROMPT_SET_VARIABLE = _chunkSVFEVKLFcjs.MCP_TOOL_PROMPT_SET_VARIABLE; exports.MCP_TOOL_VIEW_EDITOR = _chunkSVFEVKLFcjs.MCP_TOOL_VIEW_EDITOR; exports.PRESENCE_COLORS = _chunkUJGAA6AKcjs.PRESENCE_COLORS; exports.PerformanceQueue = _chunkUJGAA6AKcjs.PerformanceQueue; exports.PresenceStore = _chunkUJGAA6AKcjs.PresenceStore; exports.TOOL_BRIDGE_DEFAULT_PORT = _chunkY4BWZB6Jcjs.TOOL_BRIDGE_DEFAULT_PORT; exports.TOOL_BRIDGE_PROTOCOL = _chunkY4BWZB6Jcjs.TOOL_BRIDGE_PROTOCOL; exports.TOOL_DISCOVERY_TOOLS = _chunkY4BWZB6Jcjs.TOOL_DISCOVERY_TOOLS; exports.TOOL_NAMESPACE_SEPARATOR = _chunkY4BWZB6Jcjs.TOOL_NAMESPACE_SEPARATOR; exports.ToolRegistry = _chunkY4BWZB6Jcjs.ToolRegistry; exports.ToolRegistryError = _chunkY4BWZB6Jcjs.ToolRegistryError; exports.ToolRegistryView = _chunkY4BWZB6Jcjs.ToolRegistryView; exports.UNSAFE_JSON_KEYS = _chunk2BSBFBOAcjs.UNSAFE_JSON_KEYS; exports.baseToolName = _chunkY4BWZB6Jcjs.baseToolName; exports.captureInputSchema = _chunkN2FGYZ4Qcjs.captureInputSchema; exports.captureOutputSize = _chunkN2FGYZ4Qcjs.captureOutputSize; exports.cloneElementWithStyles = _chunkSVFEVKLFcjs.cloneElementWithStyles; exports.connectToolBridge = _chunkY4BWZB6Jcjs.connectToolBridge; exports.createAgentPlayback = _chunkD2ENR3LBcjs.createAgentPlayback; exports.createCaptureTool = _chunkN2FGYZ4Qcjs.createCaptureTool; exports.createCaptureToolProvider = _chunkN2FGYZ4Qcjs.createCaptureToolProvider; exports.createElementCaptureSurface = _chunkSVFEVKLFcjs.createElementCaptureSurface; exports.createInstantPresenceClock = _chunkUJGAA6AKcjs.createInstantPresenceClock; exports.createMcpServer = _chunkY4BWZB6Jcjs.createMcpServer; exports.createPlaybackToolProvider = _chunkD2ENR3LBcjs.createPlaybackToolProvider; exports.createToolRegistry = _chunkY4BWZB6Jcjs.createToolRegistry; exports.derivePlaybackSteps = _chunkD2ENR3LBcjs.derivePlaybackSteps; exports.elementToSvg = _chunkSVFEVKLFcjs.elementToSvg; exports.errorResult = _chunkY4BWZB6Jcjs.errorResult; exports.isUnsafeJsonKey = _chunk2BSBFBOAcjs.isUnsafeJsonKey; exports.listSkills = _chunkY4BWZB6Jcjs.listSkills; exports.parseSkillFrontmatter = _chunkY4BWZB6Jcjs.parseSkillFrontmatter; exports.playbackRefsFromArgs = _chunkD2ENR3LBcjs.playbackRefsFromArgs; exports.playbackRefsFromResult = _chunkD2ENR3LBcjs.playbackRefsFromResult; exports.rasterizeElement = _chunkSVFEVKLFcjs.rasterizeElement; exports.readSkillFile = _chunkY4BWZB6Jcjs.readSkillFile; exports.readingTime = _chunkD2ENR3LBcjs.readingTime; exports.realPresenceClock = _chunkUJGAA6AKcjs.realPresenceClock; exports.resolveCaptureRequest = _chunkN2FGYZ4Qcjs.resolveCaptureRequest; exports.runToolScript = _chunkAG2EXVCRcjs.runToolScript; exports.searchTokens = _chunkY4BWZB6Jcjs.searchTokens; exports.searchTools = _chunkY4BWZB6Jcjs.searchTools; exports.stripPrototypeKeys = _chunk2BSBFBOAcjs.stripPrototypeKeys; exports.summarize = _chunkY4BWZB6Jcjs.summarize; exports.toCapturedImageData = _chunkN2FGYZ4Qcjs.toCapturedImageData; exports.toToolResult = _chunkY4BWZB6Jcjs.toToolResult; exports.toolResultError = _chunkAG2EXVCRcjs.toolResultError; exports.toolResultValue = _chunkAG2EXVCRcjs.toolResultValue; exports.toolsetInstructions = _chunkY4BWZB6Jcjs.toolsetInstructions; exports.toolsetName = _chunkY4BWZB6Jcjs.toolsetName; exports.tweenPresenceCursor = _chunkUJGAA6AKcjs.tweenPresenceCursor; exports.unionCaptureRects = _chunkN2FGYZ4Qcjs.unionCaptureRects; exports.unionRects = _chunkD2ENR3LBcjs.unionRects; exports.unknownToolMessage = _chunkY4BWZB6Jcjs.unknownToolMessage; exports.validateJsonSchema = _chunkWOFXZ3XUcjs.validateJsonSchema;
+
+
+
+exports.AgentPlayback = _chunkGMWNBSBScjs.AgentPlayback; exports.CAPTURE_EXCLUDE_SELECTOR = _chunkSVFEVKLFcjs.CAPTURE_EXCLUDE_SELECTOR; exports.CAPTURE_OVERLAY_SELECTORS = _chunkSVFEVKLFcjs.CAPTURE_OVERLAY_SELECTORS; exports.EDITOR_CANVAS_TOOLS = _chunkSVFEVKLFcjs.EDITOR_CANVAS_TOOLS; exports.EDITOR_MCP_TOOLS = _chunkSVFEVKLFcjs.EDITOR_MCP_TOOLS; exports.EDITOR_PROMPT_TOOLS = _chunkSVFEVKLFcjs.EDITOR_PROMPT_TOOLS; exports.EDIT_OPERATION_REQUIRED_ARGUMENTS = _chunkSVFEVKLFcjs.EDIT_OPERATION_REQUIRED_ARGUMENTS; exports.EXPORT_EXCLUDED_SELECTORS = _chunkSVFEVKLFcjs.EXPORT_EXCLUDED_SELECTORS; exports.JSON_RPC_ERRORS = _chunkY4BWZB6Jcjs.JSON_RPC_ERRORS; exports.MCP_PROTOCOL_VERSIONS = _chunkY4BWZB6Jcjs.MCP_PROTOCOL_VERSIONS; exports.MCP_TOOL_CANVAS_ADD_NODE = _chunkSVFEVKLFcjs.MCP_TOOL_CANVAS_ADD_NODE; exports.MCP_TOOL_CANVAS_CONNECT = _chunkSVFEVKLFcjs.MCP_TOOL_CANVAS_CONNECT; exports.MCP_TOOL_CANVAS_HIGHLIGHT = _chunkSVFEVKLFcjs.MCP_TOOL_CANVAS_HIGHLIGHT; exports.MCP_TOOL_CANVAS_LAYOUT = _chunkSVFEVKLFcjs.MCP_TOOL_CANVAS_LAYOUT; exports.MCP_TOOL_CANVAS_REMOVE_NODES = _chunkSVFEVKLFcjs.MCP_TOOL_CANVAS_REMOVE_NODES; exports.MCP_TOOL_CANVAS_SELECT = _chunkSVFEVKLFcjs.MCP_TOOL_CANVAS_SELECT; exports.MCP_TOOL_CANVAS_UPDATE_NODE = _chunkSVFEVKLFcjs.MCP_TOOL_CANVAS_UPDATE_NODE; exports.MCP_TOOL_EDIT_CANVAS = _chunkSVFEVKLFcjs.MCP_TOOL_EDIT_CANVAS; exports.MCP_TOOL_EDIT_PROMPT = _chunkSVFEVKLFcjs.MCP_TOOL_EDIT_PROMPT; exports.MCP_TOOL_GET_EDITOR_STATE = _chunkSVFEVKLFcjs.MCP_TOOL_GET_EDITOR_STATE; exports.MCP_TOOL_PROMPT_INSERT_TEXT = _chunkSVFEVKLFcjs.MCP_TOOL_PROMPT_INSERT_TEXT; exports.MCP_TOOL_PROMPT_REPLACE_RANGE = _chunkSVFEVKLFcjs.MCP_TOOL_PROMPT_REPLACE_RANGE; exports.MCP_TOOL_PROMPT_SELECT = _chunkSVFEVKLFcjs.MCP_TOOL_PROMPT_SELECT; exports.MCP_TOOL_PROMPT_SET_VARIABLE = _chunkSVFEVKLFcjs.MCP_TOOL_PROMPT_SET_VARIABLE; exports.MCP_TOOL_VIEW_EDITOR = _chunkSVFEVKLFcjs.MCP_TOOL_VIEW_EDITOR; exports.PRESENCE_COLORS = _chunkSWTUM32Hcjs.PRESENCE_COLORS; exports.PerformanceQueue = _chunkSWTUM32Hcjs.PerformanceQueue; exports.PresenceStore = _chunkSWTUM32Hcjs.PresenceStore; exports.TOOL_BRIDGE_DEFAULT_PORT = _chunkY4BWZB6Jcjs.TOOL_BRIDGE_DEFAULT_PORT; exports.TOOL_BRIDGE_PROTOCOL = _chunkY4BWZB6Jcjs.TOOL_BRIDGE_PROTOCOL; exports.TOOL_DISCOVERY_TOOLS = _chunkY4BWZB6Jcjs.TOOL_DISCOVERY_TOOLS; exports.TOOL_NAMESPACE_SEPARATOR = _chunkY4BWZB6Jcjs.TOOL_NAMESPACE_SEPARATOR; exports.ToolRegistry = _chunkY4BWZB6Jcjs.ToolRegistry; exports.ToolRegistryError = _chunkY4BWZB6Jcjs.ToolRegistryError; exports.ToolRegistryView = _chunkY4BWZB6Jcjs.ToolRegistryView; exports.UNSAFE_JSON_KEYS = _chunk2BSBFBOAcjs.UNSAFE_JSON_KEYS; exports.baseToolName = _chunkY4BWZB6Jcjs.baseToolName; exports.captureInputSchema = _chunkN2FGYZ4Qcjs.captureInputSchema; exports.captureOutputSize = _chunkN2FGYZ4Qcjs.captureOutputSize; exports.cloneElementWithStyles = _chunkSVFEVKLFcjs.cloneElementWithStyles; exports.connectToolBridge = _chunkY4BWZB6Jcjs.connectToolBridge; exports.createAgentPlayback = _chunkGMWNBSBScjs.createAgentPlayback; exports.createCaptureTool = _chunkN2FGYZ4Qcjs.createCaptureTool; exports.createCaptureToolProvider = _chunkN2FGYZ4Qcjs.createCaptureToolProvider; exports.createElementCaptureSurface = _chunkSVFEVKLFcjs.createElementCaptureSurface; exports.createInstantPresenceClock = _chunkSWTUM32Hcjs.createInstantPresenceClock; exports.createMcpServer = _chunkY4BWZB6Jcjs.createMcpServer; exports.createPlaybackToolProvider = _chunkGMWNBSBScjs.createPlaybackToolProvider; exports.createToolRegistry = _chunkY4BWZB6Jcjs.createToolRegistry; exports.derivePlaybackSteps = _chunkGMWNBSBScjs.derivePlaybackSteps; exports.elementToSvg = _chunkSVFEVKLFcjs.elementToSvg; exports.errorResult = _chunkY4BWZB6Jcjs.errorResult; exports.isUnsafeJsonKey = _chunk2BSBFBOAcjs.isUnsafeJsonKey; exports.listSkills = _chunkY4BWZB6Jcjs.listSkills; exports.locatePlaybackChrome = _chunkGMWNBSBScjs.locatePlaybackChrome; exports.parseSkillFrontmatter = _chunkY4BWZB6Jcjs.parseSkillFrontmatter; exports.playbackRectFromClient = _chunkGMWNBSBScjs.playbackRectFromClient; exports.playbackRefsFromArgs = _chunkGMWNBSBScjs.playbackRefsFromArgs; exports.playbackRefsFromResult = _chunkGMWNBSBScjs.playbackRefsFromResult; exports.rasterizeElement = _chunkSVFEVKLFcjs.rasterizeElement; exports.readSkillFile = _chunkY4BWZB6Jcjs.readSkillFile; exports.readingTime = _chunkGMWNBSBScjs.readingTime; exports.realPresenceClock = _chunkSWTUM32Hcjs.realPresenceClock; exports.resolveCaptureRequest = _chunkN2FGYZ4Qcjs.resolveCaptureRequest; exports.runToolScript = _chunkERAGQL2Ncjs.runToolScript; exports.searchTokens = _chunkY4BWZB6Jcjs.searchTokens; exports.searchTools = _chunkY4BWZB6Jcjs.searchTools; exports.stripPrototypeKeys = _chunk2BSBFBOAcjs.stripPrototypeKeys; exports.summarize = _chunkY4BWZB6Jcjs.summarize; exports.toCapturedImageData = _chunkN2FGYZ4Qcjs.toCapturedImageData; exports.toToolResult = _chunkY4BWZB6Jcjs.toToolResult; exports.toolResultError = _chunkERAGQL2Ncjs.toolResultError; exports.toolResultValue = _chunkERAGQL2Ncjs.toolResultValue; exports.toolsetInstructions = _chunkY4BWZB6Jcjs.toolsetInstructions; exports.toolsetName = _chunkY4BWZB6Jcjs.toolsetName; exports.trackPresenceDrag = _chunkSWTUM32Hcjs.trackPresenceDrag; exports.tweenPresenceCursor = _chunkSWTUM32Hcjs.tweenPresenceCursor; exports.unionCaptureRects = _chunkN2FGYZ4Qcjs.unionCaptureRects; exports.unionRects = _chunkGMWNBSBScjs.unionRects; exports.unknownToolMessage = _chunkY4BWZB6Jcjs.unknownToolMessage; exports.validateJsonSchema = _chunkWOFXZ3XUcjs.validateJsonSchema;

package/dist/tools/index.js

@@ -2,7 +2,7 @@ import {
   runToolScript,
   toolResultError,
   toolResultValue
-} from "../chunk-SA37RU2O.js";
+} from "../chunk-KMU6QJB7.js";
 import {
   JSON_RPC_ERRORS,
   MCP_PROTOCOL_VERSIONS,
@@ -34,11 +34,13 @@ import {
   createAgentPlayback,
   createPlaybackToolProvider,
   derivePlaybackSteps,
+  locatePlaybackChrome,
+  playbackRectFromClient,
   playbackRefsFromArgs,
   playbackRefsFromResult,
   readingTime,
   unionRects
-} from "../chunk-HUHBJWTD.js";
+} from "../chunk-6DXDUVSL.js";
 import {
   CAPTURE_EXCLUDE_SELECTOR,
   CAPTURE_OVERLAY_SELECTORS,
@@ -87,8 +89,9 @@ import {
   PresenceStore,
   createInstantPresenceClock,
   realPresenceClock,
+  trackPresenceDrag,
   tweenPresenceCursor
-} from "../chunk-PEEP2YR7.js";
+} from "../chunk-O2ANJFUF.js";
 import {
   validateJsonSchema
 } from "../chunk-V2ZCJRDM.js";
@@ -147,7 +150,9 @@ export {
   errorResult,
   isUnsafeJsonKey,
   listSkills,
+  locatePlaybackChrome,
   parseSkillFrontmatter,
+  playbackRectFromClient,
   playbackRefsFromArgs,
   playbackRefsFromResult,
   rasterizeElement,
@@ -166,6 +171,7 @@ export {
   toolResultValue,
   toolsetInstructions,
   toolsetName,
+  trackPresenceDrag,
   tweenPresenceCursor,
   unionCaptureRects,
   unionRects,

package/dist/tools/playback.d.cts

@@ -150,6 +150,34 @@ export declare function derivePlaybackSteps(args: unknown, defaultKind?: string)
 export declare function readingTime(text: string): number;
 /** Smallest rectangle around `rects`, or null. */
 export declare function unionRects(rects: readonly (PlaybackRect | null | undefined)[]): PlaybackRect | null;
+/** A box in client (viewport) pixels, as `Element.getBoundingClientRect()` returns it. */
+export interface PlaybackClientRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/**
+ * A client-pixel box (e.g. `element.getBoundingClientRect()`) in a surface's coordinates, through
+ * its `fromViewport` (identity without one). Null for an empty box (a hidden element).
+ */
+export declare function playbackRectFromClient(rect: PlaybackClientRect | null | undefined, fromViewport?: (point: PlaybackPoint) => PlaybackPoint): PlaybackRect | null;
+/**
+ * How a host's own chrome (a HUD, toolbar or panel over or beside an editor) answers a surface's
+ * refs. The canvas and element playback surfaces take these options; their own locator runs first.
+ */
+export interface PlaybackChromeOptions {
+    /** Where `ref` is, in the surface's coordinates (flow units on a canvas, element pixels on an element surface), or null. */
+    locate?(ref: PlaybackRef): PlaybackRect | null;
+    /** The element that shows `ref` anywhere on the page, or null; its client box is mapped to surface coordinates. */
+    locateElement?(ref: PlaybackRef): {
+        getBoundingClientRect(): PlaybackClientRect;
+    } | null;
+    /** Show `ref` for an `open` step (switch to a tab, expand a panel). Without it, `open` steps are skipped. */
+    open?(ref: PlaybackRef): void | Promise<void>;
+}
+/** Finds `ref` through `chrome.locate`, then `chrome.locateElement` (mapped with `fromViewport`), or null. */
+export declare function locatePlaybackChrome(ref: PlaybackRef, chrome: PlaybackChromeOptions | null | undefined, fromViewport?: (point: PlaybackPoint) => PlaybackPoint): PlaybackRect | null;
 /**
  * Acts out tool calls on attached surfaces. Install it on a registry (`registry.use(playback.middleware)`
  * or `playback.install(registry)`); editors attach their surfaces while mounted. Results never change:

package/dist/tools/playback.d.ts

@@ -150,6 +150,34 @@ export declare function derivePlaybackSteps(args: unknown, defaultKind?: string)
 export declare function readingTime(text: string): number;
 /** Smallest rectangle around `rects`, or null. */
 export declare function unionRects(rects: readonly (PlaybackRect | null | undefined)[]): PlaybackRect | null;
+/** A box in client (viewport) pixels, as `Element.getBoundingClientRect()` returns it. */
+export interface PlaybackClientRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/**
+ * A client-pixel box (e.g. `element.getBoundingClientRect()`) in a surface's coordinates, through
+ * its `fromViewport` (identity without one). Null for an empty box (a hidden element).
+ */
+export declare function playbackRectFromClient(rect: PlaybackClientRect | null | undefined, fromViewport?: (point: PlaybackPoint) => PlaybackPoint): PlaybackRect | null;
+/**
+ * How a host's own chrome (a HUD, toolbar or panel over or beside an editor) answers a surface's
+ * refs. The canvas and element playback surfaces take these options; their own locator runs first.
+ */
+export interface PlaybackChromeOptions {
+    /** Where `ref` is, in the surface's coordinates (flow units on a canvas, element pixels on an element surface), or null. */
+    locate?(ref: PlaybackRef): PlaybackRect | null;
+    /** The element that shows `ref` anywhere on the page, or null; its client box is mapped to surface coordinates. */
+    locateElement?(ref: PlaybackRef): {
+        getBoundingClientRect(): PlaybackClientRect;
+    } | null;
+    /** Show `ref` for an `open` step (switch to a tab, expand a panel). Without it, `open` steps are skipped. */
+    open?(ref: PlaybackRef): void | Promise<void>;
+}
+/** Finds `ref` through `chrome.locate`, then `chrome.locateElement` (mapped with `fromViewport`), or null. */
+export declare function locatePlaybackChrome(ref: PlaybackRef, chrome: PlaybackChromeOptions | null | undefined, fromViewport?: (point: PlaybackPoint) => PlaybackPoint): PlaybackRect | null;
 /**
  * Acts out tool calls on attached surfaces. Install it on a registry (`registry.use(playback.middleware)`
  * or `playback.install(registry)`); editors attach their surfaces while mounted. Results never change:

package/dist/tools/presence.d.cts

@@ -80,3 +80,20 @@ export declare class PerformanceQueue {
     constructor(presence: PresenceStore, options: PerformanceQueueOptions);
     run<T>(actor: PresenceActorInfo, perform: () => Promise<T>): Promise<T>;
 }
+/** A box from where an agent's button went down to its cursor, in surface coordinates. */
+export interface PresenceDragBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Follows a presence store for an agent's drag (press, move, release) and reports the box from
+ * the press to the cursor, so a surface can draw its own drag feedback (a crop box or a marquee
+ * being pulled out) under the agent's cursor. `onEnd` runs on release, or when the cursor leaves
+ * the surface mid-drag. Pass the result to `PresenceStore.subscribe`.
+ */
+export declare function trackPresenceDrag(handlers: {
+    onDrag: (box: PresenceDragBox) => void;
+    onEnd: () => void;
+}): (state: PresenceState) => void;

package/dist/tools/presence.d.ts

@@ -80,3 +80,20 @@ export declare class PerformanceQueue {
     constructor(presence: PresenceStore, options: PerformanceQueueOptions);
     run<T>(actor: PresenceActorInfo, perform: () => Promise<T>): Promise<T>;
 }
+/** A box from where an agent's button went down to its cursor, in surface coordinates. */
+export interface PresenceDragBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Follows a presence store for an agent's drag (press, move, release) and reports the box from
+ * the press to the cursor, so a surface can draw its own drag feedback (a crop box or a marquee
+ * being pulled out) under the agent's cursor. `onEnd` runs on release, or when the cursor leaves
+ * the surface mid-drag. Pass the result to `PresenceStore.subscribe`.
+ */
+export declare function trackPresenceDrag(handlers: {
+    onDrag: (box: PresenceDragBox) => void;
+    onEnd: () => void;
+}): (state: PresenceState) => void;

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

@@ -15,6 +15,11 @@ export interface VideoEffectsToolProviderOptions {
     namespace?: string;
     /** The project cannot be edited: write tools are hidden. A string is the reason. */
     readOnly?: boolean | string | (() => boolean | string);
+    /**
+     * The agent playback surface its calls are acted out on (default `video`, where `VideoTimeline` attaches).
+     * Set it when one registry holds several editors of this kind, each attached under its own surface id.
+     */
+    playbackSurface?: string;
 }
 /** A clip's effects as the tools report them: its effect clip picture, its effect transition, then its stack. */
 export declare function videoClipAppliedEffects(clip: VideoClip): AppliedEffectInfo[];

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

@@ -15,6 +15,11 @@ export interface VideoEffectsToolProviderOptions {
     namespace?: string;
     /** The project cannot be edited: write tools are hidden. A string is the reason. */
     readOnly?: boolean | string | (() => boolean | string);
+    /**
+     * The agent playback surface its calls are acted out on (default `video`, where `VideoTimeline` attaches).
+     * Set it when one registry holds several editors of this kind, each attached under its own surface id.
+     */
+    playbackSurface?: string;
 }
 /** A clip's effects as the tools report them: its effect clip picture, its effect transition, then its stack. */
 export declare function videoClipAppliedEffects(clip: VideoClip): AppliedEffectInfo[];

package/dist/video-editor/index.cjs

@@ -3267,12 +3267,12 @@ function planVideoToolPlayback(tool, args) {
   if (str2(args.marker)) return click({ kind: "marker", id: args.marker });
   return null;
 }
-function withVideoPlayback(provider, surface = "video") {
+function withVideoPlayback(provider, surface) {
   const plan = (tool) => tool.plan || tool.playback !== void 0 ? tool : { ...tool, plan: (args) => planVideoToolPlayback(tool.name, args) };
   const tools = provider.tools;
   return {
     ...provider,
-    playbackSurface: _nullishCoalesce(provider.playbackSurface, () => ( surface)),
+    playbackSurface: _nullishCoalesce(_nullishCoalesce(surface, () => ( provider.playbackSurface)), () => ( "video")),
     tools: typeof tools === "function" ? () => tools().map(plan) : tools.map(plan)
   };
 }
@@ -4686,7 +4686,7 @@ function createVideoEditorToolProvider(controller, options = {}) {
         }
       });
     }
-  });
+  }, options.playbackSurface);
 }
 
 // src/video-editor/effect-tools.ts
@@ -4861,7 +4861,7 @@ function createVideoEffectsToolProvider(controller, options = {}) {
         }
       }
     ]
-  }));
+  }), options.playbackSurface);
 }
 
 

package/dist/video-editor/index.js

@@ -3267,12 +3267,12 @@ function planVideoToolPlayback(tool, args) {
   if (str2(args.marker)) return click({ kind: "marker", id: args.marker });
   return null;
 }
-function withVideoPlayback(provider, surface = "video") {
+function withVideoPlayback(provider, surface) {
   const plan = (tool) => tool.plan || tool.playback !== void 0 ? tool : { ...tool, plan: (args) => planVideoToolPlayback(tool.name, args) };
   const tools = provider.tools;
   return {
     ...provider,
-    playbackSurface: provider.playbackSurface ?? surface,
+    playbackSurface: surface ?? provider.playbackSurface ?? "video",
     tools: typeof tools === "function" ? () => tools().map(plan) : tools.map(plan)
   };
 }
@@ -4686,7 +4686,7 @@ function createVideoEditorToolProvider(controller, options = {}) {
         }
       });
     }
-  });
+  }, options.playbackSurface);
 }
 
 // src/video-editor/effect-tools.ts
@@ -4861,7 +4861,7 @@ function createVideoEffectsToolProvider(controller, options = {}) {
         }
       }
     ]
-  }));
+  }), options.playbackSurface);
 }
 export {
   VIDEO_BLEND_MODES,

package/dist/video-editor/playback.d.cts

@@ -14,7 +14,8 @@ export declare function parseVideoTimeRef(ref: PlaybackRef): VideoPlaybackTime |
 export declare function planVideoToolPlayback(tool: string, args: Record<string, any>): PlaybackStep[] | null;
 /**
  * Gives a video tool provider agent playback: each write tool plans its steps with
- * `planVideoToolPlayback` and every call plays on `surface` (default `video`, where `VideoTimeline`
- * attaches itself). `seek_video` (a read in name only) and `edit_video` (a batch) play too.
+ * `planVideoToolPlayback` and every call plays on `surface`. An explicit `surface` wins over the
+ * provider's own `playbackSurface`; with neither, it is `video` (where `VideoTimeline` attaches
+ * itself). `seek_video` (a read in name only) and `edit_video` (a batch) play too.
  */
 export declare function withVideoPlayback(provider: AgentToolProvider, surface?: string): AgentToolProvider;

package/dist/video-editor/playback.d.ts

@@ -14,7 +14,8 @@ export declare function parseVideoTimeRef(ref: PlaybackRef): VideoPlaybackTime |
 export declare function planVideoToolPlayback(tool: string, args: Record<string, any>): PlaybackStep[] | null;
 /**
  * Gives a video tool provider agent playback: each write tool plans its steps with
- * `planVideoToolPlayback` and every call plays on `surface` (default `video`, where `VideoTimeline`
- * attaches itself). `seek_video` (a read in name only) and `edit_video` (a batch) play too.
+ * `planVideoToolPlayback` and every call plays on `surface`. An explicit `surface` wins over the
+ * provider's own `playbackSurface`; with neither, it is `video` (where `VideoTimeline` attaches
+ * itself). `seek_video` (a read in name only) and `edit_video` (a batch) play too.
  */
 export declare function withVideoPlayback(provider: AgentToolProvider, surface?: string): AgentToolProvider;

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

@@ -29,6 +29,11 @@ export interface VideoEditorToolProviderOptions {
     framePixels?: (time: number) => VideoPixels | null | Promise<VideoPixels | null>;
     /** How long `get_video_scopes` waits for the preview to finish drawing a frame (ms, default 5000). */
     framePixelsTimeout?: number;
+    /**
+     * The agent playback surface its calls are acted out on (default `video`, where `VideoTimeline` attaches).
+     * Set it when one registry holds several editors of this kind, each attached under its own surface id.
+     */
+    playbackSurface?: string;
 }
 /** A sequence as agents see it: its length, the sequences it nests, who plays it, and (with `tracks`) its tracks and clips. */
 export declare function describeVideoSequence(project: VideoProject, sequence: VideoSequence, tracks?: boolean): {

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

@@ -29,6 +29,11 @@ export interface VideoEditorToolProviderOptions {
     framePixels?: (time: number) => VideoPixels | null | Promise<VideoPixels | null>;
     /** How long `get_video_scopes` waits for the preview to finish drawing a frame (ms, default 5000). */
     framePixelsTimeout?: number;
+    /**
+     * The agent playback surface its calls are acted out on (default `video`, where `VideoTimeline` attaches).
+     * Set it when one registry holds several editors of this kind, each attached under its own surface id.
+     */
+    playbackSurface?: string;
 }
 /** A sequence as agents see it: its length, the sequences it nests, who plays it, and (with `tracks`) its tracks and clips. */
 export declare function describeVideoSequence(project: VideoProject, sequence: VideoSequence, tracks?: boolean): {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor",
-  "version": "0.148.0",
+  "version": "0.150.0",
   "description": "UI-agnostic rich text and media editing core library",
   "author": "Pixerate",
   "license": "MIT",