@oxy.so/bloom 4.4.0 → 4.6.0

package/lib/typescript/module/theme/color-scope/index.web.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.web.d.ts","sourceRoot":"","sources":["../../../../../src/theme/color-scope/index.web.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACvE,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.web.d.ts","sourceRoot":"","sources":["../../../../../src/theme/color-scope/index.web.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACvE,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC"}

package/lib/typescript/module/theme/seed-scope/index.web.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.web.d.ts","sourceRoot":"","sources":["../../../../../src/theme/seed-scope/index.web.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,YAAY,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.web.d.ts","sourceRoot":"","sources":["../../../../../src/theme/seed-scope/index.web.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,YAAY,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC"}

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

@@ -1 +1 @@
-{"version":3,"file":"index.web.d.ts","sourceRoot":"","sources":["../../../../src/tooltip/index.web.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EACP,cAAc,EACd,cAAc,EACd,iBAAiB,GAClB,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.web.d.ts","sourceRoot":"","sources":["../../../../src/tooltip/index.web.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,OAAO,EACP,cAAc,EACd,cAAc,EACd,iBAAiB,GAClB,MAAM,eAAe,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/bloom",
-  "version": "4.4.0",
+  "version": "4.6.0",
   "packageManager": "bun@1.3.14",
   "description": "Bloom UI — Oxy ecosystem component library for React Native + Expo + Web",
   "main": "lib/commonjs/index.js",

package/src/agent-chat/index.web.ts

@@ -1,6 +1,8 @@
-// Web variant of the `./agent-chat` barrel: binds the web ComposerLoader and
-// DropdownMenu (`AgentChat.web`), reachable by a bundler resolving
-// `package.json#exports` only through this file.
+// AUTO-GENERATED by scripts/generate-platform-exports.mjs — DO NOT EDIT.
+// Source of truth: src/agent-chat/index.ts.
+// Re-run `bun run generate:exports` (or any `bun run build`) after
+// changing that barrel or the set of web-forked subpaths.
+
 export {
   AgentChat,
   AgentChatActions,

package/src/ai-chat/index.web.ts

@@ -1,5 +1,8 @@
-// Web variant of the `./ai-chat` barrel: binds the web Tooltip (`AiChat.web`),
-// reachable by a bundler resolving `package.json#exports` only through this file.
+// AUTO-GENERATED by scripts/generate-platform-exports.mjs — DO NOT EDIT.
+// Source of truth: src/ai-chat/index.ts.
+// Re-run `bun run generate:exports` (or any `bun run build`) after
+// changing that barrel or the set of web-forked subpaths.
+
 export {
   AiChatAssistantMessage,
   AiChatFeedbackRow,

package/src/alert-dialog/index.web.ts

@@ -1,7 +1,16 @@
+// AUTO-GENERATED by scripts/generate-platform-exports.mjs — DO NOT EDIT.
+// Source of truth: src/alert-dialog/index.ts.
+// Re-run `bun run generate:exports` (or any `bun run build`) after
+// changing that barrel or the set of web-forked subpaths.
+
 import { Dialog } from '../dialog/index.web';
 import { createAlertDialog } from './AlertDialog';
 
-/** Web variant of the `./alert-dialog` barrel — see `./index.ts`. */
+/**
+ * The declarative, CONTROLLED confirm dialog. The imperative counterpart is
+ * `confirm()` from `@oxy.so/bloom/surfaces`, which presents onto the shared
+ * surface stack — this family owns no queue and no host of its own.
+ */
 export const AlertDialog = createAlertDialog(Dialog);
 
 export type { AlertDialogProps, AlertDialogActionStyle } from './types';

package/src/avatar-group/index.web.ts

@@ -1,2 +1,7 @@
+// AUTO-GENERATED by scripts/generate-platform-exports.mjs — DO NOT EDIT.
+// Source of truth: src/avatar-group/index.ts.
+// Re-run `bun run generate:exports` (or any `bun run build`) after
+// changing that barrel or the set of web-forked subpaths.
+
 export { AvatarGroup } from './AvatarGroup.web';
 export type { AvatarGroupProps, AvatarGroupItem } from './types';

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

@@ -1,3 +1,8 @@
+// AUTO-GENERATED by scripts/generate-platform-exports.mjs — DO NOT EDIT.
+// Source of truth: src/bottom-sheet/index.ts.
+// Re-run `bun run generate:exports` (or any `bun run build`) after
+// changing that barrel or the set of web-forked subpaths.
+
 export {
   BottomSheet,
 } from './BottomSheet.web';

package/src/code/index.ts

@@ -3,6 +3,8 @@ export { CodeBlock } from './CodeBlock';
 export { CodeLines } from './CodeLines';
 export { tokenizeCode, isHighlightedLanguage } from './highlight';
 export { Pre } from './Pre';
+export { tokenColor, useCodePalette } from './shared';
+export type { CodePalette } from './shared';
 export type {
   CodeBlockLabels,
   CodeBlockProps,

package/src/command/index.web.ts

@@ -1,3 +1,8 @@
+// AUTO-GENERATED by scripts/generate-platform-exports.mjs — DO NOT EDIT.
+// Source of truth: src/command/index.ts.
+// Re-run `bun run generate:exports` (or any `bun run build`) after
+// changing that barrel or the set of web-forked subpaths.
+
 import { Dialog } from '../dialog/index.web';
 import { createCommand } from './Command';
 

package/src/composer-loader/ComposerLoader.web.tsx

@@ -1,3 +1,11 @@
+/**
+ * `ComposerLoader` — WEB: the light band laps on CSS keyframes over a DOM
+ * `<svg>`, where the native fork drives a react-native-svg frame clock.
+ *
+ * The lap geometry both forks draw is shared (`./shared`); what differs is only
+ * what advances it. Keeping the geometry in one module is what stops the two
+ * bands from drifting apart while still looking like one component.
+ */
 import React, { memo, useCallback, useEffect, useId, useMemo, useState } from 'react';
 import { StyleSheet, View, type LayoutChangeEvent } from 'react-native';
 

package/src/composer-loader/index.web.ts

@@ -1,5 +1,8 @@
-// Web variant of the `./composer-loader` barrel: the light band laps on CSS
-// keyframes over a DOM `<svg>` instead of a react-native-svg frame clock.
+// AUTO-GENERATED by scripts/generate-platform-exports.mjs — DO NOT EDIT.
+// Source of truth: src/composer-loader/index.ts.
+// Re-run `bun run generate:exports` (or any `bun run build`) after
+// changing that barrel or the set of web-forked subpaths.
+
 export { ComposerLoader } from './ComposerLoader.web';
 export { resolveComposerLoaderColors, DEFAULT_COMPOSER_LOADER_COLORS } from './shared';
 export type { ComposerLoaderColors, ComposerLoaderProps } from './types';

package/src/composer-panel/index.web.ts

@@ -1,6 +1,8 @@
-// Web variant of the `./composer-panel` barrel: binds the web panel
-// (`ComposerPopover.web` → `floating/FloatingPanel`), which a bundler resolving
-// `package.json#exports` reaches only through this file.
+// AUTO-GENERATED by scripts/generate-platform-exports.mjs — DO NOT EDIT.
+// Source of truth: src/composer-panel/index.ts.
+// Re-run `bun run generate:exports` (or any `bun run build`) after
+// changing that barrel or the set of web-forked subpaths.
+
 export { ComposerPanel } from './ComposerPanel.web';
 export { ComposerAttachments } from './ComposerAttachments.web';
 export { ModelPicker } from './ModelPicker.web';

package/src/connection-dots/index.web.ts

@@ -1,2 +1,7 @@
+// AUTO-GENERATED by scripts/generate-platform-exports.mjs — DO NOT EDIT.
+// Source of truth: src/connection-dots/index.ts.
+// Re-run `bun run generate:exports` (or any `bun run build`) after
+// changing that barrel or the set of web-forked subpaths.
+
 export { ConnectionDots } from './ConnectionDots.web';
 export type { ConnectionDotsProps } from './types';

package/src/connection-status/index.web.ts

@@ -1,3 +1,8 @@
+// AUTO-GENERATED by scripts/generate-platform-exports.mjs — DO NOT EDIT.
+// Source of truth: src/connection-status/index.ts.
+// Re-run `bun run generate:exports` (or any `bun run build`) after
+// changing that barrel or the set of web-forked subpaths.
+
 export type { ConnectionStatusToastsProps } from './shared';
 // The hatch a consumer needs off Metro, where the optional `require` does not
 // deliver the peer even when it is installed. See `netinfo.ts`.

package/src/content-panel/index.web.ts

@@ -1,3 +1,8 @@
+// AUTO-GENERATED by scripts/generate-platform-exports.mjs — DO NOT EDIT.
+// Source of truth: src/content-panel/index.ts.
+// Re-run `bun run generate:exports` (or any `bun run build`) after
+// changing that barrel or the set of web-forked subpaths.
+
 export {
   GUTTER_MASK_SPREAD,
   PANEL_TOP_INSET,

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

@@ -12,6 +12,13 @@ import type { View } from 'react-native';
 import { MENU_MIN_WIDTH_CLASS, MENU_TRIGGER_POPUP } from '../floating/constants';
 import { MenuSurfaceProvider, type MenuSurfaceContextValue } from '../floating/context';
 import { FloatingPanel } from '../floating/FloatingPanel';
+import {
+  hostElement,
+  isInMenuSurface,
+  useMenuFocusIntent,
+  useMenuPanelKeys,
+  useReturnFocusOnClose,
+} from '../floating/menu-keyboard';
 import { createMenuRows } from '../floating/menu-rows';
 import { createFlyoutMenuSub } from '../floating/menu-sub-flyout';
 import { cx } from '../floating/shared';
@@ -26,6 +33,7 @@ import type {
 
 export function ContextMenu({ children, onOpenChange }: ContextMenuProps) {
   const [anchor, setAnchor] = useState<FloatingAnchor | null>(null);
+  const focusIntent = useMenuFocusIntent();
 
   const value = useMemo(
     () => ({
@@ -41,8 +49,9 @@ export function ContextMenu({ children, onOpenChange }: ContextMenuProps) {
         onOpenChange?.(false);
       },
       anchor,
+      focusIntent,
     }),
-    [anchor, onOpenChange],
+    [anchor, onOpenChange, focusIntent],
   );
 
   return <ContextMenuProvider value={value}>{children}</ContextMenuProvider>;
@@ -59,7 +68,9 @@ export function ContextMenuTrigger({
 }: ContextMenuTriggerProps) {
   const menu = useContextMenu();
   const wrapperRef = useRef<View | null>(null);
-  const { openAt } = menu;
+  const { openAt, focusIntent } = menu;
+  // Focus returns here when the menu closes with it inside (`menu-keyboard.ts`).
+  useReturnFocusOnClose(wrapperRef, menu.open, isInMenuSurface);
 
   // A DOM subscription, not derived state: `contextmenu` has no React Native
   // prop and react-native-web filters unknown props off a `View`, so the only
@@ -73,6 +84,11 @@ export function ContextMenuTrigger({
 
     const onContextMenu = (event: MouseEvent) => {
       event.preventDefault();
+      // A context menu takes focus on its first row however it opened — the
+      // right-click is the only way in, and without focus in the panel its
+      // arrows and Escape have nothing to act on. A pointer open paints no
+      // ring: the rows highlight on `:focus-visible` only.
+      if (focusIntent) focusIntent.edge.current = 'first';
       openAt({
         top: event.clientY,
         bottom: event.clientY,
@@ -82,7 +98,7 @@ export function ContextMenuTrigger({
     };
     element.addEventListener('contextmenu', onContextMenu);
     return () => element.removeEventListener('contextmenu', onContextMenu);
-  }, [openAt, disabled]);
+  }, [openAt, disabled, focusIntent]);
 
   return (
     <TriggerSlot
@@ -129,9 +145,16 @@ export function ContextMenuContent({
     [menu.close],
   );
   const onDismiss = useCallback(() => menu.close(), [menu]);
+  const [panel, setPanel] = useState<View | null>(null);
+  useMenuPanelKeys(hostElement(panel), {
+    open: menu.open,
+    onTab: onDismiss,
+    intent: menu.focusIntent,
+  });
 
   return (
     <FloatingPanel
+      panelRef={setPanel}
       open={menu.open}
       anchor={menu.anchor}
       role="menu"

package/src/context-menu/context.ts

@@ -9,6 +9,7 @@
  */
 import { createContext, useContext } from 'react';
 
+import type { MenuFocusIntent } from '../floating/menu-keyboard';
 import type { FloatingAnchor } from '../floating/types';
 
 export interface ContextMenuContextValue {
@@ -21,6 +22,8 @@ export interface ContextMenuContextValue {
   close: () => void;
   /** Where the surface anchors. `null` on native and while closed. */
   anchor: FloatingAnchor | null;
+  /** Web only: the row focus lands on when the menu opens (`menu-keyboard.ts`). */
+  focusIntent?: MenuFocusIntent;
 }
 
 const ContextMenuContext = createContext<ContextMenuContextValue | null>(null);

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

@@ -1,3 +1,8 @@
+// AUTO-GENERATED by scripts/generate-platform-exports.mjs — DO NOT EDIT.
+// Source of truth: src/context-menu/index.ts.
+// Re-run `bun run generate:exports` (or any `bun run build`) after
+// changing that barrel or the set of web-forked subpaths.
+
 export {
   ContextMenu,
   ContextMenuTrigger,

package/src/dialog/Dialog.web.tsx

@@ -1,3 +1,16 @@
+/**
+ * `Dialog` — WEB: a pure-DOM modal overlay rendered into Bloom's `Portal`.
+ *
+ * The native fork (`Dialog.tsx`) presents through Bloom's `BottomSheet`, which
+ * is built on react-native-gesture-handler + reanimated and has no web
+ * behaviour worth emulating. So this is not a port of that file; it is the
+ * other half of one contract, and the props are what the two agree on.
+ *
+ * This fork is also the family's only publisher of `BLOOM_DIALOG_CSS` — the
+ * stylesheet a web consumer adopts. Native has no counterpart, which is why
+ * the generated web barrel carries one line its native sibling cannot
+ * (`WEB_BARREL_EXTRAS` in `scripts/generate-platform-exports.mjs`).
+ */
 import React, {
   createContext,
   useCallback,

package/src/dialog/index.web.ts

@@ -1,14 +1,9 @@
-// Web variant of the `./dialog` barrel.
-//
-// The default barrel (`./index.ts`) re-exports from `./Dialog`, which uses
-// bloom's `BottomSheet` (a native-only primitive built on
-// react-native-gesture-handler + reanimated). The web fork (`./Dialog.web`)
-// is a pure-DOM modal overlay that renders into the bloom Portal.
-//
-// Web bundlers select this file via the `"browser"` export condition in
-// `package.json`'s `exports['./dialog']`; native bundlers fall through to
-// the React Native build above.
-export { Dialog, BLOOM_DIALOG_CSS } from './Dialog.web';
+// AUTO-GENERATED by scripts/generate-platform-exports.mjs — DO NOT EDIT.
+// Source of truth: src/dialog/index.ts.
+// Re-run `bun run generate:exports` (or any `bun run build`) after
+// changing that barrel or the set of web-forked subpaths.
+
+export { Dialog } from './Dialog.web';
 export { useDialogContext, useDialogControl } from './context';
 export { useDialogHeader } from './DialogHeader';
 export { useDialogFrame } from './DialogMorph';
@@ -24,3 +19,4 @@ export type {
   DialogProps,
   ResponsiveDialogPlacement,
 } from './types';
+export { BLOOM_DIALOG_CSS } from './Dialog.web';

package/src/dropdown-menu/DropdownMenu.web.tsx

@@ -6,12 +6,18 @@
  * `floating/menu-rows` set the native file publishes; what changes between the
  * two is stated once, as `presentation`.
  */
-import React, { useCallback, useMemo, useRef } from 'react';
+import React, { useCallback, useMemo, useRef, useState } from 'react';
 import type { View } from 'react-native';
 
 import { MENU_MIN_WIDTH_CLASS, MENU_TRIGGER_POPUP } from '../floating/constants';
 import { MenuSurfaceProvider, type MenuSurfaceContextValue } from '../floating/context';
 import { FloatingPanel } from '../floating/FloatingPanel';
+import {
+  hostElement,
+  useMenuFocusIntent,
+  useMenuPanelKeys,
+  useMenuTriggerKeys,
+} from '../floating/menu-keyboard';
 import { createMenuRows } from '../floating/menu-rows';
 import { createFlyoutMenuSub } from '../floating/menu-sub-flyout';
 import { cx } from '../floating/shared';
@@ -37,7 +43,11 @@ export function DropdownMenu({
     onChange: onOpenChange,
   });
   const anchorRef = useRef<View | null>(null);
-  const value = useMemo(() => ({ open: isOpen, setOpen, anchorRef }), [isOpen, setOpen]);
+  const focusIntent = useMenuFocusIntent();
+  const value = useMemo(
+    () => ({ open: isOpen, setOpen, anchorRef, focusIntent }),
+    [isOpen, setOpen, focusIntent],
+  );
 
   return <DropdownMenuProvider value={value}>{children}</DropdownMenuProvider>;
 }
@@ -52,6 +62,14 @@ export function DropdownMenuTrigger({
   testID,
 }: DropdownMenuTriggerProps) {
   const menu = useDropdownMenu();
+  // Web: Enter/Space/ArrowDown open into the first row, ArrowUp into the last,
+  // and focus comes back here when the menu closes (`floating/menu-keyboard.ts`).
+  useMenuTriggerKeys(menu.anchorRef, {
+    open: menu.open,
+    setOpen: menu.setOpen,
+    disabled,
+    intent: menu.focusIntent,
+  });
 
   return (
     <TriggerSlot
@@ -97,9 +115,14 @@ export function DropdownMenuContent({
     () => ({ close, presentation: 'dropdown' }),
     [close],
   );
+  // Arrows, Home/End, Space and Tab inside the open menu, and the keyboard
+  // open's landing row (`floating/menu-keyboard.ts`).
+  const [panel, setPanel] = useState<View | null>(null);
+  useMenuPanelKeys(hostElement(panel), { open: menu.open, onTab: close, intent: menu.focusIntent });
 
   return (
     <FloatingPanel
+      panelRef={setPanel}
       open={menu.open}
       anchor={anchor}
       role="menu"

package/src/dropdown-menu/index.web.ts

@@ -1,3 +1,8 @@
+// AUTO-GENERATED by scripts/generate-platform-exports.mjs — DO NOT EDIT.
+// Source of truth: src/dropdown-menu/index.ts.
+// Re-run `bun run generate:exports` (or any `bun run build`) after
+// changing that barrel or the set of web-forked subpaths.
+
 export {
   DropdownMenu,
   DropdownMenuTrigger,

package/src/floating/FloatingPanel.tsx

@@ -89,6 +89,7 @@ import {
   VIEWPORT_GUTTER,
 } from './constants';
 import { useMenuPalette } from './menu-palette';
+import { pushFloatingEscape } from './escape-stack';
 import { cx } from './shared';
 import type { FloatingPanelProps, FloatingSide } from './types';
 import { useFrameThrottle } from './use-frame-throttle';
@@ -105,36 +106,31 @@ const AnimatedPanel = Animated.createAnimatedComponent(StyledView);
 const MENU_EASING = Easing.bezier(...MENU_MOTION_EASING);
 
 /**
- * The per-surface chrome and motion. All three share the one popover motion;
- * `menu` and `listbox` use the menu recipe (`menu-styles.ts`) with colours from
- * `menu-palette.ts`, while `popover` leaves the whole panel to its caller's
- * resolved `style` (`popover/surface.ts`).
+ * The ONE motion every anchored surface runs: 150ms `ease-out`, fade +
+ * `scale-95` + 2px blur, no slide, scaling from the corner nearest the
+ * trigger, and the same shape reversed on the way out. It was written out
+ * three times, once per surface, with only the chrome differing — three
+ * spellings of one decision, any of which could be edited alone.
+ */
+const MENU_MOTION = {
+  duration: MENU_MOTION_DURATION,
+  easing: MENU_EASING,
+  scaleFrom: MENU_MOTION_SCALE_FROM,
+  slide: 0,
+  blur: MENU_MOTION_BLUR,
+} as const;
+
+/**
+ * The per-surface chrome. `menu` and `listbox` use the menu recipe
+ * (`constants.ts`'s `MENU_PANEL_CLASS` / `LISTBOX_PANEL_CLASS`) with colours
+ * from `menu-palette.ts`; `popover` carries NO chrome of its own here, because
+ * `popover/surface.ts` resolves the whole panel inline and hands it over as
+ * `style` so a caller's `className` can still override any one piece of it.
  */
 const SURFACE = {
-  popover: {
-    className: '',
-    duration: MENU_MOTION_DURATION,
-    easing: MENU_EASING,
-    scaleFrom: MENU_MOTION_SCALE_FROM,
-    slide: 0,
-    blur: MENU_MOTION_BLUR,
-  },
-  menu: {
-    className: MENU_PANEL_CLASS,
-    duration: MENU_MOTION_DURATION,
-    easing: MENU_EASING,
-    scaleFrom: MENU_MOTION_SCALE_FROM,
-    slide: 0,
-    blur: MENU_MOTION_BLUR,
-  },
-  listbox: {
-    className: LISTBOX_PANEL_CLASS,
-    duration: MENU_MOTION_DURATION,
-    easing: MENU_EASING,
-    scaleFrom: MENU_MOTION_SCALE_FROM,
-    slide: 0,
-    blur: MENU_MOTION_BLUR,
-  },
+  popover: { ...MENU_MOTION, className: '' },
+  menu: { ...MENU_MOTION, className: MENU_PANEL_CLASS },
+  listbox: { ...MENU_MOTION, className: LISTBOX_PANEL_CLASS },
 } as const;
 
 /**
@@ -203,6 +199,7 @@ export function FloatingPanel({
   testID,
   children,
   surface = 'popover',
+  panelRef,
 }: FloatingPanelProps) {
   const chrome = SURFACE[surface];
   const isMenuSurface = surface !== 'popover';
@@ -224,8 +221,11 @@ export function FloatingPanel({
   const reducedMotion = useReducedMotion();
   const progress = useSharedValue(0);
 
+  const panelRefRef = useRef(panelRef);
+  panelRefRef.current = panelRef;
   const attach = useCallback((node: View | null) => {
     setPanelNode(node);
+    panelRefRef.current?.(node);
   }, []);
 
   const store = useCallback((next: DropdownPlacement | null) => {
@@ -438,18 +438,17 @@ export function FloatingPanel({
     [progress, slideX, slideY, scaleFrom, blurFrom],
   );
 
+  // Escape dismisses the INNERMOST open surface and nothing under it — a Select
+  // inside a Dialog closes its list, not the dialog (`escape-stack.ts`). The
+  // entry is taken once per open and calls the CURRENT `onDismiss` through a
+  // ref: re-pushing it whenever the callback's identity changed would move a
+  // re-rendered parent menu above its own open submenu.
+  const onDismissRef = useRef(onDismiss);
+  onDismissRef.current = onDismiss;
   useEffect(() => {
     if (phase !== 'open' || !dismissible || typeof document === 'undefined') return;
-    const onKeyDown = (event: KeyboardEvent) => {
-      if (event.key !== 'Escape') return;
-      // Stop the key reaching a Dialog underneath: the innermost open surface is
-      // the one Escape dismisses.
-      event.stopPropagation();
-      onDismiss();
-    };
-    document.addEventListener('keydown', onKeyDown);
-    return () => document.removeEventListener('keydown', onKeyDown);
-  }, [phase, dismissible, onDismiss]);
+    return pushFloatingEscape(() => onDismissRef.current());
+  }, [phase, dismissible]);
 
   // The NON-modal outside press. Deliberately `pointerdown` in the CAPTURE
   // phase and never `preventDefault`: the surface has to be gone before the

package/src/floating/escape-stack.ts

@@ -0,0 +1,92 @@
+/**
+ * Escape for the anchored surfaces — WEB. One listener for every open
+ * `FloatingPanel`, dismissing only the INNERMOST (most recently opened) one and
+ * keeping the key from every enclosing surface.
+ *
+ * THE DEFECT IT REPLACES. Each panel added its own bubble-phase `keydown`
+ * listener on `document` and called `stopPropagation()`. A `Dialog` listens on
+ * `document` too, and `stopPropagation` does not stop a SIBLING listener on the
+ * same node: listeners on one node run in registration order, and the dialog —
+ * open first — registered first. So Escape on a `Select` inside a `Dialog`
+ * closed the DIALOG, and the list with it. Two panels open at once (a select
+ * inside a popover) had the same shape: the outer one registered first and
+ * closed first.
+ *
+ * THE MECHANISM.
+ *
+ *  - The listener sits on `document.documentElement` in the BUBBLE phase. That
+ *    is one node BELOW `document`, so it runs before any `document` listener —
+ *    the Dialog's included — and its `stopPropagation()` keeps the key from
+ *    ever reaching them. It is also ABOVE React's roots (the app root and every
+ *    portal container sit inside `<body>`), so a control inside a panel still
+ *    sees Escape first and can keep it — the composer's model-picker search
+ *    clears its query on Escape and stops the key, exactly as it did when the
+ *    panel listened on `document`.
+ *  - Entries form a stack: the panel opened LAST is dismissed, whatever order
+ *    the listeners happen to be in.
+ *  - `hasOpenFloatingSurface()` lets the surface host's window-capture Escape
+ *    router (`surfaces/SurfaceHost.tsx`) stand aside while a panel is open. It
+ *    runs before anything here, so without the check it would dismiss the
+ *    stacked dialog UNDER the open list.
+ *
+ * `globalThis`-anchored for the same reason as `overlay/stack.ts`: the families
+ * that open panels are imported through different subpaths, and a bundler can
+ * resolve two physical copies of this module.
+ */
+
+interface EscapeEntry {
+  dismiss: () => void;
+}
+
+interface EscapeRegistry {
+  stack: EscapeEntry[];
+  listener: ((event: KeyboardEvent) => void) | null;
+}
+
+declare global {
+  // eslint-disable-next-line no-var
+  var __oxy_so_bloom_floating_escape__: EscapeRegistry | undefined;
+}
+
+function registry(): EscapeRegistry {
+  globalThis.__oxy_so_bloom_floating_escape__ ??= { stack: [], listener: null };
+  return globalThis.__oxy_so_bloom_floating_escape__;
+}
+
+function onKeyDown(event: KeyboardEvent): void {
+  if (event.key !== 'Escape') return;
+  const stack = registry().stack;
+  const top = stack[stack.length - 1];
+  if (!top) return;
+  event.stopPropagation();
+  top.dismiss();
+}
+
+/**
+ * Put an open surface on top of the Escape stack. Returns the release, which
+ * removes exactly this entry wherever it now sits — a parent can close before
+ * its submenu's effect cleanup runs.
+ */
+export function pushFloatingEscape(dismiss: () => void): () => void {
+  const reg = registry();
+  const entry: EscapeEntry = { dismiss };
+  reg.stack.push(entry);
+  if (!reg.listener && typeof document !== 'undefined') {
+    reg.listener = onKeyDown;
+    document.documentElement.addEventListener('keydown', onKeyDown);
+  }
+  return () => {
+    const current = registry();
+    const index = current.stack.indexOf(entry);
+    if (index >= 0) current.stack.splice(index, 1);
+    if (current.stack.length === 0 && current.listener && typeof document !== 'undefined') {
+      document.documentElement.removeEventListener('keydown', current.listener);
+      current.listener = null;
+    }
+  };
+}
+
+/** Whether an anchored surface is open and will take the next Escape. */
+export function hasOpenFloatingSurface(): boolean {
+  return registry().stack.length > 0;
+}