@cardstack/boxel-cli 0.12.0 → 0.13.0-unstable.1

package/bundled-types/glimmer-motion/presence-types.ts

@@ -1,12 +1,20 @@
 import type { PresenceContextProps } from 'motion-dom';
 
+import type { MotionEl, MotionProps, PopSeat } from './node.ts';
+
 /**
- * A direct child of a popLayout <Presence>, which has to be measured before
- * the render that removes it. React's PopChildMeasure does this in
- * getSnapshotBeforeUpdate; see MotionNode.measureForPop.
+ * A direct child of a <Presence>, which has to be read before the render
+ * that removes it: popLayout measures its seat (React's PopChildMeasure does
+ * this in getSnapshotBeforeUpdate; see MotionNode.measureForPop), and
+ * snapshot copies it (see MotionNode.exitForCopy), pinning the copy to the
+ * seat recorded before that render (see MotionNode.recordSeat).
  */
 export interface PopMeasurable {
+  exitForCopy():
+    | { element: MotionEl; props: MotionProps; seat: PopSeat | undefined }
+    | undefined;
   measureForPop(): void;
+  recordSeat(): Element[];
 }
 
 /** what one item inside <Presence> hands to its {{motion}} element */
@@ -16,8 +24,8 @@ export interface PresenceHandle {
   readonly context: PresenceContextProps;
   readonly isPresent: boolean;
   readonly key: string;
-  readonly mode: 'sync' | 'wait' | 'popLayout';
-  /** popLayout: the direct child asks to be measured while it is still in flow */
+  readonly mode: 'sync' | 'wait' | 'popLayout' | 'snapshot';
+  /** popLayout and snapshot: the direct child asks to be read while it is still in flow */
   popCandidate(node: PopMeasurable): () => void;
   /** motion elements that inherit this presence (React: PresenceContext consumers) ask to be refreshed when it flips */
   subscribe(refresh: () => void): () => void;

package/bundled-types/glimmer-motion/presence.gts

@@ -1,13 +1,15 @@
-import { registerDestructor } from '@ember/destroyable';
+import { isDestroying, registerDestructor } from '@ember/destroyable';
 import type Owner from '@ember/owner';
 import Component from '@glimmer/component';
 import { tracked } from '@glimmer/tracking';
-import type { PresenceContextProps } from 'motion-dom';
+import { consumeTag, VOLATILE_TAG } from '@glimmer/validator';
+import { frame, type PresenceContextProps } from 'motion-dom';
 
 import { snapshotOnRender } from './layout-group.gts';
 import { flushPendingMounts } from './node.ts';
 import type { PopMeasurable, PresenceHandle } from './presence-types.ts';
 import { postRender } from './scheduler.ts';
+import { captureExit, type ExitCopy } from './snapshot.ts';
 
 /**
  * AnimatePresence for Glimmer — the same algorithm as Motion's
@@ -21,6 +23,15 @@ import { postRender } from './scheduler.ts';
  *
  * Motion elements nested deeper inside a child inherit its presence through
  * their parent VisualElement, as React's PresenceContext would provide it.
+ *
+ * `@mode="snapshot"` is this package's own: a leaver's block is torn down in
+ * the render that removes it, and a static copy of the element the handle was
+ * passed to plays that element's exit, lifted out of flow at the seat the last
+ * frame showed the element in. Use it where a leaver's content comes from
+ * state that moves on as it leaves, such as a component's blocks: a live
+ * leaver would re-render from that state, and stay focusable, with its ids
+ * and form controls, beside its replacement. The copy is kept as a memory
+ * (see memory.ts). See snapshot.ts.
  */
 interface Signature<T> {
   Args: {
@@ -30,7 +41,7 @@ interface Signature<T> {
     initial?: boolean;
     items: T[];
     key: (item: T) => string;
-    mode?: 'sync' | 'wait' | 'popLayout';
+    mode?: 'sync' | 'wait' | 'popLayout' | 'snapshot';
     onExitComplete?: () => void;
     parent?: PresenceHandle;
     /** nested presence: exit with the parent handle when it leaves */
@@ -49,7 +60,7 @@ class Entry<T> implements PresenceHandle {
   readonly id = `presence-${presenceId++}`;
   private children = new Map<string | number, boolean>();
   private subscribers = new Set<() => void>();
-  /** popLayout: the direct children, so they can be measured before the DOM changes */
+  /** popLayout and snapshot: the direct children, so they can be read before the DOM changes */
   private popCandidates = new Set<PopMeasurable>();
   subscribe(refresh: () => void) {
     this.subscribers.add(refresh);
@@ -61,6 +72,24 @@ class Entry<T> implements PresenceHandle {
       this.popCandidates.delete(node);
     };
   }
+  /** snapshot: each direct child reads its seat now; returns the elements those seats depend on */
+  recordSeats(): Element[] {
+    const watched: Element[] = [];
+    this.popCandidates.forEach((node) => watched.push(...node.recordSeat()));
+    return watched;
+  }
+  /** snapshot: static copies of the direct children, taken before the render that removes them */
+  copiesForExit(): ExitCopy[] {
+    const copies: ExitCopy[] = [];
+    this.popCandidates.forEach((node) => {
+      const source = node.exitForCopy();
+      const copy = source && captureExit(source);
+      if (copy) {
+        copies.push(copy);
+      }
+    });
+    return copies;
+  }
   readonly key: string;
   private owner: Presence<T>;
   readonly initialBlocked: boolean;
@@ -123,12 +152,16 @@ class Entry<T> implements PresenceHandle {
     if (!present && this.mode === 'popLayout') {
       // React's PopChildMeasure measures in getSnapshotBeforeUpdate — BEFORE
       // the DOM is patched. That timing is the whole of it. This runs from the
-      // diff in `rendered`, which is Glimmer's equivalent slot: the newcomers
-      // for this pass have not been inserted yet, so the leaver's offsetTop is
-      // still the seat it actually occupies.
+      // diff in `rendered`, the nearest slot Glimmer has: this <Presence>'s
+      // newcomers for the pass have not been inserted yet, so the container
+      // they would grow or re-center has not moved. Content earlier in the
+      // template than this <Presence> has already been patched for the pass,
+      // though, and a leaver it moves is measured where it was moved to.
+      // (Snapshot mode pins its copies to a seat recorded before the pass
+      // instead; see `seatWatch`.)
       //
       // Measure it afterwards and you read a layout that already contains the
-      // arrivals: the container has grown, a centred one has re-centred, and
+      // arrivals: the container has grown, a centered one has re-centered, and
       // the leaver gets pinned at a place it never was. On a stage that
       // replays, every generation lands further from home than the last, and
       // what you see is a stack of ghosts drifting away from the newcomers.
@@ -175,11 +208,23 @@ export class Presence<T> extends Component<Signature<T>> {
   private pendingItems: T[] = [];
   private registeredWithParent?: () => void;
   private readonly selfId = `presence:${presenceId++}`;
+  /** snapshot: copies still playing an exit, by the key of the item they copied */
+  private copies = new Map<ExitCopy, string>();
+  /** snapshot: a read of the children's seats is booked for the next frame */
+  private seatReadBooked = false;
+  /** snapshot: re-reads the seats when a child, or the box it is pinned inside, resizes */
+  private resizes?: ResizeObserver;
+  private watched = new Set<Element>();
   @tracked private version = 0;
 
   constructor(owner: Owner, args: Signature<T>['Args']) {
     super(owner, args);
-    registerDestructor(this, () => this.registeredWithParent?.());
+    registerDestructor(this, () => {
+      this.registeredWithParent?.();
+      this.copies.forEach((_, copy) => copy.cut());
+      this.copies.clear();
+      this.stopWatchingSeats();
+    });
   }
 
   get parentPresent() {
@@ -195,6 +240,74 @@ export class Presence<T> extends Component<Signature<T>> {
     return this.presentKeys.includes(key);
   }
 
+  /* eslint-disable ember/no-side-effects -- a render detector (see LayoutGroup): re-evaluated in every
+     render pass, it books a read of the seats the pass leaves the children in */
+  /**
+   * Snapshot: a leaver's copy is pinned to the seat its element last
+   * recorded. Each direct child reads its seat in the frame after every
+   * render, and again whenever it or the box it is pinned inside resizes (see
+   * MotionNode.recordSeat). The diff cannot read it: Glimmer patches the DOM
+   * in template order, so content earlier in the template than this
+   * <Presence> has been patched by the time it diffs, and may have moved or
+   * resized the leaver. A move that is neither a render nor one of those
+   * resizes, such as a transition on a sibling's width, is not seen.
+   */
+  get seatWatch(): undefined {
+    if (this.args.mode !== 'snapshot') {
+      this.stopWatchingSeats();
+      return undefined;
+    }
+    consumeTag(VOLATILE_TAG);
+    if (!this.seatReadBooked) {
+      this.seatReadBooked = true;
+      frame.read(() => {
+        this.seatReadBooked = false;
+        this.readSeats();
+      });
+    }
+    return undefined;
+  }
+  /* eslint-enable ember/no-side-effects */
+
+  /**
+   * Reads every child's seat. After a render it also moves the resize watch
+   * onto the elements those seats depend on now; a read from the watch itself
+   * leaves it alone, since a target observed inside a resize callback can be
+   * left undelivered, which the browser reports as an error.
+   */
+  private readSeats(rewatch = true) {
+    if (isDestroying(this) || this.args.mode !== 'snapshot') {
+      return;
+    }
+    const watched = new Set<Element>();
+    this.entries.forEach((e) =>
+      e.recordSeats().forEach((el) => watched.add(el)),
+    );
+    if (!rewatch) {
+      return;
+    }
+    const resizes = (this.resizes ??= new ResizeObserver(() =>
+      this.readSeats(false),
+    ));
+    this.watched.forEach((el) => {
+      if (!watched.has(el)) {
+        resizes.unobserve(el);
+      }
+    });
+    watched.forEach((el) => {
+      if (!this.watched.has(el)) {
+        resizes.observe(el);
+      }
+    });
+    this.watched = watched;
+  }
+
+  private stopWatchingSeats() {
+    this.resizes?.disconnect();
+    this.resizes = undefined;
+    this.watched.clear();
+  }
+
   /* eslint-disable ember/no-side-effects -- AnimatePresence's diff of present vs rendered children runs
      during render; this getter is that render step (entries, order and exit bookkeeping are its output) */
   get rendered(): Entry<T>[] {
@@ -226,28 +339,50 @@ export class Presence<T> extends Component<Signature<T>> {
       this.pendingItems = items;
       const presentKeys = this.presentKeys;
       const blockInitial = this.firstRender && this.args.initial === false;
+      const snapshot = this.args.mode === 'snapshot';
       items.forEach((item) => {
         const k = this.args.key(item);
         const e = this.entries.get(k);
         if (e) {
           e.item = item;
         } else {
+          // a static copy cannot be retargeted: an item that comes back
+          // replaces the copy of it still leaving
+          this.cutCopies(k);
           this.entries.set(k, new Entry(k, item, this, blockInitial));
         }
       });
       // diff rendered vs present, keeping leavers in their slots (AnimatePresence's splice loop)
       const exitingKeys: string[] = [];
+      const copied: ExitCopy[] = [];
+      let snapshotLeft = false;
       let next = parentPresent ? [...presentKeys] : [];
       let insertionIndex = 0;
       for (const k of this.order) {
         const presentIndex = presentKeys.indexOf(k);
-        if (presentIndex === -1) {
+        if (presentIndex === -1 && snapshot) {
+          // copied now, before this render patches the block, so the copy
+          // shows the last frame's content (and is pinned to the seat
+          // recorded before this render; see `seatWatch`); the block itself
+          // leaves with this render
+          snapshotLeft = true;
+          for (const copy of this.entries.get(k)?.copiesForExit() ?? []) {
+            this.copies.set(copy, k);
+            copied.push(copy);
+          }
+          this.entries.delete(k);
+          this.exitComplete.delete(k);
+          this.exiting.delete(k);
+        } else if (presentIndex === -1) {
           next.splice(insertionIndex++, 0, k);
           exitingKeys.push(k);
         } else {
           insertionIndex = presentIndex + exitingKeys.length + 1;
         }
       }
+      if (snapshotLeft) {
+        postRender(() => this.startCopies(copied));
+      }
       if ((this.args.mode ?? 'sync') === 'wait' && exitingKeys.length) {
         next = exitingKeys;
       }
@@ -270,7 +405,16 @@ export class Presence<T> extends Component<Signature<T>> {
         }
       }
       this.firstRender = false;
-      if (this.args.propagate && !parentPresent && !this.order.length) {
+      // a leaving parent waits on this <Presence>: with nothing left to
+      // render it is done, unless copies are still playing their exits (they
+      // report when they finish; see checkCopiesLeft)
+      if (
+        this.args.propagate &&
+        !parentPresent &&
+        !this.order.length &&
+        !snapshotLeft &&
+        !this.copies.size
+      ) {
         postRender(() => this.safeToRemove());
       }
     }
@@ -318,7 +462,51 @@ export class Presence<T> extends Component<Signature<T>> {
     this.args.parent?.context.onExitComplete?.(this.selfId);
   }
 
+  /** snapshot: after the render that removed their items, the copies go back in and play their exits */
+  private startCopies(copies: ExitCopy[]) {
+    const placement = {
+      anchorX: this.args.anchorX ?? 'left',
+      anchorY: this.args.anchorY ?? 'top',
+      custom: this.args.custom,
+    } as const;
+    for (const copy of copies) {
+      if (this.copies.has(copy)) {
+        copy.start(placement, () => this.copyLeft(copy));
+      }
+    }
+    // each copy reports its own end; a pass that copied nothing reports here
+    if (!copies.length) {
+      this.checkCopiesLeft();
+    }
+  }
+
+  private copyLeft(copy: ExitCopy) {
+    this.copies.delete(copy);
+    this.checkCopiesLeft();
+  }
+
+  /** every copy has finished its exit, and no live leaver is still playing one: report as onExit does */
+  private checkCopiesLeft() {
+    if (this.copies.size || this.exitComplete.size || isDestroying(this)) {
+      return;
+    }
+    if (this.args.propagate) {
+      this.safeToRemove();
+    }
+    this.args.onExitComplete?.();
+  }
+
+  private cutCopies(key: string) {
+    this.copies.forEach((k, copy) => {
+      if (k === key) {
+        this.copies.delete(copy);
+        copy.cut();
+      }
+    });
+  }
+
   <template>
+    {{this.seatWatch}}
     {{#each this.rendered key='key' as |e|}}
       {{yield e.item e}}
     {{/each}}

package/bundled-types/glimmer-motion/snapshot.ts

@@ -0,0 +1,280 @@
+/**
+ * `<Presence @mode="snapshot">`: a leaver's exit played on a static copy of
+ * it that the engine owns, instead of on its live block.
+ *
+ * A Glimmer block re-runs from live state for as long as it is rendered, so a
+ * leaver kept on screen for its exit shows state that has already moved on.
+ * In snapshot mode the leaver's block is torn down in the render that removes
+ * it, as if no <Presence> were there. Before that render patches the
+ * leaver's block, the element is copied as it stands. After it, the copy goes
+ * back where the element stood (before the first node that followed it and is
+ * still there), lifted out of flow at its recorded seat, plays the element's
+ * exit, and is removed.
+ *
+ * The seat is read in every frame that follows a render, and whenever the
+ * element or the box it is pinned inside resizes, not at the diff: Glimmer
+ * patches the DOM in template order, so by the time <Presence> diffs, content
+ * earlier in the template has already been patched for the render, and may
+ * have moved or resized the element. Its content is still the last frame's;
+ * its box may not be. A move that is neither a render nor one of those
+ * resizes is not seen: a transition on a sibling's width can shift the
+ * element without resizing either box, and the copy is then pinned where the
+ * element stood before that move.
+ *
+ * The copy is kept as a memory (see memory.ts): it shows the element's last
+ * frame, and nothing in it acts. A clone does not carry everything the
+ * element showed, so the copy also takes the canvas pixels it showed, the
+ * option each of its selects had chosen, and the values its script
+ * animations and transitions had reached.
+ */
+import type { PresenceContextProps } from 'motion-dom';
+
+import {
+  elementsOf,
+  keepAsMemory,
+  readShown,
+  type Shown,
+  shownOnCopy,
+} from './memory.ts';
+import {
+  flushPendingMounts,
+  type MotionEl,
+  MotionNode,
+  type MotionProps,
+  type PopSeat,
+  seatInsets,
+  seatOf,
+} from './node.ts';
+import type { PresenceHandle } from './presence-types.ts';
+
+/** where a copy is pinned, and what its exit variants resolve against */
+export interface CopyPlacement {
+  anchorX: 'left' | 'right';
+  anchorY: 'top' | 'bottom';
+  custom: unknown;
+}
+
+/** what the diff read from a leaver, for its copy to use after the render */
+interface Captured {
+  copy: MotionEl;
+  /**
+   * the nodes that followed the element: the copy goes back in before the
+   * first one the render left in place (the next ones are often the leaver's
+   * own whitespace and bounds, which leave with its block)
+   */
+  following: Node[];
+  parent: Node;
+  props: MotionProps;
+  seat: PopSeat;
+  /** what the element showed, keyed to the copy's elements */
+  shown: Shown;
+}
+
+let copyId = 0;
+
+/** an element's CSS property for a keyframe key: `clipPath` → `clip-path`, `--x` stays */
+function cssProperty(key: string) {
+  if (key.startsWith('--')) {
+    return key;
+  }
+  return key === 'cssFloat'
+    ? 'float'
+    : key.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+}
+
+const KEYFRAME_META = new Set([
+  'composite',
+  'computedOffset',
+  'easing',
+  'offset',
+]);
+
+/** a script animation or a transition: the copy keeps the value it shows now */
+function freezeComputed(animation: Animation, live: Element, copy: Element) {
+  const effect = animation.effect as KeyframeEffect;
+  const computed = getComputedStyle(live);
+  const style = (copy as HTMLElement | SVGElement).style;
+  for (const frame of effect.getKeyframes()) {
+    for (const key of Object.keys(frame)) {
+      if (!KEYFRAME_META.has(key)) {
+        const property = cssProperty(key);
+        style.setProperty(property, computed.getPropertyValue(property));
+      }
+    }
+  }
+}
+
+function copyCanvas(live: HTMLCanvasElement, copy: HTMLCanvasElement) {
+  try {
+    copy.getContext('2d')?.drawImage(live, 0, 0);
+  } catch {
+    // a canvas the copy cannot draw from stays blank
+  }
+}
+
+/**
+ * Copies an element that is about to be removed, as it stands. Called from
+ * <Presence>'s diff, before the render patches the element's block. `seat` is
+ * the one recorded for it (see MotionNode.recordSeat); an element that is
+ * leaving before any seat was recorded is pinned where it stands now.
+ */
+export function captureExit(source: {
+  element: MotionEl;
+  props: MotionProps;
+  seat: PopSeat | undefined;
+}): ExitCopy | undefined {
+  const { element, props } = source;
+  const parent = element.parentNode;
+  const seat = source.seat ?? seatOf(element);
+  if (!parent || !seat) {
+    return undefined;
+  }
+  const copy = element.cloneNode(true) as MotionEl;
+  const live = elementsOf(element);
+  const copies = elementsOf(copy);
+  const indexOf = new Map(live.map((el, i) => [el, i]));
+  for (const animation of element.getAnimations({ subtree: true })) {
+    const effect = animation.effect;
+    const index =
+      !(animation instanceof CSSAnimation) &&
+      effect instanceof KeyframeEffect &&
+      !effect.pseudoElement &&
+      effect.target
+        ? indexOf.get(effect.target)
+        : undefined;
+    if (index !== undefined) {
+      freezeComputed(animation, live[index]!, copies[index]!);
+    }
+  }
+  live.forEach((el, i) => {
+    if (el instanceof HTMLCanvasElement) {
+      copyCanvas(el, copies[i] as HTMLCanvasElement);
+    } else if (el instanceof HTMLOptionElement) {
+      // a clone's options take their selectedness from the markup, not from
+      // the choice the user made
+      (copies[i] as HTMLOptionElement).selected = el.selected;
+    }
+  });
+  const following: Node[] = [];
+  for (let node = element.nextSibling; node; node = node.nextSibling) {
+    following.push(node);
+  }
+  return new ExitCopy({
+    copy,
+    following,
+    parent,
+    props,
+    seat,
+    shown: shownOnCopy(readShown(element), element, copy),
+  });
+}
+
+/** one static copy of a leaver, from the render that removed the leaver until its exit ends */
+export class ExitCopy {
+  private node?: MotionNode;
+  private ended = false;
+  /** set once the copy has mounted and its exit has started: before that, a report is the mount's */
+  private armed = false;
+  private readonly reports = new Map<string | number, boolean>();
+  private onDone?: () => void;
+  private readonly captured: Captured;
+
+  constructor(captured: Captured) {
+    this.captured = captured;
+  }
+
+  /** after the render: put the copy where its element stood and play the exit */
+  start(placement: CopyPlacement, onDone: () => void) {
+    this.onDone = onDone;
+    const { copy, following, parent, props, shown } = this.captured;
+    if (this.ended || !parent.isConnected) {
+      this.end(true);
+      return;
+    }
+    this.pin(placement);
+    const before = following.find((node) => node.parentNode === parent);
+    keepAsMemory(copy, shown, () => parent.insertBefore(copy, before ?? null));
+    const node = (this.node = new MotionNode());
+    node.update(copy, { ...props, presence: this.handle(placement) });
+    flushPendingMounts();
+    this.armed = true;
+    this.check();
+  }
+
+  /** stop now and remove the copy, without reporting an exit (its item came back) */
+  cut() {
+    this.end(false);
+  }
+
+  /** lifted out of flow at the seat its element had: inline and important, so the copy's own CSS cannot move it */
+  private pin({ anchorX, anchorY }: CopyPlacement) {
+    const { copy, seat } = this.captured;
+    const { inline, block } = seatInsets(seat, anchorX, anchorY);
+    const style = copy.style;
+    const set = (property: string, value: string) =>
+      style.setProperty(property, value, 'important');
+    set('position', 'absolute');
+    set('margin', '0');
+    set('width', `${seat.w}px`);
+    set('height', `${seat.h}px`);
+    for (const side of ['top', 'right', 'bottom', 'left']) {
+      set(side, 'auto');
+    }
+    set(inline[0], `${inline[1]}px`);
+    set(block[0], `${block[1]}px`);
+  }
+
+  /** the copy is not present, and its exit is done once every motion element registered in it reports */
+  private handle(placement: CopyPlacement): PresenceHandle {
+    const id = `presence-copy-${copyId++}`;
+    const context: PresenceContextProps = {
+      id,
+      isPresent: false,
+      custom: placement.custom,
+      register: (childId) => {
+        this.reports.set(childId, false);
+        return () => {
+          this.reports.delete(childId);
+          this.check();
+        };
+      },
+      onExitComplete: (childId) => {
+        this.reports.set(childId, true);
+        this.check();
+      },
+    };
+    return {
+      anchorX: placement.anchorX,
+      anchorY: placement.anchorY,
+      context,
+      isPresent: false,
+      key: id,
+      mode: 'sync',
+      popCandidate: () => () => undefined,
+      subscribe: () => () => undefined,
+    };
+  }
+
+  private check() {
+    if (
+      this.armed &&
+      !this.ended &&
+      [...this.reports.values()].every(Boolean)
+    ) {
+      this.end(true);
+    }
+  }
+
+  private end(report: boolean) {
+    if (this.ended) {
+      return;
+    }
+    this.ended = true;
+    this.node?.destroy();
+    this.node = undefined;
+    this.captured.copy.remove();
+    if (report) {
+      this.onDone?.();
+    }
+  }
+}

package/bundled-types/glimmer-motion/test-support/index.ts

@@ -43,6 +43,7 @@ import { rootProjectionNode } from 'motion-dom';
 import { isMotionIdle, whatIsBusy } from '../activity.ts';
 import { layoutLoopDetected, resetLayoutLoopGuard } from '../layout.ts';
 import { resetUngroupedLayoutWarning } from '../layout-group.gts';
+import { MEMORY_ATTRIBUTE } from '../memory.ts';
 import { setMotionSpeed } from '../speed.ts';
 
 export { isMotionIdle, whatIsBusy } from '../activity.ts';
@@ -50,11 +51,11 @@ export { isMotionIdle, whatIsBusy } from '../activity.ts';
 const nextFrame = () =>
   new Promise<void>((resolve) => frame.postRender(() => resolve()));
 
+const testRoot = (): Element =>
+  document.querySelector('#ember-testing') ?? document.body;
+
 /** the box QUnit renders the test into; every measurement here is relative to it */
-const container = (): DOMRect =>
-  (
-    document.querySelector('#ember-testing') ?? document.body
-  ).getBoundingClientRect();
+const container = (): DOMRect => testRoot().getBoundingClientRect();
 
 export interface Box {
   height: number;
@@ -113,6 +114,37 @@ export function boundsAndShape(
   return { ...shape(element), ...bounds(element) };
 }
 
+/**
+ * The first LIVE match for `selector`: never a memory, a leaver kept on screen
+ * while its exit plays (a `<Presence @mode="snapshot">` copy, a leaver in a
+ * `<Choreo>` orphan layer).
+ *
+ * A memory's test hooks carry a suffix (`data-test-title-memory`), so a
+ * selector made of test hooks already matches only live elements. Any other
+ * selector (a class, a role, a tag) can match a memory as well as whatever
+ * replaced it, and a bare `querySelector` can answer with the memory: an
+ * element whose component has already been torn down, which is inert, and
+ * whose box is where the old scene stood. Clicking it does nothing; measuring
+ * it measures the past. Neither failure names itself. Such a query, made while
+ * an exit may still be playing, should come through here.
+ */
+export function live<E extends Element = HTMLElement>(
+  selector: string,
+  root: ParentNode = testRoot(),
+): E | null {
+  return liveAll<E>(selector, root)[0] ?? null;
+}
+
+/** every live match for `selector`, in document order: see `live()` */
+export function liveAll<E extends Element = HTMLElement>(
+  selector: string,
+  root: ParentNode = testRoot(),
+): E[] {
+  return [...root.querySelectorAll<E>(selector)].filter(
+    (el) => !el.closest(`[${MEMORY_ATTRIBUTE}]`),
+  );
+}
+
 export interface SettleOptions {
   /** give up after this long and report what was still moving (default 5000) */
   timeout?: number;