@lotics/ui 15.0.0 → 15.1.1

package/AGENTS.md

@@ -15,7 +15,7 @@ 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, 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). |
@@ -27,6 +27,11 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
   license to hand-roll.
 - **One canonical component per data role** (member → `MemberChip`, select → `OptionBadge`,
   files → `FilePreview` family, …) — the catalog's Reach-by-role outranks neighboring code.
+- **`Badge` = STATUS only; supporting detail is the muted second line.** A type / category /
+  attribute / count is not a status — it belongs under its identity as `size="xs" color="muted"`,
+  never a second chip. A chip beside a name reads as its PEER (a colored one reads louder),
+  inverting the hierarchy the row is scanned by. →
+  [composition.md §`Badge` is for STATUS only](./docs/composition.md).
 - **The kit's fonts/colors/icons ARE the design system** — never a custom font, icon set, or
   hand-picked palette shade; color is `solid`/`tint`/`ramp` with ONE accent per screen.
 - **Pure primitives only** — no i18n, analytics, or domain types in `src/` (pass `labels`,
@@ -36,6 +41,15 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
   (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

@@ -1,7 +1,8 @@
 # @lotics/ui — migration notes
 
-Breaking changes per major, newest first. The current contract lives in `AGENTS.md` + `docs/`;
-this file exists only to move an app from one major to the next.
+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
 
@@ -12,6 +13,27 @@ just the name, so labels can vary by input and by the new **`awaiting`** step st
 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

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
@@ -905,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,

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

@@ -178,7 +178,12 @@ screens — register, per-row action, gated selection, and act-on-many in one. T
   **disabled** checkbox (the same gating as any blocked line). A row's status is
   `Badge variant="dot"` — never the tonal `Badge` (that's the drawer/header twin; → [composition
   grammar §"Status indicators have a WEIGHT"](./composition.md)) — and the SAME dot vocabulary
-  drives the status facet. A per-row action `Button` (here Print) is the row's primary action in
+  drives the status facet. A cell that carries supporting detail is a HIERARCHY, not two peers:
+  the identity on top (`size="sm"`, `weight="medium"` when it IS the row's name), its supporting
+  value beneath as `size="xs" color="muted"`, `gap: 2` — and a category / type / attribute goes
+  on THAT line, never a second chip beside the name (which reads as its peer, or louder when
+  colored, inverting what the row is scanned by; → [composition grammar §`Badge` is for STATUS
+  only](./composition.md)). A per-row action `Button` (here Print) is the row's primary action in
   the trailing column, `⋯` its overflow. A select-all band, footer totals + `Pagination`, and a
   `FloatingActionBar` carrying the bulk action while rows are ticked.
 - **A row press opens the PRODUCTION workspace `Drawer`**, which demonstrates the full
@@ -193,7 +198,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 +212,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 +291,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

package/examples/tpl_item_list.tsx

@@ -57,6 +57,7 @@ import { FollowScroll } from "@lotics/ui/follow_scroll";
 import { ClarifyWizard, type ClarifyWizardAnswer, type ClarifyWizardQuestion } from "@lotics/ui/clarify_wizard";
 import { CardSelectItem } from "@lotics/ui/card_select_item";
 import { FileDropzone } from "@lotics/ui/file_dropzone";
+import { FileDropTarget } from "@lotics/ui/file_drop_target";
 import { ChangeField, ChangeRecord, ChangeReview, ChangeReviewActions, ChangeReviewHeader, ChangeValueInput, type ChangeStatus } from "@lotics/ui/change_review";
 import { useScreenSize } from "@lotics/ui/use_screen_size";
 import { MemberSelect } from "@lotics/ui/member_select";
@@ -461,6 +462,11 @@ function HoSoWorkspace({ hs, daThu, onPaid, tasks, onTasksChange, suggestions, o
   const [declared, setDeclared] = useState<number | null>(isSeed ? 25_000_000 : null);
   const [tags, setTags] = useState<string[]>(isSeed ? (hs.trangThai === "hoantat" ? ["corporate"] : ["corporate", "courier"]) : []);
   const [files, setFiles] = useState<DisplayFile[]>(isSeed ? [sampleDoc("id-scan", "#3b82f6"), sampleDoc("application-form", "#10b981")] : []);
+  // THE standard files intake — one handler, three ways in: the section's Add
+  // CTA, a drag anywhere onto the Files section, and Ctrl/Cmd+V — the last two
+  // both ride the section's `<FileDropTarget paste>` below. Every record surface
+  // carries all three; the user should never have to hunt for a dropzone.
+  const addFiles = (picked: File[]) => setFiles((prev) => [...prev, ...toDisplayFiles(picked)]);
   // ── the case's money: CHARGES owed vs RECEIPTS received — outstanding is
   // the difference. Recording a payment appends a receipt; everything
   // (bar, group sums, the closing number) recomputes from the two lists.
@@ -688,17 +694,23 @@ function HoSoWorkspace({ hs, daThu, onPaid, tasks, onTasksChange, suggestions, o
         <Divider />
         {/* FILES — the document CRUD: FileRows (press → gallery preview, ⋯ →
             remove) + the section's OWN CTA; an EXPECTED document renders as a
-            ghost placeholder row with its own chase action. */}
+            ghost placeholder row with its own chase action.
+            The whole section is a FileDropTarget with `paste` — drag a file
+            anywhere onto it, or Ctrl/Cmd+V while focus is in it — the standard
+            files-intake behavior every record surface should carry. */}
+        <FileDropTarget onFiles={addFiles} paste>
         <Section>
           <SectionHeading>
-            <SectionHeadingTitle>Files</SectionHeadingTitle>
+            {/* The standard files-section affordance line — drag / paste / click
+                are otherwise invisible on a FileDropTarget-wrapped section. */}
+            <SectionHeadingTitle description="Drag, paste, or click to add files">Files</SectionHeadingTitle>
             <SectionHeadingMeta>{`${files.length} ${files.length === 1 ? "file" : "files"}`}</SectionHeadingMeta>
             <Button
               title="Add file"
               color="secondary"
               onPress={() => {
                 void pickFiles({ multiple: true }).then((picked) => {
-                  if (picked.length > 0) setFiles((prev) => [...prev, ...toDisplayFiles(picked)]);
+                  if (picked.length > 0) addFiles(picked);
                 });
               }}
             />
@@ -711,6 +723,7 @@ function HoSoWorkspace({ hs, daThu, onPaid, tasks, onTasksChange, suggestions, o
             trailing={<Button title="Request" color="muted" onPress={() => {}} />}
           />
         </Section>
+        </FileDropTarget>
         <Divider />
         {/* the PAYMENT summary — a plain financial STATEMENT: the two sides
             of the ledger (charges owed · receipts received), every amount on
@@ -1101,14 +1114,22 @@ const importScript = (grouping: "customer" | "order"): Part[] => [
 /** The manual gate stays the THREE-field create-then-refine form — past the
  *  popover threshold (1–2 fields), so a Dialog pane; NOT a wizard: the record's
  *  own workspace (the drawer it opens into) is where everything else is refined. */
-function EnterDataDialog({ onCreate, onCreateMany }: {
+function EnterDataDialog({ open, onOpenChange, seedDocs, onCreate, onCreateMany }: {
+  /** Controlled open — the intake is driven by BOTH the toolbar "Enter data"
+   *  button (opens empty) AND the register's whole-surface FileDropTarget (opens
+   *  PRE-SEEDED via `seedDocs`), so the trigger lives with the parent. */
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  /** Files to pre-seed the intake WELL when the dialog opens from a top-level
+   *  drop/paste — a dropped pile lands as thumbnail cards (list-first, NOT
+   *  auto-analyze), ready for the deliberate "Read with AI". Empty from the button. */
+  seedDocs: DisplayFile[];
   onCreate: (khach: string, dienThoai: string, phi: number) => void;
   onCreateMany: (records: { khach: string; dienThoai: string; phi: number }[]) => void;
 }) {
   const { small } = useScreenSize();
-  const [open, setOpen] = useState(false);
   const [phase, setPhase] = useState<IntakePhase>("intake");
-  const [fileNames, setFileNames] = useState<string[]>([]);
+  const [docs, setDocs] = useState<DisplayFile[]>([]);
   const [variant, setVariant] = useState<ManualVariant>("export");
   const [grouping, setGrouping] = useState<"customer" | "order">("customer");
   // Q2's answer is load-bearing too: it decides how the unknown customer lands
@@ -1123,13 +1144,25 @@ function EnterDataDialog({ onCreate, onCreateMany }: {
   const [dienThoai, setDienThoai] = useState("");
   const [phi, setPhi] = useState<number | null>(null);
 
-  // The stream reveal — one revealer serves both the analyze and import phases.
+  // Opening PRE-SEEDS the intake well: a top-level drop/paste passes the dropped
+  // files via `seedDocs`, the button passes []. Keyed on `open` alone — the seed
+  // is settled before the parent flips open, and re-seeding on every render would
+  // fight the user's own add/remove among the thumbnails.
+  useEffect(() => {
+    if (open) {
+      setPhase("intake");
+      setDocs(seedDocs);
+    }
+  }, [open]);
+
+  // The analyze stream names the files it reads; the reveal serves analyze + import.
+  const docNames = docs.map((d) => d.filename);
   const [revealed, setRevealed] = useState(0);
-  const script = phase === "analyze" ? analyzeScript(fileNames) : phase === "running" ? importScript(grouping) : [];
+  const script = phase === "analyze" ? analyzeScript(docNames) : phase === "running" ? importScript(grouping) : [];
   useEffect(() => {
     if (phase !== "analyze" && phase !== "running") return;
     setRevealed(0);
-    const total = phase === "analyze" ? analyzeScript(fileNames).length : importScript(grouping).length;
+    const total = phase === "analyze" ? analyzeScript(docNames).length : importScript(grouping).length;
     let n = 0;
     const t = setInterval(() => {
       n += 1;
@@ -1145,6 +1178,11 @@ function EnterDataDialog({ onCreate, onCreateMany }: {
     // settled before their stream phase begins.
   }, [phase]);
 
+  // ONE intake sink — every way IN adds to the pile: the whole-dialog
+  // FileDropTarget (drag/paste anywhere on the open dialog), the big empty-state
+  // dropzone, and the compact add-more dropzone all call this.
+  const addDocs = (fs: File[]) => setDocs((prev) => [...prev, ...toDisplayFiles(fs)]);
+
   const proposals = grouping === "customer" ? PROPOSED_BY_CUSTOMER : PROPOSED_BY_ORDER;
   // Kept = explicitly ACCEPTED (the kit's review contract): Apply stays disabled
   // at 0 kept, and the bar's own Keep-all presses every pending card's Keep.
@@ -1152,7 +1190,7 @@ function EnterDataDialog({ onCreate, onCreateMany }: {
 
   const reset = () => {
     setPhase("intake");
-    setFileNames([]);
+    setDocs([]);
     setCardStatus({});
     setFees({});
     setCustomerPlan("New customer created and linked");
@@ -1160,7 +1198,7 @@ function EnterDataDialog({ onCreate, onCreateMany }: {
     setDienThoai("");
     setPhi(null);
   };
-  const close = () => { setOpen(false); reset(); };
+  const close = () => { onOpenChange(false); reset(); };
 
   const applyProposals = () => {
     const kept = proposals.filter((p) => cardStatus[p.id] === "accepted");
@@ -1180,47 +1218,81 @@ function EnterDataDialog({ onCreate, onCreateMany }: {
     : "Import from files";
 
   return (
-    <>
-      <Button title="Enter data" color="primary" onPress={() => setOpen(true)} />
-      <ChangeReview>
-      <Dialog width={phase === "review" ? 560 : 480} open={open} onOpenChange={(o) => { if (!o) close(); }}>
+    <ChangeReview>
+      {/* the file/stream phases (intake/analyze/clarify/running/review) run
+          WIDE — room for the thumbnail hero + the AgentRun/ClarifyWizard/review
+          streams; only the manual `form` stays a narrow single-column pane.
+          760 sits just under the kit Dialog's default 786 maxWidth cap. */}
+      <Dialog width={phase === "form" ? 480 : 760} open={open} onOpenChange={(o) => { if (!o) close(); }}>
         <DialogHeader>
           <DialogHeaderTitle>{title}</DialogHeaderTitle>
         </DialogHeader>
 
         {phase === "intake" ? (
-          <View style={{ paddingHorizontal: 24, paddingBottom: 20, gap: 16 }}>
-            {/* the hero: AI reads the files — no manual step */}
-            <FileDropzone
-              label="Drop the customer's files"
-              hint="Orders, invoices, spreadsheets — AI reads them and drafts the records"
-              onFiles={(fs) => {
-                setFileNames(fs.length > 0 ? fs.map((f) => f.name) : ["orders-june.pdf", "manifest.xlsx"]);
-                setPhase("analyze");
-              }}
-            />
-            <View style={{ flexDirection: "row", alignItems: "center", gap: 12 }}>
-              <View style={{ flex: 1 }}><Divider /></View>
-              <Text size="xs" color="muted">or enter manually</Text>
-              <View style={{ flex: 1 }}><Divider /></View>
-            </View>
-            <View style={{ gap: 8 }}>
-              <CardSelectItem accessibilityLabel="New export case" onPress={() => { setVariant("export"); setPhase("form"); }} style={{ flexDirection: "row", alignItems: "center", gap: 12 }}>
-                <Icon name="arrow-up" size={18} color={colors.zinc[700]} />
-                <View style={{ flex: 1, gap: 2 }}>
-                  <Text size="sm" weight="semibold">Export case</Text>
-                  <Text size="xs" color="muted">Outbound paperwork — the record seeds the customs-out checklist.</Text>
+          // The WHOLE open dialog is a FileDropTarget: drag OR paste anywhere on
+          // it adds files, in BOTH modes (the ring/wash frames the dialog on drag
+          // — "drop anywhere here"). Nested with the dropzones below, which each
+          // light their own well; stopPropagation keeps one drop from double-adding.
+          <FileDropTarget onFiles={addDocs} paste style={{ paddingHorizontal: 24, paddingBottom: 20, gap: 16 }}>
+            {/* ONE dialog, TWO MODES (not two Dialogs): FILES-PRESENT shows the
+                pile + a compact add-more well + the deliberate Read; EMPTY shows
+                the big dropzone hero + the manual chooser. Dropping in either ADDS
+                files (via addDocs) — the paid AI read stays a DELIBERATE button,
+                never a side effect of a drop. A pile means the user came to
+                process files, so the manual cards fall away. */}
+            {docs.length > 0 ? (
+              <View style={{ gap: 16 }}>
+                {/* the pile, as document cards — removable, the hero at top */}
+                <FileThumbnailGrid
+                  files={docs}
+                  minItemWidth={120}
+                  onRemove={(id) => setDocs((prev) => prev.filter((d) => d.id !== id))}
+                />
+                {/* add-more is a real WELL (draggable + clickable), not a button —
+                    compact so the pile stays the hero */}
+                <FileDropzone
+                  height={96}
+                  label="Drop more files"
+                  hint="or click to add"
+                  onFiles={addDocs}
+                />
+                <Button
+                  title={`Read ${docs.length} ${docs.length === 1 ? "file" : "files"} with AI`}
+                  color="primary"
+                  onPress={() => setPhase("analyze")}
+                />
+              </View>
+            ) : (
+              <>
+                <FileDropzone
+                  label="Drop the customer's files"
+                  hint="Orders, invoices, spreadsheets — read them with AI"
+                  onFiles={addDocs}
+                />
+                <View style={{ flexDirection: "row", alignItems: "center", gap: 12 }}>
+                  <View style={{ flex: 1 }}><Divider /></View>
+                  <Text size="xs" color="muted">or enter manually</Text>
+                  <View style={{ flex: 1 }}><Divider /></View>
                 </View>
-              </CardSelectItem>
-              <CardSelectItem accessibilityLabel="New import case" onPress={() => { setVariant("import"); setPhase("form"); }} style={{ flexDirection: "row", alignItems: "center", gap: 12 }}>
-                <Icon name="arrow-down" size={18} color={colors.zinc[700]} />
-                <View style={{ flex: 1, gap: 2 }}>
-                  <Text size="sm" weight="semibold">Import case</Text>
-                  <Text size="xs" color="muted">Inbound paperwork — the record seeds the customs-in checklist.</Text>
+                <View style={{ gap: 8 }}>
+                  <CardSelectItem accessibilityLabel="New export case" onPress={() => { setVariant("export"); setPhase("form"); }} style={{ flexDirection: "row", alignItems: "center", gap: 12 }}>
+                    <Icon name="arrow-up" size={18} color={colors.zinc[700]} />
+                    <View style={{ flex: 1, gap: 2 }}>
+                      <Text size="sm" weight="semibold">Export case</Text>
+                      <Text size="xs" color="muted">Outbound paperwork — the record seeds the customs-out checklist.</Text>
+                    </View>
+                  </CardSelectItem>
+                  <CardSelectItem accessibilityLabel="New import case" onPress={() => { setVariant("import"); setPhase("form"); }} style={{ flexDirection: "row", alignItems: "center", gap: 12 }}>
+                    <Icon name="arrow-down" size={18} color={colors.zinc[700]} />
+                    <View style={{ flex: 1, gap: 2 }}>
+                      <Text size="sm" weight="semibold">Import case</Text>
+                      <Text size="xs" color="muted">Inbound paperwork — the record seeds the customs-in checklist.</Text>
+                    </View>
+                  </CardSelectItem>
                 </View>
-              </CardSelectItem>
-            </View>
-          </View>
+              </>
+            )}
+          </FileDropTarget>
         ) : null}
 
         {phase === "analyze" || phase === "running" ? (
@@ -1336,8 +1408,7 @@ function EnterDataDialog({ onCreate, onCreateMany }: {
           </DialogFooter>
         ) : null}
       </Dialog>
-      </ChangeReview>
-    </>
+    </ChangeReview>
   );
 }
 
@@ -1405,6 +1476,15 @@ export function TplItemList() {
     records.forEach((r) => addRow(r.khach, r.dienThoai, r.phi));
     revealNew();
   };
+  // The intake dialog is CONTROLLED here so BOTH the toolbar button and the
+  // whole-register FileDropTarget drive it: the button opens it empty, a
+  // top-level drop/paste opens it PRE-SEEDED with the dropped files (mapped to
+  // DisplayFiles so the pile shows as thumbnail cards — the paid "Read with AI"
+  // stays a deliberate button).
+  const [intakeOpen, setIntakeOpen] = useState(false);
+  const [intakeSeed, setIntakeSeed] = useState<DisplayFile[]>([]);
+  const openIntake = () => { setIntakeSeed([]); setIntakeOpen(true); };
+  const openIntakeSeeded = (dropped: File[]) => { setIntakeSeed(toDisplayFiles(dropped)); setIntakeOpen(true); };
   const [sort, setSort] = useState<SortState | null>(null);
   const [assignee, setAssignee] = useState<string[]>([]);
   const [feeStatus, setFeeStatus] = useState<"paid" | "unpaid" | null>(null);
@@ -1475,6 +1555,17 @@ export function TplItemList() {
 
   return (
     <View style={{ flex: 1 }}>
+    {/* WHOLE-SURFACE INTAKE — the standard this template DEMONSTRATES: the ENTIRE
+        register page is one `FileDropTarget`, so a file dropped or a Ctrl/Cmd+V
+        pasted ANYWHERE on the register opens the intake dialog PRE-SEEDED with
+        those files (list-first — the paid "Read with AI" stays a button). No
+        `disabled`: the intake's own inner `FileDropzone` and the record drawer's
+        Files section are later-mounted paste sinks, so while either is open the
+        paste routes THERE (top of stack); a nested drop is stopPropagation-safe.
+        `flex:1` keeps the ScrollView filling the page (the bar + drawer overlay
+        on top); the accent ring frames the page on drag. A real app opts in
+        per-app — this page is the reference shape. */}
+    <FileDropTarget onFiles={openIntakeSeeded} paste style={{ flex: 1 }}>
     <ScrollView style={{ flex: 1, backgroundColor: colors.white }} contentContainerStyle={{ padding: 28 }}>
       <View style={{ width: "100%", maxWidth: 1040, alignSelf: "center", gap: 16 }}>
         {/* header — title only; the New case action lives on the toolbar row */}
@@ -1546,7 +1637,9 @@ export function TplItemList() {
               onChange={(v) => { setFeeAmount(v); setPage(0); }}
             />
           </View>
-          <EnterDataDialog onCreate={createRecord} onCreateMany={createRecordsBulk} />
+          {/* the intake TRIGGER — the register's whole-surface drop/paste opens
+              the same dialog (see the FileDropTarget wrapper below) */}
+          <Button title="Enter data" color="primary" onPress={openIntake} />
         </View>
 
         {/* light summary of the filtered register (search/assignee/fee applied; status counts stay visible across tabs) */}
@@ -1603,6 +1696,11 @@ export function TplItemList() {
         </View>
       </View>
     </ScrollView>
+    </FileDropTarget>
+
+      {/* the intake dialog — CONTROLLED, driven by the toolbar button AND the
+          whole-register drop/paste above (opened seeded with the dropped files) */}
+      <EnterDataDialog open={intakeOpen} onOpenChange={setIntakeOpen} seedDocs={intakeSeed} onCreate={createRecord} onCreateMany={createRecordsBulk} />
 
       {/* bulk action over the ticked cases — the shared floating bar */}
       <FloatingActionBar