@lotics/ui 44.7.1 → 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 — 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. |
@@ -42,6 +42,16 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
   panel a few hundred pixels wide lays its contents out for the whole display. (A component that
   needs a number rather than a bucket — how many columns fit — measures its own box; `Table`
   does exactly that.) → [catalog.md §Utility hooks](./docs/catalog.md).
+- **No user-facing string is a literal in `src/` when a locale slice already names it.** Every
+  string a component renders resolves prop → `useLoticsLocale()` slice → the pack's English
+  default. Write it as an allowlist, not a hunt: a literal typechecks, renders, and passes a
+  render test in the language it happens to be written in — the kit shipped a Vietnamese ⓘ label
+  to every tenant that way, invisible to a whole suite of vi-pack assertions. Assert a wired
+  string under the OTHER language. → [composition.md §Microcopy](./docs/composition.md).
+- **Annotate every droppable table column, or none.** A partial `priority` is the trap: an
+  unannotated column sorts above the whole hand-written range, so one annotation makes every
+  other column drop first, and one unannotated column among annotated ones goes first however
+  important it is. → [composition.md §The register's own craft](./docs/composition.md).
 - **A section's ADD rides its heading row, right edge** — Add files, Add fee, New line: a
   `primary` `Button` beside `SectionHeadingTitle`, rendered empty or full. Under the rows it
   extends, the verb MOVES with the row count and vanishes off-screen on a long list; a heading is
@@ -62,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/MIGRATION.md

@@ -4,6 +4,112 @@ Breaking changes, newest first — normally per major, plus the rare minor that
 anyway (recorded under its exact version). The current contract lives in `AGENTS.md` + `docs/`;
 this file exists only to move an app from one release to the next.
 
+## 44.8.0 — a value column gets its own floor, and eight defaults stop fighting their own docs
+
+No API is removed. Three of these change what an existing screen renders, so read them even
+though nothing will fail to compile.
+
+**`StepProgress`'s built-in caption is locale-wired, and `LoticsLocale` gains a `stepProgress`
+slice.** A hand-built pack must supply it (both shipped packs already do):
+
+```ts
+stepProgress: {
+  complete: (total) => `Hoàn tất (${total}/${total})`,
+  stage:    (name, index, total) => `${name} (${index}/${total})`,
+  none:     (total) => `0/${total}`,
+  position: (index, total) => `${index} trên ${total}`,
+},
+```
+
+The caption over named stages was built as `Complete (7/7)` / `0/7` in the component, and the
+screen-reader fallback as `4 of 7` — hardcoded English inside a component the kit requires to
+resolve prop → pack → English default. A Vietnamese board read `Complete (7/7)` in its own
+register. Same defect class as the `fileRow`/`sources`/`counter` leak below, and it hid the same
+way: every state renders correctly under `en`, because English is what the bug produces.
+
+Each entry is a FUNCTION rather than a word to concatenate, for the reason the earlier entry
+gives — where the number sits in the sentence is a property of the language, and `position`
+is `4 of 7` against `4 trên 7`. Passing `label` still overrides the caption entirely; nothing
+that already passed one changes.
+
+**`Finding` stacks its `readings` one per line and drops the ` · ` between them.** No prop
+changes; a two-reading finding is now two lines instead of one.
+
+The separator failed twice over. `docs/reviewing.md` bans ` · ` outright — it claims a
+relationship while refusing to name it, and it is the loudest templated-metadata tell there is —
+so an app reaching for the kit's own ranked-insight component failed the kit's own microcopy
+probe with nothing it could do about that. And a middot is the one mark a screen reader drops,
+so the character carrying "these two disagree" never survived being read aloud: exactly the
+defect `CommentsButton` was fixed for. It wrapped badly too — inline + `flexWrap` could start a
+phone-width line WITH the separator, or split a source from its value across lines.
+
+Stacked, each `source value` pair is a row at every width and needs no separator to relate them.
+Pass `readings` shorter values, or move a long one to `detail`, if the extra line costs you
+somewhere tight.
+
+**A `SequenceItem` with no handlers renders no control column.** Reorder/remove controls still
+render disabled where they cannot act — first item, last item, a row that can be removed but not
+moved — because that is what holds the right edge steady between items that are editable. What
+changed is the item that declares NO editing at all: it used to get three permanently dead
+buttons, which is a dead affordance by `reviewing.md`'s own gates, and a read-only sequence (legs
+already run, a route as recorded) is a common shape rather than an edge case. A list where some
+rows are fully locked and others are editable will now step in the right margin; give the locked
+rows a handler if that matters more than the dead controls did.
+
+**`DateStamp` takes `compact`.** Additive, default `false`. It forwards the option `formatDate`
+already had, dropping the year (`08/09`) so the stamp can agree with a neighbouring column the
+caller formats itself. The format stays in `formatDate` — this is a passthrough, not a second
+implementation.
+
+**A `DetailTable` stacks earlier, because a value column's floor is no longer a control's.**
+`minValueWidth` defaulted to `MIN_CONTROL_WIDTH` (160) — the width below which a CONTROL stops
+being operable, which is a different question from the width below which a VALUE stops being
+readable. A value column holds company names and addresses. At 150/160 the stack threshold was
+334, so a 375px screen kept two columns and handed the value ~170px: a name needing 221 got 104.
+The new `MIN_VALUE_WIDTH` (200) is the default; pass `minValueWidth` explicitly to pin the old
+behaviour on a table whose values really are short.
+
+**An unannotated table column's drop priority is `columns.length + index`, not `index`.** An
+unannotated register still sheds right-to-left — that is unchanged and covered by a test — but a
+MIXED table now behaves the way its author meant. Annotating your most important column
+`priority: 1` used to TIE it with the unannotated column at index 1, and the right-to-left
+tie-break then dropped yours first: the amount column, the fact the register exists for,
+disappearing at narrow widths on a screen that reviewed as correctly annotated. **Annotate every
+droppable column or none** — a partial annotation is what the old default punished.
+
+**A selected `CardSelectItem` carries a GROUND**, not the same ring as hover. It was
+`selected || hovered || pressed || focusVisible` → one style, so the card you had CHOSEN was
+pixel-identical to the card under the pointer. Selection is now `accent_wash` + an accent edge,
+the same "you are here" a selected table row and an active chip carry. This is the fix 43.5.0
+made for `Table`'s selected row, one release late.
+
+**`DataGrid`'s flexible column has a floor** (`FLEX_MIN_WIDTH`, 120) instead of `minWidth: 0`.
+This grid sheds no columns by design — every column is a measure you came to compare — so the
+fixed columns held their widths and the flexible identity column absorbed the whole squeeze,
+all the way to zero: a narrow container rendered rows of unlabelled money, silently. Past the
+floor the grid now overflows, and a narrow container needs to scroll it.
+
+**`AgentRunLike.error` is OPTIONAL.** It was declared required while its own docblock promised
+it accepted an SDK run's optional `error` — and an optional property is not assignable to a
+required one however wide the required one's type, so the three-line usage printed in
+`ai_patterns.md` did not compile. **If you worked around it** with a `useMemo` reshape or a cast
+(`{ ...run, error: run.error ?? null }`), delete that: hand the SDK's run straight over.
+
+**`Select` takes the `D` data generic** its siblings already had, so `optionPicker(...)` spreads
+into it without a cast. Additive.
+
+Also additive, nothing to change: `MIN_VALUE_WIDTH` and `FLEX_MIN_WIDTH` are exported (the
+latter via a new `./table_fit` entry point, which also exports `ROW_HEIGHT` and `COLUMN_GAP` so
+a skeleton can be built from the register's own constants); `formatMoney` takes
+`maxFractionDigits` for a genuine per-unit price (`Intl`'s currency style floors at the
+currency's minor unit, so an LCL rate of 0,019 US$/kg printed as `0,02`); `InlineSelect`
+forwards `getOptionDescription` to the two-line option row `OptionList` already renders;
+`NumberInput` takes a `placeholder`; `EmptyState` and `ErrorState` centre their TEXT and not
+only their box (they swap into one another as a read settles, so only one of the two centred
+would have shown up as the copy jumping alignment at the moment a region fails); a
+heading row WRAPS rather than crushing its title; `Accordion`'s meta yields before its title;
+`CardHeaderTitle` reads the ⓘ's name from the locale pack; and `ReferenceField`'s peek footer
+gives its clear the same resting surface as the verb beside it.
 ## 44.5.0 — `Pagination` drops the page index
 
 The pager rendered a range AND a page index — `16–30 of 45` beside `Page 2 of 3`. Both answer
@@ -94,11 +200,10 @@ No API is removed and nothing throws, but four DEFAULTS moved, so every register
 in your app renders differently on upgrade. Each is reversible at the call site if you need the
 old look while you catch up.
 
-**Table column headers are sentence case, not all-caps** — and one ink step lighter
-(`zinc-500`). `Table` and `SortHeader` were uppercasing every column label, which the heading ramp
-bans and names the #1 templated tell. The ink step is not cosmetic and cannot be skipped: at
-`muted` the header matched a row's supporting line in size, weight AND colour, so dropping the
-case alone leaves it reading as a stray label rather than as the band naming the columns.
+**Table column headers are sentence case, not all-caps.** `Table` and `SortHeader` were
+uppercasing every column label, which the heading ramp bans and names the #1 templated tell. What
+keeps the band from reading as a stray label once the case is gone is WEIGHT: the header is
+`sm muted medium`, and a row's supporting line is `sm muted` regular, so the two never collide.
 
 **Row separators are lighter than the header rule.** The band capping a table keeps
 `colors.border`; the hairlines between rows are `zinc-100`. Every rule used to be `border`, which

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
@@ -222,6 +233,13 @@ Two columnar shapes, and the choice is about data size:
   heading, so digits line up under their label; **`DataGridColumn.footer` gives that column its
   cell in the group's footer row** (a subtotal, a resolved measure) — the grid lays it out in
   the column's own box, so a total can never drift from what it sums and no consumer rebuilds
+  **`DataGrid` SHEDS NOTHING at narrow widths, and that is deliberate** — every column is a
+  measure you came to compare, unlike `Table`'s register of objects where the row is an index
+  and the record holds the rest. So it has no `priority` and no stacked mode: fixed columns keep
+  their widths, the flexible column holds a `FLEX_MIN_WIDTH` floor, and past that the grid
+  OVERFLOWS. A narrow container must scroll it horizontally; the floor exists because without
+  one the flexible identity column absorbed the entire squeeze down to zero and the grid
+  rendered rows of unlabelled numbers, silently. If you want columns to drop, you want `Table`.
   the row. `renderGroupFooter` remains for content that does NOT sit in a column (a per-group
   add row). The grid takes exactly its container's width — no outdent to fight, so it needs no
   scroller unless YOU add one. It renders ALL rows (no
@@ -376,7 +394,9 @@ your screen. See the AI-patterns doc indexed in [AGENTS.md](../AGENTS.md) for th
 `ChoiceList` options), `Sources` (provenance chips for AI output — at review scale,
 `label={null}` slots the chips at a section's bottom), `Finding` (one ranked insight from an
 AI check, laid out HORIZONTALLY: a severity dot, the title, and the `delta` right-aligned on
-that same line, over one dim line of `readings` — `source value · source value`, both kept on
+that same line, over the `readings` stacked ONE PER LINE — each `source value`, no separator
+joining them (a middot claims a relation it will not name, and is the one mark a screen reader
+drops), both kept on
 screen with NEITHER marked as the wrong one, since a finding reports that two sources disagree
 and which is right is the reader's call. `detail` is the optional consequence. A reader scanning
 a stack gets severity down the left edge and magnitude down the right. The readings ARE the
@@ -542,6 +562,11 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   one interaction it signals; the padding still comes off the 8-grid, the ring is only
   the floor), `HOVER_BORDER`, `CONTROL_TRANSITION`, `chipSurfaceStyle` — the shared
   control-surface tokens.
+- **`table_fit`** — the register's shared geometry, importable so a skeleton or a
+  hand-built band derives from the same numbers `Table` lays out with: `ROW_HEIGHT` (72),
+  `COLUMN_GAP`, `ROW_GUTTER`, `FLEX_MIN_WIDTH` (120 — what a flexible column needs to stay
+  usable), plus `computeTableFit` itself. `MIN_VALUE_WIDTH` (200 — a record VALUE column's
+  floor, deliberately above a control's `MIN_CONTROL_WIDTH`) lives in `control_surface`.
 - **`fonts.css`** — the Inter sheet (400/500/600, served by absolute URL so it resolves on
   every origin an app runs from); the app entry imports it ONCE or every `Text` falls back
   to system fonts.
@@ -1150,7 +1175,9 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `Destination`) cannot hold a second middle entry and cannot say the entries are ordered.
   `SequenceItem` takes the content, an optional `role` (DERIVE it from index — a stored role lies
   the moment the list is reordered) and `onMoveUp`/`onMoveDown`/`onRemove`; the controls render
-  even where they cannot act so the right edge never shifts between items. Reorder is BUTTONS,
+  even where they cannot act so the right edge never shifts between items — but an item passing
+  NO handler at all renders no control column, so a read-only sequence (legs already run, a route
+  as recorded) is a first-class shape rather than three dead buttons per row. Reorder is BUTTONS,
   not a drag handle — dragging is invisible to the keyboard and fiddly on a phone, and a
   three-to-six position list does not need it. Indent anything that follows the list (an "Add"
   link) by `SEQUENCE_INSET` so it lands on the rail's column. Distinct from `Timeline` (an
@@ -1182,8 +1209,9 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   before acting (amber, announced); **`error`** = field-level failure under the value, danger +
   alert semantics (the `Inline*` editors already render their own transient save errors — don't
   wire both); invalid/cross-field STATE = a co-located `Callout`; **`flat`**
-  on a flat-text value row (`InlineStatic`, plain `Text`) tucks the annotation up by the
-  control band's slack so its gap matches a chip row's.
+  on a value sitting OFF the inline-control grid (a raw node — NOT `InlineStatic` / `InlineSlot`,
+  which are on it) aligns the annotation to it on both axes: drops the control text inset and
+  tucks up by the band's slack.
   The three annotations are ONE anatomy shared with a checklist row's `ChecklistNote` — same
   order, same alert semantics — because a record's field and a task's field are the same thing
   on two surfaces.
@@ -1249,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.
@@ -1257,7 +1309,8 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   panel narrower than the control that opened it reads as belonging to something else. So the
   field truncates its name to one line and the peek's header WRAPS the whole of it: the column
   stays scannable, the full value is one press away. Between the floor and `labelWidth +
-  MIN_CONTROL_WIDTH + 24` a `DetailTable` stacks, which is the right grammar at that width.
+  MIN_VALUE_WIDTH + 24` a `DetailTable` stacks, which is the right grammar at that width — the
+  VALUE floor (200), not the control floor, because that column holds names as well as editors.
   The verbs live INSIDE the
   peek, never on the field, and they are ALL `Button`s at one altitude — a peek is
   dialog-scale and a dialog's verbs are buttons, so mixing weights only made the reader rank
@@ -1311,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
@@ -1350,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
@@ -1374,6 +1450,9 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   position (a group band, a totals line) and the gutter stays blank so the cells beside it stay
   in line. A position is NEVER an identity: sort or filter and row 12 is a different record —
   a stable handle is a column, and it leads the cells. Worked screen: `tpl_item_list`.
+- **`tabs`** — a tab may state its band's size with `TabOption.count`, and needs attention with
+  `TabOption.status` (a `ColorName` dot). Pressing the tab IS the filter, so the count is also the
+  reason to press it. → [composition.md](./composition.md) §"A partitioning control states its band's size".
 - **`table`** rhythm — rows are separated by their own height and the hover wash, never by a hairline; the register's one line is the band capping the columns. 72px rows, overridable per row with `TableRow`'s `minHeight` when a surface genuinely needs density. There is no `spacing` prop: a table of VALUES rather than of objects is a different component (`Matrix`, `DataGrid`). → [composition.md](./composition.md) §"The register's rhythm".
 - **`table` › `TableGroup`** — a titled BAND of rows inside a `Table` (`label`, `count?`, `color?` for a single valence dot). Turns a register that presents records into one that triages them: group by what implies a different ACTION, order the bands by what needs the reader now, and let air rather than a rule separate them. → [composition.md](./composition.md) §"A register that TRIAGES".
 - **`sort_header`** — `SortHeader` + `SortState`/`SortDir` + `cycleSort` + `sortBy` +
@@ -1435,6 +1514,9 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   empty — and a ladder of fields is a form with invisible borders. Reach for `InlineDatePicker`
   when a person is expected to ENTER the date, and this when the system already knows it.
   Empty renders a thin rule, not a placeholder; read-only (omit `onChange`) renders text alone.
+  `compact` drops the year (`08/09`) — the stamp shares a row with dates the caller formats, and
+  the option goes straight through to `formatDate`, which stays the one place deciding what a
+  date looks like.
   `onChange` fires on CLOSE, not on each pick — one commit per visit, and a dismissed panel
   still writes whatever was picked in it, which is what makes a single tap enough.
   Worked screen: `examples/tpl_record.tsx` § Progress.
@@ -1606,7 +1688,9 @@ component rather than showing it at zero.
   status mix on one bar).
 - **`step_progress`** — `StepProgress`: N-of-M dots/segments progress. A real `progressbar`
   (valuenow/min/max) because its segments are decoration over ONE quantity — the opposite
-  case from `stepper`, whose steps carry content a `progressbar` would hide.
+  case from `stepper`, whose steps carry content a `progressbar` would hide. Pass the stage
+  NAMES and it captions itself from the `stepProgress` locale slice ("Hạ bãi (2/4)"); `label`
+  overrides, `captionTone="danger"` is the documented stalled-stage slot.
 - **`breakdown`** — `Breakdown`: a stacked bar + ranked share rows, pressable to drill;
   `maxRows` folds the long tail behind a localized "Show N more" toggle
   (`BreakdownLabels`).
@@ -1632,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`).
 
@@ -2019,7 +2109,9 @@ component rather than showing it at zero.
   column quietly acquires TWO left edges and two baselines, and `DetailRow`'s label (which pads
   down to meet a control) agrees with one kind of row and not the other. `InlineStatic` is the
   STRING case and composes it; reach for the slot when the value is a node, which a review
-  surface always is. NOT for a table cell — a `Table` sets its own row rhythm.
+  surface always is. An ANNOTATED row needs the grid even with no editor in sight, because the
+  annotation stack is inset to a control's words — data_entry.md §The editability affordance
+  has the per-table test. NOT for a table cell — a `Table` sets its own row rhythm.
 - **`use_change_set`** — **`useChangeSet(ids, { initial })`**: the accept/reject/undo
   bookkeeping as a HOOK, zero layout — `status`/`accept`/`reject`/`undo`/`acceptAll`/`reset`,
   `accepted`/`rejected`/`pending`, `keptCount`/`total`/`settled`. Decisions are stored as