@lotics/ui 47.4.1 → 47.5.1

package/AGENTS.md

@@ -14,11 +14,11 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 
 | Doc | Read it for |
 |---|---|
-| [docs/catalog.md](./docs/catalog.md) | **The complete inventory** — Reach-by-role (each data role → the ONE canonical component) + every `@lotics/ui/<module>` entry point (incl. `@lotics/ui/vite`'s `loticsOptimizeDeps` + `loticsResolve()` — the pre-bundle list and the whole `resolve` block a custom-code app's `vite.config.ts` imports rather than hand-carries, dev-link included). Read before building any screen; reuse first. |
+| [docs/catalog.md](./docs/catalog.md) | **The complete inventory** — incl. `just_arrived` (`useJustArrived` + `TableRow`'s `justArrived`: the one-shot wash a row wears when it LANDS, so a realtime push is visible rather than one row of two hundred silently changing) — Reach-by-role (each data role → the ONE canonical component) + every `@lotics/ui/<module>` entry point (incl. `@lotics/ui/vite`'s `loticsOptimizeDeps` + `loticsResolve()` — the pre-bundle list and the whole `resolve` block a custom-code app's `vite.config.ts` imports rather than hand-carries, dev-link included). Read before building any screen; reuse first. |
 | [docs/data_entry.md](./docs/data_entry.md) | Which editing pattern for which job — inline edit, fieldset forms, choosing a CHOICE control by option count, find-or-create (`Combobox`), line items, handoffs, phased records, billing, tags, dispositions, attachments (`InlineFiles` for a record ROW, the `FilesEditor` COMPOUND for a whole section, plus the three-way file INTAKE), stage gates, and the commit-on-blur vs action-press ordering law. |
 | [docs/ai_patterns.md](./docs/ai_patterns.md) | AI acts, the human stays in charge — composer, live run feed (`AgentRun`), the one law's split — it turns on WHO supplied the values; findings, provenance, confidence; **after the run** — a stored record that fills up from several writers; the whole run in a dialog, **stopping**; **review surfaces compose from atoms** — `DiffValue`, `DiffMark`, `useChangeSet`. |
-| [docs/composition.md](./docs/composition.md) | The design-language contract — **the form comes before the treatment** (name what the subject IS before reaching for parts), canvas + content column, heading altitude, register vs inset rows, the button ladder, master-detail `Drawer`, the register's rhythm, craft and TRIAGE bands, where the accent goes, theming as an app-level ESCAPE HATCH, color discipline, typography, **one fact one surface** (a chooser over the thing it chooses is a SELECTOR, not a second card grid; a control that only swaps one number for another is replaced by showing both), **a width floor answers can this be READ and never can this be operated** (the operating question passes a row whose every string is already cut), **a status column earns its slot by carrying a REASON rather than a state** (the floor asks for the fact to be visible, not for a badge), **a row subject's supporting line takes a REFERENCE and never a sentence** (an explanation truncates to the clause the reader already knew), and where a commit sits. |
-| [docs/reviewing.md](./docs/reviewing.md) | **Reviewing a screen you built — and the answer when one "looks bad"** — the other docs say what good looks like; this one says how to find out whether you achieved it. Run it BEFORE the deploy: a typecheck, a lint, a test and `app check` are all blind to how a screen reads. GATES that outrank every treatment question, then the probes, each naming what to COLLECT and the SIGNATURE in the numbers — including the truncation sweep (a row whose halves both measure fine and whose text is cut) the summary-vs-facet check (a strip that keeps describing the unfiltered set) and the derivable-column test (a status badge its neighbour already answers). Plus the extraction snippets, what measurement cannot see, and how to act on a finding. |
+| [docs/composition.md](./docs/composition.md) | The design-language contract — **the form comes before the treatment** (name what the subject IS before reaching for parts), canvas + content column, heading altitude, register vs inset rows, the button ladder, master-detail `Drawer`, the register's rhythm, craft and TRIAGE bands, where the accent goes, theming as an app-level ESCAPE HATCH, color discipline, typography, **one fact one surface** (a chooser over the thing it chooses is a SELECTOR, not a second card grid; a control that only swaps one number for another is replaced by showing both), **a width floor answers can this be READ and never can this be operated** (the operating question passes a row whose every string is already cut), **a status column earns its slot by carrying a REASON rather than a state** (the floor asks for the fact to be visible, not for a badge), **a row subject's supporting line takes a REFERENCE and never a sentence** (an explanation truncates to the clause the reader already knew), **a list stays fast by keeping IDENTITY rather than memoizing** (key by the record not the index; `memo` is the last resort and does nothing against a freshly-built prop), and where a commit sits. |
+| [docs/reviewing.md](./docs/reviewing.md) | **Reviewing a screen you built — and the answer when one "looks bad"** — the other docs say what good looks like; this one says how to find out whether you achieved it. Run it BEFORE the deploy: a typecheck, a lint, a test and `app check` are all blind to how a screen reads. GATES that outrank every treatment question, then the probes, each naming what to COLLECT and the SIGNATURE in the numbers — including the truncation sweep (a row whose halves both measure fine and whose text is cut) the summary-vs-facet check (a strip that keeps describing the unfiltered set) and the derivable-column test (a status badge its neighbour already answers) and the cross-FRAME check (what the screen destroys when a row arrives — the one defect that exists in no single frame). Plus the extraction snippets, what measurement cannot see, and how to act on a finding. |
 | [docs/testing.md](./docs/testing.md) | Driving the kit in a browser — the three anatomies where the a11y tree says one thing and a driver must do another: a `PressDoor` row whose named button always intercepts pointer events (by design), portalled overlays that render at the top of the DOM, and custom pointer drag that `dragTo` cannot move. |
 | [docs/templates.md](./docs/templates.md) | The map of `examples/tpl_*.tsx` — what shape each template solves and which to start from (copy + adapt, never import) — plus the record-surface composition rules (pipeline order, static shape, decision budget) and the ACTIVITY shape — a communications feed where the row's label is the GIST and the body varies by medium, one anatomy rather than a row type per kind. |
 

package/docs/catalog.md

@@ -298,6 +298,15 @@ by size.)
   ordinary case, not an exotic one; compose a hand-designed
   card pile (`PressableRow` + your own hierarchy) over `useScreenSize` only when a screen
   deserves a better mobile shape than the automatic stack.
+  **A row that LANDS while someone is looking takes `justArrived`**, paired with
+  `useJustArrived(ids, scope)` from `@lotics/ui/just_arrived` — the push that delivers it is
+  otherwise invisible, because the list is one row longer and nothing says which one. Pass the
+  hook's set, never a hand-rolled diff: it owns the two rules that make the naive version
+  unusable — a FIRST render is not an arrival (or a register opening on two hundred rows flashes
+  all of them), and a `scope` change reseeds silently (or picking a status flashes every row the
+  filter swapped in). WRONG PLACE: it is not a way to mark a row you want the reader to notice —
+  that is `marked`, or a badge in a cell. The question that decides it is *did this row exist a
+  moment ago*; if the answer does not change on its own, this is not the prop.
 - **Inline-managed grouped table** (MODERATE — hundreds, low-thousands — you MANAGE in view)
   — the `DataGrid` primitive: a grouped, sortable grid whose cells are LIVE inline editors
   (ANY field — a column is `{ key, label, width?, sortable?, cell: (item) => ReactNode }`,
@@ -2294,7 +2303,13 @@ component rather than showing it at zero.
   filename; pass `accessibilityLabel` to say what pressing it DOES instead. The per-surface
   pieces are exported for a hand-rolled layout: `DocumentBadge` (a bare pressable badge —
   its `size` is the square SLOT side, like every other tile here, and the badge is fitted to
-  it), `DocumentCard`, `MediaCard`, `RemoveButton`.
+  it), `DocumentCard`, `MediaCard`, `RemoveButton`. **`toDisplayFile(cell)` is how a file
+  reaches any of them** — it takes a `FileCell` (a record read's `files` entry: `id`,
+  `filename`, `mime_type`, `url`, optional `thumbnail_url`) and returns the `DisplayFile`
+  every component here expects. Reach for it rather than writing the five-line mapping: the
+  hand-written one is where a `mime_type`/`mimeType` slip becomes a tile that silently
+  renders as a generic document. It returns a fresh object per call by design — see
+  composition.md §"A list stays fast" for why an identity cache is the wrong answer.
 - **`file_thumbnail_grid`** — **`diffs`** (a `ReadonlyMap<string, DiffKind>`, keyed like
   `selectedIds`) marks each tile, so a grid under review is the SAME grid with one more map
   passed in rather than a different component the operator has never seen.

package/docs/composition.md

@@ -2083,6 +2083,35 @@ most common, because it survives every other check: each piece is defensible alo
 question "what does this tell me that the screen does not already say" catches decoration wearing
 an information costume.
 
+## A list stays fast by keeping IDENTITY, not by memoizing
+
+The expensive thing a screen can do is not re-render — it is REPLACE. Re-running a
+component produces no DOM work at all when the output matches; React's diff absorbs it. A
+15-row register with 58 pictures, re-rendered against equal data, writes **nothing**. The
+same register with one row inserted, when identity is lost, writes **271 mutations and
+rebuilds 89 nodes** — and every rebuilt `Image` starts empty and paints blank until a
+frame later, which is the flicker people describe as "the images reload".
+
+So the rule is about identity:
+
+- **Key a row by the record, never by its position.** `key={i}` is correct only for a list
+  that cannot reorder or grow. The moment something can be inserted, an index key hands
+  every row a different slot and React rebuilds all of them. This applies to any wrapper
+  you put around a mapped child too — a container keyed by index destroys the identity its
+  child was carrying.
+- **Don't define a component inside another component's render.** Its type changes every
+  render, so its whole subtree remounts.
+- **Don't swap a list for a placeholder on refetch.** `loading ? <Skeleton/> : <Rows/>`
+  belongs to the FIRST load only — gate it on having no rows yet, never on a request being
+  in flight, or every background refresh unmounts the content and remounts it.
+
+**Reach for `memo` last, and only with a measurement.** It prevents a re-render, which is
+the cheap half, and it silently does nothing when a prop is a fresh object each render —
+which is the normal case, since rows come from a `useMemo` over query results. Where a list
+is genuinely large enough to hurt, window the rows; that removes the work rather than
+comparing it. `toDisplayFile` returns a new object per call for exactly this reason: an
+identity cache would exist to enable a memo that measurement does not justify.
+
 ## `accessibilityState` never reaches the DOM — write `aria-*` yourself
 
 React Native Web maps a subset of RN's accessibility props and **silently drops

package/docs/reviewing.md

@@ -595,6 +595,34 @@ a second copy free to disagree — check it against the FIELD, not against itsel
 
 → [data_entry.md](./data_entry.md) §"A picker over a select FIELD keeps the field's colours".
 
+### 9c. What the screen does when the data MOVES — the cross-frame check
+Every probe above reads ONE rendered frame. This defect does not exist in a frame: the screen is
+correct before, correct after, and destroys itself in between. A register whose rows are correct
+either side of an insert can still have rebuilt every row to get there, and each rebuilt picture
+paints EMPTY for a frame before it repaints — which is what people report as "the images reload".
+
+**Collect:** stamp the nodes, move the data, count the survivors.
+
+```js
+document.querySelectorAll("img").forEach((el, i) => { el.__s = i; });
+// …now insert a row / reorder / let a refetch land…
+const imgs = [...document.querySelectorAll("img")];
+({ total: imgs.length, survived: imgs.filter((e) => e.__s !== undefined).length })
+```
+
+**The signature** is survivors far below the rows that were already there — a row that only MOVED
+should keep its node. Only genuinely new rows may be fresh. A `MutationObserver` gives the same
+answer as a magnitude: a re-render against equal data should write NOTHING, and one insert should
+write about one row's worth.
+
+Two causes, both invisible to every other probe. A container keying its wrapped children by
+POSITION overrides the caller's correct keys, so an insert shifts every child into a different slot
+and React rebuilds all of them — the caller cannot see it or fix it from outside. And a region
+gated on a REQUEST (`loading ? <Spinner/> : <Rows/>`) rather than on having nothing yet unmounts
+its whole subtree on each background refresh.
+
+→ [composition.md](./composition.md) §"A list stays fast by keeping IDENTITY, not by memoizing".
+
 ### 10. Microcopy
 - **No punctuation doing a word's job.** ` · ` is banned outright — it claims a relationship while
   refusing to name it, and it is the loudest templated-metadata tell there is. If a mark cannot be

package/docs/testing.md

@@ -70,3 +70,26 @@ and the window are the right ones. From the dragged element,
 Then check **both** halves: re-snapshot for the optimistic move, and re-read the
 record to confirm the mutation actually persisted. An optimistic move that never
 reached the server looks identical on screen.
+
+## Assert what an update KEEPS, not only what it renders
+
+A test that reads the output passes either way when a list rebuilds itself: the same rows are on
+screen, so nothing about the text is wrong. What changed is that every node was replaced — and a
+replaced `Image` paints empty before it repaints.
+
+Hold the node and compare it after the update:
+
+```tsx
+const { rerender, getByTestId } = render(board(["a", "b"]));
+const before = getByTestId("b");
+rerender(board(["new", "a", "b"]));
+expect(getByTestId("b")).toBe(before); // MOVED, not rebuilt
+```
+
+State the budget as DOM WRITES, never as a render count. Re-running a component is close to free —
+React's diff absorbs it — so counting renders fails a healthy tree and pushes the next author into
+memoising leaves that cost nothing. A `MutationObserver` around a `rerender` with equal data should
+see zero. And assert the opposite too: an insert MUST write, or a green suite only proves the
+observer was blind.
+
+→ [composition.md](./composition.md) §"A list stays fast by keeping IDENTITY, not by memoizing".

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "47.4.1",
+  "version": "47.5.1",
   "type": "module",
   "exports": {
     "./accordion": "./src/accordion.tsx",
@@ -159,6 +159,7 @@
     "./inset": "./src/inset.tsx",
     "./interaction_modality": "./src/interaction_modality.ts",
     "./json_panel": "./src/json_panel.tsx",
+    "./just_arrived": "./src/just_arrived.ts",
     "./keyboard": "./src/keyboard.ts",
     "./kpi_card": "./src/kpi_card.tsx",
     "./kpi_strip": "./src/kpi_strip.tsx",

package/src/file_thumbnail.tsx

@@ -72,6 +72,47 @@ export interface DisplayFile {
   previewUrl?: string;
 }
 
+/**
+ * The wire shape of a file cell — what a record read hands back, before it is
+ * anything a component can render.
+ *
+ * Structural, not imported: the kit stays free of platform packages, and this
+ * names only the five fields the conversion reads.
+ */
+export interface FileCell {
+  id: string;
+  filename: string;
+  mime_type: string;
+  url: string;
+  thumbnail_url?: string;
+}
+
+/**
+ * A file cell → the shape every display component here takes.
+ *
+ * It lives in the kit because it was living in every app instead: each one
+ * re-declared the same five-line mapping, so a field added here reached none of
+ * them and a `mime_type`/`mimeType` slip was a per-app bug. One definition, on
+ * the side that owns the type.
+ *
+ * It returns a NEW object per call, deliberately. An identity cache here would
+ * let callers memoize on reference, but a re-render that changes nothing
+ * already writes nothing to the DOM (`table_render_budget.test.tsx` pins it),
+ * so the cache would buy a fraction of a cheap operation and cost a map that
+ * grows for the life of the tab — presigned urls rotate, so its keys never stop
+ * accumulating. If a list ever outgrows that, the answer is windowing the rows,
+ * not remembering the objects.
+ */
+export function toDisplayFile(f: FileCell): DisplayFile {
+  return {
+    id: f.id,
+    filename: f.filename,
+    mimeType: f.mime_type,
+    url: f.url,
+    thumbnailUrl: f.thumbnail_url,
+  };
+}
+
 // =============================================================================
 // FileThumbnail - Main display component
 // =============================================================================
@@ -485,6 +526,11 @@ function ImageThumbnail(props: ImageThumbnailProps) {
   const a11yLabel = props.accessibilityLabel ?? file.filename;
   const [useFallback, setUseFallback] = useState(false);
   const { focusVisible, focusProps } = useFocusRing();
+  // STABLE, not an inline arrow. `onError` sits in react-native-web's image
+  // load effect's dependency array, so a fresh callback each render tears the
+  // pending request down and issues a new `Image()` — re-fetching a picture
+  // that never changed, on every render of the row it sits in.
+  const handleError = useCallback(() => setUseFallback(true), []);
 
   // Use thumbnail if available, fallback to full URL
   const url = !useFallback && file.thumbnailUrl ? file.thumbnailUrl : file.url;
@@ -502,7 +548,7 @@ function ImageThumbnail(props: ImageThumbnailProps) {
             source={{ uri: url }}
             style={styles.image}
             resizeMode="cover"
-            onError={() => setUseFallback(true)}
+            onError={handleError}
           />
           <TileScrim hovered={(state as { hovered?: boolean }).hovered} pressed={state.pressed} />
         </>

package/src/image_gallery.tsx

@@ -68,7 +68,12 @@ export function ImageGallery({
   // Per-image rotation, shared with the zoom modal so a turn survives opening it.
   const rotation = useImageRotation();
 
-  if (loading) return <ActivityIndicator />;
+  // FIRST load only. Gating the spinner on the request rather than on having
+  // nothing to show swaps the whole gallery for it on every revalidation —
+  // unmounting each <Image>, which then remounts empty and repaints. A caller
+  // passing `loading={isValidating}` is doing the ordinary thing; the component
+  // has to survive it.
+  if (loading && images.length === 0) return <ActivityIndicator />;
   if (images.length === 0) return <Text size="sm" color="muted">{emptyText ?? locale.imageGallery.empty}</Text>;
 
   const idx = Math.min(selected, images.length - 1);

package/src/just_arrived.ts

@@ -0,0 +1,70 @@
+import { useEffect, useRef, useState } from "react";
+
+/** Shared so an unchanged result keeps its identity and re-renders nothing. */
+const EMPTY: ReadonlySet<string> = new Set<string>();
+
+/**
+ * Which ids are new, given what was on screen before — the rule, without React.
+ *
+ * `before` is `null` when nothing has been seen yet, and that case is the whole
+ * reason this is a named function: **a first render is never an arrival.** A
+ * register opening on two hundred rows has two hundred ids it has not seen, and
+ * the naive diff flashes all of them — both wrong (nothing arrived, the page
+ * loaded) and the moment a highlight is least wanted.
+ *
+ * A removal reports nothing. A row leaving is not a row arriving, and the two
+ * share a diff only if you write it carelessly.
+ */
+export function arrivalsSince(
+  before: ReadonlySet<string> | null,
+  ids: readonly string[],
+): string[] {
+  if (before === null) return [];
+  return ids.filter((id) => !before.has(id));
+}
+
+/**
+ * Which of these ids are NEW since the last render — the set a register passes
+ * to `TableRow`'s `justArrived`.
+ *
+ * A row landing while someone is looking at the screen is the case the realtime
+ * push exists for, and until something marks it the push is invisible: the list
+ * is one row longer and nothing says which one. Every register wants the same
+ * diff, so it lives here rather than in each app.
+ *
+ * **`scope` is what the ids are a list OF** — the filter, the search, the page.
+ * Without it a register cannot tell twelve rows ARRIVING from a filter change
+ * that replaced the list, because both are a large diff, and it would flash the
+ * whole page every time someone picked a status. Change the scope and the
+ * baseline reseeds silently: nothing arrived, the reader asked a different
+ * question. Pass a string that changes exactly when the QUESTION does.
+ *
+ * An EMPTY render never seeds the baseline either: a list rendering `[]` while
+ * its query is in flight would otherwise make its real first page look like an
+ * arrival.
+ *
+ * Ids leave the set on the next render that carries them, so the highlight is a
+ * one-shot — re-rendering never restarts an animation that already played.
+ */
+export function useJustArrived(ids: readonly string[], scope = ""): ReadonlySet<string> {
+  const seen = useRef<Set<string> | null>(null);
+  const seenScope = useRef(scope);
+  const [fresh, setFresh] = useState<ReadonlySet<string>>(EMPTY);
+
+  // Keyed on the ids' CONTENT: an array literal is a new reference every render,
+  // so depending on the array itself would re-run this forever.
+  const key = ids.join(",");
+
+  useEffect(() => {
+    if (ids.length === 0) return;
+    const sameQuestion = seenScope.current === scope;
+    seenScope.current = scope;
+    const added = arrivalsSince(sameQuestion ? seen.current : null, ids);
+    seen.current = new Set(ids);
+    setFresh(added.length > 0 ? new Set(added) : EMPTY);
+    // `ids` is covered by `key`, which is its content rather than its identity.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key, scope]);
+
+  return fresh;
+}

package/src/list.tsx

@@ -15,7 +15,10 @@ export function List(props: ListProps) {
   return (
     <View style={style}>
       {childArray.map((child, index) => (
-        <React.Fragment key={index}>
+        // The child's own key, never its position: a filtered list changes
+        // membership on every keystroke, and an index key rebuilds every
+        // surviving row (see composition.md §"A list stays fast").
+        <React.Fragment key={React.isValidElement(child) ? child.key : index}>
           {child}
           {index < childArray.length - 1 && <Divider />}
         </React.Fragment>

package/src/section_stack.tsx

@@ -1,4 +1,4 @@
-import { Children, Fragment } from "react";
+import { Children, Fragment, isValidElement } from "react";
 import { View, type StyleProp, type ViewStyle } from "react-native";
 import { Divider } from "./divider";
 
@@ -17,9 +17,11 @@ function DividedStack({ children, divided = true, gap, style }: StackProps & { g
   return (
     <View style={[{ gap }, style]}>
       {blocks.map((block, i) => (
-        // Children.toArray keys are stable for conditional lists; the fragment
-        // pairs each block with the hairline that separates it from the last.
-        <Fragment key={`sec_${i}`}>
+        // Children.toArray keys are stable for conditional lists — so USE
+        // them. `toArray` drops nulls, so a conditional section appearing
+        // shifts every later index and an index key would remount all of
+        // them, including any field mid-edit.
+        <Fragment key={isValidElement(block) ? block.key : `sec_${i}`}>
           {divided && i > 0 ? <Divider /> : null}
           {block}
         </Fragment>

package/src/sequence.tsx

@@ -62,7 +62,11 @@ export function Sequence({ children }: SequenceProps) {
     // which the rail runs through.
     <View>
       {items.map((child, index) => (
-        <SequenceItemContext.Provider key={index} value={{ index, count: items.length }}>
+        // The child's own key, never its position. This list REORDERS by
+        // design, and a Provider keyed by index makes "move up" tear both
+        // items down — losing the text a person was part-way through typing
+        // in them (see composition.md §"A list stays fast").
+        <SequenceItemContext.Provider key={child.key ?? index} value={{ index, count: items.length }}>
           {child}
         </SequenceItemContext.Provider>
       ))}

package/src/stack.tsx

@@ -28,7 +28,10 @@ export function Stack(props: StackProps) {
         children,
         (child, index) =>
           child && (
-            <View key={index}>
+            // NO key: `Children.map` already composes the child's own key
+            // onto what it returns. Adding one here overrides that with the
+            // position and remounts the list whenever it changes.
+            <View>
               {child}
               {useSeparator && index < React.Children.count(children) - 1 && (
                 <Separator padding={separatorPadding} />

package/src/table.tsx

@@ -1,6 +1,8 @@
 import {
   createContext,
   useContext,
+  useEffect,
+  useRef,
   useState,
   Children,
   cloneElement,
@@ -8,7 +10,7 @@ import {
   type ReactNode,
   type ReactElement,
 } from "react";
-import { StyleSheet, View, type ViewStyle } from "react-native";
+import { Animated, StyleSheet, View, type ViewStyle } from "react-native";
 import { Text } from "./text";
 import { colors, solid, type ColorName } from "./colors";
 import { PressableRow } from "./pressable_row";
@@ -16,6 +18,13 @@ import { PressDoor } from "./press_door";
 import { DetailRow } from "./detail_row";
 import { SortHeader, type SortState, type SortHeaderLabels } from "./sort_header";
 import { COLUMN_GAP, ROW_GUTTER, ROW_HEIGHT, computeTableFit, type TableFit, type TableFitColumn } from "./table_fit";
+
+/** How long an arrival wash sits at full strength before fading, and how long
+ *  the fade takes. Together they are the window a reader has to notice the row —
+ *  short enough that a busy register does not shimmer, long enough to survive a
+ *  glance away. */
+const ARRIVAL_HOLD_MS = 900;
+const ARRIVAL_FADE_MS = 700;
 import { ROW_WASH_BLEED } from "./control_surface";
 
 /**
@@ -272,11 +281,15 @@ export function Table(props: TableProps) {
           </View>
         )}
         <View style={styles.body}>
-          {rows.map((row, i) => {
-            return (
-              <View key={i}>{row}</View>
-            );
-          })}
+          {/* Keyed by the ROW's own key, never its index. `Children.toArray`
+              derives these from the caller's `key`, so they track the record
+              rather than the position. Keyed by index, inserting a row at the
+              top shifts every row into a different wrapper: React then sees a
+              new child key inside each one and remounts the whole list, which
+              destroys every `<Image>` and repaints the register blank. */}
+          {rows.map((row, i) => (
+            <View key={row.key ?? i}>{row}</View>
+          ))}
         </View>
       </View>
     </TableContext.Provider>
@@ -347,8 +360,9 @@ export function TableGroup(props: TableGroupProps) {
         ) : null}
       </View>
       <View style={styles.body}>
+        {/* The row's own key, for the reason given in the wide variant above. */}
         {rows.map((row, i) => (
-          <View key={i}>{row}</View>
+          <View key={row.key ?? i}>{row}</View>
         ))}
       </View>
     </View>
@@ -359,6 +373,21 @@ export type TableRowProps = {
   selected?: boolean;
   /** Part of a multi-select set — a resting blue tint (the open/hover wash overrides it). */
   marked?: boolean;
+  /**
+   * This row LANDED — it was not here a moment ago. Plays a wash that fades out
+   * once, so a reader looking at the register when the push arrives can see
+   * which row is the new one.
+   *
+   * Pair it with `useJustArrived`, which owns the diff and the rule that a first
+   * render is never an arrival. Passing it per-row from a hand-rolled diff is
+   * how a register ends up flashing all two hundred rows on load.
+   *
+   * It is an OVERLAY, not a fifth interaction state: `backgroundColor` on this
+   * row already has one owner (hover / selected / marked / pressed), and a
+   * second writer would make the two agree only by luck. So an arrival composes
+   * with all of them — a new row you are hovering shows both.
+   */
+  justArrived?: boolean;
   /** Outside the door, BEFORE the cells (a selection checkbox) — width = Table `leading`. */
   leading?: ReactNode;
   /**
@@ -452,8 +481,46 @@ export type TableRowProps = {
  * the remaining cells as label-over-value blocks — same door, same wash, same
  * slots, different geometry.
  */
+/**
+ * The one-shot wash a row wears when it has just landed.
+ *
+ * OPACITY, never `backgroundColor` — that property belongs to the row's four
+ * interaction states, and a second writer would make them agree only by accident
+ * (see `pressable_row`). Fading an overlay composes with all four instead, and
+ * opacity is what `useNativeDriver` can animate off the JS thread, which matters
+ * on the surface most likely to be rendering two hundred rows.
+ *
+ * `accent_wash` is the token the kit reserves for ATTENTION — a drop target
+ * lighting up — as distinct from the neutral grounds that say which record is
+ * open. A row that arrived while you were looking at it is exactly that.
+ *
+ * It renders nothing until it has something to say, so an ordinary register pays
+ * no extra view per row, and it never takes a press.
+ */
+function ArrivalWash({ on }: { on: boolean }) {
+  const fade = useRef(new Animated.Value(0)).current;
+  const [live, setLive] = useState(false);
+
+  useEffect(() => {
+    if (!on) return;
+    setLive(true);
+    fade.setValue(1);
+    // Held, THEN faded: a wash that begins mid-fade reads as a rendering
+    // artefact rather than as something arriving.
+    Animated.sequence([
+      Animated.delay(ARRIVAL_HOLD_MS),
+      Animated.timing(fade, { toValue: 0, duration: ARRIVAL_FADE_MS, useNativeDriver: true }),
+    ]).start(({ finished }) => {
+      if (finished) setLive(false);
+    });
+  }, [on, fade]);
+
+  if (!live) return null;
+  return <Animated.View pointerEvents="none" style={[styles.arrival, { opacity: fade }]} />;
+}
+
 export function TableRow(props: TableRowProps) {
-  const { onPress, selected, marked, accessibilityLabel, leading, ordinal, trailing, action, minHeight, detail, expanded, children } = props;
+  const { onPress, selected, marked, justArrived, accessibilityLabel, leading, ordinal, trailing, action, minHeight, detail, expanded, children } = props;
   const ctx = useContext(TableContext);
   if (!ctx) throw new Error("TableRow must be used within a Table");
   // Read AFTER the context check so an airy register does not need every row to
@@ -522,6 +589,7 @@ export function TableRow(props: TableRowProps) {
 
   const rowSurface = (
     <PressableRow onPress={onPress} selected={selected || showDetail} marked={marked} style={styles.row}>
+      <ArrivalWash on={justArrived === true} />
       {!ctx.stacked ? <LeadGutter ordinal={ordinal}>{leading}</LeadGutter> : null}
       {/* The door hit-tests above in-flow content; the cells/slots lift back above it
           via zIndex 1 (see `PressDoor`), so the door gets only the keyboard. Radius
@@ -597,6 +665,15 @@ export function TableCell(props: TableCellProps) {
 }
 
 const styles = StyleSheet.create({
+  arrival: {
+    position: "absolute",
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    borderRadius: 12,
+    backgroundColor: colors.accent_wash,
+  },
   // The expanded detail. Indented to the identity column's text edge so it reads
   // as belonging to the row above rather than as a new row, and given the row's
   // own gutter so its content lines up with the cells it explains.