@lotics/ui 41.1.0 → 41.4.0

package/AGENTS.md

@@ -15,10 +15,10 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 | Doc | Read it for |
 |---|---|
 | [docs/catalog.md](./docs/catalog.md) | **The complete inventory** — Reach-by-role (each data role → the ONE canonical component) + every `@lotics/ui/<module>` entry point (incl. `@lotics/ui/vite`'s `loticsOptimizeDeps` + `loticsResolve()` — the pre-bundle list and the whole `resolve` block a custom-code app's `vite.config.ts` imports rather than hand-carries, dev-link included). Read before building any screen; reuse first. |
-| [docs/data_entry.md](./docs/data_entry.md) | Which editing pattern for which job — inline edit, fieldset forms, browser-autofill suppression (search controls only), find-or-create (`Combobox`), line items, handoffs, phased records, billing, tags, dispositions, attachments (`InlineFiles` for a record ROW — list + one CTA, `multiple` decides add-vs-replace; the `FilesEditor` COMPOUND for a whole section — root owns selection/gallery/confirm, you compose the bar, a HOST verb reads `useFilesEditorSelection` — plus the three-way file INTAKE: CTA + `FileDropTarget` + `usePasteFiles`), stage gates, the commit-on-blur vs action-press ordering law (the kit gates the press — `pending_commits`). |
-| [docs/ai_patterns.md](./docs/ai_patterns.md) | AI acts, the human stays in charge — composer, live run feed (`AgentRun`), the one law's split — it turns on WHO supplied the values (machine → a gate: a diff when something is being replaced, a full editable preview when records are being created from a document; human-typed → save-direct + the `ResultHeader` receipt), findings, provenance, confidence; the UI half of the SDK's [ai doc](../app-sdk/docs/ai.md)., the whole run in a dialog (`AgentRunScope`/`AgentRunPane`/`AgentRunActions` — a parked question REPLACES the feed, actions in the footer, **Stop** while streaming), **stopping** (`cancel` stops the run, `abort` only stops listening — so closing a dialog must `cancel` or it keeps billing); **review surfaces compose from atoms** — `DiffValue` (a changed value, droppable in any cell/row/total), `DiffMark` (what happened to the row — ONE circular disc, every surface), `useChangeSet` (accept/reject/undo bookkeeping, no layout) — see [MIGRATION.md](./MIGRATION.md) for the `ChangeReview` family they replace |
-| [docs/composition.md](./docs/composition.md) | The design-language contract — canvas + content column, heading altitude (incl. eyebrow vs group lead — a label is one or the other), banded cards, register vs inset rows (incl. the register laws a row centres its cells by: every cell a FIXED height, a pressable cell on the shared hover token, a column sized by what it carries), master-detail `Drawer` on a LIST screen vs a child collection's row EXPANDING inside a record, view controls, RECORD EXTENT (one page, sections scrolled to and never routed to), color discipline, typography, whitespace, and how to TEST an overlay component (a `Popover`-backed surface never mounts under jsdom). |
-| [docs/templates.md](./docs/templates.md) | The map of `examples/tpl_*.tsx` — what shape each template solves and which to start from (copy + adapt, never import) — plus the record-surface composition rules (pipeline order, static shape, decision budget). |
+| [docs/data_entry.md](./docs/data_entry.md) | Which editing pattern for which job — inline edit, fieldset forms, browser-autofill suppression (search controls only), find-or-create (`Combobox`), line items, handoffs, phased records, billing, tags, dispositions, attachments (`InlineFiles` for a record ROW — list + one CTA, `multiple` decides add-vs-replace; the `FilesEditor` COMPOUND for a whole section — root owns selection/gallery/confirm, you compose the bar, a HOST verb reads `useFilesEditorSelection` — plus the three-way file INTAKE: CTA + `FileDropTarget` + `usePasteFiles`), stage gates, whether a multiline value keeps its fixed reserve or `autoGrow`s (who decides the length — the field, or whoever is typing), the commit-on-blur vs action-press ordering law (the kit gates the press — `pending_commits`). |
+| [docs/ai_patterns.md](./docs/ai_patterns.md) | AI acts, the human stays in charge — composer, live run feed (`AgentRun`), the one law's split — it turns on WHO supplied the values (machine → a gate: a diff when something is being replaced, a full editable preview when records are being created from a document; human-typed → save-direct + the `ResultHeader` receipt), findings, provenance, confidence; **after the run** — a stored record that fills up from several writers (a person, a chat agent, an extraction, an automation) and remembers none of them: an unwritten value must not render like a written one, a machine's prose and a person's must not share a treatment, model markdown goes in `variant="embedded"`, and the read path must project every field the write paths set; the UI half of the SDK's [ai doc](../app-sdk/docs/ai.md)., the whole run in a dialog (`AgentRunScope`/`AgentRunPane`/`AgentRunActions` — a parked question REPLACES the feed, actions in the footer, **Stop** while streaming), **stopping** (`cancel` stops the run, `abort` only stops listening — so closing a dialog must `cancel` or it keeps billing); **review surfaces compose from atoms** — `DiffValue` (a changed value, droppable in any cell/row/total), `DiffMark` (what happened to the row — ONE circular disc, every surface), `useChangeSet` (accept/reject/undo bookkeeping, no layout) — see [MIGRATION.md](./MIGRATION.md) for the `ChangeReview` family they replace |
+| [docs/composition.md](./docs/composition.md) | The design-language contract — canvas + content column, heading altitude (incl. eyebrow vs group lead — a label is one or the other), banded cards, register vs inset rows (incl. the register laws a row centres its cells by: every cell a FIXED height, a pressable cell on the shared hover token, a column sized by what it carries), the button ladder and **what underlined text may mean** (it GOES somewhere or REVEALS something — never mutates; blue leaves the surface, muted stays on it, and the one in-prose disclosure exception is scoped there), master-detail `Drawer` on a LIST screen vs a child collection's row EXPANDING inside a record, view controls, RECORD EXTENT (one page, sections scrolled to and never routed to), color discipline, typography, whitespace, and how to TEST an overlay component (a `Popover`-backed surface never mounts under jsdom). |
+| [docs/templates.md](./docs/templates.md) | The map of `examples/tpl_*.tsx` — what shape each template solves and which to start from (copy + adapt, never import) — plus the record-surface composition rules (pipeline order, static shape, decision budget) and the ACTIVITY shape — a communications feed where the row's label is the GIST and the body varies by medium, one anatomy rather than a row type per kind. |
 
 ## Iron rules
 

package/MIGRATION.md

@@ -4,6 +4,106 @@ 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.
 
+## 41.4.0 — embedded markdown is demoted in the OUTLINE, not only on the type ladder
+
+`<Markdown variant="embedded">` sized its headings down and left them as the tags the author
+wrote, so an `h2` inside a record value still landed in heading navigation as a PEER of the
+page's own sections. Measured on a record surface, the outline read:
+
+> Activity · "Tóm tắt cuộc họp (AI) — …" · "Bài học …" · Details · Next action
+
+— a model's call-summary title between two real sections, contributed from inside ONE row of a
+feed that can hold twenty more. Nothing visual finds this, and fixing the size is what makes it
+invisible: the defect stops looking wrong at the moment it stops being measurable.
+
+Embedded headings now render `h4`/`h5`/`h6` (h1→h4, h2→h5, h3 and deeper→h6). They stay
+headings, so a reader can still navigate inside a long summary; they simply can no longer reach
+a section's level. **Nothing to migrate** — document-scale markdown is untouched, and the
+embedded type scale is unchanged.
+
+## 41.3.0 — `Timeline` rows, embedded markdown, and a disclosure that is not a link
+
+Nothing here removes an API or breaks a type. Two of the changes alter what your rows render on
+sight; the rest is additive.
+
+### `Timeline` bounds its own text, and `right` leaves the press target
+
+**The label clamps to two lines** (the description too). It was unbounded, which is invisible
+until a caller puts user-authored prose in it: measured on a real interaction log, one
+700-character summary drew a **180px label** — nine lines for one entry — and the disc, which
+centred on the label row, ended up 80px below the first line it was meant to sit beside.
+
+If your label can run long, put the full text in `details` as well. The row is then a
+truncation and the detail its source, which is the drill-down every expandable register row
+already makes:
+
+```diff
+  label: entry.summary,
++ details: <Text size="sm">{entry.summary}</Text>,
+```
+
+**`right` renders beside the press target, not inside it.** On a row with `details` the whole
+row was a `<button>`, so an interactive `right` — a row-action menu, an `IconButton` — nested a
+button inside a button: invalid HTML, and one click reaching two handlers. It is now a sibling,
+and the chevron closes the pressable region, so the order reads `label … ⌄  right`. A
+non-interactive `right` (a duration, a `Badge`) moves 14px right and is otherwise unaffected.
+The hover wash now stops where the press target does, which is the point: a wash that ran under
+a row action made that action invisible exactly when the pointer reached it.
+
+**Everything in the band aligns to the label's FIRST LINE, not to the label block** — the disc,
+the chevron and whatever you pass as `right`. Centring and first-line alignment are the same
+answer until a label wraps and then they are 10px apart, so making two-line labels ordinary made
+the old behaviour wrong. **A single-line row is pixel-identical** (measured: 40px band, zero
+drift on all three ornaments); only wrapped rows change, and they change to correct.
+
+**`TimelineItem` takes `placeholder`.** It marks a label the SURFACE supplied rather than one the
+record holds, and draws it in the ink an unfilled field uses. A feed fed by automations and
+extractions routinely receives an entry with no prose in it, and `label: string` forces the
+caller to invent some — which then renders in body ink, so "nobody has written this up" and
+"this is what happened" look identical.
+
+```diff
+- label: entry.gist || `${entry.direction} ${entry.kind}`,
++ label: entry.gist || "Not written up yet",
++ placeholder: !entry.gist,
+```
+
+### `Markdown` takes `variant`
+
+`"document"` (the default, and what every current caller keeps) is markdown that IS the surface
+— its `h1` is the page's `h1`. `"embedded"` is markdown that is a VALUE on a page someone else
+designed, and collapses every heading to the body's own size.
+
+```diff
+- <Markdown>{record.aiSummary}</Markdown>
++ <Markdown variant="embedded">{record.aiSummary}</Markdown>
+```
+
+Reach for it whenever the text was not written by whoever built the screen — now the common
+case, because the writer is routinely a model. Measured on a real feed, a machine summary at
+document scale drew 18px/600 headings, one rung under the section heading containing it.
+
+`MarkdownProps` is reached from `@lotics/ui/markdown_types`, the same way `MediaPlayerProps` is;
+the component entry points do not re-export it.
+
+### `TextDisclosure`, and what underlined text is allowed to mean
+
+New component: muted underlined text that REVEALS adjacent content in place — a transcript under
+its player, a long value under its summary. It exists because the rule used to be "underlined
+text is the NAVIGATION affordance and nothing else", and following that produced worse screens:
+the quiet control it left you (`Button color="muted"`) measures transparent, borderless and
+undecorated at rest, so its affordance arrives only on hover.
+
+The rule is now scoped rather than absolute, and the INK carries the difference:
+
+| | |
+|---|---|
+| blue + `role="link"` (`Link`) | leaves this surface |
+| muted underline (`TextDisclosure`) | reveals more of it, in place |
+
+Anything that MUTATES still carries a control surface — `Button` in chrome, `InlineButton` on a
+field. Nothing to migrate: existing `Link`/`TextLink` usage is unaffected.
+
 ## 41.1.0 — `FileRows` no longer captions every row with the file type
 
 `meta` defaulted to the file-type label, so a row read `contract.pdf` with `PDF` under it. The

package/docs/ai_patterns.md

@@ -503,6 +503,42 @@ locator after the label ("page 2", a record code). Kinds carry recognizable glyp
 make each chip pressable (hover wash + an open glyph); the host does the navigation. An empty
 list renders nothing.
 
+## After the run — a record that FILLS UP from more than one writer
+
+`Sources` and `Confidence` above belong to a live answer, where the run is on screen and the
+reader is deciding about it. The harder surface is the one they open a week later: a stored
+record whose fields were written by a person, by a chat agent, by an extraction off an upload,
+and by an automation that fired when a file landed — and which carries no memory of which was
+which. Increasingly that is the normal shape, because the app's own form is the LEAST used way
+in. Three rules, each of which a screen built for a single writer gets wrong for free.
+
+**An unwritten value must not render like a written one.** A row assembled by an automation
+arrives with its enums set and its prose empty, and the natural repair — composing a label out
+of the enums that ARE set — produces a real-looking sentence in body ink. "Nobody has written
+this up" and "this is what happened" then look identical, which is the one distinction the
+reader most needs. Say the value is missing, in the ink an unfilled field already uses
+(`Timeline`'s `placeholder`; the same idea wherever a component takes a `label: string` and
+therefore cannot express absence — that type is the trap, so give it a way to say so).
+
+**A machine's prose and a person's must not share a treatment.** They are different claims and
+they earn different trust, so rendering them alike teaches the reader to skim both at one
+speed. Carry the difference with SHAPE, not weight: name the author and the evidence on the
+line above ("Written by AI from the recording" — the source alone is not authorship), and drop
+the machine's text into a recessed `Inset`, which says it was not written on this page. Leave
+the person's conclusion on the page's own ground; that contrast IS the signal.
+
+**Model prose arrives with its own type ladder — take it away at the door.** A model asked for
+a summary emits `##` headings and heavy `**bold**` knowing nothing of what surrounds it, and
+document-scale markdown hands those an `h1` equal to your section heading: measured on a real
+feed, machine content rendered 18px/600 headings over 44 medium-weight runs, so the
+least-trustworthy text on the screen was also the loudest. Render every embedded value with
+`<Markdown variant="embedded">`.
+
+And one that is not about treatment at all: **check that the read path projects every field the
+write paths set.** A field written by an intake and never projected by the query behind the
+screen is invisible in a way no visual pass can catch — the surface renders perfectly, and the
+evidence is discarded at render. Diff the two lists whenever a surface has more than one writer.
+
 ## Confidence — `Confidence`
 
 Confidence IS a callout (`@lotics/ui/confidence`) — the ONLY form it takes: the three-tick

package/docs/catalog.md

@@ -38,16 +38,18 @@ emphasis/risk), `IconButton` (icon-ONLY — the circular affordance; an icon-onl
 type error, so reach here. `size` `lg` 40px / `md` 28px / `sm` 24px — md/sm keep a 40px touch
 target via hitSlop — the SAME `color` palette as Button plus `none`/`white`, plus `loading` and `elevated` (white
 fill + border + shadow, for a button sitting ON imagery — a tile's remove ✕, an overlay's
-retry); needs `accessibilityLabel`/`tooltip`), `TextLink` (underlined text that's OPTIONALLY
-an action (`onPress`) or a link (`href` — a real web anchor) — or, with neither, plain
-underlined text you drop in your own pressable like a table cell; colour via `color`; the
-go-to for Clear / Select all / inline links), `Chip` (dismissible facet chip), `CopyButton`
+retry); needs `accessibilityLabel`/`tooltip`), `TextLink` (underlined text that NAVIGATES with
+an `href` — a real web anchor — or, without one, a plain underlined marker you drop in your own
+pressable like a table cell; colour via `color`. It does not act: it has no `onPress`),
+`TextDisclosure` (the reveal counterpart — muted underlined text that unfolds adjacent content
+in place), `Chip` (dismissible facet chip), `CopyButton`
 (put a value on the clipboard — rides the value it copies, confirms only a real write).
 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 link/action.
+colour-configurable underlined marker. Underlined text GOES somewhere or REVEALS something and
+the ink says which — anything that MUTATES carries a control surface instead.
 
 ### Pick from a list
 
@@ -128,7 +130,9 @@ Above 1 the resting box RESERVES that many lines — the full editor height, not
 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),
+reserves less than it opens to shoves the rest of the form down the page on every click.
+**`autoGrow`** makes that budget a MINIMUM and fits the value instead — see
+[data_entry.md §Open prose grows](./data_entry.md)),
 `InlineNumberInput`, `InlineSelect` (single or
 `multi`), `InlineMemberSelect`, `InlineDatePicker`, `InlineTimePicker`; a
 READ-ONLY field in that same column uses `InlineStatic` (matches the editor box exactly, no
@@ -403,7 +407,16 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   numbers), `weight`, `color`, alignment, tabular numerals.
 - **`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.
+  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
+  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.
 - **`markdown.css`** — import once for the web markdown styling.
 - **`format_date`** — `formatDate` / `parseDate` / `toISODate` + `DateFormatStyle`.
 - **`format_money`** — `formatMoney` / `formatCompactNumber`.
@@ -488,7 +501,10 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   image-less entities — groups, organizations. A person → `Avatar`/`MemberChip`.
 - **`wave_avatar`** — `WaveAvatar`: decorative animated waveform avatar (voice/audit
   history); animates on web, renders a static fallback on native.
-- **`member_chip`** — `MemberChip`: avatar + name; the universal person render.
+- **`member_chip`** — `MemberChip`: avatar + name; the universal person render. `size` scales
+  BOTH — `sm` gives a 24px avatar and a 12px name, every larger rung keeps the name at body
+  size. Reach for `sm` when the chip sits inside a sentence or a dense row, where a body-size
+  name would collide with the 12px text around it.
 
 ### Layout & surfaces
 
@@ -632,8 +648,20 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   with no `href` it stays NEUTRAL: plain underlined text to wrap in your own pressable,
   or a MARKER that a value leads somewhere (a record reference whose press opens a peek,
   not a trip). `color` overrides either way; inherits every `Text` prop. It does NOT
-  act: an act carries a control surface (`Button`/`InlineButton`), and underlined text
-  is the NAVIGATION affordance only.
+  act: anything that MUTATES carries a control surface (`Button`/`InlineButton`).
+- **`text_disclosure`** — `TextDisclosure`: the counterpart to `TextLink` — muted
+  underlined text that REVEALS adjacent content in place (a transcript under its
+  player, a long value under its summary). Underlined text either goes somewhere or
+  reveals something, and the INK says which: blue + `role="link"` leaves the surface,
+  muted stays on it. Takes `expanded`/`onToggle` and a `label` NOUN — it supplies the
+  verb, so two call sites cannot end up with "Show" and "View". Reach for it instead
+  of the two things that look right and are not: `Button color="muted"` measures
+  transparent, borderless and undecorated at rest, so its affordance arrives only on
+  hover (invisible to keyboard and touch, and against a text column it reads as a
+  label); `Accordion` is a list-ROW disclosure, heavy furniture for a verb nested
+  inside a row that already has a chevron. Announces `role="button"` + `aria-expanded`
+  — reaching for `Link` instead tells a screen-reader user they are leaving a page
+  that is about to unfold under them.
 - **`chip`** — `Chip`: the generic pill — pressable when `onPress` (announces as a button;
   pass `accessibilityLabel` when children aren't self-describing text) + an
   absolutely-positioned dismiss ✕ sibling when `onDismiss` (its name = `dismissTooltip` ??
@@ -1395,7 +1423,20 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `pxPerDay`) + `GanttTask`/`GanttLabels` types. **Limitation:** labels are not
   provider-wired — pass `labels` (`DEFAULT_GANTT_LABELS` is English).
 - **`timeline`** — `Timeline`: a heterogeneous event LOG — per-row icon + expandable
-  details; models the past, NOT progress.
+  details; models the past, NOT progress. Three things it decides for you, because a row
+  cannot be trusted to a caller's data: the **label clamps to two lines** (and the
+  description likewise) — a row is a scan target, and an unclamped one lets a single
+  user-authored note set the section's height, so put the full text in `details` too;
+  **`placeholder`** marks a label the SURFACE supplied rather than one the record
+  holds, drawing it in the unfilled-field ink — reach for it on any feed that fills
+  from more than one direction, where an entry routinely arrives with no words in it;
+  **the disc, the chevron and `right` all sit on the label's FIRST LINE**, so a wrapped
+  row lines up with an unwrapped one (the worked reference for the rule in
+  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.
 - **`checklist`** — `Checklist` + `ChecklistGroup` + `ChecklistItem` + `ChecklistNote` /
   `ChecklistActions` / `ChecklistField`: THE run of tickable rows, at any
   altitude. It replaced a `task` family and a `pipeline` family that had converged on one

package/docs/composition.md

@@ -417,6 +417,31 @@ truncation, so you are buying a baseline with clipped text. Worth it for an iden
 contact; think harder for a cell whose job is prose, where the honest answer may be to move that
 content off the register entirely.
 
+**This is not a table rule — it is a rule about furniture centred on text.** Anywhere a fixed
+ornament sits beside a text block and centres on it — a `Timeline`'s disc, a marker, an avatar,
+a rail glyph — the ornament's position is a function of the text's height, so an unbounded text
+block moves it. A feed is where this actually bites, because a feed is the one row primitive
+whose text is written by the USER: measured on a real interaction log, one 700-character summary
+drew a 180px label and put the disc 80px below the line it names. Bound the text; the row keeps
+its beat and the ornament keeps its line. Where the full value still has to be readable, the row
+EXPANDS to it — a truncation and its source, not a second copy.
+
+**Bounding the text is half the fix; the other half is aligning to the LINE, not the block.** A
+clamp turns an 80px drift into a 10px one — it does not remove it, because a two-line label
+still centres its ornaments half a line low while the one-line rows beside it do not. So pin
+every ornament in the band to the first line's centre, from ONE constant the row derives (see
+`FIRST_LINE_CENTRE` in `timeline.tsx`, the reference): the mark, the affordance, and whatever a
+caller passes as trailing content all read it, and a wrapped row lines up with an unwrapped one.
+Two consequences worth stating, because both look like unrelated tidying: a height FLOOR above
+the content is what created the slack being distributed, so deriving the touch target from
+`padding + line` instead removes the drift and the second source of truth in one move; and an
+ornament OUTSIDE the row's padding needs its own box, since it does not inherit that offset.
+
+The way it gets in is a SLOT. A component that takes a caller's string or node cannot assume
+anything about it, and every fixture the component was built against is tidy, so the defect is
+invisible until it ships. Bound the slot in the component — not in a prop the next caller can
+re-open.
+
 Two corollaries, both counter-intuitive enough to state:
 
 - **Shrinking a NEIGHBOURING cell does not fix it.** The spread is a function of the varying
@@ -482,6 +507,24 @@ over it). `PressableHighlight` is the wrong base for such a row — it IS a butt
 children, so any nested control lands inside it; it stays for surfaces whose content is
 non-interactive by construction. `TableRow` already composes `PressDoor`.
 
+**A trailing slot is not a PEER of the row's own affordance — space them apart.** A disclosure
+chevron belongs to the row's button; the slot beside it does not, and if the two are spaced like
+siblings the eye reads one cluster. Measured on a feed row: 10px from the label to the chevron
+and 12px from the chevron to the action menu, so the only thing saying they were different
+targets was a 4px break in the hover wash — invisible to a reader who never hovers. Put clearly
+more space BETWEEN the groups than inside one (2:1 is enough) and the pair separates without a
+divider, a weight change or any new element. It is the ordinary grouping rule — one uniform gap
+makes every child a peer — applied to a row's right edge, where it is easy to miss because both
+items are small grey glyphs sitting on the same line.
+
+**"Non-interactive by construction" excludes any SLOT.** A trailing `right` / `actions` / `meta`
+prop takes whatever the caller passes, so a row that wraps one in its own press surface is a
+nested button waiting for the first caller to pass an `ActionMenu` — which is the natural thing
+to pass. The browser says so out loud (`<button> cannot contain a nested <button>`) and nothing
+else does: it renders, it measures, it typechecks, and the click quietly runs two handlers.
+Render the slot as a SIBLING of the press target (`Timeline` is the reference), which also stops
+the row's hover wash sliding under the action at the moment the pointer reaches it.
+
 Actions stay **visible** — a hover-only action is invisible to keyboard and touch users. The ONLY
 exception is a DENSE tree/register where a persistent per-row action would clutter: reveal on
 hover **OR focus-within**, keeping the action in the DOM + tab order and gating only its opacity,
@@ -661,13 +704,34 @@ by what KIND of thing they are, so an avatar takes the same number rather than a
   already puts it. Chrome has TWO rungs: `Button` (a 40px control with a surface) →
   `InlineButton` (28px, filled, on a field's own surface).
 
-  **AN ACT CARRIES A CONTROL; ONLY NAVIGATION IS UNDERLINED TEXT.** `Link`/`TextLink` are the
-  underlined pair and they GO somewhere; everything that acts is a `Button` or an `InlineButton`.
-  A surface-less ACT was tried as a third rung and removed: it made underline mean two things at
-  once, separable only by ink, so the affordance stopped answering the one question a reader has —
-  does this take me away, or does it do something here. It also competed with the `Button` colour
-  ladder for the same job, since `muted` already IS the quiet rung. Pick by what the press DOES,
-  and let the surface say which kind it is. Never a `muted` text action: it mutes
+  **AN ACT CARRIES A CONTROL; UNDERLINED TEXT REVEALS.** `Link`/`TextLink` are the underlined
+  pair; everything that MUTATES is a `Button` or an `InlineButton`. A surface-less act was tried
+  as a general third rung and removed: it made underline mean anything at all, so the affordance
+  stopped answering the one question a reader has — does this take me away, or does it do
+  something here. It also competed with the `Button` colour ladder, since `muted` already IS the
+  quiet rung.
+
+  **The ONE exception, and it is narrow: an IN-PROSE DISCLOSURE.** A show/hide for adjacent
+  content — a transcript under its player, a long value under its summary — has nowhere else to
+  go. It cannot move to chrome, because it belongs to the thing above it; and the two controls
+  that look right in chrome are both wrong against a text column. `Button color="muted"` measures
+  transparent, borderless and undecorated AT REST, with its wash arriving only on hover: that is
+  a hover-only affordance, banned above, and it reads as a stray label between two content
+  blocks. `Accordion` fixes the affordance and overcorrects — it is a LIST-ROW primitive, a
+  full-width header with its own chevron, and nesting one inside a row that already has a chevron
+  is list furniture borrowed for a one-off verb.
+
+  So underline is permitted here, and the INK keeps it unambiguous:
+
+  | | |
+  |---|---|
+  | blue + `role="link"` (`Link`) | leaves this surface |
+  | muted underline in a caller's `Pressable` (`TextLink`, no `href`) | reveals more of it, in place |
+
+  Both say "show me more"; only one takes you away, which is the question the affordance existed
+  to answer. It stays scoped to REVEAL: a press that saves, sends, deletes or opens an overlay
+  carries a control surface, always. Pick by what the press DOES,
+  and let the surface say which kind it is. Never a `muted` text action that MUTATES: it mutes
   the one thing carrying the act. No
   "success"/green button. Decision UIs put positive/negative color on the STATUS (dot) and verdict
   (colored `Text`), not the buttons.
@@ -903,10 +967,11 @@ selection washes).
 (rose vs orange) stays on `Badge`s.
 
 Links use `Link`/`TextLink` (blue-600), never `solid("blue")` — and blue-600 means NAVIGATION
-specifically, not "interactive" generally. Underlined text is the NAVIGATION affordance and nothing
-else (see the button ladder above): an act carries a control surface. `TextLink` takes the blue only
-when it has an `href`; as a passive marker on a value it stays neutral, because a press that opens a
-PEEK is not a trip.
+specifically, not "interactive" generally. Underlined text is for going somewhere or REVEALING
+something, never for mutating (see the button ladder above, which scopes the one in-prose
+disclosure exception). `TextLink` takes the blue only when it has an `href`; as a passive marker on
+a value, or as a muted in-place disclosure, it stays neutral — because a press that opens a PEEK,
+or unfolds a transcript, is not a trip.
 
 ## `Badge` is for STATUS only — everything else is text
 
@@ -932,6 +997,19 @@ tonal. A `Badge` is never a metric value.
 
 ## Typography
 
+**A `size` rung scales the WHOLE component, not just its figure.** A composite with a graphic and
+a label — a chip, a badge with a caption, a tile — has one `size` prop and the reader expects it
+to mean one thing. Scaling only the graphic makes the small rung half-small, and the defect shows
+up nowhere near the component: it appears when the chip is dropped INSIDE a sentence, where a
+12px label runs straight into its 14px name and the two read as different type systems meeting
+mid-phrase. Their line boxes differ too (16 against 20), so no `alignItems: "center"` can put
+them on a shared baseline — the symptom is usually reported as "the alignment is off".
+
+The check is cheap and worth running whenever a component takes a size: render the small rung and
+measure the TEXT inside it, not the box. If the text did not move, the prop is only half wired.
+
+
+
 Only the `Text` primitive (`size` / `weight` / `color` / `transform` / `tabular` / `level` for
 semantic heading rank). Uppercase tracking is built into `transform="uppercase"` — never hand-set
 `letterSpacing`.

package/docs/data_entry.md

@@ -203,6 +203,41 @@ cell (noise on a dense board, and a pressable nested in the trigger is invalid D
 (the app workflow must ACCEPT null on that input — a `select`/`date`/`member` field clears on
 null). `InlineSelect multi` needs no `onClear` — an empty set is already a valid `onSave`.
 
+### Open prose GROWS; a value with a known shape keeps its reserve
+
+`numberOfLines` reserves a fixed budget so the box is the same height resting and editing. That
+is right for a value whose shape the FIELD decides — a two-line address, a payment term, a
+clause — where the reserve keeps the page still and an overlong value is itself a signal that
+something belongs elsewhere.
+
+It is wrong wherever the length is the AUTHOR's choice, and it fails in the worst available way.
+The box is drawn at the budget and the value simply exceeds it: no ellipsis, no clamp, no
+scrollbar, nothing to scroll. Measured on a record note, 285 characters drew **76px of a 116px
+value** — two full lines gone with nothing on screen admitting it. A truncation mark would have
+been kinder; this is silent. So the test is not "is this field long" but **"who decides the
+length"** — the field, or whoever is typing.
+
+**And it gets worse as the surface narrows**, which is the opposite of the intuition that a
+desktop check is the demanding one. A budget is a count of LINES and the wrap point moves: the
+same value measured 60px hidden at 1280 and **96px hidden at 375**, because the narrower column
+wrapped it into more lines against the same three-line box. A fixed reserve verified on a wide
+screen is not verified.
+
+`autoGrow` makes the budget a minimum and fits the value. It costs nothing the fixed reserve was
+protecting, and the reason is worth stating because it is easy to assume otherwise: an
+`InlineTextInput` is ONE input in both states, never a resting view swapped for an editor, so a
+grown box is the same height focused as at rest — measured identical to the pixel, box and
+origin. The reserve was guarding against a jump the one-element design had already made
+impossible. Growing on a control that DOES swap (number, date, time — their resting display is
+formatted) would reintroduce it, which is why the prop lives here and not on those.
+
+Two places to keep the reserve anyway: a value that can be **arbitrarily long** (growth has no
+ceiling — 406 characters is already 238px, so a field that might hold a document wants the budget,
+and overflowing it is the signal the value belongs elsewhere), and a **grid cell** (`variant="bare"`
+in a `DataGrid`), where a cell varying with its data breaks the row rhythm the grid promises. Grow
+on a record surface; reserve in a table. Worked both ways in `dev/pages/inline_edit.tsx`
+§ Multiline — the same value in a reserved field and a grown one, side by side.
+
 ### The row stack — `DetailTable` + `DetailRow`
 
 A STACK of rows lives in a `DetailTable` (label, value laid out like a TABLE: `labelWidth` /
@@ -291,6 +326,34 @@ row that wants it. See the "General" section of `tpl_record`, which also reads t
 full record surface. Not every field is a same-height swap — a tag field, a status, or an
 attachment grid edit in place too (below).
 
+## When the editor is a MODE instead of a resident field
+
+The section above is the default and holds almost everywhere: the value IS the editor, nothing
+moves, and there is no verb to find. It has exactly one exception, and it is decided by a
+question with a factual answer — **does this value already appear somewhere else on the same
+surface?**
+
+On a FEED, it does. A row's identity line is the value, and the body opens under it, so a
+resident editor renders the same sentence twice, stacked and identical. Quieting the frame does
+not help: a sentence appearing twice reads as a mistake at any weight. So the editor becomes a
+mode, reached by an **Edit** verb in the row's trailing slot beside its other actions.
+
+**Except when the value is EMPTY, and that half matters more.** There is nothing to duplicate,
+and a surface fed by automations and extractions receives entries with no words in them
+routinely — a recording lands, the row says it has not been written up, and the empty field is
+the invitation to write it. Withhold it there and the feed can RECEIVE an entry it gives the
+reader no way to finish. **An empty value shows its field; a filled one waits to be asked.**
+
+Two things follow that are easy to get wrong in the other direction:
+
+- **Name the verb for the words, not the row.** "Edit", not "Edit entry" — on a feed the entry
+  is a record of something that happened, and only the prose a PERSON wrote is editable at all.
+  Derived values (a header's participants), verbatim ones (a transcript), artifacts (media,
+  files) and a model's output (a summary — you re-run it, you do not hand-edit it) are all
+  read-only, and a verb naming the whole entry claims otherwise.
+- **One row in edit mode at a time.** Two half-finished sentences on one feed leave the reader
+  unable to say which one the next keystroke lands in.
+
 ## Fieldset form — fields lay out on a RESPONSIVE two-column grid
 
 Never hard-code columns, never 3-up. A fieldset is `flexDirection:row, flexWrap:wrap,