Skip to main content

Actions & Replay API 🎬

Fuderu provides a serializable event log and replay engine for canvas operations.

import type { CanvasAction, ReplayOptions } from "fuderu";

Actions & Replay API 🎬

Fuderu provides a serializable event log and replay engine for canvas operations. Every user action (brush strokes, shape primitives, flood fills, text, selections, transformations, and clipboard pastes) is recorded as a structured, serializable JSON action.

import type { CanvasAction, ReplayOptions } from "fuderu";

Canvas Replay & Session Methods​

getActionLog(): readonly CanvasAction[]​

Returns a copy of all serializable actions executed in the current session.

clearActionLog(): void​

Clears the session action log without modifying the current canvas artwork or layers.

resetArtwork(): void​

Resets the canvas document to a single clean base layer:

  • Cancels any active floating transform sessions.
  • Clears active selection masks.
  • Resets the layer stack to a single clean base layer, preserving the original base layer ID (initialBaseLayerId).
  • Clears the undo/redo history stack.
  • Preserves the recorded action log so that playback can be executed cleanly from a blank canvas.

replay(actions: CanvasAction[], options?: ReplayOptions): Promise<void>​

Replays an array of actions sequentially on the canvas. Guarantees that:

  • Layer references not found on the canvas fall back to the active layer.
  • Brush points for strokes and single-dot taps are completely flushed and composited before advancing to subsequent actions.
  • Progress and action callbacks run at each step.

replayAction(action: CanvasAction): Promise<void>​

Replays a single action immediately and asynchronously awaits stroke completion.


Types​

CanvasAction​

type CanvasAction =
| StrokeAction
| FloodFillAction
| ClearLayerAction
| FillLayerAction
| DrawRectangleAction
| DrawEllipseAction
| DrawLineAction
| DrawTextAction
| CreateLayerAction
| DeleteLayerAction
| MoveLayerAction
| SetLayerPropertiesAction
| DuplicateLayerAction
| SelectRectangleAction
| SelectEllipseAction
| SelectLassoAction
| SelectAllAction
| ClearSelectionAction
| InvertSelectionAction
| TransformAction
| CopyAction
| CutAction
| PasteAction;

ReplayOptions​

interface ReplayOptions {
/** Speed multiplier (e.g., 1 = 100ms delay, 4 = 25ms delay, 0 = instant synchronous replay) */
speed?: number;

/** Explicit millisecond delay between sequential actions (overrides speed calculation) */
delayMs?: number;

/** Callback invoked as each individual action begins replaying */
onAction?: (action: CanvasAction, index: number, total: number) => void;

/** Callback reporting normalized progress (0.0 to 1.0) and step counts */
onProgress?: (progress: number, current: number, total: number) => void;
}

Replay Guarantees (v1.5.3)​

  1. Base Layer ID Preservation: resetArtwork() preserves the canvas's initial base layer UUID instead of generating a random ID, ensuring strokes drawn on the background layer replay seamlessly.
  2. Synchronous Point Flushing: Brush.flush() is awaited during stroke replay so that multi-point paths and single-dot taps finish rendering before the stroke commits.
  3. Active Layer Fallback: If an action targets a layer ID that does not exist in the destination canvas, the engine falls back to canvas.getActiveLayer() rather than discarding the stroke.
  4. Operation Guarding: Layer deletion, movement, and duplication actions verify target layer existence before executing during replay.