@lotics/ui 44.7.1 → 44.9.0

package/docs/composition.md

@@ -8,6 +8,23 @@ full worked-example screens ship as source in `examples/tpl_*.tsx` (picked by jo
 [templates](./templates.md)). Every rule here is enforced by the primitives' defaults; fighting
 them produces off-system UI.
 
+## The form comes before the treatment
+
+**Name what the subject IS, then reach for parts.** A set of records is a register; a thing moving
+through ordered places is a rail; work assigned to finite resources over time is a board; a
+sequence of events is a timeline; a population whose point is its deviant minority is a queue
+sorted by deviation. Getting this wrong cannot be recovered later — a register of objects that
+should have been a rail is well-typed, well-spaced, correctly aligned and still says nothing about
+order or progress, because a status column reports one word and leaves the reader to know which
+word comes after which.
+
+The pull toward a register is structural, not a lapse in taste: `Table`, `DetailRow`,
+`SummaryLine` and `Badge` are the most reachable things here, and they compose into something
+defensible for almost any data. That is exactly why the question has to be asked out loud. **Reuse
+first is about not duplicating primitives** — a one-off composition needs no new component, so the
+kit lacking a device is a reason to compose one from what it has, not a reason to flatten the
+subject into rows.
+
 ## Canvas & content column
 
 - **Canvas**: a full-bleed `colors.white` ScrollView with `padding: 28`. Cards separate from the
@@ -98,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
@@ -183,6 +208,14 @@ without scanning. The heading row is the section's control line — it already c
 and the view controls — so the add belongs on it, in the same spot whether the section holds
 nought or forty.
 
+**When the row runs out of width, the VERB wraps — the title never gives way.** The title names
+the section; the verb is the thing that can move. Getting this backwards is easy to ship because
+RN-Web resolves `flex: 1` to `flex-basis: 0%` with `min-width: 0`, so a title beside a button that
+holds its intrinsic width is the half that collapses — measured at 375 as a heading broken one
+word per line beside an untouched button. `SectionHeading` and `SubsectionHeading` wrap and floor
+their title column for this; do not add a second `flex: 1` spacer beside a title that already has
+one, which halves its share again and is how a badge came to land on top of a section title.
+
 **Where there IS no heading row, the add has nowhere else to be, so it rides the surface's own
 bar** — an attachment popover, a dialog body, any self-contained widget. That is not an exception
 to the law so much as the same reasoning: the rule exists so the verb sits in ONE place a reader
@@ -217,6 +250,18 @@ no path actually closes.
 - **Only the ADD.** A verb that acts on a SELECTION (delete, export, run) belongs to the
   selection — `FloatingActionBar` — and a verb about ONE row stays on the row.
 
+## A partitioning control states its band's size as a PROP
+
+`TableGroup` takes `count`; `Tabs` takes it per option. Neither takes a label with the number
+formatted into it, and that is the whole rule: `"Trên tàu (4)"` is a second copy of a figure the
+screen already computes, and it is the copy that goes stale — the band re-counts on every filter
+and the string does not.
+
+It also decides where the count may live. A register whose bands already state their sizes must
+not carry a strip of chips above it repeating the same three numbers; that is one fact twice, and
+the reader learns to skip the strip. And a count is a reason to PRESS — a control that states how
+many rows are behind it and does not filter to them is stating a fact it refuses to act on.
+
 ## Period filters for time-constrained data
 
 Time-constrained data gets a **`DateRangeFilterField`** in the header band — never a static period
@@ -312,7 +357,11 @@ compete instead of reading as different things. Selection changes what the box I
 hover changes how intensely it says it.
 
 For fields: layer the hover-border AFTER `style` so it wins over the caller's resting edge, put the
-open ring (`FOCUS_RING`) on the open state, and **a field NEVER greys its content**. The bug this
+open ring (`FOCUS_RING`) on the open state, and **a field NEVER greys its content**. That ordering
+is load-bearing rather than tidy: a caller's resting `borderColor` is exactly how a frameless
+variant gets expressed, and layered the other way it erases the hover edge that is such a field's
+ONLY affordance — a control that then draws nothing in either state and is simply never pressed.
+Give the field a variant PROP for its resting frame instead of taking one through `style`. The bug this
 grammar prevents: a FIELD built on `PressableHighlight` inherits the wash AND its own border — it
 greys *and* animates its edge while its siblings only border-hover. Reach for `PressableHighlight`
 on a bordered/input control and you've made it.
@@ -416,6 +465,12 @@ a dashboard. Card stat rails use `KPICard`.
   form round-trip never expands them to a fabricated `"2026-05-01"`. Comparisons and sorting treat
   a partial as its period start (`"2026" < "2026-05" < "2026-05-01"`).
 
+**A per-unit price is not a total, and the currency's minor unit is the wrong floor for it.**
+`Intl`'s currency style rounds to two decimals for USD, so a rate of 0,019 per kg prints as
+`0,02` — a 5% error rendered as fact, with nothing on the screen saying it was rounded. Pass
+`maxFractionDigits` on a UNIT price; leave it off for a total, where two decimals is the contract.
+Never hand-roll the grouping or the symbol to get the digits back.
+
 ## Every number is a door
 
 Except the KPI strip: a component that summarizes records leads to the records behind it when
@@ -712,6 +767,21 @@ action goes to the referenced record's own page; a local `Drawer` that re-shows
 just showed makes "Open" mean *read that again, wider*, and leaves the real record unreachable
 from the only control that promised it.
 
+**A record surface answers *which record is this* first — and the block that does it is SHORT.**
+Identity is the handful of facts someone would say aloud to name this record (its number and its
+counterparty, usually two); everything else is an ATTRIBUTE and belongs below the answer the
+reader opened the record for. Get the size wrong and the position becomes unwinnable: eight
+labelled header fields push the ledger under the fold, and moving the block to the bottom to fix
+that leaves a reader who cannot tell whose record they are in. Both orders measure perfectly, so
+neither is caught by any check that reads the rendered screen. **When a leading block buries the
+answer, shrink it — do not move it**; frequency of EDIT is not the axis, because a rarely-edited
+fact can still be the one that names the thing.
+
+"The chrome already carries identity, so the body need not lead with it" is a real argument and a
+falsifiable one — verify it FACT BY FACT before relying on it. A summary strip showing the record
+number and its totals carries half an identity; the counterparty is missing, and half is what
+makes the claim feel true while the reader still cannot name what they are looking at.
+
 **All of the above is the LIST SCREEN.** A CHILD COLLECTION inside a record page — fees, lines,
 stops, containers — does the opposite: the row **EXPANDS** (`TableRow` `detail` + `expanded`),
 never docks a drawer. A drawer's whole job is to supply a context the reader is missing, and on a
@@ -928,10 +998,13 @@ gate's SCOPE, once** — never prose beside the button, never revealed only on p
   alignment law: the row top-aligns and label, control, trailing each center within the
   first control line — a tall value block never drags the label, and a LABEL too long for its
   column WRAPS (never clipped, never abbreviated to fit) with its first line still level with
-  the value. A FLAT value row
-  (`InlineStatic`, plain `Text`) sets **`DetailRow flat`**: the annotation tucks up by the
-  control band's slack so the perceived gap under the text equals the gap under a chip —
-  the band's invisible bottom half must never read as a hole above the description.
+  the value. A value that sits OFF the
+  inline-control grid — a raw node, not an `InlineStatic` / `InlineSlot` — sets **`DetailRow
+  flat`**, which aligns its annotations on both axes: they drop the control's text inset so the
+  description starts on the value's own left edge, and tuck up by the band's slack so the gap
+  under the text matches the gap under a chip. Miss it and the row has three left edges and a
+  hole; pass it on a value that IS on the grid and you create both. Which one a static value
+  should be is decided per table — see data_entry.md §The editability affordance.
 - **A verb about a VALUE goes ON the value — an `InlineButton` in the field's `actions`.** Copy
   this reference, call this number, open this record: the act names the value, so it travels
   with what it acts on, and a reader never has to pair a control sitting at the page's right
@@ -1243,6 +1316,15 @@ which is the loudest possible version of the thing the rule exists to stop. Remo
 without replacing the separation is what left the header looking adrift — the ink step above is
 the replacement, and the two changes only work together.
 
+**Annotate every droppable column, or none.** `priority` decides what a narrow container sheds
+(lowest number is last to go, and column 0 — the identity — never drops). A PARTIAL annotation is
+the trap: an unannotated column defaults above the whole hand-written range, so one annotated
+column silently makes every other column drop before it, and one unannotated column among
+annotated ones is the first to go however important it is. Both read as correct in review. The
+question to answer per register is "what is the last column standing", and the answer is almost
+always the figure the register exists to compare — so give that one the lowest number and work
+outwards.
+
 **A row's SUBJECT is `medium`, never semibold.** Semibold is the heading ladder's weight — `#`,
 `##`, `###` are all semibold — so a register whose row subjects are semibold renders its content
 at heading weight once per row, in the same font CUT as the page title (`Inter_600SemiBold` is a
@@ -1495,6 +1577,12 @@ disclosure exception). `TextLink` takes the blue only when it has an `href`; as
 a value, or as a muted in-place disclosure, it stays neutral — because a press that opens a PEEK,
 or unfolds a transcript, is not a trip.
 
+**Selection is a GROUND, and hover is a ring — at every altitude.** A row, a card, a chip, a
+tile: the thing you have CHOSEN carries the accent wash, and the thing under the pointer carries
+the ring. Collapsing them into one "active" style makes the selected item pixel-identical to the
+hovered one, so "which did I pick" is answerable only by moving the mouse away. The tell in code
+is a single boolean OR-ing selection together with hover, press and focus.
+
 ## `Badge` is for STATUS only — everything else is text
 
 A `Badge` means STATE that must read at a GLANCE — a lifecycle status, a risk level, a quality
@@ -1610,6 +1698,12 @@ Anything pressable is ≥ 40px tall (8px minimum gap between pressables). 16px b
 canvas padding, 16–20 inside bands, 10–12 between content lines. Density comes from alignment +
 hierarchy, not cramming.
 
+**A control's height comes from `CONTROL_HEIGHT`, never from padding tuned against a leading.**
+Padding that happens to sum to the band height is a second owner of that number, and it drifts the
+moment the type ramp moves — which the ramp is allowed to do. The signature is one control
+standing a few pixels proud of every sibling in a filter bar, correct on the day it was written
+and wrong after a release that touched no control at all.
+
 **The trim test — does this element RESTATE something already on the screen?** Run it over every
 screen before shipping: a per-row proportion bar when the percentage is already on the row; the
 percentage itself when the column holds four values and a total; a state line that only says

package/docs/data_entry.md

@@ -66,6 +66,13 @@ Controlled inputs make derived state track what is on screen, and read shorter t
 they replace — four `DetailRow` + `Inline*` pairs whose `onSave` exists only to `setState` collapse
 to four fields. Worked example: `tpl_record`'s New-customer dialog.
 
+**The discriminator, since the kit's own `tpl_item_list` fills preview cards with `Inline*`
+editors:** what decides is whether anything on the surface READS the draft before the commit. A
+dialog whose Save is gated on the values being typed, or whose visible totals derive from them,
+takes controlled `FormField`s — that is this rule. A REVIEW surface whose gate is decided by
+something else (which cards are kept, which candidate is picked) may keep inline editors, because
+nothing is arguing with the box under the cursor. Neither shape is a create form's stand-in.
+
 **But do not then derive the ERROR per keystroke** — the mistake controlled inputs invite, and the
 opposite failure to the one above. Validity and the error MESSAGE are different questions. Validity
 gates the commit and is checked continuously; the message claims the reader did something wrong, so
@@ -313,19 +320,66 @@ where it must stay strictly inside its box — that is `framed`. A DISABLED `fra
 box: it drops the border and fill so it cannot promise a press, but it stays in line with the enabled
 fields beside it.
 
+**`bare` puts its whole affordance in the hover edge, so nothing may outrank that edge.** Pass the
+variant as a PROP; never express it as a resting `borderColor: "transparent"` in `style`, which is
+applied after the hover rule and erases the edge one line after it is computed. The failure is
+silent in every direction that usually catches things — the field keeps its role, its label, its
+focus ring, its metrics and its save — and what breaks is only that nobody presses it, because a
+control drawing nothing at rest and nothing on hover is text. The kit's own `TextInputField` had
+it, so a `bare` inline editor in a register column went un-pressed rather than mis-styled.
+
+**The cursor is the other half of that promise, and it belongs to the CONTROL, not to the page.**
+An inline editor takes the pointer like every other control. It once forced the arrow back, on the
+reasoning that an editor is an input rather than a button — right that it is not a button, wrong
+about the replacement: the arrow is what inert prose gets, so the one value on the row that was
+the reader's to change was the one that looked least touchable. The I-beam is not the alternative
+either; a resting editor sets `userSelect: "none"` so a drag edits rather than selects, and an
+I-beam would promise a caret that is not there. A field is disabled is the only case that reverts
+to the arrow, for the same reason it rests bare: an inert value must promise nothing.
+
 A READ-ONLY value in the same column — a computed total, a system ID, a synced/locked field — is
 **`InlineStatic`**: it copies the editor box metrics exactly (height, padding, 1px transparent
 border) but stays FLAT and non-interactive, so editable (chip) vs read-only (flat) is legible at a
 glance and the static value never reads as a disabled input.
 
-**Only in a grid that MIXES the two.** "Copies the editor box metrics" means it hard-sets
-`INLINE_CONTROL_HEIGHT` — worth paying to hold a column straight beside real editors, pure waste
-where there are none. In an ALL-static grid (a peek's facts, a summary popover) it reserves a 40px
-control band for a 20px value, and the row is the MAX of that box and the table's own band, so
-neither fix works alone: use plain `Text` for the value AND pass `DetailTable` a `minHeight` (28,
-`DetailRow`'s own default). Same test as `labelWidth` — a `DetailTable`'s defaults are the
+**In a grid that MIXES the two, or one that ANNOTATES.** "Copies the editor box metrics" means it
+hard-sets `INLINE_CONTROL_HEIGHT` — worth paying to hold a column straight, waste where there is
+no column to hold. Two different things can make the column, and missing the second is what put
+three left edges on a review dialog:
+
+- **An editor beside it.** The obvious case: a static value rendered raw beside a real editor
+  starts at the cell edge, 20px tall, at the top, while the editor's text starts 9px in and
+  centres in a 40px band.
+- **A value column's floor is not a control's floor.** `minValueWidth` decides when the table
+gives up two columns and stacks, and it defaults to `MIN_VALUE_WIDTH` (200) rather than a
+control's `MIN_CONTROL_WIDTH` (160), because the column holds company names and addresses, not
+only editors. The narrow-width failure is silent in both halves: the table technically fits, so
+it does not stack, and every value is then truncated past half while the label beside it measures
+perfectly. Raise it further where a cell holds MORE than one editor; lower it only where the
+values genuinely are short.
+
+**A `description` / `warning` / `error` under it.** `FieldAnnotations` insets its stack by
+  `CONTROL_TEXT_INSET` so it lines up with a CONTROL's words — so an annotated row whose value is
+  raw puts the value at the cell edge and its own description 9px inside it. Nothing else on the
+  screen is wrong, the drift is small enough to read as sloppiness rather than structure, and it
+  appears only on the rows that happen to carry a description, so a column slides in and out of
+  alignment down its own length.
+
+Decide it per TABLE, never per row: one annotated static row puts every static value in that table
+on the grid, or the table keeps two row heights for no reason a reader can see.
+
+In an all-static, un-annotated grid (a peek's facts, a summary popover) the grid buys nothing and
+costs 40px of band for a 20px value — and the row is the MAX of that box and the table's own band,
+so neither fix works alone: use plain `Text` for the value AND pass `DetailTable` a `minHeight`
+(28, `DetailRow`'s own default). Same test as `labelWidth` — a `DetailTable`'s defaults are the
 inline-control grid's; a grid that isn't one overrides both.
 
+`DetailRow flat` is the ESCAPE from the grid, not a synonym for read-only: it says "this value is
+a raw node sitting off the control band", and it corrects the annotations on both axes for it —
+dropping the text inset and tucking the block up by the band's slack. Never pass it with
+`InlineStatic` or `InlineSlot`, which are ON the grid: there it re-introduces the 9px drift it
+exists to remove and pulls the description 4px too tight.
+
 ### Choosing a CHOICE control — by option count, not by taste
 
 A field whose value is one-of-N has three answers, and the wrong one is what makes a record

package/docs/reviewing.md

@@ -45,10 +45,35 @@ the same direction. The kit measures the CONTAINER, not the screen — see AGENT
 
 ---
 
-## Two gates, before any probe
+## Three gates, before any probe
 
-A perfectly-treated element that should not exist still measures clean, and a wrong control cannot
-be treated into a right one. Both of these are cheap and both outrank everything below.
+A screen in the wrong FORM measures clean in every direction, a perfectly-treated element that
+should not exist still measures clean, and a wrong control cannot be treated into a right one.
+All three are cheap and all three outrank everything below.
+
+### 0. RIGHT FORM
+
+**Name what the subject IS before composing anything.** A set of records is a register. A thing
+moving through ordered places is a rail. Work assigned to finite resources over time is a board.
+A sequence of events is a timeline. A population whose point is its deviant minority is a queue
+sorted by deviation. A quantity across two dimensions is a matrix.
+
+This gate exists because **every probe below reads a screen that is already a register of fields**
+and measures its TREATMENT. So a screen that should have been a board or a rail passes the type
+inventory, the ground tally, the gaps, the rules and the alignment — all of them — and still reads
+as templated. No amount of treatment fixes it, and nothing else here can see it.
+
+*The tell that it was skipped:* every screen in the product is a register with a summary line over
+it. That is what reuse-first produces when nothing asks the question — the catalog's most reachable
+parts are `Table`, `DetailRow`, `SummaryLine` and `Badge`, so a subject whose natural shape is not
+a table gets flattened into one and no probe fires. **Reuse-first is about not duplicating
+PRIMITIVES, not about the shape of a screen**: a one-off composition needs no new component, so
+"the catalog has no journey rail" is an argument for composing one out of `Stepper`, not for
+rendering a status column and moving on.
+
+*And check the form against what the data can FILL.* A rail with no stamped stops, a calendar with
+no durations, a map with no coordinates — each renders an empty device that measures perfectly.
+→ probe 8.
 
 ### 1. SUBTRACT
 
@@ -244,6 +269,14 @@ A resting register is the cheapest thing to screenshot and the least likely to h
 
 - **Open what the row opens** and measure where the actionable field LANDS. An UNBOUNDED section
   (a feed, a thread) above a bounded one buries it, and the burial deepens with use.
+- **Name the record before you read it.** Collect the y of each fact that IDENTIFIES what is open
+  (its number, its counterparty) and compare against the viewport; any of them first answered
+  below the fold is the finding. Then measure the other direction — the top of the block answering
+  what the reader OPENED this for, and what sits above it. A leading block that pushes that answer
+  under the fold is too LONG, not mis-positioned: moving it down trades a buried ledger for a
+  reader who cannot tell whose record they are in, and both orders measure clean on their own, so
+  nothing that reads a resting screen catches either. Re-measure at 375, where a block that cleared
+  the fold at 1280 buries the answer. → [composition.md](./composition.md) §"Master-detail".
 - **Press every control** and look at the state you land in. Commonest miss: a value rendering as
   a coloured chip in a register and as bare grey text in its own EDITOR.
 - **TAB through it, then diff what a keyboard reaches against what LOOKS pressable.** A pointer
@@ -275,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/examples/tpl_item_list.tsx

@@ -47,7 +47,6 @@ 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";
-import { Link } from "@lotics/ui/link";
 import { TextInputField } from "@lotics/ui/text_input_field";
 import type { DisplayFile } from "@lotics/ui/file_thumbnail";
 import { InlineFiles } from "@lotics/ui/inline_files";
@@ -847,10 +846,15 @@ function EnterDataDialog({ open, onOpenChange, seedDocs, onCreate, onCreateMany
                           shape per card is found without reading the column. */}
                       <DiffMark kind={dropped ? "removed" : "added"} />
                       <Text size="sm" weight="semibold" style={{ flex: 1 }} numberOfLines={1}>{title}</Text>
+                      {/* A control, not a Link. These MUTATE the change set;
+                          they navigate nowhere. Blue underlined text promises a
+                          destination, and `Link` announces `role="link"` — so a
+                          template every app copies was teaching the one thing
+                          composition.md § Buttons bans outright. */}
                       {dropped ? (
-                        <Link size="sm" onPress={() => kept.undo(d.id)} accessibilityLabel={`Keep ${title}`}>Keep</Link>
+                        <Button color="secondary" title="Keep" onPress={() => kept.undo(d.id)} accessibilityLabel={`Keep ${title}`} />
                       ) : (
-                        <Link size="sm" onPress={() => kept.reject(d.id)} accessibilityLabel={`Do not create ${title}`}>Don&rsquo;t create</Link>
+                        <Button color="secondary" title="Don’t create" onPress={() => kept.reject(d.id)} accessibilityLabel={`Do not create ${title}`} />
                       )}
                     </View>
                     {/* A dropped card COLLAPSES rather than dimming in place:
@@ -997,7 +1001,7 @@ function EnterDataDialog({ open, onOpenChange, seedDocs, onCreate, onCreateMany
                     {khach}
                     {CUSTOMER_OPTIONS.some((o) => o.label === khach) ? "" : " (new customer)"}
                   </Text>
-                  <Link size="sm" onPress={() => setKhach("")} accessibilityLabel="Change customer">Change</Link>
+                  <Button color="secondary" title="Change" onPress={() => setKhach("")} accessibilityLabel="Change customer" />
                 </View>
               )}
             </FormField>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "44.7.1",
+  "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,11 +209,13 @@
     "./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",
     "./skeleton": "./src/skeleton.tsx",
     "./table": "./src/table.tsx",
+    "./table_fit": "./src/table_fit.ts",
     "./data_grid": "./src/data_grid.tsx",
     "./detail_row": "./src/detail_row.tsx",
     "./record_summary": "./src/record_summary.tsx",

package/src/accordion.tsx

@@ -150,8 +150,13 @@ export interface AccordionMetaProps {
 /** Right-side context for AccordionHeader — an amount, date, or short hint.
  * xs muted, tabular for numerals. */
 export function AccordionMeta(props: AccordionMetaProps) {
+  // The meta yields before the title does. The title NAMES the disclosure; the
+  // meta only qualifies it — but with the title on `flex: 1` and the meta at its
+  // intrinsic width, the squeeze landed entirely on the name (measured at 375:
+  // title clipped 24% and ellipsised, meta untouched). Same inverted priority
+  // `PageHeader` fixed one rung up; resolved the same way here.
   return (
-    <Text size="xs" color="muted" tabular>
+    <Text size="xs" color="muted" tabular numberOfLines={1} style={styles.meta}>
       {props.children}
     </Text>
   );
@@ -196,6 +201,9 @@ const styles = StyleSheet.create({
   titleText: {
     flex: 1,
   },
+  meta: {
+    flexShrink: 1,
+  },
   // Flush with the header's left edge — aligns with the title, like a Section
   // body. The chevron + position already say "inside"; no indent needed.
   content: {

package/src/agent_run_pane.tsx

@@ -48,11 +48,13 @@ export interface AgentRunLike {
    * the wrong document, and the only exit was to sit through it.
    */
   cancel: () => void;
-  /** The breaking error that killed the run. Accepts `undefined` as well as
-   *  `null` so an SDK run — whose `error` is an OPTIONAL property — satisfies
-   *  this without the caller reshaping the object the SDK docs say to hand
-   *  straight over. The pane normalizes both to absent. */
-  error: string | null | undefined;
+  /** The breaking error that killed the run. OPTIONAL, not merely widened to
+   *  include `undefined`: an optional property is not assignable to a required
+   *  one however wide the required one's type, so declaring it required made the
+   *  three-line usage in `ai_patterns.md` fail to compile against an SDK run —
+   *  and every app that hit it reached for a `useMemo` reshape or a cast. The
+   *  pane normalizes absent, `undefined` and `null` alike. */
+  error?: string | null | undefined;
 }
 
 export function AgentRunScope({ children }: { children: ReactNode }) {

package/src/card.tsx

@@ -3,6 +3,7 @@ import { StyleProp, StyleSheet, View, ViewStyle } from "react-native";
 import { colors } from "./colors";
 import { Divider } from "./divider";
 import { InfoPopover } from "./info_popover";
+import { useLoticsLocale } from "./locale";
 import { Text } from "./text";
 
 interface CardProps {
@@ -84,13 +85,18 @@ export interface CardHeaderTitleProps {
  * description line. Grows to push siblings (meta, actions) to the right.
  * Tabular numerals so id-like titles (SR-2026-0081) align across a list. */
 export function CardHeaderTitle(props: CardHeaderTitleProps) {
+  // The ⓘ's name comes from the pack, like every other one in the kit
+  // (`section_heading` at all three of its levels). This had the Vietnamese
+  // value of that very slot pasted in as a literal, which typechecks, renders,
+  // and announces Vietnamese to a screen reader in every other tenant's app.
+  const words = useLoticsLocale();
   return (
     <View style={styles.headerTitle}>
       <View style={styles.headerTitleRow}>
         <Text size="sm" weight="semibold" tabular>
           {props.children}
         </Text>
-        {props.info ? <InfoPopover text={props.info} accessibilityLabel="Giải thích dữ liệu" /> : null}
+        {props.info ? <InfoPopover text={props.info} accessibilityLabel={words.sectionHeading.info} /> : null}
       </View>
       {props.description ? (
         <Text size="xs" color="muted">

package/src/card_select_item.tsx

@@ -33,8 +33,13 @@ export function CardSelectItem(props: CardSelectItemProps) {
       aria-pressed={selected}
       onPress={onPress}
       style={(state: PressableHighlightState) => {
-        const active = selected || state.hovered || state.pressed || state.focusVisible;
-        return [styles.container, active && styles.ring, style];
+        // Selection is a GROUND; hover/press/focus are a ring. They used to
+        // share one style, which made the card you had CHOSEN pixel-identical to
+        // the card under the pointer — the same defect 43.5.0 fixed one release
+        // earlier for `Table`'s selected row, and the reason the kit's own
+        // `tpl_lookup` routed around this component with a hand-rolled ground.
+        const ringed = state.hovered || state.pressed || state.focusVisible;
+        return [styles.container, selected && styles.selected, ringed && styles.ring, style];
       }}
     >
       {children}
@@ -56,4 +61,12 @@ const styles = StyleSheet.create({
   ring: {
     ...({ boxShadow: FOCUS_RING } as ViewStyle),
   },
+  // The accent wash + accent edge is the same "you are here" the selected table
+  // row and the active chip carry, so one signal means one thing product-wide.
+  // A ground rather than a heavier outline: among white cards a 1px border
+  // change is noise, and it vanishes entirely under the hover ring.
+  selected: {
+    backgroundColor: colors.accent_wash,
+    borderColor: colors.accent,
+  },
 });

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/control_surface.ts

@@ -38,12 +38,26 @@ export const CONTROL_CONTENT_HEIGHT = 28;
 export const CONTROL_PADDING_V = (CONTROL_HEIGHT - CONTROL_CONTENT_HEIGHT) / 2 - 1;
 
 /** The narrowest a control may be and still be usable — below it, editors get
- *  crushed and option text has nowhere to go. It is the threshold at which a
- *  `DetailTable` gives up its side-by-side columns and stacks, and the floor
- *  under a field popover's width, so "too narrow to use" means one thing across
- *  the kit rather than a number re-picked per component. */
+ *  crushed and option text has nowhere to go. It is the floor under a field
+ *  popover's width, so "too narrow to use" means one thing across the kit rather
+ *  than a number re-picked per component. */
 export const MIN_CONTROL_WIDTH = 160;
 
+/**
+ * The narrowest a record's VALUE column may be before `DetailTable` stops
+ * putting label and value side by side and stacks them instead.
+ *
+ * Deliberately larger than {@link MIN_CONTROL_WIDTH}, because the two answer
+ * different questions. A control's floor asks "can this still be operated"; a
+ * value column's asks "can this still be READ" — and a value column holds
+ * company names, addresses and reference codes, not just controls. Sharing the
+ * control's 160 put the stack threshold low enough that a 375px screen kept its
+ * two columns and handed the value ~170px: a name needing 221 got 104, a tax
+ * code needing 114 got 53. Both halves measured "fine" and the row was
+ * unreadable.
+ */
+export const MIN_VALUE_WIDTH = 200;
+
 /** The system control radius — every interactive control surface (Button, the
  *  inputs/selects/pickers, SearchInput, MenuButton, Tabs, the SegmentedControl
  *  track, and ChipGroup/FilterChip/Chip via the surfaces below) wears it,

package/src/data_grid.tsx

@@ -5,6 +5,7 @@ import { FocusRingPressable } from "./focus_ring_pressable";
 import { Icon } from "./icon";
 import { Text } from "./text";
 import { type SortState, type SortHeaderLabels } from "./sort_header";
+import { FLEX_MIN_WIDTH } from "./table_fit";
 
 export interface DataGridColumn<T> {
   key: string;
@@ -178,7 +179,14 @@ export const gridRowStyle: ViewStyle = {
 
 const styles = StyleSheet.create({
   row: gridRowStyle,
-  flexCol: { flex: 1, minWidth: 0 },
+  // A FLOOR, not `minWidth: 0`. This grid sheds no columns — every column is a
+  // measure you came to compare, which is what separates it from `Table`'s
+  // register of objects — so the fixed columns hold their widths and the
+  // flexible identity column absorbed the entire squeeze. At 0 it absorbed it
+  // all the way to nothing: a narrow container rendered rows of unlabelled
+  // money, silently, with no overflow to notice. Past the floor the grid
+  // overflows and the caller scrolls it; see catalog.md § DataGrid.
+  flexCol: { flex: 1, minWidth: FLEX_MIN_WIDTH },
   head: {
     minHeight: 30,
     borderBottomWidth: 1,