@schlessera/brain-ui-react 0.17.0 → 0.19.0

package/src/components/activity/push-toggle.tsx

@@ -0,0 +1,128 @@
+import { useEffect, useState } from "react";
+import { Bell, BellOff } from "lucide-react";
+
+import { api } from "../../lib/api-client.js";
+import { cn } from "../../lib/utils.js";
+
+/**
+ * The push enable/disable control, living on the Activity surface (where the
+ * alerts it governs land). The permission model is THREE-state, not a bare
+ * toggle: once the browser prompt is denied, Chrome silently ignores every
+ * further in-page request — so the blocked state must say where the real
+ * switch lives (site settings) instead of offering a button that does
+ * nothing. Where the platform has no push at all (iOS Safari in-browser,
+ * pre-16.4), the control renders disabled-with-explanation, not hidden.
+ */
+type PushState =
+  | "unsupported"
+  | "not-asked"
+  | "blocked"
+  | "subscribed"
+  | "unsubscribed";
+
+export function PushToggle() {
+  const [state, setState] = useState<PushState>("unsupported");
+  const [busy, setBusy] = useState(false);
+
+  useEffect(() => {
+    void (async () => {
+      if (!("Notification" in window) || !("serviceWorker" in navigator) || !("PushManager" in window)) {
+        setState("unsupported");
+        return;
+      }
+      if (Notification.permission === "denied") {
+        setState("blocked");
+        return;
+      }
+      if (Notification.permission === "default") {
+        setState("not-asked");
+        return;
+      }
+      const registration = await navigator.serviceWorker.ready;
+      const subscription = await registration.pushManager.getSubscription();
+      setState(subscription ? "subscribed" : "unsubscribed");
+    })();
+  }, []);
+
+  async function enable() {
+    setBusy(true);
+    try {
+      const permission = await Notification.requestPermission();
+      if (permission === "denied") {
+        setState("blocked");
+        return;
+      }
+      if (permission !== "granted") {
+        setState("not-asked");
+        return;
+      }
+      const { publicKey } = await api.pushPublicKey();
+      const registration = await navigator.serviceWorker.ready;
+      const subscription = await registration.pushManager.subscribe({
+        userVisibleOnly: true,
+        applicationServerKey: publicKey,
+      });
+      await api.pushSubscribe(subscription.toJSON(), navigator.userAgent.slice(0, 100));
+      setState("subscribed");
+    } catch {
+      setState("unsubscribed");
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  async function disable() {
+    setBusy(true);
+    try {
+      const registration = await navigator.serviceWorker.ready;
+      const subscription = await registration.pushManager.getSubscription();
+      if (subscription) {
+        await api.pushUnsubscribe(subscription.endpoint).catch(() => {});
+        await subscription.unsubscribe();
+      }
+      setState("unsubscribed");
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  if (state === "unsupported") {
+    return (
+      <div className="flex items-center gap-1.5 text-[11px] text-muted-foreground/60" title="This browser has no web push. On iOS, install the app to the home screen (iOS 16.4+).">
+        <BellOff className="h-3.5 w-3.5" />
+        No push here
+      </div>
+    );
+  }
+
+  if (state === "blocked") {
+    return (
+      <div
+        className="flex items-center gap-1.5 text-[11px] text-muted-foreground"
+        title="Notifications are blocked at the browser level. Allow them in this site's browser settings, then reload."
+      >
+        <BellOff className="h-3.5 w-3.5 text-destructive" />
+        Blocked in browser settings
+      </div>
+    );
+  }
+
+  const on = state === "subscribed";
+  return (
+    <button
+      type="button"
+      disabled={busy}
+      onClick={() => void (on ? disable() : enable())}
+      className={cn(
+        "flex items-center gap-1.5 rounded-md px-2 py-1 text-[11px] transition-colors disabled:opacity-50",
+        on
+          ? "text-primary hover:bg-surface-raised"
+          : "text-muted-foreground hover:bg-surface-raised hover:text-foreground"
+      )}
+      title={on ? "Push notifications are on for this device" : "Get a push notification when background work fails"}
+    >
+      {on ? <Bell className="h-3.5 w-3.5" /> : <BellOff className="h-3.5 w-3.5" />}
+      {on ? "Push on" : "Enable push"}
+    </button>
+  );
+}

package/src/components/activity/span-bits.tsx

@@ -0,0 +1,71 @@
+import { isFailureOutcome } from "@schlessera/brain-ui-sdk/protocol";
+import type { ActivitySpan, ActivitySpanOutcome } from "@schlessera/brain-ui-sdk/protocol";
+
+import { cn } from "../../lib/utils.js";
+import { getToolLabel } from "../chat/tool-views.js";
+
+/**
+ * THE status dot for activity spans — one outcome→color mapping so every
+ * surface (timeline rows, drill-in, activity index) agrees on what a color
+ * means: running pulses primary, success is accent, failures (per
+ * `isFailureOutcome`) and denied are destructive, cancelled is muted.
+ */
+export function SpanStatusDot({
+  span,
+  outcome,
+  running,
+  className,
+}: {
+  span?: ActivitySpan;
+  /** Alternative to `span` when only the outcome is at hand. */
+  outcome?: ActivitySpanOutcome | string | null;
+  running?: boolean;
+  /** Size/position overrides; defaults to h-1.5 w-1.5. */
+  className?: string;
+}) {
+  const resolved = span ? span.outcome : outcome;
+  const isRunning = running ?? (span !== undefined && span.outcome === undefined);
+  return (
+    <span
+      className={cn(
+        "h-1.5 w-1.5 shrink-0 rounded-full",
+        isRunning
+          ? "animate-pulse bg-primary"
+          : resolved === "success"
+            ? "bg-accent"
+            : isFailureOutcome(resolved) || resolved === "denied"
+              ? "bg-destructive"
+              : "bg-muted-foreground",
+        className
+      )}
+    />
+  );
+}
+
+/**
+ * Display label for a span. Prefers the server-lifted `toolName`; root spans
+ * label by kind (a turn or cron root is not a tool call); the last resort
+ * un-parses the `execute_tool` naming convention for spans recorded before
+ * the field existed.
+ */
+export function spanToolLabel(span: ActivitySpan): string {
+  if (span.toolName) return getToolLabel(span.toolName);
+  if (span.kind === "turn") return "Turn";
+  if (span.kind === "cron") return span.jobName ?? span.name;
+  return getToolLabel(span.name.replace(/^execute_tool /, ""));
+}
+
+/** The "9+" unread-count bubble shared by the rail and the tab bar. Hidden at 0. */
+export function CountBadge({ count, className }: { count: number; className?: string }) {
+  if (count <= 0) return null;
+  return (
+    <span
+      className={cn(
+        "absolute flex h-4 min-w-4 items-center justify-center rounded-full bg-destructive px-1 text-[9px] font-semibold text-white",
+        className
+      )}
+    >
+      {count > 9 ? "9+" : count}
+    </span>
+  );
+}

package/src/components/chat/chat-page.tsx

@@ -33,6 +33,8 @@ import { WelcomeState } from "./welcome-state.js";
 import { ShareIntake } from "./share-card.js";
 import { CommandPalette } from "./command-palette.js";
 import { SessionDrawer } from "./session-drawer.js";
+import { SubagentView } from "./subagent-view.js";
+import { DigestCard } from "../activity/digest-card.js";
 import { SettingsPanel } from "../settings/settings-panel.js";
 import { StreamingPanel } from "../quick-actions/streaming-modal.js";
 import { WhatsupPanel } from "../quick-actions/whatsup-modal.js";
@@ -125,6 +127,7 @@ export function ChatPage() {
 
   const sessionPanelOpen = useUIStore((s) => s.sessionPanelOpen);
   const setSessionPanelOpen = useUIStore((s) => s.setSessionPanelOpen);
+  const subagentStack = useUIStore((s) => s.subagentStack);
   const syncPanelOpen = useUIStore((s) => s.syncPanelOpen);
   const setSyncPanelOpen = useUIStore((s) => s.setSyncPanelOpen);
   const whatsupPanelOpen = useUIStore((s) => s.whatsupPanelOpen);
@@ -521,6 +524,17 @@ export function ChatPage() {
         }
       />
 
+      {/* Subagent drill-in: an overlay stack — chat is the residence, the
+          drill-in opens over it and backs out level by level. */}
+      {subagentStack.length > 0 && (
+        <div className="fixed inset-0 z-40 bg-background">
+          <SubagentView
+            spanId={subagentStack[subagentStack.length - 1]!}
+            onApproval={handleToolApproval}
+          />
+        </div>
+      )}
+
       {/* Panels */}
       <SessionDrawer
         open={sessionPanelOpen}
@@ -558,6 +572,9 @@ export function ChatPage() {
       <div className="relative flex-1 overflow-hidden">
         {messages.length === 0 ? (
           <div className="h-full overflow-y-auto">
+            <div className="px-4 pt-3 md:px-6">
+              <DigestCard />
+            </div>
             <WelcomeState onAction={handleWelcomeAction} />
           </div>
         ) : (

package/src/components/chat/session-drawer.tsx

@@ -4,6 +4,7 @@ import { api } from "../../lib/api-client.js";
 import { useChatStore } from "../../stores/chat-store.js";
 import { SlidePanel } from "../layout/slide-panel.js";
 import { cn } from "../../lib/utils.js";
+import { formatRelativeTime } from "./tool-views.js";
 
 interface SessionInfo {
   id: string;
@@ -215,15 +216,3 @@ function groupSessionsByDate(sessions: SessionInfo[]): GroupedSessions[] {
     .filter(([, sessions]) => sessions.length > 0)
     .map(([label, sessions]) => ({ label, sessions }));
 }
-
-function formatRelativeTime(ms: number): string {
-  const diff = Date.now() - ms;
-  const minutes = Math.floor(diff / 60000);
-  if (minutes < 1) return "just now";
-  if (minutes < 60) return `${minutes}m ago`;
-  const hours = Math.floor(minutes / 60);
-  if (hours < 24) return `${hours}h ago`;
-  const days = Math.floor(hours / 24);
-  if (days < 7) return `${days}d ago`;
-  return new Date(ms).toLocaleDateString();
-}

package/src/components/chat/subagent-view.tsx

@@ -0,0 +1,229 @@
+import { useMemo } from "react";
+import { ArrowLeft, Bot, Check, X } from "lucide-react";
+import { motion } from "framer-motion";
+import { useShallow } from "zustand/react/shallow";
+import { isFailureOutcome } from "@schlessera/brain-ui-sdk/protocol";
+import type { ActivitySpan, ActivitySpanEvent } from "@schlessera/brain-ui-sdk/protocol";
+
+import { useActivityStore, childSpans, eventsFor, spanForTool } from "../../stores/activity-store.js";
+import { useUIStore } from "../../stores/ui-store.js";
+import { useChatStore, activeChat } from "../../stores/chat-store.js";
+import { cn } from "../../lib/utils.js";
+import { getToolLabel, formatDuration } from "./tool-views.js";
+import { SpanStatusDot, spanToolLabel } from "../activity/span-bits.js";
+
+/**
+ * Drill-in view of one subagent: the span tree under its Agent tool call,
+ * transcript excerpts interleaved by time, live while the subagent runs.
+ *
+ * Deliberately observation-shaped — no composer, no way to address the
+ * subagent — with ONE exception, decided during planning: an approval
+ * request raised by a tool inside this subagent renders actionable here as
+ * well as in the parent chat, because a fan-out stalled on an unaddressable
+ * approval is worse than a relaxed rule.
+ *
+ * When transcript forwarding is off (or the backend cannot forward), the
+ * view degrades to activity-only and says so, rather than looking empty.
+ */
+export function SubagentView({
+  spanId,
+  onApproval,
+}: {
+  spanId: string;
+  onApproval?: (toolUseId: string, approved: boolean) => void;
+}) {
+  const popSubagentView = useUIStore((s) => s.popSubagentView);
+  const pushSubagentView = useUIStore((s) => s.pushSubagentView);
+  const span = useActivityStore((s) => spanForTool(s, spanId));
+  const children = useActivityStore(useShallow((s) => childSpans(s, spanId)));
+  const events = useActivityStore((s) => eventsFor(s, spanId));
+  const pendingApprovals = useChatStore(
+    useShallow((s) => {
+      const chat = activeChat(s);
+      const last = chat.messages.at(-1);
+      return (last?.toolCalls ?? []).filter((t) => t.status === "pending_approval");
+    })
+  );
+
+  const timelineItems = useMemo(
+    () => interleave(children, events),
+    [children, events]
+  );
+
+  if (!span) {
+    return (
+      <div className="flex flex-col gap-3 p-4">
+        <BackButton onClick={popSubagentView} />
+        <p className="text-sm text-muted-foreground">
+          No recorded activity for this subagent — it may have been pruned.
+        </p>
+      </div>
+    );
+  }
+
+  const description = span.subagent?.description ?? null;
+  const subagentType = span.subagent?.type ?? null;
+  const summary = span.subagent?.summary ?? null;
+  const running = span.outcome === undefined;
+  const duration =
+    span.endedAt !== undefined ? formatDuration(span.endedAt - span.startedAt) : null;
+  const hasTranscript = events.some((e) => e.eventType.startsWith("transcript_"));
+  const approvalsHere = pendingApprovals.filter((t) =>
+    children.some((c) => c.spanId === t.id)
+  );
+
+  return (
+    <div className="flex h-full flex-col">
+      <div className="flex items-center gap-2 border-b border-border-subtle px-4 py-3">
+        <BackButton onClick={popSubagentView} />
+        <Bot className="h-4 w-4 shrink-0 text-muted-foreground" />
+        <div className="min-w-0 flex-1">
+          <div className="truncate text-sm font-medium">
+            {description ?? "Subagent"}
+          </div>
+          <div className="truncate text-[11px] text-muted-foreground">
+            {subagentType ?? "agent"}
+            {running ? " · running" : span.outcome ? ` · ${span.outcome}` : ""}
+            {duration ? ` · ${duration}` : ""}
+          </div>
+        </div>
+        {running && (
+          <span className="inline-block h-2 w-2 animate-pulse rounded-full bg-primary" />
+        )}
+      </div>
+
+      <div className="flex-1 space-y-1.5 overflow-y-auto p-4">
+        {approvalsHere.map((tool) => (
+          <div
+            key={tool.id}
+            className="rounded-lg border-2 border-primary/40 bg-primary/5 p-3 text-xs"
+          >
+            <div className="mb-2 font-medium">
+              Approval needed: {getToolLabel(tool.name)}
+            </div>
+            {onApproval && (
+              <div className="flex gap-2">
+                <button
+                  onClick={() => onApproval(tool.id, true)}
+                  className="flex items-center gap-1.5 rounded-lg bg-primary px-4 py-1.5 text-xs font-medium text-primary-foreground hover:brightness-110"
+                >
+                  <Check className="h-3 w-3" /> Allow
+                </button>
+                <button
+                  onClick={() => onApproval(tool.id, false)}
+                  className="flex items-center gap-1.5 rounded-lg border border-destructive/30 px-4 py-1.5 text-xs font-medium text-destructive hover:bg-destructive/10"
+                >
+                  <X className="h-3 w-3" /> Deny
+                </button>
+              </div>
+            )}
+          </div>
+        ))}
+
+        {timelineItems.length === 0 && (
+          <p className="text-xs text-muted-foreground">
+            {running ? "Waiting for the first step…" : "No recorded steps."}
+          </p>
+        )}
+
+        {timelineItems.map((item) =>
+          item.kind === "span" ? (
+            <SpanRow
+              key={item.span.spanId}
+              span={item.span}
+              onOpen={
+                item.span.kind === "subagent"
+                  ? () => pushSubagentView(item.span.spanId)
+                  : undefined
+              }
+            />
+          ) : (
+            <TranscriptRow key={`${item.event.spanId}:${item.event.eventIndex}`} event={item.event} />
+          )
+        )}
+
+        {!hasTranscript && children.length > 0 && (
+          <p className="pt-2 text-[11px] text-muted-foreground/60">
+            Activity only — this subagent's transcript was not captured.
+          </p>
+        )}
+        {summary && !running && (
+          <div className="mt-2 rounded-lg border border-border-subtle bg-surface p-3 text-xs">
+            {summary}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function BackButton({ onClick }: { onClick: () => void }) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      className="rounded-md p-1.5 text-muted-foreground transition-colors hover:bg-surface-raised hover:text-foreground"
+      aria-label="Back"
+    >
+      <ArrowLeft className="h-4 w-4" />
+    </button>
+  );
+}
+
+function SpanRow({ span, onOpen }: { span: ActivitySpan; onOpen?: () => void }) {
+  const running = span.outcome === undefined;
+  const failed = isFailureOutcome(span.outcome);
+  const duration =
+    span.endedAt !== undefined
+      ? formatDuration(span.endedAt - (span.waitUntil ?? span.startedAt))
+      : null;
+  return (
+    <motion.div
+      initial={{ opacity: 0, y: 2 }}
+      animate={{ opacity: 1, y: 0 }}
+      className={cn(
+        "flex items-center gap-2 rounded-md px-2 py-1.5 text-xs",
+        failed ? "text-destructive/80" : "text-muted-foreground",
+        onOpen && "cursor-pointer hover:text-foreground"
+      )}
+      onClick={onOpen}
+    >
+      <SpanStatusDot span={span} className="h-2 w-2" />
+      <span className="font-[family-name:var(--font-mono)] font-medium">
+        {spanToolLabel(span)}
+      </span>
+      {span.outcome && span.outcome !== "success" && (
+        <span className="text-[10px] uppercase">{span.outcome}</span>
+      )}
+      <span className="ml-auto font-[family-name:var(--font-mono)] text-[10px] text-muted-foreground/50">
+        {duration ?? (running ? "…" : "")}
+      </span>
+    </motion.div>
+  );
+}
+
+function TranscriptRow({ event }: { event: ActivitySpanEvent }) {
+  const text = typeof event.payload === "string" ? event.payload : JSON.stringify(event.payload);
+  if (!text) return null;
+  return (
+    <div className="whitespace-pre-wrap rounded-md bg-surface px-3 py-2 text-xs text-foreground/80">
+      {text}
+      {event.truncated && <span className="text-muted-foreground/60"> …</span>}
+    </div>
+  );
+}
+
+type TimelineItem =
+  | { kind: "span"; span: ActivitySpan; ts: number }
+  | { kind: "event"; event: ActivitySpanEvent; ts: number };
+
+/** Child steps and transcript excerpts in one chronological stream. */
+function interleave(spans: ActivitySpan[], events: ActivitySpanEvent[]): TimelineItem[] {
+  const items: TimelineItem[] = [
+    ...spans.map((span) => ({ kind: "span" as const, span, ts: span.startedAt })),
+    ...events
+      .filter((e) => e.eventType.startsWith("transcript_"))
+      .map((event) => ({ kind: "event" as const, event, ts: event.ts })),
+  ];
+  return items.sort((a, b) => a.ts - b.ts);
+}

package/src/components/chat/tool-call-timeline.tsx

@@ -13,9 +13,14 @@ import { resolveToolRenderer } from "@schlessera/brain-ui-sdk/client";
 import type { ToolCall } from "../../stores/chat-store.js";
 import { cn } from "../../lib/utils.js";
 import { motion, AnimatePresence } from "framer-motion";
-import { getToolLabel, getTouchedFile, formatDuration } from "./tool-views.js";
+import { getToolLabel, getTouchedFile, formatDuration, formatTokenCount } from "./tool-views.js";
 import { registerBuiltinRenderers, GENERIC_RENDERER } from "./renderers/index.js";
 import { riskHints } from "./risk-hints.js";
+import { useShallow } from "zustand/react/shallow";
+import { useActivityStore, spanForTool, childSpans } from "../../stores/activity-store.js";
+import { useUIStore } from "../../stores/ui-store.js";
+import { useNow } from "../../hooks/use-now.js";
+import { SpanStatusDot } from "../activity/span-bits.js";
 
 // Register the built-in renderer packs once. Registration is build-time; this
 // runs on module load.
@@ -127,13 +132,26 @@ function ToolCallEntry({
     toolCall.status === "pending_approval"
   );
   const prevStatus = useRef(toolCall.status);
+  // One clock for live and reloaded views: when the activity stream carries
+  // this call's span, its server-stamped timing wins over the client stamps
+  // (which don't exist at all for history-loaded messages). Selecting the
+  // span itself (a stable reference) rather than a derived timing object
+  // keeps every other entry from re-rendering on every activity delta.
+  const span = useActivityStore((s) => spanForTool(s, toolCall.id));
+  const timed: ToolCall = span
+    ? {
+        ...toolCall,
+        startedAt: span.waitUntil ?? span.startedAt,
+        ...(span.endedAt !== undefined ? { endedAt: span.endedAt } : {}),
+      }
+    : toolCall;
   // Resolve the renderer for this tool (backend-scoped exact -> global exact ->
   // shape-sniffing predicate). Falls back to the generic renderer.
   const renderer = resolveToolRenderer(toolCall, BACKEND_ID) ?? GENERIC_RENDERER;
   const Icon = renderer.icon ?? FileText;
   const isPending = toolCall.status === "pending_approval";
-  const summary = renderer.summary?.(toolCall) ?? null;
-  const meta = renderer.meta?.(toolCall) ?? null;
+  const summary = renderer.summary?.(timed) ?? null;
+  const meta = renderer.meta?.(timed) ?? null;
   const Input = renderer.Input;
   const Output = renderer.Output;
 
@@ -208,6 +226,9 @@ function ToolCallEntry({
         </span>
       </button>
 
+      {/* Live subagent state for Agent fan-outs, fed by the activity stream. */}
+      {toolCall.name === "Agent" && <SubagentEntryRows agentToolUseId={toolCall.id} />}
+
       {/* Expandable detail */}
       <AnimatePresence>
         {expanded && (
@@ -275,6 +296,43 @@ function ToolCallEntry({
   );
 }
 
+/**
+ * Compact live status of one Agent fan-out: what the subagent is, its state,
+ * elapsed time and step count — with a tap opening the drill-in view. Data
+ * comes from the activity stream (session subscription); on a host without
+ * activity recording this renders nothing and the entry stays as before.
+ */
+function SubagentEntryRows({ agentToolUseId }: { agentToolUseId: string }) {
+  const span = useActivityStore((s) => spanForTool(s, agentToolUseId));
+  const stepCount = useActivityStore(
+    useShallow((s) => childSpans(s, agentToolUseId).length)
+  );
+  const pushSubagentView = useUIStore((s) => s.pushSubagentView);
+  const now = useNow();
+  if (!span || span.kind !== "subagent") return null;
+
+  const description = span.subagent?.description ?? "subagent";
+  const tokens = span.subagent?.totalTokens ?? null;
+  const elapsed = formatDuration((span.endedAt ?? now) - span.startedAt);
+
+  return (
+    <button
+      type="button"
+      onClick={() => pushSubagentView(agentToolUseId)}
+      className="ml-6 flex w-[calc(100%-1.5rem)] items-center gap-2 rounded-md px-2 py-1 text-[11px] text-muted-foreground/80 transition-colors hover:text-foreground"
+    >
+      <SpanStatusDot span={span} />
+      <span className="truncate">{description}</span>
+      <span className="ml-auto shrink-0 font-[family-name:var(--font-mono)] text-[10px] text-muted-foreground/50">
+        {stepCount > 0 && `${stepCount} step${stepCount === 1 ? "" : "s"} · `}
+        {tokens !== null && `${formatTokenCount(tokens)} tok · `}
+        {elapsed}
+      </span>
+      <ChevronRight className="h-3 w-3 shrink-0" />
+    </button>
+  );
+}
+
 function RiskHints({ toolCall }: { toolCall: ToolCall }) {
   const hints = riskHints(toolCall);
   if (hints.length === 0) return null;

package/src/components/chat/tool-views.tsx

@@ -68,6 +68,8 @@ function fileLabel(path: string): ReactNode {
 }
 
 export function formatDuration(ms: number): string {
+  // Server and browser clocks can skew; a negative duration is just 0.
+  ms = Math.max(0, ms);
   if (ms < 1000) return `${(ms / 1000).toFixed(1)}s`;
   if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`;
   const m = Math.floor(ms / 60_000);
@@ -75,6 +77,26 @@ export function formatDuration(ms: number): string {
   return `${m}m ${s}s`;
 }
 
+/** Compact token count: 1234 → "1k", 2_345_678 → "2.3M". */
+export function formatTokenCount(n: number): string {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+  if (n >= 1_000) return `${Math.round(n / 1_000)}k`;
+  return String(n);
+}
+
+/** Relative timestamp for list rows ("3m ago"); dates beyond a week. */
+export function formatRelativeTime(ms: number): string {
+  const diff = Date.now() - ms;
+  const minutes = Math.floor(diff / 60000);
+  if (minutes < 1) return "just now";
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  if (days < 7) return `${days}d ago`;
+  return new Date(ms).toLocaleDateString();
+}
+
 export function countLines(text: string): number {
   let n = 1;
   for (let i = 0; i < text.length; i++) if (text[i] === "\n") n++;