@pixerate/editor-svelte 0.101.3 → 0.102.0

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/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/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";

package/dist/playback/PresenceLayer.svelte

@@ -0,0 +1,65 @@
+<script lang="ts">
+	import { untrack } from 'svelte';
+	import type { PresenceStore, PresenceState } from '@pixerate/editor/tools';
+
+	type Point = { x: number; y: number };
+
+	interface Props {
+		/** The cursors to draw, e.g. from `createPlaybackSurface` or a director. */
+		presence: PresenceStore;
+		/**
+		 * How surface coordinates map to this layer's pixels: a canvas viewport
+		 * (`x * zoom + viewport.x`), or a function. Default: one to one.
+		 */
+		viewport?: { x: number; y: number; zoom: number } | ((point: Point) => Point);
+		class?: string;
+	}
+
+	let { presence, viewport, class: className = '' }: Props = $props();
+	let view: PresenceState = $state.raw(untrack(() => presence.getState()));
+	$effect(() => {
+		view = presence.getState();
+		return presence.subscribe((next) => {
+			view = next;
+		});
+	});
+
+	const map = $derived.by((): ((p: Point) => Point) => {
+		const v = viewport;
+		if (typeof v === 'function') return v;
+		if (v) return (p) => ({ x: p.x * v.zoom + v.x, y: p.y * v.zoom + v.y });
+		return (p) => p;
+	});
+
+	function ring(focus: { x: number; y: number; width: number; height: number }) {
+		const tl = map(focus);
+		const br = map({ x: focus.x + focus.width, y: focus.y + focus.height });
+		return `left: ${tl.x - 4}px; top: ${tl.y - 4}px; width: ${br.x - tl.x + 8}px; height: ${br.y - tl.y + 8}px;`;
+	}
+</script>
+
+<!--
+	Agent cursors with their name tag or note, and a ring around what each one works on. Place it in
+	a `position: relative` box over the surface. The `pixerate-presence` class keeps it out of
+	snapshots and exports. Parity with React's `<PresenceLayer>`.
+-->
+{#if view.actors.length}
+	<div class="pixerate-presence {className}" aria-hidden="true" data-testid="presence-layer" style="position: absolute; inset: 0; pointer-events: none; overflow: hidden; z-index: 50;">
+		{#each view.actors as a (a.id)}
+			{#if a.focus}
+				<div data-actor-focus={a.id} style="position: absolute; {ring(a.focus)} border-radius: 8px; border: 2px solid {a.color}; background: {a.color}14; transition: all 160ms ease-out;"></div>
+			{/if}
+			<div data-actor={a.id} style="position: absolute; left: 0; top: 0; transform: translate({map(a).x}px, {map(a).y}px);">
+				<svg width="18" height="20" viewBox="0 0 12 18" style="display: block; transform-origin: 0 0; filter: drop-shadow(0 1px 2px rgba(0,0,0,.35)); {a.pressed ? 'transform: scale(0.85);' : ''}">
+					<path d="M0,0 L0,14 L4,10.5 L7,17 L9.5,16 L6.5,9.5 L11.5,9.5 Z" style="fill: {a.color}; stroke: #ffffff; stroke-width: 1;" />
+				</svg>
+				<span style="position: absolute; left: 14px; top: 16px; display: flex; flex-direction: column; align-items: flex-start; gap: 4px;">
+					<span style="white-space: nowrap; border-radius: 999px; padding: 1px 7px; font-size: 11px; font-weight: 600; color: #ffffff; background: {a.color};">{a.name}</span>
+					{#if a.message}
+						<span data-actor-message={a.id} style="width: max-content; max-width: 240px; border-radius: 8px; border-top-left-radius: 0; padding: 4px 8px; font-size: 12px; color: #1e293b; background: #ffffff; box-shadow: 0 4px 12px rgba(15,23,42,.18);">{a.message}</span>
+					{/if}
+				</span>
+			</div>
+		{/each}
+	</div>
+{/if}

package/dist/playback/PresenceLayer.svelte.d.ts

@@ -0,0 +1,22 @@
+import type { PresenceStore } from '@pixerate/editor/tools';
+type Point = {
+    x: number;
+    y: number;
+};
+interface Props {
+    /** The cursors to draw, e.g. from `createPlaybackSurface` or a director. */
+    presence: PresenceStore;
+    /**
+     * How surface coordinates map to this layer's pixels: a canvas viewport
+     * (`x * zoom + viewport.x`), or a function. Default: one to one.
+     */
+    viewport?: {
+        x: number;
+        y: number;
+        zoom: number;
+    } | ((point: Point) => Point);
+    class?: string;
+}
+declare const PresenceLayer: import("svelte").Component<Props, {}, "">;
+type PresenceLayer = ReturnType<typeof PresenceLayer>;
+export default PresenceLayer;

package/dist/playback/index.d.ts

@@ -0,0 +1,2 @@
+export { default as PresenceLayer } from './PresenceLayer.svelte';
+export { setAgentPlayback, getAgentPlayback, createPlaybackSurface, type PlaybackSurfaceOptions } from './playback.svelte.js';

package/dist/playback/index.js

@@ -0,0 +1,2 @@
+export { default as PresenceLayer } from './PresenceLayer.svelte';
+export { setAgentPlayback, getAgentPlayback, createPlaybackSurface } from './playback.svelte.js';

package/dist/playback/playback.svelte.d.ts

@@ -0,0 +1,16 @@
+import { PresenceStore, type AgentPlayback, type PlaybackSurface } from '@pixerate/editor/tools';
+type MaybeGetter<T> = T | (() => T);
+/** Makes `playback` the default for every editor surface in this component's subtree (call during init). */
+export declare function setAgentPlayback(playback: AgentPlayback | null | undefined): void;
+/** The nearest `setAgentPlayback` playback, or `null` (call during init). */
+export declare function getAgentPlayback(): AgentPlayback | null;
+/** A surface's behaviour; every function is read fresh on each call. */
+export type PlaybackSurfaceOptions = Omit<PlaybackSurface, 'presence'>;
+/**
+ * Attaches a playback surface under `id` (the tool provider's id, or its `playbackSurface`) for the
+ * calling component's lifetime (call during init), and returns its cursors to draw with
+ * `<PresenceLayer>`. `playback` defaults to `getAgentPlayback()`; with none, nothing is attached and
+ * calls run instantly. Parity with React's `usePlaybackSurface`.
+ */
+export declare function createPlaybackSurface(playback: MaybeGetter<AgentPlayback | null | undefined>, id: MaybeGetter<string | null | undefined>, options?: MaybeGetter<PlaybackSurfaceOptions>): PresenceStore;
+export {};

package/dist/playback/playback.svelte.js

@@ -0,0 +1,52 @@
+import { getContext, setContext } from 'svelte';
+import { PresenceStore } from '@pixerate/editor/tools';
+const KEY = Symbol.for('pixerate.agentPlayback');
+const read = (value) => (typeof value === 'function' ? value() : value);
+/** Makes `playback` the default for every editor surface in this component's subtree (call during init). */
+export function setAgentPlayback(playback) {
+    setContext(KEY, playback ?? null);
+}
+/** The nearest `setAgentPlayback` playback, or `null` (call during init). */
+export function getAgentPlayback() {
+    return getContext(KEY) ?? null;
+}
+/**
+ * Attaches a playback surface under `id` (the tool provider's id, or its `playbackSurface`) for the
+ * calling component's lifetime (call during init), and returns its cursors to draw with
+ * `<PresenceLayer>`. `playback` defaults to `getAgentPlayback()`; with none, nothing is attached and
+ * calls run instantly. Parity with React's `usePlaybackSurface`.
+ */
+export function createPlaybackSurface(playback, id, options = {}) {
+    const ambient = getAgentPlayback();
+    const presence = new PresenceStore();
+    const o = () => read(options);
+    $effect(() => {
+        const explicit = read(playback);
+        const target = explicit === undefined ? ambient : explicit;
+        const currentId = read(id);
+        if (!target || !currentId)
+            return;
+        const surface = {
+            presence,
+            locate: (ref) => o().locate?.(ref) ?? null,
+            bounds: () => o().bounds?.() ?? null,
+            visible: () => o().visible?.() ?? true,
+            toViewport: (p) => o().toViewport?.(p) ?? p,
+            fromViewport: (p) => o().fromViewport?.(p) ?? p,
+            beginGesture: (key) => o().beginGesture?.(key),
+            endGesture: () => o().endGesture?.(),
+            reveal: () => o().reveal?.(),
+            open: (ref) => o().open?.(ref),
+            get defaultKind() {
+                return o().defaultKind;
+            }
+        };
+        const detach = target.attach(currentId, surface);
+        return () => {
+            detach();
+            for (const a of presence.getState().actors)
+                presence.remove(a.id);
+        };
+    });
+    return presence;
+}

package/dist/vector/VectorCanvas.svelte

@@ -14,8 +14,12 @@
     toVectorKeyInput,
     toVectorPointerInput,
     vectorDiamondPath,
+    createVectorPlaybackLocator,
     type VectorEditorController
   } from '@pixerate/editor/vector';
+  import type { AgentPlayback } from '@pixerate/editor/tools';
+  import { createPlaybackSurface, getAgentPlayback } from '../playback/playback.svelte.js';
+  import PresenceLayer from '../playback/PresenceLayer.svelte';
   import VectorGradientDefs from './VectorGradientDefs.svelte';
   import VectorFilterDefs from './VectorFilterDefs.svelte';
   import VectorGradientAnnotator from './VectorGradientAnnotator.svelte';
@@ -39,6 +43,15 @@
     style?: string;
     /** Accessible label (default "Vector canvas"). */
     'aria-label'?: string;
+    /**
+     * Agent playback: act out the vector commands' calls here with the agent's cursor (default:
+     * `setAgentPlayback` above; `null` turns it off).
+     */
+    playback?: AgentPlayback | null;
+    /** The playback surface id (default `vector`, where the vector commands play). */
+    playbackId?: string;
+    /** Bring the canvas on screen (switch to its tab) before the agent acts. */
+    onplaybackreveal?: () => void | Promise<void>;
   }
 
   let {
@@ -50,7 +63,10 @@
     idPrefix = `ve${++nextId}-`,
     class: className = '',
     style = '',
-    'aria-label': ariaLabel = 'Vector canvas'
+    'aria-label': ariaLabel = 'Vector canvas',
+    playback,
+    playbackId = 'vector',
+    onplaybackreveal
   }: Props = $props();
 
   const store = vectorStateOf(() => controller);
@@ -70,6 +86,35 @@
   const as = THEME.anchorSize;
 
   let svg: SVGSVGElement | undefined = $state();
+
+  // Agent playback: the agent's cursor in document units, drawn through the viewport.
+  const ambientPlayback = getAgentPlayback();
+  const playing = $derived((playback === undefined ? ambientPlayback : playback) ?? null);
+  const svgBox = () => svg?.getBoundingClientRect() ?? null;
+  const presence = createPlaybackSurface(() => playing, () => playbackId, () => ({
+    defaultKind: 'vector',
+    locate: createVectorPlaybackLocator(controller),
+    bounds: () => {
+      const r = svgBox();
+      const v = controller.getState().viewport;
+      return r && r.width > 0 ? { x: -v.x / v.zoom, y: -v.y / v.zoom, width: r.width / v.zoom, height: r.height / v.zoom } : null;
+    },
+    visible: () => {
+      const r = svgBox();
+      return !!r && r.width > 0 && r.height > 0 && !(typeof document !== 'undefined' && document.visibilityState === 'hidden');
+    },
+    toViewport: (p) => {
+      const r = svgBox();
+      const v = controller.getState().viewport;
+      return { x: (r?.left ?? 0) + p.x * v.zoom + v.x, y: (r?.top ?? 0) + p.y * v.zoom + v.y };
+    },
+    fromViewport: (p) => {
+      const r = svgBox();
+      const v = controller.getState().viewport;
+      return { x: (p.x - (r?.left ?? 0) - v.x) / v.zoom, y: (p.y - (r?.top ?? 0) - v.y) / v.zoom };
+    },
+    reveal: () => onplaybackreveal?.()
+  }));
   $effect(() => {
     const el = svg;
     if (!el || typeof ResizeObserver === 'undefined') return;
@@ -611,4 +656,12 @@
       {/key}
     </foreignObject>
   {/if}
+  {#if playing}
+    <!-- The agent's cursor (agent playback), over everything and never in the way. -->
+    <foreignObject data-vector-presence="" x="0" y="0" width="100%" height="100%" pointer-events="none" style="overflow:visible;pointer-events:none">
+      <div style="position:relative;width:100%;height:100%">
+        <PresenceLayer {presence} viewport={view.viewport} />
+      </div>
+    </foreignObject>
+  {/if}
 </svg>

package/dist/vector/VectorCanvas.svelte.d.ts

@@ -1,4 +1,5 @@
 import { type VectorEditorController } from '@pixerate/editor/vector';
+import type { AgentPlayback } from '@pixerate/editor/tools';
 interface Props {
     controller: VectorEditorController;
     /** Fit the artboard into the canvas when it first gets a size (default `true`). */
@@ -15,6 +16,15 @@ interface Props {
     style?: string;
     /** Accessible label (default "Vector canvas"). */
     'aria-label'?: string;
+    /**
+     * Agent playback: act out the vector commands' calls here with the agent's cursor (default:
+     * `setAgentPlayback` above; `null` turns it off).
+     */
+    playback?: AgentPlayback | null;
+    /** The playback surface id (default `vector`, where the vector commands play). */
+    playbackId?: string;
+    /** Bring the canvas on screen (switch to its tab) before the agent acts. */
+    onplaybackreveal?: () => void | Promise<void>;
 }
 declare const VectorCanvas: import("svelte").Component<Props, {}, "">;
 type VectorCanvas = ReturnType<typeof VectorCanvas>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor-svelte",
-  "version": "0.101.3",
+  "version": "0.102.0",
   "description": "Svelte bindings and prompt/rich-text components for @pixerate/editor",
   "author": "Pixerate",
   "license": "MIT",
@@ -144,7 +144,7 @@
     "@tiptap/extension-bubble-menu": "^2.27.3",
     "@tiptap/extension-placeholder": "^2.27.3",
     "@tiptap/starter-kit": "^2.27.3",
-    "@pixerate/editor": "0.140.3"
+    "@pixerate/editor": "0.141.0"
   },
   "peerDependencies": {
     "@dagrejs/dagre": "^1.1.4",