gum-tool-undo
Skill659 starsChanged 2 months agoMITView on GitHub
Gum undo/redo. Triggers: History tab, UndoManager, UndoPlugin, UndoSnapshot, stale references after undo.
In this repository69 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- debuggingSkill
- frb-build-verificationSkill
- frb-pixel-harnessSkill
- gum-architecture-layersSkill
- gum-bundleSkill
- gum-cliSkill
- gum-cross-platform-unificationSkill
- gum-docs-writingSkill
- gum-file-pathsSkill
- gum-forms-behaviorsSkill
- gum-forms-controlsSkill
- gum-forms-default-visualsSkill
- gum-forms-itemscontrolSkill
- gum-forms-theme-importSkill
- gum-iconsSkill
- gum-issue-creationSkill
- gum-kernsmith-integrationsSkill
- gum-layout-engineSkill
- gum-layoutSkill
- gum-localizationSkill
- gum-monogame-renderingSkill
- gum-monthly-releaseSkill
- gum-project-versioningSkill
- gum-property-assignmentSkill
- gum-raylib-renderingSkill
- gum-releaseSkill
- gum-runtime-animation-chainsSkill
- gum-runtime-bindingSkill
- gum-runtime-fontsSkill
- gum-runtime-hot-reloadSkill
- gum-runtime-syntax-versionSkill
- gum-runtime-systemmanagers-initSkill
- gum-runtime-topologySkill
- gum-runtime-variable-referencesSkill
- gum-samplesSkill
- gum-serviceSkill
- gum-source-linked-projectSkill
- gum-themingSkill
- gum-tool-animationsSkill
- gum-tool-codegenSkill
- gum-tool-copy-pasteSkill
- gum-tool-delete-logicSkill
- gum-tool-dialogsSkill
- gum-tool-errorsSkill
- gum-tool-file-watchSkill
- gum-tool-font-generationSkill
- gum-tool-import-from-gumxSkill
- gum-tool-loggingSkill
- gum-tool-outputSkill
- gum-tool-pluginsSkill
- gum-tool-save-classesSkill
- gum-tool-screenshotsSkill
- gum-tool-selectionSkill
- gum-tool-tree-viewSkill
- gum-tool-variable-gridSkill
- gum-tool-variable-referencesSkill
- gum-tool-viewmodelsSkill
- gum-unit-testsSkill
- gum-variable-deep-diveSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 26
When an element (Screen, Component, or StandardElement) is deleted, its entire undo history is discarded along with it.
- Very specific: line 69
Always use RequestLock() — never call RecordState() or RecordUndo() manually:
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Gum Undo/Redo System Reference
Overview
Gum has a snapshot-based undo/redo system scoped per-element. Undo history is displayed in the History tab in the Gum UI tool.
Key Characteristics
Per-Element Scoping
Undo history is stored separately for each open element (Screen, Component, or StandardElement). Switching between elements does not share or merge history — each element maintains its own independent undo stack.
Narrow exception — cross-element variable changes (ADR 0016). An action that removes or rewrites variables on OTHER elements (deleting a component variable or a state/category that instances elsewhere set, renaming a state/category) records those changes with IUndoManager.RecordCrossElementVariableChanges while holding its RequestLock; they attach to the action recorded when the last lock releases and are discarded if none is. Each CrossElementVariableChange holds before/after copies (CaptureBefore/CaptureAfter). Undo/redo replays them against the other elements directly, skipping deleted targets (an instance or category state the other element's own undo swapped for a clone is found again by name), restoring a removal only if the name is absent, and reversing a modification only if the variable still holds what the action left; each replay saves via TryAutoSaveElement and fires VariableSet. This works only because Gum has no tabs — at most one element has an active RecordState baseline at a time. Callers: DeleteVariableService, DeleteLogic (state/category delete), RenameLogic (state/category rename).
No Selection Tracking
Undos do not record or restore the user's selection state. After undoing or redoing an operation, the selected object in the tree view or canvas may not match what was selected when the change was originally made.
No Persistence
Undo history is entirely in-memory and is lost when Gum closes. Loading a different project clears it. Reloading the same project file (Import .gumx, Add Forms, an on-disk .gumx change) keeps the history of each element and behavior whose file and animations the reload left unchanged, and drops the rest (HandleProjectLoaded → CarryOverTo).
Element Deletion Is Not Undoable
When an element (Screen, Component, or StandardElement) is deleted, its entire undo history is discarded along with it. Deleting an element cannot be undone.
Behaviors Have Their Own Strategy
A behavior's own changes (required instances, categories, states, required variables) undo through BehaviorUndoStrategy: whole-behavior clone snapshots applied in place to the same BehaviorSave, with one history per behavior. Behavior-instance and category/state changes record through the UndoPlugin handlers; a baseline for a behavior that is not selected needs RecordBehaviorState(behavior). Adding or removing a behavior reference on an element is an element change and goes through ElementUndoStrategy.
The snapshot covers every serialized BehaviorSave field (name, categories, required variables and instances, Forms properties, tool-only variable references, required animations, default implementation). Elements reference a behavior by name, so restoring a different name calls IUndoRenameLogic.RenameBehavior, the same BehaviorRenamer the Rename Behavior command uses: it renames the elements' ElementBehaviorReferences, the project's BehaviorReference and the .behx, then the history (keyed by the BehaviorSave object, so a rename neither orphans nor duplicates it) carries on. The command takes a RequestLock() so the rename is one behavior history step. Those element-side reference edits are not recorded in the elements' own histories, so BehaviorUndoStrategy also calls ElementUndoStrategy.RenameBehaviorInSnapshots (when the rename is recorded, and on every undo/redo that changes the name) to rewrite the old name in every stored element snapshot; otherwise replaying an older element step would bring back a reference to a behavior that no longer exists. NameVerifier.IsBehaviorNameValid rejects a name another behavior already has (case-insensitively), because the file is named after the behavior.
History Tab
The History tab in the Gum UI tool displays a human-readable list of all recorded undo actions for the currently selected element. Each entry shows a description of what changed, such as:
Modify element variables: X=10Add instances: MySpriteRemove instances: MySpriteAdd behaviors: MyBehaviorExposed variables: MyVar
The list is built by working backwards through undo snapshots and diffing consecutive states, so descriptions reflect the actual change rather than raw data.
What Is Tracked
The undo system records changes to:
- Element-level variable values (position, size, color, etc.)
- Instance additions and removals
- Instance reordering (tracked as index changes)
- State additions, removals, and variable changes within states
- Category additions and removals
- Variable exposure and unexposure
- Element animations (the
.ganxsidecar) — folded into the element'sUndoSnapshot.Animationsso an animation edit undoes atomically with the state rename/delete it was made next to (#3406). Keyframes reference states by name, so the two are coupled and must restore together or the reference desyncs.ElementUndoStrategycaptures/diffs/applies animations through the headlessIAnimationUndoProviderseam; the animation plugin implements it (reading the live tab or the.ganx) and flushes a record from itsHandleDataChangechoke point via an emptyRequestLock.
How Recording Works
The system uses a two-phase record approach:
RecordState()— Captures a snapshot of the element's current state before a change begins. Called automatically byUndoPluginon element selection, state selection, etc. Do NOT call this manually from feature code.RecordUndo()— Compares the current state against the recorded snapshot; if anything changed, saves an undo action. Called automatically when anUndoLockis disposed.
Correct Pattern for Recording Undos
Always use RequestLock() — never call RecordState() or RecordUndo() manually:
using var undoLock = _undoManager.RequestLock();
// make your changes here
// lock disposal fires RecordUndo() automaticallyRequestLock() adds an UndoLock to UndoLocks. When the lock is disposed (end of using block), it removes itself; when UndoLocks reaches 0, HandleUndoLockChanged fires RecordUndo(). The RecordState() baseline is already set by the framework when the user selected the element.
Why not RecordState() manually? RecordState() is a no-op when any locks are held, and calling it outside of that flow risks overwriting the correct baseline snapshot.
A Variables-tab edit's undo step is recorded when its lock is released after plugins react to VariableSet (SetVariableLogic), not before, so what plugins change in response (e.g. inherited instances after a BaseType change) undoes with the edit.
Changing an element that is not the selected one (a tree drop that reorders or reparents inside another open element, #4692): request the lock for that element instead, _undoManager.RequestLock(targetElement), before anything mutates it and at the outermost point of the operation. ElementUndoStrategy.CaptureBaseline(element) snapshots that element at that moment (bypassing the lock guard, since the caller holds the lock) and TryRecordTargeted() diffs it when the last lock releases, appending to that element's history. For the selected element the overload is the plain lock, so it is safe to call unconditionally. A lock taken after the mutation records nothing: the baseline already contains the change.
Snapshots Are Deep Copies
Both element and behavior snapshots use CloneElement/CloneBehavior, so every saved snapshot contains new object instances with different references than the live data. When undo is applied, the restored instances replace the live ones — meaning any code holding a reference to the pre-undo instance now has a stale reference that no longer exists in the element or behavior.
Consequence: after an undo, _selectedState.SelectedInstance may point to a stale object. Reference-based lookups (e.g. tree node searches using ==) will fail. Name-based fallback is required to re-locate the logically equivalent node. If undo also changes the instance's name, or removes it, the instance selection is dropped and, for a behavior, the behavior stays selected: ElementTreeViewManager.SelectRecordedSelection uses GetBehaviorOfStaleInstance instead of assigning the stale instance, because a behavior is found through its required instances and a stale one would clear SelectedBehavior, leaving the next undo with nothing to act on. The element path is left as it was: selecting the element in place of a dropped instance sends no SelectionChangedMessage, so the add destination would stay anchored to the old container.
Undo And Redo Re-Run The Reference Cascade
After restoring a snapshot, ElementUndoStrategy.DoAfterUndoLogic calls IVariableReferenceLogic.ReapplyReferences (before CaptureBaseline, with no lock held, so no history entry) so reference followers re-read the restored sources like a typed edit. A snapshot's follower values are therefore never trusted; do not put a second cascade in an AfterUndo plugin handler. ReapplyReferences also re-runs BehaviorToolOnlyReferencesApplier.Apply on every restore, so a snapshot's derived tool-only values (ButtonCategoryState) are never trusted either; RebaseStoredValues covers only reference-row values.
Implementation Files
| File | Purpose |
Tools/Gum.Presentation/Undo/UndoManager.cs | Orchestrator; delegates to ElementUndoStrategy (per-element history, Dictionary<ElementSave, ElementHistory>) and BehaviorUndoStrategy |
Tools/Gum.Presentation/Undo/ElementUndoStrategy.cs | Element undo/redo track: capture/diff/apply, plus cross-element variable change attach + replay |
Tools/Gum.Presentation/Undo/UndoPlugin.cs | Event handlers that call RecordState() / RecordUndo() (shared by both heads) |
Tools/Gum.Presentation/Undo/UndoSnapshot.cs | Snapshot structure and diff/comparison logic (UndoComparison) |
Tools/Gum.Presentation/Undo/ElementHistory.cs | HistoryAction (undo/redo snapshot pair + optional CrossElementVariableChanges) and ElementHistory |
Tools/Gum.Presentation/Undo/CrossElementVariableChange.cs | One variable removal or modification on another element, attached to an action for undo/redo replay |
Tools/Gum.Presentation/Undos/UndosViewModel.cs | History tab display and description generation (shared) |
Tool/Gum.Avalonia/Panels/InternalPanelViews.cs (UndosView) | Avalonia History tab (the shipped tool) |
Gum/Plugins/InternalPlugins/Undos/UndoDisplay.xaml | WPF ListBox UI for the History tab (frozen head) |
Gum/Plugins/InternalPlugins/Undos/UndoItemViewModel.cs | Individual history item (display text + undo/redo direction) |
Tests/Gum.Presentation.Tests/UndoManagerTests.cs | Unit tests for undo behavior |
Known Limitations Summary
| Limitation | Details |
| No general cross-element undo | Undo stacks are per-element; a change to a non-selected element records into that element's own history through RequestLock(element) (undo it after selecting that element), and the only action spanning two histories is a variable change recorded via RecordCrossElementVariableChanges (see above) — everything else stays ungrouped |
| No selection restore | Selection state is not captured or restored on undo/redo |
| No persistence | History is lost on app close or opening another project; a same-project reload keeps unchanged elements' history |
| No element-deletion undo | Deleting an element removes its history permanently |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

