@lotics/ui 45.9.0 → 45.10.1

package/docs/catalog.md

@@ -3,13 +3,23 @@
 The complete inventory of the kit, in two passes: **Reach by role** maps each data role /
 job (actions, members, selects, dates, files, money, status, …) to the ONE canonical
 component, and the **Full import inventory** lists every `@lotics/ui/<module>` entry point
-with its purpose. Read this before building any screen — reuse first; a component absent
-from this catalog does not exist, and one present here must never be hand-rolled. The
+with its purpose. Read this before building any screen — reuse first, and never hand-roll
+something listed here. Absence is the weaker signal: this file is a hand-written index of
+`src/`, not `src/` itself, so an entry can be missing from a kit that ships the component —
+the first bullet below is what to do about that. The
 composition patterns (data entry, AI review, templates) live in the sibling area docs
 indexed in [AGENTS.md](../AGENTS.md).
 
 ## How to read a component's API
 
+- **Reuse first — and this catalog can LAG `src/`.** The kit's inventory is `src/`; this file
+  is a hand-written index of it, so an export lands in `src/` and in `package.json`'s `exports`
+  in one edit and gets its entry here in another. Before hand-rolling ANY capability, list and
+  grep the shipped sources — `ls node_modules/@lotics/ui/src/` — as well as reading this file.
+  A component in `src/` and missing here is a DOC BUG: from inside the kit it is fixed in the
+  same change, and from an app it is a reason to import the module anyway, never a licence to
+  hand-roll a second copy of what the kit already ships. Only the converse is absolute —
+  everything listed here exists, and what is listed here is never hand-rolled.
 - **Compose with React Native primitives**: `View` / `ScrollView` from `react-native` (never
   `div`/`span`), style with RN style objects (not CSS), and render every string through the `Text`
   primitive — the kit renders on web **and** native.
@@ -47,9 +57,7 @@ in place), `Chip` (dismissible facet chip), `CopyButton`
 A button is
 never a raw `Pressable`. For a link OUT (a URL / record / document) use `Link` — fixed
 underline+blue + `role="link"`, the destination signal (`onPress` only — the consumer wires
-the opener, e.g. the app SDK's `openExternal`); `TextLink` is the neutral,
-colour-configurable underlined marker. Underlined text GOES somewhere or REVEALS something and
-the ink says which — anything that MUTATES carries a control surface instead.
+the opener, e.g. the app SDK's `openExternal`).
 
 ### Pick from a list
 
@@ -80,28 +88,23 @@ renders these per option.)
 
 **To answer "who IS this?" — `MemberPeek`**, the same chip made a door onto a
 `MemberProfileCard`: a 72px avatar, what they sign in as, their role, their teams and when they
-joined. The chip wears `marker` there — a pressable that paints nothing at rest is text, and its
-hover wash does not exist on touch. Feed it
+joined. The trigger takes `Peek`'s `variant="control"` there, so the chip seats in the 40px
+band instead of under-filling it — there is no `marker` prop. Feed it
 a member (an app's `ResolvedMember` already carries `groups`); `role` arrives ALREADY
-TRANSLATED, never a raw enum — the kit holds no domain vocabulary. Use `MemberProfileCard`
+TRANSLATED, never a raw enum. Use `MemberProfileCard`
 alone wherever the card is not behind a press (a profile header, a drawer).
 
 **Where a peek must NOT go**, both cases being one rule — *two destinations behind one
-object*: a PICKER OPTION (`MemberSelect` / `InlineMemberSelect` render a chip per option, and
-a card over the open menu fires exactly when the reader is choosing), and a ROW THAT ALREADY
-PRESSES (the row opens the record; a chip inside it would open something else four pixels
-away). Those keep the plain `MemberChip`. A peek belongs where nothing else on the line
+object*: a PICKER OPTION, and a ROW THAT ALREADY PRESSES. Those keep the plain `MemberChip`. A
+peek belongs where nothing else on the line
 presses — a person named in prose, a static header, a detail row, a log whose rows do not
 navigate. **Judge the container, not its look:** a `DataGrid` group band names a person and
 reads inert, but it is a button that collapses the group, so a peek there nests a button in a
-button. A fully interactive screen often has NO valid spot — `examples/tpl_task_board.tsx`
-names a person three times (collapsing band, inline editor, picker option) and correctly
-peeks on none of them.
+button. A fully interactive screen often has NO valid spot.
 
 **`groups` distinguishes absent from empty, and the card renders the difference**: omitted
 drops the row (this caller was never told — a public-app response, an older server), `[]`
-keeps it and says "None". Passing `[]` for "we don't know" states as fact that a colleague is
-on no team.
+keeps it and says "None".
 
 **Size is a RUNG, never a pixel count** — `sm | md | lg | xl` = 24 / 28 / 40 / 72
 (`@lotics/ui/avatar_size`, shared by `Avatar`, `MemberChip` and `GroupAvatar`). Default `md`.
@@ -111,17 +114,14 @@ Pick by density:
 
 **Both middle rungs quote `control_surface`, and which one you want depends on whether the
 avatar is IN a control or IS one.** `md` is `CONTROL_CONTENT_HEIGHT` (28) — the largest rung a
-40px control band seats without growing, and the height `InlineButton` and a `md` `IconButton`
-already used to sit inside a field. An avatar is the tallest thing in whatever row holds it, so
-a rung that overshoots doesn't look slightly big, it RESIZES the control. Put nothing taller
+40px control band seats without growing. Put nothing taller
 than `md` in a control. `lg` is `CONTROL_HEIGHT` (40) — the avatar that stands in a band on its
-own, an account menu beside a row of icon buttons, so it measures what they do. Anything bigger
-belongs in a row that sets its own height.
+own. Anything bigger belongs in a row that sets its own height.
 
 **`sm` shows ONE initial; every larger rung shows two** — two letters are not legible at 24px.
-That is the practical reason not to reach for `sm` by reflex: on a real roster a single letter
-is rarely unique (nine people can share "N"), so a register that must identify someone wants
-`md`. Initials are the first and **last** word of the name — "Vũ Thị Lan" → VL, "Mary Jane
+That is the practical reason not to reach for `sm` by reflex: a register that must identify
+someone wants `md`. Initials are the first and **last** word of the name — "Vũ Thị Lan" → VL,
+"Mary Jane
 Watson" → MW — because a Vietnamese name's first two words are the family and middle names
 that a whole office shares.
 
@@ -150,9 +150,7 @@ The `Inline*` family: `InlineTextInput` (**`numberOfLines`** — the line budget
 reader must read WHOLE rather than recognise at a glance: a payment term, an address, a clause.
 Above 1 the resting box RESERVES that many lines — the full editor height, not the height this
 particular value needs — so clicking in moves neither the field nor anything below it; Enter
-then inserts a newline and the value commits on blur. Both halves matter: a field that only
-goes multiline once focused hides the text from the reader who never clicks, and one that
-reserves less than it opens to shoves the rest of the form down the page on every click.
+then inserts a newline and the value commits on blur.
 **`autoGrow`** makes that budget a MINIMUM and fits the value instead — see
 [data_entry.md §Open prose grows](./data_entry.md). **`link`** marks a URL value with
 the navigation ink as a TREATMENT on the same single element — never a swapped-in
@@ -167,20 +165,16 @@ is mounted at rest and merely gains a draft on focus, so focusing moves nothing
 the prose stays SELECTABLE rather than sitting under a button. Its toolbar is off for
 that reason — a band that appears with the edit pushes everything under it down — and it
 passes its **`variant`** THROUGH to the editor, which is what actually draws the box:
-the frame paints no surface here, so a variant that stopped at it stopped at nothing and
-every markdown field wore the document sheet, 4px right of the plain-text field above it.
+the frame paints no surface here.
 **`numberOfLines`** is the reserve, as everywhere else in the family); a
 READ-ONLY field in that same column uses `InlineStatic` (matches the editor box exactly, no
 input chrome, so it aligns pixel-for-pixel). **`MarkdownEditor`** is that editor standalone — a WYSIWYG whose value stays a plain
-markdown string, with a formatting toolbar as a SIBLING of the field (what the border
-encloses is the document; the controls that act on it sit outside it). Web is
+markdown string, with a formatting toolbar as a SIBLING of the field. Web is
 ProseMirror via `@lotics/markdown-editor`; native falls back to raw-text editing, and
 the platform-neutral `MarkdownEditorProps` is what stops the two drifting. **`variant`**
 is `"document"` (the default soft sheet) or the two FIELD states, `"framed"` / `"bare"`,
 DERIVED from `InlineEditVariant` so they cannot drift from the rest of the family. A field
-takes the control's corner and the control's text inset instead of the sheet's. The default
-is NAMED rather than left as absence: an optional prop whose omission is a distinct third
-mode reads exactly backwards to anyone who knows `TextInputField.variant`. Wrap it in a
+takes the control's corner and the control's text inset instead of the sheet's. Wrap it in a
 label with **`FormMarkdownEditor`**. Pass **`accessibilityLabel`** whenever the visible
 label is a sibling rather than a wrapping `FormField` — a `DetailRow`, an inline
 editor's frame — or the editable surface is an unnamed text box. A stack of labelled
@@ -198,13 +192,9 @@ axes carry every shape it takes, and BOTH are decisions about meaning, not looks
   have.
 - **`mark`** — does ticking mean DONE or CHOSEN? `check` is a ring, `select` is the square box.
   Reach for the square whenever the row is PICKED rather than finished — which forms to produce,
-  which records to export. Spending the ring on a choice is the failure this axis exists to
-  prevent: a reader who has learned that a filled ring means "done" reads a ticked pick-list as
-  work already carried out, and nothing on screen corrects them. (The shapes are 24px either way
+  which records to export. (The shapes are 24px either way
   and share one gutter, so a surface swaps between them without moving anything.)
 
-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
@@ -216,21 +206,12 @@ no-op (withheld internally), because neither of the toggle-capable marks (`Check
 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
-in the row (two edit surfaces for one fact) and never rendered as a value (an avatar or badge is
-a copy that has to be kept in step). The exceptions are narrow and stated: `ChecklistItem.trailing`
-for the row's OWN stamp (a tick writes today, so a run filled in after the fact needs the
-correction in reach), and `ChecklistField` for a value with NO other home.
-
 **A list you scan DOWN columns — the same four values compared across twenty rows — is a
 `Table`.** Grouping, filters and a per-row register belong there.
 
 **A record's work state is a connected checklist** ([`tpl_record`](../examples/tpl_record.tsx)
-§ Progress), where the desks are `ChecklistGroup`s and the milestones are rows. A per-desk
-checklist without the connecting line described the work but never said where the record SAT, and
-put the CTA a section away from the state that gated it. A register's workspace drawer renders the
+§ Progress), where the desks are `ChecklistGroup`s and the milestones are rows. A register's
+workspace drawer renders the
 same record, so it follows automatically; for a surface whose SUBJECT is tasks see
 [`tpl_task_board`](../examples/tpl_task_board.tsx).
 
@@ -259,16 +240,15 @@ 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
+  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.
   **`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
+  OVERFLOWS. A narrow container must scroll it horizontally. If you want columns to drop, you
+  want `Table`. It renders ALL rows (no
   virtualization), so it's only for sets small enough to hold in view — at 10k+ it lags, and
   grouping + pagination/infinite don't compose; use the register instead. Worked example:
   [`tpl_task_board`](../examples/tpl_task_board.tsx) (a `CheckCircle` leading).
@@ -279,23 +259,26 @@ Two columnar shapes, and the choice is about data size:
 — below the toolbar, from the filtered rows), `KPICard` / `Metric` (headline figures),
 `TrendChip` (delta), `Sparkline`, `BarChart` / `LineChart` / `PieChart` (the canonical SVG
 set — no recharts), `ProgressRing`, `ProgressBar` (its `compact` prop = ONE row, track + a
-plain sm tabular count beside it — the cell/heading/peek-trigger meter; a caption floating
-above a tiny bar reads misaligned. **The track clamps at 100%, the caption does not** — over
-its max it reads `2,100 / 2,000 (105%)`, because a meter that says "100%" when you are over
-tells the reader they are exactly at the limit. Numbers format in the reader's locale, so
+plain sm tabular count beside it — the cell/heading/peek-trigger meter. **The track clamps at
+100%, the caption does not** — over its max it reads `2,100 / 2,000 (105%)`. Numbers format in the
+reader's locale, so
 never hand-format the value you pass in — when display precision differs from the true value
 (whole credits off a fractional balance), `formatValue` reshapes the caption text and leaves
-the fill and the percentage exact) / `StackedProgressBar` / `StepProgress`, `Breakdown` (a
+the fill and the percentage exact) / `StackedProgressBar` (ONE whole split across segments,
+filling its own track whatever the total) / `StackedBarChart` (SEVERAL wholes compared — rows
+of stacked bars on one shared scale, so length says how big and the segments say what of) /
+`StepProgress`, `WaterfallChart` (the BRIDGE — an opening level, the signed steps that move
+it, the level they close at; revenue walked down to net), `Breakdown` (a
 stacked bar + ranked share rows, pressable to drill; `maxRows` folds the long tail behind a
 "Show N more" toggle — `labels` to localize — so several facet cards align to one height in
 a row), `Funnel` (a CONVERSION funnel — ordered stages as bars that NARROW; the step
 conversion rate is the HEADLINE (a bold aligned row across the top, the first stage = the
-100% baseline), the count is the supporting figure below — the Amplitude/Mixpanel
-convention, never pin the rate to the fill height. `orientation` vertical columns |
+100% baseline), the count is the supporting figure below — never pin the rate to the fill height.
+`orientation` vertical columns |
 horizontal bars; pass `onSelect`+`selectedKey` to make the bars press-to-drill (the selected
 stays solid, others dim — the caller renders the records). The subset/drop-off sibling of
 `StackedProgressBar` — nested cohorts that shrink "calls → connected → won", NOT a whole
-split across stages — that's `StackedProgressBar`), `StatusGrid` + `StatusLegend`, `Heatmap`
+split across stages), `StatusGrid` + `StatusLegend`, `Heatmap`
 (density: colour-only, "where does it cluster"), `Matrix` (the PIVOT cross-tab: the NUMBER
 in each cell — optionally a heat wash behind it — plus row/column/grand totals; press a cell
 to drill).
@@ -325,11 +308,8 @@ action/badge/unit), `ActionMenu` (⋯), `FloatingActionBar` (bulk-select bar).
 
 A DESIGNED row (your own pile, card, or panel) that presses open AND carries its own
 controls is `PressableRow` + **`PressDoor`** — never `PressableHighlight`, which IS a
-button and wraps its children (a button must not contain interactive descendants). The
-door is an empty absolutely-positioned SIBLING of the content carrying the tab stop,
-accessible name, and focus ring; lift the content above it with `zIndex: 1`. `Table`/
-`TableRow` does exactly this internally, so a columnar register needs no assembly —
-reach for `PressDoor` only outside it.
+button and wraps its children (a button must not contain interactive descendants). `Table`/
+`TableRow` does exactly this internally, so a columnar register needs no assembly.
 
 ### Filters & view controls
 
@@ -362,11 +342,9 @@ into a list *and* a grid is the mistake — it gives the reader two places to lo
 thing. The minority is not stranded by this: a non-image tile in a grid renders a `DocumentCard`
 printing its filename, and a photo in a list keeps its full name plus a meta line and is ONE tap
 from the picture, because a `FileRows` row press opens the built-in gallery. (The badge is
-MIME-driven, so that row shows a generic image mark, not the shot itself — which is the cost the
-majority already decided to pay.) A screen showing BOTH surfaces (`tpl_record`) does
-so because it holds two distinct SETS the reader asks different questions of — the paperwork
-that arrived on the record, and the hand-over photos taken against it — not because one set was
-split by type.
+MIME-driven, so that row shows a generic image mark, not the shot itself.) A screen showing
+BOTH surfaces (`tpl_record`) does so because it holds two distinct SETS the reader asks
+different questions of, not because one set was split by type.
 
 `FilesEditor` (THE attachment surface: an upload-aware grid whose bar you COMPOSE — the root
 owns selection + gallery + confirmed remove, the bar pieces and any HOST verb go below it via
@@ -388,8 +366,7 @@ action / remove; `onPress` makes the whole row a pressable door, `trailing` stay
 independently-pressable sibling; for checklists & readable lists. **`size`** — `sm` (default)
 is the compact attachment line for many files scanned as a list; **`md` is the document-desk
 row** (taller badge, `ListItem` height) for the FEW rows that ARE the section's subject — an
-expected-document checklist, a slot a button fills. A two-row section at `sm` reads as an
-appendix to the page rather than its point), `FileBadge` (the two-tone
+expected-document checklist, a slot a button fills), `FileBadge` (the two-tone
 type mark), `FilePreview` / `FileGalleryModal`, `ImageGallery`; picking is `pickFiles`
 (`@lotics/ui/file_picker` — opens the browser picker and resolves the chosen `File[]`, the
 imperative half behind every Add-file CTA); for gated CRUD compose locally with
@@ -422,20 +399,14 @@ that same line, over the `readings` stacked ONE PER LINE — each `source value`
 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
+and which is right is the reader's call. `detail` is the optional consequence. The readings ARE the
 provenance, so there are no `Sources` chips under it repeating the same names. The children slot
 composes ANY visual result — a compact `Table` for per-line detail (danger color on the offending cells),
 `ProgressBar` for consumption-toward-a-cliff (free time, credit), dot `Badge`s for a
 present/missing checklist, `Confidence` for judgment calls. Display-only — it informs the
 verdict the host records; `finding` locale slice). `ApprovalPrompt` (the surface that ANSWERS
-an agent's approval-gated action — the interactive counterpart to `AgentRun`'s read-only amber
-`awaiting` row: a warning icon + message on a bordered card, Deny/Approve right-aligned, an
-optional `children` input summary; slot it where the composer sits while the run is parked;
-`approvalPrompt` locale slice), `MessageActions` (THE single shared per-message chrome bar for a
-chat transcript — copy with owned copied-feedback, regenerate, edit, and the branch/version
-pager as an internal part; each action renders only when its handler is given, so the assistant
-bar and the user bar are one component with different handlers; `messageActions` locale slice).
+an agent's approval-gated action), `MessageActions` (THE single shared per-message chrome bar
+for a chat transcript).
 
 ---
 
@@ -448,15 +419,14 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 
 - **`vite`** — `loticsOptimizeDeps`: the canonical `optimizeDeps.include` list a custom-code
   app's `vite.config.ts` must pre-bundle for `lotics app dev` to render (RN-ecosystem + markdown
-  CJS-interop; dev-only — the prod rollup build resolves the interop without it). Ships WITH the
-  kit so it can never drift from what @lotics/ui's transitive deps require across a major bump —
-  the scaffold's `vite.config.ts` imports it instead of hardcoding the list:
+  CJS-interop; dev-only — the prod rollup build resolves the interop without it). The
+  scaffold's `vite.config.ts` imports it instead of hardcoding the list:
   `import { loticsOptimizeDeps } from "@lotics/ui/vite"` → `optimizeDeps: { include: loticsOptimizeDeps }`.
   To add app-specific entries, spread: `include: [...loticsOptimizeDeps, "my-dep"]`. A Node-loadable
   `.mjs` leaf (a Vite config can't import a `.ts` from `node_modules`), zero-import by contract.
 - **`vite`** — `loticsResolve()`: the whole `resolve` block, for the same reason and on the same
-  terms — `resolve: loticsResolve()`. Every entry is dictated by the kit's internals, so the kit
-  owns them: the `react-native` → `react-native-web` alias (**load-bearing** — without it the RN
+  terms — `resolve: loticsResolve()`. The entries: the `react-native` → `react-native-web` alias
+  (**load-bearing** — without it the RN
   primitives have no web implementation and the app does not build), `.web.tsx`-first `extensions`
   (per-target variants win; `.mjs`/`.mts` kept for parity with Vite's default resolver), `dedupe`
   for React + RN-Web (the kit is consumed across many subpaths, and a second React copy in one
@@ -464,8 +434,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   read at call time so it lasts exactly one command. To add your own alias, spread:
   `const base = loticsResolve(); resolve: { ...base, alias: [...base.alias, entry] }`.
   `lotics app codegen` writes the matching `paths` into the app's `.lotics/tsconfig.link.json`,
-  so `tsc`, vitest, eslint and the editor resolve the same kit Vite does — the dev-link is not a
-  Vite-only trick that leaves every other tool checking the published package.
+  so `tsc`, vitest, eslint and the editor resolve the same kit Vite does.
 
 ### Text & formatting
 
@@ -491,18 +460,18 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `Icon` rather than rendering the wrong company's logo. Not for the app's
   own glyphs; that is `icon`. `x` is the one mark whose brand colour is BLACK, so it is the one
   that needs `muted` on a dark ground; the rest carry their own hue either way. **Not a product
-  logo**: a monochrome stand-in for one reads as a different thing (a red "M" is not Gmail), the kit
-  ships no vendor artwork, and official artwork is not uniformly inlinable anyway — pass your own
-  image to `SwitchButton`'s `leading` slot instead.
+  logo**: a monochrome stand-in for one reads as a different thing, the kit ships no vendor
+  artwork, and official artwork is not uniformly inlinable anyway — pass your own image to
+  `SwitchButton`'s `leading` slot instead.
 - **`markdown`** — `Markdown`: the single canonical markdown renderer for chat, apps, and
   `AgentRun`; rich GFM markdown on web with copyable tables, plain-text on
   native; takes a markdown `children` string. **`variant`** decides whose type
   ladder the headings belong to: `"document"` (default) where the markdown IS the
   surface, `"embedded"` where it is a VALUE on a page someone else designed — a
   field on a record, a summary in a feed row. Reach for `"embedded"` whenever the
-  text was not written by whoever built the screen, which is now the common case
-  because the writer is routinely a model; at document scale an `h1` it emits is
-  the same rung as your `SectionHeadingTitle`. Embedded demotes the heading LEVEL as well as
+  text was not written by whoever built the screen; at document scale an `h1` it
+  emits is the same rung as your `SectionHeadingTitle`. Embedded demotes the heading LEVEL as well
+  as
   the scale (h1→h4, h2→h5, h3+→h6): sizing alone leaves a model's `##` announcing as a PEER of
   your own sections in heading navigation, which no visual check can see.
 - **`markdown_types`** — `MarkdownProps`; types only.
@@ -514,10 +483,8 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `getInputLineHeight` — the 16px-mobile/14px-desktop input contract that stops Safari iOS
   auto-zoom; only for hand-rolled raw inputs. It carries the **ink** as well as the size,
   because omitting `color` on a native `<input>` does not inherit — it falls to the UA
-  default, pure black, against the `zinc-900` every resting value beside it uses. A field
-  whose text darkens the instant it is focused reads as the text MOVING (at 14px a darkness
-  change re-weights every stroke's antialiasing), which is a bug no box measurement can
-  see. Hand-rolling a raw input means taking this style, not just its font size.
+  default, pure black, against the `zinc-900` every resting value beside it uses.
+  Hand-rolling a raw input means taking this style, not just its font size.
 - **`font_family`** — the three Inter stacks (`fontFamilyRegular` / `fontFamilyMedium` /
   `fontFamilySemiBold`). Weight in this kit is a FAMILY, not a `font-weight` axis: each rung is
   a separate file, which is why `Text`'s `weight` prop swaps the family rather than a number.
@@ -527,14 +494,13 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   the ONLY themeable typeface. There is deliberately no body-face role: body weight is three
   coupled families, `text.css` hand-tunes tracking for Inter's glyphs and for Vietnamese
   diacritics at 12px, and `font-feature-settings: "cv11","ss01","ss03"` are Inter's own
-  alternates. A variable for the body face would not fail loudly — it would render every screen
-  subtly miscalibrated. Changing the body face is a kit change, done once for everybody.
+  alternates. Changing the body face is a kit change, done once for everybody.
 - **`type_ramp`** — the type ramp as DATA: `TYPE_RAMP_MOBILE` / `TYPE_RAMP_DESKTOP` (size +
   leading per rung, the 768px breakpoint between them), `TYPE_TRACKING` (em per rung, negative
   throughout and steepening as the type grows), `TypeRung` / `TypeRungName` (`TextSize` IS this
   set), and `trackingPx` for platforms with no em unit. `Text` renders through two mechanisms —
   a `data-text-size` attribute matched by `text.css` on web, a `StyleSheet` on native — and this
-  is what both derive from, so the two cannot disagree. Read it to learn what a rung IS; you
+  is what both derive from, so the two cannot disagree. You
   almost never need to import it, because `Text size=` is the way to ask for a rung. Reach for
   it only when styling something `Text` cannot wrap (a raw `TextInput`, a canvas, a chart axis)
   and the result has to sit at a rung exactly.
@@ -571,15 +537,13 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`spacing`** — the `SPACE` scale + `SpaceToken`, and **`pagePad(small)`** — the page's
   side gutter (`SPACE.md` on a phone, `SPACE.xl` wider). `PageContent` applies it; a screen
   that cannot use that shell — one with a rail, a side panel or its own scroller — imports it
-  rather than picking a number, because a list and the record it opens are one reading column
-  seen twice and must not shift sideways between them. It is also COUPLED to `ROW_WASH_BLEED`:
+  rather than picking a number. It is also COUPLED to `ROW_WASH_BLEED`:
   a register row bleeds its wash outward to `pagePad − ROW_WASH_BLEED`, so the two are read
   together and neither belongs to the app.
 - **`control_surface`** — `CONTROL_HEIGHT` (40), `CONTROL_CONTENT_HEIGHT` (28 — the tallest
   FIXED-height node a 40px band seats, 6 per side of air; what `InlineButton` and a `md`
   `IconButton` already used, now named so an avatar or any other child lands on it too. Text
-  never needs it because `minHeight` governs a single line, which is exactly why three surfaces
-  could each pick a different inset and only disagree once an avatar went in),
+  never needs it because `minHeight` governs a single line),
   `CONTROL_PADDING_V` (5 — derived from the pair, BORDER INCLUDED in the 6 per side; every 40px
   surface pads by it instead of a number of its own), `CONTROL_RADIUS` (10), `CONTROL_TEXT_INSET`
   (9 — how far a control insets its OWN text: 1px border + 8px padding; anything that must line
@@ -627,8 +591,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   so a prop declared on one side typechecks everywhere and silently does nothing in the browser.
 - **`label_tone`** — `labelTone(label)`: one stable `ColorName` per free-text label (a tag, a
   topic, a category), for `Badge`. `avatarTone`'s sibling and the same discipline: pure and
-  NEVER STORED, so a set of labels can stay a `text[]` instead of earning a table the moment a
-  colour has to be chosen; `red` and `amber` excluded, because a palette that can paint an
+  NEVER STORED; `red` and `amber` excluded, because a palette that can paint an
   arbitrary noun red makes every red on the screen ambiguous; hue-interleaved so two labels in
   adjacent buckets still look different. Case- and space-folded, matching whatever normalizes the
   set — two spellings of one label must not be two colours. Returns a NAME (not a hex like
@@ -646,14 +609,14 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   one cell. Takes `{ id, name, kind: "person" | "group", image? }`, shows `max` of them (default
   3) and makes the rest a `+N` that is the LAST MARK IN THE STACK, not loose text beside it.
   `size` is the shared avatar scale with the same `md` default as `Avatar`/`MemberChip`, and the
-  marks, the overlap and the count's type all derive from it — no fixed pixels, so a stack at any
-  rung is the same object. Three rules it exists to carry: the caller passes only principals it
+  marks, the overlap and the count's type all derive from it — no fixed pixels. Three rules it
+  exists to carry: the caller passes only principals it
   can NAME, so the overflow never counts a mark the reader sees is missing; a group is ONE mark
   bearing the group's name, never its members' faces (expanding it states a membership the reader
   may not be entitled to); and the separating hairline is **translucent ink, never the surface
   colour** — a register row washes to `zinc[50]` on hover, `accent_wash` when open and
   `zinc[200]` while pressed, so a ring painted the background is a halo in three of the four
-  states, while a dark edge darkens any ground (the trick `FileBadge` already uses). Marks
+  states, while a dark edge darkens any ground. Marks
   `announce` because they stand alone here. INERT — its home is a register row, and a row that
   already presses must not hold a second destination (see `member_peek`). A single person →
   `MemberChip`; a single group → `GroupAvatar`.
@@ -668,8 +631,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`member_profile_card`** — `MemberProfileCard`: WHO IS THIS — `xl` avatar, name, sign-in
   identity, role, join date and groups, plus one optional `action`. Every row is conditional, so a
   card told nothing is a header and nothing else. `role` comes in pre-translated (vocabulary only
-  the product can name); `joined` comes in as an ISO DATE and the card formats it to month + year
-  (a date has a canonical form the kit owns, so two hosts formatting it themselves would drift);
+  the product can name); `joined` comes in as an ISO DATE and the card formats it to month + year;
   `groups` distinguishes absent (no row) from `[]` ("None"). `inactive` draws the departed state as
   a `Badge` — a lifecycle state, not another muted line.
 - **`member_peek`** — `MemberPeek`: `MemberChip` + `Peek` + the card above, with the trigger's
@@ -696,8 +658,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   one opt-down). **Which rung it renders is the SURFACE's answer, not a prop:** `##` xl-semibold
   on a page, `####` md-semibold inside an overlay's content region (`DrawerScrollArea` /
   `DialogScrollArea` / `ModalBody` / `PopoverContent`), where the container's own title already
-  occupies lg. The call site is identical on both, which is the whole point — there is no
-  per-surface variant to pick, so it cannot be picked wrong. A whole PAGE surface docked in an
+  occupies lg. A whole PAGE surface docked in an
   overlay (a record screen in a master-detail drawer) carries its own gutters and so sits in the
   container's BARE slot, keeping the page rungs; nesting overlays never compounds.
   `SubsectionHeadingTitle` is the `###` lg-semibold level-3
@@ -709,8 +670,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `primary` `Button` beside the title, rendered whether the collection is empty or full, never
   under the rows it extends and never repeated in the `EmptyState`
   (composition.md § The add-placement law). An overlay surface loses only the type size, never an
-  affordance — `icon`, `description` and `info` are the same slots at both altitudes. **`description`
-  is on every rung** — the ramp's slots do not vary by level; only the type size does. Inside an
+  affordance — `icon`, `description` and `info` are the same slots at both altitudes. Inside an
   overlay `####` is the ramp's FLOOR: `SubsectionHeadingTitle` has one altitude and would out-rank
   the section holding it, so a named group there is `Text size="sm" weight="semibold"`. The heading
   ramp is FIXED: `#` xxl / `##` xl / `###` lg / `####` md, no size props.
@@ -719,9 +679,8 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   rung. The kit's content regions publish it, so an ordinary screen never imports this. Reach for
   it when you build your OWN pane — a docked side panel, a split view, any self-contained region
   whose own chrome caps at `lg` and which therefore uses none of those regions: wrap its content
-  in `<HeadingAltitudeContext.Provider value="panel">` and every heading inside is right. Scoping
-  the rule to the panes the KIT renders would make it an allowlist short by however many you
-  build. Flat, never a depth counter — a popover inside a drawer is one rung down, not two.
+  in `<HeadingAltitudeContext.Provider value="panel">` and every heading inside is right.
+  Flat, never a depth counter — a popover inside a drawer is one rung down, not two.
 - **`section_stack`** — `SectionStack`, `SubsectionStack` — stacks that own the
   between-block law, skipping null children: `SectionStack` = a fixed 56px beat + a hairline
   `Divider` between top-level blocks; `SubsectionStack` = a fixed 32px beat, space-only while
@@ -748,16 +707,13 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `left`/`right` form a separate nav row above. Split `trailing` from `actions` by what the
   control acts on: `actions` do something to the page's CONTENT (create, sort, export),
   `trailing` changes what is AROUND it (a side-panel toggle, a view switch). A panel toggle
-  filed under `actions` reads as a peer of "create one of these". It sits AFTER the title
-  because the title is the page's first word and nothing should come between the reader
-  and it. Under a title too long for the row the TITLE gives way and wraps while `trailing`
-  and `actions` keep their width — a wrapped title is merely taller, a control squeezed
-  below its own icon is broken.
+  filed under `actions` reads as a peer of "create one of these". Under a title too long for
+  the row the TITLE gives way and wraps while `trailing`
+  and `actions` keep their width.
 - **`page_content`** — `PageContent` + `PAGE_SIZES`: the page's padded, width-capped content
   region — a centred column with optional `title`/`titleRight`/`description`, `header`/`footer`
-  slots and `fullscreen`. **Reach for it before hand-rolling a screen shell**: a scroller, a
-  centred `maxWidth` column and a title band re-typed per screen is how two pages of one app end
-  up on different gutters. Its side padding is `pagePad` (`@lotics/ui/spacing`), so a screen that
+  slots and `fullscreen`. **Reach for it before hand-rolling a screen shell.** Its side
+  padding is `pagePad` (`@lotics/ui/spacing`), so a screen that
   genuinely cannot use it — one with a rail, a side panel, or a scroller it must hold a ref to —
   still lands on the same edge by importing that token. It OWNS its `ScrollView` and exposes no
   scroll props, which is the real limit on adoption.
@@ -804,21 +760,20 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`comments_button`** — `CommentsButton`: THE discussion affordance for a listed record — the
   count and a bubble as ONE control, opening the thread. Reach for it wherever a record is listed
   and its conversation would otherwise be invisible until opened (a register row, a card, a
-  compact header); it is `CopyButton`'s peer — the other thing a dense row lets you press — and
+  compact header); it is `CopyButton`'s peer and
   shares its surface, scale and focus ring, so a row carrying both reads as one grammar. The count
   is INSIDE the target, never loose text beside an `IconButton`: the number is what the reader
   aims at, and splitting them leaves half the affordance dead under the pointer. FULL INK, unlike
-  the muted values around it — everything else on a row is a fact ABOUT the record, this is people
-  talking about it and the one thing there that can be UNREAD. `subject` reaches the accessible
+  the muted values around it — the one thing on the row that can be UNREAD. `subject` reaches the
+  accessible
   NAME only ("3 comments on Northwind Packaging" is a destination; "3 comments" on the fortieth row
   is not) — never the visible label, which would spend row width restating whose record it is. The
   pack's `commentsButton.withSubject` builds that phrase, so the word ORDER is the pack's to choose
-  and the join is a WORD: this string exists to be read aloud, and a screen reader drops
-  punctuation along with the relation it was carrying.
-  **Render it only when `count > 0`** — a zero on every quiet row is a column of noise that trains
-  the eye to skip exactly where the signal will appear. Pair it with a jump that LANDS on the
-  thread (`tpl_item_list` opens the record's drawer on its comments section), because a count the
-  reader cannot act on states that a conversation exists and leaves them to find it.
+  and the join is a WORD — a screen reader drops punctuation along with the relation it was
+  carrying.
+  **Render it only when `count > 0`** — a zero on every quiet row is a column of noise. Pair it
+  with a jump that LANDS on the
+  thread (`tpl_item_list` opens the record's drawer on its comments section).
 - **`copy_button`** — `CopyButton`: THE copy control — `value` onto the clipboard, glyph
   flips to a check and the tooltip to the pack's "Copied" for ~2s. The confirmation follows
   a REAL write: an unreachable clipboard throws and the button stays at rest rather than
@@ -840,8 +795,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `nav.back` — "Back" / "Quay lại"). Bare it is the 40px chevron-left disc; pass
   **`label`** to name where back GOES ("Danh sách") — the SAME disc with the destination
   beside it, ONE pressable over disc + words, never an icon button beside unclickable
-  prose. It takes no size or colour: one purpose, one look, and both variants draw the
-  one disc so they cannot drift.
+  prose. It takes no size or colour.
   **A back affordance INSIDE a header row is not this** — beside a drawer's title a 40px
   disc outweighs the name it belongs to, so that one is a small `IconButton` (see
   `screen_router` below). The distinction is prominence: this HEADS a surface, that
@@ -889,8 +843,8 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`floating_action_bar`** — `FloatingActionBar`: the floating bulk-select action bar.
 - **`pressable_row`** — `PressableRow`: THE register row — full-width hover/open wash,
   `selected` (the open record) vs `marked` (ticked in bulk-select), forwards `ref` for
-  popover anchoring. **Its text is SELECTABLE**: a register row is a button wrapped around
-  data, so dragging across a name and copying it works, and a release that selected text
+  popover anchoring. **Its text is SELECTABLE**: dragging across a name and copying it
+  works, and a release that selected text
   does not open the record (see `press_selection`). Furniture that must not smear over —
   `Badge`, `Avatar`, `Button` — opts out for itself.
   The guard behind it is internal (`press_selection`): only a real, non-empty selection
@@ -948,21 +902,19 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   the section's add (that lives on the heading row, where it does not move — § The add-placement
   law in composition.md), a no-results empty is HINT-only since the filters that emptied it carry
   their own clear, and a FAILED read is `ErrorState`, not this. **`compact`** for one BAND of a
-  record — left-aligned, glyph-less, 56px against the default's 178 — because the
-  heading above it has already proved the surface rendered; the centred default speaks for a
-  whole region, where nothing else is in view to say so. → composition.md § Empty states.
+  record — left-aligned, glyph-less, 56px against the default's 178; the centred default speaks
+  for a whole region. → composition.md § Empty states.
 - **`error_state`** — `ErrorState`: the region-scale FAILED read — `message` + optional `detail`
   + `onRetry` (the kit renders the button and words it from the locale pack, so "try again" reads
   the same everywhere). The fourth of the region states: `Skeleton`/`Loading` in flight → this on
-  failure → `EmptyState` on nothing → `CompletionState` on done. Rendering a failure as an empty
-  asserts the read succeeded and found nothing, when nothing is known. For a failure INSIDE a
+  failure → `EmptyState` on nothing → `CompletionState` on done. For a failure INSIDE a
   flow (a form that won't save) use `Callout tone="error"`; this is for a region with no content
   to show, where a tinted strip leaves the area collapsed.
 - **`completion_state`** — `CompletionState`: the "all done" terminal state.
 - **`skeleton`** — `Skeleton`: loading placeholder blocks. **Mirror the layout that is
   arriving** — same row count, same column widths, same heights. A skeleton of a different
-  shape makes the content jump when it lands, which is more disruptive than an empty box
-  would have been. First of the four region states; the other three are under `error_state`.
+  shape makes the content jump when it lands. First of the four region states; the other three are
+  under `error_state`.
 - **`loading`** — `Loading`: the centered indeterminate loading state (composes
   `DotsIndicator`).
 - **`activity_indicator`** — `ActivityIndicator`: the bare spinner.
@@ -980,8 +932,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   also home of the shared `PickerOption` type. Its empty row does one of two jobs and they
   are not interchangeable: `includeEmptyOption` makes empty a **choice** the reader picks to
   clear the field, so it is NAMED ("None", from the locale pack; override per instance with
-  `emptyOptionLabel`) and keeps that name after a selection — a name that disappears once
-  something is chosen is missing exactly when it is the only route back to empty. Without
+  `emptyOptionLabel`) and keeps that name after a selection. Without
   that flag the row is a **placeholder**: it carries `placeholder` and leaves on selection.
   Don't reach for `placeholder` to name a choice — a hint and a value read differently.
   Inside a `FormField` (so inside `FormPicker`) it takes its NAME from the visible label
@@ -992,8 +943,8 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `renderSelected(item, { remove })` + `searchable` + `allowCustom` — the tag field is just
   a multi Select; opens `OptionList`. **Set `searchPlaceholder` whenever `allowCustom` is on**:
   the create row only exists once there is a query, so on an untyped menu the placeholder is the
-  only always-visible place that can say a new value is allowed — a tag field reading "Search…"
-  tells the reader the vocabulary is closed. `customOptionLabel` names what the create row will
+  only always-visible place that can say a new value is allowed. `customOptionLabel` names what
+  the create row will
   do, with the value in it. Its trigger is `role="combobox"` (a `<div>`), never
   `role="button"`: the chip box legitimately puts a remove button INSIDE the trigger, and a
   real `<button>` may not contain one. **Any trigger that renders caller-supplied content
@@ -1006,13 +957,12 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   opens — single/multi, optional internal search, create row, keyboard + native-`<select>`
   typeahead; host it directly in a `Popover`/`Dialog` for a command palette. A chosen row is
   `selected`: the kit's `zinc.100` resting highlight AND `aria-selected`, one weight above the
-  `zinc.50` the keyboard/hover row takes — a check glyph alone said nothing to a screen reader.
+  `zinc.50` the keyboard/hover row takes.
   It opens SCROLLED to its seat (the selected row in `search.mode:"none"`, else the first real
-  option), which only shows on a list longer than its own box and is the difference between a
-  96-row list opening on your value and opening at the top.
+  option), which only shows on a list longer than its own box.
   `indeterminateValues` (multi) draws a MIXED tick on values only SOME of the things being
-  edited carry — the shape for labelling a selection, where an empty box would say "none of
-  these" and be wrong. Presentational and one-directional: a mixed row is not in `value`, so
+  edited carry — the shape for labelling a selection. Presentational and one-directional: a mixed
+  row is not in `value`, so
   pressing it selects (the caller applies to all), and it announces itself in the row label
   because `role="option"` has no ARIA state for a third value.
 - **`combobox`** — COMPOUND single-select editable search: `Combobox` root +
@@ -1056,6 +1006,17 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   field with an empty slot reserves nothing, so its text starts and ends where it always did.
 - **`number_input`** — `NumberInput`: numeric input; `format` for currency/units.
 - **`search_input`** — `SearchInput`: the search box for toolbars/filters.
+- **`markdown_editor`** — `MarkdownEditor`: the standalone WYSIWYG whose value stays a plain
+  markdown string, with the formatting toolbar as a SIBLING of the field. `variant` is
+  `"document"` (the default soft sheet) or the two FIELD states `"framed"` / `"bare"`, DERIVED
+  from `InlineEditVariant`; the editor draws its own surface, so a host frame never paints one
+  under it. Web is ProseMirror via `@lotics/markdown-editor`, native falls back to raw-text
+  editing — see § Edit a record's fields in place for the whole family and its `numberOfLines`
+  reserve. **`markdown_editor_props`** is the platform-neutral `MarkdownEditorProps` /
+  `MarkdownEditorVariant` that keeps the two implementations from drifting; **`markdown_editor.css`**
+  is the web sheet, imported once at the app entry.
+- **`form_markdown_editor`** — `FormMarkdownEditor`: `FormField` wrapping a `MarkdownEditor` —
+  the labeled prose field, for a dialog or settings form.
 - **`form_field`** — `FormField` + `useFormField`: label / description / warning / error /
   `optional` marker wrapper (the three field-annotation tones — muted / amber / danger — all
   wired into the input's describedby); the fieldset grid cell (`half`/`full` widths — see the
@@ -1079,7 +1040,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   switch (`accessibilityRole="switch"`, the inner Switch read-only). The settings-panel/menu
   row toggle. The leading slot takes EITHER `icon` (an `IconName`, the app's own glyph language)
   or `leading` (any node); `icon` wins if both are passed. A row naming an outside product passes
-  its logo through `leading`, because the kit ships no vendor artwork of its own.
+  its logo through `leading`.
 - **`use_form`** — `useForm`: THE batch draft-form state hook — `values` = `initialValues` +
   an edits overlay (a revalidation refreshes untouched fields, no sync effect), `validate`
   (sync/async, gates submit, editing clears the field's error), `onSubmit(values, helpers)`
@@ -1110,7 +1071,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`date_filter`** — `DateFilter`: the date+time period filter panel — presets
   (`PresetId`), calendar, optional time segments; the body `DateRangeFilterField` opens.
   **Every preset SETS a range** — the list holds no mode and no null case, so a hand-picked
-  range selects nothing rather than lighting a "custom" row whose click cleared the value. The
+  range selects nothing. The
   presets are a `listbox` of `MenuButton` options: selection is the kit's `zinc.100` row
   highlight plus `aria-selected`, never a filled primary treatment, because the row reports
   state rather than offering an action. Sidebar at viewports of 768 and up, strip below —
@@ -1146,13 +1107,11 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `DeadlineThresholds`, `Deadline`). Three contracts a screen must not invent for itself — how
   far off a date is, what to CALL that number, and how loud it reads. `daysUntil` collapses both
   ends to midnight because the vocabulary is day-granular: rounding the raw gap lands on the
-  wrong day whenever now and the deadline straddle noon (a 02:00 cut-off tomorrow reads "today";
-  one at 02:00 today reads "1 day overdue" 12 hours in). Wording comes from the `deadline` locale
+  wrong day whenever now and the deadline straddle noon. Wording comes from the `deadline` locale
   slice; the 1-day/3-day tone lines are freight defaults and move per domain via
   `DeadlineThresholds`. **`deadlineAnnotation` spreads onto the `DetailRow` holding the date** —
   a deadline is a property OF that field, and the three annotation slots carry the three urgency
-  levels exactly (`error` / `warning` / `description`), so it never becomes a trailing badge
-  speaking a vocabulary the rest of the field grid does not. `nearestDeadline` returns an OVERDUE
+  levels exactly (`error` / `warning` / `description`). `nearestDeadline` returns an OVERDUE
   milestone FIRST and expects the caller to pass only OPEN ones — done-ness is not knowable from
   a date, and skipping past a missed cut-off is how a record silently stops reporting the failure.
   Worked example: `tpl_record`'s Due rows.
@@ -1200,8 +1159,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   same shape `Select` gives: return `<Chip onDismiss={remove}>` for a removable tag, or a plain
   badge that ignores it — a dense grid column is the case for the badge, since the ✕ costs more
   width there than the reopen it saves. `remove` detaches that one tag whether the list is open or
-  shut, and never opens the list — the innermost responder takes the gesture, so a ✕ inside the
-  trigger needs nothing to hold the press back. Single has no `remove`: unsetting one value is `onClear` and its
+  shut, and never opens the list. Single has no `remove`: unsetting one value is `onClear` and its
   Clear row. Both modes take
   `allowCustom` (a create-a-tag/option row) + `searchable` + **`customOptionPlacement`** (default
   `"bottom"`, right for a tag field; pass `"top"` for a find-or-create REFERENCE picker over a long
@@ -1230,9 +1188,14 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
     surface already promises and, down a column, draws the grid twice.
 
   It is an axis of weight, not of use: both hover and open identically. There is no `*Cell` family —
-  a data-grid cell is `<InlineSelect variant="bare" …/>`, not a `SelectCell` (naming a component for a
-  USE, and duplicating the picker stack to flip two style properties, are both things the kit forbids).
+  a data-grid cell is `<InlineSelect variant="bare" …/>`, not a `SelectCell`.
   Hand-roll a pressable cell to match `bare`, never a background wash.
+- **`inline_markdown`** — `InlineMarkdown`: the PROSE member of the Inline\* family — a
+  `MarkdownEditor` on the inline-field box metrics, `onSave` per field. It is the one member
+  that does NOT swap: the editor is mounted at rest and merely gains a draft on focus, so
+  focusing moves nothing and the prose stays SELECTABLE instead of sitting under a button. Its
+  toolbar is off for the same reason, and `variant` passes THROUGH to the editor, which draws
+  the box. Full note under § Edit a record's fields in place.
 - **`inline_files`** — `InlineFiles`: the FILES member of the Inline\* family — a record's
   attachments as a `DetailRow` value. A `FileRows` LIST (press a row to preview full-screen, ⋯
   to remove) with ONE CTA under it; no selection mode, no bulk bar, no upload queue — reach for
@@ -1240,8 +1203,8 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   is the FIELD's cardinality and it changes the verb**: many → the CTA reads `addMoreLabel` and
   the host APPENDS in `onAdd`; one → it reads `replaceLabel` and the host SETS, because "add
   another" is not an act a single-file field can perform and offering it is how a record ends up
-  holding two of something the schema says there is one of (the component owns the affordance,
-  it cannot own the persistence). `blockedReason` renders a sentence instead of the CTA for a
+  holding two of something the schema says there is one of. `blockedReason` renders a sentence
+  instead of the CTA for a
   field with nothing to attach TO yet — never a disabled button, which says only that you may
   not. A LIST and not switchable: documents are identified by NAME, images by CONTENT, so a
   photo field wants `FileGrid`/`FilesEditor` instead — that is a judgment about the data, so it
@@ -1291,8 +1254,8 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   unit (though "kg"/"$" belong IN the value via `InlineNumberInput format`) — composes into a
   row inside the value cell, costing only the row that wants it. The LABEL WRAPS inside its column and
   is never clipped — a fixed `labelWidth` would otherwise ellipsize every long field name
-  ("Registered business address"), and a name the reader can't finish is worse than a taller
-  row; a wrapped label's FIRST line stays level with the value's first control line while a
+  ("Registered business address"); a wrapped label's FIRST line stays level with the value's first
+  control line while a
   one-line label still centers on it (both modes, no prop). The FIELD-ANNOTATION vocabulary (same
   names + meanings as `FormField`), always EXPLICIT — a row never hides guidance behind an ⓘ:
   **`description`** = a fact / persistent guidance (muted), under the VALUE (stacked mode
@@ -1335,10 +1298,9 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   into a pressable door floating its particulars in an anchored popover (put links INSIDE the
   peek — never a button in a button; `reference` is the trailing-link alternative for static
   rows), `LedgerTotal` = the divider-set emphasized close with `zeroLabel` for settled. **`meta` is a
-  neutral QUALIFIER** (a date, a method) at caption weight — never a problem or a state: one
-  row's meta being a fact and another's a complaint is what makes a column read inconsistent,
-  and a caption is the wrong weight for something wanting action. A problem goes on the row
-  that can FIX it, and in a statement the arithmetic has usually said it already.
+  neutral QUALIFIER** (a date, a method) at caption weight — never a problem or a state: a
+  caption is the wrong weight for something wanting action. A problem goes on the row
+  that can FIX it.
   **Pick the shape by what the statement IS**, because there are two and they read differently:
   - **`charges → total`** — `LedgerGroup`s, each **closed by its own sum** ("Charges" vs
     "Received"), giving three ascending rungs: row `sm/regular`, subtotal `sm/medium`, total
@@ -1364,10 +1326,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   whose lookup link sits INSIDE the popover, a flat `reference` on the row with nothing to
   expand, `meta` + `success` tone on money coming back, and a one-row `Adjustments` group that
   takes no `total`. `Received` is derived from the charges carrying a payment METHOD rather than
-  a second flag to keep in step, and the refundable deposit stays OUT because a ledger earns
-  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.
+  a second flag to keep in step. `LedgerBasis` is demoed on the gallery's Charts page instead.
 - **`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
@@ -1375,23 +1334,17 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `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.
+  caller-supplied number.
   `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
+  is never auto-toned by its arithmetic sign — an OUT movement is routine business as often
+  as an IN one. 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.
+  domain the pack cannot own generically ("Tồn kho hiện tại").
 - **`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.
@@ -1404,23 +1357,21 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   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
-  four acts that are four acts. The row splits by WHAT EACH TOUCHES, and the spacer is that
+  dialog-scale and a dialog's verbs are buttons. The row splits by WHAT EACH TOUCHES, and the
+  spacer is that
   seam: **left, the LINK** — `Change` (`onChange`, `secondary`) points the field at a different
   record, named for the intent and deliberately not `danger` since a recoverable correction must
   not wear the colour reserved for destruction; `Clear` (`onClear`, NO fill — the least-reached
   verb of the four) leaves it empty. The draft's footer follows the same rule: `Cancel` carries
   no fill beside a filled `Save`, so the only filled button in either mode is the one that acts. **Both are REQUIRED**, so the footer has one shape
-  everywhere; a reference the record cannot do without gains nothing from hiding Clear, because
-  Change and then declining to pick reaches the same empty state. **Right, the RECORD it points at** — `Edit` (`primary`, the one filled-dark rung,
+  everywhere. **Right, the RECORD it points at** — `Edit` (`primary`, the one filled-dark rung,
   handed to `Save` when the draft opens) and `Open` (`secondary`, rightmost, OPTIONAL, the
-  departure — not prioritized, because on a peek whose facts are correctable in place leaving is
-  the rarest move). Every verb is optional and the footer renders only when it HAS one, so an
+  departure — not prioritized). Every verb is optional and the footer renders only when it HAS
+  one, so an
   edit-only reference draws no rule under nothing.
   **Both unset — they differ only in FOLLOW-THROUGH.** `Clear` is the plain detach (nothing
-  focused); `Change` is the same write plus the caller's focus handoff. They are separate verbs
-  because the follow-through is not inferable from the write: nothing downstream can tell "unset
-  it" from "unset it, I'm about to pick another". Whether empty is VALID is the row's business — its
+  focused); `Change` is the same write plus the caller's focus handoff. Whether empty is VALID is
+  the row's business — its
   `warning`, its validation — never the peek's.
   **Hand the picker focus after `Change`, never after `Clear`.** Both land on your empty state.
   Change said "wrong one", so open the picker focused (`Combobox`'s `autoFocus` both focuses AND
@@ -1466,11 +1417,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   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.
+  label or heading is the caller's, this renders one reference.
 - **`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
@@ -1498,9 +1445,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   **The row OWNS its `title`/`description` pair, so do not hand-roll one beside it.** Both
   lines are `sm`, `leading="tight"`, no gap between them — the stacked-pair law in
   [composition.md](./composition.md), applied by the component rather than restated at each
-  call site. It shipped rendering that pair as PROSE (two 24px boxes plus a 2px gap = 12px
-  between the lines, against the 6px the rule prescribes), and the height was sized around
-  that mistake at 64, which left a correctly-sized `md` mark adrift in it; the row is 56 now.
+  call site. The row is 56.
   A `description` passed as a NODE keeps its own leading — the component only sets it on the
   string branch, because forcing a line box on somebody else's subtree re-spaces content that
   may not be a line of text at all.
@@ -1524,14 +1469,10 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   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
-  what makes scanning twenty records unaffordable. Reach for it when the detail is read or
-  light-edit; a heavy form still deserves its own surface. `expanded` is CONTROLLED — how many
+  container narrows.
+  **`detail` + `expanded` reveal a row's detail BENEATH it instead of navigating away.**
+  Reach for it when the detail is read or light-edit; a heavy form still deserves its own surface.
+  `expanded` is CONTROLLED — how many
   may be open at once is the caller's rule, so the component does not pick one. The detail
   renders as a SIBLING of the press surface (a control inside it would otherwise be swallowed
   by the row's own toggle), the row shows the open wash while it is out, and the door announces
@@ -1539,8 +1480,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   to expand.
   **`Table.count` + `TableRow.ordinal` make it a COUNTED register** — a narrow gutter left of
   `leading` carrying each row's position, headed by the total. Reach for it on any register
-  long enough to scroll: it answers "how many" without paging to the end and "where am I"
-  without counting rows, and it is what a reader coming from a spreadsheet (STT) expects to
+  long enough to scroll — it is what a reader coming from a spreadsheet (STT) expects to
   find. `count` is the single switch — omit it and no gutter is reserved, so an uncounted
   register keeps every pixel it had. It is CHROME, not a column: it never sorts, never drops,
   and is excluded from the column band, but it IS reserved space the fit accounts for.
@@ -1560,8 +1500,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `SortHeaderLabels`: the sortable column header and the sort-state helpers `Table`/
   `DataGrid` consumers drive. `sortBy` copies rather than mutates, and compares strings with
   `localeCompare` (case- and accent-folded, `numeric`) rather than `<`/`>` — code-point order
-  exiles every accented letter past the whole unaccented alphabet, so a Vietnamese register
-  reads correctly until its first Đ and looks fine to a reviewer forever. `getValue` returns a
+  exiles every accented letter past the whole unaccented alphabet. `getValue` returns a
   NUMBER for anything ordered numerically (a timestamp, a count).
 - **`data_grid`** — `DataGrid` + `gridRowStyle`: the inline-managed grouped table (see
   [Tabular data](#tabular-data--pick-by-scale--intent)); `labels` localizes the sort-header
@@ -1593,9 +1532,9 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `Summary.Header` / `Summary.Total` / `Summary.Metric` / `Summary.Distribution` /
   `Summary.Facts`, composed as children. **Declare the buckets ONCE on the root and every part
   derives from them** — the headline is their sum (there is no `total` prop to go stale), the
-  segments and the legend swatches are the buckets' own colours. That correspondence is the
-  reason it exists: a `segments` array passed beside an `items` array beside a `total` drifts
-  three ways, invisibly. A `SummaryBucket` must PARTITION the set; an aggregate over the same
+  segments and the legend swatches are the buckets' own colours: a `segments` array passed
+  beside an `items` array beside a `total` drifts three ways, invisibly. A `SummaryBucket`
+  must PARTITION the set; an aggregate over the same
   rows that does not (a condition like "overdue" beside "draft / sent / paid", counted again
   from a different question) goes to `Summary.Facts` as `extra`, where it renders with NO swatch
   — the visual difference says it is not a slice of the bar. Ordering is the caller's and is
@@ -1631,7 +1570,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   springing to a filled check when done, distinct from the square checkbox; the
   task/to-do/checklist control. `partial` half-fills it, for the row that is underway but not
   finished (a task at "doing", a step whose children are half ticked) — a binary ring reports
-  that row as untouched, in the column readers scan fastest. The CLICK stays binary
+  that row as untouched. The CLICK stays binary
   (`onChange(done)`) so the ring means one thing everywhere; `partial` is reached through
   whatever NAMES it — a status cell, or children ticking off — never by cycling the ring. Keep
   it monochrome and let colour live in the status cell.
@@ -1680,9 +1619,8 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   never dismiss it — clicks, scrolls, and Escape belong to that layer until it closes. In a
   NARROW VIEWPORT (`small`, under 768) it presents instead as a modal bottom sheet (scrim, close
   button, slide-up) — decided by `PopoverContent` itself off the screen size, with nothing to pass
-  and no way to answer it differently: an overlay fills the viewport whatever box it was opened
-  from, so the width of the column holding the trigger is never the question. The viewport, not
-  the device — a few-hundred-pixel side panel on a desktop gets the sheet too.
+  and no way to answer it differently: the VIEWPORT, never the container the trigger sits in,
+  and never the device — a few-hundred-pixel side panel on a desktop gets the sheet too.
   `PopoverContent` already insets its
   body 12px — put content directly in it, NEVER add your own padding `View` (that double-pads);
   title/actions go in `PopoverHeader` / `PopoverFooter`. **A fixed width is the `width` PROP,
@@ -1691,8 +1629,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   then stretches the panel and leaves the content adrift in a box wider than itself. A popover
   with no bands never sees this.
   The built-in scroller is **full-bleed horizontally** and re-insets its content by the same
-  amount, so a scrolling body reaches the panel's real edges — its content slides under the
-  panel edge rather than under an invisible margin 12px inside it — while the text stays on the
+  amount, so a scrolling body reaches the panel's real edges while the text stays on the
   same column the header and footer use. Nothing to opt into; `disableBodyScroll` consumers
   (which own their scroll) are untouched.
 - **`popover_nav`** — `usePopoverNav` + `PopoverScreen` + `PopoverNavHeader` — the popover's
@@ -1735,8 +1672,8 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   section wrappers must be DIRECT children of the ScrollView content. The highlight and the
   jump both re-measure the live DOM on web, so content loading in above a section never
   strands them. Reaching the END of the scroll activates the LAST key regardless of offsets —
-  a final section shorter than the viewport never scrolls its top past the trigger line, so
-  without that it could never be the active one. On NARROW containers
+  a final section shorter than the viewport never scrolls its top past the trigger line.
+  On NARROW containers
   the rail becomes a PINNED bar naming the CURRENT section that opens a full-page
   section-picker `Modal` — never a horizontal tab strip. Worked example:
   [`tpl_record`](../examples/tpl_record.tsx).
@@ -1747,11 +1684,10 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 ### Numbers & charts
 
 **These are where a work screen gets its visual interest, and it is the only kind that survives
-contact with a real dataset.** Software with no photography has to find its imagery in the data —
-a figure at display size, a delta's colour, a line's shape, a bar's proportion, digits aligning
-down a column. Each of these is information first, so none of it is the decoration that gets cut
-in review. A screen reported as flat or boring is usually a screen with numbers in it rendered as
-sentences. → [composition.md](./composition.md) §"Character comes from the DATA".
+contact with a real dataset.** Each of these is information first, so none of it is the
+decoration that gets cut in review. A screen reported as flat or boring is usually a screen with
+numbers in it rendered as sentences.
+→ [composition.md](./composition.md) §"Character comes from the DATA".
 
 Two failure modes to hold against them. A figure nobody compares to anything is not a metric — it
 is a number with a large font, and the size promises a significance it cannot deliver. And a
@@ -1763,7 +1699,7 @@ component rather than showing it at zero.
   (ⓘ), so the reader can find out what "on-time %" counts without leaving the screen.
 - **`kpi_strip`** — `KPIStrip`: the boxed dashboard stat band. Every item has to answer a
   question the surface below it cannot — a strip restating totals the table already carries is
-  the trim test failing, and it costs the reader a pass over the screen to discover that.
+  the trim test failing.
 - **`metric`** — `Metric`: a bare headline figure (`format`
   currency|number|percentage|none, `tone`, `size` sm|md|lg|hero). Bare = no card, no label of its
   own, so whatever contains it has to name it. Always `tabular` — it is set that way here, and it
@@ -1777,10 +1713,13 @@ component rather than showing it at zero.
   Direction words via the `trendFooter` locale slice; goes in `SectionCard footer`.
 - **`sparkline`** — `Sparkline`: the inline mini trend line. Sized for a ROW or a card corner:
   it carries SHAPE (rising, spiky, flat) and no readable values, which is exactly what a
-  register wants — a column of them turns "12 numbers per row" into a pattern the eye reads
-  without stopping. Reach for a real chart the moment someone needs to read a value off it.
+  register wants. Reach for a real chart the moment someone needs to read a value off it.
 - **`bar_chart`** / **`line_chart`** / **`pie_chart`** — `BarChart` / `LineChart` /
-  `PieChart`: the canonical SVG chart set (no recharts).
+  `PieChart`: the canonical SVG chart set (no recharts). `LineChart` prints as many x labels
+  as the track fits and thins the rest, anchored on the LAST point — the newest reading is the
+  one a reader looks up, and anchoring there is what keeps the spacing uniform. The first
+  point is labelled only when it clears the same distance, so a series whose length does not
+  divide evenly drops its opening label rather than crowding the one beside it.
 - **`progress_bar`** — `ProgressBar`: the determinate meter; `compact` = ONE row, track + a
   plain sm tabular count beside it.
 - **`progress_ring`** — `ProgressRing`: the same meter in a circle, and the ONLY circular one. Same API shape as the bar — a real `value`/`max` rather than a
@@ -1792,7 +1731,34 @@ component rather than showing it at zero.
   bare ring renders no text, so it announces nothing — whatever owns it must say what it
   measures.
 - **`stacked_progress_bar`** — `StackedProgressBar`: one whole split across segments (a
-  status mix on one bar).
+  status mix on one bar). Its segments size against EACH OTHER, not against `total` — the
+  track is always full — because one whole is the whole of itself. That is the right model for
+  one bar and the wrong one for a column of them: ten unequal totals draw ten equal bars, which
+  reads as a chart and states nothing. Several wholes → `stacked_bar_chart`.
+- **`stacked_bar_chart`** — `StackedBarChart`: rows of stacked bars on ONE SHARED SCALE
+  (`max` defaults to the largest row total). Bar LENGTH answers "how big is this one", the
+  segment run answers "what is it made of", in one pass — spend against return per campaign,
+  cost make-up per product line. `series` (key/label/colour, one hue family per dimension)
+  drives a legend that is on by default; each `StackedBarRow` takes `label` + optional `meta`,
+  a pre-formatted headline `value` with its `valueTone`, and a `caption` sentence, so colour is
+  never the only channel. Between `stacked_progress_bar` (one whole, own track) and `breakdown`
+  (one whole + ranked share rows beneath it): reach here the moment there are SEVERAL wholes to
+  compare.
+- **`waterfall_chart`** — `WaterfallChart`: the BRIDGE — an opening level, the signed steps
+  that move it, and the level they close at. Revenue walked down to net, budget to actual,
+  opening balance to closing. `items` carry a `kind`: `basis` and `total` are LEVELS standing on
+  zero, `delta` (the default) is a signed STEP floating between the level before it and the
+  level after; colour derives from that — neutral basis, emerald up, red down, and a close in
+  the ink of its own sign — so a caller passes no colours. `orientation` vertical columns |
+  horizontal rows (take rows for a narrow container or long step names; a 70px column and a
+  rotated label is not an answer). The span always includes zero, so a bridge that closes at a
+  loss hangs below the baseline instead of floating on a scale that exaggerates every step.
+  `waterfallLayout` is the pure geometry, exported and tested on its own.
+  Pick it over `ledger` when the reader is scanning for SHAPE (a dashboard), and `ledger` when
+  the figures must be read exactly and reconciled line by line (a record). Over `bar_chart`
+  whenever the bars are steps in ONE arithmetic — five columns all starting at zero state a
+  comparison nobody meant. The steps must be all of the arithmetic and must close on the total
+  drawn; derive them from one computation, never two that can drift.
 - **`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. Pass the stage
@@ -1813,17 +1779,17 @@ component rather than showing it at zero.
   `Matrix.Header` (corner + axis labels) + `Matrix.Grid` (`display` number|heat|both — the
   cells, pressable, the value IN the cell) + `Matrix.Totals` (row + column + grand) +
   `Matrix.Legend`. Pick over `Heatmap` when the NUMBER and totals matter. Figures are
-  RIGHT-aligned — they are `tabular`, and centring them defeats the aligned column that is
-  the reason to read a pivot at all — and row labels carry default ink, because a row's
-  label is its identity, not chrome. `MATRIX_COL_GAP` is exported for a caller budgeting
+  RIGHT-aligned — they are `tabular`, and centring them defeats the aligned column — and row
+  labels carry default ink, because a row's label is its identity, not chrome. `MATRIX_COL_GAP` is
+  exported for a caller budgeting
   its own column widths.
 - **`matrix_totals`** — the data layer for `Matrix`: `matrixTotals` (the cross-tab
   aggregation) + `MatrixAxisItem` / `MatrixCellRef` / `MatrixTotalsResult`; React-free, so a
   KPI can be driven off the same numbers the grid shows.
 - **`highlight_segments`** — `splitHighlightSegments`: cuts a string into plain and
-  highlighted runs for `Composer`'s `highlightRanges`. React-free, and the reason it is
-  separate: it feeds a mirror sitting behind a real text field, so a boundary off by one
-  paints the tint adrift while everything still looks like a working composer. Overlapping,
+  highlighted runs for `Composer`'s `highlightRanges`. React-free: it feeds a mirror sitting
+  behind a real text field, so a boundary off by one paints the tint adrift while everything
+  still looks like a working composer. Overlapping,
   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
@@ -1833,7 +1799,7 @@ component rather than showing it at zero.
   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.
+  extract-on-the-second-hand-roll rule).
 - **`allocation_row`** — `AllocationRow`: one target's row in an allocation surface (pairs
   with `RemainderMeter`).
 
@@ -1863,19 +1829,16 @@ component rather than showing it at zero.
   composition.md §registers); and **`right` renders beside the press target, not inside
   it**, so a control there is valid HTML and keeps its own click — though on a row that
   EXPANDS, verbs belong in the BODY and `right` is better kept for a fact (a duration, a
-  badge). A control sharing the label row with the press target is what produced the nesting,
-  the first-line box and the chevron-pairing problems in the first place.
+  badge).
 - **`checklist`** — `Checklist` + `ChecklistGroup` + `ChecklistItem` + `ChecklistNote` /
   `ChecklistActions` / `ChecklistField`: THE run of tickable rows, at any
   altitude — a ring, a title, a value beside it, a muted note, a detail block, an optional
   grouping level. **`connected` is the LINE joining the rings, and it is the whole
-  difference**: on for ONE record walking positions (it asserts
-  sequence), off for a SET picked in any order, where a line claims an order the work does not
-  have. Rows are ticked ONE AT A TIME; where the run is a sequence, derive position from the
+  difference between a SEQUENCE and a set picked in any order.** Rows are ticked ONE AT A TIME; where the run is a sequence, derive position from the
   highest stamp so one click marks everything below it — a parent that ticked its children wrote
   what the reader never said (today's date onto milestones that happened on unrecorded days),
-  and a rung passed without a recorded day shows a BLANK date, which is the honest answer to
-  "when". **`ChecklistGroup` is a phase — a name, and at most a way to fold its rows away**: no
+  and a rung passed without a recorded day shows a BLANK date. **`ChecklistGroup` is a phase — a
+  name, and at most a way to fold its rows away**: no
   COMPLETION control, because a phase
   owns no completion of its own and a ring there is a control that never responds (one identical
   to the pressable rings beneath it invites the press it refuses); and no BODY, because a
@@ -1935,7 +1898,7 @@ component rather than showing it at zero.
   `accept`, `label`/`hint`/`dropLabel`, `height`); click falls back to a picker, and while
   mounted it ALSO takes a paste (Ctrl/Cmd+V) via its inner `FileDropTarget` `paste`, scoped to
   the well's region. `label`/`dropLabel`/`hint` default from the locale's `fileDropzone` slice
-  (the hint now names the paste) — pass them only to override.
+  (the hint names the paste) — pass them only to override.
 - **`file_drop_target`** — `FileDropTarget`: makes ANY region accept a file drag-drop —
   `{ onFiles, accept?, multiple?, paste?, disabled?, children, style? }` wrapped around a
   section, a card, a whole panel, so nobody hunts for a dropzone. While a drag hovers, the
@@ -1972,8 +1935,8 @@ component rather than showing it at zero.
   needs, so withholding `onAdd`/`onRemove` IS the read-only shape — there is no `readOnly`
   mode. **A HOST verb is a plain `Button`** reading **`useFilesEditorSelection()`**
   (`{selected, selectedIds, files, selectMode, clear, exit}`) — an AI read over the picked
-  papers, "send to the broker", a ZIP: acts the kit has never heard of, which is why there is
-  no props-per-act toolbar and no generic Menu. **No children means no bar** (a grid that only
+  papers, "send to the broker", a ZIP: acts the kit has never heard of. **No children means no
+  bar** (a grid that only
   previews). Bar words resolve prop → `LoticsLocale.filesEditor`; in-flight tile words →
   `LoticsLocale.fileUpload`. **No empty state:** with zero files it is a bare bar, so pair it
   with a `FileDropzone` for the well a records screen opens on. Use `FileGrid`/`FileRows` bare
@@ -2002,8 +1965,8 @@ component rather than showing it at zero.
 - **`file_thumbnail`** — **`diff`** puts a `DiffKind` corner mark on a tile (top-LEFT, the one
   corner remove/selection/uploading do not claim) and fades a `removed` one. The mark rides a
   white RING: a tile's ground is an arbitrary photo, and a pale tint over a pale scan is a
-  smudge. A `removed` tile fades its BODY only — the mark stays at full strength, since a faded
-  mark is the smudge the ring exists to prevent. Ignored at the ROW rung: a corner disc on a row-sized tile is the tile, and such a tile lives
+  smudge. A `removed` tile fades its BODY only — the mark stays at full strength. Ignored at
+  the ROW rung: a corner disc on a row-sized tile is the tile, and such a tile lives
   inside a row that carries the change instead. A grid says MEMBERSHIP well (arriving, leaving) and PAIRING not at
   all — nowhere on a 96px tile to name what a replacement supersedes — so a set where things
   are being REPLACED wants `FileRow`. Also: `FileThumbnail` + `DisplayFile` + `THUMBNAIL_SIZE` /
@@ -2035,7 +1998,7 @@ component rather than showing it at zero.
   + a ⋯ Download/Open-external/Remove menu; composes `FileRow` + `ActionMenu` +
   `FileGalleryModal`; localized via the `gallery` locale slice. **`meta` has NO default**: the
   badge states the type as colour and as a label, and the filename ends in the extension, so a
-  type caption was a fourth statement of one fact costing a line of row height. Pass a second
+  type caption is a fourth statement of one fact costing a line of row height. Pass a second
   line only when it carries something the NAME does not — what an invoice covers, who uploaded
   it, when it landed.
 - **`file_badge`** — `FileBadge`: the two-tone file-type mark (PDF / XLSX / DOCX / video /
@@ -2065,8 +2028,7 @@ component rather than showing it at zero.
   absolutely inside a positioning wrapper the component owns) because a `<video>` is a
   replaced element: once metadata loads it reports the source's intrinsic size, and any
   ancestor sized by its content grows to match — with RN-web's `flexShrink: 0` default,
-  nothing pushes back, so a 720p capture measurably widened a 342px chat column to 367px
-  the moment it loaded. **Do not add your own fullscreen/expand control**: the native
+  nothing pushes back. **Do not add your own fullscreen/expand control**: the native
   transport already carries fullscreen, picture-in-picture and download, and a second
   affordance beside them is both redundant and a claim about where it leads. A source it
   cannot load is surfaced, never silent — a media element that fails paints an EMPTY BOX and
@@ -2165,10 +2127,9 @@ component rather than showing it at zero.
 - **`confidence`** — `Confidence` + `ConfidenceLevel` + `levelFromScore`: confidence IS a
   callout — the meter + level phrase head the block, the REQUIRED `children` carry the basis
   (what was checked, what failed); the box stays white with a hairline border at every
-  level — the meter is the only colored element. There is NO standalone meter — a level without its reasons cannot
-  be rendered; where a compact meter used to decorate a ranked row or proposal card, rank /
-  badges / severity carry the standing instead. Also: calibrated
-  high/med/low; localized via the provider.
+  level — the meter is the only colored element. There is NO standalone meter — a level without
+  its reasons cannot be rendered; rank / badges / severity carry the standing instead. Also:
+  calibrated high/med/low; localized via the provider.
 - **`diff_value`** — **`DiffValue`, THE atom of a review surface**: a value that changed,
   rendering `before` struck above/before `after`. Owns no container, no context, no decision —
   so it drops into a table cell, a `DetailRow`, a total, a chip or a sentence and inherits that
@@ -2176,16 +2137,15 @@ component rather than showing it at zero.
   a chip for a link being repointed — and a node `before` is struck by a DRAWN rule rather than
   by text decoration, because `line-through` on a `Text` does not cross a `View` child (the old
   value would otherwise render at full strength beside its replacement with nothing saying it is
-  the one going away — type-checked, rendered, and wrong). Reach for a node when the value
-  genuinely is not text: an avatar carries identity a string cannot, and a review that swapped
-  the record's own chip for a name would show the operator a surface they have never seen at the
-  one moment they are asked to check something. A node belongs where it fits at FULL size — a
-  form row, a card. Shrinking a composite into a table cell takes its own type off the scale
-  (a file badge sized to a cell rendered its label at 5px), so a file in a CELL is a filename at
-  the column's own size, not a miniature badge. Worked in `dev/pages/ai.tsx` § every shape.
+  the one going away). Reach for a node when the value
+  genuinely is not text: an avatar carries identity a string cannot. A node belongs where it
+  fits at FULL size — a
+  form row, a card. Shrinking a composite into a table cell takes its own type off the scale,
+  so a file in a CELL is a filename at the column's own size, not a miniature badge. Worked in
+  `dev/pages/ai.tsx` § every shape.
   **`before === after` collapses to ONE plain value** —
   agreement is not a change, and a document confirming what the record already says is the
-  GOOD case, not a diff of a value against itself. **`delta`** (a host-formatted string, the
+  GOOD case. **`delta`** (a host-formatted string, the
   same contract as `Finding.delta`) prints HOW FAR it moved, because
   `1.600.000 → 1.481.481` otherwise makes the reader subtract to find out whether a
   correction is trivial or alarming. `layout` stacked (a column of figures) | inline (prose, dense
@@ -2193,9 +2153,9 @@ component rather than showing it at zero.
   for an addition, `after` for a removal. BOTH values stay on screen: the old one is the only
   evidence the reader has that the correction is the right SIZE.
   **`placeholder` is YOUR string — translate it.** The component renders no word of its own
-  (its only fallbacks are `—` and empty), so nothing here reaches the locale packs. That is
-  deliberate rather than an omission: `DiffMark` beside it DOES ship localized words, but the
-  two are different sentences even when English collides them — the mark says what happened to
+  (its only fallbacks are `—` and empty), so nothing here reaches the locale packs.
+  `DiffMark` beside it DOES ship localized words, but the two are different sentences even when
+  English collides them — the mark says what happened to
   the ROW ("Removed" / "Xóa"), the placeholder says what is in the FIELD now, which reads "đã
   xóa" or "bỏ trống", never the bare verb. The same prop also carries "Pick a candidate below"
   and "Not on the document". Pull it from your own catalog.
@@ -2204,9 +2164,8 @@ component rather than showing it at zero.
   accessible word (never colour alone — "added" vs "removed" by hue is invisible to a reader who
   cannot separate them, and that is the distinction a review turns on). **ONE treatment
   everywhere: a filled 22px DISC**, 14px glyph, 700 ink on a 100 ground. A form marked with bare
-  glyphs beside a table marked with filled shapes reads as two systems saying the same thing; a
-  reader parses shape before meaning, so an unexplained difference reads as an accident however
-  principled the reason. The disc also gives the glyph its own ground, which is what lets one
+  glyphs beside a table marked with filled shapes reads as two systems saying the same thing.
+  The disc also gives the glyph its own ground, which is what lets one
   mark sit on a white row, a tinted cell, or a photograph. **`unchanged` renders as an empty
   disc-sized HOLE** — silence is the honest rendering of "nothing happened", it keeps the
   column's width so nothing shifts left, and it announces nothing (eleven "Unchanged"es is the
@@ -2217,8 +2176,7 @@ component rather than showing it at zero.
   an `Inline*` editor draws (40px band, 8px horizontal padding inside a 1px transparent border),
   minus the editor. A record's value column mixes editors with things that are not editors, and
   anything rendered raw beside them starts at the cell edge, 20px tall, at the top — so the
-  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
+  column quietly acquires TWO left edges and two baselines. `InlineStatic` is the
   STRING case and composes it; reach for the slot when the value is a node, which a review
   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