@gperezmz/bb-plugin-thread-glance 0.1.2

package/features/thread-list/data/useAutoExpand.ts

@@ -0,0 +1,53 @@
+// Transient auto-expansion. Transitions are diffed against the previous
+// render, as bb does; nothing here is persisted.
+import { useCallback, useRef, useState } from "react";
+import type { Forest } from "../model/families";
+import {
+  detectTransitions,
+  mergeTargets,
+  pruneTargets,
+  snapshotOf,
+  type Snapshot,
+  type Targets,
+} from "../model/expansion";
+
+export interface AutoExpand {
+  targets: Targets;
+  /** A user's collapse: drop targets it hides, until the next transition. */
+  prune(drop: (id: string) => boolean): void;
+}
+
+export function useAutoExpand(forest: Forest | null, activeThreadId: string | null): AutoExpand {
+  const previous = useRef<Snapshot | null>(null);
+  const lastForest = useRef<Forest | null>(null);
+  const lastActive = useRef<string | null | undefined>(undefined);
+  const [targets, setTargets] = useState<Targets>(() => new Map());
+  const targetsRef = useRef(targets);
+  targetsRef.current = targets;
+
+  // Derived during render so the first paint is already expanded. Idempotent:
+  // a repeated render diffs against the snapshot it stored.
+  let current = targets;
+  if (forest !== null && (forest !== lastForest.current || activeThreadId !== lastActive.current)) {
+    const snapshot = snapshotOf(forest, activeThreadId);
+    const added = detectTransitions(previous.current, snapshot);
+    previous.current = snapshot;
+    lastForest.current = forest;
+    lastActive.current = activeThreadId;
+    current = mergeTargets(targets, added);
+    if (current !== targets) {
+      targetsRef.current = current;
+      setTargets(current);
+    }
+  }
+
+  const prune = useCallback((drop: (id: string) => boolean) => {
+    const next = pruneTargets(targetsRef.current, drop);
+    if (next !== targetsRef.current) {
+      targetsRef.current = next;
+      setTargets(next);
+    }
+  }, []);
+
+  return { targets: current, prune };
+}

package/features/thread-list/data/useClientPreferences.ts

@@ -0,0 +1,20 @@
+// Per-client preferences: filter and density, localStorage only.
+import { useCallback, useState } from "react";
+import {
+  CLIENT_PREFERENCES_STORAGE_KEY,
+  parseClientPreferences,
+  type ClientPreferences,
+} from "@/shared/preferences";
+import { readJson, writeJson } from "./storage";
+
+export function useClientPreferences(): [ClientPreferences, (patch: Partial<ClientPreferences>) => void] {
+  const [value, setValue] = useState(() => parseClientPreferences(readJson(CLIENT_PREFERENCES_STORAGE_KEY)));
+  const update = useCallback((patch: Partial<ClientPreferences>) => {
+    setValue((current) => {
+      const next = { ...current, ...patch };
+      writeJson(CLIENT_PREFERENCES_STORAGE_KEY, next);
+      return next;
+    });
+  }, []);
+  return [value, update];
+}

package/features/thread-list/data/useNotes.ts

@@ -0,0 +1,41 @@
+// Thread notes from the plugin server, kept live over realtime.
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useRealtime, useRealtimeConnectionState, useRpc } from "@get-bb/plugin-sdk/app";
+import type { RpcContract } from "@/shared/contract";
+import { CHANNELS, threadNotesSchema, type NotesSignal, type ThreadNotes } from "@/shared/signals";
+
+export function useNotes(): Readonly<Record<string, ThreadNotes>> {
+  const rpc = useRpc<RpcContract>();
+  const [notes, setNotes] = useState<Readonly<Record<string, ThreadNotes>>>({});
+  const connection = useRealtimeConnectionState();
+  const wasConnected = useRef(false);
+
+  const load = useCallback(() => {
+    rpc.call("listNotes", null).then(
+      (result) => setNotes(result.notes),
+      () => undefined,
+    );
+  }, [rpc]);
+
+  useEffect(load, [load]);
+  useEffect(() => {
+    if (connection !== "connected") return;
+    if (wasConnected.current) load();
+    wasConnected.current = true;
+  }, [connection, load]);
+
+  useRealtime(CHANNELS.notes, (payload) => {
+    const signal = payload as NotesSignal;
+    if (signal === null || typeof signal !== "object" || typeof signal.threadId !== "string") return;
+    const parsed = signal.notes === null ? null : threadNotesSchema.safeParse(signal.notes);
+    if (parsed !== null && !parsed.success) return;
+    setNotes((current) => {
+      const next = { ...current };
+      if (parsed === null) delete next[signal.threadId];
+      else next[signal.threadId] = parsed.data;
+      return next;
+    });
+  });
+
+  return notes;
+}

package/features/thread-list/data/useNow.ts

@@ -0,0 +1,19 @@
+// A clock that ticks each minute (row ages) and at the next deadline
+// (scheduled → queued), so rows change without a request.
+import { useEffect, useState } from "react";
+
+export function useNow(nextDeadline: number | null): number {
+  const [now, setNow] = useState(() => Date.now());
+  useEffect(() => {
+    const tick = setInterval(() => setNow(Date.now()), 60_000);
+    return () => clearInterval(tick);
+  }, []);
+  useEffect(() => {
+    if (nextDeadline === null) return;
+    const wait = nextDeadline - Date.now();
+    if (wait <= 0 || wait > 2 ** 31 - 1) return;
+    const timeout = setTimeout(() => setNow(Date.now()), wait + 50);
+    return () => clearTimeout(timeout);
+  }, [nextDeadline]);
+  return now;
+}

package/features/thread-list/data/usePreferences.ts

@@ -0,0 +1,126 @@
+// Server-side preferences: kv via RPC, realtime to every window, a
+// localStorage mirror for first paint, and debounced writes.
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useRealtime, useRealtimeConnectionState, useRpc } from "@get-bb/plugin-sdk/app";
+import { toast } from "sonner";
+import type { RpcContract } from "@/shared/contract";
+import { CHANNELS, type PreferenceSignal } from "@/shared/signals";
+import {
+  BB_PREFERENCES_MIRROR_STORAGE_KEY,
+  coercePreferences,
+  isPreferenceKey,
+  parsePreference,
+  PREFERENCES_MIRROR_STORAGE_KEY,
+  type PreferenceKey,
+  type Preferences,
+} from "@/shared/preferences";
+import { readJson, writeJson } from "./storage";
+
+const WRITE_DEBOUNCE_MS = 150;
+
+export interface PreferencesState {
+  prefs: Preferences;
+  /** The server's values have arrived (or failed; the mirror stands in). */
+  hydrated: boolean;
+  update(patch: Partial<Preferences>): void;
+}
+
+export function usePreferences(): PreferencesState {
+  const rpc = useRpc<RpcContract>();
+  const [prefs, setPrefs] = useState<Preferences>(() =>
+    coercePreferences(readJson(PREFERENCES_MIRROR_STORAGE_KEY)),
+  );
+  const [hydrated, setHydrated] = useState(false);
+  const pending = useRef(new Map<PreferenceKey, unknown>());
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const connection = useRealtimeConnectionState();
+  const wasConnected = useRef(false);
+
+  const load = useCallback(async () => {
+    try {
+      const { preferences } = await rpc.call("listPreferences", null);
+      const next = coercePreferences(preferences);
+      // Keys with a write in flight keep the local value.
+      for (const [key, value] of pending.current) (next as Record<string, unknown>)[key] = value;
+      setPrefs(next);
+      writeJson(PREFERENCES_MIRROR_STORAGE_KEY, next);
+    } finally {
+      setHydrated(true);
+    }
+  }, [rpc]);
+
+  useEffect(() => {
+    let cancelled = false;
+    (async () => {
+      try {
+        await rpc.call("importPreferences", { bbMirror: readJson(BB_PREFERENCES_MIRROR_STORAGE_KEY) });
+      } catch {
+        // Import is best effort; the defaults stand.
+      }
+      if (!cancelled) await load().catch(() => undefined);
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [rpc, load]);
+
+  // Realtime signals aren't replayed: re-read after a reconnect.
+  useEffect(() => {
+    if (connection !== "connected") return;
+    if (wasConnected.current) void load().catch(() => undefined);
+    wasConnected.current = true;
+  }, [connection, load]);
+
+  useRealtime(CHANNELS.preferences, (payload) => {
+    const signal = payload as PreferenceSignal;
+    if (!isPreferenceKey(signal?.key) || pending.current.has(signal.key)) return;
+    const parsed = parsePreference(signal.key, signal.value);
+    if (!parsed.success) return;
+    setPrefs((current) => {
+      const next = { ...current, [signal.key]: parsed.value };
+      writeJson(PREFERENCES_MIRROR_STORAGE_KEY, next);
+      return next;
+    });
+  });
+
+  const flush = useCallback(() => {
+    const writes = [...pending.current];
+    pending.current.clear();
+    for (const [key, value] of writes) {
+      rpc.call("setPreference", { key, value }).catch((error: unknown) => {
+        toast.error(`Couldn't save the ${key} setting`, {
+          description: error instanceof Error ? error.message : String(error),
+        });
+      });
+    }
+  }, [rpc]);
+
+  useEffect(
+    () => () => {
+      if (timer.current !== null) clearTimeout(timer.current);
+      flush();
+    },
+    [flush],
+  );
+
+  const update = useCallback(
+    (patch: Partial<Preferences>) => {
+      setPrefs((current) => {
+        const next = { ...current, ...patch };
+        writeJson(PREFERENCES_MIRROR_STORAGE_KEY, next);
+        return next;
+      });
+      for (const [key, value] of Object.entries(patch)) {
+        if (isPreferenceKey(key)) pending.current.set(key, value);
+      }
+      if (timer.current !== null) clearTimeout(timer.current);
+      timer.current = setTimeout(() => {
+        timer.current = null;
+        flush();
+      }, WRITE_DEBOUNCE_MS);
+    },
+    [flush],
+  );
+
+  return { prefs, hydrated, update };
+}

package/features/thread-list/data/useScheduled.ts

@@ -0,0 +1,43 @@
+// Scheduled sends: one map pushed by the server, no per-row requests.
+import { useEffect, useRef, useState } from "react";
+import { useRealtime, useRealtimeConnectionState, useRpc } from "@get-bb/plugin-sdk/app";
+import type { RpcContract } from "@/shared/contract";
+import { CHANNELS, type ScheduledSignal } from "@/shared/signals";
+
+const NONE: Readonly<Record<string, number>> = {};
+
+/** threadId → earliest future sendAt; empty until loaded or on error. */
+export function useScheduled(): Readonly<Record<string, number>> {
+  const rpc = useRpc<RpcContract>();
+  const [scheduled, setScheduled] = useState<Readonly<Record<string, number>>>(NONE);
+  const connection = useRealtimeConnectionState();
+  const wasConnected = useRef(false);
+  const [reload, setReload] = useState(0);
+
+  useEffect(() => {
+    let cancelled = false;
+    rpc.call("listScheduled", null).then(
+      (result) => {
+        if (!cancelled) setScheduled(result.status === "ready" ? result.scheduled : NONE);
+      },
+      () => undefined,
+    );
+    return () => {
+      cancelled = true;
+    };
+  }, [rpc, reload]);
+
+  useEffect(() => {
+    if (connection !== "connected") return;
+    if (wasConnected.current) setReload((value) => value + 1);
+    wasConnected.current = true;
+  }, [connection]);
+
+  useRealtime(CHANNELS.scheduled, (payload) => {
+    const signal = payload as ScheduledSignal;
+    if (signal === null || typeof signal !== "object") return;
+    setScheduled(signal.status === "ready" && signal.scheduled ? signal.scheduled : NONE);
+  });
+
+  return scheduled;
+}

package/features/thread-list/data/useStamps.ts

@@ -0,0 +1,68 @@
+// Thread stamps from the plugin server, kept live over realtime.
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useRealtime, useRealtimeConnectionState, useRpc } from "@get-bb/plugin-sdk/app";
+import type { RpcContract } from "@/shared/contract";
+import { CHANNELS, type StampSignal, type Stamps } from "@/shared/signals";
+
+const EMPTY: Stamps = { startedAt: {}, finishedAt: {}, pendingAt: {}, seenAt: {} };
+const KINDS = new Set(Object.keys(EMPTY));
+
+export interface StampsState {
+  stamps: Stamps;
+  markSeen(threadIds: string[]): void;
+  clearSeen(threadIds: string[]): void;
+}
+
+export function useStamps(): StampsState {
+  const rpc = useRpc<RpcContract>();
+  const [stamps, setStamps] = useState<Stamps>(EMPTY);
+  const connection = useRealtimeConnectionState();
+  const wasConnected = useRef(false);
+
+  const load = useCallback(() => {
+    rpc.call("listStamps", null).then(
+      (result) => setStamps(result.stamps),
+      () => undefined,
+    );
+  }, [rpc]);
+
+  useEffect(load, [load]);
+  useEffect(() => {
+    if (connection !== "connected") return;
+    if (wasConnected.current) load();
+    wasConnected.current = true;
+  }, [connection, load]);
+
+  const apply = useCallback((signal: StampSignal) => {
+    if (!KINDS.has(signal.kind) || !Array.isArray(signal.threadIds)) return;
+    setStamps((current) => {
+      const map = { ...current[signal.kind] };
+      for (const id of signal.threadIds) {
+        if (signal.value === null) delete map[id];
+        else map[id] = signal.value;
+      }
+      return { ...current, [signal.kind]: map };
+    });
+  }, []);
+
+  useRealtime(CHANNELS.stamps, (payload) => apply(payload as StampSignal));
+
+  const markSeen = useCallback(
+    (threadIds: string[]) => {
+      if (threadIds.length === 0) return;
+      apply({ kind: "seenAt", threadIds, value: Date.now() });
+      rpc.call("markSeen", { threadIds }).catch(() => undefined);
+    },
+    [apply, rpc],
+  );
+  const clearSeen = useCallback(
+    (threadIds: string[]) => {
+      if (threadIds.length === 0) return;
+      apply({ kind: "seenAt", threadIds, value: null });
+      rpc.call("clearSeen", { threadIds }).catch(() => undefined);
+    },
+    [apply, rpc],
+  );
+
+  return { stamps, markSeen, clearSeen };
+}

package/features/thread-list/icons.ts

@@ -0,0 +1,44 @@
+// Host icon names the list draws outside the state model. Components take
+// names from here so one test can check them all against the host list.
+
+export const ICONS = {
+  archive: "Archive",
+  unarchive: "ArchiveRestore",
+  more: "MoreHorizontal",
+  openInSplit: "Columns2",
+  copy: "Copy",
+  link: "ExternalLink",
+  markRead: "MailOpen",
+  markUnread: "Mail",
+  pin: "Pin",
+  unpin: "PinOff",
+  moveToSection: "SectionMove",
+  rename: "Edit",
+  remove: "Trash2",
+  details: "Info",
+  crossGroup: "FolderExport",
+  hidden: "EyeOff",
+  show: "Eye",
+  expand: "ChevronRight",
+  collapse: "ChevronDown",
+  moveUp: "ChevronUp",
+  newThread: "Plus",
+  newSection: "SectionAdd",
+  settings: "Settings",
+  customize: "SlidersHorizontal",
+  check: "Check",
+  pullRequest: "GitPullRequest",
+  branch: "GitBranch",
+  worktree: "FolderGit",
+  machine: "Laptop",
+  environmentFallback: "Zap",
+  filter: "FilterHorizontal",
+  drag: "DragDropVertical",
+  move: "MoveTo",
+  open: "ArrowUpRight",
+} as const;
+
+export const ROW_ICON_NAMES: readonly string[] = Object.values(ICONS);
+
+/** Glyphs the group header counters draw. */
+export const COUNTER_ICON_NAMES: readonly string[] = ["CircleQuestion", "CircleX", "CloudOff", "Loading"];

package/features/thread-list/index.ts

@@ -0,0 +1,2 @@
+// The sidebar thread list feature: what the app entry may use.
+export { ThreadList } from "./components/ThreadList";

package/features/thread-list/model/attention.ts

@@ -0,0 +1,89 @@
+// What counts as "needs attention", thread by thread. The filter, its
+// badge, the header counters, the urgency order and auto-reveal all read the
+// set this builds. Pure.
+import type { PluginSidebarThread } from "@get-bb/plugin-sdk/app";
+import type { ChildAttention } from "@/shared/preferences";
+import { type Flag, type StateKind, type ThreadState } from "./state";
+
+/** The flags that count for a thread nobody manages. Working is not one. */
+export const ROOT_ATTENTION: ReadonlySet<Flag> = new Set<Flag>([
+  "needs-you",
+  "unread-failed",
+  "queue-failed",
+  "offline",
+  "unread",
+]);
+
+/** States in which a manager is busy and may still deal with a failed child. */
+const BUSY: ReadonlySet<StateKind> = new Set<StateKind>(["working", "background", "queued", "scheduled"]);
+
+export interface Manager {
+  thread: Pick<PluginSidebarThread, "latestAttentionAt">;
+  state: Pick<ThreadState, "kind">;
+  /** When the plugin server last saw the manager finish a turn, if it did. */
+  finishedAt?: number;
+}
+
+/** A manager is idle when it is not working, setting up, running background work or holding a queued message. */
+export function isManagerIdle(manager: Manager): boolean {
+  return !BUSY.has(manager.state.kind);
+}
+
+/** When the thread's failure happened: an error bumps `latestAttentionAt`, a failed queue only `updatedAt`. */
+export function failureTime(
+  thread: Pick<PluginSidebarThread, "latestAttentionAt" | "updatedAt">,
+  flags: ReadonlySet<Flag>,
+): number {
+  let at = 0;
+  if (flags.has("unread-failed")) at = Math.max(at, thread.latestAttentionAt);
+  if (flags.has("queue-failed")) at = Math.max(at, thread.updatedAt);
+  return at;
+}
+
+/**
+ * A failure nobody is dealing with: the manager is idle and has not run or
+ * finished since the child failed. A busy manager, or one that finished after
+ * the failure, is taken to know about it. The manager's own clock is its last
+ * finish (`finishedAt`, or `latestAttentionAt` when it failed): `updatedAt`
+ * also moves when someone merely opens or renames it.
+ */
+export function isOrphanedFailure(
+  thread: Pick<PluginSidebarThread, "latestAttentionAt" | "updatedAt">,
+  flags: ReadonlySet<Flag>,
+  manager: Manager,
+): boolean {
+  if (!flags.has("unread-failed") && !flags.has("queue-failed")) return false;
+  if (!isManagerIdle(manager)) return false;
+  const managerActiveAt = Math.max(manager.thread.latestAttentionAt, manager.finishedAt ?? 0);
+  return managerActiveAt <= failureTime(thread, flags);
+}
+
+/**
+ * The flags of one thread that count towards Needs attention. A root keeps
+ * its own. A child counts when it waits on you or is offline, or when it
+ * failed with an idle manager; a finished-unread child never does. With
+ * `everything`, a child counts like a root.
+ */
+export function attentionFlagsOf(
+  flags: ReadonlySet<Flag>,
+  options: { isRoot: boolean; mode: ChildAttention; orphaned: boolean },
+): Set<Flag> {
+  const kept = new Set<Flag>();
+  if (options.isRoot || options.mode === "everything") {
+    for (const flag of flags) if (ROOT_ATTENTION.has(flag)) kept.add(flag);
+    return kept;
+  }
+  if (flags.has("needs-you")) kept.add("needs-you");
+  if (flags.has("offline")) kept.add("offline");
+  if (options.orphaned) {
+    if (flags.has("unread-failed")) kept.add("unread-failed");
+    if (flags.has("queue-failed")) kept.add("queue-failed");
+  }
+  return kept;
+}
+
+/** Whether a set of attention flags is worth an auto-reveal: it waits on you or failed. */
+export function revealsOn(attention: ReadonlySet<Flag>, isRoot: boolean): boolean {
+  if (attention.has("needs-you") || attention.has("unread-failed")) return true;
+  return !isRoot && attention.has("queue-failed");
+}

package/features/thread-list/model/counters.ts

@@ -0,0 +1,67 @@
+// Group header counters and the Needs attention filter test. Pure.
+import type { Family } from "./families";
+
+export interface Counters {
+  needsYou: number;
+  /** Unread-failed plus queue-failed threads. */
+  failed: number;
+  offline: number;
+  working: number;
+  unread: number;
+}
+
+export const EMPTY_COUNTERS: Counters = { needsYou: 0, failed: 0, offline: 0, working: 0, unread: 0 };
+
+/**
+ * Counts the threads in the families. A thread counts what its attention
+ * flags say, so a child adds to needs-you, failed, offline and unread only as
+ * the Child threads in Needs attention setting lets it; working counts every thread that runs. Hidden threads carry
+ * only needs-you and unread-failed flags already; archived threads never count.
+ */
+export function countFamilies(families: readonly Family[]): Counters {
+  const counters = { ...EMPTY_COUNTERS };
+  for (const family of families) {
+    for (const info of [family.root, ...family.descendants]) {
+      if (info.thread.isArchived) continue;
+      const flags = info.attention;
+      if (flags.has("needs-you")) counters.needsYou += 1;
+      if (flags.has("unread-failed") || flags.has("queue-failed")) counters.failed += 1;
+      if (flags.has("offline")) counters.offline += 1;
+      if (info.flags.has("working")) counters.working += 1;
+      if (flags.has("unread")) counters.unread += 1;
+    }
+  }
+  return counters;
+}
+
+export function addCounters(a: Counters, b: Counters): Counters {
+  return {
+    needsYou: a.needsYou + b.needsYou,
+    failed: a.failed + b.failed,
+    offline: a.offline + b.offline,
+    working: a.working + b.working,
+    unread: a.unread + b.unread,
+  };
+}
+
+/** The Needs attention tooltip: short enough to read at a glance. */
+export const ATTENTION_SUMMARY = "Waiting on you, failed, offline, or finished and unread. Child threads count only when stuck.";
+
+/** What the Needs attention toggle keeps, in full, for its accessible description. */
+export const ATTENTION_EXPLANATION =
+  "Threads only you can move forward: a question, approval or plan review waiting on you; a machine that is offline; a failed thread or queued message; finished threads you haven't opened. For a child thread, only what waits on you or is offline, or a failure whose manager is idle (Filter settings can widen this).";
+
+/**
+ * Which counters a header draws. needs-you, failed and offline
+ * always; working only while collapsed, since the rows show it otherwise;
+ * unread only on the More trigger, where the rows are out of sight.
+ */
+export function visibleCounters(counters: Counters, where: { collapsed: boolean; more: boolean }): Counters {
+  return {
+    needsYou: counters.needsYou,
+    failed: counters.failed,
+    offline: counters.offline,
+    working: where.collapsed || where.more ? counters.working : 0,
+    unread: where.more ? counters.unread : 0,
+  };
+}

package/features/thread-list/model/details.ts

@@ -0,0 +1,79 @@
+// Hover card and details drawer content. Pure.
+import type { Family, ThreadInfo } from "./families";
+import type { StateKind } from "./state";
+
+const SUMMARY_ORDER: readonly [StateKind, string][] = [
+  ["needs-you", "needing you"],
+  ["failed", "failed"],
+  ["queue-failed", "queue failed"],
+  ["offline", "offline"],
+  ["working", "working"],
+  ["background", "in background"],
+  ["scheduled", "scheduled"],
+  ["queued", "queued"],
+  ["unread", "unread"],
+  ["draft", "drafts"],
+  ["idle", "idle"],
+];
+
+/** "2 working, 1 need you, 3 idle": visible descendants by state. */
+export function childSummary(descendants: readonly ThreadInfo[]): string | null {
+  const counts = new Map<StateKind, number>();
+  for (const info of descendants) {
+    if (info.thread.isHidden) continue;
+    counts.set(info.state.kind, (counts.get(info.state.kind) ?? 0) + 1);
+  }
+  const parts = SUMMARY_ORDER.filter(([kind]) => counts.has(kind)).map(
+    ([kind, label]) => `${counts.get(kind)} ${label}`,
+  );
+  return parts.length > 0 ? parts.join(", ") : null;
+}
+
+/** Descendants of `id` inside its family, for the card of any row. */
+export function descendantsOf(family: Family | undefined, id: string): ThreadInfo[] {
+  if (family === undefined) return [];
+  if (family.root.thread.id === id) return family.descendants;
+  const result: ThreadInfo[] = [];
+  const within = new Set([id]);
+  for (const info of family.descendants) {
+    if (info.parentId !== null && within.has(info.parentId)) {
+      within.add(info.thread.id);
+      result.push(info);
+    }
+  }
+  return result;
+}
+
+export function formatDateTime(at: number): string {
+  return new Date(at).toLocaleString(undefined, {
+    month: "short",
+    day: "numeric",
+    hour: "2-digit",
+    minute: "2-digit",
+  });
+}
+
+/** How the card names the time in the current state. */
+export function sinceLabel(kind: string, since: string | null): string | null {
+  if (since === null) return null;
+  const ago = since === "now" ? "just now" : `${since} ago`;
+  switch (kind) {
+    case "working":
+    case "background":
+      return `started ${ago}`;
+    case "needs-you":
+      return `waiting since ${ago}`;
+    case "failed":
+      return `failed ${ago}`;
+    default:
+      return `finished ${ago}`;
+  }
+}
+
+/** The model's display name from the provider catalog, else its id. */
+export function modelDisplayName(
+  model: string,
+  catalog: readonly { id: string; model: string; displayName: string }[],
+): string {
+  return catalog.find((entry) => entry.model === model || entry.id === model)?.displayName ?? model;
+}