@lotics/ui 5.4.0 → 5.5.0

package/AGENTS.md

@@ -75,9 +75,10 @@ Pick by capability, not by name. (→ the source file for the API.)
 - **Files** — `FileDropzone`, `FileThumbnail` / `FileThumbnailGrid`, `FilePreview` /
   `FileGalleryModal`, `ImageGallery`; for gated CRUD compose locally with `useSelectionMode` +
   `shareOrDownloadFiles` + `rotateImageToBlob` (see §Data entry → Attachments).
-- **Specialized work surfaces** — `ScanField` (scan/verify), `StepList` (guided run),
-  `RemainderMeter` + `AllocationRow` (allocation), `Timeline`, `Calendar`, `Gantt`,
-  `comments_thread`.
+- **Specialized work surfaces** — `ScanField` (scan/verify), `Stepper` (a guided run / progress
+  sequence — done · current · upcoming, horizontal OR vertical), `RemainderMeter` + `AllocationRow`
+  (allocation), `Timeline` (a heterogeneous event LOG — icons + expandable details, not progress),
+  `Calendar`, `Gantt`, `comments_thread`.
 - **AI surfaces** — `Composer` (the adaptive command/chat composer — a compact pill when empty that
   expands for long text + attachments; the surface that triggers agent work),
   `AgentRun` (the live streaming work feed) + `AgentProgress` (its compact, floating, expandable
@@ -264,9 +265,13 @@ Compose the surfaces as a loop, and reach for the right one by job:
   attaching HOLDS the file for review; the human presses Send. The canvas (`tpl_dieline`) uses it this
   way; while running the host swaps `Composer` for `AgentProgress` (same pill geometry, so it reads as
   a morph).
-- **Show the work** — `AgentRun`: a live feed of the agent's steps (reasoning, tool calls) on a
-  spine, the running node a pulsing ink dot (a done step settles to a hollow ring). Transparent
-  work, NEVER a bare spinner — the
+- **Show the work** — `AgentRun`: a live feed of the agent's work — its streamed narration (with a
+  blinking caret) + tool calls as a vertical `Stepper` of neutral dots (the latest pulsing while live,
+  a white-check dot once done). No title, no avatar — just the work. A terminal "Done" step (the
+  `complete` node) appears ONLY once the run finishes. A step can carry `peek` content to glance into
+  via a popover. Tool labels resolve from the raw tool name via a built-in default map + an optional
+  `labelForTool` override (localize THERE — the kit stays English). `doneLabel` localizes the terminal.
+  Transparent work, NEVER a bare spinner — the
   intelligence is legible. On a canvas/composer app reach for `AgentProgress` — `AgentRun`
   collapsed into a floating pill (avatar + current step) that EXPANDS on press; the composer
   morphs into it while running, and reveals again when done.
@@ -365,9 +370,11 @@ controls — while **status/severity/diffs use functional colour** the way the r
 - **Confidence** — a 3-tick meter + word, emerald / amber / zinc by level.
 - **Finding severity** — a coloured dot `Badge` + metric: red critical, amber warning, blue note,
   emerald on-track (+ stacking order, most severe first).
-- **AgentRun** — `Timeline`-style tinted-disc nodes that fade in: a running step spins **blue**, a
-  finished step is an **emerald check**, a failure a **red** alert; the header reads `Working` (blue
-  spinner) / `Done` (emerald check) / `Stopped` (red).
+- **Stepper / AgentRun nodes** — progress dots on a spine: `current` a **pulsing accent ring** (white
+  centre), `done` a filled accent dot + **white check**, `upcoming` a faint **grey** ring, the terminal
+  `complete` a **blackish ring + black check**, `warning` **amber**. Default accent is neutral ink
+  (`color` themes it); `AgentRun` keeps the neutral default + appends the `complete` "Done" node only
+  when the run finishes.
 - **ChangeReview diffs** — the old value struck in **red**, the new value in **green**.
 - **Discrepancy** — the agent's pick gets a **blue** highlight; `Mismatch` reads amber, `Resolved`
   emerald.
@@ -584,8 +591,8 @@ inline_time_picker (the Inline* family — per-field editors on `inline_edit`'s
 list · list_item · menu_button · menu_list_item · detail_row · pressable_row · action_menu ·
 floating_action_bar · filter_pill · column_filter (ColumnFilter — the typed per-column filter pill +
 columnFilterToConditions; for a register filtering on several columns) · chip_group · search_input ·
-sort_header · table · pagination · accordion · stepper ·
-step_progress · step_list · timeline · drawer (+ DrawerFooter) · dialog · popover · tooltip ·
+sort_header · table · pagination · accordion · stepper (Stepper + Step — done/current/upcoming/warning/complete progress on a track (horizontal) or spine (vertical); compound `<Step status>children` OR data `steps[]`+`current`; the guided-run / agent-feed primitive — subsumes the old StepList) ·
+step_progress · timeline (heterogeneous event LOG — per-row icon + expandable details, models the past; NOT progress) · drawer (+ DrawerFooter) · dialog · popover · tooltip ·
 command_menu · alert · peek · empty_state · completion_state · callout (Callout · CalloutTitle ·
 CalloutText · CalloutActions) · kpi_card · kpi_strip · metric · trend_chip · sparkline ·
 bar_chart · line_chart · pie_chart · ring_gauge · progress_bar · stacked_progress_bar · breakdown ·

package/examples/tpl_extract.tsx

@@ -133,7 +133,7 @@ export function TplExtract() {
 
         {phase === "extracting" ? (
           <Card>
-            <AgentRun title="Extracting line items" steps={steps} state={streaming ? "streaming" : "done"} />
+            <AgentRun steps={steps} state={streaming ? "streaming" : "done"} />
           </Card>
         ) : null}
 

package/examples/tpl_lookup.tsx

@@ -201,7 +201,7 @@ export function TplLookup() {
 
         <ScrollView style={{ flex: 1 }} contentContainerStyle={{ padding: 16, gap: 16 }}>
           {/* current run */}
-          <AgentRun title="Classifying the goods" steps={steps} state={streaming ? "streaming" : "done"} />
+          <AgentRun steps={steps} state={streaming ? "streaming" : "done"} />
 
           <View style={{ gap: 8 }}>
             <Text size="xs" color="muted" weight="medium">Nearest matches</Text>

package/examples/tpl_pick.tsx

@@ -11,7 +11,7 @@ import { Divider } from "@lotics/ui/divider";
 import { Popover, PopoverContent, PopoverFooter, PopoverTrigger } from "@lotics/ui/popover";
 import { ProgressBar } from "@lotics/ui/progress_bar";
 import { ScanField } from "@lotics/ui/scan_field";
-import { StepList, type StepListItem } from "@lotics/ui/step_list";
+import { Stepper, Step, type StepStatus } from "@lotics/ui/stepper";
 import { CompletionState } from "@lotics/ui/completion_state";
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -155,18 +155,6 @@ function Complete({ lines, onReset }: { lines: PickLine[]; onReset: () => void }
 // The right rail — the whole run at a glance: done · now · up next. Read-only;
 // the run is sequential, so position is shown, not chosen.
 function RunPath({ lines, currentIndex }: { lines: PickLine[]; currentIndex: number }) {
-  const steps: StepListItem[] = lines.map((l, i) => ({
-    id: l.id,
-    status: l.status === "short" ? "warning" : l.status === "picked" ? "done" : i === currentIndex ? "current" : "pending",
-    title: l.bin,
-    subtitle: l.item,
-    trailing:
-      l.status === "short" ? (
-        <Badge variant="dot" label={`${l.picked ?? 0} of ${l.qty}`} color="amber" />
-      ) : (
-        <Text size="sm" color="muted" tabular>{`×${l.qty}`}</Text>
-      ),
-  }));
   return (
     <Card style={{ padding: 0 }}>
       <View style={{ paddingHorizontal: 16, paddingVertical: 12 }}>
@@ -174,7 +162,27 @@ function RunPath({ lines, currentIndex }: { lines: PickLine[]; currentIndex: num
       </View>
       <Divider />
       <View style={{ paddingHorizontal: 16, paddingVertical: 14 }}>
-        <StepList steps={steps} accessibilityLabel="Pick path" />
+        <Stepper orientation="vertical" accessibilityLabel="Pick path">
+          {lines.map((l, i) => {
+            const status: StepStatus =
+              l.status === "short" ? "warning" : l.status === "picked" ? "done" : i === currentIndex ? "current" : "upcoming";
+            return (
+              <Step key={l.id} status={status}>
+                <View style={{ flexDirection: "row", alignItems: "flex-start", gap: 12, flex: 1 }}>
+                  <View style={{ flex: 1, gap: 1 }}>
+                    <Text size="sm">{l.bin}</Text>
+                    <Text size="xs" color="muted" numberOfLines={1}>{l.item}</Text>
+                  </View>
+                  {l.status === "short" ? (
+                    <Badge variant="dot" label={`${l.picked ?? 0} of ${l.qty}`} color="amber" />
+                  ) : (
+                    <Text size="sm" color="muted" tabular>{`×${l.qty}`}</Text>
+                  )}
+                </View>
+              </Step>
+            );
+          })}
+        </Stepper>
       </View>
     </Card>
   );

package/examples/tpl_ratedesk.tsx

@@ -238,7 +238,7 @@ export function TplRatedesk() {
           </View>
         ) : null}
 
-        {phase === "reading" ? <AgentRun title="Reading carrier sheets" steps={runSteps} state="streaming" /> : null}
+        {phase === "reading" ? <AgentRun steps={runSteps} state="streaming" /> : null}
 
         {phase === "review" ? (
           <ChangeReview

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "5.4.0",
+  "version": "5.5.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",
@@ -139,7 +139,6 @@
     "./table": "./src/table.tsx",
     "./detail_row": "./src/detail_row.tsx",
     "./scan_field": "./src/scan_field.tsx",
-    "./step_list": "./src/step_list.tsx",
     "./completion_state": "./src/completion_state.tsx",
     "./remainder_meter": "./src/remainder_meter.tsx",
     "./allocation_row": "./src/allocation_row.tsx",

package/src/agent_progress.tsx

@@ -4,7 +4,7 @@ import { colors } from "./colors";
 import { Text } from "./text";
 import { WaveAvatar } from "./wave_avatar";
 import { PressableHighlight } from "./pressable_highlight";
-import { AgentRun, type AgentRunStep } from "./agent_run";
+import { AgentRun, resolveToolMeta, type AgentRunStep } from "./agent_run";
 
 export interface AgentProgressProps {
   steps: AgentRunStep[];
@@ -12,6 +12,11 @@ export interface AgentProgressProps {
   /** The collapsed-pill label. Defaults to the running step's label (or
    *  "Working…" / "Done"). */
   label?: string;
+  /** The agent's streamed text — forwarded to the expanded `AgentRun`. */
+  text?: string;
+  /** Localize / override a tool step's label by raw tool name — applied to both
+   *  the collapsed pill and the expanded feed. */
+  labelForTool?: (toolName: string) => string | undefined;
   defaultExpanded?: boolean;
 }
 
@@ -24,11 +29,16 @@ export interface AgentProgressProps {
  * label, so the surface stays calm until you ask to see the steps.
  */
 export function AgentProgress(props: AgentProgressProps) {
-  const { steps, state = "streaming", label, defaultExpanded } = props;
+  const { steps, state = "streaming", label, text, labelForTool, defaultExpanded } = props;
   const [expanded, setExpanded] = useState(defaultExpanded ?? false);
 
   const running = steps.filter((s) => s.status === "running").at(-1);
-  const compact = label ?? running?.label ?? (state === "done" ? "Done" : state === "error" ? "Stopped" : "Working…");
+  const runningLabel = running
+    ? running.kind === "tool"
+      ? resolveToolMeta(running.label, labelForTool).label
+      : running.label
+    : undefined;
+  const compact = label ?? runningLabel ?? (state === "done" ? "Done" : state === "error" ? "Stopped" : "Working…");
   const streaming = state === "streaming";
 
   return (
@@ -36,7 +46,7 @@ export function AgentProgress(props: AgentProgressProps) {
       {expanded ? (
         <View style={styles.panel}>
           <ScrollView style={{ maxHeight: 260 }} contentContainerStyle={{ padding: 16 }}>
-            <AgentRun steps={steps} state={state} />
+            <AgentRun steps={steps} state={state} text={text} labelForTool={labelForTool} />
           </ScrollView>
         </View>
       ) : null}

package/src/agent_run.tsx

@@ -1,174 +1,169 @@
-import { StyleSheet, View } from "react-native";
-import { colors, solid, tint } from "./colors";
+import { useEffect, useRef, type ReactNode } from "react";
+import { Animated, StyleSheet, View } from "react-native";
+import { colors, solid } from "./colors";
 import { Text } from "./text";
-import { Icon, type IconName } from "./icon";
-import { ActivityIndicator } from "./activity_indicator";
-import { AnimationFadeIn } from "./animation_fade_in";
+import { type IconName } from "./icon";
+import { Peek } from "./peek";
+import { Stepper, Step, type StepStatus } from "./stepper";
 
 export type AgentStepStatus = "running" | "done" | "error";
 
 export interface AgentRunStep {
   id: string;
-  /** The action line — what the agent is doing ("Reading the image",
-   *  "Identifying the box style"). */
+  /** 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;
-  /** Streamed reasoning or result text under the label (muted). Grows as the
-   *  model streams; the host appends to it. */
+  /** A note under the label (a count, an input summary), muted. */
   detail?: string;
   status: AgentStepStatus;
-  /** A `tool` step renders its label in a monospace chip — it called a tool
-   *  rather than reasoned. */
   kind?: "step" | "tool";
+  /** Optional content shown in a `Peek` popover when the step is pressed —
+   *  glance into what the step did (the tool input, a result summary). */
+  peek?: ReactNode;
 }
 
 export interface AgentRunProps {
   steps: AgentRunStep[];
-  /** Whole-run state. `streaming` keeps the feed alive — the running node spins
-   *  and the header shows a working indicator; `done`/`error` settle it.
-   *  Defaults to `streaming` while any step is running, else `done`. */
+  /** The agent's streamed reasoning / answer text — shown as a narration block
+   *  above the feed, with a live caret while streaming. */
+  text?: string;
+  /** Whole-run state. `streaming` keeps the caret blinking + the latest step
+   *  pulsing; `done`/`error` settle it. Defaults to `streaming` while a step runs. */
   state?: "streaming" | "done" | "error";
-  /** Header label — the task the agent is performing ("Designing the dieline").
-   *  Omit for a bare step feed with no header band. */
-  title?: 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. */
+  labelForTool?: (toolName: string) => string | undefined;
+  /** The always-last terminal step's label. Default "Done"; localize per app. */
+  doneLabel?: string;
   accessibilityLabel?: string;
 }
 
+// ── 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
+// 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" },
+  get_record: { label: "Reading a record", icon: "file-text" },
+  get_records: { label: "Reading records", icon: "file-text" },
+  create_records: { label: "Creating records", icon: "plus" },
+  update_records: { label: "Updating records", icon: "square-pen" },
+  delete_records: { label: "Removing records", icon: "trash" },
+  generate_pdf_from_template: { label: "Generating PDF", icon: "file-down" },
+  generate_excel_from_template: { label: "Generating spreadsheet", icon: "file-spreadsheet" },
+  generate_docx_from_template: { label: "Generating document", icon: "file-text" },
+};
+
+function prettifyToolName(name: string): string {
+  const s = name.replace(/_/g, " ").trim();
+  return s ? s.charAt(0).toUpperCase() + s.slice(1) : name;
+}
+
+/** Resolve a tool's display label + icon: a caller override wins on the label,
+ *  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,
+): { label: string; icon: IconName } {
+  const def =
+    TOOL_META[toolName] ??
+    (toolName.startsWith("generate_") && toolName.endsWith("_from_template")
+      ? { label: "Generating document", icon: "file-text" as IconName }
+      : undefined);
+  return {
+    label: labelForTool?.(toolName) ?? def?.label ?? prettifyToolName(toolName),
+    icon: def?.icon ?? "list",
+  };
+}
+
 /**
- * A live feed of an AI agent's work — the steps it takes (reasoning, tool
- * calls, results) revealed as they happen, on a connecting spine. The
- * transparent-work surface, NOT a spinner. Shares the `Timeline` node anatomy: a
- * tinted disc behind a full-colour icon, fading in as each step arrives. A
- * running step spins (blue); a finished step settles to an emerald check; a
- * failure to a red alert. Pair with `Composer` (the command that starts a
- * run) and `ReviewCard` (the result to review). Unlike `StepList` (a known,
- * guided run of fixed steps) the steps here arrive unknown-ahead.
+ * A live feed of an AI agent's work — the prose it streams + the tools it calls,
+ * on a vertical `Stepper`: one neutral dot per call (the latest pulsing while the
+ * run is live, a check once done) with a plain-text label, no chip/icon, ALWAYS
+ * ending on a "Done" terminal step. A step can carry `peek` content to glance
+ * into via a popover. Tool names map to labels via the built-in default + a
+ * `labelForTool` override. Pair with `Composer` + `ReviewCard`.
  */
 export function AgentRun(props: AgentRunProps) {
-  const { steps, title, accessibilityLabel } = props;
+  const { steps, text, labelForTool, doneLabel = "Done", accessibilityLabel } = props;
   const anyRunning = steps.some((s) => s.status === "running");
   const state = props.state ?? (anyRunning ? "streaming" : "done");
   const streaming = state === "streaming";
+  const last = steps.length - 1;
 
   return (
-    <View accessibilityLabel={accessibilityLabel} style={{ gap: title ? 12 : 0 }}>
-      {title ? (
-        <View style={styles.header}>
-          <Text size="sm" weight="semibold" style={{ flex: 1 }} numberOfLines={1}>
-            {title}
-          </Text>
-          <HeaderStatus state={state} streaming={streaming} />
-        </View>
+    <View accessibilityLabel={accessibilityLabel} style={{ gap: 12 }}>
+      {text ? (
+        <Text size="sm" style={styles.narration}>
+          {text}
+          {streaming ? <Caret /> : null}
+        </Text>
       ) : null}
 
-      <View>
+      <Stepper orientation="vertical" live={streaming}>
         {steps.map((s, i) => {
-          const last = i === steps.length - 1;
-          return (
-            <View key={s.id} style={styles.item}>
-              <View style={styles.spineCol}>
-                <AnimationFadeIn key={`${s.id}-${s.status}`}>
-                  <StepNode status={s.status} />
-                </AnimationFadeIn>
-                {!last ? <View style={styles.spine} /> : null}
-              </View>
-              <View style={[styles.contentCol, !last ? styles.contentGap : null]}>
-                {s.kind === "tool" ? (
-                  <View style={styles.toolChip}>
-                    <Text size="xs" color="muted" numberOfLines={1}>
-                      {s.label}
-                    </Text>
-                  </View>
-                ) : (
-                  <Text
-                    size="sm"
-                    weight={s.status === "running" ? "medium" : "regular"}
-                    color={s.status === "done" ? "muted" : s.status === "error" ? "danger" : "default"}
-                  >
-                    {s.label}
-                  </Text>
-                )}
-                {s.detail ? (
-                  <Text size="xs" color="muted" style={{ marginTop: 2 }}>
-                    {s.detail}
-                  </Text>
-                ) : null}
-              </View>
+          // Tools the SDK feeds arrive already "done"; show the most recent as
+          // the pulsing current while the run is still live.
+          const status: StepStatus =
+            s.status === "error"
+              ? "warning"
+              : s.status === "running" || (streaming && i === last)
+                ? "current"
+                : "done";
+          const label = s.kind === "tool" ? resolveToolMeta(s.label, labelForTool).label : s.label;
+          const body = (
+            <View style={{ gap: 1 }}>
+              <Text size="sm">{label}</Text>
+              {s.detail ? (
+                <Text size="xs" color={s.status === "error" ? "danger" : "muted"}>
+                  {s.detail}
+                </Text>
+              ) : null}
             </View>
           );
+          return (
+            <Step key={s.id} status={status}>
+              {s.peek ? (
+                <Peek accessibilityLabel={label} content={s.peek}>
+                  {body}
+                </Peek>
+              ) : (
+                body
+              )}
+            </Step>
+          );
         })}
-      </View>
+        {state === "done" ? (
+          <Step key="__done" status="complete">
+            <Text size="sm" weight="medium">
+              {doneLabel}
+            </Text>
+          </Step>
+        ) : null}
+      </Stepper>
     </View>
   );
 }
 
-const NODE_STATUS: Record<"done" | "error", { color: string; icon: IconName }> = {
-  done: { color: solid("emerald"), icon: "check" },
-  error: { color: solid("red"), icon: "circle-alert" },
-};
-
-function StepNode({ status }: { status: AgentStepStatus }) {
-  if (status === "running") {
-    return (
-      <View style={[styles.node, { backgroundColor: tint("blue", 0.12) }]}>
-        <ActivityIndicator size={12} color={solid("blue")} />
-      </View>
+// A blinking caret that trails the streamed text — the signature of live writing.
+function Caret() {
+  const opacity = useRef(new Animated.Value(1)).current;
+  useEffect(() => {
+    const loop = Animated.loop(
+      Animated.sequence([
+        Animated.timing(opacity, { toValue: 0, duration: 480, useNativeDriver: false }),
+        Animated.timing(opacity, { toValue: 1, duration: 480, useNativeDriver: false }),
+      ]),
     );
-  }
-  const s = NODE_STATUS[status];
-  return (
-    <View style={[styles.node, { backgroundColor: tint(status === "done" ? "emerald" : "red", 0.12) }]}>
-      <Icon name={s.icon} size={13} color={s.color} />
-    </View>
-  );
-}
-
-function HeaderStatus({ state, streaming }: { state: "streaming" | "done" | "error"; streaming: boolean }) {
-  if (streaming) {
-    return (
-      <View style={styles.headerStatus}>
-        <ActivityIndicator size={12} color={solid("blue")} />
-        <Text size="xs" weight="medium" style={{ color: solid("blue") }}>
-          Working
-        </Text>
-      </View>
-    );
-  }
-  if (state === "error") {
-    return (
-      <View style={styles.headerStatus}>
-        <Icon name="circle-alert" size={13} color={solid("red")} />
-        <Text size="xs" weight="medium" color="danger">
-          Stopped
-        </Text>
-      </View>
-    );
-  }
-  return (
-    <View style={styles.headerStatus}>
-      <Icon name="circle-check" size={13} color={solid("emerald")} />
-      <Text size="xs" weight="medium" style={{ color: solid("emerald") }}>
-        Done
-      </Text>
-    </View>
-  );
+    loop.start();
+    return () => loop.stop();
+  }, [opacity]);
+  return <Animated.Text style={{ opacity, color: solid("blue") }}>▍</Animated.Text>;
 }
 
-const NODE = 22;
-
 const styles = StyleSheet.create({
-  header: { flexDirection: "row", alignItems: "center", gap: 8, minHeight: 20 },
-  headerStatus: { flexDirection: "row", alignItems: "center", gap: 5 },
-  item: { flexDirection: "row", gap: 12 },
-  spineCol: { width: NODE, alignItems: "center", paddingTop: 1 },
-  spine: { width: 1.5, flex: 1, minHeight: 12, borderRadius: 1, backgroundColor: colors.zinc[200], marginTop: 3 },
-  contentCol: { flex: 1, paddingTop: 2 },
-  contentGap: { paddingBottom: 14 },
-  node: { width: NODE, height: NODE, borderRadius: NODE / 2, alignItems: "center", justifyContent: "center" },
-  toolChip: {
-    alignSelf: "flex-start",
-    paddingHorizontal: 8,
-    paddingVertical: 3,
-    borderRadius: 6,
-    backgroundColor: colors.zinc[100],
-  },
+  narration: { lineHeight: 21, color: colors.zinc[700] },
 });

package/src/animation_fade_in.tsx

@@ -4,19 +4,26 @@ import { Animated, StyleProp, ViewStyle } from "react-native";
 interface AnimationFadeInProps {
   children: React.ReactNode;
   style?: StyleProp<ViewStyle>;
+  /** Rise this many px while fading in — the "appearing into place" gesture.
+   *  Default 0 (fade only). */
+  translateY?: number;
 }
 
 export function AnimationFadeIn(props: AnimationFadeInProps) {
-  const { children, style } = props;
-  const opacity = useRef(new Animated.Value(0)).current;
+  const { children, style, translateY = 0 } = props;
+  const progress = useRef(new Animated.Value(0)).current;
 
   useEffect(() => {
-    Animated.spring(opacity, {
+    Animated.spring(progress, {
       toValue: 1,
       bounciness: 0,
       useNativeDriver: true,
     }).start();
-  }, [opacity]);
+  }, [progress]);
 
-  return <Animated.View style={[{ opacity }, style]}>{children}</Animated.View>;
+  const transform = translateY
+    ? [{ translateY: progress.interpolate({ inputRange: [0, 1], outputRange: [translateY, 0] }) }]
+    : undefined;
+
+  return <Animated.View style={[{ opacity: progress, transform }, style]}>{children}</Animated.View>;
 }

package/src/share_or_download.test.ts

@@ -29,6 +29,17 @@ describe("shareOrDownloadFiles", () => {
     expect(shared.title).toBe("Ảnh");
   });
 
+  it("rides the given credentials on the blob fetch so an auth-gated proxy URL authorizes", async () => {
+    // Type the init param so mock.calls[0][1] is the RequestInit we assert on.
+    const fetchMock = vi.fn(async (_url: string, _init?: RequestInit) => new Response(new Blob(["img"], { type: "image/png" })));
+    vi.stubGlobal("fetch", fetchMock);
+    vi.stubGlobal("navigator", { canShare: () => true, share: vi.fn(async () => undefined) });
+
+    await shareOrDownloadFiles([{ url: "https://api.example/v1/files/k", filename: "a.png" }], { credentials: "include" });
+
+    expect(fetchMock.mock.calls[0][1]).toMatchObject({ credentials: "include" });
+  });
+
   it("treats a cancelled share sheet (AbortError) as done — never falls back to downloading", async () => {
     vi.stubGlobal("fetch", vi.fn(async () => new Response(new Blob(["img"], { type: "image/png" }))));
     const share = vi.fn(async () => { throw new DOMException("cancelled", "AbortError"); });

package/src/stepper.tsx

@@ -1,88 +1,229 @@
-import { View } from "react-native";
-import { colors } from "./colors";
+import {
+  Children,
+  cloneElement,
+  createContext,
+  isValidElement,
+  useContext,
+  useEffect,
+  useRef,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+import { Animated, StyleSheet, View } from "react-native";
+import { colors, solid } from "./colors";
 import { Icon } from "./icon";
 import { Text } from "./text";
+import { PressableHighlight } from "./pressable_highlight";
+import { AnimationFadeIn } from "./animation_fade_in";
 
-export type StepStatus = "done" | "current" | "upcoming";
+// A node's place in a sequence. `upcoming` = not reached (greyish); `current` =
+// where we are (ring + white centre, pulses when live); `done` = passed (filled);
+// `complete` = the terminal "finished" marker (filled + check); `warning` = an
+// issue at a reached step.
+export type StepStatus = "upcoming" | "current" | "done" | "warning" | "complete";
+export type StepOrientation = "horizontal" | "vertical";
+
+const reached = (s: StepStatus) => s !== "upcoming";
+
+interface StepperConfig {
+  orientation: StepOrientation;
+  color: string;
+  /** Pulse the current node — signals an actively-running sequence (an agent
+   *  run streaming its steps). Off for a static wizard/checklist. */
+  live: boolean;
+}
+const StepperContext = createContext<StepperConfig>({ orientation: "horizontal", color: colors.zinc[900], live: false });
 
 export interface StepperProps {
-  /** Ordered step labels, left → right. */
-  steps: string[];
-  /** Index of the in-progress step; lower indices render complete. */
-  current: number;
-  /** Accent for the completed track, current ring, and current label.
-   *  Defaults to the neutral ink — pass a brand color to theme it. */
+  /** Compound form: `<Stepper><Step status>…</Step></Stepper>` — swappable content. */
+  children?: ReactNode;
+  /** Data form: ordered labels; `current` derives each step's status. Ignored when `children` is set. */
+  steps?: string[];
+  current?: number;
+  orientation?: StepOrientation;
+  live?: boolean;
+  /** Accent ink for reached nodes + the connecting track. Defaults to neutral ink. */
   color?: string;
   accessibilityLabel?: string;
 }
 
-function statusOf(index: number, current: number): StepStatus {
-  if (index < current) return "done";
-  if (index === current) return "current";
-  return "upcoming";
+interface StepPositional {
+  _last?: boolean;
+  _leftFilled?: boolean;
+  _rightFilled?: boolean;
+}
+
+export interface StepProps extends StepPositional {
+  status: StepStatus;
+  children: ReactNode;
+  /** Make the step navigable; the active one holds a wash so a panel can sit beside it (vertical). */
+  onPress?: () => void;
+  active?: boolean;
+  accessibilityLabel?: string;
 }
 
 /**
- * Full-width wizard/milestone header — a row of labeled milestones with
- * completed, current, and upcoming states and a connecting track. Every
- * label is visible; use it where the journey itself is the headline (a
- * record detail, a checkout). At card/list density use `StepProgress`
- * (segments + built-in caption) instead. For a vertical event log use
- * `Timeline`.
+ * Progress through an ordered sequence — done · current · upcoming on a
+ * connecting track (horizontal) or spine (vertical). The node encodes STATUS,
+ * not identity: a filled dot once reached, a ring with a white centre at the
+ * current step (pulsing when `live`), a faint ring for what's ahead, a check for
+ * the terminal `complete`. Drive it the compound way (`<Step status>` children —
+ * the label is yours to compose) or the data way (`steps` + `current`). For a
+ * heterogeneous event LOG with per-row icons + expandable details use `Timeline`;
+ * for a compact stage bar use `StepProgress`.
  */
 export function Stepper(props: StepperProps) {
-  const { steps, current, color = colors.zinc[900], accessibilityLabel } = props;
-  const last = steps.length - 1;
-  const safe = Math.max(0, Math.min(current, last));
-  const a11y = accessibilityLabel ?? `Step ${safe + 1} of ${steps.length}: ${steps[safe] ?? ""}`;
+  const { children, steps, current, orientation = "horizontal", live = false, color = colors.zinc[700], accessibilityLabel } = props;
+
+  const content: ReactNode =
+    children ??
+    (steps ?? []).map((label, i) => {
+      const status: StepStatus = current == null ? "upcoming" : i < current ? "done" : i === current ? "current" : "upcoming";
+      const isCurrent = status === "current";
+      return (
+        <Step key={label} status={status}>
+          <Text size="xs" color={isCurrent ? "default" : "muted"} weight={isCurrent ? "semibold" : "regular"} style={isCurrent ? { color } : undefined}>
+            {label}
+          </Text>
+        </Step>
+      );
+    });
+
+  const items = Children.toArray(content).filter((c): c is ReactElement<StepProps> => isValidElement(c));
+  const statuses = items.map((c) => c.props.status);
+  const last = items.length - 1;
+  const a11y = accessibilityLabel ?? "Progress";
+
+  const positioned = items.map((child, i) =>
+    cloneElement(child, {
+      _last: i === last,
+      _leftFilled: i > 0 && reached(statuses[i - 1]),
+      _rightFilled: i < last && reached(statuses[i]),
+    }),
+  );
 
   return (
-    <View
-      accessibilityRole="progressbar"
-      accessibilityLabel={a11y}
-      style={{ flexDirection: "row" }}
-    >
-      {steps.map((label, i) => {
-        const status = statusOf(i, current);
-        const leftFilled = i <= current && i > 0;
-        const rightFilled = i < current && i < last;
-        const isCurrent = status === "current";
-        return (
-          <View key={label} style={{ flex: 1, alignItems: "center", gap: 8 }}>
-            <View style={{ flexDirection: "row", alignItems: "center", width: "100%" }}>
-              <View style={{ flex: 1, height: 2, backgroundColor: leftFilled ? color : colors.zinc[200] }} />
-              <StepDot status={status} color={color} />
-              <View style={{ flex: 1, height: 2, backgroundColor: rightFilled ? color : colors.zinc[200] }} />
-            </View>
-            <Text
-              size="xs"
-              color={isCurrent ? "default" : "muted"}
-              weight={isCurrent ? "semibold" : "regular"}
-              style={isCurrent ? { color } : undefined}
-            >
-              {label}
-            </Text>
-          </View>
-        );
-      })}
-    </View>
+    <StepperContext.Provider value={{ orientation, color, live }}>
+      <View accessibilityRole="progressbar" accessibilityLabel={a11y} style={orientation === "horizontal" ? styles.hRow : undefined}>
+        {positioned}
+      </View>
+    </StepperContext.Provider>
   );
 }
 
-function StepDot({ status, color }: { status: StepStatus; color: string }) {
-  if (status === "done") {
-    return <Icon name="circle-check" size={16} color={color} />;
+export function Step(props: StepProps) {
+  const { status, children, onPress, active, accessibilityLabel, _last, _leftFilled, _rightFilled } = props;
+  const { orientation, color, live } = useContext(StepperContext);
+
+  if (orientation === "horizontal") {
+    return (
+      <View style={styles.hStep}>
+        <View style={styles.hTrackRow}>
+          <View style={[styles.hTrack, { backgroundColor: _leftFilled ? color : colors.zinc[200] }]} />
+          <Marker status={status} color={color} live={live} />
+          <View style={[styles.hTrack, { backgroundColor: _rightFilled ? color : colors.zinc[200] }]} />
+        </View>
+        <View style={styles.hLabel}>{children}</View>
+      </View>
+    );
   }
+
+  const body = <View style={[styles.vRowBox, active ? styles.vActive : null]}>{children}</View>;
+  // Each step rises + fades into place on mount — so a streamed feed reads as
+  // steps APPEARING, not popping in. Animates once (on mount); a status change
+  // (current → done) re-renders without re-animating.
   return (
-    <View
-      style={{
-        width: 16,
-        height: 16,
-        borderRadius: 8,
-        backgroundColor: colors.white,
-        borderWidth: status === "current" ? 3 : 1.5,
-        borderColor: status === "current" ? color : colors.zinc[300],
-      }}
-    />
+    <AnimationFadeIn translateY={6}>
+      <View style={styles.vItem}>
+        <View style={styles.vSpineCol}>
+          <Marker status={status} color={color} live={live} />
+          {!_last ? <View style={[styles.vSpine, { backgroundColor: reached(status) ? colors.zinc[300] : colors.zinc[200] }]} /> : null}
+        </View>
+        <View style={[styles.vContent, !_last ? styles.vGap : null]}>
+          {onPress ? (
+            <PressableHighlight onPress={onPress} accessibilityRole="button" accessibilityLabel={accessibilityLabel} style={styles.vPress}>
+              {body}
+            </PressableHighlight>
+          ) : (
+            body
+          )}
+        </View>
+      </View>
+    </AnimationFadeIn>
   );
 }
+
+// The node — status drives fill, never size. Monochrome: reached fills with ink,
+// the current step is a ring around white (pulsing when live), what's ahead is a
+// faint grey ring, the terminal is a checked fill.
+function Marker({ status, color, live }: { status: StepStatus; color: string; live: boolean }) {
+  if (status === "done") {
+    // A passed step: filled in the accent ink with a white check.
+    return (
+      <View style={[styles.disc, { backgroundColor: color }]}>
+        <Icon name="check" size={10} color={colors.white} />
+      </View>
+    );
+  }
+  if (status === "complete") {
+    // The terminal "Done" — a blackish ring with a white centre and a black check.
+    return (
+      <View style={[styles.disc, { backgroundColor: colors.white, borderWidth: 2, borderColor: colors.zinc[900] }]}>
+        <Icon name="check" size={10} color={colors.zinc[900]} />
+      </View>
+    );
+  }
+  if (status === "warning") {
+    return (
+      <View style={[styles.disc, { backgroundColor: solid("amber") }]}>
+        <View style={styles.shortBar} />
+      </View>
+    );
+  }
+  if (status === "current") {
+    return (
+      <View style={styles.discWrap}>
+        {live ? <Pulse color={color} /> : null}
+        <View style={[styles.disc, { backgroundColor: colors.white, borderWidth: 2.5, borderColor: color }]} />
+      </View>
+    );
+  }
+  return <View style={[styles.disc, { backgroundColor: colors.white, borderWidth: 1.5, borderColor: colors.zinc[300] }]} />;
+}
+
+// An expanding, fading halo behind the current node — the "live" pulse.
+function Pulse({ color }: { color: string }) {
+  const v = useRef(new Animated.Value(0)).current;
+  useEffect(() => {
+    const loop = Animated.loop(Animated.timing(v, { toValue: 1, duration: 1500, useNativeDriver: false }));
+    loop.start();
+    return () => loop.stop();
+  }, [v]);
+  const transform = [{ scale: v.interpolate({ inputRange: [0, 1], outputRange: [1, 2.2] }) }];
+  const opacity = v.interpolate({ inputRange: [0, 1], outputRange: [0.35, 0] });
+  return <Animated.View style={[styles.pulse, { borderColor: color, transform, opacity }]} />;
+}
+
+const NODE = 18;
+
+const styles = StyleSheet.create({
+  hRow: { flexDirection: "row" },
+  hStep: { flex: 1, alignItems: "center", gap: 8 },
+  hTrackRow: { flexDirection: "row", alignItems: "center", width: "100%" },
+  hTrack: { flex: 1, height: 2 },
+  hLabel: { alignItems: "center" },
+
+  vItem: { flexDirection: "row", gap: 12 },
+  vSpineCol: { width: NODE, alignItems: "center", paddingTop: 3 },
+  vSpine: { width: 1.5, flex: 1, minHeight: 14, borderRadius: 1, marginTop: 4 },
+  vContent: { flex: 1 },
+  vGap: { paddingBottom: 12 },
+  vPress: { borderRadius: 8, marginHorizontal: -10 },
+  vRowBox: { borderRadius: 8, paddingHorizontal: 10, paddingVertical: 2 },
+  vActive: { backgroundColor: colors.zinc[100] },
+
+  discWrap: { width: NODE, height: NODE, alignItems: "center", justifyContent: "center" },
+  disc: { width: NODE, height: NODE, borderRadius: NODE / 2, alignItems: "center", justifyContent: "center" },
+  pulse: { position: "absolute", width: NODE, height: NODE, borderRadius: NODE / 2, borderWidth: 2, pointerEvents: "none" },
+  shortBar: { width: 8, height: 2, borderRadius: 1, backgroundColor: colors.white },
+});

package/src/step_list.tsx

@@ -1,128 +0,0 @@
-import { ReactNode } from "react";
-import { StyleSheet, View } from "react-native";
-import { colors, solid } from "./colors";
-import { Text } from "./text";
-import { Icon } from "./icon";
-import { PressableHighlight } from "./pressable_highlight";
-
-export type StepStatus = "pending" | "current" | "done" | "warning";
-
-export interface StepListItem {
-  id: string;
-  status: StepStatus;
-  /** Primary line — a stage, a code, a name. */
-  title: string;
-  /** Secondary muted line. */
-  subtitle?: string;
-  /** Right-aligned node — a count, a `Badge`, a time. */
-  trailing?: ReactNode;
-}
-
-export interface StepListProps {
-  steps: StepListItem[];
-  /** When set, steps become pressable to navigate; the matching step is held
-   *  highlighted so its panel can be shown elsewhere. */
-  selectedId?: string;
-  onStepPress?: (id: string) => void;
-  accessibilityLabel?: string;
-}
-
-/**
- * A vertical step sequence on a connecting spine — done · now · up next — for a
- * guided run, a staged process, a checklist. Every status is the SAME 20px node
- * (filled once reached, hollow while pending), so the spine reads as one line no
- * matter which statuses appear or in what order. Unlike `Stepper` (horizontal) or
- * `StepProgress` (a bar), and unlike `Timeline` (past events only), it models
- * future/pending steps. Pass `onStepPress` to make the steps NAVIGABLE — the
- * selected step is held highlighted so the host can show its panel beside the list.
- */
-export function StepList(props: StepListProps) {
-  const { steps, selectedId, onStepPress, accessibilityLabel } = props;
-  return (
-    <View accessibilityLabel={accessibilityLabel}>
-      {steps.map((s, i) => {
-        // The focused step: the navigated one when navigable, else "now".
-        const active = selectedId != null ? s.id === selectedId : s.status === "current";
-        const past = s.status === "done" || s.status === "warning";
-        const content = (
-          <View style={styles.contentRow}>
-            <View style={{ flex: 1, gap: 1 }}>
-              <Text size="sm" weight={active ? "medium" : "regular"} color={past && !active ? "muted" : "default"}>
-                {s.title}
-              </Text>
-              {s.subtitle ? (
-                <Text size="xs" color="muted" numberOfLines={1}>{s.subtitle}</Text>
-              ) : null}
-            </View>
-            {s.trailing}
-          </View>
-        );
-        return (
-          <View key={s.id} style={styles.item}>
-            <View style={styles.spineCol}>
-              <Marker status={s.status} />
-              {i < steps.length - 1 ? <View style={styles.spine} /> : null}
-            </View>
-            <View style={[styles.contentCol, i < steps.length - 1 ? styles.contentGap : null]}>
-              {onStepPress ? (
-                <PressableHighlight onPress={() => onStepPress(s.id)} style={[styles.rowBox, active ? styles.active : null]}>
-                  {content}
-                </PressableHighlight>
-              ) : (
-                <View style={[styles.rowBox, active ? styles.active : null]}>{content}</View>
-              )}
-            </View>
-          </View>
-        );
-      })}
-    </View>
-  );
-}
-
-/** One uniform 20px node; status drives fill, not size or shape. */
-function Marker({ status }: { status: StepStatus }) {
-  if (status === "pending") {
-    return <View style={[styles.disc, styles.discPending]} />;
-  }
-  if (status === "current") {
-    return (
-      <View style={[styles.disc, { backgroundColor: solid("blue") }]}>
-        <View style={styles.currentDot} />
-      </View>
-    );
-  }
-  if (status === "warning") {
-    return (
-      <View style={[styles.disc, { backgroundColor: solid("amber") }]}>
-        <View style={styles.shortBar} />
-      </View>
-    );
-  }
-  return (
-    <View style={[styles.disc, { backgroundColor: solid("emerald") }]}>
-      <Icon name="check" size={12} color={colors.background} />
-    </View>
-  );
-}
-
-const NODE = 20;
-
-const styles = StyleSheet.create({
-  item: { flexDirection: "row", gap: 12 },
-  // paddingTop pairs with rowBox.paddingVertical so the node centres on the
-  // FIRST line of content, not on a multi-line block.
-  spineCol: { width: NODE, alignItems: "center", paddingTop: 4 },
-  disc: { width: NODE, height: NODE, borderRadius: NODE / 2, alignItems: "center", justifyContent: "center" },
-  discPending: { backgroundColor: colors.background, borderWidth: 1.5, borderColor: colors.zinc[300] },
-  currentDot: { width: 7, height: 7, borderRadius: 999, backgroundColor: colors.background },
-  shortBar: { width: 8, height: 2, borderRadius: 1, backgroundColor: colors.background },
-  spine: { width: 1.5, flex: 1, minHeight: 14, borderRadius: 1, backgroundColor: colors.zinc[200], marginTop: 4 },
-  contentCol: { flex: 1 },
-  // The inter-step gap — on every step but the last, so the list ends flush and
-  // a container's own padding isn't doubled at the bottom.
-  contentGap: { paddingBottom: 12 },
-  contentRow: { flexDirection: "row", alignItems: "flex-start", gap: 12, flex: 1 },
-  // press + plain share one box so the active wash looks identical either way.
-  rowBox: { borderRadius: 8, paddingHorizontal: 10, paddingVertical: 4, marginHorizontal: -10, flexDirection: "row", alignItems: "flex-start" },
-  active: { backgroundColor: colors.zinc[100] },
-});