@oxyhq/bloom 0.51.0 → 0.52.0

package/src/__tests__/TabBarWebFork.test.ts

@@ -49,7 +49,9 @@ const NEUTRAL_AND_WEB_FILES = [
   'tab-bar/shared.ts',
   'tab-bar/TabBarBase.tsx',
   'tab-bar/minimize-context.tsx',
+  'tab-bar/use-reserved-space.ts',
   'tab-bar/surface.tsx',
+  'tab-bar/surface-solid.tsx',
   'tab-bar/surface.web.tsx',
   'tab-bar/glyph.tsx',
   'progressive-blur/index.web.tsx',
@@ -128,6 +130,17 @@ describe('tab-bar platform split', () => {
     expect(moduleSpecifiers(read('tab-bar/glyph.native.tsx'))).toContain('expo-symbols');
   });
 
+  it('the native surface takes its fallback from surface-solid, never ./surface', () => {
+    // Metro resolves a bare `./surface` to `surface.native.tsx` from ANY caller,
+    // so importing the neutral sibling by that name would be a self-import — which
+    // is the entire reason `surface-solid.tsx` exists as a separate name.
+    const specifiers = moduleSpecifiers(read('tab-bar/surface.native.tsx'));
+    expect(specifiers).toContain('./surface-solid');
+    expect(specifiers).not.toContain('./surface');
+    // And the neutral variant must be that same component, not a second copy.
+    expect(moduleSpecifiers(read('tab-bar/surface.tsx'))).toContain('./surface-solid');
+  });
+
   it('the router packages live only under tab-bar/expo-router', () => {
     const router = moduleSpecifiers(read('tab-bar/expo-router/RouterTabBar.tsx'));
     expect(router.some((s) => isFrom(s, 'expo-router'))).toBe(true);
@@ -160,6 +173,8 @@ describe('tab-bar platform split', () => {
 describe('tab-bar published surface', () => {
   const pkg = JSON.parse(readFileSync(join(REPO_ROOT, 'package.json'), 'utf8')) as {
     exports: Record<string, { browser?: { import?: string; require?: string } }>;
+    peerDependencies: Record<string, string>;
+    peerDependenciesMeta: Record<string, { optional?: boolean }>;
   };
 
   it('exports ./tab-bar with a browser condition → index.web.js', () => {
@@ -184,6 +199,38 @@ describe('tab-bar published surface', () => {
     expect(entry?.browser).toBeUndefined();
   });
 
+  it('declares the two Apple-only native peers REQUIRED, keeping their ranges', () => {
+    // `expo-glass-effect` and `expo-symbols` are imported STATICALLY, by
+    // `tab-bar/surface.native` and `tab-bar/glyph.native`. That is what settles
+    // this: optional means "you may omit this", but omitting it does not degrade
+    // — the native bundle fails to RESOLVE the specifier and the build dies. An
+    // optional peer plus a static import is an incoherent pair, and the only
+    // thing marking them optional would achieve is silencing the one warning
+    // that tells a consumer their build is about to break. Declared the same way
+    // `expo-blur` already is, for the same reason.
+    //
+    // The RANGE carries the second half: both files import symbols that arrived
+    // after 1.0 — `isGlassEffectAPIAvailable` first shipped in
+    // expo-glass-effect 0.1.9 — so an older installed copy is a real
+    // incompatibility, not merely an absent one.
+    for (const peer of ['expo-glass-effect', 'expo-symbols']) {
+      expect(pkg.peerDependencies[peer]).toMatch(/^>=\d/);
+      expect(pkg.peerDependenciesMeta[peer]).toBeUndefined();
+    }
+  });
+
+  it('keeps the cross-platform native peers REQUIRED', () => {
+    // `expo-blur` and `expo-image` are apple+android native modules imported from
+    // platform-NEUTRAL files (`progressive-blur/index.tsx`,
+    // `frosted-icon-button/FrostedIconButton.tsx`, `zoomable-image-gallery/`), so
+    // every native platform genuinely needs them. Marking them optional would
+    // silence the one warning that tells a consumer their build is about to fail.
+    for (const peer of ['expo-blur', 'expo-image']) {
+      expect(pkg.peerDependencies[peer]).toBeDefined();
+      expect(pkg.peerDependenciesMeta[peer]).toBeUndefined();
+    }
+  });
+
   it('the generator lists exactly the right subpaths as web-forked', () => {
     const gen = readFileSync(join(REPO_ROOT, 'scripts/generate-platform-exports.mjs'), 'utf8');
     const block = /const WEB_FORKED_SUBPATHS = new Set\(\[([\s\S]*?)\]\);/.exec(gen)?.[1];

package/src/__tests__/icon-references.test.ts

@@ -0,0 +1,243 @@
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { extname, join, relative } from 'node:path';
+
+/**
+ * Every `Icons.*` reference in this repo must name an identifier `src/icons`
+ * actually exports.
+ *
+ * Icon exports carry their full style and corner suffix
+ * (`Home_Stroke2_Corner0_Rounded`), there are 250-odd of them, and a shortened
+ * name is not a compile error anywhere it usually appears: in a DOC COMMENT or an
+ * `.mdx` example, `tsc` never sees it. A reader copies it, gets `undefined`, and
+ * React reports "Element type is invalid … but got: undefined" against the
+ * consumer's own file — which is exactly how a phantom release blocker was filed
+ * against the tab bar's native surface.
+ *
+ * Two shapes are checked, because the real incident needed both:
+ *
+ *   1. `Icons.Home` — a member that does not exist.
+ *   2. `import { Icons } from '@oxyhq/bloom/icons'` — the NAMESPACE imported as a
+ *      named export. `Icons` is assembled by the ROOT barrel
+ *      (`export * as Icons from './icons'` in `src/index.ts`); the `./icons`
+ *      subpath exports the components flat, so that import is `undefined` too.
+ *      `import * as Icons from '@oxyhq/bloom/icons'` and
+ *      `import { Icons } from '@oxyhq/bloom'` are both correct and must stay
+ *      unflagged.
+ *
+ * Comments are deliberately NOT stripped here — the inverse of
+ * `TabBarWebFork.test.ts`, which blanks them so a doc comment naming a package is
+ * not mistaken for an import of it. Here the doc comments ARE the surface under
+ * test: four of the five instances this test was written for lived in JSDoc.
+ *
+ * Identifiers are matched against the UNION of everything exported anywhere under
+ * `src/icons`, because references legitimately target the barrel
+ * (`../icons`), a single icon file (`../icons/Check`) and `../icons/common` alike.
+ */
+
+const SRC = join(__dirname, '..');
+const REPO_ROOT = join(SRC, '..');
+const ICONS_DIR = join(SRC, 'icons');
+
+const SCANNED_EXTENSIONS = ['.ts', '.tsx', '.mdx', '.md'];
+
+/** True for a specifier that resolves to an icons module, package or relative. */
+const ICONS_MODULE = /(?:^|\/)icons(?:\/|$)/;
+
+function walk(dir: string, out: string[] = []): string[] {
+  for (const entry of readdirSync(dir)) {
+    // Agent worktrees under `.claude/` are full copies of this repo — scanning
+    // them would double every file and report another checkout's problems.
+    if (entry === 'node_modules' || entry === 'lib' || entry.startsWith('.')) continue;
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) walk(full, out);
+    else if (SCANNED_EXTENSIONS.includes(extname(full))) out.push(full);
+  }
+  return out;
+}
+
+/** Every identifier a module exports, across every export shape in use here. */
+function exportedNames(source: string): string[] {
+  const found = new Set<string>();
+
+  // `export const X` / `export function X` / `export class X` /
+  // `export type X =` / `export interface X`
+  for (const m of source.matchAll(
+    /export\s+(?:declare\s+)?(?:const|let|var|function|class|type|interface)\s+([A-Za-z0-9_$]+)/g,
+  )) {
+    if (m[1]) found.add(m[1]);
+  }
+
+  // `export { A, B as C }` and `export type { A, B } from './x'` — the form that
+  // carries `IconStyle` / `Props` out of `icons/common.tsx` through the barrel.
+  // Missing it is what made an earlier pass of this check report two phantom
+  // failures, and a check with known noise is a check somebody disables.
+  for (const m of source.matchAll(/export\s+(?:type\s+)?\{([^}]*)\}/g)) {
+    for (const name of namedBindings(m[1] ?? '', 'export')) found.add(name);
+  }
+
+  return [...found];
+}
+
+/**
+ * The bindings a brace list introduces.
+ *
+ * `as` means opposite things in the two directions: `export { A as B }` publishes
+ * `B`, while `import { A as B }` reads `A`. Getting that backwards would make the
+ * check blind to exactly the imports it exists to catch.
+ */
+function namedBindings(list: string, direction: 'import' | 'export'): string[] {
+  const names: string[] = [];
+  for (const raw of list.split(',')) {
+    const part = raw.trim().replace(/^type\s+/, '');
+    if (!part) continue;
+    const sides = part.split(/\s+as\s+/).map((s) => s.trim());
+    const name = direction === 'export' ? sides[sides.length - 1] : sides[0];
+    if (name && /^[A-Za-z0-9_$]+$/.test(name) && name !== 'default') names.push(name);
+  }
+  return names;
+}
+
+/** The union of every identifier exported anywhere under `src/icons`. */
+function iconExportUnion(): Set<string> {
+  const union = new Set<string>();
+  for (const file of walk(ICONS_DIR)) {
+    for (const name of exportedNames(readFileSync(file, 'utf8'))) union.add(name);
+  }
+  return union;
+}
+
+interface Unresolved {
+  line: number;
+  ref: string;
+}
+
+/** Every icon reference in `source` that `exported` cannot satisfy. */
+function unresolvedIconRefs(source: string, exported: Set<string>): Unresolved[] {
+  const problems: Unresolved[] = [];
+
+  source.split('\n').forEach((text, index) => {
+    const line = index + 1;
+
+    for (const m of text.matchAll(/\bIcons\.([A-Za-z0-9_$]+)/g)) {
+      if (m[1] && !exported.has(m[1])) problems.push({ line, ref: `Icons.${m[1]}` });
+    }
+
+    // Braces only: `import * as Icons from …` is the correct namespace form, and a
+    // bare `import '…/icons'` binds nothing.
+    const imported = /\bimport\s+(?:type\s+)?\{([^}]*)\}\s*from\s*['"]([^'"]+)['"]/.exec(text);
+    const specifier = imported?.[2];
+    if (imported && specifier && ICONS_MODULE.test(specifier)) {
+      for (const name of namedBindings(imported[1] ?? '', 'import')) {
+        if (!exported.has(name)) problems.push({ line, ref: `{ ${name} } from '${specifier}'` });
+      }
+    }
+  });
+
+  return problems;
+}
+
+const ICON_EXPORTS = iconExportUnion();
+
+const SCANNED = [
+  ...walk(SRC),
+  ...walk(join(REPO_ROOT, 'docs')),
+  join(REPO_ROOT, 'README.md'),
+  join(REPO_ROOT, 'AGENTS.md'),
+];
+
+/**
+ * This file is the one exclusion, and it has to be: it SPELLS the mistakes it
+ * forbids — in its probes, in the doc comment above, and in the `Icons.${…}`
+ * template that formats a finding. Nothing outside a test copies an example out of
+ * a test. The list is pinned to exactly one path in the first assertion below, so
+ * it can neither grow quietly nor become a silent no-op through a typo.
+ */
+const EXCLUDED = [join(__dirname, 'icon-references.test.ts')];
+const CHECKED = SCANNED.filter((file) => !EXCLUDED.includes(file));
+
+describe('icon reference integrity', () => {
+  it('reads a plausible repo — neither list may be empty or truncated', () => {
+    // Without these floors a broken traversal or a broken extractor makes every
+    // assertion below pass by finding nothing at all.
+    expect(ICON_EXPORTS.size).toBeGreaterThan(200);
+    expect(CHECKED.length).toBeGreaterThan(300);
+    expect(CHECKED).toContain(join(SRC, 'tab-bar', 'types.ts'));
+    expect(CHECKED).toContain(join(REPO_ROOT, 'docs', 'tab-bar.mdx'));
+
+    // Exactly one file is exempt, and it really is in the scan — a misspelled path
+    // here would make the exemption a no-op and the suite fail on itself instead.
+    expect(EXCLUDED).toHaveLength(1);
+    expect(SCANNED).toContain(EXCLUDED[0]);
+    expect(CHECKED).not.toContain(EXCLUDED[0]);
+  });
+
+  it('collects every export shape src/icons uses, types included', () => {
+    // The suffixed component itself, the helpers, and the two TYPE exports that an
+    // earlier version of this check mistook for phantom references.
+    for (const name of [
+      'Home_Stroke2_Corner0_Rounded',
+      'PlusLarge_Stroke2_Corner0_Rounded',
+      'sizes',
+      'useCommonSVGProps',
+      'createSinglePathSVG',
+      'IconStyle',
+      'Props',
+    ]) {
+      expect([...ICON_EXPORTS]).toContain(name);
+    }
+    // And nothing shortened is in there, which is the premise of the whole test.
+    expect(ICON_EXPORTS.has('Home')).toBe(false);
+    expect(ICON_EXPORTS.has('Icons')).toBe(false);
+  });
+
+  it('resolves the export/import directions of `as` correctly', () => {
+    // `export { A as B }` publishes B; `import { A as B }` reads A.
+    expect(exportedNames("export { TimesLarge_Stroke2_Corner0_Rounded as X } from './Times';")).toEqual(
+      ['X'],
+    );
+    expect(namedBindings('Check_Stroke2_Corner0_Rounded as CheckIcon', 'import')).toEqual([
+      'Check_Stroke2_Corner0_Rounded',
+    ]);
+  });
+
+  it('flags the two mistakes that have actually been made', () => {
+    const probe = [
+      "import { Icons } from '@oxyhq/bloom/icons';",
+      'const a = <Icons.Home />;',
+      "import { Bell, Home } from '@oxyhq/bloom/icons';",
+      " * A doc comment saying `<Icons.Lock size=\"sm\" />`, which is where four of these lived.",
+    ].join('\n');
+
+    expect(unresolvedIconRefs(probe, ICON_EXPORTS)).toEqual([
+      { line: 1, ref: "{ Icons } from '@oxyhq/bloom/icons'" },
+      { line: 2, ref: 'Icons.Home' },
+      { line: 3, ref: "{ Bell } from '@oxyhq/bloom/icons'" },
+      { line: 3, ref: "{ Home } from '@oxyhq/bloom/icons'" },
+      { line: 4, ref: 'Icons.Lock' },
+    ]);
+  });
+
+  it('leaves every correct form alone', () => {
+    const probe = [
+      "import * as Icons from '@oxyhq/bloom/icons';",
+      "import { Icons } from '@oxyhq/bloom';",
+      'const a = <Icons.Home_Stroke2_Corner0_Rounded />;',
+      "import { Check_Stroke2_Corner0_Rounded as CheckIcon } from '../icons/Check';",
+      "import { type IconStyle, type Props as SVGIconProps } from '../icons/common';",
+      '| `Icons` | `export * as Icons` | keep namespace | `Icons.*` |',
+      "import { useState } from 'react';",
+    ].join('\n');
+
+    expect(unresolvedIconRefs(probe, ICON_EXPORTS)).toEqual([]);
+  });
+
+  it('every icon reference in src, docs, README and AGENTS resolves', () => {
+    const problems = CHECKED.flatMap((file) =>
+      unresolvedIconRefs(readFileSync(file, 'utf8'), ICON_EXPORTS).map(
+        ({ line, ref }) => `${relative(REPO_ROOT, file)}:${line}  ${ref}`,
+      ),
+    );
+
+    expect(problems).toEqual([]);
+  });
+});

package/src/benefit-list/types.ts

@@ -4,7 +4,8 @@ import type { StyleProp, TextStyle, ViewStyle } from 'react-native';
 export interface BenefitRowProps {
   /**
    * Leading icon — rendered inside a rounded `fill-secondary` square. Pass a
-   * Bloom icon element (e.g. `<Icons.Lock size="sm" />`) or any node.
+   * Bloom icon element (e.g. `<Icons.Lock_Stroke2_Corner0_Rounded size="sm" />`,
+   * suffix included — there is no shortened alias) or any node.
    */
   icon: ReactNode;
   /**

package/src/fab/types.ts

@@ -63,8 +63,10 @@ export interface FabProps {
 
   /**
    * The icon to render inside the FAB. Typically a Bloom icon element
-   * (`<Icons.Plus .../>`). For an icon-only FAB this is the whole content; for
-   * the extended variant it sits to the left of the `label`.
+   * (`<Icons.PlusLarge_Stroke2_Corner0_Rounded />` — icon exports carry their full
+   * style and corner suffix, and there is no shortened alias). For an icon-only
+   * FAB this is the whole content; for the extended variant it sits to the left of
+   * the `label`.
    *
    * `children` is accepted as an alias/override of `icon` for ergonomics — if
    * both are given, `icon` wins and `children` is ignored.

package/src/frosted-icon-button/shared.ts

@@ -106,9 +106,19 @@ type FillableElement = ReactElement<{ fill?: unknown }>;
  * Inject `color` as the icon's `fill` — but only as a FALLBACK: if the caller
  * already set an explicit `fill` on the icon element, it wins and the node is
  * returned untouched. Bloom icons resolve their paint as `fill ?? style.color`,
- * so a bare `<Icons.X />` gets the theme-aware color for free while an
+ * so any bare Bloom icon element gets the theme-aware color for free while an
  * explicitly-colored icon is never overridden. Non-element children (plain
  * text/strings) pass through unchanged.
+ *
+ * KNOWN LIMIT, deliberately not papered over: an icon component that paints from
+ * a `color` PROP rather than from `fill`/`style.color` ignores this entirely, and
+ * does so SILENTLY — nothing throws, the glyph renders, it simply never takes the
+ * tint. `color` is not injected alongside `fill` because the prop is not ours to
+ * claim: components use it for semantic variants (`color="danger"`), so writing an
+ * `rgb(…)` string into it can produce a worse failure than the one it fixes, and
+ * an icon already carrying its own `color` would be clobbered. Consumers with such
+ * a set pre-color the element themselves; the tab bar additionally offers
+ * `TabBarItem.activeIcon`, which carries selection by shape instead of by tint.
  */
 export function applyIconColor(node: ReactNode, color: string): ReactNode {
   if (!isValidElement(node)) return node;

package/src/frosted-icon-button/types.ts

@@ -18,7 +18,8 @@ export interface FrostedIconButtonProps {
 
   /**
    * The icon to render, centered inside the circle. Typically a Bloom icon
-   * element (`<Icons.ArrowLeft… />`). If the icon does not set its own `fill`,
+   * element (`<Icons.ArrowLeft_Stroke2_Corner0_Rounded />` — icon exports carry
+   * their full style and corner suffix). If the icon does not set its own `fill`,
    * the button injects the theme-aware icon color (foreground when frosted,
    * `primaryForeground` when `active`) as a fallback so a bare icon is colored
    * correctly out of the box; an explicit `fill` on the icon always wins.

package/src/tab-bar/TabBarBase.tsx

@@ -49,10 +49,12 @@ import {
   ITEM_GAP,
   ITEM_PAD_V,
   LABEL_FONT_SIZE,
+  LONG_PRESS_MIN_DURATION,
   MINIMIZED_HEIGHT,
   MINIMIZED_INSET,
   ROW_PAD_H,
   SLIDE_SPRING,
+  tabBarBottomGap,
   useTabBarTheme,
   type TabBarGlyphProps,
   type TabBarSurfaceProps,
@@ -93,6 +95,7 @@ function TabBarBody({
   children,
   activeIndex,
   onIndexChange,
+  onIndexLongPress,
   theme: themeOverrides,
   haptics = true,
   style,
@@ -121,6 +124,14 @@ function TabBarBody({
   // scrubbing makes the content jump under the finger.
   const selectIndex = useCallback((index: number) => onIndexChange?.(index), [onIndexChange]);
 
+  // Long press is reported through the same shape, and deliberately does NOT
+  // select: it is a secondary action on the tab under the finger.
+  const longPressIndex = useCallback(
+    (index: number) => onIndexLongPress?.(index),
+    [onIndexLongPress],
+  );
+  const hasLongPress = onIndexLongPress !== undefined;
+
   // CONTROLLED path: the bar owns the highlight when `activeIndex` is provided,
   // so it tracks the prop even when a consumer renders custom children instead
   // of `TabBarButton`s. Syncing an imperative animation to a controlled prop is
@@ -200,11 +211,30 @@ function TabBarBody({
         runOnJS(selectIndex)(index);
       });
 
-    return Gesture.Race(pan, tap);
+    if (!hasLongPress) return Gesture.Race(pan, tap);
+
+    // Long press: the ONLY path to one, because the detector consumes the
+    // bar's touches and a button's inner `Pressable` therefore never sees a
+    // real finger (see `TabBarButtonBody`). Added to the race only when a
+    // handler was supplied — an always-armed long press would cancel the pan
+    // for anyone who rests a finger before scrubbing, and no existing consumer
+    // asked for that. It cannot cost a tap either: the tap gesture gives up at
+    // 400ms, before this one can activate at 500ms, so the two are never
+    // candidates at the same instant. Resolves its index through the same
+    // `indexAtX` worklet as tap and pan, so all three agree on the geometry.
+    const longPress = Gesture.LongPress()
+      .minDuration(LONG_PRESS_MIN_DURATION)
+      .onStart((event) => {
+        runOnJS(longPressIndex)(Math.round(indexAtX(event.x, progress.value)));
+      });
+
+    return Gesture.Race(pan, tap, longPress);
   }, [
     windowWidth,
     tabCount,
     selectIndex,
+    hasLongPress,
+    longPressIndex,
     tick,
     isDragging,
     lastTicked,
@@ -287,7 +317,9 @@ function TabBarBody({
     };
   }, [progress, slideIndex, windowWidth, tabCount]);
 
-  const bottomOffset = Math.max(insets.bottom - 16, 12);
+  // Shared with `useTabBarReservedSpace`, so a consumer reserving layout space
+  // for the bar can never drift from where the bar actually sits.
+  const bottomOffset = tabBarBottomGap(insets.bottom);
   const barContext = useMemo(
     () => ({ slideIndex, isDragging, theme, activeIndex, selectIndex }),
     [slideIndex, isDragging, theme, activeIndex, selectIndex],
@@ -430,11 +462,13 @@ function TabBarButtonBody({
       }
     >
       <Animated.View style={[styles.itemBox, boxStyle]}>
-        {/* Inactive glyph underneath, active glyph crossfading on top. */}
+        {/* Inactive glyph underneath, active glyph crossfading on top. `active`
+            tells each layer which one it is, so an item with an `activeIcon`
+            crossfades between two different nodes and not just two tints. */}
         <View>
-          <Glyph item={item} tint={theme.inactiveTint} size={ICON_SIZE} />
+          <Glyph item={item} tint={theme.inactiveTint} size={ICON_SIZE} active={false} />
           <Animated.View style={[StyleSheet.absoluteFill, styles.glyphLayer, activeGlyphStyle]}>
-            <Glyph item={item} tint={theme.activeTint} size={ICON_SIZE} />
+            <Glyph item={item} tint={theme.activeTint} size={ICON_SIZE} active />
           </Animated.View>
         </View>
         {/* Fades out and is clipped by the shrinking box — no layout anim. */}

package/src/tab-bar/glyph.native.tsx

@@ -17,7 +17,7 @@ import { Platform, View } from 'react-native';
 import { applyIconColor } from '../frosted-icon-button/shared';
 import type { TabBarGlyphProps } from './shared';
 
-export function TabBarGlyph({ item, tint, size }: TabBarGlyphProps) {
+export function TabBarGlyph({ item, tint, size, active }: TabBarGlyphProps) {
   if (item.sfSymbol && Platform.OS === 'ios') {
     // `TabBarItem.sfSymbol` is a plain `string` because `types.ts` may import
     // from react/react-native only — pulling `expo-symbols`' `SFSymbol` union
@@ -36,9 +36,12 @@ export function TabBarGlyph({ item, tint, size }: TabBarGlyphProps) {
     );
   }
 
+  // Same node-swapping crossfade as the neutral variant: the active layer takes
+  // `activeIcon` when the item has one. An SF Symbol never reaches here, and is
+  // tinted natively above, so the tint crossfade remains its correct expression.
   return (
     <View style={{ height: size, alignItems: 'center', justifyContent: 'center' }}>
-      {applyIconColor(item.icon, tint)}
+      {applyIconColor(active ? (item.activeIcon ?? item.icon) : item.icon, tint)}
     </View>
   );
 }

package/src/tab-bar/glyph.tsx

@@ -2,8 +2,8 @@
  * Ported from expo-glass-tabs v0.1.1 — src/glass-tab-bar.tsx
  * (MIT © 2026 David Mokos). See the top-level NOTICE.
  *
- * NEUTRAL default variant of a tab glyph: renders the item's own `icon` node,
- * tinted for this crossfade layer.
+ * NEUTRAL default variant of a tab glyph: renders the item's own `icon` node —
+ * or its `activeIcon` on the active layer — tinted for this crossfade layer.
  *
  * `item.icon` is the primary icon API for the whole family — a Bloom icon
  * element, exactly like `TabsTrigger` and `FrostedIconButton` take. `sfSymbol`
@@ -17,13 +17,17 @@ import { View } from 'react-native';
 import { applyIconColor } from '../frosted-icon-button/shared';
 import type { TabBarGlyphProps } from './shared';
 
-export function TabBarGlyph({ item, tint, size }: TabBarGlyphProps) {
+export function TabBarGlyph({ item, tint, size, active }: TabBarGlyphProps) {
   // The tint is injected as the icon's `fill` FALLBACK — an icon that sets its
   // own `fill` (a brand mark, say) keeps it, so the crossfade layers simply
   // render it twice at full opacity and it never flickers.
+  //
+  // `activeIcon` is what makes the crossfade able to swap NODES: an icon set
+  // whose selected state is a different SHAPE (outline → filled) cannot be
+  // expressed by tinting one node two ways. Absent, the layer renders `icon`.
   return (
     <View style={{ height: size, alignItems: 'center', justifyContent: 'center' }}>
-      {applyIconColor(item.icon, tint)}
+      {applyIconColor(active ? (item.activeIcon ?? item.icon) : item.icon, tint)}
     </View>
   );
 }

package/src/tab-bar/index.ts

@@ -29,4 +29,5 @@ export {
   useTabBarMinimized,
 } from './minimize-context';
 export type { MinimizeState } from './minimize-context';
+export { useTabBarReservedSpace } from './use-reserved-space';
 export type { TabBarButtonProps, TabBarItem, TabBarProps, TabBarTheme } from './types';

package/src/tab-bar/index.web.tsx

@@ -31,4 +31,5 @@ export {
   useTabBarMinimized,
 } from './minimize-context';
 export type { MinimizeState } from './minimize-context';
+export { useTabBarReservedSpace } from './use-reserved-space';
 export type { TabBarButtonProps, TabBarItem, TabBarProps, TabBarTheme } from './types';

package/src/tab-bar/shared.ts

@@ -51,6 +51,27 @@ export const BLUR_BLEED = 44;
 /** Label type size. Small by design — the icon carries the meaning. */
 export const LABEL_FONT_SIZE = 9.5;
 
+/**
+ * How much of the bottom safe-area inset the bar's own gap absorbs. The pill
+ * already floats clear of the content, so sitting the FULL inset below it
+ * strands it in the middle of the screen on a home-indicator device.
+ */
+const SAFE_AREA_ABSORBED = 16;
+/** Gap floor, for a device (or a browser) reporting no bottom inset at all. */
+const MIN_BOTTOM_GAP = 12;
+
+/**
+ * Vertical gap between the bottom of the pill and the bottom of the window.
+ *
+ * The safe-area inset is folded in HERE, which is why anything reserving layout
+ * space for the bar must go through `useTabBarReservedSpace` (which derives its
+ * number from this same function) rather than adding `insets.bottom` to a
+ * hardcoded height — that double-counts the inset.
+ */
+export function tabBarBottomGap(bottomInset: number): number {
+  return Math.max(bottomInset - SAFE_AREA_ABSORBED, MIN_BOTTOM_GAP);
+}
+
 /**
  * Slide spring: interruptible by design — rapid tab-hopping retargets with
  * preserved velocity. Slight under-damping gives the pill a tiny settle, safe
@@ -58,6 +79,15 @@ export const LABEL_FONT_SIZE = 9.5;
  */
 export const SLIDE_SPRING = { duration: 420, dampingRatio: 0.82 };
 
+/**
+ * How long a press must be held before `onIndexLongPress` fires.
+ *
+ * Comfortably above the tap gesture's own 400ms ceiling: the two can never both
+ * be candidates at the same instant, so arming the long press cannot cost the
+ * bar a tap. Matches the platform long-press feel (iOS ~0.5s).
+ */
+export const LONG_PRESS_MIN_DURATION = 500;
+
 // ---------------------------------------------------------------------------
 //  Theme
 // ---------------------------------------------------------------------------
@@ -156,4 +186,12 @@ export interface TabBarGlyphProps {
   tint: string;
   /** Rendered icon size in px ({@link ICON_SIZE}). */
   size: number;
+  /**
+   * Which crossfade layer this is: `false` for the inactive one underneath,
+   * `true` for the one fading in on top. The active layer renders
+   * `item.activeIcon` when the item has one, so a set that expresses selection
+   * by shape (outline → filled) crossfades between two different nodes rather
+   * than between two tints of the same node.
+   */
+  active: boolean;
 }

package/src/tab-bar/surface-solid.tsx

@@ -0,0 +1,40 @@
+/**
+ * Ported from expo-glass-tabs v0.1.1 — src/glass-tab-bar.tsx
+ * (MIT © 2026 David Mokos). See the top-level NOTICE.
+ *
+ * The tab bar's NON-GLASS capsule surface: a plain animated view filled with the
+ * theme's near-opaque fallback. Android, pre-iOS-26 devices and any build without
+ * a usable `expo-glass-effect` all paint this.
+ *
+ * It lives in its own module because TWO variants render it and one of them
+ * cannot reach the other: Metro resolves a bare `./surface` to
+ * `surface.native.tsx` no matter which file asks, so `surface.native.tsx`
+ * importing its neutral sibling for the fallback would import ITSELF. A name with
+ * no platform variants resolves to this one file everywhere — which is the whole
+ * point, so please do not fold it back into `surface.tsx`.
+ */
+import { StyleSheet } from 'react-native';
+import Animated from 'react-native-reanimated';
+
+import type { TabBarSurfaceProps } from './shared';
+
+export function SolidTabBarSurface({ theme, style }: TabBarSurfaceProps) {
+  return (
+    <Animated.View
+      style={[
+        StyleSheet.absoluteFill,
+        styles.surface,
+        { backgroundColor: theme.solidFallback },
+        style,
+      ]}
+    />
+  );
+}
+
+SolidTabBarSurface.displayName = 'SolidTabBarSurface';
+
+const styles = StyleSheet.create({
+  surface: {
+    borderCurve: 'continuous',
+  },
+});