canopy-ui 0.3.0 → 0.4.0

package/src/chat/PresenceChips.tsx

@@ -0,0 +1,52 @@
+import type { Participant } from "./protocol";
+
+interface Props {
+  participants: Participant[];
+  presenceUserIds: number[];
+  draftHolderId: number | null;
+  draftHolderIdle: boolean;
+}
+
+export function PresenceChips({
+  participants,
+  presenceUserIds,
+  draftHolderId,
+  draftHolderIdle,
+}: Props) {
+  const present = participants.filter((p) =>
+    presenceUserIds.includes(p.user_id),
+  );
+  if (present.length === 0) {
+    return <div className="text-sm text-muted-foreground">nobody else here</div>;
+  }
+  return (
+    <div className="flex gap-2">
+      {present.map((p) => {
+        const isHolder = p.user_id === draftHolderId && !draftHolderIdle;
+        return (
+          <div
+            key={p.user_id}
+            title={p.display_name + (isHolder ? " — editing…" : "")}
+            className={`flex h-7 w-7 items-center justify-center rounded-full text-xs font-medium ${
+              isHolder
+                ? "bg-primary text-primary-foreground ring-2 ring-primary/30"
+                : "bg-muted text-muted-foreground"
+            }`}
+          >
+            {initials(p.display_name)}
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+function initials(name: string): string {
+  return name
+    .split(" ")
+    .map((w) => w[0])
+    .filter(Boolean)
+    .join("")
+    .slice(0, 2)
+    .toUpperCase();
+}

package/src/chat/SendBox.tsx

@@ -0,0 +1,144 @@
+import {
+  useEffect,
+  useRef,
+  useState,
+  type KeyboardEvent,
+  type ReactNode,
+} from "react";
+
+import type { Draft } from "./protocol";
+import { isDraftIdle, msUntilDraftIdle } from "./drafts";
+import { Button } from "../ui/button";
+
+interface Props {
+  draft: Draft | null;
+  currentUserId: number;
+  holderIsPresent: boolean;
+  isStreaming: boolean;
+  streamingMessageId: string | null;
+  onUpdate: (body: string) => void;
+  onSend: () => void;
+  onStop: (messageId: string) => void;
+  onTakeOver: () => void;
+  /** Optional app-supplied banner rendered above the composer (e.g. an
+   *  imported-session note). The kit itself has no CLI-auth banners. */
+  banner?: ReactNode;
+  /** When set, sending is disabled and this reason is shown as a hint. */
+  disabledReason?: string;
+}
+
+export function SendBox({
+  draft,
+  currentUserId,
+  holderIsPresent,
+  isStreaming,
+  streamingMessageId,
+  onUpdate,
+  onSend,
+  onStop,
+  onTakeOver,
+  banner,
+  disabledReason,
+}: Props) {
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
+  // Force a re-render when the lock transitions from live to idle.
+  // Without this, nothing would trigger a re-render exactly at T+2s
+  // after the last edit, and another user's UI would stay locked
+  // indefinitely until some unrelated event happens to arrive.
+  const [, forceTick] = useState(0);
+
+  useEffect(() => {
+    if (!draft) return;
+    const remaining = msUntilDraftIdle(draft);
+    if (remaining === 0) return;
+    const t = window.setTimeout(() => forceTick((n) => n + 1), remaining + 10);
+    return () => window.clearTimeout(t);
+  }, [draft?.last_edit_at, draft]);
+
+  const holderId = draft?.last_editor ?? null;
+  const isHolder = holderId != null && holderId === currentUserId;
+  const holderIsIdle = isDraftIdle(draft);
+
+  // Gate on draft existence: during the pre-session.state window the
+  // textarea would otherwise accept keystrokes that silently drop
+  // because the hook's updateDraft no-ops when active_draft is null.
+  const canEdit =
+    draft != null && (isHolder || holderIsIdle || !holderIsPresent);
+
+  useEffect(() => {
+    if (canEdit && !isHolder && textareaRef.current) {
+      textareaRef.current.focus();
+    }
+  }, [canEdit, isHolder]);
+
+  const body = draft?.body ?? "";
+  const blocked = Boolean(disabledReason);
+  const canSend =
+    canEdit && body.trim().length > 0 && !isStreaming && !blocked;
+
+  const handleKey = (e: KeyboardEvent<HTMLTextAreaElement>) => {
+    // `isComposing` is true during IME input (CJK, etc.). Pressing
+    // Enter to commit a composition must not send the message.
+    const isComposing = (e.nativeEvent as unknown as { isComposing?: boolean })
+      .isComposing;
+    if (e.key === "Enter" && !e.shiftKey && !isComposing) {
+      e.preventDefault();
+      if (canSend) onSend();
+    }
+  };
+
+  const handleStopClick = () => {
+    if (streamingMessageId != null) onStop(streamingMessageId);
+  };
+
+  const placeholder = !draft
+    ? "Connecting…"
+    : blocked
+      ? disabledReason
+      : canEdit
+        ? "Type a message… (Enter to send, Shift+Enter for newline)"
+        : "Another teammate is editing…";
+
+  return (
+    <div className="border-t border-border bg-background">
+      {banner}
+      <div className="p-2">
+        <textarea
+          ref={textareaRef}
+          value={body}
+          disabled={!canEdit || blocked}
+          onChange={(e) => onUpdate(e.target.value)}
+          onKeyDown={handleKey}
+          placeholder={placeholder}
+          rows={3}
+          className="w-full resize-none rounded-md border border-input bg-transparent p-2 text-sm text-foreground shadow-sm placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:bg-muted disabled:text-muted-foreground"
+        />
+        <div className="mt-1 flex items-center justify-end gap-2">
+          {blocked && (
+            <span className="mr-auto text-xs text-muted-foreground">
+              {disabledReason}
+            </span>
+          )}
+          {isStreaming ? (
+            <Button
+              type="button"
+              variant="destructive"
+              size="sm"
+              onClick={handleStopClick}
+            >
+              stop
+            </Button>
+          ) : null}
+          {!canEdit && holderIsPresent && !holderIsIdle ? (
+            <Button type="button" variant="outline" size="sm" onClick={onTakeOver}>
+              take over
+            </Button>
+          ) : null}
+          <Button type="button" size="sm" disabled={!canSend} onClick={onSend}>
+            send
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/chat/ToolCallPair.tsx

@@ -0,0 +1,86 @@
+import { Check, ChevronRight, Loader2, X } from "lucide-react";
+
+import type { Message } from "./protocol";
+import { deriveToolStatus, toolDisplayName, toolPreview } from "./pairToolMessages";
+
+interface Props {
+  use: Message;
+  result: Message | null;
+  /** Controlled-open state: true to force open, false to force closed,
+   *  undefined to let the user control via the native <details> toggle. */
+  forceOpen?: boolean;
+}
+
+/**
+ * Renders a tool_use + tool_result as a single collapsible row.
+ *
+ * Header line: ``{status icon} {tool name} · {preview}`` — readable when
+ * collapsed so the user can scan a long stream of tool calls without
+ * expanding any. Expanded view stacks the input JSON on top of the
+ * result body, both monospace.
+ */
+export function ToolCallPair({ use, result, forceOpen }: Props) {
+  const status = deriveToolStatus(use, result);
+  const name = toolDisplayName(use);
+  const preview = toolPreview(use, result);
+
+  const StatusIcon =
+    status.kind === "success" ? Check : status.kind === "error" ? X : Loader2;
+  const iconColor =
+    status.kind === "success"
+      ? "text-success"
+      : status.kind === "error"
+        ? "text-destructive"
+        : "text-muted-foreground animate-spin";
+
+  const input = (use.content as { input?: unknown } | undefined)?.input;
+
+  return (
+    <details
+      // ``open`` controls the row when forceOpen is set; otherwise
+      // ``open={undefined}`` lets the native toggle take over so single
+      // rows still expand/collapse on click.
+      open={forceOpen}
+      className="group my-1 rounded border border-border bg-muted/40 text-sm"
+    >
+      <summary className="flex cursor-pointer items-center gap-2 px-2 py-1.5 text-muted-foreground hover:bg-muted/60 select-none [&::-webkit-details-marker]:hidden">
+        <ChevronRight className="h-3 w-3 shrink-0 transition-transform group-open:rotate-90" />
+        <StatusIcon className={`h-3.5 w-3.5 shrink-0 ${iconColor}`} />
+        <span className="font-mono text-xs font-medium text-foreground">
+          {name}
+        </span>
+        {preview && (
+          <span className="truncate text-xs italic text-muted-foreground">
+            · {preview}
+          </span>
+        )}
+      </summary>
+      <div className="space-y-2 border-t border-border/60 p-2">
+        {input !== undefined && (
+          <div>
+            <div className="mb-1 text-[10px] uppercase tracking-wider text-muted-foreground">
+              input
+            </div>
+            <pre className="overflow-x-auto whitespace-pre-wrap break-all rounded bg-background p-2 text-xs">
+              {JSON.stringify(input, null, 2)}
+            </pre>
+          </div>
+        )}
+        <div>
+          <div className="mb-1 text-[10px] uppercase tracking-wider text-muted-foreground">
+            result
+          </div>
+          {result === null ? (
+            <div className="text-xs italic text-muted-foreground">
+              (running…)
+            </div>
+          ) : (
+            <pre className="overflow-x-auto whitespace-pre-wrap break-all rounded bg-background p-2 text-xs">
+              {result.plaintext}
+            </pre>
+          )}
+        </div>
+      </div>
+    </details>
+  );
+}

package/src/chat/drafts.test.ts

@@ -0,0 +1,66 @@
+import { afterEach, describe, expect, it, vi } from "vitest"
+
+import type { Draft } from "./protocol"
+import { IDLE_THRESHOLD_MS, isDraftIdle, msUntilDraftIdle } from "./drafts"
+
+const NOW = 1_700_000_000_000
+
+function draftEditedAt(msAgo: number): Draft {
+  return {
+    id: "d1",
+    slot: "next",
+    status: "open",
+    body: "",
+    version: 0,
+    last_editor: 1,
+    last_edit_at: new Date(NOW - msAgo).toISOString(),
+  }
+}
+
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+describe("isDraftIdle", () => {
+  it("treats a null/undefined draft as idle", () => {
+    expect(isDraftIdle(null)).toBe(true)
+    expect(isDraftIdle(undefined)).toBe(true)
+  })
+
+  it("treats a draft with no last_edit_at as idle", () => {
+    const d = { ...draftEditedAt(0), last_edit_at: "" }
+    expect(isDraftIdle(d)).toBe(true)
+  })
+
+  it("is NOT idle immediately after an edit", () => {
+    vi.useFakeTimers()
+    vi.setSystemTime(NOW)
+    // edited 500ms ago — well within the 2s threshold
+    expect(isDraftIdle(draftEditedAt(500))).toBe(false)
+  })
+
+  it("IS idle once more than the threshold has elapsed", () => {
+    vi.useFakeTimers()
+    vi.setSystemTime(NOW)
+    expect(isDraftIdle(draftEditedAt(IDLE_THRESHOLD_MS + 1))).toBe(true)
+  })
+})
+
+describe("msUntilDraftIdle", () => {
+  it("returns 0 for a null draft", () => {
+    expect(msUntilDraftIdle(null)).toBe(0)
+  })
+
+  it("returns the remaining time before the idle transition", () => {
+    vi.useFakeTimers()
+    vi.setSystemTime(NOW)
+    // edited 500ms ago → 1500ms remain
+    expect(msUntilDraftIdle(draftEditedAt(500))).toBe(1500)
+  })
+
+  it("clamps to 0 once past the threshold", () => {
+    vi.useFakeTimers()
+    vi.setSystemTime(NOW)
+    expect(msUntilDraftIdle(draftEditedAt(IDLE_THRESHOLD_MS + 5000))).toBe(0)
+  })
+})

package/src/chat/drafts.ts

@@ -0,0 +1,19 @@
+import type { Draft } from "./protocol";
+
+export const IDLE_THRESHOLD_MS = 2_000;
+
+export function isDraftIdle(draft: Draft | null | undefined): boolean {
+  if (!draft?.last_edit_at) return true;
+  return Date.now() - new Date(draft.last_edit_at).getTime() > IDLE_THRESHOLD_MS;
+}
+
+/**
+ * Milliseconds until the draft lock becomes idle. Returns 0 if already
+ * idle. Use this to schedule a timer that forces a re-render at the
+ * idle transition point.
+ */
+export function msUntilDraftIdle(draft: Draft | null | undefined): number {
+  if (!draft?.last_edit_at) return 0;
+  const elapsed = Date.now() - new Date(draft.last_edit_at).getTime();
+  return Math.max(0, IDLE_THRESHOLD_MS - elapsed);
+}

package/src/chat/history.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest"
+import type { Message } from "./protocol"
+import { prependHistory } from "./history"
+
+function msg(turn_index: number, plaintext = `m${turn_index}`): Message {
+  return {
+    id: `t${turn_index}`, turn_index, role: "user", content: {}, plaintext,
+    status: "complete", error_detail: null, started_at: null, completed_at: null,
+    created_at: "",
+  }
+}
+
+describe("prependHistory", () => {
+  it("prepends older messages ahead of current, chronological", () => {
+    const current = [msg(30), msg(31)]
+    const older = [msg(28), msg(29)]
+    expect(prependHistory(current, older).map((m) => m.turn_index)).toEqual([28, 29, 30, 31])
+  })
+
+  it("dedupes on turn_index (an overlapping page is not double-inserted)", () => {
+    const current = [msg(30), msg(31)]
+    const older = [msg(29), msg(30)] // 30 overlaps
+    expect(prependHistory(current, older).map((m) => m.turn_index)).toEqual([29, 30, 31])
+  })
+
+  it("returns the same reference when older is empty", () => {
+    const current = [msg(30)]
+    expect(prependHistory(current, [])).toBe(current)
+  })
+
+  it("returns the same reference when every older row already exists", () => {
+    const current = [msg(30), msg(31)]
+    expect(prependHistory(current, [msg(30)])).toBe(current)
+  })
+})

package/src/chat/history.ts

@@ -0,0 +1,16 @@
+import type { Message } from "./protocol";
+
+/**
+ * Merge an older page (from the REST scroll-back endpoint) into the current
+ * transcript: prepend, dedupe by turn_index, keep chronological. Pure — no React,
+ * no WebSocket — so the container can apply "Load earlier" to the socket's
+ * SessionState without a new WS frame. Returns `current` unchanged (same
+ * reference) when nothing new prepends, so callers can skip a re-render.
+ */
+export function prependHistory(current: Message[], older: Message[]): Message[] {
+  if (older.length === 0) return current;
+  const seen = new Set(current.map((m) => m.turn_index));
+  const fresh = older.filter((m) => !seen.has(m.turn_index));
+  if (fresh.length === 0) return current;
+  return [...fresh, ...current].sort((a, b) => a.turn_index - b.turn_index);
+}

package/src/chat/index.ts

@@ -0,0 +1,56 @@
+// canopy-ui/chat — a reusable, app-agnostic multiplayer chat kit.
+//
+// Speaks the canonical chat WebSocket protocol (ace-web's contract; string
+// ids). App specifics — the ws URL builder, the markdown renderer, session
+// meta — are injected. The presentational tree is props-in / callbacks-out.
+
+// Protocol types
+export type {
+  Message,
+  MessageRole,
+  MessageStatus,
+  Draft,
+  Participant,
+  SessionState,
+  WsAction,
+  WsEvent,
+} from "./protocol";
+
+// Reducer (pure)
+export { sessionReducer } from "./sessionReducer";
+export { prependHistory } from "./history";
+
+// Hooks
+export {
+  useSessionSocket,
+  type UseSessionSocketOptions,
+  type UseSessionSocketResult,
+} from "./useSessionSocket";
+export { useStickyBottom } from "./useStickyBottom";
+
+// Draft idle helpers
+export { IDLE_THRESHOLD_MS, isDraftIdle, msUntilDraftIdle } from "./drafts";
+
+// Tool-message pairing helpers
+export {
+  pairToolMessages,
+  deriveToolStatus,
+  toolPreview,
+  toolDisplayName,
+  type ChatRow,
+  type ToolCallStatus,
+} from "./pairToolMessages";
+
+// Presentational components
+export { ChatPanel, type ChatPanelProps } from "./ChatPanel";
+export { MessageList } from "./MessageList";
+export { MessageItem, type RenderMarkdown } from "./MessageItem";
+export { ToolCallPair } from "./ToolCallPair";
+export { SendBox } from "./SendBox";
+export { PresenceChips } from "./PresenceChips";
+export { ConnectionStatus } from "./ConnectionStatus";
+export {
+  PlacementBanner,
+  type PlacementBannerProps,
+  type PlacementRunner,
+} from "./PlacementBanner";

package/src/chat/pairToolMessages.test.ts

@@ -0,0 +1,208 @@
+import { describe, expect, it } from "vitest";
+
+import type { Message } from "./protocol";
+import {
+  deriveToolStatus,
+  pairToolMessages,
+  toolDisplayName,
+  toolPreview,
+} from "./pairToolMessages";
+
+let seq = 0;
+function msg(
+  partial: Partial<Message> & { id: string; role: Message["role"] },
+): Message {
+  return {
+    turn_index: seq++,
+    content: {},
+    plaintext: "",
+    status: "complete",
+    error_detail: null,
+    started_at: null,
+    completed_at: null,
+    created_at: "2026-05-13T00:00:00Z",
+    ...partial,
+  };
+}
+
+describe("pairToolMessages", () => {
+  it("pairs consecutive tool_use + tool_result by id/tool_use_id", () => {
+    const rows = pairToolMessages([
+      msg({ id: "1", role: "user", plaintext: "hi" }),
+      msg({
+        id: "2",
+        role: "tool_use",
+        content: { id: "t1", name: "Bash", input: { command: "ls" } },
+      }),
+      msg({
+        id: "3",
+        role: "tool_result",
+        content: { tool_use_id: "t1" },
+        plaintext: "out",
+      }),
+      msg({ id: "4", role: "assistant", plaintext: "done" }),
+    ]);
+    expect(rows).toHaveLength(3);
+    expect(rows[0].kind).toBe("message");
+    expect(rows[1].kind).toBe("tool_pair");
+    if (rows[1].kind === "tool_pair") {
+      expect(rows[1].use.id).toBe("2");
+      expect(rows[1].result?.id).toBe("3");
+    }
+    expect(rows[2].kind).toBe("message");
+  });
+
+  it("pairs tool_use with a later non-adjacent tool_result", () => {
+    const rows = pairToolMessages([
+      msg({ id: "1", role: "tool_use", content: { id: "a", name: "X" } }),
+      msg({ id: "2", role: "tool_use", content: { id: "b", name: "Y" } }),
+      msg({ id: "3", role: "tool_result", content: { tool_use_id: "a" } }),
+      msg({ id: "4", role: "tool_result", content: { tool_use_id: "b" } }),
+    ]);
+    expect(rows).toHaveLength(2);
+    expect(rows[0].kind).toBe("tool_pair");
+    expect(rows[1].kind).toBe("tool_pair");
+    if (rows[0].kind === "tool_pair" && rows[1].kind === "tool_pair") {
+      expect(rows[0].use.id).toBe("1");
+      expect(rows[0].result?.id).toBe("3");
+      expect(rows[1].use.id).toBe("2");
+      expect(rows[1].result?.id).toBe("4");
+    }
+  });
+
+  it("leaves an in-flight tool_use with null result so UI can show pending", () => {
+    const rows = pairToolMessages([
+      msg({ id: "1", role: "tool_use", content: { id: "t1", name: "Bash" } }),
+    ]);
+    expect(rows).toHaveLength(1);
+    expect(rows[0].kind).toBe("tool_pair");
+    if (rows[0].kind === "tool_pair") {
+      expect(rows[0].result).toBeNull();
+    }
+  });
+
+  it("falls back to standalone when a tool_result has no matching use", () => {
+    const rows = pairToolMessages([
+      msg({ id: "1", role: "tool_result", content: { tool_use_id: "ghost" } }),
+    ]);
+    expect(rows).toHaveLength(1);
+    expect(rows[0].kind).toBe("message");
+  });
+
+  it("doesn't lose tool calls in long sessions", () => {
+    const msgs: Message[] = [];
+    for (let i = 0; i < 44; i++) {
+      msgs.push(
+        msg({
+          id: `${i * 2 + 1}`,
+          role: "tool_use",
+          content: { id: `t${i}`, name: "Bash" },
+        }),
+      );
+      if (i < 42) {
+        msgs.push(
+          msg({
+            id: `${i * 2 + 2}`,
+            role: "tool_result",
+            content: { tool_use_id: `t${i}` },
+          }),
+        );
+      }
+    }
+    const rows = pairToolMessages(msgs);
+    expect(rows).toHaveLength(44);
+    expect(rows.filter((r) => r.kind === "tool_pair")).toHaveLength(44);
+    // First 42 paired, last 2 pending.
+    const pending = rows.filter(
+      (r) => r.kind === "tool_pair" && r.result === null,
+    );
+    expect(pending).toHaveLength(2);
+  });
+});
+
+describe("deriveToolStatus", () => {
+  it("returns pending when result is missing", () => {
+    const use = msg({ id: "1", role: "tool_use" });
+    expect(deriveToolStatus(use, null).kind).toBe("pending");
+  });
+
+  it("returns error when result is in error status", () => {
+    const use = msg({ id: "1", role: "tool_use" });
+    const result = msg({ id: "2", role: "tool_result", status: "error" });
+    expect(deriveToolStatus(use, result).kind).toBe("error");
+  });
+
+  it("sniffs error-like result content", () => {
+    const use = msg({ id: "1", role: "tool_use" });
+    const result = msg({
+      id: "2",
+      role: "tool_result",
+      plaintext: "Error: file not found",
+    });
+    expect(deriveToolStatus(use, result).kind).toBe("error");
+  });
+
+  it("returns success on a clean result", () => {
+    const use = msg({ id: "1", role: "tool_use" });
+    const result = msg({ id: "2", role: "tool_result", plaintext: "ok" });
+    expect(deriveToolStatus(use, result).kind).toBe("success");
+  });
+});
+
+describe("toolPreview / toolDisplayName", () => {
+  it("shows the first line of a Bash command", () => {
+    const use = msg({
+      id: "1",
+      role: "tool_use",
+      content: {
+        name: "Bash",
+        input: { command: "ls -la /tmp\n# more after newline" },
+      },
+    });
+    expect(toolPreview(use, null)).toBe("ls -la /tmp");
+  });
+
+  it("shows file_path for Read/Write/Edit", () => {
+    for (const name of ["Read", "Write", "Edit"]) {
+      const use = msg({
+        id: "1",
+        role: "tool_use",
+        content: { name, input: { file_path: "/a/b.txt" } },
+      });
+      expect(toolPreview(use, null)).toBe("/a/b.txt");
+    }
+  });
+
+  it("shows the todo count for TodoWrite", () => {
+    const use = msg({
+      id: "1",
+      role: "tool_use",
+      content: {
+        name: "TodoWrite",
+        input: { todos: [{}, {}, {}] },
+      },
+    });
+    expect(toolPreview(use, null)).toBe("3 todos");
+  });
+
+  it("shows the skill name for Skill", () => {
+    const use = msg({
+      id: "1",
+      role: "tool_use",
+      content: { name: "Skill", input: { skill: "ace:run" } },
+    });
+    expect(toolPreview(use, null)).toBe("ace:run");
+  });
+
+  it("strips the mcp prefix for MCP tools", () => {
+    const use = msg({
+      id: "1",
+      role: "tool_use",
+      content: {
+        name: "mcp__plugin_ace_ace-gdrive__drive_create_file",
+        input: {},
+      },
+    });
+    expect(toolDisplayName(use)).toBe("drive_create_file");
+  });
+});