Atomui Control Optimization

AtomUI Control Optimization

Overview

This is the entry skill for AtomUI control work. Its job is to classify the change, lock down public contracts, route to narrower skills when needed, and keep control optimization from mixing unrelated API, behavior, lifecycle, performance, and layout changes.

Required Reading

Before touching control code, read:

• docs/engineering/development/control-development-guidelines.md
• docs/engineering/contributing/agent-guidelines.md

For API contract optimization, member layout, method reordering, or file splitting, also read:

• references/api-layout-and-splitting.md

For messy implementation, repeated edge-case bugs, unclear state ownership, or architecture-level control redesign, also read:

• references/deep-control-optimization.md

Route First

Classify the request before editing.

For broad optimization requests, routing is a blocking gate. Requests phrased as "重新优化", "整体优化", "代码比较乱", "按照控件优化 skill 优化", "评估整体正确性", or similar must not go directly to code edits. First perform an optimization audit and report findings, phase plan, contract impact, and residual risks. Only skip the audit when the user names one narrow bug or one narrow mechanical edit.

Mandatory Audit Gate

Before editing a control for broad optimization, write a short audit in the working notes or user-facing plan. The audit must answer:

Optimization request type: broad / narrow
Control:
Primary responsibilities:
State owners:
Lifecycle acquire/release pairs:
Data/selection/key flows:
Template parts and generated containers:
Existing tests / missing regression:
Dead or duplicate implementation scan:
Potential API/behavior/render changes:
Recommended phases:
What will not be changed in this pass:

If the audit finds no issues beyond member order, say that explicitly. If it finds behavior risks, do not hide them behind "cleanup"; classify them as edge-case correctness or architecture root fix and add tests before changing behavior.

Hard Boundaries

• Without explicit user approval, do not change control API, behavior, or rendered result. This is a blocking constraint, not a preference.
• Control API includes public/protected members, Avalonia properties/events, template parts, token names, resource keys, pseudo-classes, and documented or Gallery-exposed usage.
• Behavior includes default values, binding priority, event timing, state transitions, focus/keyboard/pointer interaction, popup lifecycle, validation, async/data loading, and observable side effects.
• Rendered result includes visual tree semantics, layout size, spacing, alignment, colors, typography, animations, theme response, pseudo-class visuals, and template selector behavior.
• Control optimization must not introduce logic bugs, performance regressions, or resource leaks. If a proposed optimization cannot preserve correctness, performance, and lifecycle safety, stop and redesign before editing.
• Fix root causes instead of patching trigger points. Do not use flag variables, delayed refreshes, forced sync, or suppression paths to hide broken state flow; patch-style fixes make controls harder to maintain and are a blocker unless explicitly justified as a deterministic state machine.
• Do not introduce unnecessary classes, helpers, abstractions, boolean-switch parameters, marker fields, or local marker variables while fixing a control. Every new artifact must have durable ownership and a reason beyond making the current patch convenient.
• If investigation or review finds an unnecessary class, duplicate helper, speculative abstraction, patch flag, or stale artifact introduced by the current change, remove it before reporting completion. Do not leave it as harmless cleanup for later.
• Prefer existing shared primitives and comparable-control implementations over one-off private classes. A private class is allowed only when no existing primitive expresses the behavior correctly and the class removes real duplication or clarifies a stable responsibility.
• Do not mix pure member reordering with behavior fixes. If a bug is found during reordering, split it into a behavior fix with tests.
• Member layout cleanup must preserve the control contract as the first reading path. Do not place internal collaboration members, internal const, internal static helpers, private helpers, runtime fields, or patch artifacts before the public contract region inside a control class.
• Do not split files just because a file looks long. Under about 2000 lines, prefer method order, regions, and private helper extraction.
• Do not treat the 2000 line threshold as an automatic split rule. Even after the threshold is crossed, split only when the control has real, stable responsibility boundaries.
• Do not scatter a control into many small partial files. Public API contracts must remain in the main control file.
• Do not move lifecycle entry points out of the main control file unless the control is already deliberately partial and the entry remains easy to find.
• Do not introduce performance-oriented dynamic C# visual creation unless atomui-control-performance allows it.
• AXAML-first binding is a hard boundary. For template-owned visual state, template part state, style state, and fixed control-to-template relationships, use AXAML binding, TemplateBinding, style selectors, or existing theme/resource mechanisms before considering C# binding.
• BindUtils.RelayBind is the last binding creation mechanism, not the default convenience API. Before adding or keeping it, prove why the same relationship cannot be expressed in AXAML without changing API, behavior, rendered result, binding mode, binding priority, or template contract.
• Allowed BindUtils.RelayBind cases are limited to relationships AXAML cannot naturally express, such as dynamically created runtime targets, sibling/template-part coordination that cannot be represented by TemplateBinding or selectors, runtime-selected source objects, or bindings whose lifecycle is owned by a non-template runtime object.
• Every accepted BindUtils.RelayBind must have an explicit release path matching its acquisition path, such as re-template cleanup, detach, owner disposal, popup/content clear, or container recycle. Do not create relay bindings without a matching dispose owner.
• Do not use BindUtils.RelayBind to work around inconvenient AXAML. If the binding source and target are both stable parts of the control template, move the relationship into AXAML unless doing so would require an approved contract or behavior change.
• Do not report broad control optimization as complete after only member reordering. If deeper risks are found but not fixed in the current pass, report them as residual risks or propose a phased follow-up.