diff --git a/docs/superpowers/plans/2026-07-15-theme-system-redesign.md b/docs/superpowers/plans/2026-07-15-theme-system-redesign.md
new file mode 100644
index 000000000..bdcdff500
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-15-theme-system-redesign.md
@@ -0,0 +1,1110 @@
+# AtomUI Theme System Redesign Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox syntax for tracking.
+
+**Goal:** Rebuild AtomUI theme parsing, compilation, activation, local inheritance, component-token isolation, and event delivery around immutable theme snapshots while preserving existing Token values and Avalonia ControlTheme contracts.
+
+**Architecture:** A pure ThemeDefinitionParser feeds a cached ThemeCatalog; one ThemeCompiler produces logically immutable ThemeSnapshot objects for both global and local themes. ThemeTokenResourceProvider exposes snapshots through Avalonia DynamicResource, component-shared resource keys implement Ant Design component isolation, and ThemeCoordinator serializes atomic global transitions.
+
+**Tech Stack:** C# 12, .NET 8 and .NET 10, Avalonia 12 ResourceProvider, DynamicResource and StyledProperty, XDocument, xUnit v3, Shouldly, Roslyn incremental generators, NativeAOT.
+
+## Global Constraints
+
+- Preserve existing Seed, Map, Alias, ControlToken values and Default, Dark and Compact calculator behavior.
+- Preserve existing ControlTheme keys, template parts, public Token names, and AXAML collection syntax.
+- ThemeConfigProvider.Inherit defaults to true and follows Ant Design parent merge semantics.
+- Component Design Token overrides affect only the target component style computation, never arbitrary Content descendants.
+- Do not add string-based runtime Binding, runtime assembly scanning, unannotated reflection, or a new dependency package.
+- Treat every published ThemeSnapshot as immutable; failed work must not mutate active state.
+- Each ThemeConfigProvider owns exactly one ThemeTokenResourceProvider.
+- All global transitions execute on Dispatcher.UIThread, are non-reentrant, and emit events only after commit.
+- Keep the legacy ScopeHost and lifecycle events only as migration adapters.
+- Do not touch unrelated dirty WindowTitleBar files.
+
+---
+
+## Planned File Structure
+
+### New Core Units
+
+- src/AtomUI.Core/Theme/Definitions/ThemeDefinitionDiagnostic.cs: structured parser and compiler diagnostics.
+- src/AtomUI.Core/Theme/Definitions/ThemeDefinitionParseResult.cs: immutable parse result.
+- src/AtomUI.Core/Theme/Definitions/ThemeDefinitionParser.cs: pure XML parser.
+- src/AtomUI.Core/Theme/Compilation/ThemeCompileRequest.cs: normalized compiler input.
+- src/AtomUI.Core/Theme/Compilation/ThemeCompileResult.cs: snapshot or diagnostics.
+- src/AtomUI.Core/Theme/Compilation/ThemeSnapshot.cs: effective global Token and resource snapshot.
+- src/AtomUI.Core/Theme/Compilation/ComponentThemeSnapshot.cs: effective component shared and own Token snapshot.
+- src/AtomUI.Core/Theme/Compilation/ThemeCompiler.cs: sole Seed, Map, Alias and component compiler.
+- src/AtomUI.Core/Theme/Catalog/ThemeDescriptor.cs: one parsed theme definition.
+- src/AtomUI.Core/Theme/Catalog/ThemeCatalog.cs: discovery, precedence, diagnostics and parse-once behavior.
+- src/AtomUI.Core/Theme/Resources/ComponentTokenIdentity.cs: catalog-aware component identity.
+- src/AtomUI.Core/Theme/Resources/ComponentSharedTokenResourceKey.cs: component-private shared Token key.
+- src/AtomUI.Core/Theme/Resources/ComponentSharedTokenResourceExtension.cs: DynamicResource markup base.
+- src/AtomUI.Core/Theme/Resources/ThemeTokenResourceProvider.cs: snapshot-backed ResourceProvider.
+- src/AtomUI.Core/Theme/Scope/ThemeScope.cs: scoped snapshot property and lookup.
+- src/AtomUI.Core/Theme/Transitions/ThemeRequest.cs: complete desired global theme.
+- src/AtomUI.Core/Theme/Transitions/ThemeTransitionEventArgs.cs: transition context.
+- src/AtomUI.Core/Theme/Transitions/ThemeCoordinator.cs: prepare and commit state machine.
+
+### New Test Project
+
+- tests/AtomUI.Core.Tests/AtomUI.Core.Tests.csproj
+- tests/AtomUI.Core.Tests/Theme/ThemeDefinitionParserTests.cs
+- tests/AtomUI.Core.Tests/Theme/TokenValueConverterTests.cs
+- tests/AtomUI.Core.Tests/Theme/ThemeCompilerTests.cs
+- tests/AtomUI.Core.Tests/Theme/ThemeCatalogTests.cs
+- tests/AtomUI.Core.Tests/Theme/ThemeTokenResourceProviderTests.cs
+- tests/AtomUI.Core.Tests/Theme/ThemeConfigProviderTests.cs
+- tests/AtomUI.Core.Tests/Theme/ThemeCoordinatorTests.cs
+- tests/AtomUI.Core.Tests/Theme/ThemeSnapshotCacheTests.cs
+
+---
+
+### Task 1: Establish AtomUI.Core Theme Test Ownership
+
+**Files:**
+- Create: tests/AtomUI.Core.Tests/AtomUI.Core.Tests.csproj
+- Create: tests/AtomUI.Core.Tests/Theme/DesignTokenBaselineTests.cs
+- Modify: src/AtomUI.Core/AtomUI.Core.csproj
+- Modify: AtomUI.slnx
+
+**Interfaces:**
+- Consumes: existing DesignToken and DefaultThemeVariantCalculator.
+- Produces: an AtomUI.Core.Tests assembly with access to AtomUI.Core internals.
+
+- [ ] **Step 1: Add the test project and internals access**
+
+~~~xml
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <IsPackable>false</IsPackable>
+    <RootNamespace>AtomUI.Core.Tests</RootNamespace>
+  </PropertyGroup>
+  <ItemGroup>
+    <PackageReference Include="Microsoft.NET.Test.Sdk" />
+    <PackageReference Include="Shouldly" />
+    <PackageReference Include="xunit.v3" />
+    <PackageReference Include="xunit.runner.visualstudio" PrivateAssets="all" />
+  </ItemGroup>
+  <ItemGroup>
+    <ProjectReference Include="../../src/AtomUI.Core/AtomUI.Core.csproj" />
+  </ItemGroup>
+</Project>
+~~~
+
+Add InternalsVisibleTo for AtomUI.Core.Tests and add the project to AtomUI.slnx.
+
+- [ ] **Step 2: Lock current default derivation**
+
+~~~csharp
+[Fact]
+public void DefaultCalculator_Derives_Stable_Primary_And_Control_Size_Tokens()
+{
+    var token = new DesignToken();
+    var calculator = new DefaultThemeVariantCalculator();
+
+    calculator.Calculate(token);
+    token.CalculateAliasTokenValues();
+
+    token.ColorPrimary.ShouldBe(Color.Parse("#1677ff"));
+    token.ControlHeight.ShouldBe(32);
+    token.BorderRadius.ShouldBe(new CornerRadius(6));
+}
+~~~
+
+- [ ] **Step 3: Run the new project**
+
+Run: dotnet test tests/AtomUI.Core.Tests/AtomUI.Core.Tests.csproj --framework net10.0 --no-restore
+
+Expected: PASS with one test and zero failures.
+
+- [ ] **Step 4: Commit**
+
+~~~bash
+git add AtomUI.slnx src/AtomUI.Core/AtomUI.Core.csproj tests/AtomUI.Core.Tests
+git commit -m "test(Theme): add core theme test project"
+~~~
+
+### Task 2: Replace the Cursor-Based XML Reader with a Pure Parser
+
+**Files:**
+- Create: src/AtomUI.Core/Theme/Definitions/ThemeDefinitionDiagnostic.cs
+- Create: src/AtomUI.Core/Theme/Definitions/ThemeDefinitionParseResult.cs
+- Create: src/AtomUI.Core/Theme/Definitions/ThemeDefinitionParser.cs
+- Modify: src/AtomUI.Core/Theme/ThemeDefinition.cs
+- Test: tests/AtomUI.Core.Tests/Theme/ThemeDefinitionParserTests.cs
+
+**Interfaces:**
+- Consumes: ThemeDefinitionParseRequest containing a Stream, file path, shared Token schema and registered component schema.
+- Produces: ThemeDefinitionParseResult ThemeDefinitionParser.Parse(ThemeDefinitionParseRequest request).
+
+- [ ] **Step 1: Write whitespace-independent parser tests**
+
+~~~csharp
+[Theory]
+[InlineData("<Theme Name='T' IsDefault='true'><Algorithms>Default,Dark</Algorithms><SharedTokens><Token Name='ColorPrimary' Value='#ff0000'/></SharedTokens><ControlTokens/></Theme>")]
+[InlineData("""
+<Theme Name="T" IsDefault="true">
+  <Algorithms>Default, Dark</Algorithms>
+  <SharedTokens>
+    <Token Name="ColorPrimary">#ff0000</Token>
+  </SharedTokens>
+  <ControlTokens />
+</Theme>
+""")]
+public void Parse_Is_Independent_Of_Formatting(string xml)
+{
+    var result = Parse(xml);
+
+    result.Success.ShouldBeTrue();
+    result.Definition!.Algorithms.ShouldBe(
+        [ThemeAlgorithm.Default, ThemeAlgorithm.Dark]);
+    result.Definition.SharedTokens["ColorPrimary"].ShouldBe("#ff0000");
+}
+~~~
+
+Add focused tests for body-valued IsShared, self-closing containers, duplicate keys, missing root, invalid bool, unknown algorithm, unknown global Token, known component with an unknown property, optional unregistered component warning, and line and column diagnostics.
+
+- [ ] **Step 2: Verify the new tests fail**
+
+Run: dotnet test tests/AtomUI.Core.Tests/AtomUI.Core.Tests.csproj --framework net10.0 --no-restore --filter FullyQualifiedName~ThemeDefinitionParserTests
+
+Expected: FAIL because the parser contracts do not exist.
+
+- [ ] **Step 3: Add immutable diagnostic contracts**
+
+~~~csharp
+internal enum ThemeDiagnosticSeverity
+{
+    Warning,
+    Error
+}
+
+internal sealed record ThemeDefinitionDiagnostic(
+    string Code,
+    ThemeDiagnosticSeverity Severity,
+    string FilePath,
+    int Line,
+    int Column,
+    string Path,
+    string Message);
+
+internal sealed record ThemeDefinitionParseResult(
+    ThemeDefinition? Definition,
+    IReadOnlyList<ThemeDefinitionDiagnostic> Diagnostics)
+{
+    public bool Success =>
+        Definition is not null &&
+        Diagnostics.All(x => x.Severity != ThemeDiagnosticSeverity.Error);
+}
+~~~
+
+Make ThemeDefinition constructor-only and expose ordered algorithms plus copied read-only dictionaries.
+
+- [ ] **Step 4: Implement secured XDocument parsing**
+
+~~~csharp
+var settings = new XmlReaderSettings
+{
+    CloseInput = false,
+    DtdProcessing = DtdProcessing.Prohibit,
+    XmlResolver = null
+};
+
+using var reader = XmlReader.Create(request.Stream, settings, request.FilePath);
+var document = XDocument.Load(reader, LoadOptions.SetLineInfo);
+~~~
+
+Read attributes before content. Require exactly one Token value source. Convert every structural failure into stable diagnostics ATMTHM001 through ATMTHM010.
+
+- [ ] **Step 5: Run all Core tests**
+
+Run: dotnet test tests/AtomUI.Core.Tests/AtomUI.Core.Tests.csproj --framework net10.0 --no-restore
+
+Expected: PASS.
+
+- [ ] **Step 6: Commit without deleting the legacy reader**
+
+~~~bash
+git add src/AtomUI.Core/Theme/Definitions src/AtomUI.Core/Theme/ThemeDefinition.cs tests/AtomUI.Core.Tests/Theme
+git commit -m "refactor(Theme): add deterministic theme definition parser"
+~~~
+
+### Task 3: Make Token Conversion Deterministic
+
+**Files:**
+- Modify: src/AtomUI.Core/Theme/TokenSystem/BuiltInTokenValueConverters.cs
+- Modify: src/AtomUI.Core/Theme/TokenSystem/AbstractDesignToken.cs
+- Test: tests/AtomUI.Core.Tests/Theme/TokenValueConverterTests.cs
+
+**Interfaces:**
+- Consumes: string Token values.
+- Produces: invariant typed values and cache-consistent LoadConfig behavior.
+
+- [ ] **Step 1: Write culture and cache tests**
+
+~~~csharp
+[Theory]
+[InlineData("fr-FR")]
+[InlineData("zh-CN")]
+[InlineData("en-US")]
+public void Double_Conversion_Uses_Invariant_Culture(string cultureName)
+{
+    using var culture = new CultureScope(cultureName);
+    new DoubleTokenValueConverter().Convert("1.5").ShouldBe(1.5d);
+}
+
+[Fact]
+public void LoadConfig_Invalidates_Previously_Read_Token_Value()
+{
+    var token = new DesignToken();
+    token.GetTokenValue(nameof(DesignToken.BorderRadius));
+
+    token.LoadConfig(new Dictionary<string, string>
+    {
+        [nameof(DesignToken.BorderRadius)] = "12"
+    });
+
+    token.GetTokenValue(nameof(DesignToken.BorderRadius))
+         .ShouldBe(new CornerRadius(12));
+}
+~~~
+
+- [ ] **Step 2: Verify failures under fr-FR and cached access**
+
+Run: dotnet test tests/AtomUI.Core.Tests/AtomUI.Core.Tests.csproj --framework net10.0 --no-restore --filter FullyQualifiedName~TokenValueConverterTests
+
+Expected: the decimal and cache tests fail.
+
+- [ ] **Step 3: Implement invariant conversion and invalidation**
+
+Use NumberStyles.Integer or NumberStyles.Float with CultureInfo.InvariantCulture. Remove each assigned Token name from the access cache before setting the property. Include Token name, target type and raw value in conversion errors.
+
+- [ ] **Step 4: Run and commit**
+
+Run: dotnet test tests/AtomUI.Core.Tests/AtomUI.Core.Tests.csproj --framework net10.0 --no-restore
+
+Expected: PASS.
+
+~~~bash
+git add src/AtomUI.Core/Theme/TokenSystem tests/AtomUI.Core.Tests/Theme/TokenValueConverterTests.cs
+git commit -m "fix(Theme): make token conversion deterministic"
+~~~
+
+### Task 4: Introduce ThemeSnapshot and the Single ThemeCompiler
+
+**Files:**
+- Create: src/AtomUI.Core/Theme/Resources/ComponentTokenIdentity.cs
+- Create: src/AtomUI.Core/Theme/Compilation/ThemeCompileRequest.cs
+- Create: src/AtomUI.Core/Theme/Compilation/ThemeCompileResult.cs
+- Create: src/AtomUI.Core/Theme/Compilation/ThemeSnapshot.cs
+- Create: src/AtomUI.Core/Theme/Compilation/ComponentThemeSnapshot.cs
+- Create: src/AtomUI.Core/Theme/Compilation/ThemeCompiler.cs
+- Modify: src/AtomUI.Core/Theme/ControlTokenRegistration.cs
+- Test: tests/AtomUI.Core.Tests/Theme/ThemeCompilerTests.cs
+
+**Interfaces:**
+- Consumes: ThemeCompileRequest with definition, parent, algorithms, overrides, runtime overrides and registrations.
+- Produces: ThemeCompileResult with one complete ThemeSnapshot or diagnostics and exception.
+
+- [ ] **Step 1: Write global and component compiler tests**
+
+~~~csharp
+[Fact]
+public void Component_Algorithm_False_Does_Not_Derive_Map_Tokens()
+{
+    var result = Compile(component: Component(
+        "Button",
+        algorithm: false,
+        shared: Token("ColorPrimary", "#00b96b")));
+
+    var button = result.Snapshot!.Components[Identity("Button")];
+
+    button.EffectiveSharedToken.ColorPrimary
+          .ShouldBe(Color.Parse("#00b96b"));
+    button.EffectiveSharedToken.ColorPrimaryHover
+          .ShouldBe(result.Snapshot.SharedToken.ColorPrimaryHover);
+}
+
+[Fact]
+public void Component_Algorithm_True_Derives_Private_Map_Tokens()
+{
+    var result = Compile(component: Component(
+        "Button",
+        algorithm: true,
+        shared: Token("ColorPrimary", "#00b96b")));
+
+    var button = result.Snapshot!.Components[Identity("Button")];
+
+    button.EffectiveSharedToken.ColorPrimary
+          .ShouldBe(Color.Parse("#00b96b"));
+    button.EffectiveSharedToken.ColorPrimaryHover
+          .ShouldNotBe(result.Snapshot.SharedToken.ColorPrimaryHover);
+}
+~~~
+
+Also test ordered Dark and Compact composition, parent immutability, Map and Alias override order, component own Token override, unknown registration diagnostics, and failure without a partial snapshot.
+
+- [ ] **Step 2: Verify missing-type failures**
+
+Run: dotnet test tests/AtomUI.Core.Tests/AtomUI.Core.Tests.csproj --framework net10.0 --no-restore --filter FullyQualifiedName~ThemeCompilerTests
+
+Expected: FAIL.
+
+- [ ] **Step 3: Add compiler contracts**
+
+~~~csharp
+internal sealed record ThemeCompileRequest(
+    string ThemeId,
+    ThemeDefinition Definition,
+    ThemeSnapshot? Parent,
+    IReadOnlyList<ThemeAlgorithm> Algorithms,
+    IReadOnlyDictionary<string, string> SharedOverrides,
+    IReadOnlyDictionary<ComponentTokenIdentity, ControlTokenConfigInfo> ComponentOverrides,
+    IReadOnlyList<ControlTokenRegistration> Registrations,
+    IReadOnlyDictionary<string, string> RuntimeOverrides);
+
+internal sealed record ThemeCompileResult(
+    ThemeSnapshot? Snapshot,
+    IReadOnlyList<ThemeDefinitionDiagnostic> Diagnostics,
+    Exception? Exception)
+{
+    public bool Success => Snapshot is not null && Exception is null;
+}
+~~~
+
+- [ ] **Step 4: Extract one deterministic compile pipeline**
+
+Create a fresh DesignToken and fresh ControlToken graph for every uncached compile. Apply Seed, algorithms, Map, Alias and component calculations in the order fixed by the design. Build resource maps off-side. Publish only when every component succeeds.
+
+Do not change Theme or ThemeConfigProvider yet.
+
+- [ ] **Step 5: Run compiler tests twice**
+
+Run the compiler-filtered test command twice. Expected: both runs PASS with identical results.
+
+- [ ] **Step 6: Commit**
+
+~~~bash
+git add src/AtomUI.Core/Theme/Compilation src/AtomUI.Core/Theme/ControlTokenRegistration.cs tests/AtomUI.Core.Tests/Theme/ThemeCompilerTests.cs
+git commit -m "refactor(Theme): centralize token compilation in snapshots"
+~~~
+
+### Task 5: Parse Definitions Once Through ThemeCatalog
+
+**Files:**
+- Create: src/AtomUI.Core/Theme/Catalog/ThemeDescriptor.cs
+- Create: src/AtomUI.Core/Theme/Catalog/ThemeCatalog.cs
+- Modify: src/AtomUI.Core/Theme/ThemeManager.cs
+- Modify: src/AtomUI.Core/Theme/Theme.cs
+- Remove: src/AtomUI.Core/Theme/ThemeDefinitionReader.cs
+- Test: tests/AtomUI.Core.Tests/Theme/ThemeCatalogTests.cs
+
+**Interfaces:**
+- Consumes: ordered theme sources, parser and registered Token schema.
+- Produces: one ThemeDescriptor per theme id and compile requests for variants.
+
+- [ ] **Step 1: Write precedence and parse-once tests**
+
+~~~csharp
+[Fact]
+public void Catalog_Parses_One_File_Once_For_All_Variants()
+{
+    var source = new CountingThemeSource("Brand.xml", ValidThemeXml);
+    var catalog = CreateCatalog(source);
+
+    catalog.GetDescriptor("Brand").ShouldNotBeNull();
+    catalog.CreateCompileRequest(
+        "Brand",
+        [ThemeAlgorithm.Default]);
+    catalog.CreateCompileRequest(
+        "Brand",
+        [ThemeAlgorithm.Default, ThemeAlgorithm.Dark]);
+
+    source.OpenCount.ShouldBe(1);
+}
+~~~
+
+Add tests for custom precedence, duplicate id diagnostics, explicit builder default, IsDefault fallback, unavailable invalid custom theme, and fatal invalid built-in default.
+
+- [ ] **Step 2: Verify failure**
+
+Run: dotnet test tests/AtomUI.Core.Tests/AtomUI.Core.Tests.csproj --framework net10.0 --no-restore --filter FullyQualifiedName~ThemeCatalogTests
+
+Expected: FAIL.
+
+- [ ] **Step 3: Implement ThemeDescriptor and ThemeCatalog**
+
+~~~csharp
+internal sealed record ThemeDescriptor(
+    string Id,
+    string DefinitionFilePath,
+    bool IsBuiltIn,
+    int SourcePriority,
+    ThemeDefinition? Definition,
+    IReadOnlyList<ThemeDefinitionDiagnostic> Diagnostics)
+{
+    public bool IsAvailable =>
+        Definition is not null &&
+        Diagnostics.All(x => x.Severity != ThemeDiagnosticSeverity.Error);
+}
+~~~
+
+Sort paths ordinally. Record duplicates instead of silently continuing.
+
+- [ ] **Step 4: Adapt Theme as a compatibility facade**
+
+Theme receives a descriptor, asks ThemeCompiler for a snapshot through ThemeCatalog, and keeps the current activation facade temporarily. It no longer opens a file or owns Seed, Map, Alias, or component compile loops. Delete ThemeDefinitionReader only after the following search returns no consumers:
+
+Run: rg "ThemeDefinitionReader" src tests
+
+Expected before deletion: only the reader definition remains.
+
+- [ ] **Step 5: Run Core and initial-mode tests**
+
+Run:
+- dotnet test tests/AtomUI.Core.Tests/AtomUI.Core.Tests.csproj --framework net10.0 --no-restore
+- dotnet test tests/AtomUI.Desktop.Controls.Tests/AtomUI.Desktop.Controls.Tests.csproj --framework net10.0 --no-restore --filter FullyQualifiedName~ThemeInitialModeTests
+
+Expected: both PASS.
+
+- [ ] **Step 6: Commit**
+
+~~~bash
+git add src/AtomUI.Core/Theme/Catalog src/AtomUI.Core/Theme/Theme.cs src/AtomUI.Core/Theme/ThemeManager.cs src/AtomUI.Core/Theme/ThemeDefinitionReader.cs tests/AtomUI.Core.Tests/Theme/ThemeCatalogTests.cs
+git commit -m "refactor(Theme): parse and catalog definitions once"
+~~~
+
+### Task 6: Add Snapshot-Backed ResourceProvider and Component Keys
+
+**Files:**
+- Modify: src/AtomUI.Core/Theme/Resources/ComponentTokenIdentity.cs
+- Create: src/AtomUI.Core/Theme/Resources/ComponentSharedTokenResourceKey.cs
+- Create: src/AtomUI.Core/Theme/Resources/ComponentSharedTokenResourceExtension.cs
+- Create: src/AtomUI.Core/Theme/Resources/ThemeTokenResourceProvider.cs
+- Modify: src/AtomUI.Core/Theme/Compilation/ThemeSnapshot.cs
+- Modify: src/AtomUI.Core/Theme/Compilation/ComponentThemeSnapshot.cs
+- Modify: src/AtomUI.Core/Theme/Theme.cs
+- Test: tests/AtomUI.Core.Tests/Theme/ThemeTokenResourceProviderTests.cs
+
+**Interfaces:**
+- Consumes: ThemeSnapshot.
+- Produces: ResourceProvider resolving global, component-private shared, and component own Token keys.
+
+- [ ] **Step 1: Write lookup and notification tests**
+
+~~~csharp
+[Fact]
+public void ComponentShared_Key_Resolves_Private_Value_Without_Changing_Global()
+{
+    var snapshot = CompileButtonPrimary("#00b96b");
+    var provider = new ThemeTokenResourceProvider(snapshot);
+
+    provider.TryGetResource(
+        SharedTokenKind.ColorPrimary,
+        null,
+        out var global).ShouldBeTrue();
+
+    provider.TryGetResource(
+        new ComponentSharedTokenResourceKey(
+            null,
+            "Button",
+            SharedTokenKind.ColorPrimary),
+        null,
+        out var component).ShouldBeTrue();
+
+    component.ShouldNotBe(global);
+}
+~~~
+
+Also test unknown ids, registered unconfigured fallback to scope-global values, catalog identity, owner attachment, silent prepare followed by one publish notification, and normal ReplaceSnapshot notification.
+
+- [ ] **Step 2: Verify failure**
+
+Run: dotnet test tests/AtomUI.Core.Tests/AtomUI.Core.Tests.csproj --framework net10.0 --no-restore --filter FullyQualifiedName~ThemeTokenResourceProviderTests
+
+Expected: FAIL.
+
+- [ ] **Step 3: Implement stable identities and cached keys**
+
+~~~csharp
+public readonly record struct ComponentSharedTokenResourceKey(
+    string? Catalog,
+    string ComponentId,
+    SharedTokenKind Kind);
+~~~
+
+Normalize empty Catalog to null. Cache keys by ComponentTokenIdentity and SharedTokenKind. ComponentTokenIdentity is an internal compiler value; generated public extensions pass catalog and id strings to their public base constructor.
+
+- [ ] **Step 4: Implement ThemeTokenResourceProvider**
+
+Subclass Avalonia ResourceProvider. Resolve prebuilt maps without reflection. Provide PrepareSnapshot for a transaction owner to swap the reference silently and PublishSnapshotChanged to raise exactly one notification after the surrounding scope state is consistent. ReplaceSnapshot combines those two operations for simple callers. Mount one provider in every compatibility Theme resource layer so old ThemeManager activation can resolve component keys before ThemeCoordinator lands.
+
+- [ ] **Step 5: Run provider and compiler tests**
+
+Run: dotnet test tests/AtomUI.Core.Tests/AtomUI.Core.Tests.csproj --framework net10.0 --no-restore --filter "FullyQualifiedName~ThemeTokenResourceProviderTests|FullyQualifiedName~ThemeCompilerTests"
+
+Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+~~~bash
+git add src/AtomUI.Core/Theme/Resources src/AtomUI.Core/Theme/Compilation tests/AtomUI.Core.Tests/Theme/ThemeTokenResourceProviderTests.cs
+git commit -m "feat(Theme): add snapshot token resource provider"
+~~~
+
+### Task 7: Generate Strongly Typed Component-Shared Extensions
+
+**Files:**
+- Modify: src/AtomUI.Generator/DesignToken/TokenInfo.cs
+- Modify: src/AtomUI.Generator/DesignToken/ControlTokenPropertyWalker.cs
+- Modify: src/AtomUI.Generator/DesignToken/ResourceKeyClassWriter.cs
+- Modify: src/AtomUI.Generator/DesignToken/ControlTokenTypePoolClassWriter.cs
+- Modify: src/AtomUI.Core/Theme/ControlTokenRegistration.cs
+- Test: tests/AtomUI.Generator.Tests/TokenResourceKeyGeneratorTests.cs
+
+**Interfaces:**
+- Consumes: ControlDesignToken class with public const string ID.
+- Produces: registration identity and ControlNameSharedTokenResourceExtension.
+
+- [ ] **Step 1: Add generator output tests**
+
+Input:
+
+~~~csharp
+[ControlDesignToken]
+internal sealed class ButtonToken : AbstractControlDesignToken
+{
+    public const string ID = "Button";
+    public ButtonToken() : base(ID) { }
+    public double Height { get; set; }
+}
+~~~
+
+Expected generated API:
+
+~~~csharp
+public sealed class ButtonTokenSharedTokenResourceExtension
+    : ComponentSharedTokenResourceExtension
+{
+    public ButtonTokenSharedTokenResourceExtension(SharedTokenKind kind)
+        : base(null, "Button", kind)
+    {
+    }
+}
+~~~
+
+Also assert a generator diagnostic when ID is missing or non-constant.
+
+- [ ] **Step 2: Verify generator failure**
+
+Run: dotnet test tests/AtomUI.Generator.Tests/AtomUI.Generator.Tests.csproj --framework net10.0 --no-restore --filter FullyQualifiedName~TokenResourceKeyGeneratorTests
+
+Expected: FAIL.
+
+- [ ] **Step 3: Extend generator metadata**
+
+Add ControlId, ResourceCatalog and generated TokenKind type to ControlTokenInfo. Emit ControlTokenRegistration with identity metadata rather than creating a Token instance to discover its id.
+
+- [ ] **Step 4: Emit component-shared markup extensions**
+
+Keep existing component own Token extensions. Emit one additional SharedTokenKind extension per registered ControlToken.
+
+- [ ] **Step 5: Verify generator and consumers**
+
+Run:
+- dotnet test tests/AtomUI.Generator.Tests/AtomUI.Generator.Tests.csproj --framework net10.0 --no-restore
+- dotnet build src/AtomUI.Desktop.Controls/AtomUI.Desktop.Controls.csproj --framework net10.0 --no-restore
+
+Expected: PASS and successful build.
+
+- [ ] **Step 6: Commit**
+
+~~~bash
+git add src/AtomUI.Generator src/AtomUI.Core/Theme/ControlTokenRegistration.cs tests/AtomUI.Generator.Tests
+git commit -m "feat(Generator): emit component shared token resources"
+~~~
+
+### Task 8: Rebuild ThemeConfigProvider as an Inheriting Snapshot Scope
+
+**Files:**
+- Create: src/AtomUI.Core/Theme/Scope/ThemeScope.cs
+- Modify: src/AtomUI.Core/Theme/ThemeConfigProvider.cs
+- Modify: src/AtomUI.Core/Theme/IThemeConfigProvider.cs
+- Modify: src/AtomUI.Core/Theme/TokenSetter.cs
+- Modify: src/AtomUI.Core/Theme/ControlTokenInfoSetter.cs
+- Test: tests/AtomUI.Core.Tests/Theme/ThemeConfigProviderTests.cs
+
+**Interfaces:**
+- Consumes: inherited parent Snapshot, observable local config and ThemeCompiler.
+- Produces: one child Snapshot, one ResourceProvider, and inherited context on Content.
+
+- [ ] **Step 1: Write nested inheritance and update tests**
+
+~~~csharp
+[Fact]
+public void Child_Provider_Inherits_Unchanged_Parent_Tokens()
+{
+    var parent = Provider(
+        Token("ColorPrimary", "#ff0000"),
+        Token("BorderRadius", "12"));
+    var child = Provider(
+        Token("ColorPrimary", "#00b96b"));
+
+    parent.Content = child;
+    child.Content = new Border();
+    Attach(parent);
+
+    child.SharedToken.ColorPrimary
+         .ShouldBe(Color.Parse("#00b96b"));
+    child.SharedToken.BorderRadius
+         .ShouldBe(new CornerRadius(12));
+}
+~~~
+
+Add tests for Inherit false, parent updates, list add and remove, TokenSetter Value changes, algorithm changes, failed compile rollback, one merged provider after 20 updates, and Content replacement cleanup.
+
+- [ ] **Step 2: Verify current failures**
+
+Run: dotnet test tests/AtomUI.Core.Tests/AtomUI.Core.Tests.csproj --framework net10.0 --no-restore --filter FullyQualifiedName~ThemeConfigProviderTests
+
+Expected: failures for inheritance, change tracking, resource count and rollback.
+
+- [ ] **Step 3: Define ThemeScope and observable config**
+
+~~~csharp
+internal static class ThemeScope
+{
+    public static readonly AttachedProperty<ThemeSnapshot?> SnapshotProperty =
+        AvaloniaProperty.RegisterAttached<
+            ThemeConfigProvider,
+            StyledElement,
+            ThemeSnapshot?>(
+                "Snapshot",
+                inherits: true);
+}
+~~~
+
+Convert TokenSetter and ControlTokenInfoSetter to AvaloniaObject properties. Use AvaloniaList collections and add InheritProperty with default true while preserving AXAML content syntax.
+
+- [ ] **Step 4: Replace CalculateTokenResources with compile and commit**
+
+The provider inherits the parent Snapshot on itself and compiles a child Snapshot off-side. On success:
+
+1. replace the single ThemeTokenResourceProvider Snapshot without notification;
+2. set the same Snapshot on Content through ThemeScope;
+3. raise one ResourcesChanged notification;
+4. publish compatibility SharedToken and ControlTokens views.
+
+On failure, retain every previously published object and resource and raise ThemeScopeCompileFailed with diagnostics.
+
+- [ ] **Step 5: Coalesce runtime changes**
+
+Queue at most one Dispatcher.UIThread recompile per event-loop turn. Detach collection, item and parent handlers symmetrically on Content replacement and logical detach.
+
+- [ ] **Step 6: Verify compatibility**
+
+Run:
+- dotnet test tests/AtomUI.Core.Tests/AtomUI.Core.Tests.csproj --framework net10.0 --no-restore
+- dotnet test tests/AtomUI.Desktop.Controls.Tests/AtomUI.Desktop.Controls.Tests.csproj --framework net10.0 --no-restore --filter FullyQualifiedName~Button_Primary_Variant_Background_Follows_Scoped_ColorPrimary
+
+Expected: PASS.
+
+- [ ] **Step 7: Commit**
+
+~~~bash
+git add src/AtomUI.Core/Theme/Scope src/AtomUI.Core/Theme/ThemeConfigProvider.cs src/AtomUI.Core/Theme/IThemeConfigProvider.cs src/AtomUI.Core/Theme/TokenSetter.cs src/AtomUI.Core/Theme/ControlTokenInfoSetter.cs tests/AtomUI.Core.Tests/Theme/ThemeConfigProviderTests.cs
+git commit -m "refactor(Theme): make config provider inherit snapshots"
+~~~
+
+### Task 9: Prove Component Isolation with Button
+
+**Files:**
+- Modify: src/AtomUI.Desktop.Controls/Buttons/Themes/ButtonTheme.axaml
+- Modify: src/AtomUI.Desktop.Controls/Buttons/Button.cs
+- Modify: src/AtomUI.Desktop.Controls/Buttons/ButtonToken.cs
+- Test: tests/AtomUI.Desktop.Controls.Tests/Buttons/ButtonThemeScopeTests.cs
+
+**Interfaces:**
+- Consumes: ButtonTokenSharedTokenResourceExtension and scoped Snapshot.
+- Produces: first component with Ant Design isolation and no instance scope host.
+
+- [ ] **Step 1: Write component isolation tests**
+
+~~~csharp
+[Fact]
+public void Button_Component_ColorPrimary_Does_Not_Leak_To_Content()
+{
+    var content = new Border();
+    content[!Border.BackgroundProperty] =
+        new DynamicResourceExtension(SharedTokenKind.ColorPrimary);
+
+    var button = new Button { Content = content };
+    var provider = Provider(
+        component: Component(
+            "Button",
+            shared: Token("ColorPrimary", "#00b96b")),
+        content: button);
+
+    ShowInWindow(provider, () =>
+    {
+        BrushColor(button.Background)
+            .ShouldBe(Color.Parse("#00b96b"));
+        BrushColor(content.Background)
+            .ShouldBe(GlobalColorPrimary);
+    });
+}
+~~~
+
+Add tests for a nested Input using Input config, runtime Button component updates without reattach, and global theme switch refresh.
+
+- [ ] **Step 2: Verify leakage or staleness**
+
+Run: dotnet test tests/AtomUI.Desktop.Controls.Tests/AtomUI.Desktop.Controls.Tests.csproj --framework net10.0 --no-restore --filter FullyQualifiedName~ButtonThemeScopeTests
+
+Expected: current Host behavior fails at least one assertion.
+
+- [ ] **Step 3: Migrate ButtonTheme references**
+
+Replace component-semantic SharedTokenResource usages with the generated Button component-shared extension. Inventory every SharedTokenResourceValue separately: use a component-aware DynamicResource when the target is a StyledElement; for non-Visual transition or animation objects, project the Token onto an owning control property with an explicit lifecycle instead of attaching DynamicResource to the non-Visual object. Leave genuinely application-global non-design resources unchanged.
+
+- [ ] **Step 4: Remove Button instance scope registration**
+
+Remove RegisterTokenResourceScope from Button and remove ButtonToken.ScopeProvider. Keep shared Host infrastructure for unconverted controls.
+
+- [ ] **Step 5: Run all Button and scope tests**
+
+Run: dotnet test tests/AtomUI.Desktop.Controls.Tests/AtomUI.Desktop.Controls.Tests.csproj --framework net10.0 --no-restore --filter "FullyQualifiedName~Button|FullyQualifiedName~ThemeConfigProvider"
+
+Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+~~~bash
+git add src/AtomUI.Desktop.Controls/Buttons tests/AtomUI.Desktop.Controls.Tests/Buttons/ButtonThemeScopeTests.cs
+git commit -m "refactor(Button): isolate component theme tokens"
+~~~
+
+### Task 10: Replace Global Activation with ThemeCoordinator
+
+**Files:**
+- Create: src/AtomUI.Core/Theme/Transitions/ThemeRequest.cs
+- Create: src/AtomUI.Core/Theme/Transitions/ThemeTransitionEventArgs.cs
+- Create: src/AtomUI.Core/Theme/Transitions/ThemeCoordinator.cs
+- Modify: src/AtomUI.Core/Theme/ThemeManager.cs
+- Modify: src/AtomUI.Core/ApplicationExtensions.cs
+- Modify: src/AtomUI.Controls.Shared/ApplicationExtensions.cs
+- Modify: src/AtomUI.Desktop.Controls/Window/MediaBreakPointThemeBootstrapper.cs
+- Test: tests/AtomUI.Core.Tests/Theme/ThemeCoordinatorTests.cs
+
+**Interfaces:**
+- Consumes: ThemeRequest, Catalog, Compiler or cache, Application and the global resource layer.
+- Produces: serialized atomic transitions and committed events.
+
+- [ ] **Step 1: Write transition tests**
+
+~~~csharp
+[Fact]
+public void Dark_Compact_Startup_Commits_Exactly_Once()
+{
+    var coordinator = CreateCoordinator();
+    var changed = new List<ThemeTransitionEventArgs>();
+    coordinator.ThemeChanged += (_, args) => changed.Add(args);
+
+    coordinator.Request(new ThemeRequest(
+        "DaybreakBlue",
+        [
+            ThemeAlgorithm.Default,
+            ThemeAlgorithm.Dark,
+            ThemeAlgorithm.Compact
+        ],
+        ThemeTransitionReason.Startup));
+
+    changed.Count.ShouldBe(1);
+    changed[0].NewSnapshot.Algorithms.ShouldBe(
+        [
+            ThemeAlgorithm.Default,
+            ThemeAlgorithm.Dark,
+            ThemeAlgorithm.Compact
+        ]);
+}
+~~~
+
+Add tests for identical no-op requests, queued requests from Changed subscribers, parser and compiler failure rollback, observer exception isolation, and UI-thread verification.
+
+- [ ] **Step 2: Verify failure**
+
+Run: dotnet test tests/AtomUI.Core.Tests/AtomUI.Core.Tests.csproj --framework net10.0 --no-restore --filter FullyQualifiedName~ThemeCoordinatorTests
+
+Expected: FAIL.
+
+- [ ] **Step 3: Implement one request model and state machine**
+
+~~~csharp
+internal sealed record ThemeRequest(
+    string ThemeId,
+    IReadOnlyList<ThemeAlgorithm> Algorithms,
+    ThemeTransitionReason Reason,
+    IReadOnlyDictionary<string, string>? RuntimeOverrides = null);
+~~~
+
+Use Idle, Preparing and Committing states with a FIFO queue. Normalize and compare requests before prepare. Build the target Snapshot before touching Application or manager properties.
+
+- [ ] **Step 4: Implement guarded commit order**
+
+Commit in this order:
+
+1. prepare or replace the target global ResourceProvider;
+2. assign active Snapshot and derived manager state under a guard;
+3. set Application.RequestedThemeVariant;
+4. acknowledge the synchronous ActualThemeVariant callback without creating a request;
+5. raise Changed after all state and resources agree;
+6. drain the queued request.
+
+Observer failures are logged separately and never converted to ThemeChangeFailed.
+
+- [ ] **Step 5: Route public extensions through complete requests**
+
+SetDarkThemeMode and SetCompactThemeMode create requests using both desired flags. Move default font into compile overrides. Migrate MediaBreakPoint bootstrap to observe committed Snapshots.
+
+- [ ] **Step 6: Remove recursive and fake lifecycle paths**
+
+Remove the second ConfigureThemeVariant call, bool-property command recursion, same-theme activation events, fake unload events, and ThemeLoaded mutation hooks after consumers migrate.
+
+- [ ] **Step 7: Verify transition behavior**
+
+Run:
+- dotnet test tests/AtomUI.Core.Tests/AtomUI.Core.Tests.csproj --framework net10.0 --no-restore
+- dotnet test tests/AtomUI.Desktop.Controls.Tests/AtomUI.Desktop.Controls.Tests.csproj --framework net10.0 --no-restore --filter FullyQualifiedName~ThemeInitialModeTests
+- dotnet test tests/AtomUI.Toolkits.GalleryBase.Tests/AtomUI.Toolkits.GalleryBase.Tests.csproj --framework net10.0 --no-restore --filter FullyQualifiedName~GalleryCodeViewer_Updates_TextMate_Theme
+
+Expected: PASS and one commit per request.
+
+- [ ] **Step 8: Commit**
+
+~~~bash
+git add src/AtomUI.Core/Theme/Transitions src/AtomUI.Core/Theme/ThemeManager.cs src/AtomUI.Core/ApplicationExtensions.cs src/AtomUI.Controls.Shared/ApplicationExtensions.cs src/AtomUI.Desktop.Controls/Window/MediaBreakPointThemeBootstrapper.cs tests/AtomUI.Core.Tests/Theme/ThemeCoordinatorTests.cs
+git commit -m "refactor(Theme): serialize atomic theme transitions"
+~~~
+
+### Task 11: Migrate Remaining Components and Delete ScopeHost
+
+**Files:**
+- Modify: AXAML inventory produced by the SharedTokenResource search under src/AtomUI.Controls and all desktop control packages.
+- Modify: C# inventory produced by the RegisterTokenResourceScope search under src.
+- Modify: ControlToken inventory produced by the ScopeProvider search under src.
+- Remove: src/AtomUI.Core/Theme/ControlTokenResourcesHost.cs
+- Remove: src/AtomUI.Core/Theme/IControlTokenResourceScopeProvider.cs
+- Modify: src/AtomUI.Core/Data/TokenFinderUtils.cs
+- Modify: src/AtomUI.Core/Data/TokenResourceUtils.cs
+- Test: tests/AtomUI.Desktop.Controls.Tests/Theme/ComponentThemeIsolationTests.cs
+- Test: existing ThemeContract tests under tests/AtomUI.Desktop.Controls.Tests
+
+**Interfaces:**
+- Consumes: generated component-shared extensions and ThemeScope.
+- Produces: repository-wide component isolation with zero instance Token dictionaries.
+
+- [ ] **Step 1: Capture and classify a checked inventory**
+
+Run:
+
+~~~bash
+rg -l "RegisterTokenResourceScope" src --glob "*.cs" | sort
+rg -l "SharedTokenResource" src --glob "*.axaml" | sort
+rg -l "SharedTokenResourceValue" src --glob "*.axaml" | sort
+rg -l "ScopeProvider" src --glob "*Token.cs" | sort
+~~~
+
+Classify every result as component-style consumption, global-style consumption, static non-Visual consumption, or obsolete registration. Any non-Visual DynamicResource replacement must have a scoped owner and verified release path; do not use a blind repository-wide replacement.
+
+- [ ] **Step 2: Migrate small packages first**
+
+Migrate src/AtomUI.Controls, DataGrid, ColorPicker and Extras. For each identity, replace component-style shared references, remove constructor registration and remove ScopeProvider.
+
+Run:
+
+~~~bash
+dotnet test tests/AtomUI.Desktop.Controls.DataGrid.Tests/AtomUI.Desktop.Controls.DataGrid.Tests.csproj --framework net10.0 --no-restore
+dotnet test tests/AtomUI.Desktop.Controls.Tests/AtomUI.Desktop.Controls.Tests.csproj --framework net10.0 --no-restore --filter FullyQualifiedName~ThemeContract
+~~~
+
+Expected: PASS.
+
+- [ ] **Step 3: Migrate the main desktop package by domain**
+
+Use separate reviewed commits for General and Layout, Navigation, DataEntry, DataDisplay, Feedback, and Window and Overlay. Each commit removes every Host registration and ScopeProvider for its domain and runs its ThemeContract and Token tests.
+
+- [ ] **Step 4: Add cross-component isolation tests**
+
+Cover Button containing Icon, LineEdit containing AddOnDecoratedBox, Select popup content, DatePicker popup content, Modal content and DataGrid cell content. Parent component overrides must not alter child component Token; scope-global overrides must affect both.
+
+- [ ] **Step 5: Delete legacy infrastructure only after zero references**
+
+Run:
+
+~~~bash
+rg "RegisterTokenResourceScope|ControlTokenResourceScopeHost|ScopeProvider" src tests
+~~~
+
+Expected: no matches outside migration documentation.
+
+Delete the Host, interface, attached properties and dead catalog parameter.
+
+- [ ] **Step 6: Run control suites**
+
+Run:
+- dotnet test tests/AtomUI.Controls.Shared.Tests/AtomUI.Controls.Shared.Tests.csproj --framework net10.0 --no-restore
+- dotnet test tests/AtomUI.Desktop.Controls.Tests/AtomUI.Desktop.Controls.Tests.csproj --framework net10.0 --no-restore
+- dotnet test tests/AtomUI.Desktop.Controls.DataGrid.Tests/AtomUI.Desktop.Controls.DataGrid.Tests.csproj --framework net10.0 --no-restore
+
+Expected: PASS.
+
+- [ ] **Step 7: Commit final removal**
+
+~~~bash
+git add src tests/AtomUI.Desktop.Controls.Tests/Theme
+git commit -m "refactor(Theme)!: remove per-control token resource scopes"
+~~~
+
+### Task 12: Add Snapshot Caching and Remove Mutable Compile Paths
+
+**Files:**
+- Create: src/AtomUI.Core/Theme/Compilation/ThemeSnapshotCache.cs
+- Modify: src/AtomUI.Core/Theme/Compilation/ThemeCompileRequest.cs
+- Modify: src/AtomUI.Core/Theme/ThemeManager.cs
+- Modify: src/AtomUI.Core/Theme/ThemeConfigProvider.cs
+- Modify: src/AtomUI.Core/Theme/Theme.cs
+- Test: tests/AtomUI.Core.Tests/Theme/ThemeSnapshotCacheTests.cs
+
+**Interfaces:**
+- Consumes: normalized compile request identity.
+- Produces: bounded shared Snapshot cache without sharing owner-bound ResourceProvider instances.
+
+- [ ] **Step 1: Write identity and eviction tests**
+
+Assert equal definition revision, parent version, ordered algorithms, overrides and registration version return the same Snapshot reference. Algorithm order or any override difference returns a different Snapshot. Provider instances remain distinct. Active Snapshots cannot be evicted.
+
+- [ ] **Step 2: Verify failure**
+
+Run: dotnet test tests/AtomUI.Core.Tests/AtomUI.Core.Tests.csproj --framework net10.0 --no-restore --filter FullyQualifiedName~ThemeSnapshotCacheTests
+
+Expected: FAIL.
+
+- [ ] **Step 3: Implement a bounded normalized cache**
+
+Use a value key containing definition revision, parent Snapshot version, ordered algorithm ids, sorted override pairs and registration version. Limit inactive entries to 32 and pin active Snapshot references. Do not add lazy component compilation in this task.
+
+- [ ] **Step 4: Remove duplicate mutable loops**
+
+Verify Theme and ThemeConfigProvider contain no Seed, Map or Alias compile loops, Activator-based metadata lookup, or direct token ResourceDictionary construction.
+
+Run:
+
+~~~bash
+rg "TokenConfigBuckets|CalculateAliasTokenValues|Activator.CreateInstance" src/AtomUI.Core/Theme/Theme.cs src/AtomUI.Core/Theme/ThemeConfigProvider.cs
+~~~
+
+Expected: no matches.
+
+- [ ] **Step 5: Add allocation and count assertions**
+
+Twenty identical ThemeConfigProviders must share one Snapshot, own twenty ResourceProviders, and retain one provider layer each. One hundred identical global requests must compile once and emit one Changed event.
+
+- [ ] **Step 6: Run and commit**
+
+Run: dotnet test tests/AtomUI.Core.Tests/AtomUI.Core.Tests.csproj --framework net10.0 --no-restore
+
+Expected: PASS.
+
+~~~bash
+git add src/AtomUI.Core/Theme tests/AtomUI.Core.Tests/Theme/ThemeSnapshotCacheTests.cs
+git commit -m "perf(Theme): cache compiled theme snapshots"
+~~~
+
+### Task 13: Documentation, Lifecycle and Release Validation
+
+**Files:**
+- Modify: docs/architecture/startup-and-registration.md
+- Modify: docs/modules/core/overview.md
+- Create: docs/modules/core/theme-system.md
+- Modify: CustomizeTheme localization files under controlgallery/AtomUIGallery/ShowCases/General/CustomizeTheme/Localization
+- Modify: tests/AtomUIGallery.Tests/ShowCases/CustomizeThemeShowCasePageTests.cs
+
+**Interfaces:**
+- Consumes: completed snapshot architecture.
+- Produces: maintained docs, Gallery contracts and release evidence.
+
+- [ ] **Step 1: Document final runtime flow**
+
+Document startup request, prepare and commit order, Snapshot contents, nested merge, component-private keys, event order, failure behavior and extension points.
+
+- [ ] **Step 2: Update Gallery examples**
+
+Add examples for nested inheritance, Inherit false, runtime Setter changes, component algorithm true and false, and isolation from Content.
+
+- [ ] **Step 3: Run lifecycle checks**
+
+Verify old ShowCases, ThemeConfigProviders, ResourceProviders and DynamicResourceExpression instances do not grow monotonically after Gallery navigation. Verify Popup and Flyout content follow the owning scope.
+
+- [ ] **Step 4: Run target test projects**
+
+~~~bash
+dotnet test tests/AtomUI.Core.Tests/AtomUI.Core.Tests.csproj --framework net10.0 --no-restore
+dotnet test tests/AtomUI.Controls.Shared.Tests/AtomUI.Controls.Shared.Tests.csproj --framework net10.0 --no-restore
+dotnet test tests/AtomUI.Desktop.Controls.Tests/AtomUI.Desktop.Controls.Tests.csproj --framework net10.0 --no-restore
+dotnet test tests/AtomUI.Desktop.Controls.DataGrid.Tests/AtomUI.Desktop.Controls.DataGrid.Tests.csproj --framework net10.0 --no-restore
+dotnet test tests/AtomUIGallery.Tests/AtomUIGallery.Tests.csproj --framework net10.0 --no-restore
+~~~
+
+Expected: all commands exit 0.
+
+- [ ] **Step 5: Build both release targets**
+
+Run: dotnet build AtomUI.slnx --configuration Release --no-restore
+
+Expected: net8.0 and net10.0 builds succeed without new warnings.
+
+- [ ] **Step 6: Publish NativeAOT Gallery**
+
+~~~bash
+pwsh -NoLogo -NoProfile -File controlgallery/AtomUIGallery.Desktop/scripts/PublishToLocal.ps1 -publishRootPath /tmp/atomui-gallery-theme-aot -runtime osx-arm64 -buildType Release -publishAot true
+~~~
+
+Expected: publish exits 0. Launch the result and verify global Dark and Compact, nested scopes, component isolation, Popup content and runtime updates.
+
+- [ ] **Step 7: Run hygiene checks**
+
+~~~bash
+rg "ThemeDefinitionReader|ControlTokenResourcesScopeHostExtensions|RegisterTokenResourceScope|ThemeAboutToUnload|ThemeUnloaded" src tests
+git diff --check
+~~~
+
+Expected: no production legacy references and a clean diff check.
+
+- [ ] **Step 8: Commit docs and validation updates**
+
+~~~bash
+git add docs controlgallery/AtomUIGallery/ShowCases/General/CustomizeTheme tests/AtomUIGallery.Tests/ShowCases/CustomizeThemeShowCasePageTests.cs
+git commit -m "docs(Theme): document snapshot theme architecture"
+~~~
+
+---
+
+## Review Gates
+
+1. **Foundation gate after Task 5:** Parser, Compiler and Catalog are pure and tested. Do not migrate behavior if old and new default Token values differ.
+2. **Architecture gate after Task 9:** Button proves component isolation, runtime refresh and zero per-instance Token dictionaries.
+3. **Transition gate after Task 10:** Dark and Compact, no-op, failure rollback and reentry tests pass before broad migration.
+4. **Removal gate during Task 11:** Delete ScopeHost only after repository searches show zero consumers.
+5. **Release gate after Task 13:** Target tests, dual-target Release build, NativeAOT publish, lifecycle checks and hygiene all pass.
+
+## Explicit Non-Goals
+
+- Changing Ant Design Token values or palette algorithms.
+- Replacing Avalonia ControlTheme and AXAML with generated runtime styles.
+- Adding third-party serialization, dependency injection or caching packages.
+- Adding theme-file watching or live hot reload.
+- Adding lazy per-component compilation before profiling proves it is needed.
+- Preserving accidental component override leakage into arbitrary Content descendants.
diff --git a/docs/superpowers/specs/2026-07-15-theme-system-redesign-design.md b/docs/superpowers/specs/2026-07-15-theme-system-redesign-design.md
new file mode 100644
index 000000000..d8a459ebf
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-15-theme-system-redesign-design.md
@@ -0,0 +1,445 @@
+# AtomUI 主题系统重构设计
+
+## 1. 背景与结论
+
+AtomUI 已经实现 Ant Design 的 Seed Token、Map Token、Alias Token、Component Token、默认算法、暗色算法、紧凑算法和组件级 `EnableAlgorithm` 语义。这些领域模型应当保留。
+
+当前主要问题不在 Token 数值或算法本身，而在定义解析、Token 编译、资源发布、主题切换、局部作用域和事件派发被组合在同一批可变对象中。静态内置主题和首次局部覆盖可以工作，但失败恢复、嵌套继承、运行期更新、自定义主题和组件级共享 Token 缺少一致性保证。
+
+本次设计参考 Ant Design 6.5.1 和 `@ant-design/cssinjs` 2.1.2。借鉴的是父配置合并、稳定主题身份、缓存 Token 结果和明确生命周期，不照搬 React Context 或 CSS-in-JS。
+
+## 2. 重构目标
+
+- 保留现有 Seed、Map、Alias、ControlToken 类型、Token 数值和算法实现。
+- 主题定义只解析一次，解析阶段不修改运行时 Theme。
+- 全局主题和局部主题使用同一套纯 Token 编译器。
+- 主题切换先完整准备目标快照，再在 UI 线程原子提交。
+- `ThemeConfigProvider` 默认继承父主题，与 Ant Design `inherit = true` 一致。
+- 组件级 Token 只影响该组件自己的样式计算，不形成控件子树资源作用域。
+- 每个全局主题变体或局部 Provider 只拥有一个可替换的资源层。
+- 主题事件只描述已定义的状态转换，并携带完整上下文和异常。
+- 保持 NativeAOT 兼容，不新增字符串反射 Binding 或运行时类型扫描。
+- 允许分阶段迁移，任何阶段都能独立测试和回滚。
+
+## 3. 完整问题清单
+
+### 3.1 主题切换重入与多状态源
+
+- `ThemeVariant`、`Application.ActualThemeVariant`、`Application.RequestedThemeVariant`、`ActivatedTheme`、`IsDarkThemeMode` 和 `IsCompactThemeMode` 都参与决定当前主题。
+- `ConfigureThemeVariant()` 回写 Dark/Compact 布尔属性；属性回调又改写 `RequestedThemeVariant`，同步触发新的主题切换。
+- Dark+Compact 首次启动可能经历 `Dark-Compact -> Dark -> Dark-Compact`，随后 `AttachApplication()` 再重复激活一次。
+- 同一 ThemeVariant 没有 no-op 判断，重复激活仍派发生命周期事件。
+- 没有 UI 线程验证、重入保护、请求队列或 transition id。
+
+### 3.2 加载和激活不是事务
+
+- `Theme.Load()` 直接修改在线 `ThemeDefinition`、`DesignToken`、ControlToken 和 `ResourceDictionary`。
+- 解析、转换、计算、资源构建或事件订阅者失败后没有回滚。
+- Application 的实际变体可能已经改变，而 `ActivatedTheme` 仍指向旧主题。
+- 失败重试会复用已经被部分修改的 Token 和资源字典。
+- 默认字体通过 `ThemeLoaded` 事件事后修改资源字典，造成 SharedToken 与资源值可能不一致。
+- Motion 和 Wave 开关直接修改已发布主题字典，破坏快照语义。
+
+### 3.3 定义发现和解析职责混乱
+
+- 每个主题文件创建四个 `Theme` 对象，每个变体首次加载时重新读取同一个 XML。
+- 主题发现阶段无法可靠获得 DisplayName、算法和诊断信息。
+- `IsDefault` 没有参与默认主题选择。
+- 定义中的算法只用于 `IsPrimary` 比较，不控制实际编译顺序。
+- 文件系统扫描顺序、重复主题和无效主题缺少结构化诊断。
+
+### 3.4 XML 解析器存在正确性缺陷
+
+- `ReadElementContentAsString()` 已将 reader 移动到后继节点，外层循环再次 `Read()`，导致无空白 XML 跳过元素。
+- 正文 Token 在读取正文后才读取 `IsShared`，读取的是错误节点的属性。
+- 空元素没有统一处理，元素栈和上下文状态可能不平衡。
+- 空文档、缺失根节点和未完成解析没有最终验证。
+- 重复 Token、重复 ControlToken 和未知元素产生不一致的异常。
+- 未知共享 Token 和未知 ControlToken id 会被静默忽略。
+- `double.Parse`、`float.Parse` 等使用当前 Culture，主题文件不可移植。
+- 错误信息可能混淆属性名和元素名，失败事件也不携带原始异常。
+
+### 3.5 全局和局部编译逻辑重复
+
+- `Theme.BuildThemeResource()` 与 `ThemeConfigProvider.CalculateTokenResources()` 重复 Seed、Map、Alias、组件算法和资源构建逻辑。
+- 两条路径已经拥有不同的生命周期、错误处理和更新语义。
+- 编译直接修改输入 Token，结果依赖此前调用历史，不是确定性的纯函数。
+- `AbstractDesignToken.GetTokenValue()` 的值缓存可能在后续直接属性修改后过期。
+- `Clone()` 对集合属性为浅复制，不能作为严格隔离边界。
+
+### 3.6 `ThemeConfigProvider` 不符合 Ant Design
+
+- Provider 从 `new DesignToken()` 开始，不读取父 Provider 或当前全局快照。
+- 未覆盖 Token 回到 AtomUI 默认值，而不是继承父主题。
+- Provider 在全局暗色主题中只设置一个颜色时，会重新生成默认亮色 Token。
+- `Algorithms`、`SharedTokenSetters` 和 `ControlTokenInfoSetters` 使用可变 `List<T>`；集合内容修改不触发 StyledProperty 变化。
+- 重算复用 `_sharedToken`，删除 Seed override 后旧值可能继续保留。
+- 每次重算向 `MergedDictionaries` 追加字典，不替换旧层。
+- 编译失败可能留下“新 Token 对象 + 旧可见资源”的混合状态。
+- 父 Provider 更新和全局主题切换不会触发子 Provider 重算。
+
+### 3.7 组件级共享 Token 作用域语义错误
+
+Ant Design 的 `theme.components.Button` 是 Button 样式计算的私有 Token 输入，只影响 Button 自己的 style hook 和内部子样式。它不向 Button 的 Content 或任意后代组件传播。
+
+当前 `ControlTokenResourcesScopeHostExtensions` 在控件 Attach 时把共享 Token 差量复制到 `control.Resources`：
+
+- Button 的组件 override 会覆盖整个 Button 逻辑子树。
+- 用户 Content 和嵌套控件可能读取到 Button 的私有 Token。
+- 每个控件实例创建自己的 ResourceDictionary。
+- 差量只在 Attach 时复制，全局切换和局部重算后不会更新。
+- Attach/Detach、重复注册和资源清理形成额外生命周期负担。
+- `ResourceCatalog` 参数没有进入实际查找键，组件 id 存在潜在冲突边界。
+- `SharedTokenResourceValue` 在 XAML 加载时从 Application 静态取值，绕过局部 scope、组件 Effective Token 和后续主题更新。
+
+该机制最终必须删除，不能通过增加更多事件订阅作为长期修复。
+
+### 3.8 事件模型不可靠
+
+- `ThemeAboutToLoad` 位于 `try` 外，`ThemeLoaded` 位于 `try` 内。
+- `ThemeLoaded` 订阅者异常会触发 `ThemeLoadFailed`，即使 Theme 已经标记为 Loaded。
+- `ThemeChanged` 早于 Dark/Compact、Motion 和 Wave 状态同步。
+- `ThemeAboutToChange` 不携带目标主题和切换原因。
+- `ThemeLoadFailed` 不携带异常。
+- `ThemeCreated` 在 ThemeManager 发布前派发，初始创建基本不可观察。
+- 未实现实际卸载，却派发 `ThemeUnloaded`。
+- 同步事件允许订阅者重入主题切换，订阅者异常会破坏主题事务。
+- 这些事件不属于公共 `IThemeManager` 契约，外部语义不明确。
+
+### 3.9 资源、缓存和性能模型粗放
+
+- 每个局部 Provider 实例化并计算所有已注册 ControlToken；Gallery 当前配置约 89 个。
+- 相同定义、算法和 override 没有共享缓存。
+- 同一主题文件最多被四个变体重复解析。
+- 首次切换到未加载变体时，在 UI 线程同步进行文件 IO 和全量计算。
+- ThemeDictionaries 和局部 MergedDictionaries 只增长，不存在真实卸载或淘汰语义。
+- 多个 Button、Tag 等控件订阅全局 ThemeChanged，只为重新读取 Token。
+
+### 3.10 可变 API 和测试缺口
+
+- `ITheme` 和 `IThemeConfigProvider` 暴露可变 DesignToken、Dictionary 和 List，没有版本或变更协议。
+- `ThemeManager.Current` 和 `Activator.CreateInstance` 增加全局耦合和测试成本。
+- 现有主题测试主要验证 ThemeVariant 名称归一化和首次静态作用域颜色。
+- 缺少解析格式、Culture、事件顺序、失败回滚、重入、嵌套继承、动态更新、资源层数量、组件隔离和生命周期测试。
+
+## 4. Ant Design 语义基线
+
+### 4.1 全局主题
+
+全局 `token` 先与父配置合并，再由有序算法链生成 Map 和 Alias Token。Map/Alias 显式 override 在派生后应用。
+
+### 4.2 嵌套主题
+
+- `inherit` 默认是 `true`。
+- 子 Provider 的 token、components 和其他主题配置与父配置合并。
+- `inherit = false` 时从默认主题配置开始，但仍保留明确规定的基础配置。
+
+### 4.3 组件主题
+
+- Component Token 和 Design Token override 只供目标组件样式使用。
+- `algorithm = false` 时仅直接覆盖，不重新派生 Seed。
+- `algorithm = true` 时继承当前全局算法并重新派生组件 Effective Token。
+- 组件可以提供独立算法链，覆盖全局算法。
+- 子组件按自己的 component id 取 Token，不继承父组件的私有 Effective Token。
+
+## 5. 目标架构
+
+```text
+ThemeDefinitionParser
+        |
+        v
+ThemeDefinition + Diagnostics
+        |
+        v
+ThemeCatalog -------- ThemeSnapshotCache
+        |                     |
+        +------> ThemeCompiler+
+                              |
+                              v
+                         ThemeSnapshot
+                              |
+              +---------------+----------------+
+              |                                |
+              v                                v
+       ThemeCoordinator                 ThemeConfigProvider
+              |                                |
+              v                                v
+    Global ThemeResourceLayer          Scoped ThemeResourceLayer
+              |                                |
+              +---------------+----------------+
+                              v
+                     Avalonia DynamicResource
+```
+
+### 5.1 `ThemeDefinitionParser`
+
+职责只有 `Stream -> ThemeDefinitionParseResult`。
+
+- 使用带 `DtdProcessing = Prohibit` 的 XmlReader 加载 `XDocument`，保留行列信息。
+- 不持有 `Theme`、ThemeManager 或 ResourceDictionary。
+- 输出不可变 ThemeDefinition 和结构化 diagnostics。
+- Token 字符串转换留在 Compiler，Parser 只验证 XML 结构和基础字段。
+- 算法顺序使用 `IReadOnlyList<ThemeAlgorithm>` 保存，不转换为 HashSet。
+- Value 属性和正文必须恰好提供一个非空值。
+- 重复键、未知全局 Token、已知组件的未知 Token 为错误。
+- 未注册组件 id 产生 warning，允许同一主题文件服务于未加载的可选包。
+- 所有诊断包含 code、severity、file、line、column、path 和 message。
+
+### 5.2 `ThemeCatalog`
+
+- 每个文件只读取和解析一次。
+- 存储 `ThemeDescriptor`，包括 id、路径、来源优先级、定义和 diagnostics。
+- 自定义目录优先级保持现有行为，但重复 id 产生诊断。
+- 如果 Builder 显式指定主题，以 Builder 为准；否则使用唯一 `IsDefault=true` 定义。
+- 内置默认主题解析失败时启动失败；未选中的自定义主题错误只标记为 unavailable。
+- 编译缓存键至少包含 definition identity、ordered algorithms、normalized overrides、parent snapshot version 和 registration version。
+
+### 5.3 `ThemeCompiler`
+
+唯一入口：
+
+```csharp
+ThemeCompileResult Compile(ThemeCompileRequest request);
+```
+
+`ThemeCompileRequest` 包含定义、父快照、算法、全局 override、组件 override、ControlToken registrations 和运行期 override。
+
+编译顺序：
+
+```text
+parent/default seed
+  + global seed override
+  -> ordered algorithms
+  + global map override
+  -> alias calculation
+  + global alias override
+  -> shared effective token
+  -> each component effective shared token
+  -> each component token calculation
+  + component token override
+  -> immutable resource maps
+```
+
+每次编译创建新的 Token 图，不复用上一次发布对象。编译失败只返回 diagnostics/exception，不修改在线状态。
+
+### 5.4 `ThemeSnapshot`
+
+```text
+ThemeSnapshot
+├── Id / Version / Algorithms / IsDark
+├── SharedToken
+├── SharedResources
+└── Components[ComponentTokenIdentity]
+    ├── EffectiveSharedToken
+    ├── SharedResourceDelta
+    ├── ControlToken
+    └── ControlResources
+```
+
+Snapshot 发布后按逻辑不可变。新内部代码不得修改其中 Token；现有返回可变 DesignToken 的公共兼容 API 由 adapter 暂时保留，并在后续版本迁移到只读视图。
+
+### 5.5 `ThemeTokenResourceProvider`
+
+实现为 Avalonia `ResourceProvider` 子类，持有一个 ThemeSnapshot：
+
+```csharp
+internal sealed class ThemeTokenResourceProvider : ResourceProvider
+{
+    public ThemeSnapshot Snapshot { get; }
+    public override bool HasResources => true;
+    public override bool TryGetResource(object key, ThemeVariant? theme, out object? value);
+    internal void PrepareSnapshot(ThemeSnapshot snapshot);
+    internal void PublishSnapshotChanged();
+    public void ReplaceSnapshot(ThemeSnapshot snapshot);
+}
+```
+
+- `TryGetResource` 直接查询预构建资源 map。
+- `PrepareSnapshot` 只替换引用，供 Coordinator/Scope 与其他状态一起提交。
+- `PublishSnapshotChanged` 在周边状态一致后只调用一次 `RaiseResourcesChanged()`。
+- `ReplaceSnapshot` 为简单调用者组合上述两步。
+- 一个 ResourceProvider 实例只属于一个 IResourceHost；缓存共享 Snapshot，不共享 Provider 实例。
+- 全局 ThemeVariant 和每个局部 Provider 各自只挂载一个 Token ResourceProvider。
+
+### 5.6 组件复合资源键
+
+新增稳定值类型：
+
+```csharp
+public readonly record struct ComponentSharedTokenResourceKey(
+    string? Catalog,
+    string ComponentId,
+    SharedTokenKind Kind);
+```
+
+查询语义：
+
+```text
+SharedTokenKind.X
+    -> snapshot.SharedResources[X]
+
+ComponentSharedTokenResourceKey(Button, X)
+    -> snapshot.Components[Button].EffectiveSharedResources[X]
+
+ButtonTokenKind.X
+    -> snapshot.Components[Button].ControlResources[X]
+```
+
+组件 ControlTheme 中消费的 Design Token 必须使用组件复合键。普通应用资源和非组件样式继续使用 SharedTokenKind。
+
+源生成器从 `[ControlDesignToken]` 类型的常量 `ID`、资源 catalog 和生成的 TokenKind 建立强类型身份，并生成组件共享 Token markup extension。禁止运行时通过类型名猜测组件 id。
+
+### 5.7 `ThemeScope` 与 `ThemeConfigProvider`
+
+新增可继承的只读上下文属性 `ThemeScope.SnapshotProperty`，内容树继承的是整个 ThemeSnapshot，不是当前组件 id。
+
+ThemeConfigProvider 自身继承父 Snapshot，编译子 Snapshot，然后：
+
+- 把子 Snapshot 设置到 Content 根元素的 `ThemeScope.SnapshotProperty`。
+- 把同一个 Snapshot 发布到自己的 ThemeTokenResourceProvider。
+- 父 Snapshot 或本地配置改变时重新编译。
+- 编译成功后一次提交；失败时继续保留上一份子 Snapshot。
+- `Inherit` 默认 true；false 时使用默认基础快照。
+- Provider 永远只保留一个 ResourceProvider，不追加字典。
+
+Provider 的集合 API 迁移到可观察 AvaloniaList，并订阅 TokenSetter/ControlTokenInfoSetter 的属性变化；后续可以增加不可变 `ThemeConfig` 入口。迁移期间保留现有 AXAML 集合语法。
+
+### 5.8 `ThemeCoordinator`
+
+唯一允许修改全局活动主题的对象。
+
+状态机：
+
+```text
+Idle -> Preparing -> Committing -> Idle
+                    \-> Failed -> Idle
+```
+
+- 所有请求在 Dispatcher.UIThread 串行执行并验证线程访问。
+- 单一 `ThemeRequest` 同时描述 theme id、ordered algorithms、runtime overrides 和 reason。
+- Preparing 阶段查询 Catalog/Cache 并得到完整 Snapshot。
+- Preparing 失败时 Application、ActivatedTheme 和资源层保持原值。
+- Committing 阶段挂载 Snapshot、同步 manager 属性、设置 RequestedThemeVariant，并在 guard 下消费 ActualThemeVariant 回调。
+- 相同请求为 no-op。
+- 提交期间的新请求进入队列，不能递归执行。
+- 提交全部完成后才派发 Changed。
+
+### 5.9 事件契约
+
+```csharp
+ThemeChanging(oldSnapshot, newSnapshot, request, transitionId)
+ThemeChanged(oldSnapshot, newSnapshot, request, transitionId)
+ThemeChangeFailed(oldSnapshot, request, transitionId, exception, diagnostics)
+```
+
+- Changing 只允许观察，不允许修改候选 Snapshot。
+- Changed 在 Application、manager、flags 和 resources 一致后派发。
+- 订阅者异常单独记录或聚合，不转换为主题加载失败。
+- 重入请求排队到当前事件派发结束后。
+- 删除没有真实实现的 unload 生命周期和不可观察的 created 生命周期。
+- DefaultFont、MediaBreakPoint 等内部副作用迁移到 Compiler options 或提交后 observer，不再借 ThemeLoaded 修改快照。
+
+## 6. 组件资源迁移策略
+
+迁移分两层：
+
+1. 先让 ResourceProvider 同时支持旧普通资源键和新组件复合键。
+2. 按控件包迁移 ControlTheme 中对 SharedToken 的消费，并保留旧 Host 作为短期兼容。
+3. 每个已迁移控件不再调用 `RegisterTokenResourceScope()`。
+4. 单独审计 `SharedTokenResourceValue`：StyledElement 目标改为组件复合 DynamicResource；非 Visual transition/animation 通过拥有明确释放路径的控件属性消费 Token，禁止把 DynamicResource 直接挂到无 scope host 的非 Visual 对象。
+5. 所有包迁移完成后删除 `ControlTokenResourcesScopeHostExtensions`、attached properties 和 ScopeProvider 静态字段。
+
+迁移验收必须验证：
+
+- Button component ColorPrimary 影响 Button 自身背景。
+- Button Content 中独立 TextBlock 仍读取 scope global ColorPrimary。
+- Button 内嵌 Input 使用 Input component config，不使用 Button config。
+- 全局切换和局部 Provider 更新无需重新 Attach 即可更新。
+- 多个相同控件共享 Snapshot，不创建实例 ResourceDictionary。
+
+## 7. AOT 与生命周期约束
+
+- 不新增字符串属性路径 Binding、运行时程序集扫描或未标注 Activator。
+- Token registration metadata 和 markup extensions 由现有增量源生成器生成。
+- ThemeTokenResourceProvider 使用公开 ResourceProvider API。
+- Snapshot 不持有 Visual、Control、ThemeConfigProvider 或事件订阅。
+- Provider 只订阅直接父 ThemeScope，Content 替换、Detach 和 reattach 时对称释放。
+- Popup、Flyout 和非 Visual DynamicResource 继续遵守 scoped IResourceHost 生命周期规范。
+- Gallery NativeAOT publish 是最终验收项。
+
+## 8. 性能目标
+
+- 每个定义文件每个进程最多解析一次。
+- 同一编译缓存键只生成一个共享 ThemeSnapshot。
+- 每个 ThemeConfigProvider 永远只有一个 Token ResourceProvider。
+- 控件实例不创建组件 Token ResourceDictionary，不订阅全局 ThemeChanged。
+- 相同主题请求不触发资源更新或事件。
+- 组件 Token 可先保持预计算，后续基于实测引入按 component id 懒加载；首轮重构不同时引入复杂 lazy provider。
+
+## 9. 测试矩阵
+
+### 9.1 Parser
+
+- 紧凑 XML、格式化 XML、自闭合元素和正文 Token 结果一致。
+- Value/正文二选一、IsShared、算法顺序、重复键和错误路径正确。
+- 空文档、错误根、未知 Token、未知算法和非法 bool 产生精确 diagnostic。
+- `en-US`、`fr-FR`、`zh-CN` 下数值结果一致。
+
+### 9.2 Compiler
+
+- Seed -> Map -> Alias 覆盖顺序固定。
+- Dark/Compact 有序组合结果稳定。
+- Component algorithm false/true 与 Ant Design 语义一致。
+- 编译不修改 parent snapshot 或 request 输入。
+- 相同输入产生相同资源图；失败不发布部分结果。
+
+### 9.3 Coordinator
+
+- 默认、Dark、Compact、Dark+Compact 各只提交一次。
+- 相同请求无事件。
+- 重入请求排队，不出现中间变体。
+- 解析、编译、资源准备和订阅者异常分别处理。
+- 失败后 Application、ActivatedTheme、flags 和资源仍指向旧 Snapshot。
+
+### 9.4 Scope
+
+- 子 Provider 默认继承父 Shared Token 和 component config。
+- `Inherit=false` 从默认快照开始。
+- 父更新传播到所有子 Provider。
+- List add/remove、Setter 值修改和算法修改都触发一次新 Snapshot。
+- 编译失败保留上一 Snapshot。
+- 重复更新不增加 MergedDictionaries 数量。
+
+### 9.5 Component isolation
+
+- 组件 override 只影响目标组件样式。
+- Content 和嵌套组件不继承父组件 private token。
+- 全局、父 scope 和子 scope 的 component config 按 Ant Design 规则合并。
+- 运行期切换不依赖逻辑树 reattach。
+
+### 9.6 Lifecycle and AOT
+
+- Provider detach 后释放父 scope 订阅。
+- Popup/Flyout 内 Token 能跟随所属 scope。
+- DynamicResource 不通过 Application 意外持有旧 ShowCase。
+- Release net8.0、Debug net10.0 和 Gallery NativeAOT publish 通过。
+
+## 10. 兼容边界
+
+- 首轮重构不改变现有 Token 名称、默认值、ControlToken public API、AXAML ControlTheme key 或现有主题视觉数值。
+- `ThemeConfigProvider` 现有集合语法继续可用，并增加正确的 change tracking。
+- `IThemeManager` 的现有查询和 Application 扩展继续工作，内部转发到 Coordinator。
+- 组件级资源语义修复可能改变此前错误泄漏到 Content 的样式；这是有意的 Ant Design 对齐，不作为兼容行为保留。
+- 旧事件和 ScopeHost 在全部内部消费者迁移前保留 adapter，最终删除前先执行仓库级引用扫描。
+
+## 11. 完成标准
+
+- Parser、Compiler、Catalog、Coordinator、Scope 和 ResourceProvider 职责独立。
+- 全局和局部主题只调用同一个 ThemeCompiler。
+- 任何失败都不会发布部分主题状态。
+- Dark+Compact 不产生中间 Dark 激活或重复 Changed。
+- 嵌套 Provider 的未覆盖 Token 继承父 Snapshot。
+- 组件 Token 不再通过实例 ResourceDictionary 形成子树作用域。
+- `ControlTokenResourcesScopeHostExtensions` 和对应 attached resources 被删除。
+- 主题资源更新、事件顺序、scope lifecycle 和组件隔离测试通过。
+- 目标测试、Release 双目标构建、Gallery 测试、NativeAOT publish 和 `git diff --check` 通过。