@oxy.so/bloom 2.10.0 → 2.12.0

package/src/chip/types.ts

@@ -2,7 +2,20 @@ import type { StyleProp, ViewStyle, TextStyle } from 'react-native';
 
 import type { AccentFill, AccentTone } from '../theme/accent-colors';
 
-export type ChipSize = 'small' | 'medium' | 'large';
+/**
+ * 24 / 24 / 28 / 32 / 40 tall. `xl` and `2xl` are the filter rungs: the scale
+ * used to stop at 28, which is why five families drew their own pill. The table
+ * is in `shared.ts`.
+ */
+export type ChipSize = 'small' | 'medium' | 'large' | 'xl' | '2xl';
+
+/**
+ * The three accent fills, plus `inverted`: a hairline pill on the page that
+ * turns the page's own reading pair OVER when selected, rather than promoting
+ * to the brand tone. `shared.ts` says why that is a different idea rather than
+ * a fourth loudness.
+ */
+export type ChipVariant = AccentFill | 'inverted';
 
 /**
  * Data hues: a category, a department, an objective — colours that carry
@@ -10,6 +23,13 @@ export type ChipSize = 'small' | 'medium' | 'large';
  */
 export type ChipHue = 'lime' | 'rose' | 'yellow' | 'cyan' | 'blue' | 'purple' | 'neutral' | 'gray' | 'soft';
 
+/**
+ * What a pressable chip IS, which decides the state ARIA reads it by:
+ * a toggle `button` (`aria-pressed`), a `radio` in a radiogroup
+ * (`aria-checked`), or a `tab` in a tablist (`aria-selected`).
+ */
+export type ChipRole = 'button' | 'radio' | 'tab';
+
 export interface ChipProps {
   /** Text content of the chip. */
   children?: React.ReactNode;
@@ -18,7 +38,7 @@ export interface ChipProps {
    * `subtle` on `Badge` — one concept, two names, resolved by the shared
    * {@link AccentFill}.
    */
-  variant?: AccentFill;
+  variant?: ChipVariant;
   /** Semantic color. */
   color?: AccentTone;
   /**
@@ -45,10 +65,55 @@ export interface ChipProps {
   onClose?: () => void;
   /** Whether the chip is in a selected state. */
   selected?: boolean;
+  /**
+   * What a pressable chip is to assistive technology. Default `button`
+   * (`aria-pressed`). Use `radio` inside a `radiogroup` and `tab` inside a
+   * `tablist` — the state attribute follows the role, and a `radio` announcing
+   * `aria-pressed` is invalid.
+   */
+  role?: ChipRole;
   /** Whether the chip is disabled. */
   disabled?: boolean;
+  /**
+   * Web only, for a roving-tabindex row: `-1` takes the chip out of the tab
+   * order so the row is a single tab stop. Inert on native.
+   */
+  tabIndex?: number;
+  /**
+   * Web only: key handling for a roving-tabindex row (arrows move focus).
+   * Inert on native.
+   */
+  onKeyDown?: (event: { key: string; preventDefault: () => void }) => void;
   style?: StyleProp<ViewStyle>;
   textStyle?: StyleProp<TextStyle>;
   accessibilityLabel?: string;
   testID?: string;
 }
+
+export interface ChipRowProps {
+  /** The pills. */
+  children?: React.ReactNode;
+  /** Between pills. Default 8. */
+  gap?: number;
+  /** Side padding inside the scroller, so the first and last pill clear the edge. */
+  contentInset?: number;
+  /**
+   * The colour the web edge fades blend into — the surface behind the row.
+   * Default the page background.
+   */
+  fadeColor?: string;
+  /**
+   * Room kept on every side for a pill's focus ring, taken back out again with
+   * negative margins so the row still lines up with what is above it. Default 4.
+   */
+  ringInset?: number;
+  /** What the row is: a `group` of toggles, a `radiogroup`, or a `tablist`. Default `group`. */
+  role?: 'group' | 'radiogroup' | 'tablist';
+  /** Names the row. Required for anything but a plain `group` of self-naming pills. */
+  accessibilityLabel?: string;
+  /** Marks the whole row disabled to assistive technology (web `aria-disabled`). */
+  disabled?: boolean;
+  style?: StyleProp<ViewStyle>;
+  contentContainerStyle?: StyleProp<ViewStyle>;
+  testID?: string;
+}

package/src/composer-panel/ComposerControls.tsx

@@ -13,6 +13,7 @@ import Animated, {
 import Svg, { Defs, LinearGradient, Rect, Stop } from 'react-native-svg';
 
 import { paintToCssImage, type ButtonStatePaint } from '../button/shared';
+import { DISABLED_OPACITY } from '../styles/tokens';
 import { RiArrowUpLine } from '../icons/remix/RiArrowUpLine';
 import { RiMic2Line } from '../icons/remix/RiMic2Line';
 import type { WebCssStyle } from '../styles/web-view-style';
@@ -187,7 +188,7 @@ function GradientFill({ paint, opacity = 1 }: { paint: ButtonStatePaint; opacity
 /**
  * Send (`bg-button-primary` disc): the accent gradient, its hover
  * gradient crossfading in over 150ms, the active gradient while held; disabled
- * paints the disabled gradient at 40% opacity (200ms). White 20px arrow.
+ * paints the disabled gradient at the disabled opacity (200ms). White 20px arrow.
  */
 export function SendButton({
   disabled,
@@ -211,7 +212,7 @@ export function SendButton({
     alignItems: 'center',
     justifyContent: 'center',
     borderRadius: 9999,
-    opacity: disabled ? 0.4 : 1,
+    opacity: disabled ? DISABLED_OPACITY : 1,
     cursor: disabled ? 'auto' : 'pointer',
     '--bloom-composer-ring': palette.focusRing,
   };

package/src/content-panel/ContentPanel.tsx

@@ -33,11 +33,14 @@
 import React, { memo } from 'react';
 import { type StyleProp, type ViewStyle } from 'react-native';
 
+import { useOptionalPanelChrome } from '../styles/panel-chrome';
 import { StyledView } from '../styles/styled-primitives';
+import { SurfaceLevelProvider, surfaceFillVars } from '../styles/surface-levels';
 import {
   ContentPanelNestingContext,
   useContentPanelNestingGuard,
 } from './context';
+import { usePanelSurfaceFill } from './shared';
 import type { ContentPanelFramedBreakpoint, ContentPanelProps } from './types';
 
 /**
@@ -68,13 +71,20 @@ const ContentPanelComponent: React.FC<ContentPanelProps> = ({
   children,
   framed,
   framedFrom = 768,
+  fill = false,
   surfaceClassName,
   surfaceStyle,
+  surfaceColor,
+  chrome = 'elevated',
+  shadow,
   contentClassName,
   contentStyle,
 }) => {
   // Dev-only invariant — a ContentPanel must never be nested inside another.
   useContentPanelNestingGuard();
+  const panelChrome = useOptionalPanelChrome();
+  // What the panel tells its subtree it is painted in (`./shared.ts`).
+  const publishedFill = usePanelSurfaceFill(surfaceClassName, surfaceStyle, surfaceColor);
 
   // Tri-state: `undefined` → responsive (breakpoint-gated), `true` → always
   // framed, `false` → never framed (plain full-bleed). Whole literal class
@@ -88,14 +98,41 @@ const ContentPanelComponent: React.FC<ContentPanelProps> = ({
       : 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(' ');
+  const surfaceClass = [surfaceBase, fill ? 'min-h-0' : '', surfaceClassName ?? 'bg-card'].filter(Boolean).join(' ');
+  // Native has no overlays: the surface itself carries the edge. `none` drops
+  // both, `border` keeps the class-drawn hairline, `elevated` adds the lift.
+  const chromeStyle =
+    framed === false || chrome === 'none' || chrome === 'border'
+      ? null
+      : shadow || panelChrome
+        ? { boxShadow: shadow ?? panelChrome?.shadow }
+        : null;
+  // `fill` is the panel's own height contract, and on native it is already
+  // met: both boxes are `flex: 1`, so in a bounded parent the panel reaches the
+  // bottom and a list inside it scrolls within it. What the prop adds here is
+  // `min-h-0`, so a tall child cannot push the panel past the box it was given
+  // — the same automatic-minimum-size trap as on web.
+  const contentClass = ['flex-1', fill ? 'min-h-0' : '', contentClassName].filter(Boolean).join(' ');
 
   return (
     <ContentPanelNestingContext.Provider value={true}>
-      <StyledView className={surfaceClass} style={surfaceStyle}>
+      <StyledView
+        className={surfaceClass}
+        style={[
+          // The surface variable rides the element that carries the fill, so
+          // the two can never disagree. A no-op on native; the provider below
+          // is what answers there. (`styles/surface-levels.ts`.)
+          surfaceFillVars(publishedFill),
+          chromeStyle,
+          surfaceStyle,
+        ]}
+      >
         <StyledView className={contentClass} style={contentStyle}>
-          {children}
+          {/* The panel is a surface: everything inside is sitting on rung 1,
+              painted in the colour this panel actually paints. */}
+          <SurfaceLevelProvider level={1} fill={publishedFill}>
+            {children}
+          </SurfaceLevelProvider>
         </StyledView>
       </StyledView>
     </ContentPanelNestingContext.Provider>

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

@@ -87,11 +87,14 @@ import { type StyleProp, type ViewStyle } from 'react-native';
 
 import { StyledView } from '../styles/styled-primitives';
 
+import { useOptionalPanelChrome } from '../styles/panel-chrome';
+import { SurfaceLevelProvider, surfaceFillVars } from '../styles/surface-levels';
 import { useTheme } from '../theme/use-theme';
 import {
   ContentPanelNestingContext,
   useContentPanelNestingGuard,
 } from './context';
+import { usePanelSurfaceFill } from './shared';
 import type { ContentPanelFramedBreakpoint, ContentPanelProps } from './types';
 
 /** Width (in px) of the sticky gutter-mask box-shadow ring. */
@@ -145,19 +148,29 @@ const ContentPanelComponent: React.FC<ContentPanelProps> = ({
   children,
   framed,
   framedFrom = 768,
+  fill = false,
   surfaceClassName,
   surfaceStyle,
+  surfaceColor,
   contentClassName,
   contentStyle,
   showStickyFrame,
+  chrome = 'elevated',
+  shadow,
   maskColor,
   overlaySizing = 'viewport',
-  overlayTopOffset,
+  overlayInset,
 }) => {
   // 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();
+  // The floating-panel edge the `Sidebar` wears. Optional: the panel drew its
+  // own surface long before it had a shadow, so it must not start throwing
+  // outside a provider.
+  const panelChrome = useOptionalPanelChrome();
+  // What the panel tells its subtree it is painted in (`./shared.ts`).
+  const publishedFill = usePanelSurfaceFill(surfaceClassName, surfaceStyle, surfaceColor);
 
   // Tri-state: `undefined` → responsive (md:-gated), `true` → always framed,
   // `false` → never framed (full-bleed).
@@ -182,6 +195,15 @@ const ContentPanelComponent: React.FC<ContentPanelProps> = ({
     : framed
       ? 'flex-1 rounded-radius-28 web:overflow-x-clip'
       : 'flex-1';
+  // `fill`: the panel takes the height its parent gives it and the CONTENT
+  // scrolls inside. `min-h-0` on both boxes is the whole trick — a flex child's
+  // automatic minimum size is its content, so without it the panel grows past
+  // the box it was told to fit and the scroller never gets a height to scroll
+  // against. The overflow goes on the content wrapper, never the surface: the
+  // surface is what the frame and the mask are drawn to, and a scrolling
+  // surface would scroll the edge with it.
+  const fillSurface = fill ? 'min-h-0' : '';
+  const fillContent = fill ? 'min-h-0 web:[overflow-y:auto]' : '';
   // `overlaySizing="panel"`: the surface becomes a single-cell CSS Grid so the
   // overlays and the content wrapper below can all be placed in that ONE cell
   // (`web:[grid-area:1/1]`) and each fill it exactly — `minmax(0,1fr)` (not
@@ -192,38 +214,52 @@ const ContentPanelComponent: React.FC<ContentPanelProps> = ({
   const gridStackClass = boundToPanel
     ? 'web:grid web:[grid-template-columns:minmax(0,1fr)] web:[grid-template-rows:minmax(0,1fr)]'
     : '';
-  const surfaceClass = [surfaceBase, gridStackClass, surfaceClassName ?? 'bg-card'].filter(Boolean).join(' ');
-  const contentClass = [contentBase, boundToPanel ? 'web:[grid-area:1/1]' : '', contentClassName]
+  const surfaceClass = [surfaceBase, fillSurface, gridStackClass, surfaceClassName ?? 'bg-card'].filter(Boolean).join(' ');
+  const contentClass = [contentBase, fillContent, boundToPanel ? 'web:[grid-area:1/1]' : '', contentClassName]
     .filter(Boolean)
     .join(' ');
 
-  // `overlayTopOffset`: the viewport-mode overlays are sized/positioned from
-  // literal Tailwind classes (`top-2`, `h-[calc(100dvh-16px)]`, a matching
-  // negative `margin-bottom`) because those values are constants known at
-  // build time. An offset is a runtime number (a consumer's measured header
-  // height), which a Tailwind arbitrary class can't express — content-scanning
-  // needs the literal class string in source, not a value computed later — so
-  // this shifts the same three properties via inline `style` instead, which
-  // has no such constraint. No-op in `panel` mode (already starts at the
-  // panel's own box) and when unset (0/undefined) — the className values are
-  // left standing on their own in both of those cases.
+  // The viewport-mode overlays are sized and positioned from literal Tailwind
+  // classes (`top-2`, `h-[calc(100dvh-16px)]`, the matching negative
+  // `margin-bottom`) because those values are constants known at build time.
+  // An INSET is a runtime number — a shell's gutter, a measured header — which
+  // a Tailwind arbitrary class cannot express (content-scanning needs the
+  // literal string in source, not a value computed later), so a non-default
+  // inset shifts the same three properties through inline `style` instead,
+  // which has no such constraint. The default (8/8) leaves the classes standing
+  // alone, and `panel` mode ignores the inset entirely — that mode already
+  // starts at the panel's own box.
+  //
   // RN's `ViewStyle.height`/`marginBottom` types only accept a number or a
-  // `${number}%` string (not an arbitrary CSS `calc()` string), because most
-  // of this type is shared with native, where `calc()` doesn't exist. This
-  // file is web-only, where it's a real, valid CSS value react-native-web
-  // passes straight through — the same reasoning `WebViewStyle`/`asViewStyle`
-  // document in OxyHQ/Mention's `types/webStyles.ts` for the identical need.
-  const topOffsetStyle = !boundToPanel && overlayTopOffset
+  // `${number}%` string, not an arbitrary CSS `calc()`, because most of that
+  // type is shared with native where `calc()` does not exist. This file is
+  // web-only, where it is a real value react-native-web passes straight
+  // through.
+  const insetTop = typeof overlayInset === 'number' ? overlayInset : (overlayInset?.top ?? PANEL_TOP_INSET);
+  const insetBottom =
+    typeof overlayInset === 'number' ? overlayInset : (overlayInset?.bottom ?? PANEL_BOTTOM_INSET);
+  const customInset = insetTop !== PANEL_TOP_INSET || insetBottom !== PANEL_BOTTOM_INSET;
+  const insetStyle = !boundToPanel && customInset
     ? ({
-        top: 8 + overlayTopOffset,
-        height: `calc(100dvh - ${16 + overlayTopOffset}px)`,
-        marginBottom: `calc(-100dvh + ${16 + overlayTopOffset}px)`,
+        top: insetTop,
+        height: `calc(100dvh - ${insetTop + insetBottom}px)`,
+        marginBottom: `calc(-100dvh + ${insetTop + insetBottom}px)`,
       } as unknown as ViewStyle)
     : undefined;
 
   return (
     <ContentPanelNestingContext.Provider value={true}>
-      <StyledView testID="content-panel-surface" className={surfaceClass} style={surfaceStyle}>
+      <StyledView
+        testID="content-panel-surface"
+        className={surfaceClass}
+        style={[
+          // `--bloom-surface` rides the element that carries the fill, so CSS
+          // below the panel and `useSurfaceFill()` below the panel cannot
+          // disagree about what the panel painted.
+          surfaceFillVars(publishedFill),
+          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. */}
@@ -239,17 +275,22 @@ const ContentPanelComponent: React.FC<ContentPanelProps> = ({
                   ? `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={{ ...topOffsetStyle, boxShadow: `0 0 0 ${GUTTER_MASK_SPREAD}px ${maskColor ?? colors.background}` }}
+            style={{ ...insetStyle, 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 && (
+        {showOverlays && showStickyFrame !== false && chrome !== 'none' && (
           <StyledView
             key="border-frame"
             testID="content-panel-border-frame"
             pointerEvents="none"
-            style={topOffsetStyle}
+            // The shadow rides the SAME element as the hairline, so the lift and
+            // the edge can never disagree about where the panel ends. It paints
+            // outward, into the gutter the page background shows.
+            style={[insetStyle, chrome === 'elevated' && (shadow || panelChrome)
+                ? { boxShadow: shadow ?? panelChrome?.shadow }
+                : null]}
             className={
               boundToPanel
                 ? `web:[grid-area:1/1] z-[120] h-full w-full rounded-radius-28 border border-border ${responsive ? bp.overlayHidden : ''}`
@@ -264,7 +305,11 @@ const ContentPanelComponent: React.FC<ContentPanelProps> = ({
             scroll/virtualizer + refetch on a breakpoint cross). Clipped to the
             rounded panel shape on web when framed. */}
         <StyledView key="content" testID="content-panel-content" className={contentClass} style={contentStyle}>
-          {children}
+          {/* The panel is a surface: everything inside is sitting on rung 1,
+              painted in the colour this panel actually paints. */}
+          <SurfaceLevelProvider level={1} fill={publishedFill}>
+            {children}
+          </SurfaceLevelProvider>
         </StyledView>
       </StyledView>
     </ContentPanelNestingContext.Provider>

package/src/content-panel/index.ts

@@ -4,4 +4,4 @@ export {
   PANEL_BOTTOM_INSET,
   ContentPanel,
 } from './ContentPanel';
-export type { ContentPanelFramedBreakpoint, ContentPanelProps } from './types';
+export type { ContentPanelChrome, ContentPanelFramedBreakpoint, ContentPanelProps } from './types';

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

@@ -4,4 +4,4 @@ export {
   PANEL_BOTTOM_INSET,
   ContentPanel,
 } from './ContentPanel.web';
-export type { ContentPanelFramedBreakpoint, ContentPanelProps } from './types';
+export type { ContentPanelChrome, ContentPanelFramedBreakpoint, ContentPanelProps } from './types';

package/src/content-panel/shared.ts

@@ -0,0 +1,76 @@
+/**
+ * What the panel tells its subtree it is painted in — shared by both forks, so
+ * web and native cannot answer the question differently.
+ *
+ * `ContentPanel` is the surface an app's routed content sits on, which makes it
+ * the container most often asked "what colour are you?" — by a sticky header
+ * that has to be opaque over the scrolling column, a tab rail, a search field's
+ * backing, a reply bar pinned to the bottom. Every one of those had to repeat
+ * the panel's own `bg-card` at its call site, and repeating it is what makes a
+ * change to the panel's surface a sweep through the app instead of one prop.
+ *
+ * So the panel publishes it: `styles/surface-levels.ts` carries the mechanism
+ * (the ambient rung, the exact `fill`, and the web variable), and this decides
+ * WHICH colour is the honest answer for a given set of props.
+ */
+import { useContext } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+
+import { BloomThemeContext } from '../theme/BloomThemeProvider';
+
+/**
+ * Whether a caller's `surfaceStyle` repaints the surface.
+ *
+ * Walked by hand rather than with `StyleSheet.flatten` for the reason
+ * `styles/flatten-web-style.ts` records: this repo's `react-native` jest mock
+ * stubs `flatten` as an identity no-op, so an array style would pass through
+ * unflattened and the answer would silently differ between a test and an app.
+ * Later entries win, mirroring React-Native array-style precedence; falsy holes
+ * and registered-style ids (bare numbers, unresolvable without the RN runtime)
+ * are skipped, and an id is treated as "cannot know" rather than "no colour".
+ */
+function repaintedByStyle(style: StyleProp<ViewStyle>): boolean {
+  if (!style) return false;
+  if (Array.isArray(style)) {
+    return style.some((entry) => repaintedByStyle(entry as StyleProp<ViewStyle>));
+  }
+  if (typeof style === 'number') return true;
+  return typeof style === 'object' && 'backgroundColor' in style && style.backgroundColor != null;
+}
+
+/**
+ * The exact fill the panel publishes, or `undefined` when it cannot know it.
+ *
+ * Four cases, in order:
+ *
+ *  - `surfaceColor` given — the caller stated it; nothing beats that.
+ *  - `surfaceClassName` given — the caller REPAINTED the surface with a utility
+ *    Bloom cannot resolve to a colour (that is the whole point of the prop), so
+ *    publishing `card` would be a confident lie. The panel falls back to
+ *    publishing the rung alone, which is the weaker answer it had before —
+ *    `surfaceColor` is how a caller in this case gets the exact one back.
+ *  - `surfaceStyle` carrying a `backgroundColor` — the same repaint by the other
+ *    door, and the panel has to stop claiming `card` for it too. The colour is
+ *    right there, but WHICH of the two paints is a platform question the panel
+ *    must not guess at: `styled()` appends the class descriptor AFTER the style
+ *    prop, so on native the class wins the array, while on web the inline style
+ *    wins the cascade. Publishing either one would be right on one platform and
+ *    quietly wrong on the other, so the panel publishes neither and the caller
+ *    names it with `surfaceColor`.
+ *  - none of them — the panel paints `bg-card`, so it publishes `colors.card`.
+ *
+ * Outside a `BloomThemeProvider` there is no palette to name, and the panel has
+ * always rendered there on native, so this stays optional rather than throwing:
+ * a panel does not start failing at the moment it gets more informative.
+ */
+export function usePanelSurfaceFill(
+  surfaceClassName: string | undefined,
+  surfaceStyle: StyleProp<ViewStyle>,
+  surfaceColor: string | undefined,
+): string | undefined {
+  const ctx = useContext(BloomThemeContext);
+  if (surfaceColor) return surfaceColor;
+  if (surfaceClassName) return undefined;
+  if (repaintedByStyle(surfaceStyle)) return undefined;
+  return ctx?.theme.colors.card;
+}

package/src/content-panel/types.ts

@@ -12,6 +12,9 @@ import { type StyleProp, type ViewStyle } from 'react-native';
  */
 export type ContentPanelFramedBreakpoint = 500 | 640 | 768 | 1024;
 
+/** How a framed `ContentPanel` draws its edge. */
+export type ContentPanelChrome = 'elevated' | 'border' | 'none';
+
 export interface ContentPanelProps {
   children: React.ReactNode;
   /**
@@ -30,9 +33,70 @@ export interface ContentPanelProps {
    * to `768` (Tailwind `md`), reproducing the prior fixed behavior exactly.
    */
   framedFrom?: ContentPanelFramedBreakpoint;
+  /**
+   * The panel's EDGE, when it is framed.
+   *
+   * - `'elevated'` (DEFAULT) — the hairline plus the floating-panel shadow the
+   *   `Sidebar` wears (`styles/panel-chrome.ts`), so the panel reads as a
+   *   surface lifted off the page rather than a box drawn on it.
+   * - `'border'` — the hairline alone, which is what this panel drew before.
+   * - `'none'` — no edge at all: a flat surface that still clips and rounds,
+   *   for an app whose page background already separates the two.
+   *
+   * Ignored while the panel is full-bleed (below `framedFrom`, or
+   * `framed={false}`) — there is no edge to draw.
+   */
+  chrome?: ContentPanelChrome;
+  /**
+   * Overrides the shadow `chrome="elevated"` draws (any `box-shadow` string).
+   * For an app that wants its own elevation without giving up the hairline.
+   */
+  shadow?: string;
+  /**
+   * The panel is the HEIGHT OF THE SPACE IT IS GIVEN, and its content scrolls
+   * inside it — instead of the panel growing with its content while the page
+   * scrolls underneath.
+   *
+   * This is what makes a framed column read as a panel: it reaches the bottom
+   * of the screen and closes there, the way the rail beside it does. Without
+   * it, a feed taller than the window gives a panel whose top edge you see and
+   * whose bottom edge is somewhere past the fold — an open-ended column, not a
+   * surface.
+   *
+   * It needs a parent that BOUNDS it (a flex column with a real height): an
+   * `AppShell` with `scroll="fixed"` or `scroll="container"`, or any screen
+   * that is `flex: 1`. In a document-scrolled page there is no height to fill
+   * and the panel keeps growing with its content — that page wants
+   * `scroll="document"`, not this prop.
+   *
+   * On web the content wrapper becomes the scroller. On native the panel and
+   * its content are already `flex: 1`, so a `FlatList`/`ScrollView` inside
+   * fills the panel and scrolls within it.
+   */
+  fill?: boolean;
   /** Override the surface background utility (defaults to `bg-card`). */
   surfaceClassName?: string;
   surfaceStyle?: StyleProp<ViewStyle>;
+  /**
+   * The colour this panel paints, when `surfaceClassName`/`surfaceStyle` has
+   * repainted it.
+   *
+   * The panel PUBLISHES its fill to everything inside it — `useSurfaceFill()`
+   * and, on web, `var(--bloom-surface)` — so in-panel chrome that has to be
+   * opaque in the panel's own colour (a sticky header, a tab rail, a reply bar)
+   * can ask instead of repeating a class. By default that colour is
+   * `theme.colors.card`, which is what the panel paints.
+   *
+   * A `surfaceClassName` override is a utility Bloom cannot resolve to a colour,
+   * so the panel stops claiming to know one rather than publishing a wrong
+   * answer — this prop is how the override says what it painted, and it is
+   * needed only then. A `surfaceStyle` carrying a `backgroundColor` is the same
+   * repaint by the other door and stops the claim the same way: the colour is
+   * legible there, but which of the class and the style actually paints differs
+   * by platform, so the panel refuses to guess. It changes nothing about how the
+   * panel LOOKS: the class or the style still paints the surface.
+   */
+  surfaceColor?: string;
   /** Extra utilities for the inner content wrapper. */
   contentClassName?: string;
   contentStyle?: StyleProp<ViewStyle>;
@@ -47,39 +111,38 @@ export interface ContentPanelProps {
    */
   maskColor?: string;
   /**
-   * How the WEB overlays (bleed-mask, border-frame) size themselves. No-op on
-   * native (there are no overlays to size).
-   * - `'viewport'` (DEFAULT) — sized to the dynamic viewport height (`100dvh`)
-   *   and `position: sticky`-pinned, so they read as a constant frame around
-   *   the visible slice of a panel whose own DOM height can exceed one screen
-   *   — the document-scroll case (e.g. a feed whose page grows with content).
-   *   Requires the panel to sit in a document that actually scrolls; see
-   *   `ContentPanel.web.tsx`'s doc comment.
-   * - `'panel'` — sized to the panel's own real box via CSS Grid layer-
-   *   stacking (the overlays and the content wrapper all occupy the same
-   *   grid cell) instead of viewport math. The right mode for a consumer
-   *   whose own shell already bounds the panel's height (no document
-   *   scroll — a fixed app shell with its own internal scroll containers),
-   *   where anything the consumer places outside the panel (e.g. a header
-   *   above it) must never be overlapped by an overlay sized to the whole
-   *   viewport.
+   * How the WEB overlays (the bleed-mask and the border frame) size themselves.
+   * No-op on native (there are no overlays to size).
+   *
+   * - `'viewport'` (DEFAULT) — the frame is a SCREEN-TALL sticky rectangle:
+   *   `100dvh` minus the insets, pinned at `overlayInset`. The panel's own box
+   *   grows with its content and the document scrolls it, while the edge stays
+   *   where the screen is — so the panel reads as a surface that occupies the
+   *   window from top to bottom and the content moves inside it. This is the
+   *   mode for a page that scrolls the document.
+   * - `'panel'` — the overlays are the panel's OWN box, through CSS Grid
+   *   layer-stacking (the overlays and the content wrapper share one grid
+   *   cell). The right mode when the panel's box already IS the visible area
+   *   (`fill`, inside a shell that bounds it) or when something the consumer
+   *   placed outside the panel — a header above it — must never be painted
+   *   over by an overlay sized to the whole viewport.
    */
   overlaySizing?: 'viewport' | 'panel';
   /**
-   * Pixels of REAL, persistent chrome the consumer has placed above the panel
-   * — outside it, in normal document flow — that the viewport-mode overlays
-   * (`overlaySizing="viewport"`, the default) do not otherwise know about.
-   * No-op when `overlaySizing="panel"` (that mode already starts at the
-   * panel's own box, wherever that is) and on native (no overlays there).
+   * The gap between the VIEWPORT's edge and the sticky frame, in `'viewport'`
+   * mode. Default 8.
+   *
+   * **It must equal the distance from the top of the screen to the panel's own
+   * top edge.** Sticky positioning leaves an element at its static position
+   * until scrolling would push it past the inset — so a panel that starts 16px
+   * down the page with an 8px inset draws its frame at 16, then SNAPS it to 8
+   * on the first scroll. That 8px jump is the whole bug, and it reads as the
+   * panel breathing. A shell passes its own gutter here.
    *
-   * The overlays are sized/positioned off the VIEWPORT (`top: 8px`,
-   * `height: calc(100dvh - 16px)`) on the assumption that the panel begins
-   * near the true top of the screen. A consumer with its own sticky chrome
-   * above the panel (a header, say, kept sticky-pinned the same way) shifts
-   * where the panel visually starts without moving the panel's own DOM
-   * position, so the overlays would still read from viewport 0 and paint
-   * over that chrome. This shifts their `top` down and shrinks their height
-   * by the same amount, so they begin exactly where the panel visually does.
+   * Takes a pair when the top and the bottom differ — persistent chrome above
+   * the panel (a sticky header the consumer keeps outside it) shifts where the
+   * panel visually starts without moving its DOM position, so the frame has to
+   * start lower without also ending higher.
    */
-  overlayTopOffset?: number;
+  overlayInset?: number | { top: number; bottom: number };
 }

package/src/creator-studio/ArtworkUploader.tsx

@@ -9,9 +9,10 @@ import { RiErrorWarningLine } from '../icons/remix/RiErrorWarningLine';
 import { RiImageLine } from '../icons/remix/RiImageLine';
 import { RiRefreshLine } from '../icons/remix/RiRefreshLine';
 import { useImageResolver } from '../image-resolver/context';
+import { isImageUrl } from '../image-resolver/is-image-url';
 import { useTheme } from '../theme/use-theme';
 import { Text } from '../typography';
-import { CARD_RADIUS, isImageUrl, resolveCreatorStudioPaint } from './shared';
+import { CARD_RADIUS, resolveCreatorStudioPaint } from './shared';
 import type { ArtworkUploaderLabels, ArtworkUploaderProps } from './types';
 
 /**