@marktiderman/genesis-chat 0.1.1 → 0.2.1

package/src/__tests__/web.test.tsx

@@ -0,0 +1,349 @@
+/**
+ * @vitest-environment happy-dom
+ * @feat:chat
+ */
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { act, cleanup, configure, fireEvent, render, screen, waitFor, within } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { ChatProvider } from "../react";
+import { ChatComposer, ChatInbox, ChatThread, VoiceNote, createMemoryChatClient, type MemoryChatClient, type MemoryConversationSeed } from "../web";
+
+afterEach(cleanup);
+// Generous waits: these run in parallel with other suites in CI.
+configure({ asyncUtilTimeout: 4000 });
+
+const ME = "00000000-0000-4000-8000-0000000000a1";
+const SAM = "00000000-0000-4000-8000-0000000000b2";
+const LEE = "00000000-0000-4000-8000-0000000000c3";
+const names: Record<string, string> = { [ME]: "Me", [SAM]: "Sam", [LEE]: "Lee" };
+const resolveUser = (id: string) => ({ name: names[id] ?? "Someone" });
+const at = (min: number) => new Date(Date.now() - (60 - min) * 60_000).toISOString();
+
+function mount(client: MemoryChatClient, ui: ReactNode) {
+  const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  return render(
+    <QueryClientProvider client={queryClient}>
+      <ChatProvider client={client} userId={ME}>
+        {ui}
+      </ChatProvider>
+    </QueryClientProvider>,
+  );
+}
+
+const group = (over: Partial<MemoryConversationSeed> = {}): MemoryConversationSeed => ({
+  id: "c1",
+  title: "Morning crew",
+  members: [{ userId: ME }, { userId: SAM }, { userId: LEE }],
+  messages: [
+    { id: "m1", kind: "system", body: "Sam started the conversation", createdAt: at(1) },
+    { id: "m2", senderId: SAM, body: "Hello **there**", createdAt: at(2), reactions: [{ emoji: "👍", userId: SAM }] },
+    { id: "m3", senderId: ME, body: "Hi Sam", createdAt: at(3) },
+    { id: "m4", senderId: LEE, body: "", deletedAt: at(5), createdAt: at(4) },
+  ],
+  ...over,
+});
+
+describe("ChatThread", () => {
+  it("draws theirs, mine, system, deleted and internal notes, each labelled for screen readers", async () => {
+    const client = createMemoryChatClient({
+      me: ME,
+      conversations: [
+        group({
+          myRole: "observer",
+          members: [{ userId: SAM }, { userId: LEE }, { userId: "00000000-0000-4000-8000-0000000000d4" }],
+          messages: [
+            ...group().messages!,
+            { id: "m5", senderId: ME, body: "Check in with Sam", visibility: "observers", createdAt: at(6) },
+          ],
+        }),
+      ],
+    });
+    mount(client, <ChatThread conversationId="c1" resolveUser={resolveUser} />);
+
+    expect(await screen.findByText("Sam started the conversation")).toBeTruthy();
+    const theirs = screen.getByTestId("genesis-chat-theirs");
+    expect(theirs.textContent).toContain("Hello there");
+    expect(theirs.querySelector("strong")?.textContent).toBe("there");
+    expect(screen.getAllByTestId("genesis-chat-mine")[0]!.textContent).toContain("Hi Sam");
+    expect(screen.getByTestId("genesis-chat-deleted").textContent).toContain("Message deleted");
+    const note = screen.getByTestId("genesis-chat-note");
+    expect(note.textContent).toContain("Internal note");
+    expect(note.textContent).toContain("Check in with Sam");
+    // Every bubble carries "Name, time: text".
+    const labels = screen.getAllByRole("article").map((a) => a.getAttribute("aria-label"));
+    expect(labels.some((l) => /^Sam, .+: Hello there$/.test(l ?? ""))).toBe(true);
+    expect(labels.some((l) => /^You, .+: Hi Sam$/.test(l ?? ""))).toBe(true);
+    expect(labels.some((l) => /internal note/.test(l ?? ""))).toBe(true);
+    // In a group, others' names show.
+    expect(screen.getAllByText("Sam").length).toBeGreaterThan(0);
+  });
+
+  it("sends on Enter, shows it as sending, then as sent", async () => {
+    const client = createMemoryChatClient({ me: ME, conversations: [group()] });
+    mount(client, <ChatThread conversationId="c1" resolveUser={resolveUser} />);
+    const input = await screen.findByTestId("genesis-chat-input");
+    // The send waits until the test lets it go, so the sending state is on screen when it's checked.
+    const release = client.holdNextSend();
+    fireEvent.change(input, { target: { value: "On my way" } });
+    fireEvent.keyDown(input, { key: "Enter" });
+
+    expect(await screen.findByTestId("genesis-chat-pending-sending")).toBeTruthy();
+    expect(await screen.findByText("Sending…")).toBeTruthy();
+    expect((input as HTMLTextAreaElement).value).toBe("");
+    release();
+    await waitFor(() => expect(screen.queryByTestId("genesis-chat-pending-sending")).toBeNull());
+    const sends = client.calls.filter((c) => c.method === "send");
+    expect(sends).toHaveLength(1);
+    expect(sends[0]!.args[0]).toMatchObject({ conversationId: "c1", body: "On my way", visibility: "everyone" });
+    expect(screen.getAllByTestId("genesis-chat-mine").some((b) => b.textContent?.includes("On my way"))).toBe(true);
+  });
+
+  it("Shift+Enter is a new line, not a send", async () => {
+    const client = createMemoryChatClient({ me: ME, conversations: [group()] });
+    mount(client, <ChatThread conversationId="c1" resolveUser={resolveUser} />);
+    const input = await screen.findByTestId("genesis-chat-input");
+    fireEvent.change(input, { target: { value: "line one" } });
+    fireEvent.keyDown(input, { key: "Enter", shiftKey: true });
+    expect(client.calls.some((c) => c.method === "send")).toBe(false);
+  });
+
+  it("a failed send says Not sent, and Retry sends it again with the same clientId", async () => {
+    const client = createMemoryChatClient({ me: ME, conversations: [group()] });
+    client.failNextSends(1);
+    mount(client, <ChatThread conversationId="c1" resolveUser={resolveUser} />);
+    const input = await screen.findByTestId("genesis-chat-input");
+    fireEvent.change(input, { target: { value: "Are you there?" } });
+    fireEvent.click(screen.getByTestId("genesis-chat-send"));
+
+    const failed = await screen.findByTestId("genesis-chat-pending-failed");
+    expect(within(failed).getByRole("alert").textContent).toMatch(/Not sent/);
+    await act(async () => {
+      fireEvent.click(within(failed).getByTestId("genesis-chat-retry"));
+    });
+    await waitFor(() => expect(screen.queryByTestId("genesis-chat-pending-failed")).toBeNull());
+    const sends = client.calls.filter((c) => c.method === "send").map((c) => c.args[0] as { clientId: string });
+    expect(sends).toHaveLength(2);
+    expect(sends[0]!.clientId).toBe(sends[1]!.clientId);
+    expect(screen.getAllByTestId("genesis-chat-mine").some((b) => b.textContent?.includes("Are you there?"))).toBe(true);
+  });
+
+  it("Delete on a failed message throws it away", async () => {
+    const client = createMemoryChatClient({ me: ME, conversations: [group()] });
+    client.failNextSends(1);
+    mount(client, <ChatThread conversationId="c1" resolveUser={resolveUser} />);
+    const input = await screen.findByTestId("genesis-chat-input");
+    fireEvent.change(input, { target: { value: "never mind" } });
+    fireEvent.keyDown(input, { key: "Enter" });
+    const failed = await screen.findByTestId("genesis-chat-pending-failed");
+    await act(async () => {
+      fireEvent.click(within(failed).getByTestId("genesis-chat-discard"));
+    });
+    await waitFor(() => expect(screen.queryByTestId("genesis-chat-pending-failed")).toBeNull());
+    expect(screen.queryByText("never mind")).toBeNull();
+  });
+
+  it("clicking a reaction chip toggles yours", async () => {
+    const client = createMemoryChatClient({ me: ME, conversations: [group()] });
+    mount(client, <ChatThread conversationId="c1" resolveUser={resolveUser} />);
+    const chip = await screen.findByTestId("genesis-chat-reaction-👍");
+    expect(chip.getAttribute("aria-pressed")).toBe("false");
+    expect(chip.textContent).toContain("1");
+    await act(async () => {
+      fireEvent.click(chip);
+    });
+    expect(client.calls.find((c) => c.method === "react")?.args).toEqual(["m2", "👍", true]);
+    await waitFor(() => expect(screen.getByTestId("genesis-chat-reaction-👍").getAttribute("aria-pressed")).toBe("true"));
+    expect(screen.getByTestId("genesis-chat-reaction-👍").textContent).toContain("2");
+
+    await act(async () => {
+      fireEvent.click(screen.getByTestId("genesis-chat-reaction-👍"));
+    });
+    expect(client.calls.filter((c) => c.method === "react").at(-1)?.args).toEqual(["m2", "👍", false]);
+    await waitFor(() => expect(screen.getByTestId("genesis-chat-reaction-👍").getAttribute("aria-pressed")).toBe("false"));
+  });
+
+  it("a reply quote scrolls to and highlights the original", async () => {
+    const client = createMemoryChatClient({
+      me: ME,
+      conversations: [group({ messages: [...group().messages!, { id: "m6", senderId: SAM, body: "Yes!", replyToId: "m3", createdAt: at(7) }] })],
+    });
+    mount(client, <ChatThread conversationId="c1" resolveUser={resolveUser} />);
+    const quote = await screen.findByTestId("genesis-chat-reply-quote");
+    expect(quote.textContent).toContain("You");
+    expect(quote.textContent).toContain("Hi Sam");
+    fireEvent.click(quote);
+    await waitFor(() => expect(document.querySelector("#genesis-chat-msg-m3 .ring-2")).not.toBeNull());
+  });
+
+  it("says why you can't post when only admins can", async () => {
+    const client = createMemoryChatClient({ me: ME, conversations: [group({ canPost: false, settings: { who_posts: "admins" } })] });
+    mount(client, <ChatThread conversationId="c1" resolveUser={resolveUser} />);
+    expect((await screen.findByTestId("genesis-chat-cannot-post")).textContent).toContain("Only admins can post here");
+    expect(screen.queryByTestId("genesis-chat-input")).toBeNull();
+  });
+
+  it("tells someone with no role here they can't post, instead of loading forever", async () => {
+    const client = createMemoryChatClient({ me: ME, conversations: [group({ canPost: false, myRole: null })] });
+    mount(client, <ChatThread conversationId="c1" resolveUser={resolveUser} />);
+    expect((await screen.findByTestId("genesis-chat-cannot-post")).textContent).toContain("can't post");
+  });
+
+  it("waits only while the conversation loads, and says can't post once it settles to nothing", () => {
+    const client = createMemoryChatClient({ me: ME, conversations: [] });
+    const state = { send: vi.fn(), signalTyping: vi.fn(), signalRecording: vi.fn(), role: null, canPost: false, accessLoading: false, conversation: null };
+    mount(client, <ChatComposer conversation={{ ...state, conversationLoading: true }} />);
+    expect(screen.queryByTestId("genesis-chat-cannot-post")).toBeNull();
+    cleanup();
+    mount(client, <ChatComposer conversation={{ ...state, conversationLoading: false }} />);
+    expect(screen.getByTestId("genesis-chat-cannot-post").textContent).toContain("can't post");
+  });
+
+  it("announces an incoming message and shows who is typing", async () => {
+    const client = createMemoryChatClient({ me: ME, conversations: [group()] });
+    mount(client, <ChatThread conversationId="c1" resolveUser={resolveUser} />);
+    await screen.findByText("Hi Sam");
+    act(() => client.activity("c1", LEE, "typing"));
+    await waitFor(() => expect(screen.getByTestId("genesis-chat-activity").textContent).toContain("Lee is typing…"));
+    act(() => void client.receive("c1", LEE, "Coming now"));
+    await waitFor(() => expect(screen.getByTestId("genesis-chat-announcer").textContent).toBe("Lee: Coming now"));
+    expect(screen.getByTestId("genesis-chat-announcer").getAttribute("aria-live")).toBe("polite");
+  });
+});
+
+describe("ChatInbox", () => {
+  it("lists conversations with the other person's name, You: previews and unread counts, and selects on click", async () => {
+    const client = createMemoryChatClient({
+      me: ME,
+      conversations: [
+        { id: "d1", members: [{ userId: ME }, { userId: SAM }], messages: [{ senderId: ME, body: "See you **soon**", createdAt: at(10) }], pinned: true },
+        group({ members: [{ userId: ME, lastReadSeq: 0 }, { userId: SAM }, { userId: LEE }], muted: true }),
+      ],
+    });
+    const picked: string[] = [];
+    mount(client, <ChatInbox resolveUser={resolveUser} onSelect={(id) => picked.push(id)} selectedId="d1" />);
+    const row = await screen.findByTestId("genesis-chat-inbox-row-d1");
+    expect(row.textContent).toContain("Sam");
+    expect(row.textContent).toContain("You: See you soon");
+    expect(row.getAttribute("aria-current")).toBe("true");
+    expect(row.getAttribute("aria-label")).toMatch(/pinned/);
+    const groupRow = screen.getByTestId("genesis-chat-inbox-row-c1");
+    expect(groupRow.textContent).toContain("Morning crew");
+    expect(groupRow.getAttribute("aria-label")).toMatch(/2 unread.*muted/);
+    fireEvent.click(groupRow);
+    expect(picked).toEqual(["c1"]);
+    row.focus();
+    fireEvent.keyDown(row, { key: "ArrowDown" });
+    expect(document.activeElement).toBe(groupRow);
+  });
+
+  it("previews a message that is only an app card by its kind's title", async () => {
+    const client = createMemoryChatClient({
+      me: ME,
+      conversations: [{ id: "d1", members: [{ userId: ME }, { userId: SAM }], messages: [{ senderId: SAM, body: "", createdAt: at(10), attachments: [{ kind: "check_in" }] }] }],
+    });
+    const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+    render(
+      <QueryClientProvider client={queryClient}>
+        <ChatProvider client={client} userId={ME} attachmentKinds={{ check_in: { title: () => "Check-in" } }}>
+          <ChatInbox resolveUser={resolveUser} onSelect={() => undefined} />
+        </ChatProvider>
+      </QueryClientProvider>,
+    );
+    expect((await screen.findByTestId("genesis-chat-inbox-row-d1")).textContent).toContain("Check-in");
+  });
+
+  it("shows an empty state when there are none", async () => {
+    const client = createMemoryChatClient({ me: ME, conversations: [] });
+    mount(client, <ChatInbox resolveUser={resolveUser} onSelect={() => undefined} />);
+    expect(await screen.findByText("No conversations yet")).toBeTruthy();
+  });
+});
+
+describe("VoiceNote", () => {
+  it("cycles the speed 1× → 1.5× → 2× → 1× and sets the audio's rate", () => {
+    const { container } = render(<VoiceNote src="https://files.example/v.webm" durationMs={42_000} waveform={[10, 50, 100, 30]} transcript="Hello there" />);
+    const rate = screen.getByTestId("genesis-chat-voice-rate");
+    const audio = container.querySelector("audio")!;
+    expect(rate.textContent).toBe("1×");
+    fireEvent.click(rate);
+    expect(rate.textContent).toBe("1.5×");
+    expect(audio.playbackRate).toBe(1.5);
+    fireEvent.click(rate);
+    expect(rate.textContent).toBe("2×");
+    expect(audio.playbackRate).toBe(2);
+    fireEvent.click(rate);
+    expect(rate.textContent).toBe("1×");
+    expect(screen.getByText("0:42")).toBeTruthy();
+    expect(screen.getByText("Transcript")).toBeTruthy();
+  });
+
+  it("says Transcribing… while the transcript is pending", () => {
+    render(<VoiceNote src={null} durationMs={5000} transcriptStatus="pending" />);
+    expect(screen.getByText("Transcribing…")).toBeTruthy();
+  });
+});
+
+describe("voice notes in the composer", () => {
+  const realMedia = Object.getOwnPropertyDescriptor(navigator, "mediaDevices");
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+    if (realMedia) Object.defineProperty(navigator, "mediaDevices", realMedia);
+  });
+
+  const stubMic = (getUserMedia: () => Promise<unknown>) =>
+    Object.defineProperty(navigator, "mediaDevices", { configurable: true, value: { getUserMedia } });
+
+  class FakeRecorder {
+    static isTypeSupported = (t: string) => t === "audio/webm;codecs=opus";
+    state: "inactive" | "recording" = "inactive";
+    mimeType: string;
+    ondataavailable: ((e: { data: Blob }) => void) | null = null;
+    onstop: (() => void) | null = null;
+    constructor(_stream: unknown, opts?: { mimeType?: string }) {
+      this.mimeType = opts?.mimeType ?? "";
+    }
+    start() {
+      this.state = "recording";
+    }
+    stop() {
+      this.state = "inactive";
+      this.ondataavailable?.({ data: new Blob(["opus"], { type: "audio/webm" }) });
+      this.onstop?.();
+    }
+  }
+
+  it("records with MediaRecorder and sends a voice attachment with its duration and waveform", async () => {
+    let now = 1_000_000;
+    vi.spyOn(Date, "now").mockImplementation(() => now);
+    vi.stubGlobal("MediaRecorder", FakeRecorder);
+    stubMic(async () => ({ getTracks: () => [{ stop() {} }] }));
+    const client = createMemoryChatClient({ me: ME, conversations: [group()] });
+    mount(client, <ChatThread conversationId="c1" resolveUser={resolveUser} />);
+
+    fireEvent.click(await screen.findByTestId("genesis-chat-mic"));
+    await screen.findByTestId("genesis-chat-recording");
+    now += 3_000;
+    await act(async () => {
+      fireEvent.click(screen.getByTestId("genesis-chat-voice-send"));
+    });
+    await waitFor(() => expect(client.calls.some((c) => c.method === "send")).toBe(true));
+    const input = client.calls.find((c) => c.method === "send")!.args[0] as { body: string; attachments: { kind: string; durationMs: number; waveform: number[]; mime: string }[] };
+    expect(input.body).toBe("");
+    expect(input.attachments[0]).toMatchObject({ kind: "voice", durationMs: 3000, mime: "audio/webm" });
+    expect(input.attachments[0]!.waveform).toHaveLength(48);
+    expect(client.calls.find((c) => c.method === "upload")!.args[1]).toMatch(/^voice-.*\.webm$/);
+  });
+
+  it("says so clearly when the microphone is blocked", async () => {
+    vi.stubGlobal("MediaRecorder", FakeRecorder);
+    stubMic(async () => {
+      throw Object.assign(new Error("denied"), { name: "NotAllowedError" });
+    });
+    const client = createMemoryChatClient({ me: ME, conversations: [group()] });
+    mount(client, <ChatThread conversationId="c1" resolveUser={resolveUser} />);
+    fireEvent.click(await screen.findByTestId("genesis-chat-mic"));
+    expect((await screen.findByTestId("genesis-chat-mic-error")).textContent).toMatch(/Microphone access is blocked/);
+  });
+});

package/src/core/availability.ts

@@ -0,0 +1,223 @@
+/**
+ * @feat:chat
+ * Availability, the same on every platform: is someone inside their working hours (read in
+ * their own time zone), are they away, and the one line a thread shows about it ("Mark
+ * replies Mon–Fri, 9–5 (Eastern)", "Away until Monday: Back Monday"). Pure: `now` is passed
+ * in, and time zones come from Intl.
+ */
+import type { ChatAvailability, Weekday, WorkingHours } from "./types";
+
+export const WEEKDAYS: readonly Weekday[] = ["mon", "tue", "wed", "thu", "fri", "sat", "sun"];
+
+const SHORT: Record<Weekday, string> = { mon: "Mon", tue: "Tue", wed: "Wed", thu: "Thu", fri: "Fri", sat: "Sat", sun: "Sun" };
+
+/** "09:30" → 570; a bad value (anything but such a string) → null. "24:00" is allowed as the end of a day. */
+export function minutesOf(hhmm: unknown): number | null {
+  if (typeof hhmm !== "string") return null;
+  const m = /^(\d{1,2}):(\d{2})$/.exec(hhmm.trim());
+  if (!m) return null;
+  const h = Number(m[1]);
+  const min = Number(m[2]);
+  if (h > 24 || min > 59 || (h === 24 && min > 0)) return null;
+  return h * 60 + min;
+}
+
+/** At most this many ranges a day, as the database allows. */
+export const MAX_RANGES_PER_DAY = 4;
+
+/**
+ * Working hours as they may safely be read: only mon..sun, each an array of `["HH:MM", "HH:MM"]`
+ * string pairs (at most four a day); every other day, range or value is dropped. Null when
+ * nothing is left. Hours come from other people, so they are never trusted as typed.
+ */
+export function normalizeHours(raw: unknown): WorkingHours | null {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const src = raw as Record<string, unknown>;
+  const out: WorkingHours = {};
+  let any = false;
+  for (const day of WEEKDAYS) {
+    if (!Object.prototype.hasOwnProperty.call(src, day)) continue;
+    const ranges = src[day];
+    if (!Array.isArray(ranges)) continue;
+    const kept: [string, string][] = [];
+    for (const r of ranges) {
+      if (!Array.isArray(r) || r.length !== 2) continue;
+      const [from, to] = r as unknown[];
+      if (typeof from !== "string" || typeof to !== "string" || minutesOf(from) == null || minutesOf(to) == null) continue;
+      kept.push([from, to]);
+      if (kept.length >= MAX_RANGES_PER_DAY) break;
+    }
+    if (kept.length) {
+      out[day] = kept;
+      any = true;
+    }
+  }
+  return any ? out : null;
+}
+
+/** The weekday and minute of the day at `now` in `timeZone` (the device's zone when null or unknown). */
+export function localClock(now: Date, timeZone?: string | null): { day: Weekday; minutes: number } {
+  let parts: Intl.DateTimeFormatPart[];
+  try {
+    parts = new Intl.DateTimeFormat("en-US", {
+      timeZone: timeZone || undefined,
+      weekday: "short",
+      hour: "2-digit",
+      minute: "2-digit",
+      hourCycle: "h23",
+    }).formatToParts(now);
+  } catch {
+    parts = new Intl.DateTimeFormat("en-US", { weekday: "short", hour: "2-digit", minute: "2-digit", hourCycle: "h23" }).formatToParts(now);
+  }
+  const get = (t: string) => parts.find((p) => p.type === t)?.value ?? "";
+  const day = get("weekday").slice(0, 3).toLowerCase() as Weekday;
+  const hour = Number(get("hour")) % 24;
+  return { day: WEEKDAYS.includes(day) ? day : "mon", minutes: hour * 60 + Number(get("minute")) };
+}
+
+/**
+ * Is `now` inside these working hours, read in `timeZone`? No hours set means always.
+ * A range whose end is at or before its start runs overnight into the next day
+ * (`fri: [["22:00","02:00"]]` covers Friday 22:00 to Saturday 02:00).
+ */
+export function isWithinWorkingHours(raw: WorkingHours | null | undefined, timeZone: string | null | undefined, now: Date = new Date()): boolean {
+  const hours = normalizeHours(raw);
+  if (!hours) return true;
+  const { day, minutes } = localClock(now, timeZone);
+  const yesterday = WEEKDAYS[(WEEKDAYS.indexOf(day) + 6) % 7]!;
+  for (const [from, to] of hours[day] ?? []) {
+    const a = minutesOf(from);
+    const b = minutesOf(to);
+    if (a == null || b == null) continue;
+    if (b > a ? minutes >= a && minutes < b : minutes >= a) return true;
+  }
+  for (const [from, to] of hours[yesterday] ?? []) {
+    const a = minutesOf(from);
+    const b = minutesOf(to);
+    if (a == null || b == null) continue;
+    if (b <= a && minutes < b) return true;
+  }
+  return false;
+}
+
+/** Away now: an away message with no end date, or an end date still ahead. */
+export function isAway(a: Pick<ChatAvailability, "awayMessage" | "awayUntil"> | null | undefined, now: Date = new Date()): boolean {
+  if (!a) return false;
+  if (a.awayUntil) return Date.parse(a.awayUntil) > now.getTime();
+  return Boolean(a.awayMessage?.trim());
+}
+
+/** "9", "9:30", "5" (12-hour, no am/pm: the range reads "9–5"). */
+function clock(hhmm: string): string {
+  const total = minutesOf(hhmm) ?? 0;
+  const h = Math.floor(total / 60) % 24;
+  const m = total % 60;
+  const h12 = h % 12 === 0 ? 12 : h % 12;
+  return m ? `${h12}:${String(m).padStart(2, "0")}` : String(h12);
+}
+
+/** "Mon–Fri, 9–5", "Mon–Thu, 9–5; Fri, 9–1". Days with the same hours are grouped. Empty when none. */
+export function hoursSummary(raw: WorkingHours | null | undefined): string {
+  const hours = normalizeHours(raw);
+  if (!hours) return "";
+  const key = (d: Weekday) => (hours[d] ?? []).map(([a, b]) => `${clock(a)}–${clock(b)}`).join(", ");
+  const runs: { from: Weekday; to: Weekday; text: string }[] = [];
+  for (const d of WEEKDAYS) {
+    const text = key(d);
+    if (!text) continue;
+    const last = runs[runs.length - 1];
+    if (last && last.text === text && WEEKDAYS.indexOf(last.to) === WEEKDAYS.indexOf(d) - 1) last.to = d;
+    else runs.push({ from: d, to: d, text });
+  }
+  return runs
+    .map((r) => {
+      const days = r.from === r.to ? SHORT[r.from] : WEEKDAYS.indexOf(r.to) - WEEKDAYS.indexOf(r.from) === 1 ? `${SHORT[r.from]}, ${SHORT[r.to]}` : `${SHORT[r.from]}–${SHORT[r.to]}`;
+      return `${days}, ${r.text}`;
+    })
+    .join("; ");
+}
+
+/** "Eastern" for America/New_York (the zone's generic name, less " Time"); the city when Intl has no name. */
+export function timeZoneLabel(timeZone: string | null | undefined, locale = "en-US"): string {
+  if (!timeZone) return "";
+  try {
+    const name = new Intl.DateTimeFormat(locale, { timeZone, timeZoneName: "longGeneric" })
+      .formatToParts(new Date())
+      .find((p) => p.type === "timeZoneName")?.value;
+    if (name && !/^GMT|^UTC/.test(name)) return name.replace(/ Time$/, "");
+  } catch {
+    // an unknown zone: fall through
+  }
+  return (timeZone.split("/").pop() ?? timeZone).replace(/_/g, " ");
+}
+
+/** "3:00 PM" today, "Monday" within the week, else "12 Mar". */
+export function untilLabel(iso: string, now: Date = new Date(), locale?: string, timeZone?: string | null): string {
+  const d = new Date(iso);
+  if (!Number.isFinite(d.getTime())) return "later";
+  try {
+    return untilIn(d, now, locale, timeZone || undefined);
+  } catch {
+    // An unknown zone or locale: the device's.
+    return untilIn(d, now, undefined, undefined);
+  }
+}
+
+function untilIn(d: Date, now: Date, locale: string | undefined, tz: string | undefined): string {
+  const dayKey = (x: Date) => new Intl.DateTimeFormat("en-CA", { timeZone: tz, year: "numeric", month: "2-digit", day: "2-digit" }).format(x);
+  if (dayKey(d) === dayKey(now)) return d.toLocaleTimeString(locale, { hour: "numeric", minute: "2-digit", timeZone: tz });
+  const days = (d.getTime() - now.getTime()) / 86_400_000;
+  if (days < 7) return d.toLocaleDateString(locale, { weekday: "long", timeZone: tz });
+  return d.toLocaleDateString(locale, { day: "numeric", month: "short", timeZone: tz });
+}
+
+export interface AwayLineOptions {
+  now?: Date;
+  locale?: string;
+  /** Show the hours line even inside working hours (a profile, not a banner). */
+  always?: boolean;
+}
+
+/**
+ * The line a thread shows about someone, or null when they are around:
+ * - away with a date: "Away until Monday: Back Monday" (the away message after the colon);
+ * - away with no date: "Mark is away: On a retreat";
+ * - outside working hours: "Mark replies Mon–Fri, 9–5 (Eastern)".
+ */
+export function awayLine(a: ChatAvailability | null | undefined, name: string, opts: AwayLineOptions = {}): string | null {
+  if (!a) return null;
+  const now = opts.now ?? new Date();
+  const message = a.awayMessage?.trim();
+  if (isAway(a, now)) {
+    if (a.awayUntil) return `Away until ${untilLabel(a.awayUntil, now, opts.locale, a.timeZone)}${message ? `: ${message}` : ""}`;
+    return `${name} is away${message ? `: ${message}` : ""}`;
+  }
+  const summary = hoursSummary(a.hours);
+  if (!summary) return null;
+  if (!opts.always && isWithinWorkingHours(a.hours, a.timeZone, now)) return null;
+  const zone = timeZoneLabel(a.timeZone, opts.locale);
+  return `${name} replies ${summary}${zone ? ` (${zone})` : ""}`;
+}
+
+/** "Sam", "Sam and Lee", "Sam, Lee and 3 others": at most two names. */
+export function namesLine(names: string[]): string {
+  if (names.length <= 1) return names[0] ?? "";
+  if (names.length === 2) return `${names[0]} and ${names[1]}`;
+  const rest = names.length - 2;
+  return `${names[0]}, ${names[1]} and ${rest === 1 ? "1 other" : `${rest} others`}`;
+}
+
+/**
+ * The line for several people (a group's members): one person's full `awayLine`, or for more
+ * "Sam and Lee are away", "Sam, Lee and 2 others are outside their hours", or "… are away or
+ * outside their hours" when it's a mix. Null when everyone is around.
+ */
+export function awaySummary(people: { availability: ChatAvailability | null | undefined; name: string }[], opts: AwayLineOptions = {}): string | null {
+  const now = opts.now ?? new Date();
+  const out = people.filter((p) => awayLine(p.availability, p.name, { ...opts, now, always: false }) !== null);
+  if (out.length === 0) return null;
+  if (out.length === 1) return awayLine(out[0]!.availability, out[0]!.name, { ...opts, now, always: false });
+  const away = out.filter((p) => isAway(p.availability, now)).length;
+  const what = away === out.length ? "away" : away === 0 ? "outside their hours" : "away or outside their hours";
+  return `${namesLine(out.map((p) => p.name))} are ${what}`;
+}