@lotics/ui 20.1.0 → 20.2.0

package/AGENTS.md

@@ -16,7 +16,7 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 |---|---|
 | [docs/catalog.md](./docs/catalog.md) | **The complete inventory** — Reach-by-role (each data role → the ONE canonical component) + every `@lotics/ui/<module>` entry point (incl. `@lotics/ui/vite`'s `loticsOptimizeDeps` for a custom-code app's `vite.config.ts`). Read before building any screen; reuse first. |
 | [docs/data_entry.md](./docs/data_entry.md) | Which editing pattern for which job — inline edit, fieldset forms, find-or-create (`Combobox`), line items, handoffs, phased records, billing, tags, dispositions, attachments (incl. the three-way file INTAKE: CTA + `FileDropTarget` + `usePasteFiles`), stage gates, the commit-on-blur vs action-press ordering law (the kit gates the press — `pending_commits`). |
-| [docs/ai_patterns.md](./docs/ai_patterns.md) | AI acts, the human stays in charge — composer, live run feed (`AgentRun`), the one law's split (modify → review-before-apply; create → save-direct + the `ResultHeader` receipt), findings, provenance, confidence; the UI half of the SDK's [ai doc](../app-sdk/docs/ai.md). |
+| [docs/ai_patterns.md](./docs/ai_patterns.md) | AI acts, the human stays in charge — composer, live run feed (`AgentRun`), the one law's split (modify → review-before-apply; create → save-direct + the `ResultHeader` receipt), findings, provenance, confidence; the UI half of the SDK's [ai doc](../app-sdk/docs/ai.md)., the whole run in a dialog (`AgentRunScope`/`AgentRunPane`/`AgentRunActions` — a parked question REPLACES the feed, actions in the footer) |
 | [docs/composition.md](./docs/composition.md) | The design-language contract — canvas + content column, heading altitude, banded cards, register vs inset rows, master-detail `Drawer`, view controls, color discipline, typography, whitespace. |
 | [docs/templates.md](./docs/templates.md) | The map of `examples/tpl_*.tsx` — what shape each template solves and which to start from (copy + adapt, never import) — plus the record-surface composition rules (pipeline order, static shape, decision budget). |
 

package/docs/ai_patterns.md

@@ -365,6 +365,44 @@ drives the footer bar (same verbs, same answered-gating). Worked example:
 [`tpl_item_list`](../examples/tpl_item_list.tsx)'s intake fork (the wizard between the analyze
 and import runs, its actions in the footer).
 
+## The whole run in a dialog — `AgentRunScope` / `AgentRunPane` / `AgentRunActions`
+
+`@lotics/ui/agent_run_pane` is the two sections above already composed: the transcript while the
+agent works, the question IN ITS PLACE when it asks, and the wizard's verbs pinned in the footer.
+Reach for it whenever an agent run happens inside a dialog — which is nearly always. Three lines:
+
+```tsx
+const run = useAgentRun("intake");            // @lotics/app-sdk
+<AgentRunScope>                                {/* wraps the Dialog, like ClarifyWizardScope */}
+  <Dialog …>
+    <AgentRunPane run={run} onCancel={…} />                        {/* content */}
+    <DialogFooter><AgentRunActions run={run} /></DialogFooter>     {/* actions */}
+  </Dialog>
+</AgentRunScope>
+```
+
+**The parked question REPLACES the feed — that is the contract, not a style.** The run is blocked
+on the answer, so the question is the only thing to act on; it gets the dialog's own scroller and
+its actions sit outside it. Stacked under the transcript in an unscrollable box — the arrangement
+every app reached for first — a multi-question ask runs past the dialog's height and clips its own
+Submit, leaving a live `awaiting_input` run readable and unanswerable until it expires. The pane
+also swaps `FollowScroll` for `DialogScrollArea` on the park, so the question opens at the top
+rather than wherever the feed was scrolled to.
+
+**`run` is a SHAPE, not an import** (`AgentRunLike`: `status`, `parts`, `pendingChoice`,
+`answerChoice`, `error`; `AgentRunQuestion` names what `pendingChoice` carries, so a template or
+test declares one directly — an option is a label + description and the answer's value IS the
+label, which is the `ask_user_choice` wire shape, so nothing maps between two question types). `useAgentRun()` satisfies it structurally — `@lotics/ui` never depends on
+`@lotics/app-sdk` — which also means a template or test can hand it a plain object and exercise the
+whole pane with no backend ([`tpl_item_list`](../examples/tpl_item_list.tsx) does exactly that).
+
+**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
+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.
+
 ## Provenance — `Sources`
 
 `Sources` (`@lotics/ui/sources`): openable chips saying where the output came FROM, under any

package/docs/catalog.md

@@ -1224,6 +1224,18 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   with **`ClarifyWizardScope`** and put **`ClarifyWizardActions`** in the `DialogFooter` — the
   wizard suppresses the inline row and drives the footer bar (same verbs, same gating), per the
   dialog grammar's footer-owns-actions law (worked example: `tpl_item_list`'s clarify phase).
+- **`agent_run_pane`** — `AgentRunScope` + `AgentRunPane` + `AgentRunActions` (+ `AgentRunLike`/`AgentRunQuestion`/`AgentRunOption`):
+  a whole agent run inside a dialog, in three lines. The pane streams `AgentRun` while the agent
+  works and, the moment it asks, renders the question IN PLACE OF the feed — in the dialog's own
+  scroller, with the wizard's verbs pinned in the `DialogFooter` via `AgentRunActions`. Replacing
+  rather than stacking is the CONTRACT: stacked under the transcript a multi-question ask clips
+  its own Submit and strands a live `awaiting_input` run. `run` is a structural shape
+  (`AgentRunLike`), so `useAgentRun()` satisfies it with no `@lotics/app-sdk` dependency and a
+  mock satisfies it with no backend — `AgentRunQuestion` names the question shape so a template
+  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.
 - **`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/examples/tpl_item_list.tsx

@@ -52,15 +52,12 @@ import { FileGalleryModal } from "@lotics/ui/file_gallery_modal";
 import { Ledger, LedgerGroup, LedgerRow, LedgerTotal } from "@lotics/ui/ledger";
 import { ProgressBar } from "@lotics/ui/progress_bar";
 import { Dialog, DialogFooter, DialogHeader, DialogHeaderTitle, DialogScrollArea } from "@lotics/ui/dialog";
-import { AgentRun } from "@lotics/ui/agent_run";
-import { FollowScroll } from "@lotics/ui/follow_scroll";
-import { ClarifyWizard, ClarifyWizardActions, ClarifyWizardScope, type ClarifyWizardAnswer, type ClarifyWizardQuestion } from "@lotics/ui/clarify_wizard";
+import { AgentRunScope, AgentRunPane, AgentRunActions, type AgentRunLike, type AgentRunQuestion } from "@lotics/ui/agent_run_pane";
 import { ResultHeader } from "@lotics/ui/result_header";
 import { Confidence } from "@lotics/ui/confidence";
 import { CardSelectItem } from "@lotics/ui/card_select_item";
 import { FileDropzone } from "@lotics/ui/file_dropzone";
 import { FileDropTarget } from "@lotics/ui/file_drop_target";
-import { useScreenSize } from "@lotics/ui/use_screen_size";
 import { MemberSelect } from "@lotics/ui/member_select";
 import { Callout, CalloutText } from "@lotics/ui/callout";
 import { Timeline, type TimelineItem } from "@lotics/ui/timeline";
@@ -1052,8 +1049,8 @@ function LinkedRecordScreen({ ma }: { ma: string }) {
 
 // ─── Enter data — the INTAKE fork ────────────────────────────────────────────
 // AI FIRST, form as fallback. The one "Enter data" CTA opens a phased dialog:
-// drop files (the hero) → a short ANALYZE stream reads them → `ClarifyWizard`
-// asks the genuine ambiguities the analysis surfaced → the IMPORT stream
+// drop files (the hero) → a short ANALYZE stream reads them → the run asks the
+// genuine ambiguities the analysis surfaced → the IMPORT stream
 // CREATES the records and the dialog ends on the RESULT LIST — one row per
 // record with its key figures. This is the one law's creation branch: no
 // review gate on a create (nothing to diff — the register IS the review);
@@ -1064,7 +1061,8 @@ function LinkedRecordScreen({ ma }: { ma: string }) {
 // create-then-refine gate). The mock plays the clarify step as two phases; a
 // real app can run it as ONE agent run — every app agent carries
 // `ask_user_choice`, so the run parks on the agent's own question and
-// `useAgentRun().pendingChoice`/`answerChoice` drive this same wizard.
+// `AgentRunPane` renders it from `useAgentRun()` with no change to this file's
+// shape: the mock below satisfies the same `AgentRunLike` the hook does.
 
 type Part = UIMessagePart<UIDataTypes, UITools>;
 type IntakePhase = "intake" | "analyze" | "clarify" | "running" | "done" | "form";
@@ -1085,20 +1083,23 @@ const PROPOSED_BY_ORDER: Proposal[] = PROPOSED_BY_CUSTOMER.flatMap((c) =>
 
 // The wizard's questions come FROM the analysis (a real app renders them off the
 // analyze run's structured output) — informed, described, one custom-answer slot.
-const INTAKE_QUESTIONS: ClarifyWizardQuestion[] = [
+// Declared in the shape `pendingChoice` actually carries, so this reads like a
+// real run: an option is a LABEL plus its description, and the answer's value IS
+// that label (the `ask_user_choice` wire shape — there is no separate code).
+const INTAKE_QUESTIONS: AgentRunQuestion[] = [
   {
     question: "6 orders across 3 customers. How should they become records?",
-    answers: [
-      { value: "customer", label: "One record per customer", description: "3 records — each customer's orders grouped into one workspace and checklist." },
-      { value: "order", label: "One record per order", description: "6 records — every order tracked on its own; more rows, finer-grained status." },
+    options: [
+      { label: "One record per customer", description: "3 records — each customer's orders grouped into one workspace and checklist." },
+      { label: "One record per order", description: "6 records — every order tracked on its own; more rows, finer-grained status." },
     ],
   },
   {
     question: "Blue Harbor Foods isn't in the customer book yet. What should happen?",
-    allowCustom: true,
-    answers: [
-      { value: "create", label: "Create the customer", description: "A new customer record is added and linked as the records land." },
-      { value: "skip", label: "Leave unassigned", description: "The records are created without a customer — link one later from each record." },
+    allow_custom: true,
+    options: [
+      { label: "Create the customer", description: "A new customer record is added and linked as the records land." },
+      { label: "Leave unassigned", description: "The records are created without a customer — link one later from each record." },
     ],
   },
 ];
@@ -1137,7 +1138,6 @@ function EnterDataDialog({ open, onOpenChange, seedDocs, onCreate, onCreateMany
   /** The import's save — rows land in the register as the stream finishes. */
   onCreateMany: (records: { khach: string; dienThoai: string; phi: number }[]) => void;
 }) {
-  const { small } = useScreenSize();
   const [phase, setPhase] = useState<IntakePhase>("intake");
   const [docs, setDocs] = useState<DisplayFile[]>([]);
   const [variant, setVariant] = useState<ManualVariant>("export");
@@ -1172,6 +1172,32 @@ function EnterDataDialog({ open, onOpenChange, seedDocs, onCreate, onCreateMany
   const docNames = docs.map((d) => d.filename);
   const [revealed, setRevealed] = useState(0);
   const script = phase === "analyze" ? analyzeScript(docNames) : phase === "running" ? importScript(grouping) : [];
+
+  // What a real app hands the pane: `const run = useAgentRun("intake")`. The
+  // template has no backend, so it satisfies the same shape from its script —
+  // which is the point, the pane never knows the difference.
+  const run: AgentRunLike = {
+    status: phase === "clarify" ? "awaiting_input" : revealed >= script.length ? "completed" : "streaming",
+    parts: script.slice(0, revealed),
+    error: null,
+    pendingChoice:
+      phase === "clarify"
+        ? { questions: INTAKE_QUESTIONS }
+        : null,
+    answerChoice: async (answers) => {
+      // The answer's value is the LABEL the human picked — match on it.
+      setGrouping(answers[0]?.value === "One record per order" ? "order" : "customer");
+      const plan = answers[1];
+      setCustomerPlan(
+        plan?.custom
+          ? plan.value
+          : plan?.value === "Leave unassigned"
+            ? "Left unassigned — link a customer later"
+            : "New customer created and linked",
+      );
+      setPhase("running");
+    },
+  };
   useEffect(() => {
     if (phase !== "analyze" && phase !== "running") return;
     setRevealed(0);
@@ -1244,14 +1270,14 @@ function EnterDataDialog({ open, onOpenChange, seedDocs, onCreate, onCreateMany
     : "Import from files";
 
   return (
-    <ClarifyWizardScope>
+    <AgentRunScope>
       {/* the file/stream phases (intake/analyze/clarify/running/done) run
-          WIDE — room for the thumbnail hero + the AgentRun/ClarifyWizard/result
+          WIDE — room for the thumbnail hero + the AgentRunPane/result
           panes; only the manual `form` stays a narrow single-column pane.
           760 sits just under the kit Dialog's default 786 maxWidth cap.
-          ClarifyWizardScope wraps the Dialog from OUTSIDE so the wizard's
-          Cancel/Back/Next/Submit render in the DialogFooter — the dialog
-          grammar's home for action bars — via ClarifyWizardActions. */}
+          AgentRunScope wraps the Dialog from OUTSIDE so the run's own action
+          bar renders in the DialogFooter — the dialog grammar's home for
+          action bars — via AgentRunActions. */}
       <Dialog width={phase === "form" ? 480 : 760} open={open} onOpenChange={(o) => { if (!o) close(); }}>
         <DialogHeader>
           <DialogHeaderTitle>{title}</DialogHeaderTitle>
@@ -1324,33 +1350,12 @@ function EnterDataDialog({ open, onOpenChange, seedDocs, onCreate, onCreateMany
           </FileDropTarget>
         ) : null}
 
-        {phase === "analyze" || phase === "running" ? (
-          // Streams follow in a FollowScroll (padding mirrors DialogScrollArea);
-          // the phase flip swaps the scroller out, so the next pane opens at the top.
-          <FollowScroll contentContainerStyle={{ paddingBottom: 24, paddingHorizontal: small ? 16 : 24 }}>
-            <AgentRun parts={script.slice(0, revealed)} state={revealed >= script.length ? "done" : "streaming"} />
-          </FollowScroll>
-        ) : null}
-
-        {phase === "clarify" ? (
-          <View style={{ paddingHorizontal: 24, paddingBottom: 20 }}>
-            <ClarifyWizard
-              questions={INTAKE_QUESTIONS}
-              onCancel={() => setPhase("intake")}
-              onSubmit={(answers: ClarifyWizardAnswer[]) => {
-                setGrouping(answers[0]?.value === "order" ? "order" : "customer");
-                const plan = answers[1];
-                setCustomerPlan(
-                  plan?.custom
-                    ? plan.value
-                    : plan?.value === "skip"
-                      ? "Left unassigned — link a customer later"
-                      : "New customer created and linked",
-                );
-                setPhase("running");
-              }}
-            />
-          </View>
+        {phase === "analyze" || phase === "running" || phase === "clarify" ? (
+          // ONE pane for the whole run. It streams the transcript, and when the
+          // agent asks, the question REPLACES the feed — scrolled, with its
+          // actions in the footer. A real app passes `useAgentRun(alias)`
+          // straight in; this mock is the same shape.
+          <AgentRunPane run={run} onCancel={() => setPhase("intake")} />
         ) : null}
 
         {phase === "done" ? (
@@ -1462,7 +1467,7 @@ function EnterDataDialog({ open, onOpenChange, seedDocs, onCreate, onCreateMany
           </DialogFooter>
         ) : phase === "clarify" ? (
           <DialogFooter>
-            <ClarifyWizardActions />
+            <AgentRunActions run={run} />
           </DialogFooter>
         ) : phase === "done" ? (
           <DialogFooter>
@@ -1471,7 +1476,7 @@ function EnterDataDialog({ open, onOpenChange, seedDocs, onCreate, onCreateMany
           </DialogFooter>
         ) : null}
       </Dialog>
-    </ClarifyWizardScope>
+    </AgentRunScope>
   );
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "20.1.0",
+  "version": "20.2.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -102,6 +102,7 @@
     "./finding": "./src/finding.tsx",
     "./clarify": "./src/clarify.tsx",
     "./clarify_wizard": "./src/clarify_wizard.tsx",
+    "./agent_run_pane": "./src/agent_run_pane.tsx",
     "./result_header": "./src/result_header.tsx",
     "./choice_list": "./src/choice_list.tsx",
     "./sources": "./src/sources.tsx",

package/src/agent_run_pane.tsx

@@ -0,0 +1,134 @@
+import { useCallback, useMemo, type ReactNode } from "react";
+import { View } from "react-native";
+import { AgentRun, type AgentRunProps } from "./agent_run";
+import type { AgentUIPart } from "./agent_transform";
+import { ClarifyWizard, ClarifyWizardActions, ClarifyWizardScope, type ClarifyWizardAnswer } from "./clarify_wizard";
+import { DialogScrollArea } from "./dialog";
+import { FollowScroll } from "./follow_scroll";
+import { useScreenSize } from "@lotics/ui/use_screen_size";
+
+/**
+ * What this pair needs from a run — structurally the shape `useAgentRun()`
+ * returns, declared here rather than imported so `@lotics/ui` keeps its one-way
+ * boundary and never depends on `@lotics/app-sdk`. Nothing enforces the match at
+ * build time; the app is where the two meet, so its typecheck is the detector.
+ */
+/** One option the agent offered. The answer's `value` IS the label — that is the
+ *  `ask_user_choice` wire shape, not a convenience. */
+export interface AgentRunOption {
+  label: string;
+  description?: string;
+}
+
+/** One question the agent asked, exactly as `pendingChoice` carries it. Named so
+ *  a consumer can DECLARE one — a template or test builds these directly, and
+ *  without a name it would borrow `ClarifyWizardQuestion` and map between two
+ *  shapes that a real run never maps between. */
+export interface AgentRunQuestion {
+  question: string;
+  options: AgentRunOption[];
+  allow_custom?: boolean;
+}
+
+export interface AgentRunLike {
+  status: "idle" | "streaming" | "awaiting_input" | "completed" | "error";
+  parts: readonly AgentUIPart[];
+  /** Non-null exactly while parked. */
+  pendingChoice: { questions: AgentRunQuestion[] } | null;
+  answerChoice: (answers: { value: string; custom: boolean }[]) => Promise<unknown>;
+  error: string | null;
+}
+
+export function AgentRunScope({ children }: { children: ReactNode }) {
+  return <ClarifyWizardScope>{children}</ClarifyWizardScope>;
+}
+
+export interface AgentRunPaneProps {
+  run: AgentRunLike;
+  labelForCall?: AgentRunProps["labelForCall"];
+  renderToolOutput?: AgentRunProps["renderToolOutput"];
+  /** Abandon a parked question — the run is left for the operator to retry. */
+  onCancel: () => void;
+}
+
+/**
+ * The run's content: the streaming transcript, or — once the agent asks — the
+ * question IN ITS PLACE.
+ *
+ * The question REPLACES the feed rather than stacking under it. The run is
+ * blocked on the answer, so the question is the only thing to act on; and
+ * stacking is what broke it in production — the wizard sat below the scroller in
+ * a container that could not scroll, so a multi-question ask ran past the
+ * dialog's height and clipped its own Submit. Every app rebuilt this arrangement
+ * by hand and it only had to be got wrong once.
+ */
+export function AgentRunPane(props: AgentRunPaneProps) {
+  const { run, labelForCall, renderToolOutput, onCancel } = props;
+  const { small } = useScreenSize();
+  const pending = run.pendingChoice;
+
+  // Mapped once per question set, not per render: the wizard keys its per-step
+  // draft off identity, and a fresh array every render is a new identity.
+  const questions = useMemo(
+    () =>
+      (pending?.questions ?? []).map((q) => ({
+        question: q.question,
+        answers: q.options.map((o) => ({ value: o.label, label: o.label, description: o.description ?? "" })),
+        allowCustom: q.allow_custom === true,
+      })),
+    [pending],
+  );
+  const submit = useCallback(
+    (answers: ClarifyWizardAnswer[]) => {
+      void run.answerChoice(answers.map((a) => ({ value: a.value, custom: a.custom })));
+    },
+    [run],
+  );
+
+  if (pending) {
+    return (
+      <DialogScrollArea>
+        <View style={{ paddingVertical: 4 }}>
+          <ClarifyWizard questions={questions} onSubmit={submit} onCancel={onCancel} />
+        </View>
+      </DialogScrollArea>
+    );
+  }
+
+  // FollowScroll, not DialogScrollArea: the transcript grows from the bottom and
+  // the newest step has to stay in view. Swapping the scroller on the park is
+  // deliberate — remounting opens the question at the top rather than wherever
+  // the feed happened to be scrolled to.
+  return (
+    <FollowScroll contentContainerStyle={{ paddingBottom: 24, paddingHorizontal: small ? 16 : 24 }}>
+      {/* No empty-state slot on purpose. `AgentRun` renders its own breathing
+          "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. */}
+      <AgentRun
+        parts={run.parts}
+        state={run.status === "error" ? "error" : run.status === "streaming" ? "streaming" : "done"}
+        error={run.error ?? undefined}
+        labelForCall={labelForCall}
+        renderToolOutput={renderToolOutput}
+      />
+    </FollowScroll>
+  );
+}
+
+/**
+ * The run's action bar, for a `DialogFooter`. Renders the wizard's
+ * Cancel/Back/Next/Submit while a question is up and NOTHING otherwise, so the
+ * host can mount it unconditionally and let the run decide.
+ *
+ * Pinned outside the scroller is the point: no length of question can push
+ * Submit out of reach.
+ */
+export function AgentRunActions({ run }: { run: AgentRunLike }) {
+  // Reads the SAME run the pane reads, rather than state the pane publishes: two
+  // components deriving from one source cannot disagree, and nothing has to set
+  // a parent's state during a child's render to keep them in step.
+  if (run.pendingChoice == null) return null;
+  return <ClarifyWizardActions />;
+}