canopy-ui 0.2.0 → 0.4.0

package/src/chat/PlacementBanner.tsx

@@ -0,0 +1,92 @@
+import { useState } from "react";
+
+/** A candidate runner the user may re-place a queued turn onto. */
+export interface PlacementRunner {
+  id: string;
+  name: string;
+  online: boolean;
+}
+
+export interface PlacementBannerProps {
+  /** The bound-but-offline runner's display name. */
+  runnerName: string;
+  /** Alternatives the user may re-place onto (the "Continue on…" picker). */
+  eligibleRunners: PlacementRunner[];
+  /** True while a placement POST is in flight — disables both actions. */
+  busy?: boolean;
+  /** A failure message to surface below the actions (e.g. "no pending
+   *  message to place"). Rendered with destructive styling. */
+  error?: string | null;
+  /** A non-failure status message (e.g. "Placed — the new runner will pick it
+   *  up shortly."). Rendered muted, visually distinct from `error`. */
+  info?: string | null;
+  /** Keep the turn queued for the bound runner to come back online. */
+  onWait: () => void;
+  /** Re-place the turn onto the given runner id. */
+  onPlace: (runnerId: string) => void;
+}
+
+/**
+ * Offline-runner placement banner: the chat session's bound runner has gone
+ * unavailable, and the user must decide whether to wait for it or continue
+ * on a different session-capable runner. Presentational only — NO fetch, NO
+ * WS. The container (canopy's ChatPage) owns the fleet poll, the derived
+ * eligible-runner list, and the placement POST; this component just renders
+ * the decision and forwards the pick.
+ */
+export function PlacementBanner({
+  runnerName,
+  eligibleRunners,
+  busy = false,
+  error,
+  info,
+  onWait,
+  onPlace,
+}: PlacementBannerProps) {
+  // Whether the "Continue on…" picker is expanded — purely local UI state,
+  // not fetch-driven, so it lives in the kit rather than round-tripping
+  // through the container.
+  const [showPicker, setShowPicker] = useState(false);
+
+  return (
+    <div className="flex flex-wrap items-center gap-2 border-b border-warning/30 bg-warning/10 px-4 py-2 text-[12px] text-warning">
+      <span className="font-medium">{runnerName} is unavailable</span>
+      <button
+        type="button"
+        onClick={onWait}
+        disabled={busy}
+        className="rounded-md border border-warning/40 px-2 py-0.5 text-warning hover:bg-warning/20 disabled:opacity-50"
+      >
+        Wait for it
+      </button>
+      <button
+        type="button"
+        onClick={() => setShowPicker((v) => !v)}
+        disabled={busy}
+        className="rounded-md border border-warning/40 px-2 py-0.5 text-warning hover:bg-warning/20 disabled:opacity-50"
+      >
+        Continue on…
+      </button>
+      {showPicker && (
+        <select
+          defaultValue=""
+          disabled={busy}
+          onChange={(e) => onPlace(e.target.value)}
+          className="rounded-md border border-warning/40 bg-card px-1.5 py-0.5 text-[12px] text-foreground disabled:opacity-50"
+          aria-label="Continue on"
+        >
+          <option value="" disabled>
+            Choose a runner…
+          </option>
+          {eligibleRunners.map((r) => (
+            <option key={r.id} value={r.id}>
+              {r.online ? "●" : "○"} {r.name}
+            </option>
+          ))}
+        </select>
+      )}
+      {error && <span className="text-destructive">{error}</span>}
+      {info && <span className="text-muted-foreground">{info}</span>}
+    </div>
+  );
+}

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";