pixelize-native-library 1.2.0 → 1.3.0

package/lib/module/modules/bottom-nav/BottomNavOverflowSheet.js

@@ -21,10 +21,12 @@
  */
 
 import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { Animated, Pressable, ScrollView, StyleSheet, Text, useWindowDimensions, View } from "react-native";
+import { Platform, Pressable, ScrollView, StyleSheet, Text, useWindowDimensions, View } from "react-native";
+import Reanimated, { useAnimatedStyle } from "react-native-reanimated";
 import { Icon } from "../../core/icon/index.js";
-import { useAnimatedValue, useMotion } from "../../core/motion/index.js";
+import { useMotion, useAnimatedValue } from "../../core/motion/index.js";
 import { useTheme } from "../../theme/hooks.js";
+import { rippleColor } from "../../theme/platform/stateLayer.native.js";
 import { Button } from "../button/index.js";
 import { Input } from "../input/index.js";
 import { editRowStructure, EDIT_SLOT_INDICATOR_SIZE, OVERFLOW_ROW_ICON_SIZE, overflowRowStructure, overflowSectionHeaderStructure, resolveBottomNavBadge, resolveBottomNavDestinationAccessibilityLabel, resolveEditRowState, resolveOverflowSheetHeight } from "./BottomNav.variants.js";
@@ -71,6 +73,14 @@ export const BottomNavOverflowSheet = /*#__PURE__*/memo(function BottomNavOverfl
     }
     wasEditing.current = isEditing;
   }, [edit?.editing, coreTabs.length]);
+  const androidRipple = useMemo(() => Platform.OS === "android" ? {
+    color: rippleColor(theme.mode)
+  } : undefined, [theme.mode]);
+  const rowStyle = useCallback(({
+    pressed
+  }) => [overflowRowStructure(theme), pressed && {
+    backgroundColor: theme.colors.bg.sunken
+  }], [theme]);
   const sheetHeight = resolveOverflowSheetHeight(windowHeight);
   const isSearching = normalizeQuery(query).length > 0;
   const matches = isSearching ? matchDestinations(query, overflowSections) : [];
@@ -107,7 +117,8 @@ export const BottomNavOverflowSheet = /*#__PURE__*/memo(function BottomNavOverfl
     }),
     "aria-selected": isRowSelected(destination.id),
     onPress: () => handleRowPress(destination),
-    style: overflowRowStructure(theme),
+    android_ripple: androidRipple,
+    style: rowStyle,
     children: [/*#__PURE__*/_jsx(BottomNavIconWithBadge, {
       icon: destination.icon,
       iconSize: OVERFLOW_ROW_ICON_SIZE,
@@ -177,7 +188,12 @@ export const BottomNavOverflowSheet = /*#__PURE__*/memo(function BottomNavOverfl
           testID: testID ? `${testID}-reset` : undefined,
           accessibilityRole: "menuitem",
           onPress: edit.onResetToDefault,
-          style: editRowStructure(theme),
+          android_ripple: androidRipple,
+          style: ({
+            pressed
+          }) => [editRowStructure(theme), pressed && {
+            backgroundColor: theme.colors.bg.sunken
+          }],
           children: [/*#__PURE__*/_jsx(Icon, {
             name: "refresh-cw",
             size: OVERFLOW_ROW_ICON_SIZE,
@@ -248,14 +264,22 @@ const EditSlotChip = /*#__PURE__*/memo(function EditSlotChip({
   const motion = useMotion();
   const opacity = useAnimatedValue(selected ? 1 : 0);
   const running = useRef(null);
-  const opacityMotionStyle = useMemo(() => ({
-    opacity
-  }), [opacity]);
+  const opacityMotionStyle = useAnimatedStyle(() => ({
+    opacity: opacity.value
+  }));
+  const androidRipple = useMemo(() => Platform.OS === "android" ? {
+    color: rippleColor(theme.mode)
+  } : undefined, [theme.mode]);
+  const chipStyle = useCallback(({
+    pressed
+  }) => [editRowStructure(theme), pressed && {
+    backgroundColor: theme.colors.bg.sunken
+  }], [theme]);
   useEffect(() => {
     const toValue = selected ? 1 : 0;
     running.current?.stop();
     if (!motion.enabled) {
-      opacity.setValue(toValue);
+      opacity.value = toValue;
       return;
     }
     running.current = motion.timing(opacity, toValue, {
@@ -278,7 +302,8 @@ const EditSlotChip = /*#__PURE__*/memo(function EditSlotChip({
     },
     accessibilityLabel: `${tab.label}, slot ${index + 1}`,
     onPress: () => onPress(index),
-    style: editRowStructure(theme),
+    android_ripple: androidRipple,
+    style: chipStyle,
     children: [/*#__PURE__*/_jsx(Icon, {
       name: tab.icon,
       size: OVERFLOW_ROW_ICON_SIZE,
@@ -292,7 +317,7 @@ const EditSlotChip = /*#__PURE__*/memo(function EditSlotChip({
         color: theme.colors.fg.default
       }],
       children: tab.label
-    }), /*#__PURE__*/_jsx(Animated.View, {
+    }), /*#__PURE__*/_jsx(Reanimated.View, {
       testID: testID ? `${testID}-indicator` : undefined,
       style: [styles.slotIndicator, {
         backgroundColor: theme.colors.accent.solid

package/lib/module/modules/bottom-nav/BottomNavProps.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export {};
+//# sourceMappingURL=BottomNavProps.js.map

package/lib/module/modules/bottom-nav/BottomNavTab.js

@@ -16,12 +16,16 @@
  */
 
 import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { Animated, Pressable, StyleSheet, Text } from "react-native";
-import { useAnimatedValue, useMotion } from "../../core/motion/index.js";
+import { Platform, Pressable, StyleSheet, Text, View } from "react-native";
+import Reanimated, { interpolate, useAnimatedStyle } from "react-native-reanimated";
+import { useMotion, useAnimatedValue } from "../../core/motion/index.js";
+import { usePressState } from "../../core/motion/usePressState.js";
+import { rippleColor, stateLayerScrim } from "../../theme/platform/stateLayer.native.js";
 import { useTheme } from "../../theme/hooks.js";
 import { BOTTOM_NAV_ACTIVE_DOT_SIZE, BOTTOM_NAV_ICON_SIZE, BOTTOM_NAV_SETTLE_SCALE, bottomNavFocusRingStructure, bottomNavTabStructure, resolveBottomNavAccessibility, resolveBottomNavBadge, resolveBottomNavDestinationAccessibilityLabel, resolveBottomNavTabColors } from "./BottomNav.variants.js";
 import { BottomNavIconWithBadge } from "./BottomNavIconWithBadge.js";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const AnimatedPressable = Reanimated.createAnimatedComponent(Pressable);
 export const BottomNavTab = /*#__PURE__*/memo(function BottomNavTab({
   id,
   label,
@@ -36,6 +40,7 @@ export const BottomNavTab = /*#__PURE__*/memo(function BottomNavTab({
 }) {
   const theme = useTheme();
   const motion = useMotion();
+  const press = usePressState(false);
   const [focused, setFocused] = useState(false);
   const colors = resolveBottomNavTabColors(theme.colors, selected);
   const a11y = resolveBottomNavAccessibility({
@@ -44,20 +49,17 @@ export const BottomNavTab = /*#__PURE__*/memo(function BottomNavTab({
   });
   const indicator = useAnimatedValue(selected ? 1 : 0);
   const running = useRef(null);
-  const indicatorMotionStyle = useMemo(() => ({
-    opacity: indicator,
+  const indicatorMotionStyle = useAnimatedStyle(() => ({
+    opacity: indicator.value,
     transform: [{
-      scale: indicator.interpolate({
-        inputRange: [0, 1],
-        outputRange: [BOTTOM_NAV_SETTLE_SCALE, 1]
-      })
+      scale: interpolate(indicator.value, [0, 1], [BOTTOM_NAV_SETTLE_SCALE, 1])
     }]
-  }), [indicator]);
+  }));
   useEffect(() => {
     const toValue = selected ? 1 : 0;
     running.current?.stop();
     if (!motion.enabled) {
-      indicator.setValue(toValue);
+      indicator.value = toValue;
       return;
     }
     running.current = motion.timing(indicator, toValue, {
@@ -71,7 +73,16 @@ export const BottomNavTab = /*#__PURE__*/memo(function BottomNavTab({
   const handlePress = useCallback(() => onPress(id), [onPress, id]);
   const handleFocus = useCallback(() => setFocused(true), []);
   const handleBlur = useCallback(() => setFocused(false), []);
-  return /*#__PURE__*/_jsxs(Pressable, {
+  const overlayStaticStyle = useMemo(() => ({
+    backgroundColor: stateLayerScrim(theme.mode),
+    borderRadius: theme.radii.md,
+    borderCurve: "continuous"
+  }), [theme.mode, theme.radii.md]);
+  const androidRipple = useMemo(() => Platform.OS === "android" ? {
+    color: rippleColor(theme.mode),
+    borderless: false
+  } : undefined, [theme.mode]);
+  return /*#__PURE__*/_jsxs(AnimatedPressable, {
     testID: testID,
     accessibilityRole: a11y.accessibilityRole,
     accessibilityLabel: resolveBottomNavDestinationAccessibilityLabel({
@@ -83,14 +94,26 @@ export const BottomNavTab = /*#__PURE__*/memo(function BottomNavTab({
     "aria-expanded": a11y["aria-expanded"],
     "aria-disabled": a11y["aria-disabled"],
     onPress: handlePress,
+    onPressIn: press.handlers.onPressIn,
+    onPressOut: press.handlers.onPressOut,
+    onLayout: press.onLayout,
     onFocus: handleFocus,
     onBlur: handleBlur,
-    style: bottomNavTabStructure(theme),
-    children: [focused && /*#__PURE__*/_jsx(Animated.View, {
-      pointerEvents: "none",
+    android_ripple: androidRipple,
+    style: [bottomNavTabStructure(theme), {
+      overflow: "hidden"
+    }, press.animatedStyle],
+    children: [/*#__PURE__*/_jsx(Reanimated.View, {
+      testID: testID ? `${testID}-press-overlay` : undefined,
+      style: [StyleSheet.absoluteFill, overlayStaticStyle, press.overlayStyle, {
+        pointerEvents: 'none'
+      }]
+    }), focused && /*#__PURE__*/_jsx(View, {
       testID: testID ? `${testID}-focus-ring` : undefined,
       style: [bottomNavFocusRingStructure(theme), {
         borderColor: theme.colors.border.focus
+      }, {
+        pointerEvents: 'none'
       }]
     }), /*#__PURE__*/_jsx(BottomNavIconWithBadge, {
       icon: icon,
@@ -106,7 +129,7 @@ export const BottomNavTab = /*#__PURE__*/memo(function BottomNavTab({
         color: colors.label
       }],
       children: label
-    }), /*#__PURE__*/_jsx(Animated.View, {
+    }), /*#__PURE__*/_jsx(Reanimated.View, {
       testID: testID ? `${testID}-indicator` : undefined,
       style: [styles.indicator, {
         backgroundColor: colors.indicator

package/lib/module/modules/bottom-nav/MODULE.md

@@ -134,7 +134,8 @@ imports `@react-native-async-storage/async-storage` and never reads a value it w
   modes, in `BottomNav.test.ts` — never eyeballed.
 - **2.3.3** — every animation here runs through `core/motion`'s `useMotion()` (opacity + transform
   only, always native-driver): the active-tab dot, the badge settle, and the edit-mode slot
-  indicator. When `motion.enabled` is false the animated value is `setValue`'d AND the resting style
+  indicator. Tab presses use `usePressState` (scale + state-layer overlay). When `motion.enabled`
+  is false the animated value is `setValue`'d AND the resting style
   is rendered outright, so the state is correct on the very first frame with no tween at all. The
   sheet's own slide/fade is inherited transitively through Drawer.
 - **2.4.7 / 2.4.11** — a `border.focus` offset ring on keyboard/AT focus per tab, identical pattern to
@@ -221,8 +222,16 @@ not a runtime guarantee); core tabs are not independently searchable from the sh
 
 `BottomNav`, and the internal (non-exported) `BottomNavOverflowSheet`/`EditSlotChip`, are wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`) — the sheet/chip need it too or the callback stabilization below is a no-op. `closeSheet`/`handleSheetPress` and (in the overflow sheet) `handleEditToggle`/`handleSlotPress` are `useCallback`'d; a module-level `EMPTY_RECENT` constant replaces `recent ?? []` (was a fresh array every render); the `Menu` trigger element is `useMemo`'d (was a freshly-created element every render, which would defeat `Menu`'s own memo); `EditSlotChip`'s `onPress` now takes `(index: number) => void` so every chip gets the SAME stable function instead of a per-item closure.
 
-## Modernization (v1.0.7)
+## Motion
 
-- Theme imports decoupled to `theme/hooks`; optional peers (reanimated, gesture-handler, flash-list) load at runtime.
-- List-heavy surfaces use `VirtualList` with device-tier window sizing where applicable.
-- `React.memo` + stable callbacks retained; render-item/key-extractor hoisted per ESLint perf rules.
+Both animated parts are Reanimated shared values driven through `core/motion`, never classic
+`Animated`. `BottomNavTab` holds an `indicator` value that `motion.timing` runs between 0 and 1 on
+selection change, feeding an `opacity` + `scale` style through `interpolate`;
+`BottomNavIconWithBadge` holds a `settle` value keyed on the badge's DISPLAY label, so a count
+change inside the `99+` cap does not re-settle the pill. When `motion.enabled` is false neither
+runs a tween — the tab falls back to the static `indicatorHidden`/visible styles and the badge to
+`styles.settled`, so the end state is identical and only the transition is dropped.
+
+Tabs, overflow-sheet rows and edit-slot chips all carry `android_ripple` alongside their
+state-layer overlay. The bar has no top hairline: `floatingBackground`/`floatingSurfaceStyle`
+already supply the tonal fill and the platform shadow/elevation.

package/lib/module/modules/bottom-sheet/BottomSheet.js

@@ -16,12 +16,18 @@
  */
 
 import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { Modal as RNModal, Pressable, StyleSheet, useWindowDimensions, View } from "react-native";
+import { Modal as RNModal, Platform, Pressable, StyleSheet, useWindowDimensions, View } from "react-native";
 import { Gesture, GestureDetector } from "react-native-gesture-handler";
-import Animated, { runOnJS, useAnimatedStyle, useSharedValue, withSpring, withTiming } from "react-native-reanimated";
+import Animated, { FadeInDown, FadeOut, LinearTransition, ReduceMotion, useAnimatedStyle, useSharedValue, withSpring, withTiming } from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+import { useReducedMotion } from "../../core/a11y/index.js";
+import { useHaptics } from "../../core/haptics/index.js";
 import { useMotion } from "../../core/motion/index.js";
+import { renderNodeSlot } from "../../core/slot/index.js";
+import { elevation, floatingBackground, floatingSurfaceStyle, highlight } from "../../theme/platform/index.js";
+import { elevation as elevationTokens } from "../../theme/tokens/primitives/index.js";
 import { useTheme } from "../../theme/hooks.js";
-import { BOTTOM_SHEET_BACKDROP, bottomSheetGrabberStructure, bottomSheetHandleStructure, bottomSheetPanelStructure, resolveBottomSheetPanelColors, resolveBottomSheetSnapOffset, resolveNearestSnapIndex } from "./BottomSheet.variants.js";
+import { BOTTOM_SHEET_BACKDROP, bottomSheetGrabberStructure, bottomSheetHandleStructure, bottomSheetPanelStructure, resolveBottomSheetBottomInset, resolveBottomSheetPanelColors, resolveBottomSheetSnapOffset, resolveNearestSnapIndex } from "./BottomSheet.variants.js";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /** Module-level so the default never hands `snapOffsets` a fresh array identity each render. */
 const DEFAULT_SNAP_POINTS = [0.5];
@@ -39,11 +45,19 @@ export const BottomSheet = /*#__PURE__*/memo(function BottomSheet({
   testID
 }) {
   const theme = useTheme();
+  const childrenSlotStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.regular), {
+    color: theme.colors.fg.default,
+    fontSize: theme.fontSizes.md
+  }], [theme]);
   const motion = useMotion();
+  const haptics = useHaptics();
+  const reducedMotion = useReducedMotion();
   const {
     height: windowHeight
   } = useWindowDimensions();
+  const lastSnapIndexRef = useRef(initialSnapIndex);
   const panelColors = useMemo(() => resolveBottomSheetPanelColors(theme.colors), [theme.colors]);
+  const bottomInset = useMemo(() => resolveBottomSheetBottomInset(theme.space[5], Platform.OS), [theme.space]);
   const [mounted, setMounted] = useState(visible);
   const mountedRef = useRef(mounted);
   mountedRef.current = mounted;
@@ -56,6 +70,11 @@ export const BottomSheet = /*#__PURE__*/memo(function BottomSheet({
   // Resolved here because `slideTo` is a worklet the pan calls from the UI thread.
   const animated = motion.enabled;
   const slideMs = motion.duration("slow");
+  const fireSnapHaptic = useCallback(index => {
+    if (index === lastSnapIndexRef.current) return;
+    lastSnapIndexRef.current = index;
+    if (!reducedMotion) haptics.selection();
+  }, [haptics, reducedMotion]);
   const slideTo = useCallback(target => {
     "worklet";
 
@@ -114,14 +133,15 @@ export const BottomSheet = /*#__PURE__*/memo(function BottomSheet({
     if (projected > windowHeight * DISMISS_PROJECTION) {
       slideTo(windowHeight);
       // Sliding away is not closing: the panel stays mounted and `accessibilityViewIsModal`.
-      runOnJS(onRequestClose)();
+      scheduleOnRN(onRequestClose);
       return;
     }
     const index = resolveNearestSnapIndex(projected, snapOffsets);
     const target = snapOffsets[index] ?? 0;
     activeSnap.value = target;
     slideTo(target);
-  }), [activeSnap, onRequestClose, slideTo, snapOffsets, translateY, windowHeight]);
+    scheduleOnRN(fireSnapHaptic, index);
+  }), [activeSnap, onRequestClose, slideTo, snapOffsets, translateY, windowHeight, fireSnapHaptic]);
   const panelStyle = useAnimatedStyle(() => ({
     transform: [{
       translateY: translateY.value
@@ -130,9 +150,18 @@ export const BottomSheet = /*#__PURE__*/memo(function BottomSheet({
   const scrimStyle = useAnimatedStyle(() => ({
     opacity: scrim.value
   }));
-  const rootPanelStyle = useMemo(() => [bottomSheetPanelStructure(theme), {
-    backgroundColor: panelColors.background
-  }, panelStyle, style], [theme, panelColors.background, panelStyle, style]);
+  const floatingStyle = useMemo(() => {
+    highlight("subtle", theme.mode);
+    elevation(elevationTokens.lg);
+    void theme.elevatedSurfaces;
+    return {
+      backgroundColor: floatingBackground(theme, "lg"),
+      ...floatingSurfaceStyle(theme, "lg")
+    };
+  }, [theme]);
+  const rootPanelStyle = useMemo(() => [bottomSheetPanelStructure(theme), floatingStyle, {
+    paddingBottom: bottomInset
+  }, panelStyle, style], [theme, floatingStyle, bottomInset, panelStyle, style]);
   const grabberStyle = useMemo(() => [bottomSheetGrabberStructure(theme), {
     backgroundColor: panelColors.grabber
   }], [theme, panelColors.grabber]);
@@ -150,12 +179,14 @@ export const BottomSheet = /*#__PURE__*/memo(function BottomSheet({
       style: StyleSheet.absoluteFill,
       onPress: onRequestClose,
       children: /*#__PURE__*/_jsx(Animated.View, {
-        pointerEvents: "none",
-        style: backdropStyle
+        style: [backdropStyle, {
+          pointerEvents: 'none'
+        }]
       })
     }), /*#__PURE__*/_jsx(View, {
-      style: styles.overlay,
-      pointerEvents: "box-none",
+      style: [styles.overlay, {
+        pointerEvents: 'box-none'
+      }],
       children: /*#__PURE__*/_jsxs(Animated.View, {
         testID: testID ? `${testID}-panel` : undefined,
         accessibilityViewIsModal: true,
@@ -172,7 +203,12 @@ export const BottomSheet = /*#__PURE__*/memo(function BottomSheet({
               style: grabberStyle
             })
           })
-        }), children]
+        }), /*#__PURE__*/_jsx(Animated.View, {
+          entering: FadeInDown.springify().reduceMotion(ReduceMotion.System),
+          exiting: FadeOut.reduceMotion(ReduceMotion.System),
+          layout: LinearTransition.reduceMotion(ReduceMotion.System),
+          children: renderNodeSlot(children, childrenSlotStyle)
+        })]
       })
     })]
   });

package/lib/module/modules/bottom-sheet/BottomSheet.variants.js

@@ -1,7 +1,17 @@
 "use strict";
 
 import { createThemedVariants } from "../../core/style/index.js";
-export const BOTTOM_SHEET_BACKDROP = "#00000080";
+import { withAlpha } from "../../core/gradient/index.js";
+import { MOTION_TRANSFORM } from "../../core/motion/config.js";
+
+// Shared `scrimOpacity` knob, not a locally-guessed hex suffix — same resting value as Modal/Drawer/Menu.
+export const BOTTOM_SHEET_BACKDROP = withAlpha("#000000", MOTION_TRANSFORM.scrimOpacity);
+
+// Duplicated from Drawer's resolver on purpose — no react-native-safe-area-context peer dependency.
+export const BOTTOM_SHEET_IOS_HOME_INDICATOR_INSET = 20;
+export function resolveBottomSheetBottomInset(basePadding, platformOS) {
+  return platformOS === "ios" ? basePadding + BOTTOM_SHEET_IOS_HOME_INDICATOR_INSET : basePadding;
+}
 export function resolveBottomSheetSnapOffset(snapFraction, windowHeight) {
   const clamped = Math.max(0.1, Math.min(0.95, snapFraction));
   return windowHeight * (1 - clamped);
@@ -27,10 +37,10 @@ export function resolveBottomSheetPanelColors(colors) {
 }
 export const bottomSheetPanelStructure = createThemedVariants(theme => ({
   base: {
-    borderTopLeftRadius: theme.radii.lg,
-    borderTopRightRadius: theme.radii.lg,
-    maxHeight: "92%",
-    paddingBottom: theme.space[5]
+    borderTopLeftRadius: theme.radii.xl,
+    borderTopRightRadius: theme.radii.xl,
+    borderCurve: "continuous",
+    maxHeight: "92%"
   }
 }));
 export const bottomSheetHandleStructure = createThemedVariants(theme => ({

package/lib/module/modules/bottom-sheet/BottomSheetProps.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export {};
+//# sourceMappingURL=BottomSheetProps.js.map

package/lib/module/modules/bottom-sheet/MODULE.md

@@ -1,7 +1,13 @@
-# bottom-sheet/
+# bottom-sheet/ — a gesture-driven bottom sheet with configurable snap points
 
 Gesture-driven bottom sheet with configurable `snapPoints` (height fractions). reanimated + gesture-handler.
 
+## Exports
+
+- `BottomSheet` — `visible`, `onRequestClose`, `children`, `snapPoints` (default `[0.5]`),
+  `initialSnapIndex` (default `0`), layout-only `style`, `testID`
+- `BottomSheetProps`
+
 ## Dismissal — the sheet is CONTROLLED
 
 `visible` is owned by the consumer, so sliding the panel away is not the same as closing it. Every
@@ -9,7 +15,7 @@ dismissal path reports through `onRequestClose` and lets the parent flip `visibl
 
 - backdrop press, and `onAccessibilityEscape` on the panel;
 - a swipe released past `DISMISS_PROJECTION` (0.85 of the window, velocity folded in) — the gesture
-  slides the panel out **and** `runOnJS(onRequestClose)()`.
+  slides the panel out **and** `scheduleOnRN(onRequestClose)`.
 
 The panel carries `accessibilityViewIsModal` for as long as it is mounted, so a swipe that only slid
 it off-screen would leave a VoiceOver user sealed inside an invisible modal. That is why the gesture
@@ -41,7 +47,18 @@ Nothing is wired here on purpose. BottomSheet always presents through React Nati
 grabber. The grabber is the sheet's only drag target (the pan is attached to the handle, not the
 panel body), so WCAG 1.4.11 applies: the previous `border.default` is the decorative boundary role
 and measured **1.16–1.43:1** on the surface across all 18 palettes. `border.interactive` clears 3:1
-everywhere (min 3.32, emerald light). The backdrop is a fixed `#00000080` scrim, not a palette role.
+everywhere (min 3.32, emerald light). The backdrop (`BOTTOM_SHEET_BACKDROP`) is
+`withAlpha("#000000", MOTION_TRANSFORM.scrimOpacity)` — the same shared `scrimOpacity` knob as
+Modal/Drawer/Menu's resting scrim, not a locally-guessed hex suffix — still not a palette role.
+
+## Known gaps
+
+- **No `react-native-safe-area-context` wiring** — same gap `Drawer` documents: listed as an
+  optional peer but not a real `peerDependencies` entry. Bottom padding instead uses
+  `resolveBottomSheetBottomInset` (a caller-supplied base padding + a static
+  `BOTTOM_SHEET_IOS_HOME_INDICATOR_INSET` on iOS), duplicated locally rather than sharing `Drawer`'s
+  resolver on purpose — modules never import across `src/modules/*`. Revisit once the package
+  becomes a real peer dependency.
 
 ## Tests
 
@@ -51,3 +68,7 @@ everywhere (min 3.32, emerald light). The backdrop is a fixed `#00000080` scrim,
 - `BottomSheet.motion.test.tsx` — both halves of the reduce-motion contract. reanimated shared
   values have no JS driver to force in, so `withSpring`/`withTiming` are mocked and a target written
   as a plain number is the proof that nothing animated.
+
+## Wave 2 behaviour
+
+Sheet motion honours reduce-motion (snap open/close) and may emit haptics on snap when `useMotion().enabled`.

package/lib/module/modules/breadcrumbs/Breadcrumbs.js

@@ -0,0 +1,54 @@
+"use strict";
+
+import { memo, useMemo } from "react";
+import { Pressable, View } from "react-native";
+import { useTheme } from "../../theme/hooks.js";
+import { Text } from "../text/index.js";
+import { breadcrumbsStructure, resolveBreadcrumbLabelStyle, resolveBreadcrumbSeparatorStyle } from "./Breadcrumbs.variants.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export const Breadcrumbs = /*#__PURE__*/memo(function Breadcrumbs({
+  items,
+  separator = "/",
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const rootStyle = useMemo(() => [breadcrumbsStructure(theme), style], [theme, style]);
+  const separatorStyle = useMemo(() => resolveBreadcrumbSeparatorStyle(theme), [theme]);
+  return /*#__PURE__*/_jsx(View, {
+    testID: testID,
+    accessibilityRole: "none",
+    style: rootStyle,
+    children: items.map((item, index) => {
+      const current = index === items.length - 1;
+      const labelStyle = resolveBreadcrumbLabelStyle(theme, current);
+      const segmentTestId = testID ? `${testID}-segment-${index}` : undefined;
+      const segment = item.onPress && !current ? /*#__PURE__*/_jsx(Pressable, {
+        accessibilityRole: "link",
+        accessibilityLabel: item.label,
+        onPress: item.onPress,
+        testID: segmentTestId,
+        children: /*#__PURE__*/_jsx(Text, {
+          style: labelStyle,
+          children: item.label
+        })
+      }) : /*#__PURE__*/_jsx(Text, {
+        style: labelStyle,
+        testID: segmentTestId,
+        children: item.label
+      });
+      return /*#__PURE__*/_jsxs(View, {
+        style: {
+          flexDirection: "row",
+          alignItems: "center",
+          gap: theme.space[1]
+        },
+        children: [index > 0 ? /*#__PURE__*/_jsx(Text, {
+          style: separatorStyle,
+          children: separator
+        }) : null, segment]
+      }, `${item.label}-${index}`);
+    })
+  });
+});
+//# sourceMappingURL=Breadcrumbs.js.map

package/lib/module/modules/breadcrumbs/Breadcrumbs.variants.js

@@ -0,0 +1,28 @@
+"use strict";
+
+import { createThemedVariants } from "../../core/style/index.js";
+export const breadcrumbsStructure = createThemedVariants(theme => ({
+  base: {
+    flexDirection: "row",
+    flexWrap: "wrap",
+    alignItems: "center",
+    gap: theme.space[1]
+  },
+  variants: {},
+  defaultVariants: {}
+}));
+export function resolveBreadcrumbLabelStyle(theme, current) {
+  return {
+    fontSize: theme.fontSizes.sm,
+    color: current ? theme.colors.fg.default : theme.colors.fg.muted,
+    ...theme.fontStyleForWeight(theme.fontWeights.medium)
+  };
+}
+export function resolveBreadcrumbSeparatorStyle(theme) {
+  return {
+    fontSize: theme.fontSizes.sm,
+    color: theme.colors.fg.muted,
+    ...theme.fontStyleForWeight(theme.fontWeights.regular)
+  };
+}
+//# sourceMappingURL=Breadcrumbs.variants.js.map

package/lib/module/modules/breadcrumbs/BreadcrumbsProps.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export {};
+//# sourceMappingURL=BreadcrumbsProps.js.map

package/lib/module/modules/breadcrumbs/MODULE.md

@@ -0,0 +1,13 @@
+# breadcrumbs/ — a horizontal back-trail for detail screens
+
+Horizontal back-trail for detail screens. Last segment is current (non-link); earlier segments may be pressable.
+
+## Exports
+
+- `Breadcrumbs` — `items`, `separator` (default `"/"`), layout-only `style`, `testID`
+- `BreadcrumbItem` — `label`, optional `onPress`
+- `BreadcrumbsProps`
+
+A segment is a `Pressable` with `accessibilityRole="link"` only when it has `onPress` **and** is not
+the last item; the current (last) segment is always plain `Text`. With `testID`, each segment gets
+`${testID}-segment-${index}`.

package/lib/module/modules/breadcrumbs/index.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export { Breadcrumbs } from "./Breadcrumbs.js";
+//# sourceMappingURL=index.js.map