@lotics/ui 27.6.0 → 27.8.0

package/docs/catalog.md

@@ -340,7 +340,12 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`text_utils`** — text/typography plumbing: `getTextColor` (the TextColor→hex map incl.
   the AA-cleared valence set), the Inter `fontFamily*` stacks, and `getInputTextStyle` /
   `getInputLineHeight` — the 16px-mobile/14px-desktop input contract that stops Safari iOS
-  auto-zoom; only for hand-rolled raw inputs.
+  auto-zoom; only for hand-rolled raw inputs. It carries the **ink** as well as the size,
+  because omitting `color` on a native `<input>` does not inherit — it falls to the UA
+  default, pure black, against the `zinc-900` every resting value beside it uses. A field
+  whose text darkens the instant it is focused reads as the text MOVING (at 14px a darkness
+  change re-weights every stroke's antialiasing), which is a bug no box measurement can
+  see. Hand-rolling a raw input means taking this style, not just its font size.
 
 ### Theming, locale & tokens
 
@@ -715,7 +720,7 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   EVERY `Inline*` editor takes it. `trailing` is decoration only (a chevron, a spinner): it
   renders INSIDE the press target, so a button there would be a button in a button.
   With `actions` the field renders through ONE shell that owns the surface in BOTH modes — so
-  the verbs never move when the editor swaps to its input, the control inside goes `seamless`
+  the verbs never move when the editor opens, the control inside goes `seamless`
   (drawing no second box), hover is tracked on the box (react-native-web hands a parent's hover
   to the innermost pressable, so a control-tracked border drops out as the pointer crosses a
   verb), and the focus ring paints on the whole FIELD via focus-within, not on the value region.
@@ -877,7 +882,13 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`reference_field`** — `ReferenceField`: a reference to ANOTHER RECORD, rendered as a
   FIELD VALUE — the kit's inline-editor surface (so a pointer sits in the value column
   like the editors above and below it), whose press opens a PEEK of that record's facts.
-  `name` + optional `code` + `facts`, plus the verb callbacks below. The verbs live INSIDE the
+  `name` + optional `code` + `facts`, plus the verb callbacks below. The peek takes THE FIELD'S
+  WIDTH (`inheritTriggerWidth`, as `InlineSelect` does), floored at `MIN_CONTROL_WIDTH` — a
+  panel narrower than the control that opened it reads as belonging to something else. So the
+  field truncates its name to one line and the peek's header WRAPS the whole of it: the column
+  stays scannable, the full value is one press away. Between the floor and `labelWidth +
+  MIN_CONTROL_WIDTH + 24` a `DetailTable` stacks, which is the right grammar at that width.
+  The verbs live INSIDE the
   peek, never on the field, and they are ALL `Button`s at one altitude — a peek is
   dialog-scale and a dialog's verbs are buttons, so mixing weights only made the reader rank
   four acts that are four acts. The row splits by WHAT EACH TOUCHES, and the spacer is that

package/docs/data_entry.md

@@ -46,8 +46,20 @@ narrow containers. A right-floated button aligns to nothing; only OVERLAY footer
 When the whole record is editable (a detail/record screen, dense settings), don't wrap it in a
 form mode or a preview↔edit card — make each VALUE inline-editable: it reads as a value on a quiet
 chip, hover reveals the input-family border (no extra grey wash, no pencil icon that shifts
-layout), click OR keyboard focus swaps the input in **at the same height** (zero reflow, the whole
-point), and it commits on blur (Enter saves, Escape reverts) or via `controls="buttons"` (✓ / ✕).
+layout), click OR keyboard focus opens it for editing **with nothing moving** (zero reflow, the
+whole point), and it commits on blur (Enter saves, Escape reverts) or via `controls="buttons"`
+(✓ / ✕).
+
+**How "nothing moves" is achieved differs by editor, and the difference is a rule.** A field whose
+resting value is the RAW string (`InlineTextInput`) is ONE `<input>` in both states — it never
+swaps elements, and `editing` is a style state driven by focus. Two elements cannot be made to
+draw the same string identically: matching the padding, the border and the ink still leaves an
+`<input>` centring by FONT METRICS where a `<div>` positions by LINE BOX, a quarter-CSS-pixel
+residual that no property closes, is invisible to `getBoundingClientRect` (it reports the rounded
+box), and lands on a real device pixel at fractional scaling. Where the resting display is
+FORMATTED and the editor shows something else (`1,250 kg` → `1250`, `31/07/2026` → a segmented
+field), the string changes anyway, so those editors do swap and should. **The rule for a new
+editor: same string in both states ⇒ one element; different string ⇒ swap.**
 
 **Commit-on-blur would race the press that caused it — the kit closes that race for you.**
 Pressing an action while an inline field is focused starts TWO things in ONE gesture: the
@@ -77,15 +89,16 @@ dialog save, a debounced autosave).
 ### Keyboard entry — type → Tab → type
 
 Bulk entry never needs the mouse. KEYBOARD focus (Tab / Shift+Tab) landing on a closed
-input-swap editor — `InlineTextInput`, `InlineNumberInput`, `InlineTimePicker`,
-`InlineDatePicker` — opens edit mode immediately with the input focused; commit-on-blur then
-makes Tab itself the commit, so the chain is type → Tab → type with the next editor already
-open. Pointer focus never auto-opens (mousedown records "pointer" modality before focus fires
-— `interaction_modality.ts`), so the click path is exactly what it always was. When a
-**keyboard** close (Enter/Escape) leaves focus on `<body>`, the editor returns focus to its
-resting view so the next Tab continues from the field. A **pointer** close (click ✓/✕, or
-click away onto non-focusable space) does NOT restore — a mouse user has no next Tab to
-preserve, and a bare `.focus()` would scroll the target into view, jerking the page (the
+SWAP editor — `InlineNumberInput`, `InlineTimePicker`, `InlineDatePicker` — opens edit mode
+immediately with the input focused; commit-on-blur then makes Tab itself the commit, so the chain
+is type → Tab → type with the next editor already open. Pointer focus never auto-opens (mousedown
+records "pointer" modality before focus fires — `interaction_modality.ts`), so the click path is
+exactly what it always was. `InlineTextInput` needs none of this — its input is always mounted, so
+focus IS the edit by either route. When a **keyboard** close (Enter/Escape) leaves focus on
+`<body>`, a swap editor returns focus to its resting view so the next Tab continues from the
+field (the always-mounted one never loses focus, so there is nothing to restore). A **pointer**
+close (click ✓/✕, or click away onto non-focusable space) does NOT restore — a mouse user has no
+next Tab to preserve, and a bare `.focus()` would scroll the target into view, jerking the page (the
 restore is gated on modality via `shouldRestoreFocusOnClose`).
 
 **Typed dates.** `InlineDatePicker`'s keyboard mode is an internal segmented date field
@@ -131,10 +144,14 @@ One per type:
   a multi `OptionList` (checkbox rows), CLOSING commits the new set in one `onSave` — never a borderless `Select` posing as an inline
   field.
 
-They split across two shared shells. The same-height **input-swap** editors (`InlineTextInput`,
+They split across two shared shells. The same-height **typed** editors (`InlineTextInput`,
 `InlineNumberInput`, `InlineTimePicker`) render **`InlineEditFrame`** driven by the
-**`useInlineEdit`** hook (the view⇄edit toggle, draft buffer, and async save) — swap a custom
-input into that pair to join the family. The **popover** editors (`InlineSelect`,
+**`useInlineEdit`** hook (the draft buffer, async save, and — for the two that swap — the view⇄edit
+toggle) — pass a custom input to that pair to join the family. On the frame, **`editing` means an
+input is MOUNTED** (which element renders, and whether the surface drops its resting padding to
+host one); an always-mounted editor passes it constant and passes the real state as **`editOpen`**,
+which the ✓/✕ verbs read — they assert "there is an edit to accept or reject", so on a resting
+field they would be both a false claim and dead buttons. The **popover** editors (`InlineSelect`,
 `InlineMemberSelect`, `InlineDatePicker`) instead compose **`InlineEditView`**
 (the resting box, wired as the popover trigger) with their OWN `useState` for open/draft/saving/
 error — a pick, not a keystroke, is the edit, so `useInlineEdit` doesn't fit. `onSave` is async

package/examples/tpl_record.tsx

@@ -136,7 +136,11 @@ interface Customer {
 // 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", 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" },
+  // DELIBERATELY too long for one line. A register of tidy two-word names cannot
+  // show what a reference does when it does not fit — which is truncate in the
+  // field and wrap in the peek — so the one fixture the template opens with is the
+  // realistic worst case. Real customer names look like this.
+  { id: "cus_02", name: "Harbor Freight Lines & Coastal Forwarding Group", 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" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "27.6.0",
+  "version": "27.8.0",
   "type": "module",
   "exports": {
     "./vite": {

package/src/inline_edit.tsx

@@ -34,7 +34,7 @@ export function useInlineEdit<T>(opts: {
   const { value, onSave, equals } = opts;
   const labels = useLoticsLocale().inline;
   const [editing, setEditing] = useState(false);
-  const [draft, setDraft] = useState<T>(value);
+  const [draft, setDraftState] = useState<T>(value);
   const [saving, setSaving] = useState(false);
   const [error, setError] = useState<string | null>(null);
   // Synchronous mirror of `editing`. The first exit (commit or cancel) flips it
@@ -42,8 +42,23 @@ export function useInlineEdit<T>(opts: {
   // input — is then a no-op, so the field commits/cancels exactly once.
   const active = useRef(false);
 
+  // A keystroke IS an edit, so writing the draft re-arms the field. `editing` and
+  // `draft` must never disagree: with `editing` false the field renders the STORED
+  // value, so the keystroke is swallowed AND the trailing blur no-ops — the user
+  // types into a dead field and the text is gone. That state was unreachable while
+  // an editor mounted on demand (Escape unmounted the input, so there was nothing
+  // left to type into); it exists the moment one stays mounted, which
+  // `InlineTextInput` now does — Escape reverts and keeps the caret. Re-arming
+  // cannot double-commit: the exactly-once guard exists to swallow the blur that
+  // TRAILS an exit, and a keystroke after that exit is a new edit that must save.
+  const setDraft = useCallback((next: T) => {
+    active.current = true;
+    setEditing(true);
+    setDraftState(next);
+  }, []);
+
   const begin = useCallback(() => {
-    setDraft(value);
+    setDraftState(value);
     setError(null);
     active.current = true;
     setEditing(true);
@@ -139,7 +154,19 @@ export function useInlineEditFocusRestore(editing: boolean, restore: () => void)
 export type InlineEditVariant = "framed" | "bare";
 
 interface InlineEditFrameProps {
+  /** An input is MOUNTED inside the frame — which element to render, and whether
+   *  the surface drops its resting padding to host one. For an editor that swaps
+   *  this is the same thing as "an edit is open", which is why it was one flag. */
   editing: boolean;
+  /**
+   * Whether an edit is actually OPEN, for an editor where that differs from
+   * `editing` — `InlineTextInput` mounts its input at REST, so it passes
+   * `editing` constant. Only the ✓/✕ verbs read this: they say "there is an edit
+   * to accept or reject", so on a resting field they are a false claim AND dead
+   * (`commit`/`cancel` both no-op with nothing active). Defaults to `editing`,
+   * which is the truth for every editor whose input arrives with the edit.
+   */
+  editOpen?: boolean;
   /** The formatted current value, shown in view mode. Empty → placeholder. */
   display: string;
   placeholder?: string;
@@ -467,6 +494,7 @@ export function InlineEditFrame(props: InlineEditFrameProps) {
   const labels = useLoticsLocale().inline;
   const {
     editing,
+    editOpen,
     display,
     placeholder,
     onBegin,
@@ -582,7 +610,7 @@ export function InlineEditFrame(props: InlineEditFrameProps) {
           ) : null}
         </View>
         )}
-        {controls === "buttons" ? (
+        {controls === "buttons" && (editOpen ?? editing) ? (
           <View style={styles.buttons}>
             <IconButton icon="check" color="primary" size="sm" tooltip={labels.save} onPress={onCommit} disabled={saving} />
             <IconButton icon="x" color="secondary" size="sm" tooltip={labels.cancel} onPress={onCancel} disabled={saving} />

package/src/inline_text_input.tsx

@@ -1,5 +1,6 @@
 import { useCallback, type ReactNode } from "react";
 import type { NativeSyntheticEvent, TextInputKeyPressEventData } from "react-native";
+import { colors } from "./colors";
 import { TextInputField } from "./text_input_field";
 import { type InlineEditVariant, InlineEditFrame, useInlineEdit, type InlineEditControls } from "./inline_edit";
 
@@ -13,15 +14,16 @@ export interface InlineTextInputProps {
    *  an explicit ✓ saves and ✕ reverts. */
   controls?: InlineEditControls;
   disabled?: boolean;
-  /** Strike + mute the resting value (a completed item that stays editable). */
+  /** Strike + mute the value (a completed item that stays editable). It stays
+   *  struck while being edited — the field is one element, so a treatment that
+   *  dropped on focus would be exactly the jump this control exists to avoid. */
   struck?: boolean;
   /** How much frame shows at rest — see {@link InlineEditVariant}. Default "framed". */
   variant?: InlineEditVariant;
   /**
    * Line budget for a value a reader has to read WHOLE rather than recognise —
    * a payment term, an address, a clause. Default 1 (the single-line field).
-   * Above 1 the resting value wraps to that many lines AND the editor opens
-   * multiline at the same height, so the row does not reflow on click. Enter
+   * Above 1 the field is that many lines tall and wraps, in both states. Enter
    * then inserts a newline; the field commits on blur (or the ✓ in "buttons").
    */
   numberOfLines?: number;
@@ -34,10 +36,14 @@ export interface InlineTextInputProps {
 }
 
 /**
- * An inline-editable single-line text value: reads as plain text, reveals an
- * edit affordance on hover, and swaps in-place to a text input on click — at the
- * same height, so the form never reflows. The preferred control for editing a
+ * An inline-editable single-line text value: reads as plain text, darkens on
+ * hover, and opens for editing on focus. The preferred control for editing a
  * value in a dense record / detail surface.
+ *
+ * It is ONE `<input>` in both states — never a resting view swapped for an
+ * editor — so nothing about the value can move when it is focused. See the
+ * comment on `editing` below for why that is load-bearing rather than an
+ * implementation detail.
  */
 export function InlineTextInput(props: InlineTextInputProps) {
   const { value, onSave, placeholder, controls = "blur", disabled, struck, accessibilityLabel , variant, actions, numberOfLines } = props;
@@ -64,7 +70,33 @@ export function InlineTextInput(props: InlineTextInputProps) {
 
   return (
     <InlineEditFrame
-      editing={edit.editing}
+      // ALWAYS the input — this editor never swaps elements, and `editing` is a
+      // STYLE state (focus) rather than a mount.
+      //
+      // The swap was the bug. A resting `Text` and an `<input>` must render the
+      // same string identically, and nothing enforces it: the padding drifted
+      // (8px), then the transparent border (1px), then the ink (zinc-900 vs the
+      // UA's black) — each fixed in turn, each revealing the next. The last one
+      // cannot be fixed at all: measured on an interior 4x crop with no border or
+      // ring in frame, the glyph mass sits 1 DEVICE pixel lower while editing
+      // (row centroid 12.985 -> 13.985, identical ink, identical column
+      // centroid). Both paths compute a 10px text top, so it is not a padding
+      // mistake — an `<input>` centres its text by FONT METRICS and a `<div>`
+      // positions it by LINE BOX, and the residual is a quarter of a CSS pixel.
+      // No amount of matching properties closes it; only rendering one element
+      // does. Hence: one element.
+      //
+      // Scope is this editor alone. Number, date and time keep the swap, because
+      // their resting display is FORMATTED (`1,250 kg`, `31/07/2026`) and their
+      // editor shows something else entirely — the string changes, so a quarter
+      // pixel is not perceptible and an always-input would buy nothing while
+      // costing reformat-on-blur inside a field the user is typing in.
+      editing
+      // ...but the ✓/✕ verbs still key off a REAL edit. `editing` above is a
+      // mount decision now, and the verbs are not: at rest there is nothing to
+      // accept and nothing to revert, so rendering them would both claim
+      // otherwise and hand the user two buttons that no-op.
+      editOpen={edit.editing}
       display={value}
       placeholder={placeholder}
       onBegin={edit.begin}
@@ -81,15 +113,44 @@ export function InlineTextInput(props: InlineTextInputProps) {
       actions={actions}
     >
       <TextInputField
-        value={edit.draft}
+        // The DRAFT only exists once editing has begun; before that the field
+        // must show the record's value, or an external update would be masked by
+        // a stale draft from the last edit (`begin` is what syncs them).
+        value={edit.editing ? edit.draft : value}
         onChangeText={edit.setDraft}
+        // Focus IS begin. There is no press-to-open any more: the element the
+        // user clicks is already the editor, so the gesture that used to mount it
+        // now just opens a draft on it. This is also why `autoFocus` is GONE —
+        // mounted permanently, it would have every text field on a record fight
+        // for focus on load.
+        onFocus={edit.begin}
         onBlur={onBlur}
         onKeyPress={onKeyPress}
-        autoFocus
         multiline={multiline}
         numberOfLines={numberOfLines}
         placeholder={placeholder}
         accessibilityLabel={accessibilityLabel}
+        // `disabled`, NOT `editable`: TextInputField derives editability as
+        // `!disabled || editable`, so passing `editable` alone can never turn it
+        // OFF. With the resting button gone, this is the only thing standing
+        // between a read-only field and a typable one.
+        disabled={disabled}
+        // Everything the resting VIEW used to draw, the input now draws, because
+        // there is no resting view left to draw it. Both of these were its job:
+        //
+        // `bare` — the transparent resting edge. Hover and the focus ring are
+        // applied after `style` inside `TextInputField`, so it still darkens on
+        // hover and still rings on focus, from the element that now owns it.
+        //
+        // `struck` — a completed item's value, line-through and muted. This was
+        // applied in `fieldContent`, which only ever runs in the resting view, so
+        // moving to one element silently dropped it: a done task on the board kept
+        // its title upright. Anything else the view used to render has to move the
+        // same way, or it goes the same way — quietly.
+        style={[
+          variant === "bare" ? { borderColor: "transparent", backgroundColor: "transparent" } : null,
+          struck ? { textDecorationLine: "line-through" as const, color: colors.zinc[500] } : null,
+        ]}
         // With verbs on the field, the FRAME owns the surface and the ring.
         seamless={actions != null}
       />

package/src/reference_field.tsx

@@ -220,6 +220,7 @@ export function ReferenceField(props: ReferenceFieldProps) {
       triggerRef={anchor}
       side="bottom"
       align="start"
+      inheritTriggerWidth
     >
       {/* THE KIT'S FIELD, not a lookalike. This was hand-rolled — a Pressable
           wearing copies of the field's border, radius, height and hover — and it
@@ -261,12 +262,24 @@ export function ReferenceField(props: ReferenceFieldProps) {
           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
           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. */}
+          the last fact.
+
+          WIDTH COMES FROM THE FIELD (`inheritTriggerWidth`), not a constant. A
+          fixed 320 was "every peek in an app is the same object", and the object
+          it was actually the same as was nothing on screen: measured on a record
+          page, a 558px field opened a 320px panel left-aligned under it, stopping
+          238px short of the edge the reader's eye had just travelled to. A
+          popover narrower than the control that opened it reads as belonging to
+          something else. `InlineSelect` — the same shape, an inline field opening
+          a `triggerRef` popover — already inherits its field's width, so the two
+          were following different rules for one job.
+
+          The prop is floored at `MIN_CONTROL_WIDTH`, so a reference in a dense
+          grid column still opens something readable rather than a 90px sliver.
+          Between that floor and `labelWidth + MIN_CONTROL_WIDTH + 24` a
+          `DetailTable` STACKS its columns, which is the right answer at that
+          width, not a failure — 88 keeps the side-by-side grammar wherever there
+          is room for it, which is the whole point of a glance. */}
       {/* `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
@@ -274,11 +287,12 @@ export function ReferenceField(props: ReferenceFieldProps) {
           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. */}
-      {/* `width` on the PANEL, not `style` — `style` reaches only the body, so a
-          long referenced name in the header stretched the panel past it and the
-          facts sat in a box wider than themselves. `maxHeight` stays on the
-          body: that is the band that scrolls. */}
-      <PopoverContent width={320} style={{ maxHeight: 420 }}>
+      {/* No `width` here at all now: a fixed panel width is applied LAST in the
+          style chain, so it beats `inheritTriggerWidth` — passing both would have
+          silently kept the 320. `maxHeight` stays on the body, which is the band
+          that scrolls; the header keeps its own height so a wrapped two-line name
+          is never what scrolls out of view. */}
+      <PopoverContent style={{ maxHeight: 420 }}>
         <PopoverHeader>
           <DialogSectionHeadingTitle description={code}>{name}</DialogSectionHeadingTitle>
         </PopoverHeader>

package/src/text_input_field.tsx

@@ -256,7 +256,14 @@ const styles = StyleSheet.create({
   // padding stay (they hold the field's size); the horizontal padding goes,
   // because the host already spent CONTROL_TEXT_INSET and two insets stacked
   // shift the text 8px right the moment the field focuses.
-  seamless: { borderColor: "transparent", backgroundColor: "transparent", paddingHorizontal: 0 },
+  //
+  // `borderWidth: 0`, not merely a transparent colour. A transparent border still
+  // OCCUPIES its 1px in the box model, so hiding the colour left the second inset
+  // in place at 1/8th the size: measured, the text moved 561 → 562 on focus — the
+  // same defect this style exists to fix, at the scale that survives a glance.
+  // Safe for height because the box is `border-box`: dropping the border changes
+  // the content box, never the field's 40px outer size.
+  seamless: { borderColor: "transparent", borderWidth: 0, backgroundColor: "transparent", paddingHorizontal: 0 },
   disabled: {
     color: colors.zinc["400"],
     outlineStyle: "none" as unknown as "solid",

package/src/text_utils.ts

@@ -73,6 +73,25 @@ export const INPUT_LINE_HEIGHT_DESKTOP = 20;
 export const inputTextStyleWeb = {
   fontSize: "var(--input-font-size)",
   lineHeight: "var(--input-line-height)",
+  // THE INK IS PART OF THE CONTRACT, because leaving it out does not mean
+  // "inherit" — a native <input> ignores inherited colour and falls to the UA
+  // default, PURE BLACK, while every resting value beside it renders `zinc-900`.
+  // So a field's own text changed colour the instant it was focused: measured
+  // rgb(24,24,27) at rest against rgb(0,0,0) editing, on an unremarkable text
+  // field. Nothing moved — which is why box geometry, insets, line boxes, fonts
+  // and five widths all measured identical — but at 14px a darkness change
+  // re-weights the antialiasing of every stroke, and the eye reads that as the
+  // text shifting on focus. An EMPTY field hid it completely, since a placeholder
+  // sets its own colour and therefore never changed.
+  //
+  // It lives here rather than in one component because six inputs share this
+  // contract, and an ink re-picked per input is the drift that produced the bug.
+  // `getTextColor()` for the same reason — the default ink has ONE definition and
+  // an input is not the place to restate it. This is a DEFAULT, not a lock: every
+  // consumer applies the caller's `style` after this one, so an app that wants a
+  // different ink still sets it. (It is not the brand accent either way — the theme
+  // is deliberately accent-only, and body ink is not themed.)
+  color: getTextColor(),
 };
 
 /**
@@ -90,6 +109,8 @@ export const inputTextStyleRN = inputTextStyleWeb as unknown as TextStyle;
 const inputTextStyleNative: TextStyle = {
   fontSize: 14,
   lineHeight: 20,
+  // Same ink as the web contract above — an input's text is body ink, not black.
+  color: getTextColor(),
 };
 
 /**