@lotics/ui 14.3.1 → 15.1.0

package/src/agent_run.tsx

@@ -2,6 +2,7 @@ import { useState, type ReactNode } from "react";
 import { StyleSheet, View } from "react-native";
 import { colors } from "./colors";
 import { Text } from "./text";
+import { Button } from "./button";
 import { Icon, type IconName } from "./icon";
 import { Markdown } from "./markdown";
 import { JsonPanel, stringifyData } from "./json_panel";
@@ -14,7 +15,24 @@ import { useLoticsLocale, type LoticsLocale } from "./locale";
 // The render model comes STRAIGHT from ai-sdk `UIMessage.parts` — no bespoke
 // transcript type. `agent_transform` is the one place that folds parts into the
 // timeline; this file is the renderer.
-import { toSegments, anyRunning, type AgentUIPart, type AgentStep } from "./agent_transform";
+import { toSegments, anyRunning, type AgentUIPart, type AgentStep, type AgentStepStatus } from "./agent_transform";
+
+/** A resolved tool call as a `labelForCall` sees it: the RAW tool name, the
+ *  input it was invoked with, and its settle state. Richer than a name-only map,
+ *  so a caller can phrase a call by what it targets or by whether it's awaiting. */
+export interface AgentToolCall {
+  toolName: string;
+  input: unknown;
+  state: AgentStepStatus;
+}
+
+/** A settled tool call as `renderToolOutput` sees it — the output stands in for
+ *  the state (only an output-carrying step reaches the renderer). */
+export interface AgentToolOutput {
+  toolName: string;
+  input: unknown;
+  output: unknown;
+}
 
 export interface AgentRunProps {
   /** The agent message's ai-sdk `parts` — the ordered transcript, rendered in
@@ -30,10 +48,20 @@ export interface AgentRunProps {
    *  it renders as a terminal danger row under the transcript. A per-tool failure
    *  is different — it rides in that tool's own `output-error` part. */
   error?: string;
-  /** Localize / override a TOOL step's display label by its raw tool name
-   *  (`update_records` → "Đang cập nhật dữ liệu"). Return `undefined` to fall
+  /** Localize / override a TOOL step's display label from the CALL — its raw
+   *  name, input, and state (`update_records` → "Đang cập nhật dữ liệu"; or a
+   *  distinct phrasing while `state === "awaiting"`). Return `undefined` to fall
    *  back to the built-in label. */
-  labelForTool?: (toolName: string) => string | undefined;
+  labelForCall?: (call: AgentToolCall) => string | undefined;
+  /** Replace the DEFAULT `JsonPanel` output rendering of an expanded tool step —
+   *  the only render escape hatch. Called only when a step carrying an output is
+   *  actually EXPANDED; a non-`undefined` return replaces the output panel (an
+   *  image preview, a table), while `undefined` keeps the default panel. Input +
+   *  error rendering are unaffected. */
+  renderToolOutput?: (call: AgentToolOutput) => ReactNode | undefined;
+  /** When the run ended on a terminal `error`, render a retry action under that
+   *  danger row. Omit it and the error row renders exactly as before. */
+  onRetry?: () => void;
   /** Localized "{n} steps" suffix on a collapsed activity group (the kit is
    *  locale-neutral). Default `"{n} steps"`. */
   stepsLabel?: (n: number) => string;
@@ -42,7 +70,7 @@ export interface AgentRunProps {
 
 // ── Tool → display meta ───────────────────────────────────────────────────────
 // The bounded set of platform tools an app agent can call. English by default
-// (the kit is locale-neutral; apps localize via `labelForTool`). A tool the map
+// (the kit is locale-neutral; apps localize via `labelForCall`). A tool the map
 // doesn't know falls back to a prettified name + a neutral icon.
 const TOOL_META: Record<string, { label: string; icon: IconName }> = {
   query_records: { label: "Searching records", icon: "search" },
@@ -65,23 +93,23 @@ function prettifyToolName(name: string): string {
  *  then the built-in map, then a prettified fallback. Exported so other agent
  *  surfaces (e.g. `AgentProgress`) render the same labels. */
 export function resolveToolMeta(
-  toolName: string,
-  labelForTool?: (toolName: string) => string | undefined,
+  call: AgentToolCall,
+  labelForCall?: (call: AgentToolCall) => string | undefined,
 ): { label: string; icon: IconName } {
   const def =
-    TOOL_META[toolName] ??
-    (toolName.startsWith("generate_") && toolName.endsWith("_from_template")
+    TOOL_META[call.toolName] ??
+    (call.toolName.startsWith("generate_") && call.toolName.endsWith("_from_template")
       ? { label: "Generating document", icon: "file-text" as IconName }
       : undefined);
   return {
-    label: labelForTool?.(toolName) ?? def?.label ?? prettifyToolName(toolName),
+    label: labelForCall?.(call) ?? def?.label ?? prettifyToolName(call.toolName),
     icon: def?.icon ?? "list",
   };
 }
 
-/** Resolve a tool step's display label from its raw tool name. */
-function stepLabel(s: AgentStep, labelForTool?: (toolName: string) => string | undefined): string {
-  return resolveToolMeta(s.toolName, labelForTool).label;
+/** Resolve a tool step's display label from its call. */
+function stepLabel(s: AgentStep, labelForCall?: (call: AgentToolCall) => string | undefined): string {
+  return resolveToolMeta({ toolName: s.toolName, input: s.input, state: s.status }, labelForCall).label;
 }
 
 const INK = colors.zinc[700];
@@ -96,7 +124,8 @@ const INK = colors.zinc[700];
  * Pair with `Composer` + `ChangeReview`.
  */
 export function AgentRun(props: AgentRunProps) {
-  const { parts, labelForTool, stepsLabel = (n) => `${n} steps`, accessibilityLabel } = props;
+  const { parts, labelForCall, renderToolOutput, onRetry, stepsLabel = (n) => `${n} steps`, accessibilityLabel } = props;
+  const locale = useLoticsLocale();
   const segments = toSegments(parts);
   const state = props.state ?? (anyRunning(segments) ? "streaming" : "done");
   const streaming = state === "streaming";
@@ -125,23 +154,32 @@ export function AgentRun(props: AgentRunProps) {
             active={streaming && i === lastIndex}
             expanded={!!expanded[seg.id]}
             onToggle={() => toggle(seg.id)}
-            labelForTool={labelForTool}
+            labelForCall={labelForCall}
+            renderToolOutput={renderToolOutput}
             stepsLabel={stepsLabel}
           />
         );
       })}
       {/* A run-level BREAKING error terminates the feed with a danger row. It lives
-          outside `parts` (the stream failed), so the caller passes it explicitly. */}
+          outside `parts` (the stream failed), so the caller passes it explicitly.
+          A retry action rides UNDER it when the caller can restart the run. */}
       {props.error ? (
-        <View style={styles.row}>
-          <View style={styles.dotCol}>
-            <Icon name="circle-alert" size={17} color={colors.red[500]} />
-          </View>
-          <View style={styles.rowBody}>
-            <Text size="sm" color="danger">
-              {props.error}
-            </Text>
+        <View style={{ gap: 8 }}>
+          <View style={styles.row}>
+            <View style={styles.dotCol}>
+              <Icon name="circle-alert" size={17} color={colors.red[500]} />
+            </View>
+            <View style={styles.rowBody}>
+              <Text size="sm" color="danger">
+                {props.error}
+              </Text>
+            </View>
           </View>
+          {onRetry ? (
+            <View style={styles.retry}>
+              <Button title={locale.agentRun.retry} color="secondary" icon="rotate-ccw" alignSelf="flex-start" onPress={onRetry} />
+            </View>
+          ) : null}
         </View>
       ) : null}
     </View>
@@ -179,24 +217,37 @@ function ActivityRow(props: {
   return <View style={styles.row}>{inner}</View>;
 }
 
-function StepBody({ label }: { label: string }) {
-  return <Text size="sm">{label}</Text>;
+// The step label, plus a muted "· {awaiting}" annotation when the call is parked
+// on a human decision (its amber dot already signals the state; the word names it).
+function StepBody({ label, awaiting }: { label: string; awaiting?: string }) {
+  return (
+    <Text size="sm">
+      {label}
+      {awaiting ? (
+        <Text size="sm" color="muted">
+          {"  ·  " + awaiting}
+        </Text>
+      ) : null}
+    </Text>
+  );
 }
 
 // The on-demand reveal for a tool step: Input / Output / Error panels auto-built
 // from the carried I/O; nothing if there's none. Raw I/O stays OUT of the row — only
-// shown here, on demand. Panel titles come from the locale.
-function stepDetail(s: AgentStep, labels: LoticsLocale["agentRun"]): ReactNode {
+// shown here, on demand. Panel titles come from the locale. A caller's
+// `renderToolOutput` replaces the OUTPUT panel (input + error stay auto-built).
+function stepDetail(s: AgentStep, labels: LoticsLocale["agentRun"], renderToolOutput?: AgentRunProps["renderToolOutput"]): ReactNode {
   const hasInput = s.input !== undefined;
   const hasOutput = s.output !== undefined;
   if (!hasInput && !hasOutput && !s.errorText) return null;
+  const customOutput = hasOutput && renderToolOutput ? renderToolOutput({ toolName: s.toolName, input: s.input, output: s.output }) : undefined;
   return (
     <View style={{ gap: 8 }}>
       {hasInput ? <JsonPanel title={labels.input} value={stringifyData(s.input)} /> : null}
       {s.errorText ? (
         <JsonPanel title={labels.error} value={s.errorText} />
       ) : hasOutput ? (
-        <JsonPanel title={labels.output} value={stringifyData(s.output)} />
+        customOutput !== undefined ? customOutput : <JsonPanel title={labels.output} value={stringifyData(s.output)} />
       ) : null}
     </View>
   );
@@ -205,24 +256,28 @@ function stepDetail(s: AgentStep, labels: LoticsLocale["agentRun"]): ReactNode {
 // A settled step row. When the step carries I/O (or an error) it EXPANDS IN PLACE on
 // press — the panels roll out under the row (same disclosure pattern as "Thinking"),
 // never a popover — so an errored call reads like any other step until you open it.
-function StepRow({ s, label }: { s: AgentStep; label: string }) {
+// An `awaiting` call wears the amber dot + an "awaiting" annotation, like an error.
+function StepRow({ s, label, renderToolOutput }: { s: AgentStep; label: string; renderToolOutput?: AgentRunProps["renderToolOutput"] }) {
   const locale = useLoticsLocale();
   const [open, setOpen] = useState(false);
-  const detail = stepDetail(s, locale.agentRun);
-  const marker: StepStatus = s.status === "error" ? "warning" : "done";
-  if (!detail) {
+  // Pressability is decided by a cheap carried-I/O check; the detail (and any
+  // caller `renderToolOutput`) is built only once the row is actually opened.
+  const hasDetail = s.input !== undefined || s.output !== undefined || !!s.errorText;
+  const marker: StepStatus = s.status === "error" || s.status === "awaiting" ? "warning" : "done";
+  const awaiting = s.status === "awaiting" ? locale.agentRun.awaiting : undefined;
+  if (!hasDetail) {
     return (
       <ActivityRow markerStatus={marker}>
-        <StepBody label={label} />
+        <StepBody label={label} awaiting={awaiting} />
       </ActivityRow>
     );
   }
   return (
     <View>
       <ActivityRow markerStatus={marker} onPress={() => setOpen((o) => !o)} accessibilityLabel={label} trailing={chevron(open ? "up" : "down")}>
-        <StepBody label={label} />
+        <StepBody label={label} awaiting={awaiting} />
       </ActivityRow>
-      {open ? <View style={styles.rowDetail}>{detail}</View> : null}
+      {open ? <View style={styles.rowDetail}>{stepDetail(s, locale.agentRun, renderToolOutput)}</View> : null}
     </View>
   );
 }
@@ -274,17 +329,29 @@ function ToolGroup(props: {
   active: boolean;
   expanded: boolean;
   onToggle: () => void;
-  labelForTool?: (toolName: string) => string | undefined;
+  labelForCall?: (call: AgentToolCall) => string | undefined;
+  renderToolOutput?: AgentRunProps["renderToolOutput"];
   stepsLabel: (n: number) => string;
 }) {
-  const { steps, active, expanded, onToggle, labelForTool, stepsLabel } = props;
-  const resolve = (s: AgentStep) => stepLabel(s, labelForTool);
+  const { steps, active, expanded, onToggle, labelForCall, renderToolOutput, stepsLabel } = props;
+  const locale = useLoticsLocale();
+  const resolve = (s: AgentStep) => stepLabel(s, labelForCall);
 
   // ACTIVE — one pulsing row whose label swaps in place as each call fires (the
   // label is keyed by the current step's id, so a new call rises + fades into the
-  // SAME row instead of stacking a new dot).
+  // SAME row instead of stacking a new dot). BUT a call parked on a human decision
+  // (`awaiting`) is NOT working — it settles to the amber, non-pulsing awaiting row.
   if (active) {
     const current = steps[steps.length - 1];
+    if (current.status === "awaiting") {
+      return (
+        <View style={styles.group}>
+          <ActivityRow markerStatus="warning">
+            <StepBody label={resolve(current)} awaiting={locale.agentRun.awaiting} />
+          </ActivityRow>
+        </View>
+      );
+    }
     return (
       <View style={styles.group}>
         <ActivityRow markerStatus="current" live>
@@ -297,6 +364,7 @@ function ToolGroup(props: {
   }
 
   const errored = steps.some((s) => s.status === "error");
+  const awaiting = steps.some((s) => s.status === "awaiting");
   const final = steps[steps.length - 1];
   const expandable = steps.length > 1;
 
@@ -304,7 +372,7 @@ function ToolGroup(props: {
   if (!expandable) {
     return (
       <View style={styles.group}>
-        <StepRow s={final} label={resolve(final)} />
+        <StepRow s={final} label={resolve(final)} renderToolOutput={renderToolOutput} />
       </View>
     );
   }
@@ -317,7 +385,7 @@ function ToolGroup(props: {
   return (
     <View style={styles.group}>
       <ActivityRow
-        markerStatus={errored ? "warning" : "complete"}
+        markerStatus={errored || awaiting ? "warning" : "complete"}
         onPress={onToggle}
         accessibilityLabel={`${resolve(final)} — ${stepsLabel(steps.length)}`}
         trailing={chevron(expanded ? "up" : "down")}
@@ -327,7 +395,7 @@ function ToolGroup(props: {
       {expanded
         ? steps.map((s) => (
             <AnimationFadeIn key={s.id} translateY={4}>
-              <StepRow s={s} label={resolve(s)} />
+              <StepRow s={s} label={resolve(s)} renderToolOutput={renderToolOutput} />
             </AnimationFadeIn>
           ))
         : null}
@@ -360,4 +428,7 @@ const styles = StyleSheet.create({
   reasoning: { paddingLeft: 28, paddingBottom: 4 },
   // A step's expanded I/O panels — same left edge as the reasoning body.
   rowDetail: { paddingLeft: 28, paddingBottom: 6, paddingTop: 2 },
+  // The retry action under the terminal error — aligned to the message body
+  // (past the dot column + its gap), so it reads as a response to that row.
+  retry: { paddingLeft: 28 },
 });

package/src/agent_transform.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect } from "vitest";
+import { toSegments, anyRunning, lastRunningStep, type AgentUIPart, type AgentSegment, type AgentStep } from "./agent_transform";
+
+// RN-free logic test for the parts → timeline fold. The renderer (agent_run.tsx)
+// is verified visually in the gallery; the mapping — ai's 7-state tool machine to
+// the feed's 4 states, plus grouping — is unit-tested here. Fixtures are the ai-sdk
+// `dynamic-tool` part shape (contextually typed as `AgentUIPart`, so each concrete
+// `state` discriminates to the right member — no casts).
+
+function groups(parts: AgentUIPart[]): Extract<AgentSegment, { kind: "group" }>[] {
+  return toSegments(parts).filter((s): s is Extract<AgentSegment, { kind: "group" }> => s.kind === "group");
+}
+
+function onlyStep(parts: AgentUIPart[]): AgentStep {
+  const [group, ...rest] = groups(parts);
+  expect(rest).toHaveLength(0);
+  expect(group.steps).toHaveLength(1);
+  return group.steps[0];
+}
+
+describe("agent_transform — tool state mapping", () => {
+  it("input-streaming → running", () => {
+    expect(onlyStep([{ type: "dynamic-tool", toolName: "update_records", toolCallId: "t", state: "input-streaming", input: {} }]).status).toBe("running");
+  });
+
+  it("input-available → running", () => {
+    expect(onlyStep([{ type: "dynamic-tool", toolName: "update_records", toolCallId: "t", state: "input-available", input: {} }]).status).toBe("running");
+  });
+
+  it("approval-requested → awaiting (parked on a human decision)", () => {
+    const step = onlyStep([{ type: "dynamic-tool", toolName: "delete_records", toolCallId: "t", state: "approval-requested", input: { table: "Containers" }, approval: { id: "a1" } }]);
+    expect(step.status).toBe("awaiting");
+    // The input still rides along for the on-demand peek.
+    expect(step.input).toEqual({ table: "Containers" });
+  });
+
+  it("approval-responded → running (the decision is in, work resumes)", () => {
+    expect(onlyStep([{ type: "dynamic-tool", toolName: "delete_records", toolCallId: "t", state: "approval-responded", input: {}, approval: { id: "a1", approved: true } }]).status).toBe("running");
+  });
+
+  it("output-available → done, carrying the output", () => {
+    const step = onlyStep([{ type: "dynamic-tool", toolName: "query_records", toolCallId: "t", state: "output-available", input: { q: 1 }, output: { rows: 3 } }]);
+    expect(step.status).toBe("done");
+    expect(step.output).toEqual({ rows: 3 });
+  });
+
+  it("output-error → error, carrying errorText", () => {
+    const step = onlyStep([{ type: "dynamic-tool", toolName: "query_records", toolCallId: "t", state: "output-error", input: {}, errorText: "Unknown field" }]);
+    expect(step.status).toBe("error");
+    expect(step.errorText).toBe("Unknown field");
+  });
+
+  it("output-denied → error, with the denial reason as the error text", () => {
+    const step = onlyStep([{ type: "dynamic-tool", toolName: "delete_records", toolCallId: "t", state: "output-denied", input: {}, approval: { id: "a1", approved: false, reason: "Delete not permitted" } }]);
+    expect(step.status).toBe("error");
+    expect(step.errorText).toBe("Delete not permitted");
+  });
+
+  it("output-denied without a reason → error with no error text", () => {
+    const step = onlyStep([{ type: "dynamic-tool", toolName: "delete_records", toolCallId: "t", state: "output-denied", input: {}, approval: { id: "a1", approved: false } }]);
+    expect(step.status).toBe("error");
+    expect(step.errorText).toBeUndefined();
+  });
+});
+
+describe("agent_transform — streaming signals", () => {
+  it("anyRunning is true while a call runs, false once every call has settled", () => {
+    const running = toSegments([{ type: "dynamic-tool", toolName: "query_records", toolCallId: "t", state: "input-available", input: {} }]);
+    expect(anyRunning(running)).toBe(true);
+
+    const settled = toSegments([{ type: "dynamic-tool", toolName: "query_records", toolCallId: "t", state: "output-available", input: {}, output: {} }]);
+    expect(anyRunning(settled)).toBe(false);
+  });
+
+  it("an awaiting call is NOT running — it's parked, so the feed never pulses it", () => {
+    const parked = toSegments([{ type: "dynamic-tool", toolName: "delete_records", toolCallId: "t", state: "approval-requested", input: {}, approval: { id: "a1" } }]);
+    expect(anyRunning(parked)).toBe(false);
+    expect(lastRunningStep(parked)).toBeUndefined();
+  });
+});
+
+describe("agent_transform — grouping", () => {
+  it("folds consecutive tool parts into ONE group, split by prose", () => {
+    const parts: AgentUIPart[] = [
+      { type: "text", text: "First" },
+      { type: "dynamic-tool", toolName: "query_records", toolCallId: "a", state: "output-available", input: {}, output: {} },
+      { type: "dynamic-tool", toolName: "query_records", toolCallId: "b", state: "output-available", input: {}, output: {} },
+      { type: "text", text: "Then" },
+      { type: "dynamic-tool", toolName: "delete_records", toolCallId: "c", state: "approval-requested", input: {}, approval: { id: "a1" } },
+    ];
+    expect(toSegments(parts).map((s) => s.kind)).toEqual(["text", "group", "text", "group"]);
+    const [first, second] = groups(parts);
+    expect(first.steps.map((s) => s.id)).toEqual(["a", "b"]);
+    expect(second.steps.map((s) => s.status)).toEqual(["awaiting"]);
+  });
+});

package/src/agent_transform.ts

@@ -10,8 +10,11 @@ import type { UIMessagePart, UIDataTypes, UITools } from "ai";
 /** An ai-sdk message part, tool-set-agnostic (we only read `type` + a few fields). */
 export type AgentUIPart = UIMessagePart<UIDataTypes, UITools>;
 
-/** A tool step's settle state, collapsed from ai's 7-state tool machine. */
-export type AgentStepStatus = "running" | "done" | "error";
+/** A tool step's settle state, folded from ai's 7-state tool machine.
+ *  `awaiting` = the call is parked on a human decision (`approval-requested`) —
+ *  first-class, distinct from `running` (working) so the feed never pulses a
+ *  parked call. */
+export type AgentStepStatus = "running" | "awaiting" | "done" | "error";
 
 /** One tool call, reduced to what the feed shows. `toolName` is the RAW name — the
  *  renderer maps it to a human label + icon (`resolveToolMeta`). */
@@ -38,11 +41,15 @@ function isToolPart(part: AgentUIPart): part is Extract<AgentUIPart, { toolCallI
   return part.type === "dynamic-tool" || part.type.startsWith("tool-");
 }
 
-// ai's tool state machine → the feed's 3 states. Approval-pending/responded read as
-// "running" (a read-only feed has no approval affordance); denied reads as an error.
+// ai's 7-state tool machine → the feed's 4 states. `approval-requested` is
+// first-class `awaiting` (the call sits parked on a human decision);
+// `approval-responded` reads `running` until the resolved output arrives —
+// `output-available` on approve, `output-denied` (an error carrying the denial
+// reason) on deny. `input-streaming`/`input-available` are `running`.
 function toStatus(state: string): AgentStepStatus {
   if (state === "output-available") return "done";
   if (state === "output-error" || state === "output-denied") return "error";
+  if (state === "approval-requested") return "awaiting";
   return "running";
 }
 
@@ -53,7 +60,12 @@ function toStep(part: Extract<AgentUIPart, { toolCallId: string }>): AgentStep {
     status: toStatus(part.state),
     input: part.input,
     output: part.state === "output-available" ? part.output : undefined,
-    errorText: part.state === "output-error" ? part.errorText : undefined,
+    errorText:
+      part.state === "output-error"
+        ? part.errorText
+        : part.state === "output-denied"
+          ? part.approval.reason
+          : undefined,
   };
 }
 

package/src/approval_prompt.tsx

@@ -0,0 +1,70 @@
+import { type ReactNode } from "react";
+import { StyleSheet, View } from "react-native";
+import { colors } from "./colors";
+import { Text } from "./text";
+import { Button } from "./button";
+import { Icon } from "./icon";
+import { useLoticsLocale } from "./locale";
+
+export interface ApprovalPromptProps {
+  /** Confirm the gated action — the agent proceeds. */
+  onApprove: () => void;
+  /** Reject the gated action — the agent does not proceed. */
+  onDeny: () => void;
+  /** Per-instance override of the prompt line (e.g. a browser-specific
+   *  phrasing); defaults to the `approvalPrompt` locale slice's `message`. */
+  message?: string;
+  /** Optional detail rendered between the message and the actions — e.g. a
+   *  summary of the input the agent is asking to run. */
+  children?: ReactNode;
+}
+
+/**
+ * The prompt that ANSWERS an agent's approval-gated action — the interactive
+ * counterpart to `AgentRun`'s read-only amber `awaiting` row. A warning icon +
+ * message on a bordered card, with Deny (secondary) + Approve (primary)
+ * right-aligned; the `children` slot renders an input summary between the two.
+ * Every string resolves prop → the `approvalPrompt` locale slice → English.
+ * Typically slotted where the composer sits while the run is parked.
+ */
+export function ApprovalPrompt(props: ApprovalPromptProps) {
+  const { onApprove, onDeny, message, children } = props;
+  const labels = useLoticsLocale().approvalPrompt;
+
+  return (
+    <View style={styles.container}>
+      <View style={styles.content}>
+        <Icon name="shield-alert" size={20} color={colors.orange[600]} />
+        <Text size="sm" style={{ flex: 1 }}>
+          {message ?? labels.message}
+        </Text>
+      </View>
+      {children}
+      <View style={styles.actions}>
+        <Button title={labels.deny} color="secondary" onPress={onDeny} />
+        <Button title={labels.approve} color="primary" onPress={onApprove} />
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    padding: 12,
+    borderRadius: 16,
+    borderWidth: 2,
+    borderColor: colors.border,
+    backgroundColor: colors.background,
+    gap: 12,
+  },
+  content: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 8,
+  },
+  actions: {
+    flexDirection: "row",
+    justifyContent: "flex-end",
+    gap: 8,
+  },
+});

package/src/dom_region.ts

@@ -0,0 +1,14 @@
+import type { RegionRef } from "./file_intake";
+
+/**
+ * Native stand-in for the region → DOM-node resolver.
+ *
+ * There is no DOM on React Native, so there is no node to resolve — the drag
+ * and focus-routing paths this backs are web-only. The file exists purely as
+ * the typecheck-resolution base for the `.web` variant (the `.web` file is the
+ * only importer at runtime; Metro never reaches this on native, but the shared
+ * signature lives here).
+ */
+export function resolveRegionNode(_region: RegionRef | undefined): HTMLElement | null {
+  return null;
+}

package/src/dom_region.web.ts

@@ -0,0 +1,13 @@
+import type { RegionRef } from "./file_intake";
+
+/**
+ * A region ref → its DOM node. RN-web exposes a `View`'s underlying
+ * `HTMLElement` straight through the ref's `.current`, so this is the SINGLE
+ * place that unwraps it — shared by `FileDropTarget`'s drag listeners and
+ * `usePasteFiles`'s focus routing, so the two can never resolve the region two
+ * different ways. Returns null when the ref is empty or not yet an element.
+ */
+export function resolveRegionNode(region: RegionRef | undefined): HTMLElement | null {
+  const node = region?.current;
+  return node instanceof HTMLElement ? node : null;
+}

package/src/file_drop_target.tsx

@@ -0,0 +1,16 @@
+import { View } from "react-native";
+import type { FileDropTargetProps } from "./file_intake";
+
+/**
+ * Native stand-in for the drop region.
+ *
+ * React Native has no HTML5 drag-and-drop, so the region is simply its children
+ * and the surface's own Add-file CTA stays the intake path. The wrapper `View`
+ * is kept (and `style` still applies) so the tree and layout match web exactly.
+ *
+ * Web targets resolve `file_drop_target.web.tsx` instead (Metro's `.web`
+ * extension resolution; the package's `react-native` export condition).
+ */
+export function FileDropTarget({ children, style }: FileDropTargetProps) {
+  return <View style={style}>{typeof children === "function" ? children(false) : children}</View>;
+}