@pixerate/editor-svelte 0.101.4 → 0.103.1

package/dist/paint-editor/PaintEditor.svelte

@@ -1,5 +1,8 @@
 <script lang="ts">
-  import type { PaintEditorController, PaintPresence, PaintTool } from '@pixerate/editor/paint-editor';
+  import { PaintPresence, documentToScreen, screenToDocument, type PaintEditorController, type PaintTool } from '@pixerate/editor/paint-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 BrushPanel from './BrushPanel.svelte';
   import ColorPanel from './ColorPanel.svelte';
   import PaintCanvas from './PaintCanvas.svelte';
@@ -20,8 +23,81 @@
     /** Agent cursors to draw over the canvas (see `createPaintDirector`). */
     presence?: PaintPresence;
     class?: string;
+    /**
+     * Agent playback: act out the paint tools' calls here with the agent's cursor, opening the
+     * panel each write belongs to (default: `setAgentPlayback` above; `null` turns it off). With
+     * `presence` (a `PaintDirector`'s), the director's strokes share the cursor.
+     */
+    playback?: AgentPlayback | null;
+    /** The playback surface id (default `paint`, where the paint tool providers play). */
+    playbackId?: string;
+    /** Bring the editor on screen (switch to its tab) before the agent acts. */
+    onplaybackreveal?: () => void | Promise<void>;
   }
-  let { controller, fileName, height = 720, presence, class: className = '' }: Props = $props();
+  let { controller, fileName, height = 720, presence, class: className = '', playback, playbackId = 'paint', onplaybackreveal }: Props = $props();
+
+  /** Controls a paint plan can point at, by `{ kind: 'control', id }`. */
+  const PAINT_CONTROLS: Record<string, string> = {
+    'mixing-pad': '[data-testid="mixing-pad"]',
+    lighting: '[data-testid="light-panel"]',
+    symmetry: '[aria-label="Symmetry"]'
+  };
+  // Agent playback in document pixels, sharing a director's presence store (one cursor). Panels
+  // outside the canvas are mapped into document pixels through the canvas view.
+  let root: HTMLDivElement | undefined = $state();
+  const ambientPlayback = getAgentPlayback();
+  const playing = $derived((playback === undefined ? ambientPlayback : playback) ?? null);
+  const viewBox = () => {
+    const r = root?.querySelector<HTMLElement>('[data-testid="paint-canvas"]')?.getBoundingClientRect();
+    return r && r.width > 0 ? r : null;
+  };
+  const docToClient = (p: PlaybackPoint): PlaybackPoint | null => {
+    const r = viewBox();
+    if (!r) return null;
+    const q = documentToScreen(controller.getState().view, controller.document.canvas, { width: r.width, height: r.height }, p.x, p.y);
+    return { x: r.left + q.x, y: r.top + q.y };
+  };
+  const clientToDoc = (p: PlaybackPoint): PlaybackPoint | null => {
+    const r = viewBox();
+    return r ? screenToDocument(controller.getState().view, controller.document.canvas, { width: r.width, height: r.height }, p.x - r.left, p.y - r.top) : null;
+  };
+  const elementRect = (selector: string): PlaybackRect | null => {
+    const r = root?.querySelector(selector)?.getBoundingClientRect();
+    if (!r || r.width <= 0) return null;
+    // The element's centre and size (the view may rotate; the cursor only needs the centre).
+    const c = clientToDoc({ x: r.left + r.width / 2, y: r.top + r.height / 2 });
+    const zoom = controller.getState().view.zoom || 1;
+    return c ? { x: c.x - r.width / zoom / 2, y: c.y - r.height / zoom / 2, width: r.width / zoom, height: r.height / zoom } : null;
+  };
+  // svelte-ignore state_referenced_locally
+  const sharedPresence = presence ?? new PaintPresence();
+  const agentPresence = createPlaybackSurface(() => playing, () => playbackId, () => ({
+    locate: (ref: PlaybackRef) => {
+      if (ref.kind === 'panel') return elementRect(`[data-paint-tab="${CSS.escape(ref.id)}"]`);
+      if (ref.kind === 'panel-body') return elementRect(`[data-paint-panel="${CSS.escape(ref.id)}"]`);
+      if (ref.kind === 'control' && PAINT_CONTROLS[ref.id]) return elementRect(PAINT_CONTROLS[ref.id]!);
+      return null;
+    },
+    open: async (ref: PlaybackRef) => {
+      if (ref.kind !== 'panel' || tab === ref.id) return;
+      root?.querySelector<HTMLElement>(`[data-paint-tab="${CSS.escape(ref.id)}"]`)?.click();
+      await new Promise((resolve) => setTimeout(resolve, 60));
+    },
+    bounds: () => ({ x: 0, y: 0, width: controller.document.canvas.width, height: controller.document.canvas.height }),
+    visible: () => {
+      const r = root?.getBoundingClientRect();
+      return !!r && r.width > 0 && r.height > 0 && !(typeof document !== 'undefined' && document.visibilityState === 'hidden');
+    },
+    toViewport: (p: PlaybackPoint) => docToClient(p) ?? p,
+    fromViewport: (p: PlaybackPoint) => clientToDoc(p) ?? p,
+    reveal: () => onplaybackreveal?.()
+  }), sharedPresence);
+  /** Document pixels → pixels in the editor's root, for the cursor layer. */
+  const docToRoot = (p: PlaybackPoint): PlaybackPoint => {
+    const c = docToClient(p);
+    const box = root?.getBoundingClientRect();
+    return c && box ? { x: c.x - box.left, y: c.y - box.top } : p;
+  };
   let tool = $state<PaintTool>('brush');
   let tab = $state<'color' | 'wet' | 'paper' | 'layers' | 'effects'>('color');
   const effects = paintEffectsProvider(() => controller);
@@ -30,25 +106,31 @@
 </script>
 
 <!-- Toolbar, brush library, the canvas, and colour / wet media / paper / layers. -->
-<div class={`flex flex-col gap-2 rounded-xl border border-slate-800 bg-slate-900 p-2 ${className}`} style={`height: ${typeof height === 'number' ? `${height}px` : height}`} data-testid="paint-editor">
+<div bind:this={root} class={`relative flex flex-col gap-2 rounded-xl border border-slate-800 bg-slate-900 p-2 ${className}`} style={`height: ${typeof height === 'number' ? `${height}px` : height}`} data-testid="paint-editor">
+  {#if playing}
+    <PresenceLayer presence={agentPresence} viewport={docToRoot} />
+  {/if}
   <PaintToolbar {controller} {tool} ontoolchange={(t) => (tool = t)} {fileName} />
   <div class="flex min-h-0 flex-1 gap-2">
     <BrushPanel {controller} class="w-60 shrink-0 overflow-y-auto pr-1" />
     <div class="flex min-w-0 flex-1 flex-col">
-      <PaintCanvas {controller} {tool} {presence} onerror={(e) => (error = e)} class="flex-1 rounded-lg" />
+      <!-- With playback the editor draws the cursor (over the panels too), so the canvas doesn't. -->
+      <PaintCanvas {controller} {tool} presence={playing ? undefined : presence} onerror={(e) => (error = e)} class="flex-1 rounded-lg" />
       {#if error}<p role="alert" class="mt-1 text-[11px] text-rose-400">{error}</p>{/if}
     </div>
     <div class="flex w-64 shrink-0 flex-col gap-2 overflow-y-auto pr-1">
       <div class="flex gap-1" role="tablist" aria-label="Paint panels">
         {#each tabs as t (t)}
-          <button type="button" role="tab" aria-selected={tab === t} class={chip(tab === t)} onclick={() => (tab = t)}>{t === 'color' ? 'Colour' : t === 'wet' ? 'Wet' : t === 'paper' ? 'Paper' : t === 'layers' ? 'Layers' : 'Effects'}</button>
+          <button type="button" role="tab" aria-selected={tab === t} data-paint-tab={t} class={chip(tab === t)} onclick={() => (tab = t)}>{t === 'color' ? 'Colour' : t === 'wet' ? 'Wet' : t === 'paper' ? 'Paper' : t === 'layers' ? 'Layers' : 'Effects'}</button>
         {/each}
       </div>
-      {#if tab === 'color'}<ColorPanel {controller} />{/if}
-      {#if tab === 'wet'}<WetPanel {controller} />{/if}
-      {#if tab === 'paper'}<PaperPanel {controller} />{/if}
-      {#if tab === 'layers'}<PaintLayersPanel {controller} /><StickerPanel {controller} />{/if}
-      {#if tab === 'effects' && effects.current}<PaintEffectsPanel {controller} />{/if}
+      <div class="flex flex-col gap-2" data-paint-panel={tab}>
+        {#if tab === 'color'}<ColorPanel {controller} />{/if}
+        {#if tab === 'wet'}<WetPanel {controller} />{/if}
+        {#if tab === 'paper'}<PaperPanel {controller} />{/if}
+        {#if tab === 'layers'}<PaintLayersPanel {controller} /><StickerPanel {controller} />{/if}
+        {#if tab === 'effects' && effects.current}<PaintEffectsPanel {controller} />{/if}
+      </div>
     </div>
   </div>
 </div>

package/dist/paint-editor/PaintEditor.svelte.d.ts

@@ -1,4 +1,5 @@
-import type { PaintEditorController, PaintPresence } from '@pixerate/editor/paint-editor';
+import { PaintPresence, type PaintEditorController } from '@pixerate/editor/paint-editor';
+import type { AgentPlayback } from '@pixerate/editor/tools';
 interface Props {
     controller: PaintEditorController;
     /** Base name of saved and exported files (default `painting`). */
@@ -8,6 +9,16 @@ interface Props {
     /** Agent cursors to draw over the canvas (see `createPaintDirector`). */
     presence?: PaintPresence;
     class?: string;
+    /**
+     * Agent playback: act out the paint tools' calls here with the agent's cursor, opening the
+     * panel each write belongs to (default: `setAgentPlayback` above; `null` turns it off). With
+     * `presence` (a `PaintDirector`'s), the director's strokes share the cursor.
+     */
+    playback?: AgentPlayback | null;
+    /** The playback surface id (default `paint`, where the paint tool providers play). */
+    playbackId?: string;
+    /** Bring the editor on screen (switch to its tab) before the agent acts. */
+    onplaybackreveal?: () => void | Promise<void>;
 }
 declare const PaintEditor: import("svelte").Component<Props, {}, "">;
 type PaintEditor = ReturnType<typeof PaintEditor>;

package/dist/parameters/ParametersPanel.svelte

@@ -6,6 +6,9 @@
 
 <script lang="ts">
   import { untrack, type Snippet } from 'svelte';
+  import type { AgentPlayback } from '@pixerate/editor/tools';
+  import { createElementPlaybackSurface, getAgentPlayback } from '../playback/playback.svelte.js';
+  import PresenceLayer from '../playback/PresenceLayer.svelte';
   import {
     isParameterGroup,
     parameterLabel,
@@ -40,6 +43,15 @@
     class?: string;
     /** Extra content after the fields. */
     children?: Snippet;
+    /**
+     * Agent playback: act out `parameters.*` commands here with the agent's cursor (default:
+     * `setAgentPlayback` above; `null` turns it off).
+     */
+    playback?: AgentPlayback | null;
+    /** The playback surface id (default `parameters`, where the parameter commands play). */
+    playbackId?: string;
+    /** Bring the panel on screen (switch to its tab) before the agent acts. */
+    onplaybackreveal?: () => void | Promise<void>;
   }
 
   let {
@@ -53,9 +65,22 @@
     emptyMessage = 'No parameters.',
     idPrefix = `pixerate-parameters-${++nextId}`,
     class: className = '',
-    children
+    children,
+    playback,
+    playbackId = 'parameters',
+    onplaybackreveal
   }: Props = $props();
 
+  // Agent playback: the cursor visits the controls a call changes.
+  let root: HTMLDivElement | undefined = $state();
+  const ambientPlayback = getAgentPlayback();
+  const playing = $derived((playback === undefined ? ambientPlayback : playback) ?? null);
+  const agentPresence = createElementPlaybackSurface(() => playing, () => playbackId, () => root, () => ({
+    defaultKind: 'parameter',
+    selectors: { parameter: (id: string) => `[data-parameter-id="${CSS.escape(id)}"]` },
+    reveal: onplaybackreveal
+  }));
+
   // Follows a replaced `controller` prop too.
   let view: ParametersState = $state.raw(untrack(() => controller.getState()));
   $effect(() => {
@@ -164,7 +189,7 @@
   keyframe diamonds, per-field reset, presets, and undo / redo / reset / randomize. Slider
   drags and colour picks are one undo step each.
 -->
-<div class="space-y-3 text-foreground {className}" data-parameters-panel="">
+<div bind:this={root} class="relative space-y-3 text-foreground {className}" data-parameters-panel="">
   {#if heading || showToolbar}
     <div class="flex flex-wrap items-center gap-1.5">
       {#if heading}
@@ -236,4 +261,8 @@
     {@render items(view.schema.fields)}
   {/if}
   {@render children?.()}
+  <!-- Last, so it doesn't shift the stacked spacing. -->
+  {#if playing}
+    <PresenceLayer presence={agentPresence} />
+  {/if}
 </div>

package/dist/parameters/ParametersPanel.svelte.d.ts

@@ -1,4 +1,5 @@
 import { type Snippet } from 'svelte';
+import type { AgentPlayback } from '@pixerate/editor/tools';
 import { type ParametersController } from '@pixerate/editor/parameters';
 interface Props {
     controller: ParametersController;
@@ -21,6 +22,15 @@ interface Props {
     class?: string;
     /** Extra content after the fields. */
     children?: Snippet;
+    /**
+     * Agent playback: act out `parameters.*` commands here with the agent's cursor (default:
+     * `setAgentPlayback` above; `null` turns it off).
+     */
+    playback?: AgentPlayback | null;
+    /** The playback surface id (default `parameters`, where the parameter commands play). */
+    playbackId?: string;
+    /** Bring the panel on screen (switch to its tab) before the agent acts. */
+    onplaybackreveal?: () => void | Promise<void>;
 }
 declare const ParametersPanel: import("svelte").Component<Props, {}, "">;
 type ParametersPanel = ReturnType<typeof ParametersPanel>;

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, createElementPlaybackSurface, type PlaybackSurfaceOptions, type ElementPlaybackSurfaceOptions } from './playback.svelte.js';

package/dist/playback/index.js

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

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

@@ -0,0 +1,32 @@
+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>, 
+/** Use this presence store (e.g. a director's, so its cursor and playback's are one) instead of a new one. */
+sharedPresence?: PresenceStore | null): PresenceStore;
+export interface ElementPlaybackSurfaceOptions {
+    /** The kind of a bare `id` / `ids` argument (e.g. `parameter`). */
+    defaultKind?: string;
+    /** A CSS selector for each ref kind the surface can find inside the element. */
+    selectors: Record<string, (id: string) => string>;
+    /** Bring the element on screen (switch to its tab) before the agent acts. */
+    reveal?: () => void | Promise<void>;
+}
+/**
+ * A playback surface for a plain DOM component (call during init): coordinates are pixels of the
+ * element's box, and refs are found by the CSS selectors given per kind. Draw the cursors with
+ * `<PresenceLayer>` inside the element. Parity with React's `useElementPlaybackSurface`.
+ */
+export declare function createElementPlaybackSurface(playback: MaybeGetter<AgentPlayback | null | undefined>, id: MaybeGetter<string | null | undefined>, element: () => HTMLElement | null | undefined, options: MaybeGetter<ElementPlaybackSurfaceOptions>): PresenceStore;
+export {};

package/dist/playback/playback.svelte.js

@@ -0,0 +1,91 @@
+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 = {}, 
+/** Use this presence store (e.g. a director's, so its cursor and playback's are one) instead of a new one. */
+sharedPresence) {
+    const ambient = getAgentPlayback();
+    const presence = sharedPresence ?? 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;
+}
+/**
+ * A playback surface for a plain DOM component (call during init): coordinates are pixels of the
+ * element's box, and refs are found by the CSS selectors given per kind. Draw the cursors with
+ * `<PresenceLayer>` inside the element. Parity with React's `useElementPlaybackSurface`.
+ */
+export function createElementPlaybackSurface(playback, id, element, options) {
+    const box = () => element()?.getBoundingClientRect() ?? null;
+    return createPlaybackSurface(playback, id, () => {
+        const o = read(options);
+        return {
+            defaultKind: o.defaultKind,
+            locate: (ref) => {
+                const selector = o.selectors[ref.kind]?.(ref.id);
+                const b = box();
+                const r = selector ? element()?.querySelector(selector)?.getBoundingClientRect() : null;
+                return b && r && r.width > 0 ? { x: r.left - b.left, y: r.top - b.top, width: r.width, height: r.height } : null;
+            },
+            bounds: () => {
+                const r = box();
+                return r && r.width > 0 ? { x: 0, y: 0, width: r.width, height: r.height } : null;
+            },
+            visible: () => {
+                const r = box();
+                return !!r && r.width > 0 && r.height > 0 && !(typeof document !== 'undefined' && document.visibilityState === 'hidden');
+            },
+            toViewport: (p) => {
+                const r = box();
+                return { x: (r?.left ?? 0) + p.x, y: (r?.top ?? 0) + p.y };
+            },
+            fromViewport: (p) => {
+                const r = box();
+                return { x: p.x - (r?.left ?? 0), y: p.y - (r?.top ?? 0) };
+            },
+            reveal: () => o.reveal?.()
+        };
+    });
+}

package/dist/spreadsheet/SpreadsheetEditor.svelte

@@ -20,8 +20,12 @@
     getDataBarCss,
     conditionalFormatStyleString,
     type SpreadsheetPanelId,
-    type SpreadsheetValidationAction
+    type SpreadsheetValidationAction,
+    parseSpreadsheetPlaybackRef
   } from '@pixerate/editor/spreadsheet';
+  import type { AgentPlayback, PlaybackRect, PlaybackRef } from '@pixerate/editor/tools';
+  import { createPlaybackSurface, getAgentPlayback } from '../playback/playback.svelte.js';
+  import PresenceLayer from '../playback/PresenceLayer.svelte';
   import FormulaBar from './FormulaBar.svelte';
   import SpreadsheetValidationDialog from './SpreadsheetValidationDialog.svelte';
   import SpreadsheetConditionalFormatPanel from './SpreadsheetConditionalFormatPanel.svelte';
@@ -54,6 +58,15 @@
      * `true` / `false` force it.
      */
     virtualize?: boolean | 'auto';
+    /**
+     * Agent playback: act out the spreadsheet tools' calls here with the agent's cursor (default:
+     * `setAgentPlayback` above; `null` turns it off).
+     */
+    playback?: AgentPlayback | null;
+    /** The playback surface id (default `spreadsheet`, where `createSpreadsheetToolProvider` plays). */
+    playbackId?: string;
+    /** Bring the grid on screen (switch to its tab) before the agent acts. */
+    onplaybackreveal?: () => void | Promise<void>;
   }
 
   let {
@@ -67,7 +80,10 @@
     onColumnHeaderClick,
     onColumnResize,
     showSheetTabs = false,
-    virtualize = 'auto'
+    virtualize = 'auto',
+    playback,
+    playbackId = 'spreadsheet',
+    onplaybackreveal
   }: Props = $props();
 
   // Virtualised rendering: frozen rows/columns, a spacer, the rows and
@@ -120,6 +136,47 @@
   let isReadOnly = $derived(readOnly || readonly);
 
   let gridContainer = $state<HTMLDivElement | null>(null);
+
+  // Agent playback: the agent's cursor in pixels of the grid's box, finding cells by data-row / data-col.
+  const ambientPlayback = getAgentPlayback();
+  const playing = $derived((playback === undefined ? ambientPlayback : playback) ?? null);
+  const agentPresence = createPlaybackSurface(() => playing, () => playbackId, () => ({
+    defaultKind: 'cell',
+    locate: (ref: PlaybackRef): PlaybackRect | null => {
+      const grid = gridContainer;
+      const range = parseSpreadsheetPlaybackRef(ref);
+      if (!grid || !range) return null;
+      const box = grid.getBoundingClientRect();
+      const inside = (v: number, a: number | null, b: number | null) => (a === null || v >= a) && (b === null || v <= b);
+      let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+      for (const td of grid.querySelectorAll<HTMLElement>('td[data-row][data-col]')) {
+        if (!inside(Number(td.dataset.row), range.startRow, range.endRow) || !inside(Number(td.dataset.col), range.startCol, range.endCol)) continue;
+        const r = td.getBoundingClientRect();
+        minX = Math.min(minX, r.left - box.left);
+        minY = Math.min(minY, r.top - box.top);
+        maxX = Math.max(maxX, r.right - box.left);
+        maxY = Math.max(maxY, r.bottom - box.top);
+      }
+      return minX < maxX ? { x: minX, y: minY, width: maxX - minX, height: maxY - minY } : null;
+    },
+    bounds: () => {
+      const r = gridContainer?.getBoundingClientRect();
+      return r && r.width > 0 ? { x: 0, y: 0, width: r.width, height: r.height } : null;
+    },
+    visible: () => {
+      const r = gridContainer?.getBoundingClientRect();
+      return !!r && r.width > 0 && r.height > 0 && !(typeof document !== 'undefined' && document.visibilityState === 'hidden');
+    },
+    toViewport: (p: { x: number; y: number }) => {
+      const r = gridContainer?.getBoundingClientRect();
+      return { x: (r?.left ?? 0) + p.x, y: (r?.top ?? 0) + p.y };
+    },
+    fromViewport: (p: { x: number; y: number }) => {
+      const r = gridContainer?.getBoundingClientRect();
+      return { x: p.x - (r?.left ?? 0), y: p.y - (r?.top ?? 0) };
+    },
+    reveal: () => onplaybackreveal?.()
+  }));
   let cellInput = $state<HTMLInputElement | null>(null);
 
   // Focus the cell editor when it opens, with the caret after the draft
@@ -586,7 +643,7 @@
 {#snippet grid()}
 <div
   bind:this={gridContainer}
-  class="flex flex-col h-full w-full overflow-hidden border border-border bg-background select-none outline-none text-foreground font-sans text-xs {className}"
+  class="relative flex flex-col h-full w-full overflow-hidden border border-border bg-background select-none outline-none text-foreground font-sans text-xs {className}"
   tabindex="0"
   onkeydown={handleKeyDown}
   role="grid"
@@ -879,6 +936,9 @@
   {#if sheetState.validationPrompt}
     <SpreadsheetValidationDialog prompt={sheetState.validationPrompt} onResolve={resolveValidation} />
   {/if}
+  {#if playing}
+    <PresenceLayer presence={agentPresence} />
+  {/if}
 </div>
 {/snippet}
 

package/dist/spreadsheet/SpreadsheetEditor.svelte.d.ts

@@ -1,5 +1,6 @@
 import type { Snippet } from 'svelte';
 import { type SpreadsheetColumn, type SpreadsheetRow, type CellData } from '@pixerate/editor/spreadsheet';
+import type { AgentPlayback } from '@pixerate/editor/tools';
 import { createReactiveSpreadsheet } from './spreadsheet.svelte.js';
 interface Props {
     sheetState?: ReturnType<typeof createReactiveSpreadsheet>;
@@ -23,6 +24,15 @@ interface Props {
      * `true` / `false` force it.
      */
     virtualize?: boolean | 'auto';
+    /**
+     * Agent playback: act out the spreadsheet tools' calls here with the agent's cursor (default:
+     * `setAgentPlayback` above; `null` turns it off).
+     */
+    playback?: AgentPlayback | null;
+    /** The playback surface id (default `spreadsheet`, where `createSpreadsheetToolProvider` plays). */
+    playbackId?: string;
+    /** Bring the grid on screen (switch to its tab) before the agent acts. */
+    onplaybackreveal?: () => void | Promise<void>;
 }
 declare const SpreadsheetEditor: import("svelte").Component<Props, {}, "">;
 type SpreadsheetEditor = ReturnType<typeof SpreadsheetEditor>;