@lotics/ui 44.7.0 → 44.8.0

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
 
@@ -222,6 +247,16 @@ spacing distinguishes them.
   offsets is the signature. Fix by bounding the child that varies — never with a cross-axis knob
   (it moves the content and leaves the chrome), and never by resizing the CONTAINER, which changes
   both terms and leaves the spread.
+- **A VARIABLE-width leading slot destroys the column behind it.** A row's lead is sized for an
+  icon; put a chip, a badge or a name in it and every row's title starts at a different x. Collect
+  one repeated cell's `left` down the rows — more than one distinct value and the column does not
+  exist, however aligned each row looks on its own. The spread is small enough to read as
+  sloppiness rather than as a defect, which is why it survives review; the fix is a fixed-width
+  lead, or a register, where columns make it impossible.
+- **Every numeric column: is its unit named anywhere, and is it ONE unit?** Collect the leaf values
+  sharing a right edge, with their size and weight. Identical treatment across values that are not
+  the same KIND of thing — a count beside a currency — is the signature, and the labels beside them
+  do not rescue it. → [composition.md](./composition.md) §"Numbers, money, dates".
 - **A slot holding another component's part must be sized by that component's constant** — a
   24px mark in an 18px column sits 3px outside the surface.
 - **A row beat belongs to the PAGE** — collect every row primitive's height on one screen before
@@ -234,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

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.0",
+  "version": "44.8.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -213,6 +213,7 @@
     "./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/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,

package/src/date_range_filter_field.tsx

@@ -2,7 +2,7 @@ import React, { useMemo, useState } from "react";
 import { View } from "react-native";
 import { Text } from "./text";
 import { colors } from "./colors";
-import { CONTROL_RADIUS, HOVER_BORDER, CONTROL_TRANSITION } from "./control_surface";
+import { CONTROL_HEIGHT, CONTROL_RADIUS, HOVER_BORDER, CONTROL_TRANSITION } from "./control_surface";
 import { Icon } from "./icon";
 import { Button } from "./button";
 import { FocusRingPressable } from "./focus_ring_pressable";
@@ -129,7 +129,14 @@ export function DateRangeFilterField(props: DateRangeFilterFieldProps) {
             flexDirection: "row",
             alignItems: "center",
             gap: 8,
-            paddingVertical: 9,
+            // The height comes from the shared constant, never from padding
+            // tuned against a particular leading. This was `paddingVertical: 9`,
+            // which was exactly 40 against the OLD `sm` 14/20 — then 43.5.0 made
+            // running text 14/24 and the same padding silently became 44, one
+            // control standing 4px proud of every sibling in its band. A ramp is
+            // allowed to move; a control's height is not derived from it.
+            height: CONTROL_HEIGHT,
+            justifyContent: "center",
             paddingHorizontal: 12,
             borderWidth: 1,
             // `colors.border` like every other control — this rested a step

package/src/date_stamp.tsx

@@ -15,6 +15,12 @@ export interface DateStampProps {
   onChange?: (iso: string) => void;
   /** Locale tag for the rendered date. Defaults to the kit's locale. */
   locale?: string;
+  /** Drop the year (`08/09` rather than `08/09/2026`). The stamp sits in
+   *  columns beside dates a caller formats itself, and a year on one side of a
+   *  row and not the other is the kind of mismatch nobody reports and everyone
+   *  notices. Same option `formatDate` takes — the format itself stays there,
+   *  so there is one place that decides what a date looks like. */
+  compact?: boolean;
   accessibilityLabel: string;
 }
 
@@ -44,7 +50,7 @@ export interface DateStampProps {
  * value therefore renders nothing at all.
  */
 export function DateStamp(props: DateStampProps) {
-  const { value, onChange, locale, accessibilityLabel } = props;
+  const { value, onChange, locale, compact = false, accessibilityLabel } = props;
   const localeTag = useLocaleTag();
   const tag = locale ?? localeTag;
   const [hovered, setHovered] = useState(false);
@@ -55,7 +61,7 @@ export function DateStamp(props: DateStampProps) {
   // replaced. This is what the close path reads instead.
   const picked = useRef<string | null>(value);
 
-  const shown = value ? formatDate(value, { locale: tag }) : "";
+  const shown = value ? formatDate(value, { locale: tag, compact }) : "";
 
   // Read-only, or nothing to show and no way to add one: render the text alone
   // so a caller can drop this into a column without a conditional.

package/src/detail_row.tsx

@@ -1,6 +1,6 @@
 import { createContext, ReactNode, useContext, useState } from "react";
 import { StyleProp, StyleSheet, View, ViewStyle } from "react-native";
-import { MIN_CONTROL_WIDTH } from "./control_surface";
+import { MIN_VALUE_WIDTH } from "./control_surface";
 import { SPACE } from "./spacing";
 import { FieldAnnotationProps, FieldAnnotations, hasFieldAnnotation } from "./field_annotations";
 import { INLINE_CONTROL_HEIGHT } from "./inline_edit";
@@ -32,9 +32,9 @@ export interface DetailTableProps {
    *  and custom rows all sit on the inline-control baseline grid. */
   minHeight?: number;
   /** The usable width the value cell must keep before the table STACKS
-   *  (default 160). Raise it when a cell holds MORE than one editor (an
-   *  amount + method pair) — side-by-side columns that technically fit can
-   *  still crush a multi-editor cell. */
+   *  (default {@link MIN_VALUE_WIDTH}). Raise it when a cell holds MORE than one
+   *  editor (an amount + method pair) — side-by-side columns that technically
+   *  fit can still crush a multi-editor cell. */
   minValueWidth?: number;
   /** `DetailRow`s (each inherits the table's columns; row props override). */
   children: ReactNode;
@@ -68,7 +68,7 @@ export interface DetailTableProps {
  * above a full-width value. No prop — the switch is automatic.
  */
 export function DetailTable(props: DetailTableProps) {
-  const { labelWidth = DETAIL_LABEL_WIDTH, minHeight = INLINE_CONTROL_HEIGHT, minValueWidth = MIN_CONTROL_WIDTH, children, style } = props;
+  const { labelWidth = DETAIL_LABEL_WIDTH, minHeight = INLINE_CONTROL_HEIGHT, minValueWidth = MIN_VALUE_WIDTH, children, style } = props;
   const [width, setWidth] = useState<number | null>(null);
   const stacked = width != null && width < labelWidth + minValueWidth + 24;
   return (
@@ -100,12 +100,17 @@ export interface DetailRowProps extends FieldAnnotationProps {
   labelSize?: "xs" | "sm";
   /** Min row height. Default 28 (or the `DetailTable`'s `minHeight`). */
   minHeight?: number;
-  /** The value renders as FLAT text (an `InlineStatic`, a plain `Text`) rather
-   *  than a control-height chip. Annotations then tuck up by the control
-   *  band's slack, so the perceived gap under the TEXT equals the gap under a
-   *  chip — without it, the band's invisible bottom half reads as a hole
-   *  between a static value and its description. Row height and label
-   *  centering are unchanged. */
+  /** The value is a RAW node — a plain `Text`, a figure, a pair — sitting off the
+   *  inline-control grid. NOT `InlineStatic` or `InlineSlot`: those compose the
+   *  grid's own box, so their words already start at the control text inset and
+   *  centre in the band, and `flat` there re-introduces both offsets it exists
+   *  to remove. Annotations then align to the value on BOTH axes,
+   *  because a control's box is what they were offset from and there is no box:
+   *  they tuck up by the control band's slack, so the perceived gap under the
+   *  TEXT equals the gap under a chip rather than leaving the band's invisible
+   *  bottom half reading as a hole; and they drop the control's text inset, so
+   *  the description starts on the value's own left edge instead of nine pixels
+   *  inside it. Row height and label centering are unchanged. */
   flat?: boolean;
 }
 
@@ -160,7 +165,7 @@ export function DetailRow(props: DetailRowProps) {
   // text inset, defined once in `field_annotations` and rendered identically by
   // a checklist row's field. A record's field and a checklist's are the same
   // thing on two surfaces; they may not say a fault two different ways.
-  const annotations = <FieldAnnotations description={description} warning={warning} error={error} />;
+  const annotations = <FieldAnnotations description={description} warning={warning} error={error} flat={flat} />;
   if (table?.stacked) {
     // Stacked mode wears the FORM grammar: the label renders exactly like a
     // `FormField` label (medium, default ink), so a narrow record surface

package/src/empty_state.tsx

@@ -42,11 +42,11 @@ export function EmptyState(props: EmptyStateProps) {
           <Icon name={props.icon} size={28} color={colors.zinc[400]} />
         </View>
       ) : null}
-      <Text size="sm" color="muted">
+      <Text size="sm" color="muted" style={styles.line}>
         {props.message}
       </Text>
       {props.hint ? (
-        <Text size="xs" color="muted">
+        <Text size="xs" color="muted" style={styles.line}>
           {props.hint}
         </Text>
       ) : null}
@@ -63,4 +63,11 @@ const styles = StyleSheet.create({
   icon: {
     marginBottom: 4,
   },
+  // The container centres the BOX; without this the text inside it still sets
+  // left. Invisible while every line is short enough not to wrap — which is
+  // exactly the case a narrow container breaks, leaving a wrapped message
+  // reading left-aligned beside a one-line hint reading centred.
+  line: {
+    textAlign: "center",
+  },
 });

package/src/error_state.tsx

@@ -41,11 +41,11 @@ export function ErrorState(props: ErrorStateProps) {
       <View style={styles.icon}>
         <Icon name="triangle-alert" size={28} color={solid("red")} />
       </View>
-      <Text size="sm" color="muted">
+      <Text size="sm" color="muted" style={styles.line}>
         {props.message}
       </Text>
       {props.detail ? (
-        <Text size="xs" color="muted">
+        <Text size="xs" color="muted" style={styles.line}>
           {props.detail}
         </Text>
       ) : null}
@@ -66,6 +66,13 @@ const styles = StyleSheet.create({
     alignItems: "center",
     gap: 4,
   },
+  // Centred like `EmptyState`'s, and for the same reason: the container centres
+  // the BOX, not the text inside it. These two swap into one another as a read
+  // settles, so a difference here would show up as the copy jumping alignment at
+  // the moment a region fails.
+  line: {
+    textAlign: "center",
+  },
   icon: {
     marginBottom: 4,
   },

package/src/field_annotations.tsx

@@ -45,10 +45,31 @@ export function hasFieldAnnotation(props: FieldAnnotationProps): boolean {
  * they answer different questions ("this is broken" / "this will cost you" / "this is what the
  * field is for"), and hiding the rule that explains the failure is exactly the wrong economy.
  */
-export function FieldAnnotations(props: FieldAnnotationProps) {
+export interface FieldAnnotationsProps extends FieldAnnotationProps {
+  /**
+   * The value above is FLAT text, not a painted control — so drop the control's
+   * text inset and sit on the value's own left edge.
+   *
+   * The inset exists to clear a control's border and padding, which is what puts
+   * an annotation under the value's WORDS instead of under the editor's
+   * invisible box. Under plain text there is no border and no padding to clear,
+   * so the same number becomes pure indent: label, value and description end up
+   * on THREE left edges where the screen only has two things to say. Nine pixels
+   * is small enough to read as sloppiness rather than as structure, and it
+   * appears only on the rows whose value happens not to be a control, so a
+   * column of fields drifts in and out of alignment down its own length.
+   *
+   * Hosts already know which kind of value they hold: `DetailRow` passes its
+   * `flat`, the same flag that tucks the block up by the control band's slack.
+   * One fact about the value, both corrections.
+   */
+  flat?: boolean;
+}
+
+export function FieldAnnotations(props: FieldAnnotationsProps) {
   if (!hasFieldAnnotation(props)) return null;
   return (
-    <View style={styles.stack}>
+    <View style={[styles.stack, props.flat === true && styles.stackFlat]}>
       {props.error != null ? (
         <Text size="xs" color="danger" accessibilityRole="alert" aria-live="polite">
           {props.error}
@@ -73,4 +94,6 @@ const styles = StyleSheet.create({
   // with the editor's invisible box — and the 2px that separates the lines from each other,
   // which is the same rhythm the host puts between the control and this block.
   stack: { gap: 2, paddingLeft: CONTROL_TEXT_INSET },
+  // ...and nothing to clear when the value is flat text — see `flat`.
+  stackFlat: { paddingLeft: 0 },
 });

package/src/finding.tsx

@@ -45,8 +45,8 @@ export interface FindingProps {
   /** What was found, in one line, in the reader's own nouns. */
   title: string;
   /**
-   * The readings that disagree, in source order. Rendered inline beneath the
-   * title as `source value · source value`.
+   * The readings that disagree, in source order. Rendered ONE PER LINE beneath
+   * the title, each as `source value` — never joined by a separator.
    *
    * NEITHER is marked as the wrong one. A finding reports that two sources
    * disagree; which one is right is the reader's call, and a struck-through or
@@ -77,8 +77,15 @@ export interface FindingProps {
 }
 
 /**
- * ONE RANKED INSIGHT from an AI check — a cross-check discrepancy, an audit
- * observation, a briefing item.
+ * ONE RANKED DISCREPANCY from a cross-check — a contradiction between two
+ * readings, an audit observation, a briefing item.
+ *
+ * WHOEVER performed the check. Nothing here is AI-specific — the labels are
+ * four severity words and "difference" — but this opened "from an AI check",
+ * and a rules-derived contradiction (two papers disagreeing, a carrier moving
+ * an ETA) reads as out of scope on that wording. It is not: the next author who
+ * believes it hand-rolls a Callout and loses the ranking, the delta and the
+ * readings line.
  *
  * The readings sit at `sm`, the same size as the title. They were `xs` — a
  * miniature that said "secondary" by being hard to read, which is the wrong
@@ -134,11 +141,6 @@ export function Finding(props: FindingProps) {
           <View style={styles.readings}>
             {readings.map((reading, index) => (
               <View key={`${reading.source}-${index}`} style={styles.reading}>
-                {index > 0 ? (
-                  <Text size="sm" color="muted">
-                    ·
-                  </Text>
-                ) : null}
                 <SourceName label={reading.source} onOpen={props.onOpenSource} />
                 <Text size="sm" weight="medium" tabular numberOfLines={1}>
                   {reading.value}
@@ -189,6 +191,13 @@ const styles = StyleSheet.create({
   // instance — the dot marks the left edge and the figure the right, so a
   // reader scanning a stack gets rank and magnitude in one pass.
   delta: { flexShrink: 0 },
-  readings: { flexDirection: "row", flexWrap: "wrap", alignItems: "baseline", gap: 6 },
+  // ONE READING PER LINE. They were joined inline by a ` · `, which fails twice:
+  // a middot claims a relation while refusing to name it (the templated-metadata
+  // tell `docs/reviewing.md` bans outright), and it is the one mark a screen
+  // reader drops — so the separator carrying "these two disagree" never survived
+  // being read aloud, the same defect `CommentsButton` was fixed for. It also
+  // wrapped: at phone width a line could BEGIN with the separator. Stacking pairs
+  // each source with its own value at every width and needs no separator at all.
+  readings: { flexDirection: "column", alignItems: "flex-start", gap: 4 },
   reading: { flexDirection: "row", alignItems: "baseline", gap: 5, minWidth: 0 },
 });

package/src/format_money.ts

@@ -5,6 +5,12 @@ export interface FormatMoneyOptions {
    * "486 tr ₫". For stat strips/cards where the full figure lives in the
    * table below — never for the table itself. */
   compact?: boolean;
+  /** Significant digits below the currency's minor unit. `Intl`'s currency
+   *  style floors at that unit — 2 for USD — so a genuine per-unit price like
+   *  an LCL rate of 0,019 US$/kg renders as `0,02`: a 5% error, printed as
+   *  fact, with nothing on screen saying it was rounded. Set this on a UNIT
+   *  price; leave it off for a total, where two decimals is the contract. */
+  maxFractionDigits?: number;
 }
 
 /**
@@ -29,10 +35,18 @@ export function formatCompactNumber(value: number, locale = "vi-VN"): string {
  * or the ₫ suffix.
  */
 export function formatMoney(value: number, options: FormatMoneyOptions = {}): string {
-  const { locale = "vi-VN", currency = "VND", compact = false } = options;
+  const { locale = "vi-VN", currency = "VND", compact = false, maxFractionDigits } = options;
   if (compact && Math.abs(value) >= 1_000_000) {
     const suffixed = formatCompactNumber(value, locale);
     return currency === "VND" ? `${suffixed} ₫` : `${suffixed} ${currency}`;
   }
-  return value.toLocaleString(locale, { style: "currency", currency });
+  return value.toLocaleString(locale, {
+    style: "currency",
+    currency,
+    // Raising the MAXIMUM alone is enough, and is what keeps a total looking
+    // like money: Intl holds its own minimum (2 for USD, 0 for VND), so 0,019
+    // gains its digits while 2750 still renders 2.750,00. Unset, both stay at
+    // the currency's own contract.
+    ...(maxFractionDigits != null ? { maximumFractionDigits: maxFractionDigits } : {}),
+  });
 }