Atomui Control Performance

AtomUI Control Performance Skill

Correctness outranks performance. Every rule below exists to defend that priority. If any rule conflicts with correctness, correctness wins.

Tier 1 — Hard Boundaries

Violating any of these blocks merge. No exception, no tradeoff, no "it's only one case".

1. Correctness regression is unacceptable. Performance optimization must preserve control functionality, UI appearance, animation behavior, interaction semantics, theme behavior, and public API. Any visible or behavioral change caused by an optimization is a regression, not a tradeoff. If the user explicitly approves a behavior change, that becomes a separate non-perf change, not a perf optimization.

2. No logic bug introduction. This includes invalid visual states, broken state transitions, incorrect property precedence, stale layout/render state, lost interactions, incorrect lifecycle cleanup, race conditions in event chains, or Gallery-visible behavior mismatches. Discovering one mid-optimization means stop, fix or revert immediately, do not continue stacking perf changes on top.

3. No resource leak. Anything created/subscribed/bound/cached/lazily materialized/reparented must have a defined and verified release path before the change is considered complete. Leak scanning is mandatory during analysis, not optional cleanup afterward.

4. No measurable speed regression. If any primary metric for the targeted control or its real Gallery ShowCase gets worse under the same measurement policy, the change must be fixed, split, reverted, or explicitly reported as a blocker.

5. No materially more complex implementation logic. Fragile state machines, duplicated template/style logic in code, broad lifecycle orchestration, unclear synchronization, or code harder to reason about than the original behavior warrants — all indicate the optimization is too expensive in complexity. Stop and propose a simpler option instead. See Process Gate 3 for the numeric thresholds that flag this.

6. No theme element → C# dynamic creation. See Theme Static Rule. This is the highest-leverage rule in this document; nearly all rollback incidents stem from violating it.

7. No same-priority binding collisions for the same property. If a property has both an internal default binding and an external override binding, they must be at different BindingPriority levels. See Avalonia Binding Priority Guardrails.

8. No BindUtils.RelayBind + disposable plumbing for lifetime-consistent children. When source and target have the same owner and lifetime, use Avalonia [!] binding syntax. Disposable infrastructure is reserved for mismatched lifetimes, replacement paths, detach/re-template, global/window subscriptions, timers, or lazily materialized objects.

9. 3-rounds optimization budget. For the same scoped target, three implementation-and-measurement rounds without primary speed metric improvement = stop. At end-of-optimization, if no worthwhile gain: restore every perf-only change, delete intermediate scratch code/docs, keep only correctness fixes / leak fixes / useful measurement tooling. Report exactly what was reverted, what correctness fixes were kept, what cleanup was done.

10. 5-control pattern rollout circuit breaker. Same refactor pattern (e.g., dynamic creation, lazy popup materialization, binding restructure) applied to ≥ 5 controls = stop and audit. Two questions: (a) did at least 3 of 5 show measurable speed gain? (b) did any one introduce ≥ 2 Gallery-visible bugs? Either "no" / "yes" stops further rollout and triggers reflection before the 6th control.

11. No unsupported claims about framework behavior. Any assertion such as "X triggers Y", "Z is O(N)", "this binding takes the fast path", or "IsVisible=False is free" MUST be backed by the currently resolved dependency source or by a measurement with explicit methodology. Source inspection is evidence about the current implementation, not an AtomUI architecture contract. Long-term documents keep AtomUI invariants and revalidation conditions; exact external versions, paths and line numbers belong only in dated upgrade or investigation records. See Framework Behavior Evidence.

12. No _ignoreXxx flags in property-changed handlers. Adding a private bool (_ignoreSelectedPropertyChanged, IgnorePropertyChange, _isUpdating, _suppressNotification, etc.) to short-circuit property-changed dispatch hides bugs rather than fixing them. The Cascader / AbstractSelect rollbacks all follow this pattern. See Re-entrancy & Ignore-Flag Guardrails. The few legitimate cases are listed there; the default answer is "fix the event flow, do not add the flag".

13. Optimization qualification documented. Every perf commit must state — in the commit description — the realistic instance count for the targeted control in its busiest Gallery ShowCase, and the per-session frequency of the operation being optimized. If instance count ≤ 5 AND operation frequency < 1/session, the commit must explain why optimization is still warranted, or be rejected before measurement begins. The investigation playbook's qualification gate (see First-60-Minutes Investigation Playbook) is the operational form of this rule.

14. Benefit report is mandatory at completion. Every optimization turn MUST proactively report the benefit to the user before stopping, even if the user did not ask. Start with a one-sentence plain-language takeaway that says what became cheaper and where the user benefits. Then include a table with metric / baseline / optimized / formula / improvement / conclusion. Metric names must be user-readable and include units/scopes such as per close, per row, per DataGrid, or per Gallery page; do not report only internal method/class names or raw callsite counts. If the optimization is structural-only, report the structural count reduction (for example handlers per instance, bindings per item, visuals per root, objects allocated per operation) and its percentage, and explicitly say it does not claim page-load speedup unless timing proves it. If timing data is single-run smoke, label it smoke-only and do not present it as proof of speedup. If no valid before/after timing exists, explicitly say that no timing percentage is claimed and use the structural/correctness result as the benefit. This is part of the definition of "done".

Framework Behavior Evidence

Use the source matching the currently resolved Avalonia dependency to verify framework-behavior hypotheses. Every framework-behavior claim in a review or commit description must cite current implementation evidence or reproducible measurement. Revalidate source-derived claims after dependency upgrades, and never promote a particular external version, commit, local path, or line number into AtomUI's long-term architecture contract.

The verified cost model and counter-intuitive points are maintained in this skill. Use the Cost Model below for both the evidence summary and the operational rule.

Required reading paths by subsystem

• Property system: Avalonia.Base/AvaloniaProperty.cs, AvaloniaObject.cs, PropertyStore/ValueStore.cs, Data/BindingPriority.cs, PropertyStore/FramePriority.cs
• Binding: Avalonia.Base/Data/TemplateBinding.cs, Data/TemplateBindingExpression.cs, Data/Core/BindingExpression.cs, Data/Core/MultiBindingExpression.cs, AvaloniaObjectExtensions.cs, PropertyStore/DirectBindingObserver.cs, Markup.Xaml.Loader/CompilerExtensions/XamlIlBindingPathHelper.cs
• Layout: Avalonia.Base/Layout/LayoutManager.cs, Layout/Layoutable.cs, Layout/LayoutQueue.cs, Visual.cs
• Render / Composition: Avalonia.Base/Visual.cs (AffectsRender, InvalidateVisual), Rendering/IRenderer.cs, Rendering/ImmediateRenderer.cs, Rendering/Composition/Server/ServerCompositionVisual/ServerCompositionVisual.DirtyInputs.cs, Media/SolidColorBrush.cs, Media/Pen.cs, Media/StreamGeometry.cs
• Routed events: Avalonia.Base/Interactivity/RoutedEvent.cs, Interactivity/Interactive.cs, Interactivity/EventRoute.cs, Input/InputElement.cs
• Style / Selector: Avalonia.Base/Styling/Selector.cs, Styling/TemplateSelector.cs, Styling/Activators/PropertyEqualsActivator.cs, Styling/Activators/StyleClassActivator.cs, Styling/Activators/NthChildActivator.cs, Styling/ControlTheme.cs, Styling/Setter.cs, Styling/PropertySetterTemplateInstance.cs, Styling/Styles.cs, StyledElement.cs
• Templates / ItemsControl: Avalonia.Controls/Primitives/TemplatedControl.cs, Controls/Presenters/ItemsPresenter.cs, Controls/Presenters/ContentPresenter.cs, Controls/Templates/DataTemplateExtensions.cs, Controls/ItemsControl.cs, Controls/VirtualizingPanel.cs
• Popup: Avalonia.Controls/Primitives/Popup.cs, Primitives/PopupRoot.cs, Primitives/OverlayPopupHost.cs
• Dispatcher / Threading: Avalonia.Base/Threading/DispatcherPriority.cs, Threading/Dispatcher.cs, Threading/Dispatcher.Invoke.cs, Threading/Dispatcher.Timers.cs
• Animation / Transition: Avalonia.Base/Animation/Animatable.cs, Animation/Transition.cs

Required practice

• Before claiming X is cheaper than Y in a commit description, point at the source path proving it. The Cost Model below is the first lookup; the pitfalls doc gives the explanation.
• If you can't find the source backing your claim in 5 minutes, your claim is a guess. Either measure it explicitly or remove it.

Verification mark

Items still pending source verification are marked [VERIFY]. Decisions must not depend on [VERIFY] items. The current open list lives in §13 of the pitfalls doc.

Theme Static Rule

Functional visuals defined in ControlTemplate / ControlTheme stay in axaml. Moving them to C# EnsureXxx() / ClearXxx() dynamic creation as a performance optimization is prohibited by default.

Why this is a hard boundary

The cost asymmetry is overwhelming:

The "saved" cost of a hidden axaml node is one Visual instance plus its initial template inflation. Every rollback in §[Incident Callouts] confirmed that this saving was outweighed by the ongoing churn of manual Ensure*/Clear* plus the lost /template/ cascade. The complexity cost of dynamic creation is permanent and compounds across controls.

/template/ selector requires TemplatedParent — non-negotiable

If you must create template children in C# (one of the three exceptions below), the framework will not match /template/ selectors against them unless TemplatedParent is set. TemplateSelector.Evaluate returns NeverThisInstance when control.TemplatedParent == null (Avalonia.Base/Styling/TemplateSelector.cs:39-49). That means every theme rule like ^[X=true] /template/ Foo#bar { ... } silently stops applying to the new C# child.

Required handling whenever a template child is created in C#:

1. Call child.SetTemplatedParent(this) immediately after creation.
2. Call child.SetTemplatedParent(null) in the symmetric Clear* path or OnDetachedFromVisualTree.
3. The Resource Leak Detection grep already includes both calls — confirm the pair stays balanced.

Allowed exceptions (must be argued in commit description)

1. Heavy popup content. Subtree node count ≥ 20, or contains ItemsControl / ScrollViewer / TreeView / CascaderView / calendar/time panels / large layout trees. The lightweight Popup shell still stays in axaml; only the popup's CONTENT may be deferred. See Popup Lazy Content Rule.
2. Adorner / overlay-layer content. Adorners cannot live in ControlTemplate (architectural constraint, see Avalonia.Controls/Primitives/AdornerLayer.cs). Notification cards, overlay dialogs, drawer overlays, tooltips fall here.
3. Variable-N data items. When N is unknown at compile time. Prefer ItemsControl + ItemTemplate; only when ItemsControl is structurally insufficient may Children.Add be used directly.

Any "fourth case" requires opening a discussion with the user and updating this skill before merge.

Reasons that are NOT acceptable for an exception

• ❌ "Save X bytes of allocation"
• ❌ "Save unused PropertyChanged broadcasts"
• ❌ "Element only used in mode Y" — use IsVisible="False" + selector instead
• ❌ "First-time inflation is slow" — one-time cost, dominated by runtime Ensure churn
• ❌ "Keep parity with TreeSelect / Select / etc." — consistency does not override hard boundary

Right way to make a sometimes-shown element cheap

<!-- ✅ Correct: stay in axaml, hide by default, reveal via selector -->
<atom:CheckBox Name="ToggleCheckbox"
               IsChecked="{TemplateBinding IsChecked, Mode=TwoWay}"
               IsVisible="False" />

<Style Selector="^[ToggleType=CheckBox] /template/ atom|CheckBox#ToggleCheckbox">
    <Setter Property="IsVisible" Value="True" />
</Style>

// ❌ Wrong: do not move axaml elements into C# dynamic creation
private CheckBox? _toggleCheckbox;
private CompositeDisposable? _toggleCheckboxDisposables;
private void EnsureToggleCheckbox() { /* ... */ }
private void ClearToggleCheckbox() { /* ... */ }

Reviewer must check

Before approving any perf commit, grep new EnsureXxx() / ClearXxx() introductions and confirm each falls into one of the three allowed exceptions. If not, the commit fails this hard boundary.

Popup Lazy Content Rule

This is the implementation of Theme Static Rule exception 1.

• A lightweight Popup shell stays in ControlTheme. It preserves placement, light-dismiss, overlay, theme styling, and required template contracts.
• Heavy popup content must not be created in the default closed state. Examples: candidate lists, TreeView, CascaderView, calendar/time panels, complex item presenters, filter lists, empty indicators, large popup layout trees.
• First-open materialization. Create popup content immediately before the first open, wire events and bindings there, sync pending selection/filter/items state after creation.
• Keep materialized after close by default — open/close churn is worse than the saved allocation. Release on re-template, detach, or explicit disposal paths.
• Closed controls pay nothing. No popup-only event subscriptions, no items-source copies, no filter setup, no selection sync, no heavy visual tree creation while popup is closed.
• Lifecycle verification. Cover first open, close, second open, re-template, detach, visual parent cleanup, event unsubscribe, binding disposal, and state toggles (loading/filter/selection).

Framework Cost Model

The following model records implementation evidence used to form and falsify performance hypotheses. Source coordinates are review aids for the currently resolved dependency and must be revalidated after upgrades; the AtomUI implication and its measurement gate are the durable parts. Use each entry's evidence, AtomUI implication, and measurement gate as the complete review record.

Property System

Binding System

Layout & Visual Tree

Render / Composition

Routed Events

Style / Selector / ControlTheme

Templates / ItemsControl

Popup

Dispatcher / Threading

Animation / Transition

Counter-Intuitive Framework Behaviors (verified)

These are the rules that catch new contributors most often. Each was confirmed (or refined) against source.

• IsVisible=False is genuinely free. Three-way short-circuit at Layoutable.cs:546, :671, ImmediateRenderer.cs:34. This is the foundation of Theme Static Rule.
• TemplateBinding is its own fast path, not a flavor of Binding. TemplateBindingExpression subscribes directly to templatedParent.PropertyChanged. {Binding RelativeSource=...} is materially heavier — never substitute it (Avalonia.Base/Data/TemplateBindingExpression.cs:37-43 vs Data/Core/BindingExpression.cs:60-134).
• DirectProperty reads bypass the value store, so they cannot be overridden via Style / Animation / LocalValue priorities (Avalonia.Base/DirectPropertyBase.cs). Use them only for runtime-state that's never theme- or style-driven.
• /template/ selectors require TemplatedParent. A C# child added with Children.Add(...) and no SetTemplatedParent(this) silently fails to match ^... /template/ ... rules (Avalonia.Base/Styling/TemplateSelector.cs:39-49). This is the silent-cascade-loss footgun that most "C# dynamic" optimizations actually hit.
• $parent[T] is recomputed on every (de)attachment, not cached. It uses LogicalAncestorElementNode + ControlLocator.Track (Avalonia.Base/Data/Core/ExpressionNodes/LogicalAncestorElementNode.cs:59-68). For state that flows Popup ↔ content, store on the templated control and TemplateBinding from the popup content.
• [!] direct binding holds a strong ref source → target. Same-lifetime parent-child pairs are auto-managed (template lifetime). Cross-lifetime usage MUST go through BindUtils.RelayBind + CompositeDisposable (Avalonia.Base/PropertyStore/DirectBindingObserver.cs:7-84).
• Dispatcher.UIThread.Post(action) is enqueue, not "in a moment." Render, DataBind, Input, Loaded all preempt default priority (Avalonia.Base/Threading/DispatcherPriority.cs:25-127). If you find yourself reaching for Post to fix timing, the event flow is wrong.
• AffectsRender registration is lazy. Subscription is wired once at type registration; cost is only paid when the registered property actually changes (Avalonia.Base/Visual.cs:446-500). A property with no AffectsX registration is genuinely free of layout/render side-effects.
• Selector activators re-evaluate on every dependency change. Combined selectors like ^[Foo=true]:pointerover re-evaluate on Foo change AND on hover state change. Keep selectors shallow (Avalonia.Base/Styling/Selector.cs:44-68).
• ControlTheme.BasedOn is a linear recursive walk, no caching (Avalonia.Base/StyledElement.cs:776-793). Keep BasedOn chains ≤ 3 deep.
• Routed events traverse the popup boundary; visual ancestry does not. PopupRoot.InteractiveParent returns the logical Popup (Avalonia.Controls/Primitives/PopupRoot.cs:96), so RoutedEvent bubbling works. But PopupRoot is a separate visual root, so GetVisualAncestors and TransformToVisual(window) don't cross it. Pick the right ancestry mode for the situation.
• IsSet(property) is "any effective value entry exists", not "user explicitly set this" (Avalonia.Base/PropertyStore/ValueStore.cs:352). The Space ItemSpacing/LineSpacing incident roots here.
• Internal token defaults and external user bindings on the same property must NOT share priority. Same-priority entries Dispose each other. BindingPriority numeric ordering is verified at Avalonia.Base/Data/BindingPriority.cs:9-50.

Performance Decision Tree

When a "X is slow" report comes in, walk this tree before writing any code. Each step has a cut-off — stop early instead of forcing a fix.

报告 / 假设："X 慢"
  │
  ▼
Step 1. 测量复现
  │ - DevTools 触发 X，记录: layout pass 数 / property change 数 / allocation rate
  │ - AtomUI.Performance 跑 cold + repeated samples (≥10 cold)
  │ - 没有数字 → 拒绝优化（不许 fix vibes）
  │
  ▼
Step 2. 识别 Avalonia 子系统
  │ - 落在 Cost Model 哪个章节？
  │ - 该子系统的单位成本量级是多少？(必须有 source 引用，不许猜)
  │ - 实际触发频率是多少？(测量得来，不许估)
  │ - 单位成本 × 频率 ≥ 1ms / 帧预算占比 ≥ 5% ?
  │
  ├── 否 → 不是真瓶颈，没有优化空间 → 拒绝
  │
  └── 是 → Step 3
  │
  ▼
Step 3. Avalonia 是否已提供更便宜的等价路径？
  │ - axaml 静态 + IsVisible/Selector 能否实现？
  │ - DirectProperty 是否合适（无须 styled value frame）？
  │ - 编译绑定 (CompiledBinding) 能否替换反射绑定？
  │ - Static cached Pen/Brush 能否替换每次创建？
  │ - Method group dispatcher callback 能否替换 lambda？
  │ - 已有的 utility (MathUtils 等) 能否替换手写代码？
  │
  ├── 是 → 走该路径，无需自定义代码
  │
  └── 否 → Step 4
  │
  ▼
Step 4. 自定义代码的复杂度成本（参见 Tier 1 §5 + Process Gate 3）
  │ - 触发 Theme Static Rule？(默认禁止，例外 1/2/3 之外的拒绝)
  │ - 新增 Ensure/Clear 链？
  │ - 新增 disposable / 标志位？
  │ - 复杂度增长是否超过 Gate 3 阈值？
  │
  ├── 是 → 重新评估收益是否值得复杂度，不值得就放弃
  │
  └── 否 → Step 5
  │
  ▼
Step 5. 实现 + 测量 + Gallery 矩阵
  │ - 不通过 Tier 1 任一边界 = 回退
  │ - 3 轮 (Tier 1 §9) 没改善 = 回退
  │ - 5 控件批量 (Tier 1 §10) 触发 audit
  │ - 通过 Process Gates → 准备 commit

First-60-Minutes Investigation Playbook

This is the operational form of the Decision Tree. Walk it in order whenever a "X is slow" report comes in. Stop early at any step that disqualifies the optimization — most reports stop at Step 1 or Step 2.

Step 1 (0–5 min) — Qualification gate

Three yes/no questions. Any "no" closes the request without further investigation.

• Does the control instantiate > 5 times in any realistic Gallery ShowCase that ships? (Open the corresponding <Control>ShowCase in controlgallery/AtomUIGallery.Desktop and count.)
• Does the user trigger the operation > 1 time per realistic session? "Page first navigation" counts as 1.
• Is there a numeric report? "Feels slow" without numbers means we don't know what we're optimizing.

If any answer is no, the answer is: "this control does not qualify for optimization — Tier 1 §13". Record the numbers, close the request.

Step 2 (5–15 min) — Reproduce in Gallery

dotnet run --project controlgallery/AtomUIGallery.Desktop/AtomUIGallery.Desktop.csproj

• Navigate to the relevant ShowCase. Confirm visually that the slow operation reproduces.
• Open DevTools (F12). Use the Visual Tree pane to count realized visuals and confirm which presenters/popups/items are alive.
• Reproduce the slow action with DevTools focused; record the layout-pass and render-tick visible behavior. If the visual tree count is much higher than expected for the visible content, the bottleneck is structural — note this and continue.

Step 3 (15–30 min) — Capture baseline numbers

Control-level baseline (low noise, single-control or small composition):

dotnet build tools/performances/AtomUI.Performance/AtomUI.Performance.csproj -c Debug --framework net10.0

dotnet run --project tools/performances/AtomUI.Performance/AtomUI.Performance.csproj \
  -c Debug --framework net10.0 --no-build -- \
  --suite <control-key> --count 60 \
  --markdown /tmp/<control>-control-baseline.md

Find <control-key> in tools/performances/README.md ("当前命令" 节), or look under tools/performances/AtomUI.Performance/Suites/<Control>/ for an existing suite. If none exists, create the smallest representative suite first; building it is part of the work, not a precondition that blocks measurement.

State / lifecycle verification, when the control has it:

dotnet run --project tools/performances/AtomUI.Performance/AtomUI.Performance.csproj \
  -c Debug --framework net10.0 --no-build -- \
  --verify-<control>-states

Gallery-level baseline (real ShowCase, includes page-level fixed costs):

dotnet build tools/performances/AtomUI.GalleryPerformance/AtomUI.GalleryPerformance.csproj -c Debug --framework net10.0

dotnet run --project tools/performances/AtomUI.GalleryPerformance/AtomUI.GalleryPerformance.csproj \
  -c Debug --framework net10.0 --no-build -- \
  --showcase <showcase-key> --label baseline \
  --cold-iterations 10 --iterations 30 --warmup 5 --timeout-ms 30000 \
  --markdown /tmp/<control>-showcase-baseline.md

Sample policy: --cold-iterations 10 is the minimum for cold-first-navigation conclusions. Single-process samples are smoke-only and may NOT be reported as proof of improvement. Same --warmup/--iterations/--cold-iterations before and after, no exceptions.

Allocation / GC observation while interacting (optional, runs against the live Gallery process):

dotnet-counters monitor -p <gallery-pid> --counters System.Runtime

Watch gen-0/1/2-gc-count, alloc-rate, gc-heap-size. An allocation drop without a time drop is still a win, but only if you can name which allocations were removed.