canopy-ui 0.12.2 → 0.14.0

package/src/chat/TypingRows.tsx

@@ -0,0 +1,25 @@
+import type { PeerDraft } from "./protocol";
+
+/** Everyone else's box, live — the multiplayer half of the composer. One row
+ *  per person, newest edit last, right above your own box. */
+export function TypingRows({ peers }: { peers: PeerDraft[] }) {
+  if (peers.length === 0) return null;
+  return (
+    <ul className="space-y-1 border-t border-border bg-background px-3 py-2" aria-live="polite">
+      {peers.map((p) =>
+        p.body === "" ? (
+          <li key={p.author.id} data-testid="typing-row" className="flex min-w-0 gap-2 text-xs">
+            <span className="shrink-0 font-medium text-foreground">{p.author.name}</span>
+            <span className="shrink-0 text-muted-foreground">is typing…</span>
+          </li>
+        ) : (
+          <li key={p.author.id} data-testid="typing-row" className="flex min-w-0 gap-2 text-xs">
+            <span className="shrink-0 font-medium text-foreground">{p.author.name}</span>
+            <span className="shrink-0 text-muted-foreground">is typing:</span>
+            <span className="min-w-0 truncate italic text-foreground-secondary">{p.body}</span>
+          </li>
+        ),
+      )}
+    </ul>
+  );
+}

package/src/chat/agui.fixture.json

@@ -62,7 +62,11 @@
       "data": {
         "message_id": "u1",
         "turn_index": 3,
-        "plaintext": "hi there"
+        "plaintext": "hi there",
+        "author": {
+          "name": "Jon",
+          "user_id": 7
+        }
       }
     },
     "agui": [
@@ -70,7 +74,11 @@
         "type": "TEXT_MESSAGE_CHUNK",
         "metadata": {
           "canopy": {
-            "turn_index": 3
+            "turn_index": 3,
+            "author": {
+              "name": "Jon",
+              "user_id": 7
+            }
           }
         },
         "messageId": "u1",
@@ -198,6 +206,33 @@
       }
     ]
   },
+  {
+    "canopy": {
+      "event": "draft.typing",
+      "data": {
+        "author": {
+          "id": 7,
+          "name": "Beth"
+        },
+        "body": "wip",
+        "at": "2026-09-26T12:00:00+00:00"
+      }
+    },
+    "agui": [
+      {
+        "type": "CUSTOM",
+        "name": "canopy.draft.typing",
+        "value": {
+          "author": {
+            "id": 7,
+            "name": "Beth"
+          },
+          "body": "wip",
+          "at": "2026-09-26T12:00:00+00:00"
+        }
+      }
+    ]
+  },
   {
     "canopy": {
       "event": "presence.joined",
@@ -441,6 +476,47 @@
       }
     ]
   },
+  {
+    "canopy": {
+      "event": "session.queued",
+      "data": {
+        "queued": [
+          {
+            "turn_id": "8f2e",
+            "client_id": "c9",
+            "author": {
+              "name": "Jon",
+              "user_id": 7
+            },
+            "text": "from jj",
+            "sent_at": "2026-09-26T12:00:00+00:00",
+            "state": "queued"
+          }
+        ]
+      }
+    },
+    "agui": [
+      {
+        "type": "CUSTOM",
+        "name": "canopy.session.queued",
+        "value": {
+          "queued": [
+            {
+              "turn_id": "8f2e",
+              "client_id": "c9",
+              "author": {
+                "name": "Jon",
+                "user_id": 7
+              },
+              "text": "from jj",
+              "sent_at": "2026-09-26T12:00:00+00:00",
+              "state": "queued"
+            }
+          ]
+        }
+      }
+    ]
+  },
   {
     "canopy": {
       "event": "session.stop",
@@ -614,27 +690,6 @@
       }
     ]
   },
-  {
-    "canopy": {
-      "event": "draft.lock_changed",
-      "data": {
-        "draft_id": "d1",
-        "holder_user_id": 7,
-        "expires_at": "2026-09-18T12:01:00+00:00"
-      }
-    },
-    "agui": [
-      {
-        "type": "CUSTOM",
-        "name": "canopy.draft.lock_changed",
-        "value": {
-          "draft_id": "d1",
-          "holder_user_id": 7,
-          "expires_at": "2026-09-18T12:01:00+00:00"
-        }
-      }
-    ]
-  },
   {
     "canopy": {
       "event": "page.invalidate",

package/src/chat/agui.ts

@@ -27,7 +27,7 @@
  * standard.
  */
 
-import type { SessionMenu, WsEvent } from "./protocol";
+import type { MessageAuthor, SessionMenu, WsEvent } from "./protocol";
 
 /** Where canopy's own fields ride. Mirrors `agui.METADATA_KEY`. */
 export const METADATA_KEY = "canopy";
@@ -117,6 +117,11 @@ export function fromAgui(frame: AguiFrame): WsEvent[] {
             message_id: str(frame.messageId),
             turn_index: num(m.turn_index),
             plaintext: str(frame.delta),
+            // Who typed it — a transcript-sourced session's durable row carries
+            // no user beyond the runner's own login, so this metadata is
+            // canopy's only chance to say (spec 2026-09-26). Absent when the
+            // server sent none (an agent/scheduled/email turn's own send).
+            author: m.author as MessageAuthor | undefined,
           },
         },
       ];

package/src/chat/drafts.test.ts

@@ -1,80 +1,18 @@
-import { afterEach, describe, expect, it, vi } from "vitest"
+import { describe, expect, it } from "vitest"
 
-import type { Draft } from "./protocol"
 import {
   DRAFT_STORAGE_TTL_MS,
-  IDLE_THRESHOLD_MS,
   clearStoredDraft,
   draftStorageKey,
-  isDraftIdle,
-  msUntilDraftIdle,
   readStoredDraft,
+  readStoredTypingVisibility,
   shouldSyncDraftLive,
   writeStoredDraft,
+  writeStoredTypingVisibility,
 } from "./drafts"
 
 const NOW = 1_700_000_000_000
 
-function draftEditedAt(msAgo: number): Draft {
-  return {
-    id: "d1",
-    slot: "next",
-    status: "open",
-    body: "",
-    version: 0,
-    last_editor: 1,
-    last_edit_at: new Date(NOW - msAgo).toISOString(),
-  }
-}
-
-afterEach(() => {
-  vi.useRealTimers()
-})
-
-describe("isDraftIdle", () => {
-  it("treats a null/undefined draft as idle", () => {
-    expect(isDraftIdle(null)).toBe(true)
-    expect(isDraftIdle(undefined)).toBe(true)
-  })
-
-  it("treats a draft with no last_edit_at as idle", () => {
-    const d = { ...draftEditedAt(0), last_edit_at: "" }
-    expect(isDraftIdle(d)).toBe(true)
-  })
-
-  it("is NOT idle immediately after an edit", () => {
-    vi.useFakeTimers()
-    vi.setSystemTime(NOW)
-    // edited 500ms ago — well within the 2s threshold
-    expect(isDraftIdle(draftEditedAt(500))).toBe(false)
-  })
-
-  it("IS idle once more than the threshold has elapsed", () => {
-    vi.useFakeTimers()
-    vi.setSystemTime(NOW)
-    expect(isDraftIdle(draftEditedAt(IDLE_THRESHOLD_MS + 1))).toBe(true)
-  })
-})
-
-describe("msUntilDraftIdle", () => {
-  it("returns 0 for a null draft", () => {
-    expect(msUntilDraftIdle(null)).toBe(0)
-  })
-
-  it("returns the remaining time before the idle transition", () => {
-    vi.useFakeTimers()
-    vi.setSystemTime(NOW)
-    // edited 500ms ago → 1500ms remain
-    expect(msUntilDraftIdle(draftEditedAt(500))).toBe(1500)
-  })
-
-  it("clamps to 0 once past the threshold", () => {
-    vi.useFakeTimers()
-    vi.setSystemTime(NOW)
-    expect(msUntilDraftIdle(draftEditedAt(IDLE_THRESHOLD_MS + 5000))).toBe(0)
-  })
-})
-
 describe("shouldSyncDraftLive", () => {
   it("does not mirror keystrokes when you are alone", () => {
     // The single-player case: a per-keystroke draft.update costs a round trip,
@@ -208,3 +146,43 @@ describe("clearStoredDraft", () => {
     expect(readStoredDraft(s, KEY, NOW)).toBeNull()
   })
 })
+
+// ---------------------------------------------------------------------------
+// Typing-visibility persistence — per browser, not per session.
+// ---------------------------------------------------------------------------
+
+describe("readStoredTypingVisibility / writeStoredTypingVisibility", () => {
+  it("defaults to null when nothing is stored", () => {
+    expect(readStoredTypingVisibility(fakeStorage())).toBeNull()
+  })
+
+  it("round-trips a written mode", () => {
+    const s = fakeStorage()
+    writeStoredTypingVisibility(s, "typing")
+    expect(readStoredTypingVisibility(s)).toBe("typing")
+  })
+
+  it("rejects a value that isn't one of the three modes", () => {
+    const s = fakeStorage({ "canopy.chat.typingVisibility": "loud" })
+    expect(readStoredTypingVisibility(s)).toBeNull()
+  })
+
+  it("is inert without a storage", () => {
+    expect(readStoredTypingVisibility(null)).toBeNull()
+    expect(() => writeStoredTypingVisibility(null, "hidden")).not.toThrow()
+  })
+
+  it("survives a storage that throws", () => {
+    const hostile = {
+      getItem: () => {
+        throw new Error("SecurityError")
+      },
+      setItem: () => {
+        throw new Error("SecurityError")
+      },
+      removeItem: () => {},
+    }
+    expect(readStoredTypingVisibility(hostile)).toBeNull()
+    expect(() => writeStoredTypingVisibility(hostile, "live")).not.toThrow()
+  })
+})

package/src/chat/drafts.ts

@@ -1,11 +1,4 @@
-import type { Draft } from "./protocol";
-
-export const IDLE_THRESHOLD_MS = 2_000;
-
-export function isDraftIdle(draft: Draft | null | undefined): boolean {
-  if (!draft?.last_edit_at) return true;
-  return Date.now() - new Date(draft.last_edit_at).getTime() > IDLE_THRESHOLD_MS;
-}
+import type { TypingVisibility } from "./protocol";
 
 /**
  * Whether keystrokes need to be mirrored to the server AS YOU TYPE.
@@ -25,17 +18,6 @@ export function shouldSyncDraftLive(presenceUserIds: readonly number[]): boolean
   return presenceUserIds.length > 1;
 }
 
-/**
- * Milliseconds until the draft lock becomes idle. Returns 0 if already
- * idle. Use this to schedule a timer that forces a re-render at the
- * idle transition point.
- */
-export function msUntilDraftIdle(draft: Draft | null | undefined): number {
-  if (!draft?.last_edit_at) return 0;
-  const elapsed = Date.now() - new Date(draft.last_edit_at).getTime();
-  return Math.max(0, IDLE_THRESHOLD_MS - elapsed);
-}
-
 // ---------------------------------------------------------------------------
 // Composer persistence — surviving a navigation the server never hears about.
 //
@@ -169,3 +151,43 @@ function remove(storage: DraftStorage, key: string): void {
     // same as above — best effort
   }
 }
+
+// ---------------------------------------------------------------------------
+// Typing-visibility persistence — per BROWSER, not per session: it is a
+// standing choice about how you type, not something that resets when you
+// switch chats. One key, not namespaced by `persistKey` like a draft body.
+// ---------------------------------------------------------------------------
+
+// Exported so a listener can recognise a `storage` event for this key coming
+// from another tab (see useSessionSocket's cross-tab sync).
+export const TYPING_VISIBILITY_STORAGE_KEY = "canopy.chat.typingVisibility";
+
+const VALID_VISIBILITIES: readonly TypingVisibility[] = ["live", "typing", "hidden"];
+
+/** The persisted mode, or null when there is nothing stored or it is
+ *  unreadable/invalid — same try/catch-safe shape as `readStoredDraft`. */
+export function readStoredTypingVisibility(storage: DraftStorage | null): TypingVisibility | null {
+  if (!storage) return null;
+  let raw: string | null = null;
+  try {
+    raw = storage.getItem(TYPING_VISIBILITY_STORAGE_KEY);
+  } catch {
+    return null;
+  }
+  return (VALID_VISIBILITIES as readonly string[]).includes(raw ?? "")
+    ? (raw as TypingVisibility)
+    : null;
+}
+
+export function writeStoredTypingVisibility(
+  storage: DraftStorage | null,
+  visibility: TypingVisibility,
+): void {
+  if (!storage) return;
+  try {
+    storage.setItem(TYPING_VISIBILITY_STORAGE_KEY, visibility);
+  } catch {
+    // Quota exceeded, or storage disabled mid-session — best effort, same as
+    // `writeStoredDraft`.
+  }
+}

package/src/chat/identity.ts

@@ -0,0 +1,37 @@
+import type { Message, MessageAuthor } from "./protocol";
+
+/** Is this line the viewer's own? A viewer is a canopy user (`currentUserId`)
+ *  OR a contact — a widget visitor, who has no user id and is named by the
+ *  snapshot's `current_contact_id` instead. Comparing user ids alone made every
+ *  line a contact wrote render as someone else's, under their own name. */
+export function isMine(
+  author: MessageAuthor | null | undefined,
+  currentUserId: number | null | undefined,
+  currentContactId: number | null | undefined,
+): boolean {
+  if (!author) return false;
+  return (
+    (author.user_id != null && author.user_id === currentUserId) ||
+    (author.contact_id != null && author.contact_id === currentContactId)
+  );
+}
+
+/** The same person, or no way to tell (either side unauthored). */
+export function sameAuthor(
+  a: MessageAuthor | null | undefined,
+  b: MessageAuthor | null | undefined,
+): boolean {
+  if (!a || !b) return true;
+  if (a.user_id != null || b.user_id != null) return a.user_id === b.user_id;
+  return a.contact_id === b.contact_id;
+}
+
+/** A user row still waiting for the durable line it will become: an optimistic
+ *  send (`local:`), a receipted transcript-sourced send (`transient:` — the
+ *  server wrote no row, the transcript will), or one still pending/failed. */
+export function isUnconfirmed(m: Message): boolean {
+  return (
+    m.status === "pending" || m.status === "error" ||
+    m.id.startsWith("local:") || m.id.startsWith("transient:")
+  );
+}

package/src/chat/index.ts

@@ -7,13 +7,17 @@
 // Protocol types
 export type {
   Message,
+  MessageAuthor,
   MessageRole,
   MessageStatus,
   Draft,
+  PeerDraft,
+  QueuedMessage,
   Participant,
   SessionMenu,
   SessionState,
   TurnStatus,
+  TypingVisibility,
   WsAction,
   WsEvent,
 } from "./protocol";
@@ -29,6 +33,7 @@ export { prependHistory } from "./history";
 // Hooks
 export {
   useSessionSocket,
+  newClientId,
   type UseSessionSocketOptions,
   type UseSessionSocketResult,
 } from "./useSessionSocket";
@@ -45,9 +50,6 @@ export {
   type TurnNotice,
 } from "./turnStatus";
 
-// Draft idle helpers
-export { IDLE_THRESHOLD_MS, isDraftIdle, msUntilDraftIdle } from "./drafts";
-
 // Composer persistence (survives unmount / tab close)
 export {
   DRAFT_STORAGE_TTL_MS,
@@ -56,6 +58,8 @@ export {
   draftStorageKey,
   readStoredDraft,
   writeStoredDraft,
+  readStoredTypingVisibility,
+  writeStoredTypingVisibility,
   type DraftStorage,
 } from "./drafts";
 
@@ -77,6 +81,9 @@ export { MessageItem, type RenderMarkdown } from "./MessageItem";
 export { ToolCallPair } from "./ToolCallPair";
 export { SendBox, type PendingAttachment } from "./SendBox";
 export { PresenceChips } from "./PresenceChips";
+export { TypingRows } from "./TypingRows";
+export { QueuedRows } from "./QueuedRows";
+export { isMine } from "./identity";
 export { ConnectionStatus } from "./ConnectionStatus";
 export {
   PlacementBanner,

package/src/chat/protocol.ts

@@ -26,6 +26,14 @@ export type MessageRole =
 // Session + message shapes (the `session.state` snapshot payload)
 // ---------------------------------------------------------------------------
 
+/** Who sent a human line — a canopy user or a contact, never both.
+ * Mirrors `apps/canopy_sessions/authorship.py::parse`'s return shape. */
+export interface MessageAuthor {
+  name: string;
+  user_id?: number;
+  contact_id?: number;
+}
+
 export interface Message {
   /** String PK (canopy sends `str(msg.pk)`), or a synthetic stream id. */
   id: string;
@@ -38,8 +46,17 @@ export interface Message {
   started_at: string | null;
   completed_at: string | null;
   created_at: string;
+  /** Who typed this line — a canopy user or a contact. Absent/null on rows
+   *  from before authorship was tracked, or on the agent's own messages. */
+  author?: MessageAuthor | null;
 }
 
+/** How much of an in-progress message its author lets OTHERS see: the words
+ *  live as typed (`live`, today's behaviour), just the fact of typing
+ *  (`typing`), or nothing at all until it's sent (`hidden`). Chosen per
+ *  person, per browser (persisted in localStorage) — see useSessionSocket. */
+export type TypingVisibility = "live" | "typing" | "hidden";
+
 export interface Draft {
   /** String PK (canopy sends `str(draft.pk)`). */
   id: string;
@@ -49,6 +66,42 @@ export interface Draft {
   version: number;
   last_editor: number;
   last_edit_at: string;
+  /** The draft's OWNER — distinct from `last_editor`, which is whoever most
+   *  recently typed in it. Since a `draft.updated` frame now only ever
+   *  reaches its author's own sockets, this is the reliable field to compare
+   *  against `current_user_id` for echo-suppression; `last_editor` is kept
+   *  for servers that don't send it yet. */
+  author_id?: number;
+  /** This author's chosen mode. Absent on an older server. */
+  visibility?: TypingVisibility;
+}
+
+/** A peer's live, uncommitted draft — everyone else's box, broadcast as they
+ *  type. Keyed by author, never by draft id: a client only ever needs "what
+ *  is this person typing right now", and an empty `body` means they sent,
+ *  discarded, or cleared it — OR its author is in `typing`/`hidden` mode,
+ *  where the server withholds the words but still says whether they're
+ *  typing via `typing`. */
+export interface PeerDraft {
+  author: { id: number; name: string };
+  body: string;
+  at: string | null;
+  /** Whether this person is actively typing right now — the one fact the
+   *  server still tells peers when `body` is withheld. Absent from an older
+   *  server, where a non-empty `body` was the only signal. */
+  typing?: boolean;
+}
+
+/** A send that landed on the server but hasn't reached the agent's turn yet
+ *  — the server-derived queue, replacing whatever a client used to infer
+ *  locally from its own optimistic sends. */
+export interface QueuedMessage {
+  turn_id: string;
+  client_id: string;
+  author: MessageAuthor | null;
+  text: string;
+  sent_at: string;
+  state: "queued" | "delivering";
 }
 
 export interface Participant {
@@ -197,10 +250,23 @@ export interface SessionState {
    *  changed. Null/undefined when nothing has been asked on this session yet —
    *  which is distinct from "finished", and must stay distinct. */
   turn_status?: TurnStatus | null;
+  /** The CALLER's own draft — null for a viewer, who has nothing to draft. */
   active_draft: Draft | null;
+  /** Everyone else's live drafts, server-derived. Absent on an older server. */
+  peer_drafts?: PeerDraft[];
+  /** Sends that landed but haven't reached the agent's turn yet, server-
+   *  derived and replaced wholesale on every frame — like `turn_status`, a
+   *  client that just connected has no correct prior to merge a delta into.
+   *  Absent on an older server. */
+  queued?: QueuedMessage[];
   participants: Participant[];
   presence_user_ids: number[];
-  current_user_id: number;
+  /** The connecting user — null for a contact (a widget visitor), who has no
+   *  user id. */
+  current_user_id: number | null;
+  /** The connecting CONTACT, when the viewer is one; null for a member.
+   *  Absent on an older server. */
+  current_contact_id?: number | null;
 }
 
 // ---------------------------------------------------------------------------
@@ -211,6 +277,14 @@ export type WsAction =
   | { action: "chat.send"; data: Record<string, never> }
   | { action: "chat.stop"; data: { message_id: string } }
   | { action: "draft.update"; data: { version: number; body: string } }
+  // The mode is its OWN idempotent frame, not a field on the version-guarded
+  // `draft.update` above — applied unconditionally server-side (no version
+  // check), so it can never race a keystroke and never itself causes a
+  // `draft_version_mismatch`. A `draft.update` carrying a stray `visibility`
+  // (an in-flight older 0.14 client) is simply ignored server-side.
+  | { action: "draft.set_visibility"; data: { visibility: TypingVisibility } }
+  /** @deprecated accepted and ignored by the server since 0.13 — every editor
+   *  gets their own draft now, so there is no lock left to take over. */
   | { action: "draft.take_over"; data: Record<string, never> }
   | { action: "draft.discard"; data: Record<string, never> }
   | { action: "presence.heartbeat"; data: Record<string, never> };
@@ -238,8 +312,17 @@ export type WsEvent =
   // offline box, unroutable) are ones activity has no way to spell.
   | { event: "session.turn_status"; data: { status: TurnStatus | null } }
   // A human typed into emdash rather than into this page. No client echoed it,
-  // so this is the only way it reaches the browser before a reload.
-  | { event: "chat.user_message"; data: { message_id: string; turn_index: number; plaintext: string } }
+  // so this is the only way it reaches the browser before a reload. `author`
+  // rides here for the same reason it rides the queued list (spec 2026-09-26):
+  // a transcript-sourced session's durable row carries no user beyond the
+  // runner's own login, so this is canopy's only chance to say who typed it.
+  // `client_id` is likewise the only way an HTTP send's OPTIMISTIC row (built
+  // locally by `noteLocalSend`, never a real server frame) can carry the same
+  // id its REST body sent — without it `QueuedRows.hideClientIds` cannot match
+  // this row to the server's queued-turn projection, and a contact's or
+  // widget's own send rendered twice: once as their bubble, once as a "queued"
+  // placeholder for the same send.
+  | { event: "chat.user_message"; data: { message_id: string; turn_index: number; plaintext: string; author?: MessageAuthor | null; client_id?: string } }
   | { event: "chat.delta"; data: { message_id: string; text: string } }
   // `turn_index` is the row's transcript ordinal — the same key the persisted
   // Message carries, so a live tool row sorts into exactly the position it will
@@ -250,7 +333,13 @@ export type WsEvent =
   | { event: "chat.stream_error"; data: { message_id: string; detail: string } }
   | { event: "chat.stream_cancelled"; data: { message_id: string | null; partial_len: number } }
   | { event: "draft.updated"; data: Draft }
-  | { event: "draft.lock_changed"; data: { draft_id: string; holder_user_id: number | null; expires_at: number | null } }
+  // Someone else's box, live — keyed by author, not draft id, because a peer's
+  // draft is never addressable by this client and never needs to be: only
+  // "what are they typing right now" does. An empty `body` means they sent,
+  // discarded, or cleared it. Replaces `draft.lock_changed`, which existed
+  // only because a session had one shared next-draft to fight over; now
+  // everyone has their own, so there is no lock left to report.
+  | { event: "draft.typing"; data: PeerDraft }
   // `client_id` is the sender's receipt for a send that carried one (see
   // useSessionSocket.sendChat); absent from older servers.
   | { event: "draft.committed"; data: { draft_id: string; user_message_id: string; client_id?: string } }
@@ -270,4 +359,7 @@ export type WsEvent =
         display_name?: string;
       };
     }
-  | { event: "presence.left"; data: { user_id: number } };
+  | { event: "presence.left"; data: { user_id: number } }
+  // The whole queue, wholesale, like `session.turn_status` — a client that
+  // just connected has no correct prior to merge a delta into.
+  | { event: "session.queued"; data: { queued: QueuedMessage[] } };