canopy-ui 0.6.1 → 0.6.2

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "canopy-ui",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "type": "module",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/jjackson/canopy-web.git",
+    "url": "git+https://github.com/dimagi-internal/canopy-web.git",
     "directory": "frontend/packages/canopy-ui"
   },
   "exports": {
@@ -12,7 +12,6 @@
     "./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",
@@ -43,7 +42,5 @@
   "devDependencies": {
     "sonner": "^2.0.7"
   },
-  "files": [
-    "src"
-  ]
+  "files": ["src"]
 }

package/src/chat/protocol.ts

@@ -64,8 +64,13 @@ export interface SessionState {
   messages: Message[];
   /** Live agent activity, from the runner's turn-boundary hooks. Undefined when
    *  no hook has reported yet — the caller then falls back to the server's
-   *  coarser `running` flag. */
-  activity?: "working" | "idle";
+   *  coarser `running` flag.
+   *
+   *  "blocked" means the agent wants a human: a permission prompt, or an idle
+   *  wait for input. It is deliberately coarse — a hook observer cannot tell
+   *  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";
   active_draft: Draft | null;
   participants: Participant[];
   presence_user_ids: number[];
@@ -91,7 +96,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" } }
+  | { event: "session.activity"; data: { state: "working" | "idle" | "blocked" } }
   // 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

@@ -539,3 +539,48 @@ describe("sessionReducer — a web send arriving twice", () => {
     expect(next.messages).toHaveLength(2)
   })
 })
+
+describe("blocked — the agent is waiting on YOU", () => {
+  it("renders as its own state, not as working", () => {
+    const state = sessionReducer(makeState(), {
+      event: "session.activity",
+      data: { state: "blocked" },
+    });
+    expect(state.activity).toBe("blocked");
+  });
+
+  it("clears once the agent produces a row again", () => {
+    // Notification fires on the way INTO a wait and nothing fires on the way
+    // out — approving a permission prompt emits no hook at all. A row is the
+    // only proof the wait ended, so without this the chip says "needs you" for
+    // the rest of the turn, long after you answered.
+    const blocked = sessionReducer(makeState(), {
+      event: "session.activity",
+      data: { state: "blocked" },
+    });
+    const after = sessionReducer(blocked, {
+      event: "chat.tool_use",
+      data: {
+        parent_message_id: null,
+        tool_message_id: "m1",
+        turn_index: 3,
+        block: { id: "toolu_1", name: "Bash" },
+      },
+    });
+    expect(after.activity).toBe("working");
+  });
+
+  it("is not cleared by traffic that proves nothing about the agent", () => {
+    // A teammate typing, or presence churn, says nothing about whether the
+    // agent is still waiting for an answer.
+    const blocked = sessionReducer(makeState(), {
+      event: "session.activity",
+      data: { state: "blocked" },
+    });
+    const after = sessionReducer(blocked, {
+      event: "presence.joined",
+      data: { user_id: 2, display_name: "Someone" },
+    });
+    expect(after.activity).toBe("blocked");
+  });
+});

package/src/chat/sessionReducer.ts

@@ -13,7 +13,24 @@ import type { Draft, Message, SessionState, WsEvent } from "./protocol";
 // `draft.committed` carries only `user_message_id` (no assistant id to
 // pre-insert), so the assistant row is created lazily when its first stream
 // frame arrives.
+/** Frames that prove the agent is producing again.
+ *
+ *  `Notification` fires on the way IN to a wait and NOTHING fires on the way
+ *  out — approving a permission prompt emits no hook at all. So without this,
+ *  a session shows "needs you" for the rest of the turn, long after you
+ *  answered. Any row the agent emits afterwards is the proof the hook cannot
+ *  give. */
+const UNBLOCKING_FRAMES = new Set([
+  "chat.stream_start",
+  "chat.delta",
+  "chat.tool_use",
+  "chat.tool_result",
+]);
+
 export function sessionReducer(prev: SessionState, frame: WsEvent): SessionState {
+  if (prev.activity === "blocked" && UNBLOCKING_FRAMES.has(frame.event)) {
+    prev = { ...prev, activity: "working" };
+  }
   switch (frame.event) {
     case "session.state":
       return frame.data;

package/src/presence/PresenceBadge.test.tsx

@@ -1,84 +0,0 @@
-// @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

@@ -1,111 +0,0 @@
-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

@@ -1,42 +0,0 @@
-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

@@ -1,36 +0,0 @@
-// 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

@@ -1,4 +0,0 @@
-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

@@ -1,53 +0,0 @@
-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

@@ -1,37 +0,0 @@
-/** 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

@@ -1,199 +0,0 @@
-// @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

@@ -1,188 +0,0 @@
-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 }
-}