@m6d/cortex-react 1.0.0

package/src/components/CortexChatWidget.tsx

@@ -0,0 +1,538 @@
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
+import {
+  applyWsEvent,
+  attachmentQueueFlags,
+  createAttachmentQueue,
+  createCortexApiClient,
+  createCortexSocket,
+  removeThread,
+  sortThreads,
+  translate,
+  upsertThread,
+  type MountMode,
+} from '@cortex/client';
+import type { AttachmentSummary, ThreadSummary, WsEvent } from '@cortex/contracts/wire';
+import {
+  ChatSession,
+  type PendingSend,
+  type SessionHandle,
+  type SessionPatch,
+  type SessionUi,
+} from '../chat-session';
+import type { CortexReactConfig } from '../config';
+import { CortexContext, type CortexContextValue } from '../context';
+import { cx } from '../cx';
+import { ChatComposer, type ChatComposerHandle } from './ChatComposer';
+import { MessageList } from './MessageList';
+import { ThreadList } from './ThreadList';
+
+const initialSessionUi = {
+  messages: [],
+  isAgentWorking: false,
+  isLoadingMessages: false,
+  hasPendingToolCalls: false,
+  messageMetadata: new Map<string, never>(),
+} satisfies SessionUi;
+
+type MountedSession = { thread: ThreadSummary; mode: MountMode; epoch: number };
+
+// fallow-ignore-next-line complexity -- 1:1 transcription of the Angular source; restructuring would risk parity drift
+export function CortexChatWidget({
+  config,
+  className,
+}: {
+  config: CortexReactConfig;
+  /** Sizing classes for the host, like the classes on Angular's widget element. */
+  className?: string;
+}) {
+  const configRef = useRef(config);
+  configRef.current = config;
+
+  const [threads, setThreads] = useState<ThreadSummary[]>();
+  const [session, setSession] = useState<MountedSession>();
+  const [sessionUi, setSessionUi] = useState<SessionUi>(initialSessionUi);
+  const [debugMode, setDebugMode] = useState(false);
+  const [screen, setScreen] = useState<'threads' | 'chat'>('threads');
+  const [sidebarOpen, setSidebarOpen] = useState(false);
+
+  const sessionRef = useRef<SessionHandle | undefined>(undefined);
+  const pendingSendRef = useRef<PendingSend[]>([]);
+  const pendingThreadCreation = useRef<Promise<string> | undefined>(undefined);
+  const composerRef = useRef<ChatComposerHandle | null>(null);
+
+  const api = useMemo(() => createCortexApiClient(() => configRef.current.transport), []);
+
+  /**
+   * Selection is the thread handed to `selectThread`, resolved against the live
+   * list: the row there receives the title and isRunning updates the server
+   * pushes, so the selection follows them without hand-syncing. The snapshot
+   * only answers for a thread the list has not caught up with yet.
+   */
+  const selectedThread = useMemo(() => {
+    const snapshot = session?.thread;
+    if (!snapshot) return undefined;
+
+    return threads?.find((thread) => thread.id === snapshot.id) ?? snapshot;
+  }, [threads, session]);
+
+  const selectedThreadRef = useRef(selectedThread);
+  selectedThreadRef.current = selectedThread;
+  const sessionUiRef = useRef(sessionUi);
+  sessionUiRef.current = sessionUi;
+
+  const patchUi = useCallback((patch: SessionPatch) => {
+    setSessionUi((previous) => ({
+      ...previous,
+      ...(typeof patch === 'function' ? patch(previous) : patch),
+    }));
+  }, []);
+
+  const setRunning = useCallback((threadId: string, isRunning: boolean) => {
+    setThreads((current) => {
+      const thread = current?.find((candidate) => candidate.id === threadId);
+      return thread ? upsertThread(current ?? [], { ...thread, isRunning }) : current;
+    });
+  }, []);
+
+  const selectThread = useCallback(
+    (thread: ThreadSummary, options?: { skipLoadingMessages?: boolean }) => {
+      if (selectedThreadRef.current?.id === thread.id && sessionRef.current) return;
+
+      const previous = selectedThreadRef.current;
+      // Eager, not render-synced: a caller in the same tick (a second file in a
+      // multi-file drop, a queued send) must already see the selection.
+      selectedThreadRef.current = thread;
+      setSessionUi(initialSessionUi);
+      setSession({ thread, mode: options?.skipLoadingMessages ? 'skip' : 'load', epoch: 0 });
+
+      if (previous && previous.id !== thread.id) {
+        void configRef.current.hooks?.onThreadDeselected?.(previous);
+      }
+      void configRef.current.hooks?.onThreadSelected?.(thread);
+    },
+    [],
+  );
+
+  const deselectThread = useCallback(() => {
+    const previous = selectedThreadRef.current;
+    if (!previous && !sessionRef.current) return;
+
+    selectedThreadRef.current = undefined;
+    setSession(undefined);
+    setSessionUi(initialSessionUi);
+
+    if (previous) {
+      void configRef.current.hooks?.onThreadDeselected?.(previous);
+    }
+  }, []);
+
+  const remountSession = useCallback(
+    (thread: ThreadSummary) => {
+      // Like Angular's mountChat: a re-mount starts with a clean envelope and no
+      // owed tool calls; hydration brings the current ones back.
+      patchUi({ hasPendingToolCalls: false, messageMetadata: new Map() });
+      setSession((current) => ({ thread, mode: 'reload', epoch: (current?.epoch ?? 0) + 1 }));
+    },
+    [patchUi],
+  );
+
+  /**
+   * The id of the thread the next message belongs to, creating it when the
+   * widget is still on a blank chat. `prompt` only seeds the generated title.
+   * Resolved once for concurrent callers so a multi-file drop onto a blank chat
+   * does not race several thread creations against each other.
+   */
+  const ensureThread = useCallback(
+    (prompt?: string) => {
+      const selected = selectedThreadRef.current;
+      if (selected) return Promise.resolve(selected.id);
+
+      pendingThreadCreation.current ??= api.createThread(prompt).then(
+        (thread) => {
+          pendingThreadCreation.current = undefined;
+          setThreads((current) => upsertThread(current ?? [], thread));
+          selectThread(thread, { skipLoadingMessages: true });
+          return thread.id;
+        },
+        (error: unknown) => {
+          pendingThreadCreation.current = undefined;
+          throw error;
+        },
+      );
+      return pendingThreadCreation.current;
+    },
+    [api, selectThread],
+  );
+
+  const queueStore = useMemo(
+    () => createAttachmentQueue({ api, ensureThread: () => ensureThread() }),
+    [api, ensureThread],
+  );
+  const queueItems = useSyncExternalStore(
+    queueStore.subscribe,
+    queueStore.getState,
+    queueStore.getState,
+  );
+
+  const send = useCallback(
+    async (prompt: string, attachments: AttachmentSummary[] = []) => {
+      if (sessionUiRef.current.isAgentWorking || sessionUiRef.current.hasPendingToolCalls) return;
+
+      const handle = sessionRef.current;
+      if (handle) {
+        await handle.send(prompt, attachments);
+        return;
+      }
+
+      // Blank chat: the message goes out with the session the new thread
+      // mounts. A queue, not a slot — a second send racing the same creation
+      // must not overwrite the first.
+      pendingSendRef.current.push({ prompt, attachments });
+      try {
+        await ensureThread(prompt);
+      } catch (error) {
+        // A failed creation must not leave messages behind to replay into
+        // whatever thread mounts next.
+        pendingSendRef.current = [];
+        throw error;
+      }
+    },
+    [ensureThread],
+  );
+
+  const abort = useCallback(async () => {
+    await sessionRef.current?.abort();
+  }, []);
+
+  const addToolResult = useCallback((toolCallId: string, toolName: string, output: unknown) => {
+    sessionRef.current?.addToolResult(toolCallId, toolName, output);
+  }, []);
+
+  const deleteThread = useCallback(
+    async (threadId: string) => {
+      if (selectedThreadRef.current?.id === threadId) deselectThread();
+
+      await api.deleteThread(threadId);
+      setThreads((current) => (current ? removeThread(current, threadId) : current));
+    },
+    [api, deselectThread],
+  );
+
+  const onTurnFinished = useCallback(() => {
+    queueStore.discardConsumed();
+    setTimeout(() => composerRef.current?.focusInput());
+  }, [queueStore]);
+
+  const onSendFailed = useCallback(() => {
+    queueStore.restoreConsumed(selectedThreadRef.current?.id);
+  }, [queueStore]);
+
+  const reloadThreads = useCallback(async () => {
+    const listed = sortThreads(await api.listThreads());
+    setThreads(listed);
+    return listed;
+  }, [api]);
+
+  const handleWsEvent = useCallback(
+    (event: WsEvent) => {
+      setThreads((current) => {
+        const next = applyWsEvent(current ?? [], event);
+        // Before the first reload lands the list is still undefined (the loading
+        // skeleton); only an event that actually adds something may materialize it.
+        return current || next.length ? next : current;
+      });
+
+      const selectedId = selectedThreadRef.current?.id;
+      switch (event.type) {
+        case 'thread:deleted':
+          if (selectedId === event.payload.threadId) deselectThread();
+          break;
+        case 'thread:run-started':
+          // The payload rather than the list: the state update absorbing this
+          // event into the list has not been rendered yet.
+          if (selectedId === event.payload.thread.id) {
+            sessionRef.current?.reattach(event.payload.thread);
+          }
+          break;
+        case 'thread:messages-updated':
+          sessionRef.current?.refreshMessages(event.payload.threadId);
+          break;
+      }
+    },
+    [deselectThread],
+  );
+
+  useEffect(() => {
+    void reloadThreads();
+
+    // The first open is startup; only a socket that comes back marks a gap.
+    let openedOnce = false;
+    const socket = createCortexSocket({
+      // Thunks so every (re)connection attempt reads the config current then.
+      wsUrl: () => configRef.current.wsUrl,
+      transport: {
+        baseUrl: () => {
+          const baseUrl = configRef.current.transport.baseUrl;
+          return typeof baseUrl === 'string' ? baseUrl : baseUrl();
+        },
+        getHeaders: () => configRef.current.transport.getHeaders(),
+      },
+      onEvent: handleWsEvent,
+      onOpen: () => {
+        if (!openedOnce) {
+          openedOnce = true;
+          return;
+        }
+        // Anything could have happened while the socket was down, so the thread
+        // list is re-read from the server, and re-attaching sees the open
+        // thread's current `isRunning` to decide whether there is a run to tail.
+        void reloadThreads().then((listed) => {
+          const selected = selectedThreadRef.current;
+          if (!selected) return;
+
+          sessionRef.current?.reattach(
+            listed.find((thread) => thread.id === selected.id) ?? selected,
+          );
+        });
+      },
+    });
+
+    return () => {
+      socket.close();
+    };
+  }, [handleWsEvent, reloadThreads]);
+
+  // Leaving a thread abandons the files queued for it.
+  const previousThreadId = useRef<string | undefined>(undefined);
+  const selectedThreadId = selectedThread?.id;
+  useEffect(() => {
+    if (selectedThreadId === previousThreadId.current) return;
+
+    queueStore.clear(previousThreadId.current);
+    previousThreadId.current = selectedThreadId;
+  }, [selectedThreadId, queueStore]);
+
+  const locale = config.locale ?? 'en';
+  const t = useCallback(
+    (key: string, params?: Record<string, string | number>) => translate(locale, key, params),
+    [locale],
+  );
+
+  const viewMode = config.viewMode ?? 'helper';
+
+  const contextValue = {
+    config,
+    t,
+    api,
+    debugMode,
+    threads,
+    selectedThread,
+    deleteThread,
+    ...sessionUi,
+    send,
+    abort,
+    addToolResult,
+    queue: {
+      items: queueItems,
+      ...attachmentQueueFlags(queueItems),
+      accept: queueStore.accept,
+      remove: queueStore.remove,
+      consumeReady: queueStore.consumeReady,
+    },
+  } satisfies CortexContextValue;
+
+  function openThread(thread: ThreadSummary) {
+    selectThread(thread);
+    setScreen('chat');
+    setSidebarOpen(false);
+  }
+
+  function newChat() {
+    deselectThread();
+    setScreen('chat');
+    setSidebarOpen(false);
+  }
+
+  function goBack() {
+    deselectThread();
+    setScreen('threads');
+  }
+
+  return (
+    <CortexContext.Provider value={contextValue}>
+      <div className={cx('cortex-widget', className)} data-cortex-theme={config.theme}>
+        <div
+          className={cx(
+            'cortex-widget__container',
+            viewMode === 'full' && 'cortex-widget__container--full',
+            sidebarOpen && 'cortex-widget__container--sidebar-open',
+          )}
+          onDragOver={(event) => event.preventDefault()}
+          onDrop={(event) => event.preventDefault()}
+        >
+          {/* SCREEN 1: THREADS */}
+          <ThreadList
+            className={cx(
+              'cortex-widget__screen',
+              screen === 'threads' && 'cortex-widget__screen--active',
+              screen !== 'threads' && 'cortex-widget__screen--left',
+            )}
+            onThreadSelected={openThread}
+            onNewChatRequested={newChat}
+          />
+
+          {/* SCREEN 2: CHAT */}
+          <div
+            className={cx(
+              'cortex-widget__screen',
+              screen === 'chat' && 'cortex-widget__screen--active',
+              screen !== 'chat' && 'cortex-widget__screen--right',
+            )}
+          >
+            <div className="cortex-widget__chat-header">
+              {/* Sidebar toggle (full mode, small screens) */}
+              <button
+                onClick={() => setSidebarOpen((open) => !open)}
+                className="cortex-widget__sidebar-toggle-btn"
+              >
+                <svg width="16" height="16" viewBox="0 0 16 16" fill="none">
+                  <path
+                    d="M2.5 4h11M2.5 8h11M2.5 12h11"
+                    stroke="currentColor"
+                    strokeWidth="1.4"
+                    strokeLinecap="round"
+                  />
+                </svg>
+              </button>
+
+              {/* Back button */}
+              <button onClick={goBack} className="cortex-widget__back-btn">
+                <svg
+                  width="14"
+                  height="14"
+                  viewBox="0 0 16 16"
+                  fill="none"
+                  className="cortex-widget__back-icon"
+                >
+                  <path
+                    d="M10 3L5 8l5 5"
+                    stroke="currentColor"
+                    strokeWidth="1.5"
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                  />
+                </svg>
+              </button>
+
+              <div className="cortex-widget__chat-title-wrap">
+                <p className="cortex-widget__chat-title">
+                  {selectedThread?.title ?? t('translate_new_chat')}
+                </p>
+              </div>
+
+              {config.showDebugButton && (
+                <button
+                  onClick={() => setDebugMode((mode) => !mode)}
+                  className={cx(
+                    'cortex-widget__debug-btn',
+                    debugMode ? 'cortex-widget__debug-btn--on' : 'cortex-widget__debug-btn--off',
+                  )}
+                >
+                  {debugMode ? t('translate_debug') : t('translate_normal')}
+                </button>
+              )}
+            </div>
+
+            {sessionUi.isLoadingMessages && !sessionUi.isAgentWorking ? (
+              <div className="cortex-widget__messages-skeleton">
+                <div className="cortex-widget__msg-skel cortex-widget__msg-skel--user">
+                  <div className="cortex-widget__msg-skel-bubble cortex-widget__msg-skel-bubble--user">
+                    <div
+                      className="cortex-skeleton cortex-widget__msg-skel-line"
+                      style={{ width: '13rem' }}
+                    />
+                    <div
+                      className="cortex-skeleton cortex-widget__msg-skel-line"
+                      style={{ width: '9rem' }}
+                    />
+                  </div>
+                </div>
+                <div className="cortex-widget__msg-skel cortex-widget__msg-skel--assistant">
+                  <div className="cortex-widget__msg-skel-bubble cortex-widget__msg-skel-bubble--assistant">
+                    <div
+                      className="cortex-skeleton cortex-widget__msg-skel-line"
+                      style={{ width: '16rem' }}
+                    />
+                    <div
+                      className="cortex-skeleton cortex-widget__msg-skel-line"
+                      style={{ width: '18rem' }}
+                    />
+                    <div
+                      className="cortex-skeleton cortex-widget__msg-skel-line"
+                      style={{ width: '12rem' }}
+                    />
+                  </div>
+                </div>
+                <div className="cortex-widget__msg-skel cortex-widget__msg-skel--user">
+                  <div className="cortex-widget__msg-skel-bubble cortex-widget__msg-skel-bubble--user">
+                    <div
+                      className="cortex-skeleton cortex-widget__msg-skel-line"
+                      style={{ width: '11rem' }}
+                    />
+                  </div>
+                </div>
+                <div className="cortex-widget__msg-skel cortex-widget__msg-skel--assistant">
+                  <div className="cortex-widget__msg-skel-bubble cortex-widget__msg-skel-bubble--assistant">
+                    <div
+                      className="cortex-skeleton cortex-widget__msg-skel-line"
+                      style={{ width: '14rem' }}
+                    />
+                    <div
+                      className="cortex-skeleton cortex-widget__msg-skel-line"
+                      style={{ width: '15rem' }}
+                    />
+                  </div>
+                </div>
+              </div>
+            ) : (
+              <MessageList className="cortex-widget__messages" debugMode={debugMode} />
+            )}
+
+            {sessionUi.isAgentWorking && !sessionUi.hasPendingToolCalls && (
+              <div className="cortex-widget__working">
+                <div className="cortex-widget__working-dots">
+                  <span className="cortex-working-dot" />
+                  <span className="cortex-working-dot" />
+                  <span className="cortex-working-dot" />
+                </div>
+                <span className="cortex-widget__working-text">{t('translate_thinking')}</span>
+              </div>
+            )}
+
+            {!sessionUi.hasPendingToolCalls && <ChatComposer ref={composerRef} />}
+          </div>
+
+          {/* Sidebar overlay backdrop (full mode, small screens) */}
+          <div className="cortex-widget__sidebar-backdrop" onClick={() => setSidebarOpen(false)} />
+        </div>
+
+        {session && (
+          <ChatSession
+            key={`${session.thread.id}:${session.epoch}`}
+            thread={session.thread}
+            mode={session.mode}
+            api={api}
+            configRef={configRef}
+            sessionRef={sessionRef}
+            pendingSendRef={pendingSendRef}
+            patchUi={patchUi}
+            setRunning={setRunning}
+            remount={remountSession}
+            onTurnFinished={onTurnFinished}
+            onSendFailed={onSendFailed}
+          />
+        )}
+      </div>
+    </CortexContext.Provider>
+  );
+}

package/src/components/JsonTree.tsx

@@ -0,0 +1,111 @@
+import { useMemo, useState } from 'react';
+import type { MouseEvent } from 'react';
+import { deepParseJson, describeJsonValue } from '@cortex/client';
+import { cx } from '../cx';
+
+type JsonTreeProps = {
+  data: unknown;
+  expandDepth?: number;
+  className?: string;
+};
+
+export function JsonTree({ data, expandDepth = 1, className }: JsonTreeProps) {
+  /** Memoized: the tree renders recursively, so parsing per pass would redo the
+   *  whole document on every render. */
+  const parsedData = useMemo(() => deepParseJson(data), [data]);
+
+  /** Until the reader touches a node, its state follows expandDepth. */
+  const [userToggled, setUserToggled] = useState<Record<string, boolean | undefined>>({});
+
+  function isCollapsed(path: string, depth: number) {
+    return userToggled[path] ?? depth >= expandDepth;
+  }
+
+  function toggle(path: string, depth: number) {
+    setUserToggled((current) => ({ ...current, [path]: !isCollapsed(path, depth) }));
+  }
+
+  return (
+    <div className={cx('cortex-json-tree', className)}>
+      <JsonValue value={parsedData} path="$" depth={0} isCollapsed={isCollapsed} toggle={toggle} />
+    </div>
+  );
+}
+
+type JsonValueProps = {
+  value: unknown;
+  path: string;
+  depth: number;
+  isCollapsed: (path: string, depth: number) => boolean;
+  toggle: (path: string, depth: number) => void;
+};
+
+/**
+ * Recursive renderer. Every value goes through describeJsonValue(), so objects,
+ * arrays and primitives all arrive in one shape and this needs a single set of
+ * branches rather than one per container kind.
+ */
+function JsonValue({ value, path, depth, isCollapsed, toggle }: JsonValueProps) {
+  const node = describeJsonValue(value, path);
+
+  if (node.kind === 'primitive') return <span className={node.className}>{node.text}</span>;
+
+  if (node.entries.length === 0) {
+    return (
+      <span className="jt-bracket">
+        {node.open}
+        {node.close}
+      </span>
+    );
+  }
+
+  const collapsed = isCollapsed(path, depth);
+
+  function onToggle(event: MouseEvent<HTMLSpanElement>) {
+    toggle(path, depth);
+    event.stopPropagation();
+  }
+
+  return (
+    <>
+      <span className="jt-toggle" onClick={onToggle} role="button">
+        <span className={cx('jt-arrow', collapsed && 'jt-arrow--collapsed')}>▾</span>
+        <span className="jt-bracket">{node.open}</span>
+      </span>
+
+      {collapsed ? (
+        <>
+          <span className="jt-collapsed-hint" onClick={onToggle} role="button">
+            {node.summary}
+          </span>
+          <span className="jt-bracket">{node.close}</span>
+        </>
+      ) : (
+        <>
+          <div className="jt-indent">
+            {node.entries.map((entry, index) => (
+              // One line of a container: its key if it has one, its value, and a separating comma.
+              <div className="jt-line" key={entry.path}>
+                {entry.key !== null && (
+                  <>
+                    <span className="jt-key">{`"${entry.key}"`}</span>
+                    <span className="jt-colon">{': '}</span>
+                  </>
+                )}
+                <JsonValue
+                  value={entry.value}
+                  path={entry.path}
+                  depth={depth + 1}
+                  isCollapsed={isCollapsed}
+                  toggle={toggle}
+                />
+                {index < node.entries.length - 1 && <span className="jt-comma">,</span>}
+              </div>
+            ))}
+          </div>
+          <span className="jt-bracket">{node.close}</span>
+        </>
+      )}
+    </>
+  );
+}

package/src/components/LlmUsageBreakdown.tsx

@@ -0,0 +1,42 @@
+import type { TokenUsage } from '@cortex/contracts/wire';
+import { useCortex } from '../context';
+import { num } from '../format';
+
+type LlmUsageBreakdownProps = {
+  usage: TokenUsage;
+};
+
+/**
+ * The expanded token accounting for one LLM request: where the input came from,
+ * what the output was spent on, and the total.
+ */
+export function LlmUsageBreakdown({ usage }: LlmUsageBreakdownProps) {
+  const { t } = useCortex();
+
+  return (
+    <div className="cortex-llm-inspector__usage-rows">
+      <div className="cortex-llm-inspector__usage-row">
+        <span className="cortex-llm-inspector__usage-lbl">{t('translate_input')}</span>
+        <span className="cortex-llm-inspector__usage-val">{num(usage.input.total)}</span>
+        <span className="cortex-llm-inspector__usage-detail">
+          {t('translate_fresh')} {num(usage.input.noCache)} &middot; {t('translate_read')}{' '}
+          {num(usage.input.cacheRead)} &middot; {t('translate_write')} {num(usage.input.cacheWrite)}
+        </span>
+      </div>
+
+      <div className="cortex-llm-inspector__usage-row">
+        <span className="cortex-llm-inspector__usage-lbl">{t('translate_output')}</span>
+        <span className="cortex-llm-inspector__usage-val">{num(usage.output.total)}</span>
+        <span className="cortex-llm-inspector__usage-detail">
+          {t('translate_text')} {num(usage.output.text)} &middot; {t('translate_reasoning')}{' '}
+          {num(usage.output.reasoning)}
+        </span>
+      </div>
+
+      <div className="cortex-llm-inspector__usage-row cortex-llm-inspector__usage-row--total">
+        <span className="cortex-llm-inspector__usage-lbl">{t('translate_total')}</span>
+        <span className="cortex-llm-inspector__usage-val">{num(usage.total)}</span>
+      </div>
+    </div>
+  );
+}