canopy-ui 0.13.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canopy-ui",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "type": "module",
   "repository": {
     "type": "git",

package/src/chat/ChatPanel.multiplayer.test.tsx

@@ -38,6 +38,13 @@ describe("multiplayer composer", () => {
     expect(screen.queryByTestId("coedit-banner")).toBeNull();
   });
 
+  it("shows 'is typing…' with no words when a teammate withholds them", () => {
+    render(<ChatPanel {...props} state={state({ peer_drafts: [{ author: { id: 2, name: "Bo B" }, body: "", at: null, typing: true }] })} />);
+    const row = screen.getByTestId("typing-row");
+    expect(row.textContent).toContain("Bo B");
+    expect(row.textContent).toContain("is typing…");
+  });
+
   it("send stays available while the agent is replying", () => {
     const streaming = { id: "a1", turn_index: 2, role: "assistant" as const, content: {}, plaintext: "working", status: "streaming" as const, error_detail: null, started_at: null, completed_at: null, created_at: "" };
     render(<ChatPanel {...props} state={state({ messages: [streaming] })} />);

package/src/chat/ChatPanel.tsx

@@ -1,6 +1,6 @@
 import { useMemo, type ReactNode } from "react";
 
-import type { SessionState } from "./protocol";
+import type { SessionState, TypingVisibility } from "./protocol";
 import type { RenderMarkdown } from "./MessageItem";
 import { ConnectionStatus } from "./ConnectionStatus";
 import { MessageList } from "./MessageList";
@@ -49,6 +49,11 @@ export interface ChatPanelProps {
   draftPersistKey?: string;
   /** Storage backing `draftPersistKey`; defaults to localStorage. */
   draftStorage?: DraftStorage | null;
+  /** This person's chosen typing-visibility mode, and its setter. Both
+   *  optional; the control renders only when both are given (see SendBox) —
+   *  a host with no draft sync (a contact) passes neither. */
+  typingVisibility?: TypingVisibility;
+  onTypingVisibilityChange?: (visibility: TypingVisibility) => void;
 }
 
 /**
@@ -76,6 +81,8 @@ export function ChatPanel({
   historySlot,
   draftPersistKey,
   draftStorage,
+  typingVisibility,
+  onTypingVisibilityChange,
 }: ChatPanelProps) {
   // `onDiscard` is part of the public surface (co-edit teardown) even though
   // the default composer doesn't render a discard button. Referenced to keep
@@ -254,6 +261,8 @@ export function ChatPanel({
         onRemoveAttachment={onRemoveAttachment}
         persistKey={draftPersistKey}
         storage={draftStorage}
+        typingVisibility={typingVisibility}
+        onTypingVisibilityChange={onTypingVisibilityChange}
       />
     </div>
   );

package/src/chat/SendBox.test.tsx

@@ -582,3 +582,30 @@ describe("SendBox — draft persistence across unmount", () => {
     expect(box().value).toBe("still typeable");
   });
 });
+
+describe("SendBox — typing visibility control", () => {
+  it("is absent when neither prop is given", () => {
+    setup();
+    expect(screen.queryByTestId("typing-visibility")).toBeNull();
+  });
+
+  it("is absent when only the value is given, with no handler", () => {
+    setup({ typingVisibility: "live" });
+    expect(screen.queryByTestId("typing-visibility")).toBeNull();
+  });
+
+  it("shows the control when both props are given, and calls the handler on selection", () => {
+    const onChange = vi.fn();
+    setup({ typingVisibility: "live", onTypingVisibilityChange: onChange });
+    const control = screen.getByTestId("typing-visibility") as HTMLSelectElement;
+    expect(control.value).toBe("live");
+    fireEvent.change(control, { target: { value: "typing" } });
+    expect(onChange).toHaveBeenCalledWith("typing");
+  });
+
+  it("has a tooltip explaining what it does", () => {
+    setup({ typingVisibility: "hidden", onTypingVisibilityChange: vi.fn() });
+    const control = screen.getByTestId("typing-visibility") as HTMLSelectElement;
+    expect(control.title.length).toBeGreaterThan(0);
+  });
+});

package/src/chat/SendBox.tsx

@@ -7,7 +7,7 @@ import {
 } from "react";
 import type React from "react";
 
-import type { Draft } from "./protocol";
+import type { Draft, TypingVisibility } from "./protocol";
 import {
   clearStoredDraft,
   defaultDraftStorage,
@@ -63,6 +63,14 @@ interface Props {
   /** Storage backing `persistKey`. Defaults to localStorage; inject a fake in
    *  tests, or sessionStorage for per-tab drafts. */
   storage?: DraftStorage | null;
+  /** This person's choice of how much of THEIR OWN in-progress message peers
+   *  get to see: the words live (`live`), just the fact of typing (`typing`),
+   *  or nothing until send (`hidden`). Both this and `onTypingVisibilityChange`
+   *  are optional, and the control renders only when BOTH are given — a host
+   *  that passes neither (a contact's socket, which has no draft sync) gets no
+   *  control at all rather than a dead one. */
+  typingVisibility?: TypingVisibility;
+  onTypingVisibilityChange?: (visibility: TypingVisibility) => void;
 }
 
 export function SendBox({
@@ -81,6 +89,8 @@ export function SendBox({
   onRemoveAttachment,
   persistKey,
   storage,
+  typingVisibility,
+  onTypingVisibilityChange,
 }: Props) {
   const textareaRef = useRef<HTMLTextAreaElement>(null);
 
@@ -343,6 +353,33 @@ export function SendBox({
               {stopState === "requested" ? "stopping…" : "stop"}
             </Button>
           ) : null}
+          {typingVisibility != null && onTypingVisibilityChange != null && (
+            <label className="flex items-center gap-1 text-xs text-muted-foreground">
+              <span className="hidden sm:inline">Others see:</span>
+              <select
+                data-testid="typing-visibility"
+                value={typingVisibility}
+                title="Choose what others see of your message while you're still typing it."
+                onChange={(e) =>
+                  onTypingVisibilityChange(e.target.value as TypingVisibility)
+                }
+                className={[
+                  // bg-background, not bg-transparent: a native <select>'s
+                  // OPTION list paints on the OS's own background, and a
+                  // transparent trigger left the closed control's text
+                  // sitting on whatever was behind it — unreadable in dark
+                  // mode, where that was the page's own dark-on-dark text.
+                  "rounded-md border border-input bg-background px-1.5 py-1 text-xs",
+                  "text-foreground focus-visible:outline-none focus-visible:ring-1",
+                  "focus-visible:ring-ring",
+                ].join(" ")}
+              >
+                <option value="live">My text</option>
+                <option value="typing">Typing…</option>
+                <option value="hidden">Nothing</option>
+              </select>
+            </label>
+          )}
           <Button
             type="button"
             size="sm"

package/src/chat/TypingRows.test.tsx

@@ -0,0 +1,33 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { TypingRows } from "./TypingRows";
+import type { PeerDraft } from "./protocol";
+
+afterEach(cleanup);
+
+describe("TypingRows", () => {
+  it("renders nothing when nobody is typing", () => {
+    const { container } = render(<TypingRows peers={[]} />);
+    expect(container.firstChild).toBeNull();
+  });
+
+  it("shows a peer's live words when a body is present", () => {
+    const peers: PeerDraft[] = [{ author: { id: 2, name: "Bo B" }, body: "hello there", at: null }];
+    render(<TypingRows peers={peers} />);
+    const row = screen.getByTestId("typing-row");
+    expect(row.textContent).toContain("Bo B");
+    expect(row.textContent).toContain("hello there");
+    expect(row.textContent).toContain("is typing:");
+  });
+
+  it("renders 'is typing…' with no words when the body is withheld", () => {
+    const peers: PeerDraft[] = [{ author: { id: 2, name: "Bo B" }, body: "", at: null, typing: true }];
+    render(<TypingRows peers={peers} />);
+    const row = screen.getByTestId("typing-row");
+    expect(row.textContent).toContain("Bo B");
+    expect(row.textContent).toContain("is typing…");
+    expect(row.textContent).not.toContain("is typing:");
+  });
+});

package/src/chat/TypingRows.tsx

@@ -6,13 +6,20 @@ 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) => (
-        <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>
-      ))}
+      {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/drafts.test.ts

@@ -5,8 +5,10 @@ import {
   clearStoredDraft,
   draftStorageKey,
   readStoredDraft,
+  readStoredTypingVisibility,
   shouldSyncDraftLive,
   writeStoredDraft,
+  writeStoredTypingVisibility,
 } from "./drafts"
 
 const NOW = 1_700_000_000_000
@@ -144,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,3 +1,5 @@
+import type { TypingVisibility } from "./protocol";
+
 /**
  * Whether keystrokes need to be mirrored to the server AS YOU TYPE.
  *
@@ -149,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/index.ts

@@ -17,6 +17,7 @@ export type {
   SessionMenu,
   SessionState,
   TurnStatus,
+  TypingVisibility,
   WsAction,
   WsEvent,
 } from "./protocol";
@@ -57,6 +58,8 @@ export {
   draftStorageKey,
   readStoredDraft,
   writeStoredDraft,
+  readStoredTypingVisibility,
+  writeStoredTypingVisibility,
   type DraftStorage,
 } from "./drafts";
 

package/src/chat/protocol.ts

@@ -51,6 +51,12 @@ export interface Message {
   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;
@@ -66,16 +72,24 @@ export interface Draft {
    *  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. */
+ *  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
@@ -263,6 +277,12 @@ 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> }

package/src/chat/sessionReducer.test.ts

@@ -227,6 +227,29 @@ describe("sessionReducer — drafts", () => {
     expect(next.active_draft?.version).toBe(3)
   })
 
+  it("draft.updated carries the server's visibility into active_draft even while keeping the local body", () => {
+    // The drift check in useSessionSocket (`current.visibility !==
+    // typingVisibilityRef.current`) compares against THIS field — if the
+    // echo-suppression branch never updated it, that check would compare
+    // against a permanently stale value.
+    const prev = makeState({
+      current_user_id: 5,
+      active_draft: { ...baseDraft, body: "local typing", version: 3, visibility: "live" },
+    })
+    const next = sessionReducer(prev, {
+      event: "draft.updated",
+      data: {
+        ...baseDraft,
+        body: "stale server echo",
+        last_editor: 5,
+        version: 4,
+        visibility: "hidden",
+      } as Draft,
+    } as WsEvent)
+    expect(next.active_draft?.body).toBe("local typing")
+    expect(next.active_draft?.visibility).toBe("hidden")
+  })
+
   it("draft.updated accepts the body when another user is editing", () => {
     const prev = makeState({
       current_user_id: 5,
@@ -746,6 +769,30 @@ describe("per-person drafts", () => {
     expect(s.peer_drafts).toEqual([]);
   });
 
+  it("keeps an empty-body row when the server says the person is still typing", () => {
+    // `typing`/`hidden` visibility withholds the words but not the fact of
+    // typing — the row must survive rather than being read as "sent/cleared".
+    const s = sessionReducer(makeState(), {
+      event: "draft.typing",
+      data: { author: { id: 2, name: "Bo" }, body: "", at: null, typing: true },
+    } as WsEvent);
+    expect(s.peer_drafts).toEqual([
+      { author: { id: 2, name: "Bo" }, body: "", at: null, typing: true },
+    ]);
+  });
+
+  it("removes the row when the body is empty and typing is not true", () => {
+    let s = sessionReducer(makeState(), {
+      event: "draft.typing",
+      data: { author: { id: 2, name: "Bo" }, body: "", at: null, typing: true },
+    } as WsEvent);
+    s = sessionReducer(s, {
+      event: "draft.typing",
+      data: { author: { id: 2, name: "Bo" }, body: "", at: null, typing: false },
+    } as WsEvent);
+    expect(s.peer_drafts).toEqual([]);
+  });
+
   it("presence.left drops that person's typing row", () => {
     let s = sessionReducer(makeState(), {
       event: "draft.typing",

package/src/chat/sessionReducer.ts

@@ -374,6 +374,13 @@ export function sessionReducer(prev: SessionState, frame: WsEvent): SessionState
             version: incoming.version,
             last_editor: incoming.last_editor,
             last_edit_at: incoming.last_edit_at,
+            // The server's CURRENT visibility, even while the body itself is
+            // kept local — `useSessionSocket`'s drift check compares against
+            // this field, and it must reflect what the server actually has,
+            // not a value frozen at whatever it was when this draft first
+            // loaded. `?? prev.active_draft.visibility` only for an older
+            // server that omits the field.
+            visibility: incoming.visibility ?? prev.active_draft.visibility,
           },
         };
       }
@@ -382,9 +389,12 @@ export function sessionReducer(prev: SessionState, frame: WsEvent): SessionState
 
     case "draft.typing": {
       // Someone else's box, live. Keyed by author; an empty body means they
-      // sent, discarded or cleared it.
+      // sent, discarded or cleared it — UNLESS `typing` is true, which means
+      // the words are simply withheld (typing/hidden visibility) while the
+      // person is still mid-thought, so the row is kept rather than removed.
       const rest = (prev.peer_drafts ?? []).filter((d) => d.author.id !== frame.data.author.id);
-      return { ...prev, peer_drafts: frame.data.body ? [...rest, frame.data] : rest };
+      const keep = frame.data.body !== "" || frame.data.typing === true;
+      return { ...prev, peer_drafts: keep ? [...rest, frame.data] : rest };
     }
 
     case "session.queued":

package/src/chat/useSessionSocket.ts

@@ -1,8 +1,14 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 
 import { fromAgui, resetAguiState } from "./agui";
-import type { Draft, Message, SessionState, WsEvent } from "./protocol";
-import { shouldSyncDraftLive } from "./drafts";
+import type { Draft, Message, SessionState, TypingVisibility, WsEvent } from "./protocol";
+import {
+  TYPING_VISIBILITY_STORAGE_KEY,
+  defaultDraftStorage,
+  readStoredTypingVisibility,
+  shouldSyncDraftLive,
+  writeStoredTypingVisibility,
+} from "./drafts";
 import { prependHistory } from "./history";
 import {
   REDUCER_EVENTS,
@@ -185,6 +191,14 @@ export interface UseSessionSocketResult {
    *  they're the same send rather than rendering it twice. */
   noteLocalSend: (text: string, clientId?: string) => void;
   lastError: string | null;
+  /** This person's chosen mode for how their OWN in-progress message appears
+   *  to others — persisted per browser (`canopy.chat.typingVisibility`).
+   *  Defaults to `"live"`, today's behaviour. */
+  typingVisibility: TypingVisibility;
+  /** Change the mode. When there is a non-empty draft body and live sync is
+   *  on (somebody else is present), sends one `draft.update` immediately so
+   *  peers switch right away rather than waiting for the next keystroke. */
+  setTypingVisibility: (visibility: TypingVisibility) => void;
 }
 
 // Frames the reducer handles: its own list, so the two cannot drift (see
@@ -211,6 +225,11 @@ export function useSessionSocket({
   // 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);
+  // Per-browser, not per-session — a standing choice about how you type, read
+  // once at mount from the same try/catch-safe storage `SendBox` uses.
+  const [typingVisibility, setTypingVisibilityState] = useState<TypingVisibility>(
+    () => readStoredTypingVisibility(defaultDraftStorage()) ?? "live",
+  );
 
   const socketRef = useRef<WebSocket | null>(null);
   const stateRef = useRef<SessionState>(INITIAL_STATE);
@@ -227,10 +246,21 @@ export function useSessionSocket({
   // vocabulary mid-session.
   const protocolRef = useRef(protocol);
   protocolRef.current = protocol;
+  // Read wherever the mode needs to be sent or compared, closing over
+  // whatever is CURRENT rather than whatever a callback was created with.
+  const typingVisibilityRef = useRef(typingVisibility);
+  typingVisibilityRef.current = typingVisibility;
   const warnedNativeRef = useRef(false);
   // Control frames that must not be lost across a reconnect (currently
   // only chat.stop). The WS-world analogue of an abortable chat transport.
   const pendingFramesRef = useRef<{ action: string; data: unknown }[]>([]);
+  // A mode the person CHOSE while this socket could not carry it (closed, or
+  // open but before the first snapshot told us what the server holds). Sent
+  // once on the next snapshot, then cleared. Nothing else is ever pushed on
+  // connect: a device with nothing stored has only a DEFAULT, and pushing a
+  // default would expose words its author hid from another device.
+  const pendingVisibilityRef = useRef<TypingVisibility | null>(null);
+  const snapshotSeenRef = useRef(false);
   // Sends awaiting the server's receipt: client_id -> {text, timer}.
   const unconfirmedRef = useRef(new Map<string, { text: string; timer: number | null }>());
   const resendRef = useRef(resendOverHttp);
@@ -248,6 +278,24 @@ export function useSessionSocket({
     onUnknownEventRef.current = onUnknownEvent;
   }, [onUnknownEvent]);
 
+  // Belt-and-braces for the SAME cross-tab sync `draft.updated` adoption
+  // covers: a native `storage` event fires in every OTHER tab the instant one
+  // tab writes the key (never the writer's own tab), so it catches the case
+  // no socket frame can — a tab with no live socket right now.
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    const onStorage = (e: StorageEvent) => {
+      if (e.key !== TYPING_VISIBILITY_STORAGE_KEY) return;
+      const next = readStoredTypingVisibility(defaultDraftStorage());
+      if (next != null && next !== typingVisibilityRef.current) {
+        typingVisibilityRef.current = next;
+        setTypingVisibilityState(next);
+      }
+    };
+    window.addEventListener("storage", onStorage);
+    return () => window.removeEventListener("storage", onStorage);
+  }, []);
+
   const send = useCallback((frame: { action: string; data: unknown }) => {
     const ws = socketRef.current;
     if (ws && ws.readyState === WebSocket.OPEN) {
@@ -298,12 +346,50 @@ export function useSessionSocket({
     ) {
       setAwaitingReply(false);
     }
+    // `draft.updated` only ever reaches the AUTHOR's own sockets (see
+    // `_broadcast_draft`), so this is always MY draft, echoed — including
+    // from a mode change in a DIFFERENT tab of my own, or from THIS tab's own
+    // `draft.set_visibility` round-tripping back. Adopted UNCONDITIONALLY:
+    // since the mode is now its own idempotent, unversioned frame
+    // (`draft.set_visibility`) rather than a field racing keystrokes on
+    // `draft.update`, the only thing that ever changes it server-side is an
+    // explicit choice — made here, in another tab, or on another device — so
+    // last-choice-wins is simply correct, with no downgrade race to guard
+    // against.
+    if (frame.event === "draft.updated" && frame.data.visibility) {
+      if (frame.data.visibility !== typingVisibilityRef.current) {
+        typingVisibilityRef.current = frame.data.visibility;
+        setTypingVisibilityState(frame.data.visibility);
+        writeStoredTypingVisibility(defaultDraftStorage(), frame.data.visibility);
+      }
+    }
     // The server's receipt for one of OUR sends: stop waiting on it.
     if (frame.event === "draft.committed" && frame.data.client_id) {
       const entry = unconfirmedRef.current.get(frame.data.client_id);
       if (entry?.timer != null) window.clearTimeout(entry.timer);
       unconfirmedRef.current.delete(frame.data.client_id);
     }
+    // On a snapshot (connect or reconnect) the SERVER's stored mode is the
+    // truth — it is the last explicit choice from any tab or device. The one
+    // exception is a choice made HERE while the socket could not carry it
+    // (`pendingVisibilityRef`): that is newer, so it is sent now, before any
+    // later joiner's snapshot can read the older mode. A local value that was
+    // never chosen (nothing stored, a private window, the widget's partitioned
+    // storage) is only a default, and is never pushed. No own draft (a viewer
+    // or a contact) means there is nothing of ours to set.
+    if (frame.event === "session.state") {
+      snapshotSeenRef.current = true;
+      const ad = frame.data.active_draft;
+      const pending = pendingVisibilityRef.current;
+      pendingVisibilityRef.current = null;
+      if (ad != null && pending != null) {
+        send({ action: "draft.set_visibility", data: { visibility: pending } });
+      } else if (ad?.visibility && ad.visibility !== typingVisibilityRef.current) {
+        typingVisibilityRef.current = ad.visibility;
+        setTypingVisibilityState(ad.visibility);
+        writeStoredTypingVisibility(defaultDraftStorage(), ad.visibility);
+      }
+    }
     // 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") {
@@ -318,7 +404,9 @@ export function useSessionSocket({
         typeof frame.data.detail === "object"
       ) {
         // Clear any pending optimistic body so the user's stale local
-        // text doesn't auto-re-send with the new version.
+        // text doesn't auto-re-send with the new version. The mode is
+        // unaffected by this — it never rides `draft.update`, so a body
+        // conflict here has nothing to do with it and needs no recovery.
         pendingDraftBodyRef.current = null;
         if (draftDebounceRef.current != null) {
           window.clearTimeout(draftDebounceRef.current);
@@ -334,7 +422,7 @@ export function useSessionSocket({
       return;
     }
     setState((prev) => sessionReducer(prev, frame));
-  }, []);
+  }, [send]);
 
   const connect = useCallback(() => {
     if (closedByUserRef.current) return;
@@ -349,6 +437,7 @@ export function useSessionSocket({
     socketRef.current = ws;
 
     ws.onopen = () => {
+      snapshotSeenRef.current = false;
       setConnected(true);
       reconnectAttemptRef.current = 0;
       // Flush any control frames that were queued while the socket was
@@ -398,6 +487,7 @@ export function useSessionSocket({
     };
 
     ws.onclose = () => {
+      snapshotSeenRef.current = false;
       setConnected(false);
       // A send still waiting for its receipt will not get one on this socket.
       for (const clientId of [...unconfirmedRef.current.keys()]) rescueSend(clientId);
@@ -515,6 +605,31 @@ export function useSessionSocket({
     [send],
   );
 
+  const setTypingVisibility = useCallback(
+    (visibility: TypingVisibility) => {
+      setTypingVisibilityState(visibility);
+      typingVisibilityRef.current = visibility;
+      writeStoredTypingVisibility(defaultDraftStorage(), visibility);
+      // The mode is its OWN idempotent frame — applied unconditionally
+      // server-side, no version check — so there is no presence gate: a mode
+      // change must reach the server even while ALONE, or a peer who joins
+      // later reads the old mode straight off their connect snapshot. Until
+      // the first snapshot has told us what the server holds (or while the
+      // socket is closed) the choice waits in `pendingVisibilityRef` and the
+      // snapshot sends it. With no own draft (a viewer or a contact) there is
+      // nothing to set, and the server would refuse it anyway.
+      const ws = socketRef.current;
+      const open = ws != null && ws.readyState === WebSocket.OPEN;
+      if (!open || !snapshotSeenRef.current) {
+        pendingVisibilityRef.current = visibility;
+        return;
+      }
+      if (stateRef.current.active_draft == null) return;
+      send({ action: "draft.set_visibility", data: { visibility } });
+    },
+    [send],
+  );
+
   // @deprecated no-op since 0.13 — the server accepts and ignores
   // `draft.take_over` too (see WsAction), so this is kept only so a host
   // wired to the old prop doesn't need an upgrade-day edit.
@@ -645,5 +760,7 @@ export function useSessionSocket({
     prependMessages,
     noteLocalSend,
     lastError,
+    typingVisibility,
+    setTypingVisibility,
   };
 }

package/src/chat/useSessionSocket.typingVisibility.test.tsx

@@ -0,0 +1,280 @@
+// @vitest-environment jsdom
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { useSessionSocket } from "./useSessionSocket";
+
+/** Per-person typing visibility: a person chooses how their own in-progress
+ *  message appears to others (live / typing / hidden). The mode is its OWN
+ *  idempotent, unversioned frame (`draft.set_visibility`) — never a field on
+ *  the version-guarded `draft.update` keystroke frame, which is exactly what
+ *  let a stale keystroke echo race a mode change and downgrade it
+ *  server-side (canopy-ui#… "hidden->live->hidden" regression). The hook
+ *  holds the choice, persists it per browser, and applies it unconditionally
+ *  both ways: every explicit choice reaches the server regardless of
+ *  presence or body, and a `draft.updated` echo's visibility is adopted
+ *  unconditionally (only an explicit choice — here, another tab, or another
+ *  device — ever changes it server-side, so last-choice-wins is simply
+ *  correct). */
+
+class FakeSocket {
+  static OPEN = 1;
+  static last: FakeSocket | null = null;
+  sent: string[] = [];
+  onopen: (() => void) | null = null;
+  onmessage: ((e: { data: string }) => void) | null = null;
+  onclose: (() => void) | null = null;
+  onerror: (() => void) | null = null;
+  readyState = 1;
+  constructor(public url: string) {
+    FakeSocket.last = this;
+  }
+  send(data: string) {
+    this.sent.push(data);
+  }
+  close() {}
+  receive(frame: unknown) {
+    this.onmessage?.({ data: JSON.stringify(frame) });
+  }
+}
+
+const DRAFT = { id: "d1", slot: "next", status: "open", body: "", version: 1, last_editor: 0, last_edit_at: "" };
+
+function snapshot(presenceIds: number[]) {
+  return {
+    event: "session.state",
+    data: { messages: [], active_draft: DRAFT, participants: [], presence_user_ids: presenceIds, current_user_id: 1 },
+  };
+}
+
+// A minimal, real Storage-shaped fake — the hook reads/writes it through
+// `defaultDraftStorage()` (which returns `window.localStorage`), so replacing
+// the global is how a remount is proven to persist across.
+function fakeLocalStorage() {
+  const map = new Map<string, string>();
+  return {
+    getItem: (k: string) => map.get(k) ?? null,
+    setItem: (k: string, v: string) => void map.set(k, v),
+    removeItem: (k: string) => void map.delete(k),
+    clear: () => map.clear(),
+  };
+}
+
+let storage: ReturnType<typeof fakeLocalStorage>;
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  vi.stubGlobal("WebSocket", FakeSocket);
+  storage = fakeLocalStorage();
+  vi.stubGlobal("localStorage", storage);
+});
+afterEach(() => {
+  vi.useRealTimers();
+  vi.unstubAllGlobals();
+});
+
+const wsUrl = () => "wss://h/x";
+
+function connectedWith(presenceIds: number[]) {
+  const hook = renderHook(() => useSessionSocket({ sessionId: "s1", wsUrl }));
+  act(() => {
+    FakeSocket.last!.onopen?.();
+    FakeSocket.last!.receive(snapshot(presenceIds));
+  });
+  return hook;
+}
+
+function sentFrames(action: string) {
+  return FakeSocket.last!.sent.map((f) => JSON.parse(f)).filter((f) => f.action === action);
+}
+const draftUpdateFrames = () => sentFrames("draft.update");
+const setVisibilityFrames = () => sentFrames("draft.set_visibility");
+
+describe("typingVisibility", () => {
+  it("defaults to live", () => {
+    const hook = connectedWith([1, 2]);
+    expect(hook.result.current.typingVisibility).toBe("live");
+  });
+
+  it("persists the mode across a remount", () => {
+    const first = connectedWith([1, 2]);
+    act(() => first.result.current.setTypingVisibility("hidden"));
+    first.unmount();
+
+    const second = connectedWith([1, 2]);
+    expect(second.result.current.typingVisibility).toBe("hidden");
+  });
+
+  it("choosing a mode sends draft.set_visibility, presence or not, body or not", () => {
+    // No gate at all: it's one tiny idempotent frame, unconditional
+    // server-side too — there is nothing left to gate on.
+    const alone = connectedWith([1]);
+    act(() => alone.result.current.setTypingVisibility("hidden"));
+    expect(setVisibilityFrames()).toEqual([{ action: "draft.set_visibility", data: { visibility: "hidden" } }]);
+  });
+
+  it("a keystroke's draft.update never carries a visibility field", () => {
+    const hook = connectedWith([1, 2]);
+    act(() => hook.result.current.setTypingVisibility("typing"));
+    act(() => hook.result.current.updateDraft("hello"));
+    act(() => vi.advanceTimersByTime(200));
+    const last = draftUpdateFrames().at(-1)!;
+    expect(last.data).toEqual({ version: 1, body: "hello" });
+  });
+
+  it("adopts a mode carried on my own draft.updated frame (other-tab sync)", () => {
+    const hook = connectedWith([1, 2]);
+    expect(hook.result.current.typingVisibility).toBe("live");
+    act(() =>
+      FakeSocket.last!.receive({
+        event: "draft.updated",
+        data: { ...DRAFT, visibility: "hidden" },
+      }),
+    );
+    expect(hook.result.current.typingVisibility).toBe("hidden");
+    expect(storage.getItem("canopy.chat.typingVisibility")).toBe("hidden");
+  });
+
+  it("adopts a LOOSENING carried on my own draft.updated frame too — last choice wins", () => {
+    // The mode can only ever change server-side via an explicit choice now
+    // (this tab, another tab, or another device), so a looser echo is a real
+    // choice made elsewhere, not a stale race — it must be adopted exactly
+    // like a tightening one.
+    const hook = connectedWith([1, 2]);
+    act(() => hook.result.current.setTypingVisibility("hidden"));
+    act(() =>
+      FakeSocket.last!.receive({
+        event: "draft.updated",
+        data: { ...DRAFT, visibility: "live" },
+      }),
+    );
+    expect(hook.result.current.typingVisibility).toBe("live");
+    expect(storage.getItem("canopy.chat.typingVisibility")).toBe("live");
+  });
+
+  // -- the connect snapshot: the SERVER's stored mode is the truth --
+  //
+  // A device with nothing stored (fresh phone, private window, blocked or
+  // partitioned storage — the embedded widget in a third-party iframe) only
+  // has a DEFAULT, and a default is not a choice: pushing it would expose
+  // words its author hid from another device. Only a choice made while this
+  // socket could not carry it (pending) is sent on connect.
+
+  function ownSnapshot(activeDraft: unknown) {
+    return {
+      event: "session.state",
+      data: {
+        messages: [],
+        active_draft: activeDraft,
+        participants: [],
+        presence_user_ids: [1, 2],
+        current_user_id: 1,
+      },
+    };
+  }
+
+  it("a fresh device adopts the server's mode off the snapshot and sends nothing", () => {
+    // Nothing stored: the local value is only the "live" default.
+    const hook = renderHook(() => useSessionSocket({ sessionId: "s1", wsUrl }));
+    act(() => {
+      FakeSocket.last!.onopen?.();
+      FakeSocket.last!.receive(ownSnapshot({ ...DRAFT, body: "x", visibility: "hidden" }));
+    });
+    expect(setVisibilityFrames()).toEqual([]);
+    expect(hook.result.current.typingVisibility).toBe("hidden");
+    expect(storage.getItem("canopy.chat.typingVisibility")).toBe("hidden");
+  });
+
+  it("a stale stored mode yields to the server's on connect, sending nothing", () => {
+    storage.setItem("canopy.chat.typingVisibility", "live");
+    const hook = renderHook(() => useSessionSocket({ sessionId: "s1", wsUrl }));
+    act(() => {
+      FakeSocket.last!.onopen?.();
+      FakeSocket.last!.receive(ownSnapshot({ ...DRAFT, visibility: "hidden" }));
+    });
+    expect(setVisibilityFrames()).toEqual([]);
+    expect(hook.result.current.typingVisibility).toBe("hidden");
+    expect(storage.getItem("canopy.chat.typingVisibility")).toBe("hidden");
+  });
+
+  it("a choice made while the socket was closed is sent once on the snapshot, then cleared", () => {
+    const hook = renderHook(() => useSessionSocket({ sessionId: "s1", wsUrl }));
+    FakeSocket.last!.readyState = 0; // CONNECTING
+    act(() => hook.result.current.setTypingVisibility("hidden"));
+    expect(setVisibilityFrames()).toEqual([]);
+    act(() => {
+      FakeSocket.last!.readyState = 1;
+      FakeSocket.last!.onopen?.();
+      FakeSocket.last!.receive(ownSnapshot({ ...DRAFT, visibility: "live" }));
+    });
+    expect(setVisibilityFrames()).toEqual([
+      { action: "draft.set_visibility", data: { visibility: "hidden" } },
+    ]);
+    expect(hook.result.current.typingVisibility).toBe("hidden");
+    // Pending is spent: a later snapshot (a reconnect) sends nothing more,
+    // and a server mode that disagrees then is simply adopted.
+    act(() => FakeSocket.last!.receive(ownSnapshot({ ...DRAFT, visibility: "hidden" })));
+    expect(setVisibilityFrames()).toHaveLength(1);
+  });
+
+  it("a choice made after open but before the first snapshot is pending too", () => {
+    const hook = renderHook(() => useSessionSocket({ sessionId: "s1", wsUrl }));
+    act(() => FakeSocket.last!.onopen?.());
+    act(() => hook.result.current.setTypingVisibility("typing"));
+    expect(setVisibilityFrames()).toEqual([]);
+    act(() => FakeSocket.last!.receive(ownSnapshot({ ...DRAFT, visibility: "hidden" })));
+    expect(setVisibilityFrames()).toEqual([
+      { action: "draft.set_visibility", data: { visibility: "typing" } },
+    ]);
+    expect(hook.result.current.typingVisibility).toBe("typing");
+  });
+
+  it("a choice made while connected is sent immediately and leaves nothing pending", () => {
+    const hook = renderHook(() => useSessionSocket({ sessionId: "s1", wsUrl }));
+    act(() => {
+      FakeSocket.last!.onopen?.();
+      FakeSocket.last!.receive(ownSnapshot({ ...DRAFT, visibility: "live" }));
+    });
+    act(() => hook.result.current.setTypingVisibility("hidden"));
+    expect(setVisibilityFrames()).toHaveLength(1);
+    act(() => FakeSocket.last!.receive(ownSnapshot({ ...DRAFT, visibility: "hidden" })));
+    expect(setVisibilityFrames()).toHaveLength(1);
+  });
+
+  it("a viewer or contact (no own draft) never sends set_visibility", () => {
+    const hook = renderHook(() => useSessionSocket({ sessionId: "s1", wsUrl }));
+    FakeSocket.last!.readyState = 0;
+    act(() => hook.result.current.setTypingVisibility("hidden")); // pending
+    act(() => {
+      FakeSocket.last!.readyState = 1;
+      FakeSocket.last!.onopen?.();
+      FakeSocket.last!.receive(ownSnapshot(null));
+    });
+    act(() => hook.result.current.setTypingVisibility("typing")); // while open
+    expect(setVisibilityFrames()).toEqual([]);
+    expect(hook.result.current.typingVisibility).toBe("typing");
+  });
+
+  it("a draft_version_mismatch never touches the mode", () => {
+    const hook = connectedWith([1, 2]);
+    act(() => hook.result.current.setTypingVisibility("hidden"));
+    act(() => hook.result.current.updateDraft("secret"));
+    act(() => vi.advanceTimersByTime(200));
+
+    act(() =>
+      FakeSocket.last!.receive({
+        event: "session.error",
+        data: {
+          code: "draft_version_mismatch",
+          message: "Draft changed since your last edit.",
+          detail: { current_version: 2, current_body: "secret" },
+        },
+      }),
+    );
+
+    // No automatic resend of anything mode-related — a body conflict has
+    // nothing to do with the mode any more.
+    expect(hook.result.current.typingVisibility).toBe("hidden");
+    expect(setVisibilityFrames()).toHaveLength(1); // only the explicit choice above
+  });
+});