@oxy.so/bloom 2.10.0 → 2.11.0

package/src/creator-studio/shared.ts

@@ -2,6 +2,7 @@ import { Platform } from 'react-native';
 
 import { ACCENT_TABLE, colorRamp, DANGER_TABLE, mixColor, resolveButtonRamps } from '../button/shared';
 import type { AccentTone } from '../theme/accent-colors';
+import { surfaceTextOn } from '../styles/surface-levels';
 import type { Theme } from '../theme/types';
 import type {
   CreatorOption,
@@ -9,6 +10,7 @@ import type {
   ReleaseType,
   TrackUploadStatus,
 } from './types';
+import { clamp } from '../styles/clamp';
 
 export const IS_WEB = Platform.OS === 'web';
 
@@ -59,13 +61,17 @@ export function resolveCreatorStudioPaint(theme: Theme): CreatorStudioPaint {
   const rose = colorRamp(theme.colors.negative, DANGER_TABLE);
   const green = colorRamp(theme.colors.success, ACCENT_TABLE);
   const surface = dark ? n[900] : n[100];
+  const quiet = surfaceTextOn(theme, surface);
   return {
     surface,
     inner: dark ? mixColor(surface, n[800], 0.6) : theme.colors.card,
     border: dark ? n[800] : n[200],
     text: theme.colors.text,
-    textSecondary: dark ? n[400] : n[500],
-    textTertiary: dark ? n[500] : n[400],
+    // Read off THIS card's fill, not off a ramp stop chosen against the page —
+    // the same copy of `neutral-400`/`neutral-500` that put chart-card captions
+    // at 2.42:1. `surfaceTextOn` floors them on `surface`.
+    textSecondary: quiet.textSecondary,
+    textTertiary: quiet.textTertiary,
     track: dark ? n[800] : n[200],
     ring: dark ? n[700] : n[300],
     placeholder: dark ? n[800] : n[200],
@@ -137,10 +143,14 @@ export const DEFAULT_CREDIT_ROLES: readonly CreatorOption[] = [
 //  Uploads
 // ---------------------------------------------------------------------------
 
-/** Clamps a progress value to a whole 0–100. */
+/**
+ * Clamps a progress value to a whole 0–100.
+ *
+ * NOT `clamp01` under another name: this is a PERCENTAGE and it rounds.
+ */
 export function clampProgress(value: number | undefined): number {
   if (value === undefined || !Number.isFinite(value)) return 0;
-  return Math.round(Math.min(100, Math.max(0, value)));
+  return Math.round(clamp(value, 0, 100));
 }
 
 /** What a row draws for a status: a determinate bar, a running bar, or none. */
@@ -213,17 +223,6 @@ export function artworkDimensionsError(
   return null;
 }
 
-/** A URL (or data/blob URI) rather than an ImageResolver id. */
-export function isImageUrl(value: string): boolean {
-  return (
-    value.startsWith('http://') ||
-    value.startsWith('https://') ||
-    value.startsWith('data:') ||
-    value.startsWith('blob:') ||
-    value.startsWith('file:')
-  );
-}
-
 /** Adds a string to a list once, trimmed; returns the same list when nothing changes. */
 export function addUnique(list: readonly string[], value: string, max?: number): string[] {
   const name = value.trim();

package/src/creator-studio/types.ts

@@ -2,9 +2,11 @@ import type { ComponentType, ReactNode } from 'react';
 import type { StyleProp, ViewStyle } from 'react-native';
 
 import type { FileUploadFile } from '../file-upload/types';
+import type { BloomIconComponent } from '../icons/icon-component';
 
 /** A Remix-style icon component: `width`, `height`, `fill`. */
-export type CreatorStudioIcon = ComponentType<{ width?: number; height?: number; fill?: string }>;
+/** @deprecated Use `BloomIconComponent` from `@oxy.so/bloom/icons`; this is an alias of it. */
+export type CreatorStudioIcon = BloomIconComponent;
 
 /** Which way a figure moved against the previous period. */
 export type CreatorTrend = 'up' | 'down' | 'flat';

package/src/data-table/types.ts

@@ -4,6 +4,7 @@ import type { StyleProp, ViewStyle } from 'react-native';
 import type { ButtonProps } from '../button/types';
 import type { AccentTone } from '../theme/accent-colors';
 import type { TableColumnLayout, TableSize } from '../table/types';
+import type { BloomIconComponent } from '../icons/icon-component';
 
 /** The table's two densities, `md` ("Normal") and `sm` ("Compact"). */
 export type DataTableSize = TableSize;
@@ -150,7 +151,8 @@ export interface DataTableProps<T> {
 }
 
 /** A Remix-style icon component: `width`, `height`, `fill`. */
-export type DataTableIconComponent = ComponentType<{ width?: number; height?: number; fill?: string }>;
+/** @deprecated Use `BloomIconComponent` from `@oxy.so/bloom/icons`; this is an alias of it. */
+export type DataTableIconComponent = BloomIconComponent;
 
 export interface DataTableRowActionProps
   extends Omit<ButtonProps, 'children' | 'variant' | 'size' | 'iconOnly' | 'icon' | 'leadingIcon' | 'trailingIcon'> {

package/src/dialog/Dialog.tsx

@@ -30,6 +30,7 @@ import { Backdrop, OverlayRoot } from '../overlay';
 import { useTheme } from '../theme/use-theme';
 import { bloomShadowStyle } from '../design-tokens/shadows';
 import { StyledView } from '../styles/styled-primitives';
+import { SurfaceLevelProvider } from '../styles/surface-levels';
 import { Context, useDialogControl } from './context';
 import { DialogBody } from './DialogContent';
 import { DialogBottomSheet } from './DialogBottomSheet';
@@ -521,6 +522,16 @@ function SideSheet({
 
   if (!mounted) return null;
 
+  // The drawer paints the PAGE colour, so it RESETS the ambient surface for its
+  // content: anything inside it that has to be opaque in "the colour I am on"
+  // gets the drawer's, not that of whatever surface it was opened from. The
+  // sheet path is covered by `BottomSheetBase`, which publishes the same way.
+  const surfaceChildren = (
+    <SurfaceLevelProvider level={0} fill={theme.colors.background}>
+      {children}
+    </SurfaceLevelProvider>
+  );
+
   return (
     // `OverlayRoot` takes this drawer's place in the open-order overlay stack.
     // It mounts here, past the `mounted` guard, so the rank tracks OPENING.
@@ -565,10 +576,10 @@ function SideSheet({
               collapse={false}
             />
             <DialogNavBarSpacer controller={headerController} header={header} />
-            <DialogHeaderProvider controller={headerController}>{children}</DialogHeaderProvider>
+            <DialogHeaderProvider controller={headerController}>{surfaceChildren}</DialogHeaderProvider>
           </View>
         ) : (
-          <View style={{ padding: contentPadding }}>{children}</View>
+          <View style={{ padding: contentPadding }}>{surfaceChildren}</View>
         )}
       </AnimatedStyledView>
     </OverlayRoot>

package/src/dialog/Dialog.web.tsx

@@ -27,6 +27,7 @@ import { Backdrop, OverlayRoot } from '../overlay';
 import { StyledView } from '../styles/styled-primitives';
 import { Portal } from '../portal/index.web';
 import { adoptStyleSheet } from '../styles/adopt-style-sheet';
+import { SurfaceLevelProvider, surfaceFillVars } from '../styles/surface-levels';
 import { Z_INDEX } from '../styles/z-index';
 import { WEB_POSITION_FIXED, type WebCssStyle } from '../styles/web-view-style';
 import { bloomShadowStyle } from '../design-tokens/shadows';
@@ -476,7 +477,13 @@ function DialogPanel({
       description={description}
       actions={actions}
     >
-      {children}
+      {/* The dialog paints the PAGE colour, so it RESETS the ambient surface.
+          On web a portal keeps React context from where the dialog was
+          rendered, so without this a dialog opened from inside a `ContentPanel`
+          would tell its content it is sitting on the panel's card. */}
+      <SurfaceLevelProvider level={0} fill={theme.colors.background}>
+        {children}
+      </SurfaceLevelProvider>
     </DialogBody>
   );
 
@@ -505,6 +512,10 @@ function DialogPanel({
           maxHeight: `${Math.round(heightRatio * 100)}%`,
           overflow: 'hidden',
           backgroundColor: theme.colors.background,
+          // `--bloom-surface` on the element that carries the fill, so web CSS
+          // inside the dialog reads the dialog's colour and not the colour of
+          // whatever surface it was opened over.
+          ...surfaceFillVars(theme.colors.background),
           borderWidth: 1,
           borderColor: theme.isDark ? 'rgba(255,255,255,0.1)' : 'rgba(0,0,0,0.1)',
           // Design-system overlay elevation (`shadow-m`) as a `boxShadow` — RN-Web
@@ -704,6 +715,15 @@ function SheetSurface({
     if (dismissOnBackdrop) onDismiss();
   }, [dismissOnBackdrop, onDismiss]);
 
+  // The drawer paints the PAGE colour, so it RESETS the ambient surface for its
+  // content — see `DialogPanel`'s own wrap for why a portal does not do that on
+  // its own.
+  const surfaceChildren = (
+    <SurfaceLevelProvider level={0} fill={theme.colors.background}>
+      {children}
+    </SurfaceLevelProvider>
+  );
+
   return (
     <OverlayRoot style={[sheetStyles.root, containerStyle]} className={containerClassName}>
       <Backdrop
@@ -731,6 +751,7 @@ function SheetSurface({
         className={panelClassName}
         style={[
           sheetStyles.panel,
+          surfaceFillVars(theme.colors.background),
           {
             backgroundColor: theme.colors.background,
             // Above this surface's OWN backdrop, and nothing more: `OverlayRoot`
@@ -778,7 +799,7 @@ function SheetSurface({
                   description={description}
                   actions={actions}
                 >
-                  {children}
+                  {surfaceChildren}
                 </DialogBody>
               </DialogHeaderProvider>
             </ScrollView>
@@ -792,7 +813,7 @@ function SheetSurface({
               description={description}
               actions={actions}
             >
-              {children}
+              {surfaceChildren}
             </DialogBody>
           </View>
         )}

package/src/field/Field.tsx

@@ -1,11 +1,10 @@
 import React, { memo, useMemo } from 'react';
 import { View } from 'react-native';
 
-import { useTheme } from '../theme/use-theme';
 import { Text } from '../typography';
 import { Label } from '../label';
 import { atoms as a } from '../styles';
-import { TEXT_FIELD_STACK_GAP, resolveTextFieldPalette } from '../text-field/shared';
+import { TEXT_FIELD_STACK_GAP, useTextFieldPalette } from '../text-field/shared';
 import type { FieldProps } from './types';
 
 /**
@@ -31,8 +30,7 @@ const FieldComponent = function Field({
   style,
   testID,
 }: FieldProps) {
-  const theme = useTheme();
-  const palette = useMemo(() => resolveTextFieldPalette(theme), [theme]);
+  const palette = useTextFieldPalette();
   const hasError = typeof error === 'string' && error.length > 0;
   const descriptionID = nativeID ? `${nativeID}-description` : undefined;
   const errorID = nativeID ? `${nativeID}-error` : undefined;

package/src/file-upload/FileUpload.tsx

@@ -22,6 +22,7 @@ import {
 import { useInteractionState } from '../hooks/use-interaction-state';
 import { useInteractiveWebCss } from '../styles/interactive-web-css';
 import type { WebCssStyle } from '../styles/web-view-style';
+import { webDataSet } from '../styles/web-data';
 import type { Theme } from '../theme/types';
 import { useTheme } from '../theme/use-theme';
 import { Text } from '../typography';
@@ -89,13 +90,10 @@ const HIDE_MS = 200;
 type UploadPhase = 'idle' | 'uploading' | 'complete';
 type StaggerState = 'shown' | 'hiding' | 'hidden';
 
-export function formatFileSize(bytes: number): string {
-  if (bytes >= 1024 * 1024) {
-    const mb = bytes / (1024 * 1024);
-    return `${mb >= 10 ? Math.round(mb) : Math.round(mb * 10) / 10} MB`;
-  }
-  return `${Math.max(1, Math.round(bytes / 1024))} KB`;
-}
+import { formatFileSize } from './shared';
+import { DISABLED_OPACITY } from '../styles/tokens';
+
+export { formatFileSize };
 
 function extensionFor(fileName: string): string {
   return fileName.split('.').pop()?.toLowerCase() ?? '';
@@ -219,10 +217,6 @@ function useStaggerState(active: boolean): StaggerState {
   return active ? 'shown' : hiding ? 'hiding' : 'hidden';
 }
 
-function webData(data: Record<string, string>): Record<string, unknown> {
-  return IS_WEB ? { dataSet: data } : {};
-}
-
 // ---------------------------------------------------------------------------
 //  Web CSS — the transitions, the blur and the focus ring, none of which has an
 //  inline-style spelling. Hung off `dataSet` attributes; `adoptStyleSheet`
@@ -382,7 +376,7 @@ function StaggerLine({
   if (IS_WEB) {
     return (
       <View
-        {...webData(
+        {...webDataSet(
           kind === 'line'
             ? { bloomFileUploadLine: String(order), bloomFileUploadState: state }
             : { bloomFileUploadSub: state },
@@ -639,7 +633,7 @@ const FileUploadComponent = function FileUpload({
     flexShrink: 0,
     borderRadius: BOX_RADIUS,
     ...(IS_WEB ? { backgroundColor: busy ? paint.busyBackground : paint.idleBackground } : null),
-    opacity: disabled ? 0.5 : 1,
+    opacity: disabled ? DISABLED_OPACITY : 1,
     '--bloom-file-upload-ring': paint.ring,
   };
 
@@ -648,7 +642,7 @@ const FileUploadComponent = function FileUpload({
   return (
     <Pressable
       ref={rootRef}
-      {...webData({ bloomFileUpload: busy ? 'busy' : 'idle' })}
+      {...webDataSet({ bloomFileUpload: busy ? 'busy' : 'idle' })}
       accessibilityRole="button"
       accessibilityLabel={accessibilityLabel}
       aria-busy={busy}
@@ -713,7 +707,7 @@ const FileUploadComponent = function FileUpload({
 
       {/* Dashed idle border. */}
       <Animated.View
-        {...webData({ bloomFileUploadDash: '' })}
+        {...webDataSet({ bloomFileUploadDash: '' })}
         pointerEvents="none"
         style={[
           fill,
@@ -729,7 +723,7 @@ const FileUploadComponent = function FileUpload({
 
       {/* Progress outline. */}
       <Animated.View
-        {...webData({ bloomFileUploadRing: '' })}
+        {...webDataSet({ bloomFileUploadRing: '' })}
         pointerEvents="none"
         style={[fill, { opacity: IS_WEB ? (busy ? 1 : 0) : busyFade }]}
       >
@@ -761,7 +755,7 @@ const FileUploadComponent = function FileUpload({
         style={{ position: 'absolute', top: -9.5, left: 0, right: 0, alignItems: 'center' }}
       >
         <Animated.View
-          {...webData({ bloomFileUploadPill: busy ? 'shown' : 'hidden' })}
+          {...webDataSet({ bloomFileUploadPill: busy ? 'shown' : 'hidden' })}
           style={[
             {
               borderRadius: 6,
@@ -808,7 +802,7 @@ const FileUploadComponent = function FileUpload({
             backgroundColor: paint.discBackground,
           }}
         >
-          <View {...webData({ bloomFileUploadIcon: '' })}>
+          <View {...webDataSet({ bloomFileUploadIcon: '' })}>
             <RiUploadCloud2Line
               width={24}
               height={24}

package/src/file-upload/shared.ts

@@ -0,0 +1,32 @@
+/**
+ * The size formatter, split out of `FileUpload.tsx` so a caller can have the
+ * STRING without the component.
+ *
+ * `message-media`'s file bubble and shared-files list print the same "2.4 MB"
+ * and must agree with the uploader that produced it. Importing it from
+ * `FileUpload.tsx` would drag the whole uploader — reanimated, its icons, its
+ * drop-zone web CSS — into every consumer of `@oxy.so/bloom/message-media`,
+ * which Metro does not tree-shake away. `FileUpload.tsx` re-exports it, so the
+ * public spelling is unchanged.
+ */
+
+/**
+ * Bytes as a size string: `"312 KB"`, `"2.4 MB"`, `"15 MB"`, `"1.4 GB"`.
+ *
+ * Binary units (1024), one decimal below ten of a unit and none at or above it,
+ * and a floor of 1 KB — a 200-byte attachment reading "0 KB" looks like a failed
+ * upload.
+ */
+export function formatFileSize(bytes: number): string {
+  const GB = 1024 * 1024 * 1024;
+  const MB = 1024 * 1024;
+  if (bytes >= GB) {
+    const gb = bytes / GB;
+    return `${gb >= 10 ? Math.round(gb) : Math.round(gb * 10) / 10} GB`;
+  }
+  if (bytes >= MB) {
+    const mb = bytes / MB;
+    return `${mb >= 10 ? Math.round(mb) : Math.round(mb * 10) / 10} MB`;
+  }
+  return `${Math.max(1, Math.round(bytes / 1024))} KB`;
+}

package/src/floating/FloatingPanel.tsx

@@ -58,7 +58,7 @@
  * than to the ones it reads, so an omitted value runs the mapper once and
  * freezes it.
  */
-import React, { useCallback, useEffect, useLayoutEffect, useMemo, useState } from 'react';
+import React, { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
 import { StyleSheet, View } from 'react-native';
 import Animated, {
   Easing,
@@ -75,6 +75,7 @@ import {
 } from '../overlay/dropdown-placement';
 import { Portal } from '../portal/index.web';
 import { StyledView } from '../styles/styled-primitives';
+import { SurfaceLevelProvider } from '../styles/surface-levels';
 import { WEB_POSITION_FIXED } from '../styles/web-view-style';
 import {
   DEFAULT_ALIGN_OFFSET,
@@ -90,6 +91,7 @@ import {
 import { useMenuPalette } from './menu-palette';
 import { cx } from './shared';
 import type { FloatingPanelProps, FloatingSide } from './types';
+import { useFrameThrottle } from './use-frame-throttle';
 
 /**
  * The one node: the panel's own chrome, the caller's classes, the computed
@@ -157,6 +159,17 @@ function resolvedSide(
   return placement.top >= anchorStart ? 'bottom' : 'top';
 }
 
+/**
+ * Did the surface land in the same place? A placement is two numbers, and while
+ * the page scrolls most passes produce the two it already had — the trigger sits
+ * in a fixed header, or in an ancestor the gesture is not scrolling.
+ */
+function samePlacement(a: DropdownPlacement | null, b: DropdownPlacement | null): boolean {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  return a.top === b.top && a.left === b.left;
+}
+
 /** The corner the panel grows from: the one nearest its trigger. */
 function transformOriginFor(side: FloatingSide, align: string): string {
   const cross =
@@ -200,6 +213,12 @@ export function FloatingPanel({
   // effect keyed only on `open` would measure nothing.
   const [panelNode, setPanelNode] = useState<View | null>(null);
   const [placement, setPlacement] = useState<DropdownPlacement | null>(null);
+  // What was last published, mirrored so a pass that resolves to the position
+  // the panel already holds never reaches the dispatcher. Returning the current
+  // state from a `setState` updater is not the same thing: React still
+  // re-renders once before it bails out, which on a scroll is a render per frame
+  // for a surface that did not move.
+  const published = useRef<DropdownPlacement | null>(null);
   const [phase, setPhase] = useState<Phase>(open ? 'open' : 'closed');
   const [lastOpen, setLastOpen] = useState(open);
   const reducedMotion = useReducedMotion();
@@ -209,6 +228,12 @@ export function FloatingPanel({
     setPanelNode(node);
   }, []);
 
+  const store = useCallback((next: DropdownPlacement | null) => {
+    if (samePlacement(published.current, next)) return;
+    published.current = next;
+    setPlacement(next);
+  }, []);
+
   // `open` drives the phase; a close goes through `closing` so the exit has time
   // to run before the subtree leaves the tree.
   //
@@ -236,7 +261,11 @@ export function FloatingPanel({
     return () => clearTimeout(timer);
   }, [phase, reducedMotion, chrome.duration]);
 
-  useLayoutEffect(() => {
+  // ONE pass of the placement: two forced layout reads (`getBoundingClientRect`
+  // and the `offset*` pair) and, at most, one state update. Split out of the
+  // effect that used to own it so the listeners below can be registered once and
+  // still call the CURRENT closure.
+  const resolve = useCallback(() => {
     // While closing, the panel holds the position it was last placed at: the
     // anchor is already gone (`useAnchorRect` clears it on close) and a
     // re-resolve would snap the surface somewhere else mid-exit.
@@ -244,7 +273,7 @@ export function FloatingPanel({
     // react-native-web resolves a `View` ref to the DOM element itself. Read
     // through the one method needed rather than asserting the whole
     // `HTMLElement` interface, and capture it as a local so the narrowing holds
-    // inside `update` — a property check does not survive into a closure.
+    // below — a property check does not survive into a closure.
     const element = panelNode as unknown as {
       getBoundingClientRect?: () => DOMRect;
       offsetWidth?: number;
@@ -257,59 +286,81 @@ export function FloatingPanel({
       typeof window === 'undefined' ||
       typeof measure !== 'function'
     ) {
-      setPlacement(null);
+      store(null);
       return;
     }
 
-    const update = () => {
-      const box = measure.call(element);
-      // The LAYOUT box, not the visual one. `getBoundingClientRect` reports the
-      // TRANSFORMED rectangle, and this panel is measured while its own enter is
-      // still at `scale(0.95)` — so the rect is 5% small. `far` placements never
-      // read the extent and looked perfect; the FLIPPED and `align="end"` ones
-      // do, and were out by 5% of the surface. Measured: a 256px sub-panel read
-      // as 243.2 and flipped 12.8px over its parent. `offsetWidth`/`offsetHeight`
-      // are the untransformed border box, integer-rounded, which is the right
-      // precision for a fit/flip decision. The rect is still the fallback for a
-      // non-DOM node (a jsdom stub has neither).
-      const layoutWidth = element?.offsetWidth ?? box.width;
-      const layoutHeight = element?.offsetHeight ?? box.height;
-      // Measured BEFORE `minWidth` is applied, so the laid-out surface can only
-      // be wider than the box read here — and a wider surface wraps less, so the
-      // measured height is an upper bound. Erring that way flips early in a tie,
-      // never late. The panel's own `min-w-*` CLASS is already in the box, since
-      // a stylesheet rule applies before a layout effect can read the node.
-      const width = Math.max(layoutWidth, minWidth ?? 0);
-      // The align axis is the one `side` does not name.
-      const alignsVertically = side === 'left' || side === 'right';
-      const shiftY = alignsVertically ? alignOffset : 0;
-      const shiftX = alignsVertically ? 0 : alignOffset;
-      setPlacement(
-        resolveDropdownPlacement({
-          anchor: {
-            top: anchor.top + shiftY,
-            bottom: anchor.bottom + shiftY,
-            left: anchor.left + shiftX,
-            right: anchor.right + shiftX,
-          },
-          size: { width, height: layoutHeight },
-          viewport: { width: window.innerWidth, height: window.innerHeight },
-          offset: sideOffset,
-          gutter: VIEWPORT_GUTTER,
-          align,
-          side,
-        }),
-      );
-    };
+    const box = measure.call(element);
+    // The LAYOUT box, not the visual one. `getBoundingClientRect` reports the
+    // TRANSFORMED rectangle, and this panel is measured while its own enter is
+    // still at `scale(0.95)` — so the rect is 5% small. `far` placements never
+    // read the extent and looked perfect; the FLIPPED and `align="end"` ones
+    // do, and were out by 5% of the surface. Measured: a 256px sub-panel read
+    // as 243.2 and flipped 12.8px over its parent. `offsetWidth`/`offsetHeight`
+    // are the untransformed border box, integer-rounded, which is the right
+    // precision for a fit/flip decision. The rect is still the fallback for a
+    // non-DOM node (a jsdom stub has neither).
+    const layoutWidth = element?.offsetWidth ?? box.width;
+    const layoutHeight = element?.offsetHeight ?? box.height;
+    // Measured BEFORE `minWidth` is applied, so the laid-out surface can only
+    // be wider than the box read here — and a wider surface wraps less, so the
+    // measured height is an upper bound. Erring that way flips early in a tie,
+    // never late. The panel's own `min-w-*` CLASS is already in the box, since
+    // a stylesheet rule applies before a layout effect can read the node.
+    const width = Math.max(layoutWidth, minWidth ?? 0);
+    // The align axis is the one `side` does not name.
+    const alignsVertically = side === 'left' || side === 'right';
+    const shiftY = alignsVertically ? alignOffset : 0;
+    const shiftX = alignsVertically ? 0 : alignOffset;
+    const next = resolveDropdownPlacement({
+      anchor: {
+        top: anchor.top + shiftY,
+        bottom: anchor.bottom + shiftY,
+        left: anchor.left + shiftX,
+        right: anchor.right + shiftX,
+      },
+      size: { width, height: layoutHeight },
+      viewport: { width: window.innerWidth, height: window.innerHeight },
+      offset: sideOffset,
+      gutter: VIEWPORT_GUTTER,
+      align,
+      side,
+    });
+    // A scroll that did not move this surface resolves to the same two numbers,
+    // and storing a NEW object for them would re-render the panel and rebuild
+    // its motion style for a position it already holds. Dropping the update is
+    // what makes a settled panel free to scroll past.
+    store(next);
+  }, [store, phase, anchor, panelNode, side, align, sideOffset, alignOffset, minWidth]);
 
-    update();
-    window.addEventListener('resize', update);
-    window.addEventListener('scroll', update, true);
+  // Coalesced to one pass per frame: a scroll gesture dispatches a stream of
+  // events (one per nested scroller, several per frame) and the browser paints
+  // once between them.
+  // No cancel needed on close: `resolve` is guarded by `phase`, so a frame that
+  // lands after the panel left `'open'` either holds the exit's position or
+  // clears a placement that is already null.
+  const [schedule] = useFrameThrottle(resolve);
+
+  // Whenever an INPUT changes — the anchor moved, the side flipped, the panel
+  // node arrived — the pass runs SYNCHRONOUSLY, before paint, so the surface is
+  // never painted a frame behind the thing it is anchored to.
+  useLayoutEffect(() => {
+    resolve();
+  }, [resolve]);
+
+  // Registered ONCE per open. `schedule` is stable for the panel's whole life,
+  // so a re-measurement no longer detaches and re-attaches this pair — which it
+  // did on every scroll event, because the effect that read the anchor was also
+  // the effect that owned the listeners.
+  useEffect(() => {
+    if (phase !== 'open' || typeof window === 'undefined') return;
+    window.addEventListener('resize', schedule);
+    window.addEventListener('scroll', schedule, true);
     return () => {
-      window.removeEventListener('resize', update);
-      window.removeEventListener('scroll', update, true);
+      window.removeEventListener('resize', schedule);
+      window.removeEventListener('scroll', schedule, true);
     };
-  }, [phase, anchor, panelNode, side, align, sideOffset, alignOffset, minWidth]);
+  }, [phase, schedule]);
 
   // Where the panel ended up, which is what both the slide and the origin
   // describe. Held across the exit with the placement itself.
@@ -495,7 +546,19 @@ export function FloatingPanel({
             motionStyle,
             style,
           ]}>
-          {children}
+          {/*
+            The panel IS a surface, so it publishes the rung its children sit on.
+            Without it a `TextField` inside a menu or popover stepped off the PAGE
+            and landed on the panel's own fill — 1.000:1, no shell at all
+            (`styles/surface-levels.ts`).
+
+            Level 1 for EVERY surface, not only `isMenuSurface`: that flag says
+            who PAINTS the chrome (`popover` resolves its own in
+            `popover/surface.ts`), not whether there is one. Keying the rung off
+            it published level 0 inside a popover, which is the case the ladder
+            exists for.
+          */}
+          <SurfaceLevelProvider level={1}>{children}</SurfaceLevelProvider>
         </AnimatedPanel>
       </OverlayRoot>
     </Portal>