@lotics/ui 13.9.0 → 14.0.0

package/src/agent_run.tsx

@@ -5,59 +5,31 @@ import { Text } from "./text";
 import { Icon, type IconName } from "./icon";
 import { Markdown } from "./markdown";
 import { JsonPanel, stringifyData } from "./json_panel";
-import { Peek } from "./peek";
 import { PressableHighlight } from "./pressable_highlight";
 import { Marker, type StepStatus } from "./stepper";
 import { AnimationFadeIn } from "./animation_fade_in";
 import { CONTROL_HEIGHT, CONTROL_RADIUS } from "./control_surface";
 import { useLoticsLocale, type LoticsLocale } from "./locale";
 
-export type AgentStepStatus = "running" | "done" | "error";
-
-export interface AgentRunStep {
-  id: string;
-  /** A `tool` step carries the RAW tool name (`update_records`) — the feed maps
-   *  it to a human label via the default map / `labelForTool`. A `step` carries
-   *  an already-human label. */
-  label: string;
-  status: AgentStepStatus;
-  kind?: "step" | "tool";
-  /** The tool call's input (arguments) and result. When present (and no explicit
-   *  `peek`), the feed reveals them ON DEMAND — a press-to-open peek with an Input /
-   *  Output panel — instead of cluttering the row; the row itself shows only the
-   *  label + state. */
-  input?: unknown;
-  output?: unknown;
-  /** The tool failure message (shown in the peek when `status` is `"error"`). */
-  errorText?: string;
-  /** A note under the label — a short, human summary (a count, a result summary),
-   *  never invented prose. Muted. For raw tool I/O prefer `input`/`output`. */
-  detail?: string;
-  /** Custom content for the press-to-open peek. Overrides the auto-built Input /
-   *  Output panel — pass this to render the reveal yourself. */
-  peek?: ReactNode;
-}
-
-/**
- * The ordered transcript of a run, in the order it happened: the agent's answer
- * prose (`text`), its thinking (`reasoning`, shown collapsed / revealed on demand),
- * and the tools it runs between prose (`step`). A real run is a timeline — text, a
- * burst of tool calls, more text — so the feed is an ordered array, NOT a text
- * block over a flat step list. Consecutive `step` items collapse into ONE activity
- * group; a `step`'s `input`/`output` reveal in a peek on press.
- */
-export type AgentRunItem =
-  | { type: "text"; id: string; text: string }
-  | { type: "reasoning"; id: string; text: string }
-  | ({ type: "step" } & AgentRunStep);
+// 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";
 
 export interface AgentRunProps {
-  /** The ordered transcript — text + step items in the order they occurred. */
-  items: AgentRunItem[];
-  /** Whole-run state. `streaming` keeps the trailing text's caret blinking and
-   *  the tail activity group pulsing; `done`/`error` settle every group. Defaults
-   *  to `streaming` while any step is `running`. */
+  /** The agent message's ai-sdk `parts` — the ordered transcript, rendered in
+   *  place. Chat passes `message.parts`; an app passes `useAgentRun().parts`. */
+  parts: readonly AgentUIPart[];
+  /** Whole-run state. `streaming` keeps the tail activity group pulsing;
+   *  `done`/`error` settle every group. Defaults to `streaming` while any tool
+   *  step is running. */
   state?: "streaming" | "done" | "error";
+  /** A run-level BREAKING error — the message that terminated the run (a stream
+   *  error, an API failure, a hit quota). It lives OUTSIDE `parts` (chat stores it
+   *  in the message's `errors`; `useAgentRun().error` carries it), so pass it here;
+   *  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
    *  back to the built-in label. */
@@ -107,36 +79,9 @@ export function resolveToolMeta(
   };
 }
 
-/** Resolve a step's display label — a `tool` maps its raw name, a `step` is
- *  already human. */
-function stepLabel(s: AgentRunStep, labelForTool?: (toolName: string) => string | undefined): string {
-  return s.kind === "tool" ? resolveToolMeta(s.label, labelForTool).label : s.label;
-}
-
-// A run is a timeline of segments: prose, thinking, then a group of consecutive
-// tool calls, then more prose. Folding the flat item list into segments is what
-// lets the feed interleave instead of forcing all text to the top.
-type Segment =
-  | { kind: "text"; id: string; text: string }
-  | { kind: "reasoning"; id: string; text: string }
-  | { kind: "group"; id: string; steps: AgentRunStep[] };
-
-function toSegments(items: AgentRunItem[]): Segment[] {
-  const segments: Segment[] = [];
-  for (const item of items) {
-    if (item.type === "text" || item.type === "reasoning") {
-      segments.push({ kind: item.type, id: item.id, text: item.text });
-      continue;
-    }
-    const { type: _t, ...step } = item;
-    const tail = segments[segments.length - 1];
-    if (tail && tail.kind === "group") {
-      segments[segments.length - 1] = { ...tail, steps: [...tail.steps, step] };
-    } else {
-      segments.push({ kind: "group", id: item.id, steps: [step] });
-    }
-  }
-  return segments;
+/** 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;
 }
 
 const INK = colors.zinc[700];
@@ -147,15 +92,14 @@ const INK = colors.zinc[700];
  * tail group is a SINGLE pulsing row whose label swaps in place as each call
  * fires (not a growing stack of dots); once prose resumes the group settles into
  * one row — "{final action} · {n} steps" — that EXPANDS on press to the steps in
- * between. Text segments render as prose, the last one carrying a live caret. The
- * run always ends on the agent's text. Pair with `Composer` + `ChangeReview`.
+ * between. Text segments render as prose. The run always ends on the agent's text.
+ * Pair with `Composer` + `ChangeReview`.
  */
 export function AgentRun(props: AgentRunProps) {
-  const { items, labelForTool, stepsLabel = (n) => `${n} steps`, accessibilityLabel } = props;
-  const anyRunning = items.some((it) => it.type === "step" && it.status === "running");
-  const state = props.state ?? (anyRunning ? "streaming" : "done");
+  const { parts, labelForTool, stepsLabel = (n) => `${n} steps`, accessibilityLabel } = props;
+  const segments = toSegments(parts);
+  const state = props.state ?? (anyRunning(segments) ? "streaming" : "done");
   const streaming = state === "streaming";
-  const segments = toSegments(items);
   const lastIndex = segments.length - 1;
 
   const [expanded, setExpanded] = useState<Record<string, boolean>>({});
@@ -167,7 +111,7 @@ export function AgentRun(props: AgentRunProps) {
         if (seg.kind === "text") {
           return (
             <View key={seg.id} style={styles.narration}>
-              <Markdown>{streaming && i === lastIndex ? `${seg.text} ▍` : seg.text}</Markdown>
+              <Markdown>{seg.text}</Markdown>
             </View>
           );
         }
@@ -186,6 +130,20 @@ export function AgentRun(props: AgentRunProps) {
           />
         );
       })}
+      {/* 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. */}
+      {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>
+        </View>
+      ) : null}
     </View>
   );
 }
@@ -213,7 +171,7 @@ function ActivityRow(props: {
   );
   if (onPress) {
     return (
-      <PressableHighlight focusRing onPress={onPress} accessibilityRole="button" accessibilityLabel={accessibilityLabel} style={styles.row}>
+      <PressableHighlight focusRing userSelect="none" onPress={onPress} accessibilityRole="button" accessibilityLabel={accessibilityLabel} style={styles.row}>
         {inner}
       </PressableHighlight>
     );
@@ -221,25 +179,14 @@ function ActivityRow(props: {
   return <View style={styles.row}>{inner}</View>;
 }
 
-function StepBody({ label, detail, status }: { label: string; detail?: string; status: AgentStepStatus }) {
-  return (
-    <View style={{ gap: 1 }}>
-      <Text size="sm">{label}</Text>
-      {detail ? (
-        <Text size="xs" color={status === "error" ? "danger" : "muted"}>
-          {detail}
-        </Text>
-      ) : null}
-    </View>
-  );
+function StepBody({ label }: { label: string }) {
+  return <Text size="sm">{label}</Text>;
 }
 
-// The press-to-open reveal for a tool step: the caller's `peek` wins; else Input /
-// Output / Error panels auto-built from the carried I/O; else nothing (no reveal).
-// Raw I/O stays OUT of the row — only shown here, on demand. Panel titles come from
-// the locale (the caller supplies a whole `peek` to override).
-function stepPeek(s: AgentRunStep, labels: LoticsLocale["agentRun"]): ReactNode {
-  if (s.peek) return s.peek;
+// 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 {
   const hasInput = s.input !== undefined;
   const hasOutput = s.output !== undefined;
   if (!hasInput && !hasOutput && !s.errorText) return null;
@@ -255,18 +202,28 @@ function stepPeek(s: AgentRunStep, labels: LoticsLocale["agentRun"]): ReactNode
   );
 }
 
-// A step's body, wrapped in a Peek when there's something to reveal (I/O or a
-// caller peek), plain otherwise.
-function StepContent({ s, label }: { s: AgentRunStep; label: string }) {
+// 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 }) {
   const locale = useLoticsLocale();
-  const peek = stepPeek(s, locale.agentRun);
-  const body = <StepBody label={label} detail={s.detail} status={s.status} />;
-  return peek ? (
-    <Peek accessibilityLabel={label} content={peek}>
-      {body}
-    </Peek>
-  ) : (
-    body
+  const [open, setOpen] = useState(false);
+  const detail = stepDetail(s, locale.agentRun);
+  const marker: StepStatus = s.status === "error" ? "warning" : "done";
+  if (!detail) {
+    return (
+      <ActivityRow markerStatus={marker}>
+        <StepBody label={label} />
+      </ActivityRow>
+    );
+  }
+  return (
+    <View>
+      <ActivityRow markerStatus={marker} onPress={() => setOpen((o) => !o)} accessibilityLabel={label} trailing={chevron(open ? "up" : "down")}>
+        <StepBody label={label} />
+      </ActivityRow>
+      {open ? <View style={styles.rowDetail}>{detail}</View> : null}
+    </View>
   );
 }
 
@@ -277,7 +234,7 @@ function ReasoningDisclosure(props: { text: string; streaming?: boolean; expande
   const locale = useLoticsLocale();
   return (
     <View style={styles.group}>
-      <PressableHighlight focusRing onPress={onToggle} accessibilityRole="button" accessibilityLabel={locale.agentRun.thinking} style={styles.row}>
+      <PressableHighlight focusRing userSelect="none" onPress={onToggle} accessibilityRole="button" accessibilityLabel={locale.agentRun.thinking} style={styles.row}>
         <View style={styles.dotCol}>
           <Marker status={streaming ? "current" : "done"} color={colors.zinc[400]} live={!!streaming} />
         </View>
@@ -313,7 +270,7 @@ function chevron(dir: "down" | "up") {
 }
 
 function ToolGroup(props: {
-  steps: AgentRunStep[];
+  steps: AgentStep[];
   active: boolean;
   expanded: boolean;
   onToggle: () => void;
@@ -321,7 +278,7 @@ function ToolGroup(props: {
   stepsLabel: (n: number) => string;
 }) {
   const { steps, active, expanded, onToggle, labelForTool, stepsLabel } = props;
-  const resolve = (s: AgentRunStep) => stepLabel(s, labelForTool);
+  const resolve = (s: AgentStep) => stepLabel(s, labelForTool);
 
   // 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
@@ -332,7 +289,7 @@ function ToolGroup(props: {
       <View style={styles.group}>
         <ActivityRow markerStatus="current" live>
           <AnimationFadeIn key={current.id} translateY={4}>
-            <StepBody label={resolve(current)} detail={current.detail} status={current.status} />
+            <StepBody label={resolve(current)} />
           </AnimationFadeIn>
         </ActivityRow>
       </View>
@@ -343,13 +300,11 @@ function ToolGroup(props: {
   const final = steps[steps.length - 1];
   const expandable = steps.length > 1;
 
-  // SETTLED, single call — just the one done/warning row (nothing to expand).
+  // SETTLED, single call — one done/warning row (its I/O expands in place on press).
   if (!expandable) {
     return (
       <View style={styles.group}>
-        <ActivityRow markerStatus={final.status === "error" ? "warning" : "done"}>
-          <StepContent s={final} label={resolve(final)} />
-        </ActivityRow>
+        <StepRow s={final} label={resolve(final)} />
       </View>
     );
   }
@@ -372,9 +327,7 @@ function ToolGroup(props: {
       {expanded
         ? steps.map((s) => (
             <AnimationFadeIn key={s.id} translateY={4}>
-              <ActivityRow markerStatus={s.status === "error" ? "warning" : "done"}>
-                <StepContent s={s} label={resolve(s)} />
-              </ActivityRow>
+              <StepRow s={s} label={resolve(s)} />
             </AnimationFadeIn>
           ))
         : null}
@@ -394,9 +347,17 @@ const styles = StyleSheet.create({
     gap: 10,
     minHeight: CONTROL_HEIGHT,
     borderRadius: CONTROL_RADIUS,
+    // The hover/press highlight BLEEDS 8px past the content on each side (negative
+    // margin absorbed by equal padding, the Peek pattern), so its rounded edges
+    // never pinch against the leading dot or the trailing chevron. Content stays
+    // flush-aligned (net zero), so the run's left edge still meets the consumer's gutter.
+    marginHorizontal: -8,
+    paddingHorizontal: 8,
   },
   dotCol: { width: 18, alignItems: "center" },
   rowBody: { flex: 1 },
   // Reasoning body aligns under the "Thinking" label (past the dot column + gap).
   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 },
 });

package/src/agent_transform.ts

@@ -0,0 +1,102 @@
+import type { UIMessagePart, UIDataTypes, UITools } from "ai";
+
+// `@lotics/ui` renders an agent run straight from the ai-sdk `UIMessage.parts` — the
+// canonical, versioned wire shape BOTH the chat and app agents already emit. There
+// is no bespoke transcript type: this module is the one place that folds parts into
+// the render timeline, shared by `AgentRun` and `AgentProgress`. Consumers pass their
+// message's `parts` (chat's static `tool-<name>` parts and the app SDK's
+// `dynamic-tool` parts are both handled).
+
+/** 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";
+
+/** One tool call, reduced to what the feed shows. `toolName` is the RAW name — the
+ *  renderer maps it to a human label + icon (`resolveToolMeta`). */
+export interface AgentStep {
+  id: string;
+  toolName: string;
+  status: AgentStepStatus;
+  /** Revealed ON DEMAND (a press-to-open peek), never inline. */
+  input?: unknown;
+  output?: unknown;
+  errorText?: string;
+}
+
+/** The render timeline: prose, thinking, and groups of consecutive tool calls, in
+ *  the order they streamed. */
+export type AgentSegment =
+  | { kind: "text"; id: string; text: string }
+  | { kind: "reasoning"; id: string; text: string }
+  | { kind: "group"; id: string; steps: AgentStep[] };
+
+// A tool part — static (`tool-<name>`) or `dynamic-tool` — is exactly the part union
+// that carries `toolCallId`, so extracting on that field is a sound, cast-free guard.
+function isToolPart(part: AgentUIPart): part is Extract<AgentUIPart, { toolCallId: string }> {
+  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.
+function toStatus(state: string): AgentStepStatus {
+  if (state === "output-available") return "done";
+  if (state === "output-error" || state === "output-denied") return "error";
+  return "running";
+}
+
+function toStep(part: Extract<AgentUIPart, { toolCallId: string }>): AgentStep {
+  return {
+    id: part.toolCallId,
+    toolName: part.type === "dynamic-tool" ? part.toolName : part.type.slice("tool-".length),
+    status: toStatus(part.state),
+    input: part.input,
+    output: part.state === "output-available" ? part.output : undefined,
+    errorText: part.state === "output-error" ? part.errorText : undefined,
+  };
+}
+
+/**
+ * Fold a message's parts into the render timeline. Consecutive tool parts collapse
+ * into ONE group (the feed shows a burst as a single expandable row). Prose parts
+ * carry no id in ai's model, so a stable index-based one is synthesized. Part kinds
+ * with no feed representation (`step-start`, `file`, `source-*`, `data-*`, `custom`)
+ * are skipped — the same kinds the chat's own renderer ignores.
+ */
+export function toSegments(parts: readonly AgentUIPart[]): AgentSegment[] {
+  const segments: AgentSegment[] = [];
+  parts.forEach((part, i) => {
+    if (part.type === "text") {
+      if (part.text) segments.push({ kind: "text", id: `text-${i}`, text: part.text });
+      return;
+    }
+    if (part.type === "reasoning") {
+      if (part.text) segments.push({ kind: "reasoning", id: `reasoning-${i}`, text: part.text });
+      return;
+    }
+    if (!isToolPart(part)) return;
+    const step = toStep(part);
+    const tail = segments[segments.length - 1];
+    if (tail?.kind === "group") tail.steps.push(step);
+    else segments.push({ kind: "group", id: step.id, steps: [step] });
+  });
+  return segments;
+}
+
+/** Whether any tool step is still running — the default "is the run streaming" signal. */
+export function anyRunning(segments: readonly AgentSegment[]): boolean {
+  return segments.some((s) => s.kind === "group" && s.steps.some((st) => st.status === "running"));
+}
+
+/** The last still-running tool step, if any — for a compact "currently doing X". */
+export function lastRunningStep(segments: readonly AgentSegment[]): AgentStep | undefined {
+  for (let i = segments.length - 1; i >= 0; i--) {
+    const seg = segments[i];
+    if (seg.kind !== "group") continue;
+    for (let j = seg.steps.length - 1; j >= 0; j--) {
+      if (seg.steps[j].status === "running") return seg.steps[j];
+    }
+  }
+  return undefined;
+}

package/src/choice_list.tsx

@@ -1,10 +1,22 @@
-import { Pressable, View } from "react-native";
+import { useState } from "react";
+import { Pressable, TextInput, View } from "react-native";
 import { colors } from "./colors";
 import { Text } from "./text";
 import { Icon } from "./icon";
 import { Divider } from "./divider";
-import { useFocusRing } from "./use_focus_ring";
-import { FOCUS_RING } from "./control_surface";
+import { composeHandler, useFocusRing } from "./use_focus_ring";
+import { useHover } from "./use_hover";
+import { CONTROL_RADIUS, FOCUS_RING } from "./control_surface";
+import { useAutoGrowHeight } from "./use_auto_grow_height";
+import { fontFamilyMedium, getInputTextStyle } from "./text_utils";
+import { useLoticsLocale } from "./locale";
+
+// A typed custom answer must read exactly like a picked option's LABEL (`Text
+// size="sm" weight="medium"`). Its SIZE stays on the input contract (getInputTextStyle:
+// 14 on desktop = the sm label, 16 on mobile to defeat iOS-Safari focus-zoom — and the
+// size useAutoGrowHeight is tuned to); this override only aligns the family, tracking,
+// and colour to the label, which is where an unstyled input actually diverges from it.
+const ANSWER_LABEL_FONT = { fontFamily: fontFamilyMedium, letterSpacing: -0.4, color: colors.zinc[900] } as const;
 
 export interface ChoiceOption {
   label: string;
@@ -15,25 +27,33 @@ export interface ChoiceOption {
 
 export interface ChoiceListProps {
   options: ChoiceOption[];
-  /** The chosen value. */
+  /** The chosen value — an option's `value`, or (with `allowCustom`) the free
+   *  TEXT of an "Other" answer. `undefined` = nothing chosen. */
   value?: string;
   onSelect: (value: string) => void;
+  /** Show an always-visible inline free-text field at the bottom for a custom
+   *  answer — typing it IS the selection. Its text IS the value (any `value` not
+   *  matching an option reads as the custom answer, so the caller distinguishes a
+   *  custom answer by "not in `options`"). */
+  allowCustom?: boolean;
 }
 
 /** One selectable option — a role-less-free `Pressable` (its own accessible name
  *  + selected state), hover wash + focus ring, no border. */
-function ChoiceRow({ option, selected, onSelect }: { option: ChoiceOption; selected: boolean; onSelect: (value: string) => void }) {
+function ChoiceRow({ option, selected, onSelect }: { option: ChoiceOption; selected: boolean; onSelect: () => void }) {
   const { focusVisible, focusProps } = useFocusRing();
   return (
     <Pressable
       accessibilityRole="button"
       accessibilityLabel={option.label}
       accessibilityState={{ selected }}
-      onPress={() => onSelect(option.value)}
+      onPress={onSelect}
       {...focusProps}
       style={({ hovered, pressed }) => [
-        { flexDirection: "row", alignItems: "center", gap: 12, paddingVertical: 14, paddingHorizontal: 6, borderRadius: 8 },
-        hovered || pressed ? { backgroundColor: colors.zinc[50] } : null,
+        { flexDirection: "row", alignItems: "center", gap: 12, paddingVertical: 14, paddingHorizontal: 8, borderRadius: CONTROL_RADIUS },
+        // Selected reads as a persistent tint (zinc-100); an unselected row only
+        // washes on hover (zinc-50). The check below reserves its slot always.
+        selected ? { backgroundColor: colors.zinc[100] } : hovered || pressed ? { backgroundColor: colors.zinc[50] } : null,
         focusVisible ? { boxShadow: FOCUS_RING } : null,
       ]}
     >
@@ -47,28 +67,97 @@ function ChoiceRow({ option, selected, onSelect }: { option: ChoiceOption; selec
           </Text>
         ) : null}
       </View>
-      {selected ? <Icon name="check" size={17} color={colors.zinc[900]} /> : null}
+      <View style={{ width: 17, alignItems: "center" }}>
+        {selected ? <Icon name="check" size={17} color={colors.zinc[900]} /> : null}
+      </View>
     </Pressable>
   );
 }
 
+/** The custom-answer row — the SAME box as a `ChoiceRow` (padding · radius · hover
+ *  wash · focus ring), but holding an always-editable, auto-growing multiline input
+ *  instead of a pressable label. Typing it IS the selection; focusing it re-selects a
+ *  parked draft (`onFocus`). */
+function CustomAnswerRow({ value, selected, onChangeText, onFocus, placeholder }: { value: string; selected: boolean; onChangeText: (text: string) => void; onFocus: () => void; placeholder: string }) {
+  const { hovered, hoverProps } = useHover();
+  const { focusVisible, focusProps } = useFocusRing({ always: true });
+  const grow = useAutoGrowHeight({ minLines: 1 });
+  return (
+    <View
+      {...(hoverProps as object)}
+      style={[
+        { paddingVertical: 14, paddingHorizontal: 8, borderRadius: CONTROL_RADIUS },
+        // Same states as an option row: a filled custom answer reads as selected
+        // (zinc-100); otherwise it washes on hover (zinc-50).
+        selected ? { backgroundColor: colors.zinc[100] } : hovered ? { backgroundColor: colors.zinc[50] } : null,
+        focusVisible ? { boxShadow: FOCUS_RING } : null,
+      ]}
+    >
+      <TextInput
+        ref={grow.inputRef}
+        multiline
+        value={value}
+        onChangeText={(text) => { onChangeText(text); grow.measure(); }}
+        onFocus={composeHandler(onFocus, focusProps.onFocus)}
+        onBlur={focusProps.onBlur}
+        onContentSizeChange={grow.onContentSizeChange}
+        scrollEnabled={grow.scrollEnabled}
+        placeholder={placeholder}
+        placeholderTextColor={colors.zinc[400]}
+        // Bare input: the row owns padding + hover + focus ring, so it strips its own
+        // padding and browser outline and just grows with the text. Input-contract size +
+        // the option-label family/tracking/colour, so a typed answer reads like a picked one.
+        style={[getInputTextStyle(), ANSWER_LABEL_FONT, { height: grow.containerHeight, padding: 0, outlineStyle: "none" as unknown as "solid" }]}
+      />
+    </View>
+  );
+}
+
 /**
  * A vertical set of selectable answer options — divider-separated rows (no
  * bordered cards), each with its own focus ring + hover wash, single-select and
  * freely switchable (pick a different option any time). The chosen row shows a
- * check. The agent's quick-reply surface (`Clarify` uses it) and any "pick one"
- * question.
+ * check. With `allowCustom`, an always-visible inline free-text field at the
+ * bottom captures a custom answer (typing it IS the selection). The agent's
+ * quick-reply surface (`Clarify` / `ClarifyWizard` use it) and any "pick one" question.
  */
 export function ChoiceList(props: ChoiceListProps) {
-  const { options, value, onSelect } = props;
+  const { options, value, onSelect, allowCustom } = props;
+  const labels = useLoticsLocale().clarify;
+  // A value that matches no option IS a custom answer (its own text, or "" right
+  // after focusing an empty custom row).
+  const isCustomValue = (v: string | undefined): v is string => !!allowCustom && typeof v === "string" && !options.some((o) => o.value === v);
+  // The custom TEXT is a draft that outlives selection: picking an option deselects
+  // the custom row but must KEEP its text so the human can return to it. The single
+  // `value` can't hold both a picked option and the parked text, so the draft is
+  // local — seeded from `value` when this row mounts already custom-selected.
+  const [customDraft, setCustomDraft] = useState(() => (isCustomValue(value) ? value : ""));
+  const customSelected = isCustomValue(value);
   return (
     <View>
       {options.map((o, i) => (
         <View key={o.value}>
-          {i > 0 ? <Divider /> : null}
-          <ChoiceRow option={o} selected={value === o.value} onSelect={onSelect} />
+          {/* The hairline carries vertical padding so each row's rounded hover/selected
+              fill has air on both sides of it (a flush divider would pinch the corners). */}
+          {i > 0 ? <Divider paddingVertical={6} /> : null}
+          <ChoiceRow option={o} selected={value === o.value} onSelect={() => onSelect(o.value)} />
         </View>
       ))}
+      {allowCustom ? (
+        <View>
+          {options.length > 0 ? <Divider paddingVertical={6} /> : null}
+          {/* The custom answer is an ALWAYS-visible inline row (no press-to-reveal). Its
+              text persists (customDraft) across option switches; typing selects it, and
+              focusing a non-empty parked draft re-selects it without retyping. */}
+          <CustomAnswerRow
+            value={customDraft}
+            selected={customSelected && customDraft.length > 0}
+            onChangeText={(text) => { setCustomDraft(text); onSelect(text); }}
+            onFocus={() => { if (customDraft.length > 0 && !customSelected) onSelect(customDraft); }}
+            placeholder={labels.otherPlaceholder}
+          />
+        </View>
+      ) : null}
     </View>
   );
 }