Repository navigation
Description
Feature name
Shared internal animation library for every toolkit animation
Link to discussion
None: proposed by a maintainer (TheCodeTraveler) as a follow-up to #1232.
Progress tracker
- Android Implementation
- iOS Implementation
- MacCatalyst Implementation
- Windows Implementation
- Unit Tests
- Samples
- Documentation
Summary
#1232 gives the toolkit's animation classes guards that took many review rounds to get right: property ownership, cancellation, interrupts, system animations off, the UI thread and a Windows projection bug. The toolkit's other animations don't use them. TouchBehavior, ImageTouchBehavior, BackgroundColorTo, the generated TextColorTo, ProgressBarAnimationBehavior and StateContainer each drive .NET MAUI's animation API their own way, and TouchBehavior fights the new animations on the same view. This proposal moves every guard into one internal library (CommunityToolkit.Maui.Animations.Engine), moves every toolkit animation onto it, enforces that in the build, and adds an instructions file that tells contributors and AI agents why each guard exists. App code doesn't change, and the only new public API is one hidden entry point for the generated TextColorTo (D6). It is a follow-up PR after #1232 merges; each change to v17 behavior waits for a maintainer's decision (D1-D12).
Motivation
Links to #1232's code point at its revision ab28da4; #1232 later renamed some members to follow the toolkit's naming conventions (AnimatedPropertyTracker.For → GetOrCreate, End → EndAnimation, HandedOverToApp → RecordHandOverToApp, FindPropertiesTakenOverByTheApp → TryFindPropertiesTakenOverByTheApp).
The gap: four engines, one set of guards
| Engine | Used by | Guards |
|---|---|---|
BaseAnimation's round trips, played one part at a time (L58-L118) |
Fade, Scale, Rotate, FlipHorizontal, FlipVertical | all of #1232's |
| One keyframe run per view (L61-L136) | Bounce, Heartbeat, RubberBand, Shake, Swing, Tada, Wobble | all of #1232's |
GestureManager's own To animations (MAUI calls such as FadeToAsync, TranslateToAsync and an Animate call for scale, which move a property from its current value to a target over time) and direct writes (L561-L1291) |
TouchBehavior, ImageTouchBehavior |
two, re-derived on its own (L1236-L1291); NaN skip for scale only |
Raw Animation.Commit, FadeToAsync, ProgressTo |
BackgroundColorTo, generated TextColorTo, ProgressBarAnimationBehavior, StateContainer |
none |
GestureManager,ColorAnimationExtensions,ProgressBarAnimationBehaviorandStateContainerare byte-identical in 17.0.0 and at Add 11 Animations for AnimationBehavior #1232's head, so their links point at the release.- Add 11 Animations for AnimationBehavior #1232 changed the animation code in 51 product commits and more than 70 test commits after 17.0.0. Each guard answers a bug a review found. Copying them into five more features means five more places to keep in step, and nothing stops the next feature from calling MAUI's animation API directly.
Bugs this causes
Measured with unit-test probes at #1232's head, except rows marked "code".
| # | Repro | Expected | Actual | Cause |
|---|---|---|---|---|
| 1 | TouchBehavior with DefaultScale 0.8, PressedScale 1.6; hold a press while ScaleAnimation runs (press duration 0 or 160 ms) |
stays at 1.6 | ends at 0.8 | the scale uses a private handle, "SetScale" (L672-L691), so ScaleAnimation's way back can't see it |
| 2 | Press during Heartbeat or Tada (scale), or Tada, Swing or Wobble (rotation), default duration 0 | the press shows | hidden every frame, then undone when the seeker restores the view | the direct write (L672-L678) has no handle; a seeker yields only to a running MAUI To animation (L138-L151) |
| 3 | Animated release (160 ms, 1.6 → 0.8) whose Command starts Heartbeat |
ends at 0.8 | stuck at 1.52 | the release has written its first frame when Command runs; the seeker takes 1.52 as its original, overwrites the release ("SetScale", which it doesn't abort) every frame, and restores 1.52 at its end |
| 4 | Translation configured; an animated state change that keeps the same translation while Bounce (Distance 30) runs (probe: MAUI TranslateToAsync as GestureManager calls it) |
Bounce's frames | dips to −33.0, below Bounce's −30 floor | the translation animation starts from the value Bounce composed (L776; MAUI reads the start from the view, L484-L485), so the offset counts twice (L64-L79, L108) |
| 5 | A custom easing returns NaN or infinity (code) | the step is skipped | on Android (target API 28+), an infinite Scale (ScaleAnimation, TouchBehavior) or a NaN ScaleX or ScaleY (RubberBand) throws an uncaught IllegalArgumentException from MAUI's ticker (View.java); most other NaN values reach the platform view |
only TouchBehavior's scale skips NaN, not infinity (L683-L686); MAUI's *ToAsync writes every step (L352) |
| 6 | The app calls CancelAnimations() while TouchBehavior animates a release (code) |
every property behaves alike | scale keeps going; opacity, rotation and translation stop mid-way until the next state change | CancelAnimations aborts MAUI's nine names only (L23-L39) |
| 7 | Tap a view with TouchBehavior (PressedScale) and AnimationBehavior (AnimateOnTap) running ScaleAnimation, FadeAnimation or Heartbeat (code) |
the same result in either event order | the release and the animation fight; the platform's event order decides | release and tap are separate events (Android: TouchBehavior's own Touch handler, L65) |
| 8 | Windows: PressedRotationY 30 with DefaultScale 0.9; press, then release (code) |
flat again | stays slightly turned | MAUI keeps its last PlaneProjection when RotationX/Y return to 0 with another transform set (L41-L67); #1232 clears it for the flips only (L10-L23) |
| 9 | The app sets CurrentTouchState from a background thread, duration 0 (code) |
writes on the UI thread | writes view properties on the calling thread (WinUI throws) | direct writes such as L611-L616 run where the state change continues |
Why the guards exist
Each guard answers a .NET MAUI behavior that broke a toolkit animation during #1232's reviews. The main ones:
- Use MAUI's own handle names. A same-name start aborts the running animation (L269-L298), and
CancelAnimationsaborts by name. A private name hid TouchBehavior's scale from everything (bug 1). - Abort first, then take a tracker id. Code after an aborted
awaitresumes inside MAUI's abort loop (L231-L254) and can start a run there (801ea02). - Never pass the token to MAUI. MAUI turns a token cancelled off the UI thread into a queued
AbortAnimation(name)(L71-L79), which stopped a newer run that had taken the name (6109948). - End the run before
Task.Yield, decide after it. An aborted animation'sawaitresumes inline, inside the abort (noRunContinuationsAsynchronously, L46), before whatever takes over has started (a4d9c1a). - Return to the original only when nothing took over (latest run, handle idle, value unchanged) (c0d4d11, 79320b4, 3099245).
- System animations off. MAUI jumps every animation to its end and reports it aborted (L369); the To animations took that for an interruption (f7ff37d).
- Start on the view's dispatcher (782edd8), and let
AnimationBehaviorstop and start in one UI-thread turn (79f84c8). - Compose translation.
TranslateToAsyncdrives both axes under one name (L482-L490), so it can't be stopped for one axis; seekers add their offset instead (f98672a, 51e687a, 890ef17, ea40bc7). - Clear MAUI's stale Windows projection after RotationX/Y return to 0 (17ba83f, 3e03359, 090ae4d).
- Never abort the app's own animation where v17 didn't. An app loop that restarts its
ScaleToAsyncafter the abortedawaitrestarted 499 times inside oneAbortAnimationcall in a capped probe; uncapped, the UI thread hangs.
Every guard, what it prevents and the commit that added it
BA = BaseAnimation, APT = AnimatedPropertyTracker, KAE = KeyframeAnimationExtensions, KT = KeyframeTarget, FP = FlipProjection, AB = AnimationBehavior. Commits are on #1232.
| ID | Guard | Prevents | Commit |
|---|---|---|---|
| BA1 | Public doubles finite and bound one way (L37-L38) | NaN or infinity in the platform transform every frame | fc517a4, 2519aa2 |
| BA2 | Abort the handle, then stop the seeker (L50-L56) | a run started inside the abort taking the newest id; the outer run stayed at its target | 801ea02, 6b3fd8c |
| BA3 | An interrupted part ends the run | the next part interrupting whatever took over | c0d4d11 |
| BA4, BA5 | Start the MAUI animation, then register the token; it aborts only while its own part runs, on the dispatcher (L58-L71, L120-L142) | a stale or queued abort stopping a newer run that took the name | 6109948 |
| BA6 | A cancelled part returns the view only if still the latest run, then throws | overwriting a newer run's value | fc517a4, c0d4d11 |
| BA7 | System animations off: "aborted" counts as completed (L91-L95) | To animations stuck at their target under Reduce Motion | f7ff37d, c0d4d11 |
| BA8-BA11 | End the run before Task.Yield; after it, restore only if latest, handle idle and value unchanged; record what the run left (L97-L117) |
losing the app's value set during CancelAnimations; undoing a takeover; the next run returning to a stale value |
a4d9c1a, c0d4d11, 3099245, 79320b4 |
| BA12 | Start on the view's dispatcher with an async method (L144-L151) | writes on the thread pool (WinUI throws); DispatchAsync(Func<Task>) faulting a cancel |
782edd8 |
| BA13, BA14, BA16 | Throw for a null view at the call; check the token before stopping anything; end the run in a finally |
a faulted Task instead of a throw; a pre-cancelled call stopping the running animation; a run left registered | 2560b69, 4b3c8ac |
| BA15, BA17 | Length is the whole round trip; Rotate turns from the tracked original |
v17's fade taking twice Length (discussion #1231); a re-trigger ending elsewhere |
48744eb, 2f16128 |
| APT | One tracker per view and property; runs end by id; only the latest acts; the original is taken only at rest (L36-L41) | a run that starts mid-animation returning the view partway | 4b3c8ac (generalizes v17's fade tracker) |
| KAE1, KAE2 | One run per view; a new run aborts the old one; a To animation of one of its properties stops it | runs reading each other's frames; both writing after the To task ended | fc517a4, 6b3fd8c |
| KAE4-KAE6 | The dispatched start can't be cancelled and skips itself if cancelled while waiting; the token aborts only its own run | stopping an unrelated animation; a stale token aborting a newer run | fc517a4, 93d7a8f |
| KAE7 | Abort the property's To animation at the start, except TranslateToAsync (L175-L199) |
a To animation finishing after the restore; a one-axis abort stranding the other axis | f98672a |
| KAE9, KAE14, KAE15 | Record the run after its keyframes exist; end only your own record; leave the taker's properties alone | Swing left untracked or its anchor undone by a nested run | 418dbe1, 6b3fd8c, 253f9d6 |
| KAE10, KAE11, KAE16 | Each tick except the first inside Commit, check by handle whether the app's To animation took over; hand its properties over (L94-L105) |
the seeker hiding the app's animation, then undoing its target; an orphan animation | 1919770, 67510c7 |
| KAE12, KAE13, KAE17 | The restore faults the run's Task instead of throwing, restores every property and ends every tracker; restore if the start throws | a PropertyChanged exception escaping into MAUI's ticker; a moved anchor left behind |
5ac6e85, fc517a4 |
| KT1-KT4, KAE18 | Seekers add their offset to another writer's translation, detect it by the stored box, re-compose on BatchCommitted (not during their own write), stop composing before the restore (L64-L100) |
overwriting a TranslateToAsync; an equal write going unseen; the offset vanishing; an endless loop |
51e687a, 890ef17, ea40bc7 |
| SK5 | Bounce keeps writing through its keyframe gap | dropping to rest at its peak under a TranslateToAsync |
a7a014d |
| FP1-FP4 | Clear only MAUI's PlaneProjection, on the container view, after RotationX/Y return to 0 (L10-L27) |
a view left slightly turned; an app projection removed | 17ba83f, 3e03359, 090ae4d |
| AB1-AB4 | Abort the seeker handle too; stop and start in one UI-thread turn; swallow OperationCanceledException only for the command's own token; await inside the try (L125-L134, L175-L191) |
a seeker moving the new start value; a frame at rest; an async void crash; defeating ShouldSuppressExceptionsInAnimations |
fc517a4, 79f84c8, 96f81e7 |
The unit tests run on a mock ticker with 16 ms virtual frames and one Fire loop (dddd59e, f229ddc, a9a29f2), use exact per-frame oracles, and each guard has a named test. The implementing PR adds a mutant per guard (Test plan).
Related issues
- Related to [Proposal] Add possibility to configure animation behavior TouchBehavior #2433 (and [BUG] TouchBehavior cancel animation even though it is just short tap #2063, where it started): the same
TouchBehaviorstate-change code. This proposal keeps v17's rule that a state change stops the previous state's own animation, and adds noAnimationShouldFinishoption;StateAnimationwould be the one place to add it. - Related to [Proposal] Compound Animations #182: the attention seekers in Add 11 Animations for AnimationBehavior #1232 implement it, and the library takes over their coordination.
- Related to TextColorToGenerator generates code referencing internal types from Microsoft.Maui.Controls, causing CS0122 #3160 (closed): the generated
TextColorTocompiles in the app and can use only public API, which is why D6 needs a public, hidden entry point. - Related to [Proposal] Expander animation #2521 (approved):
ExpanderAnimationBehaviorwould animateHeightRequest. Under this proposal it goes through the library as a new property (AnimationHandle, "Adding a property" in the rule), and RS0030 rejects a directAnimation.Commit.
Detailed Design
Prerequisite and scope
- Depends on Add 11 Animations for AnimationBehavior #1232. The implementing PR branches from
mainafter Add 11 Animations for AnimationBehavior #1232 merges (C0) and reuses the stall-proof device-test helpers that Add 11 Animations for AnimationBehavior #1232's stall fix adds before it merges. - Keeps every public API, every v17 behavior that no decision below changes, trim and NativeAOT safety, and
TouchBehavior's state machine (only its animation code moves). - Order: extract with zero behavior change (the 13,205 unit tests and every device suite prove it); harden the TouchBehavior device tests; move each feature with v17 behavior; then one commit per approved behavior change, each with a test that fails without it.
Layout
- Folder
src/CommunityToolkit.Maui/Animations/Engine/, namespaceCommunityToolkit.Maui.Animations.Engine. Every type isinternal. - A folder
.editorconfigmakes CS8509 and CS8846 (non-exhaustive switch expression; CS8846 when onlywhenarms cover a case) errors and exempts the folder from RS0030 (the build guard below). Neither is in the repo'sWarningsAsErrors(L219-L246). InternalsVisibleTocovers only the five test assemblies (L266-L272). The namespace isn't mapped to XAML.BaseAnimation's helpers areprivate protectedtoday, so moving them changes no public surface.BaseAnimationkeepsLength,Easing,AnimateandIsFinite.
Types
| Type | Responsibility | Comes from | Guards |
|---|---|---|---|
AnimationHandle |
The one handle registry: sealed with a private constructor, so a feature can't invent a name. GetDefault, GetAll, IsSharedWithAnotherProperty, IsStoppedByCancelAnimations; named KeyframeRun, TextColor, Layout |
GetToAnimationHandle and the name literals in five features |
KAE1, KAE7, KAE11 |
AnimationDispatch |
RunOnDispatcherAsync, RunOnDispatcherNowOrLater |
AnimateOnDispatcherAsync and three "dispatch if required" copies |
BA5, BA12, KAE5 |
SystemAnimations |
AreOn(view) |
BaseAnimation |
BA7 |
AnimatedPropertyTracker |
Ownership per view and property; adds TryGet, OriginalValue, StartAnimationAndSetOriginalValue, TryRetarget, TryGetValueTheRunsLeave |
moved | APT |
ValueAnimation |
The one animation that moves a property from a start value to a target, in MAUI's exact shapes: AnimateToAsync(..., ValueAnimationCurve), TranslateToAsync, AnimateColorToAsync; skips non-finite steps (D4) |
MAUI's own animation methods; v17 BackgroundColorTo |
NaN skip |
PropertyAnimations |
TryAbort, StopAnimationsOf, TakeOver, Retarget, StopAll, DescribeActivity, IsRunning, GetBaseTranslation, WriteTranslation |
StopAnimationsOf, AnimationBehavior's stop, GM's abort-then-write pairs |
BA2, AB1 |
RoundTrip |
AnimateOutAndBackAsync (Fade, Scale, flips), TurnAsync (Rotate): token check, projection capture, stop, tracker, the way out and back (or the turn), live original, settle, EndAnimation |
the skeleton five classes share (Fade, Scale, Rotate, FlipHorizontal) | BA2, BA14-BA16, FP3 |
OneWayAnimation |
TryRunAsync (one part of a round trip); TryRunToStateAsync, TryRunTranslationToStateAsync (state-driven, no token) |
TryAnimateAndRestoreIfStoppedAsync |
BA3-BA11 |
StateAnimation |
Applies the state rules below; one per state-driven feature and view | GM's per-setter tails | S1-S4 |
AnimationGroup |
The animations one state update started, aborted together, synchronously, while still running; HasAborted; IsRunningOn |
GM's StateAnimations (L1236-L1291) |
abort only while ours |
PropertyActivity |
DescribeActivity's answer: an internal closed record with sealed cases ToolkitRun, OtherAnimation, Nothing |
new | C# 15 exhaustiveness |
KeyframeAnimationExtensions, KeyframeTarget |
Seeker coordination and translation composition; add TryGetComposedBase, HandOver, Retarget, SetValueToRestore |
moved | KAE, KT |
RotationProjection |
Windows stale-projection cleanup; adds GetAppProjectionOrNull |
renamed from FlipProjection |
FP |
Rules the primitives encode
Handles
- A toolkit To animation runs under MAUI's own name by default (
GetDefault(OpacityProperty)isFadeToAsync). MAUI then treats it like its own*ToAsync: a same-name start replaces it, andCancelAnimations()stops it. IsStoppedByCancelAnimationsis true for exactly MAUI's nine names (L23-L39), not forBackgroundColorTo,TextColorTo, the seeker handle or MAUI'sProgress(L64-L71).- An explicit handle is checked:
ArgumentExceptionwhen it doesn't write the property, or (inValueAnimation.AnimateToAsync) when it is shared. This keeps v17's"SetScale"expressible until D1 is decided. - Operations that stop or hand over a property iterate
GetAll(property)and skip shared handles: abortingTranslateToAsyncfor one axis strands the other. Operations that only report skip nothing. A caller that aborts the shared handle through one axis writes both axes;AnimationGroupandStopAllstop it as a whole, asCancelAnimations()does.
ValueAnimation curves (the same MAUI calls, pinned frame by frame)
| Method | Copies | Ends | Used by |
|---|---|---|---|
AnimateToAsync(..., EaseEveryStep) |
MAUI AnimateToAsync (L41-L94) |
Ease(0), Ease(1) |
round trips, TouchBehavior opacity and rotations, StateContainer |
AnimateToAsync(..., ExactEnds) |
MAUI generic Animate(name, callback, start, end), easing applied by MAUI's internal step loop (L380-L388) |
exact | TouchBehavior scale, ProgressBarAnimationBehavior |
TranslateToAsync(..., startX, startY) |
MAUI TranslateToAsync (L439-L499), start passed in |
Ease(1) |
TouchBehavior translation, from GetBaseTranslation |
AnimateColorToAsync(owner, read, write, ...) |
v17 BackgroundColorTo (L32-L68), result and null handling included |
exact | BackgroundColorTo, TouchBehavior background, TextColorTo |
Completion uses a TaskCompletionSource without RunContinuationsAsynchronously, like MAUI, because the takeover rules rely on code resuming inside the abort.
One-way animations to a state
TryRunToStateAsynctakes no token; the caller'sWaitAsync(token)observes it, so noOperationCanceledExceptionreaches anasync voidhandler.- After its own group's abort (state change, detach, dispose) it writes nothing (v17). After a foreign abort with nothing else in charge it writes the state's value (D10). Translation uses a per-view ticket for "latest" and the seeker's base for "unchanged".
AnimationGroupsetsHasAbortedbefore aborting (MAUI completes an aborted animation inline). It stays separate from the token:CancelAsyncruns callbacks on the thread pool, and their dispatched aborts aren't ordered against the awaiting continuation on iOS.
State rules (TouchBehavior and any future state-driven feature)
GestureManager re-applies every configured property on every state change, hover and attach included (L1155-L1163), even when the value doesn't change. A naive "take over on every state change" ends a running seeker on every hover. So the rules look at the value, not the event. For a property p and the new state's target T (translation uses the seeker's base):
| Rule | When | What happens |
|---|---|---|
| S1 unchanged | (a) a toolkit animation runs p and returns it to T; (b) the app's To animation runs p and T equals the previous target, or this is the first update after attach; (c) nothing runs p and p == T |
nothing: no write, no abort |
| S2 toolkit animation | a round trip or seeker runs p and returns it elsewhere |
(a) release, cancel or hover-out: retarget it, so it returns the view to T at its end; (b) press, hover-in or attach: take it over and move p to T now |
| S3a app animation, take over | opacity, rotations, translation: the app's MAUI To animation runs p and S1 didn't apply |
abort it, move p to T (v17) |
| S3b app animation, leave it | scale under D1-B: the app's ScaleToAsync runs p |
leave it running and write nothing (v17 never stopped it) |
| S4 nothing | nothing runs p and p != T |
move p to T |
- Why S2 splits by direction: a tap fires TouchBehavior's release and the tap in platform order. A release that retargets gives the same end result in both orders; a press still shows at once.
- Why S3 differs by property: v17 shared MAUI's names for opacity, rotations and translation, so it stopped the app's animation there (the shipped remark promises it). It used a private name for scale, so it never stopped the app's
ScaleToAsync. StateAnimationpicks the rule in one switch expression over the closedPropertyActivity, with no default arm:
var rule = PropertyAnimations.DescribeActivity(view, property) switch
{
ToolkitRun run when run.ValueTheRunsLeave == target => StateRule.Unchanged,
ToolkitRun => policy is RunningAnimationPolicy.Retarget ? StateRule.RetargetRun : StateRule.TakeOverRun,
OtherAnimation when previousTarget is null || previousTarget == target => StateRule.Unchanged,
OtherAnimation => otherAnimationPolicy is OtherAnimationPolicy.LeaveRunning ? StateRule.LeaveRunning : StateRule.TakeOverOtherAnimation,
Nothing when (double)view.GetValue(property) == target => StateRule.Unchanged,
Nothing => StateRule.Move,
};Every interplay, before and after (with the recommended option of each decision)
| Situation | Today (#1232 head) | After |
|---|---|---|
| Press during Heartbeat or Tada (scale), or Tada, Swing or Wobble (rotation) | duration 0: hidden every frame, undone at the end; animated scale: both write | the seeker ends at once; the press value stays; its other properties return to rest (S2b) |
| Hover or attach that leaves the value the seeker returns to | the seeker keeps running | keeps running (S1a) |
State change while the app's ScaleToAsync runs (also a pulse loop) |
both write; the later-started animation shows | the app's animation runs on and wins (S3b); the next state update after it ends writes the state's scale if the view shows another value (S4) |
Tap with the app's own Tapped ScaleToAsync pulse plus PressedScale |
order-dependent overlap | both orders: the pulse plays and ends at the app's value |
| Hover or attach that leaves opacity, rotation or translation unchanged while the app's To animation runs | the app's animation is stopped | keeps running (S1b); afterwards the view keeps the app's end value until the next state update (D3) |
Held press during ScaleAnimation |
ends at 0.8 | ends at 1.6 (S2b) |
Heartbeat or ScaleAnimation started during an animated press |
both write | the press animation stops; Heartbeat or ScaleAnimation returns the view to the press value |
Tap: TouchBehavior (PressedScale) plus AnimationBehavior (ScaleAnimation, FadeAnimation or Heartbeat) |
order-dependent fight | both orders: the animation plays; the view ends at the released value |
Same with an animated release and FadeAnimation |
the release scale animation keeps running | both orders: the release plays to the released value (D12) |
AnimationBehavior tap during TouchBehavior's opacity, rotation or translation animation |
stops it mid-way (v17) | TouchBehavior's animation runs to the state's value (D12); a toolkit animation of that property takes it over and returns to the state's value (seekers compose translation) |
The app's CancelAnimations() during any TouchBehavior animation |
scale runs on; the others stop mid-way | the animation stops and the state's value shows at once (D1, D10) |
| TouchBehavior translation under Bounce, Shake or Wobble, unchanged target | offset counted twice (−33.0 vs −30) | untouched (S1 on the seeker's base, C7) |
| Same, changed target | offset counted twice | TouchBehavior's animation moves the base; the offset rides on top once (C7) |
The app's own TranslateToAsync started during Bounce, Shake or Wobble |
offset counted twice at its start | unchanged: MAUI reads the start from the view (documented limitation) |
A release retargets a round trip during its way back, or a RotateAnimation |
- | the running part finishes toward the old value, then the view jumps to the new one; a seeker moves to the new value at its end (D2) |
| A custom easing returns NaN | written by everything except TouchBehavior's scale | skipped everywhere (D4) |
A custom easing with Ease(1) != 1 |
TouchBehavior scale and ProgressBar end exactly at the target; the others at the eased value | unchanged |
| Windows: RotationY back to 0 with a scale set | stays slightly turned | projection cleared (D5) |
Migration per feature
| Feature | Public API | Today | Plan (commit) | Change vs v17 |
|---|---|---|---|---|
FadeAnimation, ScaleAnimation, RotateAnimation, FlipHorizontalAnimation, FlipVerticalAnimation |
unchanged | BaseAnimation plays each part with MAUI *ToAsync |
bodies move into RoundTrip unchanged (C1); each part runs on ValueAnimation (C2); live original and settle (C10); flips use GetAppProjectionOrNull (C13) |
D4 (Fade); TouchBehavior interplay (D2, D3) |
| Seven attention seekers | unchanged | keyframe run | using change (C1); NaN progress skipped (C3); composer query (C4); HandOver, Retarget (C10) |
new in #1232 |
AnimationBehavior |
unchanged | CancelAnimations() plus the seeker abort (L125-L134) |
PropertyAnimations.StopAll (C1); skips TouchBehavior's running state animations (C12) |
D12 |
TouchBehavior, ImageTouchBehavior |
unchanged; XML remarks updated | own MAUI animations, private "SetScale", direct writes |
StateAnimation with v17 behavior (C6); translation from the seeker's base (C7); one commit per decision (C8-C14). State machine, long press, commands, visual states, image swap and the background-colour give-back stay line for line |
D1, D2, D3, D4, D5, D8, D10 |
BackgroundColorTo |
unchanged signature, docs and checks | Animation.Commit |
ValueAnimation.AnimateColorToAsync(...).WaitAsync(token) (C15) |
D4 |
Generated TextColorTo |
unchanged | the same code, emitted into the app | calls one hidden public entry point (D6-A, C15) | D4 |
ProgressBarAnimationBehavior |
unchanged | MAUI ProgressTo |
ValueAnimation.AnimateToAsync(..., ExactEnds) under the same Progress name (C16) |
D4; v17 quirks kept (D7) |
StateContainer default fade |
unchanged | FadeToAsync(0) / (1) |
ValueAnimation.AnimateToAsync(..., EaseEveryStep), 250 ms, Linear (C17) |
none |
StateContainer with the app's own Animation or delegates |
unchanged | view.Animate(name, animation) (L201-L212) |
out of scope: it runs the app's animation; one #pragma with that reason |
none |
| Image swap, Windows pointer storyboards (never begun), MediaElement's WinUI template, Alerts, Popup, Expander (today; #2521 would add a MAUI animation), Camera, Sample | - | no MAUI animation | out of scope | none |
App-authored BaseAnimation subclasses still get no guards (the docs say so). Making the library public for them is a separate proposal.
C# 15 closed hierarchies
Closed hierarchies were considered as a way to keep this code away from app developers. Probes on SDK 11.0.100 (compiler 5.12.0) settle what they do:
| Another assembly... | Result |
|---|---|
derives from a public closed class |
error CS9382 |
| derives from a non-closed subclass of it | compiles: derivation isn't transitive |
| calls its public static or instance members, or creates a public sealed subclass | compiles, no diagnostic |
| In the declaring assembly | Result |
|---|---|
| switch expression over every case, no default arm | no warning; a missing case gives CS8509, or CS8846 (a warning by default) when only a when arm covers it |
| switch statement that misses a case | no diagnostic |
new on the closed class |
CS0144: it is implicitly abstract |
internal closed class, closed record, generic, partial, nested |
allowed |
closed with sealed, static or abstract; on an interface, struct or record struct |
CS9381, CS9384; CS0106 |
- Status: shipped in C# 15, the default language version for
net11.0on the .NET 11 SDK (What's new in C# 15: only memory safety needspreview). It compiles with LangVersion15,default,latest,latestmajorandpreview; C# 12, 13 and 14 reject it (CS9202, CS9260, CS9327). The toolkit targetsnet11.0only and already setspreview(L8), so no project change is needed.net11.0needs no polyfill (anet10.0probe needed its ownIsClosedTypeAttribute, CS0656). - Metadata: an IL
abstractclass with[IsClosedType]and a protected constructor marked[CompilerFeatureRequired("ClosedClasses")]. Enforcement is compile-time only, with no reflection or runtime check, so trimming and NativeAOT are unaffected. - What it doesn't do: restrict calls.
closeddecides who may derive, not who may call. - Where the design uses it:
PropertyActivityis aninternal closed recordwith sealedToolkitRun,OtherAnimationandNothing. With CS8509 and CS8846 errors in the Engine folder, a case that a switch expression misses fails the build, also when only awhenarm covers it. Switch statements over it aren't allowed, because the compiler can't flag them; reviewers grep for them. - Where it doesn't: on any shipped public type.
BaseAnimationandFadeAnimationshipped open in v17 and apps derive from them, soclosedwould break those apps (CS9382). Closing the new Add 11 Animations for AnimationBehavior #1232 classes isn't possible either:closedmakes a class abstract, sonew HeartbeatAnimation()(CS0144) and<toolkit:HeartbeatAnimation />in XAML would fail. - What keeps the library internal:
internal, withInternalsVisibleTofor test assemblies only. The generatedTextColorTocompiles in the app and can call only public API; D6 covers how that one entry point is hidden.
Build guard (D9)
Microsoft.CodeAnalysis.BannedApiAnalyzers(RS0030, build-time only,PrivateAssets="all") in the four packages, witheng/animation-rule/BannedSymbols.txtand RS0030 inWarningsAsErrors. The Engine folder is exempt through its.editorconfig.- Checked against .NET MAUI 11.0.0 with analyzer 4.14.0 and 5.6.0 (latest): a
T:line bans every member of a type (both call syntaxes, every overload, genericAnimate<T>, future overloads). AnM:line matches one signature, so it needs the full documentation ID. An ID that resolves to nothing is silently ignored.nameofis never reported; acrefto anM:-banned member is.
T:Microsoft.Maui.Controls.ViewExtensions;use the Engine library (ValueAnimation, PropertyAnimations)
T:Microsoft.Maui.Controls.AnimationExtensions;use the Engine library (ValueAnimation, PropertyAnimations)
M:Microsoft.Maui.Controls.Animation.Commit(Microsoft.Maui.Controls.IAnimatable,System.String,System.UInt32,System.UInt32,Microsoft.Maui.Easing,System.Action{System.Double,System.Boolean},System.Func{System.Boolean});use ValueAnimation or AnimateKeyframesAsync
M:Microsoft.Maui.Controls.ProgressBar.ProgressTo(System.Double,System.UInt32,Microsoft.Maui.Easing);use ValueAnimation.AnimateToAsync with ValueAnimationCurve.ExactEnds
M:Microsoft.Maui.Animations.IAnimationManager.Add(Microsoft.Maui.Animations.Animation);use ValueAnimation
M:Microsoft.Maui.Animations.Animation.Commit(Microsoft.Maui.Animations.IAnimationManager);use ValueAnimation or AnimateKeyframesAsync
M:Microsoft.Maui.Animations.AnimationManager.Add(Microsoft.Maui.Animations.Animation);use ValueAnimation
M:CommunityToolkit.Maui.Extensions.ColorAnimationExtensions.BackgroundColorTo(Microsoft.Maui.Controls.VisualElement,Microsoft.Maui.Graphics.Color,System.UInt32,System.UInt32,Microsoft.Maui.Easing,System.Threading.CancellationToken);use ValueAnimation.AnimateColorToAsync
- Permitted uses outside the Engine folder carry
#pragma warning disable RS0030with a reason:StateContainer'sview.Animate(name, animation)(L207) and theBackgroundColorTocrefin TouchBehavior's remarks. - Self-test: a fixture project outside the solution plants one use per expected report (both call syntaxes, an obsolete non-
Asyncname,Animate<double>, an interface call, the inheritedCommit(IAnimationManager), acref); adotnet-build.ymlstep checks it reports exactly those.AnimationRuleTestspins eachM:member's overloads, inherited ones included, so a MAUI update that adds one fails. A generator test checks the emittedTextColorTo. - The analyzer can't see timer or
Task.Delayloops that change a property, or switch statements overPropertyActivity; the reviewer checklist covers them.
Test plan
- After every commit: the whole unit suite in Release, then with
--culture tr-TR. Device categories by name (an animation-only filter skips the Touch ones): the 12 animation categories,KeyframeAnimationExtensions,TouchBehavior,ImageTouchBehavior,ColorAnimationExtensions, on Android 36 and 28, iOS, Mac Catalyst and Windows packaged and unpackaged. Full matrix at C1, C6, C14 and the end;pwsh eng/trim-audit/run.ps1at C1, C6, C15 and the end. - Unit tests run on the mock ticker with exact per-frame oracles. Every guard gets a mutant that must fail a named test.
- Device tests act in the UI-thread turn that proves a run is mid-way, never wait on a fixed delay, and drive TouchBehavior headless (
SimulatePress,SimulateRelease). C5 first hardens the 33 fixedTask.Delaywaits in today's Touch device tests.
The per-class test table ("New tests per primitive and per feature") is in the first comment, after the rule file.
Commit plan
Each commit builds in Release with no new warning, passes the unit suite in en-US and tr-TR, and is reviewed before the next one starts. Decision-independent work lands first. Each decision commit only wires a policy, so a rejected decision drops its commit. Exceptions: D1 (C8 implements A or C), D4 (C3 keeps v17's scale-only NaN skip), D6-B (C15 keeps a pinned mirror), D9 (C18 ships the instructions only) and D2 (C11 keeps its translation half).
| # | Commit | Behavior change | Needs |
|---|---|---|---|
| C0 | Base: main after #1232 merges |
- | #1232 |
| C1 | Move the animation guards into an internal shared animation library | none | C0 |
| C2 | Start every toolkit To animation through the library's ValueAnimation |
none (frame parity) | C1 |
| C3 | Skip non-finite steps in every toolkit To animation | D4 | C2 |
| C4 | Add the decision-independent state primitives (no caller yet) | none | C2 |
| C5 | Harden the TouchBehavior device tests that wait with fixed delays (tests only) | none | C0 |
| C6 | Animate TouchBehavior through the shared library, keeping v17 behavior (scale keeps "SetScale") |
none beyond D4 (reaches TouchBehavior's opacity, rotation and translation) | C3-C5 |
| C7 | Start TouchBehavior's translation from the value an attention seeker composes on | fixes a #1232 interplay | C6 |
| C8 | Animate TouchBehavior's scale under ScaleToAsync's handle and leave the app's own ScaleToAsync running |
D1 | C6 |
| C9 | Leave a property's animations alone when a state doesn't change it | D3 | C4, C6 |
| C10 | Let TouchBehavior take over or retarget the toolkit's animations (plus a Sample demo) | D2 | C4, C6 |
| C11 | Show the state's value when something else stops a TouchBehavior animation | D10 | C10 (numeric), C7 (translation) |
| C12 | Let AnimationBehavior leave TouchBehavior's state animations running |
D12 | C4, C6 (C8, C10 for two cases) |
| C13 | Clear MAUI's stale rotation projection after TouchBehavior turns a view on Windows | D5 | C6 |
| C14 | Apply each TouchBehavior state update on the UI thread | D8 | C6 |
| C15 | Build BackgroundColorTo and TextColorTo on the shared ValueAnimation.AnimateColorToAsync |
D6 | C4 |
| C16 | Animate ProgressBarAnimationBehavior through the shared ValueAnimation |
none beyond D4 | C3 |
| C17 | Fade StateContainer's states through the shared ValueAnimation |
none | C3 |
| C18 | Require every toolkit animation to use the shared animation library (instructions, analyzer, fixture, tests) | none | all |
Docs
One docs commit per behavior commit, in a docs PR that stays a draft until the release.
touch-behavior.md: a new section, "Using TouchBehavior with other animations", with each approved decision's before and after. Two tips: start a tap animation fromCommandorTouchGestureCompleted; a looping animation must stop when its*ToAsyncreturnstrue, or MAUI's abort restarts it inside the abort and the app hangs.- Each animation page: what a press and a release do to it. Bounce, Shake and Wobble also: the app's own
TranslateToAsyncstarted mid-run counts the offset twice at its start. color-animation-extensions.md,progressbar-animation-behavior.md: non-finite easing values are skipped.- The PR description lists each approved decision under "Breaking changes".
Proposed rule for contributors, reviewers and AI agents
Lands with the implementing PR (C18):
.github/instructions/animations.instructions.md, full text in the first comment: the rule, which primitive to pick, how to add an animation or a property, the reviewer checklist, why each guard exists, and the test rules.- One line in
AGENTS.md's instructions list, and an "Animations" section in.github/copilot-instructions.md, both pointing to it.
In short:
- Every toolkit animation goes through the Engine library. Feature code never calls MAUI's animation API; the build fails with RS0030.
- Handles come only from
AnimationHandle. Engine types stayinternal. - Round trips use
RoundTrip, state-driven features useStateAnimation, and a new To animation is compared frame by frame with the MAUI call it replaces. - A change to a guard comes with a test that fails without it. A change to shipped behavior needs a maintainer's approval and a breaking-change note.
Estimate
16-31 elapsed days after #1232 merges, most likely about 20 (four weeks).
| Phase | Raw | Contains |
|---|---|---|
| Decisions D1-D12 | 0.5-1 day | one round of answers |
| C1-C3 | 1.5-2.5 days | implementation, review, one fix round, the full device matrix (16 categories × 6 platform runs) |
| C4-C7 | 2.5-3.5 days | the primitives, device-test hardening (1-1.5 days), the TouchBehavior move |
| C8-C14 | 4-5.5 days | seven decision commits: 2-4 h work, 2-3 h review and a fix round each, targeted device runs |
| C15-C17 | 1-1.5 days | generator snapshots, colour, ProgressBar, StateContainer |
| C18, docs, CI | 1-1.5 days | analyzer and fixture; 5-8 pushes at 45 min to 2 h of CI each |
Raw total 10.5-15.5 days, plus 50-100 % for the long tail. It assumes the decisions come in one round, one fix round per commit group (two for C6 and C10), the shared Windows test machine is free at least half the time, and no new MAUI platform bug turns up. Each extra review round adds about half a day; a new platform bug adds 1-2 days.
Usage Syntax
App code doesn't change. The result does.
A held press during ScaleAnimation (bug 1)
<Border x:Name="Card">
<Border.Behaviors>
<toolkit:TouchBehavior DefaultScale="0.8" PressedScale="1.6" />
<toolkit:AnimationBehavior x:Name="Pulse">
<toolkit:AnimationBehavior.AnimationType>
<toolkit:ScaleAnimation Scale="1.2" Length="600" />
</toolkit:AnimationBehavior.AnimationType>
</toolkit:AnimationBehavior>
</Border.Behaviors>
</Border>var pulse = new AnimationBehavior { AnimationType = new ScaleAnimation { Scale = 1.2, Length = 600 } };
card.Behaviors.Add(new TouchBehavior { DefaultScale = 0.8, PressedScale = 1.6 });
card.Behaviors.Add(pulse);
pulse.AnimateCommand.Execute(CancellationToken.None);
// While the pulse runs, the user presses and holds the card- Today: the pulse's way back returns to 0.8, so the card ends at 0.8 while the finger is still down.
- After: the press takes the scale over (S2b): the pulse ends at once and the card stays at 1.6 until the release.
A tap that both behaviors react to (bug 7)
<Image Source="dotnet_bot.png">
<Image.Behaviors>
<toolkit:TouchBehavior PressedScale="0.9" PressedOpacity="0.6"
PressedAnimationDuration="120" DefaultAnimationDuration="160" />
<toolkit:AnimationBehavior AnimateOnTap="True">
<toolkit:AnimationBehavior.AnimationType>
<toolkit:HeartbeatAnimation />
</toolkit:AnimationBehavior.AnimationType>
</toolkit:AnimationBehavior>
</Image.Behaviors>
</Image>- Today: the release animation and Heartbeat write the scale in the same frames, and the platform's event order decides what shows. In release-first order,
AnimationBehavior'sCancelAnimations()also stops the opacity release mid-way, so the image stays partly transparent until the next state change. - After: in either order Heartbeat plays, the opacity release plays to 1.0, and the image ends at scale 1.0. In tap-first order Heartbeat pulses around the pressed scale and moves to 1.0 at its end (D2).
Contributor code: how a toolkit animation calls the library
using CommunityToolkit.Maui.Animations.Engine;
public override Task Animate(VisualElement view, CancellationToken token = default)
{
ArgumentNullException.ThrowIfNull(view);
return AnimationDispatch.RunOnDispatcherAsync(view,
() => RoundTrip.AnimateOutAndBackAsync(view, VisualElement.OpacityProperty, Opacity, Length, Easing, token));
}This is FadeAnimation.Animate after C1. A direct call such as view.FadeToAsync(...) in a feature file fails the build with RS0030.
Drawbacks
- A large change to
TouchBehavior, a widely used shipped feature. C6 moves it with v17 behavior first and must pass the existing suites unchanged; behavior changes then come one commit at a time. - Several v17 behavior changes (D1-D12), each with a breaking-change note. Apps that combine
TouchBehaviorwith their own animations may notice. - D6-A adds one public, hidden method that every compiled app with a generated
TextColorTocalls. Its signature can never change, only gain a sibling. - A new build-only analyzer package and a fixture project to maintain. A MAUI update that adds an animation entry point on another type is caught only by review.
- A late retarget ends with a jump: a seeker's end, a round trip's way back,
RotateAnimation's closing write (D2). - About four weeks of implementation and review after Add 11 Animations for AnimationBehavior #1232 merges.
Alternatives
- Narrow fixes per feature, for example giving TouchBehavior's scale MAUI's name plus a takeover check. A prototype during Add 11 Animations for AnimationBehavior #1232's review ended seekers on every hover (GM re-applies unchanged values), and it leaves the other engines unguarded. The guards would live in several places again.
- Keep
GestureManager's engine and port the guards into it. Two copies of the same guards, which already drifted once. - D6 option B: keep the generated
TextColorToas a mirror ofValueAnimation.AnimateColorToAsync, port the NaN skip by hand, pin both with a frame-parity test, and allow it in the guard. No new public API, but a second copy of the colour animation. - A text-search script with an allow-list instead of the analyzer (D9). It would miss generic calls and future overloads, and line-number allow-lists rot.
- A public library for app-authored animations. A separate proposal.
- Do nothing. The bugs above stay, each new animating feature starts from zero, and reviews keep finding the same MAUI behaviors.
Unresolved Questions
Each change to v17 behavior needs a maintainer's approval and a breaking-change note. All are needed before C1, so no commit ships an undecided change.
| ID | Question | Recommendation | Difference from v17 |
|---|---|---|---|
| D1 | How does TouchBehavior's scale relate to MAUI's ScaleToAsync and the app's own scale animation? A: under ScaleToAsync, taken over like the other properties; B: under ScaleToAsync, but the app's ScaleToAsync is never stopped (S3b); C: keep "SetScale", visible to the toolkit's animations |
B | the app's ScaleToAsync started during TouchBehavior's scale animation replaces it (v17: both wrote); a state change while the app's animation runs writes nothing, and the next update after it ends applies the state's scale; the app's CancelAnimations() now stops TouchBehavior's scale |
| D2 | Should a press (or hover-in, attach) that changes a property end the toolkit's animations of it, and a release (or cancel, hover-out) retarget them to the new state's value; and should a toolkit animation started during a TouchBehavior animation stop it and return the view to the state's value? | Yes | fixes bugs 1-3 and 7; a late retarget ends with a jump; a FadeAnimation started during TouchBehavior's opacity animation returns to the state's value (v17: the partway value the fade started from). Only FadeAnimation shipped in v17. Alternative: take over on release too (simpler, but the tap's own release can end a tap animation at once) |
| D3 | Should a state change that leaves a property's target unchanged stop no animation of it, and write only when nothing animates it and the view shows another value? | Yes | the app's FadeToAsync, RotateTo*Async or TranslateToAsync survives an unchanged hover and the attach, and afterwards the view keeps the app's end value until the next state update (again after every Loaded re-attach); a Style or binding value equal to the target stays bound; a FadeAnimation during a hover that leaves opacity unchanged now plays to its end (v17 cut its fade-out). Alternatives: treat attach as a change; keep v17; option (c) below |
| D4 | Should every toolkit To animation skip NaN and infinite steps? | Yes | v17 skipped NaN for TouchBehavior's scale only, and its infinite steps threw on Android (bug 5) |
| D5 | Windows: should TouchBehavior clear MAUI's stale PlaneProjection after RotationX/Y return to 0? |
Yes | the view no longer stays slightly turned |
| D6 | Generated TextColorTo: (A) call one public static method in a hidden __Internals class, [EditorBrowsable(Never)], with an [Obsolete] diagnostic only the generated code suppresses (as CommunityToolkit.Mvvm does), or (B) keep a pinned mirror |
A | none for apps; A is a permanent binary contract. Stronger: [Experimental], or an analyzer error outside generated code |
| D7 | Keep v17 quirks unrelated to sharing: BackgroundColorTo returns true when aborted (L45); ProgressBarAnimationBehavior raises AnimationCompleted for an aborted run and keeps animating after detach; StateContainer's custom Animation runs on after a cancel; dead Windows storyboards |
Keep; file separate issues | none |
| D8 | Should a state update started off the UI thread run all its writes on the UI thread (one hop per update, re-checking that it is current and attached)? | Yes | on the UI thread nothing changes |
| D9 | Enforce the rule with the banned-API analyzer, the fixture self-test and a generator test? | Yes | none for apps; one new build-only package |
| D10 | Should a TouchBehavior animation that something else stops (CancelAnimations(), AbortAnimation), with nothing taking over, show the state's value at once? A state change, detach or dispose still leaves the value it reached |
Yes | v17 left opacity, rotation and translation in between until the next state change. For numeric properties it needs D2 |
| D11 | Where does it land? | Decided: this issue first, then a follow-up PR after #1232 merges | - |
| D12 | Should AnimationBehavior keep stopping the app's To animations and seekers (v17) but no longer TouchBehavior's running state animations? |
Yes | the release animation plays in both event orders; an app's own BaseAnimation that writes the same property under its own animation name now runs alongside TouchBehavior's animation, and the one that ends last sets the value |
D1 options in detail
| v17 | A | B | C | |
|---|---|---|---|---|
| Handle of TouchBehavior's scale | "SetScale" |
ScaleToAsync |
ScaleToAsync |
"SetScale", also in GetAll(Scale) |
State change while the app's ScaleToAsync runs |
both write; whichever ends last wins | stops it when the target changes | leaves it; the next update after it ends applies the state's scale | both write |
The app's ScaleToAsync started during TouchBehavior's animation |
both write | replaces it | replaces it | both write |
Tap with the app's Tapped pulse plus PressedScale |
order-dependent | tap first: the release cuts the pulse | both orders: the pulse plays | order-dependent |
App pulse loop that ignores ScaleToAsync's result, plus a press |
unaffected | the UI thread hangs in MAUI's abort loop (499 restarts in one call, capped; v17 already hangs this way for opacity, rotation and translation loops) | unaffected | unaffected |
The app's CancelAnimations() |
doesn't stop it | stops it; D10 shows the state's value | stops it; D10 shows the state's value | doesn't stop it |
AnimationBehavior's stop |
doesn't stop it | stops it unless D12 | stops it unless D12 | doesn't stop it |
| Seekers and toolkit To animations vs the scale | fight | coordinate | coordinate | coordinate |
| Library cost | - | none | one per-property policy | a second handle for one property, forever |
Other open items
- Known limitation the toolkit can't fix: the app's own
TranslateToAsyncstarted during Bounce, Shake or Wobble counts the seeker's offset twice at its start, because MAUI reads the start from the view (L484-L485). It ships with Add 11 Animations for AnimationBehavior #1232. Should Add 11 Animations for AnimationBehavior #1232's docs PR get the docs note now? - D3, option (c): compare the at-rest target with the behavior's previous target instead of the view's value. It keeps any value the app writes at rest until a state's target changes, but moves further from v17, which wrote on every update. The recommendation stays with the view's value.
- Not verified: what iOS, Mac Catalyst and WinUI draw for a NaN transform or opacity. Moot under D4; a device test checks that none reaches the view.
Activity
TheCodeTraveler commentedon Nov 20, 2026
This is Brandon's Claude. Here is the full proposed instructions file from the "Proposed rule" section above, plus the two pointers to it. All three land with the implementing PR (C18). The per-class test table from the Test plan follows at the end.
src/CommunityToolkit.Maui/Animations/Engine/layout. Commit hashes are on Add 11 Animations for AnimationBehavior #1232.AGENTS.md, in the "Instructions" list after the async line:.github/copilot-instructions.md, a new section after "### Trimming and NativeAOT":.github/instructions/animations.instructions.mdNew tests per primitive and per feature
AnimationHandleTestsCancelAnimationsstops exactly the nine; handle checksValueAnimationTestsEase(0) != 0,Ease(1) != 1, NaN and infinity; aborts both ways; inline resume; colour edge casesRunContinuationsAsynchronously; wrong MAUI path; finite check removedRoundTripTestsEndAnimationoutsidefinally; settle removedOneWayAnimationTests,PropertyAnimationsTests,AnimationGroupTestsDescribeActivity;StopAll; batchedWriteTranslation;HasAbortedtimingStateAnimationTestsAnimationBehaviorin both event orders at 0 and 160 ms (C10);CancelAnimations(C11); release survivesAnimationBehavior(C12); off-thread (C14)ScaleAnimation; both tap orders on every platform; Windows projection; NaN and infinite easings onScaleAnimation, RubberBand and TouchBehavior's scale: no exception, no non-finite value on the viewNote the Android crash from a custom easing that returns NaN or infinity
TheCodeTraveler commentedon Nov 20, 2026
This is Brandon's Claude.
In one narrow case, the Fade, Scale, Rotate and flip animations from #1232 undo the app's own To animation. The proposed library should fix it.
When (
TryAnimateAndRestoreIfStoppedAsync):ScaleAnimation, the app starts its ownScaleToAsyncto the value the view already shows.Task.Yieldposted (Android allows this).The check then sees the handle idle and the value unchanged, so it restores the original value. It can't tell "nothing took over" from "the app took over and already finished at that value".
Fix: the design moves this check unchanged into
OneWayAnimation.TryRunAsync(BA8-BA11). Tracker run ids can't replace it, because the app'sScaleToAsyncnever gets one. Instead, decide at the posted check or the next frame, whichever comes first. MAUI registers the app's animation right after the abort (L274-L297), so both moments see it running. For example, anAnimationadded to the view'sIAnimationManagerduring the abort ticks before the app's animation in every frame (MAUI ticks in add order). It must ignore ticks inside the abort, because Android's ticker ticks at once when it restarts. Keep the value check for the app's direct writes.Test: on the mock ticker, fire one frame at least as long as the app's animation before the posted check runs; the app's value must stay. Repeat with the check first, and with
CancelAnimations(), which must still restore.Found by reading the code; not reproduced. v17 shipped only
FadeAnimation, where the app'sFadeToAsyncalways won, so for Fade this case is a narrow change from v17.