canopy-ui 0.6.2 → 0.7.0

package/src/chat/protocol.ts

@@ -60,6 +60,66 @@ export interface Participant {
   last_seen_at: string | null;
 }
 
+/** A dialog an agent is blocked on.
+ *
+ *  `title` and `body` are what makes it answerable away from the keyboard:
+ *  "Do you want to proceed?" tells you nothing without the command it means.
+ *
+ *  Two producers, one shape, so this never grows a second reader: the session
+ *  report derives it from the transcript (an `AskUserQuestion` tool call — what
+ *  actually blocks a fleet running `bypass permissions`), and the runner can
+ *  still read it off the rendered screen for the dialogs a transcript cannot
+ *  see. `source` says which, and a client is free to ignore it. */
+/** One question of an `AskUserQuestion`. The TUI draws these as TABS and will
+ *  not submit until each has an answer — so a surface that renders only the
+ *  first one cannot complete the ask no matter which button is pressed. That
+ *  was the bug: a two-question closeout showed one question, and a tap toggled
+ *  a checkbox on a dialog that then sat waiting for a Submit nobody could
+ *  reach (eva, 2026-08-12). */
+export interface MenuQuestion {
+  index: number;
+  question: string;
+  header?: string;
+  /** Whether this question takes ANY number of answers. The TUI renders it as
+   *  checkboxes and a number key TOGGLES one instead of answering, which is why
+   *  a client that cannot see this flag renders the wrong control AND the
+   *  runner presses the wrong key. */
+  multi_select?: boolean;
+  options: { number: number; label: string; description?: string }[];
+}
+
+export interface SessionMenu {
+  question: string;
+  title?: string;
+  body?: string;
+  selected?: number | null;
+  source?: string;
+  /** Every question in the ask, in declaration order. Absent on a dialog with
+   *  no tool call behind it (a permission prompt, a trust gate) and on a menu
+   *  from a producer older than this — in both cases the client falls back to
+   *  the single-question fields above, which still describe question 1. */
+  questions?: MenuQuestion[];
+  /** `description` is present on the transcript path and is often the only
+   *  thing that distinguishes two options — "Proceed to Phase 4" does not say
+   *  that Phase 4 is test-gated, and its description does. */
+  options: { number: number; label: string; description?: string }[];
+  /** Set when a human's tap was RELAYED to the runner and then refused there —
+   *  a stale dialog, a shell tab selected in emdash, an unreachable box. The
+   *  API answers `ok:true` the moment it relays the frame, so without this a
+   *  correct refusal is indistinguishable from a press that worked, and the
+   *  button reads as dead. `answer_note` is the sentence to show; the code is
+   *  for logs. The menu stays up alongside it, so there is something to retry. */
+  answer_error?: string;
+  answer_note?: string;
+  /** Carried across a runner restart rather than observed this process. Nothing
+   *  should branch on it — a tap verifies against the real screen either way. */
+  restored?: boolean;
+  /** Epoch seconds when a producer last SAW this dialog. The dialog lives on a
+   *  terminal; this object is a copy, and without an age the only way to find
+   *  out the copy is stale is to tap it and be refused. */
+  observed_at?: number;
+}
+
 export interface SessionState {
   messages: Message[];
   /** Live agent activity, from the runner's turn-boundary hooks. Undefined when
@@ -71,6 +131,21 @@ export interface SessionState {
    *  those apart — but it is the difference between "still thinking, wait" and
    *  "it is waiting on YOU", which previously rendered identically. */
   activity?: "working" | "idle" | "blocked";
+  /** Whether a stop the human asked for actually landed. A SEPARATE axis from
+   *  `activity`, deliberately: a stop that failed leaves the agent `working`,
+   *  which is true and must stay true, so the outcome of the stop cannot be a
+   *  value of activity without either lying or being lost.
+   *
+   *  "requested" is set the moment the server publishes to the runner — nothing
+   *  has pressed Escape yet. Only the runner can say "stopped" or "failed", and
+   *  it only says so after verifying the terminal (see #649: an unverified
+   *  Escape reported as success is what made Stop untrustworthy). */
+  stopState?: "requested" | "stopped" | "failed";
+  /** The dialog the agent is waiting on. Carried in the CONNECT SNAPSHOT, not
+   *  only in live frames: `session.activity` is view-only and reaches a client
+   *  only if it was already connected when the agent blocked — which is exactly
+   *  the case that fails, because you go and look BECAUSE it stopped. */
+  menu?: SessionMenu;
   active_draft: Draft | null;
   participants: Participant[];
   presence_user_ids: number[];
@@ -96,7 +171,14 @@ export type WsEvent =
   | { event: "chat.stream_start"; data: { message_id: string; turn_index: number } }
   // The agent started or finished a turn. Distinct from tool events: it fires
   // while Claude is THINKING, before any content exists to show.
-  | { event: "session.activity"; data: { state: "working" | "idle" | "blocked" } }
+  | { event: "session.activity"; data: { state: "working" | "idle" | "blocked"; menu?: SessionMenu } }
+  | { event: "session.stop"; data: { state: "requested" | "stopped" | "failed" } }
+  // The agent started, or stopped, waiting on a dialog. Its own frame rather
+  // than an overloaded `session.activity`: activity answers "is it producing",
+  // which the hook path owns on a much faster clock, and inventing a state here
+  // to carry a menu would report an agent as idle or blocked on the wrong one.
+  // `menu: null` is the retraction — somebody answered at the keyboard.
+  | { event: "session.menu"; data: { menu: SessionMenu | null } }
   // A human typed into emdash rather than into this page. No client echoed it,
   // so this is the only way it reaches the browser before a reload.
   | { event: "chat.user_message"; data: { message_id: string; turn_index: number; plaintext: string } }
@@ -113,5 +195,19 @@ export type WsEvent =
   | { event: "draft.lock_changed"; data: { draft_id: string; holder_user_id: number | null; expires_at: number | null } }
   | { event: "draft.committed"; data: { draft_id: string; user_message_id: string } }
   | { event: "draft.discarded"; data: { draft_id: string } }
-  | { event: "presence.joined"; data: { user_id: number; email?: string; display_name?: string } }
+  // `participant` carries WHO joined, so a client can add them to its
+  // participant list. Without it a first-time joiner has an id and no name,
+  // and the presence row (which renders participants filtered by presence)
+  // cannot show them at all. Optional so an older server degrades rather than
+  // breaks. The bare `email`/`display_name` below are the vestigial shape that
+  // was declared but never sent by anything.
+  | {
+      event: "presence.joined";
+      data: {
+        user_id: number;
+        participant?: Participant;
+        email?: string;
+        display_name?: string;
+      };
+    }
   | { event: "presence.left"; data: { user_id: number } };

package/src/chat/sessionReducer.test.ts

@@ -584,3 +584,146 @@ describe("blocked — the agent is waiting on YOU", () => {
     expect(after.activity).toBe("blocked");
   });
 });
+
+describe("the dialog an agent is blocked on", () => {
+  const MENU = {
+    question: "Do you want to proceed?",
+    title: "Bash command",
+    body: "rm target.txt",
+    options: [{ number: 1, label: "Yes" }, { number: 2, label: "No" }],
+  };
+
+  it("is carried with the blocked state", () => {
+    const state = sessionReducer(makeState(), {
+      event: "session.activity",
+      data: { state: "blocked", menu: MENU },
+    });
+    expect(state.menu?.options).toHaveLength(2);
+    expect(state.menu?.body).toBe("rm target.txt");
+  });
+
+  it("is dropped when the agent starts producing again", () => {
+    // Buttons that answer a dialog no longer on screen send a stray keystroke
+    // into the prompt — worse than showing nothing.
+    const blocked = sessionReducer(makeState(), {
+      event: "session.activity",
+      data: { state: "blocked", menu: MENU },
+    });
+    const after = sessionReducer(blocked, {
+      event: "chat.tool_use",
+      data: { parent_message_id: null, tool_message_id: "m1", turn_index: 3, block: { id: "t1" } },
+    });
+    expect(after.activity).toBe("working");
+    expect(after.menu).toBeUndefined();
+  });
+
+  it("is cleared by a later activity frame that says the agent is not waiting", () => {
+    const blocked = sessionReducer(makeState(), {
+      event: "session.activity",
+      data: { state: "blocked", menu: MENU },
+    });
+    const idle = sessionReducer(blocked, { event: "session.activity", data: { state: "idle" } });
+    expect(idle.menu).toBeUndefined();
+  });
+
+  it("survives a blocked frame that carries no menu", () => {
+    // The hook path reports `blocked` WITHOUT a menu — it deliberately does not
+    // read the screen (#510: doing so stole emdash's focus). Treating that as a
+    // retraction would erase a menu the snapshot or the session report had
+    // already supplied, which is every menu we now have.
+    const blocked = sessionReducer(makeState(), {
+      event: "session.activity",
+      data: { state: "blocked", menu: MENU },
+    });
+    const again = sessionReducer(blocked, { event: "session.activity", data: { state: "blocked" } });
+    expect(again.menu?.question).toBe("Do you want to proceed?");
+  });
+
+  it("arrives in the connect snapshot, not only in a live frame", () => {
+    // THE fix for "when I click on the session I don't see the menu". Activity
+    // frames are view-only and reach a client only if it was connected when
+    // they fired; you open the session precisely because it stopped.
+    const state = sessionReducer(makeState(), {
+      event: "session.state",
+      data: makeState({ activity: "blocked", menu: MENU }),
+    });
+    expect(state.menu?.question).toBe("Do you want to proceed?");
+  });
+
+  it("appears while you are already watching, via its own frame", () => {
+    const state = sessionReducer(makeState(), {
+      event: "session.menu",
+      data: { menu: MENU },
+    });
+    expect(state.menu?.options).toHaveLength(2);
+  });
+
+  it("is retracted when somebody answers at the keyboard", () => {
+    // `menu: null` from the session report. Buttons that outlive their dialog
+    // press a number into what is now an ordinary prompt, where the agent reads
+    // a bare "1" as an instruction.
+    const blocked = sessionReducer(makeState(), {
+      event: "session.menu",
+      data: { menu: MENU },
+    });
+    const cleared = sessionReducer(blocked, { event: "session.menu", data: { menu: null } });
+    expect(cleared.menu).toBeUndefined();
+  });
+
+  it("keeps an option's description, which is often the whole difference", () => {
+    const state = sessionReducer(makeState(), {
+      event: "session.menu",
+      data: {
+        menu: {
+          question: "How should the run proceed?",
+          options: [
+            { number: 1, label: "Proceed to Phase 4", description: "nothing reaches a real LLO" },
+            { number: 2, label: "Stop the run here", description: "end at the Phase 3 boundary" },
+          ],
+        },
+      },
+    });
+    expect(state.menu?.options[0].description).toContain("real LLO");
+  });
+});
+
+describe("session.stop — whether the stop actually landed", () => {
+  const base = (over: Partial<SessionState> = {}): SessionState => ({
+    messages: [],
+    active_draft: null,
+    participants: [],
+    presence_user_ids: [],
+    current_user_id: 1,
+    ...over,
+  });
+
+  it("records a requested stop without claiming it worked", () => {
+    const out = sessionReducer(base(), {
+      event: "session.stop",
+      data: { state: "requested" },
+    } as WsEvent);
+    expect(out.stopState).toBe("requested");
+  });
+
+  it("keeps the agent WORKING when the stop failed", () => {
+    // The whole point of a separate axis. A failed stop leaves the agent running,
+    // and both facts have to survive together — collapsing them into `activity`
+    // loses whichever one loses the race, and it was always the stop.
+    const out = sessionReducer(base({ activity: "working" }), {
+      event: "session.stop",
+      data: { state: "failed" },
+    } as WsEvent);
+    expect(out.stopState).toBe("failed");
+    expect(out.activity).toBe("working");
+  });
+
+  it("a new turn clears a stale stop outcome", () => {
+    // "your stop did not take" pinned over fresh work is a warning about
+    // something the human has already moved on from.
+    const out = sessionReducer(base({ stopState: "failed" }), {
+      event: "chat.stream_start",
+      data: { message_id: "m1" },
+    } as WsEvent);
+    expect(out.stopState).toBeUndefined();
+  });
+});

package/src/chat/sessionReducer.ts

@@ -28,8 +28,17 @@ const UNBLOCKING_FRAMES = new Set([
 ]);
 
 export function sessionReducer(prev: SessionState, frame: WsEvent): SessionState {
+  if (frame.event === "chat.stream_start" || frame.event === "draft.committed") {
+    // A new turn is starting, so the previous turn's stop outcome is history —
+    // leaving "your stop did not take" pinned over fresh work would be a stale
+    // warning about something the human has already moved on from.
+    prev = { ...prev, stopState: undefined };
+  }
   if (prev.activity === "blocked" && UNBLOCKING_FRAMES.has(frame.event)) {
-    prev = { ...prev, activity: "working" };
+    // Dropping the menu with the state matters as much as the state itself —
+    // the dialog is gone, and buttons that answer a gone dialog send a stray
+    // keystroke into the prompt.
+    prev = { ...prev, activity: "working", menu: undefined };
   }
   switch (frame.event) {
     case "session.state":
@@ -68,7 +77,33 @@ export function sessionReducer(prev: SessionState, frame: WsEvent): SessionState
     }
 
     case "session.activity":
-      return { ...prev, activity: frame.data.state };
+      // A frame that says the agent is NOT waiting retracts the menu — a stale
+      // dialog is worse than none, because its buttons would answer a prompt
+      // that is no longer on screen.
+      //
+      // A `blocked` frame that carries no menu does NOT, and that asymmetry is
+      // load-bearing. The hook path reports `blocked` without one on purpose
+      // (#510 — reading the screen stole emdash's focus), so treating a bare
+      // `blocked` as a retraction would erase every menu the snapshot and the
+      // session report supply, which is now all of them.
+      if (frame.data.state !== "blocked") {
+        return { ...prev, activity: frame.data.state, menu: undefined };
+      }
+      return { ...prev, activity: "blocked", menu: frame.data.menu ?? prev.menu };
+
+    case "session.stop":
+      // Independent of `activity` on purpose. A stop that FAILED leaves the agent
+      // working, and both facts have to be sayable at once: "it is still going"
+      // AND "your stop did not take". Collapsing them loses whichever one loses
+      // the race, and it was always the second — which is how a dead Stop button
+      // stayed invisible.
+      return { ...prev, stopState: frame.data.state };
+
+    case "session.menu":
+      // The authoritative producer: the session report re-derives the dialog
+      // from the transcript every ~10s and pushes only the edges. `null` is the
+      // retraction, and has to be honoured — somebody answered at the keyboard.
+      return { ...prev, menu: frame.data.menu ?? undefined };
 
     case "chat.user_message": {
       // Someone typed into emdash, OR into this page. Both reach here, and that
@@ -335,7 +370,23 @@ export function sessionReducer(prev: SessionState, frame: WsEvent): SessionState
     case "presence.joined": {
       const ids = new Set(prev.presence_user_ids);
       ids.add(frame.data.user_id);
-      return { ...prev, presence_user_ids: [...ids] };
+      // Adopt the joiner into `participants` too. The presence ROW renders
+      // participants filtered by presence, so an id with no matching
+      // participant is invisible — which is what made a first-time joiner
+      // unseeable by everyone already in the room until they reloaded.
+      // `participant` is optional (an older server may not send it); without
+      // it this degrades to exactly the previous behaviour rather than
+      // inventing a nameless entry.
+      const joined = frame.data.participant;
+      const known = joined
+        ? prev.participants.some((p) => p.user_id === joined.user_id)
+        : true;
+      return {
+        ...prev,
+        presence_user_ids: [...ids],
+        participants:
+          joined && !known ? [...prev.participants, joined] : prev.participants,
+      };
     }
 
     case "presence.left":

package/src/presence/PresenceBadge.test.tsx

@@ -0,0 +1,84 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { PresenceBadge } from './PresenceBadge'
+import type { Viewer } from './usePresence'
+
+// NOTE ON CONVENTION: canopy-web has no @testing-library/jest-dom and no
+// user-event package. Assertions use toBeTruthy(), interactions use
+// fireEvent, and every DOM test carries the `@vitest-environment jsdom`
+// docblock above — the vitest config sets no global environment. Do not
+// introduce toBeInTheDocument() here; it will not exist.
+
+const viewer = (n: number, over: Partial<Viewer> = {}): Viewer => ({
+  email: `u${n}@x.com`,
+  name: `User ${n}`,
+  subLocation: 'run overview',
+  idle: false,
+  self: false,
+  ...over,
+})
+
+describe('PresenceBadge', () => {
+  afterEach(cleanup)
+
+  it('renders nothing when you are the only viewer', () => {
+    const { container } = render(<PresenceBadge viewers={[viewer(1, { self: true })]} />)
+    expect(container.innerHTML).toBe('')
+  })
+
+  it('renders nothing when the roster is empty', () => {
+    const { container } = render(<PresenceBadge viewers={[]} />)
+    expect(container.innerHTML).toBe('')
+  })
+
+  it('shows at most three avatars and collapses the rest into +N', () => {
+    render(<PresenceBadge viewers={[viewer(1), viewer(2), viewer(3), viewer(4), viewer(5)]} />)
+    expect(screen.getByText('+2')).toBeTruthy()
+  })
+
+  it('labels the control with the viewer count for screen readers', () => {
+    render(<PresenceBadge viewers={[viewer(1), viewer(2)]} />)
+    expect(screen.getByRole('button', { name: /2 people viewing this page/i })).toBeTruthy()
+  })
+
+  it('expands to a named list on click, listing you first and marked', () => {
+    render(<PresenceBadge viewers={[viewer(1), viewer(2, { self: true, name: 'Me' })]} />)
+    fireEvent.click(screen.getByRole('button'))
+    expect(screen.getByText(/Me/)).toBeTruthy()
+    expect(screen.getByText('(you)')).toBeTruthy()
+    expect(screen.getByText('User 1')).toBeTruthy()
+  })
+
+  it('renders two viewers with no email without colliding their React keys', () => {
+    // Email is not guaranteed non-empty (the server sends "" for a user with
+    // none), so it cannot be the row key. A collision here shows up as a
+    // React duplicate-key error, not as a visibly missing row.
+    const errors: unknown[][] = []
+    const spy = vi.spyOn(console, 'error').mockImplementation((...args) => {
+      errors.push(args)
+    })
+    try {
+      render(
+        <PresenceBadge
+          viewers={[
+            viewer(1, { email: '', name: 'Ana' }),
+            viewer(2, { email: '', name: 'Bo' }),
+          ]}
+        />,
+      )
+      fireEvent.click(screen.getByRole('button'))
+      expect(screen.getByText('Ana')).toBeTruthy()
+      expect(screen.getByText('Bo')).toBeTruthy()
+    } finally {
+      spy.mockRestore()
+    }
+    expect(errors.flat().join(' ')).not.toMatch(/same key/i)
+  })
+
+  it('marks idle viewers in the expanded list', () => {
+    render(<PresenceBadge viewers={[viewer(1, { idle: true }), viewer(2)]} />)
+    fireEvent.click(screen.getByRole('button'))
+    expect(screen.getByText('idle')).toBeTruthy()
+  })
+})

package/src/presence/PresenceBadge.tsx

@@ -0,0 +1,111 @@
+import { useEffect, useRef, useState } from 'react'
+import { avatarFor } from './avatar'
+import type { Viewer } from './usePresence'
+
+const MAX_AVATARS = 3
+
+/**
+ * Collapsed viewer cluster that expands into a named list.
+ *
+ * Renders nothing when you are alone — a badge that permanently reads "1"
+ * is noise, and the account menu already tells you who you are.
+ */
+export function PresenceBadge({ viewers }: { viewers: Viewer[] }) {
+  const [open, setOpen] = useState(false)
+  const rootRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    if (!open) return
+    const onDown = (e: MouseEvent) => {
+      if (!rootRef.current?.contains(e.target as Node)) setOpen(false)
+    }
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') setOpen(false)
+    }
+    document.addEventListener('mousedown', onDown)
+    document.addEventListener('keydown', onKey)
+    return () => {
+      document.removeEventListener('mousedown', onDown)
+      document.removeEventListener('keydown', onKey)
+    }
+  }, [open])
+
+  if (viewers.length < 2) return null
+
+  // You first, then everyone else in roster order.
+  //
+  // Rows are keyed by POSITION, not by email: email is the only plausible
+  // identity field on a Viewer and it is not guaranteed non-empty (the
+  // server sends "" for a user with no email), so two such viewers would
+  // collide on one key. The list is short, server-ordered, and re-rendered
+  // wholesale on every roster broadcast, so index keys cost nothing here.
+  const ordered = [...viewers].sort((a, b) => Number(b.self) - Number(a.self))
+  const shown = ordered.slice(0, MAX_AVATARS)
+  const overflow = ordered.length - shown.length
+
+  return (
+    <div className="relative" ref={rootRef}>
+      <button
+        type="button"
+        onClick={() => setOpen((v) => !v)}
+        aria-expanded={open}
+        aria-label={`${viewers.length} people viewing this page`}
+        className="flex items-center -space-x-2 rounded-full p-0.5 hover:opacity-90"
+      >
+        {shown.map((v, i) => {
+          const { initials, colorClass } = avatarFor(v.email, v.name)
+          return (
+            <span
+              key={i}
+              className={`inline-flex h-6 w-6 items-center justify-center rounded-full
+                ring-2 ring-card text-[10px] font-semibold text-white ${colorClass}
+                ${v.idle ? 'opacity-45' : ''}`}
+            >
+              {initials}
+            </span>
+          )
+        })}
+        {overflow > 0 && (
+          <span
+            className="inline-flex h-6 w-6 items-center justify-center rounded-full
+              bg-muted ring-2 ring-card text-[10px] font-semibold text-muted-foreground"
+          >
+            +{overflow}
+          </span>
+        )}
+      </button>
+
+      {open && (
+        <div
+          className="absolute right-0 z-50 mt-2 w-64 rounded-md border border-border
+            bg-card p-1 shadow-md"
+        >
+          {ordered.map((v, i) => {
+            const { initials, colorClass } = avatarFor(v.email, v.name)
+            return (
+              <div key={i} className="flex items-center gap-2 rounded px-2 py-1.5">
+                <span
+                  className={`inline-flex h-6 w-6 shrink-0 items-center justify-center
+                    rounded-full text-[10px] font-semibold text-white ${colorClass}
+                    ${v.idle ? 'opacity-45' : ''}`}
+                >
+                  {initials}
+                </span>
+                <span className="min-w-0 flex-1">
+                  <span className="block truncate text-sm text-foreground">
+                    {v.name || v.email}
+                    {v.self && <span className="ml-1 text-muted-foreground">(you)</span>}
+                  </span>
+                  <span className="block truncate text-xs text-muted-foreground">
+                    {v.subLocation}
+                  </span>
+                </span>
+                {v.idle && <span className="text-[10px] text-muted-foreground">idle</span>}
+              </div>
+            )
+          })}
+        </div>
+      )}
+    </div>
+  )
+}

package/src/presence/avatar.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest'
+import { avatarFor } from './avatar'
+
+describe('avatarFor', () => {
+  it('takes initials from a two-part display name', () => {
+    expect(avatarFor('alice@x.com', 'Alice Chen').initials).toBe('AC')
+  })
+
+  it('falls back to the email local-part when there is no name', () => {
+    expect(avatarFor('bob.ali@x.com', '').initials).toBe('BA')
+  })
+
+  it('produces a single initial for a one-word identity', () => {
+    expect(avatarFor('ace@x.com', 'ACE').initials).toBe('A')
+  })
+
+  it('is deterministic: the same email is always the same color', () => {
+    expect(avatarFor('alice@x.com', 'Alice Chen').colorClass)
+      .toBe(avatarFor('alice@x.com', 'Different Name').colorClass)
+  })
+
+  it('color is a deterministic function of email via djb2', () => {
+    const email = 'alice@example.com'
+    const COLORS = [
+      'bg-sky-600',
+      'bg-emerald-600',
+      'bg-violet-600',
+      'bg-amber-600',
+      'bg-rose-600',
+      'bg-teal-600',
+      'bg-indigo-600',
+      'bg-fuchsia-600',
+    ]
+
+    // Compute expected color using djb2 formula
+    let h = 5381
+    for (let i = 0; i < email.length; i++) h = ((h << 5) + h + email.charCodeAt(i)) | 0
+    const expectedColorClass = COLORS[Math.abs(h) % COLORS.length]
+
+    expect(avatarFor(email, 'Any Name').colorClass).toBe(expectedColorClass)
+  })
+})

package/src/presence/avatar.ts

@@ -0,0 +1,36 @@
+// Fixed palette. Chosen for legibility against white text in both themes;
+// index is picked by a stable hash of the email so a person keeps one color
+// everywhere, in every app, across sessions.
+const COLORS = [
+  'bg-sky-600',
+  'bg-emerald-600',
+  'bg-violet-600',
+  'bg-amber-600',
+  'bg-rose-600',
+  'bg-teal-600',
+  'bg-indigo-600',
+  'bg-fuchsia-600',
+]
+
+function hash(value: string): number {
+  // djb2. Not cryptographic — we only need stable bucketing.
+  let h = 5381
+  for (let i = 0; i < value.length; i++) h = ((h << 5) + h + value.charCodeAt(i)) | 0
+  return Math.abs(h)
+}
+
+/**
+ * Initials + a stable color class for one person.
+ *
+ * Color keys on email rather than display name so changing your name does
+ * not change your color out from under people who have learned it.
+ */
+export function avatarFor(email: string, name: string): { initials: string; colorClass: string } {
+  const source = (name || email.split('@')[0] || '?').trim()
+  const words = source.split(/[\s._-]+/).filter(Boolean)
+  const initials =
+    words.length >= 2
+      ? (words[0][0] + words[1][0]).toUpperCase()
+      : (words[0]?.[0] ?? '?').toUpperCase()
+  return { initials, colorClass: COLORS[hash(email) % COLORS.length] }
+}

package/src/presence/index.ts

@@ -0,0 +1,4 @@
+export { PresenceBadge } from './PresenceBadge'
+export { usePresence, type Viewer, type UsePresenceOptions } from './usePresence'
+export { pageKeyFor, type PageLocation, type RouteRule } from './pageKey'
+export { avatarFor } from './avatar'