@oxy.so/bloom 4.1.0 → 4.3.0

package/src/__tests__/support/collision-fixture-barrel.ts

@@ -0,0 +1,20 @@
+/**
+ * A barrel that DELIBERATELY offers one name from two declarations, so that
+ * `barrel-name-collisions.test.ts` can prove its detector fires. It reproduces
+ * the shipped `Item` shape: a star export carrying `Item` from `item/`, and an
+ * explicit re-export binding that same name to a different component.
+ *
+ * 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
+ * test files there — but no entry point reaches it, so no bundler links it, and
+ * `package.json#exports` never names it.
+ *
+ * The `Card` lines below are the other half of the
+ * control: one name offered twice from ONE declaration, which the detector must
+ * stay quiet about — otherwise its cheapest fix would be deleting a legitimate
+ * redundant re-export.
+ */
+export * from '../../item';
+export { Card as Item } from '../../card';
+export { Card } from '../../card';
+export * from '../../card';

package/src/__tests__/support/commerce-harness.tsx

@@ -0,0 +1,97 @@
+/**
+ * The mount harness the four commerce suites share.
+ *
+ * Every one of them asserts EMITTED DOM — an `aria-*` attribute, a computed
+ * colour, whether a node exists at all — rather than the props it just passed,
+ * so each renders through the real react-native-web. The mock has to be
+ * installed by the SUITE (a `jest.mock` call is hoisted to the top of the file
+ * it is written in and does not travel through an import), which is why this
+ * module exports the harness and not the mock.
+ */
+import React from 'react';
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+
+import { BloomThemeProvider } from '../../theme/BloomThemeProvider';
+import type { Theme } from '../../theme/types';
+import { useTheme } from '../../theme/use-theme';
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+let container: HTMLDivElement;
+let root: Root;
+let lastTheme: Theme | null = null;
+
+function ThemeProbe() {
+  lastTheme = useTheme();
+  return null;
+}
+
+export function setupHarness(): void {
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    lastTheme = null;
+  });
+}
+
+export function mount(ui: React.ReactElement, mode: 'light' | 'dark' = 'light'): HTMLElement {
+  act(() => {
+    root.render(
+      <BloomThemeProvider mode={mode} colorPreset="teal">
+        <ThemeProbe />
+        {ui}
+      </BloomThemeProvider>,
+    );
+  });
+  return container;
+}
+
+export function theme(): Theme {
+  if (!lastTheme) throw new Error('theme not captured');
+  return lastTheme;
+}
+
+export function root$(): HTMLElement {
+  return container;
+}
+
+export function byTestId(id: string): HTMLElement {
+  const el = document.querySelector(`[data-testid="${id}"]`);
+  if (!(el instanceof HTMLElement)) throw new Error(`No element for testID "${id}"`);
+  return el;
+}
+
+export function queryTestId(id: string): HTMLElement | null {
+  return document.querySelector(`[data-testid="${id}"]`);
+}
+
+export function byLabel(label: string): HTMLElement {
+  const el = document.querySelector(`[aria-label="${label}"]`);
+  if (!(el instanceof HTMLElement)) throw new Error(`No element labelled "${label}"`);
+  return el;
+}
+
+export function allByRole(role: string): HTMLElement[] {
+  return Array.from(document.querySelectorAll(`[role="${role}"]`)).filter(
+    (el): el is HTMLElement => el instanceof HTMLElement,
+  );
+}
+
+export function click(el: HTMLElement): void {
+  act(() => {
+    el.click();
+  });
+}
+
+/** A colour as the DOM serialises it, for comparing against a computed style. */
+export function css(color: string): string {
+  const probe = document.createElement('div');
+  probe.style.color = color;
+  return probe.style.color;
+}

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

@@ -82,7 +82,7 @@ export function AiChatContainer({
         </View>
       ) : null}
       {header}
-      <View
+      {title != null || project != null || onShare || onMore ? <View
         style={{
           width: '100%',
           flexDirection: 'row',
@@ -94,20 +94,20 @@ export function AiChatContainer({
           paddingTop: 16,
         }}>
         <View style={{ minWidth: 0, flex: 1 }}>
-          <Breadcrumb accessibilityLabel={l.breadcrumb}>
+          {title != null || project != null ? <Breadcrumb accessibilityLabel={l.breadcrumb}>
             {project === undefined ? null : (
               <BreadcrumbItem icon={projectIcon} onPress={onProjectPress}>
                 {project}
               </BreadcrumbItem>
             )}
-            <BreadcrumbItem current>{title}</BreadcrumbItem>
-          </Breadcrumb>
+            {title == null ? null : <BreadcrumbItem current>{title}</BreadcrumbItem>}
+          </Breadcrumb> : null}
         </View>
         <View style={{ flexShrink: 0, flexDirection: 'row', alignItems: 'center', gap: 8 }}>
-          <GlyphAction icon={RiShare2Line} label={l.share} onPress={onShare} palette={palette} />
-          <GlyphAction icon={RiMoreFill} label={l.more} onPress={onMore} palette={palette} />
+          {onShare ? <GlyphAction icon={RiShare2Line} label={l.share} onPress={onShare} palette={palette} /> : null}
+          {onMore ? <GlyphAction icon={RiMoreFill} label={l.more} onPress={onMore} palette={palette} /> : null}
         </View>
-      </View>
+      </View> : null}
 
       {children}
 

package/src/ai-chat/types.ts

@@ -283,8 +283,8 @@ export interface AiChatContainerProps {
    * and no folder glyph.
    */
   project?: string;
-  /** The current chat crumb. */
-  title: string;
+  /** The optional current chat crumb. Omit with project to use only your header slot. */
+  title?: string;
   /** The project crumb's glyph. Default `RiFolderLine`. */
   projectIcon?: BloomIconComponent;
   onProjectPress?: () => void;

package/src/app-shell/AppShellBars.tsx

@@ -31,6 +31,7 @@ import { View, type LayoutChangeEvent } from 'react-native';
 import { SafeAreaInsetsContext } from 'react-native-safe-area-context';
 
 import { WEB_POSITION_FIXED, WEB_POSITION_STICKY, type WebCssStyle } from '../styles/web-view-style';
+import { BottomBarSlotContext } from '../layout/bottom-bar-slot';
 import { useClaimBottomEdge } from '../layout/bottom-edge';
 import { Z_INDEX } from '../styles/z-index';
 
@@ -98,7 +99,7 @@ const AppShellBottomBarComponent: React.FC<AppShellBottomBarProps> = ({
       onLayout={onLayout}
       style={[anchorBottom(doc), { paddingBottom: insets.bottom }]}
     >
-      {children}
+      <BottomBarSlotContext.Provider value={insets.bottom}>{children}</BottomBarSlotContext.Provider>
     </View>
   );
 };
@@ -152,6 +153,7 @@ AppShellFloatingAction.displayName = 'AppShellFloatingAction';
 
 export interface AppShellTopBarProps {
   children: React.ReactNode;
+  onHeightChange?: (height: number) => void;
   doc: boolean;
   testID?: string;
 }
@@ -165,11 +167,11 @@ export interface AppShellTopBarProps {
  * only as far as `top: 0`); in `container`/`fixed` and on native it is simply
  * outside the scroller, which pins it by construction.
  */
-const AppShellTopBarComponent: React.FC<AppShellTopBarProps> = ({ children, doc, testID }) => {
+const AppShellTopBarComponent: React.FC<AppShellTopBarProps> = ({ children, doc, testID, onHeightChange }) => {
   const insets = useShellInsets();
   const pinned: WebCssStyle = doc ? { position: WEB_POSITION_STICKY, top: 0 } : {};
   return (
-    <View testID={testID} style={[{ zIndex: Z_INDEX.floating, paddingTop: insets.top }, pinned]}>
+    <View testID={testID} onLayout={event => onHeightChange?.(event.nativeEvent.layout.height)} style={[{ zIndex: Z_INDEX.floating, paddingTop: insets.top }, pinned]}>
       {children}
     </View>
   );

package/src/app-shell/AppShellEngine.tsx

@@ -17,7 +17,7 @@ import { Backdrop, OverlayRoot } from '../overlay';
 import { Portal } from '../portal';
 import { Sidebar } from '../sidebar';
 import { BREAKPOINTS } from '../styles/breakpoints';
-import { WEB_OVERFLOW_CLIP, WEB_POSITION_FIXED, WEB_POSITION_STICKY, type WebCssStyle } from '../styles/web-view-style';
+import { webViewportHeightMinus, WEB_OVERFLOW_CLIP, WEB_POSITION_FIXED, WEB_POSITION_STICKY, type WebCssStyle } from '../styles/web-view-style';
 import { useTheme } from '../theme/use-theme';
 import { AppShellBottomBar, AppShellFloatingAction, AppShellTopBar, useShellInsets } from './AppShellBars';
 import { AppShellHeader } from './AppShellHeader';
@@ -221,7 +221,8 @@ const AppShellComponent: React.FC<AppShellEngineProps> = ({
     return () => document.removeEventListener('keydown', dismiss);
   }, [isOpen, drawerStyle, setOpen]);
 
-  const feedRevealAvailable = variant === 'feed' && drawerStyle === 'reveal' && drawerAvailable;
+  const revealAvailable = drawerStyle === 'reveal' && drawerAvailable;
+  const feedRevealAvailable = variant === 'feed' && revealAvailable;
   const feedRevealed = feedRevealAvailable && isOpen;
 
   const shell = useMemo(
@@ -271,6 +272,7 @@ const AppShellComponent: React.FC<AppShellEngineProps> = ({
   const showTopBar = topBar != null && barActive(topBarVisibility);
   const showBottomBar = bottomBar != null && barActive(bottomBarVisibility);
   const showFloatingAction = floatingAction != null;
+  const [topBarHeight, setTopBarHeight] = useState(0);
   const [bottomBarHeight, setBottomBarHeight] = useState(0);
   const [floatingActionHeight, setFloatingActionHeight] = useState(0);
   // Both slots are MEASURED rather than assumed: a bar's height is its
@@ -285,7 +287,7 @@ const AppShellComponent: React.FC<AppShellEngineProps> = ({
     <SurfaceLevelProvider level={compactPanel ? 1 : 0} fill={compactPanel ? theme.colors.card : background}>
       {showBottomBar ? (
         <AppShellBottomBar
-          doc={doc && !feedRevealAvailable}
+          doc={doc && !revealAvailable}
           onHeightChange={setBottomBarHeight}
           testID={testID ? `${testID}-bottom-bar` : undefined}
         >
@@ -294,7 +296,7 @@ const AppShellComponent: React.FC<AppShellEngineProps> = ({
       ) : null}
       {showFloatingAction ? (
         <AppShellFloatingAction
-          doc={doc && !feedRevealAvailable}
+          doc={doc && !revealAvailable}
           offset={bottomEdge + gutter}
           gutter={gutter}
           placement={floatingActionPlacement}
@@ -308,7 +310,7 @@ const AppShellComponent: React.FC<AppShellEngineProps> = ({
   );
 
   const topBarNode = showTopBar ? (
-    <AppShellTopBar doc={doc} testID={testID ? `${testID}-top-bar` : undefined}>
+    <AppShellTopBar doc={doc} onHeightChange={setTopBarHeight} testID={testID ? `${testID}-top-bar` : undefined}>
       {topBar}
     </AppShellTopBar>
   ) : null;
@@ -492,7 +494,15 @@ const AppShellComponent: React.FC<AppShellEngineProps> = ({
             ) : null}
           </Animated.View>
           {overlay}
-          {bars}
+          {drawerAvailable ? (
+            <Animated.View
+              testID={testID ? `${testID}-reveal-bars` : undefined}
+              pointerEvents={isOpen ? 'none' : 'box-none'}
+              style={[{ position: doc ? WEB_POSITION_FIXED : 'absolute', top: 0, bottom: 0, left: 0, right: 0, overflow: 'hidden' }, pageStyle]}
+            >
+              {bars}
+            </Animated.View>
+          ) : bars}
         </View>
       </AppShellProvider>
     );
@@ -512,6 +522,8 @@ const AppShellComponent: React.FC<AppShellEngineProps> = ({
   /** `feed` / `focus`: a fixed reading column, centred in what the nav leaves. */
   const contentAligned = navigationAlign === 'content' && centred;
   // Plain navigation belongs to the viewport; only the reading surfaces are inset.
+  const documentPanelInset = feedRevealed ? 12 : compactPanel ? 0 : gutter;
+  const externalTopHeight = showTopBar ? topBarHeight : 0;
   const plainDocumentFrame = doc && contentAligned && flowSidebar?.surface === 'plain' && !topBarNode;
   const readingGap = Math.max(0, asideGap ?? columnGap);
   const readingGroupWidth = contentWidth + (asideBeside ? asideWidth + readingGap : 0);
@@ -592,10 +604,13 @@ const AppShellComponent: React.FC<AppShellEngineProps> = ({
               // exactly where the panel starts. Left at the 8px default it
               // would sit 8px above the panel's real top edge and snap down on
               // the first scroll — the panel appearing to breathe.
-              overlayInset={feedRevealed ? 12 : gutter}
+              overlayInset={{ top: externalTopHeight + documentPanelInset, bottom: documentPanelInset }}
               // The panel's own `flex-1` (basis 0) would collapse to nothing in
               // a document-flow column, which has no free space to distribute.
-              surfaceStyle={{ flexGrow: 1, flexShrink: 1, flexBasis: 'auto' }}
+              surfaceStyle={{ flexGrow: 1, flexShrink: 1, flexBasis: 'auto',
+                // The viewport frame must have a painted surface even when the
+                // page is short. A minimum still lets long documents grow.
+                minHeight: webViewportHeightMinus(externalTopHeight + documentPanelInset * 2) }}
               contentStyle={{ flexGrow: 1, flexShrink: 1, flexBasis: 'auto' }}
             >
               {/* Header chrome spans the panel. Its own title/action insets

package/src/bottom-bar/BottomBarBase.tsx

@@ -1,8 +1,9 @@
-import { useRef, useState, type ComponentType } from 'react';
+import { useContext, useRef, useState, type ComponentType } from 'react';
 import { View, ScrollView, Keyboard, Platform } from 'react-native';
 import { useEffect } from 'react';
 import Animated, { useAnimatedReaction, useAnimatedStyle, interpolate, runOnJS, useReducedMotion } from 'react-native-reanimated';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import { BottomBarSlotContext } from '../layout/bottom-bar-slot';
 import { useClaimBottomEdge } from '../layout/bottom-edge';
 import { FAB_METRICS } from '../fab/constants';
 import { windowEdgeGap } from '../layout/edge';
@@ -17,7 +18,7 @@ interface Props extends BottomBarProps {
   Item: ComponentType<TabBarButtonProps>;
   Blur: ComponentType<ProgressiveBlurProps>;
 }
-export function BottomBarBase({ Navigation, Item, Blur, items, value, onValueChange, action,
+export function BottomBarBase({ Navigation, Item, Blur, items, value, onValueChange, activeProgress, onValueLongPress, action,
   actionPlacement = 'auto', actionBehavior = 'hide', material = 'translucent', minimizeProgress, blur = true, maxWidth = 560, style, testID }: Props) {
   const insets = useSafeAreaInsets();
   const minimize = useMinimizeState();
@@ -45,14 +46,15 @@ export function BottomBarBase({ Navigation, Item, Blur, items, value, onValueCha
     node.inert = actionHidden;
   }, [actionHidden]);
   const [keyboardVisible, setKeyboardVisible] = useState(false);
-  const bottom = windowEdgeGap(insets.bottom);
+  const suppliedBottomInset = useContext(BottomBarSlotContext);
+  const bottom = Math.max(0, windowEdgeGap(insets.bottom) - (suppliedBottomInset ?? 0));
   useEffect(() => {
     if (Platform.OS === 'web') return;
     const show = Keyboard.addListener('keyboardDidShow', () => setKeyboardVisible(true));
     const hide = Keyboard.addListener('keyboardDidHide', () => setKeyboardVisible(false));
     return () => { show.remove(); hide.remove(); };
   }, []);
-  useClaimBottomEdge(keyboardVisible ? 0 : bottom + footprint);
+  useClaimBottomEdge(keyboardVisible || suppliedBottomInset !== undefined ? 0 : bottom + footprint);
   const rowStyle = useAnimatedStyle(() => ({
     height: interpolate(reducedMotion ? Number(progress.value > 0.01) : progress.value, [0, 1], [EXPANDED_HEIGHT, MINIMIZED_HEIGHT], 'clamp'),
   }), [progress, reducedMotion]);
@@ -70,6 +72,7 @@ export function BottomBarBase({ Navigation, Item, Blur, items, value, onValueCha
     {blur && material === 'translucent' && <Blur direction="bottom" style={{ position: 'absolute', left: 0, right: 0, bottom: 0, height: bottom + footprint + BLUR_BLEED }} />}
     <Animated.View testID={testID ? `${testID}-row` : undefined} onLayout={event => setRowWidth(event.nativeEvent.layout.width)} pointerEvents="box-none" style={[{ justifyContent: items.length ? 'center' : 'flex-end', alignSelf: 'center', width: '100%', maxWidth, paddingLeft: 12, paddingRight: 12, marginBottom: bottom, flexDirection: 'row', alignItems: 'center' }, rowStyle]}>
       {items.length > 0 && <View testID={testID ? `${testID}-navigation` : undefined} style={{ width: navigationWidth, minWidth: 0 }}><ScrollView horizontal showsHorizontalScrollIndicator={false} contentContainerStyle={{ minWidth: '100%' }}><View style={{ width: Math.max(navigationWidth, items.length * 44 + 8) }}><Navigation scrollable={navigationWidth > 0 && navigationWidth < items.length * 44 + 8} embedded blur={false} material={material} minimizeProgress={progress}
+        activeProgress={activeProgress} onIndexLongPress={onValueLongPress ? index => { if (items[index]) onValueLongPress(items[index].name); } : undefined}
         activeIndex={items.findIndex(item => item.name === value)} onIndexChange={index => { if (items[index]) onValueChange(items[index].name); }}>
         {items.map((item, index) => <Item key={item.name} item={item} index={index} />)}
       </Navigation></View></ScrollView></View>}

package/src/bottom-bar/types.ts

@@ -7,6 +7,10 @@ export interface BottomBarProps {
   items: TabBarItem[];
   value: string;
   onValueChange: (value: string) => void;
+  /** Optional continuous selection supplied by a swipe pager, in item-index space. */
+  activeProgress?: SharedValue<number>;
+  /** Long press on a destination (for example an account switcher). */
+  onValueLongPress?: (value: string) => void;
   /** Static action sibling; outside the navigation scrub detector. */
   action?: ReactNode;
   /** Auto places the action above navigation when side-by-side targets would be cramped. */

package/src/layout/bottom-bar-slot.ts

@@ -0,0 +1,4 @@
+import { createContext } from 'react';
+
+/** Bottom safe area already supplied by the measured app-shell slot. */
+export const BottomBarSlotContext = createContext<number | undefined>(undefined);