@pixerate/editor-svelte 0.101.4 → 0.103.1

package/dist/agentTools.svelte.d.ts

@@ -1,4 +1,4 @@
-import type { AgentToolProvider, ToolRegistry } from "@pixerate/editor/tools";
+import type { AgentPlayback, AgentToolProvider, ToolRegistry } from "@pixerate/editor/tools";
 type MaybeGetter<T> = T | (() => T);
 /**
  * Registers a tool provider with a `ToolRegistry` for the lifetime of the
@@ -7,5 +7,7 @@ type MaybeGetter<T> = T | (() => T);
  * `useAgentToolProvider(registry, () => editor && createRichTextToolProvider(editor, { id }))`:
  * when the getter returns a different provider, the old one is unregistered.
  */
-export declare function useAgentToolProvider(registry: MaybeGetter<ToolRegistry | null | undefined>, provider: MaybeGetter<AgentToolProvider | null | undefined>): void;
+export declare function useAgentToolProvider(registry: MaybeGetter<ToolRegistry | null | undefined>, provider: MaybeGetter<AgentToolProvider | null | undefined>, options?: {
+    playback?: MaybeGetter<AgentPlayback | null | undefined>;
+}): void;
 export {};

package/dist/agentTools.svelte.js

@@ -6,7 +6,14 @@ const read = (value) => typeof value === "function" ? value() : value;
  * `useAgentToolProvider(registry, () => editor && createRichTextToolProvider(editor, { id }))`:
  * when the getter returns a different provider, the old one is unregistered.
  */
-export function useAgentToolProvider(registry, provider) {
+export function useAgentToolProvider(registry, provider, options = {}) {
+    $effect(() => {
+        const currentRegistry = read(registry);
+        const playback = options.playback === undefined ? undefined : read(options.playback);
+        // Plays the registry's calls with this playback (installed once per registry).
+        if (currentRegistry && playback)
+            playback.install(currentRegistry);
+    });
     $effect(() => {
         const currentRegistry = read(registry);
         const currentProvider = read(provider);

package/dist/animation-editor/AnimationEditor.svelte

@@ -10,6 +10,9 @@
   import type { EffectProvider } from '@pixerate/editor/effects';
   import { useEffects } from '../effects/effects.svelte.js';
   import AnimationEffectsPanel from './AnimationEffectsPanel.svelte';
+  import type { AgentPlayback } from '@pixerate/editor/tools';
+  import { createElementPlaybackSurface, getAgentPlayback } from '../playback/playback.svelte.js';
+  import PresenceLayer from '../playback/PresenceLayer.svelte';
 
   interface Props {
     controller: AnimationEditorController;
@@ -33,9 +36,32 @@
      */
     effects?: EffectProvider | null;
     class?: string;
+    /**
+     * Agent playback: act out the animation tools' calls here with the agent's cursor (default:
+     * `setAgentPlayback` above; `null` turns it off).
+     */
+    playback?: AgentPlayback | null;
+    /** The playback surface id (default `animation`, where the animation tool providers play). */
+    playbackId?: string;
+    /** Bring the editor on screen (switch to its tab) before the agent acts. */
+    onplaybackreveal?: () => void | Promise<void>;
   }
 
-  let { controller, values, onionSkin, motionPaths, showIssues = true, editable = true, effects, class: className = '' }: Props = $props();
+  let { controller, values, onionSkin, motionPaths, showIssues = true, editable = true, effects, class: className = '', playback, playbackId = 'animation', onplaybackreveal }: Props = $props();
+
+  // Agent playback: the cursor clicks shots in the timeline and visits elements on the stage
+  // (whose SVG keeps the artwork's ids, prefixed `ae-`).
+  let root: HTMLDivElement | undefined = $state();
+  const ambientPlayback = getAgentPlayback();
+  const playing = $derived((playback === undefined ? ambientPlayback : playback) ?? null);
+  const agentPresence = createElementPlaybackSurface(() => playing, () => playbackId, () => root, () => ({
+    defaultKind: 'shot',
+    selectors: {
+      shot: (id: string) => `[data-shot="${CSS.escape(id)}"]`,
+      element: (id: string) => `[data-animation-stage] [id="ae-${CSS.escape(id)}"]`
+    },
+    reveal: onplaybackreveal
+  }));
   useEffects(() => controller, () => effects);
   const view = animationEditorStateOf(() => controller);
   const editor = $derived(view.current);
@@ -84,14 +110,20 @@
   scene settings by hand. Every edit is one undo step.
 -->
 {#if !editable}
-  <div class="flex flex-col gap-2 {className}" data-animation-editor="">
+  <div bind:this={root} class="relative flex flex-col gap-2 {className}" data-animation-editor="">
+    {#if playing}
+      <PresenceLayer presence={agentPresence} />
+    {/if}
     <AnimationStage {controller} {values} onionSkin={onionSkin} {motionPaths} class="rounded-md border border-border bg-muted/40" />
     <PlayheadScrubber {controller} />
     {@render issueList()}
   </div>
 {:else}
   <!-- svelte-ignore a11y_no_static_element_interactions -->
-  <div class="grid gap-3 lg:grid-cols-[minmax(0,1fr)_20rem] {className}" data-animation-editor="" {onkeydown}>
+  <div bind:this={root} class="relative grid gap-3 lg:grid-cols-[minmax(0,1fr)_20rem] {className}" data-animation-editor="" {onkeydown}>
+    {#if playing}
+      <PresenceLayer presence={agentPresence} />
+    {/if}
     <div class="flex min-w-0 flex-col gap-2">
       <AnimationStage
         {controller}

package/dist/animation-editor/AnimationEditor.svelte.d.ts

@@ -1,5 +1,6 @@
 import { type AnimationEditorController, type MotionFrameOptions, type MotionOnionSkin } from '@pixerate/editor/animation-editor';
 import type { EffectProvider } from '@pixerate/editor/effects';
+import type { AgentPlayback } from '@pixerate/editor/tools';
 interface Props {
     controller: AnimationEditorController;
     values?: MotionFrameOptions['values'];
@@ -22,6 +23,15 @@ interface Props {
      */
     effects?: EffectProvider | null;
     class?: string;
+    /**
+     * Agent playback: act out the animation tools' calls here with the agent's cursor (default:
+     * `setAgentPlayback` above; `null` turns it off).
+     */
+    playback?: AgentPlayback | null;
+    /** The playback surface id (default `animation`, where the animation tool providers play). */
+    playbackId?: string;
+    /** Bring the editor on screen (switch to its tab) before the agent acts. */
+    onplaybackreveal?: () => void | Promise<void>;
 }
 declare const AnimationEditor: import("svelte").Component<Props, {}, "">;
 type AnimationEditor = ReturnType<typeof AnimationEditor>;

package/dist/canvas/createCanvasPlaybackSurface.svelte.d.ts

@@ -0,0 +1,30 @@
+import { type CanvasEdge, type CanvasNode, type NodeRectOptions } from '@pixerate/editor/canvas';
+import type { AgentPlayback, PresenceStore } from '@pixerate/editor/tools';
+type MaybeGetter<T> = T | (() => T);
+export interface CreateCanvasPlaybackSurfaceOptions<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdge = CanvasEdge> {
+    /** The flow's nodes and edges now (e.g. the `bind:nodes` state). */
+    getNodes: () => readonly TNode[];
+    getEdges?: () => readonly TEdge[];
+    /** The flow viewport now (Svelte Flow's `useSvelteFlow().getViewport`). */
+    getViewport: () => {
+        x: number;
+        y: number;
+        zoom: number;
+    };
+    /** The element the flow fills (and the `<PresenceLayer>` sits in); for bounds and screen mapping. */
+    container: () => HTMLElement | null | undefined;
+    /** Node size resolution (match the canvas' own). */
+    rectOptions?: NodeRectOptions;
+    /** Bring the canvas on screen (switch to its tab) before the agent acts. */
+    reveal?: () => void | Promise<void>;
+    /** Whether the canvas is on screen (default: the container has a size and the page is visible). */
+    visible?: () => boolean;
+}
+/**
+ * Svelte 5 rune: attaches the node canvas as an agent playback surface under `id` (the canvas tool
+ * provider's id) for the component's lifetime (call during init) and returns its cursors. Draw them
+ * with `<PresenceLayer presence={presence} viewport={viewport} />` inside the container. Parity with
+ * React's `useCanvasPlaybackSurface`.
+ */
+export declare function createCanvasPlaybackSurface<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdge = CanvasEdge>(playback: MaybeGetter<AgentPlayback | null | undefined>, id: MaybeGetter<string | null | undefined>, options: CreateCanvasPlaybackSurfaceOptions<TNode, TEdge>): PresenceStore;
+export {};

package/dist/canvas/createCanvasPlaybackSurface.svelte.js

@@ -0,0 +1,43 @@
+import { createCanvasPlaybackLocator } from '@pixerate/editor/canvas';
+import { createPlaybackSurface } from '../playback/playback.svelte.js';
+/**
+ * Svelte 5 rune: attaches the node canvas as an agent playback surface under `id` (the canvas tool
+ * provider's id) for the component's lifetime (call during init) and returns its cursors. Draw them
+ * with `<PresenceLayer presence={presence} viewport={viewport} />` inside the container. Parity with
+ * React's `useCanvasPlaybackSurface`.
+ */
+export function createCanvasPlaybackSurface(playback, id, options) {
+    const locate = createCanvasPlaybackLocator({
+        getNodes: options.getNodes,
+        getEdges: () => options.getEdges?.() ?? [],
+        rectOptions: options.rectOptions
+    });
+    const box = () => options.container()?.getBoundingClientRect() ?? null;
+    return createPlaybackSurface(playback, id, {
+        defaultKind: 'node',
+        locate,
+        bounds: () => {
+            const r = box();
+            const { x, y, zoom } = options.getViewport();
+            return r && r.width > 0 ? { x: -x / zoom, y: -y / zoom, width: r.width / zoom, height: r.height / zoom } : null;
+        },
+        visible: () => {
+            if (options.visible)
+                return options.visible();
+            const r = box();
+            const hidden = typeof document !== 'undefined' && document.visibilityState === 'hidden';
+            return !!r && r.width > 0 && r.height > 0 && !hidden;
+        },
+        toViewport: (p) => {
+            const r = box();
+            const { x, y, zoom } = options.getViewport();
+            return { x: (r?.left ?? 0) + p.x * zoom + x, y: (r?.top ?? 0) + p.y * zoom + y };
+        },
+        fromViewport: (p) => {
+            const r = box();
+            const { x, y, zoom } = options.getViewport();
+            return { x: (p.x - (r?.left ?? 0) - x) / zoom, y: (p.y - (r?.top ?? 0) - y) / zoom };
+        },
+        reveal: () => options.reveal?.()
+    });
+}

package/dist/canvas/index.d.ts

@@ -18,6 +18,8 @@ export { createStreamingCanvas, type CreateStreamingCanvasOptions } from './crea
 export { createCanvasArrange, createCanvasArrangeShortcuts, type CanvasArrange, type CreateCanvasArrangeOptions, type CanvasArrangeShortcutsOptions } from './createCanvasArrange.svelte.js';
 export { createCanvasScenes, type CanvasScenes, type CreateCanvasScenesOptions } from './createCanvasScenes.svelte.js';
 export { createCanvasCapture, type CreateCanvasCaptureOptions } from './createCanvasCapture.js';
+export { createCanvasPlaybackSurface, type CreateCanvasPlaybackSurfaceOptions } from './createCanvasPlaybackSurface.svelte.js';
+export { default as PresenceLayer } from '../playback/PresenceLayer.svelte';
 export { default as CanvasGuidesLayer } from './CanvasGuidesLayer.svelte';
 export { createCanvasDraw, type CanvasDraw, type CreateCanvasDrawOptions } from './createCanvasDraw.svelte.js';
 export { default as CanvasDrawLayer } from './CanvasDrawLayer.svelte';

package/dist/canvas/index.js

@@ -26,7 +26,8 @@ export { createCanvasMultiDrag } from './createCanvasMultiDrag.svelte.js';
 export { getMarqueeSelectionPreset, handleDeselectOnEscape } from './createCanvasSelection.svelte.js';
 // Viewport floating scrollbar component
 export { default as FloatingHorizontalScrollbar } from './FloatingHorizontalScrollbar.svelte';
-// Agent presence visual layer
+// Agent presence visual layer. Deprecated: use `PresenceLayer` with `createCanvasPlaybackSurface`
+// (agent playback), which plays every canvas tool call.
 export { default as AgentPresenceLayer } from './AgentPresenceLayer.svelte';
 export { default as AgentCursorPresence } from './AgentCursorPresence.svelte';
 // Streaming canvas rune
@@ -35,6 +36,8 @@ export { createStreamingCanvas } from './createStreamingCanvas.svelte.js';
 export { createCanvasArrange, createCanvasArrangeShortcuts } from './createCanvasArrange.svelte.js';
 export { createCanvasScenes } from './createCanvasScenes.svelte.js';
 export { createCanvasCapture } from './createCanvasCapture.js';
+export { createCanvasPlaybackSurface } from './createCanvasPlaybackSurface.svelte.js';
+export { default as PresenceLayer } from '../playback/PresenceLayer.svelte';
 export { default as CanvasGuidesLayer } from './CanvasGuidesLayer.svelte';
 // Freehand drawing tools (pen, highlighter, eraser)
 export { createCanvasDraw } from './createCanvasDraw.svelte.js';

package/dist/chart/ChartEditor.svelte

@@ -1,6 +1,9 @@
 <script lang="ts">
   import type { ComponentProps } from 'svelte';
-  import { describeChartSelection, downloadChartPng, type ChartController, type DownloadChartPngOptions } from '@pixerate/editor/chart';
+  import { describeChartSelection, downloadChartPng, locateChartPoint, ChartPresence, type ChartController, type ChartScene, type DownloadChartPngOptions } from '@pixerate/editor/chart';
+  import type { AgentPlayback, PlaybackPoint, PlaybackRect, PlaybackRef } from '@pixerate/editor/tools';
+  import { createPlaybackSurface, getAgentPlayback } from '../playback/playback.svelte.js';
+  import PresenceLayer from '../playback/PresenceLayer.svelte';
   import ChartCanvas from './ChartCanvas.svelte';
   import ChartDataGrid from './ChartDataGrid.svelte';
   import ChartInspector from './ChartInspector.svelte';
@@ -21,9 +24,83 @@
     height?: number;
     canvasProps?: Omit<ComponentProps<typeof ChartCanvas>, 'controller' | 'height'>;
     class?: string;
+    /**
+     * Agent playback: act out the chart tools' calls here with the agent's cursor, on the inspector,
+     * the data grid and the toolbar (default: `setAgentPlayback` above; `null` turns it off). With
+     * `canvasProps.presence` (a `ChartDirector`'s), the director's drags share the cursor.
+     */
+    playback?: AgentPlayback | null;
+    /** The playback surface id (default `chart`, where the chart tool provider plays). */
+    playbackId?: string;
+    /** Bring the editor on screen (switch to its tab) before the agent acts. */
+    onplaybackreveal?: () => void | Promise<void>;
   }
 
-  let { controller, showInspector = true, showDataGrid = true, showToolbar = true, pngOptions, height = 380, canvasProps = {}, class: className = '' }: Props = $props();
+  let { controller, showInspector = true, showDataGrid = true, showToolbar = true, pngOptions, height = 380, canvasProps = {}, class: className = '', playback, playbackId = 'chart', onplaybackreveal }: Props = $props();
+
+  // Agent playback in the chart's scene coordinates, so a director's drags (in the same presence
+  // store) and the editor's own controls share one cursor. Controls outside the chart are mapped
+  // into scene units through the SVG's box.
+  let root: HTMLDivElement | undefined = $state();
+  const ownScene: { current: ChartScene | null } = { current: null };
+  const sceneRef = $derived(canvasProps.sceneRef ?? ownScene);
+  const ambientPlayback = getAgentPlayback();
+  const playing = $derived((playback === undefined ? ambientPlayback : playback) ?? null);
+  const svgBox = () => {
+    const svg = root?.querySelector<SVGSVGElement>('[data-chart-canvas] svg');
+    const r = svg?.getBoundingClientRect();
+    const vb = svg?.viewBox?.baseVal;
+    if (!svg || !r || !vb || !vb.width || !vb.height) return null;
+    return { left: r.left, top: r.top, sx: r.width / vb.width, sy: r.height / vb.height, vx: vb.x, vy: vb.y };
+  };
+  const sceneToClient = (p: PlaybackPoint): PlaybackPoint | null => {
+    const b = svgBox();
+    return b ? { x: b.left + (p.x - b.vx) * b.sx, y: b.top + (p.y - b.vy) * b.sy } : null;
+  };
+  const clientToScene = (p: PlaybackPoint): PlaybackPoint | null => {
+    const b = svgBox();
+    return b && b.sx && b.sy ? { x: (p.x - b.left) / b.sx + b.vx, y: (p.y - b.top) / b.sy + b.vy } : null;
+  };
+  const elementRect = (selector: string): PlaybackRect | null => {
+    const el = root?.querySelector(selector);
+    // The inspector scrolls on its own: bring the control into its view first.
+    el?.scrollIntoView?.({ block: 'nearest' });
+    const r = el?.getBoundingClientRect();
+    if (!r || r.width <= 0) return null;
+    const a = clientToScene({ x: r.left, y: r.top });
+    const b = clientToScene({ x: r.right, y: r.bottom });
+    return a && b ? { x: a.x, y: a.y, width: b.x - a.x, height: b.y - a.y } : null;
+  };
+  const SELECTORS: Record<string, (id: string) => string> = {
+    control: (id) => `[data-option="${CSS.escape(id)}"]`,
+    'chart-type': (id) => `[data-chart-type="${CSS.escape(id)}"]`,
+    action: (id) => `[data-action="${CSS.escape(id)}"]`,
+    grid: () => '[data-chart-grid]'
+  };
+  // svelte-ignore state_referenced_locally
+  const ownPresence = canvasProps.presence ?? new ChartPresence();
+  const presence = createPlaybackSurface(() => playing, () => playbackId, () => ({
+    defaultKind: 'point',
+    locate: (ref: PlaybackRef) => {
+      if (ref.kind === 'point') return sceneRef.current ? locateChartPoint(controller.getSpec(), sceneRef.current, ref) : null;
+      const selector = SELECTORS[ref.kind]?.(ref.id);
+      return selector ? elementRect(selector) : null;
+    },
+    bounds: () => (sceneRef.current ? { x: 0, y: 0, width: sceneRef.current.width, height: sceneRef.current.height } : null),
+    visible: () => {
+      const r = root?.getBoundingClientRect();
+      return !!r && r.width > 0 && r.height > 0 && !(typeof document !== 'undefined' && document.visibilityState === 'hidden');
+    },
+    toViewport: (p: PlaybackPoint) => sceneToClient(p) ?? p,
+    fromViewport: (p: PlaybackPoint) => clientToScene(p) ?? p,
+    reveal: () => onplaybackreveal?.()
+  }), ownPresence);
+  /** Scene units → pixels in the editor's root, for the cursor layer. */
+  const sceneToRoot = (p: PlaybackPoint): PlaybackPoint => {
+    const c = sceneToClient(p);
+    const box = root?.getBoundingClientRect();
+    return c && box ? { x: c.x - box.left, y: c.y - box.top } : p;
+  };
 
   const view = chartStateOf(() => controller);
   const chart = $derived(view.current);
@@ -34,7 +111,10 @@
   }
 </script>
 
-<div class="flex flex-col gap-2 {className}" data-chart-editor="">
+<div bind:this={root} class="relative flex flex-col gap-2 {className}" data-chart-editor="">
+  {#if playing}
+    <PresenceLayer {presence} viewport={sceneToRoot} />
+  {/if}
   {#if showToolbar}
     <div class="flex items-center gap-1" data-chart-toolbar="">
       <button type="button" class={chartButtonClass} disabled={!chart.canUndo} title={chart.undoLabel ? `Undo ${chart.undoLabel}` : 'Undo'} data-action="undo" onclick={() => controller.undo()}>Undo</button>
@@ -53,7 +133,8 @@
   {/if}
   <div class="flex min-h-0 flex-col gap-2 md:flex-row">
     <div class="min-w-0 flex-1 rounded-md border border-border bg-background p-1">
-      <ChartCanvas {controller} {height} {...canvasProps} />
+      <!-- With playback the editor draws the cursor (over the inspector too), so the canvas doesn't. -->
+      <ChartCanvas {controller} {height} {...canvasProps} {sceneRef} presence={playing ? undefined : canvasProps.presence} />
     </div>
     {#if showInspector}
       <!-- Side by side, the canvas sets the row's height and the inspector scrolls within it. -->

package/dist/chart/ChartEditor.svelte.d.ts

@@ -1,5 +1,6 @@
 import type { ComponentProps } from 'svelte';
 import { type ChartController, type DownloadChartPngOptions } from '@pixerate/editor/chart';
+import type { AgentPlayback } from '@pixerate/editor/tools';
 import ChartCanvas from './ChartCanvas.svelte';
 interface Props {
     controller: ChartController;
@@ -15,6 +16,16 @@ interface Props {
     height?: number;
     canvasProps?: Omit<ComponentProps<typeof ChartCanvas>, 'controller' | 'height'>;
     class?: string;
+    /**
+     * Agent playback: act out the chart tools' calls here with the agent's cursor, on the inspector,
+     * the data grid and the toolbar (default: `setAgentPlayback` above; `null` turns it off). With
+     * `canvasProps.presence` (a `ChartDirector`'s), the director's drags share the cursor.
+     */
+    playback?: AgentPlayback | null;
+    /** The playback surface id (default `chart`, where the chart tool provider plays). */
+    playbackId?: string;
+    /** Bring the editor on screen (switch to its tab) before the agent acts. */
+    onplaybackreveal?: () => void | Promise<void>;
 }
 declare const ChartEditor: import("svelte").Component<Props, {}, "">;
 type ChartEditor = ReturnType<typeof ChartEditor>;

package/dist/image-editor/ImageEditor.svelte

@@ -11,8 +11,13 @@
     ImageEditorAIHooks,
     ImageEditorFit,
   } from '@pixerate/editor/image-editor';
+  import type { AgentPlayback, PlaybackPoint, PlaybackRect, PlaybackRef } from '@pixerate/editor/tools';
+  import { createPlaybackSurface, getAgentPlayback } from '../playback/playback.svelte.js';
+  import PresenceLayer from '../playback/PresenceLayer.svelte';
   import {
     canvasToImagePoint,
+    imageToCanvasPoint,
+    createImagePlaybackLocator,
     hitTestCrop,
     getCropCursor,
     calculateCropDrag,
@@ -71,6 +76,15 @@
      * with an Effects section in the Layers tab. Optional: without one the editor is as before.
      */
     effects?: EffectProvider | null;
+    /**
+     * Agent playback: act out the image tools' calls here with the agent's cursor, opening the
+     * panel each tool belongs to (default: `setAgentPlayback` above; `null` turns it off).
+     */
+    playback?: AgentPlayback | null;
+    /** The playback surface id (default `image`, where the image tool providers play). */
+    playbackId?: string;
+    /** Bring the editor on screen (switch to its tab) before the agent acts. */
+    onplaybackreveal?: () => void | Promise<void>;
   }
 
   let {
@@ -85,6 +99,9 @@
     aiHooks,
     fit,
     effects,
+    playback,
+    playbackId = 'image',
+    onplaybackreveal,
   }: Props = $props();
 
   const internalEditor = createReactiveImageEditor();
@@ -101,6 +118,67 @@
   let canvasEl = $state<HTMLCanvasElement | null>(null);
   let containerEl = $state<HTMLDivElement | null>(null);
   let activeTab = $state<'crop' | 'adjust' | 'layers' | 'paint' | 'select' | 'annotate' | 'depth' | 'ai'>('crop');
+  let rootEl = $state<HTMLDivElement | null>(null);
+
+  // Agent playback: the agent's cursor in document pixels, over the whole editor (canvas and panels).
+  const ambientPlayback = getAgentPlayback();
+  const playing = $derived((playback === undefined ? ambientPlayback : playback) ?? null);
+  /** Document pixels → pixels in the editor's root element, through the canvas projection. */
+  const docToRoot = (p: PlaybackPoint): PlaybackPoint => {
+    if (!canvasEl || !rootEl || !canvasEl.width) return p;
+    const r = canvasEl.getBoundingClientRect();
+    const box = rootEl.getBoundingClientRect();
+    const c = imageToCanvasPoint(p, editor.controller.getState(), canvasEl.width, canvasEl.height, activeTab === 'crop');
+    return { x: r.left - box.left + (c.x * r.width) / canvasEl.width, y: r.top - box.top + (c.y * r.height) / canvasEl.height };
+  };
+  /** Viewport (client) pixels → document pixels. */
+  const clientToDoc = (p: PlaybackPoint): PlaybackPoint => {
+    if (!canvasEl || !canvasEl.width) return p;
+    const r = canvasEl.getBoundingClientRect();
+    const sx = r.width > 0 ? canvasEl.width / r.width : 1;
+    const sy = r.height > 0 ? canvasEl.height / r.height : 1;
+    return canvasToImagePoint({ x: (p.x - r.left) * sx, y: (p.y - r.top) * sy }, editor.controller.getState(), canvasEl.width, canvasEl.height, activeTab === 'crop');
+  };
+  /** An element of the editor (a tab, slider or layer row) as a rectangle in document pixels. */
+  const elementRect = (selector: string): PlaybackRect | null => {
+    const r = rootEl?.querySelector(selector)?.getBoundingClientRect();
+    if (!r || r.width <= 0) return null;
+    const a = clientToDoc({ x: r.left, y: r.top });
+    const b = clientToDoc({ x: r.right, y: r.bottom });
+    return { x: Math.min(a.x, b.x), y: Math.min(a.y, b.y), width: Math.abs(b.x - a.x), height: Math.abs(b.y - a.y) };
+  };
+  const agentPresence = createPlaybackSurface(() => playing, () => playbackId, () => ({
+    defaultKind: 'layer',
+    locate: (ref: PlaybackRef) => {
+      if (ref.kind === 'panel') return elementRect(`[data-image-tab="${CSS.escape(ref.id)}"]`);
+      if (ref.kind === 'control') return elementRect(`[data-control-id="${CSS.escape(ref.id)}"]`);
+      return createImagePlaybackLocator(editor.controller)(ref) ?? (ref.kind === 'layer' || ref.kind === 'item' ? elementRect(`[data-layer-id="${CSS.escape(ref.id)}"]`) : null);
+    },
+    open: async (ref: PlaybackRef) => {
+      if (ref.kind !== 'panel' || activeTab === ref.id) return;
+      rootEl?.querySelector<HTMLElement>(`[data-image-tab="${CSS.escape(ref.id)}"]`)?.click();
+      // Let the panel render before the cursor looks for its controls.
+      await new Promise((resolve) => setTimeout(resolve, 60));
+    },
+    bounds: () => {
+      const r = canvasEl?.getBoundingClientRect();
+      if (!r || r.width <= 0) return null;
+      const a = clientToDoc({ x: r.left, y: r.top });
+      const b = clientToDoc({ x: r.right, y: r.bottom });
+      return { x: Math.min(a.x, b.x), y: Math.min(a.y, b.y), width: Math.abs(b.x - a.x), height: Math.abs(b.y - a.y) };
+    },
+    visible: () => {
+      const r = rootEl?.getBoundingClientRect();
+      return !!r && r.width > 0 && r.height > 0 && !(typeof document !== 'undefined' && document.visibilityState === 'hidden');
+    },
+    toViewport: (p: PlaybackPoint) => {
+      const box = rootEl?.getBoundingClientRect();
+      const q = docToRoot(p);
+      return { x: (box?.left ?? 0) + q.x, y: (box?.top ?? 0) + q.y };
+    },
+    fromViewport: clientToDoc,
+    reveal: () => onplaybackreveal?.()
+  }));
 
   // Selection tools (magic wand, marquees, lasso): options bar state and the pointer gesture.
   let selectionOptions = $state<SelectionToolOptions>({ ...DEFAULT_SELECTION_TOOL_OPTIONS });
@@ -883,15 +961,20 @@
 </script>
 
 <div
-  class="flex flex-col bg-slate-900 border border-slate-800 rounded-xl overflow-hidden shadow-2xl text-slate-100 {className}"
+  bind:this={rootEl}
+  class="relative flex flex-col bg-slate-900 border border-slate-800 rounded-xl overflow-hidden shadow-2xl text-slate-100 {className}"
   {style}
 >
+  {#if playing}
+    <PresenceLayer presence={agentPresence} viewport={docToRoot} />
+  {/if}
   <!-- Top Action Header -->
   <div class="flex flex-wrap items-center justify-between px-4 py-3 bg-slate-950/80 border-b border-slate-800 gap-3">
     <!-- Navigation Tabs -->
     <div class="flex items-center gap-1 bg-slate-900 p-1 rounded-lg border border-slate-800 text-xs">
       <button
         type="button"
+        data-image-tab="crop"
         onclick={() => {
           activeTab = 'crop';
           editor.setTool('crop');
@@ -904,6 +987,7 @@
       </button>
       <button
         type="button"
+        data-image-tab="adjust"
         onclick={() => {
           activeTab = 'adjust';
           editor.setTool('select');
@@ -916,6 +1000,7 @@
       </button>
       <button
         type="button"
+        data-image-tab="layers"
         onclick={() => {
           activeTab = 'layers';
           editor.setTool('select');
@@ -928,6 +1013,7 @@
       </button>
       <button
         type="button"
+        data-image-tab="paint"
         onclick={() => {
           activeTab = 'paint';
           editor.setTool('brush');
@@ -940,6 +1026,7 @@
       </button>
       <button
         type="button"
+        data-image-tab="select"
         onclick={() => {
           activeTab = 'select';
           editor.setTool('select');
@@ -952,6 +1039,7 @@
       </button>
       <button
         type="button"
+        data-image-tab="annotate"
         onclick={() => {
           activeTab = 'annotate';
           editor.setTool('pen');
@@ -964,6 +1052,7 @@
       </button>
       <button
         type="button"
+        data-image-tab="depth"
         onclick={() => {
           activeTab = 'depth';
           editor.setTool('select');
@@ -976,6 +1065,7 @@
       </button>
       <button
         type="button"
+        data-image-tab="ai"
         onclick={() => {
           activeTab = 'ai';
           editor.setTool('select');

package/dist/image-editor/ImageEditor.svelte.d.ts

@@ -1,4 +1,5 @@
 import type { ExportOptions, InpaintHook, RemoveBackgroundHook, ImageEditorAIHooks, ImageEditorFit } from '@pixerate/editor/image-editor';
+import type { AgentPlayback } from '@pixerate/editor/tools';
 import { type ReactiveImageEditor } from './imageEditorState.svelte.js';
 import type { EffectProvider } from '@pixerate/editor/effects';
 interface Props {
@@ -18,6 +19,15 @@ interface Props {
      * with an Effects section in the Layers tab. Optional: without one the editor is as before.
      */
     effects?: EffectProvider | null;
+    /**
+     * Agent playback: act out the image tools' calls here with the agent's cursor, opening the
+     * panel each tool belongs to (default: `setAgentPlayback` above; `null` turns it off).
+     */
+    playback?: AgentPlayback | null;
+    /** The playback surface id (default `image`, where the image tool providers play). */
+    playbackId?: string;
+    /** Bring the editor on screen (switch to its tab) before the agent acts. */
+    onplaybackreveal?: () => void | Promise<void>;
 }
 declare const ImageEditor: import("svelte").Component<Props, {}, "">;
 type ImageEditor = ReturnType<typeof ImageEditor>;

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export * from "./history/index.js";
 export * from "./fileImport.svelte.js";
 export * from "./docxExport.svelte.js";
 export * from "./agentTools.svelte.js";
+export * from "./playback/index.js";
 export * from "./toolBridge.svelte.js";
 export * from "./toolRegistryView.svelte.js";
 export * from "./outline.svelte.js";

package/dist/index.js

@@ -5,6 +5,7 @@ export * from "./history/index.js";
 export * from "./fileImport.svelte.js";
 export * from "./docxExport.svelte.js";
 export * from "./agentTools.svelte.js";
+export * from "./playback/index.js";
 export * from "./toolBridge.svelte.js";
 export * from "./toolRegistryView.svelte.js";
 export * from "./outline.svelte.js";