Skip to content

[Proposal] One shared, tested animation library for every toolkit animation #3449

Open

Description

@TheCodeTraveler

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, ProgressBarAnimationBehavior and StateContainer are 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 CancelAnimations aborts by name. A private name hid TouchBehavior's scale from everything (bug 1).
  • Abort first, then take a tracker id. Code after an aborted await resumes 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's await resumes inline, inside the abort (no RunContinuationsAsynchronously, 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 AnimationBehavior stop and start in one UI-thread turn (79f84c8).
  • Compose translation. TranslateToAsync drives 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 ScaleToAsync after the aborted await restarted 499 times inside one AbortAnimation call 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

Detailed Design

Prerequisite and scope

  • Depends on Add 11 Animations for AnimationBehavior #1232. The implementing PR branches from main after 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/, namespace CommunityToolkit.Maui.Animations.Engine. Every type is internal.
  • A folder .editorconfig makes CS8509 and CS8846 (non-exhaustive switch expression; CS8846 when only when arms cover a case) errors and exempts the folder from RS0030 (the build guard below). Neither is in the repo's WarningsAsErrors (L219-L246).
  • InternalsVisibleTo covers only the five test assemblies (L266-L272). The namespace isn't mapped to XAML.
  • BaseAnimation's helpers are private protected today, so moving them changes no public surface. BaseAnimation keeps Length, Easing, Animate and IsFinite.

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) is FadeToAsync). MAUI then treats it like its own *ToAsync: a same-name start replaces it, and CancelAnimations() stops it.
  • IsStoppedByCancelAnimations is true for exactly MAUI's nine names (L23-L39), not for BackgroundColorTo, TextColorTo, the seeker handle or MAUI's Progress (L64-L71).
  • An explicit handle is checked: ArgumentException when it doesn't write the property, or (in ValueAnimation.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: aborting TranslateToAsync for one axis strands the other. Operations that only report skip nothing. A caller that aborts the shared handle through one axis writes both axes; AnimationGroup and StopAll stop it as a whole, as CancelAnimations() 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

  • TryRunToStateAsync takes no token; the caller's WaitAsync(token) observes it, so no OperationCanceledException reaches an async void handler.
  • 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".
  • AnimationGroup sets HasAborted before aborting (MAUI completes an aborted animation inline). It stays separate from the token: CancelAsync runs 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.
  • StateAnimation picks the rule in one switch expression over the closed PropertyActivity, 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.0 on the .NET 11 SDK (What's new in C# 15: only memory safety needs preview). It compiles with LangVersion 15, default, latest, latestmajor and preview; C# 12, 13 and 14 reject it (CS9202, CS9260, CS9327). The toolkit targets net11.0 only and already sets preview (L8), so no project change is needed. net11.0 needs no polyfill (a net10.0 probe needed its own IsClosedTypeAttribute, CS0656).
  • Metadata: an IL abstract class 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. closed decides who may derive, not who may call.
  • Where the design uses it: PropertyActivity is an internal closed record with sealed ToolkitRun, OtherAnimation and Nothing. With CS8509 and CS8846 errors in the Engine folder, a case that a switch expression misses fails the build, also when only a when arm 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. BaseAnimation and FadeAnimation shipped open in v17 and apps derive from them, so closed would break those apps (CS9382). Closing the new Add 11 Animations for AnimationBehavior #1232 classes isn't possible either: closed makes a class abstract, so new HeartbeatAnimation() (CS0144) and <toolkit:HeartbeatAnimation /> in XAML would fail.
  • What keeps the library internal: internal, with InternalsVisibleTo for test assemblies only. The generated TextColorTo compiles 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, with eng/animation-rule/BannedSymbols.txt and RS0030 in WarningsAsErrors. 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, generic Animate<T>, future overloads). An M: line matches one signature, so it needs the full documentation ID. An ID that resolves to nothing is silently ignored. nameof is never reported; a cref to an M:-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 RS0030 with a reason: StateContainer's view.Animate(name, animation) (L207) and the BackgroundColorTo cref in TouchBehavior's remarks.
  • Self-test: a fixture project outside the solution plants one use per expected report (both call syntaxes, an obsolete non-Async name, Animate<double>, an interface call, the inherited Commit(IAnimationManager), a cref); a dotnet-build.yml step checks it reports exactly those. AnimationRuleTests pins each M: member's overloads, inherited ones included, so a MAUI update that adds one fails. A generator test checks the emitted TextColorTo.
  • The analyzer can't see timer or Task.Delay loops that change a property, or switch statements over PropertyActivity; 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.ps1 at 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 fixed Task.Delay waits 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 from Command or TouchGestureCompleted; a looping animation must stop when its *ToAsync returns true, 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 TranslateToAsync started 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 stay internal.
  • Round trips use RoundTrip, state-driven features use StateAnimation, 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's CancelAnimations() 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 TouchBehavior with their own animations may notice.
  • D6-A adds one public, hidden method that every compiled app with a generated TextColorTo calls. 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 TextColorTo as a mirror of ValueAnimation.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 TranslateToAsync started 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

  1. added
    proposalA fully fleshed out proposal describing a new feature in syntactic and semantic detail
    on Nov 20, 2026
  2. TheCodeTraveler commented on Nov 20, 2026

    @TheCodeTraveler
    CollaboratorAuthor

    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.

    • It assumes the recommended option of each decision (D1-B, D2, D3, D9, D10, D12). The bullets that name a decision change if another option is picked.
    • Paths assume the proposed 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/instructions/animations.instructions.md](.github/instructions/animations.instructions.md): every toolkit animation goes through the shared animation library

    .github/copilot-instructions.md, a new section after "### Trimming and NativeAOT":

    ### Animations
    
    * Every animation the toolkit runs goes through the internal animation library in `src/CommunityToolkit.Maui/Animations/Engine/`; feature code never calls .NET MAUI's animation API directly (the build fails with RS0030). The rule, the reviewer checklist and the reason for each guard are in [.github/instructions/animations.instructions.md](https://github.com/CommunityToolkit/Maui/blob/main/.github/instructions/animations.instructions.md). Flag violations when reviewing.

    .github/instructions/animations.instructions.md

    ---
    description: 'Every animation the .NET MAUI Community Toolkit runs goes through its internal shared animation library: the rule, how to add an animation or a property, what reviewers check, why each guard exists, and how to test it'
    applyTo: '**/*.cs,eng/animation-rule/**'
    ---
    
    # Animations: one shared, tested animation library
    
    ## The rule
    
    * Every animation the toolkit runs goes through the internal library in [src/CommunityToolkit.Maui/Animations/Engine/](../../src/CommunityToolkit.Maui/Animations/Engine/) (namespace `CommunityToolkit.Maui.Animations.Engine`). That covers the animation classes, `AnimationBehavior`, `TouchBehavior` and `ImageTouchBehavior`, `BackgroundColorTo`, the generated `TextColorTo`, `ProgressBarAnimationBehavior`, `StateContainer`'s fade, and anything new.
    * Feature code never calls .NET MAUI's animation API directly: no `Animate` (any overload), `AnimateKinetic`, `Animation.Commit` (both overloads), `AbortAnimation`, `AnimationIsRunning`, `CancelAnimations`, `ProgressTo`, `IAnimationManager.Add` or `AnimationManager.Add`, no `FadeTo`/`ScaleTo`/`ScaleXTo`/`ScaleYTo`/`RotateTo`/`RotateXTo`/`RotateYTo`/`TranslateTo`/`LayoutTo`/`RelScaleTo`/`RelRotateTo` in their `Async` or obsolete form, and no timer or `Task.Delay` loop that changes a view property over time. Inside the toolkit, do not call the public `BackgroundColorTo` or the `TextColorTo` entry point either; they are for apps and generated code. Building keyframe `Animation` objects for a seeker is fine; committing them is the library's job.
    * The build enforces it: `Microsoft.CodeAnalysis.BannedApiAnalyzers` reports RS0030 (an error) for every symbol in [eng/animation-rule/BannedSymbols.txt](../../eng/animation-rule/BannedSymbols.txt) outside the library folder. A permitted use outside the library carries `#pragma warning disable RS0030` and `restore` around that one call or doc comment, with a comment saying why; adding one needs a maintainer's OK. The generated `TextColorTo` is checked by a `SourceGenerators.UnitTests` test.
    * How `BannedSymbols.txt` is written, and why:
      * .NET MAUI's `ViewExtensions` and `AnimationExtensions` are banned whole (`T:` lines). A type ban covers every overload, the generic `Animate<T>`, extension and static call syntax, and any overload MAUI adds later.
      * Any other member gets a line with its full documentation ID, parameter list included (`M:Microsoft.Maui.Controls.ProgressBar.ProgressTo(System.Double,System.UInt32,Microsoft.Maui.Easing)`). A line without a parameter list bans only a parameterless overload, which no MAUI animation method has, and an ID that resolves to nothing is ignored without a warning.
      * So every line has a planted use in `eng/animation-rule/fixtures/`, whose CI build must report exactly the expected RS0030 lines, and `AnimationRuleTests` pins the overloads of each `M:` member by reflection, inherited ones included (`Animation` inherits `Commit(IAnimationManager)`), so a .NET MAUI update that adds one fails until it gets a line.
      * RS0030 ignores `nameof`. It reports a `cref` to a member banned by an `M:` line or to a banned type itself, but not to a member of a banned type, so a doc link to `BackgroundColorTo` needs the pragma.
    * Handles come only from `AnimationHandle`. Its constructor is private and the library's methods accept nothing else, so a feature cannot invent a handle name. A method that takes an explicit handle checks that the handle writes the property.
    * Every Engine type is `internal`. Do not make one public for a feature: the only public entry point is the hidden one the `TextColorTo` generator calls. C# `closed` does not hide members (it only stops other assemblies from deriving); use it inside the library where a switch must cover every case.
    * Animation code also follows the toolkit's [naming conventions](https://github.com/CommunityToolkit/Maui/blob/main/CONTRIBUTING.md#naming-conventions).
    * Out of scope: animations .NET MAUI's animation system never sees (WinUI VisualStateManager storyboards in MediaElement's template, Android Material's own Snackbar animation); property writes after a delay that are not animations moving a value to a target over time (`ImageTouchBehavior`'s image swap); `StateContainer`'s overloads that run the app's own `Animation` objects or delegates (there is no property guard to add; `#pragma` with that reason); the Sample's animations, which show app code. `CommunityToolkit.Maui.Core`, `.Camera` and `.MediaElement` cannot reach the library and animate nothing; the analyzer covers them so it stays that way.
    * Why: the guards below came from the review rounds on CommunityToolkit/Maui#1232 (51 product commits and more than 70 test commits on the animation code after 17.0.0), and each one is pinned by a test that fails without it. `TouchBehavior` animated on its own: it re-derived two guards, missed the rest and fought the toolkit's own animations. Its private `"SetScale"` handle let a held press during `ScaleAnimation` end at 0.8 instead of 1.6, and an attention seeker hid every press and undid it at the end. One library means one place to fix, one set of tests, and animations that know about each other.
    
    ## Pick the primitive
    
    | The animation... | Use | Interrupted and nothing takes over |
    |---|---|---|
    | goes out and back (Fade, Scale, Flip) or turns and snaps back (Rotate) | `RoundTrip.AnimateOutAndBackAsync` / `RoundTrip.TurnAsync` inside `AnimationDispatch.RunOnDispatcherAsync`; never assemble the parts yourself | returns the view to the tracker's live original value |
    | plays keyframes over several properties (attention seekers) | `view.AnimateKeyframesAsync(...)` with a `KeyframeTarget` | returns every property to its original value |
    | moves to a state's value and holds it (`TouchBehavior`) | a `StateAnimation` per view, with one `AnimationGroup` per state update; translation through `StateAnimation.TranslateToAsync` | shows the state's value; after the feature's own abort it stays where it stopped |
    | writes a translation directly while a seeker may compose it | `PropertyAnimations.WriteTranslation` | - |
    | animates a colour | `ValueAnimation.AnimateColorToAsync` | - |
    | replaces one .NET MAUI To animation (a call that moves a property from a start value to a target over time) | `ValueAnimation.AnimateToAsync` with the curve of the call it replaces: `EaseEveryStep` for a `*ToAsync` method, `ExactEnds` for `Animate(name, callback, start, end)` or `ProgressTo`; `ValueAnimation.TranslateToAsync` for `TranslateToAsync`, with start values from `PropertyAnimations.GetBaseTranslation` | - |
    
    ## Adding an animation
    
    1. Pick the primitive above; never start an animation any other way.
    2. Read the starting values from the tracker (`AnimatedPropertyTracker`) and translation from `PropertyAnimations.GetBaseTranslation`, not from the view: another animation of the property may be running, may have been interrupted, or may be composing an offset on top.
    3. Validate public double properties with `IsFinite` and `DefaultBindingMode = OneWay`, and throw for a null view before the first `await`.
    4. Write the tests in "Test rules" before you call it done.
    
    ## Adding a property
    
    1. Add it to `AnimationHandle`: .NET MAUI's own method name when MAUI has a To method for it (so MAUI's `CancelAnimations` and the app's own call interact with it as with MAUI's), else a toolkit name. Mark a handle that drives more than one property as shared, and the ones MAUI's `CancelAnimations` stops.
    2. Decide whether a second writer takes it over (`PropertyAnimations.TakeOver`) or composes with it (translation, `KeyframeTarget`).
    3. For a state-driven feature, decide what a state change does to the app's own To animation of it (`OtherAnimationPolicy`): follow what the last shipped version did for that property, and change it only with a maintainer's OK.
    4. RotationX and RotationY: clear the stale Windows projection (`RotationProjection`).
    5. A non-double property (a colour) has no tracker today. Before two toolkit animations can write one, generalize `AnimatedPropertyTracker`.
    6. Extend `AnimationHandleTests` and the primitive's tests.
    
    ## What reviewers check on a PR
    
    * The build is clean (no RS0030), and every new `#pragma warning disable RS0030` has a reason a maintainer accepted.
    * A new `BannedSymbols.txt` line is a `T:` line or a full documentation ID with its parameter list, and has a planted use in the fixture project.
    * No switch statement over a `PropertyActivity` (the compiler cannot flag one): `git grep -nE 'switch *\(' -- 'src/CommunityToolkit.Maui/Animations/Engine/'` and read each hit the PR adds.
    * No timer or `Task.Delay` loop changes a view property over time (the analyzer cannot see it): `git grep -nE 'Task\.Delay|PeriodicTimer|System\.Timers' -- 'src/CommunityToolkit.Maui*/*.cs' ':!*Tests*'` and read each hit the PR adds (none of the 14 at #1232's head animates a property).
    * Round trips use `RoundTrip`, state-driven features use `StateAnimation`; no feature reads its own captured original after a part ends.
    * No token passed to a .NET MAUI animation.
    * No new abort of the app's own animations beyond what the last shipped version did (see "the abort loop" below).
    * A change to a guard comes with a test that fails without it, and the PR says which.
    * A new To animation is compared frame by frame with the .NET MAUI call it replaces.
    * Unit tests use the mock ticker and exact per-frame oracles; device tests follow the stall rules below.
    * Behavior that shipped in the last release (`git show <last tag>:<path>`) only changes with a maintainer's OK and a breaking-change note.
    * The library stays trim- and NativeAOT-safe (`pwsh eng/trim-audit/run.ps1`) and culture-invariant.
    
    ## Why each guard exists
    
    Each bullet: the guard, the .NET MAUI behavior behind it, the bug it prevented (commit on CommunityToolkit/Maui#1232 where there is one). File and line details are in the guard's code comment.
    
    ### Handles and ownership
    
    * **One tracker per view and property** ([AnimatedPropertyTracker](../../src/CommunityToolkit.Maui/Animations/Engine/AnimatedPropertyTracker.shared.cs)). An animation that starts mid-run reads a partly animated value; returning there left the view partway. The original is the value before the first of the overlapping runs (4b3c8acf, generalizing v17's fade tracker).
    * **Runs end by id; only the latest acts.** An interrupted run and its successor both ended, or one ended twice, and the stale one moved the view (a4d9c1ac).
    * **Every toolkit write takes an id, also a direct write.** An interrupted round trip otherwise had to guess from the value whether something took over, and a write of the in-flight value looked like none.
    * **Toolkit To animations use .NET MAUI's own handle names.** MAUI aborts a same-name animation when another starts, and `CancelAnimations` aborts by name. A private name (`"SetScale"`) hid TouchBehavior's scale from `ScaleAnimation`, the seekers and `CancelAnimations`, so they fought every frame.
    * **Operations that stop whatever animates a property go through `AnimationHandle.GetAll`; an explicit handle is checked against the property.** A handle taken from the property alone cannot express a feature that must keep its own name (TouchBehavior's v17 scale), and an unchecked handle could abort another property's animation.
    * **A shared handle is never aborted or animated for one axis alone.** `TranslateToAsync` drives both axes under one name; aborting it for one axis stranded the other mid-way (f98672a4). So the operations that stop or hand over a property's animations skip shared handles, and `ValueAnimation.AnimateToAsync` rejects them (translation goes through `ValueAnimation.TranslateToAsync`). It is aborted only where both axes are meant to stop: before a duration-0 translation write, which then writes both axes; in an `AnimationGroup`, which stops the feature's own translation animation; and in `StopAll`, which stops the whole view as `CancelAnimations()` does. Operations that only report skip nothing: `IsRunning` counts the shared handle, or a running `TranslateToAsync` would look like no animation.
    * **`DescribeActivity` is for non-translation properties; translation asks `PropertyAnimations.IsRunning` on its handle.** A seeker keeps a tracker for every property it animates, the translation axes it composes included, so a "toolkit run" answer means nothing for translation.
    * **The abort loop: never abort the app's own animation where the last shipped version did not.** MAUI's `AbortAnimation(name)` keeps aborting while an animation of that name exists, and app code that restarts its animation in the aborted `await`'s continuation restarts inside that loop. An app loop that ignores the result then hangs the UI thread (a probe counted 499 restarts inside one call). This is why TouchBehavior leaves the app's `ScaleToAsync` running (decision D1).
    
    ### Cancellation and stale tokens
    
    * **Check the token before stopping anything.** A pre-cancelled call must not stop the animation that is running or write a frame (4b3c8acf).
    * **Throw for a null view at the call, before the async body.** In an async method a null argument only faults the returned Task instead of throwing where it was passed (163ed96d, 2560b69c).
    * **Never pass the token to a .NET MAUI animation; start the animation, then register the token.** For a token cancelled off the UI thread, MAUI queues `AbortAnimation(name)`, which aborted a newer run that had taken the name (6109948c). With a pre-cancelled token MAUI reports the animation as cancelled without starting it, so a running same-name animation keeps going; starting the animation first and then registering the token lets the toolkit abort it itself.
    * **The token aborts only while its own part or run is running, on the dispatcher.** Once a part ends, its name may belong to a newer run (6109948c, fc517a4a).
    * **A cancelled round trip returns the view only if it is still the latest run, then throws.** No successor will return it; a newer run owns the value (fc517a4a, c0d4d114).
    * **End the run in a `finally`.** A fault or a cancel otherwise left the run registered, and the tracker never saw the view at rest again (4b3c8acf, inherited from v17's fade).
    * **A seeker's start is not cancellable once dispatched, and skips itself if its token was cancelled while it waited.** Otherwise it stopped an unrelated running animation and moved the view for a frame (93d7a8f8).
    * **An aborted seeker ends as cancelled only when its own token caused it.** A supersede is a normal end (fc517a4a).
    * **`AnimationBehavior` swallows an `OperationCanceledException` only when its own token is cancelled.** The command is `async void`, and an exception escaping it crashes the app. The filter is the command's token, not the exception's, because a custom animation that links tokens carries the linked one; an exception the token did not cause still reaches the app (96f81e70).
    * **`AnimationBehavior` awaits the animation inside its `try`.** Returning the Task would leave the `try` before the animation ends and defeat `ShouldSuppressExceptionsInAnimations` (v17).
    
    ### Interrupts and takeover
    
    * **Abort the property's handle before taking a tracker id, then stop the seeker.** App code after an aborted `await` runs inside MAUI's abort loop and can start a run; the abort-first order ends that run before ours numbers itself (801ea023).
    * **An interrupted part ends the run.** The parts after it would interrupt whatever took over (c0d4d114).
    * **End the run before `Task.Yield`, decide after it.** MAUI resumes an aborted animation's `await` inline inside the abort; ending first lets a value the app sets in that turn become the next run's original, and the yield lets a same-turn successor register (a4d9c1ac).
    * **Return to the original only when nothing took over: still latest, handle not running, value unchanged.** Those are the three takeover forms (toolkit run, app To animation, app write). An equal `SetValue` raises no `PropertyChanged`, so a write of exactly the in-flight value is indistinguishable from none (c0d4d114, 0308d902).
    * **Record what the run left: the original after a return, nothing after a hand-over.** Otherwise the next run returned to a stale value (30992452, 79320b4d).
    * **Round trips read the tracker's live original, in `RoundTrip` only.** A state change can retarget a running round trip; reading the original captured at the start would end it at the old value. Keeping this in one primitive means a new round trip cannot forget it. A retarget during the way back ends with a jump to the new value.
    
    ### State-driven animations (TouchBehavior)
    
    * **Going to a state's value sets the tracker's original to that value.** A round trip or seeker that interrupts the state's animation must return to the state's value; otherwise a seeker started by `Command` after an animated release left the view at 1.52 instead of 0.8.
    * **A state change that leaves a property's target unchanged stops no animation of it; with nothing animating the property, it writes only when the view shows another value.** TouchBehavior re-applies every configured property on every state change; taking over on each one ended seekers on hover and attach, and stopped the app's own animation, which the shipped docs promise only "when the state changes that property". The rest check compares the view's value, not the previous target, because the last shipped version wrote on every update: the next update replaces a value the app left at rest, even when the target did not change.
    * **A press takes over the toolkit's animations; a release retargets them.** A tap fires the release and the tap gesture in platform order (on Android both listen to the same `Touch` event). Retargeting lets a tap animation play and end at the released value in either order; the press still shows at once.
    * **The app's own To animation follows the last shipped version, per property.** Opacity, rotation and translation are taken over on a state change that changes them (they shared MAUI's names in v17); the app's `ScaleToAsync` is left running (v17 used a private name, and taking it over would cut an app's tap pulse in one event order and hang an app loop, see the abort loop).
    * **Switch over `PropertyActivity` with a switch expression, never a switch statement.** `PropertyActivity` is an `internal closed record`, and CS8509 and CS8846 are errors in the library folder, so a case that a switch expression misses fails the build, also when only a `when` arm covers it (CS8846, a warning by default). The compiler does not check a switch statement for a missing case at all, so one would let a new case fall through silently. `StateAnimation` maps it to its rule in one expression; the later steps branch on that rule.
    * **A state's animation that something else stops shows the state's value; one the feature stops itself stays where it is.** `CancelAnimations()` otherwise left the view in between until the next state change. The group sets its flag before aborting, because MAUI completes an aborted animation inline inside `AbortAnimation`. Translation decides "latest" by a per-view ticket and "unchanged" by the seeker's base, because seekers compose it instead of taking it over.
    * **`AnimationBehavior` leaves a state feature's running animations alone.** They end at the state's value by themselves; stopping them made the release animation depend on event order. A toolkit animation it runs still takes over a property it animates (attention seekers compose translation instead). An app's own animation that writes the property under its own animation name runs alongside the state's animation, and the one that ends last sets the value.
    * **A feature that must stop its animations before it yields keeps them in an `AnimationGroup` and aborts it synchronously.** Token callbacks from `CancelAsync` run on the thread pool, and their dispatched aborts are not ordered against the awaiting continuation on every platform.
    * **A state update hops to the UI thread once, before its first write, and re-checks that it is still current and attached.** Apps can set the state from any thread; WinUI throws on a write from another thread, hopping per property split one update across two threads, and a detach while the hop waited leaves no element.
    
    ### System animations off
    
    * **With system animations off, treat MAUI's "aborted" as completed** ([SystemAnimations](../../src/CommunityToolkit.Maui/Animations/Engine/SystemAnimations.shared.cs)). MAUI jumps every animation to its end and reports it aborted (`Finished(value, !SystemEnabled)`), also when animations are switched off mid-run; the To animations took that for an interruption and stayed at the target (f7ff37d6, c0d4d114).
    
    ### Threading
    
    * **Start on the view's dispatcher, with an async method, not `DispatchAsync(Func<Task>)`.** Off the UI thread every `await` continued on the thread pool and wrote view properties there (WinUI throws; iOS touched UIKit off the main thread); that overload turns a cancellation into a fault and never completes when the dispatcher refuses work (782edd87).
    * **`AnimationBehavior` stops the running animations and starts the new run in one UI-thread turn.** From another thread MAUI posted them separately and the view returned to rest for a frame (79f84c8a).
    
    ### Attention seekers
    
    * **One run per view under one handle; a new run aborts the old one first.** Two runs read each other's keyframe values as the view's original values (fc517a4a).
    * **A run records its properties; a To animation of one of them stops it.** Otherwise both wrote the property and the heartbeat kept going after the Scale task completed (6b3fd8c7).
    * **Record the run only after its keyframes are created.** Swing's anchor write runs `PropertyChanged` handlers that can start a nested run; recording first left Swing untracked (418dbe14).
    * **Check every tick, except the first step inside `Commit`, whether another To animation of a property is running; if so, abort before writing.** The later-started animation ticks after the seeker and hid it, and the seeker's restore then undid the app's target. MAUI plays the first step inside `Commit`, where an abort would leave an orphan animation (1919770e, 67510c73).
    * **If the start throws, restore the view unless `Commit` already did.** `createKeyframes` may have moved an anchor, and `Commit` throws for a view without an `IAnimationManager`; with animations disabled `Commit` runs the finished callback itself, which already restored the view (fc517a4a).
    * **End only your own run record, read who took over before ending, and leave the taker's properties alone.** A nested run's cleanup removed the next run's record or undid Swing's anchor (6b3fd8c7, 253f9d6b).
    * **The restore faults the run's Task instead of throwing.** It runs inside MAUI's ticker or inside whoever aborted the run, where a throwing `PropertyChanged` handler crashed the app (5ac6e85d).
    * **Restore every property even if one throws, and end every tracker.** Otherwise later properties stayed animated and trackers kept stale originals (fc517a4a).
    * **Keep writing during a keyframe gap.** `Animation` writes nothing between children, so a running `TranslateToAsync` dropped Bounce to rest at its peak (a7a014d9).
    
    ### Translation composition
    
    * **Seekers add their offset to the translation another writer sets** ([KeyframeTarget](../../src/CommunityToolkit.Maui/Animations/Engine/KeyframeTarget.shared.cs)). `TranslateToAsync` writes absolute values and cannot be aborted per axis; the seeker overwrote it and restored the wrong value (51e687ae).
    * **Detect another writer by the stored box, not the value.** An equal write raises no `PropertyChanged` but stores a new box; comparing values restored an older translation (890ef173).
    * **Re-compose on `BatchCommitted`, but not during the composer's own write.** A later-started animation writes last in each frame; a batching `PropertyChanged` handler made the recompose loop forever (ea40bc70).
    * **Stop composing before the restore.** A composer still listening put its offset back on the next writer's value (ea40bc70).
    * **A toolkit translation starts from, and compares with, the seeker's base, not the view's value.** Under a seeker the view shows keyframe + base offset; a translation animation that started there added the offset twice (measured 3 units past a 30-unit Bounce), and an unchanged target looked changed on every hover.
    * **A direct toolkit translation write is batched.** MAUI batches every animation step, and the composer re-composes on `BatchCommitted`; an unbatched write showed one frame without the seeker's offset.
    
    ### Values and curves
    
    * **Each To animation keeps the curve of the .NET MAUI call it replaces.** MAUI's `*ToAsync` methods ease every step, including the first and the last; `Animate(name, callback, start, end)` and `ProgressTo` hand the easing to MAUI's internal step loop, so their first and last steps are exact. Moving TouchBehavior's scale or `ProgressBarAnimationBehavior` to the other curve would end them short of the target for an easing where `Ease(1)` is not 1.
    * **Skip non-finite steps in every To animation.** A custom easing can return NaN or infinity, and .NET MAUI writes it to the property every frame. On Android, a NaN or infinite `ScaleX` or `ScaleY` throws `IllegalArgumentException` inside MAUI's ticker at [target API 28 and later](https://github.com/aosp-mirror/platform_frameworks_base/blob/android-16.0.0_r1/core/java/android/view/View.java#L5903) ([View.java](https://github.com/aosp-mirror/platform_frameworks_base/blob/android-16.0.0_r1/core/java/android/view/View.java#L19975-L20010)); MAUI skips only a NaN `Scale` ([L23-L41](https://github.com/dotnet/maui/blob/11.0.0/src/Core/src/Platform/Android/TransformationExtensions.cs#L23-L41)), so an infinite `Scale` throws too. Most other NaN values reach the platform view (Controls clamps an infinite opacity, not a NaN one, [L277](https://github.com/dotnet/maui/blob/11.0.0/src/Controls/src/Core/VisualElement/VisualElement.cs#L277)); on Windows, a turned view with a NaN rotation keeps its last `PlaneProjection` ([L41-L46](https://github.com/dotnet/maui/blob/11.0.0/src/Core/src/Platform/Windows/TransformationExtensions.cs#L41-L46)).
    * **The colour animation writes Transparent before it starts when the colour is null.** Every channel step reads the current colour, so a null colour threw inside MAUI's ticker.
    * **Validate public double properties as finite and bind them one way.** Same reason as the NaN skip; an animation never writes its own properties (fc517a4a, 2519aa2e).
    * **`Length` is the whole round trip; each part takes half.** v17's fade took twice `Length` ([discussion 1231](https://github.com/CommunityToolkit/Maui/discussions/1231)).
    
    ### Windows
    
    * **Clear MAUI's stale `PlaneProjection` after RotationX/RotationY return to 0, keeping the app's own** ([RotationProjection](../../src/CommunityToolkit.Maui/Animations/Engine/RotationProjection.windows.cs)). MAUI writes a new projection on every update while the view is turned and keeps the last one when another transform is set, leaving the view turned (17ba83f4, 3e033591). A projection is the app's only if it was there while the view was unturned: TouchBehavior's press and release are separate calls, so remembering the projection per call kept the press's own projection after a zero-duration release.
    * **Read and clear the projection on the container view when the handler has one.** MAUI's mappers write the transforms there; the platform view never held the projection (090ae4d5).
    
    ## Test rules
    
    * **Unit tests run on the mock ticker** ([UnitTests/Mocks/AnimationExtensions.cs](../../src/CommunityToolkit.Maui.UnitTests/Mocks/AnimationExtensions.cs)): one Fire loop, 16 ms of virtual time per frame, frames paced by a spinning `Stopwatch`, on one thread (`BaseAnimationTest.RunOnSingleThreadAsync`, `UndisposedAsyncContext`). A `Task.Delay(16)` tick took 75-115 ms on slow runners, and a second Fire loop doubled the frame rate (dddd59e1, f229ddc8, a9a29f24).
    * **Exact oracles, not ranges.** A range let a "play keyframes, then check" mutant pass 9 of 24 rows (67510c73).
    * **Compare a To animation with its .NET MAUI reference frame by frame,** with easings whose `Ease(0)` or `Ease(1)` is not 0 or 1, and with NaN at the ends and everywhere.
    * **Fail without the fix.** Every guard has a mutant that fails a test; record which tests fail. Avoid app values equal to an in-flight value: that write is invisible by design.
    * **Prove one-turn behavior with a dispatcher that runs what was queued before the caller goes on.** A blocking dispatcher let a split stop-and-start pass (f0ceb542).
    * **Drive both orders when two events can race,** such as TouchBehavior's release and a tap animation, and the release and the app's own `Tapped` animation, and assert the same result.
    * **Bound every loop test.** A test of an app animation loop caps its restarts and counts those inside the toolkit's call, so a regression into MAUI's abort loop fails instead of hanging the test host.
    * **Translation under a seeker:** assert frames against the seeker on an untouched view (unchanged target) or keyframe + base offset (changed target), at duration 0 and animated.
    * **Device tests survive a stalled UI thread.** Act in the same UI-thread turn that proves the run is mid-way, repeat only attempts that provably missed the run, use no fixed delays to wait for a state, give runs that only the fix should end 60 s, and turn the ticker on with `SystemAnimationsTickerOverride` (CI hosts run with system animations off). See [device-tests.instructions.md](device-tests.instructions.md).
    * **Run every consumer's device category.** A library change runs the animation categories, `KeyframeAnimationExtensions`, `TouchBehavior`, `ImageTouchBehavior` and `ColorAnimationExtensions` on every platform, Windows packaged and unpackaged included.
    * **Turkish.** Run the whole unit suite with `--culture tr-TR` before every push; handles stay `nameof` or `const` inside `AnimationHandle`.
    New tests per primitive and per feature
    Class Pins Mutant that must fail it
    AnimationHandleTests names; CancelAnimations stops exactly the nine; handle checks private scale name; translation not shared
    ValueAnimationTests frame for frame against MAUI per curve, for Linear, CubicInOut, SpringOut, Ease(0) != 0, Ease(1) != 1, NaN and infinity; aborts both ways; inline resume; colour edge cases RunContinuationsAsynchronously; wrong MAUI path; finite check removed
    RoundTripTests today's five suites unchanged; pre-cancelled token; fault; retarget during each part token check after the stop; EndAnimation outside finally; settle removed
    OneWayAnimationTests, PropertyAnimationsTests, AnimationGroupTests own vs foreign abort; every takeover form; DescribeActivity; StopAll; batched WriteTranslation; HasAborted timing target write removed; order swapped; flag set late
    StateAnimationTests v17 handle parity per setter (C6); S1-S4 each rule removed
    TouchBehavior, per decision parity (C6); translation under seekers (C7); app pulse in both tap orders, capped pulse loop (C8); unchanged hover and attach (C9); AnimationBehavior in both event orders at 0 and 160 ms (C10); CancelAnimations (C11); release survives AnimationBehavior (C12); off-thread (C14) each decision reverted
    Device press during seekers; held press during ScaleAnimation; both tap orders on every platform; Windows projection; NaN and infinite easings on ScaleAnimation, RubberBand and TouchBehavior's scale: no exception, no non-finite value on the view per-call projection capture; finite check removed
  3. TheCodeTraveler commented on Nov 20, 2026

    @TheCodeTraveler
    CollaboratorAuthor

    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):

    • During a ScaleAnimation, the app starts its own ScaleToAsync to the value the view already shows.
    • A UI-thread stall makes MAUI's next frame finish the app's animation.
    • That frame runs before the check that Task.Yield posted (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's ScaleToAsync never 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, an Animation added to the view's IAnimationManager during 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's FadeToAsync always won, so for Fade this case is a narrow change from v17.

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    newproposalA fully fleshed out proposal describing a new feature in syntactic and semantic detail

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions