@lotics/ui 43.2.0 → 43.3.1

package/AGENTS.md

@@ -16,7 +16,7 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 |---|---|
 | [docs/catalog.md](./docs/catalog.md) | **The complete inventory** — Reach-by-role (each data role → the ONE canonical component) + every `@lotics/ui/<module>` entry point (incl. `@lotics/ui/vite`'s `loticsOptimizeDeps` + `loticsResolve()` — the pre-bundle list and the whole `resolve` block a custom-code app's `vite.config.ts` imports rather than hand-carries, dev-link included). Read before building any screen; reuse first. |
 | [docs/data_entry.md](./docs/data_entry.md) | 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/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/testing.md](./docs/testing.md) | Driving the kit in a browser — the three anatomies where the a11y tree says one thing and a driver must do another: a `PressDoor` row whose named button always intercepts pointer events (by design), portalled overlays that render at the top of the DOM, and custom pointer drag that `dragTo` cannot move. |
 | [docs/templates.md](./docs/templates.md) | The map of `examples/tpl_*.tsx` — what shape each template solves and which to start from (copy + adapt, never import) — plus the record-surface composition rules (pipeline order, static shape, decision budget) and the ACTIVITY shape — a communications feed where the row's label is the GIST and the body varies by medium, one anatomy rather than a row type per kind. |
@@ -55,8 +55,7 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
   order, where a line claims an order the work does not have. **`mark`** asks *does ticking mean
   DONE or CHOSEN* — a ring for completion, the square box for picking (which forms to produce,
   which records to export). Spend the ring on a choice and a reader who learned that a filled
-  ring means "done" reads a ticked pick-list as work already carried out. It replaced separate
-  task/pipeline families that had converged on one anatomy. A GROUP is a phase — a name, optionally a
+  ring means "done" reads a ticked pick-list as work already carried out. A GROUP is a phase — a name, optionally a
   Show/Hide disclosure, and no body: it owns no COMPLETION, and a ring that never responds invites
   a press it refuses. Rows tick ONE at a time; derive position from the highest stamp and one click marks
   everything below it without inventing dates. A checklist REPORTS — a field owned by a section is
@@ -101,17 +100,13 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
   padding. `PressableRow` (all variants), `Table`, `ChoiceList`, `ListItem` and `FileRow`
   already do this, so a screen composed from the kit aligns with **no per-site padding at all**.
   The moment one component insets instead, every neighbour has to be hand-padded by the same
-  amount to catch up, and that compensation spreads to each new surface built beside it — which
-  is how a `SummaryLine`, a `Clarify` question and a bare table's footer each acquired a
-  padding they should never have needed. **An indent is legible only when something VISIBLE
+  amount to catch up, and that compensation spreads to each new surface built beside it. **An indent is legible only when something VISIBLE
   occupies it** — a checkbox, an ordinal, a diff mark. An empty indent is a defect.
   - **The one exception is a self-contained OVERLAY.** A menu or a selector's popover
     (`MenuListItem`, `OptionList`) has nothing outside itself to align with, so its rows keep
     plain padding. Bleeding there would push rows past the popover's own edge.
   - **A slot holding another component's part takes THAT component's constant**, never a
-    hand-picked number that happens to look close: `AgentRun`'s dot column was 18 while the
-    `Marker` it holds is `NODE` (24), so a 24px dot centred in an 18px column put the whole run
-    rail 3px left of every other band in the dialog. Import the owner's constant.
+    hand-picked number that happens to look close. Import the owner's constant.
   - Inside a `Dialog`, every band reads `dialogGutter(small)` — header, scroll area, footer and
     any pane a caller drops in. A hand-copied `small ? 16 : 24` is a fifth copy of a number
     that has to agree with four others.

package/MIGRATION.md

@@ -4,6 +4,37 @@ 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.
 
+## 43.3.0 — a `bare` inline field sits on the column, and Enter finishes a one-line one
+
+Two fixes to `Inline*`, both of them behaviour a caller cannot see in a prop name.
+
+**A `bare` field now aligns its TEXT, not its box.** The field surface carries 8px
+of horizontal padding, which is invisible at rest on a variant that draws no
+border — so every bare value rendered 8px right of whatever named it. In a
+`DataGrid` that meant each column's values sat off its own header. The inset is
+now bled back out with a negative LEFT margin: glyphs land on the container's
+edge, the hover/focus border overhangs into the gutter, and hover moves nothing.
+
+Left only, deliberately. A matching right bleed aligns nothing on left-aligned
+text and pushes the frame past the edge its neighbours stop at, which shows the
+moment the border paints. **If you compensated with your own negative margin,
+remove it** — you will now be 8px out the other way. A field needs ~8px of slack
+on its left to hover into; in a zero-gap column, adjacent borders will touch. A
+DISABLED `framed` field is unaffected: it drops its border and fill so it cannot
+promise a press, but it stays in line with the enabled fields beside it.
+
+**`numberOfLines` now decides what ENTER does — wrapping no longer does.** The two
+were one flag, so `autoGrow` — a prop about fitting the value — silently turned
+Enter from "save" into "insert a newline". A one-line summary field that grew when
+it ran long became a field you could only leave by clicking away, and nothing at
+the call site said so.
+
+A field left at one line (or `numberOfLines={1}`) holds a single-line value that
+may WRAP, and Enter commits it. Declaring 2+ lines declares PROSE: Enter is a
+paragraph break and blur saves, exactly as before. **If you wrote
+`numberOfLines={1} autoGrow` and relied on Enter inserting a newline, raise the
+line budget** — that is now what says so.
+
 ## 43.0.0 — a time is PICKED, and there is nothing to type
 
 `TimePicker` is no longer a segmented text field. It is the value on a pressable
@@ -78,6 +109,19 @@ its reasoning are in `docs/composition.md` § The pointer cursor. If a component
 needs the pointer, set `CURSOR_ACTION` in its style — and if it is built on the bare
 react-native `Pressable`, note that the pointer is what you get by DEFAULT, from
 react-native-web, unless you set `CURSOR_DEFAULT`.
+## 42.5.0 — an expanded `Timeline` row shows its whole label
+
+The label was clamped to two lines whether the row was open or shut. Expanding a
+row is a request to see more of what is there, so a label that stays truncated
+through it leaves the caller exactly one way to make its own label readable:
+repeat it inside `details`. Then the reader meets the same sentence twice — once
+cut off, once whole — which reads as a rendering bug rather than as disclosure.
+
+It now clamps while collapsed only. **If you duplicated a label into `details`
+to work around this, delete the copy**; the row will show it in full on its own.
+Nothing else changes: a collapsed row is identical, and a row whose label already
+fitted in two lines is identical open or shut.
+
 ## 42.4.0 — `Picker` is named by its `FormField`, and its way back to empty has a name
 
 Two fixes to the same control, both about a thing on screen that the control did

package/docs/ai_patterns.md

@@ -124,8 +124,7 @@ transition — never leave a live button waiting on a network round-trip:
 
 - **Same-tick feedback.** On press, synchronously close the dialog / swap to the run surface
   (`AgentRun` with its streaming state) so there is nothing left to click. A button that stays
-  pressable while an attach/start request round-trips invites double-fires — observed in
-  production as stacked paid runs.
+  pressable while an attach/start request round-trips invites double-fires.
 - **Single-flight in app code too.** Guard the handler with a ref (state alone races the
   re-render): first press wins, later presses no-op until the flow settles.
 - **The SDK backstops runs, not workflows.** `useAgentRun().run()` is single-flight by default
@@ -242,14 +241,10 @@ feed**; the starting row IS the placeholder, consistent and localized.
 (Sonnet / Opus, not Haiku); the renderer shows every reasoning part it's handed.
 
 **Localization.** The feed's fixed chrome — the "Thinking" label, the "Input"/"Output"/"Error"
-panel titles, the "awaiting" annotation, and the "Retry" action — resolves through the
-`LoticsLocale` `agentRun` slice (translate once at the provider; a `vi` app gets them for free).
-— **and so are the tool labels** (`agentRun.tools`, keyed by raw tool name). Translating a tool
-row is no longer each app's job: an English row under a Vietnamese "Đang suy nghĩ…" was the kit
-contradicting itself. The "{n} steps" suffix is locale-backed too (`agentRun.steps`). `labelForCall`
-and `stepsLabel` remain as per-call-site OVERRIDES — for phrasing a row by what
-it targets — not as the only route to a translation. A tool name in neither the locale map nor
-`labelForCall` falls back to its prettified form.
+panel titles, the "awaiting" annotation, the "Retry" action, the tool labels (`agentRun.tools`,
+keyed by raw tool name) and the "{n} steps" suffix (`agentRun.steps`) — resolves through the
+`LoticsLocale` `agentRun` slice (translate once at the provider; a `vi` app gets them for free);
+`labelForCall` and `stepsLabel` remain as per-call-site OVERRIDES.
 
 **Answering an awaiting call — `ApprovalPrompt`.** The `awaiting` row inside `AgentRun` is
 READ-ONLY — it only NAMES that a call is parked on a human decision. The surface that ANSWERS it
@@ -466,8 +461,7 @@ rather than wherever the feed was scrolled to.
 holds the wizard's verbs while a question is up, **Stop** while the run streams, and nothing once
 it settles; the RUN decides, which is the whole point of handing it the run. A host that names a
 single phase out here duplicates that decision and gets it wrong the moment the bar learns a new
-one — which is precisely how two streaming phases ended up with an empty footer and no way to
-stop.
+one.
 
 **`run` is a SHAPE, not an import** (`AgentRunLike`: `status`, `parts`, `pendingChoice`,
 `answerChoice`, `cancel`, `error`; `AgentRunQuestion` names what `pendingChoice` carries, so a template or
@@ -610,8 +604,8 @@ ranked set, don't cram it into chat prose:
   document-driven records) — the record's files block feeds ONE "Use AI" entry that FORKS into
   the two document tasks, each a specialized run with a task-pure result: **Extract** (files
   read → fields already matching fold into one quiet line → every add / update / conflict a
-  a `DiffValue` per field (the struck current value, the proposed one, candidate rows), the record's current value
-  a first-class choice — plus proposed new lines as record-body `Change`s → one outcome-named
+  `DiffValue` per field (the struck current value, the proposed one, candidate rows), the record's current value
+  a first-class choice — plus proposed new lines as record-body `Change`s →
   an explicit outcome-named commit) and **Cross-check** (documents compared against the record and
   each other → ranked `Finding`s — severity, title, the prominent metric, sources — separated
   by hairlines; the findings ARE the outcome the human acts on). The fork carries an OPTIONAL
@@ -642,12 +636,11 @@ ranked set, don't cram it into chat prose:
 ## The visual vocabulary — functional colour, no gimmicks
 
 The AI vocabulary has **no purple accent and no gimmick glyphs** (no sparkles) — but it is NOT
-monochrome: **colour is used where it carries meaning, not for decoration.** What the violet
-sparkle used to carry now reads structurally — **provenance** is a quiet sentence-case microlabel
+monochrome: **colour is used where it carries meaning, not for decoration.** **Provenance** is a quiet sentence-case microlabel
 naming the artifact ("Proposed", "Match", "Mismatch", "Suggested edit", "Question" — xs,
-muted, medium; all-caps is banned kit-wide), and the agent's **reasoning** is a left-ruled margin
+muted, medium; all-caps is banned kit-wide), the agent's **reasoning** is a left-ruled margin
 note (a hairline rule + muted text — `ChangeReasoning`), quoted apart from the facts and the
-human's controls — while **status/severity/diffs use functional colour** the way the rest of the
+human's controls, and **status/severity/diffs use functional colour** the way the rest of the
 kit does:
 
 - **Confidence** — the 3-tick meter + the full phrase, emerald / amber / zinc by level.

package/docs/catalog.md

@@ -80,8 +80,7 @@ renders these per option.)
 
 **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`.
-The number was removed because the same concept had drifted to eleven different values across
-the product and its apps, so one person looked different on every screen. Pick by density:
+Pick by density:
 `sm` for a dense row or inline cell, `md` for a control band, register or list (the default),
 `lg` for a prominent row or the account menu, `xl` for a profile's own header.
 
@@ -89,9 +88,7 @@ the product and its apps, so one person looked different on every screen. Pick b
 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: at the old 36 the same
-member chip measured 46 in a `Select` trigger, 50 in an inline editor and 54 in an `InlineSlot`,
-because each surface had picked its own inset with no number to pick it from. Put nothing taller
+a rung that overshoots doesn't look slightly big, it RESIZES the control. 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.
@@ -155,8 +152,7 @@ axes carry every shape it takes, and BOTH are decisions about meaning, not looks
   work already carried out, and nothing on screen corrects them. (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; they were
-two families until the anatomy proved identical.
+A record's Progress and a desk's to-do list are the same component two booleans apart.
 
 **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
@@ -1068,7 +1064,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `DetailTable`: the compound parent of
   a row STACK — `labelWidth` (default `DETAIL_LABEL_WIDTH`, 130 — THE kit's label column, and
   the record surface's) / `minHeight` (default 40, the inline-control grid) declared
-  ONCE + the `SPACE.md` (16) row gap — 8 was right while a field was a tint, but a stack of
+  ONCE + the `SPACE.md` (16) row gap — a stack of
   BORDERED rows that close together fuses into one block. TWO columns, no third: the value
   FILLS what the label leaves, so nothing one row does can narrow its neighbours' editors. RESPONSIVE with no prop: it
   measures its own container (onLayout, not
@@ -1078,7 +1074,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   grammar); raise `minValueWidth` (default 160) when a cell holds
   MORE than one editor so the table stacks earlier. Two tables on one page share one grid by
   repeating the same labelWidth. Worked example:
-  [`tpl_record`](../examples/tpl_record.tsx). A label's FIRST line centres on the control line, not the label block: a wrapped label grows DOWNWARD past the value's first line rather than dragging its own first line above it, so "Registered address" over two lines still starts level with the value it names.
+  [`tpl_record`](../examples/tpl_record.tsx).
 - **`record_summary`** — `RecordSummary`: the identity band of a record detail/drawer — ONE
   row: `title` xxl semibold tabular, `subtitle` sm muted, `status` Badge slot, optional
   `metric` {label,value,tone,note} pinned right, the band's ONE accent. The record's FIELDS
@@ -1175,8 +1171,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   and Save writes the pre-action values back over what it just fetched.
   The peek uses the popover's OWN anatomy: `PopoverHeader` for the identity, a scrolling body,
   and a **pinned `PopoverFooter`** for the verbs. A long block therefore scrolls with its actions
-  still reachable — the earlier hand-rolled footer was a body child and scrolled away, hiding its
-  own Save.
+  still reachable.
   `Edit` swaps the SAME grid's value cells for inputs — a DRAFT, so nothing commits until `Save`,
   which fires `onSave` with **only the facts that CHANGED** (never a snapshot, so a lock or
   `before_update` sees the real edit). This is what lets a peek hold editors at all: a
@@ -1365,7 +1360,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   never `style`**: `style` reaches only the BODY, and the panel is `max-content`, so a width set
   there governs the scroller while the header and footer sit outside it — the first long title
   then stretches the panel and leaves the content adrift in a box wider than itself. A popover
-  with no bands never sees this, which is why `width` had to exist before one had both.
+  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
@@ -1437,8 +1432,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `PieChart`: the canonical SVG chart set (no recharts).
 - **`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
-  (it replaced `RingGauge`). Same API shape as the bar — a real `value`/`max` rather than a
+- **`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
   pre-computed percentage, optional `label`/`caption`, and a `format` that turns the centre
   figure off. `format="none"` with no label leaves the arc bare at any size: that is the
   TRIGGER form, for a control row where a figure would be unreadable and a bar would not
@@ -1487,9 +1481,12 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   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. 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;
+  cannot be trusted to a caller's data: the **label clamps to two lines WHILE COLLAPSED**
+  (the description always) — a row is a scan target, and an unclamped one lets a single
+  user-authored note set the section's height. Opening the row un-clamps it, so **never
+  repeat the label inside `details`**: the fact belongs to one element, and a copy means
+  the reader meets the same sentence twice, cut off and then whole. `details` carries
+  what the label does not — the attachments, the machine's reading, the provenance;
   **`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;
@@ -1502,10 +1499,9 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   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
-  anatomy — a ring, a title, a value beside it, a muted note, a detail block, an optional
-  grouping level — differing only in whether a LINE joined the rings. **`connected` is that
-  line, and it is the whole difference**: on for ONE record walking positions (it asserts
+  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
   highest stamp so one click marks everything below it — a parent that ticked its children wrote
@@ -1659,10 +1655,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   NODE** as well as a string, because a second line can itself be carrying a change (a file
   being RECLASSIFIED is the same bytes filed differently — a `DiffValue` on the property); a
   node renders outside the muted single-line `Text`, which would clip it and fight its colour.
-  Both `sm` variants share ONE beat (48px min + 6px vertical padding): the static row used to
-  have neither, so it came out 37px against the pressable's 49 — whether a row was a door
-  decided how tall it was — and 37 sat under every other row beat in the kit (`DetailRow` 40,
-  `TableRow` 52, this component's own `md` 56), which is what "squeezed" literally was.
+  Both `sm` variants share ONE beat (48px min + 6px vertical padding).
 - **`file_rows`** — `FileRows`: batteries-included file list — row press → built-in gallery
   + a ⋯ Download/Open-external/Remove menu; composes `FileRow` + `ActionMenu` +
   `FileGalleryModal`; localized via the `gallery` locale slice. **`meta` has NO default**: the
@@ -1835,9 +1828,8 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `added`/`changed`/`removed`/`unchanged`, for the cases no single value carries. Glyph + an
   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. It briefly had two — a
-  bare glyph for dense surfaces, a filled shape for sparse ones — and a form marked with bare
-  glyphs beside a table marked with filled shapes read as two systems saying the same thing; a
+  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
   mark sit on a white row, a tinted cell, or a photograph. **`unchanged` renders as an empty

package/docs/composition.md

@@ -380,12 +380,7 @@ holds another component's PART takes that component's constant, never a hand-pic
 centred in an 18px column put the whole run rail 3px outside the surface's edge — every row
 wrong by the same amount, so it read as internally consistent and nothing flagged it.
 
-The register used to pad 20 WITHOUT the negative margin, and the cost was not
-the 20px — it was that everything nearby had to be hand-padded by the same 20 to
-line up with it. A `Table`'s header band, its static rows and its expanded detail
-all inherited the number; a `SummaryLine` above the register got it at the call
-site; a bare table's footer borrowed `CardFooter` and picked up a *card's*
-interior gutter. **An indent is legible only when something VISIBLE occupies it**
+**An indent is legible only when something VISIBLE occupies it**
 — a checkbox, an ordinal, a diff mark. An empty one is a defect, and the
 compensation it forces spreads to every new surface that sits beside it.
 
@@ -425,8 +420,7 @@ content off the register entirely.
 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
+whose text is written by the USER. 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.
 
@@ -530,9 +524,7 @@ 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
+siblings the eye reads one cluster. 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
@@ -550,7 +542,7 @@ Actions stay **visible** — a hover-only action is invisible to keyboard and to
 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,
 so it's still keyboard-reachable. Do that locally — there is deliberately no shared hover-reveal
-primitive (one existed and made the keyboard-inaccessible anti-pattern easy; it was removed).
+primitive.
 
 **A row is a button wrapped around DATA, so its text stays SELECTABLE and a drag is not a press.**
 The surface carries no blanket `userSelect: "none"` — that made a customer's own name and number
@@ -1033,10 +1025,7 @@ When it IS a status, match weight to prominence — lightest → heaviest:
    a surface (a drawer/detail header). Opt IN explicitly and sparingly; one per view, never
    sprinkled through rows.
 
-**`tonal` IS allowed on a register's ONE primary status column, and that is the rule this
-paragraph used to get wrong.** It read "a register's dense rows read lighter, the row's primary
-status is `dot`" while `badge.tsx` named "a register's primary Status column" as a legitimate
-tonal use — two docs, opposite answers, so the choice fell to whoever read which. What "one per
+**`tonal` IS allowed on a register's ONE primary status column.** What "one per
 view" governs is the number of badge KINDS on a surface, not the number of rows: badging the
 stage AND the type AND the city is the clutter the rule exists to stop; one status column that
 happens to render 133 times is one badge.

package/docs/data_entry.md

@@ -84,6 +84,10 @@ layout), click OR keyboard focus opens it for editing **with nothing moving** (z
 whole point), and it commits on blur (Enter saves, Escape reverts) or via `controls="buttons"`
 (✓ / ✕).
 
+**`numberOfLines` declares what ENTER means — wrapping does not.** A field left at one line holds a
+single-line value that may WRAP when it runs long (a title, a summary), and Enter finishes it.
+Declaring 2+ lines declares PROSE: Enter is a paragraph break and blur is what saves.
+
 **How "nothing moves" is achieved differs by editor, and the difference is a rule.** A field whose
 resting value is the RAW string (`InlineTextInput`) is ONE `<input>` in both states — it never
 swaps elements, and `editing` is a style state driven by focus. Two elements cannot be made to
@@ -217,16 +221,12 @@ 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
+scrollbar, nothing to scroll — 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.
+**And it gets worse as the surface narrows**: a budget is a count of LINES and the wrap point
+moves, so the narrower column wraps the same value into more hidden lines. 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
@@ -277,6 +277,17 @@ already promises and, repeated down a column, draws the grid a second time. Both
 identically, so this changes what a field looks like RESTING, never what it does. A hand-rolled
 pressable cell should match `bare`: nothing at rest, the border on hover — never a background wash.
 
+**A `bare` field aligns its TEXT, not its box.** Because it looks like text at rest, it sits on the
+column like text: the frame's 8px inset is pulled back out with a negative LEFT margin, so the glyphs
+land on the container's edge. Without that, every bare value rendered 8px right of the header naming
+it. The bleed is one-sided on purpose — a matching right bleed aligns nothing on left-aligned text and
+only pushes the frame past the edge its neighbours stop at, which shows the moment the border paints.
+Two consequences for callers: a `bare` field needs ~8px of slack on its LEFT to hover into (in a
+zero-gap column the borders of adjacent cells will touch), and it is the wrong variant for a surface
+where it must stay strictly inside its box — that is `framed`. A DISABLED `framed` field keeps the
+box: it drops the border and fill so it cannot promise a press, but it stays in line with the enabled
+fields beside it.
+
 A READ-ONLY value in the same column — a computed total, a system ID, a synced/locked field — is
 **`InlineStatic`**: it copies the editor box metrics exactly (height, padding, 1px transparent
 border) but stays FLAT and non-interactive, so editable (chip) vs read-only (flat) is legible at a
@@ -331,33 +342,46 @@ 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
+## A value rendered TWICE is the bug — not the resident editor
 
-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?**
+The section above is the default and holds everywhere. There is one thing that appears to
+contradict it, and the contradiction is worth naming because the wrong resolution is the
+tempting one: **a value that already appears elsewhere 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.
+A feed used to be the example. Its row LABEL was the gist, the body opened underneath, and a
+resident editor rendered the same sentence twice — stacked and identical, which reads as a
+mistake at any weight, so quieting the frame does not help. The fix looked like demoting the
+editor to a mode behind an **Edit** verb, and that is a workaround: it keeps the duplication and
+buys silence by hiding one copy behind a click. What it costs shows up immediately after —
+the verb has to live somewhere (a button nested in the row's own button, or a footer a scroll
+away from the sentence it edits), and every repair from there is a repair to the arrangement,
+not to the surface.
 
-**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.**
+**Render it once, and the question dissolves.** Text inside a press target cannot be edited where
+it sits, so a value a person WROTE does not belong in a row's label: the label is for derived,
+read-only text ("Stage changed to Won"). Move the prose out and it is an ordinary resident field
+with no mode, no verb, and one copy — `tpl_record`'s activity feed is the worked example, and the
+byline above it carries the derived facts that used to fight it for the row.
+
+So: if a resident editor would duplicate a value, **delete the duplicate**. Make the editor a mode
+only when the second appearance is genuinely load-bearing and cannot move.
 
 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.
+- **Only the prose a PERSON wrote is editable.** 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. If a surface does end up with an edit
+  verb, name it for the words rather than the row: "Edit", not "Edit entry", which claims the
+  whole entry is yours to rewrite.
+- **An EMPTY value still shows its field, and shows it FRAMED.** A surface fed by automations
+  receives entries with no words in them routinely — a recording lands and nobody has written it
+  up — so withholding the field lets a feed RECEIVE an entry it gives the reader no way to
+  finish. Empty is also the state where `bare` fails: grey placeholder text on an invisible box
+  does not read as somewhere you can type. Follow the value — `variant={value ? "bare" : "framed"}`
+  — so a written-up entry reads as prose and an empty one is recognisable as an input from across
+  the page. A button that reveals a field is the wrong trade: `InlineTextInput` has no
+  `autoFocus` (permanently mounted, every field on a record would fight for focus on load), so
+  the revealed field cannot take the caret and the reader pays a second click for less clarity.
 
 ## Fieldset form — fields lay out on a RESPONSIVE two-column grid
 
@@ -458,8 +482,7 @@ closes the list as its add-affordance.
 
 **`connected` decides which shape you are building.** ON for one record walking positions — the
 line asserts sequence, which is what a desk handoff IS. OFF for N items ticked in any order, where
-a line claims an order the work does not have. It is the same compound either way; they were two
-families until the anatomy turned out to be identical.
+a line claims an order the work does not have. It is the same compound either way.
 
 **A GROUP is a name and nothing else.** No control: a phase owns no completion of its own, so a
 ring there reports without responding — and one identical to the pressable rings beneath it
@@ -628,13 +651,6 @@ A record field whose value is documents. `<DetailRow label="Scan"><InlineFiles
 — a `FileRows` list (press a row to preview it full-screen, ⋯ to remove) with one CTA under it,
 sitting on the inline-control grid via `InlineSlot`.
 
-It exists because every other field type shipped BOTH halves — `Select`/`InlineSelect`,
-`TextInputField`/`InlineTextInput` — and files shipped only the section-scale one. So a record
-field holding documents got hand-rolled per app as `FileRows` + `pickFiles` + a `Button`, and
-each copy re-derived the same decisions. The one they missed is `InlineSlot`: raw children in a
-value column start at the cell edge and 20px tall, beside editors that are 40px with a 9px text
-inset, so the column acquires two left edges and two baselines and stops reading as a column.
-
 **Cardinality is a property of the FIELD, and it changes the verb.**
 
 | `multiple` | picker | CTA once something is attached | the host's `onAdd` must |