@lotics/ui 20.1.0 → 21.0.0

package/AGENTS.md

@@ -15,8 +15,8 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 | Doc | Read it for |
 |---|---|
 | [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/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 (the `FilesEditor` COMPOUND — root owns selection/gallery/confirm, you compose the bar, a HOST verb reads `useFilesEditorSelection` — plus 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)., 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/MIGRATION.md

@@ -4,6 +4,63 @@ Breaking changes, newest first — normally per major, plus the rare minor that
 anyway (recorded under its exact version). The current contract lives in `AGENTS.md` + `docs/`;
 this file exists only to move an app from one release to the next.
 
+## v21 from 20.x
+
+**`FilesEditor` is a COMPOUND.** It rendered a fixed toolbar — Upload · Select · Download all,
+swapping into a select-mode row whose actions hid behind a generic "Menu" — and that shape cost
+two things in real screens. A HOST verb had nowhere to go, so a surface that needed one (an AI
+read over the picked papers, "send these to the broker") hand-rolled the whole grid and lost the
+gallery, the upload queue and the confirm with it. And the actions that DID exist sat behind a
+label naming a widget rather than an act, five interactions deep for "delete this scan".
+
+The root still owns what a host cannot reasonably re-implement — the batch selection, the
+full-screen gallery, the Alert-confirmed remove — and still renders the grid. What you can DO to
+the files is now composed below it.
+
+```tsx
+// BEFORE
+<FilesEditor
+  files={files} uploads={uploads} onAdd={add} onRemove={remove}
+  onShareSelected={share} onDownloadZipSelected={zip} readOnly={readOnly}
+/>
+
+// AFTER
+<FilesEditor files={files} uploads={uploads} onAdd={readOnly ? undefined : add} onRemove={readOnly ? undefined : remove}>
+  <FilesEditorBar>
+    <FilesEditorUpload />
+    <FilesEditorSelect />
+    <FilesEditorSelectAll />
+    <FilesEditorBarSpacer />
+    <FilesEditorDownload />
+    <FilesEditorRemove />
+  </FilesEditorBar>
+</FilesEditor>
+```
+
+| Gone | Now |
+|---|---|
+| `onShareSelected` | a `Button` in the bar reading `useFilesEditorSelection()` — sharing is a HOST act |
+| `onDownloadZipSelected` | the same |
+| `readOnly` | withhold `onAdd`/`onRemove`; the pieces render nothing without a handler, so the composition IS the read-only shape and there is no second mode to keep in sync |
+| the "Menu" popover | the bar. Actions are visible controls, in the order the surface wants them |
+| `labels.menu` · `labels.share` · `labels.downloadZip` | deleted with the acts they named |
+
+**No children means no bar** — a grid that previews and nothing else. That is the one rendering
+path; there is no default toolbar to fall back to.
+
+**The remaining labels resolve prop → `LoticsLocale.filesEditor` → nothing**, so an app that
+supplies its pack at the root gets them translated with no per-instance wiring.
+
+A host verb reads the selection:
+
+```tsx
+function ReadWithAi() {
+  const { selected, exit } = useFilesEditorSelection();
+  return <Button title="Đọc bằng AI" disabled={selected.length === 0}
+                 onPress={() => { run(selected); exit(); }} />;
+}
+```
+
 ## v20 from 19.x
 
 **`@lotics/ui/section` is DELETED.** Two modules exported a `Section` — the layout grammar's

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

@@ -221,15 +221,12 @@ reference), `InfoPopover` (the ⓘ explainer).
 
 ### Files
 
-`FilesEditor` (THE all-in-one attachment field: an upload-aware grid + a toolbar below it
-that swaps into a batch SELECT mode, full-screen preview, download/share, and
-Alert-confirmed remove — the host only owns `files` + wires `onAdd`/`onRemove`. Reach for
-this first for "manage a record's attachments"), `FileDropzone`, `FileRows`
-(batteries-included file LIST: tap a row → built-in full-screen gallery, with a per-row
-trailing ⋯ menu = Download · Open-external · Remove; the default "here are some files"
-surface), `FileGrid` (the upload-aware grid: completed files + a live upload queue in one
-surface — `FilesEditor` is this + the toolbar; reach for `FileGrid` bare when you own the
-chrome), `FileThumbnail` / `FileThumbnailGrid` (square tiles; `onPress`/`onFilePress` makes each
+`FilesEditor` (THE attachment surface: an upload-aware grid whose bar you COMPOSE — the root
+owns selection + gallery + confirmed remove, the bar pieces and any HOST verb go below it via
+`useFilesEditorSelection`),
+`FileGrid` (the upload-aware grid: completed files + a live upload queue in one
+surface — `FilesEditor` is this + selection + the composed bar; reach for `FileGrid` bare when
+you own all three), `FileThumbnail` / `FileThumbnailGrid` (square tiles; `onPress`/`onFilePress` makes each
 tile a pressable door — e.g. tap-to-preview — carrying an accessible button role + the
 filename as its name, overridable per tile with `accessibilityLabel` when what the press
 DOES reads better than a raw filename; `selectedIds` for a selection overlay),
@@ -1065,26 +1062,38 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   screenshot needs), `selectPasteSink(entries)` (the pure focus-then-stack routing rule the
   `.web` sink applies), and the types `FileIntakeFilter` / `FileTransferLike` / `RegionRef` /
   `PasteSinkEntry` / `UsePasteFilesOptions` / `FileDropTargetProps`.
-- **`files_editor`** — `FilesEditor` — THE all-in-one attachment field: `FileGrid` + a
-  toolbar (Upload primary · Select · Download all) that swaps into a batch SELECT mode
-  (Select all · a Menu of Download/Share/Delete · Done; the per-tile ✕ is select-mode-only,
-  never in the default view; `selectTileRemove={false}` drops even that so delete is
-  menu-only) + built-in gallery (Download + inline preview; no "open in new tab") +
-  Alert-confirmed remove; host wires `files` + `onAdd`/`onRemove` (+ optional `uploads`,
-  `onShareSelected`, `readOnly`, `selectTileRemove`, `labels`, `galleryLabels`,
-  `gridMaxHeight` — cap the grid height so it scrolls and the toolbar pins, for a
-  popover/drawer). Use `FileGrid`/`FileRows` bare only when you own the chrome.
+- **`files_editor`** — THE attachment surface, as a **compound**. `FilesEditor` (root) owns
+  what a host cannot reasonably re-implement — the batch selection, the built-in gallery
+  (Download + inline preview; no "open in new tab"), the Alert-confirmed remove — and renders
+  `FileGrid`; the host wires `files` + `onAdd`/`onRemove` (+ optional `uploads`,
+  `selectTileRemove`, `labels`, `galleryLabels`, `gridMaxHeight` — cap the grid height so it
+  scrolls and the bar pins, for a popover/drawer). **What you can DO to the files is composed
+  below it**, from `FilesEditorBar` + `FilesEditorUpload` · `FilesEditorSelect` ·
+  `FilesEditorSelectAll` · `FilesEditorDownload` · `FilesEditorRemove` (+
+  `FilesEditorBarSpacer` to push the rest right). Each renders nothing without the handler it
+  needs, so withholding `onAdd`/`onRemove` IS the read-only shape — there is no `readOnly`
+  mode. **A HOST verb is a plain `Button`** reading **`useFilesEditorSelection()`**
+  (`{selected, selectedIds, files, selectMode, clear, exit}`) — an AI read over the picked
+  papers, "send to the broker", a ZIP: acts the kit has never heard of, which is why there is
+  no props-per-act toolbar and no generic Menu. **No children means no bar** (a grid that only
+  previews). Bar words resolve prop → `LoticsLocale.filesEditor`; in-flight tile words →
+  `LoticsLocale.fileUpload`. **No empty state:** with zero files it is a bare bar, so pair it
+  with a `FileDropzone` for the well a records screen opens on. Use `FileGrid`/`FileRows` bare
+  only when you own the selection and the gallery too.
 - **`file_grid`** — `FileGrid` + the `FileUpload`/`PendingUpload` types: the upload-aware
   grid — `files` are the saved/completed `DisplayFile`s, `uploads` is the LIVE add-queue; it
   interleaves both and renders each in-flight tile itself with a labeled status overlay.
   Tiles FILL the container width at a uniform size (≥ `minItemWidth`, default 96); pass
   `columns` for a fixed count, `itemSize` for exact tiles, or `singleRow` to fit one row and
   collapse the rest into a clickable "+N" overflow tile (`onOverflowPress(hiddenCount)`).
-  CRUD via `onFilePress` / `onDisplayRemove` / `onUploadRemove` / `onRetry` / `onRetryAll`;
-  localize with `labels.upload` (an `UploadStatusLabels`).
+  CRUD via `onFilePress` / `onDisplayRemove` / `onUploadRemove` / `onRetry` / `onRetryAll`.
+  The status words resolve **prop → `LoticsLocale.fileUpload` → nothing**, so they follow the
+  root pack with no per-call-site wiring (that is also how the grid inside `FilesEditor`, which
+  cannot pass `labels`, gets localized); `labels.upload`/`labels.retryAll` override one grid.
 - **`uploading_thumbnail`** — `UploadingThumbnail` + `UploadStatus`/`UploadStatusLabels`:
   the single in-flight upload tile `FileGrid` renders; reach for it only when hand-rolling a
-  non-grid upload layout.
+  non-grid upload layout — it is i18n-free by design, so a bare call site owes it `labels`
+  (`FileGrid` resolves them from `LoticsLocale.fileUpload` on your behalf).
 - **`file_thumbnail`** — `FileThumbnail` + `DisplayFile` + `THUMBNAIL_SIZE` /
   `COMPACT_THUMBNAIL_SIZE` + `getMediaIcon`: the completed tile — the right surface per
   MIME: image thumbnail · a doc tile with the `FileBadge` centered + a single-line filename
@@ -1224,6 +1233,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/docs/data_entry.md

@@ -514,28 +514,59 @@ affordance line under its heading — **`<SectionHeadingTitle description="Drag,
 to add files">`** (both templates do this). A `FileDropzone`'s own hint already names the paste
 (its default `fileDropzone.hint` is "or click, or paste (⌘V)").
 
-### Default: `FilesEditor`
-
-**`<FilesEditor files onAdd onRemove>`** bundles the upload-aware grid + a toolbar below it
-(Upload · Select · Download all) + a batch SELECT mode + the full-screen gallery +
-Alert-confirmed remove; the host only owns `files` and wires `onAdd` (picked → its upload) /
-`onRemove`. The destructive per-tile ✕ shows only in SELECT mode (the default view is a clean
-preview — no stray-tap deletes); pass `selectTileRemove={false}` to drop that ✕ entirely so
-select mode deletes ONLY via Select → Menu → Delete (the batch gating flow — right for a
-height-bounded cell editor). The built-in gallery is Download + inline preview (no "open in new
-tab" — it's redundant once everything previews inline). In a height-bounded container (a
-popover/drawer) pass `gridMaxHeight` so the grid SCROLLS and the toolbar pins below it; omit it
-in free-flow layouts (a form field) where the grid grows.
+### Default: the `FilesEditor` compound
+
+**The root owns what a host cannot reasonably re-implement** — the batch selection, the
+full-screen gallery, the Alert-confirmed remove — and renders the upload-aware grid. **What you
+can DO to the files is composed below it**, so a surface offers exactly its own verbs, in its
+own order, under their own names.
+
+```tsx
+<FilesEditor files={files} uploads={queue} onAdd={add} onRemove={remove}>
+  <FilesEditorBar>
+    <FilesEditorUpload />
+    <FilesEditorSelect />       {/* "Select" ⇄ "Done" — one toggle, not two buttons */}
+    <FilesEditorSelectAll />    {/* renders only while selecting */}
+    <FilesEditorBarSpacer />
+    <FilesEditorDownload />     {/* the selection while selecting, everything at rest */}
+    <FilesEditorRemove />
+  </FilesEditorBar>
+</FilesEditor>
+```
+
+**A HOST verb is a plain `Button`** that reads `useFilesEditorSelection()` →
+`{selected, selectedIds, files, selectMode, clear, exit}`. This is the whole reason the bar is
+composed: an act the kit has never heard of — read these with AI, send them to the broker, ZIP
+them — has a home, instead of forcing the screen to hand-roll the grid and lose the gallery and
+the upload queue with it.
+
+```tsx
+function ReadWithAi() {
+  const { selected, exit } = useFilesEditorSelection();
+  return <Button title="Read with AI" disabled={selected.length === 0}
+                 onPress={() => { run(selected); exit(); }} />;
+}
+```
+
+**Each piece renders nothing without the handler it needs**, so composition expresses the
+variants that used to be flags: withhold `onAdd` and there is no Upload; withhold `onRemove` and
+there is no Remove and no per-tile ✕ — that IS read-only, with no second mode to keep in sync.
+**No children means no bar**: a grid that previews and nothing else.
+
+The destructive per-tile ✕ shows only in SELECT mode (the default view is a clean preview — no
+stray-tap deletes); `selectTileRemove={false}` drops it there too, so the bar's Remove is the
+only delete path (right for a height-bounded cell editor). The built-in gallery is Download +
+inline preview (no "open in new tab" — redundant once everything previews inline). In a
+height-bounded container (a popover/drawer) pass `gridMaxHeight` so the grid SCROLLS and the bar
+pins below it; omit it in free-flow layouts where the grid grows.
 
 The rest of the surface: `uploads` passes the live add-queue through to the grid (with
-`onUploadRemove`/`onRetry`/`onRetryAll`); `onUpload` overrides the Upload action's built-in web
-picker (e.g. a native document picker); `readOnly` (or omitting `onRemove`) makes it a view-only
-download+preview surface; omitting `onAdd` hides Upload. Select mode gains a Share action via
-`onShareSelected(files)` and a "Download as ZIP" item via `onDownloadZipSelected(files)` (shown at
-2+ selected) — both host-provided, hidden when omitted. `onDownload` overrides the default
-per-file `downloadFileFromUrl`; `accept` filters the picker; `itemSize`/`minItemWidth`/`columns`
-pass through to the grid; `credentials` covers auth-gated preview URLs; `labels` /
-`galleryLabels` localize the toolbar and the gallery chrome.
+`onUploadRemove`/`onRetry`/`onRetryAll`); `onUpload` overrides the Upload picker (e.g. a native
+document picker); `onDownload` overrides the default per-file `downloadFileFromUrl`; `accept`
+filters the picker; `itemSize`/`minItemWidth`/`columns` pass through to the grid; `credentials`
+covers auth-gated preview URLs. Bar words resolve **prop → `LoticsLocale.filesEditor`**, gallery
+chrome via `galleryLabels`, in-flight tile words via `LoticsLocale.fileUpload` — so an app that
+supplies its pack at the root needs no per-instance labels at all.
 
 Reach for the lower-level pieces below only when you need custom chrome.
 
@@ -551,9 +582,10 @@ more" affordance — only the empty state leads with it).
 the LIVE add-queue (`FileUpload[]`) — it interleaves both and renders each in-flight tile itself —
 a LABELED status overlay (uploading spinner · "Retrying" · "Paused" · "Upload failed" + a retry
 button · "Can't upload" for a dead/empty file) — so you never hand-map an upload to a
-`FileThumbnail`. Localize the labels with `labels.upload` (an `UploadStatusLabels`) and
-`labels.retryAll`. **Limitation:** the upload-status labels are NOT wired to
-`LoticsLocaleProvider` — they default to English; pass `labels` per instance to localize.
+`FileThumbnail`. Those words resolve **prop → `LoticsLocale.fileUpload` → nothing** — set the
+pack once at the root and a stalled or dead upload speaks the app's language everywhere,
+including inside `FilesEditor`, which has no per-instance way to reach them. `labels.upload` /
+`labels.retryAll` override one grid.
 
 Make it CRUDable by wiring its callbacks: `onFilePress` → set a `number|null` index that drives
 `<FileGalleryModal files activeIndex onIndexChange>` — a FULL-SCREEN viewer with a toolbar

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/examples/tpl_task_board.tsx

@@ -21,7 +21,7 @@ import { ActionMenu } from "@lotics/ui/action_menu";
 import { Alert } from "@lotics/ui/alert";
 import { pickFiles } from "@lotics/ui/file_picker";
 import { Popover, PopoverTrigger, PopoverContent } from "@lotics/ui/popover";
-import { FilesEditor } from "@lotics/ui/files_editor";
+import { FilesEditor, FilesEditorBar, FilesEditorBarSpacer, FilesEditorRemove, FilesEditorSelect, FilesEditorUpload } from "@lotics/ui/files_editor";
 import { FileThumbnail, type DisplayFile } from "@lotics/ui/file_thumbnail";
 import { DataGrid, gridRowStyle, type DataGridColumn, type DataGridGroup } from "@lotics/ui/data_grid";
 import { CONTROL_RADIUS } from "@lotics/ui/control_surface";
@@ -483,7 +483,16 @@ function FilesCell({ files, onAdd, onRemove }: { files: DisplayFile[]; onAdd: (p
       </PopoverTrigger>
       <PopoverContent>
         <View style={{ width: 340, padding: 8 }}>
-          <FilesEditor files={files} itemSize={76} onAdd={onAdd} onRemove={onRemove} />
+          {/* The bar is composed, so this popover offers exactly the three acts
+              a task attachment needs and nothing else. */}
+          <FilesEditor files={files} itemSize={76} onAdd={onAdd} onRemove={onRemove}>
+            <FilesEditorBar>
+              <FilesEditorUpload />
+              <FilesEditorSelect />
+              <FilesEditorBarSpacer />
+              <FilesEditorRemove />
+            </FilesEditorBar>
+          </FilesEditor>
         </View>
       </PopoverContent>
     </Popover>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "20.1.0",
+  "version": "21.0.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",