Skip to content

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

TypeScript
141 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file animatedLayout.ts
 * @input The DOM (layout rectangles, computed style) and Web Animations. The
 *   theme's move curve and duration (themeTiming.ts), the Reduce Motion
 *   cross-fade clock (uikit/timing.ts) and the block measure (frameBlock.ts)
 * @output Exports `createAnimatedLayout`, the opaque `AnimatedLayout` handle,
 *   `reportLayoutChange`, `playLayoutChange` and `layoutStartFor`. It also
 *   exports the exit hold (`holdLayoutExit`, `releaseLayoutExit`), the
 *   in-place swap (`holdLayoutSwap`, `playLayoutSwap`), the edge reveal's
 *   two-state form (`holdLayoutEdge`, `playLayoutEdge`), `playLayoutFrames`
 *   and `applyLayoutChangeTransition`. It exports `glideOf` and the glide
 *   landings (`landLayoutGlide`, `landLayoutGlideSideways`) too. It is the one
 *   module that produces the size-change glide and the edge reveal
 *   `spec:AST-105` defines (`architecture:react-component-runtime` INV12)
 * @position Motion foundation, internal to core. A handle comes from the
 *   public `useAnimatedLayout` hook; a component that takes it reports its
 *   size changes through this module.
 *
 * How it works:
 * - `measureBefore()` runs before the change commits: from the changed
 *   element it walks up to the handle's container and, at each level,
 *   records the rectangles of the element siblings after it and before it (a
 *   centered, end-aligned or space-between row, or `order`, moves those too),
 *   through `parentElement`, `nextElementSibling` and
 *   `previousElementSibling`, descending only into an element with
 *   `display: contents` (it has no box). Each level's walk stops at the first
 *   sibling outside the band a change can move content into view from: the
 *   area's visible part plus one viewport, or the changed element's size if
 *   larger, above and below. So its cost grows with depth plus the siblings
 *   near the visible part, never with a list's length.
 * - `animate()` runs after the commit (a layout effect). Every change in the
 *   same area reported in one frame is measured together after the commit,
 *   once, in a microtask, so each element moves once, by its total change.
 * - An element moves only when its rectangle changed and it is in the area's
 *   visible part, before or after. Absolute, fixed, top-layer, hidden and
 *   zero-size elements are skipped (an absolute child rides with its moving
 *   parent); a stuck sticky element does not change rectangle, so it stays.
 * - The move is a compositor-only `translate` (replace composition) from the
 *   old place to the new one. Its linear keyframes sample the theme's move
 *   curve, corrected for a scaled ancestor. An element already gliding
 *   keeps that motion and adds the new move: the rest of its curve and the
 *   new move are summed into one new glide, velocity included. Its place
 *   before the change is read on the clock of every glide that carries it,
 *   its own and its gliding ancestors' in the area (the box with each applied
 *   `translate` taken out, plus each glide's offset at its current time), and
 *   so is its place after the change, where only the glides the change leaves
 *   running remain: the new glide starts where the old one is drawn, and a
 *   glide the change leaves running cancels out of the move. Nothing
 *   animates height, and nothing scrolls the area.
 * - A measurement no commit claims by the next frame is dropped.
 * - The changed element plays its own entrance on the same curve, started in
 *   the same frame (`playLayoutChange`). Or it exits, kept where it is while
 *   it gives up its space and conceals (`holdLayoutExit`). Both are FR9's
 *   edge reveal: from its block-end edge by default, or from the block-start
 *   or an inline edge it is given. Once the content on that edge's side
 *   glides, the edge rides that glide, frame by frame, so the two never part;
 *   a reversal (a close while it opens) starts from what the element shows.
 *   A disclosure's indicator turns on the same motion
 *   (`applyLayoutChangeTransition`).
 * - A swap holds old content as one transient copy, inert and hidden from
 *   assistive technology, while new content enters in its place, on the same
 *   motion, and removes it when the swap ends (`holdLayoutSwap`,
 *   `playLayoutSwap`; `spec:AST-105` FR8). The caller shapes the frames over
 *   the swap's progress and, riding a gliding element, how far it has moved,
 *   so every part keeps to that glide; under Reduce Motion with a coarse
 *   pointer only opacity changes.
 * - FR9's two-state form holds an element's old state as the swap's copy
 *   while its edge rides a gliding element, such as a rail beside its
 *   content (`holdLayoutEdge`, `playLayoutEdge`): the larger state is
 *   clipped on that edge, from the extent the element shows, and the caller
 *   adds only its own fades.
 * - Frames on elements the page renders can play on the same motion with no
 *   copy (`playLayoutFrames`), such as a surface reaching over a gap a glide
 *   opens, and are released when the motion ends.
 * - Every pointer (`spec:AST-105` FR5). Under Reduce Motion nothing travels
 *   (`design:reduced-motion` DR1–DR3): a cross-fade under a coarse primary
 *   pointer, an immediate change otherwise.
 * - Without a handle nothing happens: the component keeps its jump
 *   (`spec:AST-105` FR2).
 */

import {LATE_START_MS} from './frameBlock';
import {sharedKey} from '../utils/sharedRealm';
import {paintedBackground} from './inertClone';
import {
  inertCopy,
  isCopyable,
  placeOver,
  visiblePartCopy,
  wrapText,
} from './transientCopy';
import {readThemeTiming, readThemeTokenText} from './themeTiming';
import {
  settlingDuration,
  solveSpring,
  toSpring,
  type SpringDescription,
} from './spring';
import {themeReducesMotion} from '../privateAttributes/reducedMotion.stylex';
import {reducedMotionCrossFade} from './uikit/timing';
import {
  batchPresented,
  clearPresentedResolve,
  registerPresentedOffset,
  writePresentedResolve,
} from './presentation';

/** Below this many pixels a shift is not worth a move. */
const MIN_SHIFT_PX = 0.5;
/** The touch cross-fade's cap (`design:reduced-motion` DR2). */
const CROSS_FADE_CAP_MS = 200;
/** Keyframes per second the motion is sampled at. */
const SAMPLES_PER_SECOND = 60;

// ---------------------------------------------------------------------------
// Motion
// ---------------------------------------------------------------------------

/** How a change plays under the reader's settings. */
type LayoutMotion =
  | {readonly kind: 'glide'; readonly progress: GlideProgress}
  | {
      readonly kind: 'fade';
      readonly durationMs: number;
      readonly easing: string;
    }
  | {readonly kind: 'instant'};

/** The move curve as remaining distance (1 → 0) over its duration. */
export interface GlideProgress {
  readonly durationMs: number;
  /** The move curve's CSS text, as read where the area is. */
  readonly easing: string;
  /** Remaining fraction of the move at `t` ms. */
  remaining(t: number): number;
}

function matches(element: Element, query: string): boolean {
  const view = element.ownerDocument.defaultView;
  return (
    typeof view?.matchMedia === 'function' && view.matchMedia(query).matches
  );
}

/**
 * The theme's move curve over its medium duration where `area` is:
 * one value for the glide, the changed element and the indicator. The tokens
 * carry the theme's `character` and `tempo`. Null when the duration is zero
 * or the browser plays no such easing, and then the change lands at once.
 */
function glideProgress(area: Element): GlideProgress | null {
  const curve = readThemeTiming(area, {
    duration: '--duration-medium',
    easing: '--ease-move',
  });
  const easing = readThemeTokenText(area, '--ease-move');
  if (curve == null || easing == null) {
    return null;
  }
  const durationMs = curve.duration * 1000;
  return {
    durationMs,
    easing,
    remaining: t => (t >= durationMs ? 0 : 1 - curve.at(t / 1000)),
  };
}

// A glide a gesture's release asks for, for the changes in one area.
const releaseGlides = new WeakMap<Element, GlideProgress>();

/**
 * Times the changes `area` and what it holds play in the next frame by
 * `progress`, not the theme's move curve. A release settles on its spring.
 * Reduce Motion still wins.
 */
export function glideNextChange(area: Element, progress: GlideProgress): void {
  releaseGlides.set(area, progress);
  const view = area.ownerDocument.defaultView;
  view?.requestAnimationFrame(() => {
    view.requestAnimationFrame(() => releaseGlides.delete(area));
  });
}

/**
 * `spring` from rest toward the end, released at `velocity` (fractions of
 * the move per second, toward the end), as a glide's progress.
 */
export function springGlide(
  spring: SpringDescription,
  velocity: number,
): GlideProgress {
  const physics = toSpring(spring);
  const curve = solveSpring(physics, {from: 0, to: 1, velocity});
  const durationMs =
    settlingDuration(physics, {initialVelocity: velocity}) * 1000;
  const remaining = (t: number) =>
    t >= durationMs ? 0 : 1 - curve.value(t / 1000);
  return {durationMs, easing: linearEasing(durationMs, remaining), remaining};
}

/** A move's remaining fraction over time as CSS `linear()` easing text. */
function linearEasing(
  durationMs: number,
  remaining: (t: number) => number,
): string {
  const count = sampleCount(durationMs);
  const stops: string[] = [];
  for (let i = 0; i < count; i++) {
    const done = 1 - remaining((i / (count - 1)) * durationMs);
    stops.push(String(Math.round(done * 10000) / 10000));
  }
  return `linear(${stops.join(', ')})`;
}

function releaseGlideFor(area: Element): GlideProgress | undefined {
  for (let at: Element | null = area; at != null; at = at.parentElement) {
    const progress = releaseGlides.get(at);
    if (progress != null) {
      return progress;
    }
  }
  return undefined;
}

/** The motion a change in `area` plays now. */
function layoutMotion(area: Element): LayoutMotion {
  if (
    matches(area, '(prefers-reduced-motion: reduce)') ||
    themeReducesMotion(area)
  ) {
    if (!matches(area, '(pointer: coarse)')) {
      return {kind: 'instant'};
    }
    const [x1, y1, x2, y2] = reducedMotionCrossFade.curve;
    return {
      kind: 'fade',
      durationMs: Math.min(
        CROSS_FADE_CAP_MS,
        reducedMotionCrossFade.durationMs,
      ),
      easing: `cubic-bezier(${x1}, ${y1}, ${x2}, ${y2})`,
    };
  }
  const progress = releaseGlideFor(area) ?? glideProgress(area);
  return progress == null ? {kind: 'instant'} : {kind: 'glide', progress};
}

function sampleCount(durationMs: number): number {
  return Math.max(2, Math.ceil((durationMs / 1000) * SAMPLES_PER_SECOND) + 1);
}

/** Linear keyframes over `durationMs`, one per frame, from `frame(t ms)`. */
function sampleOver(
  durationMs: number,
  frame: (t: number) => Keyframe,
): Keyframe[] {
  const count = sampleCount(durationMs);
  const keyframes: Keyframe[] = [];
  for (let i = 0; i < count; i++) {
    const offset = i / (count - 1);
    keyframes.push({...frame(offset * durationMs), offset});
  }
  return keyframes;
}

/** Linear keyframes sampled from the move curve, one per frame. */
function sampleKeyframes(
  progress: GlideProgress,
  frame: (remaining: number) => Keyframe,
): Keyframe[] {
  return sampleOver(progress.durationMs, t => frame(progress.remaining(t)));
}

function round(value: number): number {
  return Math.round(value * 1000) / 1000;
}

// ---------------------------------------------------------------------------
// Playing
// ---------------------------------------------------------------------------

/** The glide each element reports now, so that only its end clears it. */
const presentedGlides = new WeakMap<Element, object>();

/** A glide's report in the presented hit-test registry. */
interface GlideReport {
  readonly element: Element;
  /** Removes the report. A second call does nothing. */
  readonly remove: () => void;
}

const glideReports = new Set<GlideReport>();

/** The reports of ended glides, removed together in a later task. */
const endedReports: GlideReport[] = [];

/**
 * Removes the reports of ended glides with one notice to the registry's
 * watchers. A glide in a closed window or out of its document never ends, so
 * its report goes here too.
 */
function removeEndedReports(): void {
  if (endedReports.length === 0) {
    return;
  }
  batchPresented(() => {
    for (const report of endedReports.splice(0)) {
      report.remove();
    }
    for (const report of [...glideReports]) {
      const {element} = report;
      if (!element.isConnected || element.ownerDocument.defaultView == null) {
        report.remove();
      }
    }
  });
}

/** Each keyframe's `translate` in px at its offset, or null if one has none. */
function translatesOf(
  keyframes: Keyframe[],
): {at: number; x: number; y: number}[] | null {
  const points: {at: number; x: number; y: number}[] = [];
  for (const [index, frame] of keyframes.entries()) {
    const match = /^(-?[\d.e+-]+)px (-?[\d.e+-]+)px$/.exec(
      String(frame.translate ?? ''),
    );
    if (match == null) {
      return null;
    }
    points.push({
      at: frame.offset ?? index / Math.max(1, keyframes.length - 1),
      x: Number(match[1]),
      y: Number(match[2]),
    });
  }
  return points.length > 0 ? points : null;
}

/** How near its end, px or percent, an animated value counts as there. */
const SETTLED_PX = 0.5;

/** How near its end an animated value with no unit, an opacity, counts. */
const SETTLED_RATIO = 0.005;

/** Keyframe members that time a keyframe rather than style it. */
const KEYFRAME_TIMING = new Set([
  'offset',
  'computedOffset',
  'easing',
  'composite',
]);

type KeyframeValue = string | number | null | undefined;

/** Whether a CSS value is within the settle tolerance of `end`. */
function isNearEnd(value: KeyframeValue, end: KeyframeValue): boolean {
  const numbers = (text: KeyframeValue) => [
    ...String(text ?? '').matchAll(/(-?\d*\.?\d+(?:e[+-]?\d+)?)([a-z%]*)/gi),
  ];
  const ats = numbers(value);
  const ends = numbers(end);
  return (
    ats.length === ends.length &&
    ats.every(([, at, unit], index) => {
      const tolerance = ['px', '%'].includes(unit.toLowerCase())
        ? SETTLED_PX
        : SETTLED_RATIO;
      return Math.abs(Number(at) - Number(ends[index][1])) <= tolerance;
    })
  );
}

/**
 * The offset from which linear `keyframes` stay near their last one, or null
 * when only the last one is.
 */
function settledOffset(keyframes: ReadonlyArray<Keyframe>): number | null {
  const last = keyframes[keyframes.length - 1];
  if (last == null) {
    return null;
  }
  const styles = Object.keys(last).filter(key => !KEYFRAME_TIMING.has(key));
  let from: number | null = null;
  for (let index = keyframes.length - 2; index >= 0; index -= 1) {
    const frame = keyframes[index];
    if (!styles.every(key => isNearEnd(frame[key], last[key]))) {
      break;
    }
    from = frame.offset ?? index / (keyframes.length - 1);
  }
  return from;
}

/**
 * When an animation's sampled linear frames come within reach of their end,
 * ms, or null. An eased two-keyframe fade, the Reduce Motion one, has none:
 * WebKit draws its end values at its end.
 */
function settleTime(
  keyframes: ReadonlyArray<Keyframe>,
  timing: KeyframeAnimationOptions,
): number | null {
  const duration = Number(timing.duration);
  const fraction =
    (timing.easing ?? 'linear') === 'linear' ? settledOffset(keyframes) : null;
  return fraction == null || !(duration > 0)
    ? null
    : (timing.delay ?? 0) + fraction * duration;
}

interface Settling {
  readonly element: Element;
  /** Reads one frame; true once it needs no more frames. */
  readonly frame: () => boolean;
}

/** Each window's motions that have not settled yet, read once a frame. */
const settling = new WeakMap<Window, Set<Settling>>();

/**
 * Reads `entry` in each frame until it is done or its element leaves its
 * document. One frame loop per window runs while any motion waits. Returns
 * the stop.
 */
function watchSettle(view: Window, entry: Settling): () => void {
  if (typeof view.requestAnimationFrame !== 'function') {
    return () => {};
  }
  let waiting = settling.get(view);
  if (waiting == null) {
    const entries = new Set<Settling>();
    waiting = entries;
    settling.set(view, entries);
    const frame = () => {
      for (const next of entries) {
        if (!next.element.isConnected || next.frame()) {
          entries.delete(next);
        }
      }
      if (entries.size === 0) {
        settling.delete(view);
        return;
      }
      view.requestAnimationFrame(frame);
    };
    view.requestAnimationFrame(frame);
  }
  const entries = waiting;
  entries.add(entry);
  return () => {
    entries.delete(entry);
  };
}

/** Each running animation's retime, for a ride that replaces its frames. */
const settleRetimes = new WeakMap<
  Animation,
  (keyframes: ReadonlyArray<Keyframe>, durationMs: number) => void
>();

/**
 * WebKit can draw a compositor animation's last frame with the values it last
 * resolved for the element (presentation.ts). Every frame of a long task over
 * its end can show them too. It resolved them at the start or at a later
 * style write. One resolve once the animation is drawn near its end makes that
 * frame its end. `onResolve` hears it, for a reported glide's hit test.
 * Review condition: re-measure on each WebKit release, and remove these
 * resolves once WebKit draws an ended compositor animation at its final
 * values.
 */
function settleAnimation(
  element: Element,
  animation: Animation,
  keyframes: ReadonlyArray<Keyframe>,
  options: KeyframeAnimationOptions,
  onResolve?: () => void,
): void {
  const view = element.ownerDocument.defaultView;
  if (view == null || !('style' in element)) {
    return;
  }
  const styled = element as Element & ElementCSSInlineStyle;
  let at = settleTime(keyframes, options);
  let isWritten = false;
  settleRetimes.set(animation, (next, durationMs) => {
    at = settleTime(next, {...options, duration: durationMs});
  });
  const stop = watchSettle(view, {
    element,
    frame: () => {
      if (at == null) {
        return true;
      }
      // The engine's own time when it has one; otherwise the clock against
      // the settle's moment, which a subtraction would round short of.
      const isSettled =
        animation.currentTime != null
          ? Number(animation.currentTime) >= at
          : animation.startTime != null &&
            view.performance.now() >= Number(animation.startTime) + at;
      if (!isSettled) {
        return false;
      }
      writePresentedResolve(styled);
      isWritten = true;
      onResolve?.();
      return true;
    },
  });
  // A reported glide's report clears its write; any other clears at its end.
  const end = () => {
    stop();
    settleRetimes.delete(animation);
    if (isWritten && onResolve == null) {
      clearPresentedResolve(styled);
    }
  };
  animation.addEventListener?.('finish', end);
  animation.addEventListener?.('cancel', end);
}

/** Retimes `animation`'s settle after a ride replaced its frames. */
function retimeSettle(
  animation: Animation,
  keyframes: ReadonlyArray<Keyframe>,
  durationMs: number,
): void {
  settleRetimes.get(animation)?.(keyframes, durationMs);
}

/** Each indicator's settle, stopped when the next change retimes it. */
const transitionSettles = new WeakMap<Element, () => void>();

/**
 * An indicator's CSS transition runs on the compositor too, so it resolves
 * once as it settles. Its time is read from the page's clock from now, when
 * the change starts it: reading the transition itself would flush style.
 */
function settleTransition(
  element: HTMLElement | SVGElement,
  progress: GlideProgress,
): void {
  transitionSettles.get(element)?.();
  transitionSettles.delete(element);
  const view = element.ownerDocument.defaultView;
  const {durationMs} = progress;
  // The first sample from which its curve stays near its end.
  const count = sampleCount(durationMs);
  let settled: number | null = null;
  for (let index = count - 2; index >= 0; index -= 1) {
    const at = (index / (count - 1)) * durationMs;
    if (Math.abs(progress.remaining(at)) > SETTLED_RATIO) {
      break;
    }
    settled = at;
  }
  if (view == null || settled == null || !(durationMs > 0)) {
    return;
  }
  // Its moments on the clock, so a frame that lands on one counts: a
  // subtraction from the frame's time can round short of it.
  const start = view.performance.now();
  const settleAt = start + settled;
  const endAt = start + durationMs;
  let isWritten = false;
  const stop = watchSettle(view, {
    element,
    frame: () => {
      const now = view.performance.now();
      if (!isWritten && now >= settleAt) {
        writePresentedResolve(element);
        isWritten = true;
      }
      if (now < endAt) {
        return false;
      }
      clear();
      return true;
    },
  });
  const clear = () => {
    transitionSettles.delete(element);
    if (isWritten) {
      clearPresentedResolve(element);
      isWritten = false;
    }
  };
  transitionSettles.set(element, () => {
    stop();
    clear();
  });
}

/**
 * Reports `element` to the presented hit-test registry while its `translate`
 * glide runs. iOS WebKit hit-tests the element where the glide started. So
 * the gesture host resolves it at touch-down and lands the touch on what is
 * drawn. `scale` is its ancestors' scale. An inert element, such as a swap's
 * copy or a closing element, takes no touch, so it is not reported.
 */
function presentGlide(
  element: Element,
  animation: Animation,
  keyframes: Keyframe[],
  options: KeyframeAnimationOptions,
  scale: {readonly x: number; readonly y: number},
): (() => void) | undefined {
  const view = element.ownerDocument.defaultView;
  const durationMs = Number(options.duration);
  const points =
    (options.easing ?? 'linear') === 'linear' && options.delay == null
      ? translatesOf(keyframes)
      : null;
  if (
    view == null ||
    points == null ||
    !(durationMs > 0) ||
    !('style' in element) ||
    element.closest('[inert]') != null
  ) {
    return undefined;
  }
  const styled = element as Element & ElementCSSInlineStyle;
  const now = () => view.performance.now();
  // The translate drawn at `time`: the keyframes are linear between samples.
  const drawnAt = (time: number) => {
    const start = animation.startTime;
    const progress =
      start == null
        ? 0
        : Math.min(1, Math.max(0, (time - Number(start)) / durationMs));
    let next = 1;
    while (next < points.length - 1 && points[next].at < progress) {
      next += 1;
    }
    const from = points[next - 1] ?? points[0];
    const to = points[next] ?? from;
    const span = to.at - from.at;
    const part =
      span > 0 ? Math.min(1, Math.max(0, (progress - from.at) / span)) : 1;
    return {
      x: (from.x + (to.x - from.x) * part) * scale.x,
      y: (from.y + (to.y - from.y) * part) * scale.y,
    };
  };
  let hitTested = drawnAt(now());
  let isEnded = false;
  let isRemoved = false;
  const glide = {};
  presentedGlides.set(element, glide);
  const unregister = registerPresentedOffset(element, {
    // At its end the engine hit-tests the element at its layout again.
    offset: (time = now()) => {
      if (isEnded) {
        return {x: 0, y: 0};
      }
      const drawn = drawnAt(time);
      return {x: drawn.x - hitTested.x, y: drawn.y - hitTested.y};
    },
    resolve: () => {
      if (!isEnded) {
        writePresentedResolve(styled);
        hitTested = drawnAt(now());
      }
    },
  });
  const report: GlideReport = {
    element,
    remove: () => {
      if (isRemoved) {
        return;
      }
      isRemoved = true;
      glideReports.delete(report);
      unregister();
      if (presentedGlides.get(element) === glide) {
        presentedGlides.delete(element);
        clearPresentedResolve(styled);
      }
    },
  };
  glideReports.add(report);
  const end = () => {
    if (isEnded) {
      return;
    }
    isEnded = true;
    endedReports.push(report);
    // This module's own timer: a closed frame's timer never fires. The glides
    // of one change end in one frame, so the first task removes them all.
    setTimeout(removeEndedReports, 0);
  };
  animation.addEventListener?.('finish', end);
  animation.addEventListener?.('cancel', end);
  // Its settle's resolve moves where the engine hit-tests it, as a touch's.
  return () => {
    if (!isEnded && presentedGlides.get(element) === glide) {
      hitTested = drawnAt(now());
    }
  };
}

/**
 * Play `keyframes` on `element`. Every option here (linear easing over sampled
 * keyframes, replace composition) is one any Web Animations engine takes, so
 * a failure means no Web Animations at all: the change then lands at once.
 * `scale` is the element's ancestors' scale, for a `translate` glide.
 */
function safeAnimate(
  element: Element,
  keyframes: Keyframe[],
  options: KeyframeAnimationOptions,
  change?: ChangeStart,
  scale: {readonly x: number; readonly y: number} = {x: 1, y: 1},
): Animation | null {
  if (typeof (element as HTMLElement).animate !== 'function') {
    return null;
  }
  let animation: Animation;
  try {
    animation = (element as HTMLElement).animate(keyframes, options);
  } catch {
    return null;
  }
  ours.add(animation);
  // The animation starts on the document timeline's current time, not on the
  // next frame. So a retargeted glide keeps moving through the frame it is
  // replaced in. After a block since that frame, Chromium's timeline still
  // reads the frame before the block. A motion started there would skip into
  // its curve, or past all of it. So it starts at the moment of the change
  // instead, and the block delays the motion (startFor). Every animation of
  // one change, in one document, shares that start.
  const doc = element.ownerDocument;
  const now = doc.timeline?.currentTime;
  if (now != null) {
    // The start of the change it is part of, captured when that change made
    // its first animation (changeStartOf); otherwise the document's.
    const start =
      change != null && change.frame === Number(now)
        ? change
        : startFor(doc, Number(now));
    start.last = clockOf(doc);
    animation.startTime = start.at;
    if (start.at !== Number(now)) {
      // Started after the frame time the timeline still reads: until the
      // timeline gets there it shows its first keyframe, not the element at
      // rest.
      const fill = animation.effect?.getTiming().fill;
      animation.effect?.updateTiming({
        fill: fill === 'forwards' || fill === 'both' ? 'both' : 'backwards',
      });
    }
  }
  const onResolve =
    options.pseudoElement == null
      ? presentGlide(element, animation, keyframes, options, scale)
      : undefined;
  settleAnimation(element, animation, keyframes, options, onResolve);
  return animation;
}

/**
 * The start a change's animations share. It is the timeline's frame time,
 * unless a block ran more than LATE_START_MS past that frame before the first
 * of them was made. Then they start at the moment the first of them is made.
 * The frame time is from before the block, so a motion started on it would
 * skip into its curve, or past all of it. Chromium holds the timeline at the
 * frame before a long task once anything in the task reads it.
 */
interface ChangeStart {
  /** The frame time the timeline read. */
  readonly frame: number;
  /** When the change's animations start. */
  readonly at: number;
  /** When the last of them was made, on the document's clock. */
  last: number;
}

/**
 * Each document's change start: an iframe or a Picture-in-Picture window
 * keeps its own clock, with its own origin and frames.
 */
const changeStarts = new WeakMap<Document, ChangeStart>();

/** The clock of the document whose timeline a start is read on. */
function clockOf(doc: Document): number {
  return (doc.defaultView?.performance ?? performance).now();
}

/**
 * The start the current change's animations share. A change keeps one start
 * from its first animation through the flush of its glides and the parts that
 * ride them. That holds however long the work between them runs, such as the
 * rest of a commit or a slow swap. The start holds while the timeline reads
 * the same frame: through the task that made it and the microtasks after it.
 * A change that begins after a block takes a start of its own (beginChange).
 */
function startFor(doc: Document, frame: number): ChangeStart {
  const now = clockOf(doc);
  const held = changeStarts.get(doc);
  if (held != null && held.frame === frame) {
    held.last = now;
    return held;
  }
  const start: ChangeStart = {
    frame,
    at: now - frame <= LATE_START_MS ? frame : now,
    last: now,
  };
  changeStarts.set(doc, start);
  // Let go in a later task: every microtask of this one, where the glides
  // flush and the parts riding them play, has run by then.
  const view = doc.defaultView;
  (view?.setTimeout ?? setTimeout)(() => {
    if (changeStarts.get(doc) === start) {
      changeStarts.delete(doc);
    }
  }, 0);
  return start;
}

/**
 * A change begins as its "before" is read. After a block since the last
 * animation of the change before it, it takes a start of its own. So a change
 * made after a block that follows an earlier layout motion still plays.
 * Changes made together, with no block between them, share one start.
 */
function beginChange(doc: Document): void {
  const held = changeStarts.get(doc);
  if (held != null && clockOf(doc) - held.last > LATE_START_MS) {
    changeStarts.delete(doc);
  }
}

/**
 * When the animations of the layout change being made start. Code that
 * follows the change on its own clock reads it, such as a rail's width or a
 * swap's fade. It is the document timeline's current time. After a block
 * since that frame, it is the moment the change made its first animation.
 * Until the timeline reaches it, the change has not started.
 */
export function layoutStartFor(document: Document): number {
  const now = document.timeline?.currentTime;
  return now == null ? 0 : startFor(document, Number(now)).at;
}

/**
 * Where `element` shows at the timeline's time `at`: its layout box, moved by
 * its glide's offset then. After a block, WebKit evaluates a running
 * translate on the live clock. The timeline still reads the frame before the
 * block, as every glide here does, so the evaluated box would sit ahead.
 * Glides write px; a translate in percent is not ours, so the box stays.
 */
function shownBoxAt(element: Element, at: number): DOMRect {
  const box = element.getBoundingClientRect();
  const glide = glides.get(element);
  const startTime = glide?.animation.startTime;
  if (glide == null || startTime == null) {
    return box;
  }
  const translate =
    element.ownerDocument.defaultView?.getComputedStyle(element).translate ??
    '';
  if (translate.includes('%')) {
    return box;
  }
  const [appliedX = 0, appliedY = 0] = numbersIn(translate);
  const offset = glide.offsetAt(Math.max(0, at - Number(startTime)));
  return new DOMRect(
    box.x + (offset.x - appliedX) * glide.scale.x,
    box.y + (offset.y - appliedY) * glide.scale.y,
    box.width,
    box.height,
  );
}

/** Every animation this module started, so it can tell the app's apart. */
const ours = new WeakSet<Animation>();

const TRANSFORM_PROPERTIES = ['transform', 'translate', 'rotate', 'scale'];

/** The numbers in a CSS value, units dropped. */
function numbersIn(value: string): number[] {
  return (value.match(/-?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?/gi) ?? []).map(
    Number,
  );
}

/**
 * Whether a transform value leaves the element where it is: nothing at all
 * (a swipe's `translate3d(0, 0, 0)` at rest, a button's `scale(1)`, computed
 * as `matrix(1, 0, 0, 1, 0, 0)`), or a scale in place (a pressed button's
 * `scale(0.98)`). A glide's `translate` composes with either; a translation,
 * rotation or skew of its own is the app moving the element.
 */
function staysInPlace(property: string, value: string): boolean {
  if (value === 'none') {
    // No transform at all (a keyframe a press's own transition starts from).
    return true;
  }
  if (property === 'scale') {
    return true;
  }
  if (value.includes('var(')) {
    // An unresolved custom property in an app's own keyframes: its value is
    // unknown here, so the app moves the element.
    return false;
  }
  if (property === 'translate') {
    return numbersIn(value).every(n => n === 0);
  }
  if (property === 'rotate') {
    // An angle, after an optional axis: only the angle matters.
    const numbers = numbersIn(value);
    return numbers.length > 0 && numbers[numbers.length - 1] === 0;
  }
  // A list of transform functions, as computed (`matrix()`, `matrix3d()`)
  // or as written.
  const functions = [...value.matchAll(/([a-z0-9]+)\(([^)]*)\)/gi)];
  return (
    functions.length > 0 &&
    functions.every(([, name, args]) => {
      const numbers = numbersIn(args);
      const fn = name.toLowerCase();
      if (fn === 'matrix') {
        // a b c d e f: no skew, rotation or translation.
        return (
          numbers.length === 6 &&
          [1, 2, 4, 5].every(index => numbers[index] === 0)
        );
      }
      if (fn === 'matrix3d') {
        // Only the diagonal: a scale, nothing else.
        return (
          numbers.length === 16 &&
          numbers.every((n, index) => index % 5 === 0 || n === 0)
        );
      }
      if (fn === 'rotate3d') {
        return numbers[3] === 0;
      }
      if (fn.startsWith('scale')) {
        return true;
      }
      if (
        fn.startsWith('translate') ||
        fn.startsWith('rotate') ||
        fn.startsWith('skew')
      ) {
        return numbers.every(n => n === 0);
      }
      return false;
    })
  );
}

/**
 * Whether the app moves `element` itself: its own `transform`, `translate`
 * or `rotate`, or a running animation of one this module did not start. A
 * value that leaves it in place (nothing, or a scale) is not a move.
 */
function movedByApp(element: Element): boolean {
  const style = element.ownerDocument.defaultView?.getComputedStyle(element);
  if (
    style != null &&
    TRANSFORM_PROPERTIES.some(property => {
      const value = style.getPropertyValue(property);
      return value !== '' && value !== 'none' && !staysInPlace(property, value);
    })
  ) {
    return true;
  }
  if (typeof element.getAnimations !== 'function') {
    return false;
  }
  return element.getAnimations().some(animation => {
    if (ours.has(animation)) {
      return false;
    }
    const effect = animation.effect;
    if (!(effect instanceof KeyframeEffect)) {
      return false;
    }
    return effect
      .getKeyframes()
      .some(frame =>
        TRANSFORM_PROPERTIES.some(
          property =>
            property in frame &&
            !staysInPlace(property, String(frame[property])),
        ),
      );
  });
}

/** An offset in the element's own px, as a function of ms into a glide. */
type OffsetCurve = (t: number) => {readonly x: number; readonly y: number};

const AT_REST: OffsetCurve = () => ({x: 0, y: 0});

/**
 * `curve` as the browser draws it from `sampleOver`'s keyframes: a straight
 * line between each two. A new glide then starts where the old one shows.
 */
function drawnCurve(durationMs: number, curve: OffsetCurve): OffsetCurve {
  const count = sampleCount(durationMs);
  const points = Array.from({length: count}, (_, i) =>
    curve((i / (count - 1)) * durationMs),
  );
  return t => {
    const at = Math.min(Math.max(t / durationMs, 0), 1) * (count - 1);
    const i = Math.min(Math.floor(at), count - 2);
    const f = at - i;
    const a = points[i];
    const b = points[i + 1];
    return {x: a.x + (b.x - a.x) * f, y: a.y + (b.y - a.y) * f};
  };
}

/** A glide an element is playing, so a new change can retarget it. */
interface Glide {
  readonly animation: Animation;
  readonly offsetAt: OffsetCurve;
  readonly durationMs: number;
  /**
   * The offset where the element showed when its old place was read. After a
   * block the glide starts further on, where the compositor has it.
   */
  readonly shownBefore: {readonly x: number; readonly y: number};
  /** Its ancestors' scale: page px per px of its own offset. */
  readonly scale: {readonly x: number; readonly y: number};
}

const glides = new WeakMap<Element, Glide>();

/**
 * The glide `element` is playing now, if any. For an adopter that draws
 * something with each moving element (a table row's divider): it finds what
 * moves without reading the DOM.
 */
export function glideOf(element: Element): Animation | null {
  return glides.get(element)?.animation ?? null;
}

// ---------------------------------------------------------------------------
// Handles
// ---------------------------------------------------------------------------

// A registered key, so a swizzled copy of this module reads a package handle.
const AREA = sharedKey('animated-layout/area', 1);

/**
 * The opaque handle `useAnimatedLayout` returns. A component that receives it
 * reports its size changes to the handle's container, the area the glide
 * stays inside.
 */
export interface AnimatedLayout {
  /**
   * A brand that is never present, so the handle types of the package and a
   * swizzled copy match.
   */
  readonly '@astryxdesign/core/animated-layout/v1'?: never;
}

/** The container a handle reads, or null for a value that is not a handle. */
function readArea(handle: AnimatedLayout): Element | null {
  const read = (handle as {readonly [AREA]?: unknown})[AREA];
  return typeof read === 'function' ? (read as () => Element | null)() : null;
}

/** A handle over `area` (the container element, read when a change runs). */
export function createAnimatedLayout(
  area: () => Element | null,
): AnimatedLayout {
  // Not enumerable and frozen: the handle shows no fields to a caller.
  return Object.freeze(Object.defineProperty({}, AREA, {value: area}));
}

function areaOf(handle: AnimatedLayout, element: Element): Element | null {
  const area = readArea(handle);
  return area != null && area !== element && area.contains(element)
    ? area
    : null;
}

// ---------------------------------------------------------------------------
// The walk
// ---------------------------------------------------------------------------

/**
 * Whether `element` takes part: in flow, rendered, not in the top layer.
 * `display: contents` is handled by the caller.
 */
function takesPart(element: Element, style: CSSStyleDeclaration): boolean {
  if (
    style.display === 'none' ||
    style.visibility === 'hidden' ||
    style.position === 'absolute' ||
    style.position === 'fixed'
  ) {
    return false;
  }
  try {
    if (element.matches(':popover-open, :modal')) {
      return false;
    }
  } catch {
    // An engine without these pseudo-classes has no top layer to skip.
  }
  return true;
}

/**
 * The band of the page a change can move content into or out of view: the
 * area's visible part, extended above and below by one viewport or by the
 * size of every element changing in the frame, whichever is larger (a
 * collapse pulls content up by at most its size, and changes in one frame
 * add up). Content outside it before the change stays outside it, so the
 * walk stops there.
 */
interface Band {
  /** Its top edge, in client px. */
  readonly start: number;
  /** Its bottom edge, in client px. */
  readonly end: number;
}

function bandFor(visible: DOMRect, reach: number): Band {
  return {start: visible.top - reach, end: visible.bottom + reach};
}

/**
 * What one frame's walks read, kept so a level two changes share, or a walk
 * repeated when the band grows, reads each element once.
 */
interface WalkCache {
  readonly rects: Map<Element, DOMRect>;
  /** Whether the element takes part, or `contents` for a boxless element. */
  readonly parts: Map<Element, boolean | 'contents'>;
}

function partOf(element: Element, cache: WalkCache): boolean | 'contents' {
  let part = cache.parts.get(element);
  if (part === undefined) {
    const style = element.ownerDocument.defaultView?.getComputedStyle(element);
    part =
      style == null
        ? false
        : style.display === 'contents'
          ? 'contents'
          : takesPart(element, style);
    cache.parts.set(element, part);
  }
  return part;
}

/**
 * Whether a container lays its children out across the block direction, so
 * DOM order does not run down the page: multi-column, a wrapping column flex
 * box, or a grid that flows by column. The band says nothing about where its
 * later children sit, so a walk there runs through the level.
 */
function flowsAcross(container: Element | null): boolean {
  if (container == null) {
    return false;
  }
  const style =
    container.ownerDocument.defaultView?.getComputedStyle(container);
  if (style == null) {
    return false;
  }
  const count = style.getPropertyValue('column-count');
  const width = style.getPropertyValue('column-width');
  return (
    (count !== '' && count !== 'auto') ||
    (width !== '' && width !== 'auto') ||
    (style.display.includes('flex') &&
      style.flexDirection.startsWith('column') &&
      style.flexWrap.startsWith('wrap')) ||
    (style.display.includes('grid') &&
      style.getPropertyValue('grid-auto-flow').startsWith('column'))
  );
}

/**
 * The box a sticky element sticks to: its nearest scrolling ancestor's, or
 * the viewport.
 */
function scrollportOf(element: Element): {start: number; end: number} {
  const view = element.ownerDocument.defaultView;
  for (
    let node = element.parentElement;
    node != null && node !== element.ownerDocument.documentElement;
    node = node.parentElement
  ) {
    const overflow = view?.getComputedStyle(node).overflowY ?? 'visible';
    if (
      node === element.ownerDocument.body &&
      view?.getComputedStyle(element.ownerDocument.documentElement)
        .overflowY === 'visible'
    ) {
      // The body's overflow applies to the viewport while the root's is
      // visible: the body is no scroller of its own.
      continue;
    }
    if (overflow !== 'visible' && overflow !== 'clip') {
      const box = node.getBoundingClientRect();
      return {
        start: box.top + node.clientTop,
        end: box.top + node.clientTop + node.clientHeight,
      };
    }
  }
  return {start: 0, end: view?.innerHeight ?? 0};
}

/**
 * Whether a sticky element is stuck: resting against its scrollport's edge
 * at its inset. A stuck element takes its final place; an unstuck one is in
 * flow.
 */
function isStuck(element: Element, cache: WalkCache): boolean {
  const style = element.ownerDocument.defaultView?.getComputedStyle(element);
  if (style?.position !== 'sticky') {
    return false;
  }
  const rect = rectOf(element, cache);
  const edge = scrollportOf(element);
  const top = Number.parseFloat(style.top);
  const bottom = Number.parseFloat(style.bottom);
  return (
    (Number.isFinite(top) && Math.abs(rect.top - (edge.start + top)) < 1) ||
    (Number.isFinite(bottom) && Math.abs(rect.bottom - (edge.end - bottom)) < 1)
  );
}

/**
 * `rect`, a box read before a change or after it (in the flush, once the
 * glides the change retargets have stopped), with every running glide that
 * carries the element put back on its glide's own clock: its own and those of
 * its ancestors inside `area`. A glide the change retargets is read on its
 * clock before the change and is gone after it; one the change leaves running
 * (a card inside an absolutely positioned panel, which the change takes no
 * ancestors from) is read on the same clock in both places, so it cancels out
 * of the move. A box read samples a running `translate`
 * wherever the engine evaluates it, and WebKit evaluates it at the moment of
 * the read, while a glide's offset, and the glide a change retargets it into,
 * run on the timeline's frame time: from the box alone, a change made `n` ms
 * into a frame started the new glide `n` ms of motion ahead of the one drawn
 * (up to about 3 px on a slow frame), and a row inside a gliding card took up
 * the card's difference. The box is read between two readings of every
 * carrier's applied `translate` that agree: WebKit samples a running
 * animation at the moment of each read, in steps of about a millisecond, so
 * a box read between two equal readings is of that same sample, while the
 * walk's earlier box read, or one read across a step, is of another. Taken
 * out of that
 * box (each scaled by its node's ancestors, as its glide is), the `translate`s
 * leave the element's place with no glide, and each glide's offset at its
 * current time goes back in. A glide replaces any `translate` of the app's
 * own while it runs, so each applied value is the glide's alone. Where the
 * engine reports no applied `translate` at all (an environment without
 * individual transform properties), the box is taken as it is.
 */
/**
 * How many times `onGlideClock` reads a box and the applied translates around
 * it to take all of them from one sample: it bounds the reads for one
 * consistent snapshot (WebKit's samples step about once a millisecond, and a
 * second reading lands inside one step), not a retry around a result.
 */
const SAMPLE_READS = 3;

function onGlideClock(element: Element, rect: DOMRect, area: Element): DOMRect {
  const carriers: {node: Element; glide: Glide; time: number}[] = [];
  for (
    let node: Element | null = element;
    node != null && node !== area;
    node = node.parentElement
  ) {
    const glide = glides.get(node);
    const time = Number(glide?.animation.currentTime);
    if (glide != null && Number.isFinite(time)) {
      carriers.push({node, glide, time});
    }
  }
  if (carriers.length === 0) {
    return rect;
  }
  const view = element.ownerDocument.defaultView;
  const appliedNow = () =>
    carriers.map(({node}) => view?.getComputedStyle(node).translate);
  let applied = appliedNow();
  if (applied.some(translate => translate == null || translate === '')) {
    return rect;
  }
  let box = element.getBoundingClientRect();
  for (let read = 0; read < SAMPLE_READS; read++) {
    const again = appliedNow();
    if (again.every((translate, index) => translate === applied[index])) {
      break;
    }
    applied = again;
    box = element.getBoundingClientRect();
  }
  let dx = 0;
  let dy = 0;
  carriers.forEach(({node, glide, time}, index) => {
    const [appliedX = 0, appliedY = 0] = numbersIn(applied[index] as string);
    const offset = glide.offsetAt(
      Math.min(Math.max(0, time), glide.durationMs),
    );
    const scale = scaleOf(
      node,
      node === element ? box : node.getBoundingClientRect(),
      ownScaleOf(node),
    );
    dx += (offset.x - appliedX) * scale.x;
    dy += (offset.y - appliedY) * scale.y;
  });
  return new DOMRect(box.x + dx, box.y + dy, box.width, box.height);
}

function rectOf(element: Element, cache: WalkCache): DOMRect {
  let rect = cache.rects.get(element);
  if (rect === undefined) {
    rect = element.getBoundingClientRect();
    cache.rects.set(element, rect);
  }
  return rect;
}

/**
 * The elements a change can move, each with its rectangle before the change:
 * the changed element's ancestors up to the area (a centered column moves
 * the card around the change), and at each of their levels the siblings
 * after and before (a centered, end-aligned or space-between row, or
 * `order`, moves those too). A `display: contents` element has no box: its
 * children stand in its place, walked in the same direction. At each level
 * the walk stops at the first sibling outside `band`, so its cost grows with
 * depth plus the siblings near the visible part, never with the length of a
 * list; where the area opts out of scroll anchoring (`walksToBand`), the walk
 * after a change above the band goes on to the band, a cost that grows with
 * that distance. Inside a positioned, stuck sticky or top-layer ancestor only the
 * content after the change is taken.
 */
function collectCandidates(
  changed: Element,
  area: Element,
  band: Band,
  cache: WalkCache,
  walksToBand: boolean,
  ancestors: Set<Element>,
  befores: Set<Element>,
): Map<Element, DOMRect> {
  const out = new Map<Element, DOMRect>();
  /** Takes `element`; returns false once it lies outside the band. */
  /** The current level runs through its siblings, ignoring the band. */
  let runsThrough = false;
  const take = (element: Element, isAfter: boolean): boolean => {
    const part = partOf(element, cache);
    if (part === 'contents') {
      for (
        let child = isAfter
          ? element.firstElementChild
          : element.lastElementChild;
        child != null;
        child = isAfter
          ? child.nextElementSibling
          : child.previousElementSibling
      ) {
        if (!take(child, isAfter)) {
          return false;
        }
      }
      return true;
    }
    if (!part) {
      return true;
    }
    const rect = rectOf(element, cache);
    if (runsThrough) {
      out.set(element, rect);
      return true;
    }
    if (rect.top > band.end) {
      return false;
    }
    if (rect.bottom < band.start) {
      // Above the band. Where the scroller opts out of scroll anchoring, the
      // content after a change above the band shifts the rows in view, so
      // the walk after it goes on to the band; with anchoring, it stops.
      return isAfter && walksToBand;
    }
    out.set(element, rect);
    if (!isAfter) {
      befores.add(element);
    }
    return true;
  };
  // The change's chain up to the area, and from where it is inside a
  // positioned, stuck sticky or top-layer ancestor: that ancestor takes its final
  // place, so inside it only the content after the change moves; the
  // ancestors and the siblings before the change stay with it.
  const chain: Element[] = [];
  for (
    let node: Element | null = changed;
    node != null && node !== area;
    node = node.parentElement
  ) {
    chain.push(node);
  }
  // The levels below this index are inside a positioned ancestor.
  let positionedFrom = 0;
  for (let index = chain.length - 1; index > 0; index -= 1) {
    if (partOf(chain[index], cache) === false || isStuck(chain[index], cache)) {
      positionedFrom = index;
      break;
    }
  }
  for (const [level, node] of chain.entries()) {
    runsThrough = flowsAcross(node.parentElement);
    if (
      node !== changed &&
      level > positionedFrom &&
      partOf(node, cache) === true
    ) {
      // An ancestor of the change in flow: where its layout moves it (a
      // centered column), it glides, and what is inside moves only by its own
      // change. A positioned, stuck sticky or top-layer ancestor, and every
      // ancestor inside it, takes its final place.
      out.set(node, rectOf(node, cache));
      ancestors.add(node);
    }
    for (
      let sibling = node.nextElementSibling;
      sibling != null && take(sibling, true);
      sibling = sibling.nextElementSibling
    ) {
      // The siblings after it, until one lies past the band.
    }
    if (level < positionedFrom) {
      continue;
    }
    for (
      let sibling = node.previousElementSibling;
      sibling != null && take(sibling, false);
      sibling = sibling.previousElementSibling
    ) {
      // The siblings before it, until one lies before the band.
    }
  }
  return out;
}

// ---------------------------------------------------------------------------
// Batches: every change in one area in one frame moves together
// ---------------------------------------------------------------------------

interface Batch {
  readonly area: Element;
  readonly changed: Set<Element>;
  readonly before: Map<Element, DOMRect>;
  /** What each changed element's walk found, so a dropped change moves none. */
  readonly candidates: Map<Element, Element[]>;
  /** The changed elements' sizes before the change, added up. */
  changedSize: number;
  /** How far past the visible part the walks reach (0 before the first). */
  reach: number;
  /** The area's visible part, read once per frame. */
  visible: DOMRect | null;
  /** Whether the area opts out of scroll anchoring, read once per frame. */
  walksToBand: boolean | null;
  /** The change's ancestors among the candidates. */
  readonly ancestors: Set<Element>;
  /** The siblings before the change among the candidates. */
  readonly befores: Set<Element>;
  /**
   * Where the area's content sat before the change, read once per frame: the
   * area's place in view less its scroll offset, so a scroll of the area, an
   * outer scroller or the page shows up as a change of it.
   */
  originBefore: {readonly x: number; readonly y: number} | null;
  readonly cache: WalkCache;
  scheduled: boolean;
  /** Called after every reading and before any glide starts. */
  readonly beforeMove: ((candidates: ReadonlyArray<Element>) => void)[];
  /**
   * The start the change's animations share, taken by its first one: its
   * entrance, or its glides at the flush. A change begun after a block,
   * before this one flushes, takes its own and leaves this one's.
   */
  start: ChangeStart | null;
}

const batches = new Map<Element, Batch>();

function batchFor(area: Element): Batch {
  let batch = batches.get(area);
  if (batch == null) {
    const created: Batch = {
      area,
      changed: new Set(),
      before: new Map(),
      candidates: new Map(),
      changedSize: 0,
      reach: 0,
      visible: null,
      walksToBand: null,
      ancestors: new Set(),
      befores: new Set(),
      originBefore: null,
      cache: {rects: new Map(), parts: new Map()},
      scheduled: false,
      beforeMove: [],
      start: null,
    };
    batches.set(area, created);
    // A measurement no commit claims by the next frame (a controlled owner
    // refused the change) is dropped, so it never moves rows later and holds
    // no elements.
    const view = area.ownerDocument.defaultView;
    const drop = () => {
      if (batches.get(area) === created && !created.scheduled) {
        batches.delete(area);
      }
    };
    if (typeof view?.requestAnimationFrame === 'function') {
      view.requestAnimationFrame(drop);
    } else {
      setTimeout(drop, 16);
    }
    batch = created;
  }
  return batch;
}

/**
 * The start `batch`'s change shares: taken by its first animation, from the
 * document's (startFor), and kept with the batch through its flush.
 */
function changeStartOf(batch: Batch): ChangeStart | undefined {
  const doc = batch.area.ownerDocument;
  const now = doc.timeline?.currentTime;
  if (now == null) {
    return undefined;
  }
  if (batch.start == null || batch.start.frame !== Number(now)) {
    batch.start = startFor(doc, Number(now));
  }
  return batch.start;
}

/**
 * The start of the change being made in `area`, captured now for animations
 * made later in the task, such as the parts riding a glide. It is its batch's
 * when one is open there, otherwise the document's.
 */
function changeStartIn(
  area: Element | null | undefined,
  doc: Document,
): ChangeStart | undefined {
  const batch = area == null ? undefined : batches.get(area);
  if (batch != null) {
    return changeStartOf(batch);
  }
  const now = doc.timeline?.currentTime;
  return now == null ? undefined : startFor(doc, Number(now));
}

function intersects(a: DOMRect, b: DOMRect): boolean {
  return (
    a.width > 0 &&
    a.height > 0 &&
    a.right > b.left &&
    a.left < b.right &&
    a.bottom > b.top &&
    a.top < b.bottom
  );
}

/** The part of the area the person can see: its box within the viewport. */
/** Where the area's scrolled content starts, in client px. */
function originOf(area: Element): {x: number; y: number} {
  const box = area.getBoundingClientRect();
  return {x: box.left - area.scrollLeft, y: box.top - area.scrollTop};
}

function visibleRect(area: Element): DOMRect {
  const box = area.getBoundingClientRect();
  const view = area.ownerDocument.defaultView;
  const width = view?.innerWidth ?? box.right;
  const height = view?.innerHeight ?? box.bottom;
  const left = Math.max(box.left, 0);
  const top = Math.max(box.top, 0);
  return new DOMRect(
    left,
    top,
    Math.max(0, Math.min(box.right, width) - left),
    Math.max(0, Math.min(box.bottom, height) - top),
  );
}

/** The element's rendered scale against its layout size (a scaled ancestor). */
function scaleOf(
  element: Element,
  rect: DOMRect,
  own: {readonly x: number; readonly y: number} = {x: 1, y: 1},
): {x: number; y: number} {
  const html = element as HTMLElement;
  const x =
    html.offsetWidth > 0 && rect.width > 0
      ? rect.width / html.offsetWidth / own.x
      : 1;
  const y =
    html.offsetHeight > 0 && rect.height > 0
      ? rect.height / html.offsetHeight / own.y
      : 1;
  // Subpixel rounding makes an unscaled element read a hair off 1; only a
  // real scale is corrected.
  return {
    x: Math.abs(x - 1) < 0.01 ? 1 : x || 1,
    y: Math.abs(y - 1) < 0.01 ? 1 : y || 1,
  };
}

/**
 * The scale an element's own `scale` and `transform` give it, on each axis
 * (a follower that keeps one in place, `staysInPlace`). A glide's `translate`
 * does not go through them: the individual transform properties apply
 * `translate` first, in the parent's space.
 */
function ownScaleOf(element: Element): {x: number; y: number} {
  const style = element.ownerDocument.defaultView?.getComputedStyle(element);
  if (style == null) {
    return {x: 1, y: 1};
  }
  let x = 1;
  let y = 1;
  const scale = style.getPropertyValue('scale');
  if (scale !== '' && scale !== 'none') {
    const [sx = 1, sy = sx] = numbersIn(scale);
    // Its size, not its direction: a negative scale flips the element in
    // place, and its measured box stays positive.
    x *= Math.abs(sx);
    y *= Math.abs(sy);
  }
  // The computed transform is a matrix: its first column's length is the
  // scale on x, its second's on y.
  const matrix = /^matrix(3d)?\(([^)]*)\)/.exec(
    style.getPropertyValue('transform'),
  );
  if (matrix != null) {
    const m = numbersIn(matrix[2]);
    const [a = 1, b = 0, c = 0, d = 1] =
      matrix[1] == null ? m : [m[0], m[1], m[4], m[5]];
    x *= Math.hypot(a, b);
    y *= Math.hypot(c, d);
  }
  return {x: x || 1, y: y || 1};
}

function flush(batch: Batch): void {
  batches.delete(batch.area);
  const notify = (candidates: ReadonlyArray<Element>) => {
    for (const callback of batch.beforeMove) {
      callback(candidates);
    }
  };
  // What each change's walk measured before it: an element added by the
  // change has no old place, and one it removed is gone.
  const followers = new Set<Element>();
  for (const changed of batch.changed) {
    for (const element of batch.candidates.get(changed) ?? []) {
      if (element.isConnected) {
        followers.add(element);
      }
    }
  }
  if (followers.size === 0) {
    notify([]);
    return;
  }
  const motion = layoutMotion(batch.area);
  if (motion.kind === 'instant') {
    notify([]);
    return;
  }
  // The change's own start, taken by its entrance when it played one, even
  // when another change has begun since.
  const change = changeStartOf(batch);
  const visible = visibleRect(batch.area);
  // Every running glide stops first and every new place is read before any
  // glide starts, so no reading includes another's new motion.
  const entries: {
    readonly element: Element;
    readonly before: DOMRect;
    readonly carried: OffsetCurve;
    readonly carriedMs: number;
    /** The running glide's offset inside `before`, read on the held frame. */
    readonly held: {readonly x: number; readonly y: number};
    after?: DOMRect;
    rawX?: number;
    rawY?: number;
    isMovedByApp?: boolean;
    scale?: {x: number; y: number};
  }[] = [];
  for (const element of followers) {
    const before = batch.before.get(element);
    if (before == null || (before.width === 0 && before.height === 0)) {
      // Added by the change, or not rendered before it: it has no old place.
      // A changed element an earlier change displaced does have one, and
      // moves with its row while it plays its own entrance or exit.
      continue;
    }
    // An element already gliding keeps that motion and adds the new move: the
    // running glide stops (so its rectangle is its new layout place) and the
    // rest of its curve carries into the one new glide, velocity included,
    // summed with the new move.
    const running = glides.get(element);
    let carried = AT_REST;
    let carriedMs = 0;
    let held = AT_REST(0);
    if (running != null) {
      const time = Number(running.animation.currentTime);
      const elapsed = Number.isFinite(time) ? Math.max(0, time) : 0;
      if (elapsed < running.durationMs) {
        held = running.offsetAt(elapsed);
      }
      // The new glide starts at the change's start. After a block, the
      // compositor kept this glide moving past the held frame until then.
      const {startTime} = running.animation;
      const shownAt =
        change != null && startTime != null
          ? Math.max(elapsed, change.at - Number(startTime))
          : elapsed;
      if (shownAt < running.durationMs) {
        carried = t => running.offsetAt(shownAt + t);
        carriedMs = running.durationMs - shownAt;
      }
      running.animation.cancel();
      glides.delete(element);
    }
    entries.push({element, before, carried, carriedMs, held});
  }
  // Every reading (places, transforms, scales) before any glide starts: a
  // glide started between two readings would make the next one lay the page
  // out again, once per element (on a long page, the whole cost).
  const byElement = new Map<Element, (typeof entries)[number]>();
  // An ancestor of the change, and a sibling before it, move by their layout
  // change alone: when scroll anchoring re-scrolls the area, an outer
  // scroller or the page (a change above the visible part), or the area
  // itself moves as its content grows (a dialog re-centered), their place in
  // view shifts by that while their place in the area stays.
  const origin = originOf(batch.area);
  const scrolledX = origin.x - (batch.originBefore?.x ?? origin.x);
  const scrolledY = origin.y - (batch.originBefore?.y ?? origin.y);
  // Netted only where that makes the move smaller: an element the browser
  // kept in place (scroll anchoring for another change in the same frame)
  // stays where it is.
  const nearer = (raw: number, shift: number) =>
    Math.abs(raw + shift) < Math.abs(raw) ? raw + shift : raw;
  for (const entry of entries) {
    // On the same clocks as the place before the change: only the glides this
    // change does not retarget still run here (a card inside an absolutely
    // positioned panel keeps its glide while the row in it moves), so each
    // reads the same in both places and cancels out of the move.
    entry.after = onGlideClock(
      entry.element,
      entry.element.getBoundingClientRect(),
      batch.area,
    );
    // The move is the inline-start edge's, by the container's direction (it
    // decides where the element sits): in a right-to-left container an
    // element that narrows keeps its left edge and moves its right one.
    const container = entry.element.parentElement ?? entry.element;
    const isRtl =
      container.ownerDocument.defaultView?.getComputedStyle(container)
        .direction === 'rtl';
    const rawX = isRtl
      ? entry.before.right - entry.after.right
      : entry.before.left - entry.after.left;
    const rawY = entry.before.top - entry.after.top;
    // The siblings before the change stay with the ancestors around them.
    const isAncestor =
      batch.ancestors.has(entry.element) || batch.befores.has(entry.element);
    entry.rawX = isAncestor ? nearer(rawX, scrolledX) : rawX;
    entry.rawY = isAncestor ? nearer(rawY, scrolledY) : rawY;
    byElement.set(entry.element, entry);
  }
  for (const entry of entries) {
    const after = entry.after as DOMRect;
    if (intersects(entry.before, visible) || intersects(after, visible)) {
      entry.isMovedByApp = movedByApp(entry.element);
      // Only its ancestors' scale is corrected: its own scale or transform
      // (a press's scale) does not apply to the glide's `translate`.
      entry.scale = scaleOf(entry.element, after, ownScaleOf(entry.element));
    }
  }
  // An adopter's own readings join them here, before any glide starts.
  notify(entries.map(entry => entry.element));
  for (const entry of entries) {
    const {element, before, carried, carriedMs, held} = entry;
    const after = entry.after as DOMRect;
    // Nested changes compose: an element inside another moving element moves
    // only by its own change, whatever order the changes were reported in.
    let dx = entry.rawX ?? 0;
    let dy = entry.rawY ?? 0;
    for (
      let ancestor = element.parentElement;
      ancestor != null && ancestor !== batch.area;
      ancestor = ancestor.parentElement
    ) {
      const moving = byElement.get(ancestor);
      if (moving != null) {
        dx -= moving.rawX ?? 0;
        dy -= moving.rawY ?? 0;
        break;
      }
    }
    if (Math.abs(dx) < MIN_SHIFT_PX && Math.abs(dy) < MIN_SHIFT_PX) {
      continue;
    }
    if (!intersects(before, visible) && !intersects(after, visible)) {
      // Outside the visible part before and after: it lands silently.
      continue;
    }
    if (motion.kind === 'fade') {
      safeAnimate(
        element,
        [{opacity: 0}, {opacity: 1}],
        {duration: motion.durationMs, easing: motion.easing},
        change,
      );
      continue;
    }
    if (entry.isMovedByApp === true) {
      // The app moves it itself: it takes its final place at once
      // (`spec:AST-105` Coverage).
      continue;
    }
    // Where it showed before the change, against its new place, in its own
    // px. The part the glide's offset then does not cover is the new move.
    const scale = entry.scale ?? {x: 1, y: 1};
    const moveX = dx / scale.x - held.x;
    const moveY = dy / scale.y - held.y;
    const {progress} = motion;
    const durationMs = Math.max(progress.durationMs, carriedMs);
    const offsetAt = drawnCurve(durationMs, t => {
      const remaining = progress.remaining(t);
      const carry = carried(t);
      return {x: carry.x + moveX * remaining, y: carry.y + moveY * remaining};
    });
    // One replace-composited `translate`: the compositor runs it (INV12).
    const animation = safeAnimate(
      element,
      sampleOver(durationMs, t => {
        const offset = offsetAt(t);
        return {translate: `${offset.x}px ${offset.y}px`};
      }),
      {duration: durationMs, easing: 'linear'},
      change,
      scale,
    );
    if (animation != null) {
      const glide: Glide = {
        animation,
        offsetAt,
        durationMs,
        shownBefore: {x: dx / scale.x, y: dy / scale.y},
        scale,
      };
      glides.set(element, glide);
      animation.addEventListener?.('finish', () => {
        if (glides.get(element) === glide) {
          glides.delete(element);
        }
      });
    }
  }
}

type Target = {readonly current: Element | null} | (() => Element | null);

function resolve(target: Target): Element | null {
  return typeof target === 'function' ? target() : target.current;
}

export interface LayoutChange {
  /** Before the change commits (in the event handler that causes it). */
  measureBefore(): void;
  /**
   * After it commits (a layout effect). Returns whether the change was
   * measured: an unmeasured change (an owner set the state directly) moves
   * nothing, and the component plays no entrance for it either.
   *
   * `beforeMove`, when given, runs once the new places are read and before
   * any glide starts, with the elements the glide may move: whatever the
   * component reads from the layout for the glide, it reads there, so the page
   * is not laid out again (`playLayoutChange` included).
   */
  animate(beforeMove?: (candidates: ReadonlyArray<Element>) => void): boolean;
}

/**
 * Report a size change of `target` to the handle's area. Call
 * `measureBefore()` before the change commits and `animate()` after it; the
 * content after `target`, up to the area, glides from its old place.
 * Changes in one area in one frame move together. Without a handle, or
 * outside its container, nothing moves.
 */
export function reportLayoutChange(
  handle: AnimatedLayout | null | undefined,
  target: Target,
): LayoutChange {
  return {
    measureBefore() {
      const element = resolve(target);
      if (element == null || handle == null) {
        return;
      }
      const area = areaOf(handle, element);
      if (area == null) {
        return;
      }
      beginChange(element.ownerDocument);
      const batch = batchFor(area);
      if (batch.changed.has(element)) {
        return;
      }
      batch.changed.add(element);
      batch.changedSize += rectOf(element, batch.cache).height;
      batch.visible ??= visibleRect(area);
      batch.originBefore ??= originOf(area);
      batch.walksToBand ??=
        area.ownerDocument.defaultView
          ?.getComputedStyle(area)
          .getPropertyValue('overflow-anchor') === 'none';
      // Changes in one frame add up: every change's walk reaches the band
      // their summed size can pull into view. When that outgrows the band
      // walked so far, the band at least doubles and every change is walked
      // again (from the cache), so a frame of many changes re-walks a few
      // times, not once per change.
      const needed = Math.max(batch.visible.height, batch.changedSize);
      const walks = needed > batch.reach ? [...batch.changed] : [element];
      if (needed > batch.reach) {
        batch.reach = Math.max(needed, batch.reach * 2);
      }
      const band = bandFor(batch.visible, batch.reach);
      for (const changed of walks) {
        const candidates = collectCandidates(
          changed,
          area,
          band,
          batch.cache,
          batch.walksToBand,
          batch.ancestors,
          batch.befores,
        );
        for (const [candidate, rect] of candidates) {
          if (!batch.before.has(candidate)) {
            batch.before.set(candidate, onGlideClock(candidate, rect, area));
          }
        }
        batch.candidates.set(changed, [...candidates.keys()]);
      }
    },
    animate(beforeMove) {
      const element = resolve(target);
      if (element == null || handle == null) {
        return false;
      }
      const area = areaOf(handle, element);
      const batch = area == null ? undefined : batches.get(area);
      if (batch == null || !batch.changed.has(element)) {
        return false;
      }
      if (beforeMove != null) {
        batch.beforeMove.push(beforeMove);
      }
      if (!batch.scheduled) {
        batch.scheduled = true;
        // After every layout effect of this commit, before paint, with one
        // registry notice for all the glides it starts.
        queueMicrotask(() => batchPresented(() => flush(batch)));
      }
      return true;
    },
  };
}

// ---------------------------------------------------------------------------
// The edge reveal (`spec:AST-105` FR9)
// ---------------------------------------------------------------------------

/**
 * The edge an element reveals from or conceals to (`spec:AST-105` FR9): its
 * block-end edge by default, or its block-start, inline-start or inline-end
 * edge, such as a panel collapsing beside content. An inline edge follows
 * the element's direction.
 */
export type LayoutEdge =
  'block-end' | 'block-start' | 'inline-start' | 'inline-end';

/** Whether `element` lays its inline axis out right to left. */
function isRtl(element: Element): boolean {
  return (
    element.ownerDocument.defaultView?.getComputedStyle(element).direction ===
    'rtl'
  );
}

/**
 * The `clip-path` that hides `side` of an element from `edge`: `inset()`'s
 * sides are physical (top, right, bottom, left), so an inline edge is
 * mirrored right to left. `zero` is how the other three are written.
 */
function edgeClip(
  edge: LayoutEdge,
  side: string,
  zero: string,
  rtl: boolean,
): string {
  const sides = [zero, zero, zero, zero];
  const index =
    edge === 'block-start'
      ? 0
      : edge === 'block-end'
        ? 2
        : (edge === 'inline-end') !== rtl
          ? 1
          : 3;
  sides[index] = side;
  return `inset(${sides.join(' ')})`;
}

/** A hidden fraction of the element, as a percentage clip on `edge`. */
function fractionClip(edge: LayoutEdge, hidden: number, rtl: boolean): string {
  return edgeClip(edge, `${round(hidden * 100)}%`, '0', rtl);
}

/** A hidden length of the element, in its own px, as a clip on `edge`. */
function pxClip(edge: LayoutEdge, hidden: number, rtl: boolean): string {
  return edgeClip(edge, `${hidden}px`, '0px', rtl);
}

/**
 * The element's size along `edge`'s axis, in its own px (a scaled ancestor
 * divided out), read from the layout the caller already laid out.
 */
function extentOf(element: Element, edge: LayoutEdge): number {
  const rect = element.getBoundingClientRect();
  const scale = scaleOf(element, rect);
  return edge.startsWith('inline')
    ? rect.width / scale.x
    : rect.height / scale.y;
}

/** The parts that slide, and the still clip that holds them while they do. */
interface Sliding {
  readonly parts: ReadonlyArray<Element>;
  /** Each part's ancestors' scale: page px per px of its own offset. */
  readonly scales: ReadonlyArray<{readonly x: number; readonly y: number}>;
  readonly clip: string;
}

/**
 * The parts that slide inside an element revealed or concealed from a block
 * edge by `extent` px. They are its child elements that the band can show:
 * the area's visible part plus one viewport, or `extent` if larger, above and
 * below. A part past the band cannot come into view while it moves, so it
 * stays. The walk stops at the first child below the band, so its cost grows
 * with the changed size, never with the length of a list. A translation
 * cannot move text on its own, so an element with text of its own keeps the
 * clip (null).
 */
function slidingParts(
  element: Element,
  edge: LayoutEdge,
  area: Element,
  extent: number,
): Sliding | null {
  if (!edge.startsWith('block') || !(extent > 0)) {
    return null;
  }
  const view = element.ownerDocument.defaultView;
  const style = view?.getComputedStyle(element);
  // A box the element paints itself would show whole from the first frame
  // under a still clip, so such an element keeps the moving clip. So does one
  // with a generated box, which stays still while its parts slide.
  if (
    view == null ||
    style == null ||
    paintsOwnBox(style) ||
    ['::before', '::after'].some(pseudo => {
      const {content} = view.getComputedStyle(element, pseudo);
      return content !== '' && content !== 'none' && content !== 'normal';
    })
  ) {
    return null;
  }
  const visible = visibleRect(area);
  const band = bandFor(visible, Math.max(view.innerHeight, extent));
  const parts: Element[] = [];
  const scales: {x: number; y: number}[] = [];
  for (let node = element.firstChild; node != null; node = node.nextSibling) {
    if (node.nodeType === Node.TEXT_NODE) {
      if ((node.textContent ?? '').trim() !== '') {
        return null;
      }
      continue;
    }
    if (node.nodeType !== Node.ELEMENT_NODE) {
      continue;
    }
    // A translation moves neither an inline box nor a boxless one.
    const {display} = view.getComputedStyle(node as Element);
    if (display === 'inline' || display === 'contents') {
      return null;
    }
    // Each part's place, read once per reveal, before anything moves.
    const box = (node as Element).getBoundingClientRect();
    if (box.top > band.end) {
      break;
    }
    if (box.bottom >= band.start) {
      // A part an earlier change still glides keeps that glide, which a slide
      // would hide and then show again. The element keeps the moving clip.
      if (glides.has(node as Element)) {
        return null;
      }
      parts.push(node as Element);
      scales.push(scaleOf(node as Element, box, ownScaleOf(node as Element)));
    }
  }
  if (parts.length === 0) {
    return null;
  }
  // The parts come in from one side. The clip holds them inside the content
  // box there, off what the content before the element draws into its padding.
  const inner = (side: 'top' | 'bottom') =>
    (Number.parseFloat(style.getPropertyValue(`border-${side}-width`)) || 0) +
    (Number.parseFloat(style.getPropertyValue(`padding-${side}`)) || 0);
  return {
    parts,
    scales,
    clip:
      edge === 'block-end'
        ? `inset(${inner('top')}px 0px 0px 0px)`
        : `inset(0px 0px ${inner('bottom')}px 0px)`,
  };
}

/**
 * Whether a style paints a box of its own: a fill, a border, a shadow, an
 * outline or a filter.
 */
function paintsOwnBox(style: CSSStyleDeclaration): boolean {
  const isClear = (color: string) =>
    color === '' || color === 'transparent' || /^rgba\(.*,\s*0\)$/.test(color);
  return (
    !isClear(style.backgroundColor) ||
    (style.backgroundImage !== '' && style.backgroundImage !== 'none') ||
    ['Top', 'Right', 'Bottom', 'Left'].some(
      side =>
        style.getPropertyValue(`border-${side.toLowerCase()}-style`) !==
          'none' &&
        Number.parseFloat(
          style.getPropertyValue(`border-${side.toLowerCase()}-width`),
        ) > 0,
    ) ||
    (style.boxShadow !== '' && style.boxShadow !== 'none') ||
    (style.borderImageSource !== '' && style.borderImageSource !== 'none') ||
    (style.filter !== '' && style.filter !== 'none') ||
    (style.outlineStyle !== '' &&
      style.outlineStyle !== 'none' &&
      Number.parseFloat(style.outlineWidth) > 0)
  );
}

/**
 * Where the parts sit when the element hides `hidden` px from `edge`. They
 * move that far towards it, so their far edge meets the content that rides
 * the same edge.
 */
function slideFrame(edge: LayoutEdge, hidden: number): Keyframe {
  return {translate: `0px ${edge === 'block-end' ? -hidden : hidden}px`};
}

/**
 * Clips `element` with `clip` while its parts slide, and returns what puts
 * its own `clip-path` back. The clip does not move, so it stays in step with
 * the parts and the content beside them on every engine.
 */
function holdSlideClip(element: Element, clip: string): () => void {
  const {style} = element as HTMLElement;
  const value = style.getPropertyValue('clip-path');
  const priority = style.getPropertyPriority('clip-path');
  style.setProperty('clip-path', clip);
  return () => {
    if (value === '') {
      style.removeProperty('clip-path');
    } else {
      style.setProperty('clip-path', value, priority);
    }
  };
}

/**
 * The last element before `element` in the area that takes part in layout:
 * its previous sibling, or its nearest ancestor's below the area (the mirror
 * of `nextInFlow`, for a start edge).
 */
function previousInFlow(element: Element, area: Element): Element | null {
  const view = element.ownerDocument.defaultView;
  const lastBox = (from: Element): Element | null => {
    const style = view?.getComputedStyle(from);
    if (style == null) {
      return from;
    }
    if (style.display === 'contents') {
      for (
        let child = from.lastElementChild;
        child != null;
        child = child.previousElementSibling
      ) {
        const box = lastBox(child);
        if (box != null) {
          return box;
        }
      }
      return null;
    }
    return takesPart(from, style) ? from : null;
  };
  let node: Element | null = element;
  while (node != null && node !== area) {
    for (
      let sibling = node.previousElementSibling;
      sibling != null;
      sibling = sibling.previousElementSibling
    ) {
      const box = lastBox(sibling);
      if (box != null) {
        return box;
      }
    }
    node = node.parentElement;
  }
  return null;
}

/**
 * The glide that moves `neighbour`: its own, or that of its nearest gliding
 * ancestor below the area that does not also hold `element` (one that holds
 * both moves the two together, so the edge does not ride it).
 */
function glideMoving(
  neighbour: Element,
  element: Element,
  area: Element,
): Glide | null {
  for (
    let node: Element | null = neighbour;
    node != null && node !== area && !node.contains(element);
    node = node.parentElement
  ) {
    const glide = glides.get(node);
    if (glide != null) {
      return glide;
    }
  }
  return null;
}

/** A one-state reveal or conceal running on an element. */
interface EdgeMotion {
  readonly animation: Animation;
  /** The fraction of the element it shows `t` ms in (1: all of it). */
  shownAt: (t: number) => number;
  /** The parts that slide under the element's clip, and their motions. */
  readonly slides: ReadonlyArray<Animation>;
  /** Puts back what the motion set on the element, once. */
  readonly release: () => void;
}

/** Each element's running one-state reveal or conceal. */
const edgeMotions = new WeakMap<Element, EdgeMotion>();

/**
 * What a one-state motion an adopter stopped (`releaseLayoutExit`) showed,
 * and the timeline time it stopped at: a reveal started in the same frame,
 * the reversal that stopped it, starts there.
 */
const stoppedShown = new WeakMap<
  Element,
  {readonly fraction: number; readonly at: number}
>();

function timelineNow(element: Element): number {
  return Number(element.ownerDocument.timeline?.currentTime ?? Number.NaN);
}

/** What `motion` shows now, by its animation's own clock. */
function shownNow(motion: EdgeMotion): number {
  const time = Number(motion.animation.currentTime);
  return motion.shownAt(Number.isFinite(time) ? Math.max(0, time) : 0);
}

/**
 * What `element` shows as a reveal or conceal starts: where the one-state
 * motion this one reverses had got to (it stops there), or `atRest`, all of
 * it for a conceal and nothing for a reveal.
 */
function shownAtStart(element: Element, atRest: number): number {
  const running = edgeMotions.get(element);
  if (running != null) {
    edgeMotions.delete(element);
    const fraction = shownNow(running);
    running.animation.cancel();
    stopSlides(running);
    return fraction;
  }
  const stopped = stoppedShown.get(element);
  stoppedShown.delete(element);
  if (stopped != null && stopped.at === timelineNow(element)) {
    return stopped.fraction;
  }
  return atRest;
}

/** Stops `motion`'s sliding parts and puts back the element's clip, once. */
function stopSlides(motion: EdgeMotion): void {
  motion.release();
}

/** Records `animation` as `element`'s running one-state motion. */
function trackEdgeMotion(
  element: Element,
  animation: Animation,
  shownAt: (t: number) => number,
  slides: ReadonlyArray<Animation> = [],
  release: () => void = () => {},
  isHeldToRelease = false,
): EdgeMotion {
  let isReleased = false;
  const motion: EdgeMotion = {
    animation,
    shownAt,
    slides,
    release: () => {
      if (!isReleased) {
        isReleased = true;
        for (const slide of slides) {
          stopGlideOf(slide);
        }
        release();
      }
    },
  };
  edgeMotions.set(element, motion);
  if (isHeldToRelease) {
    heldSlides.set(element, motion);
  }
  // A reveal's parts have landed at its end. An exit's parts hold where they
  // end until `releaseLayoutExit`.
  animation.addEventListener?.('finish', () => {
    if (edgeMotions.get(element) === motion) {
      edgeMotions.delete(element);
      if (!isHeldToRelease) {
        motion.release();
      }
    }
  });
  return motion;
}

/** Each exit's motion, whose parts hold their slides until its release. */
const heldSlides = new WeakMap<Element, EdgeMotion>();

/**
 * After this commit's glides start (the batch flushes in a microtask queued
 * before this one), before the frame paints: once the content on `edge`'s
 * side glides, the moving edge rides that glide, frame by frame, so the two
 * never part, a reversal included (the glide carries its running motion).
 * `hiddenAt` turns that content's offset towards the edge's side into the
 * length the element hides; `frame` turns that length into a keyframe.
 * Without that glide (nothing on that side in the area, or nothing that
 * moves) the motion keeps its own curve. The animation is kept, its frames
 * replaced; `onRide` hears the ridden hidden length over time.
 */
function rideNeighbour(
  element: Element,
  area: Element,
  edge: LayoutEdge,
  rtl: boolean,
  animation: Animation,
  isCurrent: () => boolean,
  hiddenAt: (towards: number) => number,
  frame: (hidden: number) => Keyframe,
  onRide: (hidden: (t: number) => number, durationMs: number) => void,
): void {
  const effect = animation.effect as KeyframeEffect | null;
  if (effect == null || typeof effect.setKeyframes !== 'function') {
    return;
  }
  queueMicrotask(() => {
    if (!isCurrent()) {
      return;
    }
    const isEnd = edge.endsWith('end');
    const neighbour = isEnd
      ? nextInFlow(element, area)
      : previousInFlow(element, area);
    const glide =
      neighbour == null ? null : glideMoving(neighbour, element, area);
    if (neighbour == null || glide == null) {
      return;
    }
    // A glide that moves the element itself in the same batch, short of what
    // it shares with the neighbour (an item above them closing): the edge
    // rides the neighbour's offset from the element, not from the page.
    const own = glideMoving(element, neighbour, area);
    // Each glide is read on its own clock. A glide an earlier change started,
    // such as a part's slide, is already some way in.
    const glideAt = startedBefore(glide, animation);
    const ownAt = own == null ? 0 : startedBefore(own, animation);
    const durationMs = Math.max(
      glide.durationMs - glideAt,
      own == null ? 0 : own.durationMs - ownAt,
    );
    // The neighbour's offset from its place relative to the element's,
    // towards the edge's side.
    const sign = isEnd ? 1 : -1;
    const hidden = (t: number): number => {
      const offset = glide.offsetAt(glideAt + t);
      const moved = own?.offsetAt(ownAt + t) ?? {x: 0, y: 0};
      return hiddenAt(
        sign *
          (edge.startsWith('inline')
            ? (rtl ? -1 : 1) * (offset.x - moved.x)
            : offset.y - moved.y),
      );
    };
    const frames = sampleOver(durationMs, t => frame(hidden(t)));
    effect.setKeyframes(frames);
    effect.updateTiming?.({duration: durationMs});
    retimeSettle(animation, frames, durationMs);
    onRide(hidden, durationMs);
  });
}

/**
 * The one-state reveal or conceal rides the content on its edge's side: the
 * element shows what lies between its fixed edge and that content, a reveal
 * less by however far the content still is from its place towards it, a
 * conceal all of it less however far the content has come, fading with what
 * it hides.
 */
function rideEdge(
  element: Element,
  area: Element,
  edge: LayoutEdge,
  rtl: boolean,
  motion: EdgeMotion,
  isConceal: boolean,
): void {
  const extent = extentOf(element, edge);
  if (!(extent > 0)) {
    return;
  }
  rideNeighbour(
    element,
    area,
    edge,
    rtl,
    motion.animation,
    () => edgeMotions.get(element) === motion,
    towards =>
      Math.min(extent, Math.max(0, isConceal ? extent - towards : -towards)),
    hidden =>
      motion.slides.length > 0
        ? {opacity: 1 - hidden / extent}
        : {opacity: 1 - hidden / extent, clipPath: pxClip(edge, hidden, rtl)},
    (hiddenAt, durationMs) => {
      motion.shownAt = t => 1 - hiddenAt(t) / extent;
      // The parts ride the same frames, so their edge and the content's move
      // on one clock.
      for (const slide of motion.slides) {
        const effect = slide.effect as KeyframeEffect | null;
        const frames = sampleOver(durationMs, t =>
          slideFrame(edge, hiddenAt(t)),
        );
        effect?.setKeyframes?.(frames);
        effect?.updateTiming?.({duration: durationMs});
        retimeSettle(slide, frames, durationMs);
      }
    },
  );
}

/**
 * The changed element's own animation, on the same motion as the content
 * after it (`spec:AST-105` FR4): content that appears reveals from its
 * block-end edge downward, or from the `edge` it is given (FR9), and its edge
 * rides the glide of the content on that side once it starts. A reveal that
 * reverses a running conceal (an adopter opens it again mid-exit, after
 * `releaseLayoutExit`) starts from what the element shows. Plays only with a
 * handle, inside its area and in the area's visible part. Returns the
 * entrance it started, or null when it played none.
 */
export function playLayoutChange(
  handle: AnimatedLayout | null | undefined,
  element: Element,
  {edge = 'block-end'}: {edge?: LayoutEdge} = {},
): Animation | null {
  if (handle == null) {
    return null;
  }
  const area = areaOf(handle, element);
  if (area == null) {
    return null;
  }
  if (!intersects(element.getBoundingClientRect(), visibleRect(area))) {
    return null;
  }
  const motion = layoutMotion(area);
  if (motion.kind === 'instant') {
    return null;
  }
  const from = shownAtStart(element, 0);
  // The start of the change it enters with, which its glides then share.
  const batch = batches.get(area);
  const change =
    batch != null &&
    [...batch.changed].some(
      changed => changed === element || changed.contains(element),
    )
      ? changeStartOf(batch)
      : undefined;
  if (motion.kind === 'fade') {
    return safeAnimate(
      element,
      [{opacity: from}, {opacity: 1}],
      {duration: motion.durationMs, easing: motion.easing},
      change,
    );
  }
  const {progress} = motion;
  const rtl = edge.startsWith('inline') && isRtl(element);
  // A block edge's parts slide in under the element's clip, on the frames the
  // content after them glides on. A clip that moved would be painted on its
  // own clock in WebKit, and the edge would part from that content.
  const extent = edge.startsWith('block') ? extentOf(element, edge) : 0;
  const sliding = slidingParts(element, edge, area, extent);
  const partMotions = slideParts(sliding, progress, change, remaining =>
    slideFrame(edge, (1 - from) * remaining * extent),
  );
  const animation = safeAnimate(
    element,
    sampleKeyframes(progress, remaining => {
      const hidden = (1 - from) * remaining;
      return partMotions.length > 0
        ? {opacity: 1 - hidden}
        : {opacity: 1 - hidden, clipPath: fractionClip(edge, hidden, rtl)};
    }),
    {duration: progress.durationMs, easing: 'linear'},
    change,
  );
  if (animation == null) {
    for (const part of partMotions) {
      part.cancel();
    }
  } else {
    const tracked = trackEdgeMotion(
      element,
      animation,
      t => 1 - (1 - from) * progress.remaining(t),
      partMotions,
      partMotions.length > 0 && sliding != null
        ? holdSlideClip(element, sliding.clip)
        : undefined,
    );
    rideEdge(element, area, edge, rtl, tracked, false);
  }
  return animation;
}

/**
 * Plays each part's slide on the change's start, sampled like the glide.
 * `frame` turns the share of the motion still to come into a keyframe.
 */
function slideParts(
  sliding: Sliding | null,
  progress: GlideProgress,
  change: ChangeStart | undefined,
  frame: (remaining: number) => Keyframe,
  fill?: FillMode,
): Animation[] {
  const motions: Animation[] = [];
  for (const [index, part] of (sliding?.parts ?? []).entries()) {
    const motion = safeAnimate(
      part,
      sampleKeyframes(progress, frame),
      {duration: progress.durationMs, easing: 'linear', fill},
      change,
    );
    if (motion != null) {
      motions.push(motion);
      // A slide is the part's glide. A later change in the area then carries
      // its rest into the part's next glide, as it carries any glide.
      const glide: Glide = {
        animation: motion,
        offsetAt: t => drawnOffset(motion, t),
        // A ride retimes the slide, so its length is read off the slide.
        get durationMs() {
          return liveDuration(motion, progress.durationMs);
        },
        // The part showed at its place when the parts were read.
        shownBefore: {x: 0, y: 0},
        scale: sliding?.scales[index] ?? {x: 1, y: 1},
      };
      glides.set(part, glide);
      slideTargets.set(motion, part);
      // An exit's slide then holds its end until the release. The element is
      // inert and has given up its space by then.
      motion.addEventListener?.('finish', () => {
        if (glides.get(part) === glide) {
          glides.delete(part);
        }
      });
    }
  }
  return motions;
}

/**
 * The offset `animation` draws `t` ms in, read off its keyframes, a straight
 * line between each two. A slide that rides another glide reads that glide's
 * frames, so this follows it.
 */
function drawnOffset(
  animation: Animation,
  t: number,
): {readonly x: number; readonly y: number} {
  const effect = animation.effect as KeyframeEffect | null;
  if (effect == null || typeof effect.getKeyframes !== 'function') {
    return {x: 0, y: 0};
  }
  const frames = effect.getKeyframes();
  const duration = Number(effect.getTiming().duration);
  const at = duration > 0 ? Math.min(1, Math.max(0, t / duration)) : 1;
  const offsetOf = (frame: ComputedKeyframe | undefined) => {
    const [x = 0, y = 0] = numbersIn(String(frame?.translate ?? ''));
    return {x, y, offset: frame?.computedOffset ?? 0};
  };
  let from = offsetOf(frames[0]);
  let to = offsetOf(frames[frames.length - 1]);
  for (const frame of frames) {
    const point = offsetOf(frame);
    if (point.offset <= at) {
      from = point;
    }
    if (point.offset >= at) {
      to = point;
      break;
    }
  }
  const span = to.offset - from.offset;
  const k = span > 0 ? (at - from.offset) / span : 0;
  return {x: from.x + (to.x - from.x) * k, y: from.y + (to.y - from.y) * k};
}

/** How many ms before `animation` started `glide` started: 0 in one change. */
function startedBefore(glide: Glide, animation: Animation): number {
  const shift = Number(animation.startTime) - Number(glide.animation.startTime);
  return Number.isFinite(shift) ? Math.max(0, shift) : 0;
}

/** `animation`'s length now, in ms, or `fallback` if it has none. */
function liveDuration(animation: Animation, fallback: number): number {
  const effect = animation.effect as KeyframeEffect | null;
  const duration = Number(effect?.getTiming?.().duration);
  return duration > 0 ? duration : fallback;
}

/** Each part's slide, by its motion: a stopped slide is no glide. */
const slideTargets = new WeakMap<Animation, Element>();

/** Cancels a part's slide, and forgets it as the part's glide. */
function stopGlideOf(animation: Animation): void {
  const part = slideTargets.get(animation);
  if (part != null && glides.get(part)?.animation === animation) {
    glides.delete(part);
  }
  animation.cancel();
}

/** The inline properties an exit sets, so a release removes exactly them. */
const EXIT_PROPERTIES = [
  'margin-block-end',
  'margin-inline-end',
  'margin-block-start',
  'margin-inline-start',
  'pointer-events',
] as const;

/**
 * The first element after `element` in the area that takes part in layout:
 * its next sibling, or its nearest ancestor's below the area. A wrapper's
 * edge is not used: a negative end margin can collapse through it.
 */
function nextInFlow(element: Element, area: Element): Element | null {
  const view = element.ownerDocument.defaultView;
  // The first box at or inside `from` (a `display: contents` element has
  // none of its own: its children stand in its place).
  const firstBox = (from: Element): Element | null => {
    const style = view?.getComputedStyle(from);
    if (style == null) {
      return from;
    }
    if (style.display === 'contents') {
      for (
        let child = from.firstElementChild;
        child != null;
        child = child.nextElementSibling
      ) {
        const box = firstBox(child);
        if (box != null) {
          return box;
        }
      }
      return null;
    }
    return takesPart(from, style) ? from : null;
  };
  let node: Element | null = element;
  while (node != null && node !== area) {
    for (
      let sibling = node.nextElementSibling;
      sibling != null;
      sibling = sibling.nextElementSibling
    ) {
      const box = firstBox(sibling);
      if (box != null) {
        return box;
      }
    }
    node = node.parentElement;
  }
  return null;
}

/**
 * An element's place: its block start, and its inline start (RTL read right
 * to left).
 */
function placeOf(
  element: Element,
  rtl: boolean,
): {block: number; inline: number} {
  const rect = element.getBoundingClientRect();
  return {block: rect.top, inline: rtl ? -rect.right : rect.left};
}

/**
 * Keeps `element` where it is, in flow (so it scrolls and clips with its
 * container), while the content after it takes the place it takes once the
 * element is hidden: a negative end margin measured against that content,
 * so a gap or collapsing margins come out exact. Returns false, setting
 * nothing, when no margin reaches that place.
 */
function giveUpSpace(
  element: HTMLElement,
  area: Element,
  edge: LayoutEdge = 'block-end',
): boolean {
  const view = element.ownerDocument.defaultView;
  const parent =
    element.parentElement == null
      ? undefined
      : view?.getComputedStyle(element.parentElement);
  const isRow =
    parent != null &&
    parent.display.includes('flex') &&
    parent.flexDirection.startsWith('row');
  const rtl = view?.getComputedStyle(element).direction === 'rtl';
  // The default block-end exit frees its space at its end, on the axis its
  // container lays it out on; an exit by another edge frees it on that
  // edge's side, so the element stays where it shows and the content beyond
  // that edge moves (FR9).
  const isStart = edge.endsWith('start');
  const property =
    edge === 'block-end'
      ? isRow
        ? 'margin-inline-end'
        : 'margin-block-end'
      : `margin-${edge}`;
  const isInline = property.includes('inline');
  const size = isInline ? element.offsetWidth : element.offsetHeight;
  const next = nextInFlow(element, area);
  if (next == null && !isStart) {
    // Nothing after it in the area to land anywhere.
    element.style.setProperty(property, `${-size}px`);
    return true;
  }
  const own = element.style.getPropertyValue(property);
  const ownPriority = element.style.getPropertyPriority(property);
  const axis = isInline ? 'inline' : 'block';
  // The content after its container must land too: a flex-row item that
  // sets its row's height moves what follows the row.
  const afterParent =
    element.parentElement == null || element.parentElement === area
      ? null
      : nextInFlow(element.parentElement, area);
  // By a start edge, what lies before it lands too, and the element itself
  // stays where it shows.
  const before = isStart ? previousInFlow(element, area) : null;
  const checked = [next, afterParent, before, isStart ? element : null].filter(
    (box): box is Element => box != null,
  );
  if (checked.length === 0) {
    return false;
  }
  // The element's scale, read in the layout the caller's visibility check
  // already laid out.
  const scale = scaleOf(element, element.getBoundingClientRect());
  // Where the content after it goes once it is hidden, read with it taken
  // out of flow (not `display: none`, which would restart the CSS animations
  // inside it).
  const position = element.style.getPropertyValue('position');
  const positionPriority = element.style.getPropertyPriority('position');
  const shown = isStart ? placeOf(element, rtl) : null;
  element.style.setProperty('position', 'absolute', 'important');
  const targets = checked.map(box =>
    box === element && shown != null ? shown : placeOf(box, rtl),
  );
  const target = targets[0];
  if (position === '') {
    element.style.removeProperty('position');
  } else {
    element.style.setProperty('position', position, positionPriority);
  }
  // The reading is in screen px, the margin in the element's own: under a
  // scaled ancestor a distance is divided by the scale on this axis.
  const perPx = isRow ? scale.x : scale.y;
  // A first guess (its box), then one correction from the measured result:
  // a gap, a collapsed margin or the element's own margins.
  element.style.setProperty(property, `${-size}px`);
  const guess = placeOf(checked[0], rtl)[axis];
  const correction = (target[axis] - guess) / perPx;
  element.style.setProperty(property, `${-size + correction}px`);
  // Everything checked must land on both axes: a flex-row item that sets
  // its row's height frees no block space with an inline margin.
  const missed = checked.some((box, index) => {
    const landed = placeOf(box, rtl);
    return (
      Math.abs(landed.block - targets[index].block) > 1 ||
      Math.abs(landed.inline - targets[index].inline) > 1
    );
  });
  if (missed) {
    if (own === '') {
      element.style.removeProperty(property);
    } else {
      element.style.setProperty(property, own, ownPriority);
    }
    return false;
  }
  return true;
}

/** Exits holding an element back, so a release can stop one. */
const exits = new WeakMap<Element, Animation | null>();

/** What an exit replaced on its element, so a release puts back exactly it. */
interface Replaced {
  readonly inert: boolean;
  readonly styles: ReadonlyArray<readonly [string, string, string]>;
}
const replaced = new WeakMap<Element, Replaced>();

/**
 * The changed element's exit (`spec:AST-105` FR4): content that disappears
 * keeps its place on screen but gives up its space (a negative end margin
 * measured against the layout without it, so the content after it glides up
 * at once to exactly where it ends, and it still scrolls and clips with its
 * container), is inert (no focus, no pointer, nothing read), conceals upward
 * from its bottom edge on the same motion, and then `done` runs, when the
 * component hides or unmounts it. Under Reduce Motion with a coarse primary pointer it
 * fades instead. Call it in the layout effect of the commit that closes the
 * element, after the change's `animate()` reported it measured, in the same
 * task: the glide reads the layout once the element has given up its space.
 *
 * It conceals to its block-end edge by default, or to the `edge` it is given
 * (`spec:AST-105` FR9), and its edge rides the glide of the content on that
 * side once it starts; a conceal that reverses a running reveal (a close
 * while it opens) starts from what the element shows.
 *
 * Returns false, holding nothing, when the exit lands at once: no handle, a
 * close no change in the area measured, outside the area or its visible part,
 * Reduce Motion with a fine pointer, or a layout no end margin can free (a
 * grid track and its gap, a flex-row item that sets its row's height); in
 * that last case the content after it takes its final place at once too.
 * The component then hides the element itself.
 */
export function holdLayoutExit(
  handle: AnimatedLayout | null | undefined,
  element: HTMLElement,
  done: () => void,
  {edge = 'block-end'}: {edge?: LayoutEdge} = {},
): boolean {
  if (handle == null) {
    return false;
  }
  const area = areaOf(handle, element);
  if (
    area == null ||
    !intersects(element.getBoundingClientRect(), visibleRect(area))
  ) {
    return false;
  }
  // Only a measured close exits: the content after it glides into its place.
  const batch = batches.get(area);
  if (
    batch == null ||
    ![...batch.changed].some(
      changed => changed === element || changed.contains(element),
    )
  ) {
    return false;
  }
  const motion = layoutMotion(area);
  if (motion.kind === 'instant') {
    return false;
  }
  releaseLayoutExit(element);
  const prior: Replaced = {
    inert: element.hasAttribute('inert'),
    styles: EXIT_PROPERTIES.map(
      property =>
        [
          property,
          element.style.getPropertyValue(property),
          element.style.getPropertyPriority(property),
        ] as const,
    ),
  };
  if (!giveUpSpace(element, area, edge)) {
    // A layout no end margin can free (a grid track and its gap, a flex-row
    // item that sets its row's height): it hides at once, and the content
    // after it takes its final place at once (`spec:AST-105` out of
    // coverage).
    for (const changed of [...batch.changed]) {
      if (changed === element || changed.contains(element)) {
        batch.changed.delete(changed);
      }
    }
    return false;
  }
  replaced.set(element, prior);
  // Out of reach while it conceals: no focus, no pointer, nothing read.
  element.setAttribute('inert', '');
  element.style.setProperty('pointer-events', 'none');
  // A close while it opens: the reveal stops where it shows, and this starts
  // there.
  const from = shownAtStart(element, 1);
  const rtl = edge.startsWith('inline') && isRtl(element);
  // The start of the change it exits with, which its glides then share.
  const change = changeStartOf(batch);
  let animation: Animation | null;
  if (motion.kind === 'fade') {
    animation = safeAnimate(
      element,
      [{opacity: from}, {opacity: 0}],
      {duration: motion.durationMs, easing: motion.easing, fill: 'forwards'},
      change,
    );
  } else {
    const {progress} = motion;
    // As in a reveal, a block edge's parts slide out under its clip.
    const extent = edge.startsWith('block') ? extentOf(element, edge) : 0;
    const sliding = slidingParts(element, edge, area, extent);
    const partMotions = slideParts(
      sliding,
      progress,
      change,
      remaining => slideFrame(edge, (1 - from * remaining) * extent),
      'forwards',
    );
    animation = safeAnimate(
      element,
      sampleKeyframes(progress, remaining => {
        const shown = from * remaining;
        return partMotions.length > 0
          ? {opacity: shown}
          : {opacity: shown, clipPath: fractionClip(edge, 1 - shown, rtl)};
      }),
      {duration: progress.durationMs, easing: 'linear', fill: 'forwards'},
      change,
    );
    if (animation == null) {
      for (const part of partMotions) {
        part.cancel();
      }
    } else {
      const tracked = trackEdgeMotion(
        element,
        animation,
        t => from * progress.remaining(t),
        partMotions,
        partMotions.length > 0 && sliding != null
          ? holdSlideClip(element, sliding.clip)
          : undefined,
        true,
      );
      rideEdge(element, area, edge, rtl, tracked, true);
    }
  }
  exits.set(element, animation);
  if (animation == null) {
    // No Web Animations: nothing to wait for.
    done();
    return true;
  }
  animation.addEventListener?.('finish', () => {
    if (exits.get(element) === animation) {
      done();
    }
  });
  return true;
}

/**
 * Puts an element `holdLayoutExit` held back: stops its exit and puts back
 * what the exit replaced (its `inert` and inline values as they were). Called
 * once the component has hidden the element, or when the element opens again
 * mid-exit.
 */
export function releaseLayoutExit(element: HTMLElement): void {
  if (!exits.has(element)) {
    return;
  }
  // What the exit showed as it stopped: a reveal in the same frame (opened
  // again mid-exit) starts there.
  const running = edgeMotions.get(element);
  if (running != null) {
    edgeMotions.delete(element);
    stoppedShown.set(element, {
      fraction: shownNow(running),
      at: timelineNow(element),
    });
    stopSlides(running);
  }
  const held = heldSlides.get(element);
  heldSlides.delete(element);
  if (held != null) {
    stopSlides(held);
  }
  exits.get(element)?.cancel();
  exits.delete(element);
  const prior = replaced.get(element);
  replaced.delete(element);
  if (prior?.inert !== true) {
    element.removeAttribute('inert');
  }
  for (const [property, value, priority] of prior?.styles ?? []) {
    if (value === '') {
      element.style.removeProperty(property);
    } else {
      element.style.setProperty(property, value, priority);
    }
  }
}

// ---------------------------------------------------------------------------
// The in-place swap
// ---------------------------------------------------------------------------

/**
 * Old content held as one transient copy while new content enters in its
 * place (`spec:AST-105` FR8): inert, hidden from assistive technology, and
 * removed when the swap ends (`architecture:component-style-authoring` INV7).
 */
export interface LayoutSwap {
  readonly area: Element;
  readonly copy: HTMLElement;
  /** Where the old content showed, in viewport coordinates. */
  readonly rect: DOMRect;
}

/** How far a ridden element has moved since the swap began. */
export interface LayoutRide {
  readonly x: number;
  readonly y: number;
}

/**
 * How a swap plays, as frames over its progress (0 → 1) and, with
 * `rideWith`, the ridden element's travel so far.
 */
export interface LayoutSwapMotion {
  /** The box the copy is laid out in, over the old content's place. */
  readonly host: Element;
  /** The copy's frames while it travels. */
  readonly copy: (p: number, ride: LayoutRide) => Keyframe;
  /** Its text's opacity, on its own curve, when that differs from the copy's. */
  readonly copyText?: (p: number) => number;
  /**
   * The copy paints in the background it shows, above its neighbours: at
   * `z-index: 1` as the host's last child, or at `copyBefore`'s level.
   */
  readonly isOpaque?: boolean;
  /**
   * Place the copy just before this child of the host, at that child's
   * level in the paint order, with no `z-index` of its own. Without it the
   * opaque copy is the host's last child at `z-index: 1`.
   */
  readonly copyBefore?: Element;
  /**
   * An element the glide moves, such as the column the old content sat in.
   * Every part plays over its glide, frame by frame, and is told how far it
   * has moved; the copy rides it unless `isCopyMoved` is false. Without a
   * glide (it lands silently) the ride is the whole `travel` at once (its
   * old place less its new).
   */
  readonly rideWith?: {
    readonly element: Element;
    readonly travel: LayoutRide;
    readonly isCopyMoved?: boolean;
  };
  /** Called once when the swap ends, however it ends. */
  readonly onEnd?: () => void;
  /** Elements the page already renders, entering with the swap. */
  readonly incoming: ReadonlyArray<{
    readonly element: Element;
    readonly frames: (p: number, ride: LayoutRide) => Keyframe;
  }>;
}

const NO_RIDE: LayoutRide = {x: 0, y: 0};

/**
 * Before a change commits: hold `element`'s old content as one transient copy
 * (`spec:AST-105` FR8). With `isVisiblePart`, the copy is the element's
 * visible part, its content scrolled as it was (a scroll container). Returns
 * null without a handle, outside its area, under an immediate change, or for
 * content too large to copy.
 */
export function holdLayoutSwap(
  handle: AnimatedLayout | null | undefined,
  element: HTMLElement,
  {isVisiblePart = false}: {isVisiblePart?: boolean} = {},
): LayoutSwap | null {
  if (handle == null || typeof element.animate !== 'function') {
    return null;
  }
  const area = areaOf(handle, element);
  if (
    area == null ||
    layoutMotion(area).kind === 'instant' ||
    !isCopyable(element)
  ) {
    return null;
  }
  beginChange(element.ownerDocument);
  const box = element.getBoundingClientRect();
  if (!isVisiblePart) {
    const copy = inertCopy(element);
    return copy == null ? null : {area, copy, rect: box};
  }
  const part = visiblePartCopy(element);
  return part == null ? null : {area, ...part};
}

/**
 * After the change commits, before paint: the copy leaves while the incoming
 * elements enter, on FR4's one motion, every part started on the same
 * timeline time. Under Reduce Motion with a coarse pointer, only opacity
 * changes (`design:reduced-motion` DR2). Returns what ends the swap at once;
 * it also ends when its motion does, and the copy is removed.
 */
export function playLayoutSwap(
  swap: LayoutSwap,
  how: LayoutSwapMotion,
): () => void {
  const motion = layoutMotion(swap.area);
  if (motion.kind === 'instant') {
    return () => {};
  }
  const {copy} = swap;
  // Captured now: the parts riding a glide play a microtask later, on the
  // start of the change they are part of.
  const change = changeStartIn(swap.area, copy.ownerDocument);
  placeOver(copy, how.host, swap.rect, how.copyBefore ?? null);
  if (how.isOpaque === true) {
    if (how.copyBefore == null) {
      copy.style.zIndex = '1';
    }
    copy.style.backgroundColor = paintedBackground(copy);
  }
  const animations: Animation[] = [];
  let isDone = false;
  const end = () => {
    if (isDone) {
      return;
    }
    isDone = true;
    animations.forEach(animation => animation.cancel());
    copy.remove();
    how.onEnd?.();
  };
  const {copyText, rideWith} = how;
  const fadedText =
    copyText != null && motion.kind === 'glide' ? wrapText(copy) : [];
  // Each part as a function of time: its frame, or the copy's with its ride.
  const parts: [Element, (p: number, ride: LayoutRide) => Keyframe][] = [];
  if (motion.kind === 'glide') {
    const moves = rideWith != null && rideWith.isCopyMoved !== false;
    parts.push([
      copy,
      (p, ride) => ({
        ...how.copy(p, ride),
        ...(moves ? {translate: `${ride.x}px ${ride.y}px`} : null),
      }),
    ]);
    for (const span of fadedText) {
      parts.push([span, p => ({opacity: copyText?.(p) ?? 1})]);
    }
    for (const {element, frames} of how.incoming) {
      parts.push([element, frames]);
    }
  } else {
    // Reduce Motion with a coarse pointer: only opacity changes.
    parts.push([copy, p => ({opacity: 1 - p})]);
    for (const {element} of how.incoming) {
      parts.push([element, p => ({opacity: p})]);
    }
  }
  const playAll = (
    durationMs: number,
    progressAt: (t: number) => number,
    rideAt: (t: number) => LayoutRide,
    options: KeyframeAnimationOptions,
    sample: (shape: (t: number) => Keyframe) => Keyframe[],
  ) => {
    for (const [element, shape] of parts) {
      const animation = safeAnimate(
        element,
        sample(t => shape(progressAt(t), rideAt(t))),
        {duration: durationMs, fill: 'both', ...options},
        change,
      );
      if (animation != null) {
        animations.push(animation);
      }
    }
    if (animations.length === 0) {
      end();
    } else {
      // Every part runs on one clock, so the first to finish ends them all.
      animations[0].addEventListener?.('finish', end);
    }
  };
  if (motion.kind === 'fade') {
    playAll(
      motion.durationMs,
      t => (t <= 0 ? 0 : 1),
      () => NO_RIDE,
      {easing: motion.easing},
      shape => [shape(0), shape(motion.durationMs)],
    );
    return end;
  }
  const {progress} = motion;
  const progressAt = (t: number) => 1 - progress.remaining(t);
  if (rideWith == null) {
    playAll(
      progress.durationMs,
      progressAt,
      () => NO_RIDE,
      {easing: 'linear'},
      shape => sampleOver(progress.durationMs, shape),
    );
    return end;
  }
  // After this commit's glides start (the batch flushes in a microtask queued
  // before this one), before the frame paints: every part plays over the
  // ridden element's glide, told how far it has moved from where it showed.
  queueMicrotask(() => {
    if (isDone) {
      return;
    }
    const glide = glides.get(rideWith.element);
    const durationMs = glide?.durationMs ?? progress.durationMs;
    const rideAt = (t: number): LayoutRide => {
      if (glide == null) {
        return {x: -rideWith.travel.x, y: -rideWith.travel.y};
      }
      // The parts were read where the ridden element showed then. After a
      // block it has moved on by the glide's start, so they move with it.
      const now = glide.offsetAt(t);
      const start = glide.shownBefore;
      return {x: now.x - start.x, y: now.y - start.y};
    };
    playAll(durationMs, progressAt, rideAt, {easing: 'linear'}, shape =>
      sampleOver(durationMs, shape),
    );
  });
  return end;
}

/**
 * After a change commits, before paint: elements the page already renders
 * play frames over the change's progress on FR4's one motion, with no copy,
 * such as a surface reaching over a gap a glide opens. Under Reduce Motion
 * with a coarse pointer, only opacity changes; under an immediate change,
 * nothing plays. Returns what ends them at once.
 */
export function playLayoutFrames(
  handle: AnimatedLayout | null | undefined,
  parts: LayoutSwapMotion['incoming'],
): () => void {
  const area = handle == null ? null : readArea(handle);
  const motion = area == null ? null : layoutMotion(area);
  if (area == null || motion == null || motion.kind === 'instant') {
    return () => {};
  }
  const change = changeStartIn(area, area.ownerDocument);
  const animations: Animation[] = [];
  for (const {element, frames: shape} of parts) {
    const animation =
      motion.kind === 'glide'
        ? safeAnimate(
            element,
            sampleKeyframes(motion.progress, remaining =>
              shape(1 - remaining, NO_RIDE),
            ),
            {
              duration: motion.progress.durationMs,
              easing: 'linear',
              fill: 'both',
            },
            change,
          )
        : safeAnimate(
            element,
            [{opacity: 0}, {opacity: 1}],
            {duration: motion.durationMs, easing: motion.easing},
            change,
          );
    if (animation != null) {
      animations.push(animation);
    }
  }
  // Held through the motion, then released: every part shares one clock, so
  // the first to finish ends them all and each element shows its own styles.
  const end = () => animations.forEach(animation => animation.cancel());
  animations[0]?.addEventListener?.('finish', end);
  return end;
}

// ---------------------------------------------------------------------------
// The edge reveal's two-state form (`spec:AST-105` FR9)
// ---------------------------------------------------------------------------

/**
 * An element's old state, held before a change commits for FR9's two-state
 * edge reveal.
 */
export interface LayoutEdgeHold {
  readonly element: HTMLElement;
  /** Where it showed, in viewport coordinates. */
  readonly rect: DOMRect;
  /**
   * Its size along the edge's axis as it shows: what a running reveal shows
   * mid-motion, or its box.
   */
  readonly extent: number;
  /** Its old state as one transient copy, or null when it cannot be held. */
  readonly swap: LayoutSwap | null;
}

/** A playing two-state edge reveal. */
export interface LayoutEdgeMotion {
  /** Ends it at once (a new change, an unmount). */
  end(): void;
  /**
   * What it shows now: its extent along the edge's axis and the motion's
   * progress (0 → 1), or null once it has settled.
   */
  shown(): {readonly extent: number; readonly progress: number} | null;
}

/** What the caller adds to a two-state edge reveal: only its own fades. */
export interface LayoutEdgeParts {
  /** The old state's copy's opacity over the progress (1 when absent). */
  readonly copyOpacity?: (p: number) => number;
  /** Its text's opacity, on its own curve, when that differs from the copy's. */
  readonly copyText?: (p: number) => number;
  /** Parts the page renders, playing with the reveal (the new state's text). */
  readonly incoming?: ReadonlyArray<{
    readonly element: Element;
    readonly frames: (p: number) => Keyframe;
  }>;
}

const SETTLED: LayoutEdgeMotion = {end: () => {}, shown: () => null};

/**
 * Before a change commits: hold `element`'s old state for FR9's two-state edge
 * reveal, its box and the extent it shows along `edge`'s axis (`shown`, from a
 * running reveal, or its box), and its old state as one transient copy (null
 * when it cannot be copied, or under an immediate change). Returns null
 * without the element or without Web Animations.
 */
export function holdLayoutEdge(
  handle: AnimatedLayout | null | undefined,
  element: HTMLElement | null,
  {
    edge = 'block-end',
    shown = null,
  }: {edge?: LayoutEdge; shown?: number | null} = {},
): LayoutEdgeHold | null {
  if (element == null || typeof element.animate !== 'function') {
    return null;
  }
  beginChange(element.ownerDocument);
  const rect = element.getBoundingClientRect();
  return {
    element,
    rect,
    extent: shown ?? (edge.startsWith('inline') ? rect.width : rect.height),
    swap: holdLayoutSwap(handle, element),
  };
}

/**
 * After the change commits, before paint: FR9's two-state edge reveal, on
 * FR4's one motion. The state that is larger along `edge`'s axis is clipped
 * on that edge, from the extent the element showed to the new one: a conceal
 * covers the old state, held as the swap's copy, with the element raised
 * above it; a reveal opens the element, under the old state. With
 * `rideWith`, an element the glide moves after that edge (a rail's content
 * column), the edge rides its glide, frame by frame, so the two never part,
 * also when this reverses a running reveal; without it the edge follows the
 * motion's curve. `parts` gives the caller's own fades, told whether the edge
 * conceals and the element as it is now. Under Reduce Motion it follows
 * `design:reduced-motion`: opacity only under a coarse primary pointer (DR2),
 * an immediate change otherwise (DR3). `current` is the element after the
 * commit, when it remounted.
 */
export function playLayoutEdge(
  hold: LayoutEdgeHold,
  current: HTMLElement | null,
  handle: AnimatedLayout,
  {
    edge = 'block-end',
    rideWith = null,
    parts,
  }: {
    edge?: LayoutEdge;
    rideWith?: Element | null;
    parts?: (isConceal: boolean, element: HTMLElement) => LayoutEdgeParts;
  } = {},
): LayoutEdgeMotion {
  const {rect: before, swap, extent: from} = hold;
  const element = current?.isConnected === true ? current : hold.element;
  if (!element.isConnected) {
    return SETTLED;
  }
  const motion = layoutMotion(element);
  const next = element.getBoundingClientRect();
  const isInline = edge.startsWith('inline');
  const extentOfBox = (box: DOMRect) => (isInline ? box.width : box.height);
  const to = extentOfBox(next);
  if (motion.kind === 'instant' || Math.abs(to - from) < 0.5) {
    return SETTLED;
  }
  const isConceal = to < from;
  const isEnd = edge.endsWith('end');
  const rtl = isInline && isRtl(element);
  // The row that holds the element and the ridden element, or its parent.
  const host =
    rideWith?.parentElement != null && rideWith.parentElement.contains(element)
      ? rideWith.parentElement
      : element.parentElement;
  // Riding needs the swap: its frames carry the ridden element's travel.
  // Without one (old state that cannot be copied) the edge follows the
  // motion's curve.
  const rides =
    host != null &&
    rideWith != null &&
    rideWith.parentElement === host &&
    swap != null;
  // The ridden element's travel so far, towards the edge's side.
  const sign = isEnd ? 1 : -1;
  const towards = (ride: LayoutRide) =>
    sign * (isInline ? (rtl ? -ride.x : ride.x) : ride.y);
  const extentAt = (p: number, ride: LayoutRide) =>
    rides ? from + towards(ride) : from + (to - from) * p;
  const clip = (hidden: number) => pxClip(edge, hidden, rtl);
  const now = () => Number(element.ownerDocument.timeline?.currentTime ?? 0);
  // The start this change's animations share, which after a block is later
  // than the frame time the timeline still reads (startFor).
  const startedAt =
    changeStartIn(areaOf(handle, element), element.ownerDocument)?.at ?? 0;
  const durationMs =
    motion.kind === 'glide' ? motion.progress.durationMs : motion.durationMs;
  const progressAt = (ms: number) =>
    motion.kind === 'glide'
      ? 1 - motion.progress.remaining(Math.min(ms, durationMs))
      : 0;
  const shown = (): {extent: number; progress: number} | null => {
    const elapsed = Math.max(0, now() - startedAt);
    if (elapsed >= durationMs) {
      return null;
    }
    // The fades are read at the change's start, where the glide it retargets
    // carries on. The extent stays on the timeline's frame, the frame a ride
    // is measured from.
    const progress = progressAt(
      Math.max(elapsed, layoutStartFor(element.ownerDocument) - startedAt),
    );
    let extent = from + (to - from) * progressAt(elapsed);
    if (rides && rideWith != null) {
      // The edge is the ridden element's: read it where it shows, on the
      // timeline's clock.
      const ridden = shownBoxAt(rideWith, now());
      const own = element.getBoundingClientRect();
      extent = !isInline
        ? isEnd
          ? ridden.top - own.top
          : own.bottom - ridden.bottom
        : isEnd !== rtl
          ? ridden.left - own.left
          : own.right - ridden.right;
    }
    return {extent, progress};
  };
  // The ride, when the ridden element does not glide: its whole travel at
  // once, physical (its old place less its new).
  const travel = sign * (from - to);
  const rideSpec =
    rides && rideWith != null
      ? {
          element: rideWith,
          travel: isInline
            ? {x: rtl ? -travel : travel, y: 0}
            : {x: 0, y: travel},
          isCopyMoved: false,
        }
      : undefined;
  // The copy keeps the element's fixed edge (the one opposite `edge`) where
  // the element is now, so it meets the element wherever it sits.
  const fixedAtStart = isEnd !== (isInline && rtl);
  const at = new DOMRect(
    isInline && !fixedAtStart ? next.right - before.width : next.left,
    !isInline && !isEnd ? next.bottom - before.height : next.top,
    before.width,
    before.height,
  );
  const own = parts?.(isConceal, element) ?? {};
  const copyOpacity = own.copyOpacity ?? (() => 1);

  if (isConceal) {
    // A conceal covers the old state, held by the swap, from the extent it
    // shows down to the new one; the element, raised above it, shows through.
    if (swap == null || host == null) {
      return SETTLED;
    }
    let raised: HTMLElement | null = element;
    while (raised != null && raised.parentElement !== host) {
      raised = raised.parentElement;
    }
    const restore = raised == null ? null : {position: raised.style.position};
    // The copy paints at the element's own level: just before it in the
    // host, with no z-index, so page content stacks against the pair as it
    // does against the element alone. The element, positioned, paints above
    // the copy by tree order.
    if (raised != null && getComputedStyle(raised).position === 'static') {
      raised.style.position = 'relative';
    }
    const end = playLayoutSwap(
      {...swap, rect: at},
      {
        host,
        isOpaque: true,
        copyBefore: raised ?? undefined,
        copy: (p, ride) => ({
          clipPath: clip(extentOfBox(before) - extentAt(p, ride)),
          opacity: copyOpacity(p),
        }),
        copyText: own.copyText,
        rideWith: rideSpec,
        onEnd: () => {
          if (raised != null && restore != null) {
            raised.style.position = restore.position;
          }
        },
        incoming: own.incoming ?? [],
      },
    );
    return {end, shown};
  }

  // A reveal opens the element from the extent it showed, under the old
  // state held by the same swap.
  const incoming = [
    {
      element,
      frames: (p: number, ride: LayoutRide) => ({
        clipPath: clip(to - extentAt(p, ride)),
      }),
    },
    ...(own.incoming ?? []),
  ];
  const end =
    swap != null && host != null
      ? playLayoutSwap(
          {...swap, rect: at},
          {
            host,
            isOpaque: true,
            copy: p => ({opacity: copyOpacity(p)}),
            copyText: own.copyText,
            rideWith: rideSpec,
            incoming,
          },
        )
      : playLayoutFrames(handle, incoming);
  return {end, shown};
}

// ---------------------------------------------------------------------------
// The edge reveal of a resized element (`spec:AST-105` FR9, no copy)
// ---------------------------------------------------------------------------

/** A resized element's edge reveal, reported around its change. */
export interface LayoutEdgeReport {
  /** Before the change commits: measures the element and what moves. */
  measureBefore(): void;
  /**
   * After the new size is applied, before paint: the element reveals or
   * conceals by its edge, from the extent it showed to its new one, and the
   * content beside it glides on the same motion.
   */
  animate(): void;
  /** Ends a running reveal or conceal at once, removing what it holds. */
  cancel(): void;
}

/** A running edge reveal of a resized element. */
interface ResizeReveal {
  readonly animation: Animation | null;
  /** The extent it shows `t` ms in, in its own px. */
  shownAt: (t: number) => number;
  /** Its extent along the edge's axis as laid out, held or not. */
  readonly box: number;
  /** Ends it, putting back what it replaced. */
  release(): void;
}

const resizeReveals = new WeakMap<Element, ResizeReveal>();

/** The inline properties a size hold sets, by axis. */
const HOLD_PROPERTIES = {
  inline: [
    'inline-size',
    'min-inline-size',
    'max-inline-size',
    'flex-basis',
    'flex-grow',
    'flex-shrink',
  ],
  block: [
    'block-size',
    'min-block-size',
    'max-block-size',
    'flex-basis',
    'flex-grow',
    'flex-shrink',
  ],
} as const;

/**
 * The inside of an element as it was laid out: its padding along an axis, its
 * overflow and its scroll offset. A size change can change them in the same
 * commit, as a LayoutPanel at width 0 drops its padding and stops scrolling.
 */
interface LaidOutInside {
  /** Its padding at the axis's start and end. */
  readonly gutters: readonly [string, string];
  /** Its overflow across and down. */
  readonly overflow: readonly [string, string];
  /** Its scroll offset across and down. */
  readonly scroll: readonly [number, number];
}

function insideOf(
  element: HTMLElement,
  axis: 'inline' | 'block',
): LaidOutInside {
  const style = getComputedStyle(element);
  return {
    gutters: [
      style.getPropertyValue(`padding-${axis}-start`),
      style.getPropertyValue(`padding-${axis}-end`),
    ],
    overflow: [
      style.getPropertyValue('overflow-x'),
      style.getPropertyValue('overflow-y'),
    ],
    scroll: [element.scrollLeft, element.scrollTop],
  };
}

function restoreScroll(element: HTMLElement, inside: LaidOutInside): void {
  const [across, down] = inside.scroll;
  if (element.scrollLeft !== across) {
    element.scrollLeft = across;
  }
  if (element.scrollTop !== down) {
    element.scrollTop = down;
  }
}

/**
 * Holds `element` at `extent` own px along `edge`'s axis while it conceals to
 * `keep`, freeing the difference by the margin on that edge's side, so what
 * lies beyond the edge stays where the new size puts it. Its padding,
 * overflow and scroll offset stay as `inside` measured them, so nothing in it
 * moves while it is clipped. Returns what puts back every value it set.
 * When no margin frees it, as the content on that side did not stay put, it
 * sets nothing and returns null.
 */
function holdExtent(
  element: HTMLElement,
  area: Element,
  edge: LayoutEdge,
  extent: number,
  keep: number,
  inside: LaidOutInside,
): (() => void) | null {
  const axis = edge.startsWith('inline') ? 'inline' : 'block';
  const margin = `margin-${edge}`;
  const insideProperties = [
    [`padding-${axis}-start`, inside.gutters[0]],
    [`padding-${axis}-end`, inside.gutters[1]],
    ['overflow-x', inside.overflow[0]],
    ['overflow-y', inside.overflow[1]],
  ] as const;
  const properties = [
    ...HOLD_PROPERTIES[axis],
    margin,
    ...insideProperties.map(([property]) => property),
  ];
  const prior = properties.map(
    property =>
      [
        property,
        element.style.getPropertyValue(property),
        element.style.getPropertyPriority(property),
      ] as const,
  );
  const restore = () => {
    for (const [property, value, priority] of prior) {
      if (value === '') {
        element.style.removeProperty(property);
      } else {
        element.style.setProperty(property, value, priority);
      }
    }
  };
  const isEnd = edge.endsWith('end');
  const rtl = axis === 'inline' && isRtl(element);
  const beyond = isEnd
    ? nextInFlow(element, area)
    : previousInFlow(element, area);
  const before = beyond == null ? null : placeOf(beyond, rtl);
  const size = `${extent}px`;
  element.style.setProperty(`${axis}-size`, size, 'important');
  element.style.setProperty(`min-${axis}-size`, size, 'important');
  element.style.setProperty(`max-${axis}-size`, size, 'important');
  element.style.setProperty('flex-basis', 'auto', 'important');
  element.style.setProperty('flex-grow', '0', 'important');
  element.style.setProperty('flex-shrink', '0', 'important');
  for (const [property, value] of insideProperties) {
    if (value !== '') {
      element.style.setProperty(property, value, 'important');
    }
  }
  element.style.setProperty(margin, `${keep - extent}px`, 'important');
  if (beyond != null && before != null) {
    // One correction from the measured result (a gap, the element's own
    // margin), then everything beyond the edge must be where it was.
    const landed = placeOf(beyond, rtl);
    const scale = scaleOf(element, element.getBoundingClientRect());
    const perPx = axis === 'inline' ? scale.x : scale.y;
    const sign = isEnd ? 1 : -1;
    const drift = (landed[axis] - before[axis]) * sign;
    if (Math.abs(drift) > 0.5) {
      element.style.setProperty(
        margin,
        `${keep - extent - drift / perPx}px`,
        'important',
      );
    }
    const settled = placeOf(beyond, rtl);
    if (
      Math.abs(settled.block - before.block) > 1 ||
      Math.abs(settled.inline - before.inline) > 1
    ) {
      restore();
      return null;
    }
  }
  restoreScroll(element, inside);
  return restore;
}

/**
 * Reports a resized element's edge reveal (`spec:AST-105` FR9) with no copy:
 * a resize controller's pane collapsing or opening beside the content it
 * shares a row with (`component:Resizable` FR8, `component:LayoutPanel`
 * FR7). Measure before the change commits and animate after the
 * new size is applied, as `reportLayoutChange` does; the content beside the
 * element glides through that report. A larger extent reveals by `edge` from
 * the extent the element showed. A smaller one conceals: the element is held
 * at the extent it was laid out at, the difference freed by the margin on
 * that edge's side so the content beyond it stays where the new size puts it,
 * and clipped down to its new extent; the hold goes when the motion ends.
 * Its padding, overflow and scroll offset stay as laid out while it is held,
 * so nothing inside it jumps when the new size changes them. The
 * moving edge rides the glide of the content on that side, frame by frame,
 * and a change made while it runs starts from the extent it shows. It slides:
 * nothing fades. Under Reduce Motion with a coarse primary pointer a reveal
 * fades in and a conceal lands at once (`design:reduced-motion` DR2); with a
 * fine one every change lands at once (DR3).
 */
export function reportLayoutEdge(
  handle: AnimatedLayout | null | undefined,
  getElement: () => HTMLElement | null,
  {edge = 'block-end'}: {edge?: LayoutEdge} = {},
): LayoutEdgeReport {
  const report = reportLayoutChange(handle, getElement);
  /**
   * What the element showed, its laid-out extent and its box, before the
   * change.
   */
  let measured: {
    shown: number;
    box: number;
    rect: DOMRect;
    inside: LaidOutInside;
  } | null = null;
  const axis = edge.startsWith('inline') ? 'inline' : 'block';
  const release = (element: HTMLElement | null) => {
    if (element == null) {
      return;
    }
    resizeReveals.get(element)?.release();
  };
  return {
    measureBefore() {
      const element = getElement();
      measured = null;
      if (element != null) {
        beginChange(element.ownerDocument);
        const running = resizeReveals.get(element);
        const elapsed = Number(running?.animation?.currentTime);
        const rect = element.getBoundingClientRect();
        // A running conceal holds the inside as it was laid out.
        const inside = insideOf(element, axis);
        measured =
          running == null
            ? {
                shown: extentOf(element, edge),
                box: extentOf(element, edge),
                rect,
                inside,
              }
            : {
                shown: running.shownAt(
                  Number.isFinite(elapsed) ? Math.max(0, elapsed) : 0,
                ),
                box: running.box,
                rect,
                inside,
              };
        running?.release();
      }
      report.measureBefore();
    },
    animate() {
      report.animate();
      const element = getElement();
      const before = measured;
      measured = null;
      if (handle == null || element == null || before == null) {
        return;
      }
      // A conceal released to reverse can drop the scroll offset.
      restoreScroll(element, before.inside);
      const area = areaOf(handle, element);
      if (area == null) {
        return;
      }
      const after = extentOf(element, edge);
      if (Math.abs(after - before.shown) < 0.5) {
        return;
      }
      // In the area's visible part before or after: a pane collapsing to
      // nothing has no box after.
      const visible = visibleRect(area);
      if (
        !intersects(element.getBoundingClientRect(), visible) &&
        !intersects(before.rect, visible)
      ) {
        return;
      }
      const motion = layoutMotion(area);
      if (motion.kind === 'instant') {
        return;
      }
      const isConceal = after < before.shown;
      const change = changeStartIn(area, element.ownerDocument);
      if (motion.kind === 'fade') {
        if (!isConceal) {
          safeAnimate(
            element,
            [{opacity: 0}, {opacity: 1}],
            {duration: motion.durationMs, easing: motion.easing},
            change,
          );
        }
        return;
      }
      const {progress} = motion;
      const rtl = edge.startsWith('inline') && isRtl(element);
      // The box the clip works in: the new one for a reveal; for a conceal,
      // the one it was laid out at, held while it runs.
      const box = isConceal ? Math.max(before.box, before.shown) : after;
      const restore = isConceal
        ? holdExtent(element, area, edge, box, after, before.inside)
        : () => {};
      if (restore == null) {
        return;
      }
      // Hidden at the start and at the end, in the box's own px.
      const from = box - before.shown;
      const to = box - after;
      const curve = (t: number) => to + (from - to) * progress.remaining(t);
      const animation = safeAnimate(
        element,
        sampleOver(progress.durationMs, t => ({
          clipPath: pxClip(edge, curve(t), rtl),
        })),
        {duration: progress.durationMs, easing: 'linear'},
        change,
      );
      const reveal: ResizeReveal = {
        animation,
        shownAt: t => box - curve(t),
        box,
        release: () => {
          if (resizeReveals.get(element) !== reveal) {
            return;
          }
          resizeReveals.delete(element);
          animation?.cancel();
          restore();
        },
      };
      if (animation == null) {
        restore();
        return;
      }
      resizeReveals.set(element, reveal);
      animation.addEventListener?.('finish', reveal.release);
      rideNeighbour(
        element,
        area,
        edge,
        rtl,
        animation,
        () => resizeReveals.get(element) === reveal,
        // Anywhere in its box: the content beside it may carry a running
        // motion past where this one starts or ends, and the edge follows.
        towards =>
          Math.min(box, Math.max(0, isConceal ? to - towards : -towards)),
        hidden => ({clipPath: pxClip(edge, hidden, rtl)}),
        hiddenAt => {
          reveal.shownAt = t => box - hiddenAt(t);
        },
      );
    },
    cancel() {
      measured = null;
      release(getElement());
    },
  };
}

/**
 * A disclosure's indicator (its chevron) turns on the same motion as the
 * glide. Its CSS transition takes the theme's move curve and duration as the
 * glide reads them where the area is, and is immediate under Reduce Motion.
 * Without a handle the inline values are cleared, so the component's own
 * transition applies.
 */
export function applyLayoutChangeTransition(
  handle: AnimatedLayout | null | undefined,
  element: HTMLElement | SVGElement | null,
): void {
  if (element == null) {
    return;
  }
  const area = handle == null ? null : areaOf(handle, element);
  if (area == null) {
    transitionSettles.get(element)?.();
    element.style.removeProperty('transition-duration');
    element.style.removeProperty('transition-timing-function');
    return;
  }
  const motion = layoutMotion(area);
  if (motion.kind !== 'glide') {
    transitionSettles.get(element)?.();
    element.style.setProperty('transition-duration', '0s');
    element.style.removeProperty('transition-timing-function');
    return;
  }
  // Values, not the tokens: a theme scope between the area and the indicator
  // would retime a token that the indicator reads where it is.
  const ms = Math.round(motion.progress.durationMs * 1000) / 1000;
  element.style.setProperty('transition-duration', `${ms}ms`);
  element.style.setProperty(
    'transition-timing-function',
    motion.progress.easing,
  );
  settleTransition(element, motion.progress);
}

/**
 * Lands `element`'s running glide at once: it takes its layout place, and a
 * later change starts from there (a change its caller lands rather than
 * animates, such as a rail that snaps).
 */
export function landLayoutGlide(element: Element): void {
  const glide = glides.get(element);
  if (glide != null) {
    glides.delete(element);
    glide.animation.cancel();
  }
}

/**
 * Lands the sideways part of `element`'s running glide at once and keeps its
 * vertical move. It changes the glide's frames, and what a later change
 * carries from it, together. It is for an adopter that moves the element's
 * own sideways translation onto its children between the two reads. A list
 * row that a swipe left open is one.
 */
export function landLayoutGlideSideways(element: Element): void {
  const glide = glides.get(element);
  const effect = glide?.animation.effect as KeyframeEffect | null | undefined;
  if (
    glide == null ||
    effect == null ||
    typeof effect.setKeyframes !== 'function'
  ) {
    return;
  }
  effect.setKeyframes(
    effect.getKeyframes().map(({computedOffset: _, translate, ...frame}) => {
      const [, y = '0px'] = String(translate ?? '').split(/\s+/);
      return {...frame, translate: `0px ${y}`};
    }),
  );
  const vertical: Glide = {
    animation: glide.animation,
    offsetAt: t => ({x: 0, y: glide.offsetAt(t).y}),
    get durationMs() {
      return glide.durationMs;
    },
    shownBefore: {x: 0, y: glide.shownBefore.y},
    scale: glide.scale,
  };
  glides.set(element, vertical);
  glide.animation.addEventListener?.('finish', () => {
    if (glides.get(element) === vertical) {
      glides.delete(element);
    }
  });
}

/**
 * @internal The motion a change in `area` plays, for tests and for SideNav's
 * rail motion, which plays on the same clock (`component:SideNav` FR6).
 */
export function layoutMotionFor(area: Element): LayoutMotion {
  return layoutMotion(area);
}