Skip to content

Resolve ThemeRef with SetThemeResourceBinding instead of a parsed Style - #1635

Draft
Alexandre Zollinger Chohfi (azchohfi) wants to merge 24 commits into
azchohfi-set-theme-resource-bindingfrom
azchohfi-themeref-set-theme-resource-binding
Draft

Alexandre Zollinger Chohfi (azchohfi) wants to merge 24 commits into
azchohfi-set-theme-resource-bindingfrom
azchohfi-themeref-set-theme-resource-binding

Conversation

@azchohfi

@azchohfi Alexandre Zollinger Chohfi (azchohfi) commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

ThemeResourceProbe.TryResolve now calls FrameworkElement.SetThemeResourceBinding(Tag, key) on the same off-tree Border with the requested RequestedTheme, then reads Tag back, since the API has no Get method. This replaces the XamlReader-parsed Style from #1633. The per-thread style cache and BuildStyleXaml with its quoting and XML escaping are gone, and so are their unit tests in ThemeResourceProbeTests. Keys that markup could not hold, such as a key with both quote characters or a tab, now resolve through WinUI instead of going to the dictionary walk. The walk stays as the fallback for keys WinUI can't resolve for a theme, like keys an app defines only for Dark or only in Default.

Stacking. #1633 has merged, so this PR now targets #1618's branch (azchohfi-set-theme-resource-binding). The API only exists in Windows App SDK 2.6.6-experimental, which comes in through #1125, so this depends on #1618 and #1125 and can't merge until the API ships in a stable Windows App SDK. Once #1618 merges main, this gets rebased onto it, and the diff will shrink to the ThemeResourceProbe change, its tests and the CHANGELOG. Until then the diff also shows #1633's original commits.

Linked issue / spec

Fixes #1634. Follows #1534 and #1633. Depends on #1618 and #1125.

Test plan

Built through a short-path junction on this branch with the experimental SDK.

  • dotnet build src/Reactor/Reactor.csproj --no-restore -c Release -p:Platform=x64 passed with 0 errors
  • dotnet run --project tests/Reactor.AppTests.Host --no-build -c Debug -p:Platform=x64 -- --self-test --filter "Theme_Resolve" passed, 0 failures. That is all four ThemeRefResolutionFixtures. OddKeysResolveThroughProbe now expects the both-quotes key and a tab and line feed key to resolve through the probe, and an empty key not to.
  • --self-test --filter "ThemeRef" passed, 0 failures
  • dotnet test tests/Reactor.SelfTests --no-build -p:Platform=x64 --filter "ClassName~ThemeRefProbeProcessTests" passed 6 of 6, including the fresh-process --themeref-probe and its raw-read negative control
  • dotnet test tests/Reactor.Tests --no-build -p:Platform=x64 --filter-class "*Theme*" passed 111 of 111
  • Mutation check. With TryResolve forced to return false, 11 checks in Theme_Resolve failed. Restored and rerun green.

Risk / breaking changes

No public API change. The probe now throws and catches COMException for a key WinUI can't find, instead of XamlParseException at style load. Speed is about the same as the cached style per the measurements in #1634. Can't merge before SetThemeResourceBinding is in a stable Windows App SDK.

…1534)

Reading a WinUI theme dictionary entry from code creates it for the
application theme and shares it app-wide, so resolving the other theme
returned the wrong brush and changed it for every element. ThemeRef now
asks WinUI to resolve {ThemeResource key} on an off-tree element with the
requested RequestedTheme, and falls back to the dictionary walk only for
keys WinUI cannot resolve for that theme.

Adds a fresh-process probe (--themeref-probe) with MSTest coverage for
ThemeRef.Resolve, the element overload and .Resources overrides, plus
selftest fixtures and unit tests for the probe.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Reactor built two DataTemplates at runtime by handing XamlReader.Load a markup
string: the ContentControl shell every items control mounts
(ListView/GridView/FlipView), and the legacy text-node TreeView template. Both
existed only because DataTemplate could not be constructed from code.

WinUI now offers `new DataTemplate(DataTemplateElementFactory)`, which takes a
callback returning the subtree. This ports both templates onto it, so Reactor
no longer parses XAML at runtime for item templates.

Beyond removing the parse, the TreeView template loses its
`{Binding Content.Content}`. A classic Binding resolves that path by string
through CsWinRT's ICustomPropertyProvider -- reflection, which NativeAOT trims
unless the source type is annotated, and which costs a reflective lookup per
realized row even when it works. Reading the same chain in a
DataContextChanged handler is strongly typed: no annotation, no lookup, and the
event re-fires on recycling so reused rows retext correctly.

Windows App SDK versions move to the public experimental channel. The API is on
nuget.org but still carries [feature(Feature_ExperimentalApi)], so it exists
only there: it landed in Microsoft.WindowsAppSDK.WinUI 2.3.10-experimental and
is absent from 2.3.9 stable. The 2.5.4-experimental metapackage is the aggregate
that pairs with it (its nuspec names WinUI 2.3.10-experimental and pins Runtime
[2.5.4-experimental]), so the pairing rule in spec 063 section 3 is satisfied
and no package-reference workaround is needed.

Two incidental fixes this SDK requires:

  * CS8305 is demoted from error to warning. The XAML compiler's *generated*
    XamlTypeInfo.g.cs references the SDK's own experimental metadata providers
    (XamlControlsCharts/XamlControlsTabular), so every WinUI project emits it
    from code we do not own. WarningsNotAsErrors rather than NoWarn, so a
    newly-introduced experimental dependency is still reported.
  * The IElementFactory cref in IItemsRepeaterFactorySource is disambiguated.
    This SDK adds Microsoft.UI.Xaml.IElementFactory alongside the existing
    Microsoft.UI.Xaml.Controls.IElementFactory, making the bare cref ambiguous
    (CS0419) and failing the warnings-as-errors Release build. Verified still
    required: restoring the bare cref reproduces the error.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 17bce8bb-d57a-4f76-a55d-27c9029fc9a3
#1108 annotated TreeViewNodeData with [WinRT.GeneratedBindableCustomProperty]
for exactly one reason: Reactor's own text-node TreeView template bound
"Content.Content", and that string path is resolved by reflection, which
NativeAOT trims. The preceding commit replaces that binding with a
DataContextChanged handler, so the reason is gone -- there is now no {Binding}
anywhere in src/ and no SetBinding call site.

The attribute never shipped: every tag to date predates #1108, so no released
build has it, and binding to TreeViewNodeData from a consumer-supplied template
was already broken under NativeAOT in all of them. Removing it therefore takes
away nothing that ever worked in a release; it declines to keep a side effect of
an internal fix. Keeping it would carry a workaround, plus `partial` on a public
record, for a scenario Reactor does not use and does not document.

The limitation is written down instead: docs/aot-support.md gains a row
explaining that a classic {Binding} in a hand-supplied DataTemplate is not
trim-safe, that Reactor's own templates avoid it by populating content in a
DataContextChanged handler, and that a consumer installing their own template
through an escape hatch should do the same or annotate their own type.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 17bce8bb-d57a-4f76-a55d-27c9029fc9a3
The experimental channel broke nine CI jobs. None needed a workflow
restructure; each had a narrow cause.

* Doc snippet analyzer gate: the CS8305 exception for the SDK's generated
  XamlTypeInfo.g.cs lived in WarningsNotAsErrors, but this job passes
  -p:WarningsNotAsErrors=NU1900 on the command line, and a global property
  replaces the project value. Moved to an .editorconfig severity scoped to
  **/XamlTypeInfo.g.cs, which global properties cannot clobber. Narrower too:
  CS8305 still fires on Reactor's own experimental API use (verified with a
  probe file).

* REACTORGEN016 (added later by #1583): Microsoft.WinUI on this channel
  ships three XAML metadata providers (Charts and Tabular are the same
  experimental ones behind CS8305; stable ships one), so the wrapper generator
  cannot pick a unique provider for wrappers of built-in WinUI controls and
  warns, which Release turns into an error. Its fallback,
  TryRegisterControlAssembly, is what every wrapper emitted before #1583.
  Downgraded to a suggestion for tests/ and samples/ in .editorconfig; main's
  Release build has no REACTORGEN016, so this hides nothing else.

* Literal SDK pin guard: bumped the 25 literal Microsoft.WindowsAppSDK pins
  (recipes, SKILL.md, CLI scaffold, perf script, samples) to the central
  2.5.4-experimental. These ship in the agent kit, so this branch must stay a
  draft until the API graduates to stable.

* Motion parity guard: re-verified, not bumped blindly. The four WinUI motion
  sources have identical blob SHAs at winui3/release/2.2.0 and
  winui3/release/2.5.4-experimental; the tag compare is non-empty (300 files)
  as a positive control. The new tag is rooted at the repository root rather
  than under src/, so the guard's path-prefix advice is generalized.

* Roaming-hive guard: its trigger fired for real. Measured on the bundled
  runtime (Foundation 2.3.13-experimental, loaded from bin\): LocalSettings now
  writes the machine-local hive, i.e. WindowsAppSDK#6559 is fixed. The control
  now requires the value in exactly one hive, and the store is asserted absent
  from both. The spec 063 D1 follow-up is now actionable.

Coverage jobs failed on the same unit guards and are fixed by the above.

bootstrap needs no change: since template pack 0.0.8-alpha the reactor
templates carry no Microsoft.WindowsAppSDK reference, so the scaffolded app
takes the SDK transitively from the local Reactor package.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 17bce8bb-d57a-4f76-a55d-27c9029fc9a3
The 2.6 experimental release (published 2026-11-07) supersedes
2.5.4-experimental. Its metapackage nuspec pairs it with
Microsoft.WindowsAppSDK.WinUI 2.6.6-experimental and exact-pins
Runtime [2.6.6-experimental], so both central values move together per the
spec 063 pairing rule. The code-based DataTemplate constructor is still
[VelocityFeature("Feature_ExperimentalApi")] on microsoft-ui-xaml main, and
absent from every stable WinUI through 2.6.5, so this stays on the
experimental channel.

The 24 literal pins move with the central version, as the literal-pin guard
requires (draft-only: they ship in the agent kit and must go to a stable
version at graduation).

Motion-parity guard re-verified by bracketing, because no
winui3/release/2.6.6-experimental source tag is published yet: the four
motion sources have identical blob SHAs at 2.5.4-experimental, 2.6.4 stable
and main, while 2.5.4-experimental..main changes 300 files.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 17bce8bb-d57a-4f76-a55d-27c9029fc9a3
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…rsed Style

ApplyThemeBindings built a {ThemeResource} Style as a XAML string, parsed it
with XamlReader.Load, cached it, and assigned fe.Style, which replaced any
Style the app had set. It now calls FrameworkElement.SetThemeResourceBinding
(experimental WinUI API, available on the 2.6.6-experimental channel #1125
moves to) once per property, tracking what it bound on the control's
ReactorState.

The binding sits at local precedence, where the Style sat below it, so the
old winners are preserved explicitly: an explicit brush modifier wins in
either call order, and a local value Reactor did not bind (a .Set setter, an
element property) is left alone. A live binding is not re-installed on an
ordinary render, only on a resource-refresh pass (Theme.NotifyResourcesChanged),
which needs re-resolution of an edited dictionary entry.

InteractionStates used to restore a themed border brush by clearing its local
value so the Style showed through. With the binding now being that local
value, the restore re-installs the binding instead.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 0008bac9-a08b-4ee8-9f96-505c6f6f28b0
…tes restore

Returning to the normal state wrote back the background and foreground brushes
captured when the states were set up, so a ThemeRef value stopped following
the theme after the first hover. A property Reactor theme-binds now gets its
binding re-installed instead, as the border brush already does.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 0008bac9-a08b-4ee8-9f96-505c6f6f28b0
PaneBackground(ThemeRef) went through the ThemeBindings pipeline, but the old
Style path had no mapping for it, so it silently did nothing. Map it to
SplitView.PaneBackgroundProperty. The modifier-table integrity test exempts
it, since it is SplitView-only sugar with no common brush modifier to agree
with.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 0008bac9-a08b-4ee8-9f96-505c6f6f28b0
- Clear dropped theme bindings before the element's setters and element
  properties run, so a brush written in place of a removed ThemeRef on the
  same render is kept.
- Hand over a binding that a setter or element property replaced during a
  render: Reactor stops owning it, so a key change, a resource refresh, or
  dropping the ThemeRef leaves the other writer's brush alone.
- InteractionStates restores a theme-bound background or foreground only
  after a state overrode it, keeps its brush when the ThemeRef is dropped
  mid-hover, and clears (instead of resurrecting) a binding removed while
  the state held the property.
- SplitView clears a removed PaneBackground brush so a ThemeRef replacing
  it takes effect.
- Selftests for pool return, partial removal, hand-over, modifier added over
  a bound ThemeRef, an unknown key, Foreground restore, and removal during
  hover. Update the StylingGallery tab, README, AOT doc, CHANGELOG refs and
  stale test comments that described the Style-based path.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 0008bac9-a08b-4ee8-9f96-505c6f6f28b0
- An explicit brush modifier on a layer sharing the control (a keyed Memo)
  takes ownership of a ThemeRef an inner layer bound, so a resource refresh
  doesn't rebind over it.
- A refresh or key change while an InteractionStates state holds a property
  keeps the state's brush; exiting installs the binding for the current key.
- Detect a setter or element-property takeover before ApplyModifiers, so the
  control's own RequestedTheme change in the same render can't hide it.
- InteractionStates: an explicit border brush that replaces a ThemeRef
  during a hover is what the hover restores; a theme-bound background or
  foreground keeps no cached normal brush, so a removed binding's brush is
  never written back; a state on an element with no normal brush clears
  its brush on exit.
- Narrow the SetThemeResourceBinding catches to ArgumentException and
  COMException; tidy test code flagged by code quality.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 0008bac9-a08b-4ee8-9f96-505c6f6f28b0
- Record the brush Reactor installed for each theme binding, so a binding a
  nested layer sharing the control (a keyed Memo, a flyout target) installs
  isn't mistaken for a setter takeover. A wrapper's ThemeRef keeps winning
  over the inner element's after a refresh.
- A brush modifier now suppresses a binding instead of forgetting it.
  Removing the modifier restores the binding, even when the keyed Memo's
  child doesn't update.
- Clear only the ThemeRefs the updating element itself dropped, so another
  layer's bindings on the shared control are left alone.
- InteractionStates captures the normal value when a state takes a property
  over, so an explicit brush that replaced a ThemeRef is what it restores. A
  failed theme restore releases the state's brush so a later render retries.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 0008bac9-a08b-4ee8-9f96-505c6f6f28b0
- InteractionStates restores a property only while it still holds the
  state's own brush. A brush another writer (a modifier, setter or element
  property) put there during the hover now stands when the hover ends.
- A ThemeRef declared while a state holds a property over no explicit
  normal brush is recorded and installed when the state ends.
- Skip the setter-takeover hand-over when the control's effective theme
  changed inside the window (a flyout target toggling its RequestedTheme):
  that's native re-resolution, not a takeover.
- Give the remaining theme-color fixtures a Light container so they don't
  depend on the app theme.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 0008bac9-a08b-4ee8-9f96-505c6f6f28b0
…n coverage

- Update the theming-tokens guide and the design-docs skill, which still described
  ThemeRef resolution as a ThemeDictionaries walk.
- Add a raw-read negative control and a missing-key scenario to the fresh-process probe.
- Send keys XML can't hold as written (control characters, tab/CR/LF, lone surrogates)
  to the dictionary walk instead of the probe.
- Cover a cached probe style applied for a theme that lacks the key.
- State the contrast-theme behavior as a property of the lookup.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…ing' into azchohfi-themeref-set-theme-resource-binding

# Conflicts:
#	CHANGELOG.md
…ghten tests and docs

- The dictionary-walk fallback skips XamlControlsResources, so it can never read WinUI's
  own theme entries from code.
- Document the fallback's plain-lookup step on ThemeRef.Resolve; drop the untested
  contrast-theme claim.
- Docs: ThemeRef.Resolve resolves for the theme passed as isDark, not the element's theme.
- Replace XmlConvert with an in-file XML Char check so trimmed apps don't keep System.Xml.
- The raw-read negative control asserts the poisoning itself; the app-only-key fixture
  asserts the actual brush.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…le (#1634)

ThemeResourceProbe now calls FrameworkElement.SetThemeResourceBinding for Tag on an
off-tree Border with the requested RequestedTheme and reads the value back. The
XamlReader-parsed style cache and BuildStyleXaml (with its quoting and XML escaping)
are gone, along with their unit tests. Keys markup could not hold now resolve through
WinUI; the dictionary-walk fallback stays for keys WinUI cannot resolve for a theme.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…nactive-theme' into azchohfi-themeref-set-theme-resource-binding

# Conflicts:
#	CHANGELOG.md
#	src/Reactor/Core/ThemeResourceProbe.cs
#	tests/Reactor.Tests/ThemeResourceProbeTests.cs
…-resolve-nonactive-theme

# Conflicts:
#	CHANGELOG.md
…nactive-theme' into azchohfi-themeref-set-theme-resource-binding

# Conflicts:
#	CHANGELOG.md
#	src/Reactor/Core/Reconciler.cs
- The fresh-process probe reports a skip in a Windows contrast theme, where Light and Dark
  share brushes, and the MSTest driver maps it to Inconclusive; the fixture skips only its
  distinctness check there.
- Drop the generic catch in the app-only-key fixture check.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…nactive-theme' into azchohfi-themeref-set-theme-resource-binding

# Conflicts:
#	tests/Reactor.AppTests.Host/SelfTest/Fixtures/ThemeRefResolutionFixtures.cs
The dictionary-walk fallback skips XamlControlsResources' own theme dictionaries when it is
Application.Resources itself, as in every Reactor app, not only when it is merged. A new
fresh-process scenario runs the fallback walk alone on real keys for the other theme and
checks that WinUI's entries stay correct.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

📦 Build metrics

Artifact sizes for f786408 vs the base branch (55fc2c8).

Packages (compressed .nupkg)

Artifact base PR Δ
Microsoft.UI.Reactor.nupkg 2.08 MB 2.09 MB +3.06 KB (+0.14%) ⚠️
Microsoft.UI.Reactor.Advanced.nupkg 523.7 KB 523.7 KB +9 B (0.00%) ≈
Microsoft.UI.Reactor.Devtools.nupkg 287.8 KB 287.8 KB -6 B (0.00%) ≈

Assemblies in Microsoft.UI.Reactor

Artifact base PR Δ
Reactor.Analyzers.dll 422.5 KB 422.5 KB +0 B (0.00%) ≈
Reactor.dll 2.82 MB 2.83 MB +1.50 KB (+0.05%) ⚠️
Reactor.Localization.Generator.dll 16.0 KB 16.0 KB +0 B (0.00%) ≈
Reactor.Wrappers.Abstractions.dll 10.5 KB 10.5 KB +0 B (0.00%) ≈
Reactor.Wrappers.Generator.dll 164.0 KB 164.0 KB +0 B (0.00%) ≈

Assemblies in Microsoft.UI.Reactor.Advanced

Artifact base PR Δ
Reactor.Advanced.dll 1.07 MB 1.07 MB +0 B (0.00%) ≈

Assemblies in Microsoft.UI.Reactor.Devtools

Artifact base PR Δ
Microsoft.UI.Reactor.Devtools.dll 787.0 KB 787.0 KB +0 B (0.00%) ≈

✅ smaller / ⚠️ larger / ≈ within noise. Sizes come from a Release dotnet pack on the CI runner: packages are the compressed .nupkg download size, assemblies the uncompressed DLL inside it.
workflow run.

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

🧪 Merged coverage

Coverage for f786408 vs the base branch (34953e5) — unit + selftest merged.

Metric base PR Δ
Line 88.79% 88.81% +0.02 pp ≈
Branch 46.08% (18281/39669) 45.84% (18276/39865) -0.24 pp ⚠️

✅ higher / ⚠️ lower / ≈ within noise. Δ is in percentage points; coverage is unit + selftest merged (Debug x64) on the CI runner. Cobertura reports attached to the workflow run as artifacts.

…nactive-theme' into azchohfi-themeref-set-theme-resource-binding
Base automatically changed from azchohfi-fix-themeref-resolve-nonactive-theme to main November 20, 2026 22:58
@azchohfi
Alexandre Zollinger Chohfi (azchohfi) changed the base branch from main to azchohfi-set-theme-resource-binding November 20, 2026 22:59

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants