@lotics/ui 15.2.0 → 16.0.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` for a custom-code app's `vite.config.ts`). Read before building any screen; reuse first. |
 | [docs/data_entry.md](./docs/data_entry.md) | Which editing pattern for which job — inline edit, fieldset forms, find-or-create (`Combobox`), line items, handoffs, phased records, billing, tags, dispositions, attachments (incl. the three-way file INTAKE: CTA + `FileDropTarget` + `usePasteFiles`), stage gates. |
-| [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 + result list), findings, provenance, confidence; the UI half of the SDK's [ai doc](../app-sdk/docs/ai.md). |
+| [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). |
 | [docs/composition.md](./docs/composition.md) | The design-language contract — canvas + content column, heading altitude, banded cards, register vs inset rows, master-detail `Drawer`, view controls, color discipline, typography, whitespace. |
 | [docs/templates.md](./docs/templates.md) | The map of `examples/tpl_*.tsx` — what shape each template solves and which to start from (copy + adapt, never import) — plus the record-surface composition rules (pipeline order, static shape, decision budget). |
 

package/MIGRATION.md

@@ -4,6 +4,19 @@ 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.
 
+## v16 from 15.x
+
+**`Confidence` IS now a callout with a REQUIRED basis** — `children` (what was checked and
+what came of it) is mandatory, the meter + level phrase head the block, and the box stays
+white with a hairline border at every level (the meter is the only colored element). The
+standalone three-tick meter no longer exists: a bare `<Confidence level="high" />` fails to type-check. Migrate by
+adding the basis (`<Confidence level="low">2 of 7 references fail their checksum (X, Y) —
+verify against the source.</Confidence>`) — or, where a compact meter decorated a ranked row
+or a proposal card, remove it: rank, badges, and severity already convey standing there.
+
+Additively in v16: `ResultHeader` (`@lotics/ui/result_header`) — the save-direct receipt's
+outcome strip; see ai_patterns §the one law for the receipt composition.
+
 ## v15 from 14.x
 
 `AgentRun`/`AgentProgress`'s **`labelForTool`** prop was replaced by **`labelForCall`** — the

package/docs/ai_patterns.md

@@ -18,19 +18,31 @@ the human stays in charge follows the stakes — split by whether a before-state
 - **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 show the result**. The run ends on a per-item
-  result list — the receipt, not a gate. A result row is a plain composition (no component —
-  hand-roll it): the outcome mark (`success` = `circle-check` green-600 · `error` =
-  `circle-alert` red-600 · needs-attention = `circle-alert` amber-600 · skipped = `minus`
-  zinc-400, size 18) · outcome-first title (sm semibold) · the key figures / the reason (xs,
-  danger ink on error) · one-line provenance (xs muted) · a right-slot `Button` (an
-  open-record jump, a retry); rows stack with `gap: 12`. The closing footer button is
-  dismissal (secondary "Done"), never primary. Correction uses
-  the record's ORDINARY verbs — open it, edit or delete (make the delete workflow CASCADE the
-  record's children, so deletion is always safe) — never a special undo affordance duplicating
-  the delete verb in a second place. A review gate on a create degenerates into proofreading a
-  wall of cards the user blind-confirms; the register shows the same data better. Fewer steps,
-  same control.
+  is nothing to diff → **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 ·
+  outcome title) → the RECEIPT LINES — a `DetailTable` of spread `DetailRow`s (who · how
+  much · how many · the schedule) — → **`Confidence`**: the level WITH its basis as
+  one block, always (the happy path says what was checked; the flagged path NAMES the exact
+  failing values — the user knows what to verify BEFORE opening). Confidence never floats
+  alone as a bare meter on a result surface. NOTHING in the receipt edits: the RECORD is the edit surface (its
+  flagged cells carry the same amber marks), one press away — correction uses the record's
+  ordinary verbs. SEVERAL records: a compact attention-first RESULT REGISTER (`ListItem` per
+  record — tone mark · outcome title · key figures · the needs-checking count) whose rows
+  press STRAIGHT THROUGH to the record — no intermediate screen. Never tabs (they cap out),
+  never stacked collapsed cards, never a field wall duplicating the record page. A
+  flagged value names its exact verdict in amber (a reason line under the value, or a check
+  column cell) and is corrected IN PLACE — `InlineTextInput.onSave` commits immediately
+  through the ordinary update workflow (the record is saved; nothing stages, no apply button
+  exists). A batch-level failure lands on EVERY record as its reason — never ALSO a
+  banner above the list (a top `Callout` is only for information the records don't carry).
+  The closing footer button is dismissal (secondary "Done"), never primary. Correction beyond
+  the receipt uses the record's ORDINARY verbs — open it, edit or delete (make the delete
+  workflow CASCADE the record's children, so deletion is always safe) — never a special undo
+  affordance duplicating the delete verb. A review GATE on a create degenerates into
+  proofreading a wall of cards the user blind-confirms — and a human cannot eyeball-verify a
+  reference number anyway; deterministic post-save checks catch what proofreading cannot.
 
 Either way the deterministic app applies the write. Compose the surfaces as a loop, and reach
 for the right one by job.
@@ -42,7 +54,8 @@ 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`**
    (Keep/Drop per change, app-workflow writes, bounded app authority); creating new records →
-   **save direct + a result list** (correction = the record's ordinary verbs). Either way one button, never a prompt box.
+   **save direct + the receipt** (outcome, verdicts, and a route to the record).
+   Either way one button, never a prompt box.
 2. **Evidence for an in-app decision** (cross-check, audit, tie-out → nothing is written; the
    operator acts on what was found) → **in-app agent** + **`Finding`**. Still bounded and
    prompt-free (an optional instructions brief at most): the brief is fixed, the output is
@@ -369,12 +382,17 @@ list renders nothing.
 
 ## Confidence — `Confidence`
 
-`Confidence` (`@lotics/ui/confidence`): how sure the AI is — a 3-tick meter + the full level
-phrase ("High confidence" / "Medium confidence" / "Low confidence"), emerald / amber / zinc by
-level (low is *unsure*, not an error). Pass `level` (`"high" | "medium" | "low"`) or a 0–1
-`score` (≥ 0.8 high · ≥ 0.5 medium · else low; neither given defaults to medium). Phrases resolve
-prop `labels` → the `confidence` locale slice → English — one phrase per level, so it translates
-cleanly. The human weights an AI proposal by it; pair with `ChangeReview`.
+Confidence IS a callout (`@lotics/ui/confidence`) — the ONLY form it takes: the three-tick
+meter + level phrase head the block, and the REQUIRED `children` carry the basis — what was
+checked and what came of it ("all 7 references pass their checksum" / "2 of 7 fail (X, Y) —
+verify against the source"). The box stays white with a hairline border at EVERY level — the
+meter is the only colored element (the level already lives in the meter and the phrase; a
+tinted fill would say it a third time). Pass `level` or a 0–1 `score` (≥0.8 high ·
+≥0.5 medium · else low; `levelFromScore` exported). There is NO standalone meter: a level
+without its reasons cannot be acted on, so it cannot be rendered — and where a compact meter
+used to decorate a ranked row or a proposal card, remove it (rank, badges, and severity
+already convey standing). Derive levels HONESTLY (deterministic checks: all pass → high, any
+fail → low) — never render a fabricated score.
 
 ## Findings — evidence, not writes
 
@@ -447,10 +465,9 @@ ranked set, don't cram it into chat prose:
   register's New CTA leads with AI: a `FileDropzone` hero → a short ANALYZE run reads the files →
   `ClarifyWizard` asks the ambiguities the analysis surfaced (its Cancel/Back/Next/Submit riding
   the `DialogFooter` via `ClarifyWizardScope` + `ClarifyWizardActions`) → the IMPORT run
-  **creates the records and the dialog ends on the RESULT LIST** — one result row per record
-  (what landed, the key figures — the hand-rolled anatomy in the one law above) — per the one
-  law's creation branch: no review gate, the register IS the review, correction is the
-  record's ordinary verbs. The manual VARIANTS sit below the dropzone
+  **creates the records and the dialog ends on the RECEIPT** — one record: summary + named
+  verdicts + the open-record action; several: an attention-first register pressing through
+  to the records (the one law's creation branch). The manual VARIANTS sit below the dropzone
   as `CardSelectItem`s, each opening the classic create-then-refine form. The template mocks the
   clarify step as TWO app-orchestrated phases (analyze-run → wizard → import-run); a real app
   can do it in ONE run — every app agent carries `ask_user_choice`, so the run PARKS on the

package/docs/catalog.md

@@ -1065,7 +1065,12 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `AgentProgress`'s expanded panel uses it. Inherits the inverted pattern's quirks (scrollbar
   thumb runs opposite; keyboard paging inverted) — same as chat. A full-page chat list is
   already inverted and doesn't need it.
-- **`confidence`** — `Confidence` + `ConfidenceLevel` + `levelFromScore`: calibrated
+- **`confidence`** — `Confidence` + `ConfidenceLevel` + `levelFromScore`: confidence IS a
+  callout — the meter + level phrase head the block, the REQUIRED `children` carry the basis
+  (what was checked, what failed); the box stays white with a hairline border at every
+  level — the meter is the only colored element. There is NO standalone meter — a level without its reasons cannot
+  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`
@@ -1101,6 +1106,16 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`finding`** — `Finding` + `FindingComparison` + `FindingSeverity`/`FindingLabels`: one
   ranked AI-check insight — severity word · title · detail · `Sources` · children slot; the
   expected-vs-actual body with the emphasized delta; the `finding` locale slice.
+- **`result_header`** — `ResultHeader` (+ `ResultTone`): the save-direct RECEIPT's outcome
+  strip, on the page grid — tone mark (`ok`/`attention`/`error`/`skipped`) inline on the
+  title row · outcome-first title · right-slot `action` (the open-record jump / a retry) ·
+  ONE line under (the honest `Confidence`, or the failure reason). The receipt composes:
+  header → the receipt lines (a `DetailTable` of spread `DetailRow`s — label left, value at
+  the right edge) → a `Confidence` callout naming the exact values that failed their
+  deterministic checks (or stating what passed). NOTHING in a
+  receipt edits — the RECORD is the edit surface, one press away. SEVERAL records → an
+  attention-first register of `ListItem` rows (tone mark · title · figures · needs-checking
+  count) pressing straight through to the records. See ai_patterns §the one law.
 - **`comments_thread`** — `CommentList` + the
   `ThreadComment`/`ThreadMember`/`ThreadFile` types: the record comments thread.
   Composing is THE kit `Composer` (never a bespoke comment box): attach via its

package/examples/tpl_item_list.tsx

@@ -55,6 +55,8 @@ import { Dialog, DialogFooter, DialogHeader, DialogHeaderTitle, DialogScrollArea
 import { AgentRun } from "@lotics/ui/agent_run";
 import { FollowScroll } from "@lotics/ui/follow_scroll";
 import { ClarifyWizard, ClarifyWizardActions, ClarifyWizardScope, type ClarifyWizardAnswer, type ClarifyWizardQuestion } from "@lotics/ui/clarify_wizard";
+import { ResultHeader } from "@lotics/ui/result_header";
+import { Confidence } from "@lotics/ui/confidence";
 import { CardSelectItem } from "@lotics/ui/card_select_item";
 import { FileDropzone } from "@lotics/ui/file_dropzone";
 import { FileDropTarget } from "@lotics/ui/file_drop_target";
@@ -1141,8 +1143,12 @@ function EnterDataDialog({ open, onOpenChange, seedDocs, onCreate, onCreateMany
   // on the created records (create + link, leave unlinked, or the user's own
   // instruction via the custom slot).
   const [customerPlan, setCustomerPlan] = useState("New customer created and linked");
-  // the result list — what the import CREATED, one entry per record
-  const [landed, setLanded] = useState<{ title: string; detail: string }[]>([]);
+  // the RECEIPT — what the import CREATED. A real app READS BACK what the
+  // save stored (values + record ids) and runs its DETERMINISTIC checks over
+  // the stored values (a reference checksum, a count reconciliation). ONE
+  // record renders its receipt directly; several render the attention-first
+  // register whose rows press straight through to the records.
+  const [landed, setLanded] = useState<{ id: string; title: string; detail: string; ref: string; refFlagged: boolean; fee: string }[]>([]);
   // form state (the manual gate)
   const [khach, setKhach] = useState("");
   const [dienThoai, setDienThoai] = useState("");
@@ -1182,13 +1188,20 @@ function EnterDataDialog({ open, onOpenChange, seedDocs, onCreate, onCreateMany
           setTimeout(() => {
             const proposals = grouping === "customer" ? PROPOSED_BY_CUSTOMER : PROPOSED_BY_ORDER;
             onCreateMany(proposals.map((p) => ({ khach: p.khach, dienThoai: p.dienThoai, phi: p.phi })));
-            setLanded(proposals.map((p) => ({
+            const rows = proposals.map((p) => ({
+              id: p.id,
               title: grouping === "customer" ? p.khach : `${p.orders} — ${p.khach}`,
               // The wizard's answers are load-bearing: the unknown customer's row
               // states how it landed (created + linked / left unassigned / the
               // user's own instruction).
-              detail: [p.orders, p.dienThoai, formatMoney(p.phi), p.khach === "Blue Harbor Foods" ? customerPlan : ""].filter(Boolean).join(" · "),
-            })));
+              detail: [p.dienThoai, formatMoney(p.phi), p.khach === "Blue Harbor Foods" ? customerPlan : ""].filter(Boolean).join(" · "),
+              ref: p.orders,
+              // The mock flags one record's reference (a failed checksum); a
+              // real app computes this over the STORED value.
+              refFlagged: p.khach === "Blue Harbor Foods",
+              fee: String(p.phi),
+            }));
+            setLanded(rows);
             setPhase("done");
           }, 500);
         }
@@ -1338,28 +1351,61 @@ function EnterDataDialog({ open, onOpenChange, seedDocs, onCreate, onCreateMany
         ) : null}
 
         {phase === "done" ? (
-          // The RESULT LIST — one row per created record: mark · what landed ·
-          // the key figures. The receipt, not a gate: correcting a record uses
-          // its ORDINARY verbs (open it in the register, edit or delete — the
-          // app's cascade delete keeps that safe), never a special undo here.
-          // The outcome-mark vocabulary (ai_patterns §the one law): success =
-          // circle-check green-600 · error = circle-alert red-600 · attention =
-          // circle-alert amber-600 · skipped = minus zinc-400. A real app adds
-          // an open-record jump / retry Button on the row's right.
+          // The RECEIPT (ai_patterns §the one law): states the outcome and
+          // routes — NOTHING here edits; the RECORD is the edit surface,
+          // one press away (correction uses the record's ordinary verbs).
+          // ONE record: header + the big-four summary + amber verdicts naming
+          // the exact failing values. SEVERAL: an attention-first register
+          // whose rows press straight through to the record.
           <DialogScrollArea>
-            <View style={{ gap: 12 }}>
-              {landed.map((l, i) => (
-                <View key={i} style={{ flexDirection: "row", alignItems: "flex-start", gap: 12 }}>
-                  <View style={{ paddingTop: 2 }}>
-                    <Icon name="circle-check" size={18} color={colors.green[600]} />
-                  </View>
-                  <View style={{ flex: 1, gap: 2 }}>
-                    <Text size="sm" weight="semibold">{`Created ${l.title}`}</Text>
-                    <Text size="xs" color="muted" numberOfLines={1}>{l.detail}</Text>
-                  </View>
+            {(() => {
+              // The receipt lines — DetailRow spread rows (label left, value
+              // right), the kit's paper-receipt look; a warning Callout names
+              // the failing values. Read-only: the record behind the dialog
+              // is the edit surface.
+              const receipt = (l: (typeof landed)[number]) => (
+                <View style={{ gap: 16 }}>
+                  <ResultHeader
+                    tone={l.refFlagged ? "attention" : "ok"}
+                    title={`Created ${l.title}`}
+                  />
+                  <DetailTable>
+                    <DetailRow label="Customer"><Text size="sm" weight="medium">{l.title}</Text></DetailRow>
+                    <DetailRow label="Orders"><Text size="sm" weight="medium">{l.ref}</Text></DetailRow>
+                    <DetailRow label="Service fee"><Text size="sm" weight="medium" tabular>{formatMoney(Number(l.fee) || 0)}</Text></DetailRow>
+                  </DetailTable>
+                  {l.refFlagged ? (
+                    <Confidence level="low">
+                      Order reference PO-7313 fails its checksum — verify against the source file; the flagged value is marked on the record.
+                    </Confidence>
+                  ) : (
+                    <Confidence level="high">
+                      All automated checks passed: the order references validate and the totals reconcile.
+                    </Confidence>
+                  )}
                 </View>
-              ))}
-            </View>
+              );
+              if (landed.length === 1) return receipt(landed[0]);
+              return (
+                <View style={{ gap: 2 }}>
+                  {[...landed].sort((a, b) => Number(b.refFlagged) - Number(a.refFlagged)).map((l) => (
+                    <ListItem
+                      key={l.id}
+                      left={<Icon name={l.refFlagged ? "circle-alert" : "circle-check"} size={18} color={l.refFlagged ? colors.amber[600] : colors.green[600]} />}
+                      title={`Created ${l.title}`}
+                      description={l.detail}
+                      right={
+                        <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
+                          {l.refFlagged ? <Text size="xs" weight="medium" style={{ color: colors.amber[600] }}>1 to check</Text> : null}
+                          <Icon name="chevron-right" size={16} color={colors.zinc[400]} />
+                        </View>
+                      }
+                      onPress={() => { close(); }}
+                    />
+                  ))}
+                </View>
+              );
+            })()}
           </DialogScrollArea>
         ) : null}
 

package/examples/tpl_lookup.tsx

@@ -229,8 +229,6 @@ export function TplLookup() {
                 <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
                   <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>
@@ -256,12 +254,19 @@ export function TplLookup() {
           <View style={{ gap: 4 }}>
             {/* verdict header — open, no card box: the panel IS the answer */}
             <View style={{ paddingVertical: 6, gap: 10 }}>
-              <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
-                <Text size="xs" color="muted" weight="medium" style={{ flex: 1 }}>Suggested HS code</Text>
-                <Confidence level={active.confidence} />
-              </View>
+              <Text size="xs" color="muted" weight="medium">Suggested HS code</Text>
               <Text size="xxxl" weight="semibold" tabular>{active.code}</Text>
               <Text size="sm" color="muted">{active.heading}</Text>
+              {/* Confidence IS a callout — the level with its basis, never a
+                  floating meter. Ranked rows carry no meter at all: the rank
+                  and the Recommended badge already convey standing. */}
+              <Confidence level={active.confidence}>
+                {active.confidence === "high"
+                  ? "The description matches the heading notes and both classification criteria."
+                  : active.confidence === "medium"
+                    ? "The material matches, but the heading notes leave the use-case ambiguous — check the criteria below."
+                    : "Only a partial match against the heading notes — treat as a starting point and verify the criteria."}
+              </Confidence>
             </View>
 
             <Divider />

package/examples/tpl_task_board.tsx

@@ -31,7 +31,7 @@ import { AgentRun } from "@lotics/ui/agent_run";
 import { Change, ChangeReview, ChangeReviewActions, ChangeReviewHeader, ChangeSummary, type ChangeStatus } from "@lotics/ui/change_review";
 import { Dialog, DialogHeader, DialogHeaderTitle, DialogScrollArea, DialogFooter } from "@lotics/ui/dialog";
 import { CompletionState } from "@lotics/ui/completion_state";
-import { Confidence, type ConfidenceLevel } from "@lotics/ui/confidence";
+import { type ConfidenceLevel } from "@lotics/ui/confidence";
 import { toISODate } from "@lotics/ui/format_date";
 import type { UIMessagePart, UIDataTypes, UITools } from "ai";
 
@@ -442,7 +442,6 @@ function TaskProposal({ proposal, onEdit }: { proposal: Proposal; onEdit: (id: s
         <View style={{ flex: 1 }}>
           <InlineTextInput variant="cell" value={proposal.title} onSave={(v) => onEdit(proposal.id, { title: v })} accessibilityLabel="Task title" />
         </View>
-        <View style={{ paddingTop: 10 }}><Confidence level={proposal.confidence} /></View>
       </View>
       <View style={{ width: 220 }}>
         <InlineDatePicker variant="cell" value={proposal.due} optionalTime onSave={(v) => onEdit(proposal.id, { due: v })} placeholder="No date" accessibilityLabel="Due date" />

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "15.2.0",
+  "version": "16.0.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -102,6 +102,7 @@
     "./finding": "./src/finding.tsx",
     "./clarify": "./src/clarify.tsx",
     "./clarify_wizard": "./src/clarify_wizard.tsx",
+    "./result_header": "./src/result_header.tsx",
     "./choice_list": "./src/choice_list.tsx",
     "./sources": "./src/sources.tsx",
     "./icon": "./src/icon.tsx",

package/src/confidence.tsx

@@ -1,3 +1,4 @@
+import type { ReactNode } from "react";
 import { StyleSheet, View } from "react-native";
 import { colors, solid, type ColorName } from "./colors";
 import { Text } from "./text";
@@ -6,59 +7,74 @@ import { useLoticsLocale } from "./locale";
 export type ConfidenceLevel = "high" | "medium" | "low";
 
 export interface ConfidenceLabels {
-  /** The full level phrase — shown beside the meter and read out. Default "High confidence" etc.,
-   *  so the meter reads as what it is, not a bare "High". One phrase per level (translates cleanly). */
+  /** The full level phrase — heads the callout and is read out. Default "High confidence" etc.,
+   *  so the block reads as what it is, not a bare "High". One phrase per level (translates cleanly). */
   high: string;
   medium: string;
   low: string;
 }
 
-export interface ConfidenceProps {
-  /** Pass a level directly, or a 0–1 `score` (≥0.8 high · ≥0.5 medium · else low). */
-  level?: ConfidenceLevel;
-  score?: number;
-  /** Translated level phrases. Defaults to English ("High confidence" …). */
-  labels?: Partial<ConfidenceLabels>;
-}
-
-const FILLED: Record<ConfidenceLevel, number> = { high: 3, medium: 2, low: 1 };
-// high emerald, medium amber, low zinc (unsure — not an error). One family per
-// level; the fill count AND the colour both carry it.
-const COLOR: Record<ConfidenceLevel, ColorName> = { high: "emerald", medium: "amber", low: "zinc" };
-
+/** A 0–1 score folded onto the three levels: >=0.8 high · >=0.5 medium · else low. */
 export function levelFromScore(score: number): ConfidenceLevel {
   if (score >= 0.8) return "high";
   if (score >= 0.5) return "medium";
   return "low";
 }
 
+const FILLED: Record<ConfidenceLevel, number> = { high: 3, medium: 2, low: 1 };
+const COLOR: Record<ConfidenceLevel, ColorName> = { high: "green", medium: "amber", low: "red" };
+
+export interface ConfidenceProps {
+  /** Pass a level directly, or a 0–1 `score` (>=0.8 high · >=0.5 medium · else low). */
+  level?: ConfidenceLevel;
+  score?: number;
+  labels?: Partial<ConfidenceLabels>;
+  /** The BASIS — what was checked and what came of it ("all 7 references pass
+   *  their checksum" / "2 of 7 fail (X, Y) — verify against the source").
+   *  REQUIRED: a confidence with no explanation is decoration. This component
+   *  IS a callout; there is no standalone meter. */
+  children: ReactNode;
+}
+
 /**
- * How sure the AI is — a calibrated high / medium / low read as a 3-tick meter
- * (emerald / amber / zinc) beside the level word. The fill count and the colour
- * both carry the level. The human weights an AI proposal or estimate by it. Pair
- * with `ChangeReview`.
+ * Confidence WITH its basis, as a callout-shaped block — the ONLY form
+ * confidence takes: the meter + level phrase head it, the explanation of what
+ * was checked (and what failed) fills it. The box stays WHITE with a hairline
+ * border at every level — the meter is the only colored element (the level
+ * already lives there and in the phrase; a tinted fill would say it a third
+ * time). Never a bare floating meter: a level without its reasons cannot be
+ * acted on, so it cannot be rendered.
  */
 export function Confidence(props: ConfidenceProps) {
-  const level = props.level ?? (props.score != null ? levelFromScore(props.score) : "medium");
+  const level: ConfidenceLevel = props.level ?? (props.score != null ? levelFromScore(props.score) : "medium");
   const l = { ...useLoticsLocale().confidence, ...props.labels };
   const filled = FILLED[level];
   const fill = solid(COLOR[level]);
   return (
-    <View style={styles.row} accessibilityLabel={l[level]}>
-      <View style={styles.meter}>
-        {[0, 1, 2].map((i) => (
-          <View key={i} style={[styles.tick, { backgroundColor: i < filled ? fill : colors.zinc[200] }]} />
-        ))}
+    <View style={styles.container}>
+      <View style={styles.head} accessibilityLabel={l[level]}>
+        <View style={styles.meter}>
+          {[0, 1, 2].map((i) => (
+            <View key={i} style={[styles.tick, { backgroundColor: i < filled ? fill : colors.zinc[200] }]} />
+          ))}
+        </View>
+        <Text size="sm" weight="medium">{l[level]}</Text>
       </View>
-      <Text size="xs" weight="medium" style={{ color: fill }}>
-        {l[level]}
-      </Text>
+      <Text size="sm">{props.children}</Text>
     </View>
   );
 }
 
 const styles = StyleSheet.create({
-  row: { flexDirection: "row", alignItems: "center", gap: 6 },
-  meter: { flexDirection: "row", alignItems: "center", gap: 2 },
+  container: {
+    padding: 12,
+    borderRadius: 10,
+    borderWidth: 1,
+    borderColor: colors.border,
+    backgroundColor: colors.background,
+    gap: 4,
+  },
+  head: { flexDirection: "row", alignItems: "center", gap: 8 },
+  meter: { flexDirection: "row", gap: 2, alignItems: "flex-end" },
   tick: { width: 3, height: 10, borderRadius: 1 },
 });

package/src/result_header.tsx

@@ -0,0 +1,79 @@
+import type { ReactNode } from "react";
+import { StyleSheet, View } from "react-native";
+import { colors, solid } from "./colors";
+import { Icon, type IconName } from "./icon";
+import { Text, type HeadingLevel } from "./text";
+
+/**
+ * Result header — the strip that opens the POST-SAVE RECEIPT. `ChangeReview` gates a proposal
+ * BEFORE it applies; this header opens the receipt for what a save-direct run
+ * ALREADY CREATED. The receipt states the outcome and routes — it never edits
+ * (correction happens through the record's ordinary verbs, on the record):
+ *
+ * - ONE record → `ResultHeader` (tone mark inline on the title row · outcome
+ *   title · failure reason line) + a handful of spread `DetailRow` receipt
+ *   lines (the identifying figures, not the field wall) + a `Confidence`
+ *   callout naming exactly which values failed their deterministic checks.
+ * - SEVERAL records → an attention-first `ListItem` register whose rows press
+ *   straight through to the records. Never tabs (they cap out), never stacked
+ *   collapsed cards, never a field wall duplicating the record page.
+ *
+ * A flagged value carries a DETERMINISTIC verdict the host computed (a failed
+ * checksum, a count that disagrees) — never a fabricated score.
+ */
+
+export type ResultTone = "ok" | "attention" | "error" | "skipped";
+
+const TONE: Record<ResultTone, { icon: IconName; color: string }> = {
+  ok: { icon: "circle-check", color: solid("green") },
+  attention: { icon: "circle-alert", color: solid("amber") },
+  error: { icon: "circle-alert", color: solid("red") },
+  skipped: { icon: "minus", color: colors.zinc[400] },
+};
+
+export interface ResultHeaderProps {
+  /** `attention` when any value is flagged (or the item needs the user
+   *  elsewhere); `error` when the save failed; `skipped` for an item
+   *  deliberately not processed. The host computes it — it knows its flags. */
+  tone: ResultTone;
+  /** Outcome-first: "Created <ref>", "Updated <ref>", "Could not save". */
+  title: string;
+  /** The failure reason (error/skip rows), one line under the title. The
+   *  record's FIGURES never live here (they belong in the receipt lines), and
+   *  neither does confidence — that is `Confidence`'s job (a callout, WITH its
+   *  basis), further down the receipt. */
+  detail?: string;
+  /** Right-slot action (an open-record jump, a retry) — a `Button`. */
+  action?: ReactNode;
+  /** Heading rank for the outcome title (screen readers jump by heading).
+   *  Defaults to 2 — the receipt heads its surface, like `SectionHeadingTitle`. */
+  level?: HeadingLevel;
+}
+
+/** The record's outcome strip — the tone mark rides INLINE on the title row
+ *  (everything sits on the page grid; no hanging gutter), with ONE meaningful
+ *  line under it (the honest confidence, or the failure reason) and the action
+ *  pinned right. Sections of the review (`DetailTable` fields, `Table` rows)
+ *  follow at the same left edge. */
+export function ResultHeader(props: ResultHeaderProps) {
+  const { tone, title, detail, action, level = 2 } = props;
+  const t = TONE[tone];
+  return (
+    <View style={styles.header}>
+      <View style={styles.headerTitleRow}>
+        <Icon name={t.icon} size={20} color={t.color} />
+        <Text level={level} size="md" weight="semibold" style={styles.headerTitle}>{title}</Text>
+        {action}
+      </View>
+      {detail ? (
+        <Text size="sm" color={tone === "error" ? "danger" : "muted"}>{detail}</Text>
+      ) : null}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  header: { gap: 6 },
+  headerTitleRow: { flexDirection: "row", alignItems: "center", gap: 10 },
+  headerTitle: { flex: 1, minWidth: 0 },
+});