canopy-ui 0.3.0 → 0.4.0

package/src/chat/sessionReducer.ts

@@ -0,0 +1,245 @@
+import type { Draft, Message, SessionState, WsEvent } from "./protocol";
+
+// Pure reducer for SessionState — extracted from useSessionSocket so it
+// can be unit-tested without WebSocket plumbing. Side-effect events
+// (session.title_updated → optional injected callback; session.error →
+// setLastError + clear draft debounce) stay in the hook itself.
+//
+// Keep this file dependency-free (no React) so a vitest run doesn't pull
+// jsdom or RTL.
+//
+// canopy adaptation vs ace: message/draft ids are STRINGS, and
+// `chat.stream_start` UPSERTS the assistant message — canopy's
+// `draft.committed` carries only `user_message_id` (no assistant id to
+// pre-insert), so the assistant row is created lazily when its first stream
+// frame arrives.
+export function sessionReducer(prev: SessionState, frame: WsEvent): SessionState {
+  switch (frame.event) {
+    case "session.state":
+      return frame.data;
+
+    case "chat.stream_start": {
+      // Upsert: if the assistant message already exists (rare — a runner that
+      // pre-inserts it), flip it to streaming; otherwise create it. canopy's
+      // draft.committed cannot pre-send the assistant id, so this is the
+      // normal path for making the streamed reply visible.
+      const exists = prev.messages.some((m) => m.id === frame.data.message_id);
+      if (exists) {
+        return {
+          ...prev,
+          messages: prev.messages.map((m) =>
+            m.id === frame.data.message_id
+              ? { ...m, status: "streaming" as const }
+              : m,
+          ),
+        };
+      }
+      const nowIso = new Date().toISOString();
+      const assistant: Message = {
+        id: frame.data.message_id,
+        turn_index: frame.data.turn_index,
+        role: "assistant",
+        content: {},
+        plaintext: "",
+        status: "streaming",
+        error_detail: null,
+        started_at: nowIso,
+        completed_at: null,
+        created_at: nowIso,
+      };
+      return { ...prev, messages: [...prev.messages, assistant] };
+    }
+
+    case "chat.delta":
+      return {
+        ...prev,
+        messages: prev.messages.map((m) =>
+          m.id === frame.data.message_id
+            ? { ...m, plaintext: m.plaintext + frame.data.text }
+            : m,
+        ),
+      };
+
+    case "chat.stream_complete":
+      return {
+        ...prev,
+        messages: prev.messages.map((m) =>
+          m.id === frame.data.message_id
+            ? {
+                ...m,
+                plaintext: frame.data.plaintext,
+                status: "complete" as const,
+              }
+            : m,
+        ),
+      };
+
+    case "chat.stream_error":
+      // NOTE: backend emits chat.stream_error with detail="cancelled"
+      // for stop-driven cancellation; there's no separate
+      // chat.stream_cancelled event in practice. Distinguished by detail.
+      return {
+        ...prev,
+        messages: prev.messages.map((m) =>
+          m.id === frame.data.message_id
+            ? {
+                ...m,
+                status: "error" as const,
+                error_detail: frame.data.detail,
+              }
+            : m,
+        ),
+      };
+
+    case "chat.stream_cancelled":
+      return {
+        ...prev,
+        messages: prev.messages.map((m) =>
+          m.id === frame.data.message_id
+            ? {
+                ...m,
+                status: "error" as const,
+                error_detail: `cancelled (partial: ${frame.data.partial_len} chars)`,
+              }
+            : m,
+        ),
+      };
+
+    case "chat.tool_use":
+    case "chat.tool_result":
+      // Tool rows are their own Message rows on the server. A full
+      // refresh picks them up; for now, don't duplicate bookkeeping here.
+      return prev;
+
+    case "draft.updated": {
+      const incoming = frame.data as Draft;
+      // If we're the current editor, keep our local body — the server
+      // echo is stale relative to keystrokes that happened since the
+      // debounced send. Only accept metadata (version, last_editor, etc).
+      if (
+        prev.active_draft &&
+        incoming.last_editor === prev.current_user_id
+      ) {
+        return {
+          ...prev,
+          active_draft: {
+            ...prev.active_draft,
+            version: incoming.version,
+            last_editor: incoming.last_editor,
+            last_edit_at: incoming.last_edit_at,
+          },
+        };
+      }
+      return { ...prev, active_draft: incoming };
+    }
+
+    case "draft.lock_changed":
+      if (prev.active_draft && prev.active_draft.id === frame.data.draft_id) {
+        return {
+          ...prev,
+          active_draft: {
+            ...prev.active_draft,
+            last_editor: frame.data.holder_user_id ?? prev.active_draft.last_editor,
+          },
+        };
+      }
+      return prev;
+
+    case "draft.committed": {
+      // Insert the optimistic USER message from the draft body that's about
+      // to be cleared. The assistant reply is NOT inserted here — canopy's
+      // draft.committed carries no assistant id; `chat.stream_start` upserts
+      // that row when the reply begins.
+      //
+      // Also clear active_draft.body here. The server creates a new empty
+      // draft with last_editor=sender, so the follow-up draft.updated hits
+      // the "keep local body" branch above and would otherwise leave the
+      // just-sent text in the textarea — which lets Enter re-send the same
+      // turn repeatedly.
+      const prevDraftBody = prev.active_draft?.body ?? "";
+      const maxTurnIndex = prev.messages.reduce(
+        (acc, msg) => Math.max(acc, msg.turn_index),
+        0,
+      );
+      const nowIso = new Date().toISOString();
+      const userMessage: Message = {
+        id: frame.data.user_message_id,
+        turn_index: maxTurnIndex + 1,
+        role: "user",
+        content: { text: prevDraftBody },
+        plaintext: prevDraftBody,
+        status: "complete",
+        error_detail: null,
+        started_at: null,
+        completed_at: nowIso,
+        created_at: nowIso,
+      };
+      return {
+        ...prev,
+        active_draft: prev.active_draft
+          ? { ...prev.active_draft, body: "" }
+          : prev.active_draft,
+        messages: [...prev.messages, userMessage],
+      };
+    }
+
+    case "draft.discarded":
+      if (prev.active_draft && prev.active_draft.id === frame.data.draft_id) {
+        return {
+          ...prev,
+          active_draft: { ...prev.active_draft, body: "" },
+        };
+      }
+      return prev;
+
+    case "presence.joined": {
+      const ids = new Set(prev.presence_user_ids);
+      ids.add(frame.data.user_id);
+      return { ...prev, presence_user_ids: [...ids] };
+    }
+
+    case "presence.left":
+      return {
+        ...prev,
+        presence_user_ids: prev.presence_user_ids.filter(
+          (id) => id !== frame.data.user_id,
+        ),
+      };
+
+    case "session.error": {
+      // Side effects (setLastError, clear draft debounce) are handled
+      // by the hook; the reducer only knows about the version-mismatch
+      // recovery, which mutates active_draft.
+      if (
+        frame.data.code === "draft_version_mismatch" &&
+        frame.data.detail &&
+        typeof frame.data.detail === "object"
+      ) {
+        const detail = frame.data.detail as {
+          current_version: number;
+          current_body: string;
+        };
+        return prev.active_draft
+          ? {
+              ...prev,
+              active_draft: {
+                ...prev.active_draft,
+                version: detail.current_version,
+                body: detail.current_body,
+              },
+            }
+          : prev;
+      }
+      return prev;
+    }
+
+    case "session.title_updated":
+      // Pure reducer leaves this alone — the hook calls its optional
+      // onTitleUpdated callback on receipt and short-circuits. Included
+      // here so an exhaustive switch type-checks.
+      return prev;
+
+    default:
+      return prev;
+  }
+}

package/src/chat/useSessionSocket.ts

@@ -0,0 +1,269 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import type { Message, SessionState, WsEvent } from "./protocol";
+import { prependHistory } from "./history";
+import { sessionReducer } from "./sessionReducer";
+
+const HEARTBEAT_INTERVAL_MS = 20_000;
+const RECONNECT_DELAYS_MS = [1_000, 2_000, 5_000, 10_000];
+const DRAFT_UPDATE_DEBOUNCE_MS = 150;
+
+const INITIAL_STATE: SessionState = {
+  messages: [],
+  active_draft: null,
+  participants: [],
+  presence_user_ids: [],
+  current_user_id: 0,
+};
+
+export interface UseSessionSocketOptions {
+  /** The chat session id (UUID string). */
+  sessionId: string;
+  /**
+   * App-injected WebSocket URL builder. The kit never imports app routing/base
+   * helpers; the container passes one (e.g. canopy's `wsUrl`). Called with the
+   * relative path `ws/canopy-sessions/${sessionId}/`.
+   */
+  wsUrl: (path: string) => string;
+  /**
+   * Optional side-effect callback fired when the server broadcasts a
+   * `session.title_updated` (replaces ace's `notifySessionsUpdated`). The kit
+   * has no opinion on what to do with it.
+   */
+  onTitleUpdated?: () => void;
+}
+
+export interface UseSessionSocketResult {
+  state: SessionState;
+  connected: boolean;
+  sendChat: () => void;
+  stopChat: (messageId: string) => void;
+  updateDraft: (body: string) => void;
+  takeOverDraft: () => void;
+  discardDraft: () => void;
+  prependMessages: (older: Message[]) => void;
+  lastError: string | null;
+}
+
+export function useSessionSocket({
+  sessionId,
+  wsUrl,
+  onTitleUpdated,
+}: UseSessionSocketOptions): UseSessionSocketResult {
+  const [state, setState] = useState<SessionState>(INITIAL_STATE);
+  const [connected, setConnected] = useState(false);
+  const [lastError, setLastError] = useState<string | null>(null);
+
+  const socketRef = useRef<WebSocket | null>(null);
+  const stateRef = useRef<SessionState>(INITIAL_STATE);
+  const reconnectAttemptRef = useRef(0);
+  const heartbeatTimerRef = useRef<number | null>(null);
+  const draftDebounceRef = useRef<number | null>(null);
+  const pendingDraftBodyRef = useRef<string | null>(null);
+  const closedByUserRef = useRef(false);
+  const onTitleUpdatedRef = useRef(onTitleUpdated);
+  // 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 }[]>([]);
+
+  useEffect(() => {
+    stateRef.current = state;
+  }, [state]);
+
+  useEffect(() => {
+    onTitleUpdatedRef.current = onTitleUpdated;
+  }, [onTitleUpdated]);
+
+  const send = useCallback((frame: { action: string; data: unknown }) => {
+    const ws = socketRef.current;
+    if (ws && ws.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify(frame));
+      return;
+    }
+    // Queue chat.stop so a stop clicked while the socket is reconnecting
+    // is delivered on next OPEN instead of silently dropped. Draft updates
+    // are intentionally NOT queued — they have a version guard and the
+    // user's next keystroke will refresh the body anyway.
+    if (frame.action === "chat.stop") {
+      pendingFramesRef.current.push(frame);
+    }
+  }, []);
+
+  const applyEvent = useCallback((frame: WsEvent) => {
+    // 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") {
+      onTitleUpdatedRef.current?.();
+      return;
+    }
+    if (frame.event === "session.error") {
+      setLastError(frame.data.message);
+      if (
+        frame.data.code === "draft_version_mismatch" &&
+        frame.data.detail &&
+        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.
+        pendingDraftBodyRef.current = null;
+        if (draftDebounceRef.current != null) {
+          window.clearTimeout(draftDebounceRef.current);
+          draftDebounceRef.current = null;
+        }
+      }
+    }
+    setState((prev) => sessionReducer(prev, frame));
+  }, []);
+
+  const connect = useCallback(() => {
+    if (closedByUserRef.current) return;
+    const ws = new WebSocket(wsUrl(`ws/canopy-sessions/${sessionId}/`));
+    socketRef.current = ws;
+
+    ws.onopen = () => {
+      setConnected(true);
+      reconnectAttemptRef.current = 0;
+      // Flush any control frames that were queued while the socket was
+      // closed. See `send` above.
+      const queued = pendingFramesRef.current;
+      pendingFramesRef.current = [];
+      for (const frame of queued) {
+        ws.send(JSON.stringify(frame));
+      }
+      if (heartbeatTimerRef.current != null) {
+        window.clearInterval(heartbeatTimerRef.current);
+      }
+      heartbeatTimerRef.current = window.setInterval(() => {
+        send({ action: "presence.heartbeat", data: {} });
+      }, HEARTBEAT_INTERVAL_MS);
+    };
+
+    ws.onmessage = (e) => {
+      try {
+        const frame = JSON.parse(e.data) as WsEvent;
+        applyEvent(frame);
+      } catch {
+        // ignore malformed frames
+      }
+    };
+
+    ws.onclose = () => {
+      setConnected(false);
+      if (heartbeatTimerRef.current != null) {
+        window.clearInterval(heartbeatTimerRef.current);
+        heartbeatTimerRef.current = null;
+      }
+      if (closedByUserRef.current) return;
+      const attempt = reconnectAttemptRef.current;
+      const delay =
+        RECONNECT_DELAYS_MS[Math.min(attempt, RECONNECT_DELAYS_MS.length - 1)];
+      reconnectAttemptRef.current = attempt + 1;
+      window.setTimeout(connect, delay);
+    };
+
+    ws.onerror = () => {
+      // onclose will fire next; nothing to do here.
+    };
+  }, [applyEvent, send, sessionId, wsUrl]);
+
+  useEffect(() => {
+    closedByUserRef.current = false;
+    reconnectAttemptRef.current = 0;
+    connect();
+    return () => {
+      closedByUserRef.current = true;
+      if (heartbeatTimerRef.current != null) {
+        window.clearInterval(heartbeatTimerRef.current);
+      }
+      if (socketRef.current) {
+        socketRef.current.close();
+        socketRef.current = null;
+      }
+    };
+  }, [connect]);
+
+  const sendChat = useCallback(() => {
+    // Flush any pending debounced update first so the committed draft
+    // carries the latest local body.
+    if (draftDebounceRef.current != null) {
+      window.clearTimeout(draftDebounceRef.current);
+      draftDebounceRef.current = null;
+      if (pendingDraftBodyRef.current != null && stateRef.current.active_draft) {
+        send({
+          action: "draft.update",
+          data: {
+            version: stateRef.current.active_draft.version,
+            body: pendingDraftBodyRef.current,
+          },
+        });
+      }
+    }
+    pendingDraftBodyRef.current = null;
+    send({ action: "chat.send", data: {} });
+  }, [send]);
+
+  const stopChat = useCallback(
+    (messageId: string) => {
+      send({ action: "chat.stop", data: { message_id: messageId } });
+    },
+    [send],
+  );
+
+  const updateDraft = useCallback(
+    (body: string) => {
+      // Optimistic local update so the textarea feels snappy.
+      setState((prev) =>
+        prev.active_draft
+          ? { ...prev, active_draft: { ...prev.active_draft, body } }
+          : prev,
+      );
+      pendingDraftBodyRef.current = body;
+      if (draftDebounceRef.current != null) {
+        window.clearTimeout(draftDebounceRef.current);
+      }
+      draftDebounceRef.current = window.setTimeout(() => {
+        draftDebounceRef.current = null;
+        const current = stateRef.current.active_draft;
+        const pending = pendingDraftBodyRef.current;
+        pendingDraftBodyRef.current = null;
+        if (current != null && pending != null) {
+          send({
+            action: "draft.update",
+            data: { version: current.version, body: pending },
+          });
+        }
+      }, DRAFT_UPDATE_DEBOUNCE_MS);
+    },
+    [send],
+  );
+
+  const takeOverDraft = useCallback(() => {
+    send({ action: "draft.take_over", data: {} });
+  }, [send]);
+
+  const discardDraft = useCallback(() => {
+    send({ action: "draft.discard", data: {} });
+  }, [send]);
+
+  const prependMessages = useCallback((older: Message[]) => {
+    // Apply a REST "Load earlier" page into the live socket state. A later
+    // session.state snapshot (e.g. reconnect) resets to the tail — acceptable;
+    // the user re-loads earlier if needed.
+    setState((prev) => {
+      const merged = prependHistory(prev.messages, older);
+      return merged === prev.messages ? prev : { ...prev, messages: merged };
+    });
+  }, []);
+
+  return {
+    state,
+    connected,
+    sendChat,
+    stopChat,
+    updateDraft,
+    takeOverDraft,
+    discardDraft,
+    prependMessages,
+    lastError,
+  };
+}

package/src/chat/useStickyBottom.ts

@@ -0,0 +1,77 @@
+import { useCallback, useEffect, useRef, type RefObject } from "react";
+
+/**
+ * Sticky-bottom auto-scroll for a streaming message list.
+ *
+ * Behaviour:
+ *  - When the user is at (or within `thresholdPx` of) the bottom of the
+ *    scroll container, growth of `dep` (e.g. messages array, streaming
+ *    text length) snaps the view to the new bottom.
+ *  - When the user has scrolled up to read history, growth does NOT
+ *    yank them back. Auto-follow resumes once they scroll back near
+ *    the bottom themselves.
+ *
+ * The "near bottom" predicate is updated in two places:
+ *  - on the user's `scroll` event (so manual scroll-up disables follow)
+ *  - immediately after an auto-scroll write (so we stay sticky even
+ *    though the scroll event for our own write would temporarily make
+ *    `scrollHeight - scrollTop - clientHeight` larger by a few pixels)
+ *
+ * Use "instant" scroll behavior for streaming chunks — smooth scroll
+ * cannot keep up with high-frequency updates and the view drifts.
+ *
+ * Returns:
+ *  - `containerRef`: attach to the scrollable element.
+ *  - `onScroll`: attach to `onScroll` on the same element.
+ *  - `scrollToBottom`: force a snap (e.g. on send).
+ */
+export function useStickyBottom<T>(
+  dep: T,
+  options: { thresholdPx?: number; enabled?: boolean } = {},
+): {
+  containerRef: RefObject<HTMLDivElement | null>;
+  onScroll: () => void;
+  scrollToBottom: () => void;
+} {
+  const { thresholdPx = 100, enabled = true } = options;
+  const containerRef = useRef<HTMLDivElement>(null);
+  // Default true: when the container first mounts there's no history
+  // to read, so the user is "at the bottom" by definition.
+  const wasNearBottomRef = useRef(true);
+
+  const isNearBottom = useCallback(
+    (el: HTMLElement): boolean =>
+      el.scrollHeight - el.scrollTop - el.clientHeight < thresholdPx,
+    [thresholdPx],
+  );
+
+  const onScroll = useCallback(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    wasNearBottomRef.current = isNearBottom(el);
+  }, [isNearBottom]);
+
+  const scrollToBottom = useCallback(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    el.scrollTop = el.scrollHeight;
+    wasNearBottomRef.current = true;
+  }, []);
+
+  useEffect(() => {
+    if (!enabled) return;
+    const el = containerRef.current;
+    if (!el) return;
+    if (wasNearBottomRef.current) {
+      // "instant" by direct scrollTop write — smooth scroll falls
+      // behind during streaming and the view drifts.
+      el.scrollTop = el.scrollHeight;
+    }
+    // dep is intentionally the only signal that triggers a follow;
+    // it should change whenever the message list grows (length or
+    // the last message's content length).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [dep, enabled]);
+
+  return { containerRef, onScroll, scrollToBottom };
+}