@lotics/ui 41.0.0 → 41.1.0

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` + `loticsResolve()` — the pre-bundle list and the whole `resolve` block a custom-code app's `vite.config.ts` imports rather than hand-carries, dev-link included). 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, browser-autofill suppression (search controls only), 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/data_entry.md](./docs/data_entry.md) | Which editing pattern for which job — inline edit, fieldset forms, browser-autofill suppression (search controls only), find-or-create (`Combobox`), line items, handoffs, phased records, billing, tags, dispositions, attachments (`InlineFiles` for a record ROW — list + one CTA, `multiple` decides add-vs-replace; the `FilesEditor` COMPOUND for a whole section — 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 — it turns on WHO supplied the values (machine → a gate: a diff when something is being replaced, a full editable preview when records are being created from a document; human-typed → 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, **Stop** while streaming), **stopping** (`cancel` stops the run, `abort` only stops listening — so closing a dialog must `cancel` or it keeps billing); **review surfaces compose from atoms** — `DiffValue` (a changed value, droppable in any cell/row/total), `DiffMark` (what happened to the row — ONE circular disc, every surface), `useChangeSet` (accept/reject/undo bookkeeping, no layout) — see [MIGRATION.md](./MIGRATION.md) for the `ChangeReview` family they replace |
 | [docs/composition.md](./docs/composition.md) | The design-language contract — canvas + content column, heading altitude (incl. eyebrow vs group lead — a label is one or the other), banded cards, register vs inset rows (incl. the register laws a row centres its cells by: every cell a FIXED height, a pressable cell on the shared hover token, a column sized by what it carries), master-detail `Drawer` on a LIST screen vs a child collection's row EXPANDING inside a record, view controls, RECORD EXTENT (one page, sections scrolled to and never routed to), color discipline, typography, whitespace, and how to TEST an overlay component (a `Popover`-backed surface never mounts under jsdom). |
 | [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,29 @@ 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.
 
+## 41.1.0 — `FileRows` no longer captions every row with the file type
+
+`meta` defaulted to the file-type label, so a row read `contract.pdf` with `PDF` under it. The
+type was already stated three other ways — the `FileBadge`'s colour, the label printed inside
+that glyph, and the filename's own extension — so the caption was a fourth statement of one
+fact, costing a line of row height per file to say nothing.
+
+**Every `FileRows` in the repo took this default and passed no `meta`**, so this changes what
+your file lists render: each row loses its second line and gets shorter. No API is removed and
+nothing breaks a type.
+
+To keep the old caption, ask for it:
+
+```diff
+- <FileRows files={files} />
++ <FileRows files={files} meta={(f) => resolveMime(f.mimeType).label} />
+```
+
+`resolveMime` is exported from `@lotics/ui/file_badge`.
+
+Better: pass something the NAME does not already carry — what an invoice covers, who uploaded
+it, when it landed. That is what a second line is for.
+
 ## 41.0.0 — `RingGauge` is `ProgressRing`, and circular progress is one component
 
 `RingGauge` is **deleted**. `ProgressRing` replaces it and covers both what it did and the

package/docs/catalog.md

@@ -926,6 +926,21 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   a data-grid cell is `<InlineSelect variant="bare" …/>`, not a `SelectCell` (naming a component for a
   USE, and duplicating the picker stack to flip two style properties, are both things the kit forbids).
   Hand-roll a pressable cell to match `bare`, never a background wash.
+- **`inline_files`** — `InlineFiles`: the FILES member of the Inline\* family — a record's
+  attachments as a `DetailRow` value. A `FileRows` LIST (press a row to preview full-screen, ⋯
+  to remove) with ONE CTA under it; no selection mode, no bulk bar, no upload queue — reach for
+  `FilesEditor` when a surface genuinely needs those, which a record row does not. **`multiple`
+  is the FIELD's cardinality and it changes the verb**: many → the CTA reads `addMoreLabel` and
+  the host APPENDS in `onAdd`; one → it reads `replaceLabel` and the host SETS, because "add
+  another" is not an act a single-file field can perform and offering it is how a record ends up
+  holding two of something the schema says there is one of (the component owns the affordance,
+  it cannot own the persistence). `blockedReason` renders a sentence instead of the CTA for a
+  field with nothing to attach TO yet — never a disabled button, which says only that you may
+  not. A LIST and not switchable: documents are identified by NAME, images by CONTENT, so a
+  photo field wants `FileGrid`/`FilesEditor` instead — that is a judgment about the data, so it
+  picks the component rather than setting a prop. Sits on the inline grid's VERTICAL beat with
+  NO horizontal inset (unlike `InlineSlot`, which insets 9px to align a raw STRING's baseline):
+  its children are boxes, and a box aligns with the editors' box, not with their text.
 - **`inline_static`** — `InlineStatic`: a READ-ONLY value matching the Inline\* box metrics
   EXACTLY (height, padding, 1px transparent border) so a non-editable field — a computed
   total, a system ID, a synced/locked value — aligns pixel-for-pixel in the same column;
@@ -1546,7 +1561,11 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `TableRow` 52, this component's own `md` 56), which is what "squeezed" literally was.
 - **`file_rows`** — `FileRows`: batteries-included file list — row press → built-in gallery
   + a ⋯ Download/Open-external/Remove menu; composes `FileRow` + `ActionMenu` +
-  `FileGalleryModal`; localized via the `gallery` locale slice.
+  `FileGalleryModal`; localized via the `gallery` locale slice. **`meta` has NO default**: the
+  badge states the type as colour and as a label, and the filename ends in the extension, so a
+  type caption was a fourth statement of one fact costing a line of row height. Pass a second
+  line only when it carries something the NAME does not — what an invoice covers, who uploaded
+  it, when it landed.
 - **`file_badge`** — `FileBadge`: the two-tone file-type mark (PDF / XLSX / DOCX / video /
   audio …) driven by MIME. Its `size` is the badge's WIDTH and everything scales off it —
   the mark is TALLER than it is wide (26 × 32 by default), so a square slot takes the

package/docs/data_entry.md

@@ -25,7 +25,8 @@ 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; intake = CTA + drop-anywhere + paste) | add / preview / delete |
+| FILES on a record ROW | [**`InlineFiles`**](#inlinefiles--the-files-member-of-the-inline-family) — a list + one CTA, on the inline-control grid | documents are identified by NAME, and the value column stays a column |
+| FILES as a whole SECTION | [**attachment field**](#attachments--a-full-add--preview--delete-field) (dropzone + grid + gallery; intake = CTA + drop-anywhere + paste) | add / preview / delete, with select + bulk |
 | 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
@@ -553,6 +554,48 @@ blue open) with a quiet, REVERSIBLE **Change**: a popover STATE SWITCHER (each s
 dot + label, current marked + disabled), not a generic text menu. A composition (Badge + Button +
 Popover/MenuButton).
 
+## `InlineFiles` — the FILES member of the `Inline*` family
+
+A record field whose value is documents. `<DetailRow label="Scan"><InlineFiles … /></DetailRow>`
+— a `FileRows` list (press a row to preview it full-screen, ⋯ to remove) with one CTA under it,
+sitting on the inline-control grid via `InlineSlot`.
+
+It exists because every other field type shipped BOTH halves — `Select`/`InlineSelect`,
+`TextInputField`/`InlineTextInput` — and files shipped only the section-scale one. So a record
+field holding documents got hand-rolled per app as `FileRows` + `pickFiles` + a `Button`, and
+each copy re-derived the same decisions. The one they missed is `InlineSlot`: raw children in a
+value column start at the cell edge and 20px tall, beside editors that are 40px with a 9px text
+inset, so the column acquires two left edges and two baselines and stops reading as a column.
+
+**Cardinality is a property of the FIELD, and it changes the verb.**
+
+| `multiple` | picker | CTA once something is attached | the host's `onAdd` must |
+|---|---|---|---|
+| `true` (default) | many at once | `addMoreLabel` — "Add page" | APPEND |
+| `false` | exactly one | `replaceLabel` — "Replace contract" | **SET** |
+
+"Add another" is not an act a single-file field can perform, and offering it produces a field
+holding two of something the schema says there is one of. The component gets the affordance
+right; it cannot enforce the persistence, because it does not own the data — so the difference
+lives at the call site, `onAdd={([f]) => setFile(f)}` against
+`onAdd={(fs) => setFiles([...files, ...fs])}`, where it is decided.
+
+**Nothing to attach TO yet is a real state.** Pass `blockedReason` and the CTA is replaced by a
+sentence naming the act that unblocks it ("attach the invoice number first"). Never a disabled
+button: disabled says you may not and leaves the reader to work out why and what would change
+it — same pixels, one of them useful.
+
+**A LIST, and not switchable.** Documents are identified by NAME; a PDF/Word/Excel thumbnail is
+a grey page identical to every other grey page, so a grid of them is a wall of one tile under a
+truncated caption. Images are identified by their CONTENT and want `FileGrid`/`FilesEditor`.
+Which one a field holds is a judgment about the DATA, so it picks the component rather than
+setting a prop on this one.
+
+Lean by design — no selection mode, no bulk bar, no upload queue. The kit never uploads: the
+host takes `File[]`, stores them, and passes the result back as `files`. Return a promise from
+`onAdd` and the CTA stays busy until it settles, which is the whole loading state — a control
+that re-arms immediately invites the second press that files it twice.
+
 ## Attachments — a full add / preview / DELETE field
 
 ### Intake — files land THREE ways, on every surface that holds files

package/examples/tpl_item_list.tsx

@@ -49,6 +49,7 @@ import { FileDropTarget } from "@lotics/ui/file_drop_target";
 import { Link } from "@lotics/ui/link";
 import { TextInputField } from "@lotics/ui/text_input_field";
 import type { DisplayFile } from "@lotics/ui/file_thumbnail";
+import { InlineFiles } from "@lotics/ui/inline_files";
 import { InlineSelect } from "@lotics/ui/inline_select";
 import { InlineTextInput } from "@lotics/ui/inline_text_input";
 import { useSelection } from "@lotics/ui/use_selection";
@@ -361,6 +362,7 @@ function LinkedRecordScreen({ ma }: { ma: string }) {
   const [ngayNhan, setNgayNhan] = useState(() => (r ? isoReceived(r.ngayNhan) : ""));
   const [collected, setCollected] = useState(r?.daThu ? "yes" : "no");
   const [fee, setFee] = useState<number | null>(r?.phi ?? null);
+  const [docs, setDocs] = useState<DisplayFile[]>([]);
   if (!r) return null;
   return (
     <>
@@ -380,6 +382,25 @@ function LinkedRecordScreen({ ma }: { ma: string }) {
             <DetailRow label="Fee">
               <InlineNumberInput value={fee} onSave={persist(setFee)} min={0} format={(v) => (v == null ? "" : formatMoney(v))} accessibilityLabel="Fee" />
             </DetailRow>
+            {/* FILES AS A FIELD — the `Inline*` member that used to be missing,
+                so a record's documents got hand-rolled per app as `FileRows` +
+                `pickFiles` + a `Button`, each copy re-deriving the same
+                decisions and usually missing `InlineSlot` (which is what keeps
+                this value column a column rather than two left edges).
+
+                The MANY case: `multiple` defaults true, the CTA becomes
+                "Add document" once something is attached, and the host APPENDS.
+                `tpl_record` shows the single-file case, where the verb is
+                replace — see the table in data_entry.md §InlineFiles. */}
+            <DetailRow label="Documents">
+              <InlineFiles
+                files={docs}
+                onAdd={(picked) => setDocs((p) => [...p, ...toDisplayFiles(picked)])}
+                onRemove={(f) => setDocs((p) => p.filter((x) => x.id !== f.id))}
+                addLabel="Attach document"
+                addMoreLabel="Add document"
+              />
+            </DetailRow>
             <DetailRow label="Collected">
               <InlineSelect
                 value={collected}

package/examples/tpl_record.tsx

@@ -1,5 +1,5 @@
 import { Fragment, useEffect, useRef, useState, type ReactNode, useMemo } from "react";
-import { ScrollView, View } from "react-native";
+import { Pressable, ScrollView, View } from "react-native";
 import { Text } from "@lotics/ui/text";
 import { colors } from "@lotics/ui/colors";
 import { DRAWER_GUTTER } from "@lotics/ui/drawer";
@@ -8,6 +8,7 @@ import { BackButton } from "@lotics/ui/back_button";
 import { Divider } from "@lotics/ui/divider";
 import { Link } from "@lotics/ui/link";
 import { Icon } from "@lotics/ui/icon";
+import { TextLink } from "@lotics/ui/text_link";
 import { Alert } from "@lotics/ui/alert";
 import type { PickerOption } from "@lotics/ui/picker";
 import { Combobox, ComboboxInput, ComboboxContent } from "@lotics/ui/combobox";
@@ -31,7 +32,9 @@ import { Skeleton } from "@lotics/ui/skeleton";
 import { CommentList, type CommentEditFormProps, type ThreadComment, type ThreadFile } from "@lotics/ui/comments_thread";
 import { Composer } from "@lotics/ui/composer";
 import { IconButton } from "@lotics/ui/icon_button";
+import { FileBadge } from "@lotics/ui/file_badge";
 import { FileRows } from "@lotics/ui/file_rows";
+import { InlineFiles } from "@lotics/ui/inline_files";
 import { FileGrid } from "@lotics/ui/file_grid";
 import { ActionMenu, type ActionMenuItem } from "@lotics/ui/action_menu";
 import { InlineStatic } from "@lotics/ui/inline_static";
@@ -399,6 +402,19 @@ const PANEL_GUTTER = PANEL_W + RAIL_GAP;
  * `Drawer`'s 600 it sat between two columns of its own order and stopped reading
  * as the thing the page is about. */
 const CONTENT_MAX = 680;
+/** The page's own horizontal padding. Named because `groupW` subtracts it and
+ *  the panel's fold threshold must add it back — they were written apart, and
+ *  the threshold omitted it, so the reading column could sit a full 56px UNDER
+ *  the floor the same code declared. A floor that is not enforced is not a
+ *  floor; it is a comment. */
+const PAGE_PAD = 28;
+/** What the reading column needs to stay readable beside both gutters — a label
+ *  column plus its values, not what it would like. Below this the discussion
+ *  panel FOLDS to an inline section, which is the template's stated rule
+ *  ("when the two compete the panel is what gives way") finally implemented:
+ *  the panel's width is a constant, so without a floor on this side the reading
+ *  column absorbed every squeeze and the rule ran backwards. */
+const CONTENT_FLOOR = 420;
 
 // ── the DOCUMENT DESK — the Agents "Document desk" pattern, carried as the
 // record's documents surface: files feed ONE "Use AI" entry that forks into
@@ -415,6 +431,7 @@ function fmtSize(kb: number): string {
   if (kb <= 0) return "—";
   return kb < 1024 ? `${kb} KB` : `${(kb / 1024).toFixed(1)} MB`;
 }
+const MOCK_PDF_URL = "data:application/pdf;base64,JVBERi0xLjQKMSAwIG9iajw8L1R5cGUvQ2F0YWxvZy9QYWdlcyAyIDAgUj4+ZW5kb2JqCjIgMCBvYmo8PC9UeXBlL1BhZ2VzL0tpZHNbMyAwIFJdL0NvdW50IDE+PmVuZG9iagozIDAgb2JqPDwvVHlwZS9QYWdlL1BhcmVudCAyIDAgUi9NZWRpYUJveFswIDAgNjEyIDc5Ml0vQ29udGVudHMgNCAwIFIvUmVzb3VyY2VzPDwvRm9udDw8L0YxIDUgMCBSPj4+Pj4+ZW5kb2JqCjQgMCBvYmo8PC9MZW5ndGggNjM+PnN0cmVhbQpCVCAvRjEgMTggVGYgNzIgNzIwIFRkIChOb3JkaWMgRnVybml0dXJlIC0gbW9jayBkb2N1bWVudCkgVGogRVQKZW5kc3RyZWFtIGVuZG9iago1IDAgb2JqPDwvVHlwZS9Gb250L1N1YnR5cGUvVHlwZTEvQmFzZUZvbnQvSGVsdmV0aWNhPj5lbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTIgMDAwMDAgbiAKMDAwMDAwMDEwMSAwMDAwMCBuIAowMDAwMDAwMjExIDAwMDAwIG4gCjAwMDAwMDAzMjAgMDAwMDAgbiAKdHJhaWxlcjw8L1NpemUgNi9Sb290IDEgMCBSPj4Kc3RhcnR4cmVmCjM4MQolJUVPRg==";
 const MOCK_PHOTO_URL =
   "data:image/svg+xml;base64,PHN2ZyB4bWxucz0naHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmcnIHdpZHRoPSczMjAnIGhlaWdodD0nMzIwJz48cmVjdCB3aWR0aD0nMzIwJyBoZWlnaHQ9JzMyMCcgZmlsbD0nI2JmZGJmZScvPjxyZWN0IHk9JzIxMCcgd2lkdGg9JzMyMCcgaGVpZ2h0PScxMTAnIGZpbGw9JyNhOGEyOWUnLz48cmVjdCB4PScyMCcgeT0nMTUwJyB3aWR0aD0nMTI0JyBoZWlnaHQ9JzYwJyBmaWxsPScjZGMyNjI2Jy8+PHJlY3QgeD0nMTUyJyB5PScxNTAnIHdpZHRoPScxMjQnIGhlaWdodD0nNjAnIGZpbGw9JyMyNTYzZWInLz48cmVjdCB4PSc4NicgeT0nODgnIHdpZHRoPScxMjQnIGhlaWdodD0nNjAnIGZpbGw9JyNmNTllMGInLz48cmVjdCB4PScyNjInIHk9JzI0JyB3aWR0aD0nMTAnIGhlaWdodD0nMTg2JyBmaWxsPScjNTI1MjUyJy8+PHJlY3QgeD0nMTUwJyB5PScyNCcgd2lkdGg9JzEyMicgaGVpZ2h0PScxMCcgZmlsbD0nIzUyNTI1MicvPjwvc3ZnPg==";
 const DOCS: Doc[] = [
@@ -436,6 +453,11 @@ const DOCS: Doc[] = [
   { id: "p4", name: "cont-rong-mat-truoc.jpg", mimeType: "image/jpeg", kind: "JPG", sizeKB: 1231, added: "01 Jul", addedAt: 701, url: "data:image/svg+xml;base64,PHN2ZyB4bWxucz0naHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmcnIHdpZHRoPSczMjAnIGhlaWdodD0nMzIwJz48cmVjdCB3aWR0aD0nMzIwJyBoZWlnaHQ9JzMyMCcgZmlsbD0nI2U5ZDVmZicvPjxyZWN0IHk9JzIxMCcgd2lkdGg9JzMyMCcgaGVpZ2h0PScxMTAnIGZpbGw9JyNhMWExYWEnLz48cmVjdCB4PScyMCcgeT0nMTUwJyB3aWR0aD0nMTI0JyBoZWlnaHQ9JzYwJyBmaWxsPScjYmUxMjNjJy8+PHJlY3QgeD0nMTUyJyB5PScxNTAnIHdpZHRoPScxMjQnIGhlaWdodD0nNjAnIGZpbGw9JyMxZTI5M2InLz48cmVjdCB4PSc4NicgeT0nODgnIHdpZHRoPScxMjQnIGhlaWdodD0nNjAnIGZpbGw9JyNiZTEyM2MnIG9wYWNpdHk9JzAuNycvPjwvc3ZnPg==" },
   { id: "p5", name: "cont-rong-ben-trong.jpg", mimeType: "image/jpeg", kind: "JPG", sizeKB: 1368, added: "01 Jul", addedAt: 701, url: "data:image/svg+xml;base64,PHN2ZyB4bWxucz0naHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmcnIHdpZHRoPSczMjAnIGhlaWdodD0nMzIwJz48cmVjdCB3aWR0aD0nMzIwJyBoZWlnaHQ9JzMyMCcgZmlsbD0nI2ZlY2FjYScvPjxyZWN0IHk9JzIxMCcgd2lkdGg9JzMyMCcgaGVpZ2h0PScxMTAnIGZpbGw9JyM0NDQwM2MnLz48cmVjdCB4PScyMCcgeT0nMTUwJyB3aWR0aD0nMTI0JyBoZWlnaHQ9JzYwJyBmaWxsPScjMGY3NjZlJy8+PHJlY3QgeD0nMTUyJyB5PScxNTAnIHdpZHRoPScxMjQnIGhlaWdodD0nNjAnIGZpbGw9JyMzMzQxNTUnLz48cmVjdCB4PSc4NicgeT0nODgnIHdpZHRoPScxMjQnIGhlaWdodD0nNjAnIGZpbGw9JyMwZjc2NmUnIG9wYWNpdHk9JzAuNycvPjwvc3ZnPg==" },
   { id: "p6", name: "bien-so-xe.jpg", mimeType: "image/jpeg", kind: "JPG", sizeKB: 1505, added: "01 Jul", addedAt: 701, url: "data:image/svg+xml;base64,PHN2ZyB4bWxucz0naHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmcnIHdpZHRoPSczMjAnIGhlaWdodD0nMzIwJz48cmVjdCB3aWR0aD0nMzIwJyBoZWlnaHQ9JzMyMCcgZmlsbD0nI2ZlZjA4YScvPjxyZWN0IHk9JzIxMCcgd2lkdGg9JzMyMCcgaGVpZ2h0PScxMTAnIGZpbGw9JyM1MjUyNTInLz48cmVjdCB4PScyMCcgeT0nMTUwJyB3aWR0aD0nMTI0JyBoZWlnaHQ9JzYwJyBmaWxsPScjN2UyMmNlJy8+PHJlY3QgeD0nMTUyJyB5PScxNTAnIHdpZHRoPScxMjQnIGhlaWdodD0nNjAnIGZpbGw9JyMxZTNhOGEnLz48cmVjdCB4PSc4NicgeT0nODgnIHdpZHRoPScxMjQnIGhlaWdodD0nNjAnIGZpbGw9JyM3ZTIyY2UnIG9wYWNpdHk9JzAuNycvPjwvc3ZnPg==" },
+  // NOT an image, deliberately: the signed note is evidence of the same hand-over
+  // as the frames around it, and it is the tile a fixture of eight JPGs never
+  // rendered. `FileThumbnail` shows a doc tile (badge + name) — no code needed,
+  // only a fixture honest enough to reach it.
+  { id: "p8", name: "bien-ban-giao-nhan-da-ky.pdf", mimeType: "application/pdf", kind: "PDF", sizeKB: 412, added: "02 Jul", addedAt: 702, url: MOCK_PDF_URL },
   { id: "p7", name: "bang-ke-giao-nhan.jpg", mimeType: "image/jpeg", kind: "JPG", sizeKB: 1642, added: "02 Jul", addedAt: 702, url: "data:image/svg+xml;base64,PHN2ZyB4bWxucz0naHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmcnIHdpZHRoPSczMjAnIGhlaWdodD0nMzIwJz48cmVjdCB3aWR0aD0nMzIwJyBoZWlnaHQ9JzMyMCcgZmlsbD0nI2E1ZjNmYycvPjxyZWN0IHk9JzIxMCcgd2lkdGg9JzMyMCcgaGVpZ2h0PScxMTAnIGZpbGw9JyM3MzczNzMnLz48cmVjdCB4PScyMCcgeT0nMTUwJyB3aWR0aD0nMTI0JyBoZWlnaHQ9JzYwJyBmaWxsPScjYzI0MTBjJy8+PHJlY3QgeD0nMTUyJyB5PScxNTAnIHdpZHRoPScxMjQnIGhlaWdodD0nNjAnIGZpbGw9JyMwNjRlM2InLz48cmVjdCB4PSc4NicgeT0nODgnIHdpZHRoPScxMjQnIGhlaWdodD0nNjAnIGZpbGw9JyNjMjQxMGMnIG9wYWNpdHk9JzAuNycvPjwvc3ZnPg==" },
 ];
 
@@ -607,14 +629,30 @@ const PDF = "application/pdf";
 
 /**
  * A file rendered as a table VALUE — the filename at the size every other cell
- * uses.
+ * uses. The ONE-FACT cell: the name IS the value, so it is rendered like the
+ * quantity beside it and nothing else is added.
  *
  * It carried a `FileBadge` at first, which in a cell that size shrank its own
  * label to five pixels — off every rung of the type scale. Making it legible
  * means a 34px box setting the height of a 52px row, for a fact the extension
- * already carries. The discriminator is what the file IS on the surface: the
- * row's SUBJECT (a `FileRow`, a tile) earns a badge; one VALUE among columns is
- * a value, rendered like the quantity beside it.
+ * already carries.
+ *
+ * The discriminator is HOW MANY FACTS the cell owes the reader. This cell owes
+ * ONE — which document — and the name is it.
+ *
+ * A cell owing TWO is a different shape and wants a mark this one must not
+ * borrow: a reference the desk quotes (an invoice number) PLUS whether the
+ * document behind it is on file, where nothing in the value answers the second
+ * question. `tpl_item_list`'s register is the worked example — it is a
+ * full-width surface with room for the column, which this page is not: measured
+ * at 1280 the fee table already shows 3 of its 5 columns, because a record page
+ * spends its width on a nav rail and a comments column. A column that always
+ * drops teaches nothing, so the rule lives here and the example lives there.
+ *
+ * The mark is a monochrome clip, NOT a `FileBadge`: a badge's payload beyond
+ * presence is the file's TYPE, its label is unreadable at row scale (5px
+ * measured), and on a ledger where every document is a PDF it spends a hue on
+ * something that never varies.
  */
 function DocName({ doc }: { doc: LineDoc }) {
   return <Text size="sm" numberOfLines={1}>{doc.name}</Text>;
@@ -665,7 +703,6 @@ const FINDINGS: Check[] = [
 ];
 
 // A tiny REAL pdf (data URI) so the gallery preview genuinely renders.
-const MOCK_PDF_URL = "data:application/pdf;base64,JVBERi0xLjQKMSAwIG9iajw8L1R5cGUvQ2F0YWxvZy9QYWdlcyAyIDAgUj4+ZW5kb2JqCjIgMCBvYmo8PC9UeXBlL1BhZ2VzL0tpZHNbMyAwIFJdL0NvdW50IDE+PmVuZG9iagozIDAgb2JqPDwvVHlwZS9QYWdlL1BhcmVudCAyIDAgUi9NZWRpYUJveFswIDAgNjEyIDc5Ml0vQ29udGVudHMgNCAwIFIvUmVzb3VyY2VzPDwvRm9udDw8L0YxIDUgMCBSPj4+Pj4+ZW5kb2JqCjQgMCBvYmo8PC9MZW5ndGggNjM+PnN0cmVhbQpCVCAvRjEgMTggVGYgNzIgNzIwIFRkIChOb3JkaWMgRnVybml0dXJlIC0gbW9jayBkb2N1bWVudCkgVGogRVQKZW5kc3RyZWFtIGVuZG9iago1IDAgb2JqPDwvVHlwZS9Gb250L1N1YnR5cGUvVHlwZTEvQmFzZUZvbnQvSGVsdmV0aWNhPj5lbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTIgMDAwMDAgbiAKMDAwMDAwMDEwMSAwMDAwMCBuIAowMDAwMDAwMjExIDAwMDAwIG4gCjAwMDAwMDAzMjAgMDAwMDAgbiAKdHJhaWxlcjw8L1NpemUgNi9Sb290IDEgMCBSPj4Kc3RhcnR4cmVmCjM4MQolJUVPRg==";
 const toDisplay = (d: Doc): DisplayFile => ({ id: d.id, filename: d.name, mimeType: d.mimeType, url: d.url ?? MOCK_PDF_URL });
 /** A comment's ThreadFile (snake_case, the API shape) → the kit's DisplayFile. */
 const commentFileToDisplay = (f: ThreadFile): DisplayFile => ({ id: f.id, filename: f.filename, mimeType: f.mime_type, url: f.url ?? "", thumbnailUrl: f.thumbnail_url });
@@ -707,6 +744,16 @@ const iso = (d: Date): string => d.toISOString().slice(0, 10);
 // display VAT / Invoice no / Note — it drops them silently. And `note` is prose:
 // it has no column width at any measure.
 type FeeDirection = "charge" | "cost";
+/** A picked `File` as the kit's `DisplayFile`. A real host uploads and returns
+ *  the stored object; the object URL stands in for that here. */
+let feeDocSeq = 0;
+const asDisplayFile = (f: File): DisplayFile => ({
+  id: `fee-doc-u${(feeDocSeq += 1)}`,
+  filename: f.name,
+  mimeType: f.type || "application/octet-stream",
+  url: URL.createObjectURL(f),
+});
+
 interface Fee {
   id: string;
   name: string;
@@ -717,25 +764,41 @@ interface Fee {
   vat: number | null;
   due: string;
   invoiceNo: string;
+  /** The supplier's original, filed against THIS fee. A number is what the field
+   *  claimed; these are what actually arrived, and the gap between them is the
+   *  work a payables desk does. */
+  docs: DisplayFile[];
   paid: boolean;
   note: string;
 }
 let feeSeq = 4;
 const FEE_SEED: Fee[] = [
-  { id: "fee_1", name: "Freight surcharge", direction: "charge", party: "Harbor Freight Lines", amount: 350_000, vat: 8, due: "", invoiceNo: "", paid: true, note: "" },
-  { id: "fee_2", name: "Trucking", direction: "cost", party: "Northline Haulage", amount: 450_000, vat: 8, due: "2026-07-02", invoiceNo: "NH-2044", paid: false, note: "Last-mile to the port" },
-  { id: "fee_3", name: "Customs advance", direction: "cost", party: "Blue Anchor Brokerage", amount: 275_000, vat: null, due: "", invoiceNo: "BA-118", paid: true, note: "" },
-  { id: "fee_4", name: "Storage overrun", direction: "charge", party: "Harbor Freight Lines", amount: 120_000, vat: 8, due: "2026-08-02", invoiceNo: "", paid: false, note: "3 extra days at Central hub" },
+  { id: "fee_1", name: "Freight surcharge", direction: "charge", party: "Harbor Freight Lines", amount: 350_000, vat: 8, due: "", invoiceNo: "", docs: [], paid: true, note: "" },
+  { id: "fee_2", name: "Trucking", direction: "cost", party: "Northline Haulage", amount: 450_000, vat: 8, due: "2026-07-02", invoiceNo: "NH-2044", docs: [{ id: "fee-doc-1", filename: "NH-2044-invoice.pdf", mimeType: "application/pdf", url: MOCK_PDF_URL }], paid: false, note: "Last-mile to the port" },
+  // UNPAID with a number claimed and nothing filed — the state the status column
+  // exists to surface. It was `paid: true`, which meant "Awaiting invoice" could
+  // never render and the design could not be seen at all.
+  { id: "fee_3", name: "Customs advance", direction: "cost", party: "Blue Anchor Brokerage", amount: 275_000, vat: null, due: "", invoiceNo: "BA-118", docs: [], paid: false, note: "" },
+  // A PHOTO of an invoice, not a PDF — the case the badge exists for. A supplier
+  // who sends a phone snap has not sent a tax document, and the colour says so
+  // before anyone opens it. A fixture of nothing but PDFs makes the badge look
+  // like decoration, because the one thing it carries never varies.
+  { id: "fee_4", name: "Storage overrun", direction: "charge", party: "Harbor Freight Lines", amount: 120_000, vat: 8, due: "2026-08-02", invoiceNo: "HF-8821", docs: [{ id: "fee-doc-2", filename: "storage-invoice-photo.jpg", mimeType: "image/jpeg", url: MOCK_PHOTO_URL }], paid: false, note: "3 extra days at Central hub" },
 ];
 // `priority` = the mobile contract: Party then Type drop first on a narrow
 // container, Amount + Status survive with the identity; at the floor the rows
 // STACK label-over-value — and the expansion always carries the full fee.
+// THREE columns, not five — the register's grammar. A column per FACT spends
+// width on separation the reader never asked for: the party belongs to the fee's
+// identity and the payment state belongs to its amount, so each rides line 2 of
+// the cell it qualifies. Grouping bought 246px (Party 150 + Status 96), which is
+// more than the document column costs — the table gained information and lost
+// two columns. `tpl_item_list` stacks both of these already; this table was the
+// outlier.
 const FEE_COLUMNS: TableColumn[] = [
   { key: "fee", label: "Fee", flex: 1 },
-  { key: "type", label: "Type", width: 72, priority: 3 },
-  { key: "party", label: "Party", width: 150, priority: 4 },
   { key: "amount", label: "Amount", width: 104, align: "right", priority: 1 },
-  { key: "status", label: "Status", width: 96, priority: 2 },
+  { key: "invoice", label: "Invoice", width: 116, priority: 2 },
 ];
 const feeOverdue = (f: Fee): boolean => !f.paid && f.due !== "" && new Date(f.due) < new Date();
 
@@ -1162,7 +1225,7 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418", openSection
   const [feeView, setFeeView] = useState<{ kind: "edit"; id: string } | null>(null);
   const patchFee = (id: string, p: Partial<Fee>) => setFees((prev) => prev.map((f) => (f.id === id ? { ...f, ...p } : f)));
   const addFee = () => {
-    const f: Fee = { id: `fee_${(feeSeq += 1)}`, name: "", direction: "cost", party: "", amount: 0, vat: null, due: "", invoiceNo: "", paid: false, note: "" };
+    const f: Fee = { id: `fee_${(feeSeq += 1)}`, name: "", direction: "cost", party: "", amount: 0, vat: null, due: "", invoiceNo: "", docs: [], paid: false, note: "" };
     setFees((prev) => [...prev, f]);
     setFeeView({ kind: "edit", id: f.id });
   };
@@ -1173,6 +1236,15 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418", openSection
     ]);
   };
   // The status column speaks in facts: Paid, Overdue, Due <date>, Unpaid.
+  /**
+   * MONEY state only — it rides under the amount it is about.
+   *
+   * "Awaiting docs" lived here while the document had no column of its own, and
+   * it was a conflation: whether a supplier's original has arrived is not a fact
+   * about the money, and putting it in the money's state meant a fee could not
+   * report both at once. Now the Invoice column carries the document and this
+   * carries the payment, and each says one thing.
+   */
   const feeStatus = (f: Fee): { text: string; danger: boolean } =>
     f.paid ? { text: "Paid", danger: false }
       : feeOverdue(f) ? { text: "Overdue", danger: true }
@@ -1278,6 +1350,8 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418", openSection
   const [confirmIssueKey, setConfirmIssueKey] = useState<string | null>(null);
   const seq = useRef(414);
   const taxId = customer?.taxId ?? "";
+  /** The ONE signed contract — a single-file field, not a document set. */
+  const [contract, setContract] = useState<DisplayFile | null>(null);
   const taxIdValid = TAX_ID_RE.test(taxId);
 
   // ── the document desk (see the module banner above; the record's files ARE
@@ -1286,7 +1360,20 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418", openSection
   // The photo subset of the SAME collection — one list, two surfaces. Derived
   // rather than a second state, or the two sections would drift the moment
   // anything is added to one of them.
-  const photoDocs = useMemo(() => files.filter((f) => f.mimeType.startsWith("image/")), [files]);
+  /**
+   * EVERYTHING on the record, not the image subset.
+   *
+   * It filtered `mimeType.startsWith("image/")`, which read well until you asked
+   * what happens to the signed delivery note: it is evidence of the same
+   * hand-over as the photos beside it, and a MIME test filed it somewhere else.
+   * A reader looking for "what came back from the yard" then has to know which
+   * of two lenses holds each artifact — a question about the FILE FORMAT, which
+   * is never the question they actually have.
+   *
+   * `FileThumbnail` already renders a non-image as a doc tile (badge + name), so
+   * nothing here had to change for it to work — only the filter that hid it.
+   */
+  const photoDocs = files;
   /**
    * SELECT MODE — for the grid only, and only because a grid has nowhere free
    * to put a checkbox.
@@ -1934,7 +2021,13 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418", openSection
   // two gutters. The floor is what the column needs to stay readable (a label
   // column plus its values), not what it would like — hold out for the ceiling and
   // the thread folds away on every screen under ~1220.
-  const wide = pageWidth != null && pageWidth >= GUTTER + PANEL_GUTTER + 420;
+  //
+  // Every term `groupW` spends must appear here, PAGE_PAD included. It did not,
+  // and the omission ran in the dangerous direction: the check passed while the
+  // column was under its floor, so the panel kept its constant 300 and the record
+  // — the thing the page is about — took the loss. The two lines are one
+  // calculation and have to be read as one.
+  const wide = pageWidth != null && pageWidth >= PAGE_PAD * 2 + GUTTER + PANEL_GUTTER + CONTENT_FLOOR;
   // Narrow: the discussion is one tap off the same bar the sections are on —
   // on the RIGHT, opposite the section picker, since it is about the record as a
   // whole rather than a place in it.
@@ -1947,8 +2040,8 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418", openSection
   // record scrolls. (Capping the ScrollView at the column's width instead makes
   // the gutters dead zones.) Mirrors the flex maths the row does below: the
   // group is centred inside the 28px content padding.
-  const groupW = pageWidth == null ? 0 : Math.min(pageWidth - 28 * 2, GUTTER + CONTENT_MAX + PANEL_GUTTER);
-  const railLeft = pageWidth == null ? 0 : 28 + Math.max(0, (pageWidth - 28 * 2 - groupW) / 2);
+  const groupW = pageWidth == null ? 0 : Math.min(pageWidth - PAGE_PAD * 2, GUTTER + CONTENT_MAX + PANEL_GUTTER);
+  const railLeft = pageWidth == null ? 0 : PAGE_PAD + Math.max(0, (pageWidth - PAGE_PAD * 2 - groupW) / 2);
   const panelRight = railLeft;
 
   /**
@@ -2379,6 +2472,32 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418", openSection
                 <DetailRow label="Opened">
                   <InlineDatePicker value={orderDate} onSave={persist(setOrderDate)} locale="en-US" accessibilityLabel="Opened date" />
                 </DetailRow>
+                {/* FILES AS A FIELD, the SINGLE case — one signed contract, not
+                    a document set.
+                    `multiple={false}` changes the verb, and the verb is the
+                    point: "add another" is not something a one-file field can
+                    do, and offering it produces a record holding two of a thing
+                    the schema says there is one of. So the CTA reads REPLACE,
+                    the picker takes one, and the host SETS instead of appending
+                    — the component gets the affordance right but cannot enforce
+                    the persistence, which is why the difference is visible right
+                    here at the call site.
+
+                    `blockedReason` is the third state: a field with nothing to
+                    attach TO yet says which act unblocks it, rather than showing
+                    a disabled button that says only that you may not. */}
+                <DetailRow label="Signed contract">
+                  <InlineFiles
+                    files={contract === null ? [] : [contract]}
+                    multiple={false}
+                    onAdd={([picked]) => setContract({ id: "doc-contract", filename: picked.name, mimeType: picked.type || PDF, url: URL.createObjectURL(picked) })}
+                    onRemove={() => setContract(null)}
+                    addLabel="Attach contract"
+                    replaceLabel="Replace contract"
+                    accept="application/pdf"
+                    blockedReason={taxId.trim() === "" ? "Add the tax ID before filing a contract." : undefined}
+                  />
+                </DetailRow>
                 {/* The countdown ANNOTATES the date it is about — the worked
                     example for @lotics/ui/deadline. It replaced a hand-rolled
                     `error={overdue ? … }`, which was binary: a date due
@@ -2689,20 +2808,39 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418", openSection
             its NAME: a PDF thumbnail is a grey page identical to every other grey
             page, so a grid of them is a wall of one tile. A photo is identified
             by its CONTENT — `IMG_4471.jpg` tells nobody anything — so the tile IS
-            the identity and a grid puts twelve on screen at once. Same record,
-            same verbs, different surface, decided by what the reader recognises.
+            the identity and a grid puts twelve on screen at once.
             (AGENTS.md: documents get a LIST, images get a GRID.)
 
-            READ THIS BEFORE COPYING THE SHAPE. Two sections here does NOT mean
-            "sort one pile by mime type into a list and a grid". This record holds
-            two distinct SETS — the paperwork that arrived on it, and the hand-over
-            photos taken against it — which the reader asks different questions of.
-            A SINGLE pile picks ONE surface by its majority and keeps it: the odd
-            .docx among forty phone photos stays in the grid, where it renders a
-            `DocumentCard` printing its filename, and the odd photo among forty
-            PDFs stays in the list, where its row carries the full name and a press
-            opens the gallery. Splitting one set by type would give the reader two
-            places to look for the same thing.
+            BOTH SURFACES SHOW THE WHOLE COLLECTION — they are two LENSES over
+            one set, not two sets. Files answers "what is on this record" in a
+            scannable column; Photos answers "what did it LOOK like" at a glance.
+            A reader who guesses wrong still finds the artifact instead of
+            concluding it was never filed, and nobody has to know a file's FORMAT
+            before they know where to look for it.
+
+            The grid used to filter to `image/*`. That made the split a fact about
+            MIME rather than about reading, and it put the signed delivery note in
+            a different section from the photos of the same hand-over — while this
+            very comment promised that the odd `.docx` among forty phone photos
+            would stay in the grid. It could not: the filter forbade what the
+            sentence described. `FileThumbnail` already renders a non-image as a
+            doc tile (badge + filename), so nothing had to be built — only the
+            filter that hid it had to go.
+
+            THE COST IS REAL AND DELIBERATE: every file now appears twice. The
+            trade is that duplication is cheap to skim past, whereas an artifact
+            filed under the wrong lens looks like an artifact that was never
+            filed. A record whose attachments are overwhelmingly paperwork should
+            drop the grid entirely rather than carry a wall of identical tiles —
+            the choice is per-record-TYPE, made once, not per file.
+
+            Ordering follows the collection, so a record heavy in documents leads
+            this grid with grey tiles. If that reads badly for your record type,
+            sort images first rather than reinstating the filter.
+
+            The tiles are mixed by construction now, so the FIXTURE has to be
+            mixed too — a grid of eight JPGs never once renders the doc tile it
+            has always been able to render, which is how the gap survived.
 
             The ADD rides the heading row, right edge, exactly as it does on Files
             and Fees — a section's add sits in the same spot whether the section
@@ -2777,7 +2915,7 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418", openSection
                   title="Add photos"
                   color="primary"
                   onPress={() => {
-                    void pickFiles({ accept: "image/*", multiple: true }).then(intakeFiles);
+                    void pickFiles({ accept: "application/pdf,image/*", multiple: true }).then(intakeFiles);
                   }}
                 />
               )}
@@ -3058,6 +3196,35 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418", openSection
                           <DetailRow label="Invoice no" description="The party's invoice or debit note">
                             <InlineTextInput value={f.invoiceNo} onSave={persist((v: string) => patchFee(f.id, { invoiceNo: v }))} placeholder="Add the reference…" accessibilityLabel="Invoice number" />
                           </DetailRow>
+                          {/* THE FILE, ON THE ROW THAT OWES IT — the shape a
+                              payables desk actually works in: a table of
+                              charges, each row expanding to the document that
+                              justifies it. The register cell above can only
+                              MARK whether a document is held (and on this page
+                              not even that — the fee table measures 400px and
+                              its declared columns already total 422, so two
+                              drop before the flex column gets a pixel). The
+                              managing happens here.
+
+                              `multiple`, because a supplier invoice arrives as
+                              one PDF or as three scanned pages, and the second
+                              page must not replace the first.
+
+                              `blockedReason` when no number has been claimed:
+                              there is nothing to file the scan AGAINST yet, and
+                              a sentence naming that act beats a disabled button
+                              that only says no. */}
+                          <DetailRow label="Supplier original">
+                            <InlineFiles
+                              files={f.docs}
+                              onAdd={(picked) => patchFee(f.id, { docs: [...f.docs, ...picked.map(asDisplayFile)] })}
+                              onRemove={(doc) => patchFee(f.id, { docs: f.docs.filter((d) => d.id !== doc.id) })}
+                              addLabel="Attach original"
+                              addMoreLabel="Add page"
+                              accept="application/pdf,image/*"
+                              blockedReason={f.invoiceNo.trim() === "" ? "Enter the invoice number first — the scan is filed against it." : undefined}
+                            />
+                          </DetailRow>
                           <DetailRow label="Status">
                             <InlineSelect
                               value={f.paid ? "paid" : "unpaid"}
@@ -3096,11 +3263,51 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418", openSection
                       </View>
                     }
                   >
-                    <TableCell><Text size="sm" weight="medium" numberOfLines={1}>{f.name || "—"}</Text></TableCell>
-                    <TableCell><Text size="sm" color="muted">{f.direction === "charge" ? "Charge" : "Cost"}</Text></TableCell>
-                    <TableCell><Text size="sm" color="muted" numberOfLines={1}>{f.party || "—"}</Text></TableCell>
-                    <TableCell><Text size="sm" tabular numberOfLines={1}>{formatMoney(f.amount)}</Text></TableCell>
-                    <TableCell><Text size="sm" color={st.danger ? "danger" : "muted"} tabular numberOfLines={1}>{st.text}</Text></TableCell>
+                    {/* IDENTITY over its PARTY — `tpl_item_list`'s customer cell
+                        exactly: the thing you scan for on line 1, what qualifies
+                        it on line 2, in one cell rather than two columns. */}
+                    <TableCell>
+                      <View style={{ gap: 2 }}>
+                        <Text size="sm" weight="medium" numberOfLines={1}>{f.name || "—"}</Text>
+                        <Text size="xs" color="muted" numberOfLines={1}>
+                          {f.party || (f.direction === "charge" ? "Charge" : "Cost")}
+                        </Text>
+                      </View>
+                    </TableCell>
+                    {/* AMOUNT over its PAYMENT state — the register's fee cell,
+                        same stack, same rungs. The state qualifies the number it
+                        sits under, so it needs no column and no repeated label. */}
+                    <TableCell>
+                      <View style={{ gap: 2, alignItems: "flex-end" }}>
+                        <Text size="sm" tabular numberOfLines={1}>{formatMoney(f.amount)}</Text>
+                        <Text size="xs" tabular numberOfLines={1} color={st.danger ? "danger" : "muted"}>{st.text}</Text>
+                      </View>
+                    </TableCell>
+                    {/* THE DOCUMENT, with a column of its own at last.
+                        Held: a clip + the number, pressable to preview. Claimed
+                        but not arrived: the number in WARNING tone — the fee
+                        cannot be paid, and that now reads in the column the fact
+                        belongs to instead of borrowing the money's state. Never
+                        claimed (cash at the gate): an em dash, because nothing is
+                        owed and a permanent warning on every such row trains the
+                        eye straight past the column. */}
+                    <TableCell>
+                      {f.invoiceNo.trim() === "" ? (
+                        <Text size="sm" color="muted">—</Text>
+                      ) : f.docs.length === 0 ? (
+                        <Text size="sm" color="muted" numberOfLines={1}>{f.invoiceNo}</Text>
+                      ) : (
+                        <Pressable
+                          onPress={() => openPreview(DOCS, 0)}
+                          accessibilityRole="button"
+                          accessibilityLabel={`Open invoice ${f.invoiceNo}`}
+                          style={{ flexDirection: "row", alignItems: "center", gap: 6 }}
+                        >
+                          <FileBadge mimeType={f.docs[0].mimeType} size={22} />
+                          <TextLink size="sm">{f.invoiceNo}</TextLink>
+                        </Pressable>
+                      )}
+                    </TableCell>
                   </TableRow>
                 );
               })}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "41.0.0",
+  "version": "41.1.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -153,6 +153,7 @@
     "./inline_edit": "./src/inline_edit.tsx",
     "./inline_slot": "./src/inline_slot.tsx",
     "./inline_static": "./src/inline_static.tsx",
+    "./inline_files": "./src/inline_files.tsx",
     "./inline_text_input": "./src/inline_text_input.tsx",
     "./inline_number_input": "./src/inline_number_input.tsx",
     "./inline_select": "./src/inline_select.tsx",

package/src/agent_run_pane.tsx

@@ -48,7 +48,11 @@ export interface AgentRunLike {
    * the wrong document, and the only exit was to sit through it.
    */
   cancel: () => void;
-  error: string | null;
+  /** The breaking error that killed the run. Accepts `undefined` as well as
+   *  `null` so an SDK run — whose `error` is an OPTIONAL property — satisfies
+   *  this without the caller reshaping the object the SDK docs say to hand
+   *  straight over. The pane normalizes both to absent. */
+  error: string | null | undefined;
 }
 
 export function AgentRunScope({ children }: { children: ReactNode }) {

package/src/file_rows.tsx

@@ -10,7 +10,6 @@ import { Alert } from "./alert";
 import { FileRow } from "./file_row";
 import { ActionMenu, type ActionMenuItem } from "./action_menu";
 import { FileGalleryModal } from "./file_gallery_modal";
-import { resolveMime } from "./file_badge";
 import { downloadFileFromUrl } from "./download";
 import { type GalleryLabels } from "./file_preview_types";
 import { useLoticsLocale } from "./locale";
@@ -18,7 +17,18 @@ import type { DisplayFile } from "./file_thumbnail";
 
 export interface FileRowsProps {
   files: DisplayFile[];
-  /** Secondary line per file. Default: the file-type label (e.g. "PDF"). */
+  /**
+   * Secondary line per file. Default: NONE.
+   *
+   * It defaulted to the file-type label, which every row already states twice —
+   * the `FileBadge` encodes the type as its colour AND prints it inside the
+   * glyph, and the filename ends in the extension. A fourth statement of one
+   * fact is not a caption, it is noise, and it cost every consumer a line of
+   * row height to say nothing.
+   *
+   * Pass something the NAME does not already carry — what an invoice covers, who
+   * uploaded it, when it landed.
+   */
   meta?: (file: DisplayFile) => string | undefined;
   /** Adds a (confirmed) "Remove" to each ⋯ menu and the gallery toolbar. The host
    *  drops the file from its own state. */
@@ -84,7 +94,7 @@ export function FileRows({ files, meta, onRemove, onOpenExternal, onDownload, on
           <FileRow
             key={file.id}
             name={file.filename}
-            meta={meta ? meta(file) : resolveMime(file.mimeType).label}
+            meta={meta ? meta(file) : undefined}
             mimeType={file.mimeType}
             onPress={() => setActiveIndex(index)}
             trailing={<ActionMenu accessibilityLabel={`${l.actions}: ${file.filename}`} items={items} />}

package/src/inline_files.tsx

@@ -0,0 +1,219 @@
+import { useCallback, useState } from "react";
+import { View } from "react-native";
+import { Button } from "./button";
+import { Text } from "./text";
+import { FileRows } from "./file_rows";
+import { INLINE_CONTROL_HEIGHT } from "./inline_edit";
+import { pickFiles } from "./file_picker";
+import { type DisplayFile } from "./file_thumbnail";
+import { type GalleryLabels } from "./file_preview_types";
+import { useLoticsLocale } from "./locale";
+
+export interface InlineFilesProps {
+  /** What is attached now. */
+  files: DisplayFile[];
+  /**
+   * The user picked these. The HOST uploads them and persists the result — this
+   * kit never talks to a server, so `files` only changes when the host says so.
+   *
+   * **`multiple` decides what the host must DO with them**: appending on a
+   * single-file field is how a field that holds one contract quietly ends up
+   * holding three. See that prop.
+   *
+   * Return a promise and the CTA stays busy until it settles, which is the whole
+   * of this component's loading state: a picked file is in flight for as long as
+   * the host takes, and a control that re-arms immediately invites the second
+   * press that files it twice.
+   *
+   * Omit for a read-only field — the same list, no CTA.
+   */
+  onAdd?: (picked: File[]) => void | Promise<void>;
+  /** Adds a (confirmed) Remove to each row's ⋯ menu. Omit for add-only. */
+  onRemove?: (file: DisplayFile) => void;
+  /** Open outside the app — a new tab on the frontend, `openExternal` in a
+   *  sandboxed app. Omit and the row still previews in place. */
+  onOpenExternal?: (file: DisplayFile) => void;
+  /** Override the download (the host frontend sends `credentials`). */
+  onDownload?: (file: DisplayFile) => void;
+  /**
+   * **The FIELD's cardinality, not the picker's convenience.** Default `true`.
+   *
+   * `true` — a set. The picker takes several at once, and the CTA reads
+   * `addMoreLabel` once something is attached, because adding a second page to a
+   * document set is an ordinary act.
+   *
+   * `false` — exactly one. The picker takes one, and the CTA reads
+   * `replaceLabel`, because "add another" is not a thing a single-file field can
+   * do: the honest verb is replace, and offering "add" there produces a field
+   * holding two of something the schema says there is one of. **The host must
+   * then SET rather than append in `onAdd`** — the component cannot enforce it
+   * (it does not own the data), and the failure is silent, so the call site
+   * reads `onAdd={([f]) => setFile(f)}` against `onAdd={(fs) => setFiles([...files, ...fs])}`
+   * and the difference is visible where it is decided.
+   *
+   * This is a fact about the field, which is why it is a prop and the LIST shape
+   * is not: one file or many, the reader still identifies a document by its name.
+   */
+  multiple?: boolean;
+  /**
+   * CTA words for the three states — nothing attached, adding to a set,
+   * replacing the one.
+   *
+   * Three, because they are three different acts and a generic "Add files"
+   * misleads in two of them. Name them for the domain ("Attach original" /
+   * "Add page" / "Replace contract") and the field stops needing a caption to
+   * explain itself. Each falls back to the one before it, so a single-file field
+   * that never says `replaceLabel` still reads sensibly.
+   */
+  addLabel?: string;
+  addMoreLabel?: string;
+  replaceLabel?: string;
+  /** Replaces the CTA's words while `onAdd` is in flight. Omit and the CTA keeps
+   *  its words and simply disables — no invented English in a localized app. */
+  busyLabel?: string;
+  /**
+   * Renders this sentence INSTEAD of the CTA — for a field with nothing to
+   * attach TO yet (a scan whose invoice does not exist; a line before its order
+   * is saved).
+   *
+   * Deliberately not a disabled button. A disabled control states that you may
+   * not, and leaves the reader to work out why and what would change it; a
+   * sentence states the act that unblocks it. Same pixels, one of them useful.
+   */
+  blockedReason?: string;
+  /** Shown when nothing is attached AND there is no CTA. Default "—". */
+  emptyLabel?: string;
+  /** Native accept filter, e.g. `"application/pdf,image/*"`. */
+  accept?: string;
+  /** Translated gallery/menu chrome, forwarded to `FileRows`. */
+  labels?: Partial<GalleryLabels>;
+  /** Credentials mode for the preview fetches — `"include"` for auth-gated
+   *  proxy URLs, omitted for an app's presigned URLs. */
+  credentials?: RequestCredentials;
+  onError?: (error: unknown, meta: { fileId: string; mimeType: string }) => void;
+}
+
+/**
+ * The FILES member of the `Inline*` family — a record's attachments, editable in
+ * the value column of a `DetailRow`.
+ *
+ * Every other field type had both halves already (`Select`/`InlineSelect`,
+ * `TextInputField`/`InlineTextInput`); files had only the section-scale one
+ * (`FilesEditor`), so a record FIELD holding documents was hand-rolled per app as
+ * `FileRows` + a picker + a button. Each copy re-derived the same decisions —
+ * including the alignment one, which has a counter-intuitive answer: this field
+ * sits on the inline grid's VERTICAL beat but takes NO horizontal inset, because
+ * its children are boxes rather than text (see the comment on the wrapper).
+ *
+ * A LIST, not a grid, and not switchable: documents are identified by NAME — a
+ * PDF/Word/Excel thumbnail is a grey page identical to every other grey page — so
+ * a grid of them is a wall of one tile under a truncated caption. Images are
+ * identified by their CONTENT and want `FileGrid` / `FilesEditor` instead. Which
+ * one a field holds is a judgment about the DATA, so it picks the component, not
+ * a prop on this one.
+ *
+ * Lean on purpose: no selection mode, no bulk bar, no upload queue. It shows,
+ * previews, adds and removes. Reach for `FilesEditor` when a surface genuinely
+ * needs multi-select and bulk download — a record row does not.
+ */
+export function InlineFiles(props: InlineFilesProps) {
+  const {
+    files,
+    onAdd,
+    onRemove,
+    onOpenExternal,
+    onDownload,
+    multiple = true,
+    addLabel,
+    addMoreLabel,
+    replaceLabel,
+    busyLabel,
+    blockedReason,
+    emptyLabel = "—",
+    accept,
+    labels,
+    credentials,
+    onError,
+  } = props;
+
+  const loc = useLoticsLocale().filesEditor;
+  const [busy, setBusy] = useState(false);
+
+  /**
+   * Single-flight, released in `finally`.
+   *
+   * The picker is INSIDE the guard, not around it: a second press while the
+   * dialog is open would open a second dialog, and both would resolve into
+   * `onAdd`. Cancelling still settles (`pickFiles` resolves `[]`), so the guard
+   * releases without the host being called.
+   */
+  const add = useCallback(async () => {
+    if (busy || onAdd === undefined) return;
+    setBusy(true);
+    try {
+      const picked = await pickFiles({ accept, multiple });
+      if (picked.length === 0) return;
+      await onAdd(picked);
+    } finally {
+      setBusy(false);
+    }
+  }, [busy, onAdd, accept, multiple]);
+
+  const base = addLabel ?? loc.upload;
+  const cta =
+    files.length === 0
+      ? base
+      : multiple
+        ? (addMoreLabel ?? base)
+        : (replaceLabel ?? base);
+
+  return (
+    /* The inline grid's VERTICAL contract only — deliberately not `InlineSlot`.
+     *
+     * That component pads 8px + a 1px border so a raw STRING's baseline lands
+     * where an editor's text does, which is right for text and wrong here: these
+     * children are BOXES (file rows, a button), and a box aligns with the
+     * editors' box, not with their text. Measured, `InlineSlot` pushed this
+     * field 9px right of every input above it — one value column, two left
+     * edges, which is the exact defect the slot exists to prevent, arriving
+     * through the slot itself.
+     *
+     * The LIST fills the column and the CTA does not, because they are different
+     * kinds of thing: a file row is this field's VALUE and every other value in
+     * the column (a text input, a select) spans it, so a short row would read as
+     * a different column; the button is an ACTION, and a full-bleed one reads as
+     * the section's rather than this field's. Hence stretch by default, with the
+     * CTA opting out via `alignSelf` rather than the container shrinking both.
+     */
+    <View style={{ minHeight: INLINE_CONTROL_HEIGHT, justifyContent: "center" }}>
+      <View style={{ gap: 8, width: "100%" }}>
+        {files.length > 0 ? (
+          <FileRows
+            files={files}
+            onRemove={onRemove}
+            onOpenExternal={onOpenExternal}
+            onDownload={onDownload}
+            onError={onError}
+            labels={labels}
+            credentials={credentials}
+          />
+        ) : null}
+        {blockedReason !== undefined ? (
+          <Text size="sm" color="muted">{blockedReason}</Text>
+        ) : onAdd !== undefined ? (
+          <View style={{ alignSelf: "flex-start" }}>
+            <Button
+              title={busy ? (busyLabel ?? cta) : cta}
+              icon="paperclip"
+              color="secondary"
+              disabled={busy}
+              onPress={() => void add()}
+            />
+          </View>
+        ) : files.length === 0 ? (
+          <Text size="sm" color="muted">{emptyLabel}</Text>
+        ) : null}
+      </View>
+    </View>
+  );
+}