canopy-ui 0.6.2 → 0.6.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canopy-ui",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "type": "module",
   "repository": {
     "type": "git",
@@ -12,6 +12,7 @@
     "./lib": "./src/lib/index.ts",
     "./ui": "./src/ui/index.ts",
     "./chat": "./src/chat/index.ts",
+    "./presence": "./src/presence/index.ts",
     "./shell": "./src/shell/index.ts",
     "./tokens": "./src/tokens/index.ts",
     "./tokens/preset.css": "./src/tokens/preset.css",
@@ -42,5 +43,7 @@
   "devDependencies": {
     "sonner": "^2.0.7"
   },
-  "files": ["src"]
+  "files": [
+    "src"
+  ]
 }

package/src/chat/MenuPrompt.tsx

@@ -0,0 +1,58 @@
+import type { SessionMenu } from "./protocol";
+
+export interface MenuPromptProps {
+  menu: SessionMenu;
+  busy?: boolean;
+  error?: string;
+  onAnswer: (option: number | null) => void;
+}
+
+/**
+ * The dialog a blocked agent is waiting on, answerable from here.
+ *
+ * Shows the SUBJECT, not just the question: "Do you want to proceed?" tells you
+ * nothing away from the keyboard — the command is the whole decision, so it is
+ * rendered verbatim and monospaced rather than summarised.
+ *
+ * Refusing is always offered separately from the numbered options. Every dialog
+ * accepts Escape, and it is the only answer that stays correct if the dialog on
+ * screen is not the one rendered here.
+ */
+export function MenuPrompt({ menu, busy = false, error, onAnswer }: MenuPromptProps) {
+  return (
+    <div className="rounded-md border border-warning/30 bg-warning/10 px-3 py-2.5 text-sm">
+      <div className="flex items-center gap-1.5 font-medium text-warning">
+        <span className="inline-block h-1.5 w-1.5 animate-pulse rounded-full bg-warning" />
+        {menu.title || "Waiting on you"}
+      </div>
+      {menu.body ? (
+        <pre className="mt-1.5 max-h-32 overflow-auto whitespace-pre-wrap break-all rounded bg-muted px-2 py-1.5 font-mono text-[12px] text-foreground-secondary">
+          {menu.body}
+        </pre>
+      ) : null}
+      <div className="mt-2 text-foreground">{menu.question}</div>
+      <div className="mt-2 flex flex-wrap gap-1.5">
+        {menu.options.map((option) => (
+          <button
+            key={option.number}
+            type="button"
+            disabled={busy}
+            onClick={() => onAnswer(option.number)}
+            className="rounded border border-input bg-card px-2 py-1 text-[13px] text-foreground hover:bg-muted disabled:opacity-50"
+          >
+            {option.label}
+          </button>
+        ))}
+        <button
+          type="button"
+          disabled={busy}
+          onClick={() => onAnswer(null)}
+          className="rounded px-2 py-1 text-[13px] text-muted-foreground hover:text-foreground disabled:opacity-50"
+        >
+          Cancel (Esc)
+        </button>
+      </div>
+      {error ? <div className="mt-1.5 text-[12px] text-destructive">{error}</div> : null}
+    </div>
+  );
+}

package/src/chat/index.ts

@@ -11,6 +11,7 @@ export type {
   MessageStatus,
   Draft,
   Participant,
+  SessionMenu,
   SessionState,
   WsAction,
   WsEvent,
@@ -43,6 +44,7 @@ export {
 
 // Presentational components
 export { ChatPanel, type ChatPanelProps } from "./ChatPanel";
+export { MenuPrompt, type MenuPromptProps } from "./MenuPrompt";
 export { MessageList } from "./MessageList";
 export { MessageItem, type RenderMarkdown } from "./MessageItem";
 export { ToolCallPair } from "./ToolCallPair";

package/src/chat/protocol.ts

@@ -60,6 +60,18 @@ export interface Participant {
   last_seen_at: string | null;
 }
 
+/** A dialog an agent is blocked on, read off its terminal.
+ *
+ *  `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. */
+export interface SessionMenu {
+  question: string;
+  title?: string;
+  body?: string;
+  selected?: number | null;
+  options: { number: number; label: string }[];
+}
+
 export interface SessionState {
   messages: Message[];
   /** Live agent activity, from the runner's turn-boundary hooks. Undefined when
@@ -71,6 +83,10 @@ 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";
+  /** The dialog the agent is waiting on, when one could be read off its screen.
+   *  Absent when the agent is not blocked, or when the runner has no way to look
+   *  (no CDP) — "blocked" still arrives, it just has no buttons. */
+  menu?: SessionMenu;
   active_draft: Draft | null;
   participants: Participant[];
   presence_user_ids: number[];
@@ -96,7 +112,7 @@ 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 } }
   // 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 } }

package/src/chat/sessionReducer.test.ts

@@ -584,3 +584,45 @@ 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 has no menu", () => {
+    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();
+  });
+});

package/src/chat/sessionReducer.ts

@@ -29,7 +29,10 @@ const UNBLOCKING_FRAMES = new Set([
 
 export function sessionReducer(prev: SessionState, frame: WsEvent): SessionState {
   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 +71,10 @@ export function sessionReducer(prev: SessionState, frame: WsEvent): SessionState
     }
 
     case "session.activity":
-      return { ...prev, activity: frame.data.state };
+      // The menu is cleared unless this frame carries one: a stale dialog is
+      // worse than none, because its buttons would answer a prompt that is no
+      // longer on screen.
+      return { ...prev, activity: frame.data.state, menu: frame.data.menu };
 
     case "chat.user_message": {
       // Someone typed into emdash, OR into this page. Both reach here, and that

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'

package/src/presence/pageKey.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest'
+import { pageKeyFor, type RouteRule } from './pageKey'
+
+const ACE_RULES: RouteRule[] = [
+  {
+    pattern: /^\/w\/([^/]+)\/opps\/([^/]+)\/runs\/([^/]+)\/steps\/([^/]+)/,
+    build: (m) => ({ workspace: m[1], resource: `opp:${m[2]}/${m[3]}`, subLocation: m[4] }),
+  },
+  {
+    pattern: /^\/w\/([^/]+)\/opps\/([^/]+)\/runs\/([^/]+)/,
+    build: (m) => ({ workspace: m[1], resource: `opp:${m[2]}/${m[3]}`, subLocation: 'run overview' }),
+  },
+  {
+    pattern: /^\/w\/([^/]+)\/activity/,
+    build: (m) => ({ workspace: m[1], resource: 'activity', subLocation: 'Activity' }),
+  },
+]
+
+describe('pageKeyFor', () => {
+  it('collapses every step of a run onto one key, keeping the step as sub-location', () => {
+    const a = pageKeyFor('ace', '/w/dimagi-team/opps/bednet/runs/run-001/steps/idea-to-pdd', ACE_RULES)
+    const b = pageKeyFor('ace', '/w/dimagi-team/opps/bednet/runs/run-001', ACE_RULES)
+    expect(a?.pageKey).toBe('ace:dimagi-team:opp:bednet/run-001')
+    expect(b?.pageKey).toBe(a?.pageKey)
+    expect(a?.subLocation).toBe('idea-to-pdd')
+    expect(b?.subLocation).toBe('run overview')
+  })
+
+  it('keeps different runs of the same opp on different keys', () => {
+    const a = pageKeyFor('ace', '/w/dimagi-team/opps/bednet/runs/run-001', ACE_RULES)
+    const b = pageKeyFor('ace', '/w/dimagi-team/opps/bednet/runs/run-002', ACE_RULES)
+    expect(a?.pageKey).not.toBe(b?.pageKey)
+  })
+
+  it('namespaces by app so two apps never collide', () => {
+    const ace = pageKeyFor('ace', '/w/dimagi-team/activity', ACE_RULES)
+    const canopy = pageKeyFor('canopy', '/w/dimagi-team/activity', ACE_RULES)
+    expect(ace?.pageKey).toBe('ace:dimagi-team:activity')
+    expect(canopy?.pageKey).toBe('canopy:dimagi-team:activity')
+  })
+
+  it('returns null for unmatched routes rather than a catch-all key', () => {
+    expect(pageKeyFor('ace', '/totally/unknown', ACE_RULES)).toBeNull()
+  })
+
+  it('is order-sensitive: the first matching rule wins', () => {
+    const loose: RouteRule[] = [
+      { pattern: /^\/w\/([^/]+)\/opps/, build: (m) => ({ workspace: m[1], resource: 'opps', subLocation: 'Opps' }) },
+      ...ACE_RULES,
+    ]
+    expect(pageKeyFor('ace', '/w/x/opps/bednet/runs/run-001', loose)?.pageKey).toBe('ace:x:opps')
+  })
+})

package/src/presence/pageKey.ts

@@ -0,0 +1,37 @@
+/** A resolved presence location: which roster to join, and where in it you are. */
+export interface PageLocation {
+  /** `<app>:<workspace|global>:<resource>` — the roster identity. */
+  pageKey: string
+  /** Human-readable position within the resource, for the expanded panel. */
+  subLocation: string
+}
+
+export interface RouteRule {
+  pattern: RegExp
+  build: (m: RegExpMatchArray) => { workspace: string; resource: string; subLocation: string }
+}
+
+/**
+ * Resolve a pathname to a presence location. Pure — the single place
+ * grouping correctness lives.
+ *
+ * Rules are evaluated in order and the first match wins, so more specific
+ * patterns must be listed before looser ones.
+ *
+ * Returns null when nothing matches. Callers render no badge in that case;
+ * grouping every unrecognised route under one catch-all key would put
+ * unrelated strangers in the same roster.
+ */
+export function pageKeyFor(
+  app: string,
+  pathname: string,
+  rules: RouteRule[],
+): PageLocation | null {
+  for (const rule of rules) {
+    const m = pathname.match(rule.pattern)
+    if (!m) continue
+    const { workspace, resource, subLocation } = rule.build(m)
+    return { pageKey: `${app}:${workspace}:${resource}`, subLocation }
+  }
+  return null
+}

package/src/presence/usePresence.test.ts

@@ -0,0 +1,199 @@
+// @vitest-environment jsdom
+import { act, renderHook } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { usePresence } from './usePresence'
+
+class FakeSocket {
+  static last: FakeSocket | null = null
+  static created = 0
+  static OPEN = 1
+  readyState = 0
+  sent: string[] = []
+  onopen: (() => void) | null = null
+  onmessage: ((e: { data: string }) => void) | null = null
+  onclose: (() => void) | null = null
+  constructor(public url: string) {
+    FakeSocket.last = this
+    FakeSocket.created += 1
+  }
+  send(frame: string) {
+    this.sent.push(frame)
+  }
+  close() {
+    this.readyState = 3
+  }
+  open() {
+    this.readyState = FakeSocket.OPEN
+    this.onopen?.()
+  }
+  deliver(payload: unknown) {
+    this.onmessage?.({ data: JSON.stringify(payload) })
+  }
+}
+
+beforeEach(() => {
+  vi.stubGlobal('WebSocket', FakeSocket as unknown as typeof WebSocket)
+  vi.useFakeTimers()
+  FakeSocket.created = 0
+})
+afterEach(() => {
+  vi.useRealTimers()
+  vi.unstubAllGlobals()
+  FakeSocket.last = null
+})
+
+const LOC = { pageKey: 'ace:ws:opp:a/run-001', subLocation: 'run overview' }
+
+describe('usePresence', () => {
+  it('sends presence.enter once the socket opens', () => {
+    renderHook(() => usePresence({ url: 'ws://x/ws/presence/', location: LOC }))
+    act(() => FakeSocket.last!.open())
+    expect(JSON.parse(FakeSocket.last!.sent[0])).toEqual({
+      type: 'presence.enter',
+      page_key: LOC.pageKey,
+      sub_location: LOC.subLocation,
+    })
+  })
+
+  it('exposes the roster the server broadcasts', () => {
+    const { result } = renderHook(() => usePresence({ url: 'ws://x/ws/presence/', location: LOC }))
+    act(() => FakeSocket.last!.open())
+    act(() =>
+      FakeSocket.last!.deliver({
+        event: 'presence.roster',
+        data: {
+          page_key: LOC.pageKey,
+          viewers: [{ email: 'a@x.com', name: 'A', sub_location: 'idea-to-pdd', idle: false, self: true }],
+        },
+      }),
+    )
+    expect(result.current.viewers).toEqual([
+      { email: 'a@x.com', name: 'A', subLocation: 'idea-to-pdd', idle: false, self: true },
+    ])
+  })
+
+  it('ignores a roster for a page key it is no longer on', () => {
+    const { result } = renderHook(() => usePresence({ url: 'ws://x/ws/presence/', location: LOC }))
+    act(() => FakeSocket.last!.open())
+    act(() =>
+      FakeSocket.last!.deliver({
+        event: 'presence.roster',
+        data: { page_key: 'ace:ws:opp:STALE/run-999', viewers: [
+          { email: 'z@x.com', name: 'Z', sub_location: '', idle: false, self: false }] },
+      }),
+    )
+    expect(result.current.viewers).toEqual([])
+  })
+
+  it('re-enters without reconnecting when the location changes', () => {
+    const { rerender } = renderHook(
+      ({ location }) => usePresence({ url: 'ws://x/ws/presence/', location }),
+      { initialProps: { location: LOC } },
+    )
+    act(() => FakeSocket.last!.open())
+    const socket = FakeSocket.last!
+    rerender({ location: { pageKey: 'ace:ws:activity', subLocation: 'Activity' } })
+    expect(FakeSocket.last).toBe(socket) // same socket, no reconnect
+    expect(JSON.parse(socket.sent[socket.sent.length - 1])).toEqual({
+      type: 'presence.enter',
+      page_key: 'ace:ws:activity',
+      sub_location: 'Activity',
+    })
+  })
+
+  it('heartbeats every 20 seconds', () => {
+    renderHook(() => usePresence({ url: 'ws://x/ws/presence/', location: LOC }))
+    act(() => FakeSocket.last!.open())
+    act(() => void vi.advanceTimersByTime(20_000))
+    expect(JSON.parse(FakeSocket.last!.sent[1])).toEqual({ type: 'presence.heartbeat', idle: false })
+  })
+
+  it('clears the roster and sends nothing when there is no location', () => {
+    const { result } = renderHook(() =>
+      usePresence({ url: 'ws://x/ws/presence/', location: null }),
+    )
+    expect(result.current.viewers).toEqual([])
+    expect(FakeSocket.last).toBeNull()
+  })
+
+  it('backs off exponentially while reconnects keep failing, up to a ceiling', () => {
+    // A tab left open past session expiry is closed with 4001 on every
+    // attempt. A flat retry hammers a handshake every 2s forever; the delay
+    // must grow and then cap.
+    renderHook(() => usePresence({ url: 'ws://x/ws/presence/', location: LOC }))
+    expect(FakeSocket.created).toBe(1)
+
+    const failOnce = (expectedDelay: number) => {
+      const before = FakeSocket.created
+      act(() => FakeSocket.last!.onclose!())
+      // Nothing reconnects a millisecond early...
+      act(() => void vi.advanceTimersByTime(expectedDelay - 1))
+      expect(FakeSocket.created).toBe(before)
+      // ...and exactly one reconnect lands on the deadline.
+      act(() => void vi.advanceTimersByTime(1))
+      expect(FakeSocket.created).toBe(before + 1)
+    }
+
+    failOnce(2_000)
+    failOnce(4_000)
+    failOnce(8_000)
+    failOnce(16_000)
+    failOnce(32_000)
+    failOnce(60_000) // ceiling, not 64_000
+    failOnce(60_000) // and it stays there
+  })
+
+  it('resets the backoff once a socket actually opens', () => {
+    renderHook(() => usePresence({ url: 'ws://x/ws/presence/', location: LOC }))
+    act(() => FakeSocket.last!.onclose!())
+    act(() => void vi.advanceTimersByTime(2_000))
+    act(() => FakeSocket.last!.onclose!())
+    act(() => void vi.advanceTimersByTime(4_000)) // now at a 4s delay
+
+    act(() => FakeSocket.last!.open()) // a good connection clears the streak
+
+    const before = FakeSocket.created
+    act(() => FakeSocket.last!.onclose!())
+    act(() => void vi.advanceTimersByTime(2_000))
+    expect(FakeSocket.created).toBe(before + 1)
+  })
+
+  it('clears the previous page\'s viewers on navigation even when the socket is not open', () => {
+    // Otherwise the old page's avatars linger on the new page until a roster
+    // for it arrives — which, on a dead socket, may be never.
+    const { result, rerender } = renderHook(
+      ({ location }) => usePresence({ url: 'ws://x/ws/presence/', location }),
+      { initialProps: { location: LOC } },
+    )
+    act(() => FakeSocket.last!.open())
+    act(() =>
+      FakeSocket.last!.deliver({
+        event: 'presence.roster',
+        data: {
+          page_key: LOC.pageKey,
+          viewers: [{ email: 'a@x.com', name: 'A', sub_location: '', idle: false, self: false }],
+        },
+      }),
+    )
+    expect(result.current.viewers).toHaveLength(1)
+
+    FakeSocket.last!.readyState = 3 // socket dropped, reconnect pending
+    rerender({ location: { pageKey: 'ace:ws:activity', subLocation: 'Activity' } })
+    expect(result.current.viewers).toEqual([])
+  })
+
+  it('swallows a synchronous WebSocket constructor throw and stays on an empty roster', () => {
+    class ThrowingSocket {
+      constructor() {
+        throw new Error('mixed content: refused to connect to insecure WebSocket')
+      }
+    }
+    vi.stubGlobal('WebSocket', ThrowingSocket as unknown as typeof WebSocket)
+
+    let hook!: ReturnType<typeof renderHook<{ viewers: unknown[] }, void>>
+    expect(() => {
+      hook = renderHook(() => usePresence({ url: 'ws://x/ws/presence/', location: LOC }))
+    }).not.toThrow()
+    expect(hook.result.current.viewers).toEqual([])
+  })
+})

package/src/presence/usePresence.ts

@@ -0,0 +1,188 @@
+import { useEffect, useRef, useState } from 'react'
+import type { PageLocation } from './pageKey'
+
+export interface Viewer {
+  email: string
+  name: string
+  subLocation: string
+  idle: boolean
+  self: boolean
+}
+
+export interface UsePresenceOptions {
+  url: string
+  location: PageLocation | null
+}
+
+const HEARTBEAT_MS = 20_000
+const IDLE_AFTER_MS = 120_000
+// Reconnect backoff. A flat retry is wrong for the permanent-failure case:
+// a tab left open past session expiry is closed with 4001 on every attempt,
+// so a flat 2s retry hammers a handshake forever. Double up to a ceiling and
+// reset on a socket that actually opens.
+const RECONNECT_BASE_MS = 2_000
+const RECONNECT_MAX_MS = 60_000
+
+/**
+ * One presence socket per tab.
+ *
+ * Navigation re-keys the existing connection with a fresh `presence.enter`
+ * rather than reconnecting — a socket per page would churn handshakes on
+ * every click.
+ *
+ * Every failure path degrades to an empty roster. Presence is an
+ * enhancement; it must never surface an error to the user.
+ */
+export function usePresence({ url, location }: UsePresenceOptions): { viewers: Viewer[] } {
+  const [viewers, setViewers] = useState<Viewer[]>([])
+  const wsRef = useRef<WebSocket | null>(null)
+  const locationRef = useRef(location)
+  const idleRef = useRef(false)
+  locationRef.current = location
+
+  // Socket lifecycle. Deliberately NOT keyed on `location` — the socket
+  // outlives navigation.
+  useEffect(() => {
+    if (!location) {
+      setViewers([])
+      return
+    }
+    let closedByCleanup = false
+    let reconnectTimer: ReturnType<typeof setTimeout> | null = null
+    let heartbeat: ReturnType<typeof setInterval> | null = null
+    let reconnectDelay = RECONNECT_BASE_MS
+
+    const scheduleReconnect = () => {
+      if (closedByCleanup) return
+      reconnectTimer = setTimeout(open, reconnectDelay)
+      reconnectDelay = Math.min(reconnectDelay * 2, RECONNECT_MAX_MS)
+    }
+
+    const send = (frame: unknown) => {
+      const ws = wsRef.current
+      if (ws && ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(frame))
+    }
+
+    const enter = () => {
+      const loc = locationRef.current
+      if (loc) send({ type: 'presence.enter', page_key: loc.pageKey, sub_location: loc.subLocation })
+    }
+
+    function open() {
+      let sock: WebSocket
+      try {
+        sock = new WebSocket(url)
+      } catch {
+        // Synchronous construction failure (malformed URL, mixed-content
+        // scheme mismatch, …): treat exactly like any other connection
+        // failure — stay on the empty roster and retry on the normal
+        // reconnect cadence, never propagate.
+        setViewers([])
+        scheduleReconnect()
+        return
+      }
+      wsRef.current = sock
+      sock.onopen = () => {
+        // A socket that actually opened means the failure that got us here
+        // is over; start the next backoff series from the bottom.
+        reconnectDelay = RECONNECT_BASE_MS
+        enter()
+        heartbeat = setInterval(
+          () => send({ type: 'presence.heartbeat', idle: idleRef.current }),
+          HEARTBEAT_MS,
+        )
+      }
+      sock.onmessage = (e) => {
+        try {
+          const msg = JSON.parse(e.data)
+          if (msg.event !== 'presence.roster') return
+          // Drop rosters for a page we have already navigated away from —
+          // an in-flight broadcast can land after the re-key.
+          if (msg.data?.page_key !== locationRef.current?.pageKey) return
+          setViewers(
+            (msg.data.viewers ?? []).map((v: Record<string, unknown>) => ({
+              email: String(v.email ?? ''),
+              name: String(v.name ?? ''),
+              subLocation: String(v.sub_location ?? ''),
+              idle: Boolean(v.idle),
+              self: Boolean(v.self),
+            })),
+          )
+        } catch {
+          // Malformed frame: ignore. Never surface.
+        }
+      }
+      sock.onclose = () => {
+        if (wsRef.current === sock) wsRef.current = null
+        if (heartbeat) clearInterval(heartbeat)
+        setViewers([])
+        scheduleReconnect()
+      }
+    }
+    open()
+
+    return () => {
+      closedByCleanup = true
+      if (reconnectTimer) clearTimeout(reconnectTimer)
+      if (heartbeat) clearInterval(heartbeat)
+      wsRef.current?.close()
+      wsRef.current = null
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [url, location === null])
+
+  // Re-key on navigation. Deps are the primitive fields, not `location`
+  // itself — callers (e.g. pageKeyFor) may return a fresh object each
+  // render, and keying on identity would re-send presence.enter on every
+  // render instead of only on an actual location change.
+  useEffect(() => {
+    // Clear FIRST, unconditionally. If the socket is not open yet the old
+    // page's avatars are already wrong — leaving them up until a roster for
+    // the new page arrives (which, on a dead socket, may be never) shows
+    // strangers as viewing the page you just navigated to.
+    setViewers([])
+    const ws = wsRef.current
+    if (!location || !ws || ws.readyState !== WebSocket.OPEN) return
+    ws.send(
+      JSON.stringify({
+        type: 'presence.enter',
+        page_key: location.pageKey,
+        sub_location: location.subLocation,
+      }),
+    )
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [location?.pageKey, location?.subLocation])
+
+  // Idle tracking: hidden for longer than IDLE_AFTER_MS. Reports an
+  // observable fact (the tab is not frontmost), never an attention claim.
+  useEffect(() => {
+    let timer: ReturnType<typeof setTimeout> | null = null
+    const flush = () => {
+      const ws = wsRef.current
+      if (ws && ws.readyState === WebSocket.OPEN) {
+        ws.send(JSON.stringify({ type: 'presence.heartbeat', idle: idleRef.current }))
+      }
+    }
+    const onVisibility = () => {
+      if (document.hidden) {
+        timer = setTimeout(() => {
+          idleRef.current = true
+          flush()
+        }, IDLE_AFTER_MS)
+      } else {
+        if (timer) clearTimeout(timer)
+        if (idleRef.current) {
+          idleRef.current = false
+          flush()
+        }
+      }
+    }
+    document.addEventListener('visibilitychange', onVisibility)
+    return () => {
+      if (timer) clearTimeout(timer)
+      document.removeEventListener('visibilitychange', onVisibility)
+    }
+  }, [])
+
+  return { viewers }
+}