canopy-ui 0.4.0 → 0.6.1

package/src/chat/sessionReducer.ts

@@ -50,6 +50,66 @@ export function sessionReducer(prev: SessionState, frame: WsEvent): SessionState
       return { ...prev, messages: [...prev.messages, assistant] };
     }
 
+    case "session.activity":
+      return { ...prev, activity: frame.data.state };
+
+    case "chat.user_message": {
+      // Someone typed into emdash, OR into this page. Both reach here, and that
+      // is why matching on turn_index alone is not enough: a web send writes its
+      // row at a DENSE index (services._next_index), then the agent reads the
+      // message and the transcript re-ships the same text at a COMPOSITE ordinal
+      // (record * BLOCK_STRIDE + block). Same words, two different indices, two
+      // different ids — so the upsert missed and the message rendered twice
+      // live, while a reload showed it once (get_or_create dedupes server-side).
+      //
+      // Falling back to matching identical text on a recent user row closes it.
+      // Deliberately narrow: same role, same text, and only against the tail, so
+      // a genuine repeat of a short message ("yes") sent much later still lands
+      // as its own row.
+      const RECENT_USER_ROWS = 6;
+      const sameText = (m: Message) =>
+        m.role === "user" &&
+        m.plaintext.trim() !== "" &&
+        m.plaintext.trim() === frame.data.plaintext.trim();
+      const recentUsers = prev.messages.filter((m) => m.role === "user").slice(-RECENT_USER_ROWS);
+      const existing =
+        prev.messages.find(
+          (m) => m.id === frame.data.message_id ||
+            (m.role === "user" && m.turn_index === frame.data.turn_index),
+        ) ?? recentUsers.find(sameText);
+      if (existing) {
+        return {
+          ...prev,
+          messages: prev.messages.map((m) =>
+            m === existing
+              ? {
+                  ...m,
+                  id: frame.data.message_id,
+                  // Take the incoming ordinal: the transcript's composite index
+                  // is the durable one, so the row sorts where a reload puts it.
+                  turn_index: frame.data.turn_index,
+                  plaintext: frame.data.plaintext,
+                }
+              : m,
+          ),
+        };
+      }
+      const nowIso = new Date().toISOString();
+      const user: Message = {
+        id: frame.data.message_id,
+        turn_index: frame.data.turn_index,
+        role: "user",
+        content: { text: frame.data.plaintext },
+        plaintext: frame.data.plaintext,
+        status: "complete",
+        error_detail: null,
+        started_at: null,
+        completed_at: null,
+        created_at: nowIso,
+      };
+      return { ...prev, messages: [...prev.messages, user] };
+    }
+
     case "chat.delta":
       return {
         ...prev,
@@ -106,10 +166,73 @@ export function sessionReducer(prev: SessionState, frame: WsEvent): SessionState
       };
 
     case "chat.tool_use":
-    case "chat.tool_result":
-      // Tool rows are their own Message rows on the server. A full
-      // refresh picks them up; for now, don't duplicate bookkeeping here.
-      return prev;
+    case "chat.tool_result": {
+      // Tool rows are real Message rows on the server; these frames are the
+      // same row arriving live. Upsert by id so a re-delivery (reconnect
+      // catch-up, a retried post) updates in place instead of doubling the
+      // row — and so a tool_result that lands twice can't orphan its pair.
+      const role = frame.event === "chat.tool_use" ? "tool_use" : "tool_result";
+      const block = frame.data.block ?? {};
+      const plaintext = typeof block.text === "string" ? block.text : "";
+      const id = frame.data.tool_message_id;
+      // Reconcile on the CORRELATION key, not the message id. The same tool call
+      // arrives twice by design: once live from a hook (no ordinal, id `seq:-1`)
+      // and once durably from the transcript (ordinal-keyed, a real id). They
+      // share only `tool_use_id` / `id` in content, so matching on that is what
+      // makes the live row a placeholder the durable row REPLACES rather than a
+      // duplicate that sits beside it forever.
+      const correlation =
+        role === "tool_use"
+          ? (block.id as string | undefined)
+          : (block.tool_use_id as string | undefined);
+      const existing = prev.messages.find(
+        (m) =>
+          m.id === id ||
+          (m.role === role &&
+            correlation !== undefined &&
+            correlation !== "" &&
+            (m.content as Record<string, unknown>)?.[
+              role === "tool_use" ? "id" : "tool_use_id"
+            ] === correlation),
+      );
+      if (existing) {
+        // Adopt the incoming id and ordinal: a durable row superseding a live
+        // placeholder must take over its identity, or the next update keys on a
+        // `seq:-1` that no longer means anything.
+        return {
+          ...prev,
+          messages: prev.messages.map((m) =>
+            m === existing
+              ? {
+                  ...m,
+                  id,
+                  turn_index: frame.data.turn_index ?? m.turn_index,
+                  content: block,
+                  plaintext,
+                }
+              : m,
+          ),
+        };
+      }
+      const nowIso = new Date().toISOString();
+      const message: Message = {
+        id,
+        // Fall back to appending after the newest row when the server didn't
+        // send an ordinal — order still holds, since frames arrive in order.
+        turn_index:
+          frame.data.turn_index ??
+          (prev.messages[prev.messages.length - 1]?.turn_index ?? 0) + 1,
+        role,
+        content: block,
+        plaintext,
+        status: block.is_error === true ? "error" : "complete",
+        error_detail: null,
+        started_at: nowIso,
+        completed_at: nowIso,
+        created_at: nowIso,
+      };
+      return { ...prev, messages: [...prev.messages, message] };
+    }
 
     case "draft.updated": {
       const incoming = frame.data as Draft;

package/src/chat/useSessionSocket.ts

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 
 import type { Message, SessionState, WsEvent } from "./protocol";
+import { shouldSyncDraftLive } from "./drafts";
 import { prependHistory } from "./history";
 import { sessionReducer } from "./sessionReducer";
 
@@ -36,8 +37,13 @@ export interface UseSessionSocketOptions {
 export interface UseSessionSocketResult {
   state: SessionState;
   connected: boolean;
+  /** A send is outstanding with no reply yet — the turn is QUEUED, waiting for
+   *  a runner. Nothing in `state` can express this (there is no assistant
+   *  message until the first token), and it is what keeps Stop reachable while
+   *  a turn is stuck. */
+  awaitingReply: boolean;
   sendChat: () => void;
-  stopChat: (messageId: string) => void;
+  stopChat: (messageId: string | null) => void;
   updateDraft: (body: string) => void;
   takeOverDraft: () => void;
   discardDraft: () => void;
@@ -53,6 +59,11 @@ export function useSessionSocket({
   const [state, setState] = useState<SessionState>(INITIAL_STATE);
   const [connected, setConnected] = useState(false);
   const [lastError, setLastError] = useState<string | null>(null);
+  // A send has gone out but no reply has begun — i.e. the turn is QUEUED,
+  // waiting for a runner to claim it. There is no assistant message during
+  // this window, so nothing else in the state can express it, and without it
+  // the Stop control is unreachable exactly when the turn is stuck.
+  const [awaitingReply, setAwaitingReply] = useState(false);
 
   const socketRef = useRef<WebSocket | null>(null);
   const stateRef = useRef<SessionState>(INITIAL_STATE);
@@ -90,6 +101,17 @@ export function useSessionSocket({
   }, []);
 
   const applyEvent = useCallback((frame: WsEvent) => {
+    // Any of these means the queued window is over: the reply began, ended,
+    // was cancelled, or the send failed outright.
+    if (
+      frame.event === "chat.stream_start" ||
+      frame.event === "chat.stream_complete" ||
+      frame.event === "chat.stream_error" ||
+      frame.event === "chat.stream_cancelled" ||
+      frame.event === "session.error"
+    ) {
+      setAwaitingReply(false);
+    }
     // Side-effect events: handle BEFORE setState so React strict-mode's
     // double-invocation of the updater doesn't double-fire the effect.
     if (frame.event === "session.title_updated") {
@@ -183,27 +205,36 @@ export function useSessionSocket({
   }, [connect]);
 
   const sendChat = useCallback(() => {
-    // Flush any pending debounced update first so the committed draft
-    // carries the latest local body.
+    // Flush the local body BEFORE committing. `chat.send` commits the SERVER's
+    // draft, so this is the moment the body has to exist there — and when
+    // live sync is off (single-player) it is the ONLY time it is sent.
+    //
+    // Unconditional on purpose: keying this off a pending debounce timer meant
+    // nothing was flushed when there was no timer, which is now the normal case.
     if (draftDebounceRef.current != null) {
       window.clearTimeout(draftDebounceRef.current);
       draftDebounceRef.current = null;
-      if (pendingDraftBodyRef.current != null && stateRef.current.active_draft) {
-        send({
-          action: "draft.update",
-          data: {
-            version: stateRef.current.active_draft.version,
-            body: pendingDraftBodyRef.current,
-          },
-        });
-      }
+    }
+    if (pendingDraftBodyRef.current != null && stateRef.current.active_draft) {
+      send({
+        action: "draft.update",
+        data: {
+          version: stateRef.current.active_draft.version,
+          body: pendingDraftBodyRef.current,
+        },
+      });
     }
     pendingDraftBodyRef.current = null;
+    setAwaitingReply(true);
     send({ action: "chat.send", data: {} });
   }, [send]);
 
   const stopChat = useCallback(
-    (messageId: string) => {
+    (messageId: string | null) => {
+      // messageId is null when the turn is still queued. The server's
+      // chat.stop cancels every non-terminal turn on the session and only
+      // echoes the id back, so a null one cancels just as effectively.
+      setAwaitingReply(false);
       send({ action: "chat.stop", data: { message_id: messageId } });
     },
     [send],
@@ -218,6 +249,17 @@ export function useSessionSocket({
           : prev,
       );
       pendingDraftBodyRef.current = body;
+      // Alone in the session? Don't mirror keystrokes at all. The body is
+      // flushed once by sendChat, which is the only moment the server actually
+      // needs it. This is what makes single-player typing purely local — no
+      // round trip, no echo, no version to disagree about.
+      if (!shouldSyncDraftLive(stateRef.current.presence_user_ids)) {
+        if (draftDebounceRef.current != null) {
+          window.clearTimeout(draftDebounceRef.current);
+          draftDebounceRef.current = null;
+        }
+        return;
+      }
       if (draftDebounceRef.current != null) {
         window.clearTimeout(draftDebounceRef.current);
       }
@@ -225,8 +267,11 @@ export function useSessionSocket({
         draftDebounceRef.current = null;
         const current = stateRef.current.active_draft;
         const pending = pendingDraftBodyRef.current;
-        pendingDraftBodyRef.current = null;
         if (current != null && pending != null) {
+          // Only consumed once it has actually gone out. Clearing it
+          // unconditionally dropped anything typed before session.state
+          // arrived (no draft yet ⇒ nothing sent, body forgotten).
+          pendingDraftBodyRef.current = null;
           send({
             action: "draft.update",
             data: { version: current.version, body: pending },
@@ -245,6 +290,23 @@ export function useSessionSocket({
     send({ action: "draft.discard", data: {} });
   }, [send]);
 
+  // Someone joining mid-compose must see what is ALREADY typed. Nothing was
+  // mirrored while we were alone, so without this one catch-up flush their view
+  // would sit empty until the next keystroke. Closes the only gap that skipping
+  // live sync opens up.
+  const liveSync = shouldSyncDraftLive(state.presence_user_ids);
+  useEffect(() => {
+    if (!liveSync) return;
+    const pending = pendingDraftBodyRef.current;
+    const current = stateRef.current.active_draft;
+    if (pending == null || current == null) return;
+    pendingDraftBodyRef.current = null;
+    send({
+      action: "draft.update",
+      data: { version: current.version, body: pending },
+    });
+  }, [liveSync, send]);
+
   const prependMessages = useCallback((older: Message[]) => {
     // Apply a REST "Load earlier" page into the live socket state. A later
     // session.state snapshot (e.g. reconnect) resets to the tail — acceptable;
@@ -258,6 +320,7 @@ export function useSessionSocket({
   return {
     state,
     connected,
+    awaitingReply,
     sendChat,
     stopChat,
     updateDraft,

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
+}