@lotics/ui 28.3.1 → 29.3.0

package/src/file_row.tsx

@@ -9,8 +9,18 @@ import { useFocusRing } from "./use_focus_ring";
 export interface FileRowProps {
   /** The file / document name — the primary line. */
   name: string;
-  /** Secondary line: size, status, timestamp, etc. */
-  meta?: string;
+  /**
+   * Secondary line: size, status, timestamp — or a NODE, when the second line
+   * is itself carrying a change.
+   *
+   * A document set under review needs it: a file being RECLASSIFIED is the same
+   * bytes with a different filing ("Other" becomes "Certificate of origin"),
+   * and a file being SUPERSEDED wants the scan it displaces struck beneath it.
+   * Both are `DiffValue`s, and a string could only have described them in prose.
+   * A node renders OUTSIDE the muted single-line `Text` — that wrapper would
+   * clip it and its colour would fight the diff's own.
+   */
+  meta?: React.ReactNode;
   /** File type → the FileBadge glyph + color. Omit (with `placeholder`) for an
    *  expected-but-not-yet-provided document. */
   mimeType?: string;
@@ -25,6 +35,16 @@ export interface FileRowProps {
    *  control. An independently-interactive SIBLING: never swallowed by the row
    *  press (a button never nests in the door button). */
   trailing?: React.ReactNode;
+  /**
+   * Leading slot, BEFORE the badge — a `DiffMark` saying what happened to this
+   * document, a selection checkbox, a status dot.
+   *
+   * It sits outside the badge rather than on it because it must line up DOWN
+   * the list: a mark drawn over a 30px badge moves with the badge's size, and
+   * `sm` and `md` rows would stop agreeing. Give every row the same slot,
+   * filled or empty, or the names stop forming a column.
+   */
+  leading?: React.ReactNode;
   /**
    * Row weight. `"sm"` (default) is the compact attachment line — many files
    * scanned as a list. `"md"` is the DOCUMENT-DESK row: a taller badge and a
@@ -53,6 +73,7 @@ export function FileRow({
   isTemplate,
   onPress,
   trailing,
+  leading,
   size = "sm",
 }: FileRowProps) {
   const md = size === "md";
@@ -68,16 +89,22 @@ export function FileRow({
 
   const content = (
     <>
+      {leading}
       <FileBadge size={md ? 38 : 30} mimeType={mimeType} placeholder={placeholder} isTemplate={isTemplate} />
       <View style={styles.text}>
         <Text size="sm" weight="medium" numberOfLines={1}>
           {name}
         </Text>
-        {meta ? (
+        {/* A STRING keeps the muted single-line treatment; a node renders as
+            itself. Wrapping a node here would clip it at one line and tint it
+            muted, which is exactly wrong for a diff that has its own colour. */}
+        {meta == null || meta === "" ? null : typeof meta === "string" ? (
           <Text size="xs" color="muted" numberOfLines={1}>
             {meta}
           </Text>
-        ) : null}
+        ) : (
+          meta
+        )}
       </View>
     </>
   );
@@ -117,19 +144,44 @@ export function FileRow({
   );
 }
 
+/**
+ * THE ROW BEAT, owned in one place.
+ *
+ * `sm` used to have no minimum and no vertical padding at all, so a static row
+ * was as tall as its own contents — 37px measured — while the same component
+ * with an `onPress` came out at 49, because only the pressable variant carried
+ * padding for its hover wash. Whether a row was a DOOR decided how tall it was,
+ * which is two owners for one property that happened never to be compared.
+ *
+ * 37 was also under every other row beat in the kit — `DetailRow` 40, the
+ * `TableRow` 52, this component's own `md` 56 — which is what "squeezed"
+ * literally was: a file line packed tighter than any list it sits beside.
+ */
+const ROW_MIN_HEIGHT = 48;
+const ROW_PAD_Y = 6;
+
 const styles = StyleSheet.create({
-  row: { flexDirection: "row", alignItems: "center", gap: 12 },
+  row: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 12,
+    minHeight: ROW_MIN_HEIGHT,
+    // The pressable variant's padding too, so the badge sits at the same height
+    // in both and a list mixing them keeps one baseline.
+    paddingVertical: ROW_PAD_Y,
+  },
   pressableRow: {
     flexDirection: "row",
     alignItems: "center",
     gap: 12,
+    minHeight: ROW_MIN_HEIGHT,
     // Negative horizontal margin cancels the padding for the CONTENT's position
     // (badge stays aligned with static rows / the container edge) while the hover
     // wash bleeds 8px outward into the parent's padding — a hit area with no
     // layout shift. The parent is expected to have ≥8px horizontal padding.
     marginHorizontal: -8,
     paddingHorizontal: 8,
-    paddingVertical: 6,
+    paddingVertical: ROW_PAD_Y,
     borderRadius: 8,
     ...({ transitionDuration: "0.1s", transitionProperty: "background-color" } as object),
   },

package/src/file_thumbnail.tsx

@@ -21,6 +21,7 @@ import {
   Linking,
 } from "react-native";
 import { isImageMimeType, isVideoMimeType, isAudioMimeType } from "./mime";
+import { DiffMark, type DiffKind } from "./diff_mark";
 
 export const THUMBNAIL_SIZE = 96;
 export const COMPACT_THUMBNAIL_SIZE = 32;
@@ -86,14 +87,67 @@ interface FileThumbnailProps {
   /** 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;
+  /**
+   * WHAT A PROPOSAL DOES TO THIS TILE — a corner mark for a document set under
+   * review, rendered as a grid rather than as a list.
+   *
+   * Top-LEFT because it is the one corner nothing else claims (remove sits
+   * top-right, selection bottom-right, the uploading scrim covers everything),
+   * and because it puts the mark where the row list already puts it.
+   *
+   * The disc rides a white RING: a tile's ground is an arbitrary photo, and a
+   * pale tint over a pale scan is not a mark, it is a smudge. `removed`
+   * additionally fades the tile BODY — the grid's way of saying a document is
+   * on its way off the record — while the mark itself stays at full strength,
+   * since a faded mark is the exact smudge the ring exists to prevent.
+   *
+   * Ignored on a COMPACT tile (≤ 32px): a 22px disc on a 32px tile is not a
+   * corner mark, it is the tile. A compact strip lives inside a row, and that
+   * row is where its change belongs.
+   *
+   * A grid expresses MEMBERSHIP (this document is arriving, that one is going)
+   * and expresses PAIRING badly: a 96px tile has nowhere to say which file a
+   * replacement supersedes. Use `FileRow` for a set where things are being
+   * replaced rather than added and removed.
+   */
+  diff?: DiffKind;
 }
 
+/**
+ * The tile's diff mark — the same disc the rows use, on a white RING.
+ *
+ * The ring rather than the disc alone because a tile's ground is an arbitrary
+ * photo, and a pale tint over a pale scan is a smudge. It is circular rather
+ * than a rounded square: two shapes for one mark is exactly the inconsistency
+ * the disc exists to end.
+ */
+function DiffCorner({ kind }: { kind: DiffKind }) {
+  if (kind === "unchanged") return null;
+  return (
+    <View style={diffCornerStyles.chip} pointerEvents="none">
+      <DiffMark kind={kind} />
+    </View>
+  );
+}
+
+const diffCornerStyles = StyleSheet.create({
+  chip: {
+    position: "absolute",
+    top: 4,
+    left: 4,
+    zIndex: 2,
+    backgroundColor: colors.white,
+    borderRadius: 999,
+    padding: 2,
+  },
+});
+
 /**
  * Displays a file as a square thumbnail.
  * Works with any file source via DisplayFile interface.
  */
 export function FileThumbnail(props: FileThumbnailProps) {
-  const { file, size, onPress, onLongPress, onRemove, selected, uploading, isTemplate, disablePress } = props;
+  const { file, size, onPress, onLongPress, onRemove, selected, uploading, isTemplate, disablePress, diff } = props;
   const accessibilityLabel = props.accessibilityLabel ?? file.filename;
   // A tile with no `onPress` still OPENS the file — a useful default for a bare
   // thumbnail in a list or a gallery. But a caller that said `disablePress`
@@ -106,13 +160,34 @@ export function FileThumbnail(props: FileThumbnailProps) {
   const rootStyle =
     size !== undefined ? { width: size, height: size } : { width: "100%" as const, aspectRatio: 1 };
 
+  // A tile ≤ 32px is a badge in a strip, not a card: a 22px mark would swallow
+  // it. The row or cell holding the strip carries the change instead.
+  const compact = size !== undefined && size <= COMPACT_THUMBNAIL_SIZE;
+  const mark = diff === undefined || compact ? null : <DiffCorner kind={diff} />;
+
+  /**
+   * A document on its way OFF the record reads as leaving, and the fade says
+   * that across the whole tile — which is what a grid is scanned by.
+   *
+   * It wraps the BODY rather than the root on purpose. `opacity` cascades to
+   * the entire subtree, so on the root it faded the corner mark too, at exactly
+   * the moment the mark has the most to say. That is also the dimming
+   * `DiffMark`'s ink was darkened for; putting the mark inside it would have
+   * spent that margin for nothing.
+   */
+  const body = (node: React.ReactNode) =>
+    diff === "removed" ? <View style={styles.fadedBody}>{node}</View> : node;
+
   if (isImageMimeType(file.mimeType)) {
     return (
       <View style={rootStyle}>
-        <ImageThumbnail file={file} size={size} accessibilityLabel={accessibilityLabel} onPress={press} onLongPress={onLongPress} />
+        {body(
+          <ImageThumbnail file={file} size={size} accessibilityLabel={accessibilityLabel} onPress={press} onLongPress={onLongPress} />,
+        )}
         {uploading && <UploadingOverlay size={size} />}
         {onRemove && <RemoveButton onPress={onRemove} />}
         {selected !== undefined && <SelectionOverlay selected={selected} />}
+        {mark}
       </View>
     );
   }
@@ -122,46 +197,52 @@ export function FileThumbnail(props: FileThumbnailProps) {
   if (size !== undefined && size <= COMPACT_THUMBNAIL_SIZE && mediaIcon === undefined) {
     return (
       <View style={rootStyle}>
-        <DocumentBadge
-          mimeType={file.mimeType}
-          size={size}
-          isTemplate={isTemplate}
-          accessibilityLabel={accessibilityLabel}
-          onPress={pressOrOpen}
-          onLongPress={onLongPress}
-        />
+        {body(
+          <DocumentBadge
+            mimeType={file.mimeType}
+            size={size}
+            isTemplate={isTemplate}
+            accessibilityLabel={accessibilityLabel}
+            onPress={pressOrOpen}
+            onLongPress={onLongPress}
+          />,
+        )}
         {uploading && <UploadingOverlay size={size} />}
         {onRemove && <RemoveButton onPress={onRemove} />}
+        {mark}
       </View>
     );
   }
 
   return (
     <View style={rootStyle}>
-      {mediaIcon !== undefined ? (
-        <MediaCard
-          mimeType={file.mimeType}
-          filename={file.filename}
-          icon={mediaIcon}
-          size={size}
-          accessibilityLabel={accessibilityLabel}
-          onPress={pressOrOpen}
-          onLongPress={onLongPress}
-        />
-      ) : (
-        <DocumentCard
-          mimeType={file.mimeType}
-          filename={file.filename}
-          size={size}
-          isTemplate={isTemplate}
-          accessibilityLabel={accessibilityLabel}
-          onPress={pressOrOpen}
-          onLongPress={onLongPress}
-        />
+      {body(
+        mediaIcon !== undefined ? (
+          <MediaCard
+            mimeType={file.mimeType}
+            filename={file.filename}
+            icon={mediaIcon}
+            size={size}
+            accessibilityLabel={accessibilityLabel}
+            onPress={pressOrOpen}
+            onLongPress={onLongPress}
+          />
+        ) : (
+          <DocumentCard
+            mimeType={file.mimeType}
+            filename={file.filename}
+            size={size}
+            isTemplate={isTemplate}
+            accessibilityLabel={accessibilityLabel}
+            onPress={pressOrOpen}
+            onLongPress={onLongPress}
+          />
+        ),
       )}
       {uploading && <UploadingOverlay size={size} />}
       {onRemove && <RemoveButton onPress={onRemove} />}
       {selected !== undefined && <SelectionOverlay selected={selected} />}
+      {mark}
     </View>
   );
 }
@@ -456,6 +537,8 @@ function SelectionOverlay({ selected }: { selected: boolean }) {
 // =============================================================================
 
 const styles = StyleSheet.create({
+  // Fills the tile so the fade covers the whole body and nothing reflows.
+  fadedBody: { width: "100%", height: "100%", opacity: 0.45 },
   documentCard: {
     borderRadius: 10,
     backgroundColor: colors.white,

package/src/file_thumbnail_grid.tsx

@@ -15,6 +15,7 @@ import { View, Pressable, StyleSheet, type ViewStyle } from "react-native";
 import { Text } from "./text";
 import { colors } from "./colors";
 import { FileThumbnail, type DisplayFile, THUMBNAIL_SIZE, COMPACT_THUMBNAIL_SIZE } from "./file_thumbnail";
+import { type DiffKind } from "./diff_mark";
 import { FOCUS_RING } from "./control_surface";
 import { useFocusRing } from "./use_focus_ring";
 
@@ -171,12 +172,22 @@ export interface FileThumbnailGridProps {
   disablePress?: boolean;
   /** Selected file IDs — renders a selection overlay on those thumbnails. */
   selectedIds?: ReadonlySet<string>;
+  /**
+   * What a proposal does to each file, keyed by id — a corner mark on the tile
+   * and a fade on anything being removed. Keyed the same way `selectedIds` is,
+   * so a grid under review is the SAME grid with one more map passed in.
+   *
+   * A grid says MEMBERSHIP well and PAIRING badly: there is nowhere on a 96px
+   * tile to name the file a replacement supersedes. A set where documents are
+   * being replaced rather than added and removed wants `FileRow`.
+   */
+  diffs?: ReadonlyMap<string, DiffKind>;
   onFilePress?: (file: DisplayFile) => void;
   onRemove?: (id: string) => void;
 }
 
 export function FileThumbnailGrid(props: FileThumbnailGridProps) {
-  const { files, selectedIds, onFilePress, onRemove, disablePress, ...layout } = props;
+  const { files, selectedIds, diffs, onFilePress, onRemove, disablePress, ...layout } = props;
   return (
     <ThumbnailGrid
       {...layout}
@@ -187,6 +198,7 @@ export function FileThumbnailGrid(props: FileThumbnailGridProps) {
         <FileThumbnail
           file={file}
           size={size}
+          diff={diffs?.get(file.id)}
           onPress={disablePress || !onFilePress ? undefined : () => onFilePress(file)}
           // Withholding `onPress` is NOT enough: a tile with none falls back to
           // opening the file, so it stays a button and a tab stop. The prop has

package/src/finding.tsx

@@ -47,9 +47,8 @@ export interface FindingProps {
  * observation, a briefing item. Good defaults (severity word, title, detail,
  * the PROMINENT metric, `Sources` chips) with a `children` slot for any
  * extra composition. Display-only: a finding informs the verdict the host
- * records; it decides nothing itself. Stack several most-severe first —
- * inside a `ChangeReview` wrap each in a display-only `Change` (the family's
- * dividers apply); standalone, separate them yourself.
+ * records; it decides nothing itself. Stack several most-severe first,
+ * separated by a `Divider`.
  */
 export function Finding(props: FindingProps) {
   const words = useLoticsLocale().finding;

package/src/inline_slot.tsx

@@ -0,0 +1,58 @@
+import { StyleSheet, View, type StyleProp, type ViewStyle } from "react-native";
+import { type ReactNode } from "react";
+import { CONTROL_RADIUS } from "./control_surface";
+import { INLINE_CONTROL_HEIGHT } from "./inline_edit";
+
+export interface InlineSlotProps {
+  /** Whatever sits in the value column — a `DiffValue`, a chip, a pair. */
+  children: ReactNode;
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * ANY node placed on the INLINE-CONTROL GRID — the box an `Inline*` editor
+ * draws, minus the editor.
+ *
+ * A record's value column mixes editors with things that are not editors: a
+ * computed total, a synced value, a proposed change. The editors are 40px tall
+ * with 8px of horizontal padding inside a 1px border, and their text therefore
+ * sits 9px in from the cell edge and centred in a 40px band. Anything rendered
+ * raw beside them starts at the cell edge, 20px tall, at the top — so the value
+ * column quietly acquires TWO left edges and two baselines, and `DetailRow`'s
+ * label (which pads down to meet a control) agrees with one kind of row and not
+ * the other.
+ *
+ * That is not a cosmetic drift. The column is the only thing telling a reader
+ * these values belong to one record, and it stops reading as a column.
+ *
+ * `InlineStatic` is the STRING case of this and composes it. Reach for the slot
+ * directly when the value is a node — which a review surface always is, since a
+ * proposed value is a `DiffValue` sitting where its editor would be.
+ *
+ * NOT for a table cell: a `Table` sets its own row rhythm, and a 40px control
+ * band inside one only makes the rows taller.
+ */
+export function InlineSlot({ children, style }: InlineSlotProps) {
+  return <View style={[styles.box, style]}>{children}</View>;
+}
+
+const styles = StyleSheet.create({
+  // Matches `inline_edit`'s view box exactly (height, radius, padding, 1px
+  // transparent border) so the content's baseline aligns with the editors —
+  // minus the FocusRingPressable, so it never reads as an interactive control.
+  box: {
+    minHeight: INLINE_CONTROL_HEIGHT,
+    borderRadius: CONTROL_RADIUS,
+    borderWidth: 1,
+    borderColor: "transparent",
+    paddingHorizontal: 8,
+    // The editors' vertical padding too, not just the horizontal. A single line
+    // hides its absence — the box is `minHeight` 40 and the text is ~20, so both
+    // sides land on 40 whether or not this exists — but an auto-growing input
+    // sizes itself to content PLUS its padding and border, so from the SECOND
+    // line on, a value without this sits ~14px shorter than the input that
+    // replaces it. Matching by coincidence at one line is not matching.
+    paddingVertical: 8,
+    justifyContent: "center",
+  },
+});

package/src/inline_static.tsx

@@ -1,8 +1,8 @@
-import { StyleSheet, View } from "react-native";
+import { StyleSheet } from "react-native";
 import { Text } from "./text";
 import { colors } from "./colors";
-import { CONTROL_RADIUS } from "./control_surface";
-import { INLINE_CONTROL_HEIGHT, inlineValueTextStyle } from "./inline_edit";
+import { inlineValueTextStyle } from "./inline_edit";
+import { InlineSlot } from "./inline_slot";
 
 export interface InlineStaticProps {
   /** The value to show. Empty → `placeholder` (default "—"). */
@@ -45,7 +45,7 @@ export function InlineStatic(props: InlineStaticProps) {
   const isEmpty = value.length === 0;
   const display = isEmpty ? (placeholder ?? "—") : value;
   return (
-    <View style={styles.box}>
+    <InlineSlot>
       <Text
         numberOfLines={multiline ? undefined : 1}
         tabular={tabular}
@@ -56,28 +56,10 @@ export function InlineStatic(props: InlineStaticProps) {
       >
         {display}
       </Text>
-    </View>
+    </InlineSlot>
   );
 }
 
 const styles = StyleSheet.create({
-  // Matches `inline_edit`'s view box exactly (height, radius, padding, 1px
-  // transparent border) so the value's baseline aligns with the editors — minus
-  // the FocusRingPressable, so it never reads as an interactive control.
-  box: {
-    minHeight: INLINE_CONTROL_HEIGHT,
-    borderRadius: CONTROL_RADIUS,
-    borderWidth: 1,
-    borderColor: "transparent",
-    paddingHorizontal: 8,
-    // The editors' vertical padding too, not just the horizontal. A single line
-    // hides its absence — the box is `minHeight` 40 and the text is ~20, so both
-    // sides land on 40 whether or not this exists — but an auto-growing input
-    // sizes itself to content PLUS its padding and border, so from the SECOND
-    // line on, a value without this sits ~14px shorter than the input that
-    // replaces it. Matching by coincidence at one line is not matching.
-    paddingVertical: 8,
-    justifyContent: "center",
-  },
   placeholder: { color: colors.zinc[400] },
 });

package/src/locale.tsx

@@ -94,27 +94,17 @@ export interface LoticsLocale {
   suggestionChip: { add: (label: string) => string; dismiss: string };
   /** `Confidence`: the full level phrase ("High confidence" …). */
   confidence: ConfidenceLabels;
-  /** `Finding`: the severity badge word ("Critical" …). */
   /** `RemainderMeter`: the applied / remaining / over / exact captions. */
   remainderMeter: Required<RemainderMeterLabels>;
-  /** `ChangeReview` (+ `ChangeReviewActions`): the review-card chrome — the
-   *  Keep/Drop verdicts, Undo, the Applied/Discarded tags, the kept-counter,
-   *  the title, and the commit-bar Accept-all / Discard. */
+  /** `Finding`: the severity words + the comparison delta caption. */
   finding: FindingLabels;
-  changeReview: {
-    title: string;
-    accept: string;
-    reject: string;
-    undo: string;
-    keptCount: (kept: number, total: number) => string;
-    acceptAll: string;
-    discard: string;
-    apply: string;
-    recommended: string;
-    customValue: string;
-    opAdd: string;
-    opEdit: string;
-    opRemove: string;
+  /** `DiffMark`: what a proposal does to a row — the accessible word each mark
+   *  announces, since the meaning may never rest on colour alone. */
+  diff: {
+    added: string;
+    changed: string;
+    removed: string;
+    unchanged: string;
   };
   /** `DateRangeFilterField` (and the `DateFilter` panel it wraps): presets,
    *  from/to, the footer Clear/Done, the trigger placeholder, and the time-field
@@ -273,20 +263,11 @@ export const en: LoticsLocale = {
     exact: "Fully applied",
   },
   finding: { critical: "Critical", warning: "Warning", info: "Note", positive: "On track", difference: "Difference" },
-  changeReview: {
-    title: "Suggested edits",
-    accept: "Keep",
-    reject: "Drop",
-    undo: "Undo",
-    keptCount: (kept, total) => `${kept} of ${total} kept`,
-    acceptAll: "Keep all",
-    discard: "Discard",
-    apply: "Apply",
-    recommended: "AI pick",
-    customValue: "Type another value",
-    opAdd: "Add",
-    opEdit: "Edit",
-    opRemove: "Delete",
+  diff: {
+    added: "Added",
+    changed: "Changed",
+    removed: "Removed",
+    unchanged: "Unchanged",
   },
   dateRange: {
     year: "Year", month: "Month", day: "Day", hour: "Hour", minute: "Minute", dayPeriod: "AM/PM",
@@ -437,20 +418,11 @@ export const vi: LoticsLocale = {
     exact: "Đã phân bổ đủ",
   },
   finding: { critical: "Nghiêm trọng", warning: "Cảnh báo", info: "Ghi chú", positive: "Đúng tiến độ", difference: "Chênh lệch" },
-  changeReview: {
-    title: "Đề xuất chỉnh sửa",
-    accept: "Giữ",
-    reject: "Bỏ",
-    undo: "Hoàn tác",
-    keptCount: (kept, total) => `Đã giữ ${kept}/${total}`,
-    acceptAll: "Giữ tất cả",
-    discard: "Bỏ hết",
-    apply: "Áp dụng",
-    recommended: "AI đề xuất",
-    customValue: "Nhập giá trị khác",
-    opAdd: "Thêm",
-    opEdit: "Sửa",
-    opRemove: "Xóa",
+  diff: {
+    added: "Thêm mới",
+    changed: "Thay đổi",
+    removed: "Xóa",
+    unchanged: "Giữ nguyên",
   },
   dateRange: {
     year: "Năm", month: "Tháng", day: "Ngày", hour: "Giờ", minute: "Phút", dayPeriod: "SA/CH",

package/src/mime.ts

@@ -52,3 +52,79 @@ export function isPreviewableMimeType(mimeType: string): boolean {
     isDocxMimeType(mimeType)
   );
 }
+
+/** A MIME type without its parameters (`text/csv; charset=utf-8` → `text/csv`). */
+function normalizeMimeType(mimeType: string): string {
+  return mimeType.split(";")[0]!.trim().toLowerCase();
+}
+
+/**
+ * Types that carry no information — a sender that declined to classify the
+ * bytes. The empty string is only the most obvious one: an OS clipboard or drag
+ * routinely hands a file over as `application/octet-stream` instead, which is
+ * the same statement made in a way that LOOKS like an answer.
+ */
+const GENERIC_MIME_TYPES: ReadonlySet<string> = new Set([
+  "",
+  "application/octet-stream",
+  "binary/octet-stream",
+  "application/binary",
+  "application/unknown",
+]);
+
+/**
+ * Extension → MIME, for the document and image formats an intake surface names.
+ * A `Map`, not an object literal, so a file named `x.constructor` looks up a
+ * miss rather than `Object.prototype`'s member.
+ */
+const MIME_BY_EXTENSION: ReadonlyMap<string, string> = new Map([
+  ["pdf", "application/pdf"],
+  ["png", "image/png"],
+  ["jpg", "image/jpeg"],
+  ["jpeg", "image/jpeg"],
+  ["gif", "image/gif"],
+  ["webp", "image/webp"],
+  ["avif", "image/avif"],
+  ["bmp", "image/bmp"],
+  ["svg", "image/svg+xml"],
+  ["tif", "image/tiff"],
+  ["tiff", "image/tiff"],
+  ["heic", "image/heic"],
+  ["heif", "image/heif"],
+  ["csv", "text/csv"],
+  ["tsv", "text/tab-separated-values"],
+  ["txt", "text/plain"],
+  ["xml", "application/xml"],
+  ["json", "application/json"],
+  ["zip", "application/zip"],
+  ["xlsx", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"],
+  ["xls", "application/vnd.ms-excel"],
+  ["docx", "application/vnd.openxmlformats-officedocument.wordprocessingml.document"],
+  ["doc", "application/msword"],
+]);
+
+/** What a filename's extension says the file is, or `""` when it says nothing. */
+function mimeTypeFromFileName(name: string): string {
+  const dot = name.lastIndexOf(".");
+  // `dot <= 0` also rejects a dotfile (`.pdf` is a NAME, not an extension);
+  // `length - 1` rejects a trailing dot.
+  if (dot <= 0 || dot === name.length - 1) return "";
+  return MIME_BY_EXTENSION.get(name.slice(dot + 1).toLowerCase()) ?? "";
+}
+
+/**
+ * The type to TREAT content as, given what its sender declared and what it is
+ * called. An honestly-declared type is never second-guessed — only an
+ * uninformative one is resolved, and only from the filename, falling back to
+ * the declaration when the extension is unrecognized too.
+ *
+ * Mirrors `resolveMimeType` in `@lotics/shared/file_type`, which is what the
+ * server stores. The kit cannot import it (`primitives_purity.test.ts` keeps
+ * `src/` free of `@lotics/shared`), so `mime_parity.test.ts` asserts the two
+ * agree instead of trusting that they will.
+ */
+export function resolveMimeType(declaredMimeType: string, filename: string): string {
+  const declared = normalizeMimeType(declaredMimeType);
+  if (!GENERIC_MIME_TYPES.has(declared)) return declared;
+  return mimeTypeFromFileName(filename) || declared;
+}

package/src/result_header.tsx

@@ -5,7 +5,7 @@ import { Icon, type IconName } from "./icon";
 import { Text, type HeadingLevel } from "./text";
 
 /**
- * Result header — the strip that opens the POST-SAVE RECEIPT. `ChangeReview` gates a proposal
+ * Result header — the strip that opens the POST-SAVE RECEIPT. A review surface gates a proposal
  * BEFORE it applies; this header opens the receipt for what a save-direct run
  * ALREADY CREATED. The receipt states the outcome and routes — it never edits
  * (correction happens through the record's ordinary verbs, on the record):