@astryxdesign/core 0.7.8 → 0.7.9-canary.3b44b43

package/src/hooks/useMenuPress.ts

@@ -6,7 +6,8 @@
  * @file useMenuPress.ts
  * @input The menu root, its trigger, the enabled-row selector, and callbacks
  *   for opening, highlighting, activating and dismissing
- * @output useMenuPress, the marker attributes, and the activation mark
+ * @output useMenuPress, the marker attributes, the activation mark, and the
+ *   internal useDropdownMenuPress entry with its touch model
  * @position Core hook for DropdownMenu, ContextMenu, DropdownMenuSubMenu,
  *   Selector and MenuBottomSheetActionList. The transition table lives in
  *   menuPressGesture.ts.
@@ -29,10 +30,10 @@ import {
 import {currentGesture} from '../Layer/gestureCounter';
 import {
   IDLE_MENU_PRESS,
-  menuPressStep,
-  type MenuPressEffect,
-  type MenuPressEvent,
-  type MenuPressGesture,
+  menuPressTransition,
+  type MenuPressOutcome,
+  type MenuPressInput,
+  type MenuPressState,
   type MenuPressPointerType,
 } from './menuPressGesture';
 import {MENU_PRESS_MARKER} from './menuPressMarker';
@@ -45,6 +46,12 @@ import {edgeAutoscroll} from '../utils/edgeAutoscroll';
 import {focusForLastInput} from '../utils/focusReturn';
 import {useInteractionModalityTrackingFor} from '../utils/interactionModality';
 import {LONG_PRESS_DURATION_MS} from '../motion/uikit/longPress';
+import {
+  clearMenuPressLit,
+  holdMenuPressPaint,
+  markMenuPressLit,
+  releaseMenuPressPaint,
+} from '../privateAttributes/menuPressLit.stylex';
 import {
   __resetClickGuardForTest,
   armClickGuard,
@@ -235,6 +242,44 @@ interface ResolvedPoint {
   isOnTrigger: boolean;
 }
 
+/**
+ * DropdownMenu's options for the press model: everything the public hook
+ * takes, plus its touch model. DropdownMenu reaches the touch model through
+ * its `presentation`, so the public hook has no such option.
+ *
+ * @internal
+ */
+export interface DropdownMenuPressOptions extends UseMenuPressOptions {
+  /**
+   * How the finger that opened the menu from the trigger picks.
+   * `'pointer'`: its opening press follows the settle rule. `'uikit'`: it
+   * picks only after UIMenu's handoff distance, so the row that appeared
+   * under it never acts on a still lift. A mouse is unaffected.
+   * @default 'pointer'
+   */
+  touchModel?: 'pointer' | 'uikit';
+}
+
+/**
+ * What core's own menus get from {@link useDropdownMenuPress}: the public
+ * return. Not exported from the hooks entry point.
+ *
+ * @internal
+ */
+export type DropdownMenuPressReturn = UseMenuPressReturn;
+
+/**
+ * Where a pointer is, for a finger's handoff distance. Positions reach the
+ * machine only under `touchModel: 'uikit'`. Without them, it keeps the settle
+ * rule.
+ */
+function handoffPosition(
+  event: PointerEvent,
+  hasHandoff: boolean,
+): {x?: number; y?: number} {
+  return hasHandoff ? {x: event.clientX, y: event.clientY} : {};
+}
+
 /**
  * The press model for a menu: the row under the release acts, the highlight
  * follows a held pointer, and a mouse opens the menu on press.
@@ -271,13 +316,30 @@ interface ResolvedPoint {
  * ```
  */
 export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
+  // The touch model is DropdownMenu's alone; an untyped caller's
+  // `touchModel` does not reach the model.
+  const {touchModel: _touchModel, ...publicOptions} =
+    options as DropdownMenuPressOptions;
+  return useDropdownMenuPress({...publicOptions, touchModel: 'pointer'});
+}
+
+/**
+ * The press model with DropdownMenu's touch model
+ * ({@link DropdownMenuPressOptions.touchModel}). Not exported from the hooks
+ * entry point.
+ *
+ * @internal
+ */
+export function useDropdownMenuPress(
+  options: DropdownMenuPressOptions,
+): DropdownMenuPressReturn {
   const optionsRef = useRef(options);
   optionsRef.current = options;
   // The highlight, and the hover focus of the rows in this menu, follow the
   // last input, which this tracks for the menu's own document.
   useInteractionModalityTrackingFor(options.menuRef);
 
-  const gestureRef = useRef<MenuPressGesture<HTMLElement>>(IDLE_MENU_PRESS);
+  const gestureRef = useRef<MenuPressState<HTMLElement>>(IDLE_MENU_PRESS);
   const pointerIdRef = useRef<number | null>(null);
   const detachRef = useRef<(() => void) | null>(null);
   // `useLongPress` detects the held finger, as in ContextMenu, so the hold
@@ -374,8 +436,18 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
     autoscrollRef.current = null;
   }, [autoscroll]);
 
+  const litRowRef = useRef<HTMLElement | null>(null);
+  const heldMenuRef = useRef<HTMLElement | null>(null);
   const endGesture = useCallback(() => {
     longPressApiRef.current?.cancel();
+    if (litRowRef.current != null) {
+      clearMenuPressLit(litRowRef.current);
+      litRowRef.current = null;
+    }
+    if (heldMenuRef.current != null) {
+      releaseMenuPressPaint(heldMenuRef.current);
+      heldMenuRef.current = null;
+    }
     touchMovePreventerRef.current?.();
     touchMovePreventerRef.current = null;
     stopAutoscroll();
@@ -388,7 +460,34 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
 
   const highlight = useCallback(
     (row: HTMLElement | null) => {
+      // A held finger or pen marks the row it lights, for the row's pressed
+      // paint. A held mouse keeps the hover tint, as on a desktop.
+      const gesture = gestureRef.current;
+      const isHeld =
+        gesture.phase !== 'idle' && gesture.pointerType !== 'mouse';
+      const lit = isHeld ? row : null;
+      if (litRowRef.current !== lit) {
+        if (litRowRef.current != null) {
+          clearMenuPressLit(litRowRef.current);
+        }
+        litRowRef.current = lit;
+        if (lit != null) {
+          markMenuPressLit(lit);
+        }
+      }
       const {onHighlight, menuRef} = optionsRef.current;
+      // The row the press began on stays :active where a pointer hovers, so
+      // the menu holds every row but the lit one off that paint.
+      const held = isHeld ? menuRef.current : null;
+      if (heldMenuRef.current !== held) {
+        if (heldMenuRef.current != null) {
+          releaseMenuPressPaint(heldMenuRef.current);
+        }
+        heldMenuRef.current = held;
+        if (held != null) {
+          holdMenuPressPaint(held);
+        }
+      }
       if (onHighlight != null) {
         onHighlight(row);
         return;
@@ -449,13 +548,13 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
 
   // Declared before `step` so the mutual recursion through refs type-checks.
   const stepRef = useRef<
-    (event: MenuPressEvent<HTMLElement>, native?: PointerEvent) => void
+    (event: MenuPressInput<HTMLElement>, native?: PointerEvent) => void
   >(() => {});
 
   const applyEffect = useCallback(
     (
-      effect: MenuPressEffect<HTMLElement>,
-      gesture: MenuPressGesture<HTMLElement>,
+      effect: MenuPressOutcome<HTMLElement>,
+      gesture: MenuPressState<HTMLElement>,
       native: PointerEvent | undefined,
     ) => {
       const doc = getDocument();
@@ -511,8 +610,8 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
   );
 
   const step = useCallback(
-    (event: MenuPressEvent<HTMLElement>, native?: PointerEvent) => {
-      const result = menuPressStep(gestureRef.current, event);
+    (event: MenuPressInput<HTMLElement>, native?: PointerEvent) => {
+      const result = menuPressTransition(gestureRef.current, event);
       gestureRef.current = result.gesture;
       applyEffect(result.effect, result.gesture, native);
     },
@@ -619,6 +718,10 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
             row: point.row,
             isInMenu: point.isInMenu,
             time: Date.now(),
+            ...handoffPosition(
+              event,
+              optionsRef.current.touchModel === 'uikit',
+            ),
           },
           event,
         );
@@ -636,6 +739,10 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
             isInMenu: point.isInMenu,
             isOnTrigger: point.isOnTrigger,
             time: Date.now(),
+            ...handoffPosition(
+              event,
+              optionsRef.current.touchModel === 'uikit',
+            ),
           },
           event,
         );

package/src/hooks/usePressFeedback.doc.mjs

@@ -20,12 +20,12 @@ export const docs = {
       name: 'pressableProps',
       type: "{'data-astryx-pressable': ''}",
       description:
-        "The marker attribute to spread on the element that paints the press. Compose one of `interactionOverlayStyles` (from `@astryxdesign/core/utils`) on the same element — `backgroundColor` or `backgroundImage` for a surface whose hover and press are the system's overlays, `pressedBackgroundColor` for one whose hover is its own — and it paints the pressed token at the press's strength on the first frame of a believed press and fades it over the release, keeping `:active` for a mouse on a desktop. On a phone or tablet, where the stylesheet drops `:active`, the controller also paints a mouse, trackpad or Space-key press: at once, held while the button or key is down, faded at the release. A press is themed through `--color-overlay-pressed`.",
+        "The marker attribute to spread on the element that paints the press. Compose one of `interactionOverlayStyles` (from `@astryxdesign/core/utils`) on the same element — `backgroundColor` or `backgroundImage` for a surface whose hover and press are the system's overlays, `pressedBackgroundColor` for one whose hover is its own — and it paints the pressed token on the first frame of a press and fades it over the release, keeping `:active` for a mouse on a desktop. On a phone or tablet, where the stylesheet drops `:active`, the controller also paints a mouse, trackpad or Space-key press: at once, held while the button or key is down, faded at the release. A press is themed through `--color-overlay-pressed`.",
     },
   ],
   usage: {
     description:
-      'The touch press model every Astryx pressable uses, for a local component that paints its own press. Under a finger, CSS `:active` paints on the touch itself and can outlive the start of a scroll; the press model instead waits 150 ms before believing a press, cancels it the moment the finger travels 10 px or a scroll claims the gesture, never brings it back inside that gesture, answers a quick tap at the lift, and fades the release over 200 ms — the clocks a native list uses. One document-level controller does this for every marked element (installed by the first pressable to mount, removed by the last to unmount), so calling the hook adds no listener or state to your element. On a desktop a mouse press is still your `:active` rule: keep it, and drop it under `@media (pointer: coarse)` the way the built-in components do. That query reads the primary pointer, so on a phone or tablet it also drops `:active` for a connected mouse, trackpad or keyboard; the controller paints those presses there (at once, faded at the release), so nothing goes unanswered.',
+      'The touch press model every Astryx pressable uses, for a local component that paints its own press. Under a finger, CSS `:active` paints on the touch itself and can outlive the start of a scroll; the press model instead tracks the touch the way UIKit tracks a control: it highlights as the finger lands (after the content-touch delay inside a scroller, where a flick paints nothing), a quick tap answers at the lift, and a scroll that takes the touch cancels it with no fade. One document-level controller does this for every marked element (installed by the first pressable to mount, removed by the last to unmount), so calling the hook adds no listener or state to your element. On a desktop a mouse press is still your `:active` rule: keep it, and drop it under `@media (pointer: coarse)` the way the built-in components do. That query reads the primary pointer, so on a phone or tablet it also drops `:active` for a connected mouse, trackpad or keyboard; the controller paints those presses there (at once, faded at the release), so nothing goes unanswered.',
     bestPractices: [
       {
         guidance: true,
@@ -58,7 +58,7 @@ export const docs = {
 /** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
-    'Marks an element as a pressable surface of the touch press model (150 ms onset, 10 px slop, cancel on scroll, tap answers at lift, 200 ms fade) and installs the shared document controller; on a coarse primary pointer it also paints mouse, trackpad and Space-key presses at once. Returns the data-astryx-pressable marker to spread; compose one of interactionOverlayStyles on the same element to paint.',
+    'Marks an element as a pressable surface of the touch press model, tracked like a UIKit control (highlight as the finger lands, 150 ms inside a scroller, fade at the lift), and installs the shared document controller; on a coarse primary pointer it also paints mouse, trackpad and Space-key presses at once. Returns the data-astryx-pressable marker to spread; compose one of interactionOverlayStyles on the same element to paint.',
   paramDescriptions: {},
   returnDescriptions: {
     pressableProps:

package/src/hooks/usePressFeedback.ts

@@ -26,11 +26,11 @@ import {installPressFeedback, pressableProps} from '../utils/pressFeedback';
  * `interactionOverlayStyles` (from `@astryxdesign/core/utils`) on the same
  * element: `backgroundColor` or `backgroundImage` for a surface whose hover
  * and press are the system's overlays, `pressedBackgroundColor` for one
- * whose hover is its own. The controller writes its attribute on the element
- * while a touch press is believed (after the onset delay, cancelled by travel
- * or by a scroll) and for the release, and the composed style paints the
- * pressed token at the press's strength on the first frame and fades it over
- * the release, keeping `:active` for a mouse on a desktop. On a phone or
+ * whose hover is its own. Under a finger the controller tracks the press the
+ * way UIKit tracks a control and writes its
+ * attribute on the element while the press is held and for the release; the
+ * composed style paints the pressed token on the first frame and fades it
+ * over the release, keeping `:active` for a mouse on a desktop. On a phone or
  * tablet the stylesheet drops `:active` for every press, so the controller
  * also paints a mouse, trackpad or Space-key press there, at once. A press is
  * themed through `--color-overlay-pressed`, which the hold, the flash and the
@@ -46,7 +46,7 @@ import {installPressFeedback, pressableProps} from '../utils/pressFeedback';
  * @example
  * ```
  * const pressable = usePressFeedback();
- * return <div role="button" {...pressable} {...stylex.props(styles.row)} />;
+ * return <button {...pressable} {...stylex.props(styles.button)} />;
  * ```
  */
 export function usePressFeedback(): typeof pressableProps {

package/src/motion/MEASUREMENTS.md

@@ -314,3 +314,14 @@ scroll view coasts with 0.25 × the pan's velocity plus 0.75 × its value one
 event earlier (four HID releases; `velocity.scrollReleaseWeight`, which a
 pan's `scrollVelocity()` reads). On UIKit, Reduce Motion with Prefer Cross-Fade changes
 nothing on a picker; the Wheel follows design:reduced-motion instead.
+
+## Menus (UIMenu)
+
+Probe: the UIKit lab host app with a UIButton whose `UIMenu` is its primary
+action (`showsMenuAsPrimaryAction`), three to twelve items, on a plain view
+and inside a UIScrollView; the gesture-state, presentation-modifier,
+display-link and feedback hooks; real HID touches.
+
+| ID    | Scene                  | Gesture                                                                                                                                                 | Extract                                                                                                                                 | Method |
+| ----- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------ |
+| M-MN2 | button on a plain view | hold until the menu is open, then lift still; move 8 pt down, 8 pt right, 12 pt down, (7, 7), (8, 8) and lift; move 6 pt before the open and 6 pt after | row picked or not; handoff and list-selection recognizer states; highlighted row per frame: threshold, metric, where it is counted from | C      |

package/src/motion/carryAnimations.ts

@@ -0,0 +1,389 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file carryAnimations.ts
+ * @input The CSS animations and transitions of an element and its subtree,
+ *   read before the browser starts them afresh
+ * @output Exports `saveAnimations` and `carryAnimations`, which carry them on
+ *   in a clone of the element. Also `saveAnimation` and `restoreAnimations`,
+ *   which put them back after a display reset
+ * @position Motion foundation; the transient copy (transientCopy.ts) and the
+ *   layer runtime's re-placement (Layer/preserveAnimations.ts) use it
+ */
+
+/**
+ * Animation members written in a fixed order rather than generically: the
+ * timeline before the range that is measured on it, the rate before the
+ * time, and the start time (or, for a paused animation, the current time)
+ * last, once the play state is set. `effect` is not
+ * replaced, because a CSS animation whose effect script replaces leaves the
+ * stylesheet's control; its state is copied onto the new effect instead.
+ */
+const ORDERED = new Set([
+  'effect',
+  'timeline',
+  'rangeStart',
+  'rangeEnd',
+  'playbackRate',
+  'startTime',
+  'currentTime',
+]);
+
+type Writable = Record<string, unknown>;
+
+/** Every accessor with a setter on `object`'s prototype chain. */
+function writableAccessors(object: object): string[] {
+  const names = new Set<string>();
+  for (
+    let proto: object | null = Object.getPrototypeOf(object);
+    proto != null && proto !== Object.prototype;
+    proto = Object.getPrototypeOf(proto)
+  ) {
+    for (const [name, descriptor] of Object.entries(
+      Object.getOwnPropertyDescriptors(proto),
+    )) {
+      if (descriptor.set != null) {
+        names.add(name);
+      }
+    }
+  }
+  return [...names];
+}
+
+/**
+ * A textual form of a value that is compared by content rather than by
+ * identity: a CSS numeric value (as in a timeline range offset) through its
+ * serialization, a plain object (a range) through its members. Anything else
+ * is compared by identity (`null`).
+ */
+function contentOf(value: unknown): string | null {
+  if (
+    typeof CSSNumericValue !== 'undefined' &&
+    value instanceof CSSNumericValue
+  ) {
+    return value.toString();
+  }
+  if (
+    value != null &&
+    typeof value === 'object' &&
+    Object.getPrototypeOf(value) === Object.prototype
+  ) {
+    return Object.entries(value)
+      .map(([key, inner]) => `${key}:${contentOf(inner) ?? String(inner)}`)
+      .join(';');
+  }
+  return null;
+}
+
+function differs(a: unknown, b: unknown): boolean {
+  if (a === b) {
+    return false;
+  }
+  const textA = contentOf(a);
+  return textA == null || textA !== contentOf(b);
+}
+
+/** One animation's state, read before the browser starts it afresh. */
+export interface SavedAnimation {
+  animation: Animation;
+  name: string;
+  target: Element | null;
+  pseudoElement: string | null;
+  values: Writable;
+  effectValues: Writable;
+  timing: EffectTiming | null;
+  keyframes: ComputedKeyframe[] | null;
+  playState: AnimationPlayState;
+  replaceState: AnimationReplaceState;
+}
+
+/**
+ * Reads one animation's state generically, from what the platform exposes.
+ * That is every accessor with a setter on the animation's and its effect's
+ * prototype chains, every field of the effect's timing, and its keyframes. Only values
+ * that differ from the recreated animation's are written back, so a value the
+ * stylesheet controls stays under its control. A few members are not plain
+ * state and are written in their own step (`ORDERED`). The Animation and
+ * effect objects themselves cannot be carried over: the old ones keep their
+ * listeners and promises.
+ */
+export function saveAnimation(animation: Animation): SavedAnimation {
+  const effect = animation.effect as KeyframeEffect | null;
+  const values: Writable = {};
+  for (const name of writableAccessors(animation)) {
+    values[name] = (animation as unknown as Writable)[name];
+  }
+  const effectValues: Writable = {};
+  if (effect != null) {
+    for (const name of writableAccessors(effect)) {
+      effectValues[name] = (effect as unknown as Writable)[name];
+    }
+  }
+  return {
+    animation,
+    name:
+      (animation as Animation & {animationName?: string}).animationName ?? '',
+    target: effect?.target ?? null,
+    pseudoElement: effect?.pseudoElement ?? null,
+    values,
+    effectValues,
+    timing: effect?.getTiming() ?? null,
+    keyframes: effect?.getKeyframes() ?? null,
+    playState: animation.playState,
+    replaceState: animation.replaceState,
+  };
+}
+
+function write(object: object, name: string, value: unknown): void {
+  (object as Writable)[name] = value;
+}
+
+/** Give `next` the effect state `saved` had: every writable member. */
+function restoreEffect(next: KeyframeEffect, saved: SavedAnimation): void {
+  for (const name of writableAccessors(next)) {
+    if (
+      name in saved.effectValues &&
+      differs(saved.effectValues[name], (next as unknown as Writable)[name])
+    ) {
+      write(next, name, saved.effectValues[name]);
+    }
+  }
+  if (saved.timing != null) {
+    const timing = next.getTiming() as unknown as Writable;
+    const changed: Writable = {};
+    for (const [field, value] of Object.entries(saved.timing)) {
+      if (differs(value, timing[field])) {
+        changed[field] = value;
+      }
+    }
+    if (Object.keys(changed).length > 0) {
+      next.updateTiming(changed);
+    }
+  }
+  if (
+    saved.keyframes != null &&
+    JSON.stringify(saved.keyframes) !== JSON.stringify(next.getKeyframes())
+  ) {
+    next.setKeyframes(saved.keyframes);
+  }
+}
+
+/** Give `next` the state `saved` had, member by member. */
+function restore(next: Animation, saved: SavedAnimation): void {
+  const effect = next.effect as KeyframeEffect | null;
+  if (effect != null) {
+    restoreEffect(effect, saved);
+  }
+  const current = next as unknown as Writable;
+  for (const name of ['timeline', 'rangeStart', 'rangeEnd']) {
+    if (name in saved.values && differs(saved.values[name], current[name])) {
+      write(next, name, saved.values[name]);
+    }
+  }
+  for (const name of writableAccessors(next)) {
+    if (
+      !ORDERED.has(name) &&
+      name in saved.values &&
+      differs(saved.values[name], current[name])
+    ) {
+      write(next, name, saved.values[name]);
+    }
+  }
+  if (saved.replaceState === 'persisted' && next.replaceState !== 'persisted') {
+    next.persist();
+  }
+  const rate = saved.values.playbackRate;
+  if (typeof rate === 'number' && rate !== next.playbackRate) {
+    next.playbackRate = rate;
+  }
+  if (saved.playState === 'paused' && next.playState !== 'paused') {
+    next.pause();
+  } else if (saved.playState !== 'paused' && next.playState === 'paused') {
+    next.play();
+  }
+  // A running animation is anchored to its timeline by its start time, which
+  // carries its current time on exactly. A paused one has none and keeps its
+  // current time. A finished one holds its end: finishing it again holds the
+  // same time, though its start time is then counted from now, since script
+  // cannot set a start time and a held time together.
+  const start = saved.values.startTime as CSSNumberish | null | undefined;
+  const time = saved.values.currentTime as CSSNumberish | null | undefined;
+  if (saved.playState === 'finished') {
+    next.finish();
+  } else if (start != null) {
+    next.startTime = start;
+  } else if (time != null) {
+    next.currentTime = time;
+  }
+}
+
+/** Resume a cancelled CSS transition with a script animation in its state. */
+function resumeTransition(saved: SavedAnimation): void {
+  if (saved.target == null || saved.keyframes == null) {
+    return;
+  }
+  const replacement = saved.target.animate(saved.keyframes, {
+    pseudoElement: saved.pseudoElement ?? undefined,
+  });
+  restore(replacement, saved);
+}
+
+function isTransition(animation: Animation): boolean {
+  return (
+    typeof CSSTransition !== 'undefined' && animation instanceof CSSTransition
+  );
+}
+
+function isCssAnimation(animation: Animation): animation is CSSAnimation {
+  return (
+    typeof CSSAnimation !== 'undefined' && animation instanceof CSSAnimation
+  );
+}
+
+/**
+ * Finishes an animation that ends: an infinite one cannot be finished, and is
+ * left as it runs.
+ */
+function finishIfItEnds(animation: Animation): void {
+  const end = animation.effect?.getComputedTiming().endTime;
+  if (
+    end != null &&
+    Number.isFinite(Number(end)) &&
+    animation.playbackRate !== 0
+  ) {
+    animation.finish();
+  }
+}
+
+/** The members a copy's animation does not take: its element's keep them. */
+const IDENTITY_MEMBERS = new Set(['id', 'onfinish', 'oncancel', 'onremove']);
+
+/**
+ * `saved` for an animation that carries on on the copy of its element:
+ * aimed at the copy, without the element's id and event handlers.
+ */
+function retarget(
+  saved: SavedAnimation,
+  copyOf: (element: Element) => Element | null,
+): SavedAnimation | null {
+  const target = saved.target == null ? null : copyOf(saved.target);
+  if (target == null) {
+    return null;
+  }
+  const values: Writable = Object.fromEntries(
+    Object.entries(saved.values).filter(
+      ([name]) => !IDENTITY_MEMBERS.has(name),
+    ),
+  );
+  const effectValues: Writable = {...saved.effectValues};
+  if ('target' in effectValues) {
+    effectValues.target = target;
+  }
+  return {...saved, target, values, effectValues};
+}
+
+/**
+ * Puts each state `saved` holds on the CSS animations and transitions of
+ * `root` and its subtree that are not among `survivors`. Each CSS animation
+ * the browser started afresh takes the state of the one it replaces. It is
+ * matched by element, pseudo-element and name, in order, and then by name
+ * alone (an effect script moved to another element or pseudo-element). Each
+ * transition whose animation no longer runs resumes as a script animation in
+ * its state. One started afresh that replaces none is finished: an entrance
+ * that had played and been dropped, or a transition from `@starting-style`.
+ * Script animations are left as they are.
+ */
+export function restoreAnimations(
+  root: Element,
+  saved: ReadonlyArray<SavedAnimation>,
+  survivors: ReadonlySet<Animation>,
+): void {
+  const after = root.getAnimations({subtree: true});
+  const current = new Set(after);
+  const cancelled: SavedAnimation[] = [];
+  for (const state of saved) {
+    if (current.has(state.animation)) {
+      continue;
+    }
+    if (isTransition(state.animation)) {
+      resumeTransition(state);
+    } else {
+      cancelled.push(state);
+    }
+  }
+  const recreated = after.filter(
+    animation =>
+      (isCssAnimation(animation) || isTransition(animation)) &&
+      !survivors.has(animation),
+  );
+  const unmatched: Animation[] = [];
+  for (const animation of recreated) {
+    const effect = animation.effect as KeyframeEffect | null;
+    const name =
+      (animation as Animation & {animationName?: string}).animationName ?? '';
+    const index = cancelled.findIndex(
+      state =>
+        state.name === name &&
+        state.target === (effect?.target ?? null) &&
+        state.pseudoElement === (effect?.pseudoElement ?? null),
+    );
+    if (index === -1) {
+      unmatched.push(animation);
+    } else {
+      restore(animation, cancelled.splice(index, 1)[0]);
+    }
+  }
+  for (const animation of unmatched) {
+    const name =
+      (animation as Animation & {animationName?: string}).animationName ?? '';
+    const index = cancelled.findIndex(state => state.name === name);
+    if (index === -1) {
+      finishIfItEnds(animation);
+    } else {
+      restore(animation, cancelled.splice(index, 1)[0]);
+    }
+  }
+}
+
+/** The CSS animations and transitions `saveAnimations` read. */
+export type SavedAnimations = ReadonlyArray<SavedAnimation>;
+
+/**
+ * Reads the state of every CSS animation and transition of `root` and its
+ * subtree, for `carryAnimations` to give a copy of it.
+ */
+export function saveAnimations(root: Element): SavedAnimations {
+  if (typeof root.getAnimations !== 'function') {
+    return [];
+  }
+  return root
+    .getAnimations({subtree: true})
+    .filter(animation => isCssAnimation(animation) || isTransition(animation))
+    .map(saveAnimation);
+}
+
+/**
+ * Carries on in `copy`, a clone of the root `saved` was read from, now laid
+ * out, the CSS animations and transitions its element ran. A clone starts
+ * each CSS animation again and runs no transition but a `@starting-style`
+ * one. So each CSS animation the clone started takes the state of its
+ * element's, and each transition runs on as a script animation. One the
+ * clone started that its element no longer ran is finished: an entrance that
+ * had played, or a `@starting-style` transition. `copyOf` maps each element
+ * of the cloned subtree to its copy. The element's own animations keep
+ * running, so the copy's take no id or event handler.
+ */
+export function carryAnimations(
+  saved: SavedAnimations,
+  copy: Element,
+  copyOf: (element: Element) => Element | null,
+): void {
+  if (typeof copy.getAnimations !== 'function') {
+    return;
+  }
+  restoreAnimations(
+    copy,
+    saved.flatMap(state => retarget(state, copyOf) ?? []),
+    new Set(),
+  );
+}