@lotics/ui 4.9.0 → 5.0.0

package/AGENTS.md

@@ -80,13 +80,14 @@ Pick by capability, not by name. (→ the source file for the API.)
 - **AI surfaces** — `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), `Suggestion` (review-for-approval of a proposal)
-  + `Confidence`, `RecordReview` (an extracted record reviewed + edited before save — fields
-  click-to-edit, Confirm collapses it), `ChangeReview` (before→after for an agent-proposed edit —
-  whole-set OR 1-by-1), `Clarify` (the agent asks back — selectable `ChoiceList` options),
-  `Sources` (provenance chips for AI output). For STRUCTURED AI output the four review
+  form — a composer's "working" state), `ReviewCard` (THE single-proposal review card — compositional
+  body via `children`: a `RecordFields` record (header-first) or a `MatchSides` pairing (body-first))
+  + `Confidence`; `ChangeReview` (the BATCH review engine — whole-set OR 1-by-1; compositional via
+  `renderItem`, with `ChangeDiff` for the before→after body),
+  `Clarify` (the agent asks back — selectable `ChoiceList` options),
+  `Sources` (provenance chips for AI output). For STRUCTURED AI output the review
   surfaces above don't cover: `SpecList` (the "exact breakdown" — a labeled-value spec sheet, the
-  panel of an answer), `MatchRow` (a two-sided AI pairing — source ↔ proposed match + confidence),
+  panel of an answer),
   `Finding` (one ranked briefing/audit insight — severity + metric + sources + action), `Discrepancy`
   (a field whose value disagrees across sources — pick the truth), `TriageRow` (an incoming item the
   agent classified + routed), `ScoredOption` (an AI-ranked candidate — score + rationale + specs).
@@ -243,15 +244,23 @@ Compose the surfaces as a loop, and reach for the right one by job:
   intelligence is legible. On a canvas/composer app reach for `AgentProgress` — `AgentRun`
   collapsed into a floating pill (avatar + current step) that EXPANDS on press; the composer
   morphs into it while running, and reveals again when done.
-- **Review before apply** — `Suggestion` (a NEW proposed value → accept / edit / dismiss, carrying
-  a `Confidence` chip) or `ChangeReview` (an EDIT to existing state → before→after, apply / discard).
-  For a shortlist, stack ranked `Suggestion`s (highest confidence first). `ChangeReview` also has a
-  **1-by-1** mode — pass `onAcceptItem`/`onRejectItem` and each suggested change gets its own ✓/✕,
-  Apply committing only the accepted set (the chat copilot). Nothing auto-applies.
-- **Review an extracted record** — `RecordReview`: one record the agent pulled from a document, its
-  fields click-to-edit (`InlineTextInput`), with a confidence + Confirm / Remove; Confirm collapses
-  it to a checklist row (Undo to re-open). Stack several under a "Save all" to capture a whole
-  document → table (see `tpl_extract`). Nothing writes until the human confirms + saves.
+- **Review before apply — ONE card + the batch engine, the BODY is compositional.** Every "the agent
+  proposes → the human accepts / edits / dismisses → nothing auto-applies" surface wears the same
+  `reviewCardStyle` + an optional `Confidence`. There are two primitives:
+  - **`ReviewCard`** — THE single-proposal review card. It owns the chrome (eyebrow + `Confidence`,
+    rationale, a generic `actions` footer — Accept/Edit/Dismiss, Confirm/Remove, Accept/Reassign,
+    whatever the verbs are — and a collapse-to-a-row resolved state); the BODY is `children`. **Layout
+    follows the props**: give it an `eyebrow`/`title` and the chrome LEADS (header-first — a value or
+    record proposal, e.g. a `RecordFields` → `tpl_extract`); give it only `children` and the BODY leads,
+    the confidence + reason beneath it (body-first — a `MatchSides` pairing where the link is the hero
+    → `tpl_match`). Stack several (rank by confidence) for a shortlist or a document's records.
+  - **`ChangeReview`** — THE batch engine for a SET you decide each then commit together. `renderItem`
+    draws each proposal (a `ChangeDiff` before→after body, a record, an editable form), 1-by-1
+    Keep/Drop collapses each, "Accept all" + Apply commits only the kept (e.g. ingested rate lines —
+    `tpl_ratedesk`); whole-set mode applies/discards the lot.
+  The body atoms (`RecordFields`, `MatchSides`, `ChangeDiff`) are pure presentation — usable inside
+  either engine OR standalone (a live-edit field card). The decide / accept-all / apply mechanics are
+  never re-implemented per surface.
 - **Ask back** — `Clarify`: when the agent is unsure, it asks a question with quick-reply options
   and PAUSES, instead of guessing wrong. Human-in-the-loop input mid-run.
 - **Provenance** — `Sources`: openable chips saying where the output came FROM (records, a
@@ -267,7 +276,7 @@ a conversation, a single pass, or generated prose:
 - **Canvas** (`tpl_dieline`) — the page IS the design on a pannable/zoomable surface: it stays
   CENTRED at every zoom (a floating zoom pill bottom-left), the FLOATING composer at the bottom (a
   `Composer`: attach a photo → review/remove it → add a note → send, with `sendDisabled` allowing a
-  file-and/or-text submit — NOT auto-run on attach) morphs into `AgentProgress` while running, and a pinned PARAMS PANEL (the `RecordReview` field-card
+  file-and/or-text submit — NOT auto-run on attach) morphs into `AgentProgress` while running, and a pinned PARAMS PANEL (a `RecordFields` field-card
   in live-edit mode, carrying the single Download; minimizes to a pill) floats centre-right. Panel, zoom pill and composer
   float ON TOP — they never shift the design. (Floating layers use a `pointerEvents:"none"` wrapper
   with the interactive child set `"auto"`; RN-Web ignores `"box-none"` in style, so a full-width
@@ -277,22 +286,33 @@ a conversation, a single pass, or generated prose:
 - **Chat** (`tpl_assistant`) — a conversation where the agent's answer carries suggested edits the
   user approves/rejects **1-by-1** (`ChangeReview` per-item), applying only the accepted set. An AI
   copilot that proposes changes to a record and never commits on its own.
-- **One-shot** (`tpl_extract`, `RecordReview`) — read an image → the agent extracts the records →
-  review each (`RecordReview`: fields click-to-edit, Confirm collapses it to a checklist row) →
-  Save all to the table. A data-capture pass; nothing stored until confirmed.
+- **One-shot** (`tpl_extract`) — read an image → the agent extracts the records → review each as a
+  `ReviewCard` wrapping a `RecordFields` body (fields click-to-edit, Confirm collapses it to a
+  checklist row) → Save all to the table. A data-capture pass; nothing stored until confirmed.
+- **Bulk ingest desk** (`tpl_ratedesk`) — the page IS a filterable register (a From → To route picker
+  + `ColumnFilter` pills → `Card padding:0` + full-bleed `Table`), the register the hero. Updating
+  prices is ONE header CTA that opens a Dialog wizard: drop SEVERAL source docs at once → the agent
+  reads them all (`AgentRun`) → a `ChangeReview` 1-by-1 (each proposal a Keep/Drop card, New / Updated
+  with old→new delta, "Accept all" + Apply) → the kept rows land in the register. Pairs `tpl_extract`'s
+  ingest with `tpl_directory`'s register. For a maintained reference table — rate card, price list,
+  tariff, catalogue: re-ingest the source sheets beats hand-typing.
 - **Draft** (`tpl_draft`) — the agent writes a first draft from context; the OUTPUT itself streams
   (the text fills in live), then becomes an editable surface the human refines before sending.
   Tone/length steer it. For generated prose — a reply, a quote, a listing.
 
 The next six output STRUCTURE the first four can't — when the answer is a panel of facts, a queue of
 decisions, or a ranked set, don't cram it into chat prose. Each pairs a template with a primitive:
-- **Answer desk** (`tpl_lookup`, `SpecList`) — converse on the LEFT, a pinned STRUCTURED answer on
-  the RIGHT (a verdict header + an exact breakdown + the policies + sources); a follow-up refines the
-  same panel. For look-up-and-explain: tariff/HS, fee lookup, policy Q&A, a spec/compliance desk. The
-  structured answer is the product; chat just steers. (NOT a chat with the answer buried in a bubble.)
-- **Match** (`tpl_match`, `MatchRow`) — the agent proposes PAIRINGS with its reasoning; each row is
-  two-sided (source ↔ proposed counterpart + confidence), accept / reassign / reject, high-confidence
-  batch-accept. The AI reconciliation / dedup / correlation queue. (The deterministic cousin
+- **Answer desk** (`tpl_lookup`, `SpecList`) — describe the goods on the LEFT → the agent RANKS the
+  matching codes (NEAREST MATCHES, the top one Recommended) → pick one and its STRUCTURED answer pins on
+  the RIGHT (a verdict header + an exact breakdown + the policies + sources). Input → matches → pick,
+  NOT a single confident verdict: classification is ambiguous, so the alternatives are first-class and
+  picking a different one changes the duty; refining the description re-ranks. For look-up-and-explain:
+  tariff/HS, fee lookup, policy Q&A, a spec/compliance desk. (NOT a chat with the answer in a bubble.)
+- **Match** (`tpl_match`, body-first `ReviewCard` + `MatchSides`) — the agent proposes PAIRINGS with
+  its reasoning; each is a `ReviewCard` (no title, so body-first) whose body is a two-sided `MatchSides`
+  pairing (source → proposed counterpart), with the confidence + reason beneath, accept / reassign /
+  reject, high-confidence batch-accept. The AI reconciliation / dedup / correlation queue. (The
+  deterministic cousin
   `tpl_reconcile` has no agent reasoning — that's the tell for which to reach for.)
 - **Briefing** (`tpl_briefing`, `Finding`) — a generated narrative over the data + a RANKED list of
   what needs attention, each finding carrying a severity, a metric, its sources, and one action. The
@@ -425,6 +445,19 @@ was only ever about the review surfaces' sparkles/severity glyphs, not functiona
   · `FilterPill` is THE secondary-dimension filter — a compact pill that opens a composed popover
     editor (`PickerMenu multi` / `RangeSlider` / `Counter` / date range). Single-select closes on
     pick via the `{({close}) => …}` render prop.
+  · `ColumnFilter` is the TYPED column filter — give it a `FilterableColumn` (`text` / `number` /
+    `select`) + a controlled `ColumnFilterValue` and it renders the right editor (contains / range /
+    multi-select) inside a `FilterPill`, with `columnFilterToConditions` mapping the value to query
+    predicates. Reach for it — ONE compact pill per dimension — when a register filters on SEVERAL
+    columns (origin, destination, carrier, type…). Never hand-roll a row of bespoke chips/filters,
+    and never use a permanently-expanded `ChipGroup` for a secondary dimension.
+  · `Combobox pill` is the SEARCHABLE filter in the band — `<Combobox pill>` wears the same white
+    toolbar-pill surface as `SearchInput`/`FilterPill` (don't put a bare form-look Combobox in a
+    toolbar — its transparent input reads grey on the zinc-50 canvas beside the white pills). Reach
+    for it over `ColumnFilter` when the value is ONE of a large/growing set you type to narrow (a
+    port, a customer) rather than a short fixed list. Pass `recentOptions` (the same option list) so
+    a click opens the full list, then typing filters. The **From → To route picker** is two of them
+    (`icon="map-pin"`, `clearable`) with an `arrow-right` between — flight-search style.
   · `Tabs` switch between VIEWS/sections (different content/layout) — never a subset of one list.
     `SegmentedControl` chooses a MODE/PARAMETER of the SAME view (2–4 peers, no panel swap).
 - **Footer actions align RIGHT.** `PopoverFooter`/`DialogFooter`/`DrawerFooter` default
@@ -490,11 +523,13 @@ recipe for a screen JOB; copy and adapt). Pick by the job:
   reveals CENTRED on a pannable/zoomable surface, the floating composer morphing into `AgentProgress`,
   a pinned live-edit params panel centre-right; prompt OR edit a param to iterate) ·
   `tpl_assistant` (a chat copilot: the agent's answer carries suggested edits approved/rejected
-  1-by-1) · `tpl_extract` (read an image → extract records → review/edit each (`RecordReview`) →
-  Save all) · `tpl_draft` (draft generation: context → the reply text streams into an editable surface
+  1-by-1) · `tpl_extract` (read an image → extract records → review/edit each (`ReviewCard` +
+  `RecordFields`) → Save all) · `tpl_ratedesk` (BULK INGEST desk: a register-as-hero with an "Import
+  prices" CTA → a Dialog wizard: drop several sheets → `ChangeReview` 1-by-1 → kept rows land in the
+  register; for a maintained rate card / price list / tariff) · `tpl_draft` (draft generation: context → the reply text streams into an editable surface
   → refine → send; tone/length steer it). *Structure*: `tpl_lookup` (the ANSWER desk: converse left,
   a pinned `SpecList` verdict panel right; a follow-up refines it) · `tpl_match` (AI reconciliation:
-  `MatchRow` pairings with reasoning, accept/reassign/reject) · `tpl_briefing` (a generated narrative
+  body-first `ReviewCard` + `MatchSides` pairings with reasoning, accept/reassign/reject) · `tpl_briefing` (a generated narrative
   + a ranked `Finding` attention list) · `tpl_crosscheck` (the audit desk: `Discrepancy` cards where
   the documents disagree) · `tpl_triage` (an inbox of `TriageRow`s the agent classified + routed) ·
   `tpl_compare` (ranked `ScoredOption` candidates the agent scored).
@@ -516,7 +551,9 @@ inline_text_input · inline_number_input · inline_select · inline_member_selec
 inline_time_picker (the Inline* family — per-field editors on `inline_edit`'s `useInlineEdit` +
 `InlineEditView`; `InlineSelect`/`InlineMemberSelect` take `renderValue` for a chip/badge at rest) ·
 list · list_item · menu_button · menu_list_item · detail_row · pressable_row · action_menu ·
-floating_action_bar · filter_pill · sort_header · table · pagination · accordion · stepper ·
+floating_action_bar · filter_pill · column_filter (ColumnFilter — the typed per-column filter pill +
+columnFilterToConditions; for a register filtering on several columns) · chip_group · search_input ·
+sort_header · table · pagination · accordion · stepper ·
 step_progress · step_list · timeline · drawer (+ DrawerFooter) · dialog · popover · tooltip ·
 command_menu · alert · peek · empty_state · completion_state · callout (Callout · CalloutTitle ·
 CalloutText · CalloutActions) · kpi_card · kpi_strip · metric · trend_chip · sparkline ·
@@ -527,11 +564,11 @@ file_gallery_modal · image_gallery · avatar · skeleton · activity_indicator
 spacer · stack · section_card · page_header · page_content · calendar (calendar/index.ts) · gantt ·
 comments_thread · agent_run (live streaming work feed) · agent_progress (its compact floating
 expandable form — a composer's working state) · composer (Composer — the adaptive command/chat
-composer: a compact pill that expands for long text + attachments) · suggestion (review-for-approval) · confidence (calibrated high/med/low) ·
-record_review (RecordReview — an extracted record reviewed + edited before save) · change_review (before→after — whole-set OR 1-by-1) ·
+composer: a compact pill that expands for long text + attachments) · review_card (ReviewCard — THE single-proposal review card; compositional body via children + a generic actions footer; header-first with a title/eyebrow, body-first without) · confidence (calibrated high/med/low) ·
+record_fields (RecordFields — the editable extracted-record BODY for a ReviewCard, or a standalone live-edit field card) · change_review (ChangeReview — the BATCH review engine, whole-set OR 1-by-1; compositional `renderItem` body + the `ChangeDiff` before→after helper) ·
 clarify (the agent asks back, via ChoiceList) · choice_list (ChoiceList — selectable answer options,
 the agent's quick-reply surface) · sources (provenance chips, per-kind glyphs) · spec_list (SpecList — the exact
-labeled-value breakdown, the panel of an answer) · match_row (MatchRow — a two-sided AI pairing) ·
+labeled-value breakdown, the panel of an answer) · match_sides (MatchSides — the two-sided pairing BODY for a body-first ReviewCard reconciliation; composable side slots + the MatchSideText default) ·
 finding (Finding — one ranked briefing/audit insight) · discrepancy (Discrepancy — a field that
 disagrees across sources) · triage_row (TriageRow — an item the agent classified + routed) ·
 scored_option (ScoredOption — an AI-ranked candidate) ·

package/examples/tpl_assistant.tsx

@@ -4,7 +4,7 @@ import { colors } from "@lotics/ui/colors";
 import { Text } from "@lotics/ui/text";
 import { DotsIndicator } from "@lotics/ui/dots_indicator";
 import { Composer } from "@lotics/ui/composer";
-import { ChangeReview, type ChangeReviewItem, type ChangeReviewItemStatus } from "@lotics/ui/change_review";
+import { ChangeReview, ChangeDiff, type ChangeReviewItemStatus } from "@lotics/ui/change_review";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Template · AI assistant — a CHAT workflow, a different shape from the design
@@ -14,17 +14,24 @@ import { ChangeReview, type ChangeReviewItem, type ChangeReviewItemStatus } from
 // copilot proposing changes to a record, never committing on its own. All mock.
 // ─────────────────────────────────────────────────────────────────────────────
 
+/** One field's before→after edit — the assistant's proposals, reviewed 1-by-1. */
+interface EditChange {
+  label: string;
+  before?: string;
+  after: string;
+}
+
 interface ChatMsg {
   id: string;
   role: "user" | "agent";
   text?: string;
   /** An agent turn may carry suggested edits to review 1-by-1. */
-  changes?: ChangeReviewItem[];
+  changes?: EditChange[];
   applied?: boolean;
   typing?: boolean;
 }
 
-const SUGGESTED: Omit<ChangeReviewItem, "status">[] = [
+const SUGGESTED: EditChange[] = [
   { label: "Company", before: "acme packaging co", after: "Acme Packaging Co." },
   { label: "Phone", before: "0901234567", after: "+84 90 123 4567" },
   { label: "Email", before: "SALES@ACME.VN", after: "sales@acme.vn" },
@@ -109,7 +116,21 @@ export function TplAssistant() {
                 {m.text ? <Text size="sm">{m.text}</Text> : null}
                 {m.changes ? (
                   <ChangeReview
-                    changes={m.changes.map((c, i) => ({ ...c, status: decisions[`${m.id}:${i}`] ?? "pending" }))}
+                    items={m.changes}
+                    getKey={(c, i) => `${m.id}:${i}`}
+                    statusOf={(_, i) => decisions[`${m.id}:${i}`] ?? "pending"}
+                    renderItem={(c) => (
+                      <>
+                        <Text size="xs" color="muted" weight="medium">{c.label}</Text>
+                        <ChangeDiff before={c.before} after={c.after} />
+                      </>
+                    )}
+                    renderSummary={(c, kept) => (
+                      <View style={{ flexDirection: "row", alignItems: "center", gap: 10 }}>
+                        <Text size="sm" weight="medium" numberOfLines={1}>{c.label}</Text>
+                        <Text size="sm" numberOfLines={1} color={kept ? "default" : "muted"} style={[{ flex: 1 }, kept ? undefined : { textDecorationLine: "line-through" }]}>{kept ? c.after : (c.before ?? c.after)}</Text>
+                      </View>
+                    )}
                     status={m.applied ? "applied" : "open"}
                     applyLabel="Apply accepted"
                     onAcceptItem={active ? (i) => decide(m.id, i, "accepted") : undefined}

package/examples/tpl_dieline.tsx

@@ -24,7 +24,7 @@ const MOCK_PHOTO: DisplayFile = {
 // ─────────────────────────────────────────────────────────────────────────────
 // Template · AI design canvas (the carton "dieline" app) — the FLAGSHIP shape:
 // the page IS the design. The dieline fills the centre, a FLOATING composer sits
-// at the bottom, and a pinned PARAMS PANEL (the RecordReview field-card, here in
+// at the bottom, and a pinned PARAMS PANEL (a RecordFields field-card, here in
 // live-edit mode) floats at the centre-right. Empty → drop a photo in the
 // composer → the centre processes while the composer MORPHS into a progress pill
 // (AgentProgress) → the dieline reveals, the params panel appears, the composer
@@ -228,7 +228,7 @@ export function TplDieline() {
   );
 }
 
-// The pinned right-rail — the RecordReview field-card in live-edit mode: each
+// The pinned right-rail — a RecordFields field-card in live-edit mode: each
 // parameter is click-to-edit and re-flows the design on save; one primary
 // Download. Floats over the canvas, so it carries the composer's lift.
 const PARAMS: { key: keyof Dims; label: string }[] = [

package/examples/tpl_extract.tsx

@@ -6,7 +6,8 @@ import { Button } from "@lotics/ui/button";
 import { Card, CardBody, CardHeader, CardHeaderTitle } from "@lotics/ui/card";
 import { FileDropzone } from "@lotics/ui/file_dropzone";
 import { AgentRun, type AgentRunStep } from "@lotics/ui/agent_run";
-import { RecordReview, type RecordField } from "@lotics/ui/record_review";
+import { ReviewCard } from "@lotics/ui/review_card";
+import { RecordFields, type RecordField } from "@lotics/ui/record_fields";
 import { Sources } from "@lotics/ui/sources";
 import { CompletionState } from "@lotics/ui/completion_state";
 import { type ConfidenceLevel } from "@lotics/ui/confidence";
@@ -14,8 +15,8 @@ import { type ConfidenceLevel } from "@lotics/ui/confidence";
 // ─────────────────────────────────────────────────────────────────────────────
 // Template · AI extract & confirm — read an image, then review each extracted
 // RECORD before it's added to a table. Drop a photo → the agent extracts the
-// lines (AgentRun) → each lands as a `RecordReview` card whose fields are
-// click-to-edit; Confirm collapses it to a tidy checklist row (Undo to re-open),
+// lines (AgentRun) → each lands as a `ReviewCard` wrapping a `RecordFields` body
+// whose fields are click-to-edit; Confirm collapses it to a tidy checklist row (Undo to re-open),
 // Remove skips it → Save all writes the confirmed lines at once. A one-shot
 // capture pass: nothing is stored until the human has reviewed it. All mock.
 // ─────────────────────────────────────────────────────────────────────────────
@@ -145,17 +146,24 @@ export function TplExtract() {
             <Sources label="Extracted from" onOpen={() => {}} sources={[{ id: "doc", label: "packing-list.jpg", kind: "document", detail: "1 photo" }]} />
             <View style={{ gap: 10 }}>
               {RECORDS.map((r) => (
-                <RecordReview
+                <ReviewCard
                   key={r.id}
                   title={r.title}
                   confidence={r.confidence}
-                  status={statuses[r.id] ?? "pending"}
-                  fields={r.fields.map((f, i) => ({ ...f, value: values[r.id][i] }))}
-                  onEditField={(i, value) => editField(r.id, i, value)}
-                  onConfirm={() => setStatus(r.id, "confirmed")}
-                  onRemove={() => setStatus(r.id, "removed")}
+                  status={statuses[r.id] === "confirmed" ? "accepted" : statuses[r.id] === "removed" ? "dismissed" : "open"}
+                  acceptedLabel="Confirmed"
+                  dismissedLabel="Removed"
+                  actions={[
+                    { label: "Remove", onPress: () => setStatus(r.id, "removed"), kind: "muted" },
+                    { label: "Confirm", onPress: () => setStatus(r.id, "confirmed"), kind: "secondary" },
+                  ]}
                   onUndo={() => setStatus(r.id, undefined)}
-                />
+                >
+                  <RecordFields
+                    fields={r.fields.map((f, i) => ({ ...f, value: values[r.id][i] }))}
+                    onEditField={(i, value) => editField(r.id, i, value)}
+                  />
+                </ReviewCard>
               ))}
             </View>
             <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>

package/examples/tpl_lookup.tsx

@@ -9,23 +9,29 @@ import { Composer } from "@lotics/ui/composer";
 import { AgentRun, type AgentRunStep } from "@lotics/ui/agent_run";
 import { SpecList, type SpecRow } from "@lotics/ui/spec_list";
 import { Confidence, type ConfidenceLevel } from "@lotics/ui/confidence";
+import { Badge } from "@lotics/ui/badge";
 import { Sources, type SourceRef } from "@lotics/ui/sources";
 
 // ─────────────────────────────────────────────────────────────────────────────
-// Template · Answer desk — converse on the LEFT, a pinned structured ANSWER on
-// the RIGHT. The AI's verdict isn't prose buried in a chat log: it's a panel of
-// scannable components — a code, the exact duty breakdown (SpecList), the
-// policies that apply, the sources it rested on. You ask, you watch the agent
-// work (AgentRun), the panel pins; a follow-up refines the SAME panel. Same
-// shape for any look-up-and-explain: tariff/HS, fee lookup, policy Q&A, a
-// spec/compliance desk. The structured answer is the product; chat just steers.
+// Template · Answer desk — describe the goods on the LEFT, the agent RANKS the
+// matching codes (nearest matches, the top one Recommended), you pick one and its
+// structured ANSWER pins on the RIGHT. The flow is input → matches → pick, not a
+// single confident verdict: classification is ambiguous, so the alternatives are
+// first-class (the prep/pack push the goods to a different code with a different
+// duty). The answer is a panel of scannable components — the code, the exact duty
+// breakdown (SpecList), the policies, the sources. Refine the description ("what
+// if it's pre-cooked?") and the ranking updates. Same shape for any
+// look-up-and-explain: tariff/HS, fee lookup, policy Q&A, a spec/compliance desk.
 // ─────────────────────────────────────────────────────────────────────────────
 
 type Tone = "warning" | "info" | "success";
 interface Policy { tone: Tone; title: string; text: string }
-interface Verdict {
+interface Candidate {
   id: string;
-  query: string;
+  /** Short heading for the ranked list on the left. */
+  label: string;
+  /** The agent's top pick — wears a "Recommended" badge, selected first. */
+  recommended?: boolean;
   code: string;
   heading: string;
   confidence: ConfidenceLevel;
@@ -37,10 +43,16 @@ interface Verdict {
   sources: SourceRef[];
 }
 
-const VERDICTS: Verdict[] = [
+// One query, several plausible HS codes — the agent RANKS them; the declarant
+// picks. The prep and the pack push the goods to a different code with a
+// different duty, which is exactly why a single confident verdict is wrong.
+const QUERY = "Black tiger shrimp, headless shell-on, IQF frozen, 1 kg retail packs";
+
+const CANDIDATES: Candidate[] = [
   {
-    id: "v-shrimp",
-    query: "Black tiger shrimp, headless shell-on, IQF frozen, 1 kg retail packs",
+    id: "c1",
+    label: "Frozen shrimp · retail packs ≤ 1 kg",
+    recommended: true,
     code: "0306.17.10",
     heading: "Frozen shrimp & prawns of the family Penaeidae — not in airtight containers",
     confidence: "high",
@@ -69,54 +81,57 @@ const VERDICTS: Verdict[] = [
     ],
   },
   {
-    id: "v-shirt",
-    query: "Men's T-shirts, 100% cotton, knit, short sleeve",
-    code: "6109.10.00",
-    heading: "T-shirts, singlets & other vests, knitted or crocheted — of cotton",
-    confidence: "high",
-    basis: "Knitted construction of cotton → heading 6109; subheading .10 for cotton (not man-made fibres).",
+    id: "c2",
+    label: "Frozen shrimp · other (bulk / catering)",
+    code: "0306.17.90",
+    heading: "Frozen shrimp & prawns of the family Penaeidae — other",
+    confidence: "medium",
+    basis:
+      "Same heading 0306.17, but the residual national line .90 covers packs ABOVE 1 kg / bulk catering. Right only if the ≤ 1 kg retail-pack evidence is set aside — the duty is identical, the line is not.",
     duty: [
-      { label: "Import duty (MFN)", value: "20%" },
-      { label: "ATIGA (Form D)", value: "0%" },
+      { label: "Import duty (MFN)", value: "0%" },
       { label: "VAT", value: "8%" },
+      { label: "Anti-dumping", value: "0%" },
     ],
-    dutyTotal: { label: "Effective tax on CIF", value: "8–28%" },
+    dutyTotal: { label: "Effective tax on CIF", value: "8%" },
     specs: [
-      { label: "Chapter", value: "61 — Knitted apparel" },
-      { label: "Construction", value: "Knit" },
-      { label: "Material", value: "100% cotton" },
+      { label: "Chapter", value: "03 — Fish & crustaceans" },
+      { label: "Form", value: "Frozen (IQF)" },
+      { label: "Net pack", value: "> 1 kg / bulk" },
     ],
     policies: [
-      { tone: "info", title: "Origin proof is decisive", text: "Without a Form D the MFN 20% applies; with it the line drops to 0% — a 20-point swing on CIF." },
+      { tone: "warning", title: "Health certificate required", text: "Aquatic-product imports need a health certificate from the competent authority of the exporting country before clearance." },
     ],
     sources: [
-      { id: "s1", label: "Tariff schedule 2026", kind: "knowledge", detail: "Ch. 61" },
-      { id: "s2", label: "ATIGA tariff", kind: "knowledge" },
+      { id: "s1", label: "Tariff schedule 2026", kind: "knowledge", detail: "Ch. 03" },
+      { id: "s2", label: "Heading 0306.17", kind: "knowledge" },
     ],
   },
   {
-    id: "v-batt",
-    query: "Lithium-ion battery packs for e-scooters, 48V",
-    code: "8507.60.10",
-    heading: "Lithium-ion accumulators — of a kind used as the primary source of power",
-    confidence: "medium",
-    basis: "Secondary (rechargeable) lithium-ion cells assembled into a pack → heading 8507.60. The national line turns on end-use; confirm the device class.",
+    id: "c3",
+    label: "Shrimp, prepared or preserved",
+    code: "1605.21.00",
+    heading: "Shrimp & prawns, prepared or preserved — not in airtight containers",
+    confidence: "low",
+    basis:
+      "Only if the product is COOKED / breaded / marinated → chapter 16 (prepared), heading 1605.21. Raw IQF shrimp is NOT prepared — the wrong line unless processing is confirmed, and it carries a much higher MFN rate.",
     duty: [
-      { label: "Import duty (MFN)", value: "5%" },
-      { label: "VAT", value: "10%" },
+      { label: "Import duty (MFN)", value: "20%" },
+      { label: "ATIGA (Form D)", value: "0%" },
+      { label: "VAT", value: "8%" },
     ],
-    dutyTotal: { label: "Effective tax on CIF", value: "15.5%" },
+    dutyTotal: { label: "Effective tax on CIF", value: "8–28%" },
     specs: [
-      { label: "Chapter", value: "85 — Electrical machinery" },
-      { label: "Cell chemistry", value: "Li-ion (rechargeable)" },
-      { label: "Nominal voltage", value: "48 V" },
+      { label: "Chapter", value: "16 — Prepared fish / crustaceans" },
+      { label: "Form", value: "Cooked / prepared" },
+      { label: "Presentation", value: "Not airtight" },
     ],
     policies: [
-      { tone: "warning", title: "Dangerous-goods handling", text: "Lithium batteries ship under UN 3480 — IATA/IMDG packaging and declaration apply; carriers may require a test summary (UN 38.3)." },
+      { tone: "info", title: "Processing decides the chapter", text: "Raw frozen sits in Ch. 03; cooked / breaded / marinated moves to Ch. 16. The 20-point MFN gap makes the evidence of processing decisive." },
     ],
     sources: [
-      { id: "s1", label: "Tariff schedule 2026", kind: "knowledge", detail: "Ch. 85" },
-      { id: "s2", label: "Heading 8507.60", kind: "knowledge" },
+      { id: "s1", label: "Tariff schedule 2026", kind: "knowledge", detail: "Ch. 16" },
+      { id: "s2", label: "Heading 1605.21", kind: "knowledge" },
     ],
   },
 ];
@@ -131,14 +146,14 @@ const SCRIPT: ScriptStep[] = [
 ];
 
 export function TplLookup() {
-  const [activeId, setActiveId] = useState(VERDICTS[0].id);
+  const [activeId, setActiveId] = useState(CANDIDATES.find((c) => c.recommended)?.id ?? CANDIDATES[0].id);
   const [phase, setPhase] = useState<"running" | "ready">("ready");
   const [revealed, setRevealed] = useState(SCRIPT.length);
   const [prompt, setPrompt] = useState("");
   const [runKey, setRunKey] = useState(0);
   const timer = useRef<ReturnType<typeof setInterval> | null>(null);
 
-  const active = VERDICTS.find((v) => v.id === activeId) ?? VERDICTS[0];
+  const active = CANDIDATES.find((c) => c.id === activeId) ?? CANDIDATES[0];
 
   useEffect(() => {
     if (runKey === 0) return;
@@ -159,16 +174,11 @@ export function TplLookup() {
   }, [runKey]);
 
   const ask = (text: string) => {
-    const hit =
-      VERDICTS.find((v) => {
-        const q = text.toLowerCase();
-        return (
-          (v.id === "v-shirt" && (q.includes("shirt") || q.includes("cotton") || q.includes("knit"))) ||
-          (v.id === "v-batt" && (q.includes("batter") || q.includes("lithium") || q.includes("cell"))) ||
-          (v.id === "v-shrimp" && (q.includes("shrimp") || q.includes("prawn") || q.includes("frozen")))
-        );
-      }) ?? VERDICTS[0];
-    setActiveId(hit.id);
+    // Refining the description re-ranks: cooked → prepared (Ch. 16), bulk → the
+    // residual frozen line, else the recommended retail-pack code.
+    const q = text.toLowerCase();
+    const hit = /cook|prepar|breaded|marinat/.test(q) ? "c3" : /bulk|cater/.test(q) ? "c2" : "c1";
+    setActiveId(hit);
     setPrompt("");
     setRunKey((k) => k + 1);
   };
@@ -185,35 +195,38 @@ export function TplLookup() {
       <View style={{ width: 380, backgroundColor: colors.white, borderRightWidth: 1, borderRightColor: colors.zinc[200] }}>
         <View style={{ paddingHorizontal: 20, paddingTop: 18, paddingBottom: 12, gap: 2 }}>
           <Text size="md" weight="semibold">HS classification</Text>
-          <Text size="sm" color="muted">Describe the goods — the agent finds the code and explains the duty</Text>
+          <Text size="sm" color="muted">Describe the goods — the agent ranks the matching codes; pick one to see its duty</Text>
         </View>
         <Divider />
 
         <ScrollView style={{ flex: 1 }} contentContainerStyle={{ padding: 16, gap: 16 }}>
           {/* current run */}
-          <AgentRun title={`Classifying — ${active.query}`} steps={steps} state={streaming ? "streaming" : "done"} />
+          <AgentRun title="Classifying the goods" steps={steps} state={streaming ? "streaming" : "done"} />
 
           <View style={{ gap: 8 }}>
-            <Text size="xs" color="muted" weight="medium">This session</Text>
-            {VERDICTS.map((v) => (
+            <Text size="xs" color="muted" weight="medium">Nearest matches</Text>
+            <Text size="xs" color="muted" numberOfLines={2}>{QUERY}</Text>
+            {CANDIDATES.map((c) => (
               <PressableHighlight
-                key={v.id}
-                onPress={() => { setActiveId(v.id); setPhase("ready"); setRevealed(SCRIPT.length); }}
-                accessibilityLabel={`Show ${v.query}`}
+                key={c.id}
+                onPress={() => { setActiveId(c.id); setPhase("ready"); setRevealed(SCRIPT.length); }}
+                accessibilityLabel={`Show ${c.code} — ${c.label}`}
                 style={{
                   padding: 10,
                   borderRadius: 10,
                   borderWidth: 1,
-                  borderColor: v.id === activeId ? colors.zinc[900] : colors.zinc[200],
-                  backgroundColor: v.id === activeId ? colors.zinc[50] : colors.white,
-                  gap: 3,
+                  borderColor: c.id === activeId ? colors.zinc[900] : colors.zinc[200],
+                  backgroundColor: c.id === activeId ? colors.zinc[50] : colors.white,
+                  gap: 4,
                 }}
               >
-                <Text size="sm" weight="medium" numberOfLines={1}>{v.query}</Text>
                 <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
-                  <Text size="xs" color="muted" tabular>{v.code}</Text>
-                  <Confidence level={v.confidence} />
+                  <Text size="sm" weight="semibold" tabular numberOfLines={1}>{c.code}</Text>
+                  {c.recommended ? <Badge color="blue" label="Recommended" /> : null}
+                  <View style={{ flex: 1 }} />
+                  <Confidence level={c.confidence} />
                 </View>
+                <Text size="xs" color="muted" numberOfLines={1}>{c.label}</Text>
               </PressableHighlight>
             ))}
           </View>

package/examples/tpl_match.tsx

@@ -6,7 +6,8 @@ import { Button } from "@lotics/ui/button";
 import { KPIStrip } from "@lotics/ui/kpi_strip";
 import { SegmentedControl } from "@lotics/ui/segmented_control";
 import { EmptyState } from "@lotics/ui/empty_state";
-import { MatchRow } from "@lotics/ui/match_row";
+import { ReviewCard, type ReviewAction } from "@lotics/ui/review_card";
+import { MatchSides, MatchSideText } from "@lotics/ui/match_sides";
 import type { ConfidenceLevel } from "@lotics/ui/confidence";
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -102,19 +103,29 @@ export function TplMatch() {
           />
         ) : (
           <View style={{ gap: 10 }}>
-            {visible.map((r) => (
-              <MatchRow
-                key={r.id}
-                source={r.source}
-                match={r.match}
-                rationale={r.rationale}
-                confidence={r.confidence}
-                status={r.status}
-                onAccept={r.match ? () => set(r.id, "accepted") : undefined}
-                onReassign={r.alt ? () => reassign(r.id) : undefined}
-                onDismiss={() => set(r.id, "dismissed")}
-              />
-            ))}
+            {visible.map((r) => {
+              const actions: ReviewAction[] = [
+                { label: "Not a match", onPress: () => set(r.id, "dismissed"), kind: "muted" },
+                ...(r.alt ? [{ label: r.match ? "Reassign" : "Find match", onPress: () => reassign(r.id), kind: "secondary" as const }] : []),
+                ...(r.match ? [{ label: "Accept", onPress: () => set(r.id, "accepted"), kind: "primary" as const }] : []),
+              ];
+              return (
+                <ReviewCard
+                  key={r.id}
+                  summary={r.source.title}
+                  confidence={r.confidence}
+                  rationale={r.rationale}
+                  status={r.status}
+                  acceptedLabel={r.match ? `Matched · ${r.match.title}` : "Matched"}
+                  actions={actions}
+                >
+                  <MatchSides
+                    source={<MatchSideText title={r.source.title} detail={r.source.detail} />}
+                    match={r.match ? <MatchSideText title={r.match.title} detail={r.match.detail} align="right" /> : undefined}
+                  />
+                </ReviewCard>
+              );
+            })}
           </View>
         )}
       </View>