@pixerate/editor 0.142.1 → 0.144.0

package/dist/canvas/index.js

@@ -88,12 +88,13 @@ import {
   matchSize,
   overlaps,
   placeBeside,
+  placeInView,
   readStyleSize,
   reorderNodes,
   toggleLockNodes,
   unlockNodes,
   withStyleSize
-} from "../chunk-DW4CV5H4.js";
+} from "../chunk-U4VE4UI2.js";
 import {
   DEFAULT_ARRANGE_SHORTCUTS,
   matchArrangeShortcut
@@ -12057,6 +12058,7 @@ export {
   pathfinder,
   pieScene,
   placeBeside,
+  placeInView,
   planarSplit,
   playCanvasSceneTransition,
   playWebAnimations,

package/dist/canvas/layout.d.cts

@@ -1,4 +1,4 @@
-import type { CanvasEdge, CanvasLayoutOptions, CanvasNode, IncrementalLayoutOptions, PlaceBesideOptions, Rect, Side, XYPosition } from './types.cjs';
+import type { CanvasEdge, CanvasLayoutOptions, CanvasNode, IncrementalLayoutOptions, PlaceBesideOptions, Rect, Side, XYPosition } from "./types.cjs";
 export declare const DEFAULT_NODE_WIDTH = 200;
 export declare const DEFAULT_NODE_HEIGHT = 60;
 export declare const DEFAULT_PLACEMENT_GAP = 48;
@@ -42,7 +42,7 @@ export declare function overlaps(a: Rect, b: Rect, pad?: number): boolean;
 /**
  * Maps directed layout flow to its natural forward growth side.
  */
-export declare function flowSide(direction?: 'LR' | 'TB' | 'RL' | 'BT'): Side;
+export declare function flowSide(direction?: "LR" | "TB" | "RL" | "BT"): Side;
 /**
  * Incremental layout blending:
  * Keeps established/manual node positions intact. Runs Dagre on the entire graph,
@@ -58,3 +58,16 @@ export declare function placeBeside(rects: Record<string, Rect>, size: {
     width: number;
     height: number;
 }, side: Side, nearNodeId?: string, options?: PlaceBesideOptions): XYPosition;
+/**
+ * Where a node of `size` goes when nothing anchors it: centred in `view` (the visible part of
+ * the canvas, in flow coordinates) when that is free, else the nearest free spot in rings
+ * around the centre, so new work appears where the user is looking and never on top of
+ * `rects`.
+ */
+export declare function placeInView(rects: Record<string, Rect>, size: {
+    width: number;
+    height: number;
+}, view: Rect, options?: {
+    gap?: number;
+    maxRings?: number;
+}): XYPosition;

package/dist/canvas/layout.d.ts

@@ -1,4 +1,4 @@
-import type { CanvasEdge, CanvasLayoutOptions, CanvasNode, IncrementalLayoutOptions, PlaceBesideOptions, Rect, Side, XYPosition } from './types.js';
+import type { CanvasEdge, CanvasLayoutOptions, CanvasNode, IncrementalLayoutOptions, PlaceBesideOptions, Rect, Side, XYPosition } from "./types.js";
 export declare const DEFAULT_NODE_WIDTH = 200;
 export declare const DEFAULT_NODE_HEIGHT = 60;
 export declare const DEFAULT_PLACEMENT_GAP = 48;
@@ -42,7 +42,7 @@ export declare function overlaps(a: Rect, b: Rect, pad?: number): boolean;
 /**
  * Maps directed layout flow to its natural forward growth side.
  */
-export declare function flowSide(direction?: 'LR' | 'TB' | 'RL' | 'BT'): Side;
+export declare function flowSide(direction?: "LR" | "TB" | "RL" | "BT"): Side;
 /**
  * Incremental layout blending:
  * Keeps established/manual node positions intact. Runs Dagre on the entire graph,
@@ -58,3 +58,16 @@ export declare function placeBeside(rects: Record<string, Rect>, size: {
     width: number;
     height: number;
 }, side: Side, nearNodeId?: string, options?: PlaceBesideOptions): XYPosition;
+/**
+ * Where a node of `size` goes when nothing anchors it: centred in `view` (the visible part of
+ * the canvas, in flow coordinates) when that is free, else the nearest free spot in rings
+ * around the centre, so new work appears where the user is looking and never on top of
+ * `rects`.
+ */
+export declare function placeInView(rects: Record<string, Rect>, size: {
+    width: number;
+    height: number;
+}, view: Rect, options?: {
+    gap?: number;
+    maxRings?: number;
+}): XYPosition;

package/dist/{chunk-XH32BATE.cjs → chunk-AG2EXVCR.cjs}

@@ -1,6 +1,6 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
 
-var _chunkX2HQP7DFcjs = require('./chunk-X2HQP7DF.cjs');
+var _chunkD2ENR3LBcjs = require('./chunk-D2ENR3LB.cjs');
 
 // src/tools/script.ts
 function toolResultValue(result) {
@@ -36,7 +36,7 @@ async function runToolScript(source, script, options = {}) {
     if (step.say) {
       emit({ type: "say", step: i, text: step.say });
       _optionalChain([options, 'access', _6 => _6.playback, 'optionalAccess', _7 => _7.say, 'call', _8 => _8(step.say, options.actor ? { actor: options.actor } : {})]);
-      await pause(_chunkX2HQP7DFcjs.readingTime.call(void 0, step.say));
+      await pause(_chunkD2ENR3LBcjs.readingTime.call(void 0, step.say));
     }
     if (!step.tool) continue;
     if (control.stopped) return finish(false);

package/dist/{chunk-X2HQP7DF.cjs → chunk-D2ENR3LB.cjs}

@@ -107,7 +107,7 @@ var AgentPlayback = (_class = class {
   constructor(options = {}) {;_class.prototype.__init.call(this);_class.prototype.__init2.call(this);_class.prototype.__init3.call(this);_class.prototype.__init4.call(this);_class.prototype.__init5.call(this);_class.prototype.__init6.call(this);_class.prototype.__init7.call(this);_class.prototype.__init8.call(this);_class.prototype.__init9.call(this);
     this.clock = _nullishCoalesce(options.clock, () => ( _chunkUJGAA6AKcjs.realPresenceClock));
     this.speed = _nullishCoalesce(options.speed, () => ( 1));
-    this.reads = _nullishCoalesce(options.reads, () => ( "glance"));
+    this.reads = _nullishCoalesce(options.reads, () => ( "skip"));
     this.linger = _nullishCoalesce(options.linger, () => ( 1500));
     this.defaultActor = _nullishCoalesce(options.actor, () => ( { id: "agent", name: "Agent" }));
   }
@@ -143,11 +143,16 @@ var AgentPlayback = (_class = class {
   surface(id) {
     return this.surfaces.get(id);
   }
-  /** Shows `text` in the actor's bubble on the surface it last worked on (until its next step). */
+  /**
+   * Shows `text` in the actor's bubble on the surface it last worked on (until its next step).
+   * Returns that surface's id, or null when the actor has no cursor on screen (nothing shown).
+   */
   say(text, options = {}) {
     const actor = this.actorState(options.actor);
     const surface = actor.surface ? this.surfaces.get(actor.surface) : void 0;
-    if (_optionalChain([surface, 'optionalAccess', _5 => _5.presence, 'access', _6 => _6.get, 'call', _7 => _7(actor.info.id)])) surface.presence.set({ id: actor.info.id, message: text });
+    if (!_optionalChain([surface, 'optionalAccess', _5 => _5.presence, 'access', _6 => _6.get, 'call', _7 => _7(actor.info.id)])) return null;
+    surface.presence.set({ id: actor.info.id, message: text });
+    return actor.surface;
   }
   /** Finishes every running performance at once (the calls still run and keep their results). */
   stop() {
@@ -396,6 +401,40 @@ var AgentPlayback = (_class = class {
 function createAgentPlayback(options = {}) {
   return new AgentPlayback(options);
 }
+function createPlaybackToolProvider(playback, options = {}) {
+  const title = "Say a note by your cursor";
+  return {
+    id: _nullishCoalesce(options.id, () => ( "playback")),
+    namespace: options.namespace,
+    title: "Agent playback",
+    description: "Notes shown beside your cursor while the host plays your calls on screen.",
+    skill: "pixerate-agent-tools",
+    tools: [
+      {
+        name: "say",
+        title,
+        description: "Shows a short note in the bubble beside your cursor on the editor you last worked on, so the user can follow what you are doing; it stays until your next call. Changes no document. Returns shown (whether a cursor was on screen to show it) and surface (that editor, or null).",
+        inputSchema: {
+          type: "object",
+          properties: {
+            text: { type: "string", minLength: 1, maxLength: 200, description: "The note: one short sentence, at most 200 characters." }
+          },
+          required: ["text"],
+          additionalProperties: false
+        },
+        annotations: { title, readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        playback: false,
+        handler: ({ text }, context) => {
+          const note = String(text).trim();
+          if (!note) throw new Error('text is empty; pass the note to show, e.g. "Aligning the cards."');
+          const surface = playback.say(note, { actor: context.actor });
+          return { shown: surface !== null, surface };
+        }
+      }
+    ]
+  };
+}
+
 
 
 
@@ -405,4 +444,4 @@ function createAgentPlayback(options = {}) {
 
 
 
-exports.playbackRefsFromArgs = playbackRefsFromArgs; exports.playbackRefsFromResult = playbackRefsFromResult; exports.derivePlaybackSteps = derivePlaybackSteps; exports.readingTime = readingTime; exports.unionRects = unionRects; exports.AgentPlayback = AgentPlayback; exports.createAgentPlayback = createAgentPlayback;
+exports.playbackRefsFromArgs = playbackRefsFromArgs; exports.playbackRefsFromResult = playbackRefsFromResult; exports.derivePlaybackSteps = derivePlaybackSteps; exports.readingTime = readingTime; exports.unionRects = unionRects; exports.AgentPlayback = AgentPlayback; exports.createAgentPlayback = createAgentPlayback; exports.createPlaybackToolProvider = createPlaybackToolProvider;

package/dist/{chunk-UBRYHNRU.cjs → chunk-EL4PSKFT.cjs}

@@ -4,8 +4,14 @@ var DEFAULT_NODE_WIDTH = 200;
 var DEFAULT_NODE_HEIGHT = 60;
 var DEFAULT_PLACEMENT_GAP = 48;
 function getCenteredNodePosition(width = 0, height = 0, screenToFlowPosition, screenDimensions) {
-  const rect = _nullishCoalesce(screenDimensions, () => ( (typeof document !== "undefined" ? { width: document.documentElement.clientWidth, height: document.documentElement.clientHeight } : { width: 1920, height: 1080 })));
-  const flowPos = screenToFlowPosition({ x: rect.width / 2, y: rect.height / 2 });
+  const rect = _nullishCoalesce(screenDimensions, () => ( (typeof document !== "undefined" ? {
+    width: document.documentElement.clientWidth,
+    height: document.documentElement.clientHeight
+  } : { width: 1920, height: 1080 })));
+  const flowPos = screenToFlowPosition({
+    x: rect.width / 2,
+    y: rect.height / 2
+  });
   return {
     x: flowPos.x - width / 2,
     y: flowPos.y - height / 2
@@ -73,7 +79,10 @@ function getLayoutedNodes(nodes, edges, getNodesBounds, options = {}) {
 function estimateNodeSize(node, defaultWidth = DEFAULT_NODE_WIDTH, defaultHeight = DEFAULT_NODE_HEIGHT) {
   const label = String(_nullishCoalesce(_nullishCoalesce(_nullishCoalesce(_optionalChain([node, 'access', _10 => _10.data, 'optionalAccess', _11 => _11.label]), () => ( _optionalChain([node, 'access', _12 => _12.data, 'optionalAccess', _13 => _13.title]))), () => ( node.id)), () => ( "")));
   const lines = label.split(/\n|<br\s*\/?>/);
-  const longest = Math.max(...lines.map((l) => l.replace(/<[^>]+>/g, "").length), 1);
+  const longest = Math.max(
+    ...lines.map((l) => l.replace(/<[^>]+>/g, "").length),
+    1
+  );
   const width = Math.min(480, Math.max(defaultWidth, longest * 8 + 48));
   const height = Math.max(defaultHeight, lines.length * 20 + 24);
   return { width, height };
@@ -203,6 +212,38 @@ function placeBeside(rects, size, side, nearNodeId, options = {}) {
     y: Math.round(baseY)
   };
 }
+function placeInView(rects, size, view, options = {}) {
+  const gap = _nullishCoalesce(options.gap, () => ( DEFAULT_PLACEMENT_GAP));
+  const maxRings = _nullishCoalesce(options.maxRings, () => ( 24));
+  const obstacles = Object.values(rects);
+  const start = {
+    x: view.x + view.width / 2 - size.width / 2,
+    y: view.y + view.height / 2 - size.height / 2
+  };
+  const free = (p) => !obstacles.some(
+    (o) => overlaps({ ...p, width: size.width, height: size.height }, o, gap / 2)
+  );
+  if (free(start)) return { x: Math.round(start.x), y: Math.round(start.y) };
+  const stepX = size.width + gap;
+  const stepY = size.height + gap;
+  for (let ring = 1; ring <= maxRings; ring++) {
+    const candidates = [];
+    for (let i = -ring; i <= ring; i++) {
+      candidates.push(
+        { x: start.x + ring * stepX, y: start.y + i * stepY },
+        { x: start.x - ring * stepX, y: start.y + i * stepY },
+        { x: start.x + i * stepX, y: start.y + ring * stepY },
+        { x: start.x + i * stepX, y: start.y - ring * stepY }
+      );
+    }
+    candidates.sort(
+      (a, b) => Math.hypot(a.x - start.x, a.y - start.y) - Math.hypot(b.x - start.x, b.y - start.y)
+    );
+    const spot = candidates.find(free);
+    if (spot) return { x: Math.round(spot.x), y: Math.round(spot.y) };
+  }
+  return { x: Math.round(start.x), y: Math.round(start.y) };
+}
 
 // src/canvas/arrange.ts
 var LOCKED_DATA_KEY = "locked";
@@ -588,4 +629,5 @@ function invertNodeUpdates(nodes, updates) {
 
 
 
-exports.DEFAULT_NODE_WIDTH = DEFAULT_NODE_WIDTH; exports.DEFAULT_NODE_HEIGHT = DEFAULT_NODE_HEIGHT; exports.DEFAULT_PLACEMENT_GAP = DEFAULT_PLACEMENT_GAP; exports.getCenteredNodePosition = getCenteredNodePosition; exports.centerNodes = centerNodes; exports.getLayoutedNodes = getLayoutedNodes; exports.estimateNodeSize = estimateNodeSize; exports.boundsOf = boundsOf; exports.centre = centre; exports.overlaps = overlaps; exports.flowSide = flowSide; exports.ensureLayout = ensureLayout; exports.placeBeside = placeBeside; exports.LOCKED_DATA_KEY = LOCKED_DATA_KEY; exports.LOCKED_PREVIOUS_FLAGS_KEY = LOCKED_PREVIOUS_FLAGS_KEY; exports.readStyleSize = readStyleSize; exports.withStyleSize = withStyleSize; exports.getNodeSize = getNodeSize; exports.getAbsolutePosition = getAbsolutePosition; exports.createNodeLookup = createNodeLookup; exports.getNodeRect = getNodeRect; exports.isLocked = isLocked; exports.lockNodes = lockNodes; exports.unlockNodes = unlockNodes; exports.toggleLockNodes = toggleLockNodes; exports.alignNodes = alignNodes; exports.distributeNodes = distributeNodes; exports.matchSize = matchSize; exports.reorderNodes = reorderNodes; exports.applyNodeUpdates = applyNodeUpdates; exports.invertNodeUpdates = invertNodeUpdates;
+
+exports.DEFAULT_NODE_WIDTH = DEFAULT_NODE_WIDTH; exports.DEFAULT_NODE_HEIGHT = DEFAULT_NODE_HEIGHT; exports.DEFAULT_PLACEMENT_GAP = DEFAULT_PLACEMENT_GAP; exports.getCenteredNodePosition = getCenteredNodePosition; exports.centerNodes = centerNodes; exports.getLayoutedNodes = getLayoutedNodes; exports.estimateNodeSize = estimateNodeSize; exports.boundsOf = boundsOf; exports.centre = centre; exports.overlaps = overlaps; exports.flowSide = flowSide; exports.ensureLayout = ensureLayout; exports.placeBeside = placeBeside; exports.placeInView = placeInView; exports.LOCKED_DATA_KEY = LOCKED_DATA_KEY; exports.LOCKED_PREVIOUS_FLAGS_KEY = LOCKED_PREVIOUS_FLAGS_KEY; exports.readStyleSize = readStyleSize; exports.withStyleSize = withStyleSize; exports.getNodeSize = getNodeSize; exports.getAbsolutePosition = getAbsolutePosition; exports.createNodeLookup = createNodeLookup; exports.getNodeRect = getNodeRect; exports.isLocked = isLocked; exports.lockNodes = lockNodes; exports.unlockNodes = unlockNodes; exports.toggleLockNodes = toggleLockNodes; exports.alignNodes = alignNodes; exports.distributeNodes = distributeNodes; exports.matchSize = matchSize; exports.reorderNodes = reorderNodes; exports.applyNodeUpdates = applyNodeUpdates; exports.invertNodeUpdates = invertNodeUpdates;

package/dist/{chunk-54GVEVXS.js → chunk-HUHBJWTD.js}

@@ -107,7 +107,7 @@ var AgentPlayback = class {
   constructor(options = {}) {
     this.clock = options.clock ?? realPresenceClock;
     this.speed = options.speed ?? 1;
-    this.reads = options.reads ?? "glance";
+    this.reads = options.reads ?? "skip";
     this.linger = options.linger ?? 1500;
     this.defaultActor = options.actor ?? { id: "agent", name: "Agent" };
   }
@@ -143,11 +143,16 @@ var AgentPlayback = class {
   surface(id) {
     return this.surfaces.get(id);
   }
-  /** Shows `text` in the actor's bubble on the surface it last worked on (until its next step). */
+  /**
+   * Shows `text` in the actor's bubble on the surface it last worked on (until its next step).
+   * Returns that surface's id, or null when the actor has no cursor on screen (nothing shown).
+   */
   say(text, options = {}) {
     const actor = this.actorState(options.actor);
     const surface = actor.surface ? this.surfaces.get(actor.surface) : void 0;
-    if (surface?.presence.get(actor.info.id)) surface.presence.set({ id: actor.info.id, message: text });
+    if (!surface?.presence.get(actor.info.id)) return null;
+    surface.presence.set({ id: actor.info.id, message: text });
+    return actor.surface;
   }
   /** Finishes every running performance at once (the calls still run and keep their results). */
   stop() {
@@ -396,6 +401,39 @@ var AgentPlayback = class {
 function createAgentPlayback(options = {}) {
   return new AgentPlayback(options);
 }
+function createPlaybackToolProvider(playback, options = {}) {
+  const title = "Say a note by your cursor";
+  return {
+    id: options.id ?? "playback",
+    namespace: options.namespace,
+    title: "Agent playback",
+    description: "Notes shown beside your cursor while the host plays your calls on screen.",
+    skill: "pixerate-agent-tools",
+    tools: [
+      {
+        name: "say",
+        title,
+        description: "Shows a short note in the bubble beside your cursor on the editor you last worked on, so the user can follow what you are doing; it stays until your next call. Changes no document. Returns shown (whether a cursor was on screen to show it) and surface (that editor, or null).",
+        inputSchema: {
+          type: "object",
+          properties: {
+            text: { type: "string", minLength: 1, maxLength: 200, description: "The note: one short sentence, at most 200 characters." }
+          },
+          required: ["text"],
+          additionalProperties: false
+        },
+        annotations: { title, readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        playback: false,
+        handler: ({ text }, context) => {
+          const note = String(text).trim();
+          if (!note) throw new Error('text is empty; pass the note to show, e.g. "Aligning the cards."');
+          const surface = playback.say(note, { actor: context.actor });
+          return { shown: surface !== null, surface };
+        }
+      }
+    ]
+  };
+}
 
 export {
   playbackRefsFromArgs,
@@ -404,5 +442,6 @@ export {
   readingTime,
   unionRects,
   AgentPlayback,
-  createAgentPlayback
+  createAgentPlayback,
+  createPlaybackToolProvider
 };

package/dist/{chunk-Y6SGC6KO.js → chunk-SA37RU2O.js}

@@ -1,6 +1,6 @@
 import {
   readingTime
-} from "./chunk-54GVEVXS.js";
+} from "./chunk-HUHBJWTD.js";
 
 // src/tools/script.ts
 function toolResultValue(result) {

package/dist/{chunk-DW4CV5H4.js → chunk-U4VE4UI2.js}

@@ -4,8 +4,14 @@ var DEFAULT_NODE_WIDTH = 200;
 var DEFAULT_NODE_HEIGHT = 60;
 var DEFAULT_PLACEMENT_GAP = 48;
 function getCenteredNodePosition(width = 0, height = 0, screenToFlowPosition, screenDimensions) {
-  const rect = screenDimensions ?? (typeof document !== "undefined" ? { width: document.documentElement.clientWidth, height: document.documentElement.clientHeight } : { width: 1920, height: 1080 });
-  const flowPos = screenToFlowPosition({ x: rect.width / 2, y: rect.height / 2 });
+  const rect = screenDimensions ?? (typeof document !== "undefined" ? {
+    width: document.documentElement.clientWidth,
+    height: document.documentElement.clientHeight
+  } : { width: 1920, height: 1080 });
+  const flowPos = screenToFlowPosition({
+    x: rect.width / 2,
+    y: rect.height / 2
+  });
   return {
     x: flowPos.x - width / 2,
     y: flowPos.y - height / 2
@@ -73,7 +79,10 @@ function getLayoutedNodes(nodes, edges, getNodesBounds, options = {}) {
 function estimateNodeSize(node, defaultWidth = DEFAULT_NODE_WIDTH, defaultHeight = DEFAULT_NODE_HEIGHT) {
   const label = String(node.data?.label ?? node.data?.title ?? node.id ?? "");
   const lines = label.split(/\n|<br\s*\/?>/);
-  const longest = Math.max(...lines.map((l) => l.replace(/<[^>]+>/g, "").length), 1);
+  const longest = Math.max(
+    ...lines.map((l) => l.replace(/<[^>]+>/g, "").length),
+    1
+  );
   const width = Math.min(480, Math.max(defaultWidth, longest * 8 + 48));
   const height = Math.max(defaultHeight, lines.length * 20 + 24);
   return { width, height };
@@ -203,6 +212,38 @@ function placeBeside(rects, size, side, nearNodeId, options = {}) {
     y: Math.round(baseY)
   };
 }
+function placeInView(rects, size, view, options = {}) {
+  const gap = options.gap ?? DEFAULT_PLACEMENT_GAP;
+  const maxRings = options.maxRings ?? 24;
+  const obstacles = Object.values(rects);
+  const start = {
+    x: view.x + view.width / 2 - size.width / 2,
+    y: view.y + view.height / 2 - size.height / 2
+  };
+  const free = (p) => !obstacles.some(
+    (o) => overlaps({ ...p, width: size.width, height: size.height }, o, gap / 2)
+  );
+  if (free(start)) return { x: Math.round(start.x), y: Math.round(start.y) };
+  const stepX = size.width + gap;
+  const stepY = size.height + gap;
+  for (let ring = 1; ring <= maxRings; ring++) {
+    const candidates = [];
+    for (let i = -ring; i <= ring; i++) {
+      candidates.push(
+        { x: start.x + ring * stepX, y: start.y + i * stepY },
+        { x: start.x - ring * stepX, y: start.y + i * stepY },
+        { x: start.x + i * stepX, y: start.y + ring * stepY },
+        { x: start.x + i * stepX, y: start.y - ring * stepY }
+      );
+    }
+    candidates.sort(
+      (a, b) => Math.hypot(a.x - start.x, a.y - start.y) - Math.hypot(b.x - start.x, b.y - start.y)
+    );
+    const spot = candidates.find(free);
+    if (spot) return { x: Math.round(spot.x), y: Math.round(spot.y) };
+  }
+  return { x: Math.round(start.x), y: Math.round(start.y) };
+}
 
 // src/canvas/arrange.ts
 var LOCKED_DATA_KEY = "locked";
@@ -570,6 +611,7 @@ export {
   flowSide,
   ensureLayout,
   placeBeside,
+  placeInView,
   LOCKED_DATA_KEY,
   LOCKED_PREVIOUS_FLAGS_KEY,
   readStyleSize,

package/dist/commands/index.cjs

@@ -29,7 +29,7 @@ var _chunkGLQQ2VILcjs = require('../chunk-GLQQ2VIL.cjs');
 var _chunk4EFNS2HVcjs = require('../chunk-4EFNS2HV.cjs');
 
 
-var _chunkX2HQP7DFcjs = require('../chunk-X2HQP7DF.cjs');
+var _chunkD2ENR3LBcjs = require('../chunk-D2ENR3LB.cjs');
 require('../chunk-UJGAA6AK.cjs');
 
 
@@ -608,7 +608,7 @@ function createCommandToolProvider(registry, options = {}) {
     const surface = _nullishCoalesce(_nullishCoalesce(spec.playbackSurface, () => ( spec.scope)), () => ( (id.includes(".") ? id.slice(0, id.indexOf(".")) : void 0)));
     const planned = _optionalChain([spec, 'access', _24 => _24.plan, 'optionalCall', _25 => _25(context(), _nullishCoalesce(params, () => ( {})))]);
     const own = !planned ? [] : Array.isArray(planned) ? planned : planned.steps;
-    const steps = own.length ? own : _chunkX2HQP7DFcjs.derivePlaybackSteps.call(void 0, params);
+    const steps = own.length ? own : _chunkD2ENR3LBcjs.derivePlaybackSteps.call(void 0, params);
     return {
       steps,
       ...surface ? { surface } : {},

package/dist/commands/index.js

@@ -29,7 +29,7 @@ import {
 } from "../chunk-7KZ2HKKC.js";
 import {
   derivePlaybackSteps
-} from "../chunk-54GVEVXS.js";
+} from "../chunk-HUHBJWTD.js";
 import "../chunk-PEEP2YR7.js";
 import {
   validateJsonSchema

package/dist/tools/index.cjs

@@ -2,7 +2,7 @@
 
 
 
-var _chunkXH32BATEcjs = require('../chunk-XH32BATE.cjs');
+var _chunkAG2EXVCRcjs = require('../chunk-AG2EXVCR.cjs');
 
 
 
@@ -37,7 +37,8 @@ var _chunkY4BWZB6Jcjs = require('../chunk-Y4BWZB6J.cjs');
 
 
 
-var _chunkX2HQP7DFcjs = require('../chunk-X2HQP7DF.cjs');
+
+var _chunkD2ENR3LBcjs = require('../chunk-D2ENR3LB.cjs');
 
 
 
@@ -169,4 +170,5 @@ var _chunkWOFXZ3XUcjs = require('../chunk-WOFXZ3XU.cjs');
 
 
 
-exports.AgentPlayback = _chunkX2HQP7DFcjs.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 = _chunkX2HQP7DFcjs.createAgentPlayback; exports.createCaptureTool = _chunkN2FGYZ4Qcjs.createCaptureTool; exports.createCaptureToolProvider = _chunkN2FGYZ4Qcjs.createCaptureToolProvider; exports.createElementCaptureSurface = _chunkSVFEVKLFcjs.createElementCaptureSurface; exports.createInstantPresenceClock = _chunkUJGAA6AKcjs.createInstantPresenceClock; exports.createMcpServer = _chunkY4BWZB6Jcjs.createMcpServer; exports.createToolRegistry = _chunkY4BWZB6Jcjs.createToolRegistry; exports.derivePlaybackSteps = _chunkX2HQP7DFcjs.derivePlaybackSteps; exports.elementToSvg = _chunkSVFEVKLFcjs.elementToSvg; exports.errorResult = _chunkY4BWZB6Jcjs.errorResult; exports.isUnsafeJsonKey = _chunk2BSBFBOAcjs.isUnsafeJsonKey; exports.listSkills = _chunkY4BWZB6Jcjs.listSkills; exports.parseSkillFrontmatter = _chunkY4BWZB6Jcjs.parseSkillFrontmatter; exports.playbackRefsFromArgs = _chunkX2HQP7DFcjs.playbackRefsFromArgs; exports.playbackRefsFromResult = _chunkX2HQP7DFcjs.playbackRefsFromResult; exports.rasterizeElement = _chunkSVFEVKLFcjs.rasterizeElement; exports.readSkillFile = _chunkY4BWZB6Jcjs.readSkillFile; exports.readingTime = _chunkX2HQP7DFcjs.readingTime; exports.realPresenceClock = _chunkUJGAA6AKcjs.realPresenceClock; exports.resolveCaptureRequest = _chunkN2FGYZ4Qcjs.resolveCaptureRequest; exports.runToolScript = _chunkXH32BATEcjs.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 = _chunkXH32BATEcjs.toolResultError; exports.toolResultValue = _chunkXH32BATEcjs.toolResultValue; exports.toolsetInstructions = _chunkY4BWZB6Jcjs.toolsetInstructions; exports.toolsetName = _chunkY4BWZB6Jcjs.toolsetName; exports.tweenPresenceCursor = _chunkUJGAA6AKcjs.tweenPresenceCursor; exports.unionCaptureRects = _chunkN2FGYZ4Qcjs.unionCaptureRects; exports.unionRects = _chunkX2HQP7DFcjs.unionRects; exports.unknownToolMessage = _chunkY4BWZB6Jcjs.unknownToolMessage; exports.validateJsonSchema = _chunkWOFXZ3XUcjs.validateJsonSchema;
+
+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;

package/dist/tools/index.js

@@ -2,7 +2,7 @@ import {
   runToolScript,
   toolResultError,
   toolResultValue
-} from "../chunk-Y6SGC6KO.js";
+} from "../chunk-SA37RU2O.js";
 import {
   JSON_RPC_ERRORS,
   MCP_PROTOCOL_VERSIONS,
@@ -32,12 +32,13 @@ import {
 import {
   AgentPlayback,
   createAgentPlayback,
+  createPlaybackToolProvider,
   derivePlaybackSteps,
   playbackRefsFromArgs,
   playbackRefsFromResult,
   readingTime,
   unionRects
-} from "../chunk-54GVEVXS.js";
+} from "../chunk-HUHBJWTD.js";
 import {
   CAPTURE_EXCLUDE_SELECTOR,
   CAPTURE_OVERLAY_SELECTORS,
@@ -139,6 +140,7 @@ export {
   createElementCaptureSurface,
   createInstantPresenceClock,
   createMcpServer,
+  createPlaybackToolProvider,
   createToolRegistry,
   derivePlaybackSteps,
   elementToSvg,

package/dist/tools/playback.d.cts

@@ -1,4 +1,4 @@
-import type { ToolMiddleware, ToolRegistry } from './registry.cjs';
+import type { AgentToolProvider, ToolMiddleware, ToolRegistry } from './registry.cjs';
 import { type PresenceActorInfo, type PresenceClock, type PresenceStore } from './presence.cjs';
 export interface PlaybackPoint {
     x: number;
@@ -116,7 +116,7 @@ export interface AgentPlaybackOptions {
     clock?: PresenceClock;
     /** 1 = natural pace, 2 = twice as fast, `Infinity` = no animation (default 1). */
     speed?: number;
-    /** Read-only tools: `glance` moves to their target only (default), `skip` doesn't, `play` plays them like writes. */
+    /** Read-only tools: `skip` shows only changes (default), `glance` moves to their target only, `play` plays them like writes. */
     reads?: PlaybackReads;
     /** Hide a cursor this long after its actor's last call (ms, default 1500; 0 keeps it). */
     linger?: number;
@@ -183,10 +183,13 @@ export declare class AgentPlayback {
     attach(id: string, surface: PlaybackSurface): () => void;
     /** The surface attached under `id`. */
     surface(id: string): PlaybackSurface | undefined;
-    /** Shows `text` in the actor's bubble on the surface it last worked on (until its next step). */
+    /**
+     * Shows `text` in the actor's bubble on the surface it last worked on (until its next step).
+     * Returns that surface's id, or null when the actor has no cursor on screen (nothing shown).
+     */
     say(text: string, options?: {
         actor?: PresenceActorInfo;
-    }): void;
+    }): string | null;
     /** Finishes every running performance at once (the calls still run and keep their results). */
     stop(): void;
     /** Collects every step played from now on (for tests). */
@@ -203,3 +206,14 @@ export declare class AgentPlayback {
 }
 /** An {@link AgentPlayback}: install it on a registry and attach editor surfaces to see calls played. */
 export declare function createAgentPlayback(options?: AgentPlaybackOptions): AgentPlayback;
+export interface PlaybackToolProviderOptions {
+    /** Provider id and default namespace (default `playback`, so the tool is `playback__say`). */
+    id?: string;
+    namespace?: string;
+}
+/**
+ * The optional `say` tool: lets an agent put a short note in its cursor's bubble, through
+ * {@link AgentPlayback.say}. Register it only where a UI shows the cursors; it changes no document
+ * and is never played itself. Without a cursor on screen it shows nothing and says so.
+ */
+export declare function createPlaybackToolProvider(playback: AgentPlayback, options?: PlaybackToolProviderOptions): AgentToolProvider;

package/dist/tools/playback.d.ts

@@ -1,4 +1,4 @@
-import type { ToolMiddleware, ToolRegistry } from './registry.js';
+import type { AgentToolProvider, ToolMiddleware, ToolRegistry } from './registry.js';
 import { type PresenceActorInfo, type PresenceClock, type PresenceStore } from './presence.js';
 export interface PlaybackPoint {
     x: number;
@@ -116,7 +116,7 @@ export interface AgentPlaybackOptions {
     clock?: PresenceClock;
     /** 1 = natural pace, 2 = twice as fast, `Infinity` = no animation (default 1). */
     speed?: number;
-    /** Read-only tools: `glance` moves to their target only (default), `skip` doesn't, `play` plays them like writes. */
+    /** Read-only tools: `skip` shows only changes (default), `glance` moves to their target only, `play` plays them like writes. */
     reads?: PlaybackReads;
     /** Hide a cursor this long after its actor's last call (ms, default 1500; 0 keeps it). */
     linger?: number;
@@ -183,10 +183,13 @@ export declare class AgentPlayback {
     attach(id: string, surface: PlaybackSurface): () => void;
     /** The surface attached under `id`. */
     surface(id: string): PlaybackSurface | undefined;
-    /** Shows `text` in the actor's bubble on the surface it last worked on (until its next step). */
+    /**
+     * Shows `text` in the actor's bubble on the surface it last worked on (until its next step).
+     * Returns that surface's id, or null when the actor has no cursor on screen (nothing shown).
+     */
     say(text: string, options?: {
         actor?: PresenceActorInfo;
-    }): void;
+    }): string | null;
     /** Finishes every running performance at once (the calls still run and keep their results). */
     stop(): void;
     /** Collects every step played from now on (for tests). */
@@ -203,3 +206,14 @@ export declare class AgentPlayback {
 }
 /** An {@link AgentPlayback}: install it on a registry and attach editor surfaces to see calls played. */
 export declare function createAgentPlayback(options?: AgentPlaybackOptions): AgentPlayback;
+export interface PlaybackToolProviderOptions {
+    /** Provider id and default namespace (default `playback`, so the tool is `playback__say`). */
+    id?: string;
+    namespace?: string;
+}
+/**
+ * The optional `say` tool: lets an agent put a short note in its cursor's bubble, through
+ * {@link AgentPlayback.say}. Register it only where a UI shows the cursors; it changes no document
+ * and is never played itself. Without a cursor on screen it shows nothing and says so.
+ */
+export declare function createPlaybackToolProvider(playback: AgentPlayback, options?: PlaybackToolProviderOptions): AgentToolProvider;

package/package.json

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