@tangle-network/ui 11.24.0 → 11.25.0

package/src/chat/chat-message.tsx

@@ -2,12 +2,17 @@
  * ChatMessage — one message in the conversation.
  *
  * Supports user messages (plain text) and assistant messages
- * (rich markdown with inline tool call activity).
+ * (rich markdown with inline tool call activity). With `author` and
+ * `viewerId` it renders a transcript shared by several people: the reader's
+ * own messages stay at the end, everyone else's sit at the start under
+ * their author.
  */
 
 import { type ReactNode } from "react";
 import { cn } from "../lib/utils";
 import { Markdown } from "../markdown/markdown";
+import type { ChatAuthor } from "../types/message";
+import { isViewerMessage, MessageAuthor } from "./message-author";
 
 export type MessageRole = "user" | "assistant" | "system";
 
@@ -27,6 +32,17 @@ export interface ChatMessageProps {
   assistantLabel?: string;
   /** Hide the role label row entirely */
   hideRoleLabel?: boolean;
+  /**
+   * Who wrote the message, when more than one person shares the transcript.
+   * It replaces the role label with the author's avatar, name and role,
+   * except on the reader's own messages, which keep `userLabel`.
+   */
+  author?: ChatAuthor;
+  /**
+   * The reader's participant id. A user message whose `author` has another
+   * id is someone else's: it sits at the start, on a card, under its author.
+   */
+  viewerId?: string;
 }
 
 export function ChatMessage({
@@ -39,23 +55,32 @@ export function ChatMessage({
   userLabel = "You",
   assistantLabel = "Agent",
   hideRoleLabel,
+  author,
+  viewerId,
 }: ChatMessageProps) {
   const isUser = role === "user";
   const isAssistant = role === "assistant";
+  const fromViewer = isUser && isViewerMessage(author, viewerId);
+  const fromOtherPerson = isUser && !fromViewer;
+  const shownAuthor = fromViewer ? undefined : author;
 
   return (
     <div
       className={cn(
         "flex flex-col gap-1",
-        isUser ? "items-end" : "items-start",
+        fromViewer ? "items-end" : "items-start",
         className,
       )}
     >
       {!hideRoleLabel && (
-        <div className={cn("flex items-center gap-2 px-1", isUser && "flex-row-reverse")}>
-          <span className="font-medium text-foreground text-xs">
-            {isUser ? userLabel : assistantLabel}
-          </span>
+        <div className={cn("flex items-center gap-2 px-1", fromViewer && "flex-row-reverse")}>
+          {shownAuthor ? (
+            <MessageAuthor author={shownAuthor} />
+          ) : (
+            <span className="font-medium text-foreground text-xs">
+              {isUser ? userLabel : assistantLabel}
+            </span>
+          )}
           {timestamp && (
             <span className="text-muted-foreground text-xs">
               {formatTime(timestamp)}
@@ -67,11 +92,13 @@ export function ChatMessage({
       <div
         className={cn(
           "min-w-0 max-w-[85%] space-y-1",
-          isUser
+          fromViewer
             ? "rounded-[var(--radius-lg)] bg-foreground px-[var(--chat-message-px)] py-[var(--chat-message-py)] text-background"
-            : isAssistant
-              ? "text-foreground"
-              : "rounded-[var(--radius-lg)] border border-border bg-card px-[var(--chat-message-px)] py-[var(--chat-message-py)]",
+            : fromOtherPerson
+              ? "rounded-[var(--radius-lg)] border border-border bg-card px-[var(--chat-message-px)] py-[var(--chat-message-py)] text-foreground"
+              : isAssistant
+                ? "text-foreground"
+                : "rounded-[var(--radius-lg)] border border-border bg-card px-[var(--chat-message-px)] py-[var(--chat-message-py)]",
         )}
       >
         {isUser ? (

package/src/chat/index.ts

@@ -2,6 +2,8 @@ export { ChatContainer, type ChatContainerProps } from "./chat-container";
 export { MessageList, type MessageListProps } from "./message-list";
 export { UserMessage, type UserMessageProps } from "./user-message";
 export { ChatMessage, type ChatMessageProps, type MessageRole } from "./chat-message";
+export { MessageAuthor, isViewerMessage, type MessageAuthorProps } from "./message-author";
+export type { ChatAuthor } from "../types/message";
 export { ThinkingIndicator, type ThinkingIndicatorProps } from "./thinking-indicator";
 export {
   AgentTimeline,

package/src/chat/message-author.stories.tsx

@@ -0,0 +1,170 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { AgentTimeline, type AgentTimelineItem } from './agent-timeline'
+import { ChatMessage } from './chat-message'
+import { MessageAuthor } from './message-author'
+import type { ChatAuthor } from '../types/message'
+
+const client: ChatAuthor = { id: 'client-maria-lopez', name: 'Maria Lopez', role: 'Client' }
+const attorney: ChatAuthor = { id: 'attorney-jane-doe', name: 'Jane Doe', role: 'Attorney' }
+const agent: ChatAuthor = { id: 'agent-intake', name: 'Intake assistant', role: 'AI' }
+
+const NOW = Date.now()
+const t = (offsetMinutes: number) => new Date(NOW - offsetMinutes * 60 * 1000)
+
+const intakeThread: AgentTimelineItem[] = [
+  {
+    id: 'm1',
+    kind: 'message',
+    role: 'user',
+    author: client,
+    timestamp: t(42),
+    content:
+      'My landlord kept my $2,400 security deposit and never sent an itemized list. I moved out on August 31. What can I do?',
+  },
+  {
+    id: 'm2',
+    kind: 'message',
+    role: 'assistant',
+    author: agent,
+    content:
+      'In California a landlord has 21 days after move-out to return the deposit or send an itemized statement of deductions. That window closed on September 21.\n\nThis looks like a case an attorney should review, so I have shared your summary with Jane Doe.',
+  },
+  {
+    id: 'tool-1',
+    kind: 'tool',
+    call: {
+      id: 'tc-1',
+      type: 'write',
+      label: 'Write',
+      status: 'success',
+      detail: 'intake/deposit-dispute-summary.md',
+    },
+  },
+  {
+    id: 'm3',
+    kind: 'message',
+    role: 'assistant',
+    author: agent,
+    content: 'The summary includes your lease dates and the deposit amount.',
+  },
+  {
+    id: 'm4',
+    kind: 'message',
+    role: 'user',
+    author: attorney,
+    timestamp: t(30),
+    content: 'Hi Maria, I am Jane. Did you give the landlord a forwarding address in writing?',
+  },
+  {
+    id: 'm5',
+    kind: 'message',
+    role: 'user',
+    author: client,
+    timestamp: t(27),
+    content: 'Yes, I emailed it to the property manager on August 28.',
+  },
+  {
+    id: 'm6',
+    kind: 'message',
+    role: 'assistant',
+    author: agent,
+    content: 'I added the August 28 email to the case file.',
+  },
+  {
+    id: 'm7',
+    kind: 'message',
+    role: 'user',
+    author: attorney,
+    timestamp: t(20),
+    content: 'Thanks. I will draft a demand letter today, and you will have it to review by 5pm.',
+  },
+]
+
+const meta: Meta<typeof AgentTimeline> = {
+  title: 'Chat/Multi-party transcript',
+  component: AgentTimeline,
+  parameters: {
+    layout: 'fullscreen',
+  },
+  decorators: [
+    (Story) => (
+      <div className="min-h-screen bg-[var(--bg-root)]">
+        <div className="mx-auto max-w-3xl">
+          <Story />
+        </div>
+      </div>
+    ),
+  ],
+}
+
+export default meta
+type Story = StoryObj<typeof AgentTimeline>
+
+/** The client's screen: their own messages at the end, the attorney and the agent at the start. */
+export const ClientView: Story = {
+  args: { items: intakeThread, viewerId: client.id },
+}
+
+/** The same thread on the attorney's screen. */
+export const AttorneyView: Story = {
+  args: { items: intakeThread, viewerId: attorney.id },
+}
+
+/** No viewer, as in an audit log: every person is someone else, so every message is named. */
+export const ObserverView: Story = {
+  args: { items: intakeThread },
+}
+
+/** `ChatMessage` with always-on labels: the reader keeps "You", everyone else is named. */
+export const LabeledMessages: Story = {
+  render: () => (
+    <div className="space-y-4 p-4">
+      <ChatMessage role="user" author={client} viewerId={client.id} timestamp={t(42)} content="My landlord kept my $2,400 security deposit and never sent an itemized list." />
+      <ChatMessage role="assistant" author={agent} content="That window closed on September 21. I have shared your summary with Jane Doe." />
+      <ChatMessage role="user" author={attorney} viewerId={client.id} timestamp={t(30)} content="Hi Maria, I am Jane. Did you give the landlord a forwarding address in writing?" />
+    </div>
+  ),
+}
+
+const longName: ChatAuthor = {
+  id: 'attorney-long',
+  name: 'Alexandria Montgomery-Vandenberghe Castellanos',
+  role: 'Senior supervising attorney, tenant rights',
+}
+const noRole: ChatAuthor = { id: 'guest-1', name: 'Q' }
+const withImage: ChatAuthor = {
+  id: 'paralegal-sam',
+  name: 'Sam Okafor',
+  role: 'Paralegal',
+  avatarUrl:
+    "data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 20 20'><rect width='20' height='20' fill='%236366f1'/><circle cx='10' cy='8' r='4' fill='white'/><rect x='4' y='13' width='12' height='7' rx='3' fill='white'/></svg>",
+}
+const brokenImage: ChatAuthor = { id: 'client-broken', name: 'Lee Park', role: 'Client', avatarUrl: 'https://invalid.example/avatar.png' }
+
+/** Worst cases: a long name and role, a one-letter name with no role, an image, a failing image. */
+export const EdgeCases: Story = {
+  render: () => (
+    <div className="space-y-6 p-4">
+      <div className="space-y-2">
+        <MessageAuthor author={longName} />
+        <MessageAuthor author={noRole} />
+        <MessageAuthor author={withImage} />
+        <MessageAuthor author={brokenImage} />
+      </div>
+      <AgentTimeline
+        className="px-0"
+        viewerId={client.id}
+        items={[
+          {
+            id: 'e1',
+            kind: 'message',
+            role: 'user',
+            author: longName,
+            content: 'Superlongunbrokenidentifierwithoutanyspaces_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
+          },
+          { id: 'e2', kind: 'message', role: 'user', author: noRole, content: 'ok' },
+        ]}
+      />
+    </div>
+  ),
+}

package/src/chat/message-author.test.tsx

@@ -0,0 +1,189 @@
+import { render, screen, within } from "@testing-library/react"
+import type { ReactElement } from "react"
+import { describe, expect, it } from "vitest"
+import type { ChatAuthor } from "../types/message"
+import type { SessionPart } from "../types/parts"
+import { AgentTimeline, type AgentTimelineItem } from "./agent-timeline"
+import { ChatMessage } from "./chat-message"
+import { isViewerMessage, MessageAuthor } from "./message-author"
+import { UserMessage } from "./user-message"
+
+function html(ui: ReactElement): string {
+  return render(ui).container.innerHTML
+}
+
+const segmentedParts: SessionPart[] = [
+  { type: "text", text: "I signed the lease in March." },
+  { type: "text", text: "Lease uploaded: lease.pdf", synthetic: true },
+  { type: "text", text: "Here it is." },
+]
+
+// The snapshots below were recorded from the components before `author`
+// existed. A transcript that names no author must keep that exact markup.
+describe("a transcript without authors", () => {
+  it("renders ChatMessage as before", () => {
+    expect(html(<ChatMessage role="user" content="Can I break my lease early?" />)).toMatchInlineSnapshot(`"<div class="flex flex-col gap-1 items-end"><div class="flex items-center gap-2 px-1 flex-row-reverse"><span class="font-medium text-foreground text-xs">You</span></div><div class="min-w-0 max-w-[85%] space-y-1 rounded-[var(--radius-lg)] bg-foreground px-[var(--chat-message-px)] py-[var(--chat-message-py)] text-background"><div class="whitespace-pre-wrap text-[length:var(--font-size-base)] leading-[var(--line-height-base)]">Can I break my lease early?</div></div></div>"`)
+    expect(html(<ChatMessage role="assistant" content="It depends on the lease terms." />)).toMatchInlineSnapshot(`"<div class="flex flex-col gap-1 items-start"><div class="flex items-center gap-2 px-1"><span class="font-medium text-foreground text-xs">Agent</span></div><div class="min-w-0 max-w-[85%] space-y-1 text-foreground"><div class="tangle-prose max-w-none tangle-prose text-[length:var(--font-size-base)] leading-[var(--line-height-base)]"><p>It depends on the lease terms.</p></div></div></div>"`)
+    expect(html(<ChatMessage role="system" content="Session started." />)).toMatchInlineSnapshot(`"<div class="flex flex-col gap-1 items-start"><div class="flex items-center gap-2 px-1"><span class="font-medium text-foreground text-xs">Agent</span></div><div class="min-w-0 max-w-[85%] space-y-1 rounded-[var(--radius-lg)] border border-border bg-card px-[var(--chat-message-px)] py-[var(--chat-message-py)]"><div class="tangle-prose max-w-none tangle-prose text-[length:var(--font-size-base)] leading-[var(--line-height-base)]"><p>Session started.</p></div></div></div>"`)
+  })
+
+  it("renders UserMessage actions and application notes as before", () => {
+    expect(html(<UserMessage content="Can I break my lease early?" actions={<button type="button">Copy</button>} />)).toMatchInlineSnapshot(`"<div class="flex justify-end"><div class="group flex min-w-0 max-w-[78%] flex-col items-end gap-2"><div class="relative w-full min-w-0 rounded-2xl bg-foreground px-4 py-3 text-background"><div class="break-words whitespace-pre-wrap text-[length:var(--font-size-base)] leading-[1.5]">Can I break my lease early?</div></div><div class="flex flex-wrap items-center justify-end gap-1.5 text-xs text-muted-foreground"><button type="button">Copy</button></div></div></div>"`)
+    expect(html(<UserMessage parts={segmentedParts} actions={<button type="button">Copy</button>} />)).toMatchInlineSnapshot(`"<div class="space-y-2"><div class="flex justify-end"><div class="group flex min-w-0 max-w-[78%] flex-col items-end gap-2"><div class="relative w-full min-w-0 rounded-2xl bg-foreground px-4 py-3 text-background"><div class="break-words whitespace-pre-wrap text-[length:var(--font-size-base)] leading-[1.5]">I signed the lease in March.</div></div></div></div><div role="note" aria-label="Application note" data-synthetic-text="" class="min-w-0 rounded-md border border-dashed border-border bg-muted/30 px-3 py-2 text-sm text-muted-foreground"><div class="mb-1 font-medium">Application note</div><div class="break-words whitespace-pre-wrap">Lease uploaded: lease.pdf</div></div><div class="flex justify-end"><div class="group flex min-w-0 max-w-[78%] flex-col items-end gap-2"><div class="relative w-full min-w-0 rounded-2xl bg-foreground px-4 py-3 text-background"><div class="break-words whitespace-pre-wrap text-[length:var(--font-size-base)] leading-[1.5]">Here it is.</div></div></div></div><div class="flex flex-wrap items-center justify-end gap-1.5 text-xs text-muted-foreground"><button type="button">Copy</button></div></div>"`)
+  })
+
+  it("renders UserMessage as before", () => {
+    expect(html(<UserMessage content="Can I break my lease early?" />)).toMatchInlineSnapshot(`"<div class="flex justify-end"><div class="group flex min-w-0 max-w-[78%] flex-col items-end gap-2"><div class="relative w-full min-w-0 rounded-2xl bg-foreground px-4 py-3 text-background"><div class="break-words whitespace-pre-wrap text-[length:var(--font-size-base)] leading-[1.5]">Can I break my lease early?</div></div></div></div>"`)
+  })
+
+  it("renders AgentTimeline messages as before", () => {
+    expect(
+      html(
+        <AgentTimeline
+          items={[
+            { id: "u1", kind: "message", role: "user", content: "Can I break my lease early?" },
+            { id: "a1", kind: "message", role: "assistant", content: "It depends on the lease terms." },
+          ]}
+        />,
+      ),
+    ).toMatchInlineSnapshot(`"<div class="mx-auto flex w-full max-w-5xl flex-col px-4 py-4"><div data-timeline-step="user" class=""><div class="flex justify-end"><div class="group flex min-w-0 max-w-[78%] flex-col items-end gap-2"><div class="relative w-full min-w-0 rounded-2xl bg-foreground px-4 py-3 text-background"><div class="break-words whitespace-pre-wrap text-[length:var(--font-size-base)] leading-[1.5]">Can I break my lease early?</div></div></div></div></div><div data-timeline-step="prose" class="mt-4"><div><div class="tangle-prose max-w-none tangle-prose text-[length:var(--font-size-base)] leading-[1.5]"><p>It depends on the lease terms.</p></div></div></div></div>"`)
+  })
+})
+
+const client: ChatAuthor = { id: "client-maria", name: "Maria Lopez", role: "Client" }
+const attorney: ChatAuthor = { id: "attorney-jane", name: "Jane Doe", role: "Attorney" }
+const agent: ChatAuthor = { id: "agent-intake", name: "Intake assistant", role: "AI" }
+
+/** The bubble that holds a message's text. */
+function bubbleOf(text: string): HTMLElement {
+  return screen.getByText(text).parentElement as HTMLElement
+}
+
+describe("a viewerId without authors", () => {
+  it("changes nothing", () => {
+    expect(html(<UserMessage content="Hello" viewerId="client-maria" />)).toBe(html(<UserMessage content="Hello" />))
+    expect(html(<ChatMessage role="user" content="Hello" viewerId="client-maria" />)).toBe(
+      html(<ChatMessage role="user" content="Hello" />),
+    )
+  })
+})
+
+describe("isViewerMessage", () => {
+  it("treats an unauthored message as the reader's, and an authored one only when it is the viewer", () => {
+    expect(isViewerMessage(undefined, undefined)).toBe(true)
+    expect(isViewerMessage(undefined, "client-maria")).toBe(true)
+    expect(isViewerMessage(client, "client-maria")).toBe(true)
+    expect(isViewerMessage(attorney, "client-maria")).toBe(false)
+    expect(isViewerMessage(client, undefined)).toBe(false)
+  })
+})
+
+describe("MessageAuthor", () => {
+  it("shows the name, the role as a tag, and initials in a decorative avatar", () => {
+    const { container } = render(<MessageAuthor author={attorney} />)
+    expect(screen.getByText("Jane Doe")).toBeInTheDocument()
+    expect(screen.getByText("Attorney")).toBeInTheDocument()
+    const avatar = container.querySelector("[aria-hidden]")
+    expect(avatar?.textContent).toBe("JD")
+  })
+
+  it("omits the tag when the author has no role", () => {
+    const { container } = render(<MessageAuthor author={{ id: "guest", name: "Guest" }} />)
+    expect(container.querySelectorAll("span")).toHaveLength(2)
+  })
+
+  it("keys the avatar tone to the id, so two people with one name stay apart", () => {
+    const tones = (author: ChatAuthor) => render(<MessageAuthor author={author} />).container.querySelector("[aria-hidden]")!.className
+    const first = tones({ id: "client-maria", name: "Sam Lee" })
+    expect(tones({ id: "client-maria", name: "Sam Lee" })).toBe(first)
+    expect(tones({ id: "attorney-jane", name: "Sam Lee" })).not.toBe(first)
+  })
+})
+
+describe("UserMessage with an author", () => {
+  it("renders the reader's own message exactly as an unauthored one", () => {
+    expect(html(<UserMessage content="Hello" author={client} viewerId={client.id} />)).toBe(html(<UserMessage content="Hello" />))
+  })
+
+  it("puts someone else's message at the start, on a card, under their name and role", () => {
+    const { container } = render(<UserMessage content="Did you give a forwarding address?" author={attorney} viewerId={client.id} />)
+    expect(container.firstElementChild?.className).toContain("justify-start")
+    expect(bubbleOf("Did you give a forwarding address?").className).toContain("bg-card")
+    expect(bubbleOf("Did you give a forwarding address?").className).not.toContain("bg-foreground")
+    expect(screen.getByText("Jane Doe")).toBeInTheDocument()
+    expect(screen.getByText("Attorney")).toBeInTheDocument()
+  })
+
+  it("names every author when there is no viewer", () => {
+    render(<UserMessage content="Hello" author={client} />)
+    expect(screen.getByText("Maria Lopez")).toBeInTheDocument()
+  })
+
+  it("names the author once above a message split by application notes", () => {
+    const { container } = render(<UserMessage parts={segmentedParts} author={attorney} viewerId={client.id} />)
+    expect(screen.getAllByText("Jane Doe")).toHaveLength(1)
+    expect(container.querySelectorAll("[data-message-author]")).toHaveLength(1)
+    expect(bubbleOf("Here it is.").className).toContain("bg-card")
+  })
+})
+
+describe("ChatMessage with an author", () => {
+  it("keeps the reader's label on their own message", () => {
+    render(<ChatMessage role="user" content="Hello" author={client} viewerId={client.id} />)
+    expect(screen.getByText("You")).toBeInTheDocument()
+    expect(screen.queryByText("Maria Lopez")).not.toBeInTheDocument()
+  })
+
+  it("names someone else at the start of the row, on a card", () => {
+    const { container } = render(<ChatMessage role="user" content="Hello Maria" author={attorney} viewerId={client.id} />)
+    expect(container.firstElementChild?.className).toContain("items-start")
+    expect(screen.queryByText("You")).not.toBeInTheDocument()
+    expect(screen.getByText("Jane Doe")).toBeInTheDocument()
+    expect(bubbleOf("Hello Maria").className).toContain("bg-card")
+  })
+
+  it("names the agent in place of the assistant label", () => {
+    render(<ChatMessage role="assistant" content="Noted." author={agent} />)
+    expect(screen.queryByText("Agent")).not.toBeInTheDocument()
+    expect(screen.getByText("Intake assistant")).toBeInTheDocument()
+  })
+})
+
+describe("AgentTimeline with three participants", () => {
+  const thread: AgentTimelineItem[] = [
+    { id: "m1", kind: "message", role: "user", author: client, content: "My landlord kept my deposit." },
+    { id: "m2", kind: "message", role: "assistant", author: agent, content: "I shared your summary with Jane Doe." },
+    {
+      id: "t1",
+      kind: "tool",
+      call: { id: "c1", type: "write", label: "Write", status: "success", detail: "intake/summary.md" },
+    },
+    { id: "m3", kind: "message", role: "assistant", author: agent, content: "The summary has your lease dates." },
+    { id: "m4", kind: "message", role: "user", author: attorney, content: "Did you give a forwarding address?" },
+    { id: "m5", kind: "message", role: "assistant", author: agent, content: "I added the email to the case file." },
+  ]
+
+  it("sets the client's own words apart from the attorney's on the client's screen", () => {
+    render(<AgentTimeline items={thread} viewerId={client.id} />)
+    expect(bubbleOf("My landlord kept my deposit.").className).toContain("bg-foreground")
+    expect(screen.queryByText("Maria Lopez")).not.toBeInTheDocument()
+    expect(bubbleOf("Did you give a forwarding address?").className).toContain("bg-card")
+    expect(screen.getByText("Jane Doe")).toBeInTheDocument()
+  })
+
+  it("mirrors the thread on the attorney's screen", () => {
+    render(<AgentTimeline items={thread} viewerId={attorney.id} />)
+    expect(bubbleOf("Did you give a forwarding address?").className).toContain("bg-foreground")
+    expect(bubbleOf("My landlord kept my deposit.").className).toContain("bg-card")
+    expect(screen.getByText("Maria Lopez")).toBeInTheDocument()
+    expect(screen.queryByText("Jane Doe")).not.toBeInTheDocument()
+  })
+
+  it("names the agent once per turn, not after each tool row", () => {
+    const { container } = render(<AgentTimeline items={thread} viewerId={client.id} />)
+    const steps = Array.from(container.querySelectorAll("[data-timeline-step='prose']"))
+    const named = steps.map((step) => within(step as HTMLElement).queryByText("Intake assistant") !== null)
+    // m2 opens the agent's turn, m3 continues it after the tool row, m5 follows the attorney.
+    expect(named).toEqual([true, false, true])
+  })
+})

package/src/chat/message-author.tsx

@@ -0,0 +1,52 @@
+import type { HTMLAttributes } from "react";
+import { cn } from "../lib/utils";
+import { IconTile } from "../primitives/icon-tile";
+import { Tag } from "../primitives/tag";
+import { toneFor } from "../primitives/tone";
+import type { ChatAuthor } from "../types/message";
+
+/**
+ * Whether the reader wrote a human message. A message without an author is
+ * the reader's, which keeps a two-party transcript as it was. A message with
+ * an author is the reader's only when that author is `viewerId`; with no
+ * `viewerId`, every authored message belongs to someone else.
+ */
+export function isViewerMessage(author: ChatAuthor | undefined, viewerId: string | undefined): boolean {
+  return author === undefined || author.id === viewerId;
+}
+
+export interface MessageAuthorProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+  author: ChatAuthor;
+}
+
+/**
+ * The line above a message in a transcript with several participants: the
+ * author's avatar, name and, when given, their role as a tag.
+ *
+ * The avatar's tone comes from the author's id, so a participant keeps one
+ * colour for the whole thread and in every product. Tones can repeat between
+ * participants, so the name is always shown beside it. The avatar repeats the
+ * visible name and is hidden from assistive technology.
+ */
+export function MessageAuthor({ author, className, ...props }: MessageAuthorProps) {
+  return (
+    <div data-message-author="" className={cn("flex min-w-0 max-w-full items-center gap-2", className)} {...props}>
+      <IconTile
+        size="xs"
+        src={author.avatarUrl}
+        name={author.name}
+        tone={toneFor(author.id)}
+        className="rounded-full"
+      />
+      <span className="min-w-0 truncate font-medium text-foreground text-sm" title={author.name}>
+        {author.name}
+      </span>
+      {author.role ? (
+        // A long role truncates at half the row, so it never hides the name.
+        <Tag size="sm" emphasis="outline" className="max-w-[50%]">
+          {author.role}
+        </Tag>
+      ) : null}
+    </div>
+  );
+}

package/src/chat/user-message.tsx

@@ -1,6 +1,7 @@
 import { memo, type ReactNode } from "react";
-import type { SessionMessage } from "../types/message";
+import type { ChatAuthor, SessionMessage } from "../types/message";
 import type { SessionPart } from "../types/parts";
+import { isViewerMessage, MessageAuthor } from "./message-author";
 import { SyntheticText, userTextSegments } from "./synthetic-text";
 
 export interface UserMessageProps {
@@ -11,15 +12,25 @@ export interface UserMessageProps {
   content?: string;
   timestamp?: Date;
   actions?: ReactNode;
+  /**
+   * Who wrote the message, when more than one person shares the transcript.
+   * Omit it in a two-party chat: the message renders as the reader's.
+   */
+  author?: ChatAuthor;
+  /**
+   * The reader's participant id. A message whose `author` has another id is
+   * someone else's: it sits at the start, on a card, under its author.
+   */
+  viewerId?: string;
 }
 
 function formatTime(date: Date): string {
   return date.toLocaleTimeString(undefined, { hour: "numeric", minute: "2-digit" });
 }
 
-function MessageActions({ children }: { children: ReactNode }) {
+function MessageActions({ children, align = "end" }: { children: ReactNode; align?: "start" | "end" }) {
   return (
-    <div className="flex flex-wrap items-center justify-end gap-1.5 text-xs text-muted-foreground">
+    <div className={`flex flex-wrap items-center ${align === "end" ? "justify-end" : "justify-start"} gap-1.5 text-xs text-muted-foreground`}>
       {children}
     </div>
   );
@@ -52,29 +63,73 @@ function UserBubble({ text, timestamp, actions }: {
   );
 }
 
+/**
+ * Another person's speech: start-aligned under its author, on a card rather
+ * than the reader's inverse fill, so "mine" and "theirs" differ before the
+ * names are read. The timestamp is revealed on the bubble's far side.
+ */
+function OtherPersonBubble({ text, timestamp, actions, author }: {
+  text: string;
+  timestamp?: Date;
+  actions?: ReactNode;
+  /** The author line; absent on a later segment of the same message. */
+  author?: ChatAuthor;
+}) {
+  return (
+    <div className="flex justify-start">
+      <div className="group flex min-w-0 max-w-[78%] flex-col items-start gap-1.5">
+        {author ? <MessageAuthor author={author} /> : null}
+        <div className="relative min-w-0 max-w-full rounded-2xl border border-border bg-card px-4 py-3 text-foreground">
+          {timestamp ? (
+            <span
+              data-user-message-time=""
+              className="pointer-events-none absolute left-full top-1/2 ml-3 -translate-y-1/2 whitespace-nowrap text-[length:var(--font-size-xs)] text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100"
+            >
+              {formatTime(timestamp)}
+            </span>
+          ) : null}
+          <div className="break-words whitespace-pre-wrap text-[length:var(--font-size-base)] leading-[1.5]">
+            {text}
+          </div>
+        </div>
+        {actions ? <MessageActions align="start">{actions}</MessageActions> : null}
+      </div>
+    </div>
+  );
+}
+
 /**
  * User speech retains the inverse-theme bubble and direct-content contract.
  * Application notes interrupt the bubble in source order, outside its attribution.
  */
 export const UserMessage = memo(
-  ({ message: _message, parts, content, timestamp, actions }: UserMessageProps) => {
+  ({ message: _message, parts, content, timestamp, actions, author, viewerId }: UserMessageProps) => {
+    const other = isViewerMessage(author, viewerId) ? undefined : author;
+    // `headed` puts the author line on the first spoken segment only.
+    const bubble = (text: string, bubbleActions?: ReactNode, headed = true, key?: number) =>
+      other ? (
+        <OtherPersonBubble key={key} text={text} timestamp={timestamp} actions={bubbleActions} author={headed ? other : undefined} />
+      ) : (
+        <UserBubble key={key} text={text} timestamp={timestamp} actions={bubbleActions} />
+      );
     // Explicit direct content (including empty content) still overrides parts.
     if (content != null) {
-      return content.trim() ? <UserBubble text={content} timestamp={timestamp} actions={actions} /> : null;
+      return content.trim() ? bubble(content, actions) : null;
     }
     const segments = userTextSegments(parts ?? []);
     if (segments.length === 0) return null;
     if (segments.length === 1 && !segments[0].synthetic) {
-      return <UserBubble text={segments[0].text} timestamp={timestamp} actions={actions} />;
+      return bubble(segments[0].text, actions);
     }
+    const firstSpoken = segments.find((segment) => !segment.synthetic);
     return (
       <div className="space-y-2">
         {segments.map((segment) => segment.synthetic ? (
           <SyntheticText key={segment.index} text={segment.text} />
         ) : (
-          <UserBubble key={segment.index} text={segment.text} timestamp={timestamp} />
+          bubble(segment.text, undefined, segment === firstSpoken, segment.index)
         ))}
-        {actions ? <MessageActions>{actions}</MessageActions> : null}
+        {actions ? <MessageActions align={other ? "start" : "end"}>{actions}</MessageActions> : null}
       </div>
     );
   },

package/src/markdown/code-block.test.tsx

@@ -17,7 +17,8 @@ describe("CodeBlock scoped semantic colors", () => {
   it("keeps code readable before the renderer loads, then applies live semantic colors and line numbers", async () => {
     const { container } = render(<CodeBlock code={'const message = "hello";'} language="javascript" showLineNumbers />);
     expect(container.querySelector("pre code")?.textContent).toBe('const message = "hello";');
-    await waitFor(() => expect(container.innerHTML).toContain("var(--syntax-keyword, currentColor)"));
+    // The highlighter loads asynchronously; under a full parallel run it can take longer than waitFor's 1s default.
+    await waitFor(() => expect(container.innerHTML).toContain("var(--syntax-keyword, currentColor)"), { timeout: 10_000 });
     expect(container.innerHTML).toContain("var(--syntax-string, currentColor)");
     expect(container.innerHTML).toContain("var(--syntax-comment, currentColor)");
     expect(container.querySelector(".react-syntax-highlighter-line-number")).not.toBeNull();