@lotics/ui 15.2.1 → 16.1.0

package/AGENTS.md

@@ -15,8 +15,8 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 | Doc | Read it for |
 |---|---|
 | [docs/catalog.md](./docs/catalog.md) | **The complete inventory** — Reach-by-role (each data role → the ONE canonical component) + every `@lotics/ui/<module>` entry point (incl. `@lotics/ui/vite`'s `loticsOptimizeDeps` for a custom-code app's `vite.config.ts`). Read before building any screen; reuse first. |
-| [docs/data_entry.md](./docs/data_entry.md) | Which editing pattern for which job — inline edit, fieldset forms, find-or-create (`Combobox`), line items, handoffs, phased records, billing, tags, dispositions, attachments (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/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, 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). |
 | [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,21 +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`. A batch-level failure lands on
-  EVERY row as its reason — never ALSO paint it as a banner above the list (a top `Callout`
-  is only for information the rows don't carry). 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.
@@ -44,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
@@ -371,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
 
@@ -449,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

@@ -611,7 +611,10 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `controls="buttons"`; KEYBOARD focus on the closed view opens edit mode with the input
   focused (type → Tab → type — see the data-entry keyboard contract), pointer focus never
   does; **`variant: "form" | "cell"`** is THE axis that separates a form field from a data-grid
-  cell (see below).
+  cell (see below). Every commit registers in **`pending_commits`**, which
+  `Button`/`IconButton` wait on via **`use_gated_press`** so an action pressed in the same
+  gesture as the blur cannot read the record before the edit lands (data_entry.md § Inline
+  edit) — automatic, nothing to pass.
 - **`inline_text_input`**, **`inline_number_input`** (`format` for currency/units),
   **`inline_select`**, **`inline_member_select`**, **`inline_date_picker`**
   (`format="datetime"`, `optionalTime`; keyboard focus opens the TYPED segmented `DateField`
@@ -1065,7 +1068,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 +1109,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/docs/data_entry.md

@@ -49,6 +49,31 @@ chip, hover reveals the input-family border (no extra grey wash, no pencil icon
 layout), click OR keyboard focus swaps the input in **at the same height** (zero reflow, the whole
 point), and it commits on blur (Enter saves, Escape reverts) or via `controls="buttons"` (✓ / ✕).
 
+**Commit-on-blur would race the press that caused it — the kit closes that race for you.**
+Pressing an action while an inline field is focused starts TWO things in ONE gesture: the
+field's write (the blur, on mousedown) and the button's handler (on mouseup). A handler that
+RE-READS the record — to print a document, mint an invoice, copy the row into a new one — would
+overtake the still-in-flight write and act on the PRE-EDIT value, silently: the new value on
+screen, the old one in the output. So **`useInlineEdit` registers every commit and
+`Button`/`IconButton` hold their press until the commits already in flight have settled**
+(`pending_commits.ts`), showing their busy spinner while they wait. Nothing to wire up: with no
+commit pending the press dispatches synchronously exactly as before, and a FAILED commit
+releases the gate too (the field surfaces its own error). A commit started after the press was
+taken is deliberately not waited for — the gate holds a press for the edit that caused it, never
+for later work.
+
+**What the gate cannot see — an action must take an ID, not a captured object.** Holding the
+press makes the STORE current; it cannot refresh a value the handler already closed over.
+`onPress={() => onIssue(invoice)}` captures the invoice as it was at press time, so the
+confirm dialog quotes — and the mint bills — the pre-edit total no matter how long the gate
+waits. Pass the KEY and resolve the object where it is used
+(`onPress={() => onIssue(invoice.key)}`, then `invoices.find(…)` at render): worked in
+`tpl_record`'s Billing band, whose charge cells are inline editors and whose Issue is
+irreversible. The same rule kills the variant with no race at all — a handler reading a server
+row the screen copied into `useState` (`app-sdk` `docs/mutations.md` § A read must not overtake
+an in-flight write) — as does a write started by something other than an inline commit (a
+dialog save, a debounced autosave).
+
 ### Keyboard entry — type → Tab → type
 
 Bulk entry never needs the mouse. KEYBOARD focus (Tab / Shift+Tab) landing on a closed

package/docs/templates.md

@@ -329,7 +329,10 @@ billing, and quick-capture templates. Top → bottom:
   scope, once — a band-local problem (charged line missing its method) in the band, a broken
   record premise (no customer / invalid tax ID) at the section top; self-evident empties
   stay silent, and NEVER prose beside a CTA. Issuing gates on record premises only — never
-  silently on stage.
+  silently on stage. It is also the worked example of **an irreversible action taking an ID,
+  not a captured object**: `onIssue(inv.key)` with the invoice resolved where the confirm
+  renders, so the quoted total is the one that will be billed even when the press was held
+  for a charge cell's write (data_entry.md § Inline edit).
 - **Document set — the OUTPUT desk, the last WORK section** (the composition rules' output
   law worked on the record surface: the top is intake, the bottom produces on demand).
   Forms group PER PARTY on the `SubsectionStack` beat — each party a `SubsectionHeading` +

package/examples/tpl_item_list.tsx

@@ -2,7 +2,7 @@ import { useEffect, useState, useRef } from "react";
 import { ScrollView, View } from "react-native";
 import type { UIMessagePart, UIDataTypes, UITools } from "ai";
 import { Text } from "@lotics/ui/text";
-import { colors, type ColorName } from "@lotics/ui/colors";
+import { colors, solid, type ColorName } from "@lotics/ui/colors";
 import { ActionMenu, type ActionMenuItem } from "@lotics/ui/action_menu";
 import { Alert } from "@lotics/ui/alert";
 import { Badge } from "@lotics/ui/badge";
@@ -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 ? solid("amber") : solid("green")} />}
+                      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: solid("amber") }}>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_record.tsx

@@ -345,7 +345,10 @@ function InvoiceBand({
   gated: boolean;
   onAmount: (chKey: string, v: number) => Promise<void>;
   onMethod: (chKey: string, m: Method) => Promise<void>;
-  onIssue: (inv: Invoice) => void;
+  /** Takes the invoice's KEY, never the `inv` object: the press may be held while
+   *  a charge cell finishes writing (Button waits out an inline commit), and a
+   *  captured object would still be the pre-edit snapshot. Resolve at use. */
+  onIssue: (invKey: string) => void;
 }) {
   const total = invoiceTotal(inv);
   const state = invoiceStatus(inv);
@@ -410,10 +413,10 @@ function InvoiceBand({
         {state === "issued" ? (
           <>
             <Link size="xs" onPress={() => {}} accessibilityLabel={`Open invoice ${inv.ref}`}>{inv.ref}</Link>
-            <Button title="Re-issue" color="secondary" disabled={!ready} onPress={() => onIssue(inv)} />
+            <Button title="Re-issue" color="secondary" disabled={!ready} onPress={() => onIssue(inv.key)} />
           </>
         ) : (
-          <Button title="Issue invoice" color="primary" disabled={!ready} onPress={() => onIssue(inv)} />
+          <Button title="Issue invoice" color="primary" disabled={!ready} onPress={() => onIssue(inv.key)} />
         )}
       </View>
     </Subsection>
@@ -832,7 +835,9 @@ export function TplRecord() {
   // ── billing — the bill-to tax ID comes off the CUSTOMER
   const [invoices, setInvoices] = useState<Invoice[]>(BILLING_INITIAL);
   const [deposit, setDeposit] = useState(0);
-  const [confirmIssue, setConfirmIssue] = useState<Invoice | null>(null);
+  // The key, not the invoice: what the dialog shows and issues is derived below, so a
+  // charge that landed between the press and the confirm is reflected, never a stale total.
+  const [confirmIssueKey, setConfirmIssueKey] = useState<string | null>(null);
   const seq = useRef(414);
   const taxId = customer?.taxId ?? "";
   const taxIdValid = TAX_ID_RE.test(taxId);
@@ -1238,6 +1243,9 @@ export function TplRecord() {
       }, 350);
     });
 
+  // Resolved from the CURRENT invoices every render — the confirm dialog quotes the
+  // total that will actually be billed, including a charge that landed after the press.
+  const confirmIssue = invoices.find((i) => i.key === confirmIssueKey) ?? null;
   const grandTotal = invoices.reduce((sum, inv) => sum + invoiceTotal(inv), 0);
   const allMissing = invoices.flatMap(missingMethods);
   const issuedCount = invoices.filter((i) => invoiceStatus(i) === "issued").length;
@@ -1246,7 +1254,7 @@ export function TplRecord() {
     seq.current += 1;
     const ref = `INV-2026-${String(seq.current).padStart(4, "0")}`;
     setInvoices((prev) => prev.map((x) => (x.key === inv.key ? { ...x, ref } : x)));
-    setConfirmIssue(null);
+    setConfirmIssueKey(null);
     logActivity("credit-card", `Invoice ${ref} issued — ${inv.title}`, { description: formatMoney(invoiceTotal(inv)) });
   };
 
@@ -2124,7 +2132,7 @@ export function TplRecord() {
               gated={customer === null || !taxIdValid}
               onAmount={(chKey, v) => saveCharge(inv.key, chKey, { amount: v })}
               onMethod={(chKey, m) => saveCharge(inv.key, chKey, { method: m })}
-              onIssue={setConfirmIssue}
+              onIssue={setConfirmIssueKey}
             />
           ))}
 
@@ -2585,7 +2593,7 @@ export function TplRecord() {
       </Dialog>
 
       {/* issuing an e-invoice is irreversible — confirm in a Dialog (stage gate) */}
-      <Dialog width={460} open={confirmIssue !== null} onOpenChange={(o) => { if (!o) setConfirmIssue(null); }}>
+      <Dialog width={460} open={confirmIssue !== null} onOpenChange={(o) => { if (!o) setConfirmIssueKey(null); }}>
         <DialogHeader>
           <DialogHeaderTitle>{confirmIssue?.ref ? "Re-issue invoice?" : "Issue e-invoice?"}</DialogHeaderTitle>
         </DialogHeader>
@@ -2601,7 +2609,7 @@ export function TplRecord() {
           </Callout>
         </View>
         <DialogFooter>
-          <Button title="Cancel" color="secondary" onPress={() => setConfirmIssue(null)} />
+          <Button title="Cancel" color="secondary" onPress={() => setConfirmIssueKey(null)} />
           <Button title="Issue" color="primary" onPress={() => confirmIssue && issue(confirmIssue)} />
         </DialogFooter>
       </Dialog>

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.1",
+  "version": "16.1.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",
@@ -123,6 +124,7 @@
     "./menu_button": "./src/menu_button.tsx",
     "./menu_list_item": "./src/menu_list_item.tsx",
     "./pressable_highlight": "./src/pressable_highlight.tsx",
+    "./pending_commits": "./src/pending_commits.ts",
     "./pressable_row": "./src/pressable_row.tsx",
     "./press_door": "./src/press_door.tsx",
     "./floating_action_bar": "./src/floating_action_bar.tsx",
@@ -150,6 +152,7 @@
     "./use_screen_size": "./src/use_screen_size.ts",
     "./use_auto_grow_height": "./src/use_auto_grow_height.ts",
     "./use_focus_ring": "./src/use_focus_ring.ts",
+    "./use_gated_press": "./src/use_gated_press.ts",
     "./interaction_modality": "./src/interaction_modality.ts",
     "./inline_focus": "./src/inline_focus.ts",
     "./use_hover": "./src/use_hover.ts",

package/src/button.tsx

@@ -12,11 +12,12 @@ import { Text } from "./text";
 import { colors } from "./colors";
 import { CONTROL_RADIUS, FOCUS_RING } from "./control_surface";
 import { Icon, IconName } from "./icon";
-import { Ref, useCallback } from "react";
+import { Ref } from "react";
 import { TextColor } from "./text_utils";
 import { useTooltip, UseTooltipOptions } from "./tooltip";
 import { useFocusRing, composeHandler } from "./use_focus_ring";
 import { getButtonIconColor } from "./button_colors";
+import { useGatedPress } from "./use_gated_press";
 export type ButtonColor = "primary" | "secondary" | "danger" | "muted" | "danger-secondary";
 export type ButtonIconPosition = "left" | "right";
 
@@ -60,20 +61,18 @@ export function Button(props: ButtonProps) {
     accessibilityLabel,
   } = props;
 
-  const disabledOrLoading = disabled || loading;
+  // The press waits out an inline commit the same gesture started (pending_commits.ts)
+  // and reports busy while it does — so `busy`, not the `loading` prop alone, drives the
+  // spinner, aria-busy, and the double-press block.
+  const { handlePress, waiting } = useGatedPress<NativeSyntheticEvent<any>>(onPress);
+  const busy = loading || waiting;
+  const disabledOrLoading = disabled || busy;
   const tooltipProps = useTooltip(tooltip);
   const { focusVisible, focusProps } = useFocusRing();
 
-  const handlePress = useCallback(
-    (event: NativeSyntheticEvent<any>) => {
-      onPress?.(event);
-    },
-    [onPress],
-  );
-
   const children = (
     <>
-      {loading ? (
+      {busy ? (
         <ActivityIndicator color={getButtonIconColor(color)} />
       ) : (
         <>
@@ -107,7 +106,7 @@ export function Button(props: ButtonProps) {
         (typeof tooltip === "string" ? tooltip : tooltip?.text) ||
         undefined
       }
-      aria-disabled={disabledOrLoading || undefined} aria-busy={loading || undefined}
+      aria-disabled={disabledOrLoading || undefined} aria-busy={busy || undefined}
       disabled={disabledOrLoading}
       style={({ pressed, hovered }: PressableStateCallbackType & { hovered?: boolean }) => {
         const isPrimary = color === "primary" && !disabled;

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/icon_button.tsx

@@ -4,8 +4,9 @@ import { colors } from "./colors";
 import { PressableHighlight } from "./pressable_highlight";
 import { type ButtonColor } from "./button";
 import { getButtonIconColor } from "./button_colors";
-import { Ref, useCallback } from "react";
+import { Ref } from "react";
 import { TooltipSide } from "./tooltip";
+import { useGatedPress } from "./use_gated_press";
 
 interface IconButtonBase {
   ref?: Ref<View>;
@@ -61,14 +62,12 @@ export function IconButton(props: IconButtonProps) {
     style,
   } = props;
 
-  const handlePress = useCallback(
-    (event: GestureResponderEvent) => {
-      onPress?.(event);
-    },
-    [onPress],
-  );
+  // The press waits out an inline commit the same gesture started (pending_commits.ts)
+  // and reports busy while it does — `busy` drives the spinner + the double-press block.
+  const { handlePress, waiting } = useGatedPress<GestureResponderEvent>(onPress);
+  const busy = loading || waiting;
 
-  const disabledOrLoading = disabled || loading;
+  const disabledOrLoading = disabled || busy;
   const tint =
     iconColor ??
     (color === "none" ? colors.zinc[700] : color === "white" ? colors.white : getButtonIconColor(color));
@@ -88,7 +87,7 @@ export function IconButton(props: IconButtonProps) {
       // without shifting surrounding layouts.
       hitSlop={size === "lg" ? 0 : size === "sm" ? 8 : 6}
     >
-      {loading ? (
+      {busy ? (
         <ActivityIndicator size="small" color={tint} />
       ) : (
         <Icon size={size === "sm" ? 14 : size === "lg" ? 20 : 18} name={icon} color={tint} />

package/src/inline_edit.tsx

@@ -10,6 +10,7 @@ import { FOCUS_RING, CONTROL_RADIUS, HOVER_BORDER, CONTROL_TRANSITION } from "./
 import { fontFamilyRegular, getInputTextStyle, getTextColor, type TextColor } from "./text_utils";
 import { getInteractionModality } from "./interaction_modality";
 import { shouldOpenOnFocus, shouldRestoreFocusOnClose } from "./inline_focus";
+import { trackCommit } from "./pending_commits";
 
 /** The kit's standard control height (TextInputField, NumberInput, Picker, …).
  *  The view box matches it — same height, padding, and a 1px transparent border
@@ -69,7 +70,11 @@ export function useInlineEdit<T>(opts: {
       setSaving(true);
       setError(null);
       try {
-        await onSave(candidate);
+        // Registered so an action pressed in the SAME gesture (the press that caused
+        // this blur) waits for the write instead of reading the pre-edit record —
+        // see pending_commits.ts. The IIFE starts `onSave` synchronously, so the
+        // write still leaves on mousedown, and turns a sync throw into a rejection.
+        await trackCommit((async () => onSave(candidate))());
         setEditing(false);
       } catch (e) {
         // Stay in edit mode so the entry isn't lost — show the error, re-arm.

package/src/pending_commits.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from "vitest";
+import { pendingCommits, trackCommit } from "./pending_commits";
+
+/** A field write that lands in `stored` after `ms`, like a save round trip. */
+const commit = (stored: { value: string }, next: string, ms: number) =>
+  new Promise<void>((resolve) =>
+    setTimeout(() => {
+      stored.value = next;
+      resolve();
+    }, ms),
+  );
+
+/** Let the registry's own settle callback run before asserting on it. */
+const tick = () => new Promise<void>((resolve) => setTimeout(resolve, 0));
+
+describe("pendingCommits", () => {
+  it("is null with nothing in flight — a press keeps its synchronous path", () => {
+    expect(pendingCommits()).toBeNull();
+  });
+
+  it("holds until a commit still in flight has landed", async () => {
+    const stored = { value: "BKG CŨ: " };
+    void trackCommit(commit(stored, "BKG CŨ:  SGNA52926200", 20));
+    const gate = pendingCommits();
+    expect(gate).not.toBeNull();
+    await gate;
+    expect(stored.value).toBe("BKG CŨ:  SGNA52926200");
+  });
+
+  it("holds for EVERY commit in flight, not just the first", async () => {
+    const landed: string[] = [];
+    const land = (name: string, ms: number) =>
+      new Promise<void>((resolve) =>
+        setTimeout(() => {
+          landed.push(name);
+          resolve();
+        }, ms),
+      );
+    void trackCommit(land("slow", 30));
+    void trackCommit(land("fast", 5));
+    await pendingCommits();
+    expect([...landed].sort()).toEqual(["fast", "slow"]);
+  });
+
+  it("releases again once the commits have landed", async () => {
+    await trackCommit(Promise.resolve());
+    await tick();
+    expect(pendingCommits()).toBeNull();
+  });
+
+  it("is released by a FAILED commit too — a stuck gate would wedge every action", async () => {
+    const failed = trackCommit(Promise.reject(new Error("Save failed")));
+    // The caller owns the error: the inline editor keeps the edit and shows it.
+    await expect(failed).rejects.toThrow("Save failed");
+    await expect(pendingCommits() ?? Promise.resolve()).resolves.toBeUndefined();
+    await tick();
+    expect(pendingCommits()).toBeNull();
+  });
+
+  it("ignores a commit started AFTER the gate was taken — it holds the press for the edit that caused it, not later work", async () => {
+    const stored = { value: "before" };
+    void trackCommit(commit(stored, "first", 5));
+    const gate = pendingCommits();
+    void trackCommit(commit(stored, "later", 40));
+    await gate;
+    expect(stored.value).toBe("first");
+  });
+});

package/src/pending_commits.ts

@@ -0,0 +1,45 @@
+/**
+ * Inline commits that are still writing, app-wide.
+ *
+ * An inline editor commits on BLUR, so pressing an action while a field is focused
+ * starts TWO things in ONE gesture: the field's write (the blur, on mousedown) and
+ * the action's handler (on mouseup). A handler that re-reads the record — to print a
+ * document, mint an invoice, copy the row — otherwise overtakes the still-in-flight
+ * write and acts on the PRE-EDIT value. It fails silently: the screen shows the new
+ * value and the output carries the old one.
+ *
+ * `useInlineEdit` registers every commit here and `Button`/`IconButton` hold their
+ * press for the ones already in flight, so the press lands AFTER the edit that caused
+ * it. There is nothing for an app to wire up, and nothing it can forget.
+ */
+
+const inFlight = new Set<Promise<void>>();
+
+/**
+ * Register a commit. Returns it UNCHANGED — the caller keeps its own result and error
+ * handling; the gate only needs to know when the write SETTLED, so a failed commit
+ * releases it just like a successful one (the field surfaces its own error).
+ */
+export function trackCommit<T>(commit: Promise<T>): Promise<T> {
+  const settled = commit.then(
+    () => undefined,
+    () => undefined,
+  );
+  inFlight.add(settled);
+  void settled.then(() => {
+    inFlight.delete(settled);
+  });
+  return commit;
+}
+
+/**
+ * The commits in flight RIGHT NOW, or `null` when there are none — a caller takes its
+ * synchronous path on `null`, so a press with nothing pending behaves exactly as it
+ * always did. Commits started after this call are deliberately NOT awaited: the gate
+ * holds a press for the edit that caused it, never for later work.
+ */
+export function pendingCommits(): Promise<void> | null {
+  if (inFlight.size === 0) return null;
+  const snapshot = Array.from(inFlight);
+  return Promise.all(snapshot).then(() => undefined);
+}

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 },
+});

package/src/use_gated_press.ts

@@ -0,0 +1,41 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { pendingCommits } from "./pending_commits";
+
+/**
+ * Makes an action's press land AFTER any inline commit the same gesture started —
+ * see {@link pendingCommits} for the race it closes.
+ *
+ * With nothing in flight the press dispatches SYNCHRONOUSLY, exactly as before, so the
+ * gate is invisible outside the racing case. While waiting the action reports busy, so
+ * the gesture reads as "working" rather than "ignored" and cannot double-fire.
+ */
+export function useGatedPress<E>(onPress?: (event: E) => void) {
+  const [waiting, setWaiting] = useState(false);
+  // Re-armed on mount: a StrictMode remount must not leave the ref stuck at false.
+  const mounted = useRef(true);
+  useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+    };
+  }, []);
+
+  const handlePress = useCallback(
+    (event: E) => {
+      const pending = pendingCommits();
+      if (!pending) {
+        onPress?.(event);
+        return;
+      }
+      setWaiting(true);
+      void pending.then(() => {
+        if (!mounted.current) return;
+        setWaiting(false);
+        onPress?.(event);
+      });
+    },
+    [onPress],
+  );
+
+  return { handlePress, waiting };
+}