@oxyhq/bloom 0.51.1 → 0.52.1

package/lib/typescript/module/toast/position-utils.d.ts

@@ -5,16 +5,21 @@ export declare const getOrderedToastIds: (toasts: ToastProps[], position: ToastP
  *
  * Scale rather than width: changing the real width would rewrap the text. Returns
  * 1 (no squeeze) for a single row, an expanded stack, stacking turned off, or
- * before the window width is known.
+ * before the row width is known.
+ *
+ * `rowWidth` is the row's OWN width, not the window's. Upstream can use the
+ * screen width because its row is always full-bleed; Bloom's is capped at
+ * `TOAST_MAX_ROW_WIDTH`, and dividing a fixed `stackGap` inset by a 1280px window
+ * would shrink a buried row by 4 visible pixels instead of the intended 16.
  */
-export declare const calculateStackScaleX: ({ index, numberOfToasts, enableStacking, position, isExpanded, stackGap, screenWidth, }: {
+export declare const calculateStackScaleX: ({ index, numberOfToasts, enableStacking, position, isExpanded, stackGap, rowWidth, }: {
     index: number;
     numberOfToasts: number;
     enableStacking: boolean;
     position: ToastPosition;
     isExpanded: boolean;
     stackGap: number;
-    screenWidth: number;
+    rowWidth: number;
 }) => number;
 export declare const calculateToastPosition: ({ index, numberOfToasts, enableStacking, position, allToastHeights, gap, orderedToastIds, isExpanded, stackGap, }: {
     index: number;

package/lib/typescript/module/toast/position-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"position-utils.d.ts","sourceRoot":"","sources":["../../../../src/toast/position-utils.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAEzD,eAAO,MAAM,kBAAkB,GAC7B,QAAQ,UAAU,EAAE,EACpB,UAAU,aAAa,EACvB,gBAAgB,OAAO,KACtB,KAAK,CAAC,MAAM,GAAG,MAAM,CAQvB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAAI,yFAQlC;IACD,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,OAAO,CAAC;IACxB,QAAQ,EAAE,aAAa,CAAC;IACxB,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB,KAAG,MASH,CAAC;AAaF,eAAO,MAAM,sBAAsB,GAAI,mHAUpC;IACD,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,OAAO,CAAC;IACxB,QAAQ,EAAE,aAAa,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC,MAAM,GAAG,MAAM,EAAE,MAAM,CAAC,CAAC;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ,eAAe,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;IACxC,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB,KAAG,MAoDH,CAAC"}
+{"version":3,"file":"position-utils.d.ts","sourceRoot":"","sources":["../../../../src/toast/position-utils.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAEzD,eAAO,MAAM,kBAAkB,GAC7B,QAAQ,UAAU,EAAE,EACpB,UAAU,aAAa,EACvB,gBAAgB,OAAO,KACtB,KAAK,CAAC,MAAM,GAAG,MAAM,CAQvB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,GAAI,sFAQlC;IACD,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,OAAO,CAAC;IACxB,QAAQ,EAAE,aAAa,CAAC;IACxB,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB,KAAG,MASH,CAAC;AAaF,eAAO,MAAM,sBAAsB,GAAI,mHAUpC;IACD,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,OAAO,CAAC;IACxB,QAAQ,EAAE,aAAa,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC,MAAM,GAAG,MAAM,EAAE,MAAM,CAAC,CAAC;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ,eAAe,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;IACxC,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB,KAAG,MAoDH,CAAC"}

package/lib/typescript/module/zoomable-image-gallery/ZoomableImageGallery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ZoomableImageGallery.d.ts","sourceRoot":"","sources":["../../../../src/zoomable-image-gallery/ZoomableImageGallery.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA4D,MAAM,OAAO,CAAC;AAkEjF,OAAO,KAAK,EAGV,0BAA0B,EAC1B,yBAAyB,EAC1B,MAAM,SAAS,CAAC;AA44BjB,eAAO,MAAM,oBAAoB,8GAA4B,CAAC;AAyK9D,eAAe,oBAAoB,CAAC"}
+{"version":3,"file":"ZoomableImageGallery.d.ts","sourceRoot":"","sources":["../../../../src/zoomable-image-gallery/ZoomableImageGallery.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA4D,MAAM,OAAO,CAAC;AAkEjF,OAAO,KAAK,EAGV,0BAA0B,EAC1B,yBAAyB,EAC1B,MAAM,SAAS,CAAC;AA64BjB,eAAO,MAAM,oBAAoB,8GAA4B,CAAC;AAyK9D,eAAe,oBAAoB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/bloom",
-  "version": "0.51.1",
+  "version": "0.52.1",
   "description": "Bloom UI — Oxy ecosystem component library for React Native + Expo + Web",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
@@ -477,6 +477,11 @@
     },
     "./motion": {
       "react-native": "./src/motion/index.ts",
+      "browser": {
+        "types": "./lib/typescript/module/motion/index.web.d.ts",
+        "import": "./lib/module/motion/index.web.js",
+        "require": "./lib/commonjs/motion/index.web.js"
+      },
       "import": {
         "types": "./lib/typescript/module/motion/index.d.ts",
         "default": "./lib/module/motion/index.js"

package/src/__tests__/Motion.test.tsx

@@ -1,6 +1,10 @@
 import React from 'react';
 import { Text } from 'react-native';
 import { render } from '@testing-library/react-native';
+import type {
+  EntryOrExitLayoutType,
+  LayoutAnimation,
+} from 'react-native-reanimated';
 
 import {
   ScaleAndFadeIn,
@@ -12,21 +16,45 @@ import {
 // The reanimated mock resolves `withTiming(v)` -> v, `withDelay(d, v)` -> v and
 // `withSequence(...v)` -> last, so the builder output is deterministic.
 
+/**
+ * The presets are typed as reanimated's `entering`/`exiting` union so the two
+ * platform files present ONE contract and nothing can depend on the mechanism.
+ * These tests are about the native mechanism specifically, so they narrow back
+ * down through a runtime check rather than a cast: a predefined builder is a
+ * class (it carries the `createInstance` static), a custom worklet builder is a
+ * plain function.
+ */
+const isWorkletBuilder = (
+  preset: EntryOrExitLayoutType,
+): preset is () => LayoutAnimation =>
+  // A predefined builder is a class and carries the `createInstance` static; a
+  // custom worklet builder is a plain nullary function.
+  typeof preset === 'function' &&
+  !('createInstance' in preset) &&
+  preset.length === 0;
+
+const runNativeBuilder = (preset: EntryOrExitLayoutType): LayoutAnimation => {
+  if (!isWorkletBuilder(preset)) {
+    throw new Error('expected the native preset to be a custom worklet builder');
+  }
+  return preset();
+};
+
 describe('motion presets', () => {
   it('ScaleAndFadeIn enters from 70% scale and transparent', () => {
-    const { initialValues, animations } = ScaleAndFadeIn();
+    const { initialValues, animations } = runNativeBuilder(ScaleAndFadeIn);
     expect(initialValues).toEqual({ opacity: 0, transform: [{ scale: 0.7 }] });
     expect(animations).toEqual({ opacity: 1, transform: [{ scale: 1 }] });
   });
 
   it('ScaleAndFadeOut exits to 70% scale and transparent', () => {
-    const { initialValues, animations } = ScaleAndFadeOut();
+    const { initialValues, animations } = runNativeBuilder(ScaleAndFadeOut);
     expect(initialValues).toEqual({ opacity: 1, transform: [{ scale: 1 }] });
     expect(animations).toEqual({ opacity: 0, transform: [{ scale: 0.7 }] });
   });
 
   it('ShrinkAndPop overshoots to 110% before leaving', () => {
-    const { initialValues, animations } = ShrinkAndPop();
+    const { initialValues, animations } = runNativeBuilder(ShrinkAndPop);
     expect(initialValues).toEqual({ opacity: 1, transform: [{ scale: 1 }] });
     // withSequence resolves to its final keyframe (the 1.1 overshoot) in the mock.
     expect(animations.transform).toEqual([{ scale: 1.1 }]);

package/src/__tests__/MotionWebFork.test.ts

@@ -0,0 +1,140 @@
+/**
+ * Regression guard for the `motion` web fork.
+ *
+ * The bug: `motion.ts`'s custom worklet builders are INERT on web. Reanimated's
+ * web layout-animation manager resolves an animation by preset name, a custom
+ * builder has none, and `startWebLayoutAnimation` falls through to
+ * `makeElementVisible` — the element appears at its final frame with one
+ * `[Reanimated] Couldn't load entering/exiting animation` warning apiece.
+ *
+ * The trap: rebuilding all three as `Keyframe`s fixes the exits and makes the
+ * ENTER worse. Reanimated's `entering` path calls `setElementAnimation` with
+ * `shouldSavePosition` TRUE, and any animation name absent from its built-in
+ * `Animations` map — which every custom `Keyframe` is, since they mint a fresh
+ * `REA-ENTERING-n` rule — also gets a `scheduleAnimationCleanup` that pins the
+ * element with `position: absolute` and a frozen box at `duration x 5`. That is
+ * failure mode (C) in `~/Oxy/AGENTS.md`.
+ *
+ * So the invariant is asymmetric, and BOTH halves are load-bearing:
+ *   entering -> a PREDEFINED builder (its `presetName` is in `Animations`, so no
+ *               cleanup is ever scheduled), never a `Keyframe`.
+ *   exiting  -> a `Keyframe` is safe (the cleanup only reaps the throwaway clone)
+ *               and is the only mechanism that can express the full shape.
+ *
+ * The actual motion is verified in a real browser — jest cannot run reanimated's
+ * web layout-animation manager.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { Keyframe } from 'react-native-reanimated';
+
+import {
+  ScaleAndFadeIn,
+  ScaleAndFadeOut,
+  ShrinkAndPop,
+} from '../motion/motion.web';
+
+const SRC = join(__dirname, '..');
+const read = (rel: string) => readFileSync(join(SRC, rel), 'utf8');
+
+/**
+ * Upstream's `ReanimatedKeyframe` type hides the instance state that the web
+ * layout manager actually reads (`createCustomKeyFrameAnimation` takes
+ * `config.definitions` raw, `getDurationFromConfig` takes `config.durationV`), so
+ * the test narrows to it with a runtime-checked predicate rather than a cast.
+ */
+type KeyframeState = {
+  definitions: Record<string, Record<string, unknown>>;
+  durationV: number | undefined;
+};
+
+const isKeyframeState = (value: unknown): value is KeyframeState =>
+  value instanceof Keyframe && 'definitions' in value;
+
+const stateOf = (preset: unknown): KeyframeState => {
+  if (!isKeyframeState(preset)) {
+    throw new Error('expected a Keyframe');
+  }
+  return preset;
+};
+
+describe('motion web fork', () => {
+  it('never hands a Keyframe to `entering`', () => {
+    // The whole reason the enter and the exits use different mechanisms.
+    expect(ScaleAndFadeIn instanceof Keyframe).toBe(false);
+    expect(typeof ScaleAndFadeIn).toBe('object');
+  });
+
+  it('uses a predefined reanimated builder for the enter', () => {
+    const web = read('motion/motion.web.ts');
+    expect(web).toMatch(/export const ScaleAndFadeIn[^=]*=\s*FadeIn;/);
+    expect(web).toMatch(/import \{[\s\S]*\bFadeIn\b[\s\S]*\} from 'react-native-reanimated'/);
+  });
+
+  it('uses a Keyframe for both exits', () => {
+    expect(ScaleAndFadeOut instanceof Keyframe).toBe(true);
+    expect(ShrinkAndPop instanceof Keyframe).toBe(true);
+  });
+
+  it('keeps the full scale + opacity shape on ScaleAndFadeOut', () => {
+    expect(stateOf(ScaleAndFadeOut).definitions).toEqual({
+      from: { opacity: 1, transform: [{ scale: 1 }] },
+      to: { opacity: 0, transform: [{ scale: 0.7 }] },
+    });
+  });
+
+  /**
+   * Every stop declares every animated property, so the CSS the web parser emits
+   * does not depend on cross-stop interpolation, and the intermediate values are
+   * the native timeline sampled at those instants (250ms total: scale 1 -> 0.7 by
+   * 75ms, -> 1.1 by 225ms; opacity held to 125ms, then to 0 by 250ms).
+   */
+  it('samples the native ShrinkAndPop timeline at every stop', () => {
+    const stops = stateOf(ShrinkAndPop).definitions;
+    expect(Object.keys(stops)).toEqual(['0', '30', '50', '90', '100']);
+    for (const [percent, style] of Object.entries(stops)) {
+      expect({ percent, keys: Object.keys(style).sort() }).toEqual({
+        percent,
+        keys: ['opacity', 'transform'],
+      });
+    }
+    expect(stops['0']).toEqual({ opacity: 1, transform: [{ scale: 1 }] });
+    expect(stops['30']).toEqual({ opacity: 1, transform: [{ scale: 0.7 }] });
+    expect(stops['90']).toEqual({ opacity: 0.2, transform: [{ scale: 1.1 }] });
+    expect(stops['100']).toEqual({ opacity: 0, transform: [{ scale: 1.1 }] });
+  });
+
+  it('matches the native durations', () => {
+    // `withTiming`'s default for the pair the native file animates, and
+    // 75 + 150 for the pop's two sequenced scale legs.
+    expect(stateOf(ScaleAndFadeOut).durationV).toBe(300);
+    expect(stateOf(ShrinkAndPop).durationV).toBe(250);
+  });
+
+  it('leaves the native file on its custom worklet builders', () => {
+    const native = read('motion/motion.ts');
+    expect(native).toMatch(/'worklet';/);
+    expect(native).not.toMatch(/\bKeyframe\b/);
+    expect(native).not.toMatch(/\bFadeIn\b/);
+  });
+
+  it('is wired as a web-forked subpath', () => {
+    const script = readFileSync(
+      join(SRC, '..', 'scripts', 'generate-platform-exports.mjs'),
+      'utf8',
+    );
+    // Between the WEB_FORKED_SUBPATHS opener and its closing bracket.
+    const forked = script.slice(
+      script.indexOf('const WEB_FORKED_SUBPATHS'),
+      script.indexOf(']);', script.indexOf('const WEB_FORKED_SUBPATHS')),
+    );
+    expect(forked).toContain("'./motion'");
+
+    const pkg: { exports: Record<string, { browser?: { import?: string } }> } =
+      JSON.parse(readFileSync(join(SRC, '..', 'package.json'), 'utf8'));
+    expect(pkg.exports['./motion']?.browser?.import).toBe(
+      './lib/module/motion/index.web.js',
+    );
+  });
+});

package/src/__tests__/TabBar.test.tsx

@@ -46,6 +46,17 @@ const ITEMS: TabBarItem[] = [
   { name: 'you', label: 'You', icon: <BareIcon id="you-icon" /> },
 ];
 
+/**
+ * An item whose selected state is a different SHAPE, not a different tint —
+ * the icon-set convention (outline vs filled) that `activeIcon` exists for.
+ */
+const SHAPE_ITEM: TabBarItem = {
+  name: 'home',
+  label: 'Home',
+  icon: <BareIcon id="outline-icon" />,
+  activeIcon: <BareIcon id="filled-icon" />,
+};
+
 /** Captures the live `ThemeColors` so assertions compare against real tokens. */
 function ThemeProbe({ onColors }: { onColors: (colors: ThemeColors) => void }) {
   onColors(useTheme().colors);
@@ -259,6 +270,75 @@ describe('TabBar', () => {
     expect(flattenStyle(labelFor(UNSAFE_root, 'Home').props.style).color).toBe(theme.inactiveTint);
   });
 
+  describe('activeIcon', () => {
+    function ShapeBar() {
+      return (
+        <TabBar activeIndex={0}>
+          <TabBarButton item={SHAPE_ITEM} index={0} />
+        </TabBar>
+      );
+    }
+
+    it('renders the item icon underneath and activeIcon on the crossfade layer', () => {
+      // A tint crossfade cannot express an outline-to-filled swap: both layers
+      // would draw the same path in two colors. The layers must render two
+      // different NODES.
+      const { getAllByTestId } = renderWithTheme(<ShapeBar />);
+      expect(getAllByTestId('outline-icon')).toHaveLength(1);
+      expect(getAllByTestId('filled-icon')).toHaveLength(1);
+    });
+
+    it('puts activeIcon on the ACTIVE layer, not the inactive one', () => {
+      // The tint each node was cloned with is what identifies its layer — the
+      // crossfading layer is the one painted with `activeTint`.
+      const theme = readTheme();
+      const { getAllByTestId } = renderWithTheme(<ShapeBar />);
+      expect(getAllByTestId('filled-icon')[0]?.props.fill).toBe(theme.activeTint);
+      expect(getAllByTestId('outline-icon')[0]?.props.fill).toBe(theme.inactiveTint);
+    });
+
+    it('falls back to icon on both layers when the item has no activeIcon', () => {
+      // Full backward compatibility: an item that only carries `icon` behaves
+      // exactly as it did before `activeIcon` existed.
+      const theme = readTheme();
+      const { getAllByTestId } = renderWithTheme(<Bar activeIndex={0} />);
+      const fills = getAllByTestId('home-icon').map((node) => node.props.fill);
+      expect(fills).toHaveLength(2);
+      expect(fills).toEqual(expect.arrayContaining([theme.inactiveTint, theme.activeTint]));
+    });
+
+    it('is honoured by the native glyph too, per crossfade layer', () => {
+      const theme = readTheme();
+      const active = renderWithTheme(
+        <NativeTabBarGlyph item={SHAPE_ITEM} tint={theme.activeTint} size={21} active />,
+      );
+      expect(active.queryByTestId('filled-icon')).toBeTruthy();
+      expect(active.queryByTestId('outline-icon')).toBeNull();
+
+      const inactive = renderWithTheme(
+        <NativeTabBarGlyph item={SHAPE_ITEM} tint={theme.inactiveTint} size={21} active={false} />,
+      );
+      expect(inactive.queryByTestId('outline-icon')).toBeTruthy();
+      expect(inactive.queryByTestId('filled-icon')).toBeNull();
+    });
+
+    it('keeps the SF Symbol path on iOS, which is tinted natively', () => {
+      // A symbol IS tinted per layer by the system, so the tint crossfade is
+      // still the right expression there and `activeIcon` stays unused.
+      const theme = readTheme();
+      const { UNSAFE_root, queryByTestId } = renderWithTheme(
+        <NativeTabBarGlyph
+          item={{ ...SHAPE_ITEM, sfSymbol: 'house.fill' }}
+          tint={theme.activeTint}
+          size={21}
+          active
+        />,
+      );
+      expect(hosts(UNSAFE_root, 'SymbolView')).toHaveLength(1);
+      expect(queryByTestId('filled-icon')).toBeNull();
+    });
+  });
+
   describe('theming', () => {
     it('resolves its defaults from Bloom tokens, never a hardcoded palette', () => {
       const theme = readTheme();
@@ -322,7 +402,7 @@ describe('TabBar', () => {
       const theme = readTheme();
       const item: TabBarItem = { ...(ITEMS[0] as TabBarItem), sfSymbol: 'house.fill' };
       const { UNSAFE_root } = renderWithTheme(
-        <NativeTabBarGlyph item={item} tint={theme.activeTint} size={21} />,
+        <NativeTabBarGlyph item={item} tint={theme.activeTint} size={21} active />,
       );
       const symbol = hosts(UNSAFE_root, 'SymbolView')[0];
       expect(symbol?.props.name).toBe('house.fill');
@@ -333,7 +413,7 @@ describe('TabBar', () => {
     it('falls back to the item icon when no SF Symbol is given', () => {
       const theme = readTheme();
       const { queryByTestId, UNSAFE_root } = renderWithTheme(
-        <NativeTabBarGlyph item={ITEMS[0] as TabBarItem} tint={theme.activeTint} size={21} />,
+        <NativeTabBarGlyph item={ITEMS[0] as TabBarItem} tint={theme.activeTint} size={21} active />,
       );
       expect(hosts(UNSAFE_root, 'SymbolView')).toHaveLength(0);
       expect(queryByTestId('home-icon')).toBeTruthy();

package/src/__tests__/TabBarAnimatedShorthand.test.ts

@@ -0,0 +1,135 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+/**
+ * No reanimated mapper may return a React Native style SHORTHAND that
+ * react-native-web does not expand.
+ *
+ * Reanimated's web path hands a mapper's result to RNW's `createReactDOMStyle`
+ * and then assigns each surviving key straight onto the DOM node's `style`. That
+ * function expands a fixed set of shorthands (`marginInline`, `paddingInline`,
+ * `borderWidth`, `borderRadius`, `insetInline`, …) but NOT React Native's own
+ * `marginHorizontal` / `marginVertical` / `paddingHorizontal` / `paddingVertical`
+ * — verified absent from the entire file in RNW 0.21.2. An unexpanded shorthand
+ * becomes `element.style.marginHorizontal = '34px'`, which is not a CSS property,
+ * so the browser drops it WITHOUT any error.
+ *
+ * This shipped once: `barStyle` animated `marginHorizontal` (copied verbatim from
+ * upstream expo-glass-tabs, which only ever ran on native). On web the bar kept
+ * its full width while `highlightStyle` still subtracted `MINIMIZED_INSET` from
+ * `barWidth`, so the sliding highlight sat ~13.6px narrower than the tab beneath
+ * it at five tabs — visible only once the bar minimized.
+ *
+ * STATIC styles are fine and are deliberately not scanned: `StyleSheet.create`
+ * takes RNW's own StyleSheet path, which does handle the shorthand. The trap is
+ * specific to values produced inside a mapper.
+ *
+ * Neither tsc nor jest can see this: the shorthand is a valid RN style key, so it
+ * type-checks, and the reanimated mock never touches the DOM. Source analysis is
+ * the only automatable guard.
+ */
+
+const SRC = join(__dirname, '..');
+const ROOTS = ['tab-bar', 'progressive-blur'] as const;
+const MAPPERS = ['useAnimatedStyle', 'useDerivedValue', 'useAnimatedProps'] as const;
+
+/** RN shorthands with no entry in RNW's `STYLE_SHORT_FORM_EXPANSIONS`. */
+const UNEXPANDED_SHORTHANDS = [
+  'marginHorizontal',
+  'marginVertical',
+  'paddingHorizontal',
+  'paddingVertical',
+] as const;
+
+function sourceFiles(root: string): string[] {
+  const out: string[] = [];
+  const walk = (dir: string) => {
+    for (const entry of readdirSync(dir)) {
+      const full = join(dir, entry);
+      if (statSync(full).isDirectory()) {
+        walk(full);
+        continue;
+      }
+      if (!/\.tsx?$/.test(entry)) continue;
+      if (/\.(test|spec|stories)\.tsx?$/.test(entry)) continue;
+      out.push(full);
+    }
+  };
+  walk(join(SRC, root));
+  return out;
+}
+
+/**
+ * The body of every mapper call in `source`, matched by brace depth from the
+ * mapper's opening paren so nested objects and callbacks are included whole.
+ */
+function mapperBodies(source: string): string[] {
+  const bodies: string[] = [];
+  for (const mapper of MAPPERS) {
+    let from = 0;
+    for (;;) {
+      const start = source.indexOf(`${mapper}(`, from);
+      if (start === -1) break;
+      let depth = 0;
+      let index = source.indexOf('(', start);
+      const open = index;
+      for (; index < source.length; index += 1) {
+        const char = source[index];
+        if (char === '(') depth += 1;
+        else if (char === ')') {
+          depth -= 1;
+          if (depth === 0) break;
+        }
+      }
+      bodies.push(source.slice(open, index));
+      from = index === -1 ? start + mapper.length : index;
+    }
+  }
+  return bodies;
+}
+
+describe('tab-bar animated styles', () => {
+  const files = ROOTS.flatMap(sourceFiles);
+
+  // Self-check: a broken walk must not pass vacuously.
+  it('walks the real sources', () => {
+    expect(files.length).toBeGreaterThanOrEqual(10);
+    const withMappers = files.filter((file) => mapperBodies(readFileSync(file, 'utf8')).length > 0);
+    expect(withMappers.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it('extracts a mapper body that really contains its returned keys', () => {
+    const base = files.find((file) => file.endsWith('TabBarBase.tsx'));
+    expect(base).toBeDefined();
+    const bodies = mapperBodies(readFileSync(base as string, 'utf8'));
+    expect(bodies.length).toBeGreaterThanOrEqual(6);
+    // `highlightStyle` is the mapper that computes the capsule geometry.
+    expect(bodies.some((body) => body.includes('borderRadius'))).toBe(true);
+  });
+
+  it.each(UNEXPANDED_SHORTHANDS)('never returns %s from a mapper', (shorthand) => {
+    const offenders: string[] = [];
+    for (const file of files) {
+      for (const body of mapperBodies(readFileSync(file, 'utf8'))) {
+        // Strip comments so the explanatory notes naming the shorthand do not
+        // trip the guard that exists because of them.
+        const code = body.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/[^\n]*/g, '');
+        if (new RegExp(`\\b${shorthand}\\s*:`).test(code)) {
+          offenders.push(relative(SRC, file));
+        }
+      }
+    }
+    expect(offenders).toEqual([]);
+  });
+
+  it('animates the minimized inset as both long-form margins', () => {
+    const base = readFileSync(
+      files.find((file) => file.endsWith('TabBarBase.tsx')) as string,
+      'utf8',
+    );
+    const barStyle = mapperBodies(base).find((body) => body.includes('MINIMIZED_INSET'));
+    expect(barStyle).toBeDefined();
+    expect(barStyle).toMatch(/marginLeft:/);
+    expect(barStyle).toMatch(/marginRight:/);
+  });
+});

package/src/__tests__/TabBarFootprint.test.tsx

@@ -0,0 +1,172 @@
+import React from 'react';
+import type { ReactTestInstance } from 'react-test-renderer';
+import { render } from '@testing-library/react-native';
+
+import { BloomThemeProvider } from '../theme/BloomThemeProvider';
+import { TabBar, TabBarButton, useTabBarFootprint } from '../tab-bar';
+import type { TabBarItem } from '../tab-bar/types';
+
+/**
+ * `useTabBarFootprint()` — the space the floating bar physically occupies above
+ * the bottom of the window, and nothing more.
+ *
+ * The bar is absolutely positioned, so nothing accounts for it automatically,
+ * and the geometry it is built from (expanded height, bottom gap) is private.
+ * Without the hook a consumer hardcodes both — which drifts silently the first
+ * time the bar changes by a pixel — and, worse, tends to add `insets.bottom` on
+ * top, because that is what laying anything out against the bottom edge
+ * normally requires. The bar already folds the inset into its own gap, so that
+ * double-counts the home indicator.
+ *
+ * It is the RAW footprint: no clearance is folded in, because clearance differs
+ * per call site (a list wants a gap above the pill, a FAB anchored by `bottom`
+ * supplies its own) and only the consumer knows which. That is asserted here
+ * rather than merely documented — a margin quietly added to the hook would move
+ * every consumer's FAB.
+ *
+ * The suite asserts four separate things: the absolute pixel values (so a change
+ * to the constants must be deliberate), that the number is the bar and only the
+ * bar, the inset relationship (so the double-count can never creep back in), and
+ * equality with the bar's own rendered geometry (so it cannot drift from where
+ * the bar actually sits).
+ */
+
+// Mutated per test; must be `mock`-prefixed for the hoisted factory.
+const mockInsets = { top: 0, right: 0, bottom: 0, left: 0 };
+
+jest.mock('react-native-safe-area-context', () => ({
+  ...jest.requireActual('react-native-safe-area-context'),
+  useSafeAreaInsets: () => mockInsets,
+}));
+
+const ITEMS: TabBarItem[] = [
+  { name: 'home', label: 'Home', icon: null },
+  { name: 'search', label: 'Search', icon: null },
+];
+
+/** A device with a home indicator (iPhone-class bottom inset). */
+const HOME_INDICATOR_INSET = 34;
+
+function FootprintProbe({ onValue }: { onValue: (space: number) => void }) {
+  onValue(useTabBarFootprint());
+  return null;
+}
+
+function withTheme(ui: React.ReactElement) {
+  return (
+    <BloomThemeProvider mode="light" colorPreset="teal">
+      {ui}
+    </BloomThemeProvider>
+  );
+}
+
+/** The footprint the hook reports on a device whose bottom inset is `inset`. */
+function footprintFor(inset: number): number {
+  mockInsets.bottom = inset;
+  let space: number | undefined;
+  render(withTheme(<FootprintProbe onValue={(value) => (space = value)} />));
+  if (space === undefined) throw new Error('FootprintProbe never ran');
+  return space;
+}
+
+function flattenStyle(style: unknown): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  const visit = (value: unknown): void => {
+    if (Array.isArray(value)) value.forEach(visit);
+    else if (value && typeof value === 'object') Object.assign(out, value);
+  };
+  visit(style);
+  return out;
+}
+
+/**
+ * The flattened style of every styled node in the tree.
+ *
+ * Restricted to HOST nodes: the RN mock renders each component as a composite
+ * wrapping a host element of the same name, and both carry the same `style`, so
+ * counting all of them would double every match.
+ */
+function styledNodes(root: ReactTestInstance): Record<string, unknown>[] {
+  return root
+    .findAll((node) => typeof node.type === 'string' && node.props?.style !== undefined)
+    .map((node) => flattenStyle(node.props.style));
+}
+
+describe('useTabBarFootprint', () => {
+  beforeEach(() => {
+    mockInsets.bottom = 0;
+  });
+
+  it('measures the bar plus its gap where there is no bottom inset', () => {
+    // 58pt bar + the 12pt floor the gap never goes below.
+    expect(footprintFor(0)).toBe(70);
+  });
+
+  it('measures more on a device with a home indicator', () => {
+    expect(footprintFor(HOME_INDICATOR_INSET)).toBe(76);
+  });
+
+  it('adds no clearance of its own — the number is the bar and only the bar', () => {
+    // Clearance belongs to the call site: a list wants a gap above the pill, a
+    // FAB anchored by `bottom` supplies its own. A margin folded in here would
+    // lift every consumer's FAB off its intended position, and would make
+    // "footprint" mean two different things in one file.
+    expect(footprintFor(0)).toBe(58 + 12);
+    expect(footprintFor(HOME_INDICATOR_INSET)).toBe(58 + (HOME_INDICATOR_INSET - 16));
+  });
+
+  it('already includes the inset — adding insets.bottom would double-count it', () => {
+    // The bar absorbs 16pt of the inset into its own gap, so the footprint grows
+    // by the REMAINDER, never by the whole inset. A consumer writing
+    // `footprint + insets.bottom` would account 110pt for a 76pt bar.
+    const grown = footprintFor(HOME_INDICATOR_INSET) - footprintFor(0);
+    expect(grown).toBe(6);
+    expect(grown).toBeLessThan(HOME_INDICATOR_INSET);
+  });
+
+  it('does not shrink below the floor for a small inset', () => {
+    // An inset under what the gap absorbs must not pull the bar down toward the
+    // window edge — the gap is clamped, and the footprint with it.
+    expect(footprintFor(8)).toBe(footprintFor(0));
+  });
+
+  it('equals the space the rendered bar actually occupies', () => {
+    // The invariant that makes the hook worth exporting: its number is the bar's
+    // own geometry (the gap it holds off the window edge plus its expanded
+    // height), not a second copy that can drift.
+    mockInsets.bottom = HOME_INDICATOR_INSET;
+    let footprint: number | undefined;
+    const { UNSAFE_root } = render(
+      withTheme(
+        <>
+          <FootprintProbe onValue={(value) => (footprint = value)} />
+          <TabBar activeIndex={0}>
+            {ITEMS.map((item, index) => (
+              <TabBarButton key={item.name} item={item} index={index} />
+            ))}
+          </TabBar>
+        </>,
+      ),
+    );
+
+    const styles = styledNodes(UNSAFE_root);
+    // The wrapper holding the pill off the bottom edge — the only node with a
+    // bottom margin.
+    const gaps = styles.filter((style) => typeof style.marginBottom === 'number');
+    expect(gaps).toHaveLength(1);
+    // The pill itself: the animated capsule sizes BOTH its height and its
+    // horizontal inset, which nothing else in the bar does. The inset is written
+    // as the two long-form margins — `marginHorizontal` would be dropped
+    // silently on web, since RNW's `createReactDOMStyle` does not expand it (see
+    // `TabBarAnimatedShorthand.test.ts`).
+    const pills = styles.filter(
+      (style) =>
+        typeof style.height === 'number' &&
+        typeof style.marginLeft === 'number' &&
+        typeof style.marginRight === 'number',
+    );
+    expect(pills).toHaveLength(1);
+
+    expect(footprint).toBe(Number(gaps[0]?.marginBottom) + Number(pills[0]?.height));
+  });
+});