@vvedantb/native-ui 0.17.0 → 0.17.2

package/README.md

@@ -59,6 +59,20 @@ To hide a tab, give its screen Expo Router's `href: null`. From 0.3.9 `FloatingT
 
 From 0.3.16 the focused tab sits on a rounded pill with the `TabsTrigger` pills outline, with the foreground label and icon; the other tabs are muted. From 0.3.17 the pill fill is `floatingTabPillColors(scheme)`: the muted `palette.default` (`--default`, `#ebebeb`) in light, so it shows on the near-white glass bar, and `palette.tabBarPill` (`#474747`, the kit `--segment`) in dark. `palette.tabBarPill` is its own key, so an app that themes `segment` (the segmented `Tabs` thumb) keeps a pill that shows on the dark glass bar. On the web the `--segment` pill sits on a `--default` track; here the bar is the raised surface, so the light pill takes the track fill. A route's `tabBarActiveTintColor` and `tabBarInactiveTintColor` still override the label and icon colours. The pill is one tab wide, inset 4 from the bar on every side, and slides to a newly focused tab over the web `--tabs-dur` (200 ms) and `--tabs-ease`. It counts only the tabs drawn, and there is none while a hidden route is focused.
 
+## Gallery, Maestro and CI
+
+`apps/native-gallery` (at the repository root) is an Expo SDK 57 app that renders every component from every entry point, with a layering stress screen (a tab bar over glass, with dropdowns, selects, sheets, dialogs and toasts over it) and a keyboard screen (`PromptInput`, inline and stacked). Clerk is mocked there, so it needs no keys. Run it:
+
+```sh
+pnpm install
+pnpm --filter native-gallery start
+# or cd apps/native-gallery && npx expo start
+```
+
+`tests/galleryRegistry.test.ts` fails when a React component export has no entry in `apps/native-gallery/src/galleryRegistry.ts`. Maestro flows in `apps/native-gallery/.maestro/` drive the dropdown, composer, sheets and select. The `native-ui-gallery-android` GitHub Actions job builds the gallery, boots an API 34 emulator and runs them for pull requests that touch this package or the gallery. A new or changed component needs a gallery entry, a Maestro flow and a hand test on an Android emulator.
+
+The `Select` note stays: mount one `<PortalHost />` from `@rn-primitives/portal` at the app root, outside any `Modal`. The gallery does so in `app/_layout.tsx`.
+
 ## Entry points
 
 The root entry exports everything. It still imports `BottomSheetContainer` and `DateTimeField`, so Metro resolves `@gorhom/bottom-sheet`, `@react-native-community/datetimepicker` and `dayjs` for any import from it. Apps without those peers, such as V Store, should import from the smaller entries below. Between them, they export every name the root exports.
@@ -542,8 +556,8 @@ import {
 | `ChainOfThought` and its parts | Simplified: header, steps with a rail, search-result chips. |
 | `PromptInput`, `PromptInputButton`, `PromptInputSubmit` | The web field surface with a `header` slot (attachments), a field, a `toolbar` slot and the send button. The field grows from one line to 160 high (about 6 lines), then scrolls (auto-grow in both layouts from 0.12.1; send resets the height, and from 0.14.0 so does clearing the field). On web a multiline field is one row to start (0.14.0). Send is primary, and from 0.14.0 it stays primary and fades when there is nothing to send, as the web send button (before, it turned `secondary`). While `status` is `submitted` or `streaming` it is a "Stop" square that calls `onStop`. It sits in a `KeyboardAvoidingView` (padding, on iOS and Android) and pads the safe-area insets: put it last in a full-height column. Under a navigation header, pass the header height as `keyboardVerticalOffset`; above a tab bar, pass `safeBottom={false}`. |
 | `MessageActionSheet`, `ReplyQuoteChip`, `MessageQuote` (0.13.0) | Quoted replies. Long-press a `Message` with `actions` to open the sheet; Reply first, then Copy. Pass `<ReplyQuoteChip author text onDismiss />` as `PromptInput` `replyTo`; send the reply with a `MessageQuote` in `MessageContent` `quote`. See [Quoted replies](#quoted-replies-0130). |
-| `ToolApprovalCard`, `ToolDraftCard` (0.13.0) | A pending tool call: name, cut args summary, Deny and Approve (`ToolDraftCard` adds Edit). `onDecide("approve" \| "deny" \| "edit")`; `pending` or `disabled` turns the buttons off. |
-| `SubagentRunCard`, `SubagentResultCard` (0.13.0) | A subagent run (title, status pill, elapsed, Cancel while `running`) and its result (summary, detail in a fold). |
+| `ToolApprovalCard`, `ToolDraftCard` (0.13.0) | A pending tool call: name, cut args summary, Deny and Approve (`ToolDraftCard` adds Edit). `onDecide("approve" \| "deny" \| "edit", edits?)`; `pending` or `disabled` turns the buttons off. Optional chrome: `server`, `routineMode`, `expiresLabel`, `target`, `meta`, `chrome`. `ToolDraftCard` `fields` (`DraftField[]`) shows the draft and an inline editor under Edit; Approve then passes `changedDraftEdits` as `edits`. |
+| `SubagentRunCard`, `SubagentResultCard` (0.13.0) | A subagent run (title, status pill, elapsed, Cancel while `queued` or `running`; statuses `queued`, `running`, `done`, `failed`, `cancelled`, `timed_out`; optional `statusLine`, `error`, `avatar`) and its result (summary, detail in a fold; optional `approvalPending`, `approvalPendingIn`, `handoffs`, `avatar`). |
 | `MessageBotLabel`, `Message` `bot` (0.13.0) | Which bot sent an assistant message, for group chats: `bot={{ name, avatar }}`, or render `MessageBotLabel` above `MessageContent`. |
 | `PromptInput layout="inline"` | One row, as the web `Composer layout="inline"`: `leading` (such as a + button), the field (one line to start, then it grows from 0.12.1), `toolbar`, then send, in a 20-radius field with `p-1.5`. The field is the web `text-sm leading-6` (14 / 24) from 0.14.0. `shape="pill"` (0.14.0) is Eva's web chat composer: 48 high on one line, radius 24, a 14 / 20 field 36 high and a 36 send button; give the + `variant="secondary"`. |
 | `Suggestions`, `Suggestion` | A horizontal row of round chips (or `orientation="vertical"`). `onPress` gets the suggestion text. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vvedantb/native-ui",
-  "version": "0.17.0",
+  "version": "0.17.2",
   "license": "MIT",
   "description": "Shared React Native / Expo UI primitives. Floating surfaces, forms, overlays, toasts, settings chrome, tab bar, AI chat parts, the family app marks, a NativeWind preset, the Expo web root and Clerk + Convex auth screens.",
   "type": "module",

package/src/AmbientBackground.tsx

@@ -33,7 +33,7 @@ export function AmbientBackground({
         <View
           pointerEvents="none"
           style={{
-            ...StyleSheet.absoluteFillObject,
+            ...StyleSheet.absoluteFill,
             backgroundColor: tokens.color.background[scheme],
           }}
         />

package/src/BottomSheetContainer.tsx

@@ -1,18 +1,76 @@
-import {
+import BottomSheet, {
   BottomSheetBackdrop,
-  BottomSheetModal,
   BottomSheetView,
 } from "@gorhom/bottom-sheet";
-import { View, Text, TouchableOpacity } from "react-native";
-import { useRef, useEffect, useCallback, JSX } from "react";
+import type { BottomSheetDefaultBackdropProps } from "@gorhom/bottom-sheet/lib/typescript/components/bottomSheetBackdrop/types";
+import { IconX } from "@tabler/icons-react-native";
+import React, { useCallback } from "react";
+import {
+  Platform,
+  Text,
+  TouchableOpacity,
+  View,
+  type ViewProps,
+} from "react-native";
 import { Colors } from "./colors";
 import { textStyle, typeStyle } from "./controlStyles";
-import { IconX } from "@tabler/icons-react-native";
-import { BottomSheetDefaultBackdropProps } from "@gorhom/bottom-sheet/lib/typescript/components/bottomSheetBackdrop/types";
+import { floatingSolidFill } from "./floating";
 import { GlassSheetBackground } from "./LiquidGlass";
 import { useLargerText } from "./theme";
 import { useScheme } from "./useScheme";
 
+// One snap point, set explicitly. With dynamic sizing the sheet can measure to
+// height 0 on Android and never appear.
+const SNAP_POINTS = ["40%"];
+const SHEET_RADIUS = 20;
+
+/**
+ * Opaque sheet chrome for Android. The glass background needs a measured blur
+ * target, which is not reliable once an RN `Modal` has been dismissed.
+ */
+function SolidSheetBackground({
+  style,
+  pointerEvents,
+}: {
+  style?: ViewProps["style"];
+  pointerEvents?: ViewProps["pointerEvents"];
+}) {
+  const scheme = useScheme();
+  return (
+    <View
+      pointerEvents={pointerEvents}
+      style={[
+        style,
+        {
+          backgroundColor: floatingSolidFill[scheme],
+          borderTopLeftRadius: SHEET_RADIUS,
+          borderTopRightRadius: SHEET_RADIUS,
+        },
+      ]}
+    />
+  );
+}
+
+function SheetBackdrop(props: BottomSheetDefaultBackdropProps) {
+  return (
+    <BottomSheetBackdrop
+      {...props}
+      appearsOnIndex={0}
+      disappearsOnIndex={-1}
+      opacity={0.5}
+    />
+  );
+}
+
+/**
+ * A controlled bottom sheet over the screen, built on gorhom's default-export
+ * `BottomSheet` (the named `BottomSheet` export is undefined).
+ *
+ * It renders nothing while `visible` is false. A closed gorhom sheet still lays
+ * out an absolute-fill host that can cover the triggers beneath it, and
+ * `BottomSheetModal.present()` did nothing after an RN `Modal` had been
+ * dismissed on Android.
+ */
 export function BottomSheetContainer({
   visible,
   onClose,
@@ -26,53 +84,43 @@ export function BottomSheetContainer({
   children: React.ReactNode;
   closeTestID?: string;
 }) {
-  const bottomSheetModalRef = useRef<BottomSheetModal>(null);
   const largerText = useLargerText();
-  const colorScheme = useScheme();
-
-  useEffect(() => {
-    if (visible) {
-      bottomSheetModalRef.current?.present();
-    } else {
-      bottomSheetModalRef.current?.dismiss();
-    }
-  }, [visible]);
-
+  const isDark = useScheme() === "dark";
   const renderBackdrop = useCallback(
-    (props: JSX.IntrinsicAttributes & BottomSheetDefaultBackdropProps) => (
-      <BottomSheetBackdrop
-        {...props}
-        disappearsOnIndex={-1}
-        appearsOnIndex={0}
-        opacity={0.5}
-      />
-    ),
+    (props: BottomSheetDefaultBackdropProps) => <SheetBackdrop {...props} />,
     [],
   );
 
+  if (!visible) {
+    return null;
+  }
+
   return (
-    <BottomSheetModal
-      ref={bottomSheetModalRef}
+    <BottomSheet
+      index={0}
+      snapPoints={SNAP_POINTS}
+      enableDynamicSizing={false}
+      enablePanDownToClose
+      enableContentPanningGesture={false}
+      enableHandlePanningGesture
+      keyboardBehavior="interactive"
+      onClose={onClose}
       backdropComponent={renderBackdrop}
-      onDismiss={onClose}
-      backgroundComponent={GlassSheetBackground}
+      backgroundComponent={
+        Platform.OS === "android" ? SolidSheetBackground : GlassSheetBackground
+      }
       handleIndicatorStyle={{
-        backgroundColor:
-          colorScheme === "dark" ? Colors.white : Colors.neutral[800],
+        backgroundColor: isDark ? Colors.white : Colors.neutral[800],
       }}
-      enableContentPanningGesture={false}
-      enableHandlePanningGesture={true}
-      keyboardBehavior="interactive"
     >
-      <BottomSheetView className="p-5 pb-12">
+      {/* Padding is a style, not a NativeWind class: `BottomSheetView` does not
+          always apply `className`, and an unpadded sheet can measure too small. */}
+      <BottomSheetView style={{ padding: 20, paddingBottom: 48 }}>
         <View className="mb-4 flex-row items-center justify-between gap-3">
           <Text
             accessibilityRole="header"
             className={`${largerText ? "text-2xl" : "text-xl"} flex-1 font-instrument-sans-semibold`}
-            style={[
-              textStyle("foreground", colorScheme === "dark" ? "dark" : "light"),
-              typeStyle("semibold"),
-            ]}
+            style={[textStyle("foreground", isDark ? "dark" : "light"), typeStyle("semibold")]}
           >
             {title}
           </Text>
@@ -80,19 +128,16 @@ export function BottomSheetContainer({
             testID={closeTestID}
             accessibilityRole="button"
             accessibilityLabel="Close"
-            onPress={() => bottomSheetModalRef.current?.dismiss()}
+            onPress={onClose}
             className="-mr-2 h-12 w-12 items-center justify-center"
             hitSlop={8}
             activeOpacity={0.7}
           >
-            <IconX
-              size={largerText ? 32 : 28}
-              color={colorScheme === "dark" ? "white" : "black"}
-            />
+            <IconX size={largerText ? 32 : 28} color={isDark ? "white" : "black"} />
           </TouchableOpacity>
         </View>
         {children}
       </BottomSheetView>
-    </BottomSheetModal>
+    </BottomSheet>
   );
 }

package/src/DropdownMenu.tsx

@@ -28,7 +28,7 @@ import { useControllableState } from "./primitives/use-controllable-state";
 /**
  * Sizes from the web menu classes (`_menu-classes.ts`): content `min-w-[12rem]
  * p-1.5 rounded-lg`, `sideOffset` 4 and `collisionPadding` 8; items `px-2.5
- * py-2 rounded-menu-item` (8) with a 16 icon `gap-2`; radio items `pl-8` with
+ * py-3 rounded-menu-item` (8) with a 16 icon `gap-2`; radio items `pl-8` with
  * the check at `left-2.5`; the label `px-2.5 py-1.5`; the separator `-mx-1.5
  * my-1 h-px`. Items are at least 48 high, a phone menu row (the web
  * `max-sm:min-h-10` is 40).
@@ -42,7 +42,7 @@ export const DROPDOWN_MENU = {
   itemHeight: 48,
   itemRadius: 8,
   itemPaddingX: 10,
-  itemPaddingY: 8,
+  itemPaddingY: 12,
   itemGap: 8,
   indicatorInset: 32,
   indicatorLeft: 10,

package/src/ai/collapsible.tsx

@@ -1,7 +1,7 @@
 import { createContext, useContext, type ReactNode } from "react";
 import { Pressable, View, type PressableProps, type ViewProps } from "react-native";
 import { IconChevronDown, IconChevronRight } from "@tabler/icons-react-native";
-import Animated, { cubicBezier } from "react-native-reanimated";
+import Animated from "react-native-reanimated";
 import { cn } from "../cn";
 import { MIN_TOUCH_TARGET, touchSlop } from "../controlStyles";
 import { useControllableState } from "../primitives/use-controllable-state";
@@ -13,11 +13,15 @@ import { useReduceMotion } from "../useReduceMotion";
 // opening, a virtualised row scrolled back). The chevron turns in 150 ms; with
 // Reduce Motion it changes in place.
 
-/** The web chevron: `transition-transform duration-150`, on the strong ease-out. */
+/**
+ * The web chevron: `transition-transform duration-150`. The curve is the
+ * predefined `ease-out`: a `cubicBezier(...)` value in an `Animated.View`
+ * style does not typecheck against `react-native-reanimated` 4.3.
+ */
 const CHEVRON_TURN = {
   transitionProperty: "transform",
   transitionDuration: 150,
-  transitionTimingFunction: cubicBezier(0.23, 1, 0.32, 1),
+  transitionTimingFunction: "ease-out",
 } as const;
 
 type CollapsibleContextValue = { open: boolean; setOpen: (open: boolean) => void };

package/src/ai/conversation.tsx

@@ -62,9 +62,13 @@ export function isScrolledToBottom(
 /**
  * What the thread scrolls with: the `ScrollView` of `ConversationContent` or
  * the `FlatList` of `ConversationList`. `scrollToEnd` goes to the newest
- * message, which is offset 0 in an inverted list.
+ * message, which is offset 0 in an inverted list. `scrollTo` goes to an
+ * offset; only the `ScrollView` has it, so call it as `scrollTo?.(...)`.
  */
-export type ConversationScroller = { scrollToEnd: (options?: { animated?: boolean }) => void };
+export type ConversationScroller = {
+  scrollToEnd: (options?: { animated?: boolean }) => void;
+  scrollTo?: (options: { y: number; animated?: boolean }) => void;
+};
 
 type ConversationContextValue = {
   isAtBottom: boolean;

package/src/ai/index.ts

@@ -183,7 +183,21 @@ export { ActivityStepDetail } from "./activity-step-detail";
 export type { ActivityStepDetailProps, ActivityStepDetailStep } from "./activity-step-detail";
 export { UnifiedDiff, DiffStat, UNIFIED_DIFF } from "./unified-diff";
 export type { UnifiedDiffProps, UnifiedDiffLine, DiffStatProps } from "./unified-diff";
-export { ToolApprovalCard, ToolDraftCard, summarizeArgs, ARGS_MAX_CHARS } from "./tool-approval-card";
-export type { ToolApprovalCardProps, ToolDraftCardProps, ToolDecision } from "./tool-approval-card";
+export {
+  ToolApprovalCard,
+  ToolDraftCard,
+  summarizeArgs,
+  ARGS_MAX_CHARS,
+  changedDraftEdits,
+  DRAFT_ROLE_LABELS,
+} from "./tool-approval-card";
+export type {
+  ToolApprovalCardProps,
+  ToolDraftCardProps,
+  ToolDecision,
+  DraftField,
+  DraftFieldRole,
+  DraftEdit,
+} from "./tool-approval-card";
 export { SubagentRunCard, SubagentResultCard, subagentStatusColors } from "./subagent-cards";
-export type { SubagentRunCardProps, SubagentResultCardProps, SubagentStatus } from "./subagent-cards";
+export type { SubagentRunCardProps, SubagentResultCardProps, SubagentStatus, SubagentHandoff } from "./subagent-cards";

package/src/ai/prompt-input.tsx

@@ -394,6 +394,7 @@ export function PromptInput({
               </View>
             ) : null}
             <FieldInput
+              testID={testID ? `${testID}-input` : undefined}
               nativeID={COMPOSER_INPUT_ID}
               multiline
               numberOfLines={ONE_ROW}
@@ -440,6 +441,7 @@ export function PromptInput({
           {header ? <View className="flex-row flex-wrap gap-1 px-2 pt-2">{header}</View> : null}
           {/* The `Textarea` field without its `numberOfLines` (default 4), which on Android sets the line count: this one starts at one line and grows. */}
           <FieldInput
+            testID={testID ? `${testID}-input` : undefined}
             nativeID={COMPOSER_INPUT_ID}
             multiline
             numberOfLines={ONE_ROW}

package/src/ai/subagent-cards.tsx

@@ -1,3 +1,4 @@
+import type { ReactNode } from "react";
 import { Text, View } from "react-native";
 import { IconRobot } from "@tabler/icons-react-native";
 import { cn } from "../cn";
@@ -6,8 +7,9 @@ import { palette, withAlpha } from "../palette";
 import { useLargerText } from "../theme";
 import { tokens } from "../tokens";
 import { useScheme } from "../useScheme";
+import { Spinner } from "../Spinner";
 import { CardButton } from "./card-button";
-import { chatTextSize, formatElapsed } from "./chat-text";
+import { chatTextSize, formatElapsed, MONO_FONT } from "./chat-text";
 import {
   Collapsible,
   CollapsibleChevron,
@@ -17,23 +19,25 @@ import {
 } from "./collapsible";
 import { ResponseText } from "./response-text";
 
-export type SubagentStatus = "running" | "done" | "failed" | "cancelled";
+export type SubagentStatus = "queued" | "running" | "done" | "failed" | "cancelled" | "timed_out";
 
 const STATUS_LABEL: Record<SubagentStatus, string> = {
+  queued: "Queued",
   running: "Running",
   done: "Done",
   failed: "Failed",
   cancelled: "Cancelled",
+  timed_out: "Timed out",
 };
 
 /** Pill colours per status. Text and border share one hue, the fill is a wash of it. */
 export function subagentStatusColors(status: SubagentStatus, scheme: "light" | "dark") {
   const hex =
-    status === "running"
+    status === "running" || status === "queued"
       ? palette.primary[scheme]
       : status === "done"
         ? palette.success[scheme]
-        : status === "failed"
+        : status === "failed" || status === "timed_out"
           ? palette.danger[scheme]
           : tokens.color.muted[scheme];
   return { color: hex, borderColor: withAlpha(hex, 0.25), backgroundColor: withAlpha(hex, 0.12) };
@@ -64,8 +68,14 @@ export type SubagentRunCardProps = {
   status: SubagentStatus;
   /** Whole seconds the run has taken. Shown as "12s" or "1m 5s". */
   elapsedSeconds?: number;
-  /** Shows a Cancel button while `status` is `running`. */
+  /** Shows a Cancel button while `status` is `queued` or `running`. */
   onCancel?: () => void;
+  /** Muted detail under the title, such as step or progress text. */
+  statusLine?: string;
+  /** Error text, in the danger colour. */
+  error?: string;
+  /** Replaces the robot icon. While `queued` or `running` a spinner shows instead. */
+  avatar?: ReactNode;
   className?: string;
   /** Default `subagent-run-card`. Parts add `-status`, `-elapsed` and `-cancel`. */
   testID?: string;
@@ -77,6 +87,9 @@ export function SubagentRunCard({
   status,
   elapsedSeconds,
   onCancel,
+  statusLine,
+  error,
+  avatar,
   className,
   testID = "subagent-run-card",
 }: SubagentRunCardProps) {
@@ -94,7 +107,11 @@ export function SubagentRunCard({
       style={cardStyle(scheme)}
     >
       <View className="flex-row items-center gap-2">
-        <IconRobot size={largerText ? 22 : 18} color={tokens.color.muted[scheme]} />
+        {status === "queued" || status === "running" ? (
+          <Spinner size="sm" decorative />
+        ) : (
+          (avatar ?? <IconRobot size={largerText ? 22 : 18} color={tokens.color.muted[scheme]} />)
+        )}
         <Text
           numberOfLines={2}
           className={cn(body, "min-w-0 flex-1 font-instrument-sans-semibold")}
@@ -104,6 +121,16 @@ export function SubagentRunCard({
         </Text>
         <StatusPill status={status} testID={`${testID}-status`} />
       </View>
+      {statusLine ? (
+        <Text testID={`${testID}-status-line`} className={small} style={[sizeStyle(small), textStyle("muted", scheme)]}>
+          {statusLine}
+        </Text>
+      ) : null}
+      {error ? (
+        <Text testID={`${testID}-error`} className={small} style={[sizeStyle(small), { color: palette.danger[scheme] }]}>
+          {error}
+        </Text>
+      ) : null}
       <View className="flex-row flex-wrap items-center justify-between gap-2">
         {elapsed ? (
           <Text
@@ -117,7 +144,7 @@ export function SubagentRunCard({
         ) : (
           <View />
         )}
-        {status === "running" && onCancel ? (
+        {(status === "running" || status === "queued") && onCancel ? (
           <CardButton
             testID={`${testID}-cancel`}
             label="Cancel"
@@ -131,12 +158,26 @@ export function SubagentRunCard({
   );
 }
 
+export type SubagentHandoff = {
+  toolName: string;
+  server?: string;
+  argsSummary: string;
+};
+
 export type SubagentResultCardProps = {
   title: string;
   /** The short result, always shown. */
   summary: string;
   /** The full result, shown when the card is open. No fold without it. */
   detail?: string;
+  /** Shows the warning note that an approval waits in another chat. */
+  approvalPending?: boolean;
+  /** Name for `Approval pending in {name}'s chat.` Default "the other bot". */
+  approvalPendingIn?: string;
+  /** Proposed actions, listed under "Proposed actions". */
+  handoffs?: readonly SubagentHandoff[];
+  /** A leading avatar beside the title. */
+  avatar?: ReactNode;
   defaultOpen?: boolean;
   open?: boolean;
   onOpenChange?: (open: boolean) => void;
@@ -150,6 +191,10 @@ export function SubagentResultCard({
   title,
   summary,
   detail,
+  approvalPending = false,
+  approvalPendingIn,
+  handoffs,
+  avatar,
   defaultOpen = false,
   open,
   onOpenChange,
@@ -169,14 +214,39 @@ export function SubagentResultCard({
       className={cn("w-full gap-2 p-4", className)}
       style={cardStyle(scheme)}
     >
-      <Text
-        numberOfLines={2}
-        className={cn(body, "font-instrument-sans-semibold")}
-        style={[sizeStyle(body), typeStyle("semibold"), textStyle("foreground", scheme)]}
-      >
-        {title}
-      </Text>
+      <View className="flex-row items-center gap-2">
+        {avatar}
+        <Text
+          numberOfLines={2}
+          className={cn(body, "min-w-0 flex-1 font-instrument-sans-semibold")}
+          style={[sizeStyle(body), typeStyle("semibold"), textStyle("foreground", scheme)]}
+        >
+          {title}
+        </Text>
+      </View>
       <ResponseText>{summary}</ResponseText>
+      {approvalPending ? (
+        <Text testID={`${testID}-approval-pending`} className={small} style={[sizeStyle(small), { color: palette.warning[scheme] }]}>
+          {`Approval pending in ${approvalPendingIn ? `${approvalPendingIn}'s` : "the other bot's"} chat.`}
+        </Text>
+      ) : null}
+      {handoffs && handoffs.length > 0 ? (
+        <View testID={`${testID}-handoffs`} className="gap-1">
+          <Text className={small} style={[sizeStyle(small), textStyle("muted", scheme)]}>
+            Proposed actions
+          </Text>
+          {handoffs.map((handoff, index) => (
+            <Text
+              key={`${handoff.toolName}-${index}`}
+              testID={`${testID}-handoff-${index}`}
+              className={small}
+              style={[sizeStyle(small), textStyle("muted", scheme), { fontFamily: MONO_FONT }]}
+            >
+              {`${handoff.toolName}${handoff.server ? ` via ${handoff.server}` : ""}: ${handoff.argsSummary}`}
+            </Text>
+          ))}
+        </View>
+      ) : null}
       {detail ? (
         <>
           <CollapsibleTrigger

package/src/ai/tool-approval-card.tsx

@@ -1,3 +1,4 @@
+import { useState, type ReactNode } from "react";
 import { Text, View } from "react-native";
 import { IconTool } from "@tabler/icons-react-native";
 import { cn } from "../cn";
@@ -6,9 +7,34 @@ import { withAlpha, palette } from "../palette";
 import { useLargerText } from "../theme";
 import { tokens } from "../tokens";
 import { useScheme } from "../useScheme";
+import { Input } from "../Input";
+import { Textarea } from "../Textarea";
 import { CardButton } from "./card-button";
 import { chatTextSize, MONO_FONT } from "./chat-text";
 
+export type DraftFieldRole = "to" | "cc" | "bcc" | "subject" | "body";
+export type DraftField = { key: string; role: DraftFieldRole; value: string };
+export type DraftEdit = { key: string; value: string };
+
+export const DRAFT_ROLE_LABELS: Record<DraftFieldRole, string> = {
+  to: "To",
+  cc: "Cc",
+  bcc: "Bcc",
+  subject: "Subject",
+  body: "Message",
+};
+
+/** The fields whose value differs from the original. `read` returns the edited value, or undefined for no edit. */
+export function changedDraftEdits(
+  fields: readonly DraftField[],
+  read: (key: string) => string | undefined,
+): DraftEdit[] {
+  return fields.flatMap((field) => {
+    const value = read(field.key);
+    return value === undefined || value === field.value ? [] : [{ key: field.key, value }];
+  });
+}
+
 /** What the reader chose. `edit` is offered by `ToolDraftCard` only. */
 export type ToolDecision = "approve" | "deny" | "edit";
 
@@ -18,13 +44,25 @@ export type ToolApprovalCardProps = {
   /** The arguments, as a short string or an object. Shown cut to `ARGS_MAX_CHARS`. */
   args?: string | Record<string, unknown>;
   /** Called with the choice. */
-  onDecide?: (decision: ToolDecision) => void;
+  onDecide?: (decision: ToolDecision, edits?: DraftEdit[]) => void;
   /** True while the app sends the decision: the buttons are off and the card says so. */
   pending?: boolean;
   /** Turns the buttons off without the pending state. */
   disabled?: boolean;
   approveLabel?: string;
   denyLabel?: string;
+  /** The tool server. The meta line reads `via {server}`, else `built-in tool`. */
+  server?: string;
+  /** Appends "queued while you were away" to the meta line. */
+  routineMode?: boolean;
+  /** Expiry text the app has formatted. Appends `Expires {expiresLabel}` to the meta line. */
+  expiresLabel?: string;
+  /** Shows a `Target: {target}` line. */
+  target?: string;
+  /** Replaces the default meta line. */
+  meta?: ReactNode;
+  /** Extra content under the meta line (above the target and args). */
+  chrome?: ReactNode;
   className?: string;
   /** Default `tool-approval-card`. The buttons add `-approve`, `-deny` and `-edit`. */
   testID?: string;
@@ -50,7 +88,14 @@ export function summarizeArgs(args: string | Record<string, unknown> | undefined
   return text.length > max ? `${text.slice(0, Math.max(0, max - 1))}…` : text;
 }
 
-type BaseProps = ToolApprovalCardProps & { allowEdit?: boolean; editLabel?: string; heading: string };
+type BaseProps = ToolApprovalCardProps & {
+  allowEdit?: boolean;
+  editLabel?: string;
+  heading: string;
+  /** Text between the source and the expiry in the default meta line. */
+  metaNote?: string;
+  fields?: readonly DraftField[];
+};
 
 function ToolCardBase({
   toolName,
@@ -63,6 +108,14 @@ function ToolCardBase({
   editLabel = "Edit",
   allowEdit = false,
   heading,
+  metaNote,
+  fields,
+  server,
+  routineMode = false,
+  expiresLabel,
+  target,
+  meta,
+  chrome,
   className,
   testID = "tool-approval-card",
 }: BaseProps) {
@@ -73,6 +126,23 @@ function ToolCardBase({
   const caption = chatTextSize("caption", largerText);
   const off = pending || disabled;
   const summary = summarizeArgs(args);
+  const [edits, setEdits] = useState<Record<string, string> | null>(null);
+  const hasFields = fields !== undefined;
+  const headerFields = fields?.filter((field) => field.role !== "body") ?? [];
+  const bodyField = fields?.find((field) => field.role === "body");
+  const metaText = [
+    server ? `via ${server}` : "built-in tool",
+    ...(metaNote ? [metaNote] : []),
+  ].join(" · ") + (routineMode ? " · queued while you were away" : "") + (expiresLabel ? ` · Expires ${expiresLabel}` : "");
+  const showMeta = meta !== undefined || server !== undefined || routineMode || expiresLabel !== undefined || metaNote !== undefined;
+  const onEdit = () => {
+    if (!fields) return onDecide?.("edit");
+    setEdits(edits ? null : Object.fromEntries(fields.map((field) => [field.key, field.value])));
+  };
+  const onApprove = () => {
+    if (fields && edits) onDecide?.("approve", changedDraftEdits(fields, (key) => edits[key]));
+    else onDecide?.("approve");
+  };
   return (
     <View
       testID={testID}
@@ -93,6 +163,14 @@ function ToolCardBase({
           {pending ? "Sending decision…" : heading}
         </Text>
       </View>
+      {showMeta ? (
+        meta ?? (
+          <Text testID={`${testID}-meta`} className={caption} style={[sizeStyle(caption), textStyle("muted", scheme)]}>
+            {metaText}
+          </Text>
+        )
+      ) : null}
+      {chrome}
       <Text
         testID={`${testID}-name`}
         numberOfLines={2}
@@ -101,7 +179,58 @@ function ToolCardBase({
       >
         {toolName}
       </Text>
-      {summary ? (
+      {target ? (
+        <Text testID={`${testID}-target`} className={small} style={[sizeStyle(small), textStyle("muted", scheme)]}>
+          {`Target: ${target}`}
+        </Text>
+      ) : null}
+      {hasFields ? (
+        edits ? (
+          <View testID={`${testID}-editor`} className="gap-2">
+            {fields.map((field) => (
+              <View key={field.key} className="gap-1">
+                <Text className={caption} style={[sizeStyle(caption), textStyle("muted", scheme)]}>
+                  {DRAFT_ROLE_LABELS[field.role]}
+                </Text>
+                {field.role === "body" ? (
+                  <Textarea
+                    testID={`${testID}-field-${field.key}`}
+                    value={edits[field.key] ?? ""}
+                    onChangeText={(value: string) => setEdits({ ...edits, [field.key]: value })}
+                    numberOfLines={8}
+                    accessibilityLabel={DRAFT_ROLE_LABELS[field.role]}
+                  />
+                ) : (
+                  <Input
+                    testID={`${testID}-field-${field.key}`}
+                    value={edits[field.key] ?? ""}
+                    onChangeText={(value: string) => setEdits({ ...edits, [field.key]: value })}
+                    accessibilityLabel={DRAFT_ROLE_LABELS[field.role]}
+                  />
+                )}
+              </View>
+            ))}
+          </View>
+        ) : (
+          <View testID={`${testID}-preview`} className="gap-2">
+            {headerFields.map((field) => (
+              <View key={field.key} className="flex-row gap-2">
+                <Text className={cn(caption, "w-16")} style={[sizeStyle(caption), textStyle("muted", scheme)]}>
+                  {DRAFT_ROLE_LABELS[field.role]}
+                </Text>
+                <Text className={cn(small, "min-w-0 flex-1")} style={[sizeStyle(small), textStyle("foreground", scheme)]}>
+                  {field.value}
+                </Text>
+              </View>
+            ))}
+            {bodyField ? (
+              <Text numberOfLines={12} className={body} style={[sizeStyle(body), textStyle("foreground", scheme)]}>
+                {bodyField.value}
+              </Text>
+            ) : null}
+          </View>
+        )
+      ) : summary ? (
         <Text
           testID={`${testID}-args`}
           numberOfLines={3}
@@ -123,11 +252,11 @@ function ToolCardBase({
         {allowEdit ? (
           <CardButton
             testID={`${testID}-edit`}
-            label={editLabel}
-            accessibilityLabel={`${editLabel} ${toolName}`}
+            label={edits ? "Cancel edit" : editLabel}
+            accessibilityLabel={`${edits ? "Cancel edit" : editLabel} ${toolName}`}
             variant="secondary"
             disabled={off}
-            onPress={() => onDecide?.("edit")}
+            onPress={onEdit}
           />
         ) : null}
         <CardButton
@@ -136,7 +265,7 @@ function ToolCardBase({
           accessibilityLabel={`${approveLabel} ${toolName}`}
           variant="primary"
           disabled={off}
-          onPress={() => onDecide?.("approve")}
+          onPress={onApprove}
         />
       </View>
     </View>
@@ -154,9 +283,11 @@ export function ToolApprovalCard(props: ToolApprovalCardProps) {
 
 export type ToolDraftCardProps = ToolApprovalCardProps & {
   editLabel?: string;
+  /** The draft fields. Shows them as a preview and, under Edit, as inputs. Without them Edit reports `"edit"`. */
+  fields?: readonly DraftField[];
 };
 
 /** As `ToolApprovalCard`, plus an Edit button that reports `"edit"`, for a draft the reader may change first. */
 export function ToolDraftCard({ testID = "tool-draft-card", ...props }: ToolDraftCardProps) {
-  return <ToolCardBase {...props} testID={testID} allowEdit heading="Draft for review" />;
+  return <ToolCardBase {...props} testID={testID} allowEdit heading="Draft for review" metaNote="Nothing is sent until you press Send" />;
 }

package/src/examples/AiChatGallery.tsx

@@ -39,10 +39,17 @@ import {
   SourcesTrigger,
   Suggestion,
   Suggestions,
+  SubagentResultCard,
+  SubagentRunCard,
+  ToolApprovalCard,
+  ToolDraftCard,
   formatElapsed,
   useStreamingDisclosure,
   type AttachmentData,
   type ChatStatus,
+  type DraftEdit,
+  type DraftField,
+  type SubagentStatus,
 } from "../ai";
 
 const SUGGESTIONS = [
@@ -73,6 +80,68 @@ const STREAMING_REASONING =
  * reasoning and trace, reply, code, sources and actions), a second user
  * message, and an assistant message that is still working while `streaming`.
  */
+const DRAFT_FIELDS: DraftField[] = [
+  { key: "to", role: "to", value: "team@example.com" },
+  { key: "subject", role: "subject", value: "Weekly plan" },
+  { key: "body", role: "body", value: "Here is the plan for next week." },
+];
+
+const RUN_STATUSES: SubagentStatus[] = ["queued", "running", "done", "failed", "cancelled", "timed_out"];
+
+/** Tool approval, draft and subagent cards, with testIDs for E2E. */
+export function AiCardSamples() {
+  const [decision, setDecision] = useState("none");
+  const [cancelled, setCancelled] = useState(false);
+  const decide = (name: string) => (choice: string, edits?: DraftEdit[]) =>
+    setDecision(`${name}:${choice}${edits ? `:${JSON.stringify(edits)}` : ""}`);
+  return (
+    <>
+      <ResponseText>{`Last decision: ${decision}`}</ResponseText>
+      <ToolApprovalCard
+        testID="gallery-approval"
+        toolName="create_task"
+        args={{ title: "Review plan" }}
+        server="tasks"
+        routineMode
+        expiresLabel="tomorrow"
+        target="Project board"
+        onDecide={decide("approval")}
+      />
+      <ToolDraftCard
+        testID="gallery-draft"
+        toolName="send_message"
+        fields={DRAFT_FIELDS}
+        server="mail"
+        expiresLabel="in 2 hours"
+        approveLabel="Send"
+        denyLabel="Discard"
+        onDecide={decide("draft")}
+      />
+      {RUN_STATUSES.map((status) => (
+        <SubagentRunCard
+          key={status}
+          testID={`gallery-run-${status}`}
+          title="Research"
+          status={status}
+          elapsedSeconds={65}
+          statusLine={status === "running" ? "Step 2 of 4" : undefined}
+          error={status === "failed" ? "The source could not be reached." : undefined}
+          onCancel={() => setCancelled(true)}
+        />
+      ))}
+      <ResponseText>{`Cancelled: ${cancelled ? "yes" : "no"}`}</ResponseText>
+      <SubagentResultCard
+        testID="gallery-result"
+        title="Research"
+        summary="Three sources found."
+        approvalPending
+        approvalPendingIn="Planner"
+        handoffs={[{ toolName: "create_task", server: "tasks", argsSummary: '{"title":"Review plan"}' }]}
+      />
+    </>
+  );
+}
+
 export function AiChatSamples({ streaming = true }: { streaming?: boolean }) {
   const [feedback, setFeedback] = useState<"like" | "dislike" | null>(null);
   const searchFold = useStreamingDisclosure(streaming);
@@ -164,6 +233,7 @@ export function AiChatSamples({ streaming = true }: { streaming?: boolean }) {
           )}
         </MessageContent>
       </Message>
+      <AiCardSamples />
     </>
   );
 }

package/src/primitives/select-host.tsx

@@ -0,0 +1,55 @@
+import * as SelectPrimitive from "@rn-primitives/select";
+import * as React from "react";
+import { Modal, Platform, View } from "react-native";
+import { FullWindowOverlay } from "react-native-screens";
+import { useReduceMotion } from "../useReduceMotion";
+
+/**
+ * Where `SelectContent` draws its options.
+ *
+ * - Android: a transparent RN `Modal` with a full-size `box-none` host, as
+ *   `DropdownMenuContent` and `OverlayModal` use. The Modal is its own window,
+ *   so options sit above an absolute tab bar or glass layer. `SelectContent`
+ *   renders this host without a Portal, because a Modal inside a portal mounts
+ *   empty. With no Portal there is no `open` gate from the primitive, so the
+ *   host mounts the Modal only while the Select is open. Android back closes it.
+ * - iOS: `FullWindowOverlay`, which sits above native navigation chrome.
+ * - Web: no wrapper. Radix owns the layering.
+ *
+ * `Platform.OS` is read at render, not at import, so a test can switch it.
+ */
+export function SelectHost({ children }: { children: React.ReactNode }) {
+  const { open, onOpenChange, setTriggerPosition, setContentLayout } =
+    SelectPrimitive.useRootContext();
+  const reduceMotion = useReduceMotion();
+
+  if (Platform.OS === "ios") {
+    return <FullWindowOverlay>{children}</FullWindowOverlay>;
+  }
+  if (Platform.OS !== "android") {
+    return <>{children}</>;
+  }
+  if (!open) {
+    return null;
+  }
+
+  const close = () => {
+    setTriggerPosition(null);
+    setContentLayout(null);
+    onOpenChange(false);
+  };
+
+  return (
+    <Modal
+      visible
+      transparent
+      statusBarTranslucent
+      animationType={reduceMotion ? "none" : "fade"}
+      onRequestClose={close}
+    >
+      <View style={{ flex: 1 }} pointerEvents="box-none" testID="SelectContent-host">
+        {children}
+      </View>
+    </Modal>
+  );
+}

package/src/primitives/select.tsx

@@ -5,21 +5,20 @@ import { IconCheck, IconChevronDown, IconChevronUp } from "@tabler/icons-react-n
 import * as React from "react";
 import { Platform, ScrollView, StyleSheet, Text, View } from "react-native";
 import { FadeIn, FadeOut } from "react-native-reanimated";
-import { FullWindowOverlay as RNFullWindowOverlay } from "react-native-screens";
 import { NativeOnlyAnimatedView } from "./native-only-animated-view";
+import { SelectHost } from "./select-host";
 import { TextClassContext } from "./text";
 import { LiquidGlass } from "../LiquidGlass";
 import { cn } from "../cn";
 import { textStyle, typeStyle } from "../controlStyles";
 import { tokens } from "../tokens";
 import { useScheme } from "../useScheme";
+import { useLargerText } from "../theme";
 
 type Option = SelectPrimitive.Option;
 
 const Select = SelectPrimitive.Root;
 const SelectGroup = SelectPrimitive.Group;
-const FullWindowOverlay =
-  Platform.OS === "ios" ? RNFullWindowOverlay : React.Fragment;
 
 type SelectValueProps = React.ComponentPropsWithoutRef<
   typeof SelectPrimitive.Value
@@ -85,48 +84,60 @@ const SelectContent = React.forwardRef<
   React.ElementRef<typeof SelectPrimitive.Content>,
   SelectContentProps
 >(({ className, children, position = "popper", portalHost, ...props }, ref) => {
-  return (
-    <SelectPrimitive.Portal hostName={portalHost}>
-      <FullWindowOverlay>
-        <SelectPrimitive.Overlay
-          style={Platform.select({ native: StyleSheet.absoluteFill })}
+  const overlayFill = Platform.select({ native: StyleSheet.absoluteFill });
+  const content = (
+    <SelectPrimitive.Overlay style={overlayFill}>
+      <TextClassContext.Provider value="text-popover-foreground">
+        <NativeOnlyAnimatedView
+          entering={FadeIn}
+          exiting={FadeOut}
+          className="z-50"
+          // Content is absolutely positioned, so a bare wrapper has zero height
+          // and UI tests drop its children as invisible. Fill the overlay and
+          // let touches fall through to it.
+          style={overlayFill}
+          pointerEvents={Platform.select({ native: "box-none" })}
         >
-          <TextClassContext.Provider value="text-popover-foreground">
-            <NativeOnlyAnimatedView
-              entering={FadeIn}
-              exiting={FadeOut}
-              className="z-50"
+          <SelectPrimitive.Content
+            ref={ref}
+            position={position}
+            className={cn(
+              "z-50 min-w-[8rem] rounded-lg",
+              Platform.select({
+                native: "p-1",
+                web: "max-h-52 overflow-hidden",
+              }),
+              className,
+            )}
+            {...props}
+          >
+            <LiquidGlass
+              pointerEvents="none"
+              elevated={false}
+              className="absolute inset-0 rounded-lg"
+            />
+            <SelectScrollUpButton />
+            <SelectPrimitive.Viewport
+              className={cn("p-1", position === "popper" && "w-full")}
             >
-              <SelectPrimitive.Content
-                ref={ref}
-                position={position}
-                className={cn(
-                  "z-50 min-w-[8rem] rounded-lg",
-                  Platform.select({
-                    native: "p-1",
-                    web: "max-h-52 overflow-hidden",
-                  }),
-                  className,
-                )}
-                {...props}
-              >
-                <LiquidGlass
-                  pointerEvents="none"
-                  elevated={false}
-                  className="absolute inset-0 rounded-lg"
-                />
-                <SelectScrollUpButton />
-                <SelectPrimitive.Viewport
-                  className={cn("p-1", position === "popper" && "w-full")}
-                >
-                  {children}
-                </SelectPrimitive.Viewport>
-                <SelectScrollDownButton />
-              </SelectPrimitive.Content>
-            </NativeOnlyAnimatedView>
-          </TextClassContext.Provider>
-        </SelectPrimitive.Overlay>
-      </FullWindowOverlay>
+              {children}
+            </SelectPrimitive.Viewport>
+            <SelectScrollDownButton />
+          </SelectPrimitive.Content>
+        </NativeOnlyAnimatedView>
+      </TextClassContext.Provider>
+    </SelectPrimitive.Overlay>
+  );
+
+  // Android: no Portal. A Modal inside a portal mounts empty, so `SelectHost`
+  // renders the Modal directly and gates it on `open`. iOS and web keep the
+  // Portal; `SelectHost` adds the full-window layer on iOS.
+  if (Platform.OS === "android") {
+    return <SelectHost>{content}</SelectHost>;
+  }
+  return (
+    <SelectPrimitive.Portal hostName={portalHost}>
+      <SelectHost>{content}</SelectHost>
     </SelectPrimitive.Portal>
   );
 });
@@ -166,12 +177,15 @@ const SelectItem = React.forwardRef<
   SelectItemProps
 >(({ className, disabled, ...props }, ref) => {
   const scheme = useScheme();
+  const largerText = useLargerText();
   return (
     <SelectPrimitive.Item
       ref={ref}
       disabled={disabled}
       className={cn(
-        "relative flex-row items-center gap-2 rounded-sm py-3 pl-2 pr-8 active:opacity-70",
+        // 44 high (56 with larger text) so a row is a full touch target.
+        "relative min-h-[44px] flex-row items-center gap-2 rounded-sm py-3 pl-2 pr-8 active:opacity-70",
+        largerText && "min-h-[56px]",
         disabled && "opacity-50",
         className,
       )}