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)​
- 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. - 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. - 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. - Operation Guarding: Layer deletion, movement, and duplication actions verify target layer existence before executing during replay.