ComfyUI_frontend/docs/architecture/change-tracker.md

Change Tracker (Undo/Redo System)

The ChangeTracker class (src/scripts/changeTracker.ts) manages undo/redo history by comparing serialized graph snapshots.

How It Works

captureCanvasState() is the core method. It:

1. Serializes the current graph via app.rootGraph.serialize()
2. Deep-compares the result against the last known activeState
3. If different, pushes activeState onto undoQueue and replaces it

It is not reactive. Changes to the graph (widget values, node positions, links, etc.) are only captured when captureCanvasState() is explicitly triggered.

INVARIANT: captureCanvasState() asserts that it is called on the active workflow's tracker. Calling it on an inactive tracker logs a warning and returns early, preventing cross-workflow data corruption.

Automatic Triggers

These are set up once in ChangeTracker.init():

Trigger	Event / Hook	What It Catches
Keyboard (non-modifier, non-repeat)	window keydown	Shortcuts, typing in canvas
Modifier key release	window keyup	Releasing Ctrl/Shift/Alt/Meta
Mouse click	window mouseup	General clicks on native DOM
Canvas mouse up	LGraphCanvas.processMouseUp override	LiteGraph canvas interactions
Number/string dialog	LGraphCanvas.prompt override	Dialog popups for editing widgets
Context menu close	LiteGraph.ContextMenu.close override	COMBO widget menus in LiteGraph
Active input element	bindInput (change/input/blur on focused element)	Native HTML input edits
Prompt queued	api promptQueued event	Dynamic widget changes on queue
Graph cleared	api graphCleared event	Full graph clear
Transaction end	litegraph:canvas after-change event	Batched operations via beforeChange/afterChange

When You Must Call captureCanvasState() Manually

The automatic triggers above are designed around LiteGraph's native DOM rendering. They do not cover:

• Vue-rendered widgets — Vue handles events internally without triggering native DOM events that the tracker listens to (e.g., mouseup on a Vue dropdown doesn't bubble the same way as a native LiteGraph widget click)
• Programmatic graph mutations — Any code that modifies the graph outside of user interaction (e.g., applying a template, pasting nodes, aligning)
• Async operations — File uploads, API calls that change widget values after the initial user gesture

Pattern for Manual Calls

import { useWorkflowStore } from '@/platform/workflow/management/stores/workflowStore'

// After mutating the graph:
useWorkflowStore().activeWorkflow?.changeTracker?.captureCanvasState()

Existing Manual Call Sites

These locations call captureCanvasState() directly:

• WidgetSelectDropdown.vue — After dropdown selection and file upload
• ColorPickerButton.vue — After changing node colors
• NodeSearchBoxPopover.vue — After adding a node from search
• builderViewOptions.ts — After setting default view
• useSelectionOperations.ts — After align, copy, paste, duplicate, group
• useSelectedNodeActions.ts — After pin, bypass, collapse
• useGroupMenuOptions.ts — After group operations
• useSubgraphOperations.ts — After subgraph enter/exit
• useCanvasRefresh.ts — After canvas refresh
• useCoreCommands.ts — After metadata/subgraph commands
• appModeStore.ts — After app mode transitions

workflowService.ts calls captureCanvasState() indirectly via deactivate() and prepareForSave() (see Lifecycle Methods below).

Deprecated: checkState() is an alias for captureCanvasState() kept for extension compatibility. Extension authors should migrate to captureCanvasState(). See the @deprecated JSDoc on the method.

Lifecycle Methods

Method	Caller	Purpose
captureCanvasState()	Event handlers, UI interactions	Snapshots canvas into activeState, pushes undo. Asserts active tracker.
deactivate()	beforeLoadNewGraph only	captureCanvasState() (skipped during undo/redo) + store(). Freezes state for tab switch. Must be called while this workflow is still active.
prepareForSave()	Save paths only	Active: calls captureCanvasState(). Inactive: no-op (state was frozen by deactivate()).
store()	Internal to deactivate()	Saves viewport scale/offset, node outputs, subgraph navigation.
restore()	afterLoadNewGraph	Restores viewport, outputs, subgraph navigation.
reset()	afterLoadNewGraph, save	Resets initial state (marks workflow as "clean").

Transaction Guards

For operations that make multiple changes that should be a single undo entry:

changeTracker.beforeChange()
// ... multiple graph mutations ...
changeTracker.afterChange() // calls captureCanvasState() when nesting count hits 0

The litegraph:canvas custom event also supports this with before-change / after-change sub-types.

Key Invariants

• captureCanvasState() asserts it is called on the active workflow's tracker; inactive trackers get an early return (and a warning log)
• captureCanvasState() is a no-op during loadGraphData (guarded by isLoadingGraph) to prevent cross-workflow corruption
• captureCanvasState() is a no-op during undo/redo (guarded by _restoringState) to prevent undo history corruption
• captureCanvasState() is a no-op when changeCount > 0 (inside a transaction)
• undoQueue is capped at 50 entries (MAX_HISTORY)
• graphEqual ignores node order and ds (pan/zoom) when comparing