@lotics/ui 25.0.0 → 26.0.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
@@ -720,7 +735,10 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   just text. **`InlineSelect` is single OR multi** — pass `multi` for a tag SET (`value: T[]`,
   commits the new set on popover-CLOSE; selected tags render as badges via `renderSelected`),
   mirroring `Select`'s `multi` axis; there is NO separate tag component. Both modes take
-  `allowCustom` (a create-a-tag/option row) + `searchable`. **`InlineMemberSelect` takes `avatarOnly`**
+  `allowCustom` (a create-a-tag/option row) + `searchable`, plus **`autoFocus`** to open the list
+  on mount — for the picker a `ReferenceField`'s `Change` just dropped the reader into, so the
+  correction stays one gesture; leave it off for a field that is merely empty, since stealing the
+  list open on load is a different act. **`InlineMemberSelect` takes `avatarOnly`**
   — the resting display is the bare AVATAR (no name/chevron, a dashed "add" ghost when unset) for a
   DENSE row where the name won't fit (a task-row assignee); the dropdown rows still show avatar + name.
   `InlineDatePicker` takes a **`tone`**
@@ -858,7 +876,10 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `.save` / `.saving` / `.cancel`), while `openLabel` stays a prop because it names the
   DESTINATION for a screen reader, which only the caller knows. **EDIT IN THE PEEK** (`onSave`):
   a fact carrying a `name` is editable and that key is what it saves under (omit `name` for a
-  derived value that rides along read-only); `multiline` for an address or an account block.
+  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.
   `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
@@ -1169,6 +1190,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.
@@ -1179,6 +1206,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

@@ -127,16 +127,19 @@ interface Customer {
   /** Runs past one line at a peek's width — the case a fixture of short values
    *  never exercises, and the one where a read value and its editor diverge. */
   address: string;
+  /** ISO. A date fact, so the peek's draft has one non-text editor to render —
+   *  left as text it would take whatever shape the reader typed. */
+  since: string;
 }
 
 // Atlas ships WITHOUT a tax ID — attach it to see the billing gate + the
 // inline Tax ID fix-up in the Customer section.
 const KNOWN_CUSTOMERS: Customer[] = [
-  { id: "cus_01", name: "Northwind Traders", code: "KH-0148", taxId: "0312456780", contact: "Mara Lindqvist", city: "Gothenburg", address: "Ringvägen 118, 4 tr, 116 61 Stockholm, Sweden" },
-  { id: "cus_02", name: "Harbor Freight Lines", code: "KH-0203", taxId: "0312998820", contact: "Diego Alvarez", city: "Rotterdam", address: "Waalhaven Oostzijde 81, 3087 BM Rotterdam, Netherlands" },
-  { id: "cus_03", name: "Summit Packaging Co.", code: "KH-0231", taxId: "0301557742", contact: "Priya Nair", city: "Singapore", address: "9 Tuas Bay Walk, #03-14, Singapore 637803" },
-  { id: "cus_04", name: "Atlas Distribution", code: "KH-0117", taxId: "", contact: "Tom Becker", city: "Hamburg", address: "Grosser Grasbrook 9, 20457 Hamburg, Germany" },
-  { id: "cus_05", name: "Bluewater Logistics", code: "KH-0294", taxId: "0312004455", contact: "Lena Fischer", city: "Antwerp", address: "Noorderlaan 127, 2030 Antwerpen, Belgium" },
+  { id: "cus_01", name: "Northwind Traders", code: "KH-0148", taxId: "0312456780", contact: "Mara Lindqvist", city: "Gothenburg", address: "Ringvägen 118, 4 tr, 116 61 Stockholm, Sweden", since: "2019-03-14" },
+  { id: "cus_02", name: "Harbor Freight Lines", code: "KH-0203", taxId: "0312998820", contact: "Diego Alvarez", city: "Rotterdam", address: "Waalhaven Oostzijde 81, 3087 BM Rotterdam, Netherlands", since: "2021-11-02" },
+  { id: "cus_03", name: "Summit Packaging Co.", code: "KH-0231", taxId: "0301557742", contact: "Priya Nair", city: "Singapore", address: "9 Tuas Bay Walk, #03-14, Singapore 637803", since: "2023-06-19" },
+  { id: "cus_04", name: "Atlas Distribution", code: "KH-0117", taxId: "", contact: "Tom Becker", city: "Hamburg", address: "Grosser Grasbrook 9, 20457 Hamburg, Germany", since: "2018-01-30" },
+  { id: "cus_05", name: "Bluewater Logistics", code: "KH-0294", taxId: "0312004455", contact: "Lena Fischer", city: "Antwerp", address: "Noorderlaan 127, 2030 Antwerpen, Belgium", since: "2022-09-08" },
 ];
 
 const TAX_ID_RE = /^\d{10}(\d{3})?$/;
@@ -736,6 +739,7 @@ function PartyRow({ role, rec, options, placeholder, onPick, onOpen, onUnset, on
             { label: "City", value: rec.city, name: "city" },
             { label: "Tax ID", value: rec.taxId, name: "taxId" },
             { label: "Address", value: rec.address, name: "address", multiline: true },
+            { label: "Customer since", value: rec.since, name: "since", type: "date" },
           ]}
           accessibilityLabel={`${rec.name} — details`}
           openLabel={`Open ${rec.name}`}
@@ -899,6 +903,7 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418" }: { chrome?:
               city: patch.city ?? c.city,
               taxId: patch.taxId ?? c.taxId,
               address: patch.address ?? c.address,
+              since: patch.since ?? c.since,
             }
           : c,
       ),
@@ -1241,6 +1246,7 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418" }: { chrome?:
       // Not collected at create — a new party is attached from three fields and
       // the rest is filled in later, which is what the peek's Edit is for.
       address: "",
+      since: "",
     };
     setCustomers((prev) => [...prev, c]);
     setCustomerId(c.id);
@@ -1714,6 +1720,7 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418" }: { chrome?:
                         { label: "Contact", value: customer.contact, name: "contact" },
                         { label: "City", value: customer.city, name: "city" },
                         { label: "Address", value: customer.address, name: "address", multiline: true },
+                        { label: "Customer since", value: customer.since, name: "since", type: "date" },
                       ]}
                       accessibilityLabel={`${customer.name} — details`}
                       /* NO `onOpen`. The peek carries every fact this record
@@ -2023,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}
@@ -2065,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>
 
@@ -2323,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={[
@@ -2331,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) => {
@@ -2450,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.0.0",
+  "version": "26.0.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/inline_select.tsx

@@ -13,6 +13,16 @@ import { useLoticsLocale } from "./locale";
 
 interface InlineSelectBaseProps<T extends string, D = unknown> {
   options: PickerOption<T, D>[];
+  /**
+   * Open the list on mount.
+   *
+   * For a picker that REPLACED something the reader just dismissed — a
+   * `ReferenceField` whose `onChange` fired, which means "wrong one, I'm about
+   * to pick another". Landing them on a closed picker charges a second press to
+   * resume a correction they already started. Leave it off for a field that is
+   * merely empty: stealing the list open on load is not the same act.
+   */
+  autoFocus?: boolean;
   /** Custom option content in the dropdown (icon + label, two-line, a badge…).
    *  Omit for a plain label list — both render through the same `OptionList`. */
   renderOptionContent?: (option: PickerOption<T, D>) => ReactNode;
@@ -119,9 +129,9 @@ function InlineSelectShell(props: {
 }
 
 export function InlineSelect<T extends string, D = unknown>(props: InlineSelectProps<T, D>) {
-  const { options, renderOptionContent, renderSelected, placeholder, disabled, accessibilityLabel, searchable = false, allowCustom = false, customOptionLabel, variant, actions } = props;
+  const { options, renderOptionContent, renderSelected, placeholder, disabled, accessibilityLabel, searchable = false, allowCustom = false, customOptionLabel, variant, actions, autoFocus = false } = props;
   const labels = useLoticsLocale().inline;
-  const [open, setOpen] = useState(false);
+  const [open, setOpen] = useState(autoFocus);
   const [saving, setSaving] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const [draft, setDraft] = useState<T[]>(props.multi ? props.value : []);

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,7 +1,9 @@
 import { useRef, useState } 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";
@@ -10,7 +12,7 @@ import { DialogSectionHeadingTitle } from "./section_heading";
 import { Text } from "./text";
 import { TextInputField } from "./text_input_field";
 import { TextLink } from "./text_link";
-import { useLoticsLocale } from "./locale";
+import { useLocaleTag, useLoticsLocale } from "./locale";
 
 /**
  * A REFERENCE to another record, rendered as a FIELD VALUE.
@@ -73,6 +75,17 @@ export interface ReferenceFact {
   name?: string;
   /** A value that runs past one line — an address, a bank account block. */
   multiline?: boolean;
+  /**
+   * What the draft edits this fact WITH. `text` (default) is a text input;
+   * `date` is the kit's `DatePicker`, and the value is its ISO string.
+   *
+   * A date is not a short string that happens to look like one. Left as text it
+   * takes any shape the reader types, and the field it saves into accepts one —
+   * so the format ambiguity is only discovered by whatever reads the record
+   * next, which is exactly the kind of wrong a draft is supposed to catch at
+   * the input.
+   */
+  type?: "text" | "date";
 }
 
 export interface ReferenceFieldProps {
@@ -130,6 +143,9 @@ export function ReferenceField(props: ReferenceFieldProps) {
   // The peek's verbs are the component's OWN chrome, so they come from the
   // pack — hardcoding them shipped "Open"/"Remove" into every localized app.
   const t = useLoticsLocale().referenceField;
+  // The tag a date control renders in — `vi` yields dd/MM/yyyy with no per-
+  // instance prop, which is the same resolution `DatePicker` does internally.
+  const localeTag = useLocaleTag();
   const anchor = useRef<View>(null);
   const [peekOpen, setPeekOpen] = useState(false);
   const [draft, setDraft] = useState<Record<string, string> | null>(null);
@@ -263,14 +279,22 @@ export function ReferenceField(props: ReferenceFieldProps) {
             {facts.map((f) =>
               editing && f.name != null ? (
                 <DetailRow key={f.label} label={f.label}>
-                  <TextInputField
-                    value={draft[f.name] ?? ""}
-                    onChangeText={(v) => setDraft({ ...draft, [f.name as string]: v })}
-                    multiline={f.multiline}
-                    autoGrow={f.multiline}
-                    disabled={saving}
-                    accessibilityLabel={f.label}
-                  />
+                  {f.type === "date" ? (
+                    <DatePicker
+                      value={draft[f.name] || null}
+                      onValueChange={(v) => setDraft({ ...draft, [f.name as string]: v })}
+                      disabled={saving}
+                    />
+                  ) : (
+                    <TextInputField
+                      value={draft[f.name] ?? ""}
+                      onChangeText={(v) => setDraft({ ...draft, [f.name as string]: v })}
+                      multiline={f.multiline}
+                      autoGrow={f.multiline}
+                      disabled={saving}
+                      accessibilityLabel={f.label}
+                    />
+                  )}
                 </DetailRow>
               ) : (
                 <DetailRow key={f.label} label={f.label}>
@@ -281,7 +305,15 @@ 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 value={f.value} multiline={f.multiline} />
+                  <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}
+                  />
                 </DetailRow>
               ),
             )}

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);
+}