Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
176 KB
Raw Blame
// 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];
}