@oxyhq/bloom 0.35.7 → 0.36.0

package/src/__tests__/FrostedIconButton.web.test.tsx

@@ -0,0 +1,246 @@
+/**
+ * @jest-environment jsdom
+ */
+
+import React from 'react';
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { getByRole, fireEvent } from '@testing-library/dom';
+import { renderToStaticMarkup } from 'react-dom/server';
+import '@testing-library/jest-dom';
+
+import { BloomThemeProvider } from '../theme/BloomThemeProvider';
+import { FrostedIconButton } from '../frosted-icon-button/FrostedIconButton.web';
+import { parseRgb } from '../theme/color-utils';
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+let container: HTMLDivElement;
+let root: Root;
+
+function mount(ui: React.ReactElement, mode: 'light' | 'dark' = 'dark'): HTMLElement {
+  act(() => {
+    root.render(
+      <BloomThemeProvider mode={mode} colorPreset="blue">
+        {ui}
+      </BloomThemeProvider>,
+    );
+  });
+  return container;
+}
+
+beforeEach(() => {
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  root = createRoot(container);
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  container.remove();
+});
+
+// Mention's measured dark page background — the "invisible circle" bug composited
+// a near-black `card` fill onto this and vanished. The frosted chip must read.
+const PAGE_DARK = { r: 11, g: 11, b: 15 };
+
+/** Composite an `rgba(...)` surface over an opaque background (source-over). */
+function compositeOver(surface: string, bg: { r: number; g: number; b: number }) {
+  const base = parseRgb(surface);
+  const m = /rgba?\(([^)]+)\)/i.exec(surface);
+  const rawAlpha = m?.[1]?.split(',')[3];
+  const a = rawAlpha === undefined ? 1 : Number(rawAlpha);
+  if (!base) throw new Error(`not an rgba string: ${surface}`);
+  return {
+    r: Math.round(bg.r * (1 - a) + base.r * a),
+    g: Math.round(bg.g * (1 - a) + base.g * a),
+    b: Math.round(bg.b * (1 - a) + base.b * a),
+  };
+}
+
+describe('FrostedIconButton.web', () => {
+  it('renders a real <button> with the accessible label', () => {
+    const c = mount(<FrostedIconButton accessibilityLabel="Back" icon={<span>x</span>} />);
+    const btn = getByRole(c, 'button', { name: 'Back' });
+    expect(btn.tagName).toBe('BUTTON');
+    expect(btn).toHaveClass('bloom-frosted-icon-btn');
+  });
+
+  it('self-injects its interaction stylesheet once', () => {
+    mount(<FrostedIconButton accessibilityLabel="Back" icon={<span>x</span>} />);
+    mount(<FrostedIconButton accessibilityLabel="Fwd" icon={<span>y</span>} />);
+    expect(document.querySelectorAll('#bloom-frosted-icon-button-web-css')).toHaveLength(1);
+  });
+
+  // THE bug this component exists to prevent: on a dark SOLID page, a `card`-fill
+  // circle composited to near-black and vanished. Prove the frosted surface is a
+  // LIGHT tint that reads as a distinct, clearly-lighter circle on rgb(11,11,15).
+  describe('reads on a solid dark background (nothing behind it)', () => {
+    it('uses a low-opacity LIGHT tint distinguishable from the page', () => {
+      const c = mount(<FrostedIconButton accessibilityLabel="Back" icon={<span>x</span>} />);
+      const btn = getByRole(c, 'button');
+      const surface = btn.style.backgroundColor;
+
+      // Not the page color, and a genuine translucent (rgba) surface.
+      expect(surface).not.toBe('rgb(11, 11, 15)');
+      expect(surface).toMatch(/^rgba\(/);
+
+      // The tint's BASE color is light (each channel high) — a light frost, not a
+      // dark card fill.
+      const base = parseRgb(surface);
+      if (!base) throw new Error('unreachable');
+      expect(base.r).toBeGreaterThanOrEqual(200);
+      expect(base.g).toBeGreaterThanOrEqual(200);
+      expect(base.b).toBeGreaterThanOrEqual(200);
+
+      // Composited over the page it is clearly LIGHTER than rgb(11,11,15).
+      const composite = compositeOver(surface, PAGE_DARK);
+      expect(composite.r - PAGE_DARK.r).toBeGreaterThanOrEqual(15);
+      expect(composite.g - PAGE_DARK.g).toBeGreaterThanOrEqual(15);
+      expect(composite.b - PAGE_DARK.b).toBeGreaterThanOrEqual(15);
+    });
+
+    it('renders a hairline ring and a shadow that survive dark mode', () => {
+      const c = mount(<FrostedIconButton accessibilityLabel="Back" icon={<span>x</span>} />);
+      const btn = getByRole(c, 'button');
+      // Ring: a translucent border COLOR is present inline (per-instance token).
+      expect(btn.style.borderColor).toMatch(/^rgba\(/);
+      // The hairline border-style/width live in the self-injected stylesheet.
+      const css = document.getElementById('bloom-frosted-icon-button-web-css')?.textContent ?? '';
+      expect(css).toMatch(/border-style:\s*solid/);
+      expect(css).toMatch(/border-width:\s*1px/);
+      // Shadow is NOT killed in dark mode.
+      expect(btn.style.boxShadow).not.toBe('');
+      expect(btn.style.boxShadow).toMatch(/rgba?\(/);
+    });
+
+    // jsdom's CSS engine drops `backdrop-filter`, so assert it via SSR style
+    // serialization — which emits EVERY style key exactly as the browser receives
+    // it (react-dom writes the same inline style on a real DOM <button>).
+    it('emits a real CSS backdrop-filter blur when frosted (and drops it when active)', () => {
+      const frosted = renderToStaticMarkup(
+        <BloomThemeProvider mode="dark" colorPreset="blue">
+          <FrostedIconButton accessibilityLabel="Back" icon={<span>x</span>} />
+        </BloomThemeProvider>,
+      );
+      expect(frosted).toMatch(/backdrop-filter:\s*blur\(\d+px\)/);
+
+      const active = renderToStaticMarkup(
+        <BloomThemeProvider mode="dark" colorPreset="blue">
+          <FrostedIconButton accessibilityLabel="Back" active icon={<span>x</span>} />
+        </BloomThemeProvider>,
+      );
+      // Active is solid: no blur (either absent or explicitly "none").
+      expect(active).not.toMatch(/backdrop-filter:\s*blur\(/);
+    });
+  });
+
+  describe('active (solid "on") state', () => {
+    it('fills opaque (no rgba alpha), drops the blur, and sets aria-pressed', () => {
+      const c = mount(<FrostedIconButton accessibilityLabel="Mute" active icon={<span>x</span>} />);
+      const btn = getByRole(c, 'button');
+      // Opaque solid fill — an `rgb(...)` (not translucent `rgba`).
+      expect(btn.style.backgroundColor).toMatch(/^rgb\(/);
+      expect(btn.style.backgroundColor).not.toMatch(/^rgba\(/);
+      expect(btn).toHaveAttribute('aria-pressed', 'true');
+      expect(btn).toHaveAttribute('data-active', 'true');
+      const bf = btn.style.getPropertyValue('backdrop-filter');
+      expect(bf === '' || bf === 'none').toBe(true);
+    });
+
+    it('reports aria-pressed=false when not active', () => {
+      const c = mount(<FrostedIconButton accessibilityLabel="Mute" icon={<span>x</span>} />);
+      expect(getByRole(c, 'button')).toHaveAttribute('aria-pressed', 'false');
+    });
+  });
+
+  describe('icon color', () => {
+    it('injects the theme icon color as a fallback fill on a bare icon', () => {
+      const c = mount(
+        <FrostedIconButton accessibilityLabel="Back" icon={<svg data-testid="ic" />} />,
+      );
+      const icon = c.querySelector('[data-testid="ic"]');
+      expect(icon?.getAttribute('fill')).toMatch(/^rgb/);
+    });
+
+    it('never overrides an explicit fill on the icon', () => {
+      const c = mount(
+        <FrostedIconButton
+          accessibilityLabel="Back"
+          icon={<svg data-testid="ic" fill="rgb(1, 2, 3)" />}
+        />,
+      );
+      expect(c.querySelector('[data-testid="ic"]')?.getAttribute('fill')).toBe('rgb(1, 2, 3)');
+    });
+  });
+
+  describe('light theme', () => {
+    it('uses a subtle DARK tint (base near-black) distinguishable from a white page', () => {
+      const c = mount(
+        <FrostedIconButton accessibilityLabel="Back" icon={<span>x</span>} />,
+        'light',
+      );
+      const surface = getByRole(c, 'button').style.backgroundColor;
+      expect(surface).toMatch(/^rgba\(/);
+      const base = parseRgb(surface);
+      if (!base) throw new Error('unreachable');
+      expect(base.r).toBeLessThanOrEqual(60);
+      expect(base.g).toBeLessThanOrEqual(60);
+      expect(base.b).toBeLessThanOrEqual(60);
+    });
+  });
+
+  describe('behavior', () => {
+    it('fires both onClick and onPress on click', () => {
+      const onClick = jest.fn();
+      const onPress = jest.fn();
+      const c = mount(
+        <FrostedIconButton
+          accessibilityLabel="Back"
+          onClick={onClick}
+          onPress={onPress}
+          icon={<span>x</span>}
+        />,
+      );
+      act(() => {
+        fireEvent.click(getByRole(c, 'button'));
+      });
+      expect(onClick).toHaveBeenCalledTimes(1);
+      expect(onPress).toHaveBeenCalledTimes(1);
+    });
+
+    it('does not fire handlers when disabled', () => {
+      const onPress = jest.fn();
+      const c = mount(
+        <FrostedIconButton accessibilityLabel="Back" disabled onPress={onPress} icon={<span>x</span>} />,
+      );
+      const btn = getByRole(c, 'button');
+      expect(btn).toBeDisabled();
+      act(() => {
+        fireEvent.click(btn);
+      });
+      expect(onPress).not.toHaveBeenCalled();
+    });
+
+    it('applies preset sizes (md = 36px, sm = 32px)', () => {
+      const c = mount(<FrostedIconButton accessibilityLabel="Back" size="md" icon={<span>x</span>} />);
+      expect(getByRole(c, 'button').style.width).toBe('36px');
+      const c2 = mount(<FrostedIconButton accessibilityLabel="Back" size="sm" icon={<span>x</span>} />);
+      expect(getByRole(c2, 'button').style.width).toBe('32px');
+    });
+
+    it('does not crash on an array-form style prop (StyleProp flattening)', () => {
+      const showBorder = false;
+      const c = mount(
+        <FrostedIconButton
+          accessibilityLabel="Back"
+          icon={<span>x</span>}
+          style={[{ marginTop: 8 }, showBorder && { borderColor: 'rgb(9, 9, 9)' }]}
+        />,
+      );
+      const btn = getByRole(c, 'button');
+      expect(btn.style.marginTop).toBe('8px');
+      expect(btn.getAttribute('style') ?? '').not.toMatch(/(^|;)\s*0\s*:/);
+    });
+  });
+});

package/src/content-panel/index.tsx

@@ -11,11 +11,12 @@
  * 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
- * (`md:` evaluates against the window width on native too — no JS breakpoint
- * hook needed):
+ * (the breakpoint's `min-*:` variant evaluates against the window width on
+ * native too — no JS breakpoint hook needed):
  *
- *  - `undefined` (DEFAULT) → responsive: full-bleed below `md`, rounded +
- *    bordered at `md`+ (`md:rounded-radius-28 md:border md:border-border`).
+ *  - `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.
  *
@@ -47,17 +48,35 @@ export const PANEL_TOP_INSET = 8;
 /** Bottom sticky inset (px) of the framed panel chrome. */
 export const PANEL_BOTTOM_INSET = 8;
 
+/**
+ * Viewport width (px) at which a RESPONSIVE `ContentPanel` (`framed` undefined)
+ * switches from full-bleed to framed. Each value maps to a PRE-SHIPPED literal
+ * Tailwind class bundle — `768` (default) uses the named `md:` screen
+ * (byte-identical to prior behavior), `640` uses `sm:`, `1024` uses `lg:`, and
+ * `500` uses the arbitrary `min-[500px]:` variant (there is no named screen at
+ * 500px). The breakpoint tokens are never built at runtime, so a consumer's
+ * Tailwind content-scan over `src/**`/`lib/**` resolves them verbatim.
+ */
+export type ContentPanelFramedBreakpoint = 500 | 640 | 768 | 1024;
+
 export interface ContentPanelProps {
   children: React.ReactNode;
   /**
    * Framing mode. Tri-state, resolved purely with NativeWind — no consumer
    * breakpoint hook needed:
-   * - `undefined` (DEFAULT) → responsive: full-bleed below `md`, rounded +
-   *   bordered at `md`+.
+   * - `undefined` (DEFAULT) → responsive: full-bleed below the `framedFrom`
+   *   breakpoint, rounded + bordered at/above it.
    * - `false` → never framed (plain full-bleed at every size).
    * - `true` → always rounded + bordered.
    */
   framed?: boolean;
+  /**
+   * Viewport width at which the RESPONSIVE panel switches from full-bleed to
+   * framed. Only meaningful when `framed` is `undefined` (responsive) — ignored
+   * when `framed` is `true` (always framed) or `false` (never framed). Defaults
+   * to `768` (Tailwind `md`), reproducing the prior fixed behavior exactly.
+   */
+  framedFrom?: ContentPanelFramedBreakpoint;
   /** Override the surface background utility (defaults to `bg-card`). */
   surfaceClassName?: string;
   surfaceStyle?: StyleProp<ViewStyle>;
@@ -76,9 +95,24 @@ export interface ContentPanelProps {
   maskColor?: string;
 }
 
+/**
+ * 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,
@@ -87,13 +121,15 @@ const ContentPanelComponent: React.FC<ContentPanelProps> = ({
   // Dev-only invariant — a ContentPanel must never be nested inside another.
   useContentPanelNestingGuard();
 
-  // Tri-state: `undefined` → responsive (md:-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
-  // `md:` / `rounded-radius-28` token verbatim (no dynamic concatenation).
+  // 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 md:overflow-hidden md:rounded-radius-28 md:border md:border-border'
+      ? `flex-1 ${RESPONSIVE_SURFACE[framedFrom]}`
       : framed
         ? 'flex-1 overflow-hidden rounded-radius-28 border border-border'
         : 'flex-1';

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

@@ -26,18 +26,22 @@
  * Framing is tri-state via the `framed` prop:
  *
  *  - `undefined` (DEFAULT) → RESPONSIVE, driven purely by NativeWind: full-bleed
- *    below `md`, framed at `md`+. The rounding is `md:`-gated and both overlays
- *    are always rendered but carry `max-md:hidden` (`display:none` below `md`),
- *    so the breakpoint is decided in CSS — no consumer JS breakpoint hook.
+ *    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-md:hidden` literal) 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).
+ * 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`.
@@ -63,17 +67,37 @@ export const PANEL_TOP_INSET = 8;
 /** Bottom sticky inset (px) of the framed panel chrome. */
 export const PANEL_BOTTOM_INSET = 8;
 
+/**
+ * Viewport width (px) at which a RESPONSIVE `ContentPanel` (`framed` undefined)
+ * switches from full-bleed to framed. Each value maps to a PRE-SHIPPED literal
+ * Tailwind class bundle — `768` (default) uses the named `md:`/`max-md:` screens
+ * (byte-identical to prior behavior), `640` uses `sm:`/`max-sm:`, `1024` uses
+ * `lg:`/`max-lg:`, and `500` uses the arbitrary `min-[500px]:`/`max-[500px]:`
+ * variants (there is no named screen at 500px). The breakpoint tokens are never
+ * built at runtime, so a consumer's Tailwind content-scan over `lib/**` resolves
+ * them verbatim.
+ */
+export type ContentPanelFramedBreakpoint = 500 | 640 | 768 | 1024;
+
 export interface ContentPanelProps {
   children: React.ReactNode;
   /**
    * Framing mode. Tri-state, resolved purely with NativeWind — no consumer
    * breakpoint hook needed:
-   * - `undefined` (DEFAULT) → responsive: full-bleed below `md`, framed at
-   *   `md`+ (rounded corners + sticky bleed-mask/border overlays).
+   * - `undefined` (DEFAULT) → responsive: full-bleed below the `framedFrom`
+   *   breakpoint, framed at/above it (rounded corners + sticky bleed-mask/border
+   *   overlays).
    * - `false` → never framed (full-bleed at every size).
    * - `true` → always framed (rounded + overlays at every size).
    */
   framed?: boolean;
+  /**
+   * Viewport width at which the RESPONSIVE panel switches from full-bleed to
+   * framed. Only meaningful when `framed` is `undefined` (responsive) — ignored
+   * when `framed` is `true` (always framed) or `false` (never framed). Defaults
+   * to `768` (Tailwind `md`), reproducing the prior fixed behavior exactly.
+   */
+  framedFrom?: ContentPanelFramedBreakpoint;
   /** Override the surface background utility (defaults to `bg-card`). */
   surfaceClassName?: string;
   surfaceStyle?: StyleProp<ViewStyle>;
@@ -93,9 +117,50 @@ export interface ContentPanelProps {
   maskColor?: string;
 }
 
+/**
+ * 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,
@@ -112,18 +177,21 @@ const ContentPanelComponent: React.FC<ContentPanelProps> = ({
   // `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/`md:`/`web:` token stay literal).
-  // `web:md:overflow-x-clip` is platform-first-then-breakpoint, matching the
-  // consumer convention (`web:sm:flex` in `@mercaria/ui`).
+  // 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 md:rounded-radius-28'
+    ? `flex-1 ${bp.surface}`
     : framed
       ? 'flex-1 rounded-radius-28'
       : 'flex-1';
   const contentBase = responsive
-    ? 'flex-1 md:rounded-radius-28 web:md:overflow-x-clip'
+    ? `flex-1 ${bp.content}`
     : framed
       ? 'flex-1 rounded-radius-28 web:overflow-x-clip'
       : 'flex-1';
@@ -145,7 +213,7 @@ const ContentPanelComponent: React.FC<ContentPanelProps> = ({
             pointerEvents="none"
             {...({
               className: responsive
-                ? 'web:sticky web:top-2 z-30 h-[calc(100dvh-16px)] w-full rounded-radius-28 max-md:hidden 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 ${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)]',
             } as Record<string, string>)}
             style={{ boxShadow: `0 0 0 ${GUTTER_MASK_SPREAD}px ${maskColor ?? colors.background}` }}
@@ -159,7 +227,7 @@ const ContentPanelComponent: React.FC<ContentPanelProps> = ({
             pointerEvents="none"
             {...({
               className: responsive
-                ? 'web:sticky web:top-2 z-[120] h-[calc(100dvh-16px)] w-full rounded-radius-28 border border-border max-md:hidden 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 ${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)]',
             } as Record<string, string>)}
           />

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

@@ -0,0 +1,65 @@
+import React from 'react';
+import { View, ImageBackground } from 'react-native';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { FrostedIconButton } from './FrostedIconButton';
+import * as Icons from '../icons';
+
+const meta: Meta<typeof FrostedIconButton> = {
+  title: 'Components/FrostedIconButton',
+  component: FrostedIconButton,
+  args: {
+    accessibilityLabel: 'Back',
+    icon: <Icons.ChevronLeft_Stroke2_Corner0_Rounded size="md" />,
+    onPress: () => {},
+  },
+  argTypes: {
+    size: { control: 'select', options: ['sm', 'md'] },
+    active: { control: 'boolean' },
+    disabled: { control: 'boolean' },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof FrostedIconButton>;
+
+/** The frosted chip on a SOLID dark background — must read as a distinct button. */
+export const OnSolidDark: Story = {
+  render: (args) => (
+    <View style={{ padding: 40, backgroundColor: 'rgb(11, 11, 15)' }}>
+      <FrostedIconButton {...args} />
+    </View>
+  ),
+};
+
+/** The solid "on" state for toggles (no blur, brand fill). */
+export const Active: Story = {
+  render: (args) => (
+    <View style={{ padding: 40, backgroundColor: 'rgb(11, 11, 15)' }}>
+      <FrostedIconButton {...args} active />
+    </View>
+  ),
+};
+
+/** Frosting over an image (the reason it exists) — blur shows the banner behind. */
+export const OverImage: Story = {
+  render: (args) => (
+    <ImageBackground
+      source={{ uri: 'https://picsum.photos/600/300' }}
+      style={{ width: 320, height: 180, padding: 16, justifyContent: 'flex-start' }}
+    >
+      <FrostedIconButton {...args} />
+    </ImageBackground>
+  ),
+};
+
+/** Both sizes side by side. */
+export const Sizes: Story = {
+  render: (args) => (
+    <View style={{ flexDirection: 'row', gap: 12, padding: 40, backgroundColor: 'rgb(11, 11, 15)' }}>
+      <FrostedIconButton {...args} size="sm" />
+      <FrostedIconButton {...args} size="md" />
+    </View>
+  ),
+};