@oxy.so/bloom 3.2.1 → 3.3.0

package/src/__tests__/support/composite.ts

@@ -0,0 +1,68 @@
+/**
+ * Compositing and WCAG maths for suites that measure a TRANSLUCENT surface.
+ *
+ * A pane you can see through has no colour of its own to read off a style prop:
+ * what a label lands on is the fill flattened onto whatever is behind it. Every
+ * gate on a glass material therefore needs the same four functions, and they
+ * are here so a new one does not start by copying them — which is how two
+ * copies of a luminance formula end up disagreeing about the sRGB knee.
+ *
+ * `theme/__tests__/glass-colors.test.ts` keeps its OWN copies, deliberately and
+ * with its own reasons written down; this is for everything since.
+ */
+
+export interface Rgba {
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+}
+
+/** Parse `#rgb`, `#rrggbb`, `rgb(...)` or `rgba(...)`. Throws on anything else. */
+export function parseColor(value: string): Rgba {
+  const hex = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(value.trim());
+  if (hex?.[1] !== undefined) {
+    const h = hex[1].length === 3 ? hex[1].replace(/./g, (c) => c + c) : hex[1];
+    return {
+      r: parseInt(h.slice(0, 2), 16),
+      g: parseInt(h.slice(2, 4), 16),
+      b: parseInt(h.slice(4, 6), 16),
+      a: 1,
+    };
+  }
+  const fn = /^rgba?\(([^)]*)\)$/.exec(value.trim());
+  if (!fn?.[1]) throw new Error(`unparseable colour: ${JSON.stringify(value)}`);
+  const parts = fn[1].split(/[\s,/]+/).filter(Boolean).map(Number);
+  if (parts.length < 3 || parts.some((n) => Number.isNaN(n))) {
+    throw new Error(`unparseable colour: ${JSON.stringify(value)}`);
+  }
+  return { r: parts[0] ?? 0, g: parts[1] ?? 0, b: parts[2] ?? 0, a: parts[3] ?? 1 };
+}
+
+/** Flatten a translucent colour onto an opaque one — source-over. */
+export function over(top: Rgba, bottom: Rgba): Rgba {
+  return {
+    r: top.r * top.a + bottom.r * (1 - top.a),
+    g: top.g * top.a + bottom.g * (1 - top.a),
+    b: top.b * top.a + bottom.b * (1 - top.a),
+    a: 1,
+  };
+}
+
+/** WCAG relative luminance. */
+export function luminance({ r, g, b }: Rgba): number {
+  const channel = (v: number): number => {
+    const c = v / 255;
+    return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+  };
+  return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+}
+
+/** WCAG contrast ratio, order-independent. */
+export function contrastRatio(a: Rgba, b: Rgba): number {
+  const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x) as [number, number];
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+export const WHITE: Rgba = { r: 255, g: 255, b: 255, a: 1 };
+export const BLACK: Rgba = { r: 0, g: 0, b: 0, a: 1 };

package/src/__tests__/support/constructed-style-sheets.ts

@@ -0,0 +1,68 @@
+/**
+ * A spec-shaped stand-in for constructed stylesheets, for the jsdom suites.
+ *
+ * jsdom 26 ships the `CSSStyleSheet` CONSTRUCTOR but neither `replaceSync` nor
+ * `document.adoptedStyleSheets`, so every jsdom test takes Bloom's `<style>`
+ * fallback. That makes the whole CSP-safe path — the reason
+ * `styles/adopt-style-sheet.ts` exists — invisible to jest unless a test
+ * installs the API itself. Without this, a mutation that deleted the adoption
+ * branch entirely would leave the suite green.
+ *
+ * Not collected as a suite: jest's `testMatch` wants `*.test.ts` / `*.spec.ts`.
+ */
+
+export interface FakeStyleSheet {
+  /** The CSS most recently handed to `replaceSync`. */
+  cssText: string;
+  /** How many times the sheet has been re-parsed, so a test can prove it wasn't. */
+  replaceSyncCalls: number;
+  replaceSync(css: string): void;
+}
+
+export interface ConstructedStyleSheetsHarness {
+  /** The document's adopted sheets, read live (the code reassigns the array). */
+  adopted(): readonly FakeStyleSheet[];
+  /** Drop the API again, restoring jsdom's own `CSSStyleSheet`. */
+  uninstall(): void;
+}
+
+export function installConstructedStyleSheets(): ConstructedStyleSheetsHarness {
+  class FakeCSSStyleSheet implements FakeStyleSheet {
+    cssText = '';
+    replaceSyncCalls = 0;
+
+    replaceSync(css: string): void {
+      this.cssText = css;
+      this.replaceSyncCalls += 1;
+    }
+  }
+
+  const previousConstructor = Object.getOwnPropertyDescriptor(
+    globalThis,
+    'CSSStyleSheet',
+  );
+
+  Object.defineProperty(globalThis, 'CSSStyleSheet', {
+    value: FakeCSSStyleSheet,
+    writable: true,
+    configurable: true,
+  });
+  Object.defineProperty(document, 'adoptedStyleSheets', {
+    value: [],
+    writable: true,
+    configurable: true,
+  });
+
+  return {
+    adopted: () =>
+      document.adoptedStyleSheets as unknown as readonly FakeStyleSheet[],
+    uninstall: () => {
+      Reflect.deleteProperty(document, 'adoptedStyleSheets');
+      if (previousConstructor) {
+        Object.defineProperty(globalThis, 'CSSStyleSheet', previousConstructor);
+      } else {
+        Reflect.deleteProperty(globalThis, 'CSSStyleSheet');
+      }
+    },
+  };
+}

package/src/__tests__/support/press-host.ts

@@ -0,0 +1,30 @@
+/**
+ * Pressing a component's OWN host node, and proving the component is what
+ * installed the handler being measured.
+ *
+ * `fireEvent.press` walks UP from the element it is handed to the nearest
+ * ancestor carrying an `onPress` prop, and it does not stop at host nodes — a
+ * COMPOSITE counts, because `getEventHandler` only reads `element.props`. So
+ * `<Thing onPress={fn}>` written in a test's own JSX catches the press itself.
+ * Measured on a (since removed) card component: with the handler deleted from the
+ * component the card rendered as an inert `View`, and the test still reported exactly one
+ * call. Green, and measuring nothing. Nine suites had the same shape.
+ *
+ * Asserting the host node's own `onPress` FIRST closes both halves:
+ *
+ *  - a component that installs no handler at all fails here, and
+ *  - a component that installs one which drops the caller's fails on the call
+ *    count, because `fireEvent` now finds a handler AT the node and never walks
+ *    past it to the test's own JSX.
+ *
+ * `host` must therefore be the node the component itself made pressable — the
+ * one carrying its `testID` / `accessibilityLabel` — not a `Text` deep inside
+ * it, or the walk-up is back and so is the hole.
+ */
+import { fireEvent } from '@testing-library/react-native';
+import type { ReactTestInstance } from 'react-test-renderer';
+
+export function pressHost(host: ReactTestInstance): void {
+  expect(typeof host.props.onPress).toBe('function');
+  fireEvent.press(host);
+}

package/src/__tests__/support/rendered-style.ts

@@ -0,0 +1,99 @@
+/**
+ * Reading what actually landed on a rendered node — shared by every suite that
+ * asserts the "className lands on the node the parent lays out" rule.
+ *
+ * Three components had the same two-node defect (`Button`, then `Fab` and
+ * `FrostedIconButton`), and asserting it needs the same two things each time:
+ * the HOST tree (composites do not appear in `toJSON()`, so a wrapper is only
+ * visible there) and a deep flatten of the `style` prop, because react-native-css
+ * merges a caller's class in as a `{ $$css: true, className }` descriptor
+ * ALONGSIDE the style objects rather than in a prop of its own.
+ */
+import type { ReactTestRendererJSON } from 'react-test-renderer';
+
+export type StyleEntry = Record<string, unknown>;
+
+export interface HostNode {
+  type: string;
+  props: Record<string, unknown>;
+  children: Array<HostNode | string> | null;
+}
+
+/**
+ * Deep-flatten an RN `style` prop (nested arrays, `false`/`null` holes) into the
+ * list of style objects that actually reached the node.
+ */
+export function styleEntries(style: unknown, out: StyleEntry[] = []): StyleEntry[] {
+  if (!style || typeof style !== 'object') return out;
+  if (Array.isArray(style)) {
+    for (const entry of style) styleEntries(entry, out);
+    return out;
+  }
+  out.push(style as StyleEntry);
+  return out;
+}
+
+/** Every style key/value that landed on a node, later entries winning. */
+export function resolvedStyle(style: unknown): StyleEntry {
+  return Object.assign({}, ...styleEntries(style)) as StyleEntry;
+}
+
+/** The class tokens react-native-css accepted for a node, in arrival order. */
+export function classNamesOn(style: unknown): string[] {
+  return styleEntries(style)
+    .filter((entry) => entry.$$css === true && typeof entry.className === 'string')
+    .map((entry) => String(entry.className));
+}
+
+export function isHostNode(value: unknown): value is HostNode {
+  return (
+    typeof value === 'object' && value !== null && typeof (value as HostNode).type === 'string'
+  );
+}
+
+/** Walk the HOST tree (composites are absent from `toJSON()`) for a testID. */
+export function findHost(
+  node: ReactTestRendererJSON | ReactTestRendererJSON[] | unknown,
+  testID: string,
+): HostNode | null {
+  if (Array.isArray(node)) {
+    for (const child of node) {
+      const hit = findHost(child, testID);
+      if (hit) return hit;
+    }
+    return null;
+  }
+  if (!isHostNode(node)) return null;
+  if (node.props.testID === testID) return node;
+  return findHost(node.children, testID);
+}
+
+/**
+ * Every host node in a rendered tree, in document order.
+ *
+ * The reason to walk `toJSON()` rather than `UNSAFE_root.findAll` is that the
+ * latter yields COMPOSITE instances too, so a `memo(fn)` component contributes
+ * two matches for one rendered element and every count is silently doubled —
+ * which reads as "the component rendered the thing twice", not as an artefact
+ * of the query.
+ */
+export function hostNodes(tree: unknown, out: HostNode[] = []): HostNode[] {
+  if (Array.isArray(tree)) {
+    for (const child of tree) hostNodes(child, out);
+    return out;
+  }
+  if (!isHostNode(tree)) return out;
+  out.push(tree);
+  return hostNodes(tree.children, out);
+}
+
+/**
+ * The host nodes a parent laid out. Callers assert the LENGTH themselves —
+ * "exactly one" is the property, and a helper that returned only the first would
+ * hide the second.
+ */
+export function renderedChildren(tree: unknown, hostTestID: string): HostNode[] {
+  const host = findHost(tree, hostTestID);
+  if (host === null) throw new Error(`no host rendered for testID "${hostTestID}"`);
+  return (host.children ?? []).filter(isHostNode);
+}

package/src/__tests__/support/unread-hook-fixture.ts

@@ -0,0 +1,33 @@
+/**
+ * A module that DELIBERATELY throws away one of the values a hook hands back, so
+ * `hook-subscriptions-are-read.test.ts` can prove its detector fires. It carries
+ * both halves of the control: `unreadFlag` is bound and never read, which the
+ * detector must report, and `readFlag` is bound and read, which it must stay
+ * quiet about — otherwise the cheapest way to green the gate would be deleting a
+ * binding that is doing its job.
+ *
+ * Nothing imports this at runtime. bob's `exclude` keeps it out of `lib/`, and
+ * `files: ["src", …]` does ship it inside the tarball's `src/` like the other
+ * 137 test files there — but no entry point reaches it, so no bundler links it.
+ * It is a plain `.ts` with no React import because the
+ * detector reads source, never types: a call named `use…` bound to a name is all
+ * the shape there is.
+ *
+ * The destructuring RENAMES, which is not decoration — it reproduces the shipped
+ * shape (`const { state: pressed, onIn: onPressIn } = useInteractionState()`) and
+ * it is what keeps the control honest. A hook declared in the same file as its
+ * caller mentions its own property names in its return type and its return
+ * object, and the detector counts every occurrence of a spelling as a possible
+ * read, so an unrenamed fixture would be silently unreportable for a reason no
+ * real call site has.
+ */
+
+/** Stands in for a real subscription — a hook by name, with two return values. */
+function useFixtureInteractionState(): { first: boolean; second: boolean } {
+  return { first: false, second: false };
+}
+
+export function fixtureComponentBody(): boolean {
+  const { first: readFlag, second: unreadFlag } = useFixtureInteractionState();
+  return readFlag;
+}

package/src/ai-chat/AiChatContainer.tsx

@@ -1,5 +1,11 @@
-import React, { useCallback, useMemo, useRef } from 'react';
-import { ScrollView, View } from 'react-native';
+import React, { forwardRef, useCallback, useImperativeHandle, useMemo, useRef } from 'react';
+import {
+  ScrollView,
+  View,
+  type LayoutChangeEvent,
+  type NativeScrollEvent,
+  type NativeSyntheticEvent,
+} from 'react-native';
 
 import { AgentThinking } from '../agent-thinking';
 import { Breadcrumb, BreadcrumbItem } from '../breadcrumb';
@@ -8,7 +14,7 @@ import { RiMoreFill } from '../icons/remix/RiMoreFill';
 import { RiShare2Line } from '../icons/remix/RiShare2Line';
 import { GlyphAction } from './AiChatControls';
 import { CONTAINER_RADIUS, dataHook, IS_WEB, useAiChatPalette, useAiChatWebCss } from './shared';
-import type { AiChatContainerProps, AiChatThreadProps } from './types';
+import type { AiChatContainerProps, AiChatThreadHandle, AiChatThreadProps } from './types';
 
 const DEFAULT_LABELS = {
   breadcrumb: 'Chat location',
@@ -20,6 +26,9 @@ const DEFAULT_LABELS = {
  * The AI chat's centre column: the centre column of the AI chat template.
  *
  *   section   fills its parent, radius 24, background-secondary, clipped
+ *   layer     the `background` slot, filling the section above its own paint
+ *             and below everything else, clipped to the same radius;
+ *             `surface={false}` drops that paint
  *   header    px 16 / pt 16, gap 8: the project › chat breadcrumb (flex 1) and
  *             the 16px share / more glyphs, 8 apart
  *   thread    the `children` — usually an `AiChatThread`
@@ -27,6 +36,9 @@ const DEFAULT_LABELS = {
  *             while `working`, then the `composer`
  *
  * `header` renders above all of it: the shell's `AiChatMobileHeader`.
+ *
+ * `project` is optional: without one the breadcrumb is the chat's own crumb
+ * alone, since a chat that belongs to nothing must not have to invent a folder.
  */
 export function AiChatContainer({
   project,
@@ -40,6 +52,8 @@ export function AiChatContainer({
   composer,
   working = false,
   workingLabel,
+  background,
+  surface = true,
   labels,
   style,
   testID,
@@ -58,10 +72,15 @@ export function AiChatContainer({
           flexDirection: 'column',
           overflow: 'hidden',
           borderRadius: CONTAINER_RADIUS,
-          backgroundColor: palette.secondary,
+          backgroundColor: surface ? palette.secondary : 'transparent',
         },
         style,
       ]}>
+      {background ? (
+        <View pointerEvents="none" style={{ position: 'absolute', top: 0, left: 0, right: 0, bottom: 0 }}>
+          {background}
+        </View>
+      ) : null}
       {header}
       <View
         style={{
@@ -76,9 +95,11 @@ export function AiChatContainer({
         }}>
         <View style={{ minWidth: 0, flex: 1 }}>
           <Breadcrumb accessibilityLabel={l.breadcrumb}>
-            <BreadcrumbItem icon={projectIcon} onPress={onProjectPress}>
-              {project}
-            </BreadcrumbItem>
+            {project === undefined ? null : (
+              <BreadcrumbItem icon={projectIcon} onPress={onProjectPress}>
+                {project}
+              </BreadcrumbItem>
+            )}
             <BreadcrumbItem current>{title}</BreadcrumbItem>
           </Breadcrumb>
         </View>
@@ -101,24 +122,124 @@ export function AiChatContainer({
 /**
  * The thread: the scrolling conversation, anchored to the bottom
  * so a short exchange sits just above the composer and grows upward — px 16 /
- * pt 16, turns 12 apart, a thin scrollbar. It follows the newest turn with a
- * smooth scroll whenever the content grows.
+ * pt 16, turns 12 apart, a thin scrollbar.
+ *
+ * It follows the newest turn with a smooth scroll whenever the content grows.
+ * That is the default and nothing else changes it; the timeline props are the
+ * ones a host with history needs and are each off unless asked for:
+ *
+ *   autoFollow / followAnimated / followThreshold   whether, how, and from how
+ *     close to the bottom the follow happens
+ *   onStartReached                                  a chat pages UPWARD; this
+ *     fires near the TOP, once per approach, re-arming when the reader leaves
+ *   maintainStartPosition                           the growth that answers an
+ *     `onStartReached` is added to the offset, so a page landing above the
+ *     reader does not move the turn they are reading
+ *   ref (`AiChatThreadHandle`)                      scrollToEnd /
+ *     scrollToOffset / the ScrollView, for a cursor jump or a restore
+ *
+ * There is no virtualization and no `scrollToIndex`: a host jumping to a turn
+ * measures its row (`onLayout`) and calls `scrollToOffset`.
  */
-export function AiChatThread({ children, style, testID }: AiChatThreadProps) {
+export const AiChatThread = forwardRef<AiChatThreadHandle, AiChatThreadProps>(function AiChatThread(
+  {
+    children,
+    autoFollow = true,
+    followAnimated = true,
+    followThreshold,
+    onStartReached,
+    onStartReachedThreshold = 300,
+    maintainStartPosition = false,
+    onScroll,
+    scrollEventThrottle = 16,
+    style,
+    testID,
+  },
+  ref,
+) {
   const scrollRef = useRef<ScrollView>(null);
   const lastHeight = useRef(0);
-  const onContentSizeChange = useCallback((_width: number, height: number) => {
-    const grew = height > lastHeight.current + 0.5;
-    const first = lastHeight.current === 0;
-    lastHeight.current = height;
-    if (grew && !first) scrollRef.current?.scrollToEnd({ animated: true });
+  const offset = useRef(0);
+  const viewport = useRef(0);
+  /** An `onStartReached` is out and its page has not landed yet. */
+  const pageOut = useRef(false);
+  /** The reader has left the top zone, so the next approach may fire again. */
+  const startArmed = useRef(true);
+
+  useImperativeHandle(
+    ref,
+    (): AiChatThreadHandle => ({
+      scrollToEnd: (options) => scrollRef.current?.scrollToEnd({ animated: options?.animated ?? true }),
+      scrollToOffset: ({ offset: y, animated = false }) => scrollRef.current?.scrollTo({ y, animated }),
+      getScrollView: () => scrollRef.current,
+    }),
+    [],
+  );
+
+  const listening = !!onScroll || !!onStartReached || followThreshold !== undefined || maintainStartPosition;
+
+  const handleScroll = useCallback(
+    (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      const { contentOffset, layoutMeasurement } = event.nativeEvent;
+      offset.current = contentOffset.y;
+      viewport.current = layoutMeasurement.height;
+      if (onStartReached) {
+        if (contentOffset.y <= onStartReachedThreshold) {
+          if (startArmed.current) {
+            startArmed.current = false;
+            pageOut.current = true;
+            onStartReached();
+          }
+        } else {
+          startArmed.current = true;
+        }
+      }
+      onScroll?.(event);
+    },
+    [onScroll, onStartReached, onStartReachedThreshold],
+  );
+
+  const onLayout = useCallback((event: LayoutChangeEvent) => {
+    viewport.current = event.nativeEvent.layout.height;
   }, []);
+
+  const onContentSizeChange = useCallback(
+    (_width: number, height: number) => {
+      const previous = lastHeight.current;
+      const grew = height > previous + 0.5;
+      const first = previous === 0;
+      lastHeight.current = height;
+      if (!grew || first) return;
+
+      // A page landing above the reader: keep the turn they are on where it is.
+      if (maintainStartPosition && pageOut.current) {
+        pageOut.current = false;
+        scrollRef.current?.scrollTo({ y: offset.current + (height - previous), animated: false });
+        return;
+      }
+      pageOut.current = false;
+
+      if (!autoFollow) return;
+      if (followThreshold !== undefined) {
+        // Measured against the height BEFORE the growth: was the reader near
+        // the bottom when this arrived?
+        const fromBottom = previous - offset.current - viewport.current;
+        if (fromBottom > followThreshold) return;
+      }
+      scrollRef.current?.scrollToEnd({ animated: followAnimated });
+    },
+    [autoFollow, followAnimated, followThreshold, maintainStartPosition],
+  );
+
   return (
     <ScrollView
       ref={scrollRef}
       testID={testID}
       {...dataHook('bloomAiChatScroll', 'thin')}
       onContentSizeChange={onContentSizeChange}
+      onLayout={onLayout}
+      onScroll={listening ? handleScroll : undefined}
+      scrollEventThrottle={listening ? scrollEventThrottle : undefined}
       style={[{ minHeight: 0, width: '100%', flex: 1 }, style]}
       contentContainerStyle={{
         // react-native-web gives every view `min-height: 0`, so a growing
@@ -135,4 +256,4 @@ export function AiChatThread({ children, style, testID }: AiChatThreadProps) {
       {children}
     </ScrollView>
   );
-}
+});

package/src/ai-chat/AiChatShell.tsx

@@ -39,6 +39,8 @@ const REVEAL_MS = 325;
 const REVEAL_OFFSET = 272;
 const DRAWER_EASE = Easing.bezier(0.4, 0, 0.2, 1);
 const DRAWER_MS = 300;
+/** An icon-only rail: one 36px control plus its 10px gutters. */
+const COLLAPSED_SIDEBAR_WIDTH = 56;
 
 const DEFAULT_LABELS = {
   openNavigation: 'Open navigation',
@@ -257,7 +259,9 @@ export function AiChatMobileHeader({ title, style, testID }: AiChatMobileHeaderP
  * The AI chat shell: the full AI chat
  * screen on background-full with a 12px frame.
  *
- *   lg and up   the floating `sidebar` in flow, 16 from the workspace
+ *   lg and up   the floating `sidebar` in flow, 16 from the workspace, at
+ *               `sidebarWidth` (or its own width) — `sidebarCollapsed` narrows
+ *               the column to `collapsedSidebarWidth` (56) for an icon rail
  *   workspace   the chat container flexing, then (xl and up) the `panel` 12 to
  *               its right at `panelWidth`; the resize grip on the chat's right
  *               edge trades width between them, clamped 320–560
@@ -272,9 +276,19 @@ export function AiChatMobileHeader({ title, style, testID }: AiChatMobileHeaderP
  *               over the workspace closes it
  *
  * The chat container reads the drawer controls through `AiChatMobileHeader`.
+ * Everything the shell knows — including `navPresented`, which says whether the
+ * nav is on screen at all — is published to any descendant through
+ * `useAiChatShell()`.
+ *
+ * `background` is a layer drawn above the shell's own paint and below all of
+ * it; with `surface={false}` neither the root nor the workspace paints, so the
+ * layer reaches the chat.
  */
 export function AiChatShell({
   sidebar,
+  sidebarWidth,
+  sidebarCollapsed = false,
+  collapsedSidebarWidth = COLLAPSED_SIDEBAR_WIDTH,
   mobileSidebar,
   children,
   panel,
@@ -287,6 +301,8 @@ export function AiChatShell({
   onNavOpenChange,
   panelOpen: panelOpenProp,
   onPanelOpenChange,
+  background,
+  surface = true,
   labels,
   style,
   testID,
@@ -368,10 +384,14 @@ export function AiChatShell({
       navCollapsed: !navInFlow,
       hasNav: !!mobileSidebar,
       hasPanel: !!panel,
+      // In flow it is always on screen; as a drawer, only while it is open.
+      navPresented: navInFlow ? !!sidebar : navOpen,
+      sidebarCollapsed,
       openNav: () => {
         setPanelOpen(false);
         setNavOpen(true);
       },
+      closeNav: () => setNavOpen(false),
       openPanel: () => {
         setNavOpen(false);
         setPanelOpen(true);
@@ -380,7 +400,20 @@ export function AiChatShell({
       panelIcon,
       labels: { openNavigation: l.openNavigation, openPanel: l.openPanel },
     }),
-    [wide, navInFlow, mobileSidebar, panel, setPanelOpen, setNavOpen, panelLabel, panelIcon, l],
+    [
+      wide,
+      navInFlow,
+      navOpen,
+      sidebar,
+      sidebarCollapsed,
+      mobileSidebar,
+      panel,
+      setPanelOpen,
+      setNavOpen,
+      panelLabel,
+      panelIcon,
+      l,
+    ],
   );
 
   const rootStyle: WebCssStyle = {
@@ -391,7 +424,7 @@ export function AiChatShell({
     gap: 16,
     overflow: 'hidden',
     padding: 12,
-    backgroundColor: palette.full,
+    backgroundColor: surface ? palette.full : 'transparent',
   };
 
   const veil = palette.isDark ? 'rgba(255, 255, 255, 0.05)' : 'rgba(0, 0, 0, 0.1)';
@@ -403,6 +436,11 @@ export function AiChatShell({
         testID={testID}
         onLayout={(event: LayoutChangeEvent) => setShellWidth(event.nativeEvent.layout.width)}
         style={[rootStyle, style]}>
+        {background ? (
+          <View pointerEvents="none" style={{ position: 'absolute', top: 0, left: 0, right: 0, bottom: 0 }}>
+            {background}
+          </View>
+        ) : null}
         {!navInFlow && mobileSidebar ? (
           <View
             aria-hidden={!navOpen}
@@ -416,7 +454,23 @@ export function AiChatShell({
           </View>
         ) : null}
 
-        {navInFlow ? <View style={{ position: 'relative', zIndex: 10, height: '100%' }}>{sidebar}</View> : null}
+        {navInFlow ? (
+          <View
+            style={{
+              position: 'relative',
+              zIndex: 10,
+              height: '100%',
+              // Untouched unless the host asked for a width: the sidebar has
+              // always sized itself.
+              ...(sidebarCollapsed
+                ? { width: collapsedSidebarWidth, flexShrink: 0, overflow: 'hidden' }
+                : sidebarWidth !== undefined
+                  ? { width: sidebarWidth, flexShrink: 0 }
+                  : null),
+            }}>
+            {sidebar}
+          </View>
+        ) : null}
 
         <Animated.View
           style={[
@@ -428,7 +482,7 @@ export function AiChatShell({
               flexDirection: 'column',
               gap: 8,
               overflow: 'hidden',
-              backgroundColor: palette.full,
+              backgroundColor: surface ? palette.full : 'transparent',
             },
             navInFlow ? null : workspaceStyle,
           ]}>