@lotics/ui 46.1.0 → 46.2.0

package/docs/ai_patterns.md

@@ -177,8 +177,15 @@ PUT and rolls the calls out BELOW it on press.
 
 **ONE row for the whole run, and NO prose until it ends.** While the agent works, the entire feed
 is a single row. It names the call in flight — "Searching records" — and says
-**"Thinking…"** whenever the model is writing rather than calling, which is every gap between
-calls. The dot pulses; nothing rolls out unless the reader asks.
+**"Thinking"** whenever the model is writing rather than calling, which is every gap between
+calls. Nothing rolls out unless the reader asks.
+
+**An unsettled row BREATHES**, label and dot together — the label on the same opacity rhythm the
+dot's halo runs (750ms each way), so one line carries one animation rather than two that drift
+apart. That breath is what says "in progress", which is why no live label ends in an ellipsis:
+punctuation was standing in for motion, and a screen reader drops it anyway. A row that is not
+working does not breathe — settled, and `awaiting` a human decision, which is parked rather than
+in flight.
 
 **No step count.** The row says WHAT is happening and stops there. A tally was a number the reader
 could act on in no way: live, the label already changes on every call, so it added no motion the
@@ -208,12 +215,14 @@ reasoning part. An interleaved-thinking run therefore rebuilt the stack one grou
 reader watched finished rows pile up while they waited, and was then left with that pile sitting
 above the answer at the answer's weight, every row of it stale.
 
-**Expanding is where live and settled differ, and the only place they do.** Opened mid-run the
-timeline is CAPPED and self-pinning (220px, ~5 rows) — someone who opens a run in flight asked to
-see the work, not to hand the page a feed that grows for another minute; `FollowScroll` follows at
-LAYOUT level so each call paints already pinned. Opened once settled it is uncapped: nothing is
-arriving, so there is nothing to cap. Settling never closes what a reader opened; it just stops
-capping it.
+**Expanding works the same live and settled** — the timeline opens IN FULL, and the HOST'S OWN
+scroller keeps the newest row in view. `AgentRun` never frames itself. It shipped once with a
+live-only 220px window, and that window was a scroll container nested inside whatever scroll
+container the run already sat in: in chat, an inverted list inside an inverted list, which painted
+stale content over the neighbouring messages and took the wheel from the surface the reader was
+on. A component in document flow cannot know whether it is inside a scroller, so it must not act
+as one. A host that genuinely needs a bound takes the framing job itself — `collapseProcess={false}`
+plus its own `FollowScroll`. Settling never closes what a reader opened.
 
 The split is POSITIONAL (`splitTimeline` in `agent_transform`): what comes after the last tool
 call is the answer, everything before it is the work. Nothing has to decide whether a paragraph
@@ -261,10 +270,10 @@ tinted panel rather than another step row, and it carries `role="alert"` so a sc
 action (a secondary `Button`) sits INSIDE that panel so the operator can re-fire the run; omit it
 and the panel carries the message alone.
 
-**`FollowScroll` — only when you took the job (`collapseProcess={false}`).** A run opened mid-flight
-already caps itself with exactly this, so wrapping the default AGAIN nests a scroller in a
-scroller: the outer never overflows, the inner holds the content, and the wheel lands on whichever
-the pointer happens to be over. Reach for the wrapper when the run is a raw timeline you are
+**`FollowScroll` — only when you took the job (`collapseProcess={false}`).** On the default, the
+run is plain content in your flow and your own scroller follows it; adding a wrapper there nests a
+scroller in a scroller — the outer never overflows, the inner holds the content, and the wheel
+lands on whichever the pointer happens to be over. Reach for the wrapper when the run is a raw timeline you are
 framing yourself — a dialog, drawer, or fixed-height panel where the feed grows BELOW the fold and
 a plain scroll container doesn't follow. Wrap it then:
 `<FollowScroll style={{ maxHeight: … }}><AgentRun … collapseProcess={false} /></FollowScroll>` — the same
@@ -281,7 +290,7 @@ for free — no hand-assembly): `<AgentRun parts={run.parts} state={…} error={
 [the SDK doc](../../app-sdk/docs/ai.md) for the hook. The `ai` package is a regular dependency of
 `@lotics/ui` — its part TYPES resolve transitively in any consumer's typecheck with nothing to
 install; the imports are type-only (purity-enforced), so no `ai` runtime ever enters a bundle.
-**A run with no parts yet renders the breathing "Starting…" row** (streaming state only) — the
+**A run with no parts yet renders the breathing "Starting" row** (streaming state only) — the
 live dot plus a label that pulses, covering the gap between the CTA press and the first streamed
 part (upload + run creation + first token). **The law: pass
 `state="streaming"` from the moment the paid CTA fires — uploads included — and render
@@ -518,7 +527,7 @@ whole pane with no backend ([`tpl_item_list`](../examples/tpl_item_list.tsx) doe
 
 **Customize through the seams, or drop to the primitives.** `labelForCall` / `renderToolOutput`
 pass through to `AgentRun`; the `run` object is the data seam. There is deliberately NO
-empty-state slot — `AgentRun` renders its own localized "Starting…" row on zero parts, and the law
+empty-state slot — `AgentRun` renders its own localized "Starting" row on zero parts, and the law
 above forbids hand-rolling a placeholder. An app that wants a different ARRANGEMENT does not fight
 the pane: `AgentRun`, `ClarifyWizard`, `ClarifyWizardScope`/`Actions`, `FollowScroll` and
 `DialogScrollArea` all remain exported, and composing them is what this pane itself does.

package/docs/catalog.md

@@ -2094,13 +2094,15 @@ component rather than showing it at zero.
   hatch — input/error untouched). A per-tool failure shows amber with the reason in its expanded
   Error panel; a run-level breaking `error` (outside `parts`) renders as a terminal danger row, with
   an optional `onRetry` Button under it. While it runs the whole feed is ONE row and NO prose: the
-  row names the call in flight ("Searching records") and says "Thinking…" whenever the
-  model is writing rather than calling. The agent's between-call narration is never shown — the one
+  row names the call in flight ("Searching records") and says "Thinking" whenever the
+  model is writing rather than calling; an unsettled row BREATHES, label and dot on one rhythm,
+  which is why no live label carries an ellipsis (a row that is parked `awaiting` does not breathe). The agent's between-call narration is never shown — the one
   message needing a response is a bulk-mutation confirmation, and the agent waits there, so the run
   stops and that text becomes the answer. A reply with no tool calls is all answer and still streams.
-  At settle the work folds to "{last action}" with the answer below. Expanding is the one
-  place live and settled differ: opened mid-run the timeline is capped and self-pinning (220px),
-  opened settled it is uncapped. Stays fully open while a call is parked, when a SETTLED run ended on
+  At settle the work folds to "{last action}" with the answer below. Expanding opens the timeline
+  IN FULL, live or settled — the run never frames itself, and the HOST'S scroller follows it (a
+  self-imposed window nests a scroller inside the host's own, which in chat means an inverted list
+  inside an inverted list). Stays fully open while a call is parked, when a SETTLED run ended on
   a tool call, and when the work is already one row. `collapseProcess={false}` hands the job back to
   the caller (a surface that already frames the run — it then owns the `FollowScroll` too);
   `summarizeRun(steps)` renames the row.
@@ -2134,7 +2136,8 @@ component rather than showing it at zero.
   the chat message list's inverted mechanism packaged as a wrapper (single-cell inverted list),
   so the follow happens at LAYOUT level: each growth paints already pinned (no flash), scrolling
   up releases it, and short content still reads top-down. Wrap a streaming `AgentRun` with it in
-  any bounded container (a dialog, a drawer, a panel — put the height bound on `style`);
+  any bounded container (a dialog, a drawer, a panel — put the height bound on `style`) — but ONLY
+  one you framed yourself with `collapseProcess={false}`, or it nests a scroller in a scroller;
   `AgentProgress`'s expanded panel uses it. Inherits the inverted pattern's quirks (scrollbar
   thumb runs opposite; keyboard paging inverted) — same as chat. A full-page chat list is
   already inverted and doesn't need it.
@@ -2231,7 +2234,7 @@ component rather than showing it at zero.
   or test DECLARES one rather than mapping from `ClarifyWizardQuestion` (an option is a label +
   description; the answer's value IS the label, the `ask_user_choice` wire shape). Seams:
   `labelForCall` / `renderToolOutput`; no empty-state slot by design (`AgentRun` owns the
-  localized "Starting…" row). Worked example: `tpl_item_list`'s intake dialog.
+  localized "Starting" row). Worked example: `tpl_item_list`'s intake dialog.
 - **`choice_list`** — `ChoiceList` + `ChoiceOption`: selectable answer options as
   divider-separated rows (no bordered cards) with a per-row focus ring + hover wash; the
   agent's quick-reply surface. `allowCustom` appends an always-visible borderless multiline field whose

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "46.1.0",
+  "version": "46.2.0",
   "type": "module",
   "exports": {
     "./vite": {

package/src/agent_run.tsx

@@ -8,7 +8,6 @@ import { Callout, CalloutActions, CalloutText } from "./callout";
 import { Markdown } from "./markdown";
 import { JsonPanel, stringifyData } from "./json_panel";
 import { PressableHighlight } from "./pressable_highlight";
-import { FollowScroll } from "./follow_scroll";
 import { Marker, type StepStatus } from "./stepper";
 import { NODE } from "./stepper_layout";
 import { AnimationFadeIn } from "./animation_fade_in";
@@ -86,7 +85,7 @@ export interface AgentRunProps {
 // ── Tool → display meta ───────────────────────────────────────────────────────
 // The ICON per platform tool. The LABEL lives in the locale (`agentRun.tools`)
 // because it is language, and this component already renders localized chrome
-// around these rows — an English tool row under a Vietnamese "Đang suy nghĩ…"
+// around these rows — an English tool row under a Vietnamese "Đang suy nghĩ"
 // was the kit contradicting itself. An icon is not language, so it stays here.
 // A tool neither map knows falls back to a prettified name + a neutral icon.
 const TOOL_ICONS: Record<string, IconName> = {
@@ -149,6 +148,37 @@ function stepLabel(
 
 const INK = colors.zinc[700];
 
+// The "still working" breath, and the ONE rhythm every unsettled row shares.
+// Half-cycle 750ms — so a full breath is the 1500ms the `Marker`'s live halo
+// already runs, and a row's dot and its label breathe together instead of
+// drifting apart into two unrelated animations on one line. The floor is
+// `Skeleton`'s: the kit says "in progress" with an opacity rhythm, in one
+// vocabulary, whether the thing pulsing is a placeholder tile or a live label.
+const BREATH_HALF = 750;
+const BREATH_FLOOR = 0.6;
+
+/** Breathe `children` while the work behind them is unsettled. Settled, it
+ *  holds full opacity and runs no animation — a finished row is not working,
+ *  and neither is one parked `awaiting` a human decision. */
+function Breathing({ active, children }: { active: boolean; children: ReactNode }) {
+  const v = useRef(new Animated.Value(1)).current;
+  useEffect(() => {
+    if (!active) {
+      v.setValue(1);
+      return;
+    }
+    const loop = Animated.loop(
+      Animated.sequence([
+        Animated.timing(v, { toValue: BREATH_FLOOR, duration: BREATH_HALF, useNativeDriver: true }),
+        Animated.timing(v, { toValue: 1, duration: BREATH_HALF, useNativeDriver: true }),
+      ]),
+    );
+    loop.start();
+    return () => loop.stop();
+  }, [active, v]);
+  return <Animated.View style={{ opacity: v }}>{children}</Animated.View>;
+}
+
 /**
  * A live feed of an AI agent's work as a TIMELINE — the prose it streams and the
  * tools it calls, in the order they happened. While the agent is mid-tools the
@@ -197,9 +227,9 @@ export function AgentRun(props: AgentRunProps) {
   // answer, and hiding THAT behind a row until settle would be the real loss.
   //
   // SETTLED, the collapse covers the work and the answer stands below it.
-  // Expanding differs between the two, and only there: LIVE the timeline is
-  // capped and self-pinning (opening a run mid-flight must not hand the page a
-  // feed that grows for another minute), SETTLED it opens in full.
+  // Expanding is the same either way — the timeline opens IN FULL, and what
+  // keeps the newest row in view is the host's own scroller, which every host
+  // of a live run already has.
   //
   // The settled clauses are cases where collapsing would hide something needed:
   //  · no answer — the run stopped ON a tool call, so the fold would leave an
@@ -211,7 +241,7 @@ export function AgentRun(props: AgentRunProps) {
   const folded = managed && (streaming ? process.length > 0 : process.length > 1 && steps.length > 0 && result.length > 0);
 
   // What the row SAYS right now: the tool in flight, or — when the model is
-  // writing rather than calling — "Thinking…". Naming the last finished action
+  // writing rather than calling — "Thinking". Naming the last finished action
   // while the agent composes prose reports a moment that has passed.
   const thinking = streaming && !lastRunningStep(segments);
 
@@ -415,29 +445,19 @@ function StepRow({ s, label, renderToolOutput }: { s: AgentStep; label: string;
 
 // Thinking — a muted, COLLAPSED "Thinking" disclosure (revealed on press), so the
 // agent's reasoning never crowds the answer. Pulses while it's still streaming.
-/** The empty-live feed row: the live dot's halo plus a BREATHING label — the
- *  message itself pulses (Skeleton's opacity rhythm), so "work has started"
- *  reads at a glance even before the first token. */
+/** The empty-live feed row: the live dot's halo plus a BREATHING label, so
+ *  "work has started" reads at a glance even before the first token. */
 function StartingRow({ label }: { label: string }) {
-  const v = useRef(new Animated.Value(0.45)).current;
-  useEffect(() => {
-    const loop = Animated.loop(
-      Animated.sequence([
-        Animated.timing(v, { toValue: 1, duration: 700, useNativeDriver: false }),
-        Animated.timing(v, { toValue: 0.45, duration: 700, useNativeDriver: false }),
-      ]),
-    );
-    loop.start();
-    return () => loop.stop();
-  }, [v]);
   return (
     <View style={styles.row}>
       <View style={styles.dotCol}>
         <Marker status="current" color={colors.zinc[400]} live />
       </View>
-      <Animated.View style={[styles.rowBody, { opacity: v }]}>
-        <Text size="sm" color="muted">{label}</Text>
-      </Animated.View>
+      <View style={styles.rowBody}>
+        <Breathing active>
+          <Text size="sm" color="muted">{label}</Text>
+        </Breathing>
+      </View>
     </View>
   );
 }
@@ -452,9 +472,11 @@ function ReasoningDisclosure(props: { text: string; streaming?: boolean; expande
           <Marker status={streaming ? "current" : "done"} color={colors.zinc[400]} live={!!streaming} />
         </View>
         <View style={styles.rowBody}>
-          <Text size="sm" color="muted">
-            {streaming ? locale.agentRun.thinkingStreaming : locale.agentRun.thinking}
-          </Text>
+          <Breathing active={!!streaming}>
+            <Text size="sm" color="muted">
+              {streaming ? locale.agentRun.thinkingStreaming : locale.agentRun.thinking}
+            </Text>
+          </Breathing>
         </View>
         {chevron(expanded ? "up" : "down")}
       </PressableHighlight>
@@ -514,7 +536,7 @@ function WorkSummary(props: {
   const { steps, live, thinking, expanded, onToggle, labelForCall, summarizeRun, children } = props;
   const locale = useLoticsLocale();
   const final = steps[steps.length - 1];
-  // "Thinking…" WINS over a host summary while the model writes: `summarizeRun`
+  // "Thinking" WINS over a host summary while the model writes: `summarizeRun`
   // names what the run DID, and mid-compose that is a moment already past.
   const label = thinking
     ? locale.agentRun.thinkingStreaming
@@ -537,32 +559,30 @@ function WorkSummary(props: {
         trailing={chevron(expanded ? "up" : "down")}
       >
         {/* Keyed by what the row is SAYING, so a new call (or the switch to
-            "Thinking…") rises + fades into the SAME row — the label swaps, the
+            "Thinking") rises + fades into the SAME row — the label swaps, the
             row does not move. Exactly what a settled `ToolGroup` does mid-burst,
-            held for the whole run. */}
-        <AnimationFadeIn key={live ? label : "settled"} translateY={4}>
-          <SummaryLabel label={label} />
-        </AnimationFadeIn>
+            held for the whole run.
+            The breath sits OUTSIDE that key: inside it, the rhythm would restart
+            from full opacity on every label swap and fight the fade's own — two
+            animations writing one opacity. Outside, the row breathes steadily
+            for the whole run while its label changes underneath. */}
+        <Breathing active={live}>
+          <AnimationFadeIn key={live ? label : "settled"} translateY={4}>
+            <SummaryLabel label={label} />
+          </AnimationFadeIn>
+        </Breathing>
       </ActivityRow>
       {/* The run's own 10px rhythm, not the group's 2px: what rolls out here is
           whole segments — prose, thinking, tool groups — not sibling step rows.
-          Opened while the run is still LIVE it is also CAPPED and self-pinning:
-          a reader who opens a run mid-flight asked to see the work, not to hand
-          the page a feed that grows for another minute. `FollowScroll` follows at
-          LAYOUT level (an inverted single-cell list), so each new call paints
-          already pinned — no scroll-after-paint flash. Settled, it opens in full:
-          nothing is arriving, so there is nothing to cap. */}
-      {expanded ? (
-        live ? (
-          <View testID="agent-run-work-capped" style={styles.work}>
-            <FollowScroll style={styles.liveFrame}>
-              <View style={{ gap: 10 }}>{children}</View>
-            </FollowScroll>
-          </View>
-        ) : (
-          <View testID="agent-run-work" style={styles.work}>{children}</View>
-        )
-      ) : null}
+          It opens IN FULL, live or settled, and the HOST owns the scrolling. A
+          self-imposed window here was a scroller nested inside whatever scroller
+          the run already sits in — in chat, an inverted list inside an inverted
+          list — which paints stale content over its neighbours and captures the
+          wheel from the surface the reader is actually on. A component in
+          document flow cannot know whether it is inside a scroll container, so
+          it must not act as though it were one; a host that needs a bound frames
+          the run itself (`collapseProcess={false}` + `FollowScroll`). */}
+      {expanded ? <View testID="agent-run-work" style={styles.work}>{children}</View> : null}
     </View>
   );
 }
@@ -597,9 +617,11 @@ function ToolGroup(props: {
     return (
       <View style={styles.group}>
         <ActivityRow markerStatus="current" live>
-          <AnimationFadeIn key={current.id} translateY={4}>
-            <StepBody label={resolve(current)} />
-          </AnimationFadeIn>
+          <Breathing active>
+            <AnimationFadeIn key={current.id} translateY={4}>
+              <StepBody label={resolve(current)} />
+            </AnimationFadeIn>
+          </Breathing>
         </ActivityRow>
       </View>
     );
@@ -654,12 +676,6 @@ const styles = StyleSheet.create({
   // The folded work, opened: segment spacing (the run's own gap), and a small
   // lead-in under the header so the rolled-out work reads as its content.
   work: { gap: 10, paddingTop: 6 },
-  // The cap on work OPENED mid-run. ~5 rows: enough to read what is happening,
-  // short enough that opening a p90 94s run does not push the composer off the
-  // screen for the rest of it. No border and no background — the run sits flush
-  // in the consumer's gutter by law, and a frame that appeared only while
-  // streaming would be the loudest thing on the surface.
-  liveFrame: { maxHeight: 220 },
   row: {
     flexDirection: "row",
     alignItems: "center",

package/src/agent_run_pane.tsx

@@ -174,14 +174,16 @@ export function AgentRunPane<TLanding>(props: AgentRunPaneProps<TLanding>) {
     // 24` here is a fifth copy of a number that has to agree with four others.
     <FollowScroll contentContainerStyle={{ paddingBottom: 24, paddingHorizontal: gutter }}>
       {/* No empty-state slot on purpose. `AgentRun` renders its own breathing
-          "Starting…" row while streaming with zero parts, localized through the
+          "Starting" row while streaming with zero parts, localized through the
           `agentRun` locale slice — and ai_patterns states the law outright:
           never hand-roll a placeholder in front of the feed. A slot here would
           invite exactly that, and every app would localize it again. */}
-      {/* collapseProcess=false: this pane took the framing job — the FollowScroll
-          above IS the bound, sized by the dialog. Leaving the default on would
-          nest the run's own 220px window inside it, and the dialog's scroller
-          would then never overflow while the inner one held every step. */}
+      {/* collapseProcess=false: the run IS this pane's subject. A dialog opened
+          to watch one run, that then folds it behind a row the reader has to
+          press, hides the only thing it exists to show — the fold is for a run
+          sharing a surface with other content (a chat thread), not for one that
+          owns the surface. The FollowScroll above is the bound, sized by the
+          dialog; taking the framing job is what earns the right to add one. */}
       <AgentRun
         parts={run.parts}
         state={run.status === "error" ? "error" : run.status === "streaming" ? "streaming" : "done"}

package/src/locale.tsx

@@ -460,9 +460,9 @@ export const en: LoticsLocale = {
   scrollToBottom: { tooltip: "Scroll to bottom" },
   textInputField: { clear: "Clear" },
   agentRun: {
-    starting: "Starting…",
+    starting: "Starting",
     thinking: "Thinking",
-    thinkingStreaming: "Thinking…",
+    thinkingStreaming: "Thinking",
     input: "Input",
     error: "Error",
     output: "Output",
@@ -667,9 +667,9 @@ export const vi: LoticsLocale = {
   scrollToBottom: { tooltip: "Cuộn xuống cuối" },
   textInputField: { clear: "Xóa" },
   agentRun: {
-    starting: "Đang bắt đầu…",
+    starting: "Đang bắt đầu",
     thinking: "Suy nghĩ",
-    thinkingStreaming: "Đang suy nghĩ…",
+    thinkingStreaming: "Đang suy nghĩ",
     input: "Đầu vào",
     error: "Lỗi",
     output: "Kết quả",