@oxyhq/bloom 0.54.1 → 0.55.0

package/src/__tests__/toast-stack-hover.test.ts

@@ -0,0 +1,92 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { renderHook } from '@testing-library/react-native';
+
+import {
+  isStackHovered as isStackHoveredNative,
+  useStackHover as useStackHoverNative,
+} from '../toast/use-stack-hover.native';
+import { isStackHovered, useStackHover } from '../toast/use-stack-hover';
+
+/**
+ * The hover trigger's platform split. jest resolves the WEB file by default (as
+ * every non-Metro bundler and a consumer's `tsc` do), so `Toaster.test.tsx` covers
+ * the web behaviour through real rows; this file covers the NATIVE fork, which has
+ * no behaviour to exercise, plus the source properties that keep the split honest.
+ */
+const SRC = join(__dirname, '..');
+const read = (rel: string) => readFileSync(join(SRC, rel), 'utf8');
+const code = (rel: string) =>
+  read(rel)
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/^\s*\/\/.*$/gm, '');
+
+describe('stack hover platform split', () => {
+  it('native hands back no handlers at all, for either stacking value', () => {
+    const stacked = renderHook(() => useStackHoverNative({ enableStacking: true }));
+    const flat = renderHook(() => useStackHoverNative({ enableStacking: false }));
+
+    expect(Object.keys(stacked.result.current)).toEqual([]);
+    expect(Object.keys(flat.result.current)).toEqual([]);
+  });
+
+  it('native returns ONE object identity, so the row box props never churn', () => {
+    const { result, rerender } = renderHook(() =>
+      useStackHoverNative({ enableStacking: true }),
+    );
+    const first = result.current;
+    rerender(undefined);
+
+    expect(result.current).toBe(first);
+  });
+
+  it('nothing ever hovers on native', () => {
+    expect(isStackHoveredNative()).toBe(false);
+  });
+
+  it('web hands back both pointer handlers', () => {
+    const { result } = renderHook(() => useStackHover({ enableStacking: true }));
+
+    expect(typeof result.current.onPointerEnter).toBe('function');
+    expect(typeof result.current.onPointerLeave).toBe('function');
+  });
+
+  it('web is not hovered until a pointer says so', () => {
+    expect(isStackHovered()).toBe(false);
+  });
+
+  it('the native fork carries no hover state, no timer and no store import', () => {
+    const native = code('toast/use-stack-hover.native.ts');
+    // A native bundle must not ship the web file's module-level latch or its
+    // pending-leave timeout, which is the whole reason this is a file split rather
+    // than a `Platform.OS` branch.
+    expect(native).not.toMatch(/setTimeout/);
+    expect(native).not.toMatch(/from '\.\/toast-store'/);
+    expect(native).not.toMatch(/pointerType/);
+  });
+
+  it('the web fork gates on a mouse pointer', () => {
+    const web = code('toast/use-stack-hover.ts');
+    // Touch fires enter before pointerdown and leave after pointerup, so without
+    // this every tap on a touch-capable web device would expand then collapse.
+    expect(web).toMatch(/pointerType === 'mouse'/);
+  });
+
+  it('the web fork drives the store rather than a second expansion mechanism', () => {
+    const web = code('toast/use-stack-hover.ts');
+    expect(web).toMatch(/toastStore\.expand\(\)/);
+    expect(web).toMatch(/toastStore\.collapse\(\)/);
+    // With stacking off there is nothing to expand, so the pointer pauses directly.
+    expect(web).toMatch(/toastStore\.pauseAllTimers\(\)/);
+    expect(web).toMatch(/toastStore\.resumeAllTimers\(\)/);
+    // No parallel state: expansion lives in the store and nowhere else.
+    expect(web).not.toMatch(/useState/);
+    expect(web).not.toMatch(/isExpanded\s*=/);
+  });
+
+  it('the row box is the hover target and the press toggle stands down for it', () => {
+    expect(code('toast/ToastSwipeHandler.tsx')).toMatch(/\{\.\.\.hoverProps\}/);
+    // Hover owns expansion on web; a click must not toggle it shut again.
+    expect(code('toast/ToastRow.tsx')).toMatch(/else if \(!isStackHovered\(\)\)/);
+  });
+});

package/src/__tests__/toast-store.test.ts

@@ -17,6 +17,9 @@ describe('toastStore', () => {
   });
 
   afterEach(() => {
+    // The expansion hold is registered by whoever owns hovering, so a test that
+    // installs one must not leak it into the next.
+    toastStore.setExpansionHold(null);
     toastStore.dismissToast(undefined);
     // Drains the hide-overlay timeout so the next test starts from a clean state.
     jest.runOnlyPendingTimers();
@@ -573,6 +576,14 @@ describe('toastStore', () => {
       expect(toastStore.getSnapshot().isExpanded).toBe(true);
     });
 
+    /**
+     * The auto-collapse rule. A lone row renders identically expanded or collapsed
+     * (`toast-position-utils.test.ts`: "a single row is unmoved by expansion"), while
+     * `isExpanded` keeps every timer paused — so collapsing at one row is invisible
+     * and is the only thing that stops that last toast hanging on screen forever.
+     * The exception is a stack something is HOLDING open, which on web is a pointer
+     * resting on it.
+     */
     it('auto-collapses once only one toast is left', () => {
       const first = toastStore.addToast({ title: 'a' });
       toastStore.addToast({ title: 'b' });
@@ -581,6 +592,67 @@ describe('toastStore', () => {
       toastStore.dismissToast(first, 'onDismiss');
       expect(toastStore.getSnapshot().isExpanded).toBe(false);
     });
+
+    it('resumes the surviving toast on that auto-collapse, so it cannot hang', () => {
+      const first = toastStore.addToast({ title: 'a', duration: 1000 });
+      toastStore.addToast({ title: 'b', duration: 1000 });
+      toastStore.expand();
+
+      toastStore.dismissToast(first, 'onDismiss');
+      jest.advanceTimersByTime(ENTERING_ANIMATION_DURATION + 1000);
+
+      expect(toastStore.getSnapshot().toasts).toHaveLength(0);
+    });
+
+    it('stays expanded while more than one toast is left', () => {
+      const first = toastStore.addToast({ title: 'a' });
+      toastStore.addToast({ title: 'b' });
+      toastStore.addToast({ title: 'c' });
+      toastStore.expand();
+
+      toastStore.dismissToast(first, 'onDismiss');
+      expect(toastStore.getSnapshot().isExpanded).toBe(true);
+    });
+
+    it('does not auto-collapse a stack something is holding open', () => {
+      toastStore.setExpansionHold(() => true);
+      const first = toastStore.addToast({ title: 'a', duration: 1000 });
+      toastStore.addToast({ title: 'b', duration: 1000 });
+      toastStore.expand();
+
+      toastStore.dismissToast(first, 'onDismiss');
+
+      expect(toastStore.getSnapshot().isExpanded).toBe(true);
+      // Still paused: resuming here is what would let a hovered toast expire under
+      // the cursor.
+      jest.advanceTimersByTime(1_000_000);
+      expect(toastStore.getSnapshot().toasts).toHaveLength(1);
+    });
+
+    it('resets an EMPTY stack even while held', () => {
+      // Nothing can hold open a stack that no longer exists, and once the rows
+      // unmount no `pointerleave` ever arrives to release the hold — so this must
+      // not depend on it.
+      toastStore.setExpansionHold(() => true);
+      const only = toastStore.addToast({ title: 'a' });
+      toastStore.expand();
+
+      toastStore.dismissToast(only, 'onDismiss');
+
+      expect(toastStore.getSnapshot().toasts).toHaveLength(0);
+      expect(toastStore.getSnapshot().isExpanded).toBe(false);
+    });
+
+    it('stops consulting a hold once it is cleared', () => {
+      toastStore.setExpansionHold(() => true);
+      toastStore.setExpansionHold(null);
+      const first = toastStore.addToast({ title: 'a' });
+      toastStore.addToast({ title: 'b' });
+      toastStore.expand();
+
+      toastStore.dismissToast(first, 'onDismiss');
+      expect(toastStore.getSnapshot().isExpanded).toBe(false);
+    });
   });
 
   describe('subscription', () => {

package/src/toast/Toast.stories.tsx

@@ -26,6 +26,14 @@ import type { ToasterProps } from './types';
  * unstacked they must be ~54px apart (46px measured row + 8px gap), collapsed-
  * stack ~8px apart. Equal `y` values mean the rows are drawn on top of each
  * other — the failure this shape exists to catch.
+ *
+ * `Sequential*` gives you BOTH durations for a reason. The `One`/`Two` buttons use
+ * `duration: Infinity` so a row stays put while you inspect it — but that starts no
+ * auto-close timer at all, so nothing driven from those buttons can see the timer
+ * path. `One 3s`/`Two 3s` fire at the outlet's real duration; drive those when the
+ * question is a row's LIFETIME rather than its position. (`Toaster.test.tsx`'s
+ * "sequential toasts at the default duration" block covers the render set there;
+ * only a browser can judge the geometry.)
  */
 const meta: Meta = {
   title: 'Components/Toast',
@@ -249,6 +257,8 @@ function SequentialDemo({ outlet }: { outlet?: ToasterProps }) {
     <Demo outlet={outlet}>
       <Button onPress={() => toast('Row one', { duration: Infinity })}>One</Button>
       <Button onPress={() => toast('Row two', { duration: Infinity })}>Two</Button>
+      <Button onPress={() => toast('Row one')}>One 3s</Button>
+      <Button onPress={() => toast('Row two')}>Two 3s</Button>
     </Demo>
   );
 }

package/src/toast/ToastRow.tsx

@@ -60,6 +60,7 @@ import {
 } from './constants';
 import { useDynamicToastContext, useToastContext } from './context';
 import { calculateStackScaleX } from './position-utils';
+import { isStackHovered } from './use-stack-hover';
 import { useAnimatedTarget } from './use-animated-target';
 import { ToastContent } from './ToastContent';
 import { ToastSwipeHandler } from './ToastSwipeHandler';
@@ -354,18 +355,41 @@ export const ToastRow = React.forwardRef<ToastRef, ToastRowProps>(
       }
     }, [id, isExpanded]);
 
+    /**
+     * INVARIANT: NO TAP ON A STACKED ROW IS INERT. Every one of them dismisses,
+     * expands or collapses.
+     *
+     * The close-button strip dismisses only when a ✕ is actually THERE to aim at,
+     * which is exactly `closeButton && dismissible` — the same condition
+     * `ToastContent` renders it under, and nothing to do with expansion. Anything
+     * else in the strip falls through to the row's own behaviour rather than being
+     * swallowed: on a collapsed stack it expands, on an expanded one it collapses.
+     *
+     * Guarding the strip on `isExpanded` (as this did until now) made two taps do
+     * nothing at all — the whole strip at default config, where `closeButton` is
+     * `false` so the dismiss branch is unreachable, and the VISIBLE ✕ on a
+     * collapsed stack's front row. On Android that second one has no fallback:
+     * the RNGH tap wins the race against `ToastContent`'s nested close Pressable,
+     * so the ✕ never got its own press either.
+     *
+     * `x` is relative to the row, which is CAPPED at `TOAST_MAX_ROW_WIDTH`.
+     * Measuring the strip from the window edge would put it outside the row
+     * entirely on a wide viewport — do not "simplify" this back to `screenWidth`.
+     *
+     * W13 — the expansion TOGGLE stands down while a mouse is hovering the stack,
+     * because hover already owns expansion there (`use-stack-hover`). Without this
+     * a desktop click would collapse the stack under the cursor and resume the
+     * timers hover had just paused. Dismissing is unaffected, `onPress` always
+     * runs, and `isStackHovered()` is always false on native and on any touch web
+     * device — so press remains the only trigger wherever there is no pointer.
+     */
     const onSwipePress = React.useCallback(
       ({ x }: { x: number; y: number }) => {
         if (enableStacking && numberOfToasts > 1 && position !== 'center') {
-          // On Android the RNGH tap wins the race against the nested Pressable,
-          // so a press in the close-button strip has to dismiss explicitly.
-          // `x` is relative to the row, which is capped — measuring the strip
-          // from the window edge would put it outside the row on a wide viewport.
-          if (x > rowWidth - CLOSE_BUTTON_HIT_AREA) {
-            if (isExpanded && closeButton && dismissible) {
-              onDismiss(id);
-            }
-          } else {
+          const inCloseStrip = x > rowWidth - CLOSE_BUTTON_HIT_AREA;
+          if (inCloseStrip && closeButton && dismissible) {
+            onDismiss(id);
+          } else if (!isStackHovered()) {
             toggleExpand();
           }
         }
@@ -376,7 +400,6 @@ export const ToastRow = React.forwardRef<ToastRef, ToastRowProps>(
         numberOfToasts,
         position,
         rowWidth,
-        isExpanded,
         closeButton,
         dismissible,
         onDismiss,

package/src/toast/ToastSwipeHandler.tsx

@@ -14,6 +14,10 @@
  * covers `toast.custom` JSX and `unstyled` rows too, which never reach that
  * card. Every distance the gesture measures is a fraction of the capped
  * `rowWidth`, not of the window — see the constant.
+ *
+ * W13 — being THE row box also makes it the hover target: `useStackHover`'s
+ * handlers go here so a pointer over ANY row counts as a pointer over the stack.
+ * The handlers are empty on native.
  */
 import * as React from 'react';
 import {
@@ -37,6 +41,7 @@ import { easeInOutCircFn } from './animations';
 import { TOAST_MAX_ROW_WIDTH } from './constants';
 import { useToastContext } from './context';
 import type { ToastPosition, ToastProps } from './types';
+import { useStackHover } from './use-stack-hover';
 
 /** Fraction of the row a horizontal swipe must cross to dismiss. */
 const HORIZONTAL_DISMISS_FRACTION = 0.25;
@@ -76,10 +81,16 @@ export const ToastSwipeHandler: React.FC<
   // The row is `width: '100%'` up to the cap, so this is its real width.
   const rowWidth = Math.min(windowWidth, TOAST_MAX_ROW_WIDTH);
   const translate = useSharedValue(0);
-  const { swipeToDismissDirection: direction, position: positionCtx } =
-    useToastContext();
+  const {
+    swipeToDismissDirection: direction,
+    position: positionCtx,
+    enableStacking,
+  } = useToastContext();
   const position = positionProps ?? positionCtx;
   const isAndroid = Platform.OS === 'android';
+  // W13 — hover lives on THE ROW BOX, so hovering any row counts as hovering the
+  // stack. Empty on native; see `use-stack-hover.native.ts`.
+  const hoverProps = useStackHover({ enableStacking });
 
   const pan = Gesture.Pan()
     .onBegin(() => {
@@ -199,6 +210,7 @@ export const ToastSwipeHandler: React.FC<
           styles.rowBox,
           style,
         ]}
+        {...hoverProps}
         // W9 — on web `LinearTransition`'s easing degrades to CSS `ease` because
         // a `bezierFn` result carries no easing-name symbol for the CSS mapper.
         // Accepted: the transition still runs, only its curve differs.

package/src/toast/constants.ts

@@ -98,7 +98,24 @@ export const toastDefaults: {
   theme: 'system',
   autoWiggleOnUpdate: 'never',
   richColors: false,
-  enableStacking: false,
+  /**
+   * ON, unlike upstream — the same class of correction as `TOAST_MAX_ROW_WIDTH`.
+   *
+   * sonner-NATIVE defaults this off; sonner (web) has no switch at all, because a
+   * collapsed stack — front row full size, the ones behind scaled and offset,
+   * expanding on interaction — IS its default presentation. The port inherited the
+   * mobile default onto every desktop consumer, where an unstacked run of toasts
+   * is a column of full cards rather than a stack.
+   *
+   * Bloom already deviates deliberately elsewhere (`position: 'bottom-center'` vs
+   * upstream's `top-center`, `duration: 3000` vs 4000, `gap: 8` vs 14), so this is
+   * in keeping rather than a break with the port.
+   *
+   * Turning it OFF (`<ToastOutlet enableStacking={false} />`) restores the flat
+   * column, which is still the right choice for a surface that must show several
+   * toasts at once without an interaction.
+   */
+  enableStacking: true,
   stackGap: 8,
   allowFontScaling: true,
 };

package/src/toast/toast-store.ts

@@ -42,6 +42,7 @@ class ToastStore {
   private pendingPromises = new Set<string | number>();
   private collapseCooldown = false;
   private collapseCooldownTimeout: ReturnType<typeof setTimeout> | null = null;
+  private expansionHold: (() => boolean) | null = null;
 
   subscribe = (callback: Subscriber) => {
     this.subscribers.add(callback);
@@ -59,6 +60,24 @@ class ToastStore {
     this.config = config;
   };
 
+  /**
+   * Something outside the store can HOLD an expanded stack open — on web, a pointer
+   * resting on it. Registered by the platform trigger (`use-stack-hover`) so this
+   * module stays pure JS with no DOM and no platform branch; native registers
+   * nothing and the predicate stays `null`.
+   *
+   * It is asked at DECISION time rather than tracked as state on purpose: a row can
+   * stop being under the pointer with no event at all — rows unmount under the
+   * cursor and move under a stationary one, and neither fires `pointerleave` —
+   * so any cached boolean goes stale. Nothing renders from this, so it is
+   * deliberately not part of the snapshot.
+   */
+  setExpansionHold = (hold: (() => boolean) | null) => {
+    this.expansionHold = hold;
+  };
+
+  private isHeldOpen = (): boolean => this.expansionHold?.() === true;
+
   private notify = () => {
     this.subscribers.forEach((callback) => callback());
   };
@@ -305,8 +324,27 @@ class ToastStore {
     const updatedRefs = { ...this.state.toastRefs };
     delete updatedRefs[id];
 
+    /**
+     * An expanded stack collapses itself once a single row is left, because
+     * "expanded" then means nothing visually — a lone row resolves to the SAME
+     * offset and scale either way (`toast-position-utils.test.ts` pins that) — while
+     * `isExpanded` keeps every timer paused, so staying expanded would leave that
+     * last toast on screen forever with no visible reason. Inherited from
+     * sonner-native and kept deliberately: on native it is invisible and it is the
+     * only thing that stops the last row hanging.
+     *
+     * UNLESS something is holding the stack open. On web that is a pointer resting
+     * on it, and collapsing under the cursor would resume the timers hover had just
+     * paused — the toast would then expire while the user is reading it, which is
+     * exactly what hover exists to prevent.
+     *
+     * An EMPTY stack always resets, hold or no hold: it no longer exists to be held,
+     * and once the rows unmount no `pointerleave` will ever arrive to release it.
+     */
+    const isEmpty = filteredToasts.length === 0;
+    const heldOpen = !isEmpty && this.isHeldOpen();
     const shouldAutoCollapse =
-      filteredToasts.length <= 1 && this.state.isExpanded;
+      filteredToasts.length <= 1 && this.state.isExpanded && !heldOpen;
 
     const updatedIndex = this.cloneIndex();
     updatedIndex.delete(id);

package/src/toast/use-stack-hover.native.ts

@@ -0,0 +1,34 @@
+/**
+ * Bloom-original — NATIVE. Metro resolves this over `use-stack-hover.ts` on iOS and
+ * Android, the same filename split `ToastHost.native.tsx` uses.
+ *
+ * Native keeps PRESS as the only way to expand a stack, so this hands back no
+ * handlers at all. Two reasons it is a fork rather than a runtime `Platform` check:
+ * the web file's module-level hover state and its `setTimeout` have no business
+ * existing in a native bundle, and `onPointerEnter`/`onPointerLeave` DO fire on
+ * native for touch (RN's pointer events unify touch and mouse), which would make
+ * every tap expand-then-collapse while the press toggle fired as well.
+ *
+ * Keep the shape identical to the web file — `ToastSwipeHandler` spreads whatever
+ * this returns onto the row box, and `ToastRow` calls `isStackHovered()`
+ * unconditionally.
+ */
+export type StackHoverProps = Record<string, never>;
+
+/** Parity with the web file's export; nothing here waits for anything. */
+export const HOVER_LEAVE_GRACE = 0;
+
+/** Nothing hovers on a touch screen. */
+export function isStackHovered(): boolean {
+  return false;
+}
+
+/** One frozen object, so spreading it never changes the row box's props. */
+const NO_HOVER_PROPS: StackHoverProps = Object.freeze({});
+
+export function useStackHover(_options: { enableStacking: boolean }): StackHoverProps {
+  return NO_HOVER_PROPS;
+}
+
+/** Parity with the web file so the shared suite can call it on either platform. */
+export function resetStackHoverForTests(): void {}

package/src/toast/use-stack-hover.ts

@@ -0,0 +1,182 @@
+/**
+ * Bloom-original — WEB/default. `use-stack-hover.native.ts` is the native no-op,
+ * filename-resolved by Metro exactly as `ToastHost.native.tsx` is, so `toast/`
+ * stays one universal engine with no `index.web` fork.
+ *
+ * sonner expands its stack on HOVER; sonner-native only has press, because a phone
+ * has no pointer. Bloom needs both: press is the touch and native affordance, hover
+ * is what a desktop user expects, and a touch-capable web device must not get a
+ * phantom hover from its own taps.
+ *
+ * THIS IS A TRIGGER, NOT A SECOND MECHANISM. It drives the store's existing
+ * `expand`/`collapse`, which already pause and resume the auto-close timers
+ * (`ToastStore.expand` calls `timers.pauseAll()`, `collapse` calls `resumeAll()`),
+ * so hovering to read a toast cannot let it expire under the cursor — no new
+ * pausing path, no new store state. With stacking OFF there is nothing to expand,
+ * so the pointer pauses the timers directly instead: the reason sonner pauses is
+ * that the pointer is over the toast, which has nothing to do with stacking.
+ *
+ * TWO THINGS ARE LOAD-BEARING:
+ *
+ *  - `pointerType === 'mouse'`. Touch fires `pointerenter` before `pointerdown`
+ *    and `pointerleave` after `pointerup` (the pointer ceases to exist), so
+ *    without this guard every TAP on a touch-capable web device would expand then
+ *    collapse the stack while the press toggle fired too — three handlers fighting
+ *    over one tap. Hover is additive: pens and touch fall through to press.
+ *  - THE LEAVE IS DEFERRED BY A FRAME-ISH GRACE PERIOD, and any enter cancels it.
+ *    Rows are separate absolutely-positioned boxes with `gap` between them once
+ *    expanded, so moving the pointer from one row to the next leaves the first
+ *    before entering the second. Collapsing on that would snap the stack shut and
+ *    reopen it on whatever row ends up under the pointer — a jitter loop, plus a
+ *    resume/pause pair per crossing that re-banks each timer's remaining time.
+ *
+ * The state is module-level on purpose: there is ONE stack per document, the same
+ * reason `toastStore` is a module singleton. It is written and read only inside
+ * event handlers — never in render — so the React Compiler has nothing to freeze.
+ */
+import { useMemo } from 'react';
+
+import { toastStore } from './toast-store';
+
+/**
+ * How long a leave waits for a neighbouring row to claim the pointer. One frame is
+ * enough for the same-tick leave/enter pair a row crossing produces; this is a
+ * little more so a slow frame cannot flash the stack shut. Exported so the suite
+ * asserts against the real value rather than a copy of it.
+ */
+export const HOVER_LEAVE_GRACE = 80;
+
+/** The portal root every toast row lives under — see `portal/index.web.tsx`. */
+const PORTAL_ROOT_ID = 'bloom-portal-root';
+
+type HoverEvent = { nativeEvent: { pointerType?: string } };
+
+let hovered = false;
+let leaveTimeout: ReturnType<typeof setTimeout> | null = null;
+
+const isMouse = (event: HoverEvent) => event.nativeEvent.pointerType === 'mouse';
+
+const cancelPendingLeave = () => {
+  if (leaveTimeout !== null) {
+    clearTimeout(leaveTimeout);
+    leaveTimeout = null;
+  }
+};
+
+/**
+ * Whether the pointer is over the stack RIGHT NOW.
+ *
+ * Two sources, and both are load-bearing:
+ *
+ *  - the `hovered` latch answers "a mouse entered and has not left", which is the
+ *    only thing available where there is no DOM (jest runs on `testEnvironment:
+ *    'node'`), and is a cheap early-out.
+ *  - the live `:hover` query answers "a row is under the pointer", which the latch
+ *    CANNOT: a row can stop being hovered with no event whatsoever. Measured — a row
+ *    culled by `visibleToasts` under a stationary cursor fires no `pointerleave`,
+ *    `pointerout` or `mouseleave` at all, and the restack then slides the remaining
+ *    rows out from under the pointer. A latch alone therefore sticks TRUE, which
+ *    would disable the press toggle for the rest of the session and suppress every
+ *    later auto-collapse.
+ *
+ * Requiring both means a stale latch is corrected by the DOM and a stray DOM match
+ * (a pen, a touch) is rejected by the latch.
+ *
+ * COVERAGE, stated plainly: jest cannot see the DOM half at all
+ * (`testEnvironment: 'node'`), and a browser cannot isolate it either — its two
+ * consequences are a press toggle standing down (unreachable with a mouse, which
+ * always hovers what it presses) and a suppressed auto-collapse (which the deferred
+ * leave below independently corrects the moment any boundary event fires). Both
+ * halves are kept because each is measurably more accurate than the other alone, not
+ * because a test proves the composite.
+ *
+ * `ToastRow` asks so a press does not TOGGLE what hover already opened, and
+ * `toastStore` asks before auto-collapsing a stack down to its last row. The press
+ * still runs the toast's own `onPress`; only the expansion toggle steps aside.
+ */
+export function isStackHovered(): boolean {
+  return hovered && rowUnderPointer() !== false;
+}
+
+/**
+ * The live DOM answer, or `undefined` where there is no DOM to ask (jest runs on
+ * `testEnvironment: 'node'`). Deliberately tri-state: "unknowable" and "no" must not
+ * collapse into the same value, because the two callers want opposite defaults —
+ * `isStackHovered` trusts the latch when it cannot check, while the deferred leave
+ * only stands down on a positive "yes, still hovered".
+ */
+function rowUnderPointer(): boolean | undefined {
+  if (typeof document === 'undefined') {
+    return undefined;
+  }
+  return document.querySelector(`#${PORTAL_ROOT_ID} [aria-live]:hover`) !== null;
+}
+
+/**
+ * A pointer resting on the stack HOLDS it open, so the store must not auto-collapse
+ * it out from under the cursor. Registered here rather than passed in because this
+ * file is the one that knows what hovering means; the store only knows that
+ * something says "not yet". Native's fork registers nothing.
+ */
+toastStore.setExpansionHold(isStackHovered);
+
+export type StackHoverProps = {
+  onPointerEnter: (event: HoverEvent) => void;
+  onPointerLeave: (event: HoverEvent) => void;
+};
+
+export function useStackHover({
+  enableStacking,
+}: {
+  enableStacking: boolean;
+}): StackHoverProps {
+  // Stable per outlet configuration: these land on the row box as props, and every
+  // row re-renders on each stack change.
+  return useMemo(
+    () => ({
+      onPointerEnter: (event: HoverEvent) => {
+        if (!isMouse(event)) {
+          return;
+        }
+        cancelPendingLeave();
+        hovered = true;
+        if (enableStacking) {
+          // Pauses the timers as part of expanding.
+          toastStore.expand();
+        } else {
+          toastStore.pauseAllTimers();
+        }
+      },
+      onPointerLeave: (event: HoverEvent) => {
+        if (!isMouse(event) || !hovered) {
+          return;
+        }
+        cancelPendingLeave();
+        leaveTimeout = setTimeout(() => {
+          leaveTimeout = null;
+          // The rows may have moved rather than the pointer: an expand, a collapse
+          // or a restack slides them under a stationary cursor without firing a
+          // single pointer event, so re-ask the DOM before acting on a leave that
+          // fired 80ms ago. Only a positive "still hovered" stands the collapse down.
+          if (rowUnderPointer() === true) {
+            return;
+          }
+          hovered = false;
+          if (enableStacking) {
+            // Resumes the timers as part of collapsing.
+            toastStore.collapse();
+          } else {
+            toastStore.resumeAllTimers();
+          }
+        }, HOVER_LEAVE_GRACE);
+      },
+    }),
+    [enableStacking],
+  );
+}
+
+/** Test-only reset: the module state outlives a render tree, so a suite must clear it. */
+export function resetStackHoverForTests(): void {
+  cancelPendingLeave();
+  hovered = false;
+}