@oxyhq/bloom 0.88.0 → 1.0.0

package/src/combobox/Combobox.tsx

@@ -9,7 +9,7 @@ import {
 } from 'react-native';
 
 import { useTheme } from '../theme/use-theme';
-import { useControllableState } from '../hooks/useControllableState';
+import { useControllableState } from '../hooks/use-controllable-state';
 import { Text } from '../typography';
 import { Item } from '../item';
 import { Search } from '../search';
@@ -23,7 +23,7 @@ import type {
   PopoverProps,
   PopoverTriggerProps,
 } from '../popover/types';
-import type { usePopoverContext as usePopoverContextType } from '../popover/context';
+import type { usePopover as usePopoverType } from '../popover/context';
 import type { ComboboxOption, ComboboxProps } from './types';
 
 /**
@@ -36,7 +36,7 @@ interface PopoverModule {
   Popover: (props: PopoverProps) => React.ReactElement;
   PopoverTrigger: (props: PopoverTriggerProps) => React.ReactElement;
   PopoverContent: (props: PopoverContentProps) => React.ReactElement | null;
-  usePopoverContext: typeof usePopoverContextType;
+  usePopover: typeof usePopoverType;
 }
 
 function defaultFilter<T>(option: ComboboxOption<T>, query: string): boolean {
@@ -80,7 +80,7 @@ export function createCombobox(PopoverImpl: PopoverModule) {
   > &
     Pick<ComboboxProps<T>, 'label' | 'query' | 'onQueryChange' | 'disabled'>) {
     const theme = useTheme();
-    const { control } = PopoverImpl.usePopoverContext();
+    const popover = PopoverImpl.usePopover();
     const searchRef = useRef<TextInput>(null);
 
     const [query, setQuery] = useControllableState<string>({
@@ -104,54 +104,70 @@ export function createCombobox(PopoverImpl: PopoverModule) {
         if (option.disabled) return;
         onValueChange(option.value);
         setQuery('');
-        control.close();
+        popover.setOpen(false);
       },
-      [onValueChange, setQuery, control],
+      [onValueChange, setQuery, popover],
     );
 
     const accessibleLabel = label ?? placeholder;
 
     return (
       <>
-        <PopoverImpl.PopoverTrigger label={accessibleLabel}>
-          {({ props }) => (
-            <Pressable
-              {...props}
-              disabled={disabled}
-              onPress={() => {
-                if (disabled) return;
-                props.onPress();
-                if (Platform.OS === 'web') {
-                  requestAnimationFrame(() => searchRef.current?.focus());
-                }
-              }}
-              accessibilityState={{ disabled: disabled ?? false }}
+        {/* `asChild` composes rather than replaces: the trigger's own
+            `onPress` runs first and `TriggerSlot` opens the popover after it,
+            which is how the web focus hop below still happens on open.
+            `disabled` goes to BOTH — the popover must know not to open, and the
+            `Pressable` must draw and announce itself as disabled. */}
+        <PopoverImpl.PopoverTrigger
+          asChild
+          disabled={disabled}
+          label={accessibleLabel}
+          style={styles.triggerSlot}>
+          <Pressable
+            disabled={disabled}
+            onPress={() => {
+              if (disabled) return;
+              if (Platform.OS === 'web') {
+                requestAnimationFrame(() => searchRef.current?.focus());
+              }
+            }}
+            accessibilityState={{ disabled: disabled ?? false }}
+            style={[
+              styles.trigger,
+              {
+                backgroundColor: theme.colors.contrast50,
+                borderColor: theme.colors.borderLight,
+              },
+              disabled && styles.disabled,
+            ]}>
+            <Text
+              numberOfLines={1}
               style={[
-                styles.trigger,
+                styles.triggerText,
                 {
-                  backgroundColor: theme.colors.contrast50,
-                  borderColor: theme.colors.borderLight,
+                  color: selectedOption
+                    ? theme.colors.text
+                    : theme.colors.textSecondary,
                 },
-                disabled && styles.disabled,
               ]}>
-              <Text
-                numberOfLines={1}
-                style={[
-                  styles.triggerText,
-                  {
-                    color: selectedOption
-                      ? theme.colors.text
-                      : theme.colors.textSecondary,
-                  },
-                ]}>
-                {selectedOption ? selectedOption.label : placeholder}
-              </Text>
-              <ChevronUpDownIcon size="xs" fill={theme.colors.textSecondary} />
-            </Pressable>
-          )}
+              {selectedOption ? selectedOption.label : placeholder}
+            </Text>
+            <ChevronUpDownIcon size="xs" fill={theme.colors.textSecondary} />
+          </Pressable>
         </PopoverImpl.PopoverTrigger>
 
-        <PopoverImpl.PopoverContent label={accessibleLabel} placement="bottom-start" minWidth={240}>
+        <PopoverImpl.PopoverContent
+          label={accessibleLabel}
+          align="start"
+          minWidth={240}
+          // shadcn's own combobox opts out of the popover card the same way,
+          // with `className="w-[200px] p-0"`: this panel holds a search field
+          // and `Item` rows, which have to reach its edge to draw a full-width
+          // highlight, and it sizes to the field it drops from rather than to a
+          // fixed `w-72`. A CLASS, because that is what `PopoverContent`'s own
+          // chrome is now — an inline style would outrank it silently instead of
+          // replacing the two utilities it means to.
+          className="w-auto p-space-4">
           <View style={styles.searchWrap}>
             <Search
               ref={searchRef}
@@ -242,6 +258,12 @@ export function createCombobox(PopoverImpl: PopoverModule) {
 }
 
 const styles = StyleSheet.create({
+  // `TriggerSlot`'s wrapper is `alignSelf: 'flex-start'` so an anchored surface
+  // lines up with the CONTROL rather than the row it sits in. A combobox is the
+  // exception: its trigger is a full-width field, so the wrapper stretches.
+  triggerSlot: {
+    alignSelf: 'stretch',
+  },
   trigger: {
     flexDirection: 'row',
     alignItems: 'center',

package/src/combobox/index.ts

@@ -1,6 +1,7 @@
-import * as Popover from '../popover/index';
+import { usePopover } from '../popover/context';
+import { Popover, PopoverContent, PopoverTrigger } from '../popover/index';
 import { createCombobox } from './Combobox';
 
-export const Combobox = createCombobox(Popover);
+export const Combobox = createCombobox({ Popover, PopoverTrigger, PopoverContent, usePopover });
 
 export type { ComboboxProps, ComboboxOption } from './types';

package/src/combobox/index.web.ts

@@ -1,6 +1,7 @@
-import * as Popover from '../popover/index.web';
+import { usePopover } from '../popover/context';
+import { Popover, PopoverContent, PopoverTrigger } from '../popover/index.web';
 import { createCombobox } from './Combobox';
 
-export const Combobox = createCombobox(Popover);
+export const Combobox = createCombobox({ Popover, PopoverTrigger, PopoverContent, usePopover });
 
 export type { ComboboxProps, ComboboxOption } from './types';

package/src/command/Command.tsx

@@ -8,7 +8,7 @@ import {
 } from 'react-native';
 
 import { useTheme } from '../theme/use-theme';
-import { useControllableState } from '../hooks/useControllableState';
+import { useControllableState } from '../hooks/use-controllable-state';
 import { Text } from '../typography';
 import { Item } from '../item';
 import { Kbd } from '../kbd';
@@ -161,8 +161,8 @@ export function createCommand(Dialog: DialogComponent) {
   // Bridge the public *controlled* `visible` prop onto the Dialog's imperative
   // open/close (mirrors `AlertDialog`). `control` is referentially stable
   // (memoised on its id), so this effect only re-runs when `visible` actually
-  // flips. Opening straight from an effect on mount matches bloom's own
-  // `AutoMountedDialog`. When a consumer flips `visible` to `false` (their own
+  // flips. Opening straight from an effect on mount is Bloom's fresh-mount
+  // imperative-open pattern. When a consumer flips `visible` to `false` (their own
   // close, or after a select), we imperatively `close()` so the exit animation
   // still plays.
   const closingFromPropRef = useRef(false);

package/src/command/types.ts

@@ -1,5 +1,5 @@
 import type { StyleProp, ViewStyle } from 'react-native';
-import type { Props as IconProps } from '../icons/common';
+import type { Props as IconProps } from '../icons/shared';
 
 export interface CommandItem {
   /** Stable id. */

package/src/composition-bar/CompositionBar.tsx

@@ -75,7 +75,11 @@ const CompositionBarComponent: React.FC<CompositionBarProps> = ({
               onPress={() => onSelect(category.key)}
               accessibilityRole="button"
               accessibilityLabel={category.name}
+              // See `Chip`: `accessibilityState` carries this on native (which
+              // has no `aria-pressed`), `aria-pressed` on web (where
+              // react-native-web never reads `accessibilityState`).
               accessibilityState={{ selected: category.key === selectedKey }}
+              aria-pressed={category.key === selectedKey}
               style={[
                 styles.segment,
                 {

package/src/connection-dots/ConnectionDots.web.tsx

@@ -96,8 +96,16 @@ const ConnectionDotsComponent: React.FC<ConnectionDotsProps> = ({
     return (
       <View
         key={i}
-        // marker attribute lets the reduced-motion media query target dots
-        {...({ 'data-bloom-connection-dot': '' } as Record<string, string>)}
+        // Marker attribute, so the reduced-motion media query above can target
+        // the dots. It MUST go through `dataSet`: react-native-web filters props
+        // against a fixed list and silently drops anything outside it, so the
+        // literal `'data-bloom-connection-dot'` prop this used to spread never
+        // reached the DOM and the media query matched nothing — measured in a
+        // real browser, where the attribute was simply absent. The JS
+        // `matchMedia` gate below is what kept the behaviour correct, so the
+        // dead half was invisible: it is defence-in-depth for the case where the
+        // preference changes with no re-render.
+        {...({ dataSet: { bloomConnectionDot: '' } } as Record<string, unknown>)}
         style={[base, animated]}
       />
     );

package/src/connection-dots/ConnectionDotsBase.tsx

@@ -2,6 +2,7 @@ import React from 'react';
 import { View, type StyleProp, type ViewStyle } from 'react-native';
 
 import { atoms as a, tokens } from '../styles';
+import { StyledView } from '../styles/styled-primitives';
 import type { ConnectionDotsProps } from './types';
 
 export interface ConnectionDotsBaseProps
@@ -40,8 +41,8 @@ export function ConnectionDotsBase({
   ];
 
   return (
-    <View
-      {...(className ? ({ className } as Record<string, string>) : {})}
+    <StyledView
+      className={className}
       style={rowStyle}>
       <View style={[a.align_center, a.justify_center]}>{left}</View>
 
@@ -57,6 +58,6 @@ export function ConnectionDotsBase({
       </View>
 
       <View style={[a.align_center, a.justify_center]}>{right}</View>
-    </View>
+    </StyledView>
   );
 }

package/src/connection-status/ConnectionStatusToasts.tsx

@@ -0,0 +1,46 @@
+/**
+ * Connection loss as a toast, not a layout-shifting banner.
+ *
+ * Every Oxy app needs this and none of them should hand-roll it: a coloured bar
+ * sliding in above the header pushes the whole screen down, has to be themed
+ * again in each app, and competes with the app's own chrome. The toast host is
+ * already mounted, already themed, already stacks.
+ *
+ * NATIVE variant: `@react-native-community/netinfo` reports both link state and
+ * reachability. It is an OPTIONAL peer loaded through `./netinfo` — see that
+ * file for why it is not a static import, and why an app that omits it gets an
+ * inert component rather than a broken bundle. The web fork uses
+ * `navigator.onLine` instead so Vite/SPA consumers need no extra dependency at
+ * all.
+ */
+import { useEffect, useState } from 'react';
+
+import { loadNetInfo, warnNetInfoUnavailable } from './netinfo';
+import { useConnectionStatusToasts, type ConnectionStatusToastsProps } from './shared';
+
+/** Mount once at the app root. Renders nothing. */
+export function ConnectionStatusToasts(props: ConnectionStatusToastsProps = {}): null {
+  const [isOnline, setIsOnline] = useState<boolean | null>(null);
+
+  useEffect(() => {
+    const netInfo = loadNetInfo();
+    if (!netInfo) {
+      // `isOnline` stays `null`, which `useConnectionStatusToasts` already reads
+      // as "not determined yet", so the component is inert instead of broken.
+      warnNetInfoUnavailable();
+      return undefined;
+    }
+
+    // `isInternetReachable` is null until the first probe resolves; treat that
+    // as "connected as far as we know" so a captive-portal check never flashes
+    // an outage on launch.
+    return netInfo.addEventListener((state) => {
+      setIsOnline(Boolean(state.isConnected && state.isInternetReachable !== false));
+    });
+  }, []);
+
+  useConnectionStatusToasts(isOnline, props);
+  return null;
+}
+
+ConnectionStatusToasts.displayName = 'ConnectionStatusToasts';

package/src/connection-status/ConnectionStatusToasts.web.tsx

@@ -0,0 +1,34 @@
+/**
+ * Web variant — see `./index.tsx` for what this is and why it is a toast.
+ *
+ * `navigator.onLine` + the `online`/`offline` events are the browser's own
+ * signal, so a Vite/SPA consumer needs no native dependency to get the same
+ * behaviour. (The browser only knows about the link, not reachability; that is
+ * the honest limit of what a web app can detect without polling.)
+ */
+import { useEffect, useState } from 'react';
+
+import { useConnectionStatusToasts, type ConnectionStatusToastsProps } from './shared';
+
+/** Mount once at the app root. Renders nothing. */
+export function ConnectionStatusToasts(props: ConnectionStatusToastsProps = {}): null {
+  const [isOnline, setIsOnline] = useState<boolean | null>(null);
+
+  useEffect(() => {
+    if (typeof navigator === 'undefined' || typeof window === 'undefined') return undefined;
+
+    setIsOnline(navigator.onLine);
+    const update = () => setIsOnline(navigator.onLine);
+    window.addEventListener('online', update);
+    window.addEventListener('offline', update);
+    return () => {
+      window.removeEventListener('online', update);
+      window.removeEventListener('offline', update);
+    };
+  }, []);
+
+  useConnectionStatusToasts(isOnline, props);
+  return null;
+}
+
+ConnectionStatusToasts.displayName = 'ConnectionStatusToasts';

package/src/connection-status/index.ts

@@ -0,0 +1,4 @@
+export type { ConnectionStatusToastsProps } from './shared';
+export {
+  ConnectionStatusToasts,
+} from './ConnectionStatusToasts';

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

@@ -0,0 +1,4 @@
+export type { ConnectionStatusToastsProps } from './shared';
+export {
+  ConnectionStatusToasts,
+} from './ConnectionStatusToasts.web';

package/src/content-panel/ContentPanel.tsx

@@ -0,0 +1,106 @@
+/**
+ * Native variant of `ContentPanel` — the framed app-content surface.
+ *
+ * `ContentPanel` is the rounded, bordered panel that holds an app's routed
+ * content. On WEB it adds two sticky overlays (a gutter "bleed-mask" box-shadow
+ * ring and a continuous rounded border frame) so feed content that bleeds into
+ * the rounded corners / lateral gutters is masked while a single seamless border
+ * is drawn around the panel — see `index.web.tsx`.
+ *
+ * On NATIVE none of the WEB overlay machinery applies: there is no document
+ * scroll, no sticky positioning, and no bleed to mask, so the panel is simply a
+ * surface wrapping its content. The `framed` prop still drives whether that
+ * surface is rounded + bordered, tri-state and resolved with pure NativeWind
+ * (the breakpoint's `min-*:` variant evaluates against the window width on
+ * native too — no JS breakpoint hook needed):
+ *
+ *  - `undefined` (DEFAULT) → responsive: full-bleed below the `framedFrom`
+ *    breakpoint (default `768` / Tailwind `md`), rounded + bordered at/above it
+ *    (e.g. `md:rounded-radius-28 md:border md:border-border`).
+ *  - `false` → never framed (plain full-bleed at every size).
+ *  - `true` → always rounded + bordered.
+ *
+ * `showStickyFrame` and `maskColor` are accepted for cross-platform API parity
+ * but are no-ops here (there are no sticky overlays on native).
+ *
+ * Web bundlers select `./index.web` via the `"browser"` export condition in
+ * `package.json`; native bundlers fall through to this file.
+ *
+ * Styling is NativeWind-className-first; the literal class strings below must
+ * stay literal so a consumer's Tailwind content-scan over `lib/**` (and the
+ * native `src/**`) picks them up.
+ */
+import React, { memo } from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+
+import { StyledView } from '../styles/styled-primitives';
+import {
+  ContentPanelNestingContext,
+  useContentPanelNestingGuard,
+} from './context';
+import type { ContentPanelFramedBreakpoint, ContentPanelProps } from './types';
+
+/**
+ * Width (in px) of the WEB sticky gutter-mask box-shadow ring. Exported for
+ * cross-platform API parity (it has no effect on native).
+ */
+export const GUTTER_MASK_SPREAD = 40;
+/** Top sticky inset (px) of the framed panel chrome. */
+export const PANEL_TOP_INSET = 8;
+/** Bottom sticky inset (px) of the framed panel chrome. */
+export const PANEL_BOTTOM_INSET = 8;
+
+/**
+ * Per-breakpoint literal Tailwind surface class bundle for the NATIVE responsive
+ * mode. Each value is a WHOLE literal string (never assembled from parts at
+ * runtime) so the Tailwind content-scan over `src/**`/`lib/**` picks up every
+ * `min-*`/`sm:`/`md:`/`lg:` token verbatim. Selecting a bundle by `framedFrom`
+ * value is the only runtime decision.
+ */
+const RESPONSIVE_SURFACE: Record<ContentPanelFramedBreakpoint, string> = {
+  500: 'min-[500px]:overflow-hidden min-[500px]:rounded-radius-28 min-[500px]:border min-[500px]:border-border',
+  640: 'sm:overflow-hidden sm:rounded-radius-28 sm:border sm:border-border',
+  768: 'md:overflow-hidden md:rounded-radius-28 md:border md:border-border',
+  1024: 'lg:overflow-hidden lg:rounded-radius-28 lg:border lg:border-border',
+};
+
+const ContentPanelComponent: React.FC<ContentPanelProps> = ({
+  children,
+  framed,
+  framedFrom = 768,
+  surfaceClassName,
+  surfaceStyle,
+  contentClassName,
+  contentStyle,
+}) => {
+  // Dev-only invariant — a ContentPanel must never be nested inside another.
+  useContentPanelNestingGuard();
+
+  // Tri-state: `undefined` → responsive (breakpoint-gated), `true` → always
+  // framed, `false` → never framed (plain full-bleed). Whole literal class
+  // strings are selected per mode so the Tailwind content-scan over `src/**`
+  // picks up every `min-*`/`sm:`/`md:`/`lg:` / `rounded-radius-28` token verbatim
+  // (the breakpoint bundle lives whole in `RESPONSIVE_SURFACE`; `framed ===
+  // true`/`false` ignore `framedFrom` for fixed always/never framing).
+  const surfaceBase =
+    framed === undefined
+      ? `flex-1 ${RESPONSIVE_SURFACE[framedFrom]}`
+      : framed
+        ? 'flex-1 overflow-hidden rounded-radius-28 border border-border'
+        : 'flex-1';
+  const surfaceClass = [surfaceBase, surfaceClassName ?? 'bg-card'].join(' ');
+  const contentClass = ['flex-1', contentClassName].filter(Boolean).join(' ');
+
+  return (
+    <ContentPanelNestingContext.Provider value={true}>
+      <StyledView className={surfaceClass} style={surfaceStyle}>
+        <StyledView className={contentClass} style={contentStyle}>
+          {children}
+        </StyledView>
+      </StyledView>
+    </ContentPanelNestingContext.Provider>
+  );
+};
+
+export const ContentPanel = memo(ContentPanelComponent);
+ContentPanel.displayName = 'ContentPanel';

package/src/content-panel/ContentPanel.web.tsx

@@ -0,0 +1,198 @@
+/**
+ * Web variant of `ContentPanel` — the framed app-content surface.
+ *
+ * On the web, app content scrolls the DOCUMENT, and a multi-column shell keeps
+ * the routed content in a rounded, bordered center panel. Two problems follow
+ * from letting feed content bleed to the rounded panel edge, both solved here
+ * with sticky, full-viewport-height overlays inside the panel surface:
+ *
+ *  1. BLEED-MASK overlay (`z-30`): a `box-shadow` ring in the GUTTER color
+ *     (Bloom `background` token) drawn OVER content that bleeds into the thin
+ *     lateral gutter / rounded corners. `clip-path: inset(-12px)` keeps that
+ *     ring off the side columns. It sits below opaque chrome (headers/banners),
+ *     so it only masks the content's bleed, never the chrome. No border.
+ *     (`clip-path` MUST be the arbitrary class — RN-web drops it from `style`.)
+ *
+ *  2. BORDER-FRAME overlay (`z-[120]`): a single 1px rounded `border-border`
+ *     outline with a transparent interior, ABOVE all content. Being one element
+ *     above everything, it draws ONE continuous rounded border around all four
+ *     sides — no seams, no double lines, no per-chrome borders.
+ *
+ * Both overlays are `position: sticky; top: 8px` with a negative
+ * `margin-bottom` so they occupy zero layout height (they overlay the scrolled
+ * content rather than displacing it). They render BEFORE the content wrapper so
+ * z-index — not DOM order — decides layering.
+ *
+ * Framing is tri-state via the `framed` prop:
+ *
+ *  - `undefined` (DEFAULT) → RESPONSIVE, driven purely by NativeWind: full-bleed
+ *    below the `framedFrom` breakpoint, framed at/above it. The breakpoint is
+ *    configurable per consumer (`framedFrom`, default `768` / Tailwind `md`); the
+ *    rounding is gated by that breakpoint's `min-*:` variant and both overlays
+ *    are always rendered but carry the matching `max-*:hidden` literal
+ *    (`display:none` below the breakpoint), so the breakpoint is decided entirely
+ *    in CSS — no consumer JS breakpoint hook.
+ *  - `false` → NEVER framed (full-bleed at every size): a single flat surface,
+ *    no rounding, no overlays.
+ *  - `true` → ALWAYS framed (rounded + overlays at every size).
+ *
+ * The overlays are gated by VISIBILITY (a `max-*:hidden` literal for the chosen
+ * breakpoint) rather than by conditional mounting for the responsive case, so
+ * crossing the breakpoint never remounts them. The content wrapper likewise
+ * keeps a stable `key` so `{children}` reconciles in place across the breakpoint
+ * instead of remounting (which would reset feed scroll / the virtualizer +
+ * refetch).
+ *
+ * Native bundlers use `./index.tsx` (a plain rounded surface); web bundlers
+ * select this file via the `"browser"` export condition in `package.json`.
+ *
+ * Styling is NativeWind-className-first; the literal class strings below MUST
+ * stay literal so a consumer's Tailwind content-scan over `lib/**` picks them up
+ * (no dynamic concatenation of the arbitrary `web:[…]` / `rounded-radius-28` /
+ * `md:` parts — whole class strings are selected per mode instead).
+ */
+import React, { memo } from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+
+import { StyledView } from '../styles/styled-primitives';
+
+import { useTheme } from '../theme/use-theme';
+import {
+  ContentPanelNestingContext,
+  useContentPanelNestingGuard,
+} from './context';
+import type { ContentPanelFramedBreakpoint, ContentPanelProps } from './types';
+
+/** Width (in px) of the sticky gutter-mask box-shadow ring. */
+export const GUTTER_MASK_SPREAD = 40;
+/** Top sticky inset (px) the framed panel chrome pins to. */
+export const PANEL_TOP_INSET = 8;
+/** Bottom sticky inset (px) of the framed panel chrome. */
+export const PANEL_BOTTOM_INSET = 8;
+
+/**
+ * Per-breakpoint literal Tailwind variant tokens for the WEB responsive mode.
+ * Each field is a WHOLE literal class string (never assembled from parts at
+ * runtime) so the consumer's content-scan over `lib/**` picks up every
+ * arbitrary/`min-*`/`max-*`/`web:` token verbatim. Selecting a bundle by
+ * `framedFrom` value is the only runtime decision:
+ * - `surface`       → framing rounding on the surface at/above the breakpoint.
+ * - `content`       → the same rounding + a web-only horizontal clip on the
+ *   inner content wrapper (`web:<bp>:overflow-x-clip`, platform-first-then-
+ *   breakpoint — matching the consumer convention `web:sm:flex` in `@mercaria/ui`).
+ * - `overlayHidden` → `display:none` for the sticky overlays BELOW the breakpoint.
+ *   `min-[500px]:` (≥500) and `max-[500px]:` (<500) are exactly complementary
+ *   (meet at 500, no overlap/gap), mirroring the named `md:`/`max-md:` pair.
+ */
+const RESPONSIVE_WEB: Record<
+  ContentPanelFramedBreakpoint,
+  { surface: string; content: string; overlayHidden: string }
+> = {
+  500: {
+    surface: 'min-[500px]:rounded-radius-28',
+    content: 'min-[500px]:rounded-radius-28 web:min-[500px]:overflow-x-clip',
+    overlayHidden: 'max-[500px]:hidden',
+  },
+  640: {
+    surface: 'sm:rounded-radius-28',
+    content: 'sm:rounded-radius-28 web:sm:overflow-x-clip',
+    overlayHidden: 'max-sm:hidden',
+  },
+  768: {
+    surface: 'md:rounded-radius-28',
+    content: 'md:rounded-radius-28 web:md:overflow-x-clip',
+    overlayHidden: 'max-md:hidden',
+  },
+  1024: {
+    surface: 'lg:rounded-radius-28',
+    content: 'lg:rounded-radius-28 web:lg:overflow-x-clip',
+    overlayHidden: 'max-lg:hidden',
+  },
+};
+
+const ContentPanelComponent: React.FC<ContentPanelProps> = ({
+  children,
+  framed,
+  framedFrom = 768,
+  surfaceClassName,
+  surfaceStyle,
+  contentClassName,
+  contentStyle,
+  showStickyFrame,
+  maskColor,
+}) => {
+  // Dev-only invariant — must run unconditionally (before deriving any
+  // mode-specific branch) so the hook order stays stable (rules of hooks).
+  useContentPanelNestingGuard();
+  const { colors } = useTheme();
+
+  // Tri-state: `undefined` → responsive (md:-gated), `true` → always framed,
+  // `false` → never framed (full-bleed).
+  const responsive = framed === undefined;
+  const showOverlays = framed !== false;
+  // Responsive mode selects a pre-shipped literal breakpoint bundle by value;
+  // `framed === true`/`false` ignore `framedFrom` (fixed always/never framing).
+  const bp = RESPONSIVE_WEB[framedFrom];
+
+  // Whole literal class strings selected per mode (the Tailwind content-scan
+  // over `lib/**` requires each arbitrary/`min-*`/`max-*`/`web:` token stay
+  // literal — the breakpoint tokens live whole in `RESPONSIVE_WEB` above and are
+  // only spliced in, never assembled from parts).
+  const surfaceBase = responsive
+    ? `flex-1 ${bp.surface}`
+    : framed
+      ? 'flex-1 rounded-radius-28'
+      : 'flex-1';
+  const contentBase = responsive
+    ? `flex-1 ${bp.content}`
+    : framed
+      ? 'flex-1 rounded-radius-28 web:overflow-x-clip'
+      : 'flex-1';
+  const surfaceClass = [surfaceBase, surfaceClassName ?? 'bg-card'].join(' ');
+  const contentClass = [contentBase, contentClassName].filter(Boolean).join(' ');
+
+  return (
+    <ContentPanelNestingContext.Provider value={true}>
+      <StyledView className={surfaceClass} style={surfaceStyle}>
+        {/* (1) Bleed-mask overlay — gutter box-shadow ring, below chrome. Not
+            rendered when never-framed; `max-md:hidden` (display:none <md) when
+            responsive, so the breakpoint is decided in CSS, not by remounting. */}
+        {showOverlays && (
+          <StyledView
+            key="bleed-mask"
+            pointerEvents="none"
+            className={
+              responsive
+                ? `web:sticky web:top-2 z-30 h-[calc(100dvh-16px)] w-full rounded-radius-28 ${bp.overlayHidden} web:[margin-bottom:calc(-100dvh+16px)] web:[clip-path:inset(-12px)]`
+                : 'web:sticky web:top-2 z-30 h-[calc(100dvh-16px)] w-full rounded-radius-28 web:[margin-bottom:calc(-100dvh+16px)] web:[clip-path:inset(-12px)]'
+            }
+            style={{ boxShadow: `0 0 0 ${GUTTER_MASK_SPREAD}px ${maskColor ?? colors.background}` }}
+          />
+        )}
+        {/* (2) Border-frame overlay — one continuous rounded border, above all.
+            Same visibility gating as the bleed-mask. */}
+        {showOverlays && showStickyFrame !== false && (
+          <StyledView
+            key="border-frame"
+            pointerEvents="none"
+            className={
+              responsive
+                ? `web:sticky web:top-2 z-[120] h-[calc(100dvh-16px)] w-full rounded-radius-28 border border-border ${bp.overlayHidden} web:[margin-bottom:calc(-100dvh+16px)]`
+                : 'web:sticky web:top-2 z-[120] h-[calc(100dvh-16px)] w-full rounded-radius-28 border border-border web:[margin-bottom:calc(-100dvh+16px)]'
+            }
+          />
+        )}
+        {/* Content wrapper — STABLE position + key so toggling `framed` reconciles
+            in place instead of remounting `{children}` (which would reset feed
+            scroll/virtualizer + refetch on a breakpoint cross). Clipped to the
+            rounded panel shape on web when framed. */}
+        <StyledView key="content" className={contentClass} style={contentStyle}>
+          {children}
+        </StyledView>
+      </StyledView>
+    </ContentPanelNestingContext.Provider>
+  );
+};
+
+export const ContentPanel = memo(ContentPanelComponent);
+ContentPanel.displayName = 'ContentPanel';