agentleFS
vchelaruvchelaru/Gum/.claude/skills/gum-tool-undo/SKILL.md

gum-tool-undo

Skill659 starsChanged 2 months agoMITView on GitHub

Gum undo/redo. Triggers: History tab, UndoManager, UndoPlugin, UndoSnapshot, stale references after undo.

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
  1. Distinctive:

    When an element (Screen, Component, or StandardElement) is deleted, its entire undo history is discarded along with it.

    line 26
  2. Very specific:

    Always use RequestLock() — never call RecordState() or RecordUndo() manually:

    line 69

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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=10
  • Add instances: MySprite
  • Remove instances: MySprite
  • Add behaviors: MyBehavior
  • Exposed 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 .ganx sidecar) — folded into the element's UndoSnapshot.Animations so 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. ElementUndoStrategy captures/diffs/applies animations through the headless IAnimationUndoProvider seam; the animation plugin implements it (reading the live tab or the .ganx) and flushes a record from its HandleDataChange choke point via an empty RequestLock.

How Recording Works

The system uses a two-phase record approach:

  1. RecordState() — Captures a snapshot of the element's current state before a change begins. Called automatically by UndoPlugin on element selection, state selection, etc. Do NOT call this manually from feature code.
  2. RecordUndo() — Compares the current state against the recorded snapshot; if anything changed, saves an undo action. Called automatically when an UndoLock is 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() automatically

RequestLock() 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

FilePurpose
Tools/Gum.Presentation/Undo/UndoManager.csOrchestrator; delegates to ElementUndoStrategy (per-element history, Dictionary<ElementSave, ElementHistory>) and BehaviorUndoStrategy
Tools/Gum.Presentation/Undo/ElementUndoStrategy.csElement undo/redo track: capture/diff/apply, plus cross-element variable change attach + replay
Tools/Gum.Presentation/Undo/UndoPlugin.csEvent handlers that call RecordState() / RecordUndo() (shared by both heads)
Tools/Gum.Presentation/Undo/UndoSnapshot.csSnapshot structure and diff/comparison logic (UndoComparison)
Tools/Gum.Presentation/Undo/ElementHistory.csHistoryAction (undo/redo snapshot pair + optional CrossElementVariableChanges) and ElementHistory
Tools/Gum.Presentation/Undo/CrossElementVariableChange.csOne variable removal or modification on another element, attached to an action for undo/redo replay
Tools/Gum.Presentation/Undos/UndosViewModel.csHistory tab display and description generation (shared)
Tool/Gum.Avalonia/Panels/InternalPanelViews.cs (UndosView)Avalonia History tab (the shipped tool)
Gum/Plugins/InternalPlugins/Undos/UndoDisplay.xamlWPF ListBox UI for the History tab (frozen head)
Gum/Plugins/InternalPlugins/Undos/UndoItemViewModel.csIndividual history item (display text + undo/redo direction)
Tests/Gum.Presentation.Tests/UndoManagerTests.csUnit tests for undo behavior

Known Limitations Summary

LimitationDetails
No general cross-element undoUndo 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 restoreSelection state is not captured or restored on undo/redo
No persistenceHistory is lost on app close or opening another project; a same-project reload keeps unchanged elements' history
No element-deletion undoDeleting an element removes its history permanently

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.