Skip to content

Spec 066 layer 1: share implicit animation keys through ImplicitAnimationSlots - #1654

Open
Alexandre Zollinger Chohfi (azchohfi) wants to merge 16 commits into
azchohfi-spec-066-layer-v-validation-ledgerfrom
azchohfi-spec-066-layer-1-implicit-anim-slots
Open

Alexandre Zollinger Chohfi (azchohfi) wants to merge 16 commits into
azchohfi-spec-066-layer-v-validation-ledgerfrom
azchohfi-spec-066-layer-1-implicit-anim-slots

Conversation

@azchohfi

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

Copy link
Copy Markdown
Collaborator

Summary

Adds ImplicitAnimationSlots, the one owner of Visual.ImplicitAnimations (spec 066 §6). .LayoutAnimation(), .Animate(), the implicit transitions (the XAML path and the compositor fallback) and the two ambient reorder-move sites now claim and release keys per property instead of replacing the whole collection. The Update gate now includes the old element's transitions, so a removed transition is released.

  • Claims are keyed by key, feature and chain slot. Between features LayoutAnimation > .Animate() > transition > ambient move, and releasing the winner restores the next claim. Re-claiming the winner republishes it, so a reused transition instance with a new Duration takes effect.
  • The slot is the layer's depth in the shared-target chain (a keyed Memo, a flyout, or any decorator that forwards its child's control), 0 = outermost. Update counts depth from the outermost layer. Mount detects a forwarded control from the Mount frame that claimed on it, not from OwnsControl, so a decorator without a source target numbers its child the same way. A replaced control is renumbered once, by the layers above the Mount that handled it.
  • .Animate() channels dropped in an update are released before setters run, as before. A claim that takes over a released key (for example a retained transition) comes back only after the outermost layer sharing the control has written its values, so those writes still jump. The restore also happens when the update throws.
  • The release paths that used to take the visual still do, so a facade Translation a setter wrote in the same update keeps moving to the visual.
  • The claims logic is a pure state machine behind IImplicitAnimationSink, unit-tested headless.
  • Transitions still use XAML while the visual hasn't been handed out (layer 2 moves them to the compositor). A transition claim holds the XAML transition, and the sink writes it to XAML or, once WinUI refuses that, as a compositor key.
  • Docs: new "Shared implicit keys" section in animation-pipeline.md.dt, compiled through the pipeline. It notes that a transition plus .Animate()/.LayoutAnimation() in the same mount still throws ([Bug] XAML implicit transitions crash with any compositor modifier (LayoutAnimation, Animate, Transition, InteractionStates, Keyframes) #1623, layer 2).

Left for later layers, as planned:

Ownership leftovers from #1646, evaluated and not fixed here because they're not implicit-key ownership:

  • A Flyout and its target that use the same keyframe name still share one trigger slot. The trigger table is keyed (UIElement, name), and shared targets deliberately share name slots today.
  • ReleaseRemovedKeyframeChannels still runs its deferred reset without a controller check in the BeforeHandler/BeforeSharedTarget stages (only BeforePlayback passes the deferred controller).

Linked issue / spec

Fixes #1625
Relates to #1626 (fixes its XAML and compositor-fallback arms; layer 2 finishes the Background arm)
Implements docs/specs/066-transforms-on-composition-visual.md §6 (§13 row 1). Part of #1630.

Test plan

  • Unit: tests/Reactor.Tests/Animation/ImplicitAnimationClaimsTests.cs (11 cases: precedence, restore, non-owner release, last release, replace in place, republish of a re-claimed winner, slot order, deferred restore, ReleaseAll). dotnet test tests/Reactor.Tests --no-build -p:Platform=x64 --filter-class "*ImplicitAnimationClaimsTests*" --filter-class "*TransformsMatrixTests*": passed 62/62 (before the last ledger merge). TransformsMatrixTests alone (REACTOR_TRANSFORMS_BASE_REF set to the V branch) after recording: passed 53/53.
  • Selftests in ImplicitAnimationSlotsFixtures.cs (13 fixtures): dotnet run --project tests/Reactor.AppTests.Host --no-build -c Debug -p:Platform=x64 -- --self-test --filter "ImplicitSlots": 0 failures.
  • Mutation checks, each turned at least one check red: Update depth forced to 0, no shift on a replaced control, no shift on mount, the Update gate narrowed back to the new element, ambient move ranked above layout.
  • Neighbouring selftest families on the final code (AnimRemove, AnimCombo, Animate_, LayoutAnim, TransformHandoff, Flyout, Stagger, KF, AAF, ModifierTransform_Transitions): 0 failures. A full local corpus run on this branch and on the base gave the same failures, all wall-clock or scroll fixtures that fail because this machine doesn't render compositor frames in real time.
  • CI on 344e6c5: every check passes, including Build solution (Release), Unit Tests, Selftests, AOT Selftests, Packaged Selftests, E2E, AOT Trim Proof and the full Transforms matrix.
  • Transforms matrix ledger: recorded on a hosted runner (Transforms matrix run 44909740431, 0 failures) after merging layer V's final ledger (13f9b92). All 84 differences from V's ledger are the removeModifier residue of the Opacity, Scale, Rotation and Translation transition cases (xaml=X -> xaml=-), declared in transforms-ledger.expected.json as fixes [Bug] Removing .OpacityTransition()/.ScaleTransition()/.RotationTransition() never clears the transition #1626. V's new settled opacity fields show no layer-1 differences. TransformsMatrixTests passes 57/57. The matrix has no [Bug] ApplyLayoutAnimation replaces the visual's ImplicitAnimations, dropping implicit-transition fallback keys #1625 case, because it mounts a feature together with its transition (spec §12.1 F), so [Bug] ApplyLayoutAnimation replaces the visual's ImplicitAnimations, dropping implicit-transition fallback keys #1625 is covered by the selftests.
  • Known flake, not caused by this change: TransformKeyframes_OpacityLoopStarted/Retained (in ModifierTransform_Transitions) also fails on base-branch CI runs without this change, for example run 44879123765 on the layer V branch and run 44832337755 on the ANIM_004 branch.

Risk / breaking changes

No public API change; all new types are internal. Behaviour changes:

  • Removing a transition modifier now removes the transition.
  • When two features animate the same property, removing the winner restores the other one instead of leaving none.
  • An ambient reorder move no longer wipes the element's other implicit keys, and a declared .LayoutAnimation()/.Animate(Offset) curve wins over it.
  • A control whose claims published to the visual gets its implicit collection cleared when it leaves Reactor ownership (ClearElementTag, DetachReactorState).

…66 layer 1)

LayoutAnimation, .Animate(), the implicit transitions and the ambient move
animations now claim and release Visual.ImplicitAnimations keys through one
owner, so adding or removing one feature never drops another's key (#1625).
The Update gate includes the old element's transitions, so a removed
transition is released on the XAML path and on the compositor fallback
(#1626, except Background, which layer 2 handles).

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

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Limit the shared-keys docs to the orders that work before layer 2 (#1623),
split the Size row out of the precedence table, and cover the update depth
of a flyout chain, the replaced-control path and the ambient move claim.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@azchohfi Alexandre Zollinger Chohfi (azchohfi) added the transforms-matrix-record Record the spec 066 transforms ledger on a hosted runner and upload it as an artifact label Nov 21, 2026
@github-actions

github-actions Bot commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

📦 Build metrics

Artifact sizes for 344e6c5 vs the base branch (13f9b92).

Packages (compressed .nupkg)

Artifact base PR Δ
Microsoft.UI.Reactor.nupkg 2.09 MB 2.10 MB +4.85 KB (+0.23%) ⚠️
Microsoft.UI.Reactor.Advanced.nupkg 528.6 KB 528.6 KB +12 B (0.00%) ≈
Microsoft.UI.Reactor.Devtools.nupkg 287.9 KB 287.9 KB +1 B (0.00%) ≈

Assemblies in Microsoft.UI.Reactor

Artifact base PR Δ
Reactor.Analyzers.dll 437.5 KB 437.5 KB +0 B (0.00%) ≈
Reactor.dll 2.83 MB 2.84 MB +6.50 KB (+0.22%) ⚠️
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.08 MB 1.08 MB +0 B (0.00%) ≈

Assemblies in Microsoft.UI.Reactor.Devtools

Artifact base PR Δ
Microsoft.UI.Reactor.Devtools.dll 787.5 KB 787.5 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 21, 2026 •

Copy link
Copy Markdown
Contributor

🧪 Merged coverage

Coverage for 344e6c5 vs the base branch (28a8722) — unit + selftest merged.

Metric base PR Δ
Line 88.70% 88.73% +0.03 pp ≈
Branch 45.68% (18380/40239) 45.65% (18439/40393) -0.03 pp ≈

No coverage change beyond the noise floor. ✅

✅ 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.

…tion-ledger' into azchohfi-spec-066-layer-1-implicit-anim-slots
Recorded on a hosted runner (Transforms matrix run 44884508798). The only
differences from layer V's ledger are the removeModifier residue of the XAML
transition cases, declared in transforms-ledger.expected.json (fixes #1626).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@azchohfi Alexandre Zollinger Chohfi (azchohfi) added transforms-matrix Run the spec 066 transforms matrix against the ledger (Transforms matrix workflow) and removed transforms-matrix-record Record the spec 066 transforms ledger on a hosted runner and upload it as an artifact labels Nov 21, 2026
@azchohfi
Alexandre Zollinger Chohfi (azchohfi) marked this pull request as ready for review November 21, 2026 08:44
@azchohfi Alexandre Zollinger Chohfi (azchohfi) added the agent-preparing Agent is addressing feedback or completing required validation and CI label Nov 21, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Unresolved animation lifecycle defects leave visual translations out of sync with setters and retain stale animation claims after decorator updates or control returns.

4 open issues
What changed in this PR

Implements spec 066 layer 1 by centralizing implicit-animation key ownership in Reactor’s animation pipeline. This addresses #1625 and the XAML/compositor removal paths of #1626, while leaving the #1623 handoff limitation for layer 2.

Changes:

  • Adds per-property claims with feature precedence, shared-target slots, and restoration of lower-priority animations.
  • Routes layout, property, transition, and ambient-move animations through the shared owner.
  • Adds regression tests, updates transform baselines, and documents behavior and remaining limitations.
File Description
tests/​Reactor.Tests/​Animation/​ImplicitAnimationClaimsTests.cs Tests claim precedence, restoration, replacement, and release.
tests/​Reactor.AppTests.Host/​SelfTest/​SelfTestFixtureRegistry.cs Registers seven new animation fixtures.
tests/​Reactor.AppTests.Host/​SelfTest/​Fixtures/​ImplicitAnimationSlotsFixtures.cs Exercises transition removal, shared targets, and ambient moves.
tests/​Reactor.AppTests.Host/​SelfTest/​Baselines/​transforms-ledger.json Records cleared transitions after modifier removal.
tests/​Reactor.AppTests.Host/​SelfTest/​Baselines/​transforms-ledger.expected.json Declares expected baseline changes for #1626.
src/​Reactor/​Core/​Reconciler.Update.cs Tracks claim slots and releases removed animation declarations.
src/​Reactor/​Core/​Reconciler.Mount.cs Assigns shared-target claim slots during mount.
src/​Reactor/​Core/​Reconciler.cs Integrates claims into animation application and cleanup.
src/​Reactor/​Core/​ChildReconciler.cs Preserves existing keys during ambient reorder animation.
src/​Reactor/​Animation/​ImplicitAnimationSlots.cs Implements claim arbitration and XAML/compositor publication.
docs/​guide/​animation-pipeline.md Publishes generated shared-key documentation.
docs/​_pipeline/​templates/​animation-pipeline.md.dt Documents precedence, restoration, and the handoff caveat.
CHANGELOG.md Records animation ownership and transition-removal fixes.

Review effort: Balanced

Comment thread src/Reactor/Core/Reconciler.Mount.cs Resolved
Comment thread src/Reactor/Core/Reconciler.cs Resolved
Comment thread src/Reactor/Core/Reconciler.cs Resolved
Keep the facade migration on the release paths that used to take the visual
(ClearLayoutAnimation, ClearPropertyAnimation, and transitions once their keys
live on the visual), so a setter's Translation still reaches the visual.

Detect a forwarded control from the Mount frame that claimed on it instead
of ownsControl, so a decorator without a source target numbers its child's
slots as Update does, on mount and on replacement.

Defer restoring a claim that takes over a key .Animate() releases before the
setters run, so those writes keep jumping, as they did before.

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

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Unresolved issues allow layout animations to persist after declaration removal, retain obsolete element graphs, and leave fallback animation durations stale after same-instance transition updates.

1 open issue
2 previously missed issues

In code that hasn't changed since last review

Medium severity Refresh fallback animations when transition duration changes

src/​Reactor/​Animation/​ImplicitAnimationSlots.cs:60

On an already handed-out visual, changing a retained Vector3Transition instance's Duration from 300 ms to 900 ms and forcing an update leaves its fallback animation at 300 ms: reference equality skips rebuilding the animation with the new duration. Refresh effective fallback transition claims even when the transition instance is unchanged, while preserving hidden claims and deferred restoration. Add a selftest for a same-instance duration change.

Medium severity Expire Move claims after the animated layout completes

src/​Reactor/​Core/​ChildReconciler.cs:1374

After an ambient reorder of a row with .LayoutAnimation(), removing that declaration in a later non-animated render restores the old Move claim, so ordinary layout changes keep animating without an active transaction. Expire the Move claim after the relevant layout/move completes, preserving declared claims, and cover reorder followed by declaration removal outside the transaction. The same issue occurs in src/Reactor/Core/Reconciler.Update.cs:1743.

4 resolved since last review

Review effort: Balanced

Comment thread src/Reactor/Core/Reconciler.Update.cs Resolved
Hold the last stamped Mount element weakly, so the replacement check never
keeps an element graph alive.

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

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Unresolved transition-handling issues leave reused mutable transitions with stale durations and restore deferred transitions too early during nested Flyout updates, causing unintended animation.

No open issues 🎉

2 previously missed issues

In code that hasn't changed since last review

Medium severity Reapplied transition instances retain stale compositor duration

src/​Reactor/​Animation/​ImplicitAnimationSlots.cs:64

On a handed-out visual, reusing a Vector3Transition in .ScaleTransition(t) or .TranslationTransition(t) after changing t.Duration leaves the compositor key at its original duration, even when the render reaches Update. Reference equality skips publishing the mutable object's new settings. Refresh the effective compositor transition when that instance is reapplied, without refreshing hidden claims with different values, and cover a duration change on a reused instance.

Medium severity Deferred scale transitions flush too early during nested Flyout updates

src/​Reactor/​Animation/​ImplicitAnimationSlots.cs:137

When a Flyout removes .Animate(..., AnimateProperty.Scale) while changing its scale, its target can restore a deferred transition before the outer modifier runs, making that write animate unexpectedly. Child reclaims, hidden-claim releases, and child flushes can all restore the key too early. Preserve deferrals across nested claim changes and flush only after the outermost shared-control update finishes its writes; cover both child reclaims and releases.

1 resolved since last review

Review effort: Balanced

Republish a re-claimed winner even when it's the same instance, so a reused
transition with a new Duration rebuilds its compositor key. Keep a deferred
key held back until the outermost layer sharing the control has written its
values, so a flyout target's re-claim can't bring a transition back before
the flyout's own modifier write.

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

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Human assessment is needed because unpublished moderate findings identify animation-claim tracking errors in forwarding-layer replacements that can leave removed animations installed or remove the wrong animation.

No open issues 🎉

Review effort: Balanced

Record the outermost Mount that handled a control's claims on the claims
themselves, so the replaced-control path can't renumber claims a decorator's
own Mount already shifted. Cover nested forwarders across a replacement.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…tion-ledger' into azchohfi-spec-066-layer-1-implicit-anim-slots

# Conflicts:
#	tests/Reactor.AppTests.Host/SelfTest/Baselines/transforms-ledger.json
@azchohfi Alexandre Zollinger Chohfi (azchohfi) added the transforms-matrix-record Record the spec 066 transforms ledger on a hosted runner and upload it as an artifact label Nov 21, 2026
Recorded on a hosted runner (Transforms matrix run 44894365610). The only
differences from layer V's ledger are the 84 removeModifier residue entries
already declared in transforms-ledger.expected.json (fixes #1626).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@azchohfi Alexandre Zollinger Chohfi (azchohfi) removed the transforms-matrix-record Record the spec 066 transforms ledger on a hosted runner and upload it as an artifact label Nov 21, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

The cross-cutting WinUI ownership and lifecycle changes require maintainer verification because native runtime behavior could not be independently validated and the Release build remains unconfirmed.

No open issues 🎉

Review effort: Balanced

…-slots

# Conflicts:
#	tests/Reactor.AppTests.Host/SelfTest/Baselines/transforms-ledger.json
@azchohfi Alexandre Zollinger Chohfi (azchohfi) added the transforms-matrix-record Record the spec 066 transforms ledger on a hosted runner and upload it as an artifact label Nov 21, 2026
Recorded on a hosted runner (Transforms matrix run 44909740431). The only
differences from layer V's final ledger are the 84 removeModifier residue
entries already declared in transforms-ledger.expected.json (fixes #1626);
the settled opacity fields match V's.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@azchohfi Alexandre Zollinger Chohfi (azchohfi) removed the transforms-matrix-record Record the spec 066 transforms ledger on a hosted runner and upload it as an artifact label Nov 21, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

An exceptional update can leave a deferred opacity restore unpublished on a retained control, causing retries to keep opacity animation disabled; exception-safe cleanup and a same-control retry regression are needed.

1 open issue

Review effort: Balanced

Comment thread src/Reactor/Core/Reconciler.Update.cs Resolved
Flush deferred implicit keys in the outermost layer's finally, so an update
that throws after .Animate() released a key still restores the transition
it held back.

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

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Human assessment is needed because nested forwarding decorators can misnumber animation claims during leaf replacement, causing subsequent removal to leave an Offset installed.

No open issues 🎉

1 resolved since last review

Review effort: Balanced

A layer that claims on a replaced control now records a fresh frame and
itself as the claims' owner, as a Mount layer does, so the layers above
shift its claims even when the replaced leaf claimed nothing.

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

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Human assessment is needed for an unpublished transition-ordering edge case that can animate a flyout’s scale write intended to jump when its animation claim is removed as the target adds a scale transition.

No open issues 🎉

Review effort: Balanced

@azchohfi Alexandre Zollinger Chohfi (azchohfi) added ready-for-review Agent work and technical checks complete; awaiting review, not approval or merge and removed agent-preparing Agent is addressing feedback or completing required validation and CI labels Nov 21, 2026

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

ready-for-review Agent work and technical checks complete; awaiting review, not approval or merge transforms-matrix Run the spec 066 transforms matrix against the ledger (Transforms matrix workflow)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants