@oxyhq/bloom 0.72.2 → 0.73.0

package/lib/typescript/module/styles/z-index.d.ts

@@ -1,49 +1,62 @@
 /**
- * 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 declare const Z_INDEX: {
+    /** Default resting level. */
     readonly base: 0;
+    /** One step above an immediate sibling — a badge over its avatar. */
     readonly raised: 1;
+    /** A control floating over the content it belongs to. */
     readonly floating: 10;
-    readonly sticky: 20;
+    /** A dropdown's INLINE trigger wrapper, still in the app's document flow. */
     readonly dropdown: 40;
-    readonly dropdownSurface: 41;
-    readonly overlayBackdrop: 50;
-    readonly overlaySurface: 60;
-    readonly tooltip: 70;
-    readonly toast: 80;
-    readonly fullscreen: 90;
-    readonly fullscreenControl: 91;
+    /** A bottom sheet's drag handle, over the sheet's own body. */
     readonly 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.
+     */
     readonly portalRoot: 999999;
 };
-export declare const Z_INDEX_LAYER_STEP = 10;
-export declare function createDropdownZIndex(layer?: number): {
-    readonly root: number;
-    readonly surface: number;
-};
-export declare function createOverlayZIndex(layer?: number): {
-    readonly backdrop: number;
-    readonly surface: number;
-};
 export declare const zIndex: {
+    /** Default resting level. */
     readonly base: 0;
+    /** One step above an immediate sibling — a badge over its avatar. */
     readonly raised: 1;
+    /** A control floating over the content it belongs to. */
     readonly floating: 10;
-    readonly sticky: 20;
+    /** A dropdown's INLINE trigger wrapper, still in the app's document flow. */
     readonly dropdown: 40;
-    readonly dropdownSurface: 41;
-    readonly overlayBackdrop: 50;
-    readonly overlaySurface: 60;
-    readonly tooltip: 70;
-    readonly toast: 80;
-    readonly fullscreen: 90;
-    readonly fullscreenControl: 91;
+    /** A bottom sheet's drag handle, over the sheet's own body. */
     readonly 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.
+     */
     readonly portalRoot: 999999;
 };
 //# sourceMappingURL=z-index.d.ts.map

package/lib/typescript/module/styles/z-index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"z-index.d.ts","sourceRoot":"","sources":["../../../../src/styles/z-index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;CAeV,CAAC;AAEX,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAMrC,wBAAgB,oBAAoB,CAAC,KAAK,SAAI;;;EAM7C;AAED,wBAAgB,mBAAmB,CAAC,KAAK,SAAI;;;EAM5C;AAED,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;CAAU,CAAC"}
+{"version":3,"file":"z-index.d.ts","sourceRoot":"","sources":["../../../../src/styles/z-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,OAAO;IAClB,6BAA6B;;IAE7B,qEAAqE;;IAErE,yDAAyD;;IAEzD,6EAA6E;;IAE7E,+DAA+D;;IAE/D;;;;OAIG;;CAEK,CAAC;AAEX,eAAO,MAAM,MAAM;IAlBjB,6BAA6B;;IAE7B,qEAAqE;;IAErE,yDAAyD;;IAEzD,6EAA6E;;IAE7E,+DAA+D;;IAE/D;;;;OAIG;;CAIwB,CAAC"}

package/lib/typescript/module/surfaces/SurfaceHost.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SurfaceHost.d.ts","sourceRoot":"","sources":["../../../../src/surfaces/SurfaceHost.tsx"],"names":[],"mappings":"AAAA,OAAO,KAKN,MAAM,OAAO,CAAC;AAIf,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAYnD,KAAK,eAAe,GAAG,KAAK,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC;AAgCxD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,eAAe;;;;;;uBAqGhB;YAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;SAAE;;;EAcrE"}
+{"version":3,"file":"SurfaceHost.d.ts","sourceRoot":"","sources":["../../../../src/surfaces/SurfaceHost.tsx"],"names":[],"mappings":"AAAA,OAAO,KAKN,MAAM,OAAO,CAAC;AAIf,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAYnD,KAAK,eAAe,GAAG,KAAK,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC;AAgCxD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,eAAe;;;;;;uBA8FhB;YAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;SAAE;;;EAcrE"}

package/lib/typescript/module/toast/ToastHost.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ToastHost.d.ts","sourceRoot":"","sources":["../../../../src/toast/ToastHost.tsx"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,wBAAgB,SAAS,CAAC,EAAE,QAAQ,EAAE,qBAAqB,EAAE,EAAE,cAAc,2CAwB5E;yBAxBe,SAAS"}
+{"version":3,"file":"ToastHost.d.ts","sourceRoot":"","sources":["../../../../src/toast/ToastHost.tsx"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,wBAAgB,SAAS,CAAC,EAAE,QAAQ,EAAE,qBAAqB,EAAE,EAAE,cAAc,2CAwB5E;yBAxBe,SAAS"}

package/lib/typescript/module/tooltip/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/tooltip/index.tsx"],"names":[],"mappings":"AAoEA;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,EACzC,QAAQ,GACT,EAAE;IACD,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B,2CAEA;yBANe,0BAA0B;;;AAS1C,wBAAgB,OAAO,CAAC,EACtB,QAAQ,EACR,QAAmB,EACnB,OAAO,EAAE,cAAc,EACvB,eAAe,GAChB,EAAE;IACD,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;CAC7C,2CAsCA;AAED,wBAAgB,cAAc,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAAE,2CAuBzE;AAED,wBAAgB,cAAc,CAAC,EAC7B,QAAQ,EACR,KAAK,GACN,EAAE;IACD,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;CACf,kDAoBA;AAgND,eAAO,MAAM,iBAAiB;;6CAAmC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/tooltip/index.tsx"],"names":[],"mappings":"AAqEA;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,EACzC,QAAQ,GACT,EAAE;IACD,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B,2CAEA;yBANe,0BAA0B;;;AAS1C,wBAAgB,OAAO,CAAC,EACtB,QAAQ,EACR,QAAmB,EACnB,OAAO,EAAE,cAAc,EACvB,eAAe,GAChB,EAAE;IACD,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;CAC7C,2CAsCA;AAED,wBAAgB,cAAc,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAAE,2CAuBzE;AAED,wBAAgB,cAAc,CAAC,EAC7B,QAAQ,EACR,KAAK,GACN,EAAE;IACD,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;CACf,kDA0BA;AAgND,eAAO,MAAM,iBAAiB;;6CAAmC,CAAC"}

package/lib/typescript/module/zoomable-image-gallery/ZoomableImageGallery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ZoomableImageGallery.d.ts","sourceRoot":"","sources":["../../../../src/zoomable-image-gallery/ZoomableImageGallery.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA6E,MAAM,OAAO,CAAC;AAoElG,OAAO,KAAK,EAGV,0BAA0B,EAC1B,yBAAyB,EAC1B,MAAM,SAAS,CAAC;AA87BjB,eAAO,MAAM,oBAAoB,8GAA4B,CAAC;AAyK9D,eAAe,oBAAoB,CAAC"}
+{"version":3,"file":"ZoomableImageGallery.d.ts","sourceRoot":"","sources":["../../../../src/zoomable-image-gallery/ZoomableImageGallery.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA6E,MAAM,OAAO,CAAC;AAmElG,OAAO,KAAK,EAGV,0BAA0B,EAC1B,yBAAyB,EAC1B,MAAM,SAAS,CAAC;AA87BjB,eAAO,MAAM,oBAAoB,8GAA4B,CAAC;AA0K9D,eAAe,oBAAoB,CAAC"}

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@oxyhq/bloom",
-  "version": "0.72.2",
+  "version": "0.73.0",
+  "packageManager": "bun@1.3.14",
   "description": "Bloom UI — Oxy ecosystem component library for React Native + Expo + Web",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",

package/src/__tests__/ToastHostWebFork.test.ts

@@ -52,9 +52,17 @@ describe('ToastHost platform split', () => {
     expect(host).not.toMatch(/'fixed' as/);
   });
 
-  it('web/default host layers toasts at Z_INDEX.toast', () => {
-    const host = read('toast/ToastHost.tsx');
-    expect(host).toMatch(/zIndex: Z_INDEX\.toast/);
+  it('web/default host pins toasts above the whole overlay stack', () => {
+    const host = code('toast/ToastHost.tsx');
+    // A toast is a notification, not a modal surface: it must stay visible over
+    // whatever is open, including a surface opened AFTER it. So it opts out of
+    // the open-order stack via `OverlayRoot`'s `zIndex` prop rather than taking
+    // a rank (see `src/overlay/stack.ts`).
+    expect(host).toMatch(/<OverlayRoot zIndex=\{TOAST_LAYER_Z\}/);
+    // And it must not ALSO carry a hand-picked depth in its stylesheet: a fixed
+    // number there is exactly what left toasts stranded behind an open bottom
+    // sheet, and it would fight the prop above.
+    expect(host).not.toMatch(/zIndex: Z_INDEX\./);
   });
 
   it('native host imports neither react-native-screens nor the portal (D6)', () => {

package/src/__tests__/overlay-stack-order.test.tsx

@@ -0,0 +1,270 @@
+/**
+ * @jest-environment jsdom
+ */
+
+/**
+ * The overlay stacking rule: a surface opened LATER paints above one opened
+ * earlier.
+ *
+ * Jest cannot see the bug this guards — the losing surface renders perfectly
+ * and its styles are all valid; it is simply painted underneath. So these tests
+ * pin the two halves Jest CAN decide:
+ *
+ *   1. the authority in `src/overlay/stack.ts` hands out ascending depths, and
+ *      keeps doing so across the interleavings that actually occur;
+ *   2. every overlay surface in `src/` gets its depth FROM that authority
+ *      rather than from a constant of its own — the property whose absence
+ *      caused the bug in the first place.
+ *
+ * The hit test that proves the user-visible outcome lives in
+ * `scripts/verify-overlay-stacking.mjs`, driven against a real browser.
+ */
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { createElement } from 'react';
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+// The point of the DOM half is what react-native-web actually emits, so it runs
+// against the REAL RNW — the repo-wide `react-native` mock renders no host
+// elements and would make every depth assertion below vacuous.
+jest.mock('react-native', () => jest.requireActual('react-native-web'));
+
+import { OverlayRoot } from '../overlay';
+import {
+  acquireOverlayRank,
+  layerForRank,
+  OVERLAY_STACK_BASE,
+  OVERLAY_STACK_MAX_RANK,
+  registerOverlayRank,
+  releaseOverlayRank,
+  resetOverlayStack,
+  TOAST_LAYER_Z,
+} from '../overlay/stack';
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+beforeEach(() => {
+  resetOverlayStack();
+});
+
+describe('the stacking authority', () => {
+  it('gives a later opener a higher depth than an earlier one', () => {
+    const first = layerForRank(acquireOverlayRank());
+    const second = layerForRank(acquireOverlayRank());
+    const third = layerForRank(acquireOverlayRank());
+
+    expect(second.root).toBeGreaterThan(first.root);
+    expect(third.root).toBeGreaterThan(second.root);
+  });
+
+  it('puts a surface above its OWN backdrop without reaching the next surface', () => {
+    const lower = layerForRank(acquireOverlayRank());
+    const upper = layerForRank(acquireOverlayRank());
+
+    expect(lower.surface).toBeGreaterThan(lower.backdrop);
+    // The band is what keeps a surface's own parts from colliding with the
+    // floor of the surface above it.
+    expect(lower.surface).toBeLessThan(upper.backdrop);
+  });
+
+  it('keeps ordering when surfaces close out of order', () => {
+    // A opens, B opens, A closes, C opens. C is newest and must outrank B.
+    const a = acquireOverlayRank();
+    registerOverlayRank(a);
+    const b = acquireOverlayRank();
+    registerOverlayRank(b);
+
+    releaseOverlayRank(a);
+
+    const c = acquireOverlayRank();
+    registerOverlayRank(c);
+
+    expect(layerForRank(c).root).toBeGreaterThan(layerForRank(b).root);
+  });
+
+  it('starts over once every surface has closed, so depths stay small', () => {
+    const a = acquireOverlayRank();
+    registerOverlayRank(a);
+    releaseOverlayRank(a);
+
+    expect(layerForRank(acquireOverlayRank()).root).toBe(layerForRank(a).root);
+  });
+
+  it('cannot lose a rank handed out but not yet registered', () => {
+    // The one interleaving the reset could otherwise break: a surface takes a
+    // rank during render, and before its effect registers it the last open
+    // surface unmounts and resets the counter. The newcomer must still land
+    // ABOVE the one that is on its way up.
+    const open = acquireOverlayRank();
+    registerOverlayRank(open);
+
+    const rendering = acquireOverlayRank(); // taken, effect not run yet
+    releaseOverlayRank(open); // live set empties -> reset
+    registerOverlayRank(rendering); // effect finally runs
+
+    const next = acquireOverlayRank();
+    expect(next).toBeGreaterThan(rendering);
+    expect(layerForRank(next).root).toBeGreaterThan(layerForRank(rendering).root);
+  });
+
+  it('saturates instead of climbing into the toast layer', () => {
+    const runaway = layerForRank(OVERLAY_STACK_MAX_RANK + 5_000);
+    expect(runaway.surface).toBeLessThan(TOAST_LAYER_Z);
+    expect(runaway.root).toBe(layerForRank(OVERLAY_STACK_MAX_RANK).root);
+  });
+
+  it('keeps every rank below the toast layer', () => {
+    // Toasts are notifications, not modal surfaces: they stay visible over
+    // whatever is open, including a surface opened after them.
+    expect(layerForRank(1).root).toBeGreaterThanOrEqual(OVERLAY_STACK_BASE);
+    expect(layerForRank(OVERLAY_STACK_MAX_RANK).surface).toBeLessThan(TOAST_LAYER_Z);
+  });
+});
+
+describe('OverlayRoot', () => {
+  function render(node: ReturnType<typeof createElement>): {
+    root: Root;
+    container: HTMLElement;
+  } {
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    const root = createRoot(container);
+    act(() => {
+      root.render(node);
+    });
+    return { root, container };
+  }
+
+  const depthOf = (container: HTMLElement, testID: string) => {
+    const el = container.querySelector<HTMLElement>(`[data-testid="${testID}"]`);
+    if (!el) throw new Error(`no element with testID ${testID}`);
+    return Number(getComputedStyle(el).zIndex);
+  };
+
+  it('paints a surface mounted later above one mounted earlier', () => {
+    const first = render(createElement(OverlayRoot, { testID: 'first', children: null }));
+    const second = render(createElement(OverlayRoot, { testID: 'second', children: null }));
+
+    const firstZ = depthOf(first.container, 'first');
+    const secondZ = depthOf(second.container, 'second');
+
+    // Vacuity floor: both must have emitted a real depth, or "second > first"
+    // would be comparing two NaNs into a silent pass.
+    expect(Number.isFinite(firstZ)).toBe(true);
+    expect(Number.isFinite(secondZ)).toBe(true);
+    expect(secondZ).toBeGreaterThan(firstZ);
+
+    act(() => {
+      first.root.unmount();
+      second.root.unmount();
+    });
+    first.container.remove();
+    second.container.remove();
+  });
+
+  it('pins to the given depth, and takes no rank, when told to', () => {
+    const pinned = render(
+      createElement(OverlayRoot, { testID: 'pinned', zIndex: TOAST_LAYER_Z, children: null }),
+    );
+    expect(depthOf(pinned.container, 'pinned')).toBe(TOAST_LAYER_Z);
+
+    // Having opted out, it must not have consumed a rank either — the next
+    // surface to open is still the FIRST one in the stack.
+    const ranked = render(createElement(OverlayRoot, { testID: 'ranked', children: null }));
+    expect(depthOf(ranked.container, 'ranked')).toBe(layerForRank(1).root);
+
+    act(() => {
+      pinned.root.unmount();
+      ranked.root.unmount();
+    });
+    pinned.container.remove();
+    ranked.container.remove();
+  });
+});
+
+describe('no surface picks its own depth', () => {
+  const SRC = path.join(__dirname, '..');
+  const read = (rel: string) => readFileSync(path.join(SRC, rel), 'utf8');
+
+  /**
+   * Every file in `src/` that presents an overlay surface. Enumerated
+   * explicitly rather than globbed: a glob that silently stops matching is the
+   * shape of check that passes forever while covering nothing.
+   */
+  const SURFACES = [
+    'dialog/Dialog.tsx',
+    'dialog/Dialog.web.tsx',
+    'bottom-sheet/index.web.tsx',
+    'menu/index.web.tsx',
+    'select/index.web.tsx',
+    'context-menu/index.web.tsx',
+    'popover/index.web.tsx',
+    'tooltip/index.tsx',
+    'zoomable-image-gallery/ZoomableImageGallery.tsx',
+    'prompt-input/PromptInput.tsx',
+    'avatar-group/AvatarGroup.web.tsx',
+    'toast/ToastHost.tsx',
+  ];
+
+  /** Strips comments, so prose ABOUT the old constants never trips the scan. */
+  const code = (rel: string) =>
+    read(rel)
+      .replace(/\/\*[\s\S]*?\*\//g, '')
+      .replace(/^\s*\/\/.*$/gm, '')
+      .replace(/\{\s*\/\*[\s\S]*?\*\/\s*\}/g, '');
+
+  it.each(SURFACES)('%s claims no overlay-ordering constant', (rel) => {
+    const body = code(rel);
+
+    // The rungs that used to decide which SURFACE was on top. Their absence is
+    // the property that makes open order the only authority.
+    expect(body).not.toMatch(
+      /Z_INDEX\.(overlayBackdrop|overlaySurface|dropdownSurface|tooltip|toast|fullscreen|fullscreenControl|portalRoot)\b/,
+    );
+    expect(body).not.toMatch(/createOverlayZIndex|createDropdownZIndex|Z_INDEX_LAYER_STEP/);
+  });
+
+  it('the scale no longer offers an overlay-ordering rung to reach for', () => {
+    const scale = code('styles/z-index.ts');
+    for (const gone of [
+      'overlayBackdrop',
+      'overlaySurface',
+      'dropdownSurface',
+      'tooltip',
+      'toast',
+      'fullscreen',
+      'fullscreenControl',
+      'createOverlayZIndex',
+      'createDropdownZIndex',
+      'Z_INDEX_LAYER_STEP',
+    ]) {
+      expect(scale).not.toContain(gone);
+    }
+    // Vacuity floor: the module must still export the within-context scale, or
+    // the loop above would pass against an empty file.
+    expect(scale).toMatch(/export const Z_INDEX = \{/);
+    expect(scale).toMatch(/portalRoot: 999999/);
+  });
+
+  it('the WEB tooltip is deliberately NOT in this list', () => {
+    // It is the one tooltip that is not portaled: the bubble is absolutely
+    // positioned against its own trigger and renders inline, so it cannot be
+    // lifted over another surface and has no rank to take. The NATIVE tooltip
+    // does portal, and IS in the list above. If this ever starts portaling,
+    // move it into `SURFACES`.
+    expect(code('tooltip/index.web.tsx')).not.toMatch(/from '\.\.\/portal/);
+    expect(code('tooltip/index.tsx')).toMatch(/from '\.\.\/portal/);
+  });
+
+  it('every surface routes its depth through OverlayRoot', () => {
+    // `Dialog.web`'s side placement renders `SheetSurface`, which mounts its
+    // own `OverlayRoot`; the centred branch mounts one directly. Both files are
+    // covered by the membership check below.
+    const missing = SURFACES.filter((rel) => !code(rel).includes('OverlayRoot'));
+    expect(missing).toEqual([]);
+    // Vacuity floor on the list itself.
+    expect(SURFACES.length).toBeGreaterThanOrEqual(12);
+  });
+});

package/src/avatar-group/AvatarGroup.web.tsx

@@ -1,8 +1,8 @@
 import React, { memo, useCallback, useMemo, useRef, useState } from 'react';
 import { Pressable, StyleSheet, View } from 'react-native';
 
+import { OverlayRoot } from '../overlay';
 import { Portal } from '../portal';
-import { Z_INDEX } from '../styles/z-index';
 import { WEB_POSITION_FIXED } from '../styles/web-view-style';
 import { UserHoverCard } from '../user-hover-card';
 import {
@@ -97,35 +97,40 @@ const AvatarGroupWebComponent: React.FC<AvatarGroupProps> = (props) => {
       <AvatarGroupBase {...props} hoverHandlers={hoverHandlers} />
       {hoverCard && hover && (
         <Portal>
-          {/*
-            A Pressable hosts the hover-bridge: `onHoverIn`/`onHoverOut` are
-            typed in React Native (and map to mouseenter/mouseleave on
-            react-native-web), so the card stays open while the cursor is over
-            it without any web-only DOM-prop type suppression.
-          */}
-          <Pressable
-            onHoverIn={cancelClose}
-            onHoverOut={scheduleClose}
-            accessibilityRole="none"
-            pointerEvents="auto"
-            style={[
-              webStyles.floating,
-              { top: hover.top, left: hover.left, width: CARD_WIDTH },
-            ]}
-          >
-            <UserHoverCard
-              avatar={hover.item.uri ?? undefined}
-              displayName={getItemName(hover.item)}
-              username={hover.item.username}
-              onPressProfile={
-                onPressItem
-                  ? () => onPressItem(hover.item, hover.index)
-                  : undefined
-              }
-              action={renderItemAction?.(hover.item, hover.index)}
-              style={webStyles.card}
-            />
-          </Pressable>
+          {/* The hover card stacks by when it opened, like every other Bloom
+              overlay (`src/overlay/stack.ts`). `box-none` keeps the area
+              around it click-through. */}
+          <OverlayRoot>
+            {/*
+              A Pressable hosts the hover-bridge: `onHoverIn`/`onHoverOut` are
+              typed in React Native (and map to mouseenter/mouseleave on
+              react-native-web), so the card stays open while the cursor is over
+              it without any web-only DOM-prop type suppression.
+            */}
+            <Pressable
+              onHoverIn={cancelClose}
+              onHoverOut={scheduleClose}
+              accessibilityRole="none"
+              pointerEvents="auto"
+              style={[
+                webStyles.floating,
+                { top: hover.top, left: hover.left, width: CARD_WIDTH },
+              ]}
+            >
+              <UserHoverCard
+                avatar={hover.item.uri ?? undefined}
+                displayName={getItemName(hover.item)}
+                username={hover.item.username}
+                onPressProfile={
+                  onPressItem
+                    ? () => onPressItem(hover.item, hover.index)
+                    : undefined
+                }
+                action={renderItemAction?.(hover.item, hover.index)}
+                style={webStyles.card}
+              />
+            </Pressable>
+          </OverlayRoot>
         </Portal>
       )}
     </>
@@ -135,7 +140,6 @@ const AvatarGroupWebComponent: React.FC<AvatarGroupProps> = (props) => {
 const webStyles = StyleSheet.create({
   floating: {
     position: WEB_POSITION_FIXED,
-    zIndex: Z_INDEX.tooltip,
   },
   card: {
     width: CARD_WIDTH,

package/src/bottom-sheet/index.web.tsx

@@ -4,7 +4,6 @@ import { StyleSheet } from 'react-native';
 import { GestureHandlerRootView } from 'react-native-gesture-handler';
 import { OverlayRoot } from '../overlay';
 import { Portal } from '../portal/index.web';
-import { Z_INDEX } from '../styles/z-index';
 import { WEB_POSITION_FIXED } from '../styles/web-view-style';
 import {
     BottomSheetBase,
@@ -54,16 +53,22 @@ const BottomSheet = forwardRef((props: BottomSheetProps, ref: React.ForwardedRef
 BottomSheet.displayName = 'BottomSheet';
 
 const webStyles = StyleSheet.create({
+    // Fixed, full-viewport box the sheet's `StyleSheet.absoluteFill` body
+    // anchors to. The pointer-events opt-in and the STACKING both live in
+    // `OverlayRoot`.
+    //
+    // This used to also pin `zIndex: Z_INDEX.portalRoot` (999999) here. Inside
+    // the portal root that number does not mean "the portal layer" — it means
+    // "above every other portaled surface", which is how a confirm dialog
+    // opened from inside an open sheet ended up rendering underneath it,
+    // unreachable, no matter which one opened last. Stacking is the overlay
+    // stack's job now (`src/overlay/stack.ts`); do not reintroduce a constant.
     rootView: {
-        // Fixed, full-viewport box the sheet's `StyleSheet.absoluteFill` body
-        // anchors to. The pointer-events opt-in lives in `OverlayRoot`; this
-        // only adds the stacking context.
         position: WEB_POSITION_FIXED,
         top: 0,
         left: 0,
         right: 0,
         bottom: 0,
-        zIndex: Z_INDEX.portalRoot,
     },
 });
 

package/src/context-menu/index.web.tsx

@@ -18,10 +18,9 @@ import { Pressable, StyleSheet, View } 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 { useInteractionState } from '../hooks/useInteractionState';
-import { createOverlayZIndex } from '../styles/z-index';
 import { WEB_POSITION_FIXED } from '../styles/web-view-style';
 import {
   resolveDropdownPlacement,
@@ -40,7 +39,6 @@ import type {
   ItemContextValue,
 } from './types';
 
-const contextMenuZIndex = createOverlayZIndex();
 const VIEWPORT_GUTTER = 8;
 
 // ---------------------------------------------------------------------------
@@ -211,31 +209,38 @@ export function ContextMenuContent({ children, style }: ContextMenuContentProps)
 
   return (
     <Portal>
-      <Backdrop
-        style={styles.backdrop}
-        onPress={close}
-        accessibilityLabel="Close context menu"
-      />
-      <View
-        ref={attachMenu}
-        style={[
-          styles.dropdown,
-          {
-            // The raw click point is the pre-measurement anchor; the layout
-            // effect above replaces it before the browser paints.
-            top: placement?.top ?? position.y,
-            left: placement?.left ?? position.x,
-            backgroundColor: theme.isDark
-              ? theme.colors.backgroundSecondary
-              : theme.colors.background,
-            borderColor: theme.colors.borderLight,
-            ...bloomShadowStyle('m'),
-          },
-          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>
+        <Backdrop
+          style={styles.backdrop}
+          onPress={close}
+          accessibilityLabel="Close context menu"
+        />
+        <View
+          ref={attachMenu}
+          style={[
+            styles.dropdown,
+            {
+              // The raw click point is the pre-measurement anchor; the layout
+              // effect above replaces it before the browser paints.
+              top: placement?.top ?? position.y,
+              left: placement?.left ?? position.x,
+              backgroundColor: theme.isDark
+                ? theme.colors.backgroundSecondary
+                : theme.colors.background,
+              borderColor: theme.colors.borderLight,
+              ...bloomShadowStyle('m'),
+            },
+            style,
+          ]}
+        >
+          {children}
+        </View>
+      </OverlayRoot>
     </Portal>
   );
 }
@@ -374,13 +379,11 @@ const styles = StyleSheet.create({
     left: 0,
     right: 0,
     bottom: 0,
-    zIndex: contextMenuZIndex.backdrop,
     // Opt back in from the Portal root's `pointer-events: none`.
     pointerEvents: 'auto',
   },
   dropdown: {
     position: WEB_POSITION_FIXED,
-    zIndex: contextMenuZIndex.surface,
     borderRadius: 8,
     padding: 4,
     borderWidth: 1,