@oxyhq/bloom 0.72.1 → 0.73.0

package/src/overlay/stack.ts

@@ -0,0 +1,166 @@
+/**
+ * The overlay stacking authority.
+ *
+ * ## The rule
+ *
+ * An overlay opened LATER paints above one opened earlier. That is the whole
+ * contract, and it is decided here, once, for every Bloom overlay surface —
+ * never by a per-component constant.
+ *
+ * ## Why this module exists
+ *
+ * Stacking used to be a set of hand-picked rungs on a shared scale: menus at
+ * 40, dialogs at 50/60, tooltips at 70, sheets at 999999. Because those numbers
+ * are fixed per COMPONENT KIND, the answer to "which surface is on top" was
+ * decided by what each surface WAS rather than by when the user opened it — so
+ * some pairings were permanently inverted no matter the order:
+ *
+ *   - A confirm dialog (50/60) opened from inside an open bottom sheet (999999)
+ *     rendered fully, interactively, and completely underneath the sheet. It
+ *     could be neither pressed nor dismissed.
+ *   - A menu (40/41) opened from inside a dialog (50/60) landed behind the very
+ *     dialog that launched it.
+ *
+ * Both failed silently: correct markup, correct styles, nothing in the console.
+ * Only a hit test in a real browser tells the difference, which is why
+ * `scripts/verify-overlay-stacking.mjs` exists alongside the unit tests here.
+ *
+ * ## How a rank is acquired
+ *
+ * `useOverlayLayer()` takes a rank on MOUNT and releases it on unmount, so the
+ * caller must be a component that mounts when the surface OPENS — which is how
+ * every Bloom surface is already built (`Dialog.web` returns null while closed;
+ * `BottomSheetBase` returns null until `rendered`). Acquiring per mount, in a
+ * `useState` initializer, is what makes the rank correct on the surface's FIRST
+ * paint: an effect-assigned z would leave one frame at the wrong depth, which
+ * on a 200ms fade-in is a visible flash of the surface behind its neighbour.
+ *
+ * It also keeps the acquisition out of any position the React Compiler may
+ * memoize. A counter read during render is exactly the external-mutable-state
+ * hazard the compiler mangles; a state initializer is not memoizable that way.
+ * (React StrictMode double-invokes initializers in development, so a rank can
+ * be consumed and dropped. That is harmless: only the ORDER of the numbers
+ * matters, never their density.)
+ *
+ * ## Toasts are deliberately not in this stack
+ *
+ * A toast is a notification, not a modal surface: it must stay visible over
+ * whatever is open, including a surface opened after it. It is pinned above the
+ * whole stack at `TOAST_LAYER_Z` instead of taking a rank. (Under the old
+ * scale a toast at 80 was already lost behind any open bottom sheet at 999999.)
+ */
+
+/**
+ * First z-index handed to an overlay. Comfortably above app content while
+ * staying far below `TOAST_LAYER_Z`.
+ */
+export const OVERLAY_STACK_BASE = 1000;
+
+/**
+ * Z-index distance between consecutive overlays. A surface owns its whole band,
+ * so it can order its own parts (backdrop, panel, a floating control) without
+ * ever reaching the next surface's floor.
+ */
+export const OVERLAY_STACK_BAND = 10;
+
+/**
+ * Ceiling on simultaneously open overlays. Beyond this, ranks saturate and the
+ * topmost surfaces tie (falling back to DOM order) rather than climbing into
+ * the toast layer. Nothing in the ecosystem stacks remotely this deep; the
+ * clamp exists so a runaway caller degrades instead of breaking the toast
+ * layer's guarantee.
+ */
+export const OVERLAY_STACK_MAX_RANK = 500;
+
+/**
+ * The toast layer, pinned above every overlay rank (see the note above on why
+ * toasts are not part of the stack).
+ */
+export const TOAST_LAYER_Z =
+  OVERLAY_STACK_BASE + OVERLAY_STACK_BAND * (OVERLAY_STACK_MAX_RANK + 1);
+
+/** The z-indices one overlay surface may use, all within its own band. */
+export interface OverlayLayer {
+  /** The surface's outermost node — everything it renders is inside this. */
+  root: number;
+  /** Its dimming layer. */
+  backdrop: number;
+  /** Its panel, above its own backdrop. */
+  surface: number;
+}
+
+/**
+ * Registry state.
+ *
+ * `sequence` only ever moves forward while anything is open, which is what
+ * guarantees the ordering. It resets once the last overlay closes so the
+ * numbers stay small over a long session.
+ */
+interface Registry {
+  sequence: number;
+  live: Set<number>;
+}
+
+declare global {
+  // eslint-disable-next-line no-var
+  var __oxyhq_bloom_overlay_stack__: Registry | undefined;
+}
+
+/**
+ * `globalThis`-anchored, for the same reason as the portal group and the theme
+ * context: `exports` ships a `react-native` → `src` condition beside the
+ * `lib/module` and `lib/commonjs` forks, and overlay surfaces are imported
+ * cross-subpath (`./dialog`, `./bottom-sheet`, `./menu`, `./select`, …). A
+ * bundler can resolve those through different conditions, and two physical
+ * copies of this module would each run their own counter — handing out
+ * colliding ranks and reintroducing exactly the bug this module removes.
+ */
+function registry(): Registry {
+  globalThis.__oxyhq_bloom_overlay_stack__ ??= { sequence: 0, live: new Set() };
+  return globalThis.__oxyhq_bloom_overlay_stack__;
+}
+
+/** Z-indices for a given rank. Exported for tests and for the native surfaces. */
+export function layerForRank(rank: number): OverlayLayer {
+  const clamped = Math.min(Math.max(rank, 1), OVERLAY_STACK_MAX_RANK);
+  const root = OVERLAY_STACK_BASE + OVERLAY_STACK_BAND * clamped;
+  return { root, backdrop: root, surface: root + 1 };
+}
+
+/**
+ * Take the next rank. Exported for tests; components use `useOverlayLayer`.
+ */
+export function acquireOverlayRank(): number {
+  const reg = registry();
+  reg.sequence += 1;
+  return reg.sequence;
+}
+
+/**
+ * Mark a rank as live. Called from an effect, which React balances against
+ * `releaseOverlayRank` even under StrictMode's mount/unmount/remount.
+ *
+ * It also re-floors `sequence` to at least this rank. That closes the only race
+ * the reset below could otherwise open: a surface takes rank N during render,
+ * and before its effect runs, the last previously-open surface unmounts and
+ * resets the counter to 0 — the next surface would then take rank 1 and sit
+ * BELOW the one still coming up at N. Re-flooring on register makes the reset
+ * unable to lose a rank that has been handed out.
+ */
+export function registerOverlayRank(rank: number): void {
+  const reg = registry();
+  reg.live.add(rank);
+  if (rank > reg.sequence) reg.sequence = rank;
+}
+
+/** Release a rank; resets the counter once nothing is open. */
+export function releaseOverlayRank(rank: number): void {
+  const reg = registry();
+  reg.live.delete(rank);
+  if (reg.live.size === 0) reg.sequence = 0;
+}
+
+/** Test seam — drops all registry state. */
+export function resetOverlayStack(): void {
+  globalThis.__oxyhq_bloom_overlay_stack__ = { sequence: 0, live: new Set() };
+}

package/src/overlay/use-overlay-layer.ts

@@ -0,0 +1,39 @@
+/**
+ * `useOverlayLayer` — the hook every Bloom overlay surface stacks with.
+ *
+ * See `./stack.ts` for the rule and the reasoning. The contract for callers is
+ * one line: **call this from a component that mounts when the surface OPENS**,
+ * not from one that stays mounted while it is closed. Every Bloom surface is
+ * already shaped that way (`Dialog.web` returns null while closed;
+ * `BottomSheetBase` returns null until `rendered`), and `OverlayRoot` — which
+ * lives inside those guards — is where the call actually sits for most of them.
+ */
+import { useEffect, useState } from 'react';
+
+import {
+  acquireOverlayRank,
+  layerForRank,
+  registerOverlayRank,
+  releaseOverlayRank,
+  type OverlayLayer,
+} from './stack';
+
+/**
+ * Reserve this surface's place in the overlay stack for as long as it is
+ * mounted. Returns the z-indices it should paint with.
+ */
+export function useOverlayLayer(): OverlayLayer {
+  // A state initializer, not a render-body call: it runs once per mount, so the
+  // rank is fixed before the first paint (an effect would leave one frame at
+  // the wrong depth) and it is not a position the React Compiler can memoize
+  // into a stale read.
+  const [rank] = useState(acquireOverlayRank);
+
+  useEffect(() => {
+    registerOverlayRank(rank);
+    return () => releaseOverlayRank(rank);
+  }, [rank]);
+
+  const [layer] = useState(() => layerForRank(rank));
+  return layer;
+}

package/src/popover/index.web.tsx

@@ -10,9 +10,8 @@ import React, {
 import { Pressable, StyleSheet, View } from 'react-native';
 
 import { useTheme } from '../theme/use-theme';
-import { Backdrop } from '../overlay';
+import { Backdrop, OverlayRoot } from '../overlay';
 import { Portal } from '../portal/index.web';
-import { createOverlayZIndex } from '../styles/z-index';
 import { WEB_POSITION_FIXED } from '../styles/web-view-style';
 import { bloomShadowStyle } from '../design-tokens/shadows';
 import { PopoverContext, usePopoverContext } from './context';
@@ -36,7 +35,6 @@ export type {
 
 export { usePopoverContext };
 
-const popoverZIndex = createOverlayZIndex();
 
 /**
  * Web self-contained control. Unlike native (which proxies a `BottomSheet`
@@ -262,45 +260,52 @@ export function PopoverContent({
 
   return (
     <Portal>
-      {dismissible ? (
-        <Backdrop
-          style={styles.backdrop}
-          onPress={() => control.close()}
-          accessibilityLabel="Dismiss popover"
-        />
-      ) : null}
-      <View
-        ref={panelRef}
-        accessibilityRole="none"
-        aria-label={label}
-        testID={testID}
-        onLayout={(e) =>
-          setPanelSize({
-            width: e.nativeEvent.layout.width,
-            height: e.nativeEvent.layout.height,
-          })
-        }
-        style={[
-          styles.panel,
-          {
-            left: position.left,
-            top: position.top,
-            minWidth: resolvedMinWidth,
-            maxWidth,
-            backgroundColor: theme.isDark
-              ? theme.colors.backgroundSecondary
-              : theme.colors.background,
-            borderColor: theme.colors.borderLight,
-            // Design-system overlay elevation (`shadow-m`) as a `boxShadow` —
-            // RN-Web deprecated the `shadow*` style props.
-            ...bloomShadowStyle('m'),
-            // Hide until measured to avoid a one-frame jump.
-            opacity: panelSize ? 1 : 0,
-          },
-          style,
-        ]}>
-        {children}
-      </View>
+      {/* `OverlayRoot` takes this surface's place in the open-order overlay
+          stack, so it paints above anything opened before it (see
+          `src/overlay/stack.ts`). It is `box-none`, so the area outside the
+          panel stays click-through and the backdrop below still takes its own
+          presses. */}
+      <OverlayRoot>
+        {dismissible ? (
+          <Backdrop
+            style={styles.backdrop}
+            onPress={() => control.close()}
+            accessibilityLabel="Dismiss popover"
+          />
+        ) : null}
+        <View
+          ref={panelRef}
+          accessibilityRole="none"
+          aria-label={label}
+          testID={testID}
+          onLayout={(e) =>
+            setPanelSize({
+              width: e.nativeEvent.layout.width,
+              height: e.nativeEvent.layout.height,
+            })
+          }
+          style={[
+            styles.panel,
+            {
+              left: position.left,
+              top: position.top,
+              minWidth: resolvedMinWidth,
+              maxWidth,
+              backgroundColor: theme.isDark
+                ? theme.colors.backgroundSecondary
+                : theme.colors.background,
+              borderColor: theme.colors.borderLight,
+              // Design-system overlay elevation (`shadow-m`) as a `boxShadow` —
+              // RN-Web deprecated the `shadow*` style props.
+              ...bloomShadowStyle('m'),
+              // Hide until measured to avoid a one-frame jump.
+              opacity: panelSize ? 1 : 0,
+            },
+            style,
+          ]}>
+          {children}
+        </View>
+      </OverlayRoot>
     </Portal>
   );
 }
@@ -315,12 +320,10 @@ const styles = StyleSheet.create({
     left: 0,
     right: 0,
     bottom: 0,
-    zIndex: popoverZIndex.backdrop,
     pointerEvents: 'auto',
   },
   panel: {
     position: WEB_POSITION_FIXED,
-    zIndex: popoverZIndex.surface,
     borderRadius: 12,
     borderWidth: 1,
     paddingVertical: 4,

package/src/prompt-input/PromptInput.tsx

@@ -10,6 +10,7 @@ import {
 } from 'react-native';
 
 import { useTheme } from '../theme/use-theme';
+import { OverlayRoot } from '../overlay';
 import { Portal } from '../portal';
 import { Z_INDEX } from '../styles/z-index';
 import { PromptInputContext, type Attachment } from './context';
@@ -230,36 +231,42 @@ export function PromptInput({
 
       {showFullscreen && (
         <Portal>
-          <View
-            style={[
-              StyleSheet.absoluteFill,
-              {
-                zIndex: Z_INDEX.fullscreen,
-                backgroundColor: theme.colors.background,
-                // Opt back in from the Portal root's `pointer-events: none`
-                // (web only — harmless on native).
-                pointerEvents: 'auto',
-              },
-            ]}
-          >
-            <Pressable
-              onPress={() => setShowFullscreen(false)}
-              style={{
-                position: 'absolute',
-                top: 16,
-                right: 16,
-                zIndex: Z_INDEX.fullscreenControl,
-                padding: 8,
-                backgroundColor: theme.colors.background,
-                borderRadius: 9999,
-              }}
+          {/* `OverlayRoot` takes the fullscreen editor's place in the
+              open-order overlay stack (`src/overlay/stack.ts`). It mounts with
+              `showFullscreen`, so the rank tracks opening. */}
+          <OverlayRoot>
+            <View
+              style={[
+                StyleSheet.absoluteFill,
+                {
+                  backgroundColor: theme.colors.background,
+                  // Opt back in from the Portal root's `pointer-events: none`
+                  // (web only — harmless on native).
+                  pointerEvents: 'auto',
+                },
+              ]}
             >
-              {collapseIcon ?? (
-                <Text style={{ fontSize: 18, color: theme.colors.text }}>⤡</Text>
-              )}
-            </Pressable>
-            <View style={{ flex: 1 }}>{content}</View>
-          </View>
+              <Pressable
+                onPress={() => setShowFullscreen(false)}
+                style={{
+                  position: 'absolute',
+                  top: 16,
+                  right: 16,
+                  // Above the editor's own body; where the editor sits relative
+                  // to OTHER surfaces is the overlay stack's call.
+                  zIndex: Z_INDEX.raised,
+                  padding: 8,
+                  backgroundColor: theme.colors.background,
+                  borderRadius: 9999,
+                }}
+              >
+                {collapseIcon ?? (
+                  <Text style={{ fontSize: 18, color: theme.colors.text }}>⤡</Text>
+                )}
+              </Pressable>
+              <View style={{ flex: 1 }}>{content}</View>
+            </View>
+          </OverlayRoot>
         </Portal>
       )}
     </PromptInputContext.Provider>

package/src/select/index.web.tsx

@@ -12,9 +12,8 @@ import { Pressable, StyleSheet, View, type ViewStyle } from 'react-native';
 
 import { useTheme } from '../theme/use-theme';
 import { Text } from '../typography';
-import { Backdrop } from '../overlay';
+import { Backdrop, OverlayRoot } from '../overlay';
 import { Portal } from '../portal/index.web';
-import { createOverlayZIndex } from '../styles/z-index';
 import { WEB_POSITION_FIXED } from '../styles/web-view-style';
 import { resolveDropdownPlacement } from '../overlay/dropdown-placement';
 import { bloomShadowStyle } from '../design-tokens/shadows';
@@ -39,7 +38,6 @@ import type {
 
 export { useSelectItemContext };
 
-const selectZIndex = createOverlayZIndex();
 const VIEWPORT_GUTTER = 8;
 const SELECT_OFFSET = 6;
 
@@ -259,33 +257,40 @@ export function SelectContent<T>({
 
   return (
     <Portal>
-      <Backdrop
-        style={styles.backdrop}
-        onPress={ctx.close}
-        accessibilityLabel="Close selection"
-      />
-      <View
-        ref={attachDropdown}
-        accessibilityRole="list"
-        accessibilityLabel={label}
-        style={[
-          styles.dropdown,
-          {
-            backgroundColor: theme.isDark
-              ? theme.colors.backgroundSecondary
-              : theme.colors.background,
-            borderColor: theme.colors.borderLight,
-            ...bloomShadowStyle('m'),
-          },
-          position,
-        ]}
-      >
-        {items.map((item, index) => (
-          <React.Fragment key={valueExtractor(item)}>
-            {renderItem(item, index, ctx.value)}
-          </React.Fragment>
-        ))}
-      </View>
+      {/* `OverlayRoot` takes this surface's place in the open-order overlay
+          stack, so it paints above anything opened before it (see
+          `src/overlay/stack.ts`). It is `box-none`, so the area outside the
+          panel stays click-through and the backdrop below still takes its own
+          presses. */}
+      <OverlayRoot>
+        <Backdrop
+          style={styles.backdrop}
+          onPress={ctx.close}
+          accessibilityLabel="Close selection"
+        />
+        <View
+          ref={attachDropdown}
+          accessibilityRole="list"
+          accessibilityLabel={label}
+          style={[
+            styles.dropdown,
+            {
+              backgroundColor: theme.isDark
+                ? theme.colors.backgroundSecondary
+                : theme.colors.background,
+              borderColor: theme.colors.borderLight,
+              ...bloomShadowStyle('m'),
+            },
+            position,
+          ]}
+        >
+          {items.map((item, index) => (
+            <React.Fragment key={valueExtractor(item)}>
+              {renderItem(item, index, ctx.value)}
+            </React.Fragment>
+          ))}
+        </View>
+      </OverlayRoot>
     </Portal>
   );
 }
@@ -415,7 +420,6 @@ const styles = StyleSheet.create({
     left: 0,
     right: 0,
     bottom: 0,
-    zIndex: selectZIndex.backdrop,
     // Opt back in from the Portal root's `pointer-events: none`.
     pointerEvents: 'auto',
   },
@@ -428,7 +432,6 @@ const styles = StyleSheet.create({
     position: WEB_POSITION_FIXED,
     top: 0,
     left: 0,
-    zIndex: selectZIndex.surface,
     borderRadius: 8,
     borderWidth: 1,
     overflow: 'hidden',

package/src/styles/z-index.ts

@@ -1,47 +1,45 @@
 /**
- * Shared stacking scale for Bloom primitives.
+ * Stacking scale for stacking WITHIN a single context.
  *
- * Keep component layers on this scale instead of introducing local magic
- * numbers. App-specific surfaces can still sit above Bloom's inline layers,
- * while portaled overlays use `portalRoot` as the document-level host.
+ * ## What belongs here, and what does not
+ *
+ * These values order elements against their own siblings — a badge over its
+ * avatar, a floating control over the panel it sits on, a sheet's drag handle
+ * over the sheet body. That is a local decision with a local answer, so a
+ * constant is the right tool.
+ *
+ * **Which OVERLAY SURFACE is on top of which is NOT on this scale**, and must
+ * never be added back to it. That question is answered by open order — the
+ * surface the user opened last wins — and is owned by `src/overlay/stack.ts`.
+ *
+ * This file used to carry rungs for that too (`dropdown` 40/41, `overlay`
+ * 50/60, `tooltip` 70, `toast` 80, `fullscreen` 90/91), plus
+ * `createOverlayZIndex` / `createDropdownZIndex` / `Z_INDEX_LAYER_STEP` to
+ * offset them. Because a rung is fixed per COMPONENT KIND, it decided stacking
+ * by what a surface WAS rather than by when it opened, so some pairings were
+ * permanently inverted: a confirm dialog (50/60) opened from inside an open
+ * bottom sheet (999999) rendered underneath it and could not be pressed or
+ * dismissed, and a menu (40/41) opened from inside a dialog landed behind that
+ * dialog. Those rungs and helpers are gone; reintroducing one reintroduces the
+ * bug.
  */
 export const Z_INDEX = {
+  /** Default resting level. */
   base: 0,
+  /** One step above an immediate sibling — a badge over its avatar. */
   raised: 1,
+  /** A control floating over the content it belongs to. */
   floating: 10,
-  sticky: 20,
+  /** A dropdown's INLINE trigger wrapper, still in the app's document flow. */
   dropdown: 40,
-  dropdownSurface: 41,
-  overlayBackdrop: 50,
-  overlaySurface: 60,
-  tooltip: 70,
-  toast: 80,
-  fullscreen: 90,
-  fullscreenControl: 91,
+  /** A bottom sheet's drag handle, over the sheet's own body. */
   sheetHandle: 100,
+  /**
+   * The document-level portal container itself (`#bloom-portal-root`). Overlay
+   * surfaces render INSIDE it and order among themselves by open order — none
+   * of them may claim this value, which is what made the sheet unbeatable.
+   */
   portalRoot: 999999,
 } as const;
 
-export const Z_INDEX_LAYER_STEP = 10;
-
-function layerOffset(layer = 0) {
-  return Math.max(0, Math.floor(layer)) * Z_INDEX_LAYER_STEP;
-}
-
-export function createDropdownZIndex(layer = 0) {
-  const offset = layerOffset(layer);
-  return {
-    root: Z_INDEX.dropdown + offset,
-    surface: Z_INDEX.dropdownSurface + offset,
-  } as const;
-}
-
-export function createOverlayZIndex(layer = 0) {
-  const offset = layerOffset(layer);
-  return {
-    backdrop: Z_INDEX.overlayBackdrop + offset,
-    surface: Z_INDEX.overlaySurface + offset,
-  } as const;
-}
-
 export const zIndex = Z_INDEX;

package/src/surfaces/SurfaceHost.tsx

@@ -67,13 +67,7 @@ export function createSurfaceHost(Dialog: DialogComponent) {
    * dismiss REQUEST and has no post-exit callback, so it could never tell the
    * store WHEN to splice the entry after the exit animation.
    */
-  function SurfaceLayer({
-    entry,
-    index,
-  }: {
-    entry: SurfaceEntry;
-    index: number;
-  }) {
+  function SurfaceLayer({ entry }: { entry: SurfaceEntry }) {
     const control = useDialogControl();
     const { id, status } = entry;
 
@@ -125,7 +119,6 @@ export function createSurfaceHost(Dialog: DialogComponent) {
       <Dialog
         control={control}
         onClose={handleClose}
-        layer={index}
         startOpen={status !== 'closing'}
         {...placement}
       >
@@ -144,8 +137,8 @@ export function createSurfaceHost(Dialog: DialogComponent) {
 
     return (
       <>
-        {stack.map((entry, index) => (
-          <SurfaceLayer key={entry.id} entry={entry} index={index} />
+        {stack.map((entry) => (
+          <SurfaceLayer key={entry.id} entry={entry} />
         ))}
       </>
     );

package/src/toast/ToastHost.tsx

@@ -26,10 +26,9 @@ import * as React from 'react';
 import { StyleSheet } from 'react-native';
 import { GestureHandlerRootView } from 'react-native-gesture-handler';
 
-import { OverlayRoot } from '../overlay';
+import { OverlayRoot, TOAST_LAYER_Z } from '../overlay';
 import { Portal } from '../portal/index.web';
 import { WEB_POSITION_FIXED } from '../styles/web-view-style';
-import { Z_INDEX } from '../styles/z-index';
 import type { ToastHostProps } from './types';
 
 export function ToastHost({ children, ToasterOverlayWrapper }: ToastHostProps) {
@@ -37,7 +36,7 @@ export function ToastHost({ children, ToasterOverlayWrapper }: ToastHostProps) {
     // `OverlayRoot` carries the pointer-events opt-in as a PROP; as a style
     // entry it never reached the DOM, so the rows inherited the portal root's
     // `pointer-events: none` and no toast could be pressed or swiped away.
-    <OverlayRoot style={styles.host}>
+    <OverlayRoot zIndex={TOAST_LAYER_Z} style={styles.host}>
       {/* Also `box-none`: as the direct child of a box-none root it would
           otherwise be handed `pointer-events: auto` and, spanning the whole
           viewport, block the app underneath while a toast is up. */}
@@ -68,8 +67,12 @@ const styles = StyleSheet.create({
     left: 0,
     right: 0,
     bottom: 0,
-    // Inside `#bloom-portal-root` (which owns the document layer at 999999),
-    // this keeps toasts above Dialog's surface (60) and tooltips (70).
-    zIndex: Z_INDEX.toast,
+    // The depth is `TOAST_LAYER_Z`, applied by `OverlayRoot` via its `zIndex`
+    // prop — a toast is a notification, not a modal surface, so it is pinned
+    // above the whole open-order overlay stack rather than taking a rank in it
+    // (see `src/overlay/stack.ts`). It must not be set here as well: a style
+    // z-index would fight the prop and, being a fixed number again, would land
+    // back under any surface that outranked it — which is how toasts were
+    // already being lost behind an open bottom sheet.
   },
 });