agentleFS
vchelaruvchelaru/Gum/.claude/skills/gum-tool-import-from-gumx/SKILL.md

gum-tool-import-from-gumx

Skill659 starsChanged 2 months agoMITView on GitHub

The "Import from .gumx" dialog. Triggers: ImportFromGumxPlugin, GumxDependencyResolver, ImportTreeNodeViewModel, ImportFromGumxView, importing components/screens/behaviors/standards across projects, the dialog's tree rows and Details link.

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:

    All three concrete services above (and their interfaces) live in the headless Gum.Presentation assembly (no WPF) — their dependency …

    line 17
  2. Very specific:

    When you touch the recompute loop: always detach OnItemPropertyChanged before mutating InclusionState, then re-attach.

    line 34

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

Import from .gumx Dialog

Cross-project import dialog (Content → Import → ".gumx…"). Lets the user pick a source .gumx (local or URL), preview its Components/Screens/Behaviors/Standards in a checkbox TreeView, and import a selected subset into the currently open project.

Layout (one-screen map)

  • Gum/ImportFromGumxPlugin/MainImportFromGumxPlugin.cs — plugin entry, menu item, DI wiring.
  • Tools/Gum.Presentation/Plugins/ImportPlugin/Services/GumxSourceService — loads source .gumx (file path or URL).
  • Tools/Gum.Presentation/ImportFromGumx/Services/GumxDependencyResolver — ComputeTransitive(...) → DependencySet { TransitiveComponents, Behaviors, DifferingStandards, DifferingStandardDiffs }. Standards that differ from destination are included; standards that match are excluded entirely. An imported Standard replaces the target's whole, element file and animation file (one the source lacks is deleted); components and screens instead follow the Skip/Overwrite choice. A component kept by Skip still gains the instances (with their default-state values) that imported elements read through VariableReferences and it lacks, such as a new Styles swatch, plus the category states they select on its instances and it lacks (a missing category is created with only those states); nothing it already has changes (GumxImportService.AddMissingReferencedInstances). A differing Standard a selected element uses is force-included, its checkbox disabled with the reason as tooltip. The DifferingStandardDiffs dictionary (#2779) carries the full StandardComparisonResult per differing standard so the dialog can render a variable-level diff.
  • Tools/Gum.Presentation/ImportFromGumx/Services/GumxImportService — performs the actual import + conflict reporting.

All three concrete services above (and their interfaces) live in the headless Gum.Presentation assembly (no WPF) — their dependency closures were already headless, so the concrete classes moved too, not just their interfaces. GumxSourceService/IGumxSourceService keep their original Gum.Plugins.ImportPlugin.Services namespace; GumxDependencyResolver/GumxImportService use ImportFromGumxPlugin.Services.

  • Tools/Gum.Presentation/ImportFromGumx/ImportFromGumxViewModel — orchestrates load/preview/import; owns RootNodes and RecomputeTransitiveDependencies().
  • Tools/Gum.ProjectServices/ImportFromGumx/ImportTreeNodeViewModel — one node in the TreeView; folder or leaf; carries IsChecked, InclusionState, optional StandardDiffRows. Lives in the headless net8.0 Gum.ProjectServices assembly (no WPF) so its display logic is unit-testable without standing up WPF (#3229, ADR-0003/0004); namespace stays ImportFromGumxPlugin.ViewModels.
  • Tools/Gum.ProjectServices/ImportFromGumx/StandardDiffRowViewModel — passive Kind + Summary display record for one diff entry (same headless assembly; sibling ImportPreviewItemViewModel.cs holds the ElementItemType/InclusionState enums).
  • Tool/Gum.Avalonia/Plugins/PluginDialogs/ImportFromGumxViews.cs — the dialog (ImportFromGumxView) and the read-only "Details..." modal (StandardDiffDetailsView), built in C#. The modal's view model is Tools/Gum.Presentation/ImportFromGumx/StandardDiffDetailsViewModel.

Other callers: Add Forms

Add Forms (gum-forms-theme-import) imports a theme through GumxImportService and, on a conflict, opens this dialog on the theme with a FixedImportSource (ImportFromGumxDialog.ShowAsync): no source or subfolder rows, Standards hidden unless asked, GetDestinationStatus marks rows the project has (StatusNote/StatusHint) and starts only new ones checked. ImportAsync's beforeImport hook runs once the import is going ahead, before any write. An existing destination file whose content equals what would be written is not a conflict.

InclusionState bookkeeping (#2642)

Three sets of state live on ImportFromGumxViewModel:

  • _autoAddedComponentNames — components that the resolver pulled in transitively. Cleared and rebuilt every recompute pass. Auto-added items get reset to NotIncluded first so unchecked-by-user deselection sticks.
  • _userExplicitBehaviorNames / _userExplicitStandardNames — behaviors/standards the user explicitly checked. Must be preserved across recompute, because RecomputeTransitiveDependencies wipes those groups and rebuilds from resolver output.

When you touch the recompute loop: always detach OnItemPropertyChanged before mutating InclusionState, then re-attach. Otherwise the mutation re-enters the recompute path and clobbers tracking.

Nothing is skipped silently

Anything GumxImportService.ImportAsync cannot bring over (a listed file that is missing or damaged, a missing texture or font, a behavior or Standard it cannot copy, a name the project refuses, an unreadable .ganx) goes into ImportResult through AddSkipped(name, reason), and the rest still imports. GumxSourceProblems.Find lists what the source project names but did not load (a missing file loads as an IsSourceFileMissing stand-in; a damaged one is left out of the lists). Add Forms shows DescribeSkipped() one line per item; the dialog shows the first five. A caller that imports only part of a source scopes what counts with ImportSelections.ReportSourceProblem (Add Forms ignores an unused Standard or demo screen). A failure mid-write throws ImportFailedException listing the files already written, since the import writes in place. Show lists of skipped items through ImportResult.CapLines. A new early return, continue or catch in the import path must report the same way.

Files reached through another file: each copied .achx/.achj is loaded with AnimationChainListSave.FromFile and its textures are copied with their path relative to the chain kept (once if shared). A texture that is missing, absolute, or leaves the source project, and a chain that will not load, go through AddSkipped; the element still imports. Shader files (ShaderFileExtensions) are copied like any Source File.

Files outside the source project

ExternalAssetPlan (built before classification, reads only) decides where every asset the elements name from OUTSIDE the source folder lands: a .. or absolute path to a real file is copied into the destination's external folder (an existing folder of that name, any casing, is reused; none is created unless needed) and ExternalAssetPlan.Rewrite points every variable in every state and category of the cloned element, and of imported Standards, at the copy. Behaviors (states, required variables, forms properties) and the instances and category states added to a component kept by Skip are rewritten the same way. Same content (SHA-256) already there is reused, a different file with the same name (case-insensitive) becomes name-2.ext; an outside animation chain keeps its textures' layout relative to it (a group, renamed by folder on conflict). Destination paths are never built from the source's ... A missing outside file is reported like any missing file. Web sources are never planned.

SourceProjectContainment.GetRefusal refuses what resolves outside THROUGH a link (symlink or junction on the file or any parent folder) and is applied to every asset read and the element animation file. Behavior and Standard file paths are not checked: a project may reference them anywhere. An in-project chain whose texture climbs out of the project is still refused.

Tree rows

Each row is a check box plus a "Details..." HyperlinkButton, visible only on flagged-Standard rows (ImportTreeNodeViewModel.IsDetailsButtonVisible). The link opens StandardDiffDetailsView as a separate modal showing the row's StandardDiffRows; the diff is not expanded inline in the tree. A force-included Standard's check box is disabled, with RequiredReason as its tooltip.

Diff row generation

ImportFromGumxViewModel.BuildDiffRows(StandardComparisonResult) flattens:

  • Added/removed categories → StandardDiffRowViewModel("Category added"|"Category removed", name).
  • Each StandardVariableDiff → one row with Kind mapped from StandardVariableDiffKind (Added/Removed/Changed) and Summary = "{Variable} · {Field}: {Default} → {Project} · ...".

Returns null when there are no rows, so the row shows no Details link.

Testing

  • ImportFromGumxViewModelTests (in Tests/Gum.Presentation.Tests/Plugins/ImportFromGumxPlugin/) uses InitializeFromProjectForTesting(GumProjectSave) to bypass the file/URL load and seed the source. The _projectState field exposes the destination (a FakeProjectState whose GumProjectSave is mutable) so tests can stage destination standards/components for diff and conflict scenarios.
  • GumxDependencyResolverTests operate on the resolver directly without going through the VM.
  • ImportTreeNodeViewModelTests lives in Tests/Gum.ProjectServices.Tests — it covers the node's IsChecked folder/child cascade and the IsDetailsButtonVisible flag.
  • The Avalonia view is covered headlessly in Tests/Gum.Avalonia.Tests (PluginDialogTests), and the end-to-end import scenarios are in EndToEnd/FormsAndImportScenarioTests.cs.

History notes

  • #2642 fixed user-explicit behaviors/standards being wiped on the dispatcher tick.
  • #2644 added the conflict-resolution dialog (Skip / Overwrite All).
  • #2779 added variable-level diff rendering for flagged Standards. The underlying diff infrastructure (IStandardComparer in Tools/Gum.ProjectServices) already existed for the CLI; this issue surfaces it in the UI.

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.