@lotics/ui 41.1.0 → 41.4.0

package/examples/tpl_record.tsx

@@ -1,20 +1,24 @@
 import { Fragment, useEffect, useRef, useState, type ReactNode, useMemo } from "react";
 import { Pressable, ScrollView, View } from "react-native";
 import { Text } from "@lotics/ui/text";
-import { colors } from "@lotics/ui/colors";
+import { colors, solid } from "@lotics/ui/colors";
 import { DRAWER_GUTTER } from "@lotics/ui/drawer";
 import { Button } from "@lotics/ui/button";
 import { BackButton } from "@lotics/ui/back_button";
 import { Divider } from "@lotics/ui/divider";
 import { Link } from "@lotics/ui/link";
-import { Icon } from "@lotics/ui/icon";
+import { Icon, type IconName } from "@lotics/ui/icon";
+import { Timeline, type TimelineItem } from "@lotics/ui/timeline";
+import { MediaPlayer } from "@lotics/ui/media_player";
+import { Markdown } from "@lotics/ui/markdown";
+import { TextDisclosure } from "@lotics/ui/text_disclosure";
 import { TextLink } from "@lotics/ui/text_link";
 import { Alert } from "@lotics/ui/alert";
 import type { PickerOption } from "@lotics/ui/picker";
 import { Combobox, ComboboxInput, ComboboxContent } from "@lotics/ui/combobox";
 import { DetailRow, DetailTable } from "@lotics/ui/detail_row";
 import { Callout, CalloutText } from "@lotics/ui/callout";
-import { Section, SectionHeading, SectionHeadingTitle, Subsection, SubsectionHeading, SubsectionHeadingTitle } from "@lotics/ui/section_heading";
+import { Section, SectionHeading, SectionHeadingTitle, SectionHeadingMeta, Subsection, SubsectionHeading, SubsectionHeadingTitle } from "@lotics/ui/section_heading";
 import { SectionStack, SubsectionStack } from "@lotics/ui/section_stack";
 import { Checklist, ChecklistActions, ChecklistGroup, ChecklistItem, ChecklistNote } from "@lotics/ui/checklist";
 import { DateStamp } from "@lotics/ui/date_stamp";
@@ -50,6 +54,10 @@ import { FormField } from "@lotics/ui/form_field";
 import { TextInputField } from "@lotics/ui/text_input_field";
 import { FileThumbnail, type DisplayFile } from "@lotics/ui/file_thumbnail";
 import { FileThumbnailGrid } from "@lotics/ui/file_thumbnail_grid";
+import { MemberChip } from "@lotics/ui/member_chip";
+import { WaveAvatar } from "@lotics/ui/wave_avatar";
+import { Inset } from "@lotics/ui/inset";
+import { isImageMimeType } from "@lotics/ui/mime";
 import { FileGalleryModal } from "@lotics/ui/file_gallery_modal";
 import { DangerZone } from "@lotics/ui/danger_zone";
 import { FileRow } from "@lotics/ui/file_row";
@@ -298,6 +306,578 @@ const PRIORITY_DOT: Record<string, string> = {
   rush: colors.amber[500],
 };
 
+// ── ACTIVITY — what has been SAID with the other party, in the order it
+// happened. Every entry answers the same four questions (what came of it, which
+// way, over what, when) and then carries a BODY whose shape depends on what the
+// entry IS: a call has audio, a demo has video, an email has a subject, a note
+// has only its own text.
+//
+// One row anatomy, one varying body — never a row type per medium. The four
+// invariants are what makes the feed scannable; a per-medium row would put the
+// same fact in four places and let them drift.
+type ActivityKind = "call" | "video" | "email" | "message" | "note";
+
+interface ActivityEntry {
+  key: string;
+  kind: ActivityKind;
+  /**
+   * What came of it, in the reader's words. THIS is the row — see the anatomy
+   * note at the section.
+   *
+   * OPTIONAL, because a feed fills from more than one direction. A person writes
+   * an entry; an automation also files one the instant a recording lands, and an
+   * extraction files one off a screenshot. Those arrive with no words in them,
+   * and the row has to say so rather than borrow a phrase from the enums.
+   */
+  gist?: string;
+  direction: "in" | "out";
+  /** The medium as a person would say it, not an enum: "Zalo", "Google Meet". */
+  over: string;
+  when: string;
+  /**
+   * WHO put this here — and this feed has two kinds of author, so the type has
+   * two shapes. A person gets a `MemberChip`; an automation, an extraction or an
+   * agent gets `WaveAvatar`, the kit's mark for a non-human identity. Modelling
+   * both as one string forces the surface to give a recording bot a face and two
+   * initials, which is a small fabrication every reader notices and no test
+   * catches.
+   */
+  by: { kind: "member"; name: string; image?: string } | { kind: "system"; name: string };
+  /** An unanswered outreach is a real state and reads differently from a reply. */
+  awaiting?: boolean;
+
+  // ── THE BODY IS A SET OF BLOCKS, NOT A SHAPE PER KIND.
+  //
+  // Every field below is optional and any combination is legal, because what an
+  // entry CARRIES is independent of what it IS: a call may arrive as a recording
+  // alone, gain a transcript minutes later and a summary after that; an email
+  // carries a subject, prose and attachments; a note carries prose and nothing
+  // else. A shape per kind would put the same block in five places and let them
+  // drift — and the sixth kind, the one nobody has thought of yet, would need a
+  // sixth. `kind` survives only to pick the ROW's glyph and the media element.
+  //
+  // The blocks, in the order they render:
+
+  /** The exchange itself, when it was recorded. `kind` picks audio vs video. */
+  media?: { src: string; label: string };
+  /** VERBATIM and long, folded behind its own toggle: it is the SOURCE a summary
+   *  was made from — read rarely, and in full when it is read at all. */
+  transcript?: string;
+  /**
+   * Anyone on it the row does not ALREADY name — the other addresses on an email
+   * header, and nothing else.
+   *
+   * Two rules, both learned by getting this wrong. It must be CAPTURABLE: a
+   * call's attendees are stored nowhere, so a line naming them can only be
+   * invented, and a block with no source teaches app authors to fabricate one.
+   * And it must be ADDITIVE: the record IS the counterparty, the supporting line
+   * gives the direction and the footer names who logged it, so "From <them>, to
+   * <us>" is three facts the row already carries. What is left is the third
+   * party — which is the entire value of the block.
+   */
+  participants?: string;
+  /** An email's subject — the one thing an email has that nothing else does. */
+  subject?: string;
+  /** Prose a PERSON wrote: an email body, a note. Markdown. */
+  body?: string;
+  /** Prose a MODEL wrote. Separate from `body` rather than a flag on it, because
+   *  one entry routinely holds both — a rep's own note and the machine's reading
+   *  of the same call — and they are different claims that must not merge. */
+  bodyByAi?: string;
+  files?: DisplayFile[];
+  /** Where it happened, when that is somewhere the reader can open — a post, a
+   *  thread, a ticket. */
+  sourceUrl?: string;
+}
+
+// A note somebody typed in FULL rather than summarising — the realistic worst
+// case for a feed, and the one a fixture of tidy one-liners never produces. It
+// is here so the template exercises `Timeline`'s label clamp and the drill-down
+// that pairs with it; unclamped, prose this length drew a 180px row and dragged
+// the disc off the line it names.
+// A self-contained SVG so the capture tiles render with no network.
+const img = (label: string, fill: string) =>
+  "data:image/svg+xml," +
+  encodeURIComponent(
+    `<svg xmlns="http://www.w3.org/2000/svg" width="320" height="240"><rect width="320" height="240" fill="${fill}"/><text x="160" y="128" font-family="sans-serif" font-size="20" fill="white" text-anchor="middle">${label}</text></svg>`,
+  );
+
+// VERBATIM, and interleaved the way a real diarised transcript is — short turns,
+// a name per line, no structure to lean on. It is here because the fold that
+// hides it only earns its place against text of this shape: a tidy paragraph
+// would have made an inline render look perfectly reasonable.
+const TRANSCRIPT = [
+  "**Sarah:** …so that panel is the reconciliation view. Every paid shipment on the left, every bank line on the right.",
+  "**Duc:** And it matches them itself?",
+  "**Sarah:** It proposes the match. You confirm it. Nothing posts without a person.",
+  "**Duc:** Can you show that again? Marc should see this part.",
+  "**Sarah:** Of course. I'll wait.",
+  "**Duc:** *(off mic)* …Marc, có rảnh hai phút không?",
+  "**Marc:** Sorry — I'm here. What am I looking at?",
+  "**Sarah:** Reconciliation. This is the step that takes your team a morning a week.",
+  "**Marc:** It's more than a morning. And what does it cost?",
+  "**Sarah:** Per document. I'd rather put the figure in writing than say a number now.",
+  "**Marc:** Please do. I'm at the board on Thursday and I'm not walking in with a range.",
+  "**Duc:** One thing — the person who keeps that spreadsheet isn't on this call.",
+].join("\n\n");
+
+// A PHONE call leaves a transcript exactly as a video call does — the medium
+// decides which element plays it, never whether the words exist. Splitting that
+// (video gets a transcript, audio does not) is the sort of gap a fixture creates
+// and a real system never has.
+const CALL_TRANSCRIPT = [
+  "**Duc:** …six months in. Changing it now is not a conversation I can win.",
+  "**Sarah:** Then let's not have it. What if nothing moves and we sit on top?",
+  "**Duc:** On top how?",
+  "**Sarah:** Two pieces. A carrier layer, so an order becomes a booking in one press. And reconciliation against what the bank actually paid.",
+  "**Duc:** The bookings are the part that hurts. We re-key every one.",
+  "**Sarah:** Into the carrier's own site?",
+  "**Duc:** Into three of them. Different fields, same shipment.",
+  "**Sarah:** That is the layer. Nothing you have today changes.",
+  "**Duc:** I'd still need leadership on it. Six months of licence left.",
+].join("\n\n");
+
+const LONG_NOTE =
+  "Ran the whole process end to end with their coordinator. Costs arrive as a PDF payment " +
+  "slip per job, the invoices are then downloaded one at a time against the numbers listed on " +
+  "the slip, and everything is keyed twice — once into their software and once into a separate " +
+  "master spreadsheet — before it goes to accounts for payment. Their OCR reads the notes field " +
+  "and nothing else, so the invoice number and the amount are typed by hand every time. Roughly " +
+  "twenty minutes a job, and she does eight to twelve a day.";
+
+// The fixture is deliberately UNEVEN: a 34-minute call with a machine summary, a
+// one-line note typed between meetings, an email nobody has answered, a message
+// with an attachment, and one entry of unsummarised prose. A tidy set of similar
+// rows would prove nothing about a feed whose whole problem is that its entries
+// are not alike — and would hide the length case entirely.
+const ACTIVITY: ActivityEntry[] = [
+  {
+    // ARRIVED, NOT WRITTEN — an automation filed this the moment the recording
+    // landed, and nobody has said what came of it yet. The most common shape on
+    // a feed that fills from elsewhere, and the one a hand-built fixture never
+    // contains, so the row that has to say "no words yet" never gets designed.
+    // Note the author: a bot, which is why `by` is not a name string.
+    key: "a0",
+    kind: "call",
+    direction: "in",
+    over: "Phone",
+    when: "Today, 11:40",
+    by: { kind: "system", name: "Recording bot" },
+    media: { src: "/sample-audio.mp3", label: "Call recording" },
+    transcript: CALL_TRANSCRIPT,
+  },
+  {
+    // THE FULL CALL: the recording, the verbatim transcript folded behind its
+    // own toggle, and a machine reading of it — three blocks on one entry, each
+    // a different kind of claim. This is the shape an app should copy.
+    key: "a3",
+    kind: "video",
+    gist: "Demo — the reconciliation step is what sold it; pricing still open",
+    direction: "out",
+    over: "Google Meet",
+    when: "Today, 10:15",
+    by: { kind: "member", name: "Sarah Chen" },
+    media: { src: "/sample-video.webm", label: "Demo recording" },
+    transcript: TRANSCRIPT,
+    // NO human note on this entry, deliberately. It carried "the person who
+    // maintains it was not in the room" — which the summary's own Risk line says
+    // better, and which the participants line was gesturing at too: one fact,
+    // three places. When a machine summary is good the rep usually adds nothing,
+    // and the note block is already taught by the two note entries below.
+    bodyByAi:
+      "**Where it landed.** The bank-reconciliation step is what changed the " +
+      "room — Duc asked to see it twice and pulled Marc in for it.\n\n**Open.** Pricing. Marc " +
+      "wants a per-document figure in writing before the board on Thursday.\n\n**Risk.** The " +
+      "spreadsheet owner was absent and is the person whose work this replaces.",
+  },
+  {
+    key: "a1",
+    kind: "note",
+    gist: "They want the integration layer built and maintained, not the platform replaced",
+    direction: "out",
+    over: "Note",
+    when: "Today, 09:12",
+    by: { kind: "member", name: "Sarah Chen" },
+  },
+  {
+    key: "a1b",
+    kind: "note",
+    // The gist and the body are the SAME string on purpose: the row clamps it to
+    // two lines and the detail carries it whole. That is a truncation and its
+    // source — the drill-down every expandable register row makes — not a second
+    // copy of one value.
+    gist: LONG_NOTE,
+    body: LONG_NOTE,
+    direction: "in",
+    over: "Site visit",
+    when: "Today, 08:05",
+    by: { kind: "member", name: "Sarah Chen" },
+  },
+  {
+    // AN EMAIL carries three things nothing else does: who it was between, what
+    // it was called, and a body somebody else composed. The body is `body`, not
+    // `bodyByAi` — a counterparty's own words are not a machine's summary, and
+    // rendering them alike would be the same mistake in the other direction.
+    key: "a2",
+    kind: "email",
+    subject: "Re: Pricing for the customs documentation module",
+    participants: "Copied to accounts@",
+    gist: "Asked for the per-document price in writing before the board meeting",
+    direction: "in",
+    over: "Email",
+    when: "Yesterday, 16:40",
+    by: { kind: "system", name: "Mailbox sync" },
+    body:
+      "Thanks for the walkthrough. Before I take this to the board on Thursday I need the " +
+      "per-document price **in writing**, and confirmation that the customs forms come out of " +
+      "the same record without re-keying.\n\nCould you also confirm the setup is included?" +
+      "\n\n> Sent from the board pack thread",
+    files: [{ id: "f-pack", filename: "Board pack — draft.pdf", mimeType: "application/pdf", url: "/sample.pdf" }],
+  },
+  {
+    // A CAPTURE: an extraction filed this off a screenshot of a public post, so
+    // the evidence is an image and the entry can point back at where it lives.
+    // Images go in a GRID — a photo is identified by what is in it, never by a
+    // filename — where a document set would be a row list.
+    key: "a6",
+    kind: "message",
+    gist: "Asked in the forwarders' group who handles Japan customs paperwork",
+    direction: "in",
+    over: "Facebook Group",
+    when: "10 Aug, 21:30",
+    by: { kind: "system", name: "Capture" },
+    files: [
+      { id: "s1", filename: "post.png", mimeType: "image/png", url: img("Post", "#3f3f46") },
+      { id: "s2", filename: "profile.png", mimeType: "image/png", url: img("Profile", "#52525b") },
+    ],
+    sourceUrl: "https://example.com/groups/forwarders/posts/1849",
+  },
+  {
+    key: "a4",
+    kind: "call",
+    gist: "34 minutes — locked into their current platform for six months, wants us to sit on top of it",
+    direction: "out",
+    over: "Phone",
+    when: "3 Aug, 11:20",
+    by: { kind: "member", name: "Sarah Chen" },
+    media: { src: "/sample-audio.mp3", label: "Call recording" },
+    transcript: CALL_TRANSCRIPT,
+    bodyByAi:
+      "**Context.** International freight forwarder, Japanese ownership, six " +
+      "months into their current platform.\n\n**What they need**\n\n1. A carrier API layer — one " +
+      "press from an order to a booking.\n2. Bank reconciliation against paid shipments.\n\n" +
+      "**Why it has not closed.** Deep commitment to the incumbent; replacing it is a non-starter " +
+      "and leadership would have to approve.",
+  },
+  {
+    key: "a5",
+    kind: "message",
+    gist: "Sent the one-page summary; no reply yet",
+    direction: "out",
+    over: "Zalo",
+    when: "28 Jul, 18:05",
+    by: { kind: "member", name: "Sarah Chen" },
+    awaiting: true,
+    files: [{ id: "f-sum", filename: "Summary — one page.pdf", mimeType: "application/pdf", url: "/sample.pdf" }],
+  },
+];
+
+/**
+ * What came WITH the entry, as a clause for the supporting line.
+ *
+ * A sentence rather than a row of glyphs: an icon run is compact but needs a key
+ * the reader has to learn before the first row means anything, and the line it
+ * would save already exists.
+ *
+ * ONLY on an entry with no gist. There, the attachments ARE the content — "not
+ * written up yet" is useless without "there is a recording to write it up from".
+ * Anywhere else it repeats what the body shows one press away, and it is not
+ * free: measured at 375 the supporting line already fills the two lines
+ * `Timeline` clamps it at, so an unconditional clause clips the date it was
+ * appended to. The clause APPEARING is therefore itself the signal that the row
+ * is otherwise empty.
+ */
+function arrivedWith(a: ActivityEntry): string {
+  if (a.gist) return "";
+  // Name the thing, not its relation to the sentence: "Attachment attached" is
+  // the shape a templated clause produces and it reads as a stutter.
+  // Lower case throughout, capitalised once at the end — joining already-capital
+  // words gave "Recording, Transcript and file attached." the moment a third
+  // artifact appeared, which no fixture reached and every real row eventually
+  // will. The type guard rather than `filter(Boolean)` is what removes the `!`
+  // on the last element: `Boolean` does not narrow.
+  const parts = [
+    a.media ? "recording" : null,
+    a.transcript ? "transcript" : null,
+    a.files?.length ? "file" : null,
+  ].filter((x): x is string => x !== null);
+  if (parts.length === 0) return "";
+  const list =
+    parts.length === 1 ? parts[0] : `${parts.slice(0, -1).join(", ")} and ${parts.at(-1)}`;
+  return ` ${list[0].toUpperCase()}${list.slice(1)} attached.`;
+}
+
+/**
+ * THE ACTIVITY BODY — one component, every block, each rendered only if the
+ * entry carries it.
+ *
+ * This is the half of the anatomy that VARIES, and the reason it is a component
+ * rather than five: an app that branches on `kind` writes the media block once
+ * per kind and then fixes a bug in four of them. Reading order is fixed and
+ * means something — who and what it was, then the artifact, then the verbatim
+ * source, then what people made of it, then what came with it, then where it
+ * came from and who filed it.
+ */
+function ActivityBody({
+  a,
+  editing,
+  onEdit,
+  onToggleEdit,
+  onDelete,
+}: {
+  a: ActivityEntry;
+  /** Set by the footer's Edit verb — see the fields below for why it is a MODE
+   *  here rather than the resident editors every other section uses. */
+  editing: boolean;
+  onEdit: (patch: Partial<Pick<ActivityEntry, "gist" | "body">>) => void;
+  onToggleEdit: () => void;
+  onDelete: () => void;
+}) {
+  const [showTranscript, setShowTranscript] = useState(false);
+  const images = (a.files ?? []).filter((f) => isImageMimeType(f.mimeType));
+  const docs = (a.files ?? []).filter((f) => !isImageMimeType(f.mimeType));
+
+  return (
+    <View style={{ gap: 12 }}>
+      {/* THE WORDS A PERSON WROTE — the only editable thing on an entry, and the
+          one place this template does NOT use a resident editor.
+
+          Exactly two blocks were authored by a person: the gist and the note.
+          Everything else is derived (participants, off a header), verbatim (the
+          transcript), an artifact (the media, the files) or a machine's output
+          (the summary — you re-run that, you do not hand-edit it). So the verb
+          is "Edit", not "Edit entry": an entry is not an editable thing, the
+          words typed into it are.
+
+          WHY A MODE, when every other section on this record is a resident
+          `InlineTextInput`. Those sections show each value ONCE. Here the gist is
+          already the row's label, so a resident field renders the same sentence
+          twice, stacked and identical — which is what it looked like, and no
+          amount of quieting the frame fixes a sentence appearing twice.
+
+          THE EXCEPTION IS AN EMPTY GIST, and it is the important half: an
+          automation files an entry the moment a recording lands, the row says
+          "Not written up yet", and there is nothing to duplicate. The field shows
+          itself and invites the sentence. Without that the feed can RECEIVE an
+          entry it gives you no way to finish — a dead end on the most common row
+          a multi-writer feed produces. An empty value shows its field; a filled
+          one waits to be asked. */}
+      {editing || !a.gist ? (
+        <InlineTextInput
+          value={a.gist ?? ""}
+          onSave={(v) => onEdit({ gist: v.trim() || undefined })}
+          placeholder="What came of it?"
+          accessibilityLabel="What came of it"
+          numberOfLines={2}
+          autoGrow
+        />
+      ) : null}
+
+      {/* HEADER — who it was between, and what it was called. A subject line
+          never says who was on it, and on a call there is no subject at all, so
+          these are two blocks rather than one formatted string. Both are read
+          off the message itself, so neither is editable. */}
+      {a.participants ? (
+        <Text size="xs" color="muted">{a.participants}</Text>
+      ) : null}
+      {a.subject ? <Text size="sm" weight="medium">{a.subject}</Text> : null}
+
+      {/* THE ARTIFACT. A recording rendered as a file row makes the reader leave
+          the record to hear thirty seconds of a call they are already reading
+          about. `kind` is the caller's to state, because one container can hold
+          both streams and only this surface knows whether it wants the picture.
+
+          THE BOX IS THE CALLER'S: `MediaPlayer` fills its parent rather than
+          carrying a size, so a player dropped bare into a gap-spaced stack
+          collapses to nothing — it renders, it reports no error, and there is
+          simply no pixel. Video takes a 16:9 frame so the row does not resize
+          when metadata arrives; audio carries its own intrinsic height. */}
+      {a.media ? (
+        a.kind === "video" ? (
+          <View style={{ aspectRatio: 16 / 9, borderRadius: 12, overflow: "hidden" }}>
+            <MediaPlayer src={a.media.src} kind="video" accessibilityLabel={a.media.label} />
+          </View>
+        ) : (
+          <MediaPlayer src={a.media.src} kind="audio" accessibilityLabel={a.media.label} />
+        )
+      ) : null}
+
+      {/* THE VERBATIM SOURCE, folded. It belongs next to the summary rather than
+          behind a dialog, because the reason anyone opens a transcript is to
+          check a claim the summary made — and a modal takes the claim off the
+          screen at the moment they want to compare. Revealed in FULL, not into a
+          scroll box: a scroller inside a drawer that also scrolls traps the
+          wheel, and a reader who pressed "Show transcript" asked for the length. */}
+      {a.transcript ? (
+        <View style={{ gap: 8, alignItems: "flex-start" }}>
+          {/* Underlined text that REVEALS rather than navigates — muted, so the
+              ink never promises a trip. Two controls were tried first and both
+              are wrong here: `Button color="muted"` measures transparent and
+              undecorated at rest (a hover-only affordance), and `Accordion` is a
+              list-row disclosure nested inside a list row. See the component's
+              own doc and composition.md §"Commit & feedback surfaces". */}
+          <TextDisclosure
+            expanded={showTranscript}
+            onToggle={setShowTranscript}
+            label="transcript"
+          />
+          {/* PLAIN, not a tinted well. The toggle directly above already says
+              what this is and where it came from, and a panel here would put two
+              identical recessed boxes on one row meaning two different things —
+              a verbatim record and a machine's reading of it. */}
+          {showTranscript ? <Markdown variant="embedded">{a.transcript}</Markdown> : null}
+        </View>
+      ) : null}
+
+      {/* PROSE A PERSON WROTE — a note of their own. It sits on the page's own
+          ground, which is what makes the recessed block below legible as "not
+          written here", and it is EDITABLE for the same reason the gist is:
+          somebody typed it.
+
+          The exception is a body that arrived FROM the counterparty — an email
+          they sent is a record of what they said, so it renders as markdown and
+          is not ours to rewrite. */}
+      {a.kind === "email" ? (
+        a.body ? <Markdown variant="embedded">{a.body}</Markdown> : null
+      ) : editing ? (
+        <InlineTextInput
+          value={a.body ?? ""}
+          onSave={(v) => onEdit({ body: v.trim() || undefined })}
+          placeholder="Add a note…"
+          accessibilityLabel="Note"
+          numberOfLines={2}
+          autoGrow
+        />
+      ) : a.body ? (
+        <Markdown variant="embedded">{a.body}</Markdown>
+      ) : null}
+
+      {/* PROSE A MODEL WROTE. Two devices carry the difference and neither is a
+          weight nudge: the line names the AUTHOR and the evidence it worked
+          from — naming only the source ("From the call") leaves the reader to
+          assume a person — and the recessed `Inset` says the text was not
+          written on this page. `embedded` stops the `##` headings a model emits
+          freely from outranking the section they were dropped inside. */}
+      {a.bodyByAi ? (
+        // The label sits INSIDE the panel it names. Floating above it, a 12px
+        // muted fragment over a tinted box reads as an orphan — the type was on
+        // the ladder and the PLACEMENT was the defect, which is why it looked
+        // wrong without looking measurably wrong.
+        //
+        // Two words, and they are the whole job: a model wrote this. It read
+        // "Written by AI from the recording" over markdown that then opened with
+        // its own `## Summary` — two labels for one thing, the longer one
+        // spending four words on evidence the reader can watch playing directly
+        // above. Provenance is weighted by consequence: name the source where it
+        // is NOT on screen.
+        <Inset>
+          <Text size="xs" color="muted" weight="medium">AI summary</Text>
+          <Markdown variant="embedded">{a.bodyByAi}</Markdown>
+        </Inset>
+      ) : null}
+
+      {/* WHAT CAME WITH IT, split by what IDENTIFIES each file. A document is its
+          NAME — every PDF thumbnail is the same grey page — so documents are
+          rows. A photo is its CONTENT (`IMG_4471.jpg` tells nobody anything), so
+          images are tiles. One `files` array, two surfaces, decided by the data
+          rather than by a prop the caller has to remember. */}
+      {docs.length ? <FileRows files={docs} /> : null}
+      {images.length ? <FileThumbnailGrid files={images} itemSize={88} /> : null}
+
+      {/* PROVENANCE — where it happened, and who filed it. Two shapes for the
+          author because there are two kinds: a person gets a face, and an
+          automation gets `WaveAvatar`, the kit's mark for a non-human identity.
+          Giving a bot initials and an avatar is a small fabrication that every
+          reader notices and no test catches. */}
+      {/* THE FOOTER — provenance on the left, the entry's verbs on the right.
+          Two kinds of thing on one line, so they are two GROUPS pushed apart by
+          the space between them rather than a uniform gap that would make them
+          peers.
+
+          THE VERBS LIVE HERE, NOT ON THE ROW, and the reason is not tidiness.
+          A control in the row's trailing slot produced three separate defects in
+          a row: it nested a button inside the row's own button (invalid HTML,
+          one click reaching two handlers), it needed a fixed-height box of its
+          own to stay on the label's first line, and it sat close enough to the
+          disclosure chevron to read as one cluster with it. All three exist only
+          because something interactive shares the row with the press target.
+          Down here there is no press target to share with, and the whole class
+          is gone.
+
+          It also puts the verbs where the thing they act on IS. Editing a gist
+          you cannot read is not a real act, and a delete you reach without
+          opening the entry is a delete you make without looking at it — the
+          expansion is the confirmation step, which is why "two clicks" is the
+          feature rather than the cost.
+
+          They are ordinary `Button`s, not the quiet text controls used inside
+          prose above: these MUTATE, so they carry a control surface. Right-
+          aligned in a footer band, they establish no text edge to betray, which
+          is the condition the fill-less rungs need. */}
+      <View style={{ flexDirection: "row", alignItems: "center", gap: 12, flexWrap: "wrap" }}>
+        <View style={{ flexDirection: "row", alignItems: "center", gap: 6 }}>
+          <Text size="xs" color="muted">Logged by</Text>
+          {a.by.kind === "member" ? (
+            <MemberChip name={a.by.name} image={a.by.image} size="sm" />
+          ) : (
+            <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
+              <WaveAvatar size={24} />
+              <Text size="sm">{a.by.name}</Text>
+            </View>
+          )}
+        </View>
+        {a.sourceUrl ? (
+          <Link size="xs" onPress={() => {}}>{a.sourceUrl}</Link>
+        ) : null}
+        {/* Pushes the verbs to the far edge, so provenance and actions are two
+            groups rather than a run of four items on one gap. */}
+        <View style={{ flex: 1, minWidth: 24 }} />
+        <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
+          <Button
+            title={editing ? "Done" : "Edit"}
+            color="muted"
+            onPress={onToggleEdit}
+          />
+          <Button
+            title="Delete"
+            color="danger-secondary"
+            onPress={() =>
+              Alert.alert(
+                "Delete this entry?",
+                "It leaves the customer's history and stops counting toward the activity total. This cannot be undone.",
+                [
+                  { text: "Cancel", style: "cancel" },
+                  { text: "Delete", style: "destructive", onPress: onDelete },
+                ],
+              )
+            }
+          />
+        </View>
+      </View>
+    </View>
+  );
+}
+
+/** The glyph per medium. A medium is a CATEGORY, so it rides the icon and the
+ *  supporting line — never a `Badge`, which this kit reserves for status. */
+const ACTIVITY_ICON: Record<ActivityKind, IconName> = {
+  call: "phone",
+  video: "monitor",
+  email: "mail",
+  message: "message-circle",
+  note: "sticky-note",
+};
+
 // ── billing — charges grouped into issuable invoice DOCUMENTS on this record
 type Method = "cash" | "transfer" | "card";
 const METHODS: PickerOption<Method>[] = [
@@ -1251,6 +1831,19 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418", openSection
         : f.due !== "" ? { text: `Due ${new Date(f.due).toLocaleDateString("en-GB", { day: "numeric", month: "short" })}`, danger: false }
           : { text: "Unpaid", danger: false };
 
+  // ── activity — the feed is state so a logged note appears at the top of it,
+  // where it happened, rather than after a refetch.
+  const [activity, setActivity] = useState<ActivityEntry[]>(ACTIVITY);
+  // A record's feed is not a register: you do not PAGE it, you fold the tail.
+  // The recent entries are what the reader came for, and an unbounded feed makes
+  // every other section on the record unreachable by scroll.
+  const [showAllActivity, setShowAllActivity] = useState(false);
+  const ACTIVITY_FOLD = 3;
+  // ONE entry at a time. A feed with several rows open in edit mode gives the
+  // reader two half-finished sentences and no way to tell which one the next
+  // keystroke lands in.
+  const [editingActivity, setEditingActivity] = useState<string | null>(null);
+
   // ── the record — seeded mid-flight so every state is visible
   const [stage, setStage] = useState<Stage>("sales");
   // The customer book is STATE: the attached customer's tax ID edits inline in
@@ -1949,6 +2542,7 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418", openSection
     // The rail lists sections in PAGE order, or the scroll-spy highlights one
     // entry while the reader is looking at another.
     { key: "progress", label: "Progress", icon: "git-branch" },
+    { key: "activity", label: "Activity", icon: "message-square" },
     { key: "general", label: "General", icon: "file-text" },
     // Only a SECTION when the page is too narrow to seat the panel — so the wide
     // rail filters it out rather than offering a jump to something that is not
@@ -1971,7 +2565,7 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418", openSection
   // by scroll and invisible in the outline. Bound to `SecKey`, a key here that
   // `SECTIONS` does not carry stops being assignable, so the omission is a
   // compile error instead of a missing row nobody notices.
-  const nav = useSectionNav<SecKey>(["progress", "general", "comments", "files", "photos", "transport", "fees", "billing", "docset", "receipt", "danger"] as const);
+  const nav = useSectionNav<SecKey>(["progress", "activity", "general", "comments", "files", "photos", "transport", "fees", "billing", "docset", "receipt", "danger"] as const);
   // ONE record, ONE page. A section is a place you SCROLL to, never a
   // destination you swap to: routing a record was tried here and lost, because
   // every fix it needed rebuilt the whole-record view in miniature — a dot to
@@ -2334,6 +2928,160 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418", openSection
         </Section>
         </View>
 
+        {/* ACTIVITY — what has been SAID with the other party. It follows
+            Progress because the two answer the reader's first two questions in
+            order: where the record stands, then what passed between us to get
+            it there.
+
+            It is NOT the handoff trail. Progress owns where the record SITS and
+            the act that moves it; this owns COMMUNICATIONS with a counterparty,
+            which a desk transition is not. Keeping that line is what stops this
+            section becoming the audit log the Progress note deliberately
+            refuses — an entry here is something a person said or sent, never a
+            field that changed.
+
+            THE ROW ANATOMY, and the mistake it exists to prevent: the row's
+            LABEL is the GIST — what came of the exchange, in the reader's own
+            words. The medium and the direction are metadata and ride the muted
+            supporting line under it. Putting the taxonomy in the label
+            ("Outbound Meeting") and the substance behind the chevron is the
+            natural way to build this and it makes the feed unreadable: every
+            row renders as a pair of enum values, the reader has to expand each
+            one to learn anything, and a column of near-identical labels defeats
+            the scan the feed exists for.
+
+            ONE anatomy, a body that VARIES. A touchpoint can be a call, a
+            recorded demo, an email, a message or a note typed between meetings,
+            and those differ in what they CARRY, not in what they are: all five
+            answer what-came-of-it, which way, over what, and when. So the four
+            invariants are the row and the body is a slot — audio and video get
+            a real MediaPlayer, an email gets its subject, prose gets Markdown,
+            attachments get FileRows. A row TYPE per medium would put those four
+            facts in five places and let them drift. */}
+        <View onLayout={nav.register("activity")}>
+        <Section>
+          <SectionHeading>
+            <SectionHeadingTitle description="Calls, mail and messages with the customer, newest first.">
+              Activity
+            </SectionHeadingTitle>
+            <SectionHeadingMeta>{activity.length}</SectionHeadingMeta>
+          </SectionHeading>
+
+          {/* The capture sits AT the feed, not in a section of its own. Logging
+              a touchpoint is this section's input, not a distinct AREA of the
+              record — and a section costs a rail entry, which is a claim that
+              there is somewhere else to go. The Composer is compact until
+              typed into, so the resting cost of "you can add one" is one row
+              rather than a form nobody is filling. */}
+          <Composer
+            placeholder="Log a call, an email, a note…"
+            accessibilityLabel="Log an activity"
+            sendLabel="Log"
+            onSend={(text) => {
+              const t = text.trim();
+              if (!t) return;
+              setActivity((prev) => [
+                {
+                  key: `a-${prev.length + 1}-${t.length}`,
+                  kind: "note",
+                  gist: t,
+                  direction: "out",
+                  over: "Note",
+                  when: "Just now",
+                  by: { kind: "member", name: "Sarah Chen" },
+                },
+                ...prev,
+              ]);
+            }}
+          />
+
+          {activity.length === 0 ? (
+            <EmptyState
+              icon="message-circle"
+              message="Nothing logged yet"
+              hint="Add the first call, email or note above."
+            />
+          ) : (
+            <>
+              <Timeline
+                items={(showAllActivity ? activity : activity.slice(0, ACTIVITY_FOLD)).map(
+                  (a): TimelineItem => ({
+                    id: a.key,
+                    icon: ACTIVITY_ICON[a.kind],
+                    // An unanswered outreach is the one state in this feed worth
+                    // a colour: it is the only entry that owes somebody
+                    // something. Everything else is history and reads neutral.
+                    iconColor: a.awaiting ? solid("amber") : colors.zinc[400],
+                    // NEVER a phrase assembled from the enums ("Inbound Call").
+                    // That renders in body ink and so claims somebody wrote it;
+                    // `placeholder` is how the row says the words are missing,
+                    // and the medium and direction are already on the line below.
+                    label: a.gist ?? "Not written up yet",
+                    placeholder: a.gist == null,
+                    // The metadata line — a real preposition and a comma, never
+                    // a middot standing in for the relation (§Microcopy) — and
+                    // then WHAT ARRIVED, because a closed row is the scanning
+                    // state and on an entry with no words the attachments are
+                    // the entire content. Written out rather than glyphed: an
+                    // icon run needs a key the reader has to learn first, and
+                    // this line is already here.
+                    description:
+                      `${a.direction === "in" ? "From them" : "From us"} over ${a.over}, ${a.when}.` +
+                      arrivedWith(a),
+                    // The row's verbs. `right` sits BESIDE the press target, so a
+                    // menu here is independently clickable and does not nest a
+                    // button inside the row's own button.
+                    //
+                    details: (
+                      <ActivityBody
+                        a={a}
+                        editing={editingActivity === a.key}
+                        onEdit={(patch) =>
+                          setActivity((prev) =>
+                            prev.map((e) => (e.key === a.key ? { ...e, ...patch } : e)),
+                          )
+                        }
+                        onToggleEdit={() =>
+                          setEditingActivity((cur) => (cur === a.key ? null : a.key))
+                        }
+                        onDelete={() => {
+                          setActivity((prev) => prev.filter((e) => e.key !== a.key));
+                          setEditingActivity((cur) => (cur === a.key ? null : cur));
+                        }}
+                      />
+                    ),
+                  }),
+                )}
+              />
+              {/* The tail FOLDS rather than paging. A record's feed is read
+                  newest-first and the old entries are reference — but they are
+                  still on the record, so the count says how much is behind the
+                  toggle instead of hiding that there is more. */}
+              {activity.length > ACTIVITY_FOLD ? (
+                // A REVEAL, so the same control as the transcript's: it shows
+                // more of what is already here, in place. It was a
+                // `Button color="muted"` — transparent, borderless and
+                // undecorated at rest, so the affordance only arrived on hover
+                // and it read as a stray line under the feed. It also sat at
+                // 420: its own 10px padding, which matches neither the section's
+                // edge nor the rows' text column, so it aligned to nothing.
+                //
+                // No wrapper and no indent: the 44px the rows are inset by is
+                // the disc rail, and at this line the rail has ended. An indent
+                // is legitimate only where something visible occupies it.
+                <View style={{ alignItems: "flex-start" }}>
+                  <TextDisclosure
+                    expanded={showAllActivity}
+                    onToggle={setShowAllActivity}
+                    label={`${activity.length - ACTIVITY_FOLD} earlier`}
+                  />
+                </View>
+              ) : null}
+            </>
+          )}
+        </Section>
+        </View>
+
 
         {/* FEES — the DETAILED money ledger, both directions (charge = billed
             to the customer, cost = paid to a vendor), distinct from Billing's
@@ -3598,11 +4346,17 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418", openSection
                     })}
                   </Checklist>
                   {hidden > 0 ? (
-                    <View style={{ flexDirection: "row" }}>
-                      <Button
-                        title={open ? "Show fewer forms" : `Show all forms (${hidden} hidden)`}
-                        color="muted"
-                        onPress={() => toggleFold(g.id)}
+                    // The same reveal, the same control. The label is the NOUN
+                    // only — `TextDisclosure` supplies the verb, which is what
+                    // stops a pair drifting into two framings ("Show all forms
+                    // (3 hidden)" against "Show fewer forms" named different
+                    // things in each state, so pressing it twice taught the
+                    // reader nothing about what it does).
+                    <View style={{ alignItems: "flex-start" }}>
+                      <TextDisclosure
+                        expanded={open}
+                        onToggle={() => toggleFold(g.id)}
+                        label={`${hidden} more forms`}
                       />
                     </View>
                   ) : null}