@lotics/ui 47.5.2 → 47.6.1

package/AGENTS.md

@@ -16,9 +16,9 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 |---|---|
 | [docs/catalog.md](./docs/catalog.md) | **The complete inventory** — incl. `just_arrived` (`useJustArrived` + `TableRow`'s `justArrived`: the one-shot wash a row wears when it LANDS, so a realtime push is visible rather than one row of two hundred silently changing) — 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) | Which editing pattern for which job — inline edit, fieldset forms, choosing a CHOICE control by option count, find-or-create (`Combobox`), line items, handoffs, phased records, billing, tags, dispositions, attachments (`InlineFiles` for a record ROW, the `FilesEditor` COMPOUND for a whole section, plus the three-way file INTAKE), stage gates, and the commit-on-blur vs action-press ordering law. |
-| [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; findings, provenance, confidence; **after the run** — a stored record that fills up from several writers; the whole run in a dialog, **stopping**; **review surfaces compose from atoms** — `DiffValue`, `DiffMark`, `useChangeSet`. |
-| [docs/composition.md](./docs/composition.md) | The design-language contract — **the form comes before the treatment** (name what the subject IS before reaching for parts), canvas + content column, heading altitude, register vs inset rows, the button ladder, master-detail `Drawer`, the register's rhythm, craft and TRIAGE bands, where the accent goes, theming as an app-level ESCAPE HATCH, color discipline, typography, **one fact one surface** (a chooser over the thing it chooses is a SELECTOR, not a second card grid; a control that only swaps one number for another is replaced by showing both), **a width floor answers can this be READ and never can this be operated** (the operating question passes a row whose every string is already cut), **a status column earns its slot by carrying a REASON rather than a state** (the floor asks for the fact to be visible, not for a badge), **a row subject's supporting line takes a REFERENCE and never a sentence** (an explanation truncates to the clause the reader already knew), **a list stays fast by keeping IDENTITY rather than memoizing** (key by the record not the index; `memo` is the last resort and does nothing against a freshly-built prop), and where a commit sits. |
-| [docs/reviewing.md](./docs/reviewing.md) | **Reviewing a screen you built — and the answer when one "looks bad"** — the other docs say what good looks like; this one says how to find out whether you achieved it. Run it BEFORE the deploy: a typecheck, a lint, a test and `app check` are all blind to how a screen reads. GATES that outrank every treatment question, then the probes, each naming what to COLLECT and the SIGNATURE in the numbers — including the truncation sweep (a row whose halves both measure fine and whose text is cut) the summary-vs-facet check (a strip that keeps describing the unfiltered set) and the derivable-column test (a status badge its neighbour already answers) and the cross-FRAME check (what the screen destroys when a row arrives — the one defect that exists in no single frame). Plus the extraction snippets, what measurement cannot see, and how to act on a finding. |
+| [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; findings, provenance, confidence (`Finding` is filed here because AI produces most of them, NOT because it is AI-only — a rules-derived contradiction is as in scope as an extraction's); **after the run** — a stored record that fills up from several writers; the whole run in a dialog, **stopping**; **review surfaces compose from atoms** — `DiffValue`, `DiffMark`, `useChangeSet`. |
+| [docs/composition.md](./docs/composition.md) | The design-language contract — **the form comes before the treatment** (name what the subject IS before reaching for parts), canvas + content column, heading altitude, register vs inset rows, the button ladder, master-detail `Drawer`, the register's rhythm, craft and TRIAGE bands, where the accent goes, theming as an app-level ESCAPE HATCH, color discipline, typography, **one fact one surface** (a chooser over the thing it chooses is a SELECTOR, not a second card grid; a control that only swaps one number for another is replaced by showing both), **a width floor answers can this be READ and never can this be operated** (the operating question passes a row whose every string is already cut), **a status column earns its slot by carrying a REASON rather than a state** (the floor asks for the fact to be visible, not for a badge), **an identity mark's GLYPH is derived from the name's distinguishing part** (an organization's first word is its legal form, so untreated every row marks one letter), **a row subject's supporting line takes a REFERENCE and never a sentence** (an explanation truncates to the clause the reader already knew), **a list stays fast by keeping IDENTITY rather than memoizing** (key by the record not the index; `memo` is the last resort and does nothing against a freshly-built prop), and where a commit sits. |
+| [docs/reviewing.md](./docs/reviewing.md) | **Reviewing a screen you built — and the answer when one "looks bad"** — the other docs say what good looks like; this one says how to find out whether you achieved it. Run it BEFORE the deploy: a typecheck, a lint, a test and `app check` are all blind to how a screen reads. GATES that outrank every treatment question, then the probes, each naming what to COLLECT and the SIGNATURE in the numbers — including the truncation sweep (a row whose halves both measure fine and whose text is cut) the summary-vs-facet check (a strip that keeps describing the unfiltered set) and the derivable-column test (a status badge its neighbour already answers) the first-line drift a column shows when its cell is sometimes one line and sometimes two, and the cross-FRAME check (what the screen destroys when a row arrives — the one defect that exists in no single frame). Plus the extraction snippets, what measurement cannot see, and how to act on a finding. |
 | [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. |
 
@@ -81,6 +81,19 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
   identity. And a radius is a PROPORTION of the box (`proportionalRadius`), because a component
   sized by data renders as a pill at one height and barely a corner at another.
   → [composition.md §"A body, not an edge"](./docs/composition.md).
+- **A subject over one qualifying line is `CellStack`, never two `Text`s in a `View`.** It owns
+  the whole stacked-pair rule — which rung the caption takes (from what ELSE separates the pair),
+  which lines are tightened, and the zero gap. A hand-rolled pair gets one of the three wrong
+  silently: the excess comes from the LINE BOX, so no margin and no gap exists to explain it and
+  no spacing probe can see it.
+  → [catalog.md §"Lists, tables & registers"](./docs/catalog.md),
+  [composition.md §"Typography"](./docs/composition.md).
+- **An exception a CHECK produced is `Finding`; a state with nothing to contradict it is a
+  `Callout`.** The discriminator is the shape of what was found, never who found it — two
+  readings that disagree plus a magnitude is a `Finding` whether an extraction or a rules engine
+  compared them. Reaching for a Callout on a real contradiction throws away the ranking, the
+  delta and the provenance, and the call site cannot get them back.
+  → [catalog.md §"Status / feedback"](./docs/catalog.md), `src/finding.tsx`.
 - **`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. →
@@ -151,6 +164,12 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
   `detail` + `expanded` reveal the detail beneath the row; keep the drawer for a heavy form.
   → [composition.md §"No dead rows"](./docs/composition.md),
   [catalog.md §"Lists, tables & registers"](./docs/catalog.md).
+- **A register with a TRAILING CONTROL beside multi-line cells passes `Table align="top"`.**
+  Centring is per cell, so one taller cell drops the control below the field it acts on by a
+  data-dependent amount. Without such a control keep the default — centring is what makes a
+  one-line cell sit level with its two-line neighbours rather than stranded at the top.
+  → [composition.md §"No dead rows"](./docs/composition.md),
+  [reviewing.md probe 8d](./docs/reviewing.md).
 - **ONE LEFT EDGE — a row that paints a wash BLEEDS it, and never insets its content.**
   `marginHorizontal: -ROW_WASH_BLEED` absorbed by an equal `paddingHorizontal` is net zero, so
   a row's content sits on its container's own edge. **An indent is legible only when something

package/MIGRATION.md

@@ -101,7 +101,68 @@ exported for anything that needs the same lane geometry.
 There are deliberately **no dependency connectors**. Lane order and bar position already carry
 the sequence, and elbow arrows over an already-ruled grid restate it as line noise.
 
+## 47.0.0
+**`Text`'s `color` drops every palette name, and `inverted` becomes `onInverse`.** The vocabulary
+is now seven ROLES and no shades: `default`, `muted`, `inactive`, `onInverse`, `danger`, `warning`,
+`success`. `zinc-900` / `zinc-700` / `zinc-500` / `zinc-400` no longer typecheck.
+
+```diff
+-<Text color="zinc-500">{caption}</Text>
++<Text color="muted">{caption}</Text>
+-<Text color="inverted">{label}</Text>
++<Text color="onInverse">{label}</Text>
+```
+
+Map them: `zinc-900` → `default` (it was the same ink under a second name), `zinc-700` and
+`zinc-500` → `muted`, `zinc-400` → `inactive`. **Text previously set to `zinc-500` gets slightly
+darker**, which is the point — it clears AA on white by 0.33 (4.83:1) and FAILS on `zinc-100`, the
+kit's own selected-row ground, at 4.40:1, for text at `sm`/`xs` where the bar is 4.5. A call site
+naming a shade cannot know which ground it will land on; a role is resolved once against the
+darkest ground the kit paints. `text_ink_contrast.test.ts` now asserts this for every ink, over a
+list the `TextColor` type is DERIVED from, so a new ink cannot ship unchecked.
+
+`inverted` → `onInverse` names the GROUND rather than the operation: it is the one ink that is
+illegal on the canvas, and the contract a caller needs is "there must be a dark surface under this".
+
+**`TextColor`, `getTextColor` and `TEXT_COLORS` moved** from `@lotics/ui/text_utils` to
+**`@lotics/ui/text_ink`**, which is react-native-free so `@lotics/ui/tokens` can be imported by an
+app that hand-rolls plain DOM. `text_utils` keeps the input-metrics exports.
+
+**New: the ink vocabulary is addressable.** `TEXT_INK` is an alias table (`muted` → `zinc.600`),
+`textInkTokens()` serializes both layers in the W3C Design Tokens format with the alias intact for
+a Figma Variables import, and `getCssVariables()` gains `--lotics-ink-*` pointing at the primitive
+var rather than copying its value.
+
 ## 46.3.0
+**Six components lay themselves out differently at NARROW widths, and the three charts no longer
+claim their host's height.** No type changes and nothing to edit — but each of these was invisible
+at 1280 and therefore invisible to the width most reviews measure, so a screen you signed off at a
+desk width may look different on a phone now (better, is the intent).
+
+- **`Tabs` scrolls.** The strip was a plain row with no wrap and no scroller, so once the options
+  exceeded the container the trailing tabs were cut by whatever clipped the surface — a tab band
+  partitions a register, so on a phone a whole band was unreachable. It is now a horizontal
+  `ScrollView`. If you wrapped `Tabs` in your own scroller, delete yours; nesting two is what
+  makes a strip that scrolls in one direction only.
+- **`BarChart`, `LineChart` and `PieChart` are content-sized.** All three declared `flex: 1` on
+  their root, which RN-Web resolves to a zero basis on the parent's main axis — so dropping one
+  into a card body (a vertical stack) collapsed it to no height and painted its fixed-height
+  content outside the card. `Funnel` and `Breakdown` were content-sized all along. **If you
+  neutralised this by wrapping a chart in a row, that wrapper is now unnecessary**; a chart that
+  should fill a box is told so on the box.
+- **`SectionHeading`'s actions wrap as ONE group.** With two verbs, one stayed on the title row
+  and the other dropped to the next at a different indent, so a single action group rendered as
+  two unrelated controls. Two or more trailing children are now wrapped in one row that moves
+  together, and the heading top-aligns so that group rides the title's FIRST line instead of the
+  centre of a column whose height came from however many lines the description wrapped to. One
+  trailing child keeps the previous geometry exactly.
+- **`Finding`'s headline stacks at narrow widths.** Side by side, a title long enough to wrap
+  broke AROUND the delta and the sentence read as two fragments with a number interposed. It
+  never overflowed — it only wrapped mid-sentence — so no clipping probe saw it.
+- **`PageHeader`'s description sits with the title, above the actions.** It rendered after the
+  whole title row, and that row wraps, so at narrow widths the reading order became title → verbs
+  → the sentence explaining them. `actions` was effectively unusable on any header with a
+  `description`.
 
 **A `Text` with `numberOfLines` now declares `flexShrink: 1` + `minWidth: 0` for you.**
 A clamp that cannot shrink cannot clamp: on web a clamped `Text` is `white-space: nowrap`, so
@@ -189,7 +250,6 @@ so `status` changes identity whenever a decision does — which a screen that me
 `review.status` needs, and which a predicate held out of the dependency lists could not give.
 
 ## 46.0.0
-
 **`AgentRun` / `AgentProgress` drop `stepsLabel`, and the `agentRun` locale slice drops `steps`.**
 The run row no longer prints a step count — not on the folded run row, not on a settled
 `ToolGroup` header. The tally was a number a reader could act on in no way: while the run is live
@@ -216,7 +276,6 @@ now share a name once the work is expanded (the run row and the step it was name
 `getAllByLabelText(...)[0]` over `getByLabelText` there.
 
 ## 45.9.0
-
 **`BrandMark` no longer carries product logos, and `SwitchButton` takes `leading` instead of
 `brand`.** `BRAND_NAMES` drops `gmail`, `outlook` and `google-drive`; the kit's marks are the
 single-colour CC0 silhouettes that NAME a channel — `facebook`, `zalo`, `linkedin`, `x`,
@@ -234,7 +293,6 @@ A retired name no longer typechecks, and a bundle compiled against an older kit
 where the mark was rather than throwing.
 
 ## 45.5.0
-
 **`InlineSelect` and `InlineMemberSelect` are a `combobox`, not a `button`.** They rest as a
 `<div role="combobox">` carrying `aria-expanded`, where they rested as a `<button>`
 (`InlineMemberSelect` is built on `InlineSelect`, so it follows). Other inline fields are
@@ -273,7 +331,6 @@ owners, since ticking the box also opened the file. A slot the docs tell you to
 cannot be inside the control.
 
 ## 45.0.0 — a section heading stops shouting over the panel that holds it
-
 *A MAJOR, because an export was removed.* Every consumer pinning `^44.x` is excluded by design:
 the removal below breaks a build, and the altitude change silently re-ranks headings in any pane
 that already composes its body in a content region. Neither should arrive with a routine install —
@@ -330,7 +387,6 @@ sat a rung AND a weight below its own peers, measured live as 12px/400 beside 14
 structural role, same treatment.
 
 ## 44.9.3 — an option's description stops being erased, and a pivot's headers rejoin the ramp
-
 **`OptionList` no longer suppresses `getOptionDescription` when `renderOptionContent` is set.**
 The two are independent facts about an option — how its value renders, and a subtitle under it —
 and one was erasing the other. A caller who wanted both had one slot for two things, so they put
@@ -347,7 +403,6 @@ reading as a caption that lost its value."* A screen carrying both a `Table` and
 rendered the same structural role two ways.
 
 ## 44.9.3 — the rules probe could not see a rule
-
 **`docs/reviewing.md`'s probe 3 collector missed border-drawn rules and counted transparent
 spacers.** Docs only, no code change — but this is the method app authors run, so it shipped a
 blind spot: it selected on "thin and wide" with no paint check, which counts a zero-height flex
@@ -361,7 +416,6 @@ edge rather than the box origin, and reports what each rule SEPARATES — which
 actually asks.
 
 ## 44.9.2 — a pivot's figures actually align, and a ledger row keeps its own name
-
 **`Matrix.Grid`'s cell stretches its figure instead of centring it, so 44.9.1's right-alignment
 actually applies.** A `Text` centred by its parent shrink-wraps, so the `align="right"` added in
 44.9.1 had nothing to align against and the value cells never moved — while the headers and totals,
@@ -393,7 +447,6 @@ own code; that is the component's job.
 for one line.
 
 ## 44.9.1 — a pivot's figures align, and a ledger row stops losing its own name
-
 No API is removed and nothing fails to compile. Three renders change.
 
 **`Matrix` right-aligns its figures instead of centring them.** Every value, column
@@ -426,7 +479,6 @@ keeps 55 and the caption 16. Any caller that dropped `meta` at small widths to d
 can stop.
 
 ## 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.
 
@@ -532,7 +584,6 @@ heading row WRAPS rather than crushing its title; `Accordion`'s meta yields befo
 `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
 "where am I", and the second enables no decision the first does not: how much is left is in the
 total, and whether this is the end is in the disabled arrow. The index is gone; the range is the
@@ -555,7 +606,6 @@ total, so a `Table` paired with the pager takes **`counted`** instead of `count`
 the matched total prints twice a few rows apart.
 
 ## 44.4.0 — `MemberChip`'s `marker` is gone
-
 A minor that broke a type, recorded here under its exact version rather than held
 for a major: `marker` existed for one release, had a single consumer inside the
 kit, and underlined the chip's name to say "this opens something".
@@ -578,7 +628,6 @@ requested `md`), because two lines of text stand taller than a 28px avatar. Sing
 beside a two-line chip will need the number.
 
 ## 44.0.0 — `Finding` is horizontal, and `FindingComparison` is gone
-
 `Finding` stacked six blocks — badge, title, detail, a labelled row per side, a hairline, the
 delta, then `Sources` chips. It spent roughly 200px to say one sentence and one figure, buried
 the delta in the middle where nothing scans it, and named every source twice: once in the
@@ -616,7 +665,6 @@ composes. Readings render at `sm` rather than `xs` — they are the values the f
 and hierarchy comes from weight and colour, never from shrinking the evidence.
 
 ## 43.5.0 — registers, type and theming all change appearance
-
 No API is removed and nothing throws, but four DEFAULTS moved, so every register and every avatar
 in your app renders differently on upgrade. Each is reversible at the call site if you need the
 old look while you catch up.
@@ -708,7 +756,6 @@ prop (`"open"` — no gallery), `Avatar`'s `shape` prop, and the `avatar_tone` /
 `avatar_props` / `type_ramp` modules.
 
 ## 43.3.0 — a `bare` inline field sits on the column, and Enter finishes a one-line one
-
 Two fixes to `Inline*`, both of them behaviour a caller cannot see in a prop name.
 
 **A `bare` field now aligns its TEXT, not its box.** The field surface carries 8px
@@ -739,7 +786,6 @@ paragraph break and blur saves, exactly as before. **If you wrote
 line budget** — that is now what says so.
 
 ## 43.0.0 — a time is PICKED, and there is nothing to type
-
 `TimePicker` is no longer a segmented text field. It is the value on a pressable
 control — the bordered surface a `Select` uses — that opens an **hour / minute /
 day-period** picker. `InlineTimePicker` is the same thing on the inline shell.
@@ -813,7 +859,6 @@ needs the pointer, set `CURSOR_ACTION` in its style — and if it is built on th
 react-native `Pressable`, note that the pointer is what you get by DEFAULT, from
 react-native-web, unless you set `CURSOR_DEFAULT`.
 ## 42.5.0 — an expanded `Timeline` row shows its whole label
-
 The label was clamped to two lines whether the row was open or shut. Expanding a
 row is a request to see more of what is there, so a label that stays truncated
 through it leaves the caller exactly one way to make its own label readable:
@@ -826,7 +871,6 @@ Nothing else changes: a collapsed row is identical, and a row whose label alread
 fitted in two lines is identical open or shut.
 
 ## 42.4.0 — `Picker` is named by its `FormField`, and its way back to empty has a name
-
 Two fixes to the same control, both about a thing on screen that the control did
 not actually say.
 
@@ -867,7 +911,6 @@ site passing `placeholder` **as** the empty option's name should move that strin
 which is why they were all rendering blanks.
 
 ## 42.0.0 — `DateFilter`'s presets are a listbox, and "Custom" is not one of them
-
 Three defects with one root: the preset row used EMPHASIS to mean "current state", inside a
 panel where emphasis means "action".
 
@@ -901,7 +944,6 @@ object you pass — it is an excess property now and the compiler will point at
 matches no preset simply leaves every row unselected, which is what it always meant.
 
 ## 41.4.0 — embedded markdown is demoted in the OUTLINE, not only on the type ladder
-
 `<Markdown variant="embedded">` sized its headings down and left them as the tags the author
 wrote, so an `h2` inside a record value still landed in heading navigation as a PEER of the
 page's own sections. Measured on a record surface, the outline read:
@@ -918,7 +960,6 @@ a section's level. **Nothing to migrate** — document-scale markdown is untouch
 embedded type scale is unchanged.
 
 ## 41.3.0 — `Timeline` rows, embedded markdown, and a disclosure that is not a link
-
 Nothing here removes an API or breaks a type. Two of the changes alter what your rows render on
 sight; the rest is additive.
 
@@ -1001,7 +1042,6 @@ Anything that MUTATES still carries a control surface — `Button` in chrome, `I
 field. Nothing to migrate: existing `Link`/`TextLink` usage is unaffected.
 
 ## 41.1.0 — `FileRows` no longer captions every row with the file type
-
 `meta` defaulted to the file-type label, so a row read `contract.pdf` with `PDF` under it. The
 type was already stated three other ways — the `FileBadge`'s colour, the label printed inside
 that glyph, and the filename's own extension — so the caption was a fourth statement of one
@@ -1024,7 +1064,6 @@ Better: pass something the NAME does not already carry — what an invoice cover
 it, when it landed. That is what a second line is for.
 
 ## 41.0.0 — `RingGauge` is `ProgressRing`, and circular progress is one component
-
 `RingGauge` is **deleted**. `ProgressRing` replaces it and covers both what it did and the
 bare arc it could not.
 
@@ -1066,7 +1105,6 @@ decoration inside a labelled control, and it means a bare ring must never be the
 carrying a meaning — whatever owns it says what it measures.
 
 ## 40.0.0 — `PopoverContent` decides its own presentation; `small` is gone
-
 `PopoverContent` took a `small` prop meaning "render as a bottom sheet". It now asks
 `useScreenSize()` itself. **Delete the prop** — passing it is a type error.
 
@@ -1095,7 +1133,6 @@ remains exported for its real uses — deciding whether a surface is a `Dialog`
 at all, sizing touch targets, showing a keyboard shortcut.
 
 ## 39.0.0 — `PageHeader.leading` is `trailing`, and it renders AFTER the title
-
 38.0.0 shipped `leading`, a slot before the title. It is now **`trailing`**, in the same
 place in the props but rendered on the other side of the title text.
 
@@ -1120,7 +1157,6 @@ The layout law is unchanged and now covers both: the TITLE gives way and wraps,
 `trailing` and `actions` keep their width.
 
 ## 38.0.0 — the `lg` avatar is a control (40), not a size (48)
-
 `AVATAR_PX.lg` was 48 and `AVATAR_TEXT.lg` was `lg` type. They are now **40** and `md`
 type. Every `size="lg"` avatar — `Avatar`, `MemberChip`, `GroupAvatar` — renders 8px
 smaller. Nothing to pass; there is no way to ask for 48.
@@ -1148,7 +1184,6 @@ a title, hiding the CTA at narrow widths, or capping the header's width, that wo
 is now what is distorting the layout — drop it.
 
 ## 37.0.0 — `PageContent`'s side gutter is a token, and responsive
-
 `PageContent` padded `16` at every width. It now uses `pagePad` from
 `@lotics/ui/spacing` — **16 on a phone, 32 wider**. Nothing to pass; the only visible
 change is that a wide page breathes where it used to sit 16px off the chrome.
@@ -1175,7 +1210,6 @@ whether `PageContent` would do — it carries the centred `maxWidth` column and
 title band most screens re-type by hand.
 
 ## 36.0.0 — seven components stopped announcing English; their strings moved to the pack
-
 **Nothing to change if you pass a shipped pack** (`en` / `vi`) — both carry every
 new entry, and no component API changed. A HAND-BUILT pack must add them:
 
@@ -1229,7 +1263,6 @@ If a surface of yours is genuinely not a button, say so (`accessibilityRole="lin
 …) — or reach for `PressableRow`, which carries no role by design.
 
 ## 35.0.0 — `FilterChip` has no Clear footer; the × is the clear
-
 `FilterChip` no longer renders a Clear button in its popover footer. **Nothing to
 change at a call site** — `onClear` and `clearLabel` are unchanged, and the × on
 the pill still clears, still carries `clearLabel` as its tooltip, and still
@@ -1258,7 +1291,6 @@ controls with no per-option deselect), put one in the `footer` slot, which is
 still there and is now the only thing that draws a footer band.
 
 ## 34.0.0 — one avatar rung fits a control band
-
 **`AVATAR_PX.md` is 28, not 36.** Nothing to change at a call site — `md` is still
 the default and still shows two initials — but every `Avatar`, `MemberChip` and
 `GroupAvatar` on that rung renders 8px smaller (its initials drop a type rung with
@@ -1302,7 +1334,6 @@ Two knock-on effects worth looking at once:
   It always claimed to; it was 2px more padded, invisible at one line.
 
 ## 33.0.0 — `DrawerScrollArea`
-
 A `Drawer` gets the content primitive its siblings already had, named to match
 `DialogScrollArea`. **Wrap your drawer body in it and delete the padding you were
 applying:**
@@ -1343,7 +1374,6 @@ Import `DRAWER_GUTTER` in both cases; a hardcoded `20` stops matching the day it
 moves.
 
 ## 32.0.0 — `Table`'s `align` prop is gone; rows are centred
-
 `align?: "center" | "top"` and the `TableAlign` type are removed. `center` was the
 default and nothing shipped on `top`, so a caller passing nothing is unaffected.
 
@@ -1364,7 +1394,6 @@ stack — `computeTableFit` already drops to stacked below the register floor. R
 that, or move the content to a record page. Do not reintroduce a cross-axis knob.
 
 ## 31.0.0 — avatar `size` is a rung, not a pixel count
-
 `Avatar`, `MemberChip` and `GroupAvatar` no longer take `size?: number`. They take
 `size?: AvatarSize` — `"sm" | "md" | "lg" | "xl"` = **24 / 36 / 48 / 72** — defaulting to `md`.
 
@@ -1405,7 +1434,6 @@ The initials' TYPE SIZE now follows the rung instead of being a fixed `xs`. Most
 large rungs: an avatar that was 80px wore 12px letters and looked empty; at `xl` it wears 28px.
 
 ## 30.0.0 — a washed row bleeds; content sits on the container's edge
-
 No API changed. Every register, table and choice list **moves its content 20px
 left** onto its container's own edge, because `PressableRow` (all three
 variants), `ChoiceList` and `Table` now bleed their hover/selection wash outward
@@ -1428,7 +1456,6 @@ padding, so a column that used to drop at a given width may now survive. Nothing
 that was visible becomes hidden — the change only ever un-drops.
 
 ## 29.0.0 — review surfaces compose from atoms
-
 `ChangeReview` and its family are DELETED, replaced by three layout-free pieces. The
 `change_review` export and the `changeReview` locale slice are gone. Apps pinned to 28.x are
 unaffected until they upgrade.
@@ -1454,7 +1481,6 @@ The opinionated stack is not gone, it is demoted: build it in your own screen fr
 Every app needed a slightly different shape, which is why one container could not serve them.
 
 ## 28.2.0 — `SubsectionHeadingTitle` takes a `description`
-
 Additive; nothing to change. The heading ramp's three rungs are meant to carry the SAME slots
 and differ only in type size — `description` was missing from the middle one, so a group that
 needed a muted line under its title had to borrow the section rung above it or hand-roll a
@@ -1474,7 +1500,6 @@ a dropped file says which bucket it belongs to) carries those regions at subsect
 The rung is unchanged (`###`, lg semibold, level 3) — only the slot is new.
 
 ## 28.1.0 — `ChecklistItem` can announce more than its title
-
 Additive; nothing to change. `accessibilityLabel` overrides the row's accessible name, which
 still defaults to `title`. It exists for a surface carrying one checklist PER person, party or
 period, where the same row labels repeat and only the headings between them tell the copies
@@ -1488,7 +1513,6 @@ and always about a CONTROL's text rather than a step's, which is why it did not
 of `task` into `checklist`.
 
 ## 28.0.0 — `task` and `pipeline` merge into `checklist`
-
 Two families had converged on one anatomy: a ring, a title, a value beside it, a muted note, a
 detail block, an optional grouping level. What differed was a LINE between the rings — a mode,
 not a family. The proof: a single session added `trailing`/`meta` to `TaskTitle` **and**,
@@ -1552,7 +1576,6 @@ it, and the rungs it passes show a BLANK date, which is the honest answer to "wh
 others.
 
 ## 27.15.0 — a register row's text is selectable, and a drag no longer opens the record
-
 No API change, but two behaviors changed on **every** `PressableRow` / `TableRow` / `PressDoor`
 in every app:
 
@@ -1572,7 +1595,6 @@ reads as a selection, not a press. Programmatic `fireEvent.click` / `press()` ar
 The shipped `en` / `vi` packs carry it; a HAND-AUTHORED pack must add it or it will not typecheck.
 
 ## 27.13.3 — a stacked `Table` row's identity cell no longer renders its column label
-
 No API change, but the rendered output changed on NARROW containers only (below the
 two-column floor, where `Table` stacks). The identity cell — column 0 — used to render as a
 `DetailRow` spread like every other cell, so its column label appeared beside the value. It
@@ -1591,7 +1613,6 @@ and it had nowhere to go: a label and a full-width identity on one line with not
 made the label collapse under a long value, which is what a narrow register used to render.
 
 ## 27.4.0 — a `Select` trigger announces as `combobox`, not `button`
-
 No API change, but the DOM and the accessibility tree changed, so **a test or script that
 finds a Select by its button role must be updated**:
 
@@ -1611,7 +1632,6 @@ Note for `searchable`: `OptionList`'s filter input is a combobox too, so scope s
 to the trigger (or use `.first()`) rather than assuming one match per Select.
 
 ## 27.2.0 — a `LedgerGroup`'s sum moved below its rows
-
 No API change; the rendering moved. A summed group used to print `LABEL … sum` as an eyebrow
 ABOVE its rows and now closes them: the rows come first, then `Label   sum` at `sm/medium`,
 with no eyebrow (the label travels with the sum instead of being said twice).
@@ -1623,7 +1643,6 @@ bare rather than grouping it (a one-row group's sum only restates the row). Omit
 remains fully supported for a statement whose groups all name categories without summing them.
 
 ## 27.0.0 — `TextButton` is REMOVED; an act carries a control surface
-
 **`@lotics/ui/text_button` is gone, with no replacement component.** It was the wrong
 abstraction, and 25.0.0 had already retreated from it inside `ReferenceField`.
 
@@ -1661,7 +1680,6 @@ two rungs — `Button` (40px, a surface) and `InlineButton` (28px, filled, on a
 on a value whose press opens a peek — were never this component's job and keep working.
 
 ## 26.0.0 — a section's ADD moves to its heading row; `EmptyState` loses its verb
-
 **`EmptyState.action` is REMOVED — no replacement on that component.** Two different things
 were going into it, and neither belonged:
 
@@ -1712,7 +1730,6 @@ whose title row carries an inline control. Hand-rolling that row leaves the mark
 text line while the label centres in the taller row, so every label reads ~10px low.
 
 ## 25.0.0 — `ReferenceField` edits in place; `onRemove` becomes `onClear`
-
 **`onRemove` is now `onClear` — a pure rename, identical behaviour.** The act was always
 "detach and leave it empty"; only the VERB was wrong. Named "Remove" and coloured `danger`, a
 recoverable unset wore the ink reserved for destruction. Rename the prop and nothing else
@@ -1750,7 +1767,6 @@ on the left act on the LINK, Edit and Open on the right act on the RECORD, Edit
 filled-dark rung and handing it to Save when the draft opens.
 
 ## 24.0.0 — `TextLink` navigates, `TextButton` acts
-
 ```tsx
 <TextLink onPress={selectAll}>Select all</TextLink>     // BEFORE
 <TextButton onPress={selectAll}>Select all</TextButton> // AFTER — same look, role=button
@@ -1787,7 +1803,6 @@ by construction and keeps a 40px target via `hitSlop`. Do NOT reach for a fill-l
 padding, so it reads as indented against the labels it should line up with.
 
 ## 23.0.0 — the `Inline*` editors are WHITE, and `variant` is renamed
-
 ```tsx
 <InlineSelect variant="cell" … />   // BEFORE
 <InlineSelect variant="bare" … />   // AFTER — same axis, named for the LOOK not the use
@@ -1824,7 +1839,6 @@ Row hover on a dense surface is unaffected: a `TaskItem`/`PressableRow` still wa
 What changed is only what the editor inside it looks like at rest.
 
 ## 23.0.0 — `DetailRow.trailing` and `DetailTable.trailingWidth` are DELETED
-
 A row's third column is gone; a `DetailTable` is label + value, and the value fills what the
 label leaves. `InlineButton` (`@lotics/ui/inline_button`) is the replacement for the case that
 mattered.
@@ -1872,7 +1886,6 @@ Porting, by what the slot held:
 (`description` / `warning` / `error`).
 
 ## 23.0.0 — `LinkedRecordBox` is DELETED; a reference is a field
-
 ```tsx
 // BEFORE — a bordered card, its own section, three surfaces for one name
 <LinkedRecordBox
@@ -1927,7 +1940,6 @@ Porting, piece by piece:
 `tpl_record`'s Customer and Handoff sections are the worked examples.
 
 ## 22.0.0 — `RangeSlider` is `Slider`, and single-value is a mode on it
-
 ```ts
 import { RangeSlider, rangeSummary } from "@lotics/ui/range_slider";   // BEFORE
 import { Slider, rangeSummary } from "@lotics/ui/slider";              // AFTER
@@ -1958,7 +1970,6 @@ the DOM as a bare `role="slider"` with no value, so a screen reader read "slider
 `View` in both targets. A test asserting the old (absent) attributes was asserting a bug.
 
 ## 21.2.0 — `Stepper` is a list, not a progressbar
-
 No API changed, but the RENDERED role did, so a test that queried it breaks:
 
 ```ts
@@ -1974,7 +1985,6 @@ positions is a `list` whose live entry has `aria-current="step"`. `StepProgress`
 values it was missing.
 
 ## v21 from 20.x
-
 **`FilesEditor` is a COMPOUND.** It rendered a fixed toolbar — Upload, Select, Download all,
 swapping into a select-mode row whose actions hid behind a generic "Menu" — and that shape cost
 two things in real screens. A HOST verb had nowhere to go, so a surface that needed one (an AI
@@ -2031,7 +2041,6 @@ function ReadWithAi() {
 ```
 
 ## v20 from 19.x
-
 **`@lotics/ui/section` is DELETED.** Two modules exported a `Section` — the layout grammar's
 card-less region (`section_heading`) and a standalone titled block with its own `title` string,
 `collapsible` flag and imperative `SectionHandlers.expand/collapse`. The second one predated both
@@ -2065,7 +2074,6 @@ Compose the heading rung exactly as for a static section — `SectionHeadingTitl
 carries the same slots, so a disclosure header loses no affordance.
 
 ## v19 from 18.x
-
 **`TaskFields` is DELETED, with `fieldsWidth`.** A task row was carrying a
 value COLUMN — a width declared on the list and reserved by every row. It aligned, and it read
 badly: a two-word field name sat at the title's origin while its control started a quarter of
@@ -2131,7 +2139,6 @@ wrap against), and `TaskDetail` now ends on the content edge instead of overhang
 inset.
 
 ## v18 from 17.x
-
 **`TimePicker` is a segmented field, not `<input type="time">`.** A native time input takes
 its 12- vs 24-hour form from the BROWSER's UI locale and ignores the `lang` attribute
 entirely, so a Vietnamese screen on an en-US browser rendered "01:45 PM" beside its own
@@ -2151,7 +2158,6 @@ The value is unchanged — canonical 24-hour `"HH:mm"` either way. Two prop chan
 than spreading the locale pack) must add it.
 
 ## v17 from 16.x
-
 **`Checklist` / `ChecklistRow` are DELETED.** They are replaced by the `Task` compound
 (`@lotics/ui/task`), which composes the anatomy instead of configuring it:
 
@@ -2198,7 +2204,6 @@ it through (`state={s.status === "done" ? "done" : s.status === "doing" ? "parti
 rather than leaving the ring binary.
 
 ## v16 from 15.x
-
 **`Confidence` IS now a callout with a REQUIRED basis** — `children` (what was checked and
 what came of it) is mandatory, the meter + level phrase head the block, and the box stays
 white with a hairline border at every level (the meter is the only colored element). The
@@ -2211,7 +2216,6 @@ Additively in v16: `ResultHeader` (`@lotics/ui/result_header`) — the save-dire
 outcome strip; see ai_patterns §the one law for the receipt composition.
 
 ## v15 from 14.x
-
 `AgentRun`/`AgentProgress`'s **`labelForTool`** prop was replaced by **`labelForCall`** — the
 callback now receives the whole call (`AgentToolCall = { toolName, input, state }`) instead of
 just the name, so labels can vary by input and by the new **`awaiting`** step state (ai's
@@ -2220,7 +2224,6 @@ an expanded step's Output panel), `onRetry` (a retry button under the terminal e
 the new `ApprovalPrompt` + `MessageActions` components with their locale slices.
 
 ## v14 from 13.x
-
 The ai-sdk `UIMessage.parts` shape IS the `AgentRun` contract — the bespoke transcript type is
 gone. `AgentRun`/`AgentProgress`'s **`items: AgentRunItem[]`** was replaced by **`parts:
 readonly AgentUIPart[]`**, and the **`AgentRunItem`** / **`AgentRunStep`** / **`AgentStepStatus`**
@@ -2232,7 +2235,6 @@ parts. Additively: a run-level **`error`** prop for the BREAKING failure that li
 — and tool I/O now expands IN PLACE on press instead of opening a `Peek` popover.
 
 ## 13.9.0 — a BREAKING type change in a MINOR
-
 **`ClarifyOption.description` went optional → REQUIRED** (every answer explains itself). It
 shipped in a minor, which is why it surprises an app on `^13`: a `<Clarify options={…}>` whose
 options carry only `label` stops typechecking on any 13.9.0+ install. Fix by writing the
@@ -2241,14 +2243,12 @@ eyebrow was dropped (the question text stays), and `allowCustom` ("Other…" fre
 `ClarifyWizard` were added.
 
 ## v13 from 12.x
-
 `RadioPicker`'s **`direction`** prop was removed — the picker is always the stacked column of
 full-width choices. A former `direction="row"` usage just drops the prop. Additively, `DetailRow`
 and `FormField` gained a **`warning`** field annotation (amber, the third tone between
 `description` and `error`).
 
 ## v12 from 11.x
-
 Two exports were removed: **`CommentComposer`** (compose comments with THE kit `Composer` —
 attach via `actionsButton`/`files`; `CommentList` is unchanged) and **`DetailRow.info`** (field
 annotations are explicit — use the new **`DetailRow.description`** under the value and
@@ -2262,7 +2262,6 @@ resting chip gained 6px vertical padding (identical for one-line values; multi-l
 content now breathes).
 
 ## v11 from ≤10.x
-
 The type scale was re-slotted — the display sizes gained the missing `##` step: `xl` is now 22/24
 (section title), `xxl` is 28/32 (page/record title — the OLD `xl` look), and the new `xxxl` is
 32/48 (hero numbers — the OLD `xxl` look). Migrate an app with two renames IN THIS ORDER: first

package/docs/ai_patterns.md

@@ -607,13 +607,20 @@ fail → low) — never render a fabricated score.
 
 ## Findings — evidence, not writes
 
-`Finding` (`@lotics/ui/finding`) is one ranked insight from an AI check — a cross-check
-discrepancy, an audit observation, a briefing item — laid out HORIZONTALLY, in the order a reader
+`Finding` (`@lotics/ui/finding`) is one ranked discrepancy from a cross-check — a contradiction
+between two readings, an audit observation, a briefing item — laid out HORIZONTALLY, in the order a reader
 needs it: a severity dot, the `title`, and the `delta` right-aligned on that same line, then the
 `readings` beneath — ONE PER LINE, each a dim `source` plus its `value`, never joined by a
 separator. `detail` is the CONSEQUENCE and is optional — a second sentence restating the title in
 longer words costs a line and adds nothing.
 
+**It is described here because AI produces most of them, NOT because it is an AI component.**
+Nothing in it is AI-specific — the labels are four severity words and "difference" — and a
+rules-derived contradiction (two stored figures disagreeing, a carrier moving an ETA) is exactly
+as in scope as an extraction's. The author who reads "AI" as a fence hand-rolls a `Callout` for a
+deterministic check and loses the ranking, the magnitude and the provenance. The test is the
+SHAPE: two readings that disagree → `Finding`; a state with nothing to contradict it → `Callout`.
+
 BOTH readings stay on screen and NEITHER is struck through or marked wrong: a finding reports
 that two sources disagree, and which one is right is the reader's call. Omit `delta` where the
 fields are not commensurable — two spellings of a name have no difference to compute. The