An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
* @file animator.ts
* @input An element, target values, and a spring, momentum curves (coast.ts)
* or any closed-form curve
* @output Exports `createMotionEngine`, a compositor animator for
* translate, rotate, scale and opacity, and its option, handle and
* transition types. It reads presentation values and velocities from the
* analytic curves. It retargets with the velocity kept, freezes in place on
* `stop`, and gives completion promises, a shared clock, and UIKit's
* Reduced Motion substitution.
* @position Motion foundation (DOM). Internal to core: components use it for
* every touch-presentation animation; not exported from the package entry
*
* HOW IT RUNS
*
* Each animated value (x, y, rotate, scaleX, scaleY, opacity) follows a
* closed-form curve: a spring (spring.ts), momentum curves its caller built (a
* UIScrollView coast with an edge bounce, coast.ts), a curve handed to `play` (a spring chasing a moving
* target, a fitted UIKit curve), or a Reduced Motion cross-fade. The curves are baked into
* Web Animations keyframes on the individual transform properties (`translate`,
* `rotate`, `scale`) and `opacity`, sampled adaptively until linear
* interpolation between keyframes is within a fraction of a pixel, and played
* with `easing: linear`. The browser then runs them on its compositor: they
* keep advancing every frame while JavaScript is busy (`spec:AST-094` FR5).
*
* Why keyframes and not one `linear()` easing: measured in Chromium, both
* forms are composited and equally precise for the same samples, but WebKit's
* Core Animation path refuses to accelerate an effect whose easing is
* `linear()` with points (KeyframeEffect::canBeAccelerated) unless its newer
* threaded animations are on, so on older iOS Safari a `linear()` spring would
* run on the main thread. Linear segments between keyframes map directly onto
* a Core Animation keyframe animation. Why the individual properties and not
* `transform`: each can be animated, retargeted or driven by a finger on its
* own (a drag writes `translate` while `scale` keeps springing), with no
* additive composition, which neither engine composites.
*
* The page never reads the DOM to know where something is: `get` and
* `getVelocity` evaluate the curves at a time on the document timeline's
* clock (`performance.now()` by default), so a finger can grab anything
* mid-flight from the value on screen, and a new target starts from the
* current value with the current velocity (`spec:AST-094` FR6). A gesture's release velocity
* can be handed in explicitly instead.
*
* No frame shows a value the element is not at. While a curve runs, the
* element's inline style holds the value the curve starts from (the value on
* screen when it was built), so a frame painted before the compositor has the
* curve (WebKit can receive a new curve a few updates late) shows the element
* where it is, never where it is going. The keyframes hold the end state for a
* while after the curve ends (END_HOLD_MS); the main thread retires a finished
* animation as soon as it runs after the curve's end, writing the end values
* inline in the same task that cancels it, so nothing moves. The hold matters
* when the curve ends during a main-thread block: WebKit's compositor ends an
* animation by falling back to the value its main thread last committed.
*
* Start time: a call that starts from rest (nothing on its channels moving,
* no `options.at`) gets no start time, so the browser starts it when it
* commits it, as Core Animation starts an animation at its transaction's
* commit: a main-thread block before that frame delays the motion instead of
* skipping into it. Everything the call starts, and every
* call from rest in the same task, starts at that one time, which
* `handle.started` reports. Where the compositor starts it and the page
* learns that start only a frame or more later (Chromium), the call starts
* at the frame that commits it, the start the compositor takes, so a
* retarget or a rebase before then continues from the frame on screen. A
* call that continues motion on screen (a retarget, a catch) keeps an
* explicit start: the first motion call of its callback, or `options.at`.
* So calls on several animators in one callback line up. The new curve
* then continues from the frame on screen. A late commit restarts each
* spring at its frame (lookAtShown). Keyframes are sampled from the call's
* start, so a value that keeps moving through a rebuild stays on its curve
* to the frame.
* `options.start` changes that per call. `'commit'` dates a retarget by the
* browser's commit as well. `'presented'` creates the animations of a call
* from rest two frames later, once its element at rest has been presented.
* That serves a UI process that applies commits late. It does not change
* when a retarget starts.
* `handle.curve(property)` hands out the curve a call plays, so a
* companion can follow it on the same clock.
* `options.additive` retargets as UIKit does: the old curve keeps going and a
* curve of the change between the targets is added on top, baked into one
* animation (two animations on one property leave the compositor in both
* engines), so the retarget keeps the velocity on screen.
*
* WebKit dates an animation created just before a block at its last frame
* time before the block, where the first frame after it would show the
* motion skipped into its curve; when the call's own task ran on more than
* two frames, the call's first read of that start moves it to that read, so
* WebKit delays the motion as Chromium's commit does (startAfterBlock). Every
* call of that task moves together, and a shorter task or a read that other
* tasks delay keeps the browser's start, so a sequence chained on a call's
* end (a Reduce Motion cross-fade's second half) keeps its clock.
*
* Promotion: Mobile Safari runs an animation whose start time is set from
* script on its compositor at its first commit only if the element (or the
* pseudo-element) already has a compositing layer; without one, a block
* right after that commit freezes it (iOS 26.2 simulator: 2 of 7 runs kept
* moving, 0 of 5 on a ::before). Every animation the animator creates, and
* every `set` (unless it passes `{promote: false}`), therefore promotes its
* channels in the same task: inline
* `will-change` on the element, merged with the element's own, or the custom
* property `--astryx-motion-will-change-<pseudo>` on the host for a
* pseudo-element, whose style opts in with
* `will-change: var(--astryx-motion-will-change-before, auto)`. That is
* enough (5 of 5, and 4 of 4 through the animator); promotion ends
* PROMOTION_LINGER_MS after the last motion.
*
* Known limits, iOS Safari (measured on the iOS 26.2 simulator):
* - a block in the task that starts a motion delays it: it starts when the
* browser commits it, after the block;
* - an animation created in the task that first displays a dialog stays on
* the main thread: start it in the next animation frame;
* - after a long block, an animation frame's timestamp is when the frame was
* due, so passing it as `at` starts the curve in the past: keep the default
* clock;
* - WebKit does not promote the siblings a moving layer will cross, so a
* moving layer below content can paint over it: give it `z-index: -1`
* inside a parent with `isolation: isolate`;
* - a tap-driven start can show its first moving frame two to four frames
* into the curve (simulator, not yet confirmed on a device).
*
* Reduced Motion (design:reduced-motion): with `prefers-reduced-motion:
* reduce`, every `animate` and `play` (travel or opacity, on a spring or any
* curve) is replaced, and nothing moves, scales or springs. The planner
* (reducedMotionPlan.ts) decides what each call becomes; the animator
* applies the plan and runs its landings:
* - on a coarse primary pointer, or for a call started by a touch drag's
* release on any pointer (`touchRelease`), it becomes (DR2) an
* opacity-only cross-fade of `timing.reducedMotionCrossFadeMs` (200 ms)
* on `timing.curves.move`:
* - entering (opacity rises from 0 in the same call, or `crossfadeAs:
* 'entrance'`): lands in its new place at once and fades in;
* - leaving (opacity falls to 0, or `crossfadeAs: 'exit'`): fades out in
* place, then lands;
* - an opacity change alone: fades to its value;
* - otherwise: dips (fades out, lands, fades back in);
* travel lands with a plain style write while the element is transparent,
* never as an animated transform; a busy main thread only keeps it
* transparent longer, and a dip fades back in from the landing; a later
* call that lands too carries a landing still waiting (two calls in one
* frame land together), and a later opacity change lands it at once;
* - on any other primary pointer (DR3) it completes at once.
* No call option and no role value lengthens the fade or keeps travel (DR4):
* the fade's length is not a role.
*
* Momentum under Reduce Motion (`design:reduced-motion` DR2, DEC-2): a
* decay's momentum continues the velocity a finger handed it on release
* (UIScrollView's coast after a flick, with its bounce at an edge), so it
* keeps its motion, as native momentum does: it is direct movement, not a
* transition. A curve marked `isTransition` (coast()'s spring back from past
* an edge), like a spring a component starts on release toward a target it
* picks (a detent, a page), is a transition: it plays through the Reduce
* Motion policy above, a cross-fade on a coarse pointer or after a touch
* release (`touchRelease`) and at once elsewhere (DR2, DR3).
*
* Roles: every spring and curve the animator plays passes through
* resolveMotion.ts, which names the motion role it plays. `springs.settle`
* registers as its module loads, and the animator registers the Reduce Motion
* fade's curve alone. The per-role tables stay internal
* (`spec:AST-094` DEC-15), so a role plays its table value: nothing reads a
* role's own CSS variable. Its time scales by the tempo of the element's
* theme. A spring written inline at the call
* site, and a table never registered, play as given; the fade's length is not
* a role.
*
* A pseudo-element (`options.pseudoElement`, a dialog's `::backdrop`) has no
* inline style. A static filling animation holds its end value, after a
* curve ends and after `set`, until the next animation replaces it. The hold
* lasts as long as the pseudo-element exists. A value equal to its `base`,
* the values its own stylesheet shows at rest, is not held. The stylesheet
* shows it, so the pseudo-element keeps no compositing layer at rest. In
* development, the first hold dropped this way checks that the stylesheet
* shows it. The browser makes a `::backdrop` again, without the hold, each
* time its dialog opens. So a presentation calls `set` with its starting
* value right after `showModal()`, in the same task. A `set` before it lands
* on the backdrop the open replaces.
*
* SSR-safe: nothing touches `window` or `document` at module scope, and an
* animator created without an element only keeps state until one is attached.
*
* SYNC: When modified, update:
* - /packages/core/src/motion/animator.test.ts
* - /packages/core/src/motion/reducedMotionPlan.ts (the Reduce Motion plan)
* - /packages/core/src/motion/__tests__/animator.interaction.browser.spec.ts
* - /packages/core/src/motion/resolveMotion.ts (the roles it resolves)
* - /packages/core/src/motion/README.md
*/
import {cubicBezier} from './bezier';
import {LATE_START_MS} from './frameBlock';
import {solveSpring, toSpring, type SpringDescription} from './spring';
import {
clearPresentedResolve,
registerPresentedOffset,
type PresentedSource,
writePresentedResolve,
} from './presentation';
import {resolveMotion} from './resolveMotion';
import {
reducedMotionCrossFade,
registerReducedMotionCrossFade,
} from './uikit/timing';
import {planReducedMotion, type ReducedMotionView} from './reducedMotionPlan';
import {themeReducesMotion} from '../privateAttributes/reducedMotion.stylex';
import {devWarn} from '../utils/devWarning';
declare const process: {readonly env: {readonly NODE_ENV?: string}};
/**
* A value the animator can drive.
*/
export type MotionProperty =
'x' | 'y' | 'rotate' | 'scaleX' | 'scaleY' | 'opacity';
/**
* Values by property; `scale` sets `scaleX` and `scaleY` together.
*/
export type MotionValues = Partial<Record<MotionProperty | 'scale', number>>;
/**
* A spring and the velocity it starts with.
*/
export interface SpringTransition {
/** The spring, in any vocabulary of the constants table. */
spring: SpringDescription;
/**
* Initial velocities in units per second (px/s, deg/s, 1/s), for example a
* gesture's release velocity. A property without one keeps the velocity it
* has on screen.
*/
velocity?: MotionValues;
}
/** What `Animator.rebase` takes besides the amounts. */
export interface RebaseOptions {
/** Time of the shift on the document timeline (ms). Defaults to now. */
at?: number;
/**
* Per property, the value its spring heads for after the shift. A spring
* whose target plus its amount lands there moves whole, before its first
* frame and once its start is known. Its curve and target move by the
* amount. It keeps its start time and velocity, as when the element's
* resting place moves under a curve that keeps going. If its first frame
* has run while its start is unread, only the model moves. The next call
* on the channel in the same task rebuilds its animation, or else the end
* of the task does.
*/
towards?: MotionValues;
}
/**
* Options of `animate` and `play`: the spring, a release velocity, the Reduced
* Motion handling.
*/
export interface AnimateOptions {
/**
* Start time on the document timeline (ms, `performance.now()` clock).
* Defaults to now. Pass one value to several animators to put their
* animations on one clock.
*/
at?: number;
/**
* The call starts from the release of a touch drag (a sheet let go, a swipe
* back released). Under Reduced Motion it then cross-fades whatever the
* primary pointer (design:reduced-motion DR2), where another call on a
* fine primary pointer completes at once (DR3). The gesture host knows;
* nothing is inferred from the last pointer.
*/
touchRelease?: boolean;
/**
* Which way the substituted cross-fade goes when the call's own opacity
* does not say (a sheet slides in or out without fading): `'entrance'`
* lands the travel at once and fades the opacity in from 0; `'exit'` fades
* it out in place, then lands the travel and returns the opacity to its
* value. The call's targets stay the end state; without Reduced Motion this
* changes nothing.
*/
crossfadeAs?: 'entrance' | 'exit';
/**
* When the call's animations start. By default a call from rest starts
* when the browser commits it. A call that continues motion on screen (a
* retarget) starts now, from the value on screen. A curve whose tail
* already shows as at rest counts as rest. Ignored with `at`.
* - `'commit'`: a call that continues motion also starts when the browser
* commits it. The browser dates it, as it dates a call from rest.
* - `'presented'`: a call from rest leaves its element at rest. Its
* animations are created two frames later, once the frame with the
* element at rest has been presented. They then start at their commit,
* so a busy UI process delays the motion instead of skipping into it.
* Any other change to the animator before then creates the animations
* first, in call order. A call that continues motion on screen starts
* now, as by default.
*/
start?: 'commit' | 'presented';
/**
* A call that retargets a curve on screen adds to it instead of replacing
* it, as UIKit's animations do: the old curve keeps going (past its end, at
* its target) and a spring of the difference between the two targets runs
* from 0 on top, in the same animation. Its value and velocity at the call
* are the old curve's, so whichever frame first shows it (WebKit can apply
* a new curve tens of ms late), nothing steps back. Ignored for a property
* at rest or still waiting for the browser's start, for a property given a
* velocity, and under Reduced Motion. Use it for a played curve that starts
* at rest (an eased reversal) while the property moves; a spring retarget
* on the same spring moves the same either way, and a curve that already
* continues the velocity on screen must not add to it.
*/
additive?: boolean;
}
/**
* Any closed-form curve to play on the compositor (`Animator.play`, and a
* release's coast through `Animator.decay`): a spring chasing a moving
* target, a piecewise curve, a fitted UIKit curve. Times are seconds from
* the curve's start; the value at `duration` is the end state. Start it at
* the property's presentation value (`get`) to continue without a jump.
*/
export interface MotionCurve {
/** Length, s. */
readonly duration: number;
/** Value `t` seconds after the start (0 ≤ t ≤ duration). */
at(t: number): number;
/** Velocity `t` seconds after the start, units/s. */
velocity(t: number): number;
/**
* A transition started on release rather than a throw's momentum (a
* spring back from past an edge): under Reduce Motion it is no coast and
* cross-fades like `animate` (`design:reduced-motion` DR2).
*/
readonly isTransition?: boolean;
}
/** How `set` puts values in place. */
export interface SetOptions {
/**
* Whether the write promotes its channels to a compositing layer, as a
* drag's per-frame writes need so each is a composite only (default
* true). `false` writes the values and nothing else: a one-off switch that
* must not give its element a layer, such as a veil under a sticky header
* switched during a programmatic scroll (on iOS 26.2, a layer there blanks
* the header's painted items for about two frames). A channel another
* motion keeps promoted stays promoted, and a channel with other motion
* still running gets its animation's layer as usual.
*/
promote?: boolean;
}
/**
* Options of `createMotionEngine`.
*/
export interface AnimatorOptions {
/**
* Animates a pseudo-element of the element instead (`'::backdrop'` of a
* native dialog). A pseudo-element has no inline style. So a static filling
* animation holds its value after a curve ends and after `set`, unless the
* value is its `base`.
*/
pseudoElement?: string;
/** Starting values; identity by default. Never read from the DOM. */
initial?: MotionValues;
/**
* For a pseudo-element: the values its own stylesheet shows at rest. A
* value equal to its base needs no holding animation, so the
* pseudo-element keeps no compositing layer there. Declare only what the
* stylesheet shows: in development, the first hold dropped warns when the
* computed style differs.
*/
base?: MotionValues;
/** Clock in ms on the document timeline's time base. */
now?: () => number;
/**
* Runs a callback in the next animation frame, with the frame's timestamp;
* `requestAnimationFrame` by default. A call from rest reads the start the
* browser gave it there.
*/
requestFrame?: (callback: (frame?: number) => void) => void;
}
/**
* One `animate` / `decay` call's animations.
*/
export interface MotionHandle {
/** The properties this call drives. */
readonly properties: ReadonlyArray<MotionProperty>;
/**
* True when every property reached the end of this call's curve, false
* as soon as any of them is retargeted, stopped or set before that.
*/
readonly finished: Promise<boolean>;
/**
* When the motion started on the document timeline (ms): for a call from
* rest, the time the browser committed it (a block before the first frame
* moves it later); otherwise the call time, or `at`. A retarget whose
* frame comes late starts its springs at that frame, and this stays the
* call time.
*/
readonly started: Promise<number>;
/** Presentation value of a property at `time` (default now). */
value(property: MotionProperty, time?: number): number;
/** Presentation velocity of a property at `time`, units/s. */
velocity(property: MotionProperty, time?: number): number;
/**
* The curve this call started on `property` (`scale` reads `scaleX`),
* in seconds from the call's start: what the keyframes play. Null for a
* property the call does not move, or moves without travel (Reduced
* Motion). Map it onto a companion property with `mapProgress`, and play
* that on the same clock. A retarget whose frame comes late starts its
* spring again at that frame, and this stays the curve the call started.
*/
curve(property: MotionProperty | 'scale'): MotionCurve | null;
/** New targets for this call's properties, keeping their velocity. */
retarget(
to: MotionValues,
transition?: SpringTransition,
options?: AnimateOptions,
): MotionHandle;
/** Freezes this call's properties at their presentation values. */
stop(): void;
}
/**
* A compositor animator bound to one element (see the file header).
*/
export interface Animator {
/**
* What Reduced Motion makes of a call on this element right now:
* `'off'` (motion plays), `'crossfade'` (an opacity-only fade: a coarse
* pointer, or `touchRelease`) or `'instant'` (any other pointer). For
* feedback that has no fade of its own (a press lift, a lens chasing the
* finger): skip it unless `'off'`.
*/
reducedMotion(options?: {
touchRelease?: boolean;
}): 'off' | 'crossfade' | 'instant';
/** The element the animator writes to, if attached. */
readonly element: HTMLElement | null;
/**
* Attaches (or detaches, with null) the element. Attaching writes the
* current state and resumes running curves from now.
*/
attach(element: HTMLElement | null): void;
/** Presentation value at `time` (default now), from the curve. */
get(property: MotionProperty | 'scale', time?: number): number;
/** Presentation velocity at `time` (default now), units/s. */
getVelocity(property: MotionProperty | 'scale', time?: number): number;
/**
* Puts values in place now, ending their animations: the per-frame write
* of a drag (one style write per channel, no animation when nothing else
* on the channel is moving).
*/
set(values: MotionValues, options?: SetOptions): void;
/** Springs to `to` from the presentation values. */
animate(
to: MotionValues,
transition: SpringTransition,
options?: AnimateOptions,
): MotionHandle;
/**
* Plays given curves (`scale` drives both axes), baked like a spring:
* presentation values, velocities, `stop`, `finished` and the shared
* clock work the same, and a later `animate` starts from the curve's
* value and velocity. Reduced Motion treats a curve that moves x, y, rotate
* or scale as travel, which the policy replaces (design:reduced-motion: a
* cross-fade after a touch, an immediate change otherwise). Its handle has
* no spring of its own: `retarget` needs one.
*/
play(
curves: Partial<Record<MotionProperty | 'scale', MotionCurve>>,
options?: AnimateOptions,
): MotionHandle;
/**
* Plays momentum curves as given, on the translate axes only: a released
* scroll view's coast and edge bounce, which `coast()` (coast.ts) builds
* from a finger's release velocity. Under Reduce Motion momentum keeps
* its motion: it continues a throw, direct movement (design:reduced-motion
* DR2, DEC-2). A curve marked `isTransition` (coast()'s spring back from
* past an edge) is a transition and plays through the Reduce Motion
* policy, as `animate` does. Anything else (a fade, a slide a tap starts)
* is a transition too: play it with `play` or `animate`. Pass
* `touchRelease` when a touch drag's release starts it, so a spring back
* cross-fades on any pointer (DR2). Only a surface that coasts imports the
* coast math and the scroll table.
*/
decay(
curves: Partial<Record<'x' | 'y', MotionCurve>>,
options?: Pick<AnimateOptions, 'at' | 'touchRelease'>,
): MotionHandle;
/**
* Moves properties by the given amounts at once, as when a layout shift
* moves the element under them: a property moving on a spring keeps its
* spring, velocity and target (the curve restarts from the shifted value);
* any other moving curve shifts whole, its end included; a resting
* property takes the offset and stays. `towards` moves some springs whole
* instead (RebaseOptions).
*/
rebase(deltas: MotionValues, options?: RebaseOptions): void;
/** Freezes properties (all by default) at their presentation values. */
stop(properties?: ReadonlyArray<MotionProperty | 'scale'>): void;
/**
* Resolves once none of `properties` (every property by default) is moving:
* after the last curve ends, whoever started it, retargets included.
*/
atRest(properties?: ReadonlyArray<MotionProperty | 'scale'>): Promise<void>;
/** Cancels everything and detaches. */
dispose(): void;
}
// ---------------------------------------------------------------------------
// Curves
// ---------------------------------------------------------------------------
interface Segment {
/**
* Start on the document timeline, ms. A call started from rest moves it to
* the time the browser committed the animation (StartGroup).
*/
start: number;
/** Length in ms (finite). */
readonly duration: number;
/** Value from the end on. */
readonly target: number;
/** Value `t` ms after the start (0 ≤ t ≤ duration). */
at(t: number): number;
/** Velocity `t` ms after the start, units/s. */
speed(t: number): number;
/** Times (ms after the start) where the value jumps; `at` is right-continuous. */
readonly jumps: ReadonlyArray<number>;
/**
* The curve a `play` call gave, which other calls in its task can share. A
* segment whose values move from that curve's has none.
*/
readonly source?: MotionCurve;
/** A Reduce Motion fade: an interruption finishes it instead of freezing it. */
readonly isFade?: true;
readonly owner: HandleState;
/** The call's start group while its start waits for the commit. */
group?: StartGroup;
/** The spring driving it, when one does (`rebase` keeps it). */
spring?: SpringDescription;
/** The old curve plus a spring of the difference (`additive`). */
readonly isAdditive?: true;
/** A velocity the call handed the spring, such as a release's. */
readonly handedVelocity?: number;
}
/**
* A call started from rest. Its animations are created without a start time,
* so the browser starts them when it commits them, as Core Animation starts
* an animation at its transaction's commit: a main-thread block before that
* frame delays the motion instead of skipping into it. Until then the curves
* read from the call time; once the browser's start is known they move to it.
*/
interface StartGroup {
readonly provisional: number;
/**
* Its animations were created in the running task: the browser cannot have
* started them yet, so nothing reads their start time until it ends.
*/
fresh: boolean;
readonly segments: Segment[];
readonly animations: Animation[];
readonly channels: Set<Channel>;
resolved: boolean;
/**
* The first frame after the call has run: a start read later is the
* browser's, whatever it says (startAfterBlock).
*/
framed?: boolean;
/**
* Made in an animation-frame callback of an animator's own (a presented
* call's second frame): the browser commits its animations in that frame,
* so the frame after it is not the one that starts them.
*/
madeInFrame?: boolean;
/** The task it was made in, with every call made in that task. */
task?: TaskMark;
/**
* Per channel, when its animation's first frame ran without a known start.
* That frame came too late to stand for the start, and the browser had not
* told it yet. The compositor starts the animation within about a frame of
* this time. Until the browser tells its start, a read of the channel takes
* the curve from here.
*/
latest?: Map<Channel, number>;
/** A later call in the same task that took over its curves. */
adoptedBy?: StartGroup;
readonly resolve: (start: number) => void;
readonly started: Promise<number>;
}
/** An atRest() call waiting for its curves to end. */
interface RestWait {
timer: ReturnType<typeof setTimeout> | null;
settle: () => void;
}
interface HandleState {
resolve: (finished: boolean) => void;
settled: boolean;
timer: ReturnType<typeof setTimeout> | null;
}
/**
* Reduced Motion travel that lands with a plain style write while the
* element is fully transparent (never an animated transform), then, in a
* dip, the fade back in.
*/
interface Landing {
/**
* The call that settles when the landing (and its fade back in) ends; a
* call that joins the dip takes it over, and the call it replaces is
* carried.
*/
owner: HandleState;
/** ms after the call's start. */
readonly at: number;
readonly values: Map<MotionProperty, number>;
/**
* The fade back in that follows the landing (a dip); `isBorrowed` when it
* returns to the stylesheet's opacity, which owns it again once it ends.
*/
fadeIn: {
readonly to: number;
readonly ms: number;
readonly isBorrowed?: boolean;
} | null;
/** The opacity written with the landing (an exit by role). */
restore: number | null;
/**
* The restore returns to the stylesheet's opacity (an exit by role on a
* surface no call owns opacity on): the stylesheet owns it again.
*/
restoreIsBorrowed?: boolean;
/** Earlier calls whose landings this one carries: they land with it. */
readonly carried: HandleState[];
/** Whose move each value is: a carried value keeps its own call. */
readonly owners: Map<MotionProperty, HandleState>;
timer: ReturnType<typeof setTimeout> | null;
/** When it is due on the document timeline, once the call has started. */
due: number | null;
}
/** What Reduced Motion makes of a call: its segments, and any landing. */
interface ReducedPlan {
readonly next: Partial<Record<MotionProperty, Segment | null>>;
/** Values that stay where they are until the landing writes them. */
readonly holds: Partial<Record<MotionProperty, number>>;
readonly landing: Omit<
Landing,
'owner' | 'timer' | 'carried' | 'owners' | 'due'
> | null;
/** The stylesheet opacity a dip borrowed (no call owns opacity). */
readonly borrowed?: number | null;
/** The call joins the waiting dip (see the planner's `joins`). */
readonly joins?: boolean;
}
const PROPERTIES: ReadonlyArray<MotionProperty> = [
'x',
'y',
'rotate',
'scaleX',
'scaleY',
'opacity',
];
/** The axes momentum moves: `decay` takes only these (DR2, DEC-2). */
const DECAY_PROPERTIES: ReadonlyArray<'x' | 'y'> = ['x', 'y'];
const IDENTITY: Record<MotionProperty, number> = {
x: 0,
y: 0,
rotate: 0,
scaleX: 1,
scaleY: 1,
opacity: 1,
};
/**
* Within this of its target a curve is over (in the property's own unit). A
* curve built outside the animator (a progress curve) settles where a call
* would with this as its epsilon.
*/
export const SETTLE_THRESHOLD: Record<MotionProperty, number> = {
x: 0.05,
y: 0.05,
rotate: 0.01,
scaleX: 0.0001,
scaleY: 0.0001,
opacity: 0.001,
};
/**
* Keyframes are added until linear interpolation is within this: a quarter of
* a device pixel (this quarter of a CSS pixel, divided by the device pixel
* ratio where it is above 1), a twentieth of a degree, a 2000th of the size,
* about one step of an 8-bit alpha. Every one is below what a moving element
* can show.
*/
const SAMPLE_TOLERANCE: Record<MotionProperty, number> = {
x: 0.25,
y: 0.25,
rotate: 0.05,
scaleX: 0.0005,
scaleY: 0.0005,
opacity: 0.004,
};
/** Keyframes start on this grid (ms) and are split where the curve needs it. */
const SAMPLE_GRID_MS = 1000 / 30;
/**
* A curve within this many sample tolerances of its target can show as at
* rest. A call on it then starts as one from rest does, at the browser's start.
*/
const REST_DISTANCE_TOLERANCES = 2;
/**
* A curve shows as at rest only while it moves at most one `SAMPLE_TOLERANCE`
* a frame at this rate.
*/
const REST_FRAMES_PER_SECOND = 60;
/** A curve that has not settled by then (an undamped spring) snaps. */
const MAX_DURATION_MS = 30_000;
/**
* How close a spring's target and a value must be to count as the same, in
* the property's own units. Only float rounding separates two ways of
* computing one value, far below anything the screen shows.
*/
const SAME_VALUE = 1e-6;
/**
* The task calls from rest are made in, shared by every call made in it
* (every animator's), so one motion's parts that are separate calls start
* together (startAfterBlock).
*/
interface TaskMark {
/**
* When its first call from rest created animations: the call itself, or a
* presented call's second frame.
*/
readonly first: number;
/** When the task ended, at its first microtask. */
ended?: number;
/** The start every call of a blocked task moves to, set by its first read. */
at?: number;
}
/** The task the current calls from rest are made in, until it ends. */
let openTask: TaskMark | null = null;
/** How many of the animators' animation-frame callbacks are running now. */
let frameDepth = 0;
/** The mark of the running task, opened by its first call from rest. */
function markTask(time: number, clock: () => number): TaskMark {
if (openTask == null) {
const task: TaskMark = {first: time};
openTask = task;
queueMicrotask(() => {
task.ended = clock();
openTask = null;
});
}
return openTask;
}
/** The first read of the time an animation frame runs, by its timestamp. */
let frameRead: {readonly frame: number; readonly time: number} | null = null;
/** The first motion call on a clock since the last microtask checkpoint. */
let openCall: {readonly time: number; readonly clock: () => number} | null =
null;
/**
* The time of a motion call with no explicit clock. It is the time of the
* first such call on the same clock since the last microtask checkpoint. One
* event listener or frame callback thus shares one clock. So calls on
* several animators in one callback, such as a pager's children, line up, as
* calls from rest share one start. A call more than LATE_START_MS after the
* first opens a new clock: the curves that a block passed restart at their
* frame instead.
*/
function callTime(clock: () => number): number {
const time = clock();
if (
openCall != null &&
openCall.clock === clock &&
time - openCall.time <= LATE_START_MS
) {
return openCall.time;
}
const call = {time, clock};
openCall = call;
queueMicrotask(() => {
if (openCall === call) {
openCall = null;
}
});
return time;
}
/**
* Promotions that wait for their stylesheet's will-change, from every
* animator, until the running callback's microtasks run.
*/
const sheetReads: SheetRead[] = [];
/** One element's wait in sheetReads. */
interface SheetRead {
/** Takes the promotion off the element, so a read sees its stylesheet. */
readonly lift: () => void;
readonly read: () => void;
/** Writes the promotion back with the stylesheet's reasons. */
readonly write: () => void;
}
/**
* Queues an element's stylesheet read for a microtask after the callback.
* That microtask lifts every queued promotion, reads every stylesheet, and
* then writes every promotion back. So motions that one callback starts force
* one style pass, not one per element.
*/
function queueSheetRead(read: SheetRead) {
if (sheetReads.length === 0) {
queueMicrotask(flushSheetReads);
}
sheetReads.push(read);
}
function flushSheetReads() {
const reads = sheetReads.splice(0);
for (const read of reads) {
read.lift();
}
for (const read of reads) {
read.read();
}
for (const read of reads) {
read.write();
}
}
/**
* Per animator, the first of its calls that still wait for the frame that
* commits them. An animator removes its entry once nothing of its waits: a
* rebuild or a hidden page committed its calls, or it was disposed or moved.
* The frame's first read takes every entry.
*/
const waitingCalls = new Map<object, number>();
/** The first waiting call, read once by the frame with this timestamp. */
let waitingRead: {readonly frame: number; readonly first: number} | null = null;
/**
* The first call that the animation frame with timestamp `frame` commits.
* The frame reads it once, so every animator in it judges a late commit from
* the same call. `own` is the first of the reading animator's calls.
*/
function firstCommitted(frame: number | undefined, own: number): number {
if (frame != null && waitingRead?.frame === frame) {
return Math.min(waitingRead.first, own);
}
const first = Math.min(own, ...waitingCalls.values());
// The frame commits every call that waits now. An animator whose look
// never runs, such as one on another frame source, counts once at most.
waitingCalls.clear();
if (frame != null) {
const read = {frame, first};
waitingRead = read;
// A browser runs every callback of a frame before its next task.
setTimeout(() => {
if (waitingRead === read) {
waitingRead = null;
}
}, 0);
}
return first;
}
/**
* The time the animation frame with timestamp `frame` runs, read once in
* that frame. Every animator's callback in the frame takes that read, so the
* calls from rest that one frame commits start together. A long callback
* before them does not move their start. A call on a moving element keeps
* its own clock. The read ends with the frame's task, so a frame
* source that repeats a timestamp still reads each frame anew. A frame
* source with no timestamp reads the clock.
*/
function frameTime(frame: number | undefined, clock: () => number): number {
if (frame == null) {
return clock();
}
if (frameRead?.frame === frame) {
return frameRead.time;
}
const read = {frame, time: clock()};
frameRead = read;
// A browser runs every callback of a frame before its next task.
setTimeout(() => {
if (frameRead === read) {
frameRead = null;
}
}, 0);
return read.time;
}
/**
* What the calls of the running task have baked. A call that plays the same
* curve objects reuses them: a row of items that one curve moves samples it
* once. Cleared at the next microtask checkpoint.
*/
interface TaskBakes {
/** Sample times, from the bake's start, by curve, offset and tolerance. */
readonly times: {readonly key: unknown[]; readonly times: number[]}[];
/** Keyframes, by curves, offsets and the channel's rest values. */
readonly keyframes: {
readonly key: unknown[];
readonly keyframes: Keyframe[];
effect: AnimationEffect | null;
}[];
}
let taskBakes: TaskBakes | null = null;
function bakesOfTask(): TaskBakes {
if (taskBakes == null) {
const bakes: TaskBakes = {times: [], keyframes: []};
taskBakes = bakes;
queueMicrotask(() => {
if (taskBakes === bakes) {
taskBakes = null;
}
});
}
return taskBakes;
}
function isSameKey(a: unknown[], b: unknown[]): boolean {
return a.length === b.length && a.every((value, i) => Object.is(value, b[i]));
}
/** Whether the engine can copy an effect with its parsed keyframes. */
function isCopyable(effect: AnimationEffect | null): effect is KeyframeEffect {
return (
typeof KeyframeEffect === 'function' &&
typeof Animation === 'function' &&
effect instanceof KeyframeEffect
);
}
/**
* Plays a copy of `effect` on `element`, as `element.animate` would play the
* same keyframes and timing, without parsing them again.
*/
function copyAnimation(effect: KeyframeEffect, element: Element): Animation {
const copy = new KeyframeEffect(effect);
copy.target = element;
const animation = new Animation(copy, element.ownerDocument.timeline);
animation.play();
return animation;
}
/** Above this many keyframes the tolerance is relaxed. */
const MAX_KEYFRAMES = 1200;
/**
* The keyframes hold the end state this long after a curve ends. An engine
* whose compositor ends an animation while the main thread is blocked falls
* back to the value its main thread last committed, the curve's start
* (WebKit on Linux); the hold keeps the end state on screen through any such
* block. It only stretches the last keyframe. The main thread retires the
* animation as soon as it runs after the curve's end.
*
* Why a tail inside the curve's own animation, with a bound (measured Oct 24
* 2026; do not replace it without these proofs):
* - WebKit on Linux (WebKitGTK and WPE) ignores `fill` on its compositor:
* a 400 ms move that ends during a 1 s main-thread block snaps back to the
* block-start position 13 ms after its end, with `fill: forwards` or with
* no fill, and holds with this tail. iOS 26.2 Mobile Safari holds the end
* in all three forms, so there the tail is unneeded but harmless (measured
* Oct 25 2026). The browser proof "a spring that ends inside the block
* keeps showing its end state" catches it.
* - A separate static animation of the end state under the curve would hold
* it without a bound, but two animations on one property push Chromium to
* run the curve on the main thread: the 1 s block proof moved in 0 of 57
* frames, the start-before-a-block proof failed, and seeking the curve
* broke.
*/
export const END_HOLD_MS = 60_000;
/** How often a paused animation is looked at again for retiring, ms. */
const RETIRE_RECHECK_MS = 100;
/**
* The soonest a running animation's end is looked for again, ms: a frame at
* 60 Hz. WebKit moves an animation's currentTime once per frame, so a look
* within a frame reads the frame's time, a fraction of a ms short of the end,
* and a timer for that fraction would fire again before anything moved.
*/
const END_RECHECK_MS = 1000 / 60;
/** How long an element stays promoted after its last motion, ms. */
export const PROMOTION_LINGER_MS = 500;
type Channel = 'translate' | 'rotate' | 'scale' | 'opacity';
const CHANNELS: Record<Channel, ReadonlyArray<MotionProperty>> = {
translate: ['x', 'y'],
rotate: ['rotate'],
scale: ['scaleX', 'scaleY'],
opacity: ['opacity'],
};
const CHANNEL_OF: Record<MotionProperty, Channel> = {
x: 'translate',
y: 'translate',
rotate: 'rotate',
scaleX: 'scale',
scaleY: 'scale',
opacity: 'opacity',
};
function round(value: number, digits: number): number {
return Number(value.toFixed(digits));
}
function format(
channel: Channel,
value: (property: MotionProperty) => number,
): string {
switch (channel) {
case 'translate':
return `${round(value('x'), 3)}px ${round(value('y'), 3)}px`;
case 'rotate':
return `${round(value('rotate'), 4)}deg`;
case 'scale':
return `${round(value('scaleX'), 5)} ${round(value('scaleY'), 5)}`;
case 'opacity':
return `${round(Math.min(1, Math.max(0, value('opacity'))), 4)}`;
}
}
/**
* Whether a computed value shows `expected` (`format`'s text). An unset or
* `none` value is the channel's identity. One value of a two-value channel
* stands for both (scale), or for x with y at 0 (translate).
*/
function sameShown(channel: Channel, shown: string, expected: string): boolean {
const numbers = (text: string): number[] => {
const values = (
text === '' || text === 'none' ? IDENTITY_TEXT[channel] : text
).match(/-?\d*\.?\d+(?:e-?\d+)?/g);
const list = (values ?? []).map(Number);
if (channel === 'translate') {
return [list[0] ?? 0, list[1] ?? 0];
}
if (channel === 'scale') {
return [list[0] ?? 1, list[1] ?? list[0] ?? 1];
}
return list.length > 0 ? list : [channel === 'opacity' ? 1 : 0];
};
const a = numbers(shown);
const b = numbers(expected);
return (
a.length === b.length &&
a.every((value, i) => Math.abs(value - b[i]) < 1e-3)
);
}
const shared = new WeakMap<HTMLElement, Map<string, Animator>>();
/**
* The one animator for `element` (and `options.pseudoElement`), created on
* first use. Code that animates one element from several places (a swipe on
* x, a removal on y) shares it, so their curves compose in one `translate`
* track and retargeting one axis leaves the other on its curve; two
* animators on one element would overwrite each other. `options` apply
* when it is created; later calls get the same animator. Never `attach` it
* elsewhere or `dispose` it: it lives as long as the element.
*/
export function animatorFor(
element: HTMLElement,
options: AnimatorOptions = {},
): Animator {
let byPseudo = shared.get(element);
if (byPseudo == null) {
byPseudo = new Map();
shared.set(element, byPseudo);
}
const key = options.pseudoElement ?? '';
let animator = byPseudo.get(key);
if (animator == null) {
animator = createMotionEngine(element, options);
byPseudo.set(key, animator);
}
return animator;
}
/**
* The inline text for a channel: `format`, except that an identity transform
* is written `none`. Any other value, `translate: 0px 0px` included, makes
* the element the containing block of its `position: fixed` descendants and
* a stacking context, so a motion back to identity would leave a fixed child
* moved with its parent; Mobile Safari also lets no finger scroll a list
* inside an element left at `scale: 1`. At rest the identity leaves the
* element entirely when its stylesheet agrees (`releaseIdentity`).
*/
function inlineText(
channel: Channel,
value: (property: MotionProperty) => number,
): string {
const at = (property: MotionProperty, identity: number, digits: number) =>
round(value(property), digits) === identity;
switch (channel) {
case 'translate':
return at('x', 0, 3) && at('y', 0, 3) ? 'none' : format(channel, value);
case 'rotate':
return at('rotate', 0, 4) ? 'none' : format(channel, value);
case 'scale':
return at('scaleX', 1, 5) && at('scaleY', 1, 5)
? 'none'
: format(channel, value);
case 'opacity':
return format(channel, value);
}
}
/** What `inlineText` writes for each channel at identity. */
const IDENTITY_TEXT: Record<Channel, string> = {
translate: 'none',
rotate: 'none',
scale: 'none',
opacity: '1',
};
/** Whether a computed value (or an unset one) is the channel's identity. */
export function isIdentityText(channel: Channel, text: string): boolean {
const value = text.trim();
if (value === '' || value === 'none') {
return true;
}
const numbers = value.split(/\s+/).map(part => Number.parseFloat(part));
if (numbers.some(number => !Number.isFinite(number))) {
return false;
}
const identity = channel === 'scale' || channel === 'opacity' ? 1 : 0;
return numbers.every(number => Math.abs(number - identity) < 1e-6);
}
function expand(values: MotionValues): Partial<Record<MotionProperty, number>> {
const out: Partial<Record<MotionProperty, number>> = {};
for (const [key, value] of Object.entries(values)) {
if (value == null || !Number.isFinite(value)) {
continue;
}
if (key === 'scale') {
out.scaleX ??= value;
out.scaleY ??= value;
} else if ((PROPERTIES as ReadonlyArray<string>).includes(key)) {
out[key as MotionProperty] = value;
}
}
return out;
}
/** The time the motion clock reads (`performance.now()`'s time base). */
export function motionNow(): number {
return typeof performance === 'undefined' ? Date.now() : performance.now();
}
/**
* Whether the user asked for reduced motion (`prefers-reduced-motion:
* reduce`), read at the moment of the call: the preference the animator uses
* by default for its Reduce Motion substitution. A component never reads it
* to pick a curve of its own: its motion settings do not override the
* policy (design:reduced-motion DR4); `animator.reducedMotion()` or
* `reducedMotionFade()` gives the policy's answer. False without a window
* (server rendering).
*/
export function defaultPrefersReducedMotion(): boolean {
return (
typeof window !== 'undefined' &&
typeof window.matchMedia === 'function' &&
window.matchMedia('(prefers-reduced-motion: reduce)').matches
);
}
/** Whether the primary pointer is coarse: `(pointer: coarse)`. */
export function defaultIsCoarsePointer(): boolean {
return (
typeof window !== 'undefined' &&
typeof window.matchMedia === 'function' &&
window.matchMedia('(pointer: coarse)').matches
);
}
/**
* The transition `decay` hands a Reduce Motion transition curve to: under
* Reduce Motion `animate` plays no spring (a cross-fade, or at once), so the
* spring itself is never solved.
*/
const REDUCED_TRANSITION: SpringTransition = {
spring: {duration: 0.5, bounce: 0},
};
/**
* Creates an animator for `element` (or for an element attached later).
*
* @example
* ```
* const animator = createMotionEngine(sheet);
* // finger lifts at 1200 px/s heading for the detent at 0 (a component
* // passes the spring of its motion role):
* animator.animate({y: 0}, {spring: {response: 0.45, dampingRatio: 0.9}, velocity: {y: 1200}});
* // the finger lands again: where is it right now?
* const y = animator.get('y', event.timeStamp);
* animator.stop(['y']);
* ```
*/
export function createMotionEngine(
element: HTMLElement | null,
options: AnimatorOptions = {},
): Animator {
const now = options.now ?? motionNow;
const frameSource =
options.requestFrame ??
(typeof requestAnimationFrame === 'function'
? (callback: (frame?: number) => void) => {
requestAnimationFrame(frame => callback(frame));
}
: null);
// Every frame callback of an animator's counts itself, so a call made in
// one knows its animations commit in that frame.
const requestFrame =
frameSource == null
? null
: (callback: (frame?: number) => void) => {
frameSource(frame => {
frameDepth += 1;
try {
callback(frame);
} finally {
frameDepth -= 1;
}
});
};
const pseudoElement = options.pseudoElement;
// Reduced Motion reads the person's settings and nothing else: no option
// overrides them (design:reduced-motion DR4). A theme that reduces motion
// for everyone counts as the setting.
const prefersReducedMotion = () =>
defaultPrefersReducedMotion() || themeReducesMotion(target);
const isCoarsePointer = defaultIsCoarsePointer;
const resting: Record<MotionProperty, number> = {
...IDENTITY,
...expand(options.initial ?? {}),
};
const base = expand(options.base ?? {});
const segments = new Map<MotionProperty, Segment>();
const running = new Map<Channel, Animation>();
/** Drops a finished, still-filling animation once the main thread runs. */
const retireTimers = new Map<Channel, ReturnType<typeof setTimeout>>();
/**
* Animations whose retire looks again at the next frame (scheduleRetire):
* each its own, so one still waiting for a replaced animation does not
* stand in for the next.
*/
const retireFrames = new Set<Animation>();
/** The timer that starts those looks a frame before a curve's end. */
const retireLooks = new Map<Channel, ReturnType<typeof setTimeout>>();
const touched = new Set<Channel>();
/**
* The stylesheet's opacity a Reduce Motion dip borrowed because no call
* owned opacity; the dip runs from and back to it, then hands it back.
*/
let borrowedOpacity: number | null = null;
let target: HTMLElement | null = null;
/** Calls from rest whose start still waits for the browser's commit. */
const pendingGroups = new Set<StartGroup>();
/** atRest() calls still waiting; dispose settles them. */
const restWaits = new Set<RestWait>();
/** A detach that settles as an unmount at the end of the task, unless an attach follows. */
let unmountQueued = false;
/**
* The node the latest attach(null) detached, while its unmount is pending:
* a waiting Reduce Motion move lands there, so that node is left visible
* where it was going.
*/
let lastDetached: HTMLElement | null = null;
/** Runs `write` with the pending unmount's node as the target. */
const onLastDetached = (write: () => void) => {
const current = target;
target = target ?? lastDetached;
try {
write();
} finally {
target = current;
}
};
/** The call being committed, when it starts from rest. */
let callGroup: StartGroup | null = null;
/** The element reported to presentation.ts while translate moves. */
let presented: Element | null = null;
/**
* The translate the engine hit-tests the element at while the compositor
* moves it: where the animation started, or where a `resolve` left it.
*/
let hitTested = {x: 0, y: 0};
let unpresent: (() => void) | null = null;
/** Channels promoted to the element's compositing layer (will-change). */
const promoted = new Set<Channel>();
/** The element's own inline will-change, restored when promotion ends. */
let ownWillChange: string | null = null;
/** The stylesheet's will-change when there is no inline value. */
let sheetWillChange = '';
/**
* Whether sheetWillChange holds a read of the element's current style: it
* is read in the task after the element is attached, and again after each
* demotion, so a promotion (a drag's first move) reads no style in its
* own task.
*/
let sheetWillChangeRead = false;
/** The pending read of sheetWillChange, cancelled with its element. */
let sheetReadTimer: ReturnType<typeof setTimeout> | null = null;
/** The node whose promotion waits in sheetReads for its stylesheet. */
let sheetReadQueuedFor: HTMLElement | null = null;
let demoteTimer: ReturnType<typeof setTimeout> | null = null;
/** A pseudo-element is promoted through a custom property on its host. */
const promotionProperty =
pseudoElement == null
? null
: `--astryx-motion-will-change-${pseudoElement.replace(/^:+/, '')}`;
/** Channels whose identity the last node held inline (see `attach`). */
let heldIdentity = new Set<Channel>();
// -- reading the curves ---------------------------------------------------
const segmentAt = (
property: MotionProperty,
time: number,
): Segment | null => {
const segment = segments.get(property);
if (segment == null) {
return null;
}
if (time >= endOf(property, segment)) {
return null;
}
return segment;
};
/**
* A curve whose call the browser has not started yet: still at its start
* on screen (valueAt), already moving in the model (velocityAt).
*/
const isHeld = (segment: Segment) =>
segment.group != null && !segment.group.resolved;
/** The curve itself at `time`: what the keyframes play. */
const curveAt = (property: MotionProperty, time: number): number => {
const segment = segments.get(property);
if (segment == null) {
return resting[property];
}
if (time >= segment.start + segment.duration) {
return segment.target;
}
return segment.at(Math.max(0, time - segment.start));
};
/**
* A held curve's start once a frame dated its call, as the browser's start
* moves it: by that frame's lead over the call's own time.
*/
const datedFromLatest = (
segment: Segment,
latest: number | undefined,
): {latest: number; start: number} | null =>
latest == null || segment.group == null
? null
: {latest, start: segment.start + latest - segment.group.provisional};
/**
* When a waiting curve's call had its first frame, which put the curve on
* screen. Undefined for a curve that does not wait, or whose call has had
* no first frame.
*/
const shownSince = (
property: MotionProperty,
segment: Segment,
): number | undefined =>
segment.group?.resolved === false
? segment.group.latest?.get(CHANNEL_OF[property])
: undefined;
/** A curve's end, dated from its call's first frame while it waits. */
const endOf = (property: MotionProperty, segment: Segment): number =>
(datedFromLatest(segment, shownSince(property, segment))?.start ??
segment.start) + segment.duration;
/**
* Takes a curve on screen out of the call that still waits for the
* browser's start. The curve keeps its course, dated from the call's first
* frame. A call that has no channel left starts at that frame.
*/
const leaveWaitingCall = (
segment: Segment,
channel: Channel,
latest: number,
) => {
const group = segment.group;
if (group == null) {
return;
}
const index = group.segments.indexOf(segment);
if (index >= 0) {
group.segments.splice(index, 1);
}
segment.start += latest - group.provisional;
segment.group = undefined;
if (!CHANNELS[channel].some(p => segments.get(p)?.group === group)) {
group.latest?.delete(channel);
group.channels.delete(channel);
}
if (group.channels.size === 0 && group.segments.length === 0) {
resolveGroup(group, latest);
}
};
/**
* The value on screen at `time`. Until the browser reports its start, a
* held curve shows its first value. A frame that ran without that start
* dates the curve. Without that frame, a later time reads from the
* provisional start, so a companion that samples ahead follows the curve's
* shape.
*/
const valueAt = (property: MotionProperty, time: number): number => {
const segment = segments.get(property);
if (segment != null && isHeld(segment)) {
// The compositor starts the call near its first frame. The curve is
// dated as the browser's start would date it. A curve that joined by an
// older clock keeps its lead over the call's own time.
const latest = segment.group?.latest?.get(CHANNEL_OF[property]);
const dated = datedFromLatest(segment, latest);
if (dated != null) {
const elapsed = Math.max(time, dated.latest) - dated.start;
return elapsed >= segment.duration
? segment.target
: segment.at(elapsed);
}
// Nothing has moved on screen until the browser starts the call.
if (time <= now()) {
return segment.at(0);
}
}
return curveAt(property, time);
};
/**
* Whether a curve's tail already shows as at rest at `time`. Under a
* starved main thread the browser commits a call late. A call that starts
* at its own time then skips that far into its curve. One that starts at
* the commit holds an element that hardly moves.
*/
const showsAtRest = (
property: MotionProperty,
segment: Segment,
time: number,
): boolean =>
Math.abs(valueAt(property, time) - segment.target) <=
REST_DISTANCE_TOLERANCES * SAMPLE_TOLERANCE[property] &&
Math.abs(velocityAt(property, time)) <=
SAMPLE_TOLERANCE[property] * REST_FRAMES_PER_SECOND;
const velocityAt = (property: MotionProperty, time: number): number => {
const held = segments.get(property);
if (held != null && isHeld(held)) {
// Still at its start on screen, but moving in the model. A retarget
// carries the velocity the curve has reached by now. So a flick whose
// moves all land before the browser starts any keeps its speed. Past
// its first frame, it reads from that frame, as its value does.
const dated = datedFromLatest(
held,
held.group?.latest?.get(CHANNEL_OF[property]),
);
return held.speed(
Math.max(
0,
dated != null && time > dated.latest
? time - dated.start
: time - held.start,
),
);
}
const segment = segmentAt(property, time);
if (segment == null || time < segment.start) {
return 0;
}
return segment.speed(time - segment.start);
};
// The curve just before a jump at absolute time `time`.
const valueBefore = (property: MotionProperty, time: number): number =>
curveAt(property, time - 1e-6);
// -- writing --------------------------------------------------------------
const finalValue = (property: MotionProperty): number =>
segments.get(property)?.target ?? resting[property];
/**
* Where translate is drawn relative to where the translate animation
* started, read live when a touch lands. iOS WebKit keeps the transform it
* resolved when the animation went to the compositor (iOS 26.2: the
* element's rect and its hit tests stay at the start for the whole curve,
* while the computed style is live), until the animation is retired. A
* segment whose start still waits for the browser's commit has painted
* nothing of its curve yet.
*/
const drawnTranslate = (property: MotionProperty, time: number) => {
const segment = segments.get(property);
return segment?.group != null && !segment.group.resolved
? segment.at(0)
: valueAt(property, time);
};
const presentedSource: PresentedSource = {
offset: (time = now()) => {
syncPending();
return {
x: drawnTranslate('x', time) - hitTested.x,
y: drawnTranslate('y', time) - hitTested.y,
};
},
resolve: () => {
if (target == null) {
return;
}
syncPending();
const time = now();
// Any style write makes WebKit resolve the element's transform again,
// to the value drawn now, where it then stays (iOS 26.2: in the same
// task); a custom property changes nothing else.
writePresentedResolve(target);
hitTested = {x: drawnTranslate('x', time), y: drawnTranslate('y', time)};
},
};
/** Reports the element while its translate moves (not a pseudo-element's). */
const present = (isMoving: boolean) => {
const element = isMoving && pseudoElement == null ? target : null;
if (element === presented) {
return;
}
unpresent?.();
unpresent = null;
if (presented instanceof HTMLElement) {
clearPresentedResolve(presented);
}
presented = element;
if (element != null) {
unpresent = registerPresentedOffset(element, presentedSource);
}
};
const writeInline = (
channel: Channel,
value: (property: MotionProperty) => number,
release = true,
) => {
if (target == null || pseudoElement != null) {
return;
}
touched.add(channel);
const text = inlineText(channel, value);
// An unchanged value is not written: a style write invalidates the
// element, and WebKit can repaint sticky content stale when that lands in
// the frame a scroll commits.
if (target.style.getPropertyValue(channel) !== text) {
target.style.setProperty(channel, text);
}
if (release && text === IDENTITY_TEXT[channel]) {
// Identity leaves the element when nothing else would move it.
releaseIdentity(channel);
}
};
/**
* What identifies a channel's keyframes across calls of one task: each
* moving property's curve object, offset and length, and each other
* property's rest value. Null when a moving property has no shared curve
* (a spring, a rebase, a jump).
*/
const taskBakeKey = (
channel: Channel,
moving: MotionProperty[],
from: number,
end: number,
devicePixel: number,
): unknown[] | null => {
const key: unknown[] = [channel, end - from, devicePixel];
for (const property of CHANNELS[channel]) {
const segment = segments.get(property);
if (!moving.includes(property)) {
key.push(property, resting[property]);
} else if (segment?.source != null && segment.jumps.length === 0) {
key.push(property, segment.source, segment.start - from);
key.push(segment.duration);
} else {
return null;
}
}
return key;
};
/** `sampleTimes`, shared by the calls of a task that play one curve. */
const sharedSampleTimes = (
property: MotionProperty,
from: number,
end: number,
tolerance: number,
): number[] => {
const segment = segments.get(property);
if (segment?.source == null || segment.jumps.length > 0) {
return sampleTimes(property, from, end, tolerance);
}
const key: unknown[] = [
segment.source,
segment.start - from,
segment.duration,
end - from,
tolerance,
];
const {times} = bakesOfTask();
const known = times.find(entry => isSameKey(entry.key, key));
if (known != null) {
return known.times.map(t => t + from);
}
const sampled = sampleTimes(property, from, end, tolerance);
times.push({key, times: sampled.map(t => t - from)});
return sampled;
};
const sampleTimes = (
property: MotionProperty,
from: number,
to: number,
tolerance: number,
): number[] => {
const segment = segments.get(property);
if (segment == null) {
return [];
}
const begin = Math.max(from, segment.start);
const end = Math.min(to, segment.start + segment.duration);
if (end <= begin) {
return [];
}
const times: number[] = [begin];
const value = (t: number) => curveAt(property, t);
const breaks = segment.jumps
.map(j => segment.start + j)
.filter(t => t > begin && t < end);
const edges = [begin, ...breaks, end];
for (let e = 0; e + 1 < edges.length; e++) {
const a = edges[e];
const b = edges[e + 1];
// A 30 Hz grid, each interval split until the chord is within the
// tolerance at its quarter points.
const steps = Math.max(1, Math.ceil((b - a) / SAMPLE_GRID_MS));
const split = (t0: number, t1: number, depth: number) => {
const v0 = value(t0);
const v1 =
t1 === b && breaks.includes(b) ? valueBefore(property, b) : value(t1);
let worst = 0;
for (const f of [0.25, 0.5, 0.75]) {
const t = t0 + (t1 - t0) * f;
worst = Math.max(worst, Math.abs(value(t) - (v0 + (v1 - v0) * f)));
}
if (worst > tolerance && depth < 10 && t1 - t0 > 0.25) {
const mid = (t0 + t1) / 2;
split(t0, mid, depth + 1);
split(mid, t1, depth + 1);
} else {
times.push(t1);
}
};
for (let i = 0; i < steps; i++) {
split(a + ((b - a) * i) / steps, a + ((b - a) * (i + 1)) / steps, 0);
}
}
return times;
};
/**
* Whether the pseudo-element's stylesheet shows the channel's resting
* value: its base, to within the sampling tolerance, which no frame shows.
* A curve that settles to a threshold ends that close to its target.
*/
const atBase = (channel: Channel) =>
CHANNELS[channel].every(property => {
const value = base[property];
return (
value != null &&
Math.abs(finalValue(property) - value) <= SAMPLE_TOLERANCE[property]
);
});
let baseChecked = false;
/**
* The first hold dropped at `base` checks, in development, that the
* stylesheet shows it. It reads after the cancel and off the motion's task,
* so it adds no style read to a frame that starts a motion.
*/
const checkBase = (channel: Channel) => {
if (process.env.NODE_ENV === 'production' || baseChecked) {
return;
}
baseChecked = true;
setTimeout(() => {
if (target == null) {
return;
}
const shown = getComputedStyle(target, pseudoElement).getPropertyValue(
channel,
);
const expected = format(channel, p => base[p] ?? IDENTITY[p]);
if (!sameShown(channel, shown, expected)) {
devWarn(
'Astryx motion',
`the ${pseudoElement} stylesheet shows ${channel} ` +
`${shown || '(unset)'}, not its declared base ${expected}, so ` +
'it shows the wrong value at rest. Make `base` match the ' +
'stylesheet.',
);
}
}, 0);
};
/**
* A pseudo-element's resting value, held by a static filling animation,
* unless its stylesheet shows it (`base`).
*/
const hold = (channel: Channel, time: number) => {
if (target == null) {
return;
}
if (atBase(channel)) {
checkBase(channel);
return;
}
const value = format(channel, finalValue);
const animation = target.animate([{[channel]: value}, {[channel]: value}], {
duration: 1,
fill: 'both',
pseudoElement,
});
animation.startTime = time;
running.set(channel, animation);
};
const replaceIn = (group: StartGroup, segment: Segment, next: Segment) => {
const index = group.segments.indexOf(segment);
if (index >= 0) {
group.segments[index] = next;
} else {
group.segments.push(next);
}
};
/**
* Channels whose model a rebase moved while their animation still shows
* the old curve. Any rebuild clears its channel; the end of the task
* rebuilds the rest, so a frame never shows the old curve at the new rest.
*/
const stale = new Set<Channel>();
let healQueued = false;
const markStale = (channel: Channel) => {
stale.add(channel);
if (!healQueued) {
healQueued = true;
queueMicrotask(healStale);
}
};
const healStale = () => {
healQueued = false;
if (stale.size === 0) {
return;
}
// A waiting channel rebuilds at the frame that commits its call.
const properties = [...stale]
.filter(channel => !heldForFrame.has(channel))
.flatMap(channel => CHANNELS[channel]);
stale.clear();
commit(properties, now());
};
const rebuild = (channel: Channel, time: number) => {
commitWaitingNow(channel);
stale.delete(channel);
const previous = running.get(channel);
running.delete(channel);
clearTimeout(retireTimers.get(channel));
retireTimers.delete(channel);
clearTimeout(retireLooks.get(channel));
retireLooks.delete(channel);
// An element's inline style takes the value on screen below, so its old
// animation can go first. A pseudo-element has none: its old animation
// keeps holding the value until the new one exists (same task, no frame in
// between).
if (pseudoElement == null) {
previous?.cancel();
}
const properties = CHANNELS[channel];
// Settled curves become resting values.
for (const property of properties) {
const segment = segments.get(property);
if (segment != null && time >= endOf(property, segment)) {
resting[property] = segment.target;
segments.delete(property);
}
}
const moving = properties.filter(p => segments.has(p));
if (callGroup == null) {
// A call that starts now rebuilds a channel the compositor has moving
// since a first frame without a known start. The channel carries on
// from that frame, with a start of its own, instead of starting its
// curve again.
for (const property of moving) {
const segment = segments.get(property) as Segment;
const latest = shownSince(property, segment);
if (latest != null) {
leaveWaitingCall(segment, channel, latest);
}
}
}
// An explicit call can rebuild a channel while one of its curves still
// waits for the browser's start. The animation then joins the current
// call, or else that waiting call, with no start of its own.
const waiting =
callGroup ??
moving
.map(p => (segments.get(p) as Segment).group)
.find(group => group != null && !group.resolved) ??
null;
const rebuiltAfterFirstFrame = waiting?.framed === true;
// The new animation starts at the frame that commits it, from its first
// keyframe. That holds for a waiting call it joins after that call's
// first frame, and for every waiting call it takes a curve from. So this
// channel's reads below, and until that frame, take that first value.
const restarted = new Set<StartGroup>();
if (rebuiltAfterFirstFrame) {
restarted.add(waiting);
}
if (callGroup != null) {
for (const property of moving) {
const group = (segments.get(property) as Segment).group;
if (group != null && group !== callGroup && !group.resolved) {
restarted.add(group);
}
}
}
for (const group of restarted) {
group.latest?.delete(channel);
}
if (channel === 'translate') {
// The animation built below starts from the value at `time` (its first
// keyframe); a rebase or a retarget builds a new one, so a new start.
hitTested = {x: valueAt('x', time), y: valueAt('y', time)};
present(
moving.length > 0 &&
target != null &&
typeof target.animate === 'function',
);
}
if (
moving.length === 0 ||
target == null ||
typeof target.animate !== 'function'
) {
writeInline(channel, finalValue);
} else {
// The value on screen as the curve starts: what a frame painted before
// the compositor has the curve shows. The end is written at retire.
writeInline(channel, p => valueAt(p, time));
}
if (target == null || typeof target.animate !== 'function') {
previous?.cancel();
return;
}
if (moving.length === 0) {
if (pseudoElement != null) {
hold(channel, time);
}
previous?.cancel();
return;
}
// The keyframes start where the animation will: at the waiting call's
// own time, which its start moves to the browser's (resolveGroup), so a
// write later in the task keeps the screen on the model's clock.
const from = waiting?.provisional ?? time;
const end = Math.min(
from + MAX_DURATION_MS,
Math.max(
...moving.map(
p =>
(segments.get(p) as Segment).start +
(segments.get(p) as Segment).duration,
),
),
);
if (end <= from) {
if (pseudoElement != null) {
hold(channel, time);
}
previous?.cancel();
return;
}
if (callGroup != null) {
// A curve of an earlier call still waiting for its first frame is
// rebaked here: it starts with this call's commit.
for (const property of moving) {
const segment = segments.get(property) as Segment;
const group = segment.group;
if (group != null && group !== callGroup && !group.resolved) {
const index = group.segments.indexOf(segment);
if (index >= 0) {
group.segments.splice(index, 1);
}
group.adoptedBy = callGroup;
segment.group = callGroup;
// Re-dated to this call's time: it starts at the commit too, not
// the work between the two calls into its curve.
segment.start += callGroup.provisional - group.provisional;
callGroup.segments.push(segment);
}
}
}
// Read where the keyframes are baked: a page moved to another screen
// bakes its next motion for that screen.
const devicePixel = 1 / Math.max(1, globalThis.devicePixelRatio || 1);
// An earlier call of this task that played the same curves from the same
// offset, over the same rest values, baked these keyframes already.
const bakeKey =
pseudoElement == null
? taskBakeKey(channel, moving, from, end, devicePixel)
: null;
const baked =
bakeKey == null
? undefined
: bakesOfTask().keyframes.find(bake => isSameKey(bake.key, bakeKey));
const collect = (scale: number) => {
const times = new Set<number>([from, end]);
for (const property of moving) {
const tolerance =
SAMPLE_TOLERANCE[property] *
scale *
(property === 'x' || property === 'y' ? devicePixel : 1);
for (const t of sharedSampleTimes(property, from, end, tolerance)) {
times.add(t);
}
}
return times;
};
const span = end - from + END_HOLD_MS;
const bakeKeyframes = (): Keyframe[] => {
let scale = 1;
let all = collect(scale);
while (all.size > MAX_KEYFRAMES && scale < 64) {
scale *= 2;
all = collect(scale);
}
// Jumps become two keyframes at one offset: the value just before,
// then the value after. A jump on the last frame (fade out, then move)
// too.
const jumpTimes = new Set<number>();
for (const property of moving) {
const segment = segments.get(property) as Segment;
for (const j of segment.jumps) {
const t = segment.start + j;
if (t > from && t <= end) {
jumpTimes.add(t);
all.add(t);
}
}
}
const times = [...all].sort((a, b) => a - b);
const frames: Keyframe[] = [];
for (const t of times) {
const offset = (t - from) / span;
if (jumpTimes.has(t)) {
frames.push({
offset,
[channel]: format(channel, p => valueBefore(p, t)),
});
}
frames.push({
offset,
[channel]: format(channel, p =>
t >= end ? finalValue(p) : curveAt(p, t),
),
});
}
frames.push({offset: 1, [channel]: format(channel, finalValue)});
return frames;
};
const keyframes = baked?.keyframes ?? bakeKeyframes();
promote(channel);
const animation =
baked != null && isCopyable(baked.effect)
? copyAnimation(baked.effect, target)
: target.animate(keyframes, {
duration: span,
// The last keyframes hold the end state (END_HOLD_MS); filling both
// ways also keeps it where an engine honors the fill on its compositor.
// The main thread retires the animation once it runs after the end,
// writing the end inline in that task, so that changes no pixel.
fill: 'both',
easing: 'linear',
...(pseudoElement != null ? {pseudoElement} : {}),
});
if (bakeKey != null && baked == null) {
bakesOfTask().keyframes.push({
key: bakeKey,
keyframes,
effect: animation.effect,
});
}
if (waiting != null) {
// From rest: no start time, so the browser starts the animation when
// it commits it (StartGroup); the keyframes are sampled from `from`,
// the call's own start.
waiting.animations.push(animation);
waiting.channels.add(channel);
// A cancel before the first frame rejects its ready promise.
(animation as Partial<Animation>).ready?.catch(() => {});
if (rebuiltAfterFirstFrame) {
// The frame that commits it dates this channel's start again. The
// call's other channels keep their own.
requestFrame?.(frame => {
if (
!waiting.resolved &&
running.get(channel) === animation &&
animation.startTime == null &&
animation.playState === 'running'
) {
(waiting.latest ??= new Map()).set(channel, frameTime(frame, now));
}
});
}
} else {
// One clock: the keyframes were sampled from `time`.
animation.startTime = time;
}
running.set(channel, animation);
previous?.cancel();
scheduleRetire(channel, animation, end);
};
/**
* Once the main thread runs after the curve's end, the animation leaves the
* running state: an element's end values are written inline in the task
* that cancels it; a pseudo-element's end value moves to a static holding
* animation, created before the long one goes.
*
* Why a timer at the curve's end: no browser event reports that an
* animation's time has reached a point inside its effect, and its
* `finished` comes only after the END_HOLD_MS tail, which would keep the
* element promoted and the animation alive for a minute. The timer is set
* on the curve's own clock and re-armed while a sampler pauses or seeks the
* animation, so it never retires a held one.
*/
const scheduleRetire = (
channel: Channel,
animation: Animation,
end: number,
) => {
clearTimeout(retireTimers.get(channel));
retireTimers.delete(channel);
clearTimeout(retireLooks.get(channel));
retireLooks.delete(channel);
// Looks for the end in the next frame, before it paints: the frame whose
// time reaches the curve's end retires it there, where a timer could land
// between two frames under load and leave it on the element a frame or two
// past its curve. The timers stay, for a page that draws no frames (a
// hidden tab).
const lookAtFrame = () => {
if (requestFrame == null || retireFrames.has(animation)) {
return;
}
retireFrames.add(animation);
requestFrame(() => {
retireFrames.delete(animation);
retire(true);
});
};
// `atFrame`: a look from a frame callback, which leaves a pending timer
// where it is.
const retire = (atFrame = false) => {
if (!atFrame) {
retireTimers.delete(channel);
}
if (running.get(channel) !== animation) {
return;
}
// The old curve plays on until the frame that commits the call
// (lookAtShown).
if (heldForFrame.has(channel)) {
if (!retireTimers.has(channel)) {
retireTimers.set(channel, setTimeout(retire, END_RECHECK_MS));
}
return;
}
// Paused or sought (a sampler holding it): retire when its own time
// reaches the curve's end, never from the wall clock.
const remaining = remainingCurve(animation);
if (atFrame && remaining == null) {
// Its time cannot be read: the timer decides.
return;
}
if (remaining != null && remaining > 0) {
const paused = animation.playState === 'paused';
// A frame look keeps looking while up to two frames remain: the frame
// it ran in can be dated before the timer that started the looks was
// due, and the frame after it is the one that reaches the end.
if (!paused && remaining <= (atFrame ? 2 : 1) * END_RECHECK_MS) {
lookAtFrame();
}
if (!retireTimers.has(channel)) {
retireTimers.set(
channel,
setTimeout(
retire,
paused ? RETIRE_RECHECK_MS : Math.max(remaining, END_RECHECK_MS),
),
);
}
return;
}
clearTimeout(retireTimers.get(channel));
retireTimers.delete(channel);
running.delete(channel);
if (channel === 'translate') {
present(false);
}
// A pseudo-element holds its resting value, unless the stylesheet
// takes it back now (a borrowed dip that has ended).
const handsBack =
channel === 'opacity' &&
borrowedOpacity != null &&
![...landings].some(landing => landing.fadeIn?.isBorrowed === true);
if (pseudoElement != null && !handsBack) {
hold(channel, now());
} else {
// The end goes inline in the task that cancels the animation. Whether
// an identity end may leave the element is judged after the cancel:
// until then the end-state tail still holds the end, so the computed
// style would hide a stylesheet value (an opacity 0) under it.
writeInline(channel, finalValue, false);
}
// A call from rest the browser never started (finished from outside
// before its first frame, a sampler's finish()): read its start from the
// animation before the cancel takes it, and with nothing left to wait
// on the call keeps its own clock, so its landing is still armed.
const waiting = [...pendingGroups].filter(group =>
group.animations.includes(animation),
);
for (const group of waiting) {
syncGroup(group);
}
animation.cancel();
for (const group of waiting) {
resolveGroup(group, group.provisional);
}
releaseIdentity(channel);
flushReleases();
};
retireTimers.set(channel, setTimeout(retire, Math.max(0, end - now())));
if (requestFrame != null) {
// Frames start looking a frame before the end, so the frame that
// reaches it retires it even when the timer above runs late.
retireLooks.set(
channel,
setTimeout(
() => {
retireLooks.delete(channel);
lookAtFrame();
},
Math.max(0, end - now() - END_RECHECK_MS),
),
);
}
};
/** The element's own (stylesheet) opacity, read once when a dip starts. */
const ownOpacity = (): number => {
const view = target?.ownerDocument.defaultView;
const value =
target == null
? NaN
: Number.parseFloat(
view
?.getComputedStyle(target, pseudoElement ?? null)
.getPropertyValue('opacity') ?? '',
);
return Number.isFinite(value) ? Math.min(1, Math.max(0, value)) : 1;
};
/**
* Whether the animator holds an opacity of its own on the element: an inline
* value it wrote, or a pseudo-element's holding animation (a `set` over a
* stylesheet that hides or dims it). A dip returns to that value.
*/
const writesOwnOpacity = (): boolean =>
pseudoElement == null
? (target?.style.getPropertyValue('opacity') ?? '') !== ''
: running.has('opacity');
/**
* Gives the element's opacity back to its stylesheet: an element's inline
* value goes; a pseudo-element, which has no inline style, loses the
* animation holding its value.
*/
const releaseOwnOpacity = () => {
if (pseudoElement == null) {
target?.style.removeProperty('opacity');
return;
}
const held = running.get('opacity');
running.delete('opacity');
held?.cancel();
};
/**
* Lands every Reduce Motion move still waiting, at once, on the current
* element: its travel, and the opacity its fade was heading to (the
* stylesheet's again for a borrowed one). Its calls settle `finished`.
*/
const landPending = (finished: boolean) => {
if (landings.size === 0) {
return;
}
const changed = new Set<MotionProperty>();
let handedBack = false;
for (const landing of [...landings]) {
endLanding(landing);
for (const [property, value] of landing.values) {
segments.delete(property);
resting[property] = value;
changed.add(property);
}
if (landing.fadeIn != null || landing.restore != null) {
const borrowed =
landing.fadeIn?.isBorrowed === true ||
landing.restoreIsBorrowed === true;
segments.delete('opacity');
resting.opacity = borrowed
? IDENTITY.opacity
: (landing.fadeIn?.to ?? landing.restore ?? IDENTITY.opacity);
changed.add('opacity');
if (borrowed) {
borrowedOpacity = null;
handedBack = true;
}
}
for (const owner of [landing.owner, ...landing.carried]) {
carriedOwners.delete(owner);
if (!owner.settled) {
settle(owner, finished);
}
}
}
commit(changed, now());
if (handedBack) {
// The stylesheet owns its opacity again: no value stays inline.
releaseOwnOpacity();
}
};
/**
* Ends a borrowed dip on the element it ran on: the stylesheet owns its
* opacity again (an unmount or a new element never keeps the borrow).
*/
const handBackBorrow = () => {
if (borrowedOpacity == null) {
return;
}
borrowedOpacity = null;
segments.delete('opacity');
resting.opacity = IDENTITY.opacity;
releaseOwnOpacity();
};
/**
* A channel at identity with no animation of its own leaves the element:
* its inline value is removed, unless the stylesheet would then move the
* element, in which case the identity stays inline. Runs when such a value
* is written and again when a motion ends.
*/
const releaseIdentity = (channel: Channel) => {
if (target == null || running.has(channel)) {
return;
}
if (channel === 'opacity' && borrowedOpacity != null) {
if ([...landings].some(landing => landing.fadeIn?.isBorrowed === true)) {
// At the bottom of the dip, before it lands and fades back in.
return;
}
// A dip on the stylesheet's opacity ended: the stylesheet owns it again.
borrowedOpacity = null;
segments.delete('opacity');
resting.opacity = IDENTITY.opacity;
releaseOwnOpacity();
return;
}
if (pseudoElement != null) {
return;
}
if (target.style.getPropertyValue(channel) !== IDENTITY_TEXT[channel]) {
return;
}
// Read with every other channel the same commit leaves at identity: one
// style read for the element, not one per channel (flushReleases).
releasing.add(channel);
if (!releaseQueued) {
releaseQueued = true;
queueMicrotask(flushReleases);
}
};
/** Channels left at identity whose stylesheet value is still to be read. */
const releasing = new Set<Channel>();
let releaseQueued = false;
/**
* Removes the identity values written since the last flush, reads the
* stylesheet once for all of them, and puts back the ones it would move:
* a single forced style read per element and commit, where a read per
* channel used to force one each.
*/
const flushReleases = () => {
releaseQueued = false;
const element = target;
const channels = [...releasing].filter(
channel =>
!running.has(channel) &&
element?.style.getPropertyValue(channel) === IDENTITY_TEXT[channel],
);
releasing.clear();
if (element == null || channels.length === 0) {
return;
}
for (const channel of channels) {
element.style.removeProperty(channel);
}
const style = element.ownerDocument.defaultView?.getComputedStyle(element);
for (const channel of channels) {
const underneath = style?.getPropertyValue(channel);
if (underneath != null && !isIdentityText(channel, underneath)) {
element.style.setProperty(channel, IDENTITY_TEXT[channel]);
}
}
};
/**
* Curve time an animation still has to play on its own clock (its keyframes
* hold the end for END_HOLD_MS after the curve), or null where the engine
* does not report it; a paused animation always has some left.
*/
const remainingCurve = (animation: Animation): number | null => {
const timing = animation.effect?.getTiming?.();
const current = animation.currentTime;
if (timing == null || current == null) {
return animation.playState === 'paused' ? Infinity : null;
}
const left = Number(timing.duration) - END_HOLD_MS - Number(current);
return animation.playState === 'paused' ? Math.max(left, 1) : left;
};
// -- promotion -------------------------------------------------------------
/** Writes the promoted channels as will-change (or the pseudo's property). */
const writePromotion = (element: HTMLElement) => {
const list = [...promoted].join(', ');
if (promotionProperty != null) {
if (list === '') {
element.style.removeProperty(promotionProperty);
} else {
element.style.setProperty(promotionProperty, list);
}
return;
}
if (list === '') {
element.style.willChange = ownWillChange ?? '';
ownWillChange = null;
return;
}
if (ownWillChange == null) {
ownWillChange = element.style.willChange;
}
// Without an inline value, the stylesheet's reasons stay alongside the
// promotion's. They were read in the task after the element was attached.
// A promotion that comes first (an element attached in this task that
// moves at once) is written now. Its reasons join it once the callback's
// microtasks run (queueSheetRead).
if (ownWillChange === '' && !sheetWillChangeRead) {
element.style.willChange = [...promoted].join(', ');
queueSheetReadFor(element);
return;
}
const base = ownWillChange !== '' ? ownWillChange : sheetWillChange;
const own = base === 'auto' ? '' : base;
const reasons = own
.split(',')
.map(reason => reason.trim())
.filter(reason => reason !== '' && !promoted.has(reason as Channel));
element.style.willChange = [...reasons, ...promoted].join(', ');
};
/** Reads the element's own will-change while no promotion of ours is written. */
const readSheetWillChange = (element: HTMLElement) => {
sheetWillChange =
element.ownerDocument.defaultView
?.getComputedStyle(element)
.getPropertyValue('will-change') ?? '';
sheetWillChangeRead = true;
};
/** Joins the stylesheet's reasons to a promotion once the callback ends. */
const queueSheetReadFor = (element: HTMLElement) => {
if (sheetReadQueuedFor === element) {
return;
}
sheetReadQueuedFor = element;
// Still waiting: the same node, still promoted, with no inline reason.
const waits = () =>
sheetReadQueuedFor === element &&
target === element &&
promoted.size > 0 &&
ownWillChange === '';
queueSheetRead({
lift: () => {
if (waits()) {
element.style.willChange = '';
}
},
read: () => {
if (waits()) {
readSheetWillChange(element);
}
},
write: () => {
if (sheetReadQueuedFor !== element) {
return;
}
sheetReadQueuedFor = null;
if (target === element && promoted.size > 0) {
writePromotion(element);
}
},
});
};
/**
* Reads sheetWillChange in a task of its own, so a later promotion reads no
* style in its own task. Skipped while a promotion of ours is written,
* which the read would see (demote asks again), and for a node out of the
* document. A pseudo-element's promotion is its own property, with
* nothing to read.
*/
const readSheetWillChangeLater = () => {
cancelSheetWillChangeRead();
sheetWillChangeRead = false;
if (target == null || promotionProperty != null) {
return;
}
const element = target;
sheetReadTimer = setTimeout(() => {
sheetReadTimer = null;
// A node out of the document has no style to read, and reading one
// still costs a style pass: a shared animator (animatorFor) is never
// detached, so its node can leave with this read waiting. Skipped, the
// read waits for a promotion that needs it.
if (target === element && promoted.size === 0 && element.isConnected) {
readSheetWillChange(element);
}
}, 0);
};
const cancelSheetWillChangeRead = () => {
if (sheetReadTimer != null) {
clearTimeout(sheetReadTimer);
sheetReadTimer = null;
}
};
/**
* Gives the element (or its pseudo-element) a compositing layer for
* `channel` from the task that starts the motion: Mobile Safari runs an
* animation whose start time is set from script on its compositor at its
* first commit only if the element already has a layer.
*/
const promote = (channel: Channel) => {
if (target == null) {
return;
}
if (!promoted.has(channel)) {
promoted.add(channel);
writePromotion(target);
}
scheduleDemote();
};
/** Ends promotion PROMOTION_LINGER_MS after the last motion ends. */
const scheduleDemote = () => {
if (demoteTimer != null) {
clearTimeout(demoteTimer);
}
let end = now();
for (const segment of segments.values()) {
end = Math.max(end, segment.start + segment.duration);
}
demoteTimer = setTimeout(
() => {
demoteTimer = null;
const time = now();
const moving = [...segments.values()].some(
segment => time < segment.start + segment.duration,
);
if (moving || pendingGroups.size > 0) {
scheduleDemote();
return;
}
demote();
},
Math.max(0, end - now()) + PROMOTION_LINGER_MS,
);
};
const demote = () => {
if (demoteTimer != null) {
clearTimeout(demoteTimer);
demoteTimer = null;
}
if (promoted.size === 0) {
return;
}
promoted.clear();
if (target != null) {
writePromotion(target);
// Its stylesheet may have changed its will-change since.
readSheetWillChangeLater();
}
};
// -- starting from rest ---------------------------------------------------
/**
* A call starts from rest when nothing on the channels it drives moves on
* screen and nothing pins its clock (`at`). A curve still waiting for its
* first frame counts as rest, as does one whose tail already shows as at
* rest. Returns its start group, or null for an explicit start.
*/
const beginGroup = (
time: number,
properties: Iterable<MotionProperty>,
at: number | undefined,
start?: AnimateOptions['start'],
): StartGroup | null => {
if (target == null || typeof target.animate !== 'function') {
return null;
}
const channels = new Set<Channel>();
for (const property of properties) {
channels.add(CHANNEL_OF[property]);
}
if (at != null) {
// An explicit clock is the caller's, except a clock no later than a
// call from rest on these channels still waiting for the browser's
// start (an event timestamp, such as a drop's, for the reorder that
// rebases it): the new call joins that call, and the browser's start
// moves both. A later clock is a later call, often a frame or more
// later while the browser has not started the first: it keeps its own
// clock, since joining would sample its curve from the earlier call's
// time and hold its first value for the gap.
for (const channel of channels) {
for (const property of CHANNELS[channel]) {
const group = segments.get(property)?.group;
if (group != null && !group.resolved && at <= group.provisional) {
return group;
}
}
}
return null;
}
// A call that continues motion keeps its call's clock, unless it asks
// for the browser's start (`commit`). `presented` asks only for a call
// from rest. A curve that still moves is not at rest, so a call on it
// continues from the value and velocity on screen. A tail that shows as
// at rest counts as rest, so a call on it waits, under `presented` for
// its two frames.
for (const channel of start === 'commit' ? [] : channels) {
for (const property of CHANNELS[channel]) {
const segment = segments.get(property);
// A call's first frame puts its channels on screen, even before the
// browser reports the start. So such a channel is not at rest either.
if (
segment != null &&
time < endOf(property, segment) &&
(segment.group == null ||
segment.group.resolved ||
shownSince(property, segment) != null) &&
!showsAtRest(property, segment, time)
) {
return null;
}
}
}
let resolve: (start: number) => void = () => {};
const started = new Promise<number>(r => {
resolve = r;
});
return {
provisional: time,
fresh: false,
segments: [],
animations: [],
channels: new Set(),
resolved: false,
resolve,
started,
};
};
/** Commits a call's changes, from rest when it has a start group. */
const commitCall = (
group: StartGroup | null,
owner: HandleState,
changed: MotionProperty[],
time: number,
presented = false,
waitsForFrame = false,
) => {
if (group != null) {
for (const property of changed) {
const segment = segments.get(property);
if (segment != null && segment.owner === owner) {
segment.group = group;
group.segments.push(segment);
}
}
}
if (presented && group != null && requestFrame != null) {
// At rest until then: the animations, and the layer they promote, come
// two frames later. Promoting now, a layer at rest for two frames, left
// a stale paint of the element's rest in WebKit on iOS 26.2 (a title in
// a scroller inside a clipped card) after the motion ended.
// Each call waits its own two frames: one queued after another change
// flushed the queue, or after an earlier call's first frame, still
// waits its two.
const call = {group, changed};
deferredCalls.push(call);
requestFrame(() => requestFrame(() => flushDeferredThrough(call)));
return;
}
if (group == null && waitsForFrame) {
deferRebuild(changed, time);
return;
}
startCall(group, changed, time);
};
/** Calls with `start: 'presented'` waiting for their second frame. */
const deferredCalls: {group: StartGroup; changed: MotionProperty[]}[] = [];
/** Creates the animations of the given waiting calls, in call order. */
const startDeferred = (
calls: {group: StartGroup; changed: MotionProperty[]}[],
) => {
for (const {group, changed} of calls) {
// Not a channel that holds the curve of a later call still waiting: a
// later presented call that took a property over starts that channel
// with its own two frames. Every other property starts here, whatever
// its segment's group: a value Reduce Motion writes at once, or lands
// under a dip, has no curve of this call's.
const own: MotionProperty[] = [];
let handedTo: StartGroup | null = null;
for (const property of changed) {
const holder = CHANNELS[CHANNEL_OF[property]]
.map(other => segments.get(other)?.group)
.find(
waiting =>
waiting != null &&
waiting !== group &&
deferredCalls.some(call => call.group === waiting),
);
if (holder == null) {
own.push(property);
continue;
}
// A curve of this call's in that channel never ran: the element held
// it at its start. It starts with the later call, which creates the
// channel, dated from that call's start, so the model reads what the
// screen shows.
const segment = segments.get(property);
if (segment != null && segment.group === group) {
segment.start += holder.provisional - group.provisional;
segment.group = holder;
holder.segments.push(segment);
group.segments.splice(group.segments.indexOf(segment), 1);
handedTo = holder;
}
}
if (own.length === 0 && handedTo != null) {
// Everything this call still plays starts with the later call.
const adopter = handedTo;
group.adoptedBy = adopter;
void adopter.started.then(start => resolveGroup(group, start));
continue;
}
// From the call's own time: the curve starts at the browser's commit.
startCall(group, own, group.provisional);
}
};
/** Creates the animations of every waiting call, in call order. */
const flushDeferred = () => {
startDeferred(deferredCalls.splice(0));
};
/**
* A call's second frame: it starts, with every call queued before it (in
* call order), unless another change created it already.
*/
const flushDeferredThrough = (call: {
group: StartGroup;
changed: MotionProperty[];
}) => {
const index = deferredCalls.indexOf(call);
if (index >= 0) {
startDeferred(deferredCalls.splice(0, index + 1));
}
};
const startCall = (
group: StartGroup | null,
changed: MotionProperty[],
time: number,
) => {
callGroup = group;
try {
commit(changed, time);
} finally {
callGroup = null;
}
if (group == null) {
return;
}
if (group.animations.length === 0) {
resolveGroup(group, group.provisional); // nothing to start
return;
}
pendingGroups.add(group);
group.fresh = true;
// The task that creates the animations, not the call's: a presented
// call's is its second frame's callback, wherever in its frame the call
// was made.
group.task = markTask(now(), now);
group.madeInFrame = frameDepth > 0;
queueMicrotask(() => {
group.fresh = false;
});
for (const animation of group.animations) {
// A cancel before the first frame rejects each one's ready promise.
(animation as Partial<Animation>).ready?.catch(() => {});
}
const ready = (group.animations[0] as Partial<Animation>).ready;
if (ready == null || typeof ready.then !== 'function') {
resolveGroup(group, group.provisional); // no pending start to wait for
return;
}
// The browser sets the start: at the frame that commits the animations,
// or when its compositor starts them (Chromium). Read it in that first
// frame, ahead of anything that might pause or seek the animations, and
// when `ready` settles.
requestFrame?.(frame => {
syncGroup(group);
group.framed = true;
// Chromium's compositor starts a composited animation when the frame
// that commits it reaches it, and tells the page that start a frame or
// more later (longer under load). Until then the call would read as
// not started while the screen moves it, and a retarget or a rebase
// would replay its curve from the start. A call made in a task, still
// waiting in the first frame after it, starts when this frame runs. The
// compositor takes that time as its start. All calls the frame commits
// take one read of it (frameTime). That read is not the frame timestamp,
// which after a block is the frame time from before the block. Only
// when this frame is the one that commits it: not for a call made in a
// frame callback, whose frame committed it already, nor when a block
// ran between the call and this frame (more than LATE_START_MS), after
// which this frame cannot tell a call made in a task from one a page's
// own frame callback made; those keep the browser's start.
if (group.resolved) {
return;
}
const at = frameTime(frame, now);
if (
group.madeInFrame !== true &&
at - (group.task?.first ?? group.provisional) <= LATE_START_MS &&
group.animations.some(
animation =>
animation.startTime == null && animation.playState === 'running',
)
) {
resolveGroup(group, at);
}
// The browser's start is still unread. The compositor starts the call
// near this frame, so each moving channel's reads take the curve from
// now until the browser tells its start.
if (!group.resolved) {
for (const channel of group.channels) {
const animation = running.get(channel);
if (
animation != null &&
group.animations.includes(animation) &&
animation.startTime == null &&
animation.playState === 'running'
) {
(group.latest ??= new Map()).set(channel, at);
}
}
}
});
ready.then(
() => syncGroup(group),
() => settleCancelled(group),
);
};
/**
* A call whose first animation was cancelled before its first frame: if a
* later call in the same task took over its curves, it starts with that
* call; otherwise it never started.
*/
const settleCancelled = (group: StartGroup) => {
if (group.resolved) {
return;
}
let adopter = group.adoptedBy;
while (adopter?.adoptedBy != null) {
adopter = adopter.adoptedBy;
}
if (adopter != null && adopter !== group) {
void adopter.started.then(start => resolveGroup(group, start));
return;
}
// A same-task write replaced the animation the call waited on: the call
// still starts with the browser's start of the ones that remain.
if (awaitStart(group)) {
return;
}
resolveGroup(group, group.provisional);
};
/**
* Waits for the browser's start of a call through one of its animations
* still playing; false when none is left to wait on.
*/
const awaitStart = (group: StartGroup): boolean => {
const live = group.animations.find(
animation => animation.playState !== 'idle',
);
const ready = (live as Partial<Animation> | undefined)?.ready;
if (ready == null || typeof ready.then !== 'function') {
return false;
}
ready.then(
() => syncGroup(group),
() => settleCancelled(group),
);
return true;
};
const syncGroup = (group: StartGroup) => {
if (group.resolved) {
return;
}
for (const animation of group.animations) {
if (animation.startTime != null) {
resolveGroup(
group,
startAfterBlock(group, Number(animation.startTime)),
);
return;
}
}
// Finished from outside before the browser started it (a sampler's
// finish() on a held animation): nothing is left to wait on, so the call
// keeps its own clock, and a later call on an explicit clock does not
// join it and wait for a start that never comes.
if (
group.animations.length > 0 &&
group.animations.every(
animation =>
animation.playState === 'finished' || animation.playState === 'idle',
) &&
group.animations.some(animation => animation.playState === 'finished')
) {
resolveGroup(group, group.provisional);
return;
}
// No start yet (paused before its first frame by a harness or a page,
// or resumed with play() and still pending): neither `ready` nor the
// first frame will look again, so keep looking each frame until the call
// has a start, or its animations finish (its own clock) or are cancelled.
if (
group.animations.some(
animation =>
animation.startTime == null && animation.playState !== 'idle',
)
) {
requestFrame?.(() => syncGroup(group));
}
};
/**
* Reads the start of every call whose first frame may have been committed:
* not those created in the running task, whose start the browser cannot
* have set (reading it there can cost a style update per call).
*/
const syncPending = () => {
for (const group of pendingGroups) {
if (!group.fresh) {
syncGroup(group);
}
}
syncFinished();
};
/**
* An animation finished from outside (a test utility's or devtools'
* `finish()`) shows its end state while the model still reads its curve:
* the curve ends now in the model too, so the next call starts from what
* is on screen.
*/
const syncFinished = () => {
for (const [channel, animation] of running) {
if (animation.playState !== 'finished') {
continue;
}
const time = now();
for (const property of CHANNELS[channel]) {
const segment = segments.get(property);
if (segment == null || time >= segment.start + segment.duration) {
continue;
}
segments.delete(property);
resting[property] = segment.target;
}
}
};
/**
* The start of a call from rest, on the frame that commits it. Chromium,
* like Core Animation, starts a pending animation when it commits it, so a
* main-thread block later in the call's task delays the motion; WebKit
* dates it at its last frame time before that task, so the first frame
* after the block would show it skipped into its curve. When the task ran
* on more than LATE_START_MS past its first call, a start the browser put
* by the task's first animations (a presented call's second frame, not the
* call) and more than LATE_START_MS before the call's first read (its
* `ready`, once the task has ended, or the first frame after it) moves to
* that read, with every animation of the call, and every call of the task
* moves to the same read. A shorter task, or a read other tasks delay,
* keeps the browser's start.
*/
const startAfterBlock = (group: StartGroup, start: number): number => {
const timeline =
typeof document === 'undefined'
? null
: (document.timeline?.currentTime as number | null | undefined);
// A start well after the animations were created is the browser's
// commit of them.
if (
timeline == null ||
group.framed === true ||
start > (group.task?.first ?? group.provisional) + LATE_START_MS
) {
return start;
}
const {task} = group;
// A read in the task's first microtasks comes after its end too.
const ended = task?.ended ?? now();
if (task == null || ended - task.first <= LATE_START_MS) {
return start;
}
// Read once the task has ended (its `ready`) or in the first frame after
// it, both after the block; the task's other calls take the same read.
const at = task.at ?? Math.max(now(), timeline);
if (at - start <= LATE_START_MS) {
return start;
}
task.at = at;
for (const animation of group.animations) {
if (animation.playState !== 'idle') {
animation.startTime = at;
}
}
return at;
};
/** Moves a call from rest onto the time the browser started it. */
const resolveGroup = (group: StartGroup, start: number) => {
if (group.resolved) {
return;
}
group.resolved = true;
pendingGroups.delete(group);
for (const animation of group.animations) {
// One clock for the whole call; a cancelled one stays cancelled (a
// start time would play it again).
if (animation.startTime == null && animation.playState !== 'idle') {
animation.startTime = start;
}
}
const delta = start - group.provisional;
if (delta !== 0) {
for (const segment of group.segments) {
segment.start += delta;
}
for (const channel of group.channels) {
const animation = running.get(channel);
if (animation == null || !group.animations.includes(animation)) {
continue;
}
const ends = CHANNELS[channel].flatMap(p => {
const segment = segments.get(p);
return segment == null ? [] : [segment.start + segment.duration];
});
if (ends.length > 0) {
scheduleRetire(channel, animation, Math.max(...ends));
}
}
for (const owner of new Set(group.segments.map(s => s.owner))) {
if (owner.settled || owner.timer == null) {
continue;
}
clearTimeout(owner.timer);
const ends = group.segments
.filter(segment => segment.owner === owner)
.map(segment => segment.start + segment.duration);
owner.timer = setTimeout(
() => settleAtEnd(owner),
Math.max(0, Math.max(start, ...ends) - now()),
);
}
}
group.resolve(start);
};
// -- handles --------------------------------------------------------------
const lastSpring = new WeakMap<HandleState, SpringDescription>();
const interrupt = (property: MotionProperty, time: number) => {
cancelLanding(property);
const segment = segments.get(property);
if (segment == null) {
return;
}
if (
time < segment.start + segment.duration &&
!carriedOwners.has(segment.owner)
) {
settle(segment.owner, false);
}
};
const settle = (owner: HandleState, finished: boolean) => {
if (owner.settled) {
return;
}
owner.settled = true;
if (owner.timer != null) {
clearTimeout(owner.timer);
owner.timer = null;
}
owner.resolve(finished);
};
/**
* A handle whose curves have reached their end on the wall clock finishes,
* unless a sampler holds one of its animations (paused, or sought back):
* then it waits on that animation's own time, as retiring does
* (scheduleRetire), so `finished` never resolves under motion still on
* screen.
*/
const settleAtEnd = (owner: HandleState) => {
owner.timer = null;
let wait = 0;
for (const [channel, animation] of running) {
if (
!CHANNELS[channel].some(
property => segments.get(property)?.owner === owner,
)
) {
continue;
}
if (heldForFrame.has(channel)) {
wait = Math.max(wait, END_RECHECK_MS);
continue;
}
const remaining = remainingCurve(animation);
if (remaining != null && remaining > 0) {
wait = Math.max(
wait,
animation.playState === 'paused'
? RETIRE_RECHECK_MS
: Math.max(remaining, END_RECHECK_MS),
);
}
}
if (wait > 0) {
owner.timer = setTimeout(() => settleAtEnd(owner), wait);
return;
}
settle(owner, true);
};
const makeHandle = (
owner: HandleState,
properties: MotionProperty[],
finished: Promise<boolean>,
time: number,
group: StartGroup | null = null,
settlesWithLanding = false,
): MotionHandle => {
const ends = properties.map(p => {
const segment = segments.get(p);
return segment != null && segment.owner === owner
? segment.start + segment.duration
: time;
});
const end = Math.max(time, ...ends);
if (settlesWithLanding) {
// The landing it joined settles it.
} else if (properties.length === 0 || end <= time) {
settle(owner, true);
} else {
// Interruptions settle false as they happen (interrupt); reaching the
// end untouched is completion.
owner.timer = setTimeout(
() => settleAtEnd(owner),
Math.max(0, end - now()),
);
}
// The call's own curves, as it started them.
const curves = new Map<MotionProperty, Segment>();
for (const property of properties) {
const segment = segments.get(property);
if (segment != null && segment.owner === owner) {
curves.set(property, segment);
}
}
const handle: MotionHandle = {
properties,
finished,
started: group?.started ?? Promise.resolve(time),
curve: property => {
const segment = curves.get(property === 'scale' ? 'scaleX' : property);
if (segment == null) {
return null;
}
return {
duration: segment.duration / 1000,
at: t =>
t * 1000 >= segment.duration
? segment.target
: segment.at(Math.max(0, t * 1000)),
velocity: t =>
t * 1000 >= segment.duration ? 0 : segment.speed(t * 1000),
};
},
value: (property, at = now()) => {
syncPending();
return valueAt(property, at);
},
velocity: (property, at = now()) => {
syncPending();
return velocityAt(property, at);
},
retarget: (to, transition, retargetOptions) => {
const spring = transition?.spring ?? lastSpring.get(owner);
if (spring == null) {
throw new Error('animator: retarget needs a spring');
}
return animator.animate(to, {...transition, spring}, retargetOptions);
},
// The call's own curves, and its travel still waiting to land under
// Reduce Motion: a catch freezes both where they are on screen
// (AST-094 FR6), travel first so the fade's landing no longer carries
// it, as `animator.stop()` does.
stop: () =>
animator.stop(
PROPERTIES.filter(
p =>
properties.includes(p) &&
(segments.get(p)?.owner === owner ||
[...landings].some(
landing =>
landing.values.has(p) &&
(landing.owners.get(p) ?? landing.owner) === owner,
)),
),
),
};
return handle;
};
const newOwner = (): {owner: HandleState; finished: Promise<boolean>} => {
let resolve: (finished: boolean) => void = () => {};
const finished = new Promise<boolean>(r => {
resolve = r;
});
return {owner: {resolve, settled: false, timer: null}, finished};
};
// -- segment factories ------------------------------------------------------
const springSegment = (
owner: HandleState,
property: MotionProperty,
start: number,
to: number,
spring: SpringDescription,
velocity: number,
): Segment | null =>
// The motion role it plays, at the tempo of the theme it is in.
springFrom(
owner,
property,
start,
valueAt(property, start),
velocity,
to,
resolveMotion(target, spring),
);
/**
* `resolved` is already at the theme's tempo. A restart passes a segment's
* spring as it is.
*/
const springFrom = (
owner: HandleState,
property: MotionProperty,
start: number,
from: number,
velocity: number,
to: number,
resolved: SpringDescription,
): Segment | null => {
if (from === to && velocity === 0) {
return null;
}
const curve = solveSpring(toSpring(resolved), {from, to, velocity});
const duration = Math.min(
MAX_DURATION_MS,
curve.settleTime(SETTLE_THRESHOLD[property]) * 1000,
);
return {
start,
duration,
target: to,
at: t => curve.value(t / 1000),
speed: t => curve.velocity(t / 1000),
jumps: [],
owner,
spring: resolved,
};
};
/** The retarget of `additive`: the old curve plus a spring of the difference. */
const additiveSegment = (
owner: HandleState,
property: MotionProperty,
start: number,
to: number,
spring: SpringDescription,
old: Segment,
): Segment => {
const oldEnd = old.start + old.duration;
const resolved = resolveMotion(target, spring);
const delta = solveSpring(toSpring(resolved), {
from: 0,
to: to - old.target,
velocity: 0,
});
const deltaMs = Math.min(
MAX_DURATION_MS,
delta.settleTime(SETTLE_THRESHOLD[property]) * 1000,
);
const ownAt = (t: number) =>
t >= deltaMs ? to - old.target : delta.value(t / 1000);
const oldAt = (time: number) =>
time >= oldEnd ? old.target : old.at(Math.max(0, time - old.start));
return {
start,
duration: Math.min(MAX_DURATION_MS, Math.max(oldEnd - start, deltaMs)),
target: to,
at: t => oldAt(start + t) + ownAt(t),
speed: t =>
(start + t >= oldEnd ? 0 : old.speed(start + t - old.start)) +
(t >= deltaMs ? 0 : delta.velocity(t / 1000)),
jumps: old.jumps
.map(jump => old.start + jump - start)
.filter(jump => jump > 0),
owner,
spring: resolved,
isAdditive: true,
};
};
/**
* `additive` for a played curve: the old curve plus the new curve's shape,
* scaled to the difference between the two targets.
*/
const additiveCurveSegment = (
owner: HandleState,
start: number,
curve: MotionCurve,
old: Segment,
): Segment => {
const from = curve.at(0);
const to = curve.at(curve.duration);
const scale = (to - old.target) / (to - from);
const ms = Math.min(MAX_DURATION_MS, curve.duration * 1000);
const oldEnd = old.start + old.duration;
const oldAt = (time: number) =>
time >= oldEnd ? old.target : old.at(Math.max(0, time - old.start));
return {
start,
duration: Math.min(MAX_DURATION_MS, Math.max(oldEnd - start, ms)),
target: to,
at: t =>
oldAt(start + t) +
(t >= ms ? to - old.target : (curve.at(t / 1000) - from) * scale),
speed: t =>
(start + t >= oldEnd ? 0 : old.speed(start + t - old.start)) +
(t >= ms ? 0 : curve.velocity(t / 1000) * scale),
jumps: old.jumps
.map(jump => old.start + jump - start)
.filter(jump => jump > 0),
owner,
};
};
const fadeSegment = (
owner: HandleState,
start: number,
stops: ReadonlyArray<{at: number; value: number}>,
jumps: ReadonlyArray<number> = [],
): Segment => {
registerReducedMotionCrossFade();
const ease = cubicBezier(
resolveMotion(target, reducedMotionCrossFade.curve),
);
const duration = stops[stops.length - 1].at;
const at = (t: number) => {
for (let i = 0; i + 1 < stops.length; i++) {
const a = stops[i];
const b = stops[i + 1];
if (t < b.at || i + 2 === stops.length) {
if (b.at === a.at) {
return b.value;
}
const p = Math.min(1, Math.max(0, (t - a.at) / (b.at - a.at)));
return a.value + (b.value - a.value) * ease(p);
}
}
return stops[stops.length - 1].value;
};
return {
start,
duration,
target: stops[stops.length - 1].value,
at,
speed: t =>
((at(t + 0.5) - at(Math.max(0, t - 0.5))) / (t >= 0.5 ? 1 : 0.5 + t)) *
1000,
jumps,
owner,
isFade: true,
};
};
// -- a retarget's start ----------------------------------------------------
/**
* What the screen shows of a property after a call that continues its
* motion: the old curve, or the value at rest. It shows that until the
* frame that commits the call. A rebase since then moves the element
* under it by `offset`.
*/
interface Shown {
readonly segment: Segment | null;
readonly resting: number;
offset: number;
/** When the first such call changed the property. */
readonly since: number;
}
const shown = new Map<MotionProperty, Shown>();
/**
* Channels whose rebuild waits for the frame that commits their call, with
* the time of the last call on each.
*/
const heldForFrame = new Map<Channel, number>();
let isShownLookQueued = false;
let stopWatchingHidden: (() => void) | null = null;
/** The page whose frames the animator's own frame source draws. */
const framePage =
options.requestFrame == null && typeof document !== 'undefined'
? document
: null;
/**
* Whether no frame comes. A hidden page draws none. The frame source of a
* hidden page draws none either, while the element shows elsewhere (a
* Picture-in-Picture window's opener).
*/
const isPageHidden = () =>
target?.ownerDocument.visibilityState === 'hidden' ||
framePage?.visibilityState === 'hidden';
const forgetShown = () => {
shown.clear();
syncWaiting();
stopWatchingHidden?.();
};
/** This animator's entry in the waiting calls, from what still waits. */
const waitKey = {};
const syncWaiting = () => {
let first = Infinity;
for (const entry of shown.values()) {
first = Math.min(first, entry.since);
}
if (first === Infinity) {
waitingCalls.delete(waitKey);
} else {
waitingCalls.set(waitKey, first);
}
};
/**
* Rebuilds channels from their last calls' times, as those calls would
* have rebuilt them: the same keyframes and start time.
*/
const rebuildOnCallClocks = (channels: [Channel, number][]) => {
for (const time of new Set(channels.map(([, at]) => at))) {
commit(
channels
.filter(([, at]) => at === time)
.flatMap(([channel]) => CHANNELS[channel]),
time,
);
}
};
const flushWaiting = () => {
const channels = [...heldForFrame];
heldForFrame.clear();
rebuildOnCallClocks(channels);
};
/**
* A hidden page draws no frames and shows nothing, so its calls keep their
* own clock, as the timers do (scheduleRetire). A page that goes hidden
* before the frame forgets what it showed and rebuilds what waits.
*/
const watchHidden = () => {
const pages = [
...new Set(
[target?.ownerDocument, framePage].filter(page => page != null),
),
];
if (stopWatchingHidden != null || pages.length === 0) {
return;
}
const onChange = () => {
if (isPageHidden()) {
forgetShown();
flushWaiting();
}
};
for (const page of pages) {
page.addEventListener('visibilitychange', onChange);
}
stopWatchingHidden = () => {
for (const page of pages) {
page.removeEventListener('visibilitychange', onChange);
}
stopWatchingHidden = null;
};
};
/**
* Holds a call's channels for the frame that commits it, which rebuilds
* them (lookAtShown). Until then the old curve plays on, and no end look
* retires it.
*/
const deferRebuild = (changed: MotionProperty[], time: number) => {
for (const property of changed) {
const channel = CHANNEL_OF[property];
const isNew = !heldForFrame.has(channel);
heldForFrame.set(channel, time);
if (!isNew) {
continue;
}
stale.delete(channel);
clearTimeout(retireTimers.get(channel));
retireTimers.delete(channel);
clearTimeout(retireLooks.get(channel));
retireLooks.delete(channel);
}
};
/** A rebuild before that frame commits the channel's calls at once. */
const commitWaitingNow = (channel: Channel) => {
if (!heldForFrame.delete(channel)) {
return;
}
for (const property of CHANNELS[channel]) {
shown.delete(property);
}
syncWaiting();
};
/**
* Rebuilds a waiting channel from what the screen shows, after a rebase
* moved the element under it. The old curve plays on, shifted with the
* element, until the frame that commits the call.
*/
const rebuildShown = (channel: Channel, time: number) => {
const model = new Map<MotionProperty, Segment | undefined>();
const rests = new Map<MotionProperty, number>();
for (const property of CHANNELS[channel]) {
const entry = shown.get(property);
if (entry == null) {
continue;
}
model.set(property, segments.get(property));
rests.set(property, resting[property]);
if (entry.segment == null) {
segments.delete(property);
resting[property] = entry.resting + entry.offset;
} else {
segments.set(property, shifted(entry.segment, entry.offset));
}
}
const callTime = heldForFrame.get(channel);
heldForFrame.delete(channel);
try {
rebuild(channel, time);
} finally {
for (const [property, segment] of model) {
if (segment == null) {
segments.delete(property);
} else {
segments.set(property, segment);
}
}
for (const [property, rest] of rests) {
resting[property] = rest;
}
if (callTime != null) {
heldForFrame.set(channel, callTime);
}
}
};
/**
* Notes what the screen shows of each property that a call continuing
* motion changes, before the call replaces its curve. The call's channels
* then wait for the frame that commits it, which rebuilds them
* (lookAtShown). That holds for a call in a frame callback of the page's.
* A call from rest, a call on an explicit clock and a call in an
* animator's frame callback start on their frame already.
*/
const noteShown = (
properties: Iterable<MotionProperty>,
time: number,
group: StartGroup | null,
at: number | undefined,
): boolean => {
if (
group != null ||
at != null ||
frameDepth > 0 ||
requestFrame == null ||
target == null ||
typeof target.animate !== 'function' ||
isPageHidden()
) {
return false;
}
// A curve on these channels may still wait for the browser's start.
// Its call's own start then settles where the new curve begins.
const list = [...properties];
if (
list.some(property =>
CHANNELS[CHANNEL_OF[property]].some(other => {
const segment = segments.get(other);
return segment != null && isHeld(segment);
}),
)
) {
return false;
}
for (const property of list) {
if (shown.has(property)) {
continue;
}
shown.set(property, {
segment: segments.get(property) ?? null,
resting: resting[property],
offset: 0,
since: time,
});
}
syncWaiting();
watchHidden();
if (!isShownLookQueued) {
isShownLookQueued = true;
requestFrame(lookAtShown);
}
return true;
};
/** The value and velocity that the screen shows of a property at `time`. */
const shownAt = (entry: Shown, time: number) => {
const {segment, offset} = entry;
if (segment == null) {
return {value: entry.resting + offset, velocity: 0};
}
const elapsed = time - segment.start;
if (elapsed >= segment.duration) {
return {value: segment.target + offset, velocity: 0};
}
const t = Math.max(0, elapsed);
return {value: segment.at(t) + offset, velocity: segment.speed(t)};
};
const shifted = (segment: Segment, offset: number): Segment =>
offset === 0
? segment
: {
...segment,
target: segment.target + offset,
at: t => segment.at(t) + offset,
};
/**
* The frame that commits calls that continue motion. When it comes more
* than LATE_START_MS after the first call it commits on any animator, the
* screen has shown the old curve. Each spring that they leave
* then starts here, from the value on screen, as UIKit's added spring
* begins at its commit. It keeps a velocity that its call handed it, such
* as a release's, and otherwise takes the one on screen. A played curve or
* a coast keeps its call's clock, and an earlier frame keeps every call on
* its own clock.
*/
const lookAtShown = (frame?: number) => {
isShownLookQueued = false;
const entries = [...shown];
const channels = [...heldForFrame];
heldForFrame.clear();
forgetShown();
if (target == null) {
return;
}
const at = frameTime(frame, now);
const late =
at -
firstCommitted(
frame,
Math.min(...entries.map(([, entry]) => entry.since)),
) >
LATE_START_MS;
const changed: MotionProperty[] = [];
const owners = new Set<HandleState>();
for (const [property, entry] of entries) {
const current = segments.get(property);
if (
!late ||
current == null ||
current.spring == null ||
current.isFade === true ||
isHeld(current)
) {
continue;
}
const screen = shownAt(entry, at);
const next =
current.isAdditive === true && entry.segment != null
? additiveSegment(
current.owner,
property,
at,
current.target,
current.spring,
shifted(entry.segment, entry.offset),
)
: springFrom(
current.owner,
property,
at,
screen.value,
current.handedVelocity ??
// From rest, the call's own start velocity.
(entry.segment == null ? current.speed(0) : screen.velocity),
current.target,
current.spring,
);
if (next == null) {
segments.delete(property);
resting[property] = current.target;
} else {
segments.set(
property,
current.handedVelocity == null
? next
: {...next, handedVelocity: current.handedVelocity},
);
}
owners.add(current.owner);
changed.push(property);
}
const restarted = new Set(changed.map(property => CHANNEL_OF[property]));
if (restarted.size > 0) {
commit(
[...restarted].flatMap(channel => CHANNELS[channel]),
at,
);
}
rebuildOnCallClocks(
channels.filter(([channel]) => !restarted.has(channel)),
);
for (const owner of owners) {
if (owner.settled || owner.timer == null) {
continue;
}
clearTimeout(owner.timer);
let end = at;
for (const segment of segments.values()) {
if (segment.owner === owner) {
end = Math.max(end, segment.start + segment.duration);
}
}
owner.timer = setTimeout(
() => settleAtEnd(owner),
Math.max(0, end - now()),
);
}
};
// -- the animator -----------------------------------------------------------
const commit = (changed: Iterable<MotionProperty>, time: number) => {
const channels = new Set<Channel>();
for (const property of changed) {
channels.add(CHANNEL_OF[property]);
}
if (channels.has('opacity')) {
borrowedOpacity = null;
}
for (const channel of channels) {
rebuild(channel, time);
}
flushReleases();
};
/** Reduced Motion landings still waiting for the element to be transparent. */
const landings = new Set<Landing>();
/** Calls a later call's landing carries: an interrupt does not settle them. */
const carriedOwners = new Set<HandleState>();
/**
* A later write to `property` takes it from any landing. A write to opacity
* decides what shows, so a landing still waiting writes its travel at once
* rather than never, and its calls settle as interrupted.
*/
const cancelLanding = (property: MotionProperty) => {
for (const landing of [...landings]) {
if (property === 'opacity') {
endLanding(landing);
landNow(landing);
} else if (landing.values.delete(property)) {
// Set or stopped before it landed: the call whose move it was did
// not finish (a carried value is an earlier call's).
const moved = landing.owners.get(property) ?? landing.owner;
landing.owners.delete(property);
if (!moved.settled) {
settle(moved, false);
}
}
}
};
const landNow = (landing: Landing) => {
const changed: MotionProperty[] = [];
for (const [property, value] of landing.values) {
segments.delete(property);
resting[property] = value;
changed.push(property);
}
if (changed.length > 0) {
commit(changed, now());
}
for (const owner of [landing.owner, ...landing.carried]) {
carriedOwners.delete(owner);
if (!owner.settled) {
settle(owner, false);
}
}
};
/**
* A later Reduced Motion call that lands too carries the landings still
* waiting: their travel lands with its own, which wins where both move a
* property, and their calls settle when it lands. So two calls in one
* frame (a drag cancel's position and scale) both land.
*/
const adoptLandings = (
plan: NonNullable<ReducedPlan['landing']>,
properties: ReadonlyArray<MotionProperty>,
): {carried: HandleState[]; owners: Map<MotionProperty, HandleState>} => {
const carried: HandleState[] = [];
const owners = new Map<MotionProperty, HandleState>();
for (const landing of [...landings]) {
for (const [property, value] of landing.values) {
const moved = landing.owners.get(property) ?? landing.owner;
if (!properties.includes(property) && !plan.values.has(property)) {
plan.values.set(property, value);
owners.set(property, moved);
} else if (!moved.settled) {
// This call takes the property over: the earlier move never lands.
settle(moved, false);
}
}
carried.push(landing.owner, ...landing.carried);
endLanding(landing);
}
for (const owner of carried) {
carriedOwners.add(owner);
}
return {carried, owners};
};
/**
* A call joins the newest waiting dip: it takes the landing over and
* settles when the dip ends, and the call it replaces lands with it. Each
* value keeps the call whose move it is.
*/
const joinWaitingDip = (owner: HandleState) => {
const dip = [...landings].reverse().find(landing => landing.fadeIn != null);
if (dip == null) {
settle(owner, true);
return;
}
for (const property of dip.values.keys()) {
if (!dip.owners.has(property)) {
dip.owners.set(property, dip.owner);
}
}
dip.carried.push(dip.owner);
carriedOwners.add(dip.owner);
dip.owner = owner;
};
/** Where opacity is heading: past a waiting landing's fade back in. */
const opacityHeading = (): number => {
let to = finalValue('opacity');
for (const landing of landings) {
if (landing.fadeIn != null) {
to = landing.fadeIn.to;
} else if (landing.restore != null) {
to = landing.restore;
}
}
return to;
};
const endLanding = (landing: Landing) => {
if (landing.timer != null) {
clearTimeout(landing.timer);
}
landings.delete(landing);
};
/**
* How long `landing` still waits for its fade, in ms. A sampler that pauses
* the fade holds it, so it checks again later. A resumed fade holds it until
* the fade starts again. A fade that runs past the landing's due time, as
* after a pause, holds it for the rest of the fade. Any other fade holds
* nothing.
*/
const fadeHeldFor = (landing: Landing): number => {
const animation = running.get('opacity');
const owner = segments.get('opacity')?.owner;
if (
animation == null ||
owner == null ||
(owner !== landing.owner && !landing.carried.includes(owner))
) {
return 0;
}
if (animation.playState === 'paused') {
return RETIRE_RECHECK_MS;
}
// The timeline reads the frame before a long task, so the fade's current
// time would date a fade that has ended as still running.
const start = animation.startTime;
const duration = Number(animation.effect?.getTiming?.().duration);
if (!Number.isFinite(duration)) {
return 0;
}
if (start == null) {
// A fade resumed with play() has no start until its next frame.
return animation.playState === 'running' ? END_RECHECK_MS : 0;
}
// A fade that ends by the landing's due time holds nothing. A timer runs
// in whole milliseconds, so it often fires a fraction early.
const end = Number(start) + duration - END_HOLD_MS;
if (landing.due != null && end <= landing.due) {
return 0;
}
const left = end - now();
return left > 0 ? left : 0;
};
/**
* The landing's timer: it lands once its fade lets it. A call that takes the
* landing over lands it directly, at once.
*/
const landWhenFaded = (landing: Landing) => {
const held = fadeHeldFor(landing);
if (held > 0) {
landing.due = now() + held;
landing.timer = setTimeout(() => landWhenFaded(landing), held);
return;
}
land(landing);
};
/** Arms a landing from the call's start (the browser's, for a call from rest). */
const scheduleLanding = (
owner: HandleState,
started: Promise<number>,
plan: NonNullable<ReducedPlan['landing']>,
adopted: ReturnType<typeof adoptLandings> | null,
) => {
const owners = new Map<MotionProperty, HandleState>();
for (const property of plan.values.keys()) {
owners.set(property, adopted?.owners.get(property) ?? owner);
}
const landing: Landing = {
...plan,
owner,
carried: adopted?.carried ?? [],
owners,
timer: null,
due: null,
};
landings.add(landing);
// The handle settles when the landing (and its fade back in) is done.
if (owner.timer != null) {
clearTimeout(owner.timer);
owner.timer = null;
}
void started.then(start => {
if (!landings.has(landing)) {
return;
}
landing.due = start + landing.at;
landing.timer = setTimeout(
() => landWhenFaded(landing),
Math.max(0, landing.due - now()),
);
});
};
/**
* Writes the travel while the element is transparent: a plain style write,
* never an animation (DR2: opacity only), so it is never shown in the wrong
* place. In a dip the fade back in starts from here and takes what is left
* of the cross-fade, so the dip ends when it was due even when a busy main
* thread runs this timer late; past the whole fade back in (100 ms late or
* more) the element appears at once where it landed, with no animation,
* and the call settles then.
*/
const land = (landing: Landing) => {
landings.delete(landing);
landing.timer = null;
const time = now();
const changed: MotionProperty[] = [];
for (const [property, value] of landing.values) {
segments.delete(property);
resting[property] = value;
changed.push(property);
}
let end = time;
// The fade back in takes what is left of the cross-fade: a timer that a
// busy main thread runs late shortens it, so the dip still ends when it
// was due (design:reduced-motion DR2, 200 ms or less), and the element is
// never shown before it lands. Past the whole fade back in nothing is
// left: the element appears at once, a plain write with no fade for the
// browser to start a frame later, so the call settles showing it.
const late = landing.due == null ? 0 : Math.max(0, time - landing.due);
const appears = landing.fadeIn != null && late >= landing.fadeIn.ms;
if (landing.fadeIn != null && !appears) {
const ms = landing.fadeIn.ms - late;
segments.set(
'opacity',
fadeSegment(landing.owner, time, [
{at: 0, value: valueAt('opacity', time)},
{at: ms, value: landing.fadeIn.to},
]),
);
changed.push('opacity');
end = time + ms;
} else if (landing.fadeIn != null) {
segments.delete('opacity');
resting.opacity =
landing.fadeIn.isBorrowed === true
? IDENTITY.opacity
: landing.fadeIn.to;
changed.push('opacity');
} else if (landing.restore != null) {
segments.delete('opacity');
resting.opacity =
landing.restoreIsBorrowed === true ? IDENTITY.opacity : landing.restore;
changed.push('opacity');
}
commit(changed, time);
if (
landing.restoreIsBorrowed === true ||
(appears && landing.fadeIn?.isBorrowed === true)
) {
// The stylesheet owns its opacity again.
releaseOwnOpacity();
} else if (landing.fadeIn?.isBorrowed === true) {
// The fade back in returns to the stylesheet's opacity: it owns it
// again once the fade ends (releaseIdentity).
borrowedOpacity = landing.fadeIn.to;
}
// The calls it carries are done: their travel has landed.
for (const carried of landing.carried) {
carriedOwners.delete(carried);
if (!carried.settled) {
settle(carried, true);
}
}
const {owner} = landing;
if (owner.settled) {
return;
}
if (end <= time) {
settle(owner, true);
} else {
owner.timer = setTimeout(
() => settleAtEnd(owner),
Math.max(0, end - now()),
);
}
};
/**
* A call that sets a value still waiting to land takes it over: the earlier
* move never lands, and its call settles interrupted. Once nothing waiting
* is left, a call that names its own opacity replaces an earlier fade back
* in or restore too, so a caught dismissal fades straight back up instead
* of dipping. Whatever still waits is carried by the new plan.
*/
const takeOverLandings = (
properties: ReadonlyArray<MotionProperty>,
namesOpacity: boolean,
) => {
for (const property of properties) {
if (property !== 'opacity') {
cancelLanding(property);
}
}
if (!namesOpacity) {
// A dip left with nothing to land (a move taken back) fades straight
// back in from where it is, rather than finishing its dip.
for (const landing of [...landings]) {
if (landing.values.size === 0 && landing.fadeIn != null) {
endLanding(landing);
land(landing);
}
}
return;
}
for (const landing of [...landings]) {
// A waiting call that named its own opacity loses it to this call: it
// never reaches that opacity, so it settles interrupted even though its
// travel still lands.
for (const owner of [landing.owner, ...landing.carried]) {
if (namedOpacity.has(owner) && !owner.settled) {
settle(owner, false);
}
}
if (landing.values.size > 0) {
continue;
}
endLanding(landing);
if (
landing.fadeIn?.isBorrowed === true ||
landing.restoreIsBorrowed === true
) {
// The call's own opacity owns it now, not the stylesheet's.
borrowedOpacity = null;
}
for (const owner of [landing.owner, ...landing.carried]) {
carriedOwners.delete(owner);
if (!owner.settled) {
settle(owner, false);
}
}
}
};
/** Reduce Motion calls that named their own opacity. */
const namedOpacity = new WeakSet<HandleState>();
/**
* Where opacity was heading before a call took the waiting landings over:
* an entrance by role that catches an exit fades back to what the exit
* would have restored.
*/
let headingBeforeTakeOver: number | null = null;
/** What the Reduce Motion planner reads of this animator. */
const planView: ReducedMotionView = {
valueAt,
opacityHeading: () => headingBeforeTakeOver ?? opacityHeading(),
ownOpacity: () => ownOpacity(),
writesOwnOpacity: () => writesOwnOpacity(),
get borrowedOpacity() {
return borrowedOpacity;
},
get hasOpacityCurve() {
return segments.has('opacity');
},
get restingOpacity() {
return resting.opacity;
},
get hasPendingLanding() {
return landings.size > 0;
},
get hasWaitingDip() {
return [...landings].some(landing => landing.fadeIn != null);
},
};
/**
* Reduced Motion (see the file header): the planner's plan
* (reducedMotionPlan.ts) as this call's segments.
*/
const reducedMotion = (
owner: HandleState,
time: number,
targets: Partial<Record<MotionProperty, number>>,
properties: MotionProperty[],
fade: boolean,
role?: 'entrance' | 'exit',
): ReducedPlan => {
const heading = opacityHeading();
// An entrance or an exit by role drives the opacity as a named one does.
takeOverLandings(properties, targets.opacity != null || role != null);
if (targets.opacity != null) {
namedOpacity.add(owner);
}
headingBeforeTakeOver = heading;
let plan: ReturnType<typeof planReducedMotion>;
try {
plan = planReducedMotion(planView, time, targets, properties, fade, role);
} finally {
headingBeforeTakeOver = null;
}
const next: Partial<Record<MotionProperty, Segment | null>> = {};
for (const property of plan.atOnce) {
next[property] = null;
}
if (plan.opacityFade != null) {
next.opacity = fadeSegment(owner, time, plan.opacityFade);
}
return {
next,
holds: plan.holds,
landing: plan.landing,
borrowed: plan.borrowed,
joins: plan.joins,
};
};
const animator: Animator = {
get element() {
return target;
},
reducedMotion(reducedOptions = {}) {
if (!prefersReducedMotion()) {
return 'off';
}
return isCoarsePointer() || reducedOptions.touchRelease === true
? 'crossfade'
: 'instant';
},
attach(next) {
if (next === target) {
return;
}
flushDeferred();
present(false);
// The next node never showed the old curves.
forgetShown();
heldForFrame.clear();
if (next == null) {
// Unmount, unless a node replaces this one in the same task (React's
// replacement order: attach(null), then the new node): nothing is
// left to animate, so at the end of the task every other handle
// settles as interrupted, every atRest() wait settles and no
// completion timer outlives the element, as in dispose()
// (architecture:react-component-runtime INV5). A replacement keeps
// them all: the motion goes on on the new node.
lastDetached = target;
if (!unmountQueued) {
unmountQueued = true;
queueMicrotask(() => {
if (!unmountQueued) {
return;
}
unmountQueued = false;
// A Reduce Motion move still waiting lands where it was going, as
// in dispose(), on the node just detached too: a dip's fade out
// left its low opacity inline there, so a later attach of that
// node (a Suspense or Activity reveal) shows it landed and
// visible. Its calls settle as interrupted.
onLastDetached(() => {
landPending(false);
// The landing's commit rebuilt every channel it touched on the
// detached node, any axis still moving included: leave that
// node with no animation, timer or promotion.
for (const animation of running.values()) {
animation.cancel();
}
running.clear();
for (const timer of retireTimers.values()) {
clearTimeout(timer);
}
retireTimers.clear();
for (const timer of retireLooks.values()) {
clearTimeout(timer);
}
retireLooks.clear();
retireFrames.clear();
demote();
// demote() asks for a fresh will-change read of the node it
// demotes; a detached node gets none.
cancelSheetWillChangeRead();
});
lastDetached = null;
const time = now();
for (const property of PROPERTIES) {
interrupt(property, time);
}
for (const wait of [...restWaits]) {
wait.settle();
}
});
}
} else {
// A node in place of the one just detached: no unmount.
unmountQueued = false;
lastDetached = null;
}
// After the landing's commit, which can promote the element again.
demote();
// A pseudo-element holds an identity with a static animation, which the
// cancel below drops: note the channels to hold again on the next node
// (never a borrowed opacity, which is the stylesheet's).
const isOpacityBorrowed =
borrowedOpacity != null ||
[...landings].some(landing => landing.restoreIsBorrowed === true);
const pseudoHeld =
pseudoElement == null || target == null
? null
: new Set(
(Object.keys(CHANNELS) as Channel[]).filter(
channel =>
running.has(channel) &&
!(channel === 'opacity' && isOpacityBorrowed) &&
CHANNELS[channel].every(
p => !segments.has(p) && resting[p] === IDENTITY[p],
),
),
);
for (const animation of running.values()) {
animation.cancel();
}
running.clear();
for (const timer of retireTimers.values()) {
clearTimeout(timer);
}
retireTimers.clear();
for (const timer of retireLooks.values()) {
clearTimeout(timer);
}
retireLooks.clear();
retireFrames.clear();
if (isOpacityBorrowed) {
// A running borrowed dip (or an exit by role returning to the
// stylesheet) stays in the model through any attach, so a pending
// move still lands while the element is invisible; only the
// outgoing element gets its stylesheet's opacity back.
releaseOwnOpacity();
}
// Identities the outgoing node holds inline over a stylesheet that
// differs, kept through a detach for the node that comes next.
if (target != null) {
const outgoing = target;
heldIdentity =
pseudoHeld ??
new Set(
(Object.keys(CHANNELS) as Channel[]).filter(
channel =>
outgoing.style.getPropertyValue(channel) ===
IDENTITY_TEXT[channel],
),
);
}
const held = heldIdentity;
target = next;
// A new node: its own will-change is read again.
cancelSheetWillChangeRead();
sheetWillChangeRead = false;
if (target == null) {
return;
}
heldIdentity = new Set();
const time = now();
// A borrowed dip that ended while detached hands the opacity back
// instead of writing the borrowed value inline.
const dip = segments.get('opacity');
if (
borrowedOpacity != null &&
(dip == null || time >= dip.start + dip.duration)
) {
borrowedOpacity = null;
segments.delete('opacity');
resting.opacity = IDENTITY.opacity;
}
for (const channel of Object.keys(CHANNELS) as Channel[]) {
const properties = CHANNELS[channel];
const isDefault = properties.every(
p => !segments.has(p) && resting[p] === IDENTITY[p],
);
if (!isDefault) {
rebuild(channel, time);
} else if (held.has(channel)) {
// An identity the animator held inline over a stylesheet that
// differs goes onto the new node too (writeInline keeps it only
// where the new node's stylesheet still differs); a pseudo-element's
// is held again.
if (pseudoElement != null) {
hold(channel, time);
} else {
writeInline(channel, property => resting[property]);
}
}
}
flushReleases();
readSheetWillChangeLater();
},
get(property, time = now()) {
syncPending();
return valueAt(property === 'scale' ? 'scaleX' : property, time);
},
getVelocity(property, time = now()) {
syncPending();
return velocityAt(property === 'scale' ? 'scaleX' : property, time);
},
set(values, setOptions = {}) {
syncPending();
flushDeferred();
const time = now();
const next = expand(values);
for (const [property, value] of Object.entries(next) as [
MotionProperty,
number,
][]) {
interrupt(property, time);
segments.delete(property);
shown.delete(property);
resting[property] = value;
}
// Direct manipulation: the layer makes each write a composite only.
if (setOptions.promote !== false) {
for (const property of Object.keys(next) as MotionProperty[]) {
promote(CHANNEL_OF[property]);
}
}
commit(Object.keys(next) as MotionProperty[], time);
},
animate(to, transition, animateOptions = {}) {
syncPending();
if (animateOptions.start !== 'presented') {
flushDeferred();
}
const time = animateOptions.at ?? callTime(now);
const targets = expand(to);
const velocities = expand(transition.velocity ?? {});
const {owner, finished} = newOwner();
lastSpring.set(owner, transition.spring);
const properties = Object.keys(targets) as MotionProperty[];
const next: Partial<Record<MotionProperty, Segment | null>> = {};
let plan: ReducedPlan | null = null;
if (prefersReducedMotion()) {
plan = reducedMotion(
owner,
time,
targets,
properties,
isCoarsePointer() || animateOptions.touchRelease === true,
animateOptions.crossfadeAs,
);
Object.assign(next, plan.next);
} else {
for (const property of properties) {
const running =
animateOptions.additive === true && velocities[property] == null
? segmentAt(property, time)
: null;
if (running != null && !isHeld(running)) {
next[property] = additiveSegment(
owner,
property,
time,
targets[property] as number,
transition.spring,
running,
);
continue;
}
const handed = velocities[property];
const current = velocityAt(property, time);
const segment = springSegment(
owner,
property,
time,
targets[property] as number,
transition.spring,
handed ?? current,
);
// A velocity that is the curve's own at the call keeps the current
// velocity, as no velocity does. Any other is handed on, such as a
// release's.
const isHanded =
handed != null &&
Math.abs(handed - current) >
SAMPLE_TOLERANCE[property] * REST_FRAMES_PER_SECOND;
next[property] =
segment != null && isHanded
? {...segment, handedVelocity: handed}
: segment;
}
}
const group = beginGroup(
time,
Object.keys(next) as MotionProperty[],
animateOptions.at,
animateOptions.start,
);
const waitsForFrame = noteShown(
Object.keys(next) as MotionProperty[],
time,
group,
animateOptions.at,
);
const adopted =
plan?.landing != null
? adoptLandings(plan.landing, Object.keys(next) as MotionProperty[])
: null;
const changed: MotionProperty[] = [];
for (const [property, segment] of Object.entries(next) as [
MotionProperty,
Segment | null,
][]) {
interrupt(property, time);
changed.push(property);
if (segment == null) {
// Read before the segment goes: valueAt falls back to resting.
const value =
plan?.holds[property] ??
targets[property] ??
valueAt(property, time);
segments.delete(property);
resting[property] = value;
} else {
segments.set(property, segment);
}
}
commitCall(
group,
owner,
changed,
time,
animateOptions.start === 'presented' && animateOptions.at == null,
waitsForFrame,
);
if (plan?.borrowed != null) {
// The dip's own commit cleared it; the borrow lasts the dip.
borrowedOpacity = plan.borrowed;
}
if (plan?.joins === true) {
joinWaitingDip(owner);
}
const handle =
plan?.joins === true
? makeHandle(owner, ['opacity'], finished, time, group, true)
: makeHandle(owner, changed, finished, time, group);
if (plan?.landing != null) {
scheduleLanding(owner, handle.started, plan.landing, adopted);
}
return handle;
},
play(curves, playOptions = {}) {
syncPending();
if (playOptions.start !== 'presented') {
flushDeferred();
}
const time = playOptions.at ?? callTime(now);
const {owner, finished} = newOwner();
const byProperty: Partial<Record<MotionProperty, MotionCurve>> = {};
// `scale` first, so an explicit `scaleX` or `scaleY` beside it wins.
const entries = (
Object.entries(curves) as [
MotionProperty | 'scale',
MotionCurve | undefined,
][]
).sort(([a], [b]) => Number(b === 'scale') - Number(a === 'scale'));
for (const [key, curve] of entries) {
if (curve == null) {
continue;
}
if (!Number.isFinite(curve.duration) || curve.duration < 0) {
throw new RangeError(
`animator: a curve needs a finite duration ≥ 0 (got ${curve.duration})`,
);
}
for (const property of expandList([key])) {
byProperty[property] = curve;
}
}
const properties = Object.keys(byProperty) as MotionProperty[];
const targets: Partial<Record<MotionProperty, number>> = {};
for (const property of properties) {
const curve = byProperty[property] as MotionCurve;
targets[property] = curve.at(curve.duration);
}
const plan = prefersReducedMotion()
? reducedMotion(
owner,
time,
targets,
properties,
isCoarsePointer() || playOptions.touchRelease === true,
playOptions.crossfadeAs,
)
: null;
const next: Partial<Record<MotionProperty, Segment | null>> = {
...plan?.next,
};
for (const property of properties) {
if (property in next) {
continue;
}
const curve = byProperty[property] as MotionCurve;
const running =
playOptions.additive === true ? segmentAt(property, time) : null;
if (
running != null &&
!isHeld(running) &&
curve.duration > 0 &&
Math.abs(curve.at(curve.duration) - curve.at(0)) > 1e-9
) {
next[property] = additiveCurveSegment(owner, time, curve, running);
continue;
}
next[property] =
curve.duration === 0
? null
: {
start: time,
duration: Math.min(MAX_DURATION_MS, curve.duration * 1000),
target: targets[property] as number,
at: t => curve.at(t / 1000),
speed: t => curve.velocity(t / 1000),
jumps: [],
owner,
source: curve,
};
}
const group = beginGroup(
time,
Object.keys(next) as MotionProperty[],
playOptions.at,
playOptions.start,
);
const waitsForFrame = noteShown(
Object.keys(next) as MotionProperty[],
time,
group,
playOptions.at,
);
const adopted =
plan?.landing != null
? adoptLandings(plan.landing, Object.keys(next) as MotionProperty[])
: null;
const changed: MotionProperty[] = [];
for (const [property, segment] of Object.entries(next) as [
MotionProperty,
Segment | null,
][]) {
interrupt(property, time);
changed.push(property);
if (segment == null) {
// Read before the segment goes: valueAt falls back to resting.
const value =
plan?.holds[property] ??
targets[property] ??
valueAt(property, time);
segments.delete(property);
resting[property] = value;
} else {
segments.set(property, segment);
}
}
commitCall(
group,
owner,
changed,
time,
playOptions.start === 'presented' && playOptions.at == null,
waitsForFrame,
);
if (plan?.borrowed != null) {
// The dip's own commit cleared it; the borrow lasts the dip.
borrowedOpacity = plan.borrowed;
}
if (plan?.joins === true) {
joinWaitingDip(owner);
}
const handle =
plan?.joins === true
? makeHandle(owner, ['opacity'], finished, time, group, true)
: makeHandle(owner, changed, finished, time, group);
if (plan?.landing != null) {
scheduleLanding(owner, handle.started, plan.landing, adopted);
}
return handle;
},
decay(curves, decayOptions = {}) {
syncPending();
flushDeferred();
const time = decayOptions.at ?? callTime(now);
// Under Reduce Motion only momentum keeps moving (DR2, DEC-2): a curve
// that is a transition plays as `animate` does, a cross-fade or at once.
const reduce = prefersReducedMotion();
const transitions: MotionValues = {};
for (const property of DECAY_PROPERTIES) {
const curve = curves[property];
if (reduce && curve?.isTransition === true) {
transitions[property] = curve.at(curve.duration);
}
}
const transitioned =
Object.keys(transitions).length > 0
? animator.animate(transitions, REDUCED_TRANSITION, {
at: time,
touchRelease: decayOptions.touchRelease,
})
: null;
const {owner, finished} = newOwner();
// Momentum moves the translate axes only (DR2's throw exception).
const properties = DECAY_PROPERTIES.filter(
property =>
curves[property] != null && transitions[property] === undefined,
);
if (transitioned != null && properties.length === 0) {
return transitioned;
}
const group = beginGroup(time, properties, decayOptions.at);
const waitsForFrame = noteShown(properties, time, group, decayOptions.at);
for (const property of properties) {
const curve = curves[property] as MotionCurve;
interrupt(property, time);
if (!(curve.duration > 0)) {
segments.delete(property);
resting[property] = curve.at(0);
continue;
}
segments.set(property, {
start: time,
duration: Math.min(MAX_DURATION_MS, curve.duration * 1000),
target: curve.at(curve.duration),
at: t => curve.at(t / 1000),
speed: t => curve.velocity(t / 1000),
jumps: [],
owner,
});
}
commitCall(group, owner, properties, time, false, waitsForFrame);
const handle = makeHandle(owner, properties, finished, time, group);
if (transitioned == null) {
return handle;
}
// One handle for the whole release: the cross-faded axes too.
const faded = transitioned;
const owns = (property: MotionProperty) =>
faded.properties.includes(property);
return {
...handle,
properties: [...handle.properties, ...faded.properties],
started: Promise.all([handle.started, faded.started]).then(
([coasting]) => coasting,
),
finished: Promise.all([handle.finished, faded.finished]).then(
([coasted, done]) => coasted && done,
),
value: (property, at) =>
owns(property)
? faded.value(property, at)
: handle.value(property, at),
velocity: (property, at) =>
owns(property)
? faded.velocity(property, at)
: handle.velocity(property, at),
stop: () => {
handle.stop();
faded.stop();
},
};
},
stop(properties) {
syncPending();
flushDeferred();
const time = now();
const list = properties == null ? PROPERTIES : expandList(properties);
const changed: MotionProperty[] = [];
// A borrowed dip, or an exit by role that returns to the stylesheet.
const wasBorrowed =
borrowedOpacity != null ||
[...landings].some(landing => landing.restoreIsBorrowed === true);
// Read before the landings go: a dip's fade back in, an exit's restore.
const heading = opacityHeading();
for (const property of list) {
cancelLanding(property);
const segment = segments.get(property);
if (segment == null) {
continue;
}
// A Reduce Motion fade is never left half done: it finishes, and a
// dip on the stylesheet's opacity hands that opacity back. A call
// that continued the motion and is still not on screen past its
// frame shows the old curve: the element stops where that is.
const noted = shown.get(property);
shown.delete(property);
const value = !segment.isFade
? noted != null && time - noted.since > LATE_START_MS
? shownAt(noted, time).value
: valueAt(property, time)
: wasBorrowed
? IDENTITY.opacity
: heading;
interrupt(property, time);
segments.delete(property);
resting[property] = value;
changed.push(property);
}
commit(changed, time);
if (wasBorrowed && changed.includes('opacity')) {
releaseOwnOpacity();
}
},
rebase(deltas, rebaseOptions = {}) {
syncPending();
flushDeferred();
const time = rebaseOptions.at ?? now();
const towards = expand(rebaseOptions.towards ?? {});
const changed: MotionProperty[] = [];
const owners = new Set<HandleState>();
for (const [property, delta] of Object.entries(expand(deltas)) as [
MotionProperty,
number,
][]) {
if (delta === 0) {
continue;
}
const noted = shown.get(property);
if (noted != null) {
noted.offset += delta;
}
const segment = segmentAt(property, time);
if (segment == null) {
changed.push(property);
resting[property] = valueAt(property, time) + delta;
segments.delete(property);
continue;
}
owners.add(segment.owner);
// A curve still waiting for the browser's start stays in its call:
// it starts with that call's commit. A curve whose call had its first
// frame is on screen already, so it leaves the call (leaveWaitingCall).
const latest = shownSince(property, segment);
const group =
latest == null && segment.group != null && !segment.group.resolved
? segment.group
: undefined;
const replace = (next: Segment) => {
if (group != null) {
replaceIn(group, segment, next);
}
segments.set(property, next);
};
const heading = towards[property];
if (
segment.spring != null &&
heading != null &&
Math.abs(segment.target + delta - heading) <= SAME_VALUE
) {
// The spring keeps its course to the shifted target from its own
// start.
const whole: Segment = {
...segment,
target: heading,
at: t => segment.at(t) + delta,
};
if (latest == null) {
changed.push(property);
replace(whole);
continue;
}
// While the browser has not told the start, only the model moves.
// The call that follows rebuilds the channel from it, or else the
// end of the task does.
const waiting = segment.group;
if (waiting != null && !waiting.resolved) {
replaceIn(waiting, segment, whole);
segments.set(property, whole);
markStale(CHANNEL_OF[property]);
continue;
}
}
changed.push(property);
if (segment.spring != null) {
const from = valueAt(property, time) + delta;
const velocity = velocityAt(property, time);
if (latest != null) {
leaveWaitingCall(segment, CHANNEL_OF[property], latest);
}
const curve = solveSpring(toSpring(segment.spring), {
from,
to: segment.target,
velocity,
});
replace({
start: group?.provisional ?? time,
...(group != null ? {group} : {}),
duration: Math.min(
MAX_DURATION_MS,
curve.settleTime(SETTLE_THRESHOLD[property]) * 1000,
),
target: segment.target,
at: t => curve.value(t / 1000),
speed: t => curve.velocity(t / 1000),
jumps: [],
owner: segment.owner,
spring: segment.spring,
});
} else {
if (latest != null) {
leaveWaitingCall(segment, CHANNEL_OF[property], latest);
}
replace({
...segment,
source: undefined,
target: segment.target + delta,
at: t => segment.at(t) + delta,
});
}
}
// A waiting channel shows its old curve, moved with the element, until
// the frame that commits its call.
commit(
changed.filter(property => !heldForFrame.has(CHANNEL_OF[property])),
time,
);
for (const channel of new Set(changed.map(p => CHANNEL_OF[p]))) {
if (heldForFrame.has(channel)) {
rebuildShown(channel, time);
}
}
// The handles that own the rebased curves finish at their new ends.
for (const owner of owners) {
if (owner.settled || owner.timer == null) {
continue;
}
clearTimeout(owner.timer);
let end = time;
for (const segment of segments.values()) {
if (segment.owner === owner) {
end = Math.max(end, segment.start + segment.duration);
}
}
owner.timer = setTimeout(
() => settleAtEnd(owner),
Math.max(0, end - now()),
);
}
},
async atRest(properties) {
const list = properties == null ? PROPERTIES : expandList(properties);
return new Promise<void>(resolve => {
const wait: RestWait = {timer: null, settle: () => {}};
const done = () => {
if (wait.timer != null) {
clearTimeout(wait.timer);
}
restWaits.delete(wait);
resolve();
};
wait.settle = done;
restWaits.add(wait);
const check = () => {
wait.timer = null;
syncPending();
const time = now();
let end = time;
for (const property of list) {
const segment = segments.get(property);
if (segment != null) {
end = Math.max(end, segment.start + segment.duration);
}
}
if (landings.size > 0) {
// A Reduced Motion landing is still to come.
wait.timer = setTimeout(check, 16);
} else if (end <= time) {
done();
} else {
// A retarget or a later start moves the end: look again then.
wait.timer = setTimeout(check, end - time);
}
};
check();
});
},
dispose() {
flushDeferred();
// A Reduce Motion move still waiting to land is written at its end
// state, so the element is left visible where it was going (the node
// just detached, when an unmount is pending); its call and the calls
// it carries settle as interrupted.
if (target == null && unmountQueued) {
target = lastDetached;
}
lastDetached = null;
unmountQueued = false;
landPending(false);
// Nothing moves any more: every atRest() wait settles.
for (const wait of [...restWaits]) {
wait.settle();
}
const time = now();
for (const property of PROPERTIES) {
interrupt(property, time);
}
for (const animation of running.values()) {
animation.cancel();
}
running.clear();
stale.clear();
forgetShown();
heldForFrame.clear();
for (const timer of retireTimers.values()) {
clearTimeout(timer);
}
retireTimers.clear();
present(false);
for (const timer of retireLooks.values()) {
clearTimeout(timer);
}
retireLooks.clear();
retireFrames.clear();
handBackBorrow();
demote();
cancelSheetWillChangeRead();
target = null;
},
};
animator.attach(element);
return animator;
}
function expandList(
properties: ReadonlyArray<MotionProperty | 'scale'>,
): MotionProperty[] {
const out = new Set<MotionProperty>();
for (const property of properties) {
if (property === 'scale') {
out.add('scaleX');
out.add('scaleY');
} else {
out.add(property);
}
}
return [...out];
}