@oxyhq/bloom 1.13.0 → 1.14.0

package/src/avatar/resolve-shape.ts

@@ -0,0 +1,33 @@
+import { SQUIRCLE_PATH } from './squircle-path';
+import { AVATAR_SHAPE_PATHS, NAMED_SHAPE_VIEW_BOX } from './shape-paths';
+import type { AvatarShape, AvatarShapePath } from './types';
+
+/**
+ * A shape reduced to what the renderers need: either nothing (a circle, drawn
+ * with `borderRadius` and no SVG at all) or one outline plus the size of the
+ * square space it is drawn in.
+ */
+export type ResolvedAvatarShape = AvatarShapePath | null;
+
+/**
+ * Turns the public `shape` prop into an outline.
+ *
+ * Returns `null` for a circle so callers can keep the cheap `borderRadius`
+ * path — the common case never touches `react-native-svg`. An unknown string
+ * also returns `null`: a shape name that does not resolve should degrade to a
+ * plain circular avatar, never to a blank hole where a face should be.
+ */
+export function resolveAvatarShape(shape: AvatarShape | AvatarShapePath | undefined): ResolvedAvatarShape {
+  if (!shape || shape === 'circle') return null;
+
+  if (typeof shape !== 'string') {
+    return { d: shape.d, viewBox: shape.viewBox ?? 1 };
+  }
+
+  if (shape === 'squircle') {
+    return { d: SQUIRCLE_PATH, viewBox: 1 };
+  }
+
+  const named = AVATAR_SHAPE_PATHS[shape];
+  return named ? { d: named, viewBox: NAMED_SHAPE_VIEW_BOX } : null;
+}

package/src/avatar/shape-paths.ts

@@ -0,0 +1,150 @@
+/**
+ * Named avatar outlines.
+ *
+ * Each entry is an SVG path drawn in a 100×100 square coordinate space, scaled
+ * at render time to the avatar's pixel size. That space is declared once in
+ * {@link NAMED_SHAPE_VIEW_BOX} rather than baked into the numbers, so the paths
+ * can be read and edited at human-friendly magnitudes. The built-in squircle
+ * lives in `squircle-path.ts` and uses a 0–1 space; both are supported because
+ * {@link AvatarShapePath} carries its own `viewBox`.
+ *
+ * `circle` is deliberately absent: a circular avatar is rendered with
+ * `borderRadius` and never reaches the SVG renderer.
+ */
+
+/** Side length of the coordinate space every path below is drawn in. */
+export const NAMED_SHAPE_VIEW_BOX = 100;
+
+export type AvatarShapeName =
+  | 'square' | 'slanted' | 'arch' | 'semicircle'
+  | 'oval' | 'pill' | 'triangle' | 'arrow' | 'fan'
+  | 'diamond' | 'clamshell' | 'pentagon' | 'gem' | 'very-sunny'
+  | 'sunny' | '4-sided-cookie' | '6-sided-cookie' | '7-sided-cookie'
+  | '9-sided-cookie' | '12-sided-cookie' | '4-leaf-clover'
+  | '8-leaf-clover' | 'burst' | 'soft-burst' | 'boom' | 'soft-boom'
+  | 'flower' | 'puffy' | 'puffy-diamond' | 'ghost-ish'
+  | 'pixel-circle' | 'pixel-triangle' | 'bun' | 'heart';
+
+export const AVATAR_SHAPE_PATHS: Record<AvatarShapeName, string> = {
+  // --- Basic ---
+  square:
+    'M12 0H88Q100 0 100 12V88Q100 100 88 100H12Q0 100 0 88V12Q0 0 12 0Z',
+  slanted:
+    'M22 0H88Q100 0 100 12V78Q100 100 78 100H12Q0 100 0 88V22Q0 0 22 0Z',
+  arch:
+    'M50 0Q100 0 100 50V88Q100 100 88 100H12Q0 100 0 88V50Q0 0 50 0Z',
+  semicircle:
+    'M0 50A50 50 0 0 1 100 50V88Q100 100 88 100H12Q0 100 0 88Z',
+
+  // --- Organic ---
+  oval:
+    'M50 2C78 2 96 22 96 50S78 98 50 98S4 78 4 50S22 2 50 2Z',
+  pill:
+    'M34 4H66Q96 4 96 34V66Q96 96 66 96H34Q4 96 4 66V34Q4 4 34 4Z',
+  triangle:
+    'M50 5L95 90Q97 95 92 95H8Q3 95 5 90Z',
+  arrow:
+    'M50 0L100 45Q100 52 94 52H68V92Q68 100 58 100H42Q32 100 32 92V52H6Q0 52 0 45Z',
+  fan:
+    'M50 8Q90 8 96 48Q100 78 70 96Q50 108 30 96Q0 78 4 48Q10 8 50 8Z',
+
+  // --- Geometric ---
+  diamond:
+    'M50 2L96 50L50 98L4 50Z',
+  clamshell:
+    'M10 20Q10 4 26 4H74Q90 4 90 20V60Q90 96 50 96Q10 96 10 60Z',
+  pentagon:
+    'M50 2L97 36L79 96H21L3 36Z',
+  gem:
+    'M30 4H70L98 36L50 98L2 36Z',
+
+  // --- Sunny/Cookie ---
+  'very-sunny':
+    'M50 0L58 20L78 6L72 28L96 22L82 42L100 50L82 58L96 78L72 72L78 94L58 80L50 100L42 80L22 94L28 72L4 78L18 58L0 50L18 42L4 22L28 28L22 6L42 20Z',
+  sunny:
+    'M50 4L60 24L80 10L74 32L98 28L84 48L100 50L84 52L98 72L74 68L80 90L60 76L50 96L40 76L20 90L26 68L2 72L16 52L0 50L16 48L2 28L26 32L20 10L40 24Z',
+  '4-sided-cookie':
+    'M50 2Q76 22 76 50Q76 78 50 98Q24 78 24 50Q24 22 50 2Z',
+  '6-sided-cookie':
+    'M50 2Q72 10 82 30Q92 52 80 74Q66 96 44 96Q22 96 10 74Q-2 52 10 30Q22 10 50 2Z',
+  '7-sided-cookie':
+    'M50 2Q70 6 84 22Q96 40 94 62Q90 82 74 94Q56 102 38 96Q20 88 10 70Q2 50 8 32Q18 10 50 2Z',
+  '9-sided-cookie':
+    'M50 2Q64 4 76 14Q86 26 92 42Q94 58 88 72Q78 86 64 94Q50 98 36 94Q22 86 12 72Q6 58 8 42Q14 26 24 14Q36 4 50 2Z',
+  '12-sided-cookie':
+    'M50 2L62 6L74 14L84 26L90 40L92 54L88 68L80 80L68 88L54 92L40 90L28 84L18 72L10 58L8 44L12 30L20 18L32 10L44 4Z',
+
+  // --- Nature ---
+  '4-leaf-clover':
+    'M50 4Q70 4 70 26Q96 26 96 50Q96 74 70 74Q70 96 50 96Q30 96 30 74Q4 74 4 50Q4 26 30 26Q30 4 50 4Z',
+  '8-leaf-clover':
+    'M50 2Q60 16 72 8Q84 16 80 30Q96 32 92 46Q100 60 86 66Q92 80 78 84Q76 98 60 92Q52 100 42 92Q28 98 24 84Q10 80 16 66Q2 60 10 46Q6 32 22 30Q18 16 30 8Q42 16 50 2Z',
+  burst:
+    'M50 0L56 30L80 6L62 34L100 26L70 44L100 50L70 56L100 74L62 66L80 94L56 70L50 100L44 70L20 94L38 66L0 74L30 56L0 50L30 44L0 26L38 34L20 6L44 30Z',
+  'soft-burst':
+    'M50 4L58 28L78 8L66 32L96 24L76 44L98 50L76 56L96 76L66 68L78 92L58 72L50 96L42 72L22 92L34 68L4 76L24 56L2 50L24 44L4 24L34 32L22 8L42 28Z',
+  boom:
+    'M50 0L54 18L62 2L60 20L76 6L68 24L88 14L76 30L98 24L82 38L100 38L86 46L100 50L86 54L100 62L82 62L98 76L76 70L88 86L68 76L76 94L60 80L62 98L54 82L50 100L46 82L38 98L40 80L24 94L32 76L12 86L24 70L2 76L18 62L0 62L14 54L0 50L14 46L0 38L18 38L2 24L24 30L12 14L32 24L24 6L40 20L38 2L46 18Z',
+  'soft-boom':
+    'M50 4L56 22L68 6L64 26L82 14L74 32L94 24L82 40L100 36L86 48L100 50L86 52L100 64L82 60L94 76L74 68L82 86L64 74L68 94L56 78L50 96L44 78L32 94L36 74L18 86L26 68L6 76L18 60L0 64L14 52L0 50L14 48L0 36L18 40L6 24L26 32L18 14L36 26L32 6L44 22Z',
+  flower:
+    'M50 4Q62 18 72 10Q82 18 76 32Q90 30 88 44Q98 50 88 56Q90 70 76 68Q82 82 72 90Q62 82 50 96Q38 82 28 90Q18 82 24 68Q10 70 12 56Q2 50 12 44Q10 30 24 32Q18 18 28 10Q38 18 50 4Z',
+  puffy:
+    'M34 6Q50-4 66 6Q84 6 90 22Q104 34 96 50Q104 66 90 78Q84 94 66 94Q50 104 34 94Q16 94 10 78Q-4 66 4 50Q-4 34 10 22Q16 6 34 6Z',
+  'puffy-diamond':
+    'M50 2Q66 10 72 4Q86 12 84 28Q98 32 94 48Q100 64 86 70Q88 86 72 88Q62 98 48 94Q34 100 26 86Q12 88 8 72Q-2 62 6 48Q0 32 16 28Q14 12 28 4Q38 10 50 2Z',
+
+  // --- Fun ---
+  'ghost-ish':
+    'M20 96V40Q20 4 50 4Q80 4 80 40V96L70 86L60 96L50 86L40 96L30 86Z',
+  'pixel-circle':
+    'M30 4H70V4H86V14H96V30H100V70H96V86H86V96H70V100H30V96H14V86H4V70H0V30H4V14H14V4H30Z',
+  'pixel-triangle':
+    'M42 4H58V18H70V32H82V46H94V60H100V100H0V60H6V46H18V32H30V18H42Z',
+  bun:
+    'M12 54Q-4 24 20 8Q44-6 68 8Q92 22 94 50Q96 72 76 88Q56 100 36 96Q14 90 12 54Z',
+  heart:
+    'M50 90C25 70 2 55 2 32Q2 10 24 6Q40 2 50 18Q60 2 76 6Q98 10 98 32Q98 55 75 70Z',
+};
+
+/**
+ * Display labels for the named shapes, in the order a picker should show them.
+ * Exported so consumers building a shape picker do not re-derive the order (or
+ * the capitalisation) themselves.
+ */
+export const AVATAR_SHAPE_LABELS: { name: AvatarShapeName; label: string }[] = [
+  { name: 'square', label: 'Square' },
+  { name: 'slanted', label: 'Slanted' },
+  { name: 'arch', label: 'Arch' },
+  { name: 'semicircle', label: 'Semicircle' },
+  { name: 'oval', label: 'Oval' },
+  { name: 'pill', label: 'Pill' },
+  { name: 'triangle', label: 'Triangle' },
+  { name: 'arrow', label: 'Arrow' },
+  { name: 'fan', label: 'Fan' },
+  { name: 'diamond', label: 'Diamond' },
+  { name: 'clamshell', label: 'Clamshell' },
+  { name: 'pentagon', label: 'Pentagon' },
+  { name: 'gem', label: 'Gem' },
+  { name: 'very-sunny', label: 'Very Sunny' },
+  { name: 'sunny', label: 'Sunny' },
+  { name: '4-sided-cookie', label: '4-Sided Cookie' },
+  { name: '6-sided-cookie', label: '6-Sided Cookie' },
+  { name: '7-sided-cookie', label: '7-Sided Cookie' },
+  { name: '9-sided-cookie', label: '9-Sided Cookie' },
+  { name: '12-sided-cookie', label: '12-Sided Cookie' },
+  { name: '4-leaf-clover', label: '4-Leaf Clover' },
+  { name: '8-leaf-clover', label: '8-Leaf Clover' },
+  { name: 'burst', label: 'Burst' },
+  { name: 'soft-burst', label: 'Soft Burst' },
+  { name: 'boom', label: 'Boom' },
+  { name: 'soft-boom', label: 'Soft Boom' },
+  { name: 'flower', label: 'Flower' },
+  { name: 'puffy', label: 'Puffy' },
+  { name: 'puffy-diamond', label: 'Puffy Diamond' },
+  { name: 'ghost-ish', label: 'Ghost-ish' },
+  { name: 'pixel-circle', label: 'Pixel Circle' },
+  { name: 'pixel-triangle', label: 'Pixel Triangle' },
+  { name: 'bun', label: 'Bun' },
+  { name: 'heart', label: 'Heart' },
+];

package/src/avatar/types.ts

@@ -3,7 +3,30 @@ import type { ImageSourcePropType, StyleProp, ViewStyle, ImageStyle } from 'reac
 // Referenced by the `variant` prop docs below.
 import type { ImageResolver } from '../image-resolver/context';
 
-export type AvatarShape = 'circle' | 'squircle';
+import type { AvatarShapeName } from './shape-paths';
+
+/**
+ * Built-in avatar outlines: the two originals plus the named registry in
+ * `shape-paths.ts`. Any of these can be passed as a plain string.
+ */
+export type AvatarShape = 'circle' | 'squircle' | AvatarShapeName;
+
+/**
+ * A caller-supplied outline, for shapes that are not in the built-in registry.
+ *
+ * The path is clipped against the avatar box, so it should fill its coordinate
+ * space edge to edge; anything outside is cut off rather than scaled to fit.
+ */
+export interface AvatarShapePath {
+  /** SVG path data (the `d` attribute) describing a closed outline. */
+  d: string;
+  /**
+   * Side length of the square coordinate space `d` is drawn in — 100 for a
+   * path written over a 0–100 grid, 1 for one written over a 0–1 grid.
+   * Defaults to 1.
+   */
+  viewBox?: number;
+}
 
 /** Gradient sweep direction for a multi-color {@link AvatarRingConfig}. */
 export type AvatarRingGradientDirection = 'diagonal' | 'horizontal' | 'vertical';
@@ -45,8 +68,14 @@ export interface AvatarProps {
   verified?: boolean;
   /** Custom verified badge icon (rendered at bottom-right) */
   verifiedIcon?: ReactNode;
-  /** Shape of the avatar (defaults to 'circle'). 'squircle' requires react-native-svg. */
-  shape?: AvatarShape;
+  /**
+   * Shape of the avatar (defaults to `'circle'`). Accepts a built-in name —
+   * `'squircle'`, `'heart'`, `'pentagon'`, … see {@link AvatarShapeName} — or an
+   * {@link AvatarShapePath} with your own outline. Everything except `'circle'`
+   * clips through `react-native-svg`; a name that does not resolve falls back to
+   * a circle.
+   */
+  shape?: AvatarShape | AvatarShapePath;
   /** Container style */
   style?: StyleProp<ViewStyle>;
   /** Image style (circle shape only) */

package/src/tab-bar/TabBarBase.tsx

@@ -29,6 +29,7 @@ import Animated, {
   interpolate,
   interpolateColor,
   runOnJS,
+  useAnimatedReaction,
   useAnimatedStyle,
   useSharedValue,
   withSpring,
@@ -83,6 +84,13 @@ type BarContextValue = {
   theme: TabBarTheme;
   /** Set only on the CONTROLLED path (see `TabBarProps.activeIndex`). */
   activeIndex: number | undefined;
+  /**
+   * True while a driver owns the highlight's POSITION (see
+   * `TabBarProps.activeProgress`). Buttons read it to stand down: their focus
+   * effect and their press must not spring `slideIndex` out from under a pager
+   * mid-gesture. It says nothing about visibility, which stays where it was.
+   */
+  driven: boolean;
   /** Report a selection made by a button press. */
   selectIndex: (index: number) => void;
 };
@@ -103,6 +111,7 @@ function TabBarBody({
   Blur,
   children,
   activeIndex,
+  activeProgress,
   onIndexChange,
   onIndexLongPress,
   theme: themeOverrides,
@@ -189,6 +198,33 @@ function TabBarBody({
   // a legitimate effect (external-system sync), the same shape `Tabs` uses for
   // its underline. The focus-driven path is handled per-button instead — see
   // `TabBarButtonBody`.
+  // DRIVEN path: a pager owns the highlight's position and writes it every
+  // frame, so the position is COPIED rather than sprung — a spring chasing a
+  // per-frame value lags behind the finger, which is the whole thing this path
+  // exists to avoid.
+  //
+  // `useAnimatedReaction` cannot be called conditionally, so an unsupplied
+  // `activeProgress` is stood in for by a shared value nothing ever writes and
+  // the reaction returns early. `driven` changing flips the identity of `source`
+  // too, and both are in the deps array, so the reaction re-registers either
+  // way.
+  //
+  // Scrubbing still wins: a finger on the BAR is a direct manipulation of the
+  // bar and must not be fought by the pager's settle animation.
+  // (Deps: see the CRITICAL note below.)
+  const idleProgress = useSharedValue(0);
+  const driven = activeProgress !== undefined;
+  const source = activeProgress ?? idleProgress;
+  useAnimatedReaction(
+    () => source.value,
+    (value) => {
+      if (!driven) return;
+      if (isDragging.value) return;
+      slideIndex.value = value;
+    },
+    [source, driven, isDragging, slideIndex],
+  );
+
   useEffect(() => {
     if (activeIndex === undefined) return;
     // While scrubbing the finger owns the highlight; never fight it.
@@ -209,10 +245,17 @@ function TabBarBody({
     // stale index would animate out of a position the user never saw, and would
     // light up every tab in between on the way. Interrupted mid-fade it is
     // still on screen, so from there it slides as it always does.
-    slideIndex.value =
-      highlightOpacity.value === 0 ? activeIndex : withSpring(activeIndex, SLIDE_SPRING);
+    //
+    // On the DRIVEN path this effect keeps owning visibility and gives up the
+    // position: the driver is already writing `slideIndex` every frame, and a
+    // spring started here would drag the capsule across the bar between two of
+    // its writes.
+    if (!driven) {
+      slideIndex.value =
+        highlightOpacity.value === 0 ? activeIndex : withSpring(activeIndex, SLIDE_SPRING);
+    }
     highlightOpacity.value = withTiming(1, HIGHLIGHT_FADE);
-  }, [activeIndex, hasSelection, slideIndex, highlightOpacity, isDragging]);
+  }, [activeIndex, hasSelection, driven, slideIndex, highlightOpacity, isDragging]);
 
   // Scrubbing: the highlight tracks the finger 1:1 while dragging (no spring —
   // it must feel attached), haptic ticks fire on boundary crossings, and
@@ -292,8 +335,15 @@ function TabBarBody({
         const index = Math.round(indexAtX(event.x, progress.value));
         // Same rule as the controlled path above: appear at the tapped tab when
         // hidden, slide to it when already on screen.
-        slideIndex.value =
-          highlightOpacity.value === 0 ? index : withSpring(index, SLIDE_SPRING);
+        //
+        // A tap is a discrete writer, so on the DRIVEN path it stands down like
+        // the others and the driver carries the highlight to the tapped tab.
+        // The scrub is the one gesture that does not: a finger dragging the
+        // pill is manipulating the bar itself, not asking for a page.
+        if (!driven) {
+          slideIndex.value =
+            highlightOpacity.value === 0 ? index : withSpring(index, SLIDE_SPRING);
+        }
         highlightOpacity.value = withTiming(1, HIGHLIGHT_FADE);
         setMinimized(minimized, 0);
         runOnJS(selectIndex)(index);
@@ -324,6 +374,7 @@ function TabBarBody({
     hasLongPress,
     longPressIndex,
     tick,
+    driven,
     isDragging,
     lastTicked,
     slideIndex,
@@ -444,8 +495,8 @@ function TabBarBody({
   const constrainedWrapStyle: ViewStyle | null =
     maxWidth === undefined ? null : { width: barOuterWidth, alignSelf: 'center' };
   const barContext = useMemo(
-    () => ({ slideIndex, highlightOpacity, isDragging, theme, activeIndex, selectIndex }),
-    [slideIndex, highlightOpacity, isDragging, theme, activeIndex, selectIndex],
+    () => ({ slideIndex, highlightOpacity, isDragging, theme, activeIndex, driven, selectIndex }),
+    [slideIndex, highlightOpacity, isDragging, theme, activeIndex, driven, selectIndex],
   );
 
   return (
@@ -522,6 +573,10 @@ function TabBarButtonBody({
   useEffect(() => {
     if (isFocused === undefined || !isFocused || !bar) return;
     if (bar.isDragging.value) return;
+    // A driver owns the position — see `TabBarProps.activeProgress`. It is
+    // already tracking this same focus change; springing from here as well would
+    // be a second writer on one shared value.
+    if (bar.driven) return;
     bar.slideIndex.value = withSpring(index, SLIDE_SPRING);
   }, [isFocused, index, bar]);
 
@@ -589,9 +644,13 @@ function TabBarButtonBody({
         // for assistive-technology activation (VoiceOver) and keyboard focus.
         if (bar) {
           // Appear at the tab when hidden, slide to it when visible — the same
-          // rule the tap gesture and the controlled path follow.
-          bar.slideIndex.value =
-            bar.highlightOpacity.value === 0 ? index : withSpring(index, SLIDE_SPRING);
+          // rule the tap gesture and the controlled path follow. Skipped on the
+          // driven path, where the position belongs to the driver and this
+          // press will reach it as an ordinary selection.
+          if (!bar.driven) {
+            bar.slideIndex.value =
+              bar.highlightOpacity.value === 0 ? index : withSpring(index, SLIDE_SPRING);
+          }
           bar.highlightOpacity.value = withTiming(1, HIGHLIGHT_FADE);
         }
         setMinimized(minimized, 0);

package/src/tab-bar/expo-router/RouterTabBar.tsx

@@ -19,6 +19,11 @@ import type { TabBarItem, TabBarProps } from '../types';
  * by each trigger's own focus (see `RouterTabBarButton`), which is what keeps it
  * correct through deep links, back gestures and any other programmatic
  * navigation. Setting both would put two writers on one shared value.
+ *
+ * `activeProgress` is NOT omitted, and that is not an oversight. It answers a
+ * different question — where the highlight is, not whether there is one — so a
+ * router-focused bar whose screens are PAGED can pass it and keep the focus
+ * path for selection. See `TabBarProps.activeProgress`.
  */
 export type RouterTabBarProps = TabListProps & Omit<TabBarProps, 'activeIndex'>;
 

package/src/tab-bar/types.ts

@@ -4,14 +4,21 @@
  *
  * Public API types for `@oxyhq/bloom/tab-bar`.
  *
- * This module imports from `react` and `react-native` ONLY. It is resolved by a
- * consumer's `tsc`, by Metro, and by every web bundler alike, so a platform
- * import here (expo-glass-effect / expo-symbols / expo-router) would break all
- * three at once. Platform behaviour lives in `surface.native.tsx` /
- * `glyph.native.tsx` / `surface.web.tsx` and the `expo-router/` adapter.
+ * This module names no PLATFORM package. It is resolved by a consumer's `tsc`,
+ * by Metro, and by every web bundler alike, so an import here of
+ * expo-glass-effect / expo-symbols / expo-router / react-native-screens would
+ * break all three at once. Platform behaviour lives in `surface.native.tsx` /
+ * `glyph.native.tsx` / `surface.web.tsx` and the `expo-router/` adapter; the
+ * gate is `src/__tests__/TabBarWebFork.test.ts`.
+ *
+ * `react-native-reanimated` is exempt and always was: it is a REQUIRED peer that
+ * every neutral module in this family already imports at runtime
+ * (`TabBarBase.tsx`), and the one reference below is `import type`, erased
+ * before any bundler sees it.
  */
 import type { ReactNode } from 'react';
 import type { PressableProps, ViewProps } from 'react-native';
+import type { SharedValue } from 'react-native-reanimated';
 
 export type TabBarItem = {
   /** Stable identity for the tab (a route name in router-driven usage). */
@@ -92,6 +99,30 @@ export type TabBarProps = ViewProps & {
    * highlight from its own `isFocused`.
    */
   activeIndex?: number;
+  /**
+   * DRIVEN path — the highlight's live position, in TAB UNITS, on the UI thread.
+   * A pager writes its own page position here (`1.4` is 40% of the way from the
+   * second tab to the third) and the highlight tracks the finger 1:1 instead of
+   * springing to a settled index after the navigation commits.
+   *
+   * It says WHERE the highlight is, never WHETHER there is one. Selection stays
+   * with the path already in play: `activeIndex` when the bar is controlled (an
+   * index naming no tab still fades the highlight out — see above), each
+   * button's `isFocused` when it is not. Passing this alone, with neither, is a
+   * bar that is always selected, which is what the focus-driven path already
+   * means.
+   *
+   * PRECEDENCE, because a shared value with two writers is a race: the SCRUB
+   * always wins — a finger on the bar is a direct manipulation of the bar, and
+   * releasing it reports through `onIndexChange` like any other selection. Below
+   * that, this value wins over every discrete writer: while it is supplied, the
+   * controlled effect, the focus effect and a `TabBarButton`'s own press all
+   * stop writing the position and leave it to the driver. So a consumer that
+   * passes this must keep it truthful — spring it to the settled index after a
+   * commit, and after any navigation it did not cause (a deep link, a back
+   * gesture), or the highlight stays where the last gesture left it.
+   */
+  activeProgress?: SharedValue<number>;
   /**
    * Called with the chosen index when a tab is picked by tap, by scrub release,
    * or by keyboard/assistive-technology activation of a `TabBarButton`.

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

@@ -1,20 +0,0 @@
-/**
- * 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/constructed-style-sheets.ts

@@ -1,68 +0,0 @@
-/**
- * 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

@@ -1,30 +0,0 @@
-/**
- * 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 `ProfileCard`: 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

@@ -1,99 +0,0 @@
-/**
- * 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);
-}