@lotics/ui 25.1.0 → 26.1.0

package/AGENTS.md

@@ -27,13 +27,23 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
   license to hand-roll.
 - **One canonical component per data role** (member → `MemberChip`, select → `OptionBadge`,
   files → `FilePreview` family, …) — the catalog's Reach-by-role outranks neighboring code.
+- **A section's ADD rides its heading row, right edge** — Add files, Add fee, New line: a
+  `primary` `Button` beside `SectionHeadingTitle`, rendered empty or full. Under the rows it
+  extends, the verb MOVES with the row count and vanishes off-screen on a long list; a heading is
+  the one place it doesn't. → [composition.md §The add-placement law](./docs/composition.md).
+- **`EmptyState` carries NO verb, and a FAILED read is not an empty one.** Four region states,
+  picked by what the region can ASSERT: `Skeleton`/`Loading` in flight → **`ErrorState`**
+  (`message`/`detail`/`onRetry`) on failure → `EmptyState` (succeeded, found nothing) →
+  `CompletionState` on done. An alert glyph inside an empty state claims the read succeeded when
+  nothing is known. → [catalog.md §Status / feedback](./docs/catalog.md).
 - **Progress: rows of WORK vs positions of ONE thing.** N items ticked in any order, every row
   the same shape → `task` (`TaskList`). ONE record walking ordered stages where the stage decides
   which fields, conditions and act are even offered → **`pipeline`** (`Pipeline` +
   `PipelineStage`, over `stepper`) — worked in `examples/tpl_record.tsx` § Progress, which it took
   over FROM a per-desk checklist. Rendering positions as a checklist forces every row to carry
   every control and never says where the record sits; rendering work items as a pipeline implies
-  an order that is not there.
+  an order that is not there. A long ladder whose stages each own one value goes dense with
+  `PipelineStage.trailing` rather than a hand-rolled title row — see `docs/catalog.md`.
 - **`Badge` = STATUS only; supporting detail is the muted second line.** A type / category /
   attribute / count is not a status — it belongs under its identity as `size="xs" color="muted"`,
   never a second chip. A chip beside a name reads as its PEER (a colored one reads louder),

package/MIGRATION.md

@@ -4,6 +4,57 @@ 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.
 
+## 26.0.0 — a section's ADD moves to its heading row; `EmptyState` loses its verb
+
+**`EmptyState.action` is REMOVED — no replacement on that component.** Two different things
+were going into it, and neither belonged:
+
+- **"Create the first one"** gave the section's add a SECOND home that exists only while the
+  list is empty, so the verb jumped elsewhere the moment the first row landed — and on a long
+  list the other copy sat off-screen below the rows. The add now lives on the section's heading
+  row, at the right, rendered whether the collection is empty or full (`AGENTS.md` iron rules,
+  `composition.md` § The add-placement law).
+- **"The read failed, try again"** was a failure wearing an empty state's clothes. An empty
+  state asserts the read SUCCEEDED and found nothing; a failed read does not know whether there
+  is anything. That is now **`ErrorState`** (NEW, `@lotics/ui/error_state`).
+
+```tsx
+// BEFORE — the add lived in the empty state, and again under the rows
+<SectionHeading><SectionHeadingTitle>Fees</SectionHeadingTitle></SectionHeading>
+{fees.length === 0
+  ? <EmptyState message="No fees" action={<Button title="Add fee" onPress={addFee} />} />
+  : <Table …/>}
+{fees.length > 0 ? <Button title="Add fee" onPress={addFee} /> : null}
+
+// AFTER — one add, one place, never moves
+<SectionHeading>
+  <SectionHeadingTitle>Fees</SectionHeadingTitle>
+  <Button title="Add fee" color="primary" onPress={addFee} />
+</SectionHeading>
+{fees.length === 0 ? <EmptyState message="No fees" /> : <Table …/>}
+```
+
+```tsx
+// BEFORE — a failure rendered as an empty, with a hand-written retry
+<EmptyState icon="triangle-alert" message="Couldn't load trips" hint={err}
+            action={<Button title="Reload" onPress={() => q.refetch()} />} />
+
+// AFTER — its own state; the kit words the button (locale `errorState.retry`)
+<ErrorState message="Couldn't load trips" detail={err} onRetry={() => q.refetch()} />
+```
+
+**Per call site:** an `action` that CREATED → delete it, put the button in the heading. One that
+RECOVERED from a failed read → switch the whole component to `ErrorState` and drop the label.
+One that cleared filters on a no-results empty → delete it; that empty is hint-only and the
+filter controls carry their own clear.
+
+**Locale packs** gain `errorState: { retry }`. A custom pack won't compile until it's filled —
+which is the point.
+
+**Also new (additive, no migration):** `Step.headHeight` and `PipelineStage.trailing` — a stage
+whose title row carries an inline control. Hand-rolling that row leaves the marker centred on a
+text line while the label centres in the taller row, so every label reads ~10px low.
+
 ## 25.0.0 — `ReferenceField` edits in place; `onRemove` becomes `onClear`
 
 **`onRemove` is now `onClear` — a pure rename, identical behaviour.** The act was always

package/docs/catalog.md

@@ -236,8 +236,10 @@ reference), `InfoPopover` (the ⓘ explainer).
 
 ### Status / feedback
 
-`Badge` / `StatusBadge`, `Callout` (inline status), `EmptyState`, `CompletionState`,
-`ActivityIndicator` / `Loading`, `Skeleton`.
+`Badge` / `StatusBadge`, `Callout` (a failure INSIDE a flow), and the four REGION states a read
+passes through — `Skeleton` / `Loading` (in flight) → `ErrorState` (failed) → `EmptyState`
+(succeeded, nothing) → `CompletionState` (done). Pick by what the region can ASSERT: an empty
+says the read succeeded and found nothing, a failed read knows neither.
 
 ### Files
 
@@ -411,7 +413,10 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `weight="medium"` opt-down only) + `info` for an ⓘ provenance popover after the title,
   same as `CardHeaderTitle.info`. `SubsectionHeadingTitle` is the `###` lg-semibold level-3
   title of a named group inside a section (same `info` ⓘ affordance as the section title) —
-  heading-row siblings ride its right edge. `DialogSectionHeadingTitle` is the `####`
+  heading-row siblings ride its right edge. **A section's ADD is one of those siblings** — a
+  `primary` `Button` beside the title, rendered whether the collection is empty or full, never
+  under the rows it extends and never repeated in the `EmptyState`
+  (composition.md § The add-placement law). `DialogSectionHeadingTitle` is the `####`
   md-semibold rung with the SAME `icon`/`description`/`info` slots as the section title, so a
   dialog surface loses only the type size, never an affordance. The heading ramp is FIXED:
   `#` xxl / `##` xl / `###` lg / `####` md, no size props.
@@ -553,8 +558,18 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`callout`** — `Callout`, `CalloutTitle`, `CalloutText`, `CalloutActions` (`tone`
   info|success|warning|error|neutral): inline status band — a MESSAGE (`warning`/`error`
   are ARIA `alert`s). For a form / nested content surface use **`Inset`**, never a Callout.
-- **`empty_state`** — `EmptyState`: centered placeholder for an empty list/filter result —
-  `message` + `hint`, optional `icon` anchor and `action` CTA.
+- **`empty_state`** — `EmptyState`: centered placeholder for a read that SUCCEEDED and found
+  nothing — `message` + `hint` + an optional `icon` anchor, and **no verb at all**. It cannot hold
+  the section's add (that lives on the heading row, where it does not move — § The add-placement
+  law in composition.md), a no-results empty is HINT-only since the filters that emptied it carry
+  their own clear, and a FAILED read is `ErrorState`, not this.
+- **`error_state`** — `ErrorState`: the region-scale FAILED read — `message` + optional `detail`
+  + `onRetry` (the kit renders the button and words it from the locale pack, so "try again" reads
+  the same everywhere). The fourth of the region states: `Skeleton`/`Loading` in flight → this on
+  failure → `EmptyState` on nothing → `CompletionState` on done. Rendering a failure as an empty
+  asserts the read succeeded and found nothing, when nothing is known. For a failure INSIDE a
+  flow (a form that won't save) use `Callout tone="error"`; this is for a region with no content
+  to show, where a tinted strip leaves the area collapsed.
 - **`completion_state`** — `CompletionState`: the "all done" terminal state.
 - **`skeleton`** — `Skeleton`: loading placeholder blocks.
 - **`loading`** — `Loading`: the centered indeterminate loading state (composes
@@ -864,7 +879,14 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   derived value that rides along read-only); `multiline` for an address or an account block;
   `type: "date"` swaps the draft's text input for a `DatePicker` and formats the read value —
   the fact's `value` stays the canonical ISO string on both sides, so a date is never edited as
-  free text and the format ambiguity never reaches the record.
+  free text and the format ambiguity never reaches the record; `action` hangs a verb ABOUT the
+  value on it (an `InlineButton` — "look this tax id up"), rendered AT REST only, because an
+  action writes the RECORD while a draft holds values seeded before it ran — fire one mid-draft
+  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.
   `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
@@ -1175,6 +1197,12 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   moving, one stage live, different controls per stage; `task` is N identical rows ticked in any
   order. `PipelineNote` is a condition ON a stage (never a `Callout` above the run);
   `PipelineField` stays editable on a PASSED stage, which is what makes a mis-entry fixable.
+  A field stacks UNDER the title (two lines per stage); on a ladder long enough that this
+  pushes the run past a screenful, **`PipelineStage.trailing`** puts ONE value on the title's
+  own row instead. Never hand-roll that row: a control is twice a text line's height, so the
+  marker — which centres on the first row — reads half the difference too high against it.
+  `trailing` fixes the row at `INLINE_CONTROL_HEIGHT` and tells the `Step`, so the ladder keeps
+  one rhythm whatever the value is. An ACT still belongs in `PipelineActions`.
   Worked screen: `examples/tpl_record.tsx` § Progress — the desks (Sales → Operations →
   Accounting) ARE the stages, each owning the facts it stamps and, on the live one, the act
   that leaves it. A `PipelineStage` is deliberately NOT pressable: its body holds the controls.
@@ -1185,6 +1213,11 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   switcher; the guided-run / agent-feed primitive. It is a **`list` of `listitem`s** with
   `aria-current="step"` on the live one — a sequence of NAMED positions whose steps carry
   their own content is a list, never a `progressbar`.
+  VERTICAL: the marker centres on the content's FIRST ROW, assumed to be one line of `sm` text.
+  Put anything taller on that row — an inline editor beside the label — and pass
+  **`Step.headHeight`** (`INLINE_CONTROL_HEIGHT` for an editor) or the marker stays pinned to
+  the text line while the label centres in the taller row. Prefer `PipelineStage.trailing`,
+  which does this for you.
 
 ### Files
 

package/docs/composition.md

@@ -44,9 +44,9 @@ restyle a heading level per-page.
   numbers) + optional `CardHeaderMeta` (a count/unit/period, xs muted tabular).
 - **Section title** — ONE construct: `Section` › `SectionHeading` › `SectionHeadingTitle`
   (`##` — xl semibold, optional muted `description` and `info` popover), everything left-aligned
-  at the column edge; `SectionHeadingMeta` and any VIEW control ride the heading row's right edge
-  (the title's `flex: 1` pushes them) — but a verb that CHANGES the content does not: see the
-  action-placement law below. The page column is a **`SectionStack`** — it owns the
+  at the column edge; `SectionHeadingMeta`, any VIEW control, and the section's own ADD ride the
+  heading row's right edge (the title's `flex: 1` pushes them) — see the add-placement law
+  below. The page column is a **`SectionStack`** — it owns the
   between-section law (a fixed 56px beat + a bare hairline separating one section from the NEXT;
   null/false children are skipped so a conditional section never leaves a stray hairline). The
   `Divider` NEVER goes directly under a heading — that orphans the title from its own content.
@@ -101,6 +101,30 @@ restyle a heading level per-page.
 - **Gate header** — a `Dialog` uses `DialogHeaderTitle`; a popover form uses
   `Text size="sm" weight="semibold"` + an optional xs muted subtitle.
 
+### The add-placement law — a section's ADD rides its heading row, right edge
+
+**Add files / Add fee / Add member / New line — the verb that EXTENDS a section's collection
+sits on that section's heading row, at the right, and nowhere else.** One `Button` as a sibling
+of `SectionHeadingTitle` (whose `flex: 1` pushes it there); the same at subsection and card
+altitude (`SubsectionHeading`, `CardHeader`).
+
+The rule is about a position that does not MOVE. Put the add under the register it extends and
+where the reader looks for it depends on how many rows there already are — past a screenful the
+verb is off-screen, and on an empty list there is no last row to sit under, so it has to become
+a second button inside the `EmptyState`. That is one verb with two homes, neither findable
+without scanning. The heading row is the section's control line — it already carries the meta
+and the view controls — so the add belongs on it, in the same spot whether the section holds
+nought or forty.
+
+- **Weight is the section's**, not a hedge: a section's add is the act that section offers, so
+  `primary`. Don't drop to `secondary` because the list is full — an add that changes weight
+  with row count is the fault, not the cure.
+- **It renders unconditionally**, empty or not. A heading whose CTA appears only once there is
+  data cannot be used to create the first row.
+- **The `EmptyState` then takes NO `action`** — see § Empty states.
+- **Only the ADD.** A verb that acts on a SELECTION (delete, export, run) belongs to the
+  selection — `FloatingActionBar` — and a verb about ONE row stays on the row.
+
 ## Period filters for time-constrained data
 
 Time-constrained data gets a **`DateRangeFilterField`** in the header band — never a static period
@@ -832,13 +856,20 @@ one exists).
 
 ### Empty states — confirm, orient, one action
 
-An empty region has three jobs (NN/g): confirm this is EMPTY (not loading, not broken), say
-what belongs here, and offer ONE next action — the `EmptyState` props are this anatomy
-(`message` = what's empty, `hint` = what to do about it, `action` = the one CTA). The three
-empties get DIFFERENT copy:
+An empty region has three jobs (NN/g): confirm this is EMPTY — not loading, not broken — and
+say what belongs here. The `EmptyState` props are that anatomy and nothing more (`message` =
+what's empty, `hint` = what to do about it). "Not broken" is why the failed read has its own
+component: an alert glyph inside an empty state says both at once and means neither.
+
+**`EmptyState` carries NO verb.** The add is on the heading row (§ The add-placement law) and
+duplicating it here would put two buttons for one act in view and make the add jump the moment
+the first row lands. A read that FAILED is not an empty one — it does not know whether there is
+anything — so it gets `ErrorState` (`message` + `detail` + `onRetry`), never an empty state
+wearing an alert glyph. The three empties get DIFFERENT copy:
 
-- **First use** → teach + invite: message names what will live here, `action` creates the first
-  one ("Chưa có khoản phí" + "Thêm khoản thu/chi cho lô" + a Thêm phí button).
+- **First use** → teach + invite: message names what will live here, and the CTA — the
+  heading's, or `action` where there is no heading — creates the first one ("Chưa có khoản phí"
+  + "Thêm khoản thu/chi cho lô").
 - **User cleared it** → stay quiet: the user knows why it's empty; confirmation only, no tutorial.
 - **No search/filter results** → help recover: restate the scope ("Không có lô nào khớp
   'ABC'"), hint the fix ("Thử từ khóa khác / xóa bộ lọc"). Never a blank panel or bare "No data".

package/docs/templates.md

@@ -309,8 +309,9 @@ billing, and quick-capture templates. Top → bottom:
   just Documents) — a drag or Ctrl/Cmd+V ANYWHERE on the record (`disabled` while the intake
   dialog runs so a paste can't start a second one) — all landing in ONE `intakeFiles` fork
   dialog. The Documents section therefore carries NO drop target of its own (the whole-record
-  one covers it), only its Add-files CTA and a muted `SectionHeadingTitle description` ("Drag,
-  paste, or click to add files") that keeps the otherwise-invisible paths discoverable.
+  one covers it), only its Add-files CTA on the heading row's right edge and a muted
+  `SectionHeadingTitle description` ("Drag, paste, or click to add files") that keeps the
+  otherwise-invisible paths discoverable.
   Every row's leading visual is a `FileThumbnail` in ONE square 32px slot — an image file
   fills it as a real thumbnail, a document centers its badge in it — never a bare `FileBadge`
   (mixed footprints misalign the identity column). The desk holds what ARRIVES; generation
@@ -332,7 +333,9 @@ billing, and quick-capture templates. Top → bottom:
   a `priority`-annotated register `Table` (Fee, Type, Party, Amount, Status — status in
   plain ink, danger only when overdue) → EVERY row opens a right-docked entity `Drawer`
   (◀ ▶ + position stepping) with all fields inline-editable and a confirmed Remove in the
-  `DrawerFooter`. "Add fee" is create-then-refine: a blank fee opens straight in the drawer.
+  `DrawerFooter`. "Add fee" rides the section heading's right edge — the one place it does not
+  move as rows arrive — and is create-then-refine: a blank fee opens straight in the drawer. The
+  empty state carries no button of its own, because that one is already on screen.
 - **Billing — a REGISTER, the same shape as Fees.** Both sections are a list of money items
   where each item has detail and a per-item act, so both are a compact `Table` whose row opens
   its FULL detail in a right-docked `Drawer` (◀ ▶ step the invoices) — the drill-down law.

package/examples/tpl_record.tsx

@@ -2030,6 +2030,17 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418" }: { chrome?:
             {/* The standard files-section affordance line — drag / paste / click
                 stay discoverable even though the drop target is the whole record. */}
             <SectionHeadingTitle description="Everything that ARRIVED on this record. Drag, paste, or click to add.">Files</SectionHeadingTitle>
+            {/* The section's ADD, on the heading row — see the Fees section for
+                the rule. PENDING until the user chooses: saving is a decision the
+                dialog asks for (save only / run a task), never a side effect of
+                picking — closing the dialog discards. */}
+            <Button
+              title="Add files"
+              color="primary"
+              onPress={() => {
+                void pickFiles({ accept: "application/pdf,image/*", multiple: true }).then(intakeFiles);
+              }}
+            />
           </SectionHeading>
           <Table
             columns={DOC_COLUMNS}
@@ -2072,19 +2083,6 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418" }: { chrome?:
               </TableRow>
             ))}
           </Table>
-          {/* the Add, under the register it extends — see the Fees section for
-              why it is not in the heading. PENDING until the user chooses:
-              saving is a decision the dialog asks for (save only / run a task),
-              never a side effect of picking — closing the dialog discards. */}
-          <View style={{ flexDirection: "row" }}>
-            <Button
-              title="Add files"
-              color="primary"
-              onPress={() => {
-                void pickFiles({ accept: "application/pdf,image/*", multiple: true }).then(intakeFiles);
-              }}
-            />
-          </View>
         </Section>
         </View>
 
@@ -2330,6 +2328,18 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418" }: { chrome?:
         <Section>
           <SectionHeading>
             <SectionHeadingTitle description="Every fee the order incurs or charges — its party, due date and paid state.">Fees</SectionHeadingTitle>
+            {/* THE SECTION'S ADD RIDES THE HEADING ROW, right edge — the one
+                place it can sit that does not MOVE. Under the register it sat
+                below the last row, so where a reader looks for "how do I add
+                one" depended on how many there already were: past a screenful
+                the verb is off-screen entirely, and on an empty list there is no
+                last row to sit under, so it had to be a SECOND button inside the
+                `EmptyState`. One verb, two renderings, neither findable without
+                scanning. The heading row is the section's control line — it
+                already carries `SectionHeadingMeta` and the title grows to push
+                its siblings right — so the add belongs on it, in the same spot
+                whether the list holds nought or forty. */}
+            <Button title="Add fee" color="primary" onPress={addFee} />
           </SectionHeading>
           <SummaryLine
             items={[
@@ -2338,8 +2348,13 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418" }: { chrome?:
               { label: "to pay", value: fees.filter((f) => f.direction === "cost" && !f.paid).reduce((s, f) => s + f.amount, 0), format: "currency", compact: true, tone: fees.some((f) => f.direction === "cost" && feeOverdue(f)) ? "warning" : undefined },
             ]}
           />
+          {/* The empty state takes NO `action` — the heading's Add is the only
+              one, and it is already on screen. Repeating the section's verb here
+              puts two buttons for one act in view at once, and makes the add MOVE
+              the moment the first row lands. The empty state says what the
+              section holds; the heading says how to fill it. */}
           {fees.length === 0 ? (
-            <EmptyState icon="receipt" message="No fees on this order" hint="Add the first charge or cost — it expands ready to fill in." action={<Button title="Add fee" color="primary" onPress={addFee} />} />
+            <EmptyState icon="receipt" message="No fees on this order" hint="Add the first charge or cost — it expands ready to fill in." />
           ) : (
             <Table columns={FEE_COLUMNS}>
               {fees.map((f) => {
@@ -2457,21 +2472,6 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418" }: { chrome?:
               })}
             </Table>
           )}
-          {/* THE ADD SITS WHERE ITS RESULT APPEARS — under the last row, on the
-              list's own left edge. In the heading it sat ABOVE the thing it
-              extends and at a different altitude from it, and it competed with
-              the title for the one line that names the section. Secondary and
-              left, and PRIMARY — in the empty state too, which is what makes it
-              consistent. A section's add is the act that section offers, so it
-              carries the section's weight; a lone `secondary` button reads as
-              though the real action were somewhere else. One verb keeps ONE
-              weight either way: the fault to avoid is an add that is primary on
-              an empty list and secondary on a full one. */}
-          {fees.length > 0 ? (
-            <View style={{ flexDirection: "row" }}>
-              <Button title="Add fee" color="primary" onPress={addFee} />
-            </View>
-          ) : null}
         </Section>
         </View>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "25.1.0",
+  "version": "26.1.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -63,6 +63,7 @@
     "./kpi_strip": "./src/kpi_strip.tsx",
     "./summary_line": "./src/summary_line.tsx",
     "./empty_state": "./src/empty_state.tsx",
+    "./error_state": "./src/error_state.tsx",
     "./format_date": "./src/format_date.ts",
     "./format_money": "./src/format_money.ts",
     "./calendar": "./src/calendar/index.ts",

package/src/callout.tsx

@@ -40,7 +40,10 @@ const TONES: Record<CalloutTone, ToneStyle> = {
 /**
  * An inline callout — a tinted, bordered box carrying a short status message
  * (info / success / warning / error / neutral). Use it inline in a flow: form
- * feedback, a heads-up, an actionable empty state. For a blocking, dismissible
+ * feedback, a heads-up, a failure INSIDE a flow. NOT for a dead region — a list
+ * that came back empty is `EmptyState`, one that FAILED is `ErrorState`; a
+ * tinted strip there leaves the area collapsed and reading as a render bug.
+ * For a blocking, dismissible
  * prompt use `Alert`; for a one-word status use `Badge`. The tone is carried by
  * the icon + tint + border (never color alone — the icon and text stay legible),
  * so it reads on a glance and meets contrast on the light tint.

package/src/empty_state.tsx

@@ -1,4 +1,3 @@
-import type { ReactNode } from "react";
 import { View, StyleSheet } from "react-native";
 import { Text } from "./text";
 import { Icon, type IconName } from "./icon";
@@ -12,16 +11,28 @@ interface EmptyStateProps {
   /** Optional Lucide glyph centered above the message — a visual anchor so the
    *  empty region reads as a deliberate state, not two lone lines of muted text. */
   icon?: IconName;
-  /** Optional call-to-action below the text (e.g. a Button) for an actionable
-   *  empty state ("no records yet → create one"). */
-  action?: ReactNode;
 }
 
 /**
  * Centered placeholder for an empty list/filter result. Generous vertical
  * space on purpose — an empty region that collapses to nothing reads as a
- * rendering bug, not a state. Pass `icon` for a visual anchor and `action`
- * for a CTA when the empty state is actionable.
+ * rendering bug, not a state.
+ *
+ * IT CARRIES NO VERB — the prop is gone, not narrowed. This took an
+ * `action?: ReactNode` and two different things went into it, both wrong here:
+ *
+ * - **"Create the first one"** put the section's add in a SECOND place that only
+ *   exists while the list is empty, so the verb jumped elsewhere the moment the
+ *   first row landed. It belongs on the section's heading row, where it does not
+ *   move (composition.md § The add-placement law).
+ * - **"The read failed, try again"** was a failure wearing an empty state's
+ *   clothes. That asserts the read SUCCEEDED and found nothing, when the truth
+ *   is that nothing is known — use `ErrorState`. Retrying a true empty just
+ *   returns the same nothing.
+ *
+ * What is left says one thing and offers nothing to press: this region is empty,
+ * and here is what would live in it. A no-results empty is hint-only too — the
+ * filters that emptied it carry their own clear.
  */
 export function EmptyState(props: EmptyStateProps) {
   return (
@@ -39,7 +50,6 @@ export function EmptyState(props: EmptyStateProps) {
           {props.hint}
         </Text>
       ) : null}
-      {props.action ? <View style={styles.action}>{props.action}</View> : null}
     </View>
   );
 }
@@ -53,7 +63,4 @@ const styles = StyleSheet.create({
   icon: {
     marginBottom: 4,
   },
-  action: {
-    marginTop: 8,
-  },
 });

package/src/error_state.tsx

@@ -0,0 +1,75 @@
+import { View, StyleSheet } from "react-native";
+import { Text } from "./text";
+import { Button } from "./button";
+import { Icon } from "./icon";
+import { solid } from "./colors";
+import { useLoticsLocale } from "./locale";
+
+export interface ErrorStateProps {
+  /** What failed, in plain language ("Couldn't load customers"). */
+  message: string;
+  /** The cause when the system knows it — the server's own message. Never a
+   *  stack trace or an error code alone: neither tells the reader what to do. */
+  detail?: string;
+  /** Re-run the read. Omitted for a failure the reader cannot retry (denied,
+   *  not found) — the kit renders the button and words it from the locale pack,
+   *  so "try again" is phrased the same everywhere instead of per app. */
+  onRetry?: () => void;
+}
+
+/**
+ * The read FAILED — the region-scale sibling of `EmptyState`, and the missing
+ * fourth in the family (`Skeleton`/`Loading` in flight → this on failure →
+ * `EmptyState` on nothing → `CompletionState` on done).
+ *
+ * IT EXISTS BECAUSE EMPTY AND FAILED ARE DIFFERENT ASSERTIONS. "No fees on this
+ * order" says the read succeeded and there is nothing; a failed read does not
+ * know whether there is anything. Apps were rendering the failure through
+ * `EmptyState` with an alert glyph and a hand-written retry — which states a
+ * fact the system does not have (unknown drawn as none), and left every app
+ * inventing its own wording for the same verb. A retry on a TRUE empty is
+ * equally wrong: running it again returns the same nothing.
+ *
+ * Use `Callout tone="error"` instead for a failure inside a flow — a form that
+ * would not save. This is for a whole REGION that has no content to show, where
+ * a tinted strip would leave the area collapsed and reading as a render bug.
+ */
+export function ErrorState(props: ErrorStateProps) {
+  const words = useLoticsLocale();
+  return (
+    <View style={styles.container}>
+      <View style={styles.icon}>
+        <Icon name="triangle-alert" size={28} color={solid("red")} />
+      </View>
+      <Text size="sm" color="muted">
+        {props.message}
+      </Text>
+      {props.detail ? (
+        <Text size="xs" color="muted">
+          {props.detail}
+        </Text>
+      ) : null}
+      {props.onRetry ? (
+        <View style={styles.action}>
+          <Button title={words.errorState.retry} color="secondary" onPress={props.onRetry} />
+        </View>
+      ) : null}
+    </View>
+  );
+}
+
+// The same rhythm as `EmptyState` — the two swap into one another as a read
+// settles, and a region that changed height on failure would jump the page.
+const styles = StyleSheet.create({
+  container: {
+    paddingVertical: 48,
+    alignItems: "center",
+    gap: 4,
+  },
+  icon: {
+    marginBottom: 4,
+  },
+  action: {
+    marginTop: 8,
+  },
+});

package/src/locale.tsx

@@ -70,6 +70,9 @@ export interface LoticsLocale {
   ledger: { rowDetails: (label: string) => string };
   /** `SectionHeadingTitle`: the info-popover trigger's screen-reader name. */
   sectionHeading: { info: string };
+  /** `ErrorState`'s retry button. The kit owns the wording so "try again" is
+   *  phrased identically everywhere instead of hand-written per app. */
+  errorState: { retry: string };
   /** `Chip`: the ✕ default name when no `dismissTooltip` is given. */
   chip: { remove: string };
   /** `SequenceItem`: the reorder + drop controls on one position of a `Sequence`. */
@@ -234,6 +237,7 @@ export const en: LoticsLocale = {
   clarify: { otherPlaceholder: "Or type your own answer…", back: "Back", next: "Next", cancel: "Cancel", submit: "Submit" },
   ledger: { rowDetails: (label) => `${label} details` },
   sectionHeading: { info: "About this data" },
+  errorState: { retry: "Try again" },
   chip: { remove: "Remove" },
   sequence: { moveUp: "Move up", moveDown: "Move down", remove: "Remove" },
   trendFooter: { up: "Up", down: "Down" },
@@ -393,6 +397,7 @@ export const vi: LoticsLocale = {
   clarify: { otherPlaceholder: "Hoặc nhập câu trả lời khác…", back: "Quay lại", next: "Tiếp", cancel: "Hủy", submit: "Gửi" },
   ledger: { rowDetails: (label) => `Chi tiết ${label}` },
   sectionHeading: { info: "Giải thích dữ liệu" },
+  errorState: { retry: "Thử lại" },
   chip: { remove: "Xóa" },
   sequence: { moveUp: "Lên trên", moveDown: "Xuống dưới", remove: "Xóa" },
   trendFooter: { up: "Tăng", down: "Giảm" },

package/src/pipeline.tsx

@@ -2,6 +2,7 @@ import { type ReactNode } from "react";
 import { View } from "react-native";
 import { Text } from "./text";
 import { Stepper, Step, type StepPositional, type StepStatus } from "./stepper";
+import { INLINE_CONTROL_HEIGHT } from "./inline_edit";
 
 export interface PipelineProps {
   children?: ReactNode;
@@ -40,11 +41,16 @@ export interface PipelineProps {
  *   editable behind you, or the only way to fix a mis-entry is direct table
  *   access.
  *
+ * A stage's values stack UNDER its title by default (`PipelineField`), which
+ * costs two lines each. On a ladder long enough that this pushes the run past a
+ * screenful, `trailing` puts one value on the title's own row instead.
+ *
  * ```tsx
  * <Pipeline>
  *   <PipelineStage status="done" title="Submitted">
  *     <PipelineField label="Date"><InlineDatePicker … /></PipelineField>
  *   </PipelineStage>
+ *   <PipelineStage status="done" title="Received" trailing={<InlineDatePicker … />} />
  *   <PipelineStage status="current" title="In review" meta="Waiting 3d, Ops">
  *     <PipelineNote tone="warning">Sent back — missing payslips.</PipelineNote>
  *     <PipelineActions>
@@ -71,6 +77,18 @@ export interface PipelineStageProps extends StepPositional {
   /** A muted line under the title: how long it has sat here, whose desk it is on.
    *  Prose, not a value the reader sets. */
   meta?: string;
+  /**
+   * ONE value the stage owns, on the TITLE's row rather than stacked under it —
+   * the date a milestone was reached, its reference number. Use it when the
+   * ladder is long enough that a `PipelineField` per stage costs two lines each
+   * and pushes the whole run past a screenful; use `PipelineField` when the value
+   * needs a label to be read, or when there is more than one.
+   *
+   * The row is fixed at `INLINE_CONTROL_HEIGHT` whatever you put here, so the
+   * marker lines up with the title and the stages keep one rhythm down the spine.
+   * An ACT still belongs in `PipelineActions` — this is for a value.
+   */
+  trailing?: ReactNode;
   /** The stage's own body — `PipelineNote`, `PipelineField`, `PipelineActions`,
    *  or anything else. A stage with no body renders as its title alone, which is
    *  what an unreached stage should be. */
@@ -78,27 +96,49 @@ export interface PipelineStageProps extends StepPositional {
   accessibilityLabel?: string;
 }
 
-/** One milestone. Its title reads by STATUS — the current one in full ink and
- *  medium weight, everything else muted — so the eye lands on the stage that is
- *  live without reading a word.
+/** One milestone. Its title reads by STATUS — the LIVE one (`current`, or the
+ *  terminal `complete`) in full ink and medium weight, everything else muted —
+ *  so the eye lands on where the record sits without reading a word.
  *
  *  Deliberately NOT pressable. `Step` can be (a wizard whose steps navigate),
  *  but a pipeline stage is a workspace, not a destination — its body already
  *  holds the controls, and a press target wrapping them would swallow their taps. */
 export function PipelineStage(props: PipelineStageProps) {
-  const { status, title, meta, children, accessibilityLabel, ...positional } = props;
-  const isCurrent = status === "current";
+  const { status, title, meta, trailing, children, accessibilityLabel, ...positional } = props;
+  // `complete` is the terminal stage REACHED — where a finished record sits, not
+  // one it walked past. Muting it like an unreached stage leaves a completed run
+  // with nothing in full ink, so the eye has no landing point and the last thing
+  // that happened reads as the thing that hasn't.
+  const isLive = status === "current" || status === "complete";
+  const titleText = (
+    <Text size="sm" color={isLive ? "default" : "muted"} weight={isLive ? "medium" : "regular"}>
+      {title}
+    </Text>
+  );
   return (
     <Step
       status={status}
       accessibilityLabel={accessibilityLabel ?? title}
+      // The marker centres on the FIRST ROW, so it has to be told when that row
+      // is a control band and not a line of text — otherwise it stays pinned to
+      // the text and every title reads low by half the difference.
+      headHeight={trailing != null ? INLINE_CONTROL_HEIGHT : undefined}
       {...positional}
     >
       <View style={{ gap: 6 }}>
         <View style={{ gap: 2 }}>
-          <Text size="sm" color={isCurrent ? "default" : "muted"} weight={isCurrent ? "medium" : "regular"}>
-            {title}
-          </Text>
+          {trailing != null ? (
+            // Fixed at the control band whatever `trailing` holds: a stage whose
+            // row height followed its content would step the marker in and out of
+            // alignment down the ladder, and a badge would sit on a shorter row
+            // than a date picker two stages up.
+            <View style={{ flexDirection: "row", alignItems: "center", gap: 12, minHeight: INLINE_CONTROL_HEIGHT }}>
+              <View style={{ flex: 1, minWidth: 0 }}>{titleText}</View>
+              {trailing}
+            </View>
+          ) : (
+            titleText
+          )}
           {meta ? <Text size="xs" color="muted">{meta}</Text> : null}
         </View>
         {children}

package/src/reference_field.tsx

@@ -1,13 +1,12 @@
-import { useRef, useState } from "react";
+import { useRef, useState, type ReactNode } from "react";
 import { View } from "react-native";
 import { Button } from "./button";
 import { DatePicker } from "./date_picker";
 import { DetailRow, DetailTable } from "./detail_row";
 import { formatDate } from "./format_date";
-import { Divider } from "./divider";
 import { InlineEditView } from "./inline_edit";
 import { InlineStatic } from "./inline_static";
-import { Popover, PopoverContent } from "./popover";
+import { Popover, PopoverContent, PopoverFooter, PopoverHeader } from "./popover";
 import { DialogSectionHeadingTitle } from "./section_heading";
 import { Text } from "./text";
 import { TextInputField } from "./text_input_field";
@@ -86,6 +85,17 @@ export interface ReferenceFact {
    * the input.
    */
   type?: "text" | "date";
+  /**
+   * A verb ABOUT this value — an `InlineButton`, per the kit's rule that such a
+   * verb travels with what it acts on. "Look this tax id up in the business
+   * register", "call this number".
+   *
+   * Rendered at REST, never inside the draft, and that is a correctness bound
+   * rather than a layout choice: an action here acts on the RECORD, while a
+   * draft holds values seeded before it ran. Fire one mid-draft and Save would
+   * write the pre-action values straight back over whatever it just fetched.
+   */
+  action?: ReactNode;
 }
 
 export interface ReferenceFieldProps {
@@ -250,16 +260,25 @@ export function ReferenceField(props: ReferenceFieldProps) {
           (`DialogSectionHeadingTitle`, ####) with the code as its description
           rather than a hand-picked font weight; the facts are `DetailRow`s, which
           is what label-beside-value IS everywhere else on this page; and the
-          destructive verb is fenced off by a `Divider` instead of floating after
+          verbs sit in the popover's own pinned footer rather than floating after
           the last fact. Width matches `Peek`'s own content width so every peek in
           an app is the same object.
           `labelWidth` is the one override, and it is not arbitrary: a `DetailTable`
           STACKS its columns below `labelWidth + MIN_CONTROL_WIDTH + 24`, so the
           page's 150 would flip a 320 popover into stacked form grammar. 88 keeps
           the summary side-by-side, which is the whole point of a glance. */}
-      <PopoverContent style={{ width: 320 }} disableBodyScroll>
-        <View style={{ gap: 12 }}>
+      {/* `PopoverContent` PARTITIONS its children: a `PopoverHeader` sits above
+          the scroller, a `PopoverFooter` is pinned below it, and everything else
+          scrolls between them. This component used none of that — it disabled
+          the body scroll and hand-rolled both bands as ordinary children, which
+          is invisible at three facts and fatal at eleven: the panel ran past the
+          viewport with no way to scroll, carrying its own Save button off-screen
+          with it. The three-fact fixture is what hid it. */}
+      <PopoverContent style={{ width: 320, maxHeight: 420 }}>
+        <PopoverHeader>
           <DialogSectionHeadingTitle description={code}>{name}</DialogSectionHeadingTitle>
+        </PopoverHeader>
+        <View style={{ gap: 12 }}>
           {/* ONE geometry for both modes — the table's own 40px band, which is
               `CONTROL_HEIGHT` and exactly what `TextInputField` renders at. The
               read row therefore RESERVES the space its editor will need, and
@@ -305,15 +324,21 @@ export function ReferenceField(props: ReferenceFieldProps) {
                       editors, border and all, and reaching for it means the
                       alignment survives the control geometry changing. Copying
                       the box here instead would drift the first time it does. */}
-                  <InlineStatic
-                    /* A date's canonical value is its ISO string — that is what
-                       the picker reads and what Save sends — so the FORMATTING
-                       happens here, where the type is known. Handing the caller
-                       that job would make `value` mean two things (display in
-                       read, ISO in the draft) and the two would drift. */
-                    value={f.type === "date" ? formatDate(f.value, { locale: localeTag }) : f.value}
-                    multiline={f.multiline}
-                  />
+                  <View style={{ flex: 1, minWidth: 0, flexDirection: "row", alignItems: "center", gap: 6 }}>
+                    <View style={{ flex: 1, minWidth: 0 }}>
+                      <InlineStatic
+                        /* A date's canonical value is its ISO string — that is
+                           what the picker reads and what Save sends — so the
+                           FORMATTING happens here, where the type is known.
+                           Handing the caller that job would make `value` mean
+                           two things (display in read, ISO in the draft) and the
+                           two would drift. */
+                        value={f.type === "date" ? formatDate(f.value, { locale: localeTag }) : f.value}
+                        multiline={f.multiline}
+                      />
+                    </View>
+                    {f.action}
+                  </View>
                 </DetailRow>
               ),
             )}
@@ -339,15 +364,20 @@ export function ReferenceField(props: ReferenceFieldProps) {
               edit-only reference would otherwise draw a rule under the facts and
               fence off an empty band, which is chrome asserting a structure that
               is not there. */}
-          <Divider />
-          {/* THE DRAFT'S FOOTER REPLACES the peek's, it does not join it. Change
-              and Open are moves AWAY from an unsaved draft — one detaches the
-              record being edited, one navigates off it — so offering either here
-              would be offering to lose the typing. Cancel and Save are the only
-              two exits, which is also what the pinned popover promised. */}
+        </View>
+        {/* `PopoverFooter` — PINNED outside the scroller, and it owns the rule,
+            the full-bleed inset and the action-layout alignment this component
+            used to hand-roll. Hand-rolled, the verbs were a body child: they
+            scrolled away with the facts, so a long block hid its own Save.
+
+            THE DRAFT'S FOOTER REPLACES the peek's, it does not join it. Change
+            and Open are moves AWAY from an unsaved draft — one detaches the
+            record being edited, one navigates off it — so offering either here
+            would be offering to lose the typing. Cancel and Save are the only
+            two exits, which is also what the pinned popover promised. */}
+        <PopoverFooter align={editing ? "end" : "space-between"}>
           {editing ? (
-            <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
-              <View style={{ flex: 1 }} />
+            <>
               <Button title={t.cancel} color="secondary" disabled={saving} onPress={closeDraft} />
               {/* Disabled until something DIFFERS: with nothing to send, a save
                   is a write that fires the record's hooks and bumps its
@@ -358,52 +388,46 @@ export function ReferenceField(props: ReferenceFieldProps) {
                 disabled={!dirty || saving}
                 onPress={() => void save()}
               />
-            </View>
+            </>
           ) : (
-          <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
-            {/* LEFT PAIR acts on the LINK — which record this points at. Both
-                are unconditional: the peek always offers "point it elsewhere"
-                and "leave it empty", so its footer has ONE shape everywhere
-                instead of four depending on which callbacks a call site
-                remembered. */}
-            <Button
-              title={t.change}
-              color="secondary"
-              accessibilityLabel={`${t.change} — ${name}`}
-              onPress={() => { setPeekOpen(false); onChange(); }}
-            />
-            {/* No fill — Clear is the least-reached verb here, and the one whose
-                result the reader is least likely to want by accident, so it
-                carries the least weight of the four. */}
-            <Button
-              title={t.clear}
-              accessibilityLabel={`${t.clear} — ${name}`}
-              onPress={() => { setPeekOpen(false); onClear(); }}
-            />
-            {/* The spacer is the SEAM between what the two pairs touch: left the
-                link, right the record it points at. Without that split, Open's
-                position is just "pushed over". */}
-            <View style={{ flex: 1 }} />
-            {/* RIGHT PAIR acts on the RECORD the link points at — correct its
-                data, or go to it. Edit takes the ONE filled-dark rung because it
-                is the only verb here that leads to a commit, and it hands that
-                rung straight to Save when the draft opens: one primary per mode,
-                never two. Every other verb stays `secondary` and FILLED — a
-                fill-less Button shows no box, so its ink sits a padding inside
-                its own edge, and one boxless label in a row of boxes reads as
-                indented (the geometry that made `TextButton` exist). */}
-            {editable ? (
-              <Button title={t.edit} color="primary" accessibilityLabel={`${t.edit} — ${name}`} onPress={openDraft} />
-            ) : null}
-            {/* `openLabel` names the DESTINATION ("Open customer"): a page carries
-                four of these peeks, and four buttons announcing a bare "Open"
-                are four controls a screen reader cannot tell apart. */}
-            {onOpen ? (
-              <Button title={t.open} color="secondary" accessibilityLabel={openLabel} onPress={() => { setPeekOpen(false); onOpen(); }} />
-            ) : null}
-          </View>
+            <>
+              {/* LEFT acts on the LINK — which record this points at. Both are
+                  unconditional: the peek always offers "point it elsewhere" and
+                  "leave it empty", so its footer has ONE shape everywhere. */}
+              <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
+                <Button
+                  title={t.change}
+                  color="secondary"
+                  accessibilityLabel={`${t.change} — ${name}`}
+                  onPress={() => { setPeekOpen(false); onChange(); }}
+                />
+                {/* No fill — the least-reached verb here, and the one whose
+                    result the reader is least likely to want by accident. */}
+                <Button
+                  title={t.clear}
+                  accessibilityLabel={`${t.clear} — ${name}`}
+                  onPress={() => { setPeekOpen(false); onClear(); }}
+                />
+              </View>
+              {/* RIGHT acts on the RECORD the link points at. Edit takes the ONE
+                  filled-dark rung because it is the only verb here that leads to
+                  a commit, and it hands that rung straight to Save when the
+                  draft opens: one primary per mode, never two. */}
+              <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
+                {editable ? (
+                  <Button title={t.edit} color="primary" accessibilityLabel={`${t.edit} — ${name}`} onPress={openDraft} />
+                ) : null}
+                {/* `openLabel` names the DESTINATION ("Open customer"): a page
+                    carries four of these peeks, and four buttons announcing a
+                    bare "Open" are four controls a screen reader cannot tell
+                    apart. */}
+                {onOpen ? (
+                  <Button title={t.open} color="secondary" accessibilityLabel={openLabel} onPress={() => { setPeekOpen(false); onOpen(); }} />
+                ) : null}
+              </View>
+            </>
           )}
-        </View>
+        </PopoverFooter>
       </PopoverContent>
     </Popover>
   );

package/src/stepper.tsx

@@ -15,6 +15,7 @@ import { Icon } from "./icon";
 import { Text } from "./text";
 import { PressableHighlight } from "./pressable_highlight";
 import { AnimationFadeIn } from "./animation_fade_in";
+import { NODE, STEP_HEAD_TEXT_LINE, STEP_ROW_PAD, markerTopOffset } from "./stepper_layout";
 
 // A node's place in a sequence. `upcoming` = not reached (greyish); `current` =
 // where we are (ring + white centre, pulses when live); `done` = passed (filled);
@@ -64,6 +65,15 @@ export interface StepProps extends StepPositional {
    *  `active` washes the selected one (a panel can also sit beside it in vertical). */
   onPress?: () => void;
   active?: boolean;
+  /**
+   * VERTICAL only. Height of the content's FIRST ROW — the marker centres on it.
+   * Defaults to one line of `sm` text, which is what a step's first row is unless
+   * you put something taller on it. Pass `INLINE_CONTROL_HEIGHT` when the row
+   * carries an inline editor beside the label, or the marker centres on the text
+   * while the label centres in the taller row and reads low by half the
+   * difference. Ignored horizontally, where the marker sits above the label.
+   */
+  headHeight?: number;
   accessibilityLabel?: string;
 }
 
@@ -123,7 +133,7 @@ export function Stepper(props: StepperProps) {
 }
 
 export function Step(props: StepProps) {
-  const { status, children, onPress, active, accessibilityLabel, _last, _leftFilled, _rightFilled } = props;
+  const { status, children, onPress, active, headHeight = STEP_HEAD_TEXT_LINE, accessibilityLabel, _last, _leftFilled, _rightFilled } = props;
   const { orientation, color, live } = useContext(StepperContext);
   // Each step is one `listitem`, and the live one says so with `aria-current`.
   // It goes on the ITEM, not the label: "current" is a fact about this position
@@ -173,7 +183,7 @@ export function Step(props: StepProps) {
     <View {...item}>
       <AnimationFadeIn translateY={6}>
         <View style={styles.vItem}>
-          <View style={styles.vSpineCol}>
+          <View style={[styles.vSpineCol, { paddingTop: markerTopOffset(headHeight) }]}>
             <Marker status={status} color={color} live={live} />
             {!_last ? <View style={[styles.vSpine, { backgroundColor: reached(status) ? colors.zinc[300] : colors.zinc[200] }]} /> : null}
           </View>
@@ -244,8 +254,6 @@ function Pulse({ color }: { color: string }) {
   return <Animated.View style={[styles.pulse, { borderColor: color, transform, opacity }]} />;
 }
 
-const NODE = 18;
-
 const styles = StyleSheet.create({
   hRow: { flexDirection: "row" },
   hStep: { flex: 1, alignItems: "center", gap: 8 },
@@ -257,12 +265,12 @@ const styles = StyleSheet.create({
   hLabel: { alignItems: "center" },
 
   vItem: { flexDirection: "row", gap: 12 },
-  vSpineCol: { width: NODE, alignItems: "center", paddingTop: 3 },
+  vSpineCol: { width: NODE, alignItems: "center" },
   vSpine: { width: 1.5, flex: 1, minHeight: 14, borderRadius: 1, marginTop: 4 },
   vContent: { flex: 1 },
   vGap: { paddingBottom: 12 },
   vPress: { borderRadius: 8, marginHorizontal: -10 },
-  vRowBox: { borderRadius: 8, paddingHorizontal: 10, paddingVertical: 2 },
+  vRowBox: { borderRadius: 8, paddingHorizontal: 10, paddingVertical: STEP_ROW_PAD },
   vActive: { backgroundColor: colors.zinc[100] },
 
   discWrap: { width: NODE, height: NODE, alignItems: "center", justifyContent: "center" },

package/src/stepper_layout.ts

@@ -0,0 +1,38 @@
+/**
+ * Where a vertical `Step`'s marker sits against its content.
+ *
+ * The marker centres on the content's FIRST ROW — not on the content box, which
+ * can be many lines tall. That row is usually a line of text, but a dense stage
+ * puts a control on it (a date beside the milestone's name), and a control is
+ * twice a text line's height. Centring on the wrong one is a visible drift on
+ * every row of the ladder, so the offset is derived from the row's height rather
+ * than tuned to whatever the first caller happened to render.
+ *
+ * RN-free so the arithmetic is testable: `stepper.tsx` imports `react-native`,
+ * which Vitest cannot parse.
+ */
+
+/** The marker disc's diameter. */
+export const NODE = 18;
+
+/** `vRowBox`'s vertical padding — the gap above the content's first row. */
+export const STEP_ROW_PAD = 2;
+
+/**
+ * A single line of `Text size="sm"` on web (`text.css`), which is what a step's
+ * first row is unless it carries a control. NOT the native StyleSheet's 24: the
+ * kit renders on web, and the two scales disagree.
+ */
+export const STEP_HEAD_TEXT_LINE = 20;
+
+/**
+ * Top padding for the spine column so the marker's centre lands on the centre of
+ * a first row `headHeight` tall.
+ *
+ * Never negative: a row SHORTER than the marker would otherwise lift the disc
+ * above the content box and out of the step's own bounds, clipping it against
+ * whatever sits above.
+ */
+export function markerTopOffset(headHeight: number): number {
+  return Math.max(0, STEP_ROW_PAD + headHeight / 2 - NODE / 2);
+}