@lotics/ui 44.8.0 → 44.9.0

package/AGENTS.md

@@ -16,8 +16,8 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 |---|---|
 | [docs/catalog.md](./docs/catalog.md) | **The complete inventory** — Reach-by-role (each data role → the ONE canonical component) + every `@lotics/ui/<module>` entry point (incl. `@lotics/ui/vite`'s `loticsOptimizeDeps` + `loticsResolve()` — the pre-bundle list and the whole `resolve` block a custom-code app's `vite.config.ts` imports rather than hand-carries, dev-link included). Read before building any screen; reuse first. |
 | [docs/data_entry.md](./docs/data_entry.md) | **a picker over a select field keeps the field's colours** (`optionPicker` — the hand-rolled `map` to `{value,label}` drops `color`, so a value reads coloured in a register and grey in the editor); Which editing pattern for which job — inline edit, fieldset forms, browser-autofill suppression (search controls only), find-or-create (`Combobox`), line items, handoffs, phased records, billing, tags, dispositions, attachments (`InlineFiles` for a record ROW — list + one CTA, `multiple` decides add-vs-replace; the `FilesEditor` COMPOUND for a whole section — root owns selection/gallery/confirm, you compose the bar, a HOST verb reads `useFilesEditorSelection` — plus the three-way file INTAKE: CTA + `FileDropTarget` + `usePasteFiles`), stage gates, whether a multiline value keeps its fixed reserve or `autoGrow`s (who decides the length — the field, or whoever is typing), the commit-on-blur vs action-press ordering law (the kit gates the press — `pending_commits`). |
-| [docs/ai_patterns.md](./docs/ai_patterns.md) | AI acts, the human stays in charge — composer, live run feed (`AgentRun`), the one law's split — it turns on WHO supplied the values (machine → a gate: a diff when something is being replaced, a full editable preview when records are being created from a document; human-typed → save-direct + the `ResultHeader` receipt), findings, provenance, confidence; **after the run** — a stored record that fills up from several writers (a person, a chat agent, an extraction, an automation) and remembers none of them: an unwritten value must not render like a written one, a machine's prose and a person's must not share a treatment, model markdown goes in `variant="embedded"`, and the read path must project every field the write paths set; the UI half of the SDK's [ai doc](../app-sdk/docs/ai.md), the whole run in a dialog (`AgentRunScope`/`AgentRunPane`/`AgentRunActions` — a parked question REPLACES the feed, actions in the footer, **Stop** while streaming), **stopping** (`cancel` stops the run, `abort` only stops listening — so closing a dialog must `cancel` or it keeps billing); **review surfaces compose from atoms** — `DiffValue` (a changed value, droppable in any cell/row/total), `DiffMark` (what happened to the row — ONE circular disc, every surface), `useChangeSet` (accept/reject/undo bookkeeping, no layout) — see [MIGRATION.md](./MIGRATION.md) for the `ChangeReview` family they replace |
-| [docs/composition.md](./docs/composition.md) | The design-language contract — **the form comes before the treatment** (name what the subject IS — register, rail, board, timeline, deviation queue — before reaching for parts; a subject flattened into rows is well-typed and says nothing, and reuse-first is about not duplicating primitives, not about a screen's shape), canvas + content column, heading altitude (incl. eyebrow vs group lead — a label is one or the other), banded cards, register vs inset rows (incl. the register laws a row centres its cells by: every cell a FIXED height, a pressable cell on the shared hover token, a column sized by what it carries), the button ladder and **what underlined text may mean** (it GOES somewhere or REVEALS something — never mutates; blue leaves the surface, muted stays on it, and the one in-prose disclosure exception is scoped there), master-detail `Drawer` on a LIST screen vs a child collection's row EXPANDING inside a record, view controls, RECORD EXTENT (one page, sections scrolled to and never routed to), **the register's rhythm** (no hairline between rows — their own height and the hover wash separate them; the register's one line is the band capping the columns, because that is the break whitespace cannot state. Density is `TableRow`'s `minHeight`, never a mode), **a register that TRIAGES** (`TableGroup` — titled bands ordered by what needs the reader now, grouped by what implies a different ACTION rather than by a category already in a column), **the register's own craft** (a column header treated as CHROME a step lighter than row metadata, sentence case in the table header too, and a supporting line one RUNG BELOW the line it supports rather than a fixed size — plus the half that rule was missing: every SUBJECT on one row starts at the same rung, the subject leads by WEIGHT and its identity mark rather than by size, and whether the supporting line drops a rung is decided by what else separates the pair), **identity marks** (a mark that looks the same on every row carries nothing — `Avatar` derives its hue from the name and takes circle/square for person vs organization; the palette is ordered by contrast, not spectrum, and never paints a person red or amber), **where the accent goes** ("which of these" — a selected row, an active filter; never DATA and never the focus ring, while a page-scale position marker like an active TAB takes `primary`, the ink the kit already spends on "this is on"; and selection must not share a wash with hover), **theming is an app-level ESCAPE HATCH, not a product surface** (`applyLoticsTheme({ … })` once at boot, before `mount`, writing the `--lotics-*` roles on the document root; nothing in the platform writes a theme, and `apps.theme.color` is the launcher icon only — the five `var()` roles plus the three font rungs ARE the whole mechanism, and wrapping a component cannot replace them because RN-Web writes `fontFamily` per element and background/border do not inherit), color discipline, **typography** (the ramp is DATA in `type_ramp`, one table both platforms derive from; leading and tracking are baked per rung and a hand-set `letterSpacing` is always a second copy of the curve), whitespace, and how to TEST an overlay component (a `Popover`-backed surface never mounts under jsdom). |
+| [docs/ai_patterns.md](./docs/ai_patterns.md) | AI acts, the human stays in charge — composer, live run feed (`AgentRun`), the one law's split — it turns on WHO supplied the values (machine → a gate: a diff when something is being replaced, a full editable preview when records are being created from a document; human-typed → save-direct + the `ResultHeader` receipt), findings, provenance, confidence; **after the run** — a stored record that fills up from several writers (a person, a chat agent, an extraction, an automation) and remembers none of them: an unwritten value must not render like a written one, a machine's prose and a person's must not share a treatment, model markdown goes in `variant="embedded"`, and the read path must project every field the write paths set; the UI half of the SDK's [ai doc](../app-sdk/docs/ai.md), the whole run in a dialog (`AgentRunScope`/`AgentRunPane`/`AgentRunActions` — a parked question REPLACES the feed, actions in the footer, **Stop** while streaming), **stopping** (`cancel` stops the run, `abort` only stops listening — so closing a dialog must `cancel` or it keeps billing); **review surfaces compose from atoms** — `DiffValue` (a changed value, droppable in any cell/row/total), `DiffMark` (what happened to the row — ONE circular disc, every surface, its kind derived from before/after rather than a boolean "did this change" — an empty `before` is `added`, never `changed`), `useChangeSet` (accept/reject/undo bookkeeping, no layout) — see [MIGRATION.md](./MIGRATION.md) for the `ChangeReview` family they replace |
+| [docs/composition.md](./docs/composition.md) | The design-language contract — **the form comes before the treatment** (name what the subject IS — register, rail, board, timeline, deviation queue — before reaching for parts; a subject flattened into rows is well-typed and says nothing, and reuse-first is about not duplicating primitives, not about a screen's shape), canvas + content column, heading altitude (incl. eyebrow vs group lead — a label is one or the other, and a section heading's own row never wraps so a control label that repeats the title can squeeze the title+description into a narrow ribbon at phone width), banded cards, register vs inset rows (incl. the register laws a row centres its cells by: every cell a FIXED height, a pressable cell on the shared hover token, a column sized by what it carries), the button ladder and **what underlined text may mean** (it GOES somewhere or REVEALS something — never mutates; blue leaves the surface, muted stays on it, and the one in-prose disclosure exception is scoped there), master-detail `Drawer` on a LIST screen vs a child collection's row EXPANDING inside a record, view controls, RECORD EXTENT (one page, sections scrolled to and never routed to), **the register's rhythm** (no hairline between rows — their own height and the hover wash separate them; the register's one line is the band capping the columns, because that is the break whitespace cannot state. Density is `TableRow`'s `minHeight`, never a mode), **a register that TRIAGES** (`TableGroup` — titled bands ordered by what needs the reader now, grouped by what implies a different ACTION rather than by a category already in a column), **the register's own craft** (a column header treated as CHROME a step lighter than row metadata, sentence case in the table header too, and a supporting line one RUNG BELOW the line it supports rather than a fixed size — plus the half that rule was missing: every SUBJECT on one row starts at the same rung, the subject leads by WEIGHT and its identity mark rather than by size, and whether the supporting line drops a rung is decided by what else separates the pair), **identity marks** (a mark that looks the same on every row carries nothing — `Avatar` derives its hue from the name and takes circle/square for person vs organization; the palette is ordered by contrast, not spectrum, and never paints a person red or amber), **where the accent goes** ("which of these" — a selected row, an active filter; never DATA and never the focus ring, while a page-scale position marker like an active TAB takes `primary`, the ink the kit already spends on "this is on"; and selection must not share a wash with hover), **theming is an app-level ESCAPE HATCH, not a product surface** (`applyLoticsTheme({ … })` once at boot, before `mount`, writing the `--lotics-*` roles on the document root; nothing in the platform writes a theme, and `apps.theme.color` is the launcher icon only — the five `var()` roles plus the three font rungs ARE the whole mechanism, and wrapping a component cannot replace them because RN-Web writes `fontFamily` per element and background/border do not inherit), color discipline, **typography** (the ramp is DATA in `type_ramp`, one table both platforms derive from; leading and tracking are baked per rung and a hand-set `letterSpacing` is always a second copy of the curve), whitespace, and how to TEST an overlay component (a `Popover`-backed surface never mounts under jsdom). |
 | [docs/reviewing.md](./docs/reviewing.md) | **Reviewing a screen you built** — the other docs say what good looks like; this one says how to find out whether you achieved it, because "it looks fine" is the same claim as "it should work" made with the same evidence. Measure, never eyeball: render it, extract computed values, let the table show the defect. Two GATES that outrank every treatment question (**SUBTRACT** — what question does this element answer, and count FACTS not elements; **RIGHT CONTROL** — name the species before treating it), then 10 probes each naming what to COLLECT and the SIGNATURE in the numbers: type inventory (range, singletons, the label/value shrink war), ground+border+radius across siblings, what each RULE separates, gap RATIOS, the state diff (paint may change, geometry may not), alignment drift (incl. a centred child that moves while its container measures identical), the surface walk (open it, press it, read the settled string), the DATA probe (what is really in the table — incl. grepping rendered text for internal ids), the ABSENCE pass that catches "bland", and microcopy. Plus the extraction snippets, what measurement cannot see, and how to act on a finding (fix the CLASS, and never resolve one with "the docs say X"). |
 | [docs/testing.md](./docs/testing.md) | Driving the kit in a browser — the three anatomies where the a11y tree says one thing and a driver must do another: a `PressDoor` row whose named button always intercepts pointer events (by design), portalled overlays that render at the top of the DOM, and custom pointer drag that `dragTo` cannot move. |
 | [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) and the ACTIVITY shape — a communications feed where the row's label is the GIST and the body varies by medium, one anatomy rather than a row type per kind. |
@@ -72,7 +72,9 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
   a press it refuses. Rows tick ONE at a time; derive position from the highest stamp and one click marks
   everything below it without inventing dates. A checklist REPORTS — a field owned by a section is
   named as a gap with a `ChecklistNote action` that jumps there, never edited or previewed in the
-  row. Worked in `examples/tpl_record.tsx` § Progress. See `docs/catalog.md`.
+  row. A per-ROW third axis, `ChecklistItem.verdict` (`"pass"`/`"fail"`), is a DECIDED outcome — a
+  QC gate, a reconciliation match — never toggled; see `docs/catalog.md` for why it withholds
+  `onToggle`. Worked in `examples/tpl_record.tsx` § Progress. See `docs/catalog.md`.
 - **`Badge` = STATUS only; supporting detail is the muted second line.** A type / category /
   attribute / count is not a status — it belongs under its identity as `size="xs" color="muted"`,
   never a second chip. A chip beside a name reads as its PEER (a colored one reads louder),

package/docs/ai_patterns.md

@@ -318,6 +318,16 @@ shape its root draws, and every surface needing a diff somewhere else rebuilds i
   operator opening a job of twelve fee lines to see where a dropped invoice landed should find
   the one filled shape in a column of blanks without reading anything or separating two hues.
   The hole keeps the column's width and announces nothing.
+
+  **Derive the kind from the same before/after the row's `DiffValue` carries — never from a
+  boolean "did this differ".** A field with no prior value (`before` empty or absent) that a run
+  now proposes a value for is an ADD, not a CHANGE, and a local review row that only asks
+  "does `draft !== before`" answers yes for both and always renders `changed` — the amber pencil
+  on a value that was never there to begin with, which reads as the AI having second-guessed a
+  figure it actually just filled in for the first time. This bites hardest on the record that
+  looks most ordinary: the first proposal any fresh record ever gets has an empty `before` on
+  every field, so every mark on that one run is wrong until the kind is derived per field
+  (`before === after` → no mark; `before === ""` → `added`; otherwise → `changed`).
 - **`useChangeSet(ids, { initial })`** (`@lotics/ui/use_change_set`) — the bookkeeping:
   `status`/`accept`/`reject`/`undo`/`acceptAll`/`reset`, `accepted`/`rejected`/`pending`,
   `keptCount`/`total`/`settled`. `initial` defaults to **`accepted`** so an operator drops
@@ -387,6 +397,16 @@ shape its root draws, and every surface needing a diff somewhere else rebuilds i
   only reject costs the whole re-entry.
 - **Gate the commit on what will actually be written**, not on the proposal count — disable at
   zero kept.
+- **A decided row's Keep/Drop must be reachable from BOTH directions when `initial: "accepted"`.**
+  `undo` returns a row to its DEFAULT, not to `"pending"` — so on the common default
+  (`initial: "accepted"`, the operator drops the exceptions rather than re-approving every
+  identical field) a row starts already decided and Undo is a no-op with nothing to reach:
+  there is no path back to a `pending`-style Keep/Drop pair, and the row is stuck accepted
+  forever. The collapsed-to-Undo anatomy (value + one "Undo" button, swapping to Keep/Drop only
+  while `pending`) is correct ONLY under `initial: "pending"`, where every row genuinely starts
+  undecided. Under `initial: "accepted"`, render Keep/Drop as an always-visible TOGGLE instead —
+  both buttons present, the one matching the row's current status disabled, the other live —
+  so either direction is one press away regardless of where the row started.
 - **The mark rides the LABEL, and the value sits in an `InlineSlot`.** Both are alignment
   before they are semantics. A mark beside the VALUE indents every row it marks by its own
   width plus a gap, so an unmarked row needs a spacer of exactly the glyph's width to keep up —

package/docs/catalog.md

@@ -179,6 +179,17 @@ axes carry every shape it takes, and BOTH are decisions about meaning, not looks
 
 A record's Progress and a desk's to-do list are the same component two booleans apart.
 
+**A row can carry a DECIDED outcome instead of a tick — `ChecklistItem.verdict` (`"pass"` /
+`"fail"`).** This is a per-ROW axis, not a list-level one: a QC gate, a reconciliation match,
+any row whose mark means an inspection SETTLED rather than work getting done. `fail` renders in
+red with an X (`StepStatus`'s `fail`, shared with `Stepper`/`AgentRun` via the same `Marker`) —
+distinct from `warning`, which means "still open, needs a look," where `fail` means the answer is
+already no. A verdict is reported, not toggled: passing `onToggle` alongside `verdict` is a
+no-op (withheld internally), because neither of the toggle-capable marks (`CheckboxInput`,
+`CheckCircle`) has a fail-shaped state — a caller with an inspector who taps to CONFIRM a
+pass/fail should drive that from its own control, then set `verdict` from the result, never
+reach for `done`+`onToggle` on the same row a verdict already settled.
+
 **A row carries its TITLE and its own stamp, and nothing else.** A checklist REPORTS: it does not
 collect, and it does not PREVIEW. A field some section owns — an assignee, an address, a portal
 login — is NAMED as a gap by a `ChecklistNote` whose `action` jumps to that section, never edited
@@ -1266,6 +1277,30 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   trust by summing exactly what its label claims. `LedgerBasis` is demoed on the gallery's
   Charts page instead — a delivery order has no base to compute from, and inventing one to
   place a component is how invented needs start.
+- **`running_ledger`** — `RunningLedger`: a CHRONOLOGICAL, self-totalling ledger — a stock
+  kardex, a statement of account — where every row carries the balance AS OF that row. Not
+  `Ledger`: that compound closes a fixed set of charge/receipt groups into one total and has no
+  chronological concept at all. `opening` (label + optional date + the anchor balance) then
+  `rows` (date, label, a SIGNED `amount` — positive in/debit, negative out/credit, one field
+  rather than paired columns so the same shape serves a stock quantity and a money statement),
+  each rendered with its running balance **computed by the component**, never accepted as a
+  caller-supplied number — a running balance is exactly the figure that must equal what it
+  accumulates, and a caller-supplied one is the one kind of drift no reader can catch by looking.
+  `format` is ONE formatter for the whole ledger (`formatMoney`, or a quantity formatter with a
+  unit suffix) — every row shares one unit, which is what lets the column state it once.
+  `criticalAtOrBelow` reads a row's balance in danger tone once it reaches a caller-declared
+  floor (a stock-out, a negative balance) — **the ONLY tone this component owns**, evaluated
+  independently on EVERY balance in the column: each row, the opening anchor (so an already-critical
+  opening reads danger even with zero rows following it), and the closing line. A row's `amount`
+  is never auto-toned by its arithmetic sign, because an OUT movement is routine business as often
+  as an IN one and colouring every negative red claims a meaning the number alone does not carry. Closes with a `Divider`-set current-balance line at `Ledger`'s own
+  `LedgerTotal` weight, `closingLabel` overriding the locale default ("Current balance") for a
+  domain the pack cannot own generically ("Tồn kho hiện tại"). No `examples/` worked example yet
+  — a stock kardex or an AR statement of account is a genuinely different shape from every
+  existing template (the 3-statement accrual grammar in `tpl_statements`, the fleet-register
+  drawer in `tpl_stock`), so forcing it into either would be a mismatch rather than a worked
+  example; proven against real, live deployed consumers instead (a warehouse and a receivables
+  app) until a template of its own earns its place.
 - **`reference_field`** — `ReferenceField`: a reference to ANOTHER RECORD, rendered as a
   FIELD VALUE — the kit's inline-editor surface (so a pointer sits in the value column
   like the editors above and below it), whose press opens a PEEK of that record's facts.
@@ -1329,6 +1364,22 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   reference is a FIELD, not a section — one pointer to one other row never earns a heading
   and a rail entry. Worked example: [`tpl_record`](../examples/tpl_record.tsx) § General
   (customer) and its Transport parties.
+- **`related_record_row`** — `RelatedRecordRow`: a pointer to a record in a DIFFERENT app's
+  table — never `ReferenceField`, which peeks an in-WORKSPACE link this app's own table holds
+  (a facts draft, Change/Clear). A suite of apps that deploys one bundle per department has no
+  in-app route to a sibling's record and no local fields to peek, so this only ever reports:
+  `kind` (an `Eyebrow` naming what the reference IS — "Lệnh sản xuất"), `code` (the record's own
+  human id), an optional `status` (pass a `Badge`), and `onOpen` — the HOST's job, typically
+  `openExternal(url)` from `@lotics/app-sdk` into the sibling app's own deployed URL, since only
+  the calling app's author knows that app's subdomain and its route shape for a record page.
+  Omitting `onOpen` renders a plain, non-interactive reference — never a press target wired to
+  nothing, which is worse than no affordance. Composes as a `DetailRow`'s value for a single
+  relationship, or repeats plainly (no per-row label) in a list for several — the surrounding
+  label or heading is the caller's, this renders one reference. No `examples/` worked example
+  yet, for the same reason as `running_ledger` above: what this component is FOR — a reference
+  into a genuinely separate deployed app — has no natural home inside any single-app template in
+  this repo without inventing a fictional sibling app to point at; proven against real, live
+  deployed consumers instead.
 - **`peek`** — `Peek`: drill-down for a reference — press a name/id where it appears and get its
   details in an anchored popover, without leaving the screen; keep the content a summary with ONE
   action to the full record. **`variant` picks the register the TRIGGER sits in, and getting it
@@ -1368,6 +1419,13 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   On pressable rows dropped values stay one tap away — the row opens the record; a READ-ONLY
   register (rows without `onPress`) has no door, so give the columns it can't afford to lose
   a low `priority` (e.g. `priority: 1` — outlives its right-side neighbours).
+  **Set `priority` from what the page already told the reader matters, never leave it at the
+  default.** A `SummaryLine`/`KPIStrip` figure above the register is a claim that ONE column is
+  the reason to scan this page; left unset, `priority` defaults to column order and sheds
+  right-to-left, so that exact column is the first thing table_fit drops the moment the
+  container narrows — the banner keeps promising a number the row beneath it can no longer
+  show. The fix is one line per column, not a rewrite: rank by what the summary already flagged
+  as the point, not by where the column happens to sit in the header row.
   **`detail` + `expanded` reveal a row's detail BENEATH it instead of navigating away.** A
   register answers "which one"; the moment it cannot answer "and what about it" the reader is
   sent to a drawer, loses the surrounding rows, and pays a navigation to come back — which is
@@ -1658,7 +1716,13 @@ component rather than showing it at zero.
   unsorted and out-of-bounds ranges all normalize; no input drops a character.
 - **`legend_item`** — `LegendItem`: one swatch + label of a chart legend.
 - **`remainder_meter`** — `RemainderMeter`: allocated-vs-remaining meter
-  (`RemainderMeterLabels` localized via the provider).
+  (`RemainderMeterLabels` localized via the provider). **A THREE-way comparison (ordered vs.
+  received vs. invoiced, say) is TWO stacked meters against the same `total`** — one per pairwise
+  relationship (ordered-vs-received, ordered-vs-invoiced) — not a new component: the primitive's
+  whole model is one source distributed one way, and a caller with a second relationship to show
+  reaches for a second instance before reaching for a wider one. Extract a true 3-column strip
+  only once a SECOND real caller needs the exact same 3-way shape (the kit's own
+  extract-on-the-second-hand-roll rule) — one confirmed need is not yet a pattern.
 - **`allocation_row`** — `AllocationRow`: one target's row in an allocation surface (pairs
   with `RemainderMeter`).
 

package/docs/composition.md

@@ -115,7 +115,15 @@ restyle a heading level per-page.
   (`##` — xl semibold, optional muted `description` and `info` popover), everything left-aligned
   at the column edge; `SectionHeadingMeta`, any VIEW control, and the section's own ADD ride the
   heading row's right edge (the title's `flex: 1` pushes them) — see the add-placement law
-  below. A COUNT earns that slot only when what it counts is not fully on screen — collapsed,
+  below. **The row is `flexDirection: "row"` and never wraps**, so a long control label doesn't
+  drop to its own line at phone width — it holds its own width and the title's `flex: 1` gives
+  up whatever is left, taking the `description` down with it. A label that repeats the heading
+  verbatim is the usual way this gets long enough to bite: measured on a real section, an
+  11-character title-plus-button pair left the title a comfortable column, and the SAME text
+  duplicated onto the button squeezed both title and description into a 107px ribbon wrapping
+  one or two words per line for eleven lines total. The button-label law already asks for
+  2–4 words; a heading-row control is the case where skipping it has a measurable width cost,
+  not just a wordier button. A COUNT earns that slot only when what it counts is not fully on screen — collapsed,
   paged, or long enough that the reader would have to scan to know. Over a list or thread
   rendered whole directly beneath its own heading it restates what is already in view, and the
   heading reads busier for it. The page column is a **`SectionStack`** — it owns the

package/docs/reviewing.md

@@ -308,6 +308,14 @@ A resting register is the cheapest thing to screenshot and the least likely to h
   no option colours). The fix is often config or a write path, not CSS.
 - **The obvious column may be the empty one.** Reading only the field the composer writes ships a
   feature empty on every row and correct in code review.
+- **List every field a write path SETS and check each one has a render on the record's own read
+  surface.** A screen with no visual defect can still be hiding real stored data: a workflow or
+  form commits a field, the record page never grew a row for it, and nothing about the page
+  LOOKS wrong — there is no empty box, no broken layout, just an absence with nothing marking
+  it. Pull the field list from the write path (a workflow's `set`, a mutation's payload), not
+  from the screen, then confirm each one against the record's own DetailRow/Text tree; where one
+  is missing, query the record directly to prove the value is really sitting there unseen before
+  calling it a fix. A screenshot cannot catch this — it only shows what already renders.
 - **A fixture can fail in the generous direction too**: an image tile pointed at a dead URL renders
   nothing, so the chip designed to survive a photo was never tested against one.
 - **Grep rendered text for internal identifiers — first probe, every audit** —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "44.8.0",
+  "version": "44.9.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -57,6 +57,7 @@
     "./use_selection": "./src/use_selection.ts",
     "./use_section_nav": "./src/use_section_nav.ts",
     "./ledger": "./src/ledger.tsx",
+    "./running_ledger": "./src/running_ledger.tsx",
     "./use_selection_mode": "./src/use_selection_mode.ts",
     "./file_thumbnail_grid": "./src/file_thumbnail_grid.tsx",
     "./uploading_thumbnail": "./src/uploading_thumbnail.tsx",
@@ -208,6 +209,7 @@
     "./counter": "./src/counter.tsx",
     "./link": "./src/link.tsx",
     "./reference_field": "./src/reference_field.tsx",
+    "./related_record_row": "./src/related_record_row.tsx",
     "./text_disclosure": "./src/text_disclosure.tsx",
     "./text_link": "./src/text_link.tsx",
     "./sort_header": "./src/sort_header.tsx",

package/src/checklist.tsx

@@ -209,6 +209,15 @@ export interface ChecklistItemProps extends StepPositional {
   accessibilityLabel?: string;
   /** Ticked. */
   done?: boolean;
+  /**
+   * A DECIDED outcome, not a completion tick — a QC pass/fail, a match that
+   * held or didn't. Takes over the row's mark from `done`/`current` (a
+   * verdict is reached by definition) and renders `fail` in red with an X, so
+   * a scan of the run tells "settled" from "settled, and the answer is no" —
+   * ticking every row and separately noting a rejection in prose is the
+   * failure this exists to replace.
+   */
+  verdict?: "pass" | "fail";
   /** The row the reader is waiting on — medium weight, so a run full of ticks
    *  still says which one is owed. */
   current?: boolean;
@@ -241,6 +250,7 @@ export function ChecklistItem({
   title,
   accessibilityLabel,
   done,
+  verdict,
   current,
   onToggle,
   trailing,
@@ -249,10 +259,18 @@ export function ChecklistItem({
   children,
   ...positional
 }: ChecklistItemProps) {
+  const settled = done || verdict != null;
   return (
     <Step
-      status={done ? "done" : current ? "current" : "upcoming"}
-      onToggle={onToggle}
+      status={verdict === "fail" ? "fail" : verdict === "pass" ? "done" : done ? "done" : current ? "current" : "upcoming"}
+      // A verdict is DECIDED elsewhere (an inspection, an AI check) and
+      // reported here, not toggled — passing `onToggle` through would put a
+      // completion checkbox on a row whose mark already means something else,
+      // and neither `CheckCircle` nor `CheckboxInput` (the interactive marks)
+      // know a `fail` state exists, so it would silently render as "not done"
+      // instead. The non-interactive `Marker` does, so this keeps a verdict
+      // row on that path.
+      onToggle={verdict != null ? undefined : onToggle}
       accessibilityLabel={accessibilityLabel ?? title}
       {...positional}
     >
@@ -262,7 +280,9 @@ export function ChecklistItem({
             WRAPS, so a long title drops its stamp to the next line rather than
             crushing it. */}
         <View style={{ flexDirection: "row", alignItems: "baseline", gap: 10, flexWrap: "wrap" }}>
-          <Text size="sm" weight={current ? "medium" : "regular"} color={done ? "muted" : "default"}>
+          {/* A fail stays in default ink, never muted — muting reads as
+              "settled, move on" and a rejection is the opposite of that. */}
+          <Text size="sm" weight={current ? "medium" : "regular"} color={verdict === "fail" ? "danger" : settled ? "muted" : "default"}>
             {title}
           </Text>
           {trailing}

package/src/ledger.tsx

@@ -44,8 +44,11 @@ function useLedger(): LedgerContextValue {
 }
 
 /** Signed display: negatives render as "− <abs>" (a receipt against charges).
- *  `n + 0` normalizes -0 (a zero receipts sum passed negated) to plain 0. */
-function signed(format: (n: number) => string, n: number) {
+ *  `n + 0` normalizes -0 (a zero receipts sum passed negated) to plain 0.
+ *  Exported for `RunningLedger`, which shares this exact glyph rule for every
+ *  money/quantity figure it renders — one definition, so the two components'
+ *  output can never drift into two different negative-number conventions. */
+export function signed(format: (n: number) => string, n: number) {
   return n < 0 ? `− ${format(-n)}` : format(n + 0);
 }
 

package/src/locale.tsx

@@ -74,6 +74,9 @@ export interface LoticsLocale {
   clarify: { otherPlaceholder: string; back: string; next: string; cancel: string; submit: string };
   /** `Ledger`: the screen-reader name of a peekable row. */
   ledger: { rowDetails: (label: string) => string };
+  /** `RunningLedger`: the closing line's label ("Số dư hiện tại", "Tồn kho
+   *  hiện tại") — the ledger's one derived, always-current figure. */
+  runningLedger: { currentBalance: string };
   /** `Step`/`ChecklistItem`'s toggleable MARKER, when the caller names no
    *  label of its own. A pipeline stage always passes its title, so this is the
    *  bare-`Step` fallback. */
@@ -207,6 +210,10 @@ export interface LoticsLocale {
    *  a SOURCE with different words. */
   fileRow: { open: (name: string) => string };
   sources: { open: (label: string) => string; heading: string };
+  /** `RelatedRecordRow`: the accessible name for its press target, when the
+   *  caller has not overridden it — "<kind> <code>", e.g. "Kế hoạch sản xuất
+   *  KH-2026-0001". */
+  relatedRecordRow: { open: (kind: string, code: string) => string };
   /** `Counter`: the two steppers, named for the value they move. */
   counter: { decrease: (label: string) => string; increase: (label: string) => string };
   /** `AllocationRow`: the a11y name of the amount input (naming its destination),
@@ -303,6 +310,7 @@ export const en: LoticsLocale = {
   inline: { saveError: "Couldn't save. Try again.", save: "Save", cancel: "Cancel" },
   clarify: { otherPlaceholder: "Or type your own answer…", back: "Back", next: "Next", cancel: "Cancel", submit: "Submit" },
   ledger: { rowDetails: (label) => `${label} details` },
+  runningLedger: { currentBalance: "Current balance" },
   stepper: { complete: "Complete step", progress: "Progress" },
   stepProgress: {
     complete: (total) => `Complete (${total}/${total})`,
@@ -409,6 +417,7 @@ export const en: LoticsLocale = {
   infoPopover: { more: "More information", about: (label) => `About ${label}` },
   fileRow: { open: (name) => `Open ${name}` },
   sources: { open: (label) => `Open ${label}`, heading: "Sources" },
+  relatedRecordRow: { open: (kind, code) => `Open ${kind} ${code}` },
   counter: { decrease: (label) => `Decrease ${label}`, increase: (label) => `Increase ${label}` },
   allocationRow: {
     allocateTo: (label) => `Allocate to ${label}`,
@@ -488,6 +497,7 @@ export const vi: LoticsLocale = {
   inline: { saveError: "Không lưu được. Thử lại.", save: "Lưu", cancel: "Hủy" },
   clarify: { otherPlaceholder: "Hoặc nhập câu trả lời khác…", back: "Quay lại", next: "Tiếp", cancel: "Hủy", submit: "Gửi" },
   ledger: { rowDetails: (label) => `Chi tiết ${label}` },
+  runningLedger: { currentBalance: "Số dư hiện tại" },
   stepper: { complete: "Hoàn thành bước", progress: "Tiến trình" },
   stepProgress: {
     complete: (total) => `Hoàn tất (${total}/${total})`,
@@ -594,6 +604,7 @@ export const vi: LoticsLocale = {
   infoPopover: { more: "Thông tin thêm", about: (label) => `Thông tin về ${label}` },
   fileRow: { open: (name) => `Mở ${name}` },
   sources: { open: (label) => `Mở ${label}`, heading: "Nguồn" },
+  relatedRecordRow: { open: (kind, code) => `Mở ${kind} ${code}` },
   counter: { decrease: (label) => `Giảm ${label}`, increase: (label) => `Tăng ${label}` },
   allocationRow: {
     allocateTo: (label) => `Phân bổ vào ${label}`,

package/src/related_record_row.tsx

@@ -0,0 +1,80 @@
+import { type ReactNode } from "react";
+import { View } from "react-native";
+import { Text } from "./text";
+import { Eyebrow } from "./eyebrow";
+import { Icon } from "./icon";
+import { colors } from "./colors";
+import { PressableHighlight } from "./pressable_highlight";
+import { useLoticsLocale } from "./locale";
+
+export interface RelatedRecordRowProps {
+  /** What KIND of record this is — the table/app it lives in ("Kế hoạch sản
+   *  xuất", "Lệnh sản xuất"). Rendered as an `Eyebrow` naming the value below
+   *  it, the same job an `Eyebrow` does in a cell or a metric caption. */
+  kind: string;
+  /** The record's own human code ("KH-2026-0001"). */
+  code: string;
+  /** The record's status, rendered as-is beside the code — pass a `Badge`.
+   *  Omit for a reference with no lifecycle state worth carrying here. */
+  status?: ReactNode;
+  /**
+   * Opens the record. THE HOST performs the navigation — typically
+   * `openExternal(url)` from `@lotics/app-sdk` into a sibling app's own
+   * deployed URL, since a suite of apps like this one is several SEPARATELY
+   * DEPLOYED bundles with no shared router; only the calling app knows the
+   * target app's subdomain and its own route shape for a record page. Omit
+   * for a report-only reference with nowhere to send the reader (a linked
+   * record whose app cannot be reached, or a same-app case better served by
+   * an in-app navigate instead of this component at all).
+   */
+  onOpen?: () => void;
+  /** Accessible name for the row when `onOpen` is set. Defaults to
+   *  "<kind> <code>" — override when that reads ambiguously (the same kind
+   *  repeated down a list of several). */
+  accessibilityLabel?: string;
+}
+
+/**
+ * A pointer to ONE record living in a DIFFERENT app's table — never a route
+ * inside this bundle, because a document-desk suite deploys one app per
+ * department with no in-app path to a sibling's record. Composes as a
+ * `DetailRow`'s value for a single relationship ("Kế hoạch sản xuất" →
+ * one linked plan) or repeats plainly in a list for several (an order's
+ * three downstream production plans) — the surrounding label/heading is the
+ * caller's choice, this renders one reference.
+ *
+ * NOT `ReferenceField`: that component edits an in-workspace link (peek,
+ * Change, Clear, an editable facts draft) for a reference the CURRENT app's
+ * own table holds. This one only ever reports — the target record's fields
+ * live in a table another app's bundle renders, so there is no draft to
+ * open and no picker to reassign from here.
+ */
+export function RelatedRecordRow(props: RelatedRecordRowProps) {
+  const { kind, code, status, onOpen, accessibilityLabel } = props;
+  const locale = useLoticsLocale();
+  const content = (
+    <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
+      <View style={{ flex: 1, minWidth: 0, gap: 2 }}>
+        <Eyebrow numberOfLines={1}>{kind}</Eyebrow>
+        <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
+          <Text size="sm" numberOfLines={1}>
+            {code}
+          </Text>
+          {status}
+        </View>
+      </View>
+      {onOpen ? <Icon name="external-link" size={14} color={colors.zinc[400]} /> : null}
+    </View>
+  );
+  if (!onOpen) return content;
+  return (
+    <PressableHighlight
+      focusRing
+      onPress={onOpen}
+      accessibilityLabel={accessibilityLabel ?? locale.relatedRecordRow.open(kind, code)}
+      style={{ paddingVertical: 4 }}
+    >
+      {content}
+    </PressableHighlight>
+  );
+}

package/src/running_ledger.tsx

@@ -0,0 +1,196 @@
+import { StyleSheet, View } from "react-native";
+import { Divider } from "./divider";
+import { Link } from "./link";
+import { signed } from "./ledger";
+import { Text } from "./text";
+import { formatDate } from "./format_date";
+import { useLoticsLocale } from "./locale";
+
+export interface RunningLedgerOpening {
+  /** What the anchor IS ("Tồn đầu kỳ", "Số dư đầu kỳ"). */
+  label: string;
+  /** ISO date, when the anchor has one — a stock count date, a statement's
+   *  period start. Omit for a balance with no dated origin. */
+  date?: string;
+  /** The balance BEFORE the first row. */
+  balance: number;
+}
+
+export interface RunningLedgerRow {
+  id: string;
+  /** ISO date. Rows render in the order given — this component does not sort
+   *  them, so the caller's own query order IS the chronology on screen. */
+  date: string;
+  /** What happened ("Nhập kho theo PO-2026-0001", "Thu tiền hóa đơn HD-014"). */
+  label: string;
+  /** The movement. Signed: positive is IN/debit, negative is OUT/credit — ONE
+   *  field rather than paired in/out columns, so the same row shape serves a
+   *  stock quantity and a money statement without either caller picking the
+   *  other's vocabulary. */
+  amount: number;
+  /** A trailing reference link (the source PO, the invoice this receipt was
+   *  matched against). */
+  reference?: { label: string; onPress: () => void };
+}
+
+export interface RunningLedgerProps {
+  opening: RunningLedgerOpening;
+  /** Chronological rows — oldest first. Each row's running balance is this
+   *  component's own DERIVED value (`opening.balance` plus every `amount` up
+   *  to and including that row), never a value the caller supplies: a running
+   *  balance is exactly the row that MUST equal what it accumulates, and a
+   *  caller-supplied figure is the one shape of drift no reader can catch by
+   *  looking. */
+  rows: RunningLedgerRow[];
+  /** Formats every figure on the balance/amount column — `formatMoney` for a
+   *  statement, or a quantity formatter (`(n) => \`${n.toLocaleString()} kg\`
+   *  `) for a stock ledger. ONE formatter for the whole ledger: every row here
+   *  shares one unit, which is what lets the column state it once instead of
+   *  per row. */
+  format: (n: number) => string;
+  /** A row whose running balance lands AT OR BELOW this reads in danger tone
+   *  — a stock-out, an account gone negative. Omit for a ledger with no
+   *  critical floor (most money statements; a stock ledger typically passes
+   *  0). */
+  criticalAtOrBelow?: number;
+  /**
+   * The closing line's label. Default resolves from the locale pack
+   * ("Current balance"), which fits a money statement but not every domain
+   * this serves both of on day one — a stock kardex wants "Tồn kho hiện
+   * tại", specific vocabulary the locale pack cannot own for every future
+   * caller. Override per instance the same way `Sources.label` does.
+   */
+  closingLabel?: string;
+}
+
+/**
+ * A chronological, self-totalling ledger — a stock kardex, a statement of
+ * account — where every row carries the balance AS OF that row. NOT `Ledger`:
+ * that component closes a fixed set of charge/receipt GROUPS into one total
+ * and has no chronological concept at all; reaching for it here would mean
+ * inventing a "group" for what is actually a time series and losing the
+ * running balance a kardex or a statement is FOR. Composes a `Divider`-closed
+ * current-balance line the same way `Ledger`'s own `LedgerTotal` does, so a
+ * page mixing this with a `Ledger` elsewhere still reads as one design
+ * language.
+ *
+ * The balance column is DERIVED — see `rows`' own doc. A platform whose
+ * rollup engine cannot produce an ordered cumulative aggregate (no per-row
+ * stored balance exists for a stock movement today) is exactly the case this
+ * is for: opening balance + a plain list of signed deltas needs no schema
+ * change on either side to render correctly.
+ */
+export function RunningLedger(props: RunningLedgerProps) {
+  const { opening, rows, format, criticalAtOrBelow, closingLabel } = props;
+  const locale = useLoticsLocale();
+  let running = opening.balance;
+  const computed = rows.map((r) => {
+    running += r.amount;
+    return { row: r, balance: running };
+  });
+  const closing = computed.length > 0 ? computed[computed.length - 1].balance : opening.balance;
+  const closingCritical = criticalAtOrBelow != null && closing <= criticalAtOrBelow;
+  // Evaluated independently of `closingCritical` (and of whether there are
+  // any rows at all) — an opening balance that already sits at/below the
+  // floor must read as critical on ITS OWN row; the closing line below only
+  // renders when there is at least one row, so it can never be the sole
+  // carrier of this signal.
+  const openingCritical = criticalAtOrBelow != null && opening.balance <= criticalAtOrBelow;
+
+  return (
+    <View style={styles.ledger}>
+      <View style={styles.openingRow}>
+        <View style={styles.grow}>
+          <Text size="sm" weight="medium">
+            {opening.label}
+          </Text>
+          {opening.date ? (
+            <Text size="xs" color="muted">
+              {formatDate(opening.date)}
+            </Text>
+          ) : null}
+        </View>
+        <Text size="sm" weight="medium" tabular color={openingCritical ? "danger" : undefined}>
+          {signed(format, opening.balance)}
+        </Text>
+      </View>
+      {computed.map(({ row, balance }) => {
+        const critical = criticalAtOrBelow != null && balance <= criticalAtOrBelow;
+        return (
+          <View key={row.id} style={styles.row}>
+            <Text size="xs" color="muted" numberOfLines={1} style={styles.date}>
+              {formatDate(row.date)}
+            </Text>
+            <Text size="sm" numberOfLines={1} style={styles.shrink}>
+              {row.label}
+            </Text>
+            {row.reference ? (
+              <Link size="xs" onPress={row.reference.onPress} accessibilityLabel={row.reference.label}>
+                {row.reference.label}
+              </Link>
+            ) : null}
+            <View style={styles.grow} />
+            {/* Neutral, never auto-toned by sign: an OUT movement is routine
+                business (a stock issue to a filled order, a payment applied)
+                as often as an IN one, and colouring every negative red would
+                claim a meaning the number alone does not carry — the same
+                restraint `LedgerRow`'s own `tone` leaves to its caller. The
+                one signal this component DOES own is `criticalAtOrBelow`,
+                which is a real domain rule the caller opted into, not a
+                guess from the arithmetic sign. */}
+            <Text size="sm" tabular style={styles.amount}>
+              {signed(format, row.amount)}
+            </Text>
+            <Text size="sm" weight="medium" tabular color={critical ? "danger" : undefined} style={styles.balance}>
+              {signed(format, balance)}
+            </Text>
+          </View>
+        );
+      })}
+      {computed.length > 0 ? (
+        <View style={styles.total}>
+          <Divider />
+          <View style={styles.row}>
+            <Text size="md" weight="semibold" style={styles.grow}>
+              {closingLabel ?? locale.runningLedger.currentBalance}
+            </Text>
+            <Text size="md" weight="semibold" tabular color={closingCritical ? "danger" : undefined}>
+              {signed(format, closing)}
+            </Text>
+          </View>
+        </View>
+      ) : null}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  // Mirrors `Ledger`'s own outdent + row rhythm so the two read as one design
+  // language wherever a page uses both.
+  ledger: { gap: 0, marginHorizontal: -8 },
+  row: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 10,
+    minHeight: 28,
+    paddingHorizontal: 8,
+  },
+  openingRow: {
+    flexDirection: "row",
+    alignItems: "baseline",
+    gap: 10,
+    minHeight: 28,
+    paddingHorizontal: 8,
+    marginBottom: 4,
+  },
+  grow: { flexGrow: 1, flexShrink: 1 },
+  shrink: { flexShrink: 1 },
+  date: { width: 72 },
+  // Fixed widths so the amount and balance columns each keep ONE right edge
+  // down the whole run, whatever an individual figure's digit count — the
+  // same reasoning `Ledger`'s single money column applies to two columns
+  // instead of one.
+  amount: { minWidth: 90, textAlign: "right" },
+  balance: { minWidth: 100, textAlign: "right" },
+  total: { gap: 6, marginTop: 6 },
+});

package/src/stepper.tsx

@@ -23,8 +23,13 @@ import { NODE, STEP_HEAD_TEXT_LINE, STEP_MARKER_GAP, STEP_ROW_INSET, STEP_ROW_PA
 // A node's place in a sequence. `upcoming` = not reached (greyish); `current` =
 // where we are (ring + white centre, pulses when live); `done` = passed (filled);
 // `complete` = the terminal "finished" marker (filled + check); `warning` = an
-// issue at a reached step.
-export type StepStatus = "upcoming" | "current" | "done" | "warning" | "complete";
+// issue at a reached step; `fail` = a reached step whose OUTCOME is negative —
+// a verdict, not an issue still open. Distinct from `warning`: amber asks the
+// reader to look, red tells them the answer is already no (a QC reject, a
+// failed match) — collapsing the two into one amber "something's off" loses
+// the one bit that actually matters, whether the row is still actionable or
+// already decided.
+export type StepStatus = "upcoming" | "current" | "done" | "warning" | "fail" | "complete";
 export type StepOrientation = "horizontal" | "vertical";
 
 const reached = (s: StepStatus) => s !== "upcoming";
@@ -302,6 +307,14 @@ export function Step(props: StepProps) {
             {onToggle && mark === "box" ? (
               // SELECTION: the square, in the ring's own box so the column and the
               // spine keep their rhythm whichever mark a surface uses.
+              // `fail` deliberately reads as unchecked here, not done: neither
+              // mark below has a fail-shaped state, and forcing one to `done`
+              // would draw a rejected step in the same ink as a passed one —
+              // the one distinction a verdict exists to keep. A verdict is
+              // reported, not toggled, so a real caller never reaches this
+              // combination (`ChecklistItem` withholds `onToggle` once
+              // `verdict` is set); this stays correct for anyone driving
+              // `Step` directly.
               <View style={{ width: NODE, height: NODE, alignItems: "center", justifyContent: "center" }}>
                 <CheckboxInput
                   checked={status === "done" || status === "complete"}
@@ -376,6 +389,17 @@ export function Marker({ status, color, live }: { status: StepStatus; color: str
       </View>
     );
   }
+  if (status === "fail") {
+    // A decided negative: filled in the same solid-red the kit uses for danger
+    // everywhere else (deadline.ts's own tone→hue mapping), with a white X —
+    // the "done" disc's shape, wrong-answer color, so a scanning eye reads
+    // both as "reached and settled" and only the color says which way.
+    return (
+      <View style={[styles.disc, { backgroundColor: solid("red") }]}>
+        <Icon name="x" size={10} color={colors.white} />
+      </View>
+    );
+  }
   if (status === "current") {
     return (
       <View style={styles.discWrap}>