@lotics/ui 14.3.1 → 15.1.0

package/AGENTS.md

@@ -1,31 +1,5 @@
 # @lotics/ui — the UI reference index
 
-> **Upgrading to v13 from 12.x.** `RadioPicker`'s **`direction`** prop was removed — the
-> picker is always the stacked column of full-width choices. A former `direction="row"`
-> usage just drops the prop. Additively, `DetailRow` and `FormField` gained a **`warning`**
-> field annotation (amber, the third tone between `description` and `error`).
-
-> **Upgrading to v12 from 11.x.** Two exports were removed: **`CommentComposer`** (compose
-> comments with THE kit `Composer` — attach via `actionsButton`/`files`; `CommentList` is
-> unchanged) and **`DetailRow.info`** (field annotations are explicit — use the new
-> **`DetailRow.description`** under the value and **`DetailRow.error`**, the `FormField`
-> vocabulary; heading/card `info` ⓘ props are untouched). Visual behavior changes:
-> `SubsectionStack` is SPACE-ONLY (32px beat, no hairlines — titles carry the grouping),
-> `Section` heading gap 12→16, `DetailTable` row gap 6→8, `DetailRow` rows top-align with
-> label/control/trailing centered on the first control line, `Timeline` grew to 32px
-> discs / 16px icons / 40px minimum rows, `TextInputField` paints a WHITE surface on any
-> background (it was transparent — identical on the white canvas, visible on tinted
-> panels), and the inline editors' resting chip gained 6px vertical padding (identical for
-> one-line values; multi-line resting content now breathes).
-
-> **Upgrading to v11 from ≤10.x — the type scale was re-slotted.** The display sizes gained the
-> missing `##` step: `xl` is now 22/24 (section title), `xxl` is 28/32 (page/record title — the
-> OLD `xl` look), and the new `xxxl` is 32/48 (hero numbers — the OLD `xxl` look). Migrate an
-> app with two renames IN THIS ORDER: first `size="xxl"` → `size="xxxl"`, then `size="xl"` →
-> `size="xxl"` — every existing usage keeps its exact look. Also: `SectionHeadingTitle` is now
-> ALWAYS `##` (22/24), and disabled `Button`s fade their label to the zinc-400 disabled ink on
-> every variant EXCEPT `primary`, which keeps inverted ink over its washed surface.
-
 The component kit for Lotics custom-code apps and the product frontend: React-Native-Web
 primitives (renders on web **and** native), data-entry patterns, AI surfaces, a composition
 grammar, and worked-example screens. It pairs with **`@lotics/app-sdk`** (data + RPC — read
@@ -33,14 +7,15 @@ grammar, and worked-example screens. It pairs with **`@lotics/app-sdk`** (data +
 
 This file is the index. The comprehensive references live in **`docs/`** — read the owning area
 doc before building any screen, **never from memory**. Exact props are the shipped sources
-(`src/<name>.tsx`); full worked screens are `examples/tpl_*.tsx`.
+(`src/<name>.tsx`); full worked screens are `examples/tpl_*.tsx`. Everything here describes the
+CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 
 ## The area references
 
 | 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, stage gates. |
+| [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. |
 | [docs/ai_patterns.md](./docs/ai_patterns.md) | AI proposes, the human decides — composer, live run feed (`AgentRun`), review-before-apply, findings, provenance, confidence; the UI half of the SDK's [ai doc](../app-sdk/docs/ai.md). |
 | [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). |
@@ -61,6 +36,15 @@ doc before building any screen, **never from memory**. Exact props are the shipp
   (the tab stop, name, focus ring), never `PressableHighlight`, which wraps its children in the
   button. `Table`/`TableRow` and `LinkedRecordBox` already do this. →
   [composition.md](./docs/composition.md).
+- **Files land THREE ways on any surface that holds them** — the section's Add CTA
+  (`pickFiles`), and a drag OR paste, both from ONE **`<FileDropTarget … paste>`** wrapping the
+  region — a Files section, OR a WHOLE surface (a record's section stack, a register page), so a
+  drop/paste anywhere on it routes to that surface's intake (its `paste` scopes Ctrl/Cmd+V to the
+  region's focus; `usePasteFiles` is the bare hook for a region-less modal), all on ONE handler.
+  Paste routes to the top-most FOCUSED region, else the top of the stack — two peer file sections
+  each win when focus is in them. Nobody should hunt for a dropzone; a `FileDropzone` well is the
+  empty state, not the only way in. Since a wrapped region shows no zone, name the paths with a
+  muted heading description ("Drag, paste, or click to add files"). → [data_entry.md](./docs/data_entry.md).
 - **Every state designed** — skeleton (mirroring layout), empty, error; no layout shift.
 - **Copy states content, not mechanics** — a `description` names the section's content or one
   domain rule; widget behavior ("edits in place, saves on its own") and selling points never

package/MIGRATION.md

@@ -0,0 +1,66 @@
+# @lotics/ui — migration notes
+
+Breaking changes, newest first — normally per major, plus the rare minor that broke a type
+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.
+
+## v15 from 14.x
+
+`AgentRun`/`AgentProgress`'s **`labelForTool`** prop was replaced by **`labelForCall`** — the
+callback now receives the whole call (`AgentToolCall = { toolName, input, state }`) instead of
+just the name, so labels can vary by input and by the new **`awaiting`** step state (ai's
+`approval-requested`, rendered as an amber parked row). Additively: `renderToolOutput` (replace
+an expanded step's Output panel), `onRetry` (a retry button under the terminal error row), and
+the new `ApprovalPrompt` + `MessageActions` components with their locale slices.
+
+## v14 from 13.x
+
+The ai-sdk `UIMessage.parts` shape IS the `AgentRun` contract — the bespoke transcript type is
+gone. `AgentRun`/`AgentProgress`'s **`items: AgentRunItem[]`** was replaced by **`parts:
+readonly AgentUIPart[]`**, and the **`AgentRunItem`** / **`AgentRunStep`** / **`AgentStepStatus`**
+exports were deleted. An app feeds it straight from the SDK: `useAgentRun().items` →
+**`.parts`** (`@lotics/app-sdk` ≥ 0.54.0, whose SSE reducer now emits ai `dynamic-tool` / `text`
+/ `reasoning` parts); chat passes `message.parts`. Hand-built demo transcripts are rewritten as
+parts. Additively: a run-level **`error`** prop for the BREAKING failure that lives OUTSIDE
+`parts` (a killed stream / API error) — a per-tool failure stays in its own `output-error` part
+— and tool I/O now expands IN PLACE on press instead of opening a `Peek` popover.
+
+## 13.9.0 — a BREAKING type change in a MINOR
+
+**`ClarifyOption.description` went optional → REQUIRED** (every answer explains itself). It
+shipped in a minor, which is why it surprises an app on `^13`: a `<Clarify options={…}>` whose
+options carry only `label` stops typechecking on any 13.9.0+ install. Fix by writing the
+one-line description each option always needed. Same release: `Clarify`'s hardcoded "Question"
+eyebrow was dropped (the question text stays), and `allowCustom` ("Other…" free text) +
+`ClarifyWizard` were added.
+
+## v13 from 12.x
+
+`RadioPicker`'s **`direction`** prop was removed — the picker is always the stacked column of
+full-width choices. A former `direction="row"` usage just drops the prop. Additively, `DetailRow`
+and `FormField` gained a **`warning`** field annotation (amber, the third tone between
+`description` and `error`).
+
+## v12 from 11.x
+
+Two exports were removed: **`CommentComposer`** (compose comments with THE kit `Composer` —
+attach via `actionsButton`/`files`; `CommentList` is unchanged) and **`DetailRow.info`** (field
+annotations are explicit — use the new **`DetailRow.description`** under the value and
+**`DetailRow.error`**, the `FormField` vocabulary; heading/card `info` ⓘ props are untouched).
+Visual behavior changes: `SubsectionStack` is SPACE-ONLY (32px beat, no hairlines — titles carry
+the grouping), `Section` heading gap 12→16, `DetailTable` row gap 6→8, `DetailRow` rows top-align
+with label/control/trailing centered on the first control line, `Timeline` grew to 32px discs /
+16px icons / 40px minimum rows, `TextInputField` paints a WHITE surface on any background (it was
+transparent — identical on the white canvas, visible on tinted panels), and the inline editors'
+resting chip gained 6px vertical padding (identical for one-line values; multi-line resting
+content now breathes).
+
+## v11 from ≤10.x
+
+The type scale was re-slotted — the display sizes gained the missing `##` step: `xl` is now 22/24
+(section title), `xxl` is 28/32 (page/record title — the OLD `xl` look), and the new `xxxl` is
+32/48 (hero numbers — the OLD `xxl` look). Migrate an app with two renames IN THIS ORDER: first
+`size="xxl"` → `size="xxxl"`, then `size="xl"` → `size="xxl"` — every existing usage keeps its
+exact look. Also: `SectionHeadingTitle` is now ALWAYS `##` (22/24), and disabled `Button`s fade
+their label to the zinc-400 disabled ink on every variant EXCEPT `primary`, which keeps inverted
+ink over its washed surface.

package/docs/ai_patterns.md

@@ -111,7 +111,10 @@ text, NOT all text on top of a flat step list. Content parts with no feed repres
 tool part's `input`/`output` are hidden in the row and **expand in place** on press — auto-built
 Input / Output `JsonPanel`s roll out under the row (the same disclosure pattern as "Thinking",
 never a popover). A tool in an `output-error` state flows like any other call — the dot goes
-amber and its `errorText` shows in the expanded Error panel.
+amber and its `errorText` shows in the expanded Error panel. To render a tool's OUTPUT yourself
+(an image preview, a table) pass **`renderToolOutput`** — the ONLY render escape hatch: it fires
+when an output-carrying step is expanded, and a non-`undefined` return replaces the default
+Output panel; `undefined` keeps it. Input + error rendering are untouched.
 
 **Activity grouping.** Consecutive tool parts fold into ONE group. While the agent is mid-tools
 the tail group is a SINGLE pulsing row whose label swaps in place as each call fires (no growing
@@ -123,18 +126,24 @@ no global terminal node.
 
 **Tool labels.** A tool part carries the RAW tool name (`update_records` from `tool-update_records`,
 or a `dynamic-tool`'s `toolName`), resolved via a built-in map of the platform record/document
-tools + an optional `labelForTool` override (localize THERE — the kit stays English); unknown
-names fall back to a prettified form. `stepsLabel` localizes the "{n} steps" suffix. The tool
-`state` collapses ai's lifecycle to running / done / error (an approval-pending state reads as
-running — a read-only feed has no approval control). The whole-run `state` prop
-(`"streaming" | "done" | "error"`) defaults to `streaming` while any tool is running, else `done`.
+tools + an optional **`labelForCall`** override (localize THERE — the kit stays English). It gets
+the whole call — `{ toolName, input, state }` (`AgentToolCall`) — so a caller can phrase by what the
+call targets or by whether it's awaiting; return `undefined` to fall back. Unknown names fall back
+to a prettified form. `stepsLabel` localizes the "{n} steps" suffix. The tool `state` folds ai's
+7-state lifecycle to **running / awaiting / done / error**: `approval-requested` → `awaiting` (the
+call is parked on a human decision — an amber dot + an "awaiting" annotation, and it NEVER pulses,
+because it isn't working); `approval-responded` → running; `output-denied` → error carrying the
+denial reason. The whole-run `state` prop (`"streaming" | "done" | "error"`) defaults to `streaming`
+while any tool is running, else `done` (an awaiting call is not running, so it settles).
 
 **Errors — two kinds, both surfaced, neither shouting.** An INTERMEDIARY tool failure rides in
 that tool's `output-error` part and flows like a normal call — the amber dot marks it (a settled
 group's header goes amber too), the reason waits in the expanded Error panel; real runs retry and
 move on, so the feed doesn't dramatize it. A BREAKING error that terminates the whole run lives
 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.
+pass it as the `error` prop and it renders as a terminal danger row under the transcript. Pass
+**`onRetry`** alongside it and a Retry action (a secondary `Button`) rides under that row so the
+operator can re-fire the run; omit it and the error row renders exactly as before.
 
 **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
@@ -155,20 +164,33 @@ install; the imports are type-only (purity-enforced), so no `ai` runtime ever en
 **Reasoning only shows when the model produces it** — the declared model must support thinking
 (Sonnet / Opus, not Haiku); the renderer shows every reasoning part it's handed.
 
-**Limitation:** the collapsed reasoning row's "Thinking" label and the expanded detail's
-"Input"/"Output"/"Error" panel titles are currently English-only (not on the locale provider and
-not prop-overridable); `labelForTool`/`stepsLabel` localize everything else in the feed.
+**Localization.** The feed's fixed chrome — the "Thinking" label, the "Input"/"Output"/"Error"
+panel titles, the "awaiting" annotation, and the "Retry" action — resolves through the
+`LoticsLocale` `agentRun` slice (translate once at the provider; a `vi` app gets them for free).
+It is provider-localized, not per-instance prop-overridable; `labelForCall`/`stepsLabel` localize
+the tool labels and the "{n} steps" suffix per call site.
+
+**Answering an awaiting call — `ApprovalPrompt`.** The `awaiting` row inside `AgentRun` is
+READ-ONLY — it only NAMES that a call is parked on a human decision. The surface that ANSWERS it
+is `ApprovalPrompt` (`@lotics/ui/approval_prompt`): a warning icon + `message` (per-instance
+override, else the `approvalPrompt` slice default) on a bordered card, with **Deny** (secondary)
++ **Approve** (primary) right-aligned and an optional `children` slot for an input summary between
+them — `onApprove`/`onDeny` fire the SDK's approve/deny (the ai-sdk approval vocabulary). Slot it
+where the composer normally sits while the run is parked, so the operator reads the parked row in
+the feed and answers it below; on decision the run resumes (`approval-responded` → running) or the
+call settles denied (`output-denied` → error). Its strings resolve prop → the `approvalPrompt`
+locale slice → English.
 
 ### `AgentProgress` — the floating pill
 
 On a canvas/composer app reach for `AgentProgress` (`@lotics/ui/agent_progress`) — `AgentRun`
 collapsed into a floating pill (an animated `WaveAvatar` + the current step's label) that EXPANDS
-on press to the full feed in a capped scroll panel. It takes the same `items`/`state`/
-`labelForTool`/`stepsLabel`, plus `label` (override the collapsed text — defaults to the running
-step's label, else "Working…" / "Done" / "Stopped"; pass it to localize — note it's one static
-string, so it no longer tracks the running step) and `defaultExpanded`. Its pill matches
-`Composer`'s compact geometry, so the composer morphs into it while running and reveals again
-when done.
+on press to the full feed in a capped scroll panel. It takes the same `parts`/`state`/`error`, and
+forwards `labelForCall`/`renderToolOutput`/`onRetry`/`stepsLabel` to the expanded feed, plus `label`
+(override the collapsed text — defaults to the running step's label, else "Working…" / "Done" /
+"Stopped"; pass it to localize — note it's one static string, so it no longer tracks the running
+step) and `defaultExpanded`. Its pill matches `Composer`'s compact geometry, so the composer morphs
+into it while running and reveals again when done.
 
 **Limitation:** the pill's expand/collapse accessibility labels ("Show the agent's steps" /
 "Hide the agent's steps") are currently hardcoded English.

package/docs/catalog.md

@@ -225,7 +225,11 @@ tile a pressable door — e.g. tap-to-preview — carrying an accessible button
 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),
 `UploadingThumbnail` (the single in-flight tile FileGrid renders — reach for it only when
-hand-rolling a non-grid upload layout), `FileRow` (a horizontal file/document LINE —
+hand-rolling a non-grid upload layout), `FileDropTarget` (wrap ANY region — a record's Files
+section, a card, a panel — so a file dragged onto it lands; `paste` also takes Ctrl/Cmd+V
+scoped to that region's focus; the region-wrapper next to `FileDropzone`'s dedicated well) +
+`usePasteFiles` (the bare clipboard hook underneath, for a region-less surface) — the halves of
+"files land without hunting for a dropzone", `FileRow` (a horizontal file/document LINE —
 badge-or-placeholder + name + meta + a composable `trailing` slot for a status badge /
 action / remove; `onPress` makes the whole row a pressable door, `trailing` stays an
 independently-pressable sibling; for checklists & readable lists), `FileBadge` (the two-tone
@@ -263,7 +267,14 @@ a plain `metric` prop remains for one-number findings. The children slot compose
 result — a compact `Table` for per-line detail (danger color on the offending cells),
 `ProgressBar` for consumption-toward-a-cliff (free time, credit), dot `Badge`s for a
 present/missing checklist, `Confidence` for judgment calls. Display-only — it informs the
-verdict the host records; `finding` locale slice).
+verdict the host records; `finding` locale slice). `ApprovalPrompt` (the surface that ANSWERS
+an agent's approval-gated action — the interactive counterpart to `AgentRun`'s read-only amber
+`awaiting` row: a warning icon + message on a bordered card, Deny/Approve right-aligned, an
+optional `children` input summary; slot it where the composer sits while the run is parked;
+`approvalPrompt` locale slice), `MessageActions` (THE single shared per-message chrome bar for a
+chat transcript — copy with owned copied-feedback, regenerate, edit, and the branch/version
+pager as an internal part; each action renders only when its handler is given, so the assistant
+bar and the user bar are one component with different handlers; `messageActions` locale slice).
 
 ---
 
@@ -898,9 +909,35 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`file_picker`** — `pickFiles({ accept?, multiple? }) → Promise<File[]>`: opens the
   browser file dialog imperatively — the trigger half behind every Add-file CTA; cancel
   resolves `[]` on modern engines.
-- **`file_dropzone`** — `FileDropzone`: the drag-drop capture well (`onFiles`, `accept`,
-  `label`/`hint`/`dropLabel`, `height`); click falls back to a picker. `label`/`dropLabel`
-  default from the locale's `fileDropzone` slice — pass them only to override.
+- **`file_dropzone`** — `FileDropzone`: the dedicated drag-drop capture well (`onFiles`,
+  `accept`, `label`/`hint`/`dropLabel`, `height`); click falls back to a picker, and while
+  mounted it ALSO takes a paste (Ctrl/Cmd+V) via its inner `FileDropTarget` `paste`, scoped to
+  the well's region. `label`/`dropLabel`/`hint` default from the locale's `fileDropzone` slice
+  (the hint now names the paste) — pass them only to override.
+- **`file_drop_target`** — `FileDropTarget`: makes ANY region accept a file drag-drop —
+  `{ onFiles, accept?, multiple?, paste?, disabled?, children, style? }` wrapped around a
+  section, a card, a whole panel, so nobody hunts for a dropzone. While a drag hovers, the
+  region wears the kit's accent ring + wash (a box-shadow — nothing reflows); pass a FUNCTION
+  child (`(dragging) => …`) to draw the drag state yourself and the target paints nothing (how
+  `FileDropzone` keeps its well styling). **`paste`** ALSO takes Ctrl/Cmd+V, wiring
+  `usePasteFiles` scoped to THIS region's focus — so two peer file sections each win when
+  focus is in them, instead of the last-mounted one grabbing every paste. Native renders the
+  children unchanged.
+- **`use_paste_files`** — `usePasteFiles({ onFiles, accept?, multiple?, enabled?, region? })`:
+  the clipboard half of intake — Ctrl/Cmd+V adds a copied file or a screenshot to the open
+  surface (most reach it via `FileDropTarget`'s `paste`; use the bare hook for a region-less
+  surface like a modal dialog). Scope it with `enabled` ("while this dialog/record is open"); a
+  paste carrying no acceptable file is left alone, so typing Ctrl+V in a text field still pastes
+  text. **Routing (`region`):** among all enabled sinks, the paste goes to the TOP-MOST whose
+  `region` contains `document.activeElement`; with none focused it falls back to the top of the
+  stack (the last-mounted surface — right for a dialog over a screen). A sink with no `region`
+  is a pure stack participant, so a single existing consumer is unchanged. Native is a no-op.
+- **`file_intake`** — the shared, RN-free intake core + the contracts above:
+  `matchesAccept(file, accept)`, `filesFromTransfer(dataTransfer, { accept?, multiple? })`
+  (one extractor for BOTH `drop` and `paste`, with the clipboard-`items` fallback a pasted
+  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,
@@ -986,20 +1023,40 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`composer`** — `Composer`: the adaptive command/chat composer — a compact pill that
   expands for long text + attachments (`pills` + attachment slots, controlled or
   uncontrolled `value`, `onSend`/`onStop`, `sendDisabled` override).
-- **`agent_run`** — `AgentRun` + `resolveToolMeta`: the live streaming work feed. Its prop is the
-  agent message's ai-sdk `parts` (`UIMessagePart[]` — text, reasoning, and tool parts), fed straight
-  from `useAgentRun().parts`; renders prose, a collapsed "Thinking" disclosure, and grouped tool
-  steps whose I/O expands in place on press (no popover). 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. Needs `ai` as an optional
-  type-only peer. AI work ONLY —
-  deterministic work (template fill, an export) shows a `loading` state on its trigger and delivers
-  at once; dressing it as an agent run is theater.
+- **`agent_run`** — `AgentRun` + `resolveToolMeta` + `AgentToolCall` + `AgentToolOutput` (the
+  `renderToolOutput` call shape — `{ toolName, input, output }`): the live streaming work feed.
+  Its prop is the agent message's ai-sdk `parts` (`UIMessagePart[]` — text, reasoning, and tool
+  parts), fed straight from `useAgentRun().parts`; renders prose, a collapsed "Thinking" disclosure,
+  and grouped tool steps whose I/O expands in place on press (no popover). A tool `state` folds ai's
+  7-state lifecycle to running / **awaiting** / done / error — an `awaiting` call (parked on a human
+  approval) wears an amber dot + an "awaiting" annotation and never pulses. `labelForCall(call)`
+  localizes/overrides a step's label from the whole call (`AgentToolCall` = `{ toolName, input,
+  state }`); `renderToolOutput(call)` replaces a step's default Output panel (the one render escape
+  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. Fixed chrome (Thinking / Input / Output / Error / awaiting /
+  Retry) localizes via the `agentRun` locale slice. Needs `ai` as an optional type-only peer. AI
+  work ONLY — deterministic work (template fill, an export) shows a `loading` state on its trigger
+  and delivers at once; dressing it as an agent run is theater.
 - **`agent_transform`** — internal (no component): the one place that folds an ai-sdk `UIMessage`'s
   `parts` into the render timeline (`AgentUIPart`, `toSegments`, `lastRunningStep`), shared by
   `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.
+- **`approval_prompt`** — `ApprovalPrompt`: the surface that ANSWERS an agent's approval-gated
+  action — the interactive counterpart to `AgentRun`'s read-only amber `awaiting` row. A warning
+  icon + `message` (per-instance override; else the slice default) on a bordered card, `onDeny`
+  (secondary) + `onApprove` (primary) right-aligned, an optional `children` slot for an input
+  summary between them. Approve/deny is the ai-sdk approval vocabulary. Slot it where the composer
+  sits while the run is parked; the `approvalPrompt` locale slice.
+- **`message_actions`** — `MessageActions` + `MessageActionsBranch`: THE single shared per-message
+  action bar for a chat transcript — `onCopy` (the bar OWNS the copied feedback: the icon flips to
+  a check + the tooltip to "Copied" for ~2s, timer cleared on unmount; the handler only does the
+  clipboard write), `onRegenerate`, `onEdit`, and `branch` (the sibling-version pager, absorbed as
+  an internal part — renders when `total > 1`). Each action renders ONLY when its handler is given,
+  so an assistant bar (copy + regenerate) and a user bar (copy + edit) are the same component with
+  a different handler set. The bar hugs its content — the parent aligns it (left under an assistant
+  turn, right under a user bubble); the `messageActions` locale slice.
 - **`follow_scroll`** — `FollowScroll`: a scroll container that FOLLOWS its growing content —
   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

package/docs/data_entry.md

@@ -24,7 +24,7 @@ in [the templates](./templates.md) (`examples/tpl_*.tsx`).
 | ONE pick from a BIG registry (ports, projects…) | on a RECORD surface: **`InlineSelect searchable`** (search lives in the popover); on a form/attach surface: **`Combobox`** with `value` | an inline row stays an inline editor — a persistent search input breaks the surface's grammar |
 | a YES/NO on a record | **`CheckboxInput`** as the `DetailRow` value | a boolean needs no editor mode |
 | a STATUS with terminal outcomes | [**disposition**](#disposition--lifecycle-status-is-asymmetric-by-phase) (open → resolve → revise) | guides the decision |
-| FILES | [**attachment field**](#attachments--a-full-add--preview--delete-field) (dropzone + grid + gallery) | add / preview / delete |
+| FILES | [**attachment field**](#attachments--a-full-add--preview--delete-field) (dropzone + grid + gallery; intake = CTA + drop-anywhere + paste) | add / preview / delete |
 | a state TRANSITION mid-flow | [**stage gate**](#stage-gates--tiered-by-weight) (popover / dialog by weight) | right-sized friction |
 
 **The right-input-per-field law.** A field gets the control its SHAPE wants, never a default
@@ -340,6 +340,56 @@ Popover/MenuButton).
 
 ## Attachments — a full add / preview / DELETE field
 
+### Intake — files land THREE ways, on every surface that holds files
+
+A user should never hunt for a dropzone. Any surface that holds files carries all three
+intake paths, all wired to ONE handler:
+
+1. **The section's own CTA** — `pickFiles` behind an Add-file button (the explicit path).
+2. **Drop anywhere on the region + paste** — wrap the region in
+   **`<FileDropTarget onFiles accept multiple paste disabled style>`**. It makes ARBITRARY
+   children a drop region: drag a file over any part of it and the region wears the accent ring
+   + wash (a box-shadow, so nothing reflows), drop and `onFiles` fires. Add **`paste`** and the
+   SAME region also takes Ctrl/Cmd+V (a screenshot or a copied file) — so the region carries
+   both non-explicit paths from one wrapper. This is the region-wrapper; `FileDropzone` stays
+   the dedicated empty-state WELL (and is itself a `FileDropTarget` with `paste` — a function
+   child, `(dragging) => …`, lets a child own the drag visual and the target paint nothing).
+   **The region can be a WHOLE SURFACE, not just a Files section.** Wrap a record's entire
+   section stack (or a register's whole page) in ONE `FileDropTarget` and a drop/paste ANYWHERE
+   on it routes to that surface's intake — the user never has to find the Files section. Give
+   `flex:1` (+ `minWidth:0` inside a flex row) so the wrapper is layout-transparent, and
+   `disabled` while an intake dialog is open so a paste can't start a second one. When the whole
+   surface is the target, the inner section drops its OWN `FileDropTarget` (redundant — one drop
+   would otherwise double it); its affordance line stays.
+3. **The bare paste hook** — **`usePasteFiles({ onFiles, accept, multiple, enabled, region })`**
+   is what `paste` wires internally; reach for it directly only for a region-LESS surface (a
+   modal dialog with no wrapper). Scope it with `enabled` ("while this record/dialog is open");
+   a paste with no acceptable file is left alone, so Ctrl+V in a text field still pastes text.
+
+**Paste routing (focus, then stack).** When two file targets are enabled on the same layer,
+the paste goes to the TOP-MOST one whose `region` contains focus (`document.activeElement`) —
+so two peer file sections each win while the user is working in them, never "last-mounted
+silently grabs everything." With none focused it falls back to the top of the stack (the
+last-mounted surface — the right default for a dialog stacked over a screen). A `usePasteFiles`
+with no `region` is a pure stack participant, so a single existing consumer is byte-for-byte
+unchanged. `FileDropTarget paste` passes its own region, so you get focus routing for free.
+
+Both drop and paste are web behaviors with native no-op siblings — wrap/call them
+unconditionally on a shared screen. The two templates are the worked examples of the
+WHOLE-SURFACE shape: `examples/tpl_record.tsx` wraps its ENTIRE section stack in one
+`<FileDropTarget … paste disabled={aiOpen}>` → a drop/paste anywhere on the record opens the
+`intakeFiles` fork dialog; `examples/tpl_item_list.tsx` wraps its whole register page → a
+drop/paste anywhere opens the "Enter data" intake PRE-SEEDED with the dropped files (the
+register also keeps a section-scoped `FileDropTarget` on the record drawer's Files section, so
+both scopes are shown). Each is one `intakeFiles`/`addFiles`/seed handler behind the wrapper
+plus the Add/Enter CTA.
+
+**Make the two invisible paths discoverable.** A `FileDropTarget`-wrapped section shows no
+dropzone, so drag + paste are invisible unless you SAY so. Every files section carries a muted
+affordance line under its heading — **`<SectionHeadingTitle description="Drag, paste, or click
+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
@@ -368,7 +418,8 @@ Reach for the lower-level pieces below only when you need custom chrome.
 ### The pieces — `FileDropzone`, `FileGrid`, `FileGalleryModal`, `FileRow`
 
 Capture with `<FileDropzone onFiles accept label hint dropLabel height>` (drag-over lights the
-accent; click falls back to a picker); display what landed with **`<FileGrid files uploads>`**
+accent; click falls back to a picker; a mounted zone is also the paste sink, so Ctrl/Cmd+V
+works inside an open upload dialog); display what landed with **`<FileGrid files uploads>`**
 ABOVE the dropzone (existing files are the content; the dropzone sinks to the bottom as the "add
 more" affordance — only the empty state leads with it).
 

package/docs/templates.md

@@ -193,7 +193,9 @@ screens — register, per-row action, gated selection, and act-on-many in one. T
     drawer header swaps to a back button + the pushed id and the ◀ ▶ sequencer hides; back
     pops with scroll preserved.
   - **Files** with its own Add CTA — `FileRows` CRUD via `pickFiles`, plus an EXPECTED
-    document as a ghost `FileRow placeholder` with a Request action.
+    document as a ghost `FileRow placeholder` with a Request action. The section is wrapped in
+    a `<FileDropTarget … paste>`, so a drag anywhere onto it or a Ctrl/Cmd+V lands on the same
+    `addFiles` handler; a `SectionHeadingTitle description` names the three ways in.
   - **Payment** — the `Ledger` (charge/received groups with sums, peekable fee rows,
     `LedgerTotal`) + a Record-payment popover that appends a receipt.
   - **Activity** — the CRM touch-log shape: optional outcome pills (`ChipGroup`,
@@ -205,7 +207,11 @@ screens — register, per-row action, gated selection, and act-on-many in one. T
     whose press opens the shared `FileGalleryModal`.
   - A closing `DangerZone`.
 - **The "Enter data" INTAKE FORK** (the New CTA) — AI FIRST, the form as fallback, one phased
-  dialog: a `FileDropzone` hero (drop the customer's files) → a short ANALYZE stream
+  dialog. The whole register page is ALSO a `<FileDropTarget … paste>` (the whole-surface intake
+  standard): a file dropped or Ctrl/Cmd+V pasted ANYWHERE on the register opens this same dialog
+  PRE-SEEDED with the dropped files (list-first — the paid "Read with AI" stays a deliberate
+  button). The dialog is CONTROLLED (`open`/`onOpenChange` + `seedNames`) so both the button and
+  the top-level drop drive it. The dialog itself: a `FileDropzone` hero (drop the customer's files) → a short ANALYZE stream
   (`AgentRun` in a `FollowScroll`) reads them → `ClarifyWizard` asks the ambiguities the
   analysis surfaced (described options, one custom-answer slot) → the IMPORT stream drafts the
   records → `ChangeRecord` cards to Keep/Drop (fee editable in place) + one outcome-named
@@ -280,6 +286,13 @@ billing, and quick-capture templates. Top → bottom:
 - **Documents** — the Agents "Document desk" pattern (this template is its worked example —
   see the Agents chapter below): the register `Table` (search · Add files) whose selection
   feeds the `FloatingActionBar` → ONE "Use AI" fork (extract / cross-check / edit-with-AI).
+  The template is the worked example of the THREE-way, WHOLE-SURFACE file intake: the Add-files
+  CTA plus a `<FileDropTarget … paste disabled={aiOpen}>` wrapping the ENTIRE section stack (not
+  just Documents) — a drag or Ctrl/Cmd+V ANYWHERE on the record (`disabled` while the intake
+  dialog runs so a paste can't start a second one) — all landing in ONE `intakeFiles` fork
+  dialog. The Documents section therefore carries NO drop target of its own (the whole-record
+  one covers it), only its Add-files CTA and a muted `SectionHeadingTitle description` ("Drag,
+  paste, or click to add files") that keeps the otherwise-invisible paths discoverable.
   Every row's leading visual is a `FileThumbnail` in ONE square 32px slot — an image file
   fills it as a real thumbnail, a document centers its badge in it — never a bare `FileBadge`
   (mixed footprints misalign the identity column). The desk holds what ARRIVES; generation