@pixerate/editor 0.141.0 → 0.143.0

package/dist/chart/index.d.ts

@@ -25,3 +25,4 @@ export * from './stream.js';
 export * from './presence.js';
 export * from './office-files.js';
 export * from './file-tools.js';
+export * from './playback.js';

package/dist/chart/index.js

@@ -925,6 +925,242 @@ function chartHitTest(scene, point, measure = (t, s, w = 400) => t.length * s *
   return point.x >= 0 && point.y >= 0 && point.x <= scene.width && point.y <= scene.height ? { kind: "chart" } : null;
 }
 
+// src/chart/presence.ts
+var ChartPresence = class extends PresenceStore {
+};
+var CHART_PRESENCE_COLORS = PRESENCE_COLORS;
+var realChartClock = realPresenceClock;
+var createInstantChartClock = createInstantPresenceClock;
+function chartPointAnchor(scene, seriesId, index) {
+  const mark = scene.marks.find((m) => (m.role === "bar" || m.role === "point") && m.target?.kind === "point" && m.target.seriesId === seriesId && m.target.index === index);
+  if (!mark) return null;
+  if (mark.kind === "rect") return { x: mark.x + mark.width / 2, y: mark.y };
+  if (mark.kind === "circle") return { x: mark.cx, y: mark.cy };
+  return null;
+}
+var anchorFor = (scene, role) => {
+  const m = scene.marks.find((x) => x.role === role);
+  if (!m) return null;
+  if (m.kind === "text") return { x: m.x, y: m.y };
+  if (m.kind === "rect") return { x: m.x + m.width / 2, y: m.y + m.height / 2 };
+  if (m.kind === "line") return { x: (m.x1 + m.x2) / 2, y: (m.y1 + m.y2) / 2 };
+  return null;
+};
+function planChartCommand(spec, scene, command, speed = 1) {
+  const ms = (n) => Math.round(n / Math.max(0.1, speed));
+  const steps = [];
+  const note = "note" in command && command.note ? command.note : void 0;
+  if (note) steps.push({ type: "say", text: note, ms: ms(500) });
+  switch (command.kind) {
+    case "say":
+      steps.push({ type: "say", text: command.text, ms: ms(900) });
+      return steps;
+    case "setValue": {
+      const at = chartPointAnchor(scene, command.seriesId, command.index);
+      const series = spec.series.find((s) => s.id === command.seriesId);
+      const from = series?.values[command.index] ?? 0;
+      const scale = series?.axis === "secondary" ? scene.valueScale2 ?? scene.valueScale : scene.valueScale;
+      if (at && scale) {
+        const px = linearMap(command.value, scale.domain, scale.range);
+        const to = scale.axis === "y" ? { x: at.x, y: px } : { x: px, y: at.y };
+        steps.push({ type: "move", to: at, ms: ms(380) }, { type: "press" }, { type: "drag", to, ms: ms(520), from, value: command.value }, { type: "release" });
+      } else steps.push({ type: "drag", to: { x: scene.plot.x + scene.plot.width / 2, y: scene.plot.y + scene.plot.height / 2 }, ms: ms(200), from, value: command.value });
+      steps.push({ type: "commit" });
+      return steps;
+    }
+    case "select": {
+      const sel = command.selection;
+      let to = null;
+      if (sel?.kind === "point") to = chartPointAnchor(scene, sel.seriesId, sel.index);
+      else if (sel) {
+        const m = scene.marks.find((x) => x.target && JSON.stringify(x.target) === JSON.stringify(sel));
+        if (m?.kind === "text") to = { x: m.x, y: m.y };
+        else if (m?.kind === "rect") to = { x: m.x + m.width / 2, y: m.y + m.height / 2 };
+        else if (m?.kind === "circle") to = { x: m.cx, y: m.cy };
+      }
+      if (to) steps.push({ type: "move", to, ms: ms(380) }, { type: "press" }, { type: "release" });
+      steps.push({ type: "commit" });
+      return steps;
+    }
+    case "update": {
+      const keys = Object.keys(command.patch);
+      const role = keys.includes("title") ? "title" : keys.includes("legend") ? "legend-label" : keys.some((k) => k === "xAxis") ? "axis" : keys.some((k) => k === "yAxis" || k === "yAxis2") ? "tick-label" : null;
+      const to = role && anchorFor(scene, role) || { x: scene.plot.x + scene.plot.width / 2, y: scene.plot.y + 12 };
+      steps.push({ type: "move", to, ms: ms(380) }, { type: "press" }, { type: "release" }, { type: "commit" });
+      return steps;
+    }
+  }
+}
+var ChartDirector = class {
+  constructor(controller, presence, options) {
+    this.controller = controller;
+    this.presence = presence;
+    this.options = options;
+    this.clock = options.clock ?? realChartClock;
+    this.queue = new PerformanceQueue(presence, {
+      clock: this.clock,
+      linger: options.linger,
+      beginGesture: (key) => controller.beginGesture(key),
+      endGesture: () => controller.endGesture()
+    });
+  }
+  controller;
+  presence;
+  options;
+  clock;
+  queue;
+  /** Acts out `commands` in order for `actor`. Resolves with one result per command. */
+  perform(actor, commands) {
+    return this.queue.run(actor, async () => {
+      const results = [];
+      for (const command of commands) results.push(await this.performOne(actor.id, command));
+      return results;
+    });
+  }
+  stale(command) {
+    const spec = this.controller.getSpec();
+    if (command.kind === "setValue") {
+      const s = spec.series.find((x) => x.id === command.seriesId);
+      if (!s) return `The series "${command.seriesId}" no longer exists.`;
+      if (command.index < 0 || command.index >= spec.categories.length) return `Category ${command.index} no longer exists.`;
+      if (!Number.isFinite(command.value)) return "The value must be a finite number.";
+    }
+    return null;
+  }
+  move(id, from, to, ms, each) {
+    return tweenPresenceCursor(this.presence, this.clock, id, from, to, ms, each);
+  }
+  async performOne(id, command) {
+    const stale = this.stale(command);
+    if (stale) return { ok: false, command, message: stale };
+    const steps = planChartCommand(this.controller.getSpec(), this.options.scene(), command, this.options.speed);
+    const where = () => {
+      const a = this.presence.getState().actors.find((x) => x.id === id);
+      return { x: a.x, y: a.y };
+    };
+    {
+      for (const step of steps) {
+        switch (step.type) {
+          case "say":
+            this.presence.set({ id, message: step.text });
+            await this.clock.wait(step.ms);
+            break;
+          case "move":
+            await this.move(id, where(), step.to, step.ms);
+            break;
+          case "press":
+            this.presence.set({ id, pressed: true });
+            break;
+          case "release":
+            this.presence.set({ id, pressed: false });
+            break;
+          case "drag": {
+            if (command.kind !== "setValue") break;
+            const stale2 = this.stale(command);
+            if (stale2) return { ok: false, command, message: stale2 };
+            const label = `${this.presence.getState().actors.find((a) => a.id === id)?.name ?? "Agent"}: edit value`;
+            await this.move(id, where(), step.to, step.ms, (e) => {
+              const v = step.from + (step.value - step.from) * e;
+              this.controller.setValue(command.seriesId, command.index, Number(v.toPrecision(12)), { label });
+            });
+            this.controller.setValue(command.seriesId, command.index, step.value, { label });
+            break;
+          }
+          case "commit": {
+            if (command.kind === "select") this.controller.select(command.selection);
+            else if (command.kind === "update") {
+              const result = this.controller.update(command.patch, command.label ? { label: command.label } : {});
+              if (!result.ok) return { ok: false, command, message: result.message };
+            }
+            break;
+          }
+        }
+      }
+      return { ok: true, command };
+    }
+  }
+};
+
+// src/chart/playback.ts
+var click = (ref) => [{ type: "target", ref }, { type: "press" }, { type: "release" }];
+var control = (id) => ({ kind: "control", id });
+function chartPointRef(series, category) {
+  return { kind: "point", id: JSON.stringify([series, category]) };
+}
+function locateChartPoint(spec, scene, ref) {
+  if (ref.kind !== "point") return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(ref.id);
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(parsed)) return null;
+  const [seriesRef, categoryRef] = parsed;
+  const series = spec.series.find((s) => s.id === seriesRef) ?? spec.series.find((s) => s.name === seriesRef);
+  const index = typeof categoryRef === "number" ? categoryRef : spec.categories.findIndex((c) => String(c) === String(categoryRef));
+  if (!series || index < 0) return null;
+  const at = chartPointAnchor(scene, series.id, index);
+  return at ? { x: at.x - 6, y: at.y - 6, width: 12, height: 12 } : null;
+}
+function planChartToolPlayback(tool, args) {
+  switch (tool) {
+    case "update_chart": {
+      const steps = [];
+      for (const key of Object.keys(args).slice(0, 4)) {
+        steps.push(...click(key === "type" && typeof args.type === "string" ? { kind: "chart-type", id: args.type } : control(key)));
+      }
+      return steps.length ? steps : null;
+    }
+    case "apply_chart_preset":
+      return [...args.layout ? click(control("preset.layout")) : [], ...args.colors ? click(control("preset.colors")) : []];
+    case "set_chart_values": {
+      const cells = Array.isArray(args.cells) ? args.cells : [];
+      const steps = cells.slice(0, 6).filter((c) => typeof c.series === "string" && (typeof c.category === "string" || typeof c.category === "number")).flatMap((c) => click(chartPointRef(c.series, c.category)));
+      return steps.length ? steps : null;
+    }
+    case "select_chart_element":
+      if (args.kind === "point" && typeof args.series === "string" && args.category !== void 0) return click(chartPointRef(args.series, args.category));
+      return typeof args.kind === "string" && args.kind !== "none" ? click(control(args.kind)) : null;
+    case "set_chart_data":
+    case "import_chart_csv":
+    case "import_chart_mermaid":
+    case "import_chart_ooxml":
+    case "add_chart_series":
+    case "update_chart_series":
+    case "remove_chart_series":
+    case "add_chart_category":
+    case "remove_chart_category":
+    case "transpose_chart":
+      return [{ type: "target", ref: { kind: "grid", id: "data" } }];
+    case "add_chart_trendline":
+    case "remove_chart_trendline":
+      return click(control("trendline.add"));
+    case "render_chart":
+      return [{ type: "target", ref: { kind: "action", id: "download-png" } }];
+    case "undo_chart":
+      return click({ kind: "action", id: "undo" });
+    case "redo_chart":
+      return click({ kind: "action", id: "redo" });
+    default:
+      return null;
+  }
+}
+var DIRECTED = /* @__PURE__ */ new Set(["set_chart_values", "select_chart_element"]);
+function withChartPlayback(provider, options) {
+  const plan = (tool) => {
+    if (tool.plan || tool.playback !== void 0) return tool;
+    if (options.director && DIRECTED.has(tool.name)) return { ...tool, playback: "self" };
+    return { ...tool, plan: (args) => planChartToolPlayback(tool.name, args) };
+  };
+  const tools = provider.tools;
+  return {
+    ...provider,
+    playbackSurface: provider.playbackSurface ?? options.surface ?? "chart",
+    tools: typeof tools === "function" ? () => tools().map(plan) : tools.map(plan)
+  };
+}
+
 // src/chart/tools.ts
 var RENDER_CHART_INSTRUCTIONS = 'Draws the chart without changing it so you can check how it looks: SVG text by default, or a PNG image with format "png" when the host can rasterize. Returns the layout warnings (hidden or thinned labels, dropped markers) alongside. An image costs tokens, so render after a batch of edits rather than after each one, and use it to check what text cannot tell you: overlapping or cut-off labels, a crowded legend, unreadable colours, whether the chart reads at the given size. For values, ids and warnings alone, get_chart is cheaper.';
 var READ = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
@@ -1488,7 +1724,7 @@ function createChartToolProvider(controller, options = {}) {
   };
   const reads = [getChart, renderChart, checkColors, recommend, getTrendline, listPresets, exportMermaid, exportOoxml];
   const writes = [updateChart, setData, setValues, addSeries, updateSeries, removeSeries, addCategory, removeCategory, importCsv, importMermaid, addTrendline, removeTrendline, applyPreset, transpose, select, drag, key, undo, redo];
-  return {
+  return withChartPlayback({
     id: options.id ?? "chart",
     namespace: options.namespace,
     title: "Chart editor",
@@ -1508,7 +1744,7 @@ function createChartToolProvider(controller, options = {}) {
         }
       });
     }
-  };
+  }, { director: !!options.director });
 }
 
 // src/chart/stream.ts
@@ -1643,162 +1879,6 @@ function blendChartScenes(from, to, t) {
 }
 var easeChartTween = (t) => 1 - Math.pow(1 - Math.max(0, Math.min(1, t)), 3);
 
-// src/chart/presence.ts
-var ChartPresence = class extends PresenceStore {
-};
-var CHART_PRESENCE_COLORS = PRESENCE_COLORS;
-var realChartClock = realPresenceClock;
-var createInstantChartClock = createInstantPresenceClock;
-function chartPointAnchor(scene, seriesId, index) {
-  const mark = scene.marks.find((m) => (m.role === "bar" || m.role === "point") && m.target?.kind === "point" && m.target.seriesId === seriesId && m.target.index === index);
-  if (!mark) return null;
-  if (mark.kind === "rect") return { x: mark.x + mark.width / 2, y: mark.y };
-  if (mark.kind === "circle") return { x: mark.cx, y: mark.cy };
-  return null;
-}
-var anchorFor = (scene, role) => {
-  const m = scene.marks.find((x) => x.role === role);
-  if (!m) return null;
-  if (m.kind === "text") return { x: m.x, y: m.y };
-  if (m.kind === "rect") return { x: m.x + m.width / 2, y: m.y + m.height / 2 };
-  if (m.kind === "line") return { x: (m.x1 + m.x2) / 2, y: (m.y1 + m.y2) / 2 };
-  return null;
-};
-function planChartCommand(spec, scene, command, speed = 1) {
-  const ms = (n) => Math.round(n / Math.max(0.1, speed));
-  const steps = [];
-  const note = "note" in command && command.note ? command.note : void 0;
-  if (note) steps.push({ type: "say", text: note, ms: ms(500) });
-  switch (command.kind) {
-    case "say":
-      steps.push({ type: "say", text: command.text, ms: ms(900) });
-      return steps;
-    case "setValue": {
-      const at = chartPointAnchor(scene, command.seriesId, command.index);
-      const series = spec.series.find((s) => s.id === command.seriesId);
-      const from = series?.values[command.index] ?? 0;
-      const scale = series?.axis === "secondary" ? scene.valueScale2 ?? scene.valueScale : scene.valueScale;
-      if (at && scale) {
-        const px = linearMap(command.value, scale.domain, scale.range);
-        const to = scale.axis === "y" ? { x: at.x, y: px } : { x: px, y: at.y };
-        steps.push({ type: "move", to: at, ms: ms(380) }, { type: "press" }, { type: "drag", to, ms: ms(520), from, value: command.value }, { type: "release" });
-      } else steps.push({ type: "drag", to: { x: scene.plot.x + scene.plot.width / 2, y: scene.plot.y + scene.plot.height / 2 }, ms: ms(200), from, value: command.value });
-      steps.push({ type: "commit" });
-      return steps;
-    }
-    case "select": {
-      const sel = command.selection;
-      let to = null;
-      if (sel?.kind === "point") to = chartPointAnchor(scene, sel.seriesId, sel.index);
-      else if (sel) {
-        const m = scene.marks.find((x) => x.target && JSON.stringify(x.target) === JSON.stringify(sel));
-        if (m?.kind === "text") to = { x: m.x, y: m.y };
-        else if (m?.kind === "rect") to = { x: m.x + m.width / 2, y: m.y + m.height / 2 };
-        else if (m?.kind === "circle") to = { x: m.cx, y: m.cy };
-      }
-      if (to) steps.push({ type: "move", to, ms: ms(380) }, { type: "press" }, { type: "release" });
-      steps.push({ type: "commit" });
-      return steps;
-    }
-    case "update": {
-      const keys = Object.keys(command.patch);
-      const role = keys.includes("title") ? "title" : keys.includes("legend") ? "legend-label" : keys.some((k) => k === "xAxis") ? "axis" : keys.some((k) => k === "yAxis" || k === "yAxis2") ? "tick-label" : null;
-      const to = role && anchorFor(scene, role) || { x: scene.plot.x + scene.plot.width / 2, y: scene.plot.y + 12 };
-      steps.push({ type: "move", to, ms: ms(380) }, { type: "press" }, { type: "release" }, { type: "commit" });
-      return steps;
-    }
-  }
-}
-var ChartDirector = class {
-  constructor(controller, presence, options) {
-    this.controller = controller;
-    this.presence = presence;
-    this.options = options;
-    this.clock = options.clock ?? realChartClock;
-    this.queue = new PerformanceQueue(presence, {
-      clock: this.clock,
-      linger: options.linger,
-      beginGesture: (key) => controller.beginGesture(key),
-      endGesture: () => controller.endGesture()
-    });
-  }
-  controller;
-  presence;
-  options;
-  clock;
-  queue;
-  /** Acts out `commands` in order for `actor`. Resolves with one result per command. */
-  perform(actor, commands) {
-    return this.queue.run(actor, async () => {
-      const results = [];
-      for (const command of commands) results.push(await this.performOne(actor.id, command));
-      return results;
-    });
-  }
-  stale(command) {
-    const spec = this.controller.getSpec();
-    if (command.kind === "setValue") {
-      const s = spec.series.find((x) => x.id === command.seriesId);
-      if (!s) return `The series "${command.seriesId}" no longer exists.`;
-      if (command.index < 0 || command.index >= spec.categories.length) return `Category ${command.index} no longer exists.`;
-      if (!Number.isFinite(command.value)) return "The value must be a finite number.";
-    }
-    return null;
-  }
-  move(id, from, to, ms, each) {
-    return tweenPresenceCursor(this.presence, this.clock, id, from, to, ms, each);
-  }
-  async performOne(id, command) {
-    const stale = this.stale(command);
-    if (stale) return { ok: false, command, message: stale };
-    const steps = planChartCommand(this.controller.getSpec(), this.options.scene(), command, this.options.speed);
-    const where = () => {
-      const a = this.presence.getState().actors.find((x) => x.id === id);
-      return { x: a.x, y: a.y };
-    };
-    {
-      for (const step of steps) {
-        switch (step.type) {
-          case "say":
-            this.presence.set({ id, message: step.text });
-            await this.clock.wait(step.ms);
-            break;
-          case "move":
-            await this.move(id, where(), step.to, step.ms);
-            break;
-          case "press":
-            this.presence.set({ id, pressed: true });
-            break;
-          case "release":
-            this.presence.set({ id, pressed: false });
-            break;
-          case "drag": {
-            if (command.kind !== "setValue") break;
-            const stale2 = this.stale(command);
-            if (stale2) return { ok: false, command, message: stale2 };
-            const label = `${this.presence.getState().actors.find((a) => a.id === id)?.name ?? "Agent"}: edit value`;
-            await this.move(id, where(), step.to, step.ms, (e) => {
-              const v = step.from + (step.value - step.from) * e;
-              this.controller.setValue(command.seriesId, command.index, Number(v.toPrecision(12)), { label });
-            });
-            this.controller.setValue(command.seriesId, command.index, step.value, { label });
-            break;
-          }
-          case "commit": {
-            if (command.kind === "select") this.controller.select(command.selection);
-            else if (command.kind === "update") {
-              const result = this.controller.update(command.patch, command.label ? { label: command.label } : {});
-              if (!result.ok) return { ok: false, command, message: result.message };
-            }
-            break;
-          }
-        }
-      }
-      return { ok: true, command };
-    }
-  }
-};
-
 // src/chart/office-files.ts
 var OfficeChartsError = class extends Error {
   constructor(message, options) {
@@ -2168,6 +2248,7 @@ export {
   chartMovingAverage,
   chartPointAnchor,
   chartPointColor,
+  chartPointRef,
   chartPresetPatch,
   chartQuantile,
   chartRasterSize,
@@ -2231,6 +2312,7 @@ export {
   layoutChart,
   layoutSparkline,
   linearMap,
+  locateChartPoint,
   monochromeChartPalette,
   niceLogScale,
   niceScale,
@@ -2246,6 +2328,7 @@ export {
   parseChartValue,
   parsePartialChartJson,
   planChartCommand,
+  planChartToolPlayback,
   rasterizeChartSvg,
   realChartClock,
   recommendChartTypes,
@@ -2262,5 +2345,6 @@ export {
   summarizeChart,
   summarizeChartSeries,
   trendNumberText,
-  uniqueChartSeriesId
+  uniqueChartSeriesId,
+  withChartPlayback
 };

package/dist/chart/playback.d.cts

@@ -0,0 +1,22 @@
+import type { AgentToolProvider } from '../tools/registry.cjs';
+import type { PlaybackRef, PlaybackStep } from '../tools/playback.cjs';
+import type { ChartScene, ChartSpec } from './types.cjs';
+/** A point ref: a series (id or name) and a category (index or label), as the tools take them. */
+export declare function chartPointRef(series: string, category: string | number): PlaybackRef;
+/** Where a point ref is drawn in `scene` (a small box around its anchor), or null. */
+export declare function locateChartPoint(spec: ChartSpec, scene: ChartScene, ref: PlaybackRef): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | null;
+/** The cursor steps for one chart tool call (by bare name), or null to fall back to the ids it names. */
+export declare function planChartToolPlayback(tool: string, args: Record<string, any>): PlaybackStep[] | null;
+/**
+ * Gives a chart tool provider agent playback on `surface` (default `chart`, where `ChartEditor`
+ * attaches). With a director, value changes and selections play through it (`playback: 'self'`).
+ */
+export declare function withChartPlayback(provider: AgentToolProvider, options: {
+    director: boolean;
+    surface?: string;
+}): AgentToolProvider;

package/dist/chart/playback.d.ts

@@ -0,0 +1,22 @@
+import type { AgentToolProvider } from '../tools/registry.js';
+import type { PlaybackRef, PlaybackStep } from '../tools/playback.js';
+import type { ChartScene, ChartSpec } from './types.js';
+/** A point ref: a series (id or name) and a category (index or label), as the tools take them. */
+export declare function chartPointRef(series: string, category: string | number): PlaybackRef;
+/** Where a point ref is drawn in `scene` (a small box around its anchor), or null. */
+export declare function locateChartPoint(spec: ChartSpec, scene: ChartScene, ref: PlaybackRef): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | null;
+/** The cursor steps for one chart tool call (by bare name), or null to fall back to the ids it names. */
+export declare function planChartToolPlayback(tool: string, args: Record<string, any>): PlaybackStep[] | null;
+/**
+ * Gives a chart tool provider agent playback on `surface` (default `chart`, where `ChartEditor`
+ * attaches). With a director, value changes and selections play through it (`playback: 'self'`).
+ */
+export declare function withChartPlayback(provider: AgentToolProvider, options: {
+    director: boolean;
+    surface?: string;
+}): AgentToolProvider;

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

@@ -87,6 +87,7 @@ function normalizePlan(plan) {
 }
 var isErrorResult = (value) => !!value && typeof value === "object" && value.isError === true;
 var center = (r) => ({ x: r.x + r.width / 2, y: r.y + r.height / 2 });
+var finiteRect = (r) => r && [r.x, r.y, r.width, r.height].every(Number.isFinite) ? r : null;
 var GLANCE_STEPS = /* @__PURE__ */ new Set(["move", "target", "focus", "say", "wait", "commit"]);
 var AgentPlayback = class {
   /** 1 = natural pace; `Infinity` plays nothing (calls run instantly). Takes effect on the next step. */
@@ -222,7 +223,7 @@ var AgentPlayback = class {
     const pace = () => Math.max(0.1, this.speed) * (run.glance ? 1.6 : 1);
     const wait = (ms) => instant() || ms <= 0 ? Promise.resolve() : this.clock.wait(ms / pace());
     const presence = surface.presence;
-    const locate = (ref) => surface.locate?.(ref.kind === "item" ? { kind: surface.defaultKind ?? "item", id: ref.id } : ref) ?? null;
+    const locate = (ref) => finiteRect(surface.locate?.(ref.kind === "item" ? { kind: surface.defaultKind ?? "item", id: ref.id } : ref) ?? null);
     const record = (step) => {
       for (const list of this.recordings) list.push({ actor: id, surface: surfaceId, tool: call.name, step });
     };
@@ -346,7 +347,7 @@ var AgentPlayback = class {
         return wait(60);
       case "type": {
         const total = step.ms ?? Math.min(900, 40 * step.text.length + 150);
-        if (instant() || total <= 0) {
+        if (instant() || !(total > 0) || !Number.isFinite(total)) {
           presence.set({ id, message: step.text });
           return;
         }
@@ -366,11 +367,12 @@ var AgentPlayback = class {
   }
   /** Glides along a slight arc with ease-out, by elapsed time (fewer frames in a throttled tab, never longer). */
   async glide(presence, id, to, ms, instant) {
+    if (!Number.isFinite(to.x) || !Number.isFinite(to.y)) return;
     const a = presence.get(id);
-    const from = a ? { x: a.x, y: a.y } : to;
+    const from = a && Number.isFinite(a.x) && Number.isFinite(a.y) ? { x: a.x, y: a.y } : to;
     const dist = Math.hypot(to.x - from.x, to.y - from.y);
     const duration = (ms ?? Math.min(900, 260 + dist * 0.5)) / Math.max(0.1, this.speed);
-    if (instant() || dist < 1 || duration <= 0) {
+    if (instant() || dist < 1 || !(duration > 0) || !Number.isFinite(duration)) {
       presence.set({ id, x: to.x, y: to.y });
       return;
     }

package/dist/{chunk-E747F3D5.js → chunk-CC6WKVIH.js}

@@ -8,6 +8,7 @@ import {
   formatIsoDate,
   formatIsoDateTime,
   formatTextFunction,
+  indexToColName,
   isBlank,
   isFormulaError,
   isoDateHasTime,
@@ -2947,16 +2948,16 @@ var FormulaEvaluator = class {
     const value = this.evaluateNode(argument);
     if (!Array.isArray(value)) return value;
     if (value.length <= 1) return firstValue(value);
-    const cell = this.context.getFormulaCell?.();
-    if (argument.type === "Range" && cell) {
+    const cell2 = this.context.getFormulaCell?.();
+    if (argument.type === "Range" && cell2) {
       const range = toFormulaRange(value);
       const top = Math.min(argument.startRow, argument.endRow);
       const left = Math.min(colNameToIndex(argument.startCol), colNameToIndex(argument.endCol));
       if (range.cols === 1) {
-        const r = cell.row - top;
+        const r = cell2.row - top;
         if (r >= 0 && r < range.rows) return range.values[r];
       } else if (range.rows === 1) {
-        const c = colNameToIndex(cell.col) - left;
+        const c = colNameToIndex(cell2.col) - left;
         if (c >= 0 && c < range.cols) return range.values[c];
       }
       return this.fail("#VALUE!", `The @ operator found no cell of ${argument.raw} in the formula's row or column.`);
@@ -3757,6 +3758,84 @@ function getFillDirection(source, target) {
   return null;
 }
 
+// src/spreadsheet/playback.ts
+var CELL = /^\s*\$?([A-Za-z]{1,3})\$?(\d+)\s*$/;
+var COL = /^\s*([A-Za-z]{1,3})\s*$/;
+var ROW = /^\s*(\d+)\s*$/;
+function parseSpreadsheetPlaybackRef(ref) {
+  const [a, b = a] = ref.id.split(":");
+  if (!a) return null;
+  if (ref.kind === "cell") {
+    const s = CELL.exec(a);
+    const e = CELL.exec(b);
+    if (!s || !e) return null;
+    const r = [Number(s[2]) - 1, Number(e[2]) - 1];
+    const c = [colNameToIndex(s[1].toUpperCase()), colNameToIndex(e[1].toUpperCase())];
+    return { startRow: Math.min(r[0], r[1]), endRow: Math.max(r[0], r[1]), startCol: Math.min(c[0], c[1]), endCol: Math.max(c[0], c[1]) };
+  }
+  if (ref.kind === "row") {
+    const s = ROW.exec(a);
+    const e = ROW.exec(b);
+    if (!s || !e) return null;
+    return { startRow: Math.min(+s[1], +e[1]) - 1, endRow: Math.max(+s[1], +e[1]) - 1, startCol: null, endCol: null };
+  }
+  if (ref.kind === "column") {
+    const s = COL.exec(a);
+    const e = COL.exec(b);
+    if (!s || !e) return null;
+    const c = [colNameToIndex(s[1].toUpperCase()), colNameToIndex(e[1].toUpperCase())];
+    return { startRow: null, endRow: null, startCol: Math.min(c[0], c[1]), endCol: Math.max(c[0], c[1]) };
+  }
+  return null;
+}
+var cell = (id) => ({ kind: "cell", id });
+var shown = (v) => {
+  if (v === null || v === void 0 || v === "") return null;
+  const text = String(v);
+  return text.length > 40 ? `${text.slice(0, 39)}\u2026` : text;
+};
+function planSpreadsheetToolPlayback(tool, args) {
+  const count = Number.isInteger(args.count) && args.count > 0 ? args.count : 1;
+  switch (tool) {
+    case "set_cell": {
+      if (typeof args.cell !== "string") return null;
+      const value = shown(args.value);
+      return [{ type: "target", ref: cell(args.cell) }, { type: "press" }, { type: "release" }, ...value ? [{ type: "type", text: value }] : []];
+    }
+    case "set_range": {
+      const start = typeof args.start === "string" ? CELL.exec(args.start) : null;
+      const rows = Array.isArray(args.values) ? args.values : [];
+      if (!start || !rows.length) return null;
+      const width = Math.max(1, ...rows.map((r) => Array.isArray(r) ? r.length : 1));
+      const col = colNameToIndex(start[1].toUpperCase());
+      const end = `${indexToColName(col + width - 1)}${Number(start[2]) + rows.length - 1}`;
+      const first = shown(rows.flat().find((v) => v !== null && v !== void 0 && v !== ""));
+      return [
+        { type: "target", ref: cell(args.start) },
+        { type: "press" },
+        { type: "target", ref: cell(`${args.start}:${end}`) },
+        { type: "release" },
+        ...first ? [{ type: "type", text: first }] : []
+      ];
+    }
+    case "insert_rows":
+    case "delete_rows": {
+      const from = Number(tool === "insert_rows" ? args.before : args.start);
+      if (!Number.isInteger(from) || from < 1) return null;
+      return [{ type: "target", ref: { kind: "row", id: `${from}:${from + count - 1}` } }, { type: "press" }, { type: "release" }];
+    }
+    case "insert_columns":
+    case "delete_columns": {
+      const from = String(tool === "insert_columns" ? args.before : args.start ?? "");
+      if (!COL.test(from)) return null;
+      const index = colNameToIndex(from.trim().toUpperCase());
+      return [{ type: "target", ref: { kind: "column", id: `${indexToColName(index)}:${indexToColName(index + count - 1)}` } }, { type: "press" }, { type: "release" }];
+    }
+    default:
+      return null;
+  }
+}
+
 export {
   tokenizeFormula,
   WHOLE_COLUMN_END_ROW,
@@ -3794,5 +3873,7 @@ export {
   roundFloat,
   fillSeries,
   computeFillTarget,
-  getFillDirection
+  getFillDirection,
+  parseSpreadsheetPlaybackRef,
+  planSpreadsheetToolPlayback
 };