@lotics/ui 14.0.0 → 14.2.0

package/AGENTS.md

@@ -56,6 +56,11 @@ doc before building any screen, **never from memory**. Exact props are the shipp
   hand-picked palette shade; color is `solid`/`tint`/`ramp` with ONE accent per screen.
 - **Pure primitives only** — no i18n, analytics, or domain types in `src/` (pass `labels`,
   callbacks); Lotics-coupled UI belongs in `@lotics/ui-internal`.
+- **A button never contains a control** — a row that presses open AND carries its own controls
+  (a CTA, ⋯, a checkbox, a `Link`) is a role-less `PressableRow` + a **`PressDoor`** sibling
+  (the tab stop, name, focus ring), never `PressableHighlight`, which wraps its children in the
+  button. `Table`/`TableRow` and `LinkedRecordBox` already do this. →
+  [composition.md](./docs/composition.md).
 - **Every state designed** — skeleton (mirroring layout), empty, error; no layout shift.
 - **Copy states content, not mechanics** — a `description` names the section's content or one
   domain rule; widget behavior ("edits in place, saves on its own") and selling points never

package/docs/ai_patterns.md

@@ -136,11 +136,18 @@ move on, so the feed doesn't dramatize it. A BREAKING error that terminates the
 OUTSIDE `parts` (chat persists it in the message's `errors`; `useAgentRun().error` carries it) —
 pass it as the `error` prop and it renders as a terminal danger row under the transcript.
 
+**In a bounded container, wrap it in `FollowScroll`.** An `AgentRun` streaming inside a dialog,
+drawer, or fixed-height panel grows BELOW the fold — a plain scroll container doesn't follow. Wrap
+the feed: `<FollowScroll style={{ maxHeight: … }}><AgentRun … /></FollowScroll>` — pinned to the
+newest content while streaming, unpinned when the human scrolls up to read (`AgentProgress`'s
+expanded panel already does this). A full-page inverted list (chat) follows by construction and
+doesn't need it.
+
 Fed natively by `@lotics/app-sdk`'s `useAgentRun().parts` (reasoning + per-tool I/O + state come
 for free — no hand-assembly): `<AgentRun parts={run.parts} state={…} error={run.error} />` — see
 [the SDK doc](../../app-sdk/docs/ai.md) for the hook. Requires `ai` as an optional (type-only) peer.
 **Reasoning only shows when the model produces it** — the declared model must support thinking
-(Sonnet 4.6 / Opus 4.8, not Haiku); the renderer shows every reasoning part it's handed.
+(Sonnet / Opus, not Haiku); the renderer shows every reasoning part it's handed.
 
 **Limitation:** the collapsed reasoning row's "Thinking" label and the expanded detail's
 "Input"/"Output"/"Error" panel titles are currently English-only (not on the locale provider and
@@ -268,7 +275,7 @@ reads as the custom answer).
 
 `ClarifyWizard` (`@lotics/ui/clarify_wizard`): a SEQUENCE of clarify questions worked one at a time —
 Back / Next / Cancel / Submit (Next/Submit primary), the step position an eyebrow ("1 / 3") above the
-question — no progress bar. Each step is a `Clarify`; advance only once the
+question — no progress bar, and no eyebrow at all for a single question. Each step is a `Clarify`; advance only once the
 current question is answered; `onSubmit` gives one `{ value, custom }` per question (aligned by index,
 `custom` true when the answer came from "Other…"), `onCancel` dismisses. All navigation chrome is
 locale-wired (the `clarify` slice). The multi-question form of the ask-back.

package/docs/catalog.md

@@ -179,10 +179,19 @@ of a record/settings surface).
 
 `PressableRow` (THE register row; forwards its `ref`, so wrapping it in a `PopoverTrigger`
 anchors a row-triggered peek Popover — without the ref the trigger is unmeasurable and the
-popover renders off-screen), `ListItem`, `MenuButton`, `MenuListItem`, `DetailRow`
+popover renders off-screen), `PressDoor` (the keyboard door that pairs with it — see
+below), `ListItem`, `MenuButton`, `MenuListItem`, `DetailRow`
 (label+value for drawers/peeks; optional `trailing` slot for a right-side
 action/badge/unit), `ActionMenu` (⋯), `FloatingActionBar` (bulk-select bar).
 
+A DESIGNED row (your own pile, card, or panel) that presses open AND carries its own
+controls is `PressableRow` + **`PressDoor`** — never `PressableHighlight`, which IS a
+button and wraps its children (a button must not contain interactive descendants). The
+door is an empty absolutely-positioned SIBLING of the content carrying the tab stop,
+accessible name, and focus ring; lift the content above it with `zIndex: 1`. `Table`/
+`TableRow` and `LinkedRecordBox` do exactly this internally, so a columnar register needs
+no assembly — reach for `PressDoor` only outside them.
+
 ### Filters & view controls
 
 `SearchInput`, `ChipGroup`, `FilterChip` (+ `RangeSlider`, `Counter`), `Chip`,
@@ -212,8 +221,9 @@ trailing ⋯ menu = Download · Open-external · Remove; the default "here are s
 surface), `FileGrid` (the upload-aware grid: completed files + a live upload queue in one
 surface — `FilesEditor` is this + the toolbar; reach for `FileGrid` bare when you own the
 chrome), `FileThumbnail` / `FileThumbnailGrid` (square tiles; `onPress`/`onFilePress` makes each
-tile a pressable door — e.g. tap-to-preview — carrying an accessible button role + filename
-label; `selectedIds` for a selection overlay),
+tile a pressable door — e.g. tap-to-preview — carrying an accessible button role + the
+filename as its name, overridable per tile with `accessibilityLabel` when what the press
+DOES reads better than a raw filename; `selectedIds` for a selection overlay),
 `UploadingThumbnail` (the single in-flight tile FileGrid renders — reach for it only when
 hand-rolling a non-grid upload layout), `FileRow` (a horizontal file/document LINE —
 badge-or-placeholder + name + meta + a composable `trailing` slot for a status badge /
@@ -443,6 +453,14 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`pressable_row`** — `PressableRow`: THE register row — full-width hover/open wash,
   `selected` (the open record) vs `marked` (ticked in bulk-select), forwards `ref` for
   popover anchoring.
+- **`press_door`** — `PressDoor`: THE keyboard door — an EMPTY absolutely-positioned
+  `Pressable` sibling that carries the `role="button"` tab stop, the (REQUIRED)
+  `accessibilityLabel`, and the focus ring for a pressable surface whose content holds its
+  own controls. Pair it with `PressableRow` (surface takes the mouse + the wash, door takes
+  the keyboard, nested controls keep their own presses); the parent owns the positioning
+  context and the content lifts above the door with `zIndex: 1`. `radius` (default 10)
+  matches the surface it spans. `TableRow` / `LinkedRecordBox` are the in-kit consumers —
+  reach for it when designing a row those don't cover.
 - **`linked_record_box`** — `LinkedRecordBox`: a bordered box scoping ANOTHER record's data
   (`icon` · `name` · `subtitle` · vertical `facts`), the WHOLE box a keyboard door into its
   detail (`onOpen`/`doorLabel`); verbs ride an `actions` slot in a hairline-fenced footer at the
@@ -906,7 +924,11 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`file_thumbnail`** — `FileThumbnail` + `DisplayFile` + `THUMBNAIL_SIZE` /
   `COMPACT_THUMBNAIL_SIZE` + `getMediaIcon`: the completed tile — the right surface per
   MIME: image thumbnail · a doc tile with the `FileBadge` centered + a single-line filename
-  · media card; `isTemplate` overlays a TMPL marker.
+  · media card; `isTemplate` overlays a TMPL marker. The tile's accessible name is the
+  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`.
 - **`file_thumbnail_grid`** — `FileThumbnailGrid` (+ the generic `ThumbnailGrid`):
   display-only square-tile grid; `selectedIds` + `onFilePress` pair with
   `useSelectionMode()` for gated select-mode CRUD.
@@ -919,7 +941,9 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   + a ⋯ Download/Open-external/Remove menu; composes `FileRow` + `ActionMenu` +
   `FileGalleryModal`; localized via the `gallery` locale slice.
 - **`file_badge`** — `FileBadge`: the two-tone file-type mark (PDF / XLSX / DOCX / video /
-  audio …) driven by MIME.
+  audio …) driven by MIME. Its `size` is the badge's WIDTH and everything scales off it —
+  the mark is TALLER than it is wide (26 × 32 by default), so a square slot takes the
+  fitted width, not the slot side (that conversion is what `DocumentBadge` does).
 - **`file_preview`** — `FilePreview`: the universal inline preview — image/PDF/video/audio +
   Word via `@lotics/docx` + Excel/CSV via `@lotics/xlsx`; the heavy engines (pdf.js ·
   `@lotics/docx` · `@lotics/xlsx`) are LAZY (dynamic-imported, ~free until a doc of that
@@ -976,6 +1000,11 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `AgentRun` and `AgentProgress`. The sole file permitted to `import type` from `ai`.
 - **`agent_progress`** — `AgentProgress`: `AgentRun`'s compact, floating, expandable form (same
   `parts` prop) — a composer's working state.
+- **`follow_scroll`** — `FollowScroll`: a scroll container that FOLLOWS its growing content —
+  pinned to the bottom as children stream in; scrolling up unpins (read history), scrolling back
+  re-pins. Wrap a streaming `AgentRun` with it in any bounded container (a dialog, a drawer,
+  a panel — put the height bound on `style`); `AgentProgress`'s expanded panel uses it. Chat
+  doesn't need it (an inverted message list follows by construction).
 - **`confidence`** — `Confidence` + `ConfidenceLevel` + `levelFromScore`: calibrated
   high/med/low; localized via the provider.
 - **`change_review`** — the COMPOUND review family — frame: `ChangeReview` provider/stack ·
@@ -995,7 +1024,8 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `{ value, label, description }` — the description is MANDATORY (every answer explains itself).
   `allowCustom` adds an always-visible borderless multiline custom-answer field below the options.
 - **`clarify_wizard`** — `ClarifyWizard` + `ClarifyWizardQuestion`/`ClarifyWizardAnswer`: a SEQUENCE
-  of `Clarify` questions with Back/Next/Cancel/Submit + a `n / total` position indicator; advance
+  of `Clarify` questions with Back/Next/Cancel/Submit + a `n / total` position indicator (omitted
+  for a single question); advance
   only when the current is answered, `onSubmit` returns one `{ value, custom }` per question.
   Navigation chrome is locale-wired (the `clarify` locale slice).
 - **`choice_list`** — `ChoiceList` + `ChoiceOption`: selectable answer options as

package/docs/composition.md

@@ -287,6 +287,14 @@ body is arbitrary app content — `TableRow`'s cells, which legitimately carry a
 trigger — the door is an EMPTY absolutely-positioned sibling under the cells (tab stop + name +
 focus ring; the mouse rides the surface), so a control in a cell never nests inside it.
 
+That empty door is the **`PressDoor`** primitive (`@lotics/ui/press_door`) — don't hand-roll it
+when you design a row `Table` doesn't cover (a mobile pile with a per-row control, a bespoke
+card): `<PressableRow onPress>` + `<PressDoor onPress accessibilityLabel="Open …" />` + your
+content on `zIndex: 1` (the door hit-tests above in-flow siblings, so the content must lift back
+over it). `PressableHighlight` is the wrong base for such a row — it IS a button and wraps its
+children, so any nested control lands inside it; it stays for surfaces whose content is
+non-interactive by construction. `TableRow` and `LinkedRecordBox` already compose `PressDoor`.
+
 Actions stay **visible** — a hover-only action is invisible to keyboard and touch users. The ONLY
 exception is a DENSE tree/register where a persistent per-row action would clutter: reveal on
 hover **OR focus-within**, keeping the action in the DOM + tab order and gating only its opacity,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "14.0.0",
+  "version": "14.2.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -80,6 +80,7 @@
     "./activity_indicator": "./src/activity_indicator.tsx",
     "./agent_run": "./src/agent_run.tsx",
     "./agent_progress": "./src/agent_progress.tsx",
+    "./follow_scroll": "./src/follow_scroll.tsx",
     "./markdown": {
       "react-native": "./src/markdown.tsx",
       "default": "./src/markdown.web.tsx"
@@ -112,6 +113,7 @@
     "./menu_list_item": "./src/menu_list_item.tsx",
     "./pressable_highlight": "./src/pressable_highlight.tsx",
     "./pressable_row": "./src/pressable_row.tsx",
+    "./press_door": "./src/press_door.tsx",
     "./floating_action_bar": "./src/floating_action_bar.tsx",
     "./icon_button": "./src/icon_button.tsx",
     "./info_popover": "./src/info_popover.tsx",

package/src/agent_progress.tsx

@@ -1,8 +1,9 @@
 import { useState } from "react";
-import { ScrollView, StyleSheet, View } from "react-native";
+import { StyleSheet, View } from "react-native";
 import { colors } from "./colors";
 import { Text } from "./text";
 import { WaveAvatar } from "./wave_avatar";
+import { FollowScroll } from "./follow_scroll";
 import { PressableHighlight } from "./pressable_highlight";
 import { AgentRun, resolveToolMeta } from "./agent_run";
 import { toSegments, lastRunningStep, type AgentUIPart } from "./agent_transform";
@@ -46,9 +47,11 @@ export function AgentProgress(props: AgentProgressProps) {
     <View style={{ gap: 8 }}>
       {expanded ? (
         <View style={styles.panel}>
-          <ScrollView style={{ maxHeight: 260 }} contentContainerStyle={{ padding: 16 }}>
+          {/* FollowScroll keeps the newest step in view as the run streams —
+              a plain ScrollView would let new content grow below the fold. */}
+          <FollowScroll style={{ maxHeight: 260 }} contentContainerStyle={{ padding: 16 }}>
             <AgentRun parts={parts} state={state} error={error} labelForTool={labelForTool} stepsLabel={stepsLabel} />
-          </ScrollView>
+          </FollowScroll>
         </View>
       ) : null}
 

package/src/clarify_wizard.tsx

@@ -64,10 +64,11 @@ export function ClarifyWizard(props: ClarifyWizardProps) {
 
   return (
     <View style={{ gap: 16 }}>
-      {/* The step position is an eyebrow above the question (no progress bar); the
-          footer aligns to the same 8px inset as the question and answers. Keyed by
-          index so each step's custom-answer draft is its own (no bleed across steps). */}
-      <Clarify key={index} eyebrow={`${index + 1} / ${total}`} question={q.question} options={q.answers} answer={current} onAnswer={setAnswer} allowCustom={q.allowCustom} />
+      {/* The step position is an eyebrow above the question (no progress bar — and
+          none at all for a single question); the footer aligns to the same 8px inset
+          as the question and answers. Keyed by index so each step's custom-answer
+          draft is its own (no bleed across steps). */}
+      <Clarify key={index} eyebrow={total > 1 ? `${index + 1} / ${total}` : undefined} question={q.question} options={q.answers} answer={current} onAnswer={setAnswer} allowCustom={q.allowCustom} />
       <View style={{ flexDirection: "row", alignItems: "center", justifyContent: "space-between", gap: 8, paddingHorizontal: 8 }}>
         <Button title={labels.cancel} color="muted" onPress={onCancel} />
         <View style={{ flexDirection: "row", gap: 8 }}>

package/src/file_badge.tsx

@@ -2,6 +2,7 @@ import { Text, View } from "react-native";
 import { fontFamilySemiBold } from "./text_utils";
 import { Icon, type IconName } from "./icon";
 import { isVideoMimeType, isAudioMimeType } from "./mime";
+import { FILE_BADGE_DEFAULT_WIDTH, fileBadgeHeight } from "./file_badge_fit";
 
 const VIDEO_COLOR = "#ea580c";
 const AUDIO_COLOR = "#db2777";
@@ -32,12 +33,14 @@ export function resolveMime(mimeType: string): { label: string; color: string }
   return MIME_MAP[mimeType] ?? DEFAULT_BADGE;
 }
 
-const DEFAULT_SIZE = 26;
+const DEFAULT_SIZE = FILE_BADGE_DEFAULT_WIDTH;
 
 interface FileBadgeProps {
   /** Omit only with `placeholder` — a ghost slot has no resolved type yet. */
   mimeType?: string;
-  /** Base width in pixels. Height, radii, font, and padding scale proportionally. Default: 26 */
+  /** Base WIDTH in pixels. Height, radii, font, and padding scale proportionally — the
+   *  badge is TALLER than it is wide (26 × 32 at the default), so a SQUARE slot takes the
+   *  fitted width, not the slot side (`DocumentBadge` does that conversion). Default: 26 */
   size?: number;
   /** Show a "TMPL" overlay to distinguish templates from regular files. */
   isTemplate?: boolean;
@@ -58,7 +61,7 @@ function getMediaIcon(mimeType: string): IconName | undefined {
 
 export function FileBadge({ mimeType, size = DEFAULT_SIZE, isTemplate, placeholder }: FileBadgeProps) {
   const scale = size / DEFAULT_SIZE;
-  const height = Math.round(32 * scale);
+  const height = fileBadgeHeight(size);
   const radius = Math.round(4 * scale);
 
   if (placeholder) {

package/src/file_badge_fit.test.ts

@@ -0,0 +1,49 @@
+import { describe, it, expect } from "vitest";
+import {
+  FILE_BADGE_BOX,
+  FILE_BADGE_DEFAULT_WIDTH,
+  fileBadgeHeight,
+  fileBadgeWidthForBox,
+} from "./file_badge_fit";
+
+describe("FileBadge geometry", () => {
+  it("scales the badge with the requested width instead of pinning the default", () => {
+    // The bug this covers: a caller's `size` was dropped and every badge rendered at
+    // the 26x32 default. A requested width must produce a proportionally smaller badge.
+    expect(fileBadgeHeight(FILE_BADGE_DEFAULT_WIDTH)).toBe(FILE_BADGE_BOX);
+    expect(fileBadgeHeight(20)).toBe(25);
+    expect(fileBadgeHeight(13)).toBe(16);
+    expect(fileBadgeHeight(52)).toBe(64);
+  });
+
+  it("fills the compact thumbnail slot exactly at the default width", () => {
+    // Why DEFAULT_WIDTH is 26: a default badge is exactly as tall as the 32px compact
+    // tile it sits in. A slot of 32 must therefore resolve to the default, unchanged.
+    expect(fileBadgeWidthForBox(FILE_BADGE_BOX)).toBe(FILE_BADGE_DEFAULT_WIDTH);
+  });
+
+  it("resolves a SMALLER slot to a smaller badge, not the default", () => {
+    // The reported bug: a sub-32 tile still rendered the 26x32 default — wider AND taller
+    // than its own tile. The requested slot now drives the badge.
+    expect(fileBadgeWidthForBox(30)).toBe(24);
+    expect(fileBadgeHeight(fileBadgeWidthForBox(30))).toBe(30);
+    expect(fileBadgeWidthForBox(24)).toBe(19);
+    expect(fileBadgeHeight(fileBadgeWidthForBox(24))).toBe(23);
+  });
+
+  it("never overflows its square slot, at any slot size", () => {
+    // The badge is taller than it is wide, so height is the binding dimension and the
+    // rounding in `fileBadgeHeight` can push a naive floor over the edge.
+    for (let box = 8; box <= 200; box++) {
+      const width = fileBadgeWidthForBox(box);
+      expect(width).toBeLessThanOrEqual(box);
+      expect(fileBadgeHeight(width)).toBeLessThanOrEqual(box);
+    }
+  });
+
+  it("grows monotonically with the slot", () => {
+    for (let box = 9; box <= 200; box++) {
+      expect(fileBadgeWidthForBox(box)).toBeGreaterThanOrEqual(fileBadgeWidthForBox(box - 1));
+    }
+  });
+});

package/src/file_badge_fit.ts

@@ -0,0 +1,34 @@
+/**
+ * `FileBadge` geometry — RN-free so it is unit-testable (a component file importing
+ * `react-native` cannot be loaded by Vitest).
+ *
+ * A `FileBadge`'s `size` is its WIDTH; every other dimension scales off it, so the badge
+ * has a FIXED aspect (26 × 32 at the default) and is TALLER than it is wide. A caller that
+ * owns a SQUARE slot — the thumbnail family, whose `size` is the tile side — therefore
+ * cannot pass its tile side through as a width: the badge would overflow the tile's
+ * bottom. `fileBadgeWidthForBox` converts a square slot to the width that fits it.
+ */
+
+/** The default badge width. A default badge is exactly `FILE_BADGE_BOX` tall. */
+export const FILE_BADGE_DEFAULT_WIDTH = 26;
+
+/** The height of a default-width badge — and the square slot it exactly fills. */
+export const FILE_BADGE_BOX = 32;
+
+/** The badge's height at a given width. The aspect is fixed. */
+export function fileBadgeHeight(width: number): number {
+  return Math.round((FILE_BADGE_BOX * width) / FILE_BADGE_DEFAULT_WIDTH);
+}
+
+/**
+ * The widest badge that fits inside a `box`×`box` square slot — height is the binding
+ * dimension, since the badge is taller than it is wide. `fileBadgeWidthForBox(32)` is
+ * `FILE_BADGE_DEFAULT_WIDTH`: the default badge fills the compact thumbnail slot exactly.
+ */
+export function fileBadgeWidthForBox(box: number): number {
+  let width = Math.max(1, Math.floor((box * FILE_BADGE_DEFAULT_WIDTH) / FILE_BADGE_BOX));
+  // Guard the rounding in `fileBadgeHeight`: the floored width can still round UP past
+  // the box by a pixel.
+  while (width > 1 && fileBadgeHeight(width) > box) width--;
+  return width;
+}

package/src/file_thumbnail.tsx

@@ -1,4 +1,5 @@
 import { FileBadge, resolveMime } from "./file_badge";
+import { fileBadgeWidthForBox } from "./file_badge_fit";
 import { fontFamilySemiBold } from "./text_utils";
 import { Text } from "./text";
 import { Icon, type IconName } from "./icon";
@@ -76,6 +77,9 @@ interface FileThumbnailProps {
   uploading?: boolean;
   /** Marks the file as a document TEMPLATE — adds a "TMPL" badge (any file type). */
   isTemplate?: boolean;
+  /** Accessible name for the tile — what pressing it DOES, when the raw filename isn't
+   *  the useful name ("Xem chứng từ"). Defaults to `file.filename`. */
+  accessibilityLabel?: string;
 }
 
 /**
@@ -84,6 +88,7 @@ interface FileThumbnailProps {
  */
 export function FileThumbnail(props: FileThumbnailProps) {
   const { file, size, onPress, onLongPress, onRemove, selected, uploading, isTemplate } = props;
+  const accessibilityLabel = props.accessibilityLabel ?? file.filename;
 
   const rootStyle =
     size !== undefined ? { width: size, height: size } : { width: "100%" as const, aspectRatio: 1 };
@@ -91,7 +96,7 @@ export function FileThumbnail(props: FileThumbnailProps) {
   if (isImageMimeType(file.mimeType)) {
     return (
       <View style={rootStyle}>
-        <ImageThumbnail file={file} size={size} onPress={onPress} onLongPress={onLongPress} />
+        <ImageThumbnail file={file} size={size} accessibilityLabel={accessibilityLabel} onPress={onPress} onLongPress={onLongPress} />
         {uploading && <UploadingOverlay size={size} />}
         {onRemove && <RemoveButton onPress={onRemove} />}
         {selected !== undefined && <SelectionOverlay selected={selected} />}
@@ -108,7 +113,7 @@ export function FileThumbnail(props: FileThumbnailProps) {
           mimeType={file.mimeType}
           size={size}
           isTemplate={isTemplate}
-          accessibilityLabel={file.filename}
+          accessibilityLabel={accessibilityLabel}
           onPress={onPress ?? (() => Linking.openURL(file.url))}
           onLongPress={onLongPress}
         />
@@ -126,6 +131,7 @@ export function FileThumbnail(props: FileThumbnailProps) {
           filename={file.filename}
           icon={mediaIcon}
           size={size}
+          accessibilityLabel={accessibilityLabel}
           onPress={onPress ?? (() => Linking.openURL(file.url))}
           onLongPress={onLongPress}
         />
@@ -135,6 +141,7 @@ export function FileThumbnail(props: FileThumbnailProps) {
           filename={file.filename}
           size={size}
           isTemplate={isTemplate}
+          accessibilityLabel={accessibilityLabel}
           onPress={onPress ?? (() => Linking.openURL(file.url))}
           onLongPress={onLongPress}
         />
@@ -176,6 +183,9 @@ const uploadingOverlayStyles = StyleSheet.create({
 
 interface DocumentBadgeProps {
   mimeType: string;
+  /** The square SLOT side the badge fills — the same unit as `DocumentCard`/`MediaCard`
+   *  `size` and the thumbnail tile it sits in. A `FileBadge` is TALLER than it is wide,
+   *  so the slot is converted to a fitting badge width; omit for the default 32px slot. */
   size?: number;
   isTemplate?: boolean;
   onPress?: () => void;
@@ -189,7 +199,7 @@ interface DocumentBadgeProps {
  * Compact two-tone file badge with document lines and colored label.
  */
 export function DocumentBadge(props: DocumentBadgeProps) {
-  const { mimeType, isTemplate, onPress, onLongPress, accessibilityLabel } = props;
+  const { mimeType, size, isTemplate, onPress, onLongPress, accessibilityLabel } = props;
   const { focusVisible, focusProps } = useFocusRing();
 
   return (
@@ -201,7 +211,11 @@ export function DocumentBadge(props: DocumentBadgeProps) {
       {...focusProps}
       style={focusVisible ? { boxShadow: FOCUS_RING, borderRadius: 6 } : undefined}
     >
-      <FileBadge mimeType={mimeType} isTemplate={isTemplate} />
+      <FileBadge
+        mimeType={mimeType}
+        size={size !== undefined ? fileBadgeWidthForBox(size) : undefined}
+        isTemplate={isTemplate}
+      />
     </Pressable>
   );
 }
@@ -214,6 +228,8 @@ interface DocumentCardProps {
   onPress?: () => void;
   onLongPress?: () => void;
   overlay?: React.ReactNode;
+  /** Accessible name for the tile. Defaults to `filename` (which the tile also shows). */
+  accessibilityLabel?: string;
 }
 
 /**
@@ -224,6 +240,7 @@ interface DocumentCardProps {
  */
 export function DocumentCard(props: DocumentCardProps) {
   const { mimeType, filename, size, isTemplate, onPress, onLongPress, overlay } = props;
+  const a11yLabel = props.accessibilityLabel ?? filename;
 
   const sizeStyle =
     size !== undefined
@@ -246,7 +263,7 @@ export function DocumentCard(props: DocumentCardProps) {
       onPress={onPress}
       onLongPress={onLongPress}
       accessibilityRole="button"
-      accessibilityLabel={filename}
+      accessibilityLabel={a11yLabel}
       {...focusProps}
     >
       <FileBadge mimeType={mimeType} size={badgeSize} isTemplate={isTemplate} />
@@ -267,6 +284,8 @@ interface MediaCardProps {
   onPress?: () => void;
   onLongPress?: () => void;
   overlay?: React.ReactNode;
+  /** Accessible name for the tile. Defaults to `filename` (which the card also shows). */
+  accessibilityLabel?: string;
 }
 
 /**
@@ -276,6 +295,7 @@ interface MediaCardProps {
  */
 export function MediaCard(props: MediaCardProps) {
   const { mimeType, filename, size, onPress, onLongPress, overlay, icon } = props;
+  const a11yLabel = props.accessibilityLabel ?? filename;
   const { label, color } = resolveMime(mimeType);
 
   const sizeStyle =
@@ -294,7 +314,7 @@ export function MediaCard(props: MediaCardProps) {
         onPress={onPress}
         onLongPress={onLongPress}
         accessibilityRole="button"
-        accessibilityLabel={filename}
+        accessibilityLabel={a11yLabel}
         {...focusProps}
       >
         <Icon name={icon} size={iconSize} color={colors.white} />
@@ -307,7 +327,7 @@ export function MediaCard(props: MediaCardProps) {
   const backdrop = iconSize + 20;
 
   return (
-    <Pressable style={[styles.documentCard, sizeStyle, focusVisible && { boxShadow: FOCUS_RING }]} onPress={onPress} onLongPress={onLongPress} accessibilityRole="button" accessibilityLabel={filename} {...focusProps}>
+    <Pressable style={[styles.documentCard, sizeStyle, focusVisible && { boxShadow: FOCUS_RING }]} onPress={onPress} onLongPress={onLongPress} accessibilityRole="button" accessibilityLabel={a11yLabel} {...focusProps}>
       {(state) => (
         <>
           <View style={[styles.mediaCardBody, { backgroundColor: color }]}>
@@ -342,10 +362,13 @@ interface ImageThumbnailProps {
   size?: number;
   onPress?: () => void;
   onLongPress?: () => void;
+  /** Accessible name for the tile. Defaults to `file.filename`. */
+  accessibilityLabel?: string;
 }
 
 function ImageThumbnail(props: ImageThumbnailProps) {
   const { file, size, onPress, onLongPress } = props;
+  const a11yLabel = props.accessibilityLabel ?? file.filename;
   const [useFallback, setUseFallback] = useState(false);
   const { focusVisible, focusProps } = useFocusRing();
 
@@ -358,7 +381,7 @@ function ImageThumbnail(props: ImageThumbnailProps) {
       : { width: "100%" as const, height: "100%" as const };
 
   return (
-    <Pressable onPress={onPress} onLongPress={onLongPress} accessibilityRole={onPress ? "button" : "image"} accessibilityLabel={file.filename} {...focusProps} style={[styles.imageThumbnail, sizeStyle, focusVisible && { boxShadow: FOCUS_RING }]}>
+    <Pressable onPress={onPress} onLongPress={onLongPress} accessibilityRole={onPress ? "button" : "image"} accessibilityLabel={a11yLabel} {...focusProps} style={[styles.imageThumbnail, sizeStyle, focusVisible && { boxShadow: FOCUS_RING }]}>
       {(state) => (
         <>
           <Image

package/src/follow_scroll.tsx

@@ -0,0 +1,58 @@
+import { useRef, type ReactNode } from "react";
+import { ScrollView, StyleProp, ViewStyle, type NativeScrollEvent, type NativeSyntheticEvent } from "react-native";
+
+export interface FollowScrollProps {
+  children: ReactNode;
+  /** The frame — put the height bound here (`maxHeight` / `height` / `flex`);
+   *  without one the container never overflows and there is nothing to follow. */
+  style?: StyleProp<ViewStyle>;
+  contentContainerStyle?: StyleProp<ViewStyle>;
+}
+
+// "At the bottom" tolerance: within this many px of the end still counts as
+// pinned, so sub-pixel scroll positions and streaming-growth rounding never
+// silently unpin the follow.
+const PIN_THRESHOLD = 40;
+
+/**
+ * A scroll container that FOLLOWS its growing content — pinned to the bottom, it
+ * keeps the newest content in view as children stream in (an `AgentRun` in a
+ * dialog, a log feed). Scrolling up UNPINS it so the human can read history while
+ * the content keeps growing; scrolling back to the bottom re-pins. Chat doesn't
+ * need this (its message list is inverted, which follows by construction) — this
+ * is for the plain top-down containers everywhere else: dialogs, drawers, panels.
+ */
+export function FollowScroll(props: FollowScrollProps) {
+  const { children, style, contentContainerStyle } = props;
+  const scrollRef = useRef<ScrollView>(null);
+  // Pinned state lives in a ref — it changes on every scroll tick and must never
+  // re-render the (streaming, already-busy) subtree.
+  const pinnedRef = useRef(true);
+
+  const followIfPinned = () => {
+    if (pinnedRef.current) scrollRef.current?.scrollToEnd({ animated: false });
+  };
+
+  const onScroll = (e: NativeSyntheticEvent<NativeScrollEvent>) => {
+    const { contentOffset, contentSize, layoutMeasurement } = e.nativeEvent;
+    const distanceFromBottom = contentSize.height - contentOffset.y - layoutMeasurement.height;
+    pinnedRef.current = distanceFromBottom < PIN_THRESHOLD;
+  };
+
+  return (
+    <ScrollView
+      ref={scrollRef}
+      style={style}
+      contentContainerStyle={contentContainerStyle}
+      // Content grew (a new part streamed in) or the frame resized (dialog
+      // re-measured) — both move the bottom edge, so both re-follow when pinned.
+      onContentSizeChange={followIfPinned}
+      onLayout={followIfPinned}
+      onScroll={onScroll}
+      scrollEventThrottle={16}
+      nestedScrollEnabled
+    >
+      {children}
+    </ScrollView>
+  );
+}

package/src/linked_record_box.tsx

@@ -1,11 +1,10 @@
 import { type ReactNode } from "react";
-import { View, Pressable, StyleSheet } from "react-native";
+import { View, StyleSheet } from "react-native";
 import { PressableRow } from "./pressable_row";
+import { PressDoor } from "./press_door";
 import { Text } from "./text";
 import { Icon, type IconName } from "./icon";
 import { colors } from "./colors";
-import { useFocusRing } from "./use_focus_ring";
-import { FOCUS_RING } from "./control_surface";
 
 interface LinkedRecordBoxProps {
   /** The linked record's kind glyph (building-2 for a company, file-text for a record…). */
@@ -38,13 +37,13 @@ interface LinkedRecordBoxProps {
  *
  * The a11y contract it enforces (the error-prone part, hence a primitive): a container with
  * interactive descendants must NEVER be `role="button"` (invalid HTML). So the box is a
- * role-less `PressableRow`, an empty absolutely-positioned door sibling carries the tab stop /
- * accessible name / focus ring, and the interior verbs lift above it via `zIndex`.
+ * role-less `PressableRow`, a `PressDoor` sibling carries the tab stop / accessible name /
+ * focus ring, and the interior verbs lift above it via `zIndex`.
  */
 export function LinkedRecordBox({ icon, name, subtitle, facts, factLabelWidth = 80, doorLabel, onOpen, actions }: LinkedRecordBoxProps) {
   return (
     <PressableRow onPress={onOpen} style={styles.box}>
-      <Door label={doorLabel} onPress={onOpen} />
+      <PressDoor accessibilityLabel={doorLabel} onPress={onOpen} />
       <View style={styles.identity}>
         <View style={styles.glyph}>
           <Icon name={icon} size={17} color={colors.zinc[600]} />
@@ -75,25 +74,8 @@ export function LinkedRecordBox({ icon, name, subtitle, facts, factLabelWidth =
   );
 }
 
-// The keyboard DOOR: an empty absolutely-positioned sibling beneath the box content — a
-// button must NOT wrap the box's interactive descendants, so the door alone carries the tab
-// stop, accessible name, and focus ring; mouse presses ride the PressableRow surface.
-function Door({ label, onPress }: { label: string; onPress: () => void }) {
-  const { focusVisible, focusProps } = useFocusRing();
-  return (
-    <Pressable
-      accessibilityRole="button"
-      accessibilityLabel={label}
-      onPress={onPress}
-      {...focusProps}
-      style={[styles.door, focusVisible ? { boxShadow: FOCUS_RING } : null]}
-    />
-  );
-}
-
 const styles = StyleSheet.create({
   box: { flexDirection: "column", alignItems: "stretch", borderWidth: 1, borderColor: colors.zinc[200], borderRadius: 10, paddingHorizontal: 16, paddingTop: 14, paddingBottom: 10, gap: 12 },
-  door: { position: "absolute", top: 0, right: 0, bottom: 0, left: 0, borderRadius: 10 },
   identity: { flexDirection: "row", alignItems: "center", gap: 10 },
   glyph: { width: 34, height: 34, borderRadius: 8, backgroundColor: colors.zinc[100], alignItems: "center", justifyContent: "center" },
   fact: { flexDirection: "row", gap: 10 },

package/src/press_door.tsx

@@ -0,0 +1,68 @@
+import { Pressable, StyleSheet } from "react-native";
+import { FOCUS_RING } from "./control_surface";
+import { useFocusRing } from "./use_focus_ring";
+
+export interface PressDoorProps {
+  /** Opens the thing the surface stands for — the same handler the surface presses. */
+  onPress: () => void;
+  /**
+   * REQUIRED. The door is EMPTY, so it has no text content to derive a name from —
+   * without a label it is a nameless button. Name the destination ("Open ORD-1042").
+   */
+  accessibilityLabel: string;
+  /** Focus-ring corner radius — match the surface the door spans. Default 10 (the register wash). */
+  radius?: number;
+}
+
+/**
+ * THE keyboard door: an empty, absolutely-positioned `Pressable` that carries the
+ * `role="button"` tab stop, the accessible name, and the focus ring for a pressable
+ * surface whose CONTENT can hold its own controls.
+ *
+ * A button must not contain interactive descendants — nesting `<button>` in `<button>`
+ * is invalid HTML (React hydration warning) and collapses the inner control's press and
+ * tab stop. So the door is never an ANCESTOR of the content: it is a SIBLING beneath it.
+ *
+ * Composition (the contract) — the role-less `PressableRow` takes the mouse and paints the
+ * hover wash, the door takes the keyboard, the content keeps its own controls:
+ * ```tsx
+ * <PressableRow onPress={open}>
+ *   <PressDoor onPress={open} accessibilityLabel="Open ORD-1042" />
+ *   <View style={{ zIndex: 1 }}>…cells, CTAs, overflow menus…</View>
+ * </PressableRow>
+ * ```
+ * The parent must establish the positioning context (`PressableRow` and any
+ * `position: "relative"` box do), and the in-flow content must lift above the door with
+ * `zIndex: 1` — an absolutely-positioned sibling paints AND hit-tests above in-flow
+ * content, which would otherwise swallow every nested control's press. (A negative z on
+ * the door instead would escape the row — no stacking context — and bury the focus ring
+ * under the card background.) With that, the door takes only the keyboard, the mouse
+ * rides the surface, and nested controls claim their own presses.
+ *
+ * Wrap the content in the pressable itself (`PressableHighlight`, `FileRow`'s door) ONLY
+ * when that content is non-interactive by construction.
+ *
+ * `TableRow` and `LinkedRecordBox` are the in-kit consumers.
+ */
+export function PressDoor({ onPress, accessibilityLabel, radius = 10 }: PressDoorProps) {
+  const { focusVisible, focusProps } = useFocusRing();
+  return (
+    <Pressable
+      accessibilityRole="button"
+      accessibilityLabel={accessibilityLabel}
+      onPress={onPress}
+      {...focusProps}
+      style={[styles.door, { borderRadius: radius }, focusVisible && { boxShadow: FOCUS_RING }]}
+    />
+  );
+}
+
+const styles = StyleSheet.create({
+  door: {
+    position: "absolute",
+    top: 0,
+    right: 0,
+    bottom: 0,
+    left: 0,
+  },
+});

package/src/pressable_highlight.tsx

@@ -63,6 +63,13 @@ export interface PressableHighlightProps extends PressableProps {
 /**
  * A pressable component that highlights when hovered and pressed.
  * It will darken the `backgroundColor` prop when hovered and pressed.
+ *
+ * It IS a button and it WRAPS its children — so its content must be non-interactive by
+ * construction. A row whose content carries its own controls (a CTA, a ⋯ menu, a
+ * checkbox, a `Link`) must not be built on it: a button cannot contain interactive
+ * descendants. Compose the role-less `PressableRow` + a `PressDoor` sibling instead —
+ * the surface takes the mouse, the door takes the keyboard, the controls stay their own
+ * tab stops (`TableRow` and `LinkedRecordBox` are the references).
  */
 export function PressableHighlight(props: PressableHighlightProps) {
   const {

package/src/table.tsx

@@ -8,15 +8,14 @@ import {
   type ReactNode,
   type ReactElement,
 } from "react";
-import { StyleSheet, View, Pressable, type ViewStyle } from "react-native";
+import { StyleSheet, View, type ViewStyle } from "react-native";
 import { Text } from "./text";
 import { colors } from "./colors";
 import { PressableRow } from "./pressable_row";
+import { PressDoor } from "./press_door";
 import { Divider } from "./divider";
 import { DetailRow } from "./detail_row";
 import { SortHeader, type SortState, type SortHeaderLabels } from "./sort_header";
-import { FOCUS_RING } from "./control_surface";
-import { useFocusRing } from "./use_focus_ring";
 import { COLUMN_GAP, ROW_GUTTER, computeTableFit, type TableFit, type TableFitColumn } from "./table_fit";
 
 /**
@@ -182,7 +181,7 @@ export type TableRowProps = {
 
 /**
  * A register row: a full-bleed `PressableRow` (its hover wash spans the whole row,
- * incl. the leading/trailing controls) holding the cells, with the door — the
+ * incl. the leading/trailing controls) holding the cells, with a `PressDoor` — the
  * keyboard-accessible `role="button"` open target — as an EMPTY absolutely-
  * positioned SIBLING beneath them, never their ancestor. A button must not
  * contain interactive descendants, and cells legitimately carry their own
@@ -209,7 +208,6 @@ export function TableRow(props: TableRowProps) {
     // the declared columns stay — same tolerance as the width mapping.
     .filter(({ column }) => ctx.stacked || column == null || ctx.visibleKeys.has(column.key))
     .map(({ cell, column }) => cloneElement(cell, { _column: column, _stacked: ctx.stacked }));
-  const { focusVisible, focusProps } = useFocusRing();
 
   const body = ctx.stacked ? (
     <View style={styles.stackedBody}>
@@ -254,18 +252,10 @@ export function TableRow(props: TableRowProps) {
   return (
     <PressableRow onPress={onPress} selected={selected} marked={marked} style={styles.row}>
       {!ctx.stacked && ctx.leading > 0 ? <View style={[styles.slot, { width: ctx.leading }]}>{leading}</View> : null}
-      {/* An absolutely-positioned sibling paints — and hit-tests — above in-flow
-          content, which would swallow every cell control's press; the slots lift
-          above it via zIndex 1 (z-index applies to flex items), so the door gets
-          only the keyboard. Negative z on the door instead would escape the row
-          (no stacking context) and bury the focus ring under the Card background. */}
-      <Pressable
-        accessibilityRole="button"
-        accessibilityLabel={accessibilityLabel}
-        onPress={onPress}
-        {...focusProps}
-        style={[styles.door, focusVisible && { boxShadow: FOCUS_RING }]}
-      />
+      {/* 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
+          matches the register wash. */}
+      <PressDoor onPress={onPress} accessibilityLabel={accessibilityLabel} />
       {ctx.stacked ? (
         body
       ) : (
@@ -348,17 +338,6 @@ const styles = StyleSheet.create({
     flexDirection: "row",
     paddingHorizontal: ROW_GUTTER,
   },
-  // The keyboard door: an empty overlay spanning the row — the tab stop + focus
-  // ring live here, the cells are its SIBLINGS (see TableRow's doc). Radius
-  // matches the register wash.
-  door: {
-    position: "absolute",
-    top: 0,
-    right: 0,
-    bottom: 0,
-    left: 0,
-    borderRadius: 10,
-  },
   cells: {
     flex: 1,
     flexDirection: "row",