@oxy.so/bloom 4.5.0 → 4.6.1

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;
+}

package/src/floating/menu-keyboard.ts

@@ -0,0 +1,242 @@
+/**
+ * The keyboard half of the ARIA menu-button pattern for the anchored menus —
+ * `DropdownMenu`, `ContextMenu`, `Menubar` and their flyout sub-menus — on WEB.
+ *
+ * What shipped: the trigger opened the menu on Enter/Space (it is a real
+ * `<button>`) and focus STAYED on it. The rows are portaled to the end of
+ * `<body>`, so the arrow keys had nothing to move, Tab walked on through the
+ * page BEHIND the open menu, and a keyboard user could open a menu and choose
+ * nothing. The markup was right throughout (`role="menu"`, `menuitem`,
+ * `aria-checked`), which is why nothing flagged it.
+ *
+ * The contract now:
+ *
+ *  - Opening from the keyboard moves focus INTO the menu: Enter, Space and
+ *    ArrowDown land on the first enabled row, ArrowUp on the last. A pointer
+ *    open leaves focus where the pointer put it; an arrow on the trigger of an
+ *    already-open menu then moves it in.
+ *  - In the menu: ArrowDown/ArrowUp move between enabled rows and WRAP;
+ *    Home/End jump to the ends; Enter and Space activate the row — a checkbox
+ *    row toggles, a radio row selects, and a row's `keepOpen` still decides
+ *    whether the menu closes. react-native-web presses a `menuitem`, `checkbox`
+ *    or `radio` on Enter only (`PressResponder.isValidKeyPress` limits Space to
+ *    `role="button"`), so Space is supplied here.
+ *  - Tab closes the menu and returns focus to the trigger — a menu is not in
+ *    the page's tab sequence. Escape closes the innermost surface
+ *    (`escape-stack.ts`) and focus returns the same way.
+ *  - The sub-menu keys stay `menu-sub-flyout.tsx`'s: → on a sub trigger opens
+ *    the flyout and focuses its first row, ← inside it closes it and refocuses
+ *    the trigger row.
+ *
+ * DOM listeners rather than props, like the sub-menu's: a row is
+ * `shared.tsx`'s `MenuRowShell`, the trigger may be the caller's own element
+ * under `asChild`, and the order of rows is whatever the caller rendered —
+ * the DOM already holds all of it. Every entry point is inert without a DOM
+ * node, so native (the menu is a bottom sheet there) is untouched.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import { isSpaceKey, rovingItems, rovingMove, rovingTarget } from '../hooks/roving-focus';
+import { MENU_MOTION_DURATION } from './constants';
+
+/** Every role a menu ROW can carry — the rows a pointer or a key can land on. */
+export const MENU_ROW_SELECTOR =
+  '[role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"], [role="checkbox"], [role="radio"]';
+
+/** A panel, so a nested panel's rows are never counted as this one's. */
+const MENU_PANEL_SELECTOR = '[role="menu"]';
+
+export type MenuFocusEdge = 'first' | 'last';
+
+/**
+ * Where focus should land the next time the menu's panel is ready — set by a
+ * key on the trigger, consumed by the panel. Owned by the family ROOT, which is
+ * the one component both the trigger and the content can reach.
+ */
+export interface MenuFocusIntent {
+  /** The pending edge, or `null` for "leave focus alone" (a pointer open). */
+  edge: React.MutableRefObject<MenuFocusEdge | null>;
+  /** Bumped to ask an ALREADY-open panel to take focus. */
+  tick: number;
+  request: (edge: MenuFocusEdge) => void;
+}
+
+export function useMenuFocusIntent(): MenuFocusIntent {
+  const edge = useRef<MenuFocusEdge | null>(null);
+  const [tick, setTick] = useState(0);
+  const request = useCallback((next: MenuFocusEdge) => {
+    edge.current = next;
+    setTick((count) => count + 1);
+  }, []);
+  return useMemo(() => ({ edge, tick, request }), [tick, request]);
+}
+
+/** A react-native-web host ref, read as the DOM element it is on web. */
+export function hostElement(node: unknown): HTMLElement | null {
+  if (!node || typeof node !== 'object') return null;
+  const scrollable = (node as { getScrollableNode?: () => unknown }).getScrollableNode?.();
+  const element = (scrollable ?? node) as Partial<HTMLElement>;
+  return typeof element.querySelector === 'function' &&
+    typeof element.addEventListener === 'function'
+    ? (element as HTMLElement)
+    : null;
+}
+
+/** The trigger's own focusable control inside its anchor wrapper. */
+export function triggerControl(anchor: unknown): HTMLElement | null {
+  const wrapper = hostElement(anchor);
+  return (
+    wrapper?.querySelector<HTMLElement>('[aria-haspopup]') ??
+    wrapper?.querySelector<HTMLElement>('[tabindex]') ??
+    null
+  );
+}
+
+/**
+ * Hand focus back to the trigger when a surface closes with focus inside it.
+ *
+ * `isInside` says whether an element belongs to the surface. Checked AT the
+ * close, when the panel is still mounted for its exit animation, so a row that
+ * was just activated still counts. Focus that has already gone somewhere real
+ * — a dialog the row opened, a field the pointer clicked — is left alone. The
+ * one deferred case is focus left on a node the exit is about to UNMOUNT (the
+ * outside-press backdrop): once the exit has run and focus has fallen to
+ * `<body>`, it goes back to the trigger too.
+ */
+export function useReturnFocusOnClose(
+  anchorRef: React.RefObject<unknown>,
+  open: boolean,
+  isInside: (element: Element) => boolean,
+): void {
+  const wasOpen = useRef(open);
+  const isInsideRef = useRef(isInside);
+  isInsideRef.current = isInside;
+  useEffect(() => {
+    const closed = wasOpen.current && !open;
+    wasOpen.current = open;
+    if (!closed || typeof document === 'undefined') return undefined;
+    const active = document.activeElement;
+    if (!active || active === document.body || isInsideRef.current(active)) {
+      triggerControl(anchorRef.current)?.focus({ preventScroll: true });
+      return undefined;
+    }
+    const timer = setTimeout(() => {
+      if (document.activeElement === document.body && !active.isConnected) {
+        triggerControl(anchorRef.current)?.focus({ preventScroll: true });
+      }
+    }, MENU_MOTION_DURATION + 50);
+    return () => clearTimeout(timer);
+  }, [open, anchorRef]);
+}
+
+/** Whether an element is one of the menu surfaces — any panel, any depth. */
+export function isInMenuSurface(element: Element): boolean {
+  return element.closest(MENU_PANEL_SELECTOR) !== null;
+}
+
+/**
+ * The menu trigger's keys, on its anchor wrapper: Enter/Space mark a closed
+ * menu's open as a keyboard one (the press itself is the button's own);
+ * ArrowDown/ArrowUp open it — or, open already, move focus in — landing on the
+ * first/last row. Plus the focus return on close.
+ */
+export function useMenuTriggerKeys(
+  anchorRef: React.RefObject<unknown>,
+  {
+    open,
+    setOpen,
+    disabled,
+    intent,
+  }: {
+    open: boolean;
+    setOpen: (next: boolean) => void;
+    disabled?: boolean;
+    intent: MenuFocusIntent | undefined;
+  },
+): void {
+  const edge = intent?.edge;
+  const request = intent?.request;
+  useEffect(() => {
+    const wrapper = hostElement(anchorRef.current);
+    if (!wrapper || disabled || !edge || !request) return undefined;
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.defaultPrevented) return;
+      if (event.key === 'Enter' || isSpaceKey(event.key)) {
+        if (!open) edge.current = 'first';
+        return;
+      }
+      if (event.key !== 'ArrowDown' && event.key !== 'ArrowUp') return;
+      event.preventDefault();
+      if (!open) setOpen(true);
+      request(event.key === 'ArrowDown' ? 'first' : 'last');
+    };
+    wrapper.addEventListener('keydown', onKeyDown);
+    return () => wrapper.removeEventListener('keydown', onKeyDown);
+  }, [anchorRef, disabled, open, setOpen, edge, request]);
+
+  // A pointer open must not inherit a stale keyboard intent from a key that
+  // did not open anything (a disabled row, a prevented press).
+  useEffect(() => {
+    if (!open && edge) edge.current = null;
+  }, [open, edge]);
+
+  useReturnFocusOnClose(anchorRef, open, isInMenuSurface);
+}
+
+/** The enabled rows that belong to `panel`, in document order. */
+function menuRows(panel: Element): HTMLElement[] {
+  // The owner is the nearest `role="menu"` — the panel itself, or (for a sub
+  // panel, whose rows sit in an inner scroller) the panel around it.
+  const owner = panel.closest(MENU_PANEL_SELECTOR) ?? panel;
+  return rovingItems(owner, MENU_ROW_SELECTOR, { owner: MENU_PANEL_SELECTOR });
+}
+
+/**
+ * The keys inside an open menu panel: arrows (wrapping), Home/End, Space, Tab.
+ * `intent`, when given, lands focus on the first/last row as the panel opens
+ * from the keyboard (a sub-panel focuses its own first row and passes none).
+ */
+export function useMenuPanelKeys(
+  panel: HTMLElement | null,
+  { open, onTab, intent }: { open: boolean; onTab: () => void; intent?: MenuFocusIntent },
+): void {
+  const onTabRef = useRef(onTab);
+  onTabRef.current = onTab;
+
+  const edge = intent?.edge;
+  const tick = intent?.tick;
+  useEffect(() => {
+    if (!open || !panel || !edge?.current) return;
+    const rows = menuRows(panel);
+    const target = edge.current === 'last' ? rows[rows.length - 1] : rows[0];
+    edge.current = null;
+    target?.focus({ preventScroll: true });
+  }, [open, panel, edge, tick]);
+
+  useEffect(() => {
+    if (!panel || !open) return undefined;
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.defaultPrevented) return;
+      const active =
+        typeof document !== 'undefined' ? (document.activeElement as HTMLElement | null) : null;
+      const current = active?.closest?.(MENU_ROW_SELECTOR) ?? null;
+      if (event.key === 'Tab') {
+        event.preventDefault();
+        onTabRef.current();
+        return;
+      }
+      if (isSpaceKey(event.key)) {
+        if (!current || current.getAttribute('aria-disabled') === 'true') return;
+        event.preventDefault();
+        (current as HTMLElement).click();
+        return;
+      }
+      const move = rovingMove(event.key, { orientation: 'vertical', homeEnd: true });
+      if (move === null) return;
+      event.preventDefault();
+      rovingTarget(menuRows(panel), current, move, true)?.focus();
+    };
+    panel.addEventListener('keydown', onKeyDown);
+    return () => panel.removeEventListener('keydown', onKeyDown);
+  }, [panel, open]);
+}

package/src/floating/menu-sub-flyout.tsx

@@ -51,7 +51,10 @@ import {
   MENU_SUB_SIDE_OFFSET,
   ROW_ICON_SIZE,
 } from './constants';
+import { useMenuSurface } from './context';
+import { pushFloatingEscape } from './escape-stack';
 import { FloatingPanel } from './FloatingPanel';
+import { hostElement, MENU_ROW_SELECTOR, useMenuPanelKeys } from './menu-keyboard';
 import { cx, MenuRowChevron, MenuRowShell, splitChildren, SUB_TRIGGER_CLASS } from './shared';
 import type {
   FloatingAnchor,
@@ -119,8 +122,7 @@ function isHoverPointer(event: Event): boolean {
 }
 
 /** Every role a menu ROW can carry — the rows a pointer can actually land on. */
-const MENU_ITEM_SELECTOR =
-  '[role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"], [role="checkbox"], [role="radio"]';
+const MENU_ITEM_SELECTOR = MENU_ROW_SELECTOR;
 
 /**
  * Did the pointer leave for another ROW, rather than for the gap this sub's
@@ -546,22 +548,25 @@ export function createFlyoutMenuSub(prefix: string): MenuSubParts {
       };
     }, [node, sub]);
 
-    // Escape, in the CAPTURE phase with `stopImmediatePropagation`. Every open
-    // `FloatingPanel` has a bubble-phase `keydown` listener on `document`, and
-    // `stopPropagation` does not stop a sibling listener on the same node — so
-    // without this the sub and its parent menu would both close on one press.
-    // Capture runs before bubble whatever the registration order, which is what
-    // makes "innermost first" hold rather than "whichever mounted first".
+    // Escape closes this flyout and leaves the menu open. The flyout's panel is
+    // `dismissible={false}` (a press outside it is the parent's business), so it
+    // takes its own entry on the escape stack — pushed after the parent's, so it
+    // is the one Escape reaches first (`escape-stack.ts`). This used to be a
+    // document CAPTURE listener with `stopImmediatePropagation`, which also took
+    // Escape away from any field inside the flyout.
+    const { open: subOpen, closeAndRefocus } = sub;
+    const closeRef = useRef(closeAndRefocus);
+    closeRef.current = closeAndRefocus;
     useEffect(() => {
-      if (!sub.open || typeof document === 'undefined') return;
-      const onKeyDown = (event: KeyboardEvent) => {
-        if (event.key !== 'Escape') return;
-        event.stopImmediatePropagation();
-        sub.closeAndRefocus();
-      };
-      document.addEventListener('keydown', onKeyDown, true);
-      return () => document.removeEventListener('keydown', onKeyDown, true);
-    }, [sub]);
+      if (!subOpen || typeof document === 'undefined') return undefined;
+      return pushFloatingEscape(() => closeRef.current());
+    }, [subOpen]);
+
+    // Arrows (wrapping), Home/End, Space and Tab among the flyout's own rows —
+    // the same keys as the menu it flew out of (`menu-keyboard.ts`). Tab closes
+    // the WHOLE menu, not just this flyout: the menu is not in the tab order.
+    const surface = useMenuSurface();
+    useMenuPanelKeys(hostElement(node), { open: sub.open, onTab: surface.close });
 
     // Move focus onto the panel once it has been placed, so Right genuinely
     // ENTERS the submenu rather than only opening it.

package/src/floating/types.ts

@@ -19,6 +19,7 @@
  */
 import type { GestureResponderEvent, StyleProp, TextStyle, View, ViewStyle } from 'react-native';
 
+import type { MenuFocusIntent } from './menu-keyboard';
 import type { WebAriaProps } from '../styles/styled-primitives';
 
 /**
@@ -32,6 +33,11 @@ export interface OverlayShellContextValue {
   setOpen: (next: boolean) => void;
   /** The trigger wrapper. Measured by the web forks, unused on native. */
   anchorRef: React.RefObject<View | null>;
+  /**
+   * Web menus only: where a keyboard open lands focus, handed from the trigger
+   * to the panel (`menu-keyboard.ts`). Absent on native and on `Popover`.
+   */
+  focusIntent?: MenuFocusIntent;
 }
 
 /**
@@ -129,6 +135,11 @@ export interface FloatingPanelProps extends FloatingPositionProps {
    * panel inline (`popover/surface.ts`) and passes it as `style`.
    */
   surface?: 'popover' | 'menu' | 'listbox';
+  /**
+   * Receives the panel's own node as it mounts and unmounts — for a family that
+   * attaches keyboard handling to the rows inside it (`menu-keyboard.ts`).
+   */
+  panelRef?: (node: View | null) => void;
 }
 
 /**

package/src/fonts/index.web.ts

@@ -1,23 +1,8 @@
-// Web variant of the `./fonts` barrel.
-//
-// Every re-export below that has a platform fork names its `.web` source
-// OUTRIGHT rather than letting the bundler pick. That is deliberate: web
-// bundlers are not required to resolve `.web` extensions (Vite does not, out
-// of the box), so an extensionless specifier here would quietly fall through
-// to the default file.
-//
-// - `./apply-font-faces.web` performs the real `@font-face` injection against
-//   the `.woff2` URLs the consuming bundler emits (see `font-urls.web.ts`);
-//   the default `./apply-font-faces` is a no-op stub for native.
-// - `./font-assets.web` is an empty map. The native map is built from Metro
-//   asset `require()` calls, and importing it from an ES module throws
-//   `ReferenceError: require is not defined` during module evaluation — which
-//   white-screens the consumer before React mounts. Naming the `.web` file
-//   here is what keeps it out of the web graph.
-//
-// Web bundlers select this file via the `"browser"` condition in
-// `package.json`'s `exports['./fonts']`; native bundlers fall through to
-// `./index.ts` via the `"react-native"` condition.
+// AUTO-GENERATED by scripts/generate-platform-exports.mjs — DO NOT EDIT.
+// Source of truth: src/fonts/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 { fontFamilies, fontCssVars } from './tokens';
 export type { FontFamilyName } from './tokens';
 export { applyFontFaces } from './apply-font-faces.web';

package/src/frosted-icon-button/FrostedIconButton.web.tsx

@@ -1,3 +1,12 @@
+/**
+ * `FrostedIconButton` — WEB: a real HTML `<button>` frosted by a real CSS
+ * `backdrop-filter`.
+ *
+ * The native fork frosts via `expo-blur`'s `BlurView`. Forking the file rather
+ * than branching inside one is what keeps that import out of the web graph
+ * entirely — `expo-blur` is an optional peer, and a web bundler that resolves
+ * it at all is a build a consumer did not ask for.
+ */
 import { useBloomAppearance } from '../appearance';
 import { resolveBloomColors } from '../appearance/colors';
 import React, {

package/src/frosted-icon-button/index.web.ts

@@ -1,9 +1,7 @@
-// Web variant of the `./frosted-icon-button` barrel.
-//
-// The default barrel (`./index.ts`) re-exports the React Native implementation,
-// which frosts via `expo-blur`'s `BlurView`. The web fork (`./FrostedIconButton.web`)
-// renders a real HTML `<button>` and frosts via a real CSS `backdrop-filter` —
-// no `expo-blur` import ever reaches a web bundler. Web bundlers select this
-// file via the `"browser"` export condition in `package.json`.
+// AUTO-GENERATED by scripts/generate-platform-exports.mjs — DO NOT EDIT.
+// Source of truth: src/frosted-icon-button/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 { FrostedIconButton } from './FrostedIconButton.web';
 export type { FrostedIconButtonProps, FrostedIconButtonSize } from './types';