@lotics/ui 28.3.1 → 29.3.0

package/AGENTS.md

@@ -16,7 +16,7 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 |---|---|
 | [docs/catalog.md](./docs/catalog.md) | **The complete inventory** — Reach-by-role (each data role → the ONE canonical component) + every `@lotics/ui/<module>` entry point (incl. `@lotics/ui/vite`'s `loticsOptimizeDeps` + `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/ai_patterns.md](./docs/ai_patterns.md) | AI acts, the human stays in charge — composer, live run feed (`AgentRun`), the one law's split (modify → review-before-apply; create → save-direct + the `ResultHeader` receipt), findings, provenance, confidence; the UI half of the SDK's [ai doc](../app-sdk/docs/ai.md)., the whole run in a dialog (`AgentRunScope`/`AgentRunPane`/`AgentRunActions` — a parked question REPLACES the feed, actions in the footer) |
+| [docs/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); **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, 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). |
 
@@ -89,6 +89,17 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
   back — which is what makes scanning twenty records unaffordable. `TableRow`'s `detail` +
   `expanded` reveal the detail beneath the row; keep the drawer for a heavy form.
   → [catalog.md](./docs/catalog.md).
+- **Documents get a LIST; images get a GRID.** The discriminator is what identifies the file to
+  the person looking for it. A PDF, a Word doc and a spreadsheet are identified by their NAME —
+  their thumbnails are a grey page with grey lines on it, identical to every other grey page —
+  so a grid of them is a wall of the same tile and the reader has to read a truncated caption
+  anyway. Use `FileRow` / `FileRows`, where the full name is the row and a second line can
+  carry a date, a size, a status, a diff. Photos, scans and drawings are identified by their
+  CONTENT — the filename is `IMG_4471.jpg` and tells nobody anything — so use
+  `FileThumbnailGrid`, where the picture is the identity and many fit on one screen. A mixed
+  set follows its majority; an app whose attachments are overwhelmingly paperwork should not
+  pay a grid's wasted space for the occasional photo.
+  → [catalog.md](./docs/catalog.md).
 - **A reference to another record is a FIELD** — it wears the inline editor's own resting
   surface and PEEKS its facts on press; EVERY verb lives in the peek's footer as a `Button`,
   none on the field — LEFT the link (Change and Clear, both standard), RIGHT the record (Edit's

package/MIGRATION.md

@@ -4,6 +4,32 @@ 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.
 
+## 29.0.0 — review surfaces compose from atoms
+
+`ChangeReview` and its family are DELETED, replaced by three layout-free pieces. The
+`change_review` export and the `changeReview` locale slice are gone. Apps pinned to 28.x are
+unaffected until they upgrade.
+
+**Why.** `ChangeReview` was a REQUIRED context root — `useReviewCtx` threw outside it — so a
+change could not be dropped into a screen that already existed; you adopted the whole container
+or nothing. And the family owned LAYOUT, not just semantics (a divided stack, a ruled field
+container, a label-plus-bands block), so a change could only ever *look like* a stack of
+labelled field diffs. Every surface needing a diff somewhere else — inside a ledger row, beside
+a total, in a cell — rebuilt it by hand, and several apps did.
+
+**What to reach for instead**
+
+| Was | Now |
+|---|---|
+| `ChangeField` `before`/`value` bands | **`DiffValue`** — anywhere a value renders |
+| `ChangeRecord` op wash, add/remove framing | **`DiffMark`** on whatever row you already draw |
+| `ChangeReview` provider + `Change` status + `ChangeReviewHeader` counter | **`useChangeSet(ids)`** — the same bookkeeping, no container |
+| `ChangeReviewActions` | your own `Button`s, reading `review.keptCount` / `review.settled` |
+| `ChangeFields`, `ChangeLabel`, `ChangeSummary`, `ChangeReasoning`, `ChangeBand`, `ChangeValueInput` | ordinary `DetailTable` / `Text` / inline inputs — they were layout, not contract |
+
+The opinionated stack is not gone, it is demoted: build it in your own screen from the atoms.
+Every app needed a slightly different shape, which is why one container could not serve them.
+
 ## 28.2.0 — `SubsectionHeadingTitle` takes a `description`
 
 Additive; nothing to change. The heading ramp's three rungs are meant to carry the SAME slots

package/docs/ai_patterns.md

@@ -13,12 +13,23 @@ file). Every component here is in the [catalog](./catalog.md) inventory.
 
 The AI surfaces share ONE law: the agent never commits **invisibly**. The agent owns judgment
 (recognition, estimation, intent→parameters); the app owns geometry, math, and the write. How
-the human stays in charge follows the stakes — split by whether a before-state exists:
+the human stays in charge follows **who supplied the values**, not whether a before-state
+exists. A diff is one way to show a person what a machine decided; it is not the only reason
+they need to see it. Values a HUMAN typed need no gate — they already read them, on the way in.
+Values a MACHINE read off a document need one, and a create is not exempt just because there is
+nothing to compare against: a receipt saying "Created 3 cases" is the first moment the operator
+could have caught a misread reference, and by then it is in the data.
 
 - **Modifying an existing record** — a diff exists, and a wrong value can clobber a right one →
-  review BEFORE apply: the `ChangeReview` family, Keep/Drop per change, nothing auto-applies.
-- **Creating new records** (intake, import, drafting rows) — there is no before-state, so there
-  is nothing to diff → **apply directly, then end on the RECEIPT**
+  review BEFORE apply: `DiffValue` + `DiffMark` + `useChangeSet`, composed into the screen; nothing auto-applies.
+- **Creating new records from a DOCUMENT** (intake, import, drafting rows) — no before-state,
+  so nothing to diff, but the values are still proposed rather than typed → **a full EDITABLE
+  preview of every record before the write**, not a summary of it. Lay the records out as they
+  will be stored — every field, editable in place, nothing behind a "3 fields" count — and
+  commit once. There is no diff to mark, so the whole record is the review; `DiffMark` still
+  earns its place to say which records are new versus matched onto something existing.
+- **Creating new records a human TYPED** (the manual create form) — they read every value on
+  the way in → **apply directly, then end on the RECEIPT**
   (`@lotics/ui/result_header`) — the receipt states the outcome and ROUTES; it is never a
   record editor. Run DETERMINISTIC checks over what the save STORED (a checksum, a count
   reconciliation — binary math, never a fabricated score). ONE record: `ResultHeader` (tone,
@@ -52,7 +63,7 @@ for the right one by job.
 Three shapes:
 
 1. **Field writes** (extract, match, rank, classify → records change) → **in-app agent**
-   (`useAgentRun`), then split by the one law: modifying an existing record → **`ChangeReview`**
+   (`useAgentRun`), then split by the one law: modifying an existing record → **a review surface you compose**
    (Keep/Drop per change, app-workflow writes, bounded app authority); creating new records →
    **save direct + the receipt** (outcome, verdicts, and a route to the record).
    Either way one button, never a prompt box.
@@ -241,107 +252,143 @@ into it while running and reveals again when done.
 **Limitation:** the pill's expand/collapse accessibility labels ("Show the agent's steps" /
 "Hide the agent's steps") are currently hardcoded English.
 
-## Review before apply — ONE surface, the compound `ChangeReview` family
-
-**When to reach for it — the one law's boundary.** `ChangeReview` is for MODIFYING an existing
-record: a diff exists (the `−` band has something real to show) and a wrong extraction can
-overwrite a right value — the record page's document desk is the home ground. Do NOT put it in
-front of a creation flow (intake, import, bulk drafting): there is no before-state to diff, so
-the "review" is a proofread the user blind-confirms — save direct and end on a result list
-instead (see [the one law](#the-one-law) and `tpl_item_list`'s intake).
-
-Every "the agent proposes → the human accepts / edits / dismisses → nothing auto-applies" surface
-composes from twelve pieces in three groups (all in `@lotics/ui/change_review`; worked example:
-[`tpl_record`](../examples/tpl_record.tsx)'s Use-AI extract flow).
-
-**Frame**
-
-- `ChangeReview` — context provider + stack; hairline dividers between consecutive `Change`
-  sections (and `ChangeFields` rules between fields). Changes are OPEN sections — spacing and
-  rules, never card boxes.
-- `ChangeReviewHeader` — the SECTION heading (md semibold; default title localizes to "Suggested
-  edits"). Keep it lean: never repeat the record the dialog is already about. The counter does
-  NOT live here.
-- `ChangeReviewActions` — the commit bar; pin it in the `DialogFooter`/`DrawerFooter` (or inline
-  under the list). **Keep all** sits bottom-left and presses every pending decision's own
-  `onAccept` — pass `onAcceptAll` when decisions live in host state the registry can't see
-  (field-level Keep/Drop, unresolved conflicts); it then replaces the derived handler entirely.
-  The "N of M kept" counter reads HERE beside it, never in the header (the counter renders only
-  when at least one registered entry carries `onAccept`; Keep-all renders when one does OR when
-  you pass `onAcceptAll`; `showAcceptAll={false}` hides Keep-all). Apply
-  disables below `minKept` kept (default 1 when any registered entry carries `onAccept`, else 0)
-  or via `applyDisabled` (host-level gate, ORed in); `applyLoading` marks the async write.
-  `onDiscard` puts the Discard button beside Apply. Apply is the only outcome-named button
-  (`applyLabel`).
-
-**Sections**
-
-- `Change` — one proposed change: `id` (registers in the review context — the counter, Keep-all
-  and the apply gate derive from registered ids), controlled `status`
-  (`"pending" | "accepted" | "rejected"`), `onAccept`/`onReject`/`onUndo`, heading + free body +
-  optional verbs + collapse. Omit both callbacks for a **display-only** entry (a finding inside a
-  review). Decided → collapses to the `ChangeSummary` child (falls back to the body) behind a
-  status mark + Undo. `acceptDisabled` gates Keep on a precondition.
-- `ChangeLabel` — the change's SUBJECT heading; a stack of changes skims by subject.
-- `ChangeSummary` — the collapsed row's one-line content after a decision.
-- `ChangeReasoning` — the agent's quiet hairline-ruled aside (muted text behind a left rule) —
-  only when the change is not self-explanatory.
-
-**The grammar**
-
-- **`ChangeFields` + `ChangeField`** — THE field unit. `ChangeFields` is the OPEN form (the
-  section IS the record — an extract dialog's one order: no card chrome), stacking `ChangeField`s
-  with hairline rules. A diff-form `ChangeField` renders, top to bottom: the label (sm medium,
-  **full colour** — it names the subject of a decision, never `DetailRow`'s muted ink), the
-  field's `reasoning` directly under the label, the `−` band when replacing (`before`), the
-  value — `ChangeValueInput` when `onChangeText` is given (the green `+` band; pressing it edits
-  IN THE BAND — a borderless input with identical type metrics, so nothing shifts), the read-only
-  `+` band when `valueReadOnly` or no `onChangeText` (muted `placeholder` while empty), or any
-  input via `children` — compose `<ChangeValueInput unit="pcs" …>` there yourself for a unit
-  suffix (`unit` fixes the suffix outside the editable core — type the number, never the unit;
-  the built-in default doesn't take it), conflict `candidates` as full-width decision rows
-  (picked via `onPickCandidate`) + the localized "Type another value" third option
-  (`customValue`/`customSelected`/`onCustomValue`/`onCustomSelect`; the outcome band is read-only
-  via `valueReadOnly` — the decision comes from picking, never from editing the band; gate with
-  `keepDisabled`), per-field **Keep/Drop** bottom-right
-  (`status: "pending" | "kept" | "dropped"`, `onKeep`/`onDrop`/`onUndo`). A pure REMOVAL is
-  `before` with no value — the `−` band alone. A decided field collapses to the compact one-row
-  card (mark, label → `summary`, Undo). A field with no diff and no decision is the plain
-  inline label, value row — this form borrows `DetailRow`'s *metrics* (130px label column /
-  40px row) — press-to-edit when `onChangeText` is given.
-
-  **Limitation:** `ChangeFieldCandidate.source` and `.description` are accepted by the type but
-  the built-in candidate row currently renders only the `value` (plus `selected`). Fold a short
-  qualifier into the value string, or compose your own rows; provenance belongs in `Sources` at
-  the review's bottom anyway.
-
-- **`ChangeRecord`** — THE item card for SETS of records (order lines): `id` (registers in the
-  review context like a `Change`), `tone` `"add" | "edit" | "remove"`, the tinted header band
-  with the localized op word (Add / Edit / Delete — the `changeReview` locale slice) + `title`,
-  body = its `ChangeField`s, required `summary` for the collapsed row. **The verb level follows
-  the decision level**: add/remove carry ONE card Keep/Drop (fields none — editable parts, one
-  write); edit carries NO card verbs (only its changed fields, each deciding for itself —
-  dropping a field narrows the update diff).
-- **`ChangeBand`** — the raw diff band (aligned `+`/`−` marker column, light emerald/red, dark
-  text) every piece builds from; reach for it directly for custom strokes (a removed record's
-  one-line summary). String content is UNCLAMPED by default (`numberOfLines` to clamp) — a
-  review must show the whole value being decided.
-- **`ChangeValueInput`** — the proposed value as a proper diff at rest (the green `+` line) that
-  becomes a real input on press; rest and edit share one height, so nothing shifts.
-
-**The scaling boundary (known, deliberate)**: `ChangeFields` + `ChangeRecord` cards cover one
-record through ~10; a BULK review (30+ imported rows — a bank statement, a spreadsheet import)
-needs a dense form that does not exist yet — design it against the first real migration, not
-speculatively.
-
-**The laws**: ONE verb pair everywhere — Keep/Drop, localized through the `changeReview` locale
-slice (en: Keep / Drop / Keep all / Apply / Discard / Undo); never rename per shape (Apply is the
-only outcome-named button; `acceptLabel`/`rejectLabel` exist but are not a license to invent
-verbs). Candidate rows carry the VALUE only; provenance = `Sources` at the VERY bottom of the
-review (after every change; or omit it — lean beats decorated). The HOST owns every decision in
-plain `useState` (controlled `status` everywhere); the family owns the mechanics (collapse +
-Undo, the counter, Keep-all, apply gating). Never apply a field with no value — gate unresolved
-conflicts (`keepDisabled`, `applyDisabled`). Editing IS the review.
+## Review before apply — TWO atoms and a hook, composed into your screen
+
+**When to reach for it — the one law's boundary.** A review gates values the MACHINE
+supplied, whether or not they replace anything. Modifying an existing record is the obvious
+case and takes the full diff. Creating records FROM A DOCUMENT takes the same gate in a
+different shape — no diff, because nothing is being replaced, but the whole record laid out
+and editable before the write (`examples/tpl_item_list.tsx`). Only values a HUMAN TYPED skip
+it: they read them on the way in, so the manual form saves direct and ends on the receipt.
+
+**There is no review CONTAINER, deliberately.** A review is not a place you go; it is something
+that happens to values already on screen. So the diff renders wherever the value renders — a
+table cell, a `DetailRow`, a total, a chip, a sentence — and inherits that container's width,
+alignment and rhythm. A compound family with a provider at its root can only produce the one
+shape its root draws, and every surface needing a diff somewhere else rebuilds it by hand.
+
+### The three pieces
+
+- **`DiffValue`** (`@lotics/ui/diff_value`) — a value that changed. `before` struck, `after`
+  emphasised. `layout="stacked"` (default) for a column of figures, `"inline"` for prose and
+  dense rows; `align`/`tabular` for money so the struck value and its replacement line up;
+  `tone` when the change itself is the bad news. **The three ops are the same component:**
+  an ADD omits `before`, a REMOVAL omits `after` (the struck value IS the change), an UPDATE
+  passes both, and **equal values collapse to one** — agreement is not a change, and an invoice
+  confirming the amount that was claimed is the GOOD case, not a diff of a value against
+  itself. **Both values stay on screen** on a real change (the old one is the only evidence the
+  correction is the right SIZE), and **`delta`** prints the movement itself — "+250 pcs",
+  "−118.519 ₫ VAT" — so nobody subtracts in their head.
+
+  **The struck value is muted, never red.** An old value is not an ERROR, and red is this
+  system's error colour — every routine update would read as a problem, and a table of eight
+  changed rows would carry sixteen coloured figures. Red-against-green is also the one pair a
+  colour-blind reader cannot separate, and it is the distinction a review turns on. The
+  strikethrough carries "going away" with no colour at all; weight, tone and (stacked) size
+  carry the rest.
+- **`DiffMark`** (`@lotics/ui/diff_mark`) — what happened to the row holding the value, for the
+  cases no single value carries: `added` / `changed` / `removed` / `unchanged`. Glyph plus an
+  accessible word, never colour alone. `unchanged` draws a quiet dot, because most rows in a
+  real review are untouched.
+
+  **ONE treatment, every surface: a filled 22px disc.** The form, the line table, the files
+  list and the thumbnail grid all draw the same mark, because a reader parses shape before
+  meaning and a form marked with bare glyphs beside a table marked with filled shapes reads as
+  two systems saying the same thing. `unchanged` renders as an empty disc-sized HOLE: an
+  operator opening a job of twelve fee lines to see where a dropped invoice landed should find
+  the one filled shape in a column of blanks without reading anything or separating two hues.
+  The hole keeps the column's width and announces nothing.
+- **`useChangeSet(ids, { initial })`** (`@lotics/ui/use_change_set`) — the bookkeeping:
+  `status`/`accept`/`reject`/`undo`/`acceptAll`/`reset`, `accepted`/`rejected`/`pending`,
+  `keptCount`/`total`/`settled`. `initial` defaults to **`accepted`** so an operator drops
+  exceptions instead of approving eight identical lines; pass `pending` when each change
+  genuinely deserves its own verdict, and gate the commit on `settled`.
+
+### The shapes, and what each one is
+
+- **A record's fields** — a `DetailTable` of rows, each a label plus a `DiffValue`, with
+  Keep/Drop on the row and a collapsed state once decided. That row is ~20 lines and it belongs
+  to your screen: `examples/tpl_record.tsx` and `dev/pages/ai.tsx` each write their own and they
+  read differently, which is the system working.
+- **A record SET** — a `Table`, one row per proposed record, `DiffMark` leading and `DiffValue`
+  inside the figure cells. A set of ledger lines reads like the ledger it is about.
+- **A conflict** — two documents disagree, so the value is the read-only OUTCOME of a pick:
+  a `DiffValue` showing the placeholder until resolved, over `CardSelectItem` candidates (each
+  naming its source document) and a type-another-value option. **Never pre-select**, and gate
+  Keep until one is chosen — a pre-selected candidate is a decision the system made and
+  attributed to the person.
+- **An ATTACHMENT** — a dropped document's proposal is often not a value at all: it is WHICH
+  LINE the file belongs to. That decision is as wrong-able as a misread figure and gets the
+  same treatment — the file rendered on the row it lands on, inside a `DiffValue` whose sides
+  are NODES (a `FileBadge` plus its name). A file replacing one already filed shows both, and
+  the superseded one is struck by a DRAWN rule: `line-through` set on a `Text` does not cross
+  a `View` child, so without it the old scan renders at full strength beside its replacement
+  with nothing saying which is going away. Worked in `examples/tpl_record.tsx`.
+- **A DOCUMENT SET** — a files section is not a field. It is a set of objects with identity,
+  so what changes is MEMBERSHIP plus per-document properties, and the kinds do not share a
+  treatment. **Added** and **removed** are membership: the row's existence and its mark are
+  the whole change. **Superseded** is one slot whose bytes changed — the row names the new
+  file and its second line names the one it displaces. **Reclassified** is the one a review
+  surface gets wrong: the bytes are untouched and only the FILING moved, so the `DiffValue`
+  belongs on the property — a mark with no visible diff reads as though the file itself
+  changed. `FileRow` takes the mark in `leading` (so the names still form a column) and a node
+  `meta` (so the second line can carry a diff).
+
+  **In a GRID** the same set reads differently again, and that is a property of the shape
+  rather than a gap: a grid is scanned whole, so it carries membership (this is arriving, that
+  is leaving — `FileThumbnailGrid diffs`, a corner mark plus a fade) at a glance and carries
+  pairing not at all. Pick the surface for the change; do not shrink the change to fit a shape.
+
+  **A file badge has a discriminator too.** Where the file is the row's SUBJECT — a `FileRow`,
+  a tile — the badge earns its space and the row is built around it. Where the file is one
+  VALUE among several columns, render the filename as a value at the column's own text size:
+  a badge shrunk to fit a table cell takes its label off the type scale entirely (5px, at the
+  size a cell allows), and sizing it back up makes it set the row's height for a fact the
+  extension already carries.
+
+  **The strikethrough has a discriminator.** Strike the superseded file when it shares a CELL
+  with its replacement, adjacent — a table's document column, where the pairing is what the
+  cell means. Do NOT strike it on a files-section line, where the two sit on different rows:
+  there the strike says "going away" without saying what replaces it, so a word names the
+  relation and the chip only identifies the file. Both shapes are worked in `dev/pages/ai.tsx`.
+- **A record being CREATED from a document** — no before-state, so no diff: the whole record
+  is the review. Lay every field out as it will be stored, editable in place, and mark only
+  the fact that IS relational (matched onto something existing, or new alongside it). One
+  commit named for the outcome. Worked in `examples/tpl_item_list.tsx`.
+- **Display-only** — a finding that informs but has nothing to decide simply is not in the
+  change set. There is no "display-only" mode to remember.
+
+### The laws that survive the container
+
+- **Nothing auto-applies.** The commit is one explicit press, named for its outcome
+  ("Update record (3)", "Add 4 tasks") — never "Apply" alone, never "OK".
+- **Editing IS the review.** A value the operator can correct in place beats accept-or-reject
+  on a value they cannot touch: a wrong proposal you can fix costs a keystroke, one you can
+  only reject costs the whole re-entry.
+- **Gate the commit on what will actually be written**, not on the proposal count — disable at
+  zero kept.
+- **The mark rides the LABEL, and the value sits in an `InlineSlot`.** Both are alignment
+  before they are semantics. A mark beside the VALUE indents every row it marks by its own
+  width plus a gap, so an unmarked row needs a spacer of exactly the glyph's width to keep up —
+  and they drift (17 against 13 shipped that way). The label column is a fixed width with one
+  left edge, so a mark placed there aligns down the page for free. Give the slot a fixed HEIGHT
+  as well as width: it is an inline-flex box inside `DetailRow`'s label `Text`, so an empty one
+  baselines differently from one holding a glyph. On the value side, a form mixes 40px editors
+  with 20px flat diffs; without the slot the column has two left edges and two baselines, and
+  the label agrees with one kind of row and not the other.
+- **The reason goes above the verdict.** A `why` passed as `DetailRow`'s `description` renders
+  under the whole cell — which is under the Keep/Drop buttons. A justification printed after
+  the controls that act on it is one nobody reads. Render it inside the value block.
+- **Show the WHOLE thing, not just the parts that moved.** The operator's question is rarely
+  "what did it find" — it is "is this right, and where does it sit". A surface showing only
+  the changed rows answers the first and leaves the second to a second screen. Render the
+  record entire and let `DiffValue` collapse what agrees (equal values render as one plain
+  value, so the same component tree serves a record with one change and a record with twenty).
+  Emphasis, not omission, is what makes the changes findable.
+- **The fixture must not flatter.** A review demo whose every row carries a change proves
+  nothing about the screen that matters — the one where a document touched two lines of
+  fourteen. Build the sparse case and check the marks are still findable in it.
+- **Provenance belongs at the bottom of the section** (`Sources`), never crowded into a heading.
 
 ## Ask back — `Clarify` / `ClarifyWizard`
 
@@ -449,7 +496,7 @@ sources. Severity → colour: `critical` red, `warning` amber, `info` zinc ("Not
 emerald ("On track"); words come from the `finding` locale slice. **Display-only**: a finding
 informs the action the human takes in the app; it decides nothing itself — no phantom "record
 verdict" write (a persisted check-status goes stale on the next edit). Stack several most-severe
-first — inside a `ChangeReview` wrap each in a display-only `Change` (the family's dividers
+first — render each as its own section separated by a `Divider` (a finding that only informs
 apply). `FindingComparison` is the expected-vs-actual body: each disagreeing side a labeled row
 (source, value), a hairline, then the DELTA emphasized — compose it as the finding's children
 for any one-value-disagrees insight (quantities, totals, dates).
@@ -496,9 +543,9 @@ ranked set, don't cram it into chat prose:
   document-driven records) — the record's files block feeds ONE "Use AI" entry that FORKS into
   the two document tasks, each a specialized run with a task-pure result: **Extract** (files
   read → fields already matching fold into one quiet line → every add / update / conflict a
-  `ChangeField` (the `−` band, the editable value, candidate rows), the record's current value
+  a `DiffValue` per field (the struck current value, the proposed one, candidate rows), the record's current value
   a first-class choice — plus proposed new lines as record-body `Change`s → one outcome-named
-  `ChangeReviewActions` commit) and **Cross-check** (documents compared against the record and
+  an explicit outcome-named commit) and **Cross-check** (documents compared against the record and
   each other → ranked `Finding`s — severity, title, the prominent metric, sources — separated
   by hairlines; the findings ARE the outcome the human acts on). The fork carries an OPTIONAL
   instructions field — the user steers what the agent checks or extracts, so `Finding` serves ANY
@@ -518,10 +565,10 @@ ranked set, don't cram it into chat prose:
   can do it in ONE run — every app agent carries `ask_user_choice`, so the run PARKS on the
   agent's own question and `useAgentRun().pendingChoice`/`answerChoice` drive the same
   `ClarifyWizard` (see the SDK's [ai doc](../../app-sdk/docs/ai.md)).
-- **Triage** — an inbox the agent classified + routed is a `ChangeReview` of `Change`s (body: the
+- **Triage** — an inbox the agent classified + routed is a `useChangeSet` over rows (body: the
   item + the agent's call; the standard Keep/Drop verbs; Keep-all covers the high-confidence
   sweep). Leads, tickets, documents, emails.
-- **Compare / ranked pick** — one `ChangeField` whose `candidates` carry the ranked options; the
+- **Compare / ranked pick** — one `DiffValue` over `CardSelectItem` rows carrying the ranked options; the
   human picks one. Quotes, carriers, suppliers, plans. (Fold the score/reason into each
   candidate's value string — see the candidate-row limitation above.)
 

package/docs/catalog.md

@@ -301,13 +301,13 @@ upcoming, horizontal OR vertical), `RemainderMeter` + `AllocationRow` (allocatio
 `Composer` (the adaptive command/chat composer — a compact pill when empty that expands for
 long text + attachments; the surface that triggers agent work), `AgentRun` (the live
 streaming work feed) + `AgentProgress` (its compact, floating, expandable form — a
-composer's "working" state) + `Confidence`; **`ChangeReview` — THE one review-before-apply
-surface, a COMPOUND family** (frame: `ChangeReview`, `ChangeReviewHeader`,
-`ChangeReviewActions`; sections: `Change`, `ChangeLabel`, `ChangeSummary`,
-`ChangeReasoning`; the grammar: `ChangeFields` + `ChangeField`, `ChangeRecord`,
-`ChangeBand` + `ChangeValueInput`): adds, updates, removals, conflicts, whole records,
-display-only findings are all compositions — see the AI-patterns doc indexed in
-[AGENTS.md](../AGENTS.md) for the laws; `Clarify` (the agent asks back — selectable
+composer's "working" state) + `Confidence`; **review-before-apply composes from two atoms
+plus a hook** — `DiffValue` (a value that changed: before struck beside/above after; drops
+into a table cell, a `DetailRow`, a total, a sentence), `DiffMark` (what happened to the row:
+added/changed/removed/unchanged) and `useChangeSet` (accept/reject/undo/counter, zero
+layout). An add is `after` alone, a removal is `before` alone, an update is both, a conflict
+is a `DiffValue` over `CardSelectItem` candidates — and the ROW around any of them belongs to
+your screen. See the AI-patterns doc indexed in [AGENTS.md](../AGENTS.md) for the laws; `Clarify` (the agent asks back — selectable
 `ChoiceList` options), `Sources` (provenance chips for AI output — at review scale,
 `label={null}` slots the chips at a section's bottom), `Finding` (one ranked insight from an
 AI check — localized severity word, title, detail, `Sources` chips, a `children` slot;
@@ -1328,7 +1328,13 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 
 - **`mime`** — pure MIME predicates: `isImageMimeType` / `isVideoMimeType` /
   `isAudioMimeType` / `isPdfMimeType` / `isExcelMimeType` / `isCsvMimeType` /
-  `isDocxMimeType` / `isPreviewableMimeType`.
+  `isDocxMimeType` / `isPreviewableMimeType`. Plus
+  **`resolveMimeType(declaredType, filename)`** — what to TREAT a file as. An
+  honestly-declared type is returned untouched; an *uninformative* one (`""`,
+  `application/octet-stream` and friends — what an OS clipboard or drag hands
+  over) is resolved from the filename extension instead, falling back to the
+  declaration when the extension is unknown too. It returns the same answer the
+  server stores, so a surface that filters on it agrees with what gets persisted.
 - **`download`** — `downloadFileFromUrl(url, filename, { credentials? })`: fetch+blob+anchor
   download that works inside sandboxed iframes (where `window.open` is silently dropped);
   `credentials` defaults to `same-origin` — pass `"include"` only for auth-gated same-site
@@ -1397,7 +1403,14 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   the single in-flight upload tile `FileGrid` renders; reach for it only when hand-rolling a
   non-grid upload layout — it is i18n-free by design, so a bare call site owes it `labels`
   (`FileGrid` resolves them from `LoticsLocale.fileUpload` on your behalf).
-- **`file_thumbnail`** — `FileThumbnail` + `DisplayFile` + `THUMBNAIL_SIZE` /
+- **`file_thumbnail`** — **`diff`** puts a `DiffKind` corner mark on a tile (top-LEFT, the one
+  corner remove/selection/uploading do not claim) and fades a `removed` one. The mark rides a
+  white RING: a tile's ground is an arbitrary photo, and a pale tint over a pale scan is a
+  smudge. A `removed` tile fades its BODY only — the mark stays at full strength, since a faded
+  mark is the smudge the ring exists to prevent. Ignored below 32px: a 22px disc on a compact
+  tile is the tile, and a compact strip lives inside a row that carries the change instead. A grid says MEMBERSHIP well (arriving, leaving) and PAIRING not at
+  all — nowhere on a 96px tile to name what a replacement supersedes — so a set where things
+  are being REPLACED wants `FileRow`. Also: `FileThumbnail` + `DisplayFile` + `THUMBNAIL_SIZE` /
   `COMPACT_THUMBNAIL_SIZE` + `getMediaIcon`: the completed tile — the right surface per
   MIME: image thumbnail, a doc tile with the `FileBadge` centered + a single-line filename
  , media card; `isTemplate` overlays a TMPL marker. The tile's accessible name is the
@@ -1405,14 +1418,26 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   pieces are exported for a hand-rolled layout: `DocumentBadge` (a bare pressable badge —
   its `size` is the square SLOT side, like every other tile here, and the badge is fitted to
   it), `DocumentCard`, `MediaCard`, `RemoveButton`.
-- **`file_thumbnail_grid`** — `FileThumbnailGrid` (+ the generic `ThumbnailGrid`):
+- **`file_thumbnail_grid`** — **`diffs`** (a `ReadonlyMap<string, DiffKind>`, keyed like
+  `selectedIds`) marks each tile, so a grid under review is the SAME grid with one more map
+  passed in rather than a different component the operator has never seen.
+  `FileThumbnailGrid` (+ the generic `ThumbnailGrid`):
   display-only square-tile grid; `selectedIds` + `onFilePress` pair with
   `useSelectionMode()` for gated select-mode CRUD.
 - **`file_row`** — `FileRow`: a horizontal file/document LINE — `FileBadge` or a
-  `placeholder` + the FULL name + a meta line + a composable `trailing` slot; `onPress`
-  makes the whole row a pressable door, `trailing` stays an independently-pressable sibling;
-  for attachment lists / message files / document checklists where a square tile truncates
-  the name.
+  `placeholder` + the FULL name + a meta line + composable `leading` / `trailing` slots;
+  `onPress` makes the whole row a pressable door, `trailing` stays an independently-pressable
+  sibling; for attachment lists / message files / document checklists where a square tile
+  truncates the name. **`leading`** sits BEFORE the badge — a `DiffMark` for a document set
+  under review, a select checkbox, a status dot; outside the badge rather than drawn on it, so
+  it lines up down the list instead of moving with the badge's `sm`/`md` size. **`meta` takes a
+  NODE** as well as a string, because a second line can itself be carrying a change (a file
+  being RECLASSIFIED is the same bytes filed differently — a `DiffValue` on the property); a
+  node renders outside the muted single-line `Text`, which would clip it and fight its colour.
+  Both `sm` variants share ONE beat (48px min + 6px vertical padding): the static row used to
+  have neither, so it came out 37px against the pressable's 49 — whether a row was a door
+  decided how tall it was — and 37 sat under every other row beat in the kit (`DetailRow` 40,
+  `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.
@@ -1514,17 +1539,67 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   be rendered; where a compact meter used to decorate a ranked row or proposal card, rank /
   badges / severity carry the standing instead. Also: calibrated
   high/med/low; localized via the provider.
-- **`change_review`** — the COMPOUND review family — frame: `ChangeReview` provider/stack,
-  `ChangeReviewHeader` (auto kept-counter over decidable entries), `ChangeReviewActions`
-  (the commit bar in the DialogFooter/DrawerFooter: Keep-all bottom-left (`onAcceptAll` for
-  host-held field state) + Apply gating); sections: `Change` (host-owned status, labeled
-  verbs, collapses to its `ChangeSummary` + Undo; no callbacks = display-only),
-  `ChangeLabel`, `ChangeSummary`, `ChangeReasoning` (the quiet why); grammar:
-  `ChangeFields` (the open record form) + `ChangeField` (THE field: − band, value,
-  candidates + type-another-value, reasoning, per-field Keep/Drop, collapse),
-  `ChangeRecord` (THE item card: registers like a Change; tone wash + localized op word;
-  verb level follows the decision level), `ChangeBand` (the raw ± band),
-  `ChangeValueInput` (the diff-at-rest editor); the `changeReview` locale slice.
+- **`diff_value`** — **`DiffValue`, THE atom of a review surface**: a value that changed,
+  rendering `before` struck above/before `after`. Owns no container, no context, no decision —
+  so it drops into a table cell, a `DetailRow`, a total, a chip or a sentence and inherits that
+  container's width and alignment. Either side may be a NODE — a `MemberChip` for a reassignment,
+  a chip for a link being repointed — and a node `before` is struck by a DRAWN rule rather than
+  by text decoration, because `line-through` on a `Text` does not cross a `View` child (the old
+  value would otherwise render at full strength beside its replacement with nothing saying it is
+  the one going away — type-checked, rendered, and wrong). Reach for a node when the value
+  genuinely is not text: an avatar carries identity a string cannot, and a review that swapped
+  the record's own chip for a name would show the operator a surface they have never seen at the
+  one moment they are asked to check something. A node belongs where it fits at FULL size — a
+  form row, a card. Shrinking a composite into a table cell takes its own type off the scale
+  (a file badge sized to a cell rendered its label at 5px), so a file in a CELL is a filename at
+  the column's own size, not a miniature badge. Worked in `dev/pages/ai.tsx` § every shape.
+  **`before === after` collapses to ONE plain value** —
+  agreement is not a change, and a document confirming what the record already says is the
+  GOOD case, not a diff of a value against itself. **`delta`** (a host-formatted string, the
+  same contract as `FindingComparison.delta`) prints HOW FAR it moved, because
+  `1.600.000 → 1.481.481` otherwise makes the reader subtract to find out whether a
+  correction is trivial or alarming. `layout` stacked (a column of figures) | inline (prose, dense
+  rows); `align`/`tabular` for money; `tone` for whether the change is good news. Omit `before`
+  for an addition, `after` for a removal. BOTH values stay on screen: the old one is the only
+  evidence the reader has that the correction is the right SIZE.
+  **`placeholder` is YOUR string — translate it.** The component renders no word of its own
+  (its only fallbacks are `—` and empty), so nothing here reaches the locale packs. That is
+  deliberate rather than an omission: `DiffMark` beside it DOES ship localized words, but the
+  two are different sentences even when English collides them — the mark says what happened to
+  the ROW ("Removed" / "Xóa"), the placeholder says what is in the FIELD now, which reads "đã
+  xóa" or "bỏ trống", never the bare verb. The same prop also carries "Pick a candidate below"
+  and "Not on the document". Pull it from your own catalog.
+- **`diff_mark`** — **`DiffMark`**: what happened to the row holding the value —
+  `added`/`changed`/`removed`/`unchanged`, for the cases no single value carries. Glyph + an
+  accessible word (never colour alone — "added" vs "removed" by hue is invisible to a reader who
+  cannot separate them, and that is the distinction a review turns on). **ONE treatment
+  everywhere: a filled 22px DISC**, 14px glyph, 700 ink on a 100 ground. It briefly had two — a
+  bare glyph for dense surfaces, a filled shape for sparse ones — and a form marked with bare
+  glyphs beside a table marked with filled shapes read as two systems saying the same thing; a
+  reader parses shape before meaning, so an unexplained difference reads as an accident however
+  principled the reason. The disc also gives the glyph its own ground, which is what lets one
+  mark sit on a white row, a tinted cell, or a photograph. **`unchanged` renders as an empty
+  disc-sized HOLE** — silence is the honest rendering of "nothing happened", it keeps the
+  column's width so nothing shifts left, and it announces nothing (eleven "Unchanged"es is the
+  same noise to a screen reader that a dot is to an eye). `showLabel` puts the word OUTSIDE the
+  disc; text crammed inside stops it being a circle, and the shape is what makes it findable
+  without reading. Leads a table row, sits in a card corner, precedes a field label.
+- **`inline_slot`** — **`InlineSlot`**: any node placed on the INLINE-CONTROL grid — the box
+  an `Inline*` editor draws (40px band, 8px horizontal padding inside a 1px transparent border),
+  minus the editor. A record's value column mixes editors with things that are not editors, and
+  anything rendered raw beside them starts at the cell edge, 20px tall, at the top — so the
+  column quietly acquires TWO left edges and two baselines, and `DetailRow`'s label (which pads
+  down to meet a control) agrees with one kind of row and not the other. `InlineStatic` is the
+  STRING case and composes it; reach for the slot when the value is a node, which a review
+  surface always is. NOT for a table cell — a `Table` sets its own row rhythm.
+- **`use_change_set`** — **`useChangeSet(ids, { initial })`**: the accept/reject/undo
+  bookkeeping as a HOOK, zero layout — `status`/`accept`/`reject`/`undo`/`acceptAll`/`reset`,
+  `accepted`/`rejected`/`pending`, `keptCount`/`total`/`settled`. Decisions are stored as
+  OVERRIDES against a default, never seeded from `ids` into state (seeding needs an effect, and
+  `ids` is normally a memo over query rows — a new array every render, which is the
+  `Maximum update depth exceeded` loop). `initial` defaults to `accepted` so the operator drops
+  exceptions instead of approving eight identical lines; pass `pending` when each change deserves
+  its own verdict and gate the commit on `settled`.
 - **`clarify`** — `Clarify` + `ClarifyOption`: the agent asks back — a borderless block
   (the question text + a `ChoiceList`, no card wrapper; an optional muted `eyebrow` sits tight above
   the question — e.g. a wizard's "1 / 3"). `ClarifyOption` requires