@lotics/ui 46.1.0 → 46.3.0

package/AGENTS.md

@@ -75,6 +75,30 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 - **The kit's fonts/colors/icons ARE the design system** — never a custom font, icon set, or
   hand-picked palette shade; color is `solid`/`tint`/`ramp` with ONE accent per screen.
   → [composition.md §"Color discipline"](./docs/composition.md).
+- **An overlay paints in the order it was OPENED, and a scroller that swaps content opens the new
+  content at the top.** Compose overlays wherever you like — a `Dialog` written beside the
+  `Drawer` whose row opens it works, both ways round, and a `Dialog` opened from an open `Popover`
+  paints over its panel. An overlay of your OWN gets that for free by rendering its react-native
+  `Modal` **only while open** (`{open && <Modal visible …>}`); mounted while closed it takes its
+  body-level slot on the app's first paint and is then covered by anything opened later —
+  rendering and announcing perfectly, dead to every press. The z-index rungs beside the overlays
+  are published in `overlay_layer`, so never hand-pick a number to clear a Lotics overlay.
+  `DrawerScrollArea` / `DialogScrollArea` / `ModalBody` take a `scrollKey` and the routed
+  `Popover` takes the same seam off its route, so a swapped-in record opens at the top and the
+  reader returns to their place on the way back.
+  → [composition.md §"Canvas & content column"](./docs/composition.md)
+  → [catalog.md §"Overlays & navigation"](./docs/catalog.md)
+- **ONE VALUE, ONE RENDERING, inside one card — the chart draws the entity its table draws.**
+  A value's filter renders it the way its cell does, and the same rule reaches the chart beside
+  the table: `StackedBarRow` and `BarChartItem` take a `leading` slot for the entity's own mark.
+  A LEGEND row is the exception — its subject is a category, and the swatch is that identity.
+  → [composition.md §"A register that TRIAGES"](./docs/composition.md).
+- **A row says which side HOLDS; `numberOfLines` handles the side that gives way.** The clamp
+  brings its own `minWidth: 0` + `flexShrink: 1` (a clamp that cannot shrink cannot clamp), so
+  what a call site still has to state is `flexShrink: 0` on the figure or control that must stay
+  whole. Same law on a categorical axis: the LABELS thin to fit, the bars never do.
+  → [composition.md §"Typography"](./docs/composition.md),
+  [catalog.md §"Numbers & charts"](./docs/catalog.md).
 - **Hand-typed type is off-system — and it always lands too small.** Every run of language is
   `<Text size= weight= color=>` on the fixed rungs. **Grep the diff: `fontSize:` / `lineHeight:` /
   `letterSpacing:` outside `src/` is a bug.** → [composition.md §"Typography"](./docs/composition.md).

package/MIGRATION.md

@@ -4,6 +4,93 @@ Breaking changes, newest first — normally per major, plus the rare minor that
 anyway (recorded under its exact version). The current contract lives in `AGENTS.md` + `docs/`;
 this file exists only to move an app from one release to the next.
 
+## 46.3.0
+
+**A `Text` with `numberOfLines` now declares `flexShrink: 1` + `minWidth: 0` for you.**
+A clamp that cannot shrink cannot clamp: on web a clamped `Text` is `white-space: nowrap`, so
+`min-width: auto` floors it at the WHOLE string; on native a `Text` is `flexShrink: 0`. Either way
+two clamped values on one row laid out at intrinsic width and ran off the frame. Both declarations
+now come with the clamp, and both are no-ops until a row actually overflows.
+
+Nothing's API changed, but **a layout default moved under every clamped `Text` in your app** — this
+is the one 46.3.0 change to re-check by looking. Two shapes are worth a pass:
+
+- A flex ROW where a clamped `Text` was the side that HELD and an unclamped sibling gave way. Both
+  can shrink now, so the wrong one may truncate.
+- A flex COLUMN with a bounded height (a fixed-height card, a `maxHeight` panel). `flexShrink` acts
+  on the MAIN axis, so a clamped `Text` that used to hold its height can now be compressed.
+
+The pair sits BEFORE your own `style`, so the site that must stay whole says so:
+
+```diff
+-<Text numberOfLines={1}>{amount}</Text>
++<Text numberOfLines={1} style={{ flexShrink: 0 }}>{amount}</Text>
+```
+
+That is how a figure keeps winning over its label. `minWidth` is overridden the same way
+(`style={{ minWidth: "auto" }}`) on the rare surface that wants the old min-content floor back.
+
+**An overlay of your OWN must render its react-native `Modal` only while it is OPEN.**
+`Dialog`, `Drawer`, `Modal` and `FileGalleryModal` now do — nothing in their API changed — and a
+hand-rolled overlay outside the kit has to do the same, or it loses to them:
+
+```diff
+-<Modal visible={open} onRequestClose={close} transparent>
+-  …
+-</Modal>
++{open && (
++  <Modal visible onRequestClose={close} transparent>
++    …
++  </Modal>
++)}
+```
+
+react-native-web appends a `Modal`'s body-level `<div>` on its FIRST render and never re-orders
+it, so an overlay mounted while closed takes its slot on the app's first paint and is then covered
+by any overlay opened later — while rendering, reading and announcing perfectly, with only its
+presses dead. Nothing is lost by the change: react-native-web renders a closed `Modal`'s children
+as `null` already, so only the empty portal div was being held. A takeover with
+`animationType="fade"` keeps its fade IN and now closes immediately, as `FileGalleryModal` always
+has; state that must survive a close belongs outside the `Modal` element either way.
+
+**The overlay z-index rungs are now published constants.** The numbers are unchanged for `Tooltip`
+and `Alert` (`10000`) and for a toast (`10001`); **the skip link moved `10001` → `10002`**, off the
+rung it was sharing with a toast. Read the rung instead of naming a number:
+
+```diff
+-import { View } from "react-native";
++import { NOTIFICATION_Z } from "@lotics/ui/overlay_layer";
+ …
+-  zIndex: 10001,
++  zIndex: NOTIFICATION_Z,
+```
+
+The full table is in `docs/catalog.md` § Overlays & navigation: `OVERLAY_Z` (every overlay, and
+`Popover`), `OVERLAY_Z_ABOVE` (tooltip/alert), `NOTIFICATION_Z` (a toast), `SKIP_LINK_Z`.
+
+**`PageContent`'s title band is now a `PageHeader`**, so the two stop drifting. `title`,
+`titleRight` and `description` are unchanged, and `PageHeader`'s `title` became optional — but the
+band's rhythm is now `PageHeader`'s everywhere: a description sits **8px** under the title (it was
+flush in `PageHeader`) and the band clears **16px** before the content (it was 24 in
+`PageContent`). Nothing to change; worth one look at a page shell you care about.
+
+**`useChangeSet`'s per-proposal default is a MAP, not a predicate.** `initial: "accepted"` /
+`"pending"` are unchanged.
+
+```diff
+-useChangeSet(ids, { initial: (id) => (overwrites.has(id) ? "rejected" : "accepted") })
++const initial = useMemo(
++  () => new Map(rows.filter((r) => r.overwrites).map((r) => [r.id, "rejected" as const])),
++  [rows],
++);
++useChangeSet(ids, { initial })
+```
+
+An id the map does not name arrives `accepted`, as before. A value rather than a function is what
+lets the default be an ordinary dependency: `status` and the group arrays derive from it together,
+so `status` changes identity whenever a decision does — which a screen that memoizes its rows on
+`review.status` needs, and which a predicate held out of the dependency lists could not give.
+
 ## 46.0.0
 
 **`AgentRun` / `AgentProgress` drop `stepsLabel`, and the `agentRun` locale slice drops `steps`.**

package/docs/ai_patterns.md

@@ -177,8 +177,15 @@ PUT and rolls the calls out BELOW it on press.
 
 **ONE row for the whole run, and NO prose until it ends.** While the agent works, the entire feed
 is a single row. It names the call in flight — "Searching records" — and says
-**"Thinking…"** whenever the model is writing rather than calling, which is every gap between
-calls. The dot pulses; nothing rolls out unless the reader asks.
+**"Thinking"** whenever the model is writing rather than calling, which is every gap between
+calls. Nothing rolls out unless the reader asks.
+
+**An unsettled row BREATHES**, label and dot together — the label on the same opacity rhythm the
+dot's halo runs (750ms each way), so one line carries one animation rather than two that drift
+apart. That breath is what says "in progress", which is why no live label ends in an ellipsis:
+punctuation was standing in for motion, and a screen reader drops it anyway. A row that is not
+working does not breathe — settled, and `awaiting` a human decision, which is parked rather than
+in flight.
 
 **No step count.** The row says WHAT is happening and stops there. A tally was a number the reader
 could act on in no way: live, the label already changes on every call, so it added no motion the
@@ -208,12 +215,14 @@ reasoning part. An interleaved-thinking run therefore rebuilt the stack one grou
 reader watched finished rows pile up while they waited, and was then left with that pile sitting
 above the answer at the answer's weight, every row of it stale.
 
-**Expanding is where live and settled differ, and the only place they do.** Opened mid-run the
-timeline is CAPPED and self-pinning (220px, ~5 rows) — someone who opens a run in flight asked to
-see the work, not to hand the page a feed that grows for another minute; `FollowScroll` follows at
-LAYOUT level so each call paints already pinned. Opened once settled it is uncapped: nothing is
-arriving, so there is nothing to cap. Settling never closes what a reader opened; it just stops
-capping it.
+**Expanding works the same live and settled** — the timeline opens IN FULL, and the HOST'S OWN
+scroller keeps the newest row in view. `AgentRun` never frames itself. It shipped once with a
+live-only 220px window, and that window was a scroll container nested inside whatever scroll
+container the run already sat in: in chat, an inverted list inside an inverted list, which painted
+stale content over the neighbouring messages and took the wheel from the surface the reader was
+on. A component in document flow cannot know whether it is inside a scroller, so it must not act
+as one. A host that genuinely needs a bound takes the framing job itself — `collapseProcess={false}`
+plus its own `FollowScroll`. Settling never closes what a reader opened.
 
 The split is POSITIONAL (`splitTimeline` in `agent_transform`): what comes after the last tool
 call is the answer, everything before it is the work. Nothing has to decide whether a paragraph
@@ -261,10 +270,10 @@ tinted panel rather than another step row, and it carries `role="alert"` so a sc
 action (a secondary `Button`) sits INSIDE that panel so the operator can re-fire the run; omit it
 and the panel carries the message alone.
 
-**`FollowScroll` — only when you took the job (`collapseProcess={false}`).** A run opened mid-flight
-already caps itself with exactly this, so wrapping the default AGAIN nests a scroller in a
-scroller: the outer never overflows, the inner holds the content, and the wheel lands on whichever
-the pointer happens to be over. Reach for the wrapper when the run is a raw timeline you are
+**`FollowScroll` — only when you took the job (`collapseProcess={false}`).** On the default, the
+run is plain content in your flow and your own scroller follows it; adding a wrapper there nests a
+scroller in a scroller — the outer never overflows, the inner holds the content, and the wheel
+lands on whichever the pointer happens to be over. Reach for the wrapper when the run is a raw timeline you are
 framing yourself — a dialog, drawer, or fixed-height panel where the feed grows BELOW the fold and
 a plain scroll container doesn't follow. Wrap it then:
 `<FollowScroll style={{ maxHeight: … }}><AgentRun … collapseProcess={false} /></FollowScroll>` — the same
@@ -281,7 +290,7 @@ for free — no hand-assembly): `<AgentRun parts={run.parts} state={…} error={
 [the SDK doc](../../app-sdk/docs/ai.md) for the hook. The `ai` package is a regular dependency of
 `@lotics/ui` — its part TYPES resolve transitively in any consumer's typecheck with nothing to
 install; the imports are type-only (purity-enforced), so no `ai` runtime ever enters a bundle.
-**A run with no parts yet renders the breathing "Starting…" row** (streaming state only) — the
+**A run with no parts yet renders the breathing "Starting" row** (streaming state only) — the
 live dot plus a label that pulses, covering the gap between the CTA press and the first streamed
 part (upload + run creation + first token). **The law: pass
 `state="streaming"` from the moment the paid CTA fires — uploads included — and render
@@ -370,6 +379,17 @@ alignment and rhythm.
   `keptCount`/`total`/`settled`. `initial` defaults to **`accepted`** so an operator drops
   exceptions instead of approving eight identical lines; pass `pending` when each change
   genuinely deserves its own verdict, and gate the commit on `settled`.
+  - **A set that mixes KINDS defaults per kind: `initial` also takes a `Map<id, decision>`.** A
+    review usually holds both — filling a blank should arrive `accepted`, overwriting a value a
+    human already set should arrive `rejected`, so the destructive half is opt-in — and one
+    global default puts one of the two on the wrong footing. An id the map does not name arrives
+    `accepted`. Build it with a `useMemo` over the proposals your screen already holds, which is
+    what keeps the hook ignorant of what a proposal IS; a VALUE (rather than a predicate written
+    inline) is what lets `status` and the group arrays derive from it together, so `status`
+    changes identity the moment a decision moves and a screen memoizing its rows on it re-runs.
+    Deciding those rows by calling `reject()` from the result handler instead writes overrides
+    nobody made, and `undo` then hands the row back **accepted** — the destructive change
+    silently in, from the control that means "undo".
 
 ### The shapes, and what each one is
 
@@ -518,7 +538,7 @@ whole pane with no backend ([`tpl_item_list`](../examples/tpl_item_list.tsx) doe
 
 **Customize through the seams, or drop to the primitives.** `labelForCall` / `renderToolOutput`
 pass through to `AgentRun`; the `run` object is the data seam. There is deliberately NO
-empty-state slot — `AgentRun` renders its own localized "Starting…" row on zero parts, and the law
+empty-state slot — `AgentRun` renders its own localized "Starting" row on zero parts, and the law
 above forbids hand-rolling a placeholder. An app that wants a different ARRANGEMENT does not fight
 the pane: `AgentRun`, `ClarifyWizard`, `ClarifyWizardScope`/`Actions`, `FollowScroll` and
 `DialogScrollArea` all remain exported, and composing them is what this pane itself does.

package/docs/catalog.md

@@ -443,6 +443,10 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   numbers), `weight`, `color`, alignment, tabular numerals. **`leading="tight"`** sets the line
   box for a STACKED PAIR rather than for prose — a subject over its supporting line, a value over
   its annotation; see composition.md, which also covers the `gap` that goes with it.
+  **`numberOfLines`** clamps, and brings the `minWidth: 0` + `flexShrink: 1` that makes clamping
+  possible on a flex row — a clamp that cannot shrink cannot clamp. Both are no-ops until the row
+  overflows, and a `style` on the call site still wins, so a value that must never give way says
+  `flexShrink: 0` and keeps holding over its own label.
 - **`eyebrow`** — `Eyebrow`: the small quiet label above or beside a VALUE (`xs` muted medium) —
   a metric caption, a field name in a cell, an artifact tag. Takes `color` (for a VERDICT word
   like "Mismatch") and `align`, and deliberately takes no `size`, `weight` or `transform`:
@@ -702,16 +706,21 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   useSeparator` inserts and what menus/popovers put between option groups.
 - **`container`** — `Container`: centers content at a max width (`ContainerSize` sm|md|lg,
   `CONTAINER_SIZES`).
-- **`page_header`** — `PageHeader`: the page's title band. `actions` puts page-level CTAs on
+- **`page_header`** — `PageHeader`: the page's title band, and the ONE place that band is
+  defined — `PageContent`'s `title`/`titleRight`/`description` render one of these rather than a
+  second copy of the row. `actions` puts page-level CTAs on
   the title row (right-aligned) and `trailing` puts a control immediately AFTER the title;
   `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". Under a title too long for
   the row the TITLE gives way and wraps while `trailing`
-  and `actions` keep their width.
+  and `actions` keep their width. **The band owns the space under itself** — 16px, whether it
+  is rendered on a hand-rolled screen or by `PageContent`; a shell adds nothing after it, or
+  the same band closes on two different rhythms depending on which shell a screen picked.
 - **`page_content`** — `PageContent` + `PAGE_SIZES`: the page's padded, width-capped content
-  region — a centred column with optional `title`/`titleRight`/`description`, `header`/`footer`
+  region — a centred column with optional `title`/`titleRight`/`description` (which render a
+  `PageHeader`, so the band's row law and rhythm have one home), `header`/`footer`
   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 —
@@ -1586,15 +1595,56 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 
 ### Overlays & navigation
 
+**Every overlay paints in the order it was OPENED**, so mount them wherever composition wants — a
+`Dialog` written beside the `Drawer` whose row opens it is the ordinary shape and it works; a
+drawer opened from a dialog covers the dialog, which is the same rule the other way round. There
+is no layer prop and nothing at the call site has to know the tree order. It covers every
+body-level surface the kit has, `Popover` included: a `Dialog` or a file-preview `Modal` opened
+from an open popover paints OVER the panel that opened it. `Alert` and `Tooltip` stay above every
+overlay at any depth.
+
+**The one rule an overlay of your OWN has to follow: render the react-native `Modal` element only
+while it is open** (`{open && <Modal visible …>}`, or an early `return null`). react-native-web
+appends a `Modal`'s body-level `<div>` on its FIRST render and never re-orders it, so an overlay
+mounted while closed has already taken its slot before anything opened — and once two overlays tie
+at the same z-index, that slot is what decides. The symptom is nasty precisely because it is not
+visual: the covered surface renders, reads and announces perfectly, and only its presses do
+nothing. Nothing is lost by not mounting it — react-native-web renders a closed `Modal`'s children
+as `null` anyway, so only the empty portal div was ever being held, and anything that must survive
+a close (a router, a context, form state) belongs outside the `Modal` element regardless.
+
+**The rungs beside the overlays are a published contract** (`overlay_layer`), because a surface
+OUTSIDE the kit that has to clear a Lotics overlay cannot do it with a hand-picked literal:
+
+| z-index | what sits there |
+|---|---|
+| `9999` | every overlay, and `Popover` — `OVERLAY_Z` |
+| `10000` | `Tooltip`, `Alert` — `OVERLAY_Z_ABOVE` |
+| `10001` | a transient notification / toast — `NOTIFICATION_Z` |
+| `10002` | the skip link — `SKIP_LINK_Z` |
+
+Overlays all share one rung on purpose: DOM order settles the tie and DOM order is open order.
+`Popover` is on it too — it is no `Modal`, but it portals into the nearest `PortalHost`, so one
+opened inside an overlay is already inside that overlay's stacking context and a page-level one is
+a child of the app root, which every overlay's body-level box follows.
+
 - **`portal`** — `PortalHost` + `Portal`: the floating-content mount point; the app root
   needs ONE `PortalHost` or `Dialog`/`Popover`/`Tooltip`/`Alert`/`OptionList` cannot render.
 - **`dialog`** — `Dialog` (+ `DialogHeader`/`DialogHeaderTitle`/`DialogFooter`, `useDialog`,
   `useDialogNavigation`): the centered card over a scrim; BAKES a screen router in
-  (`<Dialog><Screen route="">…` — see `screen_router`).
+  (`<Dialog><Screen route="">…` — see `screen_router`). `DialogScrollArea` takes the same
+  **`scrollKey`** seam as `DrawerScrollArea` for a pane that swaps its body in place; a dialog
+  navigating between `Screen`s does not need it, because a stacked screen stays mounted and keeps
+  its own offset.
 - **`drawer`** — `Drawer` + `DrawerScrollArea` + `DrawerFooter`: the docked side panel with scrim; the
   register row's edit surface. ONE standard width (600px) — pass `width` only for a genuinely
   exceptional panel; full-width on small screens. `DrawerScrollArea` is the guttered content
-  region — `DialogScrollArea`'s counterpart — so never hand-pad a drawer body. It always
+  region — `DialogScrollArea`'s counterpart — so never hand-pad a drawer body. Give it a
+  **`scrollKey`** (the open content's identity — `scrollKey={openChild?.id}`, where the undefined
+  leg names the root content rather than opting out) on a drawer that SWAPS its body in place, so
+  the new content opens at the top and the previous one's offset returns on the way back — the seam
+  `DialogScrollArea` and `ModalBody` take too, and the one thing a React `key` on the scroller
+  cannot buy, since that resets the parent's place along with the child's. It always
   scrolls: a padded box around a `flex:1` scroller insets that scroller's viewport, ending the
   list short of the panel with the last row clipped. Two bodies skip it and take the `Drawer`'s
   bare slot: a FULL-BLEED one (a band spanning the panel, a record screen with its own gutters),
@@ -1605,7 +1655,8 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   edge-to-edge takeover: an OPAQUE surface that COVERS THE WHOLE SCREEN, so unlike Dialog
   (centered card WITH scrim) and Drawer (docked panel WITH scrim) there is nothing behind it
   to dim — NO scrim, NO backdrop. Lays children as a flex column: a pinned ModalHeader
-  (eyebrow/title + an actions slot + close), a flex:1 scrolling ModalBody, a pinned
+  (eyebrow/title + an actions slot + close), a flex:1 scrolling ModalBody (which takes the
+  **`scrollKey`** seam — a wizard stepping between steps swaps its body in place), a pinned
   ModalFooter (the commit bar, same chrome as DialogFooter/DrawerFooter). Reach for it for a
   focused capture / multi-step wizard / a console the user steps INTO; pick Dialog when the
   surface is a card the user can see context around.
@@ -1631,11 +1682,16 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   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 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.
+  (which own their scroll) are untouched. It also carries the **scroll seam** every scroller
+  that swaps its body in place takes — keyed on the routed popover's current route, with no prop
+  at call site, and inert in a popover that has no sub-screens.
 - **`popover_nav`** — `usePopoverNav` + `PopoverScreen` + `PopoverNavHeader` — the popover's
   built-in mini-router: EVERY `Popover` provides the nav context (`navigate(route)` pushes,
   `goBack`, `currentRoute`, `canGoBack`; resets on close), `PopoverScreen route=""` is the
-  root and screens render conditionally (unmounted when inactive — no scroll preservation),
+  root and screens render conditionally (unmounted when inactive, so a screen's own state does
+  not survive the round trip — the panel's SCROLL does: the screens share `PopoverContent`'s one
+  scroller, which takes the ROUTE as its seam key, so a sub-screen opens at the top with its
+  `PopoverNavHeader` in view and the root list's offset returns on the way back),
   `PopoverNavHeader` is the title row whose back chevron auto-appears while `canGoBack`
   (`right` slot, `backLabel`). For a multi-screen menu inside ONE popover; route PATTERNS,
   `params`, and stacked-alive screens are `screen_router`'s job.
@@ -1661,6 +1717,11 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   content) — it is what `SectionHeadingTitle.info`/`CardHeaderTitle.info` render.
 - **`alert`** — `Alert` (+ `AlertButton`/`AlertOptions`): the blocking confirm —
   `Alert.alert(title, message, [{cancel}, {destructive}])`.
+- **`overlay_layer`** — `OVERLAY_Z` / `OVERLAY_Z_ABOVE` / `NOTIFICATION_Z` / `SKIP_LINK_Z`: the
+  ONE paint-order table for everything that reaches `document.body` (the rungs are in the table
+  above), and the file that states why open order works. Constants only — there is no layer to
+  render and nothing to claim; an overlay of your own gets its place by mounting its react-native
+  `Modal` only while it is open. Never write one of these numbers as a literal.
 - **`overlay_scope`** — `isOverlayScopeActive` / `pushOverlayScope` / `useOverlayScope`: the
   module-level open-overlay counter every overlay primitive reports into; the host's
   shortcut registry reads it synchronously to floor page-level shortcuts while any overlay
@@ -1715,11 +1776,24 @@ component rather than showing it at zero.
   it carries SHAPE (rising, spiky, flat) and no readable values, which is exactly what a
   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). `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.
+  `PieChart`: the canonical SVG chart set (no recharts). **A categorical axis prints as many
+  labels as the track fits and thins the rest** — `LineChart` and `BarChart`'s vertical
+  orientation both, because it is the axis's rule and not one chart's. It is anchored on the LAST
+  position: the newest reading is the one a reader looks up, and anchoring there is what keeps the
+  spacing uniform; the first position 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. **The BARS never thin** — how many bars a card carries is a question about the data,
+  never about how wide a label happens to be, and an unlabelled bar keeps its slot so the row
+  above stays in line. **What thins is the whole annotation, label AND value together**, because a
+  bar's name and its figure are one reading: a number under an unnamed bar is a quantity of nothing
+  a reader can name, and the surviving annotation is widened across the room its dropped neighbours
+  vacated — room the figure needs as much as the name does. So a DENSE vertical `BarChart` (more
+  bars than `track ÷ 50px`: a 30-day daily series in a 600px card keeps roughly ten) shows the
+  figures only for the bars it labels. When every bar's number has to be readable, that is a
+  `Table` or the horizontal orientation, which gives each entity its own row and its own value
+  column. `BarChart`'s horizontal orientation is one row per entity: **`labelWidth`**
+  sizes the fixed label column (default 80, which fits a date and not a company name), and each
+  item's **`leading`** slot carries that entity's own mark ahead of its name.
 - **`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
@@ -1741,7 +1815,10 @@ component rather than showing it at zero.
   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`
+  never the only channel. **`leading`** is the entity's own mark (`BrandMark`, `Avatar`, a status
+  dot), centred on the label's line box — a row's segment colours belong to the MEASURE, so unlike
+  a legend row this one carries no identity until you give it one, and a chart beside a table over
+  the same entities has to draw them the same way (composition.md § the register's own craft). 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
@@ -2094,13 +2171,15 @@ component rather than showing it at zero.
   hatch — input/error untouched). A per-tool failure shows amber with the reason in its expanded
   Error panel; a run-level breaking `error` (outside `parts`) renders as a terminal danger row, with
   an optional `onRetry` Button under it. While it runs the whole feed is ONE row and NO prose: the
-  row names the call in flight ("Searching records") and says "Thinking…" whenever the
-  model is writing rather than calling. The agent's between-call narration is never shown — the one
+  row names the call in flight ("Searching records") and says "Thinking" whenever the
+  model is writing rather than calling; an unsettled row BREATHES, label and dot on one rhythm,
+  which is why no live label carries an ellipsis (a row that is parked `awaiting` does not breathe). The agent's between-call narration is never shown — the one
   message needing a response is a bulk-mutation confirmation, and the agent waits there, so the run
   stops and that text becomes the answer. A reply with no tool calls is all answer and still streams.
-  At settle the work folds to "{last action}" with the answer below. Expanding is the one
-  place live and settled differ: opened mid-run the timeline is capped and self-pinning (220px),
-  opened settled it is uncapped. Stays fully open while a call is parked, when a SETTLED run ended on
+  At settle the work folds to "{last action}" with the answer below. Expanding opens the timeline
+  IN FULL, live or settled — the run never frames itself, and the HOST'S scroller follows it (a
+  self-imposed window nests a scroller inside the host's own, which in chat means an inverted list
+  inside an inverted list). Stays fully open while a call is parked, when a SETTLED run ended on
   a tool call, and when the work is already one row. `collapseProcess={false}` hands the job back to
   the caller (a surface that already frames the run — it then owns the `FollowScroll` too);
   `summarizeRun(steps)` renames the row.
@@ -2134,7 +2213,8 @@ component rather than showing it at zero.
   the chat message list's inverted mechanism packaged as a wrapper (single-cell inverted list),
   so the follow happens at LAYOUT level: each growth paints already pinned (no flash), scrolling
   up releases it, and short content still reads top-down. Wrap a streaming `AgentRun` with it in
-  any bounded container (a dialog, a drawer, a panel — put the height bound on `style`);
+  any bounded container (a dialog, a drawer, a panel — put the height bound on `style`) — but ONLY
+  one you framed yourself with `collapseProcess={false}`, or it nests a scroller in a scroller;
   `AgentProgress`'s expanded panel uses it. Inherits the inverted pattern's quirks (scrollbar
   thumb runs opposite; keyboard paging inverted) — same as chat. A full-page chat list is
   already inverted and doesn't need it.
@@ -2202,7 +2282,14 @@ component rather than showing it at zero.
   `ids` is normally a memo over query rows — a new array every render, which is the
   `Maximum update depth exceeded` loop). `initial` defaults to `accepted` so the operator drops
   exceptions instead of approving eight identical lines; pass `pending` when each change deserves
-  its own verdict and gate the commit on `settled`.
+  its own verdict and gate the commit on `settled`. **`initial` also takes a
+  `ReadonlyMap<id, decision>`**, for a set that mixes kinds with different safe defaults —
+  filling a blank arrives `accepted`, overwriting a value a human already set arrives `rejected`,
+  so the destructive half is opt-in; an id the map does not name arrives `accepted`. Build it in a
+  `useMemo` over your own rows: it is a VALUE, so `status` and the groups derive from it together
+  and `status` changes identity whenever a decision does — which is what a screen memoizing its
+  rows on `status` needs. Do not reach for `reject()` in the result handler instead: that writes
+  overrides the operator never made, so `undo` hands the row back `accepted`.
 - **`clarify`** — `Clarify` + `ClarifyOption`: the agent asks back — a borderless block
   (the question text + a `ChoiceList`, no card wrapper; an optional muted `eyebrow` sits tight above
   the question — e.g. a wizard's "1 / 3"). `ClarifyOption` requires
@@ -2231,7 +2318,7 @@ component rather than showing it at zero.
   or test DECLARES one rather than mapping from `ClarifyWizardQuestion` (an option is a label +
   description; the answer's value IS the label, the `ask_user_choice` wire shape). Seams:
   `labelForCall` / `renderToolOutput`; no empty-state slot by design (`AgentRun` owns the
-  localized "Starting…" row). Worked example: `tpl_item_list`'s intake dialog.
+  localized "Starting" row). Worked example: `tpl_item_list`'s intake dialog.
 - **`choice_list`** — `ChoiceList` + `ChoiceOption`: selectable answer options as
   divider-separated rows (no bordered cards) with a per-row focus ring + hover wash; the
   agent's quick-reply surface. `allowCustom` appends an always-visible borderless multiline field whose

package/docs/composition.md

@@ -69,6 +69,28 @@ the subject into rows.
   the same left edge as the title above it and the actions below it. Never hand-pad inside one,
   and never hand-roll one: the three surfaces disagree on the number (24 / responsive / 20) and
   only the surface knows which it is.
+  - **ANY scroller whose body is SWAPPED opens the new content at the top.** Stated as a rule and
+    not as a count of the surfaces that happen to have one today: `ModalBody`,
+    `DialogScrollArea` and `DrawerScrollArea` each take a `scrollKey` — the content's identity (a
+    record id, a step name) — and the kit's routed `Popover` takes the same seam with no prop at
+    all, because its ROUTE already is that identity. A scroller you add that swaps its body joins
+    the rule rather than being added to a list. `scrollKey={openChild?.id}` is the right shape:
+    an ABSENT key names the root content, not an opt-out, so the offset comes back when the child
+    closes. Opting out needs no signal — a surface whose key never changes never scrolls. Without it the container keeps the offset it
+    was holding for content that no longer exists, so a swapped-in record opens part-way down
+    itself with its heading off-screen above — invisible until the first list long enough to
+    scroll, which is the same list that made the swap worth having. The key opens unseen content
+    at the top and restores the offset when it comes BACK, which is what a React `key` on the
+    scroll area cannot do: that rebuilds the container, resetting the parent's place along with
+    the child's. Omit it where the body is one thing, and inside a `Screen`-routed dialog, where
+    a stacked screen stays mounted and already keeps its own offset.
+- **Overlays paint in the order they were OPENED, and no call site has to know it.** Mount them
+  wherever composition wants — a `Dialog` sitting always-mounted beside the `Drawer` whose row
+  opens it is the ordinary shape, and it is the one that used to fail: the dialog claimed its DOM
+  slot on the app's first paint, the drawer landed after it, and the dialog then rendered
+  perfectly and read correctly with every control under the panel DEAD. Whatever opens last is on
+  top, both ways round, so a drawer opened from a dialog covers it too. `Alert` and `Tooltip` sit
+  above every overlay at any depth — they are ABOUT the surface under them.
   - **The responsive one is READ, never re-derived — `useDialogGutter()`, no argument.** Inside
     a `Dialog` that is what the header, the scroll area, the footer and any pane a caller drops
     in all call. The `Dialog` resolves `small ? 16 : 24` ONCE, off the SCREEN, and publishes it.
@@ -829,7 +851,11 @@ unconditionally and let an empty `value` disable it, rather than revealing it on
 
 Pressing a PRIMARY entity row opens the record workspace in a `Drawer` with `onPrev`/`onNext`/
 `position` ("3/24") over the visible ordering (←/→ arrow keys are built in). Key the drawer body by
-record id so per-record state resets on step. Facts are `DetailRow`s; the commit bar is a
+record id so per-record state resets on step. A drawer that instead REPLACES its body with a child
+record — the shape where a row inside the panel opens a second record rather than stacking a
+second drawer — passes that id as `DrawerScrollArea`'s `scrollKey` (`scrollKey={openChild?.id}` —
+the undefined leg is the list's own identity), so the child opens at the top and the list keeps its
+place on the way back. Facts are `DetailRow`s; the commit bar is a
 `DrawerFooter` (a hairline-topped band pinned to the panel bottom — render it as the LAST child,
 after the scroll body; actions sit right, a leading `<Text style={{ flex: 1 }}>` hint pushes them
 there). The open row shows a `selected` highlight (and `marked` for a bulk-ticked row). `Peek` is
@@ -1318,6 +1344,15 @@ colours, same shapes. Re-rendering it as plain text makes the reader translate b
 presentations of one field, and the two drift the first time either side gains a value. This holds
 for every custom-rendered value, not just status.
 
+**The same rule reaches the CHART beside the table.** One entity, one rendering, everywhere inside
+one card: if the table's first cell carries the entity's mark (`BrandMark`, `Avatar`, a status
+dot), the chart's rows carry it too — `StackedBarRow` and `BarChartItem` each take a `leading`
+slot for exactly that, laid out on the label's own line box. It is worst where the mark carries
+most (a channel, a platform, a person), and the two ways out that are not the slot are both
+losses: dropping the mark from the table to match makes *both* halves anonymous, and hand-drawing
+the chart to get one slot loses the component. A LEGEND row is the exception and needs no slot —
+its subject is a category, and the colour swatch already is that category's identity.
+
 **Group by what implies a different ACTION, never by a category the reader can already see.**
 Bands like *Waiting on you* / *Gone quiet* / *Open* / *Closed* each name a different response, so
 the grouping tells the reader something no column does. Grouping by a value that is already a
@@ -1780,13 +1815,20 @@ complaint it was meant to fix, because a reader who cannot read a label reports
 cluttered rather than as small. Recede with INK, at the same rung. `xs` is for genuine meta (a
 timestamp, a count), not for a label that a person actually has to read.
 
-**A LABEL sharing a row with a flexible VALUE must be told which one gives way.** Two items in one
+**A LABEL sharing a row with a flexible VALUE must be told which one HOLDS.** Two items in one
 flex row, and whichever cannot shrink forces the other to. It is invisible wherever the values
 happen to fit, which is usually the width it was built at, and it appears the first time a real
-record carries a long one. Decide deliberately: `flexShrink: 0` on the one that must stay
-whole (a fixed-length key, a label), `flexShrink: 1` + `numberOfLines` on the one that may clip,
-and pick by which is still USEFUL truncated — `RC-2026-0…` is unusable, `(555) 384-7…` is still
-recognisably a phone number.
+record carries a long one. Say which one stays whole — `flexShrink: 0` on a fixed-length key, on a
+figure, on a control — and pick by which is still USEFUL truncated: `RC-2026-0…` is unusable,
+`(555) 384-7…` is still recognisably a phone number.
+
+The clipping half needs only **`numberOfLines`**, which now brings its own `minWidth: 0` +
+`flexShrink: 1`: a clamp that cannot shrink cannot clamp, so the prop that says "cut this to fit"
+is what makes it possible. (Neither platform gave it for free — on web a clamped `Text` is
+`white-space: nowrap`, so `min-width: auto` floors it at the WHOLE string; on native a `Text` is
+`flexShrink: 0`. A row of two clamped values laid out at intrinsic width and ran off the frame.)
+Both are no-ops until a row actually overflows, and a `style` on the call site still wins — which
+is how a figure keeps holding over its own label.
 
 
 

package/docs/templates.md

@@ -450,7 +450,9 @@ The corollaries, each of which a register is routinely missing:
     DRAFTS; it does not write. Every drafted record then renders in full — all four fields as
     they will be stored, each editable in place, a `DiffMark` per card, Keep/Drop via
     `useChangeSet` (`initial: "accepted"` — the operator drops the exceptions rather than
-    approving six identical records) — and ONE commit named for its outcome creates them. The
+    approving six identical records; a set that also OVERWRITES values a human set passes a
+    `Map<id, decision>` instead, so that half arrives dropped) — and ONE commit named for its outcome
+    creates them. The
     manual form beside it skips all of that and saves direct. Only the DOCUMENT path needs the
     gate. The receipt still follows the write — it states the outcome, ROUTES, and carries the
     deterministic checks (a checksum, a count reconciliation).

package/docs/testing.md

@@ -46,6 +46,12 @@ Assert two things, not one: that the content appeared, and that it **dismisses**
 backdrop, so clicking the trigger a second time is often intercepted; click the
 backdrop or press `Escape`.
 
+Two overlays open at once stack by the order they were OPENED, so the newest one
+takes the press. If a driver reports `subtree intercepts pointer events` on a
+control of the overlay you just opened, that is a real defect and not this
+anatomy: check with `document.elementFromPoint` at the control's centre, which
+names whatever is actually on top.
+
 ## Custom pointer drag is not `dragTo`
 
 The calendar and gantt drags are built on `use_pointer_drag`, which listens for

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "46.1.0",
+  "version": "46.3.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -150,6 +150,7 @@
     "./popover_nav": "./src/popover_nav.tsx",
     "./popover": "./src/popover.tsx",
     "./overlay_scope": "./src/overlay_scope.ts",
+    "./overlay_layer": "./src/overlay_layer.ts",
     "./switcher": "./src/switcher.tsx",
     "./menu_button": "./src/menu_button.tsx",
     "./menu_list_item": "./src/menu_list_item.tsx",
@@ -334,7 +335,7 @@
   "dependencies": {
     "@lotics/docx": "^0.3.0",
     "@lotics/markdown-editor": "^0.1.0",
-    "@lotics/xlsx": "^0.2.0",
+    "@lotics/xlsx": "^0.3.0",
     "ai": "^7.0.30",
     "mdast-util-from-markdown": "^2.0.3",
     "mdast-util-gfm-footnote": "^2.1.0",