@heyramzi/ui 2.8.0 → 2.10.0

package/src/inbox/logic.ts

@@ -1,8 +1,9 @@
-import { isOpen, isTyping } from "../tasks/inbox/inbox-logic.js";
+import { isOpen, isTyping } from "../work/inbox/inbox-logic.js";
 import {
   ALL,
   DEFAULT_INBOX_LABELS,
   type InboxEntry,
+  type InboxEntryKind,
   type InboxFilter,
   type InboxKey,
   type InboxLabels,
@@ -97,13 +98,15 @@ export function subjectTypes(threads: InboxThread[]): string[] {
 }
 
 export function actorNames(threads: InboxThread[]): string[] {
-  return [...new Set(threads.flatMap((thread) => thread.entries.map((entry) => entry.actor.name)))];
+  return [
+    ...new Set(threads.flatMap((thread) => thread.entries.map((entry) => entry.actor.name))),
+  ].filter(Boolean);
 }
 
 type KeyEventLike = Pick<
   KeyboardEvent,
   "key" | "metaKey" | "ctrlKey" | "altKey" | "defaultPrevented" | "target"
->;
+> & { shiftKey?: boolean; code?: string };
 
 const KEYS: Record<string, InboxKey> = {
   j: "next",
@@ -113,13 +116,20 @@ const KEYS: Record<string, InboxKey> = {
   a: "approve",
   d: "decline",
   s: "steer",
+  S: "unfollow",
   e: "edit",
 };
 
-/** What a key press asks for, or null when it isn't ours: a modifier is held, or focus is in a text field. */
+/**
+ * What a key press asks for, or null when it isn't ours: focus is in a text field, or a modifier
+ * other than Linear's Shift+S, Shift+Backspace and Alt+U is held.
+ */
 export function inboxKeyOf(event: KeyEventLike): InboxKey | null {
-  if (event.defaultPrevented || event.metaKey || event.ctrlKey || event.altKey) return null;
+  if (event.defaultPrevented || event.metaKey || event.ctrlKey) return null;
   if (isTyping(event.target)) return null;
+  // Option+U on a Mac types a dead key, so the physical key decides.
+  if (event.altKey) return event.code === "KeyU" && !event.shiftKey ? "readAll" : null;
+  if (event.key === "Backspace") return event.shiftKey ? "clearRead" : "clear";
   return KEYS[event.key] ?? null;
 }
 
@@ -167,3 +177,17 @@ export function entryLine(entry: InboxEntry, labels: InboxLabels): string {
       return labels.commented;
   }
 }
+
+/** An entry as a sentence: who, then what. With no known actor it starts with the verb, capitalised. */
+export function sentenceOf(entry: InboxEntry, labels: InboxLabels): string {
+  const line = entryLine(entry, labels);
+  if (entry.actor.name) return `${entry.actor.name} ${line}`;
+  return line.charAt(0).toUpperCase() + line.slice(1);
+}
+
+/** What happened to the subject, as against something a person wrote. */
+const EVENT_KINDS: ReadonlySet<InboxEntryKind> = new Set(["status", "assigned", "proposal"]);
+
+export function isEvent(entry: InboxEntry): boolean {
+  return EVENT_KINDS.has(entry.kind);
+}

package/src/inbox/thread-inbox.svelte

@@ -1,7 +1,19 @@
 <script lang="ts">
 	import { tick, type Snippet } from "svelte";
-	import { ArrowSquareOut, BellSlash, Circle, Envelope, EnvelopeOpen } from "phosphor-svelte";
-	import { AgentAvatar } from "../agents/index.js";
+	import {
+		ArrowRight,
+		ArrowSquareOut,
+		Bell,
+		BellSlash,
+		Check,
+		Checks,
+		Circle,
+		Envelope,
+		EnvelopeOpen,
+		EyeSlash,
+		Sparkle,
+		UserPlus,
+	} from "phosphor-svelte";
 	import DetailHeader from "../components/list-page/detail-header.svelte";
 	import DetailPanel from "../components/list-page/detail-panel.svelte";
 	import FilterItem from "../components/list-page/filter-item.svelte";
@@ -18,12 +30,20 @@
 	import { Kbd, KbdGroup } from "../shadcn/kbd/index.js";
 	import { cn } from "../lib/utils.js";
 	import { TONE_CLASS } from "../lib/tone.js";
-	import InboxCard from "../tasks/inbox/inbox-card.svelte";
-	import type { InboxItem, InboxVerdict } from "../tasks/inbox/inbox-types.js";
+	import {
+		Thread,
+		type ThreadComment,
+		type ThreadEvent,
+		type ThreadLabels,
+	} from "../thread/index.js";
+	import InboxCard from "../work/inbox/inbox-card.svelte";
+	import { whenOf } from "../work/inbox/inbox-logic.js";
+	import type { InboxItem, InboxVerdict } from "../work/inbox/inbox-types.js";
 	import {
 		NO_FILTER,
 		actorNames,
-		entryLine,
+		sentenceOf,
+		isEvent,
 		filterThreads,
 		inboxKeyOf,
 		resolveInboxLabels,
@@ -57,12 +77,33 @@
 		status?: Snippet<[InboxSubject]>;
 		/** Replaces a pinned proposal's summary lines. */
 		renderProposal?: Snippet<[InboxItem]>;
-		/** How a timestamp reads. Defaults to a short date and time. */
+		/** Content under an entry's text, such as links to what it mentions. */
+		attachments?: Snippet<[InboxEntry]>;
+		/** The words of the thread under the pinned card, such as its "Activity" heading. */
+		threadLabels?: Partial<ThreadLabels>;
+		/** How a timestamp reads. Defaults to a relative time. */
 		when?: (at: string) => string;
 		onSelect?: (thread: InboxThread) => void;
 		/** `read` is true when the thread had unread entries, so the host marks them all read. */
 		onRead?: (thread: InboxThread, read: boolean) => void;
+		/** Alt+U: mark every thread read. */
+		onReadAll?: () => void;
 		onSnooze?: (request: InboxSnooze) => void;
+		/** The host is passing snoozed threads too, each with `subject.snoozedUntil`. */
+		showSnoozed?: boolean;
+		/** Adds "Show snoozed" to the filter. The host passes the snoozed entries or stops. */
+		onShowSnoozed?: (show: boolean) => void;
+		/** `h` on a snoozed thread brings it back now. */
+		onUnsnooze?: (thread: InboxThread) => void;
+		/** Shift+S on a thread whose `subject.followed` is set. */
+		onUnfollow?: (thread: InboxThread) => void;
+		/**
+		 * Backspace: take the thread out of the inbox. The host stops passing its entries, and new
+		 * activity can bring it back. A thread holding a pending proposal can't be cleared.
+		 */
+		onClear?: (thread: InboxThread) => void;
+		/** Shift+Backspace: clear every thread with nothing unread and no pending proposal. */
+		onClearRead?: (threads: InboxThread[]) => void;
 		onDecide?: (verdict: InboxVerdict, thread: InboxThread) => void;
 		class?: string;
 	}
@@ -76,20 +117,19 @@
 		avatar,
 		status,
 		renderProposal,
-		when = (at) => {
-			const date = new Date(at);
-			return Number.isNaN(date.getTime())
-				? ""
-				: date.toLocaleString(undefined, {
-						month: "short",
-						day: "numeric",
-						hour: "numeric",
-						minute: "2-digit",
-					});
-		},
+		attachments,
+		threadLabels,
+		when = (at) => whenOf(at),
 		onSelect,
 		onRead,
+		onReadAll,
 		onSnooze,
+		showSnoozed = false,
+		onShowSnoozed,
+		onUnsnooze,
+		onUnfollow,
+		onClear,
+		onClearRead,
 		onDecide,
 		class: className,
 	}: Props = $props();
@@ -110,14 +150,37 @@
 	let current = $derived(visible.find((thread) => thread.key === selected) ?? visible[0]);
 	let needsYouCount = $derived(all.filter((thread) => thread.pending.length > 0).length);
 	let filtered = $derived(filter.type !== ALL || filter.who !== ALL || filter.needsYou);
-	let narrowed = $derived(Number(filter.type !== ALL) + Number(filter.who !== ALL));
+	let narrowed = $derived(
+		Number(filter.type !== ALL) + Number(filter.who !== ALL) + Number(showSnoozed),
+	);
+	let anyUnread = $derived(all.some((thread) => thread.unread > 0));
 	let views = $derived([
 		{ value: ALL, label: labels.all, count: all.length },
 		{ value: NEEDS_YOU, label: labels.needsYou, count: needsYouCount },
 	]);
+	let readThreads = $derived(
+		all.filter((thread) => thread.unread === 0 && thread.pending.length === 0),
+	);
 	let pinned = $derived(current?.pending[0]);
-	let timeline = $derived(
-		current?.entries.filter((entry) => !current.pending.includes(entry)) ?? [],
+	let rest = $derived(current?.entries.filter((entry) => !current.pending.includes(entry)) ?? []);
+	let byId = $derived(new Map(rest.map((entry) => [entry.id, entry])));
+	let comments = $derived(
+		rest
+			.filter((entry) => !isEvent(entry))
+			.map((entry): ThreadComment => ({
+				id: entry.id,
+				author: entry.actor,
+				body: entry.body ?? "",
+				createdAt: entry.at,
+			})),
+	);
+	let events = $derived(
+		rest.filter(isEvent).map((entry): ThreadEvent => ({
+			id: entry.id,
+			title: sentenceOf(entry, labels),
+			at: entry.at,
+			icon: entry.kind === "status" ? ArrowRight : entry.kind === "assigned" ? UserPlus : Sparkle,
+		})),
 	);
 
 	function open(thread: InboxThread): void {
@@ -143,6 +206,35 @@
 		snoozing = false;
 	}
 
+	/** A snoozed thread comes back at once. Any other opens the snooze row. */
+	function snoozeKey(): void {
+		if (current?.subject.snoozedUntil && onUnsnooze) onUnsnooze(current);
+		else snoozing = !snoozing;
+	}
+
+	function unfollow(): void {
+		if (current?.subject.followed) onUnfollow?.(current);
+	}
+
+	function readAll(): void {
+		if (anyUnread) onReadAll?.();
+	}
+
+	/** Clears the open thread and opens the one below it, or above it at the end of the list. */
+	function clear(): void {
+		if (!current || !onClear || current.pending.length > 0) return;
+		const gone = current;
+		const index = visible.indexOf(gone);
+		const next = visible[index + 1] ?? visible[index - 1];
+		if (next) selected = next.key;
+		snoozing = false;
+		onClear(gone);
+	}
+
+	function clearRead(): void {
+		if (onClearRead && readThreads.length > 0) onClearRead(readThreads);
+	}
+
 	function onkeydown(event: KeyboardEvent): void {
 		if (snoozing && !event.defaultPrevented && !event.metaKey && !event.ctrlKey && !event.altKey) {
 			const choice = snoozeChoices(new Date())[Number(event.key) - 1];
@@ -163,7 +255,11 @@
 			next: () => move(1),
 			previous: () => move(-1),
 			toggleRead,
-			snooze: () => (snoozing = !snoozing),
+			readAll,
+			snooze: snoozeKey,
+			unfollow,
+			clear,
+			clearRead,
 			approve: () => card?.approve(),
 			decline: () => card?.decline(),
 			steer: () => card?.steer(),
@@ -181,32 +277,18 @@
 				: labels.snoozeNextWeek;
 	}
 
-	function initial(name: string): string {
-		return name.trim().charAt(0).toLocaleUpperCase() || "?";
-	}
-
 	function lastEntry(thread: InboxThread): InboxEntry {
 		return thread.entries[thread.entries.length - 1];
 	}
 </script>
 
-{#snippet face(actor: InboxActor)}
-	<span class="relative size-6 shrink-0">
-		{#if avatar}
-			{@render avatar(actor)}
-		{:else if actor.kind === "agent"}
-			<AgentAvatar name={actor.name} size={24} paused interactive={false} />
-		{:else if actor.avatar}
-			<img src={actor.avatar} alt="" class="size-6 rounded-full object-cover" />
-		{:else}
-			<span
-				class="grid size-6 place-items-center rounded-full bg-muted text-xs font-medium text-muted-foreground"
-				aria-hidden="true"
-			>
-				{initial(actor.name)}
-			</span>
-		{/if}
-	</span>
+{#snippet threadAvatar(comment: ThreadComment)}
+	{@render avatar?.(comment.author)}
+{/snippet}
+
+{#snippet threadAttachments(comment: ThreadComment)}
+	{@const entry = byId.get(comment.id)}
+	{#if entry}{@render attachments?.(entry)}{/if}
 {/snippet}
 
 {#snippet subjectStatus()}
@@ -222,11 +304,13 @@
 	class={cn("flex h-full min-h-0 flex-col gap-3", className)}
 	{onkeydown}
 >
+	<!-- WHY *:shrink-0: the header and panels clip their overflow, so they squashed to a sliver
+	     when an expanded card filled the pane. Now the pane scrolls. -->
 	<MasterDetail
 		bind:pane
 		railWidth={queueRailWidth}
 		railClass={queueRailClass}
-		detailClass="flex flex-col gap-4 overflow-y-auto"
+		detailClass="flex flex-col gap-4 overflow-y-auto *:shrink-0"
 		pad={false}
 		backLabel={labels.title}
 		class="min-h-0 flex-1"
@@ -245,9 +329,17 @@
 						label={labels.filter}
 						count={narrowed}
 						align="end"
-						onClear={() => (filter = { ...NO_FILTER, needsYou: filter.needsYou })}
+						onClear={() => {
+							filter = { ...NO_FILTER, needsYou: filter.needsYou };
+							if (showSnoozed) onShowSnoozed?.(false);
+						}}
 						clearLabel={labels.clearFilters}
 					>
+						{#if onShowSnoozed}
+							<FilterItem checked={showSnoozed} onclick={() => onShowSnoozed(!showSnoozed)}>
+								{labels.showSnoozed}
+							</FilterItem>
+						{/if}
 						{#if types.length > 1}
 							<p class={filterSectionClass()}>{labels.kind}</p>
 							{#each [ALL, ...types] as type (type)}
@@ -271,6 +363,32 @@
 							</FilterItem>
 						{/each}
 					</FilterPopover>
+					{#if onReadAll && anyUnread}
+						<Button
+							size="sm"
+							variant="ghost"
+							icon
+							onclick={readAll}
+							aria-label={labels.markAllRead}
+							title={labels.markAllRead}
+							aria-keyshortcuts="Alt+U"
+						>
+							<EnvelopeOpen aria-hidden="true" />
+						</Button>
+					{/if}
+					{#if onClearRead && readThreads.length > 0}
+						<Button
+							size="sm"
+							variant="ghost"
+							icon
+							onclick={clearRead}
+							aria-label={labels.clearRead}
+							title={labels.clearRead}
+							aria-keyshortcuts="Shift+Backspace"
+						>
+							<Checks aria-hidden="true" />
+						</Button>
+					{/if}
 				</div>
 			</RailHead>
 			<RailBody>
@@ -283,12 +401,19 @@
 								titleLines={2}
 								selected={current?.key === thread.key}
 								onclick={() => open(thread)}
-								preview="{last.actor.name} {entryLine(last, labels)}"
-								meta={[thread.subject.ref, when(thread.latestAt)]}
+								preview={sentenceOf(last, labels)}
+								meta={[
+									thread.subject.ref,
+									thread.subject.snoozedUntil
+										? `${labels.snoozed} ${when(thread.subject.snoozedUntil)}`
+										: when(thread.latestAt),
+								]}
 								metaTruncate="last"
 							>
 								{#snippet trailing()}
-									{#if thread.pending.length > 0}
+									{#if thread.subject.snoozedUntil}
+										<BellSlash class="size-3.5 text-muted-foreground" aria-label={labels.snoozed} />
+									{:else if thread.pending.length > 0}
 										<span
 											class={cn(
 												"inline-flex h-5 items-center rounded-sm border px-1.5 font-medium",
@@ -342,15 +467,31 @@
 								<Envelope aria-hidden="true" />{labels.markUnread}
 							{/if}
 						</Button>
-						<Button
-							size="sm"
-							variant="ghost"
-							onclick={() => (snoozing = !snoozing)}
-							aria-expanded={snoozing}
-							aria-keyshortcuts="h"
-						>
-							<BellSlash aria-hidden="true" />{labels.snooze}
-						</Button>
+						{#if current.subject.snoozedUntil && onUnsnooze}
+							<Button size="sm" variant="ghost" onclick={snoozeKey} aria-keyshortcuts="h">
+								<Bell aria-hidden="true" />{labels.unsnooze}
+							</Button>
+						{:else}
+							<Button
+								size="sm"
+								variant="ghost"
+								onclick={snoozeKey}
+								aria-expanded={snoozing}
+								aria-keyshortcuts="h"
+							>
+								<BellSlash aria-hidden="true" />{labels.snooze}
+							</Button>
+						{/if}
+						{#if onUnfollow && current.subject.followed}
+							<Button size="sm" variant="ghost" onclick={unfollow} aria-keyshortcuts="Shift+S">
+								<EyeSlash aria-hidden="true" />{labels.unfollow}
+							</Button>
+						{/if}
+						{#if onClear && current.pending.length === 0}
+							<Button size="sm" variant="ghost" onclick={clear} aria-keyshortcuts="Backspace">
+								<Check aria-hidden="true" />{labels.clear}
+							</Button>
+						{/if}
 						{#if current.subject.href}
 							<Button size="sm" variant="ghost" href={current.subject.href}>
 								<ArrowSquareOut aria-hidden="true" />{labels.open}
@@ -376,46 +517,24 @@
 						selected={entry === pinned}
 						onverdict={(verdict) => onDecide?.(verdict, current)}
 						{renderProposal}
+						when={(at) => when(at)}
 					/>
 				{/each}
 
-				{#if timeline.length > 0}
+				{#if comments.length + events.length > 0}
 					<DetailPanel>
-						<ol class="flex flex-col gap-4">
-							{#each timeline as entry (entry.id)}
-								<li class={cn("flex gap-3", !entry.read && "font-medium")}>
-									{@render face(entry.actor)}
-									<div class="min-w-0 flex-1">
-										<div class="flex flex-wrap items-center gap-x-2 text-[13px]">
-											<span class="truncate font-medium">{entry.actor.name}</span>
-											{#if entry.actor.kind === "agent"}
-												<span
-													class={cn(
-														"inline-flex h-5 items-center rounded-sm border px-1.5 text-xs font-medium",
-														TONE_CLASS.accent,
-													)}
-												>
-													{labels.agent}
-												</span>
-											{/if}
-											<span class="font-normal text-muted-foreground"
-												>{entryLine(entry, labels)}</span
-											>
-											<span class="ms-auto text-xs font-normal text-muted-foreground tabular-nums"
-												>{when(entry.at)}</span
-											>
-										</div>
-										{#if entry.body}
-											<p
-												class="mt-1 text-sm leading-relaxed font-normal whitespace-pre-wrap text-pretty"
-											>
-												{entry.body}
-											</p>
-										{/if}
-									</div>
-								</li>
-							{/each}
-						</ol>
+						<Thread
+							{comments}
+							{events}
+							labels={{
+								agent: labels.agent,
+								...threadLabels,
+							}}
+							avatar={avatar ? threadAvatar : undefined}
+							attachments={attachments ? threadAttachments : undefined}
+							when={(comment) => when(comment.createdAt)}
+							whenEvent={(event) => when(event.at)}
+						/>
 					</DetailPanel>
 				{/if}
 			{:else}
@@ -431,7 +550,15 @@
 			><KbdGroup><Kbd>j</Kbd><Kbd>k</Kbd></KbdGroup> {labels.hintMove}</span
 		>
 		<span class="inline-flex items-center gap-1.5"><Kbd>u</Kbd> {labels.hintRead}</span>
+		{#if onReadAll}
+			<span class="inline-flex items-center gap-1.5"
+				><KbdGroup><Kbd>⌥</Kbd><Kbd>u</Kbd></KbdGroup> {labels.hintReadAll}</span
+			>
+		{/if}
 		<span class="inline-flex items-center gap-1.5"><Kbd>h</Kbd> {labels.hintSnooze}</span>
+		{#if onClear}
+			<span class="inline-flex items-center gap-1.5"><Kbd>⌫</Kbd> {labels.hintClear}</span>
+		{/if}
 		<span class="inline-flex items-center gap-1.5"
 			><KbdGroup><Kbd>a</Kbd><Kbd>d</Kbd><Kbd>s</Kbd><Kbd>e</Kbd></KbdGroup> {labels.hintAct}</span
 		>

package/src/inbox/types.ts

@@ -1,4 +1,4 @@
-import type { InboxItem } from "../tasks/inbox/inbox-types.js";
+import type { InboxItem } from "../work/inbox/inbox-types.js";
 
 export type InboxActorKind = "user" | "agent";
 
@@ -28,6 +28,10 @@ export type InboxSubject = {
   /** A status id the host draws itself, for a badge in the thread header. */
   status?: string;
   href?: string;
+  /** ISO time a snoozed thread comes back. Set only when the host shows snoozed threads. */
+  snoozedUntil?: string;
+  /** The person follows this subject, so the thread offers Unfollow. */
+  followed?: boolean;
 };
 
 export type InboxEntry = {
@@ -77,7 +81,11 @@ export type InboxKey =
   | "next"
   | "previous"
   | "toggleRead"
+  | "readAll"
   | "snooze"
+  | "unfollow"
+  | "clear"
+  | "clearRead"
   | "approve"
   | "decline"
   | "steer"
@@ -101,6 +109,13 @@ export type InboxLabels = {
   snoozeLater: string;
   snoozeTomorrow: string;
   snoozeNextWeek: string;
+  snoozed: string;
+  showSnoozed: string;
+  unsnooze: string;
+  unfollow: string;
+  markAllRead: string;
+  clear: string;
+  clearRead: string;
   selectThread: string;
   filterType: string;
   filterWho: string;
@@ -119,7 +134,9 @@ export type InboxLabels = {
   /** Keyboard hint words. */
   hintMove: string;
   hintRead: string;
+  hintReadAll: string;
   hintSnooze: string;
+  hintClear: string;
   hintAct: string;
 };
 
@@ -139,6 +156,13 @@ export const DEFAULT_INBOX_LABELS: InboxLabels = {
   snoozeLater: "Later today",
   snoozeTomorrow: "Tomorrow",
   snoozeNextWeek: "Next week",
+  snoozed: "Snoozed",
+  showSnoozed: "Show snoozed",
+  unsnooze: "Unsnooze",
+  unfollow: "Unfollow",
+  markAllRead: "Mark all read",
+  clear: "Clear",
+  clearRead: "Clear read",
   selectThread: "Select a thread",
   filterType: "Filter by type",
   filterWho: "Filter by person or agent",
@@ -156,6 +180,8 @@ export const DEFAULT_INBOX_LABELS: InboxLabels = {
   proposed: "asks for your call",
   hintMove: "move",
   hintRead: "read",
+  hintReadAll: "all read",
   hintSnooze: "snooze",
+  hintClear: "clear, with shift every read thread",
   hintAct: "approve, decline, steer, edit",
 };

package/src/lib/initials.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vite-plus/test";
+import { initial, initials } from "./initials.js";
+
+describe("initial", () => {
+  it("keeps an emoji whole and uppercases a lowercase name", () => {
+    expect(initial("🦊 Fox")).toBe("🦊");
+    expect(initial("dana")).toBe("D");
+    expect(initial("Ólafur Darri")).toBe("Ó");
+  });
+  it("falls back for a missing or blank name", () => {
+    expect(initial(undefined)).toBe("?");
+    expect(initial("   ")).toBe("?");
+  });
+});
+
+describe("initials", () => {
+  it("takes the first and last word and skips a suffix", () => {
+    expect(initials("Christopher Alexander Montgomery III")).toBe("CM");
+    expect(initials("  Sam   Lee ")).toBe("SL");
+  });
+  it("gives one letter for one word and one script without spaces", () => {
+    expect(initials("Jo")).toBe("J");
+    expect(initials("王秀英")).toBe("王");
+  });
+});

package/src/lib/initials.ts

@@ -0,0 +1,29 @@
+const segmenter = typeof Intl !== "undefined" && "Segmenter" in Intl ? new Intl.Segmenter() : null;
+
+/** The first whole character of a string: an emoji or an accented letter stays in one piece. */
+function firstGrapheme(text: string): string {
+  if (!text) return "";
+  if (segmenter) return segmenter.segment(text)[Symbol.iterator]().next().value?.segment ?? "";
+  return Array.from(text)[0] ?? "";
+}
+
+/** One letter for an avatar fallback. Falls back to `fallback` for an empty or missing name. */
+export function initial(name: string | null | undefined, fallback = "?"): string {
+  const first = firstGrapheme((name ?? "").trim());
+  return first ? first.toLocaleUpperCase() : fallback;
+}
+
+/**
+ * Two letters for an avatar fallback, first and last word, skipping suffixes: "Christopher
+ * Montgomery III" gives "CM". A one-word name gives one letter.
+ */
+export function initials(name: string | null | undefined, fallback = "?"): string {
+  const words = (name ?? "")
+    .trim()
+    .split(/\s+/)
+    .filter((word) => word && !/^(?:[IVX]{1,4}|jr\.?|sr\.?)$/i.test(word));
+  if (words.length === 0) return initial(name, fallback);
+  const head = firstGrapheme(words[0]);
+  const tail = words.length > 1 ? firstGrapheme(words[words.length - 1]) : "";
+  return (head + tail).toLocaleUpperCase();
+}