canopy-ui 0.12.2 → 0.14.0

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,
@@ -23,17 +29,37 @@ const SEND_RECEIPT_TIMEOUT_MS = 4_000;
 const NOT_SENT =
   "Not sent: the connection dropped before canopy got it. Your words are kept here, so copy them and send again.";
 
-function newClientId(): string {
-  const c = (globalThis as { crypto?: { randomUUID?: () => string } }).crypto;
-  return c?.randomUUID ? c.randomUUID() : `c${Date.now().toString(36)}${Math.random().toString(36).slice(2)}`;
+/**
+ * A client-generated nonce for a send's `client_id` — exported so a host
+ * driving its own HTTP send (the widget's opening message, before a socket
+ * exists to send over; `ChatPage`'s `/share` command) can mint the SAME id
+ * for both the REST body and the matching `noteLocalSend` call, which is what
+ * lets `QueuedRows.hideClientIds` recognise the two as one send rather than
+ * rendering it twice.
+ */
+export function newClientId(): string {
+  // An idempotency nonce, not a secret — but it rides a request, so it comes
+  // from the platform CSPRNG, never Math.random (CodeQL js/insecure-randomness).
+  // randomUUID needs a secure context; getRandomValues does not.
+  const c = (globalThis as {
+    crypto?: { randomUUID?: () => string; getRandomValues?: (a: Uint8Array) => Uint8Array };
+  }).crypto;
+  if (c?.randomUUID) return c.randomUUID();
+  if (c?.getRandomValues) {
+    const bytes = c.getRandomValues(new Uint8Array(16));
+    return `c${Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("")}`;
+  }
+  return `c${Date.now().toString(36)}${(clientIdCounter++).toString(36)}`;
 }
 
+let clientIdCounter = 0;
+
 const INITIAL_STATE: SessionState = {
   messages: [],
   active_draft: null,
   participants: [],
   presence_user_ids: [],
-  current_user_id: 0,
+  current_user_id: null,
 };
 
 export interface UseSessionSocketOptions {
@@ -84,8 +110,15 @@ export interface UseSessionSocketOptions {
    * Everything else is unchanged — the same `state`, the same pending row, the
    * same "waiting for a reply" — so one chat UI serves a user and a contact
    * without a second send path in every host. Omit for a user (the default).
+   *
+   * Must pass `clientId` through as the send's `client_id` (both `/api/canopy-
+   * sessions/{id}/send` and `/api/contact/sessions/{id}/send` accept it) — it
+   * is the SAME id `sendChatOverHttp` stamps on the optimistic row, and without
+   * it the server's queued-turn projection has no way to recognise that row as
+   * the one it already showed, so the sender's own send rendered a second time
+   * as an unowned "queued" placeholder.
    */
-  sendOverHttp?: (text: string) => Promise<unknown>;
+  sendOverHttp?: (text: string, clientId: string) => Promise<unknown>;
   /**
    * The HTTP route for a USER's send, used only when a socket send gets no
    * receipt (see `SEND_RECEIPT_TIMEOUT_MS`). Must pass `clientId` through as the
@@ -128,6 +161,10 @@ export interface UseSessionSocketResult {
   sendChat: () => void;
   stopChat: (messageId: string | null) => void;
   updateDraft: (body: string) => void;
+  /** @deprecated ignored since 0.13 — everyone has their own draft now, so
+   *  there is no lock left to take over. Kept as a no-op so a host still
+   *  passing it through (e.g. ace-web's `onTakeOver={socket.takeOverDraft}`)
+   *  keeps compiling across the upgrade. */
   takeOverDraft: () => void;
   discardDraft: () => void;
   prependMessages: (older: Message[]) => void;
@@ -144,9 +181,24 @@ export interface UseSessionSocketResult {
    *  by `sendChat` alone, and the user's own line is not a server row until
    *  the agent's transcript ships it back. So you typed, pressed send, and got
    *  an empty panel — for as long as the reply took, and forever if its runner
-   *  was offline. */
-  noteLocalSend: (text: string) => void;
+   *  was offline.
+   *
+   *  Pass the SAME `clientId` the matching REST body sent (`sendChatOverHttp`
+   *  does this internally; a host driving its own HTTP send — the widget's
+   *  first message, `ChatPage`'s `/share` command — must generate one and pass
+   *  it to both), so the optimistic row's `content.client_id` matches the
+   *  server's queued-turn projection and `QueuedRows.hideClientIds` can tell
+   *  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
@@ -173,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);
@@ -189,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);
@@ -210,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) {
@@ -260,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") {
@@ -280,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);
@@ -296,7 +422,7 @@ export function useSessionSocket({
       return;
     }
     setState((prev) => sessionReducer(prev, frame));
-  }, []);
+  }, [send]);
 
   const connect = useCallback(() => {
     if (closedByUserRef.current) return;
@@ -311,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
@@ -360,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);
@@ -477,9 +605,35 @@ export function useSessionSocket({
     [send],
   );
 
-  const takeOverDraft = useCallback(() => {
-    send({ action: "draft.take_over", data: {} });
-  }, [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.
+  const takeOverDraft = useCallback(() => undefined, []);
 
   const discardDraft = useCallback(() => {
     send({ action: "draft.discard", data: {} });
@@ -521,7 +675,29 @@ export function useSessionSocket({
     });
   }, []);
 
-  const noteLocalSend = useCallback((text: string) => {
+  // A failed send's restore, NOT the same as `updateLocalDraft`: this is a
+  // stale write racing whatever the person typed while the request was in
+  // flight, so it must never overwrite it. A functional update reads the
+  // CURRENT draft rather than one closed over at send time — sendChatOverHttp
+  // cleared the draft to null before the request even went out, so "the local
+  // draft is still null or empty" means nothing newer has been typed since,
+  // and only then is it safe to put the failed body back. If the person has
+  // already started something else, that stays exactly as they left it; the
+  // failed send is simply lost rather than clobbering live typing (2026-09-26
+  // review: "contact sends hello, starts typing world, hello's failure
+  // overwrote world").
+  const restoreFailedLocalDraft = useCallback((body: string) => {
+    setLocalDraft((prev) =>
+      prev == null || prev.body === ""
+        ? {
+            id: "local", slot: "next", status: "open", body, version: 0,
+            last_editor: 0, last_edit_at: new Date().toISOString(),
+          }
+        : prev,
+    );
+  }, []);
+
+  const noteLocalSend = useCallback((text: string, clientId?: string) => {
     setAwaitingReply(true);
     const body = text.trim();
     if (!body) return;
@@ -539,6 +715,7 @@ export function useSessionSocket({
           message_id: `local:${Date.now()}`,
           turn_index: prev.messages.reduce((acc, m) => Math.max(acc, m.turn_index), 0) + 1,
           plaintext: body,
+          client_id: clientId,
         },
       }),
     );
@@ -547,15 +724,24 @@ export function useSessionSocket({
   const sendChatOverHttp = useCallback(() => {
     const body = (localDraft?.body ?? "").trim();
     if (!body || !sendOverHttp) return;
-    noteLocalSend(body);
+    // ONE id for both halves of this send — the optimistic row and the REST
+    // body — so the server's queued-turn projection and this row compare
+    // equal (`QueuedRows.hideClientIds`) instead of rendering the same send
+    // twice, once as the sender's own bubble and once as an unowned "queued"
+    // placeholder (a contact's `author.user_id` is never set, so without a
+    // shared id that placeholder didn't even read as "mine").
+    const clientId = newClientId();
+    noteLocalSend(body, clientId);
     setLocalDraft(null);
-    sendOverHttp(body).catch((err: unknown) => {
+    sendOverHttp(body, clientId).catch((err: unknown) => {
       setAwaitingReply(false);
       setLastError(err instanceof Error ? err.message : "the message could not be sent");
-      // Put the words back, so a failed send never costs what was typed.
-      updateLocalDraft(body);
+      // Put the words back, so a failed send never costs what was typed —
+      // but only if nothing NEWER has been typed since (see
+      // `restoreFailedLocalDraft`).
+      restoreFailedLocalDraft(body);
     });
-  }, [localDraft, sendOverHttp, noteLocalSend, updateLocalDraft]);
+  }, [localDraft, sendOverHttp, noteLocalSend, restoreFailedLocalDraft]);
 
   const exposedState = useMemo(
     () => (sendOverHttp ? { ...state, active_draft: localDraft } : state),
@@ -574,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
+  });
+});