@lotics/ui 14.0.0 → 14.1.0

package/docs/ai_patterns.md

@@ -136,6 +136,13 @@ move on, so the feed doesn't dramatize it. A BREAKING error that terminates the
 OUTSIDE `parts` (chat persists it in the message's `errors`; `useAgentRun().error` carries it) —
 pass it as the `error` prop and it renders as a terminal danger row under the transcript.
 
+**In a bounded container, wrap it in `FollowScroll`.** An `AgentRun` streaming inside a dialog,
+drawer, or fixed-height panel grows BELOW the fold — a plain scroll container doesn't follow. Wrap
+the feed: `<FollowScroll style={{ maxHeight: … }}><AgentRun … /></FollowScroll>` — pinned to the
+newest content while streaming, unpinned when the human scrolls up to read (`AgentProgress`'s
+expanded panel already does this). A full-page inverted list (chat) follows by construction and
+doesn't need it.
+
 Fed natively by `@lotics/app-sdk`'s `useAgentRun().parts` (reasoning + per-tool I/O + state come
 for free — no hand-assembly): `<AgentRun parts={run.parts} state={…} error={run.error} />` — see
 [the SDK doc](../../app-sdk/docs/ai.md) for the hook. Requires `ai` as an optional (type-only) peer.
@@ -268,7 +275,7 @@ reads as the custom answer).
 
 `ClarifyWizard` (`@lotics/ui/clarify_wizard`): a SEQUENCE of clarify questions worked one at a time —
 Back / Next / Cancel / Submit (Next/Submit primary), the step position an eyebrow ("1 / 3") above the
-question — no progress bar. Each step is a `Clarify`; advance only once the
+question — no progress bar, and no eyebrow at all for a single question. Each step is a `Clarify`; advance only once the
 current question is answered; `onSubmit` gives one `{ value, custom }` per question (aligned by index,
 `custom` true when the answer came from "Other…"), `onCancel` dismisses. All navigation chrome is
 locale-wired (the `clarify` slice). The multi-question form of the ask-back.

package/docs/catalog.md

@@ -976,6 +976,11 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `AgentRun` and `AgentProgress`. The sole file permitted to `import type` from `ai`.
 - **`agent_progress`** — `AgentProgress`: `AgentRun`'s compact, floating, expandable form (same
   `parts` prop) — a composer's working state.
+- **`follow_scroll`** — `FollowScroll`: a scroll container that FOLLOWS its growing content —
+  pinned to the bottom as children stream in; scrolling up unpins (read history), scrolling back
+  re-pins. Wrap a streaming `AgentRun` with it in any bounded container (a dialog, a drawer,
+  a panel — put the height bound on `style`); `AgentProgress`'s expanded panel uses it. Chat
+  doesn't need it (an inverted message list follows by construction).
 - **`confidence`** — `Confidence` + `ConfidenceLevel` + `levelFromScore`: calibrated
   high/med/low; localized via the provider.
 - **`change_review`** — the COMPOUND review family — frame: `ChangeReview` provider/stack ·
@@ -995,7 +1000,8 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `{ value, label, description }` — the description is MANDATORY (every answer explains itself).
   `allowCustom` adds an always-visible borderless multiline custom-answer field below the options.
 - **`clarify_wizard`** — `ClarifyWizard` + `ClarifyWizardQuestion`/`ClarifyWizardAnswer`: a SEQUENCE
-  of `Clarify` questions with Back/Next/Cancel/Submit + a `n / total` position indicator; advance
+  of `Clarify` questions with Back/Next/Cancel/Submit + a `n / total` position indicator (omitted
+  for a single question); advance
   only when the current is answered, `onSubmit` returns one `{ value, custom }` per question.
   Navigation chrome is locale-wired (the `clarify` locale slice).
 - **`choice_list`** — `ChoiceList` + `ChoiceOption`: selectable answer options as

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "14.0.0",
+  "version": "14.1.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -80,6 +80,7 @@
     "./activity_indicator": "./src/activity_indicator.tsx",
     "./agent_run": "./src/agent_run.tsx",
     "./agent_progress": "./src/agent_progress.tsx",
+    "./follow_scroll": "./src/follow_scroll.tsx",
     "./markdown": {
       "react-native": "./src/markdown.tsx",
       "default": "./src/markdown.web.tsx"

package/src/agent_progress.tsx

@@ -1,8 +1,9 @@
 import { useState } from "react";
-import { ScrollView, StyleSheet, View } from "react-native";
+import { StyleSheet, View } from "react-native";
 import { colors } from "./colors";
 import { Text } from "./text";
 import { WaveAvatar } from "./wave_avatar";
+import { FollowScroll } from "./follow_scroll";
 import { PressableHighlight } from "./pressable_highlight";
 import { AgentRun, resolveToolMeta } from "./agent_run";
 import { toSegments, lastRunningStep, type AgentUIPart } from "./agent_transform";
@@ -46,9 +47,11 @@ export function AgentProgress(props: AgentProgressProps) {
     <View style={{ gap: 8 }}>
       {expanded ? (
         <View style={styles.panel}>
-          <ScrollView style={{ maxHeight: 260 }} contentContainerStyle={{ padding: 16 }}>
+          {/* FollowScroll keeps the newest step in view as the run streams —
+              a plain ScrollView would let new content grow below the fold. */}
+          <FollowScroll style={{ maxHeight: 260 }} contentContainerStyle={{ padding: 16 }}>
             <AgentRun parts={parts} state={state} error={error} labelForTool={labelForTool} stepsLabel={stepsLabel} />
-          </ScrollView>
+          </FollowScroll>
         </View>
       ) : null}
 

package/src/clarify_wizard.tsx

@@ -64,10 +64,11 @@ export function ClarifyWizard(props: ClarifyWizardProps) {
 
   return (
     <View style={{ gap: 16 }}>
-      {/* The step position is an eyebrow above the question (no progress bar); the
-          footer aligns to the same 8px inset as the question and answers. Keyed by
-          index so each step's custom-answer draft is its own (no bleed across steps). */}
-      <Clarify key={index} eyebrow={`${index + 1} / ${total}`} question={q.question} options={q.answers} answer={current} onAnswer={setAnswer} allowCustom={q.allowCustom} />
+      {/* The step position is an eyebrow above the question (no progress bar — and
+          none at all for a single question); the footer aligns to the same 8px inset
+          as the question and answers. Keyed by index so each step's custom-answer
+          draft is its own (no bleed across steps). */}
+      <Clarify key={index} eyebrow={total > 1 ? `${index + 1} / ${total}` : undefined} question={q.question} options={q.answers} answer={current} onAnswer={setAnswer} allowCustom={q.allowCustom} />
       <View style={{ flexDirection: "row", alignItems: "center", justifyContent: "space-between", gap: 8, paddingHorizontal: 8 }}>
         <Button title={labels.cancel} color="muted" onPress={onCancel} />
         <View style={{ flexDirection: "row", gap: 8 }}>

package/src/follow_scroll.tsx

@@ -0,0 +1,58 @@
+import { useRef, type ReactNode } from "react";
+import { ScrollView, StyleProp, ViewStyle, type NativeScrollEvent, type NativeSyntheticEvent } from "react-native";
+
+export interface FollowScrollProps {
+  children: ReactNode;
+  /** The frame — put the height bound here (`maxHeight` / `height` / `flex`);
+   *  without one the container never overflows and there is nothing to follow. */
+  style?: StyleProp<ViewStyle>;
+  contentContainerStyle?: StyleProp<ViewStyle>;
+}
+
+// "At the bottom" tolerance: within this many px of the end still counts as
+// pinned, so sub-pixel scroll positions and streaming-growth rounding never
+// silently unpin the follow.
+const PIN_THRESHOLD = 40;
+
+/**
+ * A scroll container that FOLLOWS its growing content — pinned to the bottom, it
+ * keeps the newest content in view as children stream in (an `AgentRun` in a
+ * dialog, a log feed). Scrolling up UNPINS it so the human can read history while
+ * the content keeps growing; scrolling back to the bottom re-pins. Chat doesn't
+ * need this (its message list is inverted, which follows by construction) — this
+ * is for the plain top-down containers everywhere else: dialogs, drawers, panels.
+ */
+export function FollowScroll(props: FollowScrollProps) {
+  const { children, style, contentContainerStyle } = props;
+  const scrollRef = useRef<ScrollView>(null);
+  // Pinned state lives in a ref — it changes on every scroll tick and must never
+  // re-render the (streaming, already-busy) subtree.
+  const pinnedRef = useRef(true);
+
+  const followIfPinned = () => {
+    if (pinnedRef.current) scrollRef.current?.scrollToEnd({ animated: false });
+  };
+
+  const onScroll = (e: NativeSyntheticEvent<NativeScrollEvent>) => {
+    const { contentOffset, contentSize, layoutMeasurement } = e.nativeEvent;
+    const distanceFromBottom = contentSize.height - contentOffset.y - layoutMeasurement.height;
+    pinnedRef.current = distanceFromBottom < PIN_THRESHOLD;
+  };
+
+  return (
+    <ScrollView
+      ref={scrollRef}
+      style={style}
+      contentContainerStyle={contentContainerStyle}
+      // Content grew (a new part streamed in) or the frame resized (dialog
+      // re-measured) — both move the bottom edge, so both re-follow when pinned.
+      onContentSizeChange={followIfPinned}
+      onLayout={followIfPinned}
+      onScroll={onScroll}
+      scrollEventThrottle={16}
+      nestedScrollEnabled
+    >
+      {children}
+    </ScrollView>
+  );
+}