@m6d/cortex-react 1.0.0

package/dist/theme.css

@@ -0,0 +1,69 @@
+/* fallow-ignore-file code-duplication -- deliberately restates styles/_theme.scss: the whole point of this file is the full token set in one place */
+/*
+ * Theming surface.
+ *
+ * Every value below is the widget's own default, restated here so the full set is
+ * discoverable in one place — the same declarations already ship inside cortex.css,
+ * so importing this file changes nothing until you edit it. Override any token on
+ * :root, or on any ancestor of the widget, to retheme it.
+ *
+ * Each color is a light-dark() pair. Which side applies follows the widget root's
+ * color-scheme, set by the `theme` config option ('light' | 'dark' | 'system').
+ * The radius and font tokens below the colors are plain values — neither depends
+ * on the scheme.
+ */
+:root {
+  --cortex-color-surface: light-dark(#ffffff, #0a0a0a);
+  --cortex-color-surface-subtle: light-dark(#f8fafc, #141414);
+  --cortex-color-surface-muted: light-dark(#f1f5f9, #1f1f1f);
+
+  --cortex-color-border: light-dark(#e2e8f0, #2e2e2e);
+  --cortex-color-border-strong: light-dark(#cbd5e1, #444444);
+
+  --cortex-color-text-heading: light-dark(#1e293b, #fafafa);
+  --cortex-color-text-strong: light-dark(#334155, #e5e5e5);
+  --cortex-color-text: light-dark(#475569, #d4d4d4);
+  --cortex-color-text-secondary: light-dark(#64748b, #a3a3a3);
+  --cortex-color-text-muted: light-dark(#94a3b8, #737373);
+
+  --cortex-color-primary: light-dark(#1e293b, #fafafa);
+  --cortex-color-primary-foreground: light-dark(#ffffff, #0a0a0a);
+  --cortex-color-accent: light-dark(#4f46e5, #818cf8);
+  --cortex-color-accent-surface: light-dark(#e0e7ff, #312e81);
+  --cortex-color-link: light-dark(#2563eb, #60a5fa);
+  --cortex-color-hover: light-dark(rgba(0, 0, 0, 0.05), rgba(255, 255, 255, 0.06));
+
+  /* User messages default to the same subtle surface every other quiet panel
+   * uses, split out so a consumer can give their own side of the chat a color
+   * without touching anything else. */
+  --cortex-color-user-surface: var(--cortex-color-surface-subtle);
+  --cortex-color-user-border: var(--cortex-color-border);
+
+  --cortex-color-success: light-dark(#059669, #34d399);
+  --cortex-color-success-surface: light-dark(#ecfdf5, #064e3b);
+  --cortex-color-success-border: light-dark(#d1fae5, #065f46);
+  --cortex-color-danger: light-dark(#dc2626, #f87171);
+  --cortex-color-danger-surface: light-dark(#fef2f2, #450a0a);
+  --cortex-color-danger-border: light-dark(#fecaca, #7f1d1d);
+
+  /* The corner scale every rounded surface derives from: the widget multiplies
+   * this by 0.5/0.75/1.5/2, so overriding it rescales all of them together. */
+  --cortex-radius: 0.5rem;
+
+  --cortex-font-mono: var(
+    --default-mono-font-family,
+    ui-monospace,
+    SFMono-Regular,
+    Menlo,
+    Monaco,
+    Consolas,
+    monospace
+  );
+  --cortex-font-size: 0.8125rem;
+
+  /* The widget's headings read --cortex-font-display and fall back to `inherit`,
+   * so it ships unset on purpose — declaring it here is how you opt in:
+   *
+   * --cortex-font-display: 'Your Display Face', sans-serif;
+   */
+}

package/index.ts

@@ -0,0 +1,17 @@
+/*
+ * Public API Surface of cortex-react — mirrors cortex-angular's public-api.ts.
+ */
+
+// Config
+export type { CortexReactConfig, CortexToolComponentProps } from './src/config';
+export type {
+  CortexHooks,
+  CortexTheme,
+  CortexToolCall,
+  CortexToolCallContext,
+  CortexTransport,
+  CortexViewMode,
+} from '@cortex/client';
+
+// Components
+export { CortexChatWidget } from './src/components/CortexChatWidget';

package/package.json

@@ -0,0 +1,67 @@
+{
+    "name": "@m6d/cortex-react",
+    "version": "1.0.0",
+    "description": "React chat widget SDK for cortex servers",
+    "license": "MIT",
+    "sideEffects": [
+        "dist/*.css"
+    ],
+    "type": "module",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "bun": "./index.ts",
+            "import": "./dist/index.js",
+            "default": "./dist/index.js"
+        },
+        "./styles.css": "./dist/styles.css",
+        "./theme.css": "./dist/theme.css"
+    },
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "files": [
+        "dist",
+        "src",
+        "!src/**/*.test.ts",
+        "!src/**/*.test.tsx",
+        "theme.css",
+        "index.ts",
+        "README.md"
+    ],
+    "scripts": {
+        "build": "bash scripts/build.sh",
+        "check": "tsc --noEmit"
+    },
+    "devDependencies": {
+        "@cortex/client": "workspace:*",
+        "@cortex/contracts": "workspace:*",
+        "@m6d/prettier-config": "workspace:*",
+        "@m6d/tsconfig": "workspace:*",
+        "@tanstack/ai": "^0.43.1",
+        "@tanstack/ai-client": "^0.23.1",
+        "@tanstack/ai-react": "^0.19.1",
+        "@types/bun": "latest",
+        "@types/react": "^19",
+        "@types/react-dom": "^19",
+        "dompurify": "^3.3.3",
+        "dts-bundle-generator": "^9.5.1",
+        "highlight.js": "^11.11.1",
+        "marked": "^17.0.4",
+        "react": "^19.2.0",
+        "sass": "^1.83.0",
+        "typescript": "~5.9.3"
+    },
+    "peerDependencies": {
+        "@tanstack/ai": "^0.43.1",
+        "@tanstack/ai-client": "^0.23.1",
+        "@tanstack/ai-react": "^0.19.1",
+        "dompurify": "^3.0.0",
+        "highlight.js": "^11.0.0",
+        "marked": "^17.0.0",
+        "react": ">=18",
+        "react-dom": ">=18"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}

package/src/chat-session.tsx

@@ -0,0 +1,379 @@
+import { useEffect, useLayoutEffect, useMemo, useRef } from 'react';
+import type { ToolCallPart, UIMessage } from '@tanstack/ai';
+import { useChat } from '@tanstack/ai-react';
+import {
+  createCortexConnection,
+  metadataByMessageId,
+  settleTurn,
+  unansweredToolCalls,
+  type CortexApiClient,
+  type MountMode,
+} from '@cortex/client';
+import type { AttachmentSummary, MessageMetadata, ThreadSummary } from '@cortex/contracts/wire';
+import type { CortexHooks } from '@cortex/client';
+import type { CortexReactConfig } from './config';
+
+export type SessionUi = {
+  messages: UIMessage[];
+  isAgentWorking: boolean;
+  isLoadingMessages: boolean;
+  hasPendingToolCalls: boolean;
+  /**
+   * The per-message facts the SDK's `UIMessage` has no room for — usage, model
+   * id, the aborted flag, attachments. They are cortex's own envelope around the
+   * stored parts, so they arrive with the persisted transcript rather than over
+   * the stream, and are merged back in by message id at render time.
+   */
+  messageMetadata: ReadonlyMap<string, MessageMetadata>;
+};
+
+export type SessionPatch = Partial<SessionUi> | ((previous: SessionUi) => Partial<SessionUi>);
+
+export type PendingSend = { prompt: string; attachments: AttachmentSummary[] };
+
+/** The imperative face the widget keeps of the mounted session. */
+export type SessionHandle = {
+  threadId: string;
+  send: (prompt: string, attachments: AttachmentSummary[]) => Promise<void>;
+  abort: () => Promise<void>;
+  addToolResult: (toolCallId: string, toolName: string, output: unknown) => void;
+  reattach: (thread: ThreadSummary) => void;
+  refreshMessages: (threadId: string) => void;
+};
+
+type ChatSessionProps = {
+  thread: ThreadSummary;
+  mode: MountMode;
+  api: CortexApiClient;
+  configRef: { current: CortexReactConfig };
+  sessionRef: { current: SessionHandle | undefined };
+  /** Sends that arrived while no session was mounted; consumed in order on mount. */
+  pendingSendRef: { current: PendingSend[] };
+  patchUi: (patch: SessionPatch) => void;
+  setRunning: (threadId: string, isRunning: boolean) => void;
+  /** Remounts this session in `reload` mode so hydration re-reads the transcript
+   *  and re-attaches to whatever run is live now. */
+  remount: (thread: ThreadSummary) => void;
+  onTurnFinished: () => void;
+  onSendFailed: () => void;
+};
+
+/**
+ * The headless per-thread chat driver — CortexChatService's turn lifecycle
+ * around the SDK's `useChat`. It renders nothing: its state is lifted into the
+ * widget's context so the composer (which must keep its draft across thread
+ * switches) and the message list live outside the remount boundary. The
+ * `key={threadId}:{epoch}` the widget renders it under IS the per-thread
+ * lifetime — remounting replaces Angular's environment-injector dance.
+ */
+// fallow-ignore-next-line complexity -- 1:1 transcription of the Angular source; restructuring would risk parity drift
+export function ChatSession(props: ChatSessionProps) {
+  const { thread, api, patchUi } = props;
+
+  const alive = useRef(true);
+  /**
+   * Whether this widget is driving the run it is showing or watching one another
+   * tab started. A watcher owes nothing: the tool calls it sees belong to the tab
+   * that sent the message, and how the turn ended is the server's to tell it.
+   */
+  const ownsRun = useRef(false);
+  /**
+   * Whether the server has answered the turn in flight. Until it does, a failure
+   * means the message never got out and the composer takes back the files it was
+   * carrying; after it, those files are on the message the server stored.
+   */
+  const serverAnswered = useRef(false);
+  const wasAborted = useRef(false);
+  const wasWorking = useRef(false);
+  const dispatchedToolCalls = useRef(new Set<string>());
+  const refreshing = useRef(Promise.resolve());
+
+  // Created once per mount: `useChat` captures the connection at client
+  // creation, and a new mount is exactly what a re-hydration needs.
+  const connection = useMemo(
+    () =>
+      createCortexConnection({
+        api,
+        thread: { id: thread.id, isRunning: thread.isRunning },
+        mode: props.mode,
+        onHydrated: (rows, messages) => {
+          if (!alive.current) return;
+
+          patchUi({
+            messageMetadata: metadataByMessageId(rows),
+            hasPendingToolCalls: unansweredToolCalls(messages).length > 0,
+          });
+        },
+        setLoadingMessages: (loading) => {
+          if (alive.current) patchUi({ isLoadingMessages: loading });
+        },
+      }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [],
+  );
+
+  const chat = useChat({
+    threadId: thread.id,
+    persistence: true,
+    connection,
+    // Both guarded: the SDK disposes a replaced client a macrotask after
+    // unmount, so a dead session's callbacks can still fire into the new one.
+    onChunk: () => {
+      if (!alive.current) return;
+      serverAnswered.current = true;
+    },
+    onError: () => {
+      if (!alive.current) return;
+      patchUi({ hasPendingToolCalls: false });
+      // A failure only means the message never went while the server has said
+      // nothing at all. Once it has answered it holds the message, and the
+      // files it claimed are on it — reporting that as a failed send would
+      // offer the composer files it can no longer send.
+      if (serverAnswered.current) props.onTurnFinished();
+      else props.onSendFailed();
+    },
+  });
+
+  const chatRef = useRef(chat);
+  chatRef.current = chat;
+  const isLoadingRef = useRef(chat.isLoading);
+  isLoadingRef.current = chat.isLoading;
+
+  function syncPendingToolCalls() {
+    const pending = unansweredToolCalls(chatRef.current.messages);
+    patchUi({ hasPendingToolCalls: pending.length > 0 });
+    return pending;
+  }
+
+  async function resolveToolCall(
+    call: ToolCallPart,
+    onToolCall: NonNullable<CortexHooks['onToolCall']>,
+  ) {
+    const result = onToolCall(
+      { toolCallId: call.id, toolName: call.name, input: call.input },
+      { threadId: thread.id },
+    );
+    if (result === null || result === undefined) return;
+
+    const output = await Promise.resolve(result);
+    if (output === null || output === undefined) return;
+    // The hook is free to take its time, and the thread may have moved on since.
+    if (!alive.current) return;
+
+    await chatRef.current.addToolResult({ toolCallId: call.id, tool: call.name, output });
+    syncPendingToolCalls();
+  }
+
+  /**
+   * Hands the calls the run left open to the consumer's hook — cortex's tools all
+   * run on the server, so anything still unanswered when the stream ends is one
+   * the client was asked to resolve. Reports whether any are still waiting.
+   */
+  function dispatchPendingToolCalls() {
+    const pending = syncPendingToolCalls();
+    const onToolCall = props.configRef.current.hooks?.onToolCall;
+    if (!onToolCall) return pending.length > 0;
+
+    for (const call of pending) {
+      // Anything short of complete arguments is a call the model never finished
+      // asking for — `input` is not parsed until then, so there is nothing to
+      // hand over. It still counts as pending; it is just not answerable.
+      if (call.state !== 'input-complete') continue;
+      if (dispatchedToolCalls.current.has(call.id)) continue;
+
+      dispatchedToolCalls.current.add(call.id);
+      void resolveToolCall(call, onToolCall);
+    }
+
+    return pending.length > 0;
+  }
+
+  async function readBackMessages(threadId: string) {
+    if (!alive.current || threadId !== thread.id) return;
+
+    await settleTurn({
+      api,
+      threadId,
+      isStale: () => !alive.current,
+      isStreaming: () => isLoadingRef.current,
+      absorbMetadata: (metadata) => patchUi({ messageMetadata: metadata }),
+      setMessages: (messages) => {
+        chatRef.current.setMessages(messages);
+        patchUi({ hasPendingToolCalls: unansweredToolCalls(messages).length > 0 });
+      },
+    });
+  }
+
+  function refreshMessages(threadId: string) {
+    // Queued rather than deduplicated: a refresh asked for while one is in
+    // flight is asking about a newer state — the commit that has just landed —
+    // so it has to follow that one rather than be dropped in favour of it.
+    refreshing.current = refreshing.current.then(() => readBackMessages(threadId));
+    return refreshing.current;
+  }
+
+  /**
+   * A finished stream leaves the SDK holding only what came over the wire, while
+   * usage, model id and attachments live in cortex's envelope — so a settled turn
+   * is read back from the database. The one turn that is not read back is one
+   * this widget is still in the middle of: a tool call it owes an answer to.
+   */
+  async function settleSession() {
+    // Cancelling is the one exit that does not wait for the server: the turn
+    // settles on the thread:messages-updated event the commit sends, not here.
+    if (wasAborted.current) {
+      wasAborted.current = false;
+      return;
+    }
+
+    if (ownsRun.current && dispatchPendingToolCalls()) return;
+
+    await refreshMessages(thread.id);
+  }
+
+  async function performSend(prompt: string, attachments: AttachmentSummary[]) {
+    props.setRunning(thread.id, true);
+    ownsRun.current = true;
+    serverAnswered.current = false;
+
+    const message = {
+      id: crypto.randomUUID(),
+      role: 'user',
+      parts: [{ type: 'text', content: prompt }],
+    } satisfies UIMessage;
+
+    // The server claims the thread's pending attachments for this message and
+    // serves them back on it; recording them now only saves the round trip.
+    if (attachments.length) {
+      patchUi((previous) => ({
+        messageMetadata: new Map(previous.messageMetadata).set(message.id, { attachments }),
+      }));
+    }
+
+    await chatRef.current.append(message);
+  }
+
+  async function abort() {
+    if (!isLoadingRef.current) return;
+
+    // Ask the server first: the stop button can outlive the run, and an abort
+    // that found nothing to abort must not be presented as one. Only a confirmed
+    // abort suppresses the settle-time read-back — the unconfirmed path falls
+    // through to it and pulls the truthful committed turn.
+    const { aborted } = await api.abortStream(thread.id).catch(() => ({ aborted: false }));
+    // The selection can move while the request is out; a late answer about
+    // another thread must not poison the one selected now.
+    if (!alive.current) return;
+
+    if (aborted) {
+      wasAborted.current = true;
+      props.setRunning(thread.id, false);
+    }
+
+    chatRef.current.stop();
+    patchUi({ hasPendingToolCalls: false });
+  }
+
+  /** Answers a tool call on behalf of a consumer-supplied tool component. */
+  function addToolResult(toolCallId: string, toolName: string, output: unknown) {
+    void chatRef.current
+      .addToolResult({ toolCallId, tool: toolName, output })
+      .then(() => syncPendingToolCalls());
+  }
+
+  function reattach(freshThread: ThreadSummary) {
+    if (isLoadingRef.current) return;
+
+    // Only a live run needs a new client: joining one is something only a mount
+    // can do. With nothing to join, re-reading the transcript in place leaves
+    // the conversation on screen instead of tearing it down for a round trip.
+    if (freshThread.isRunning) {
+      props.remount(freshThread);
+      return;
+    }
+
+    void refreshMessages(freshThread.id);
+  }
+
+  useEffect(() => {
+    alive.current = true;
+    return () => {
+      alive.current = false;
+    };
+  }, []);
+
+  // The widget's imperative face. One stable object per mount whose methods are
+  // refreshed every render, registered in a layout effect: on a key remount the
+  // replaced instance's cleanup runs before the new instance registers, and the
+  // identity check keeps it from wiping a registration that is not its own.
+  const handleRef = useRef<SessionHandle | undefined>(undefined);
+  handleRef.current = {
+    threadId: thread.id,
+    send: performSend,
+    abort,
+    addToolResult,
+    reattach,
+    refreshMessages: (threadId) => {
+      void refreshMessages(threadId);
+    },
+  };
+  useLayoutEffect(() => {
+    props.sessionRef.current = handleRef.current;
+  });
+  useLayoutEffect(() => {
+    return () => {
+      if (props.sessionRef.current === handleRef.current) {
+        props.sessionRef.current = undefined;
+      }
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // Sends that were waiting for a thread to exist go out with this mount.
+  // Deferred a tick and cancelled on cleanup: under StrictMode the first,
+  // throwaway mount's client is disposed right after the effect runs, so a
+  // synchronous drain would tie the send to a client whose stream is already
+  // aborted. Leaving the queue untouched until the timer fires also hands it
+  // to the next mount if this one is torn down first.
+  useEffect(() => {
+    if (!props.pendingSendRef.current.length) return;
+
+    const timer = setTimeout(() => {
+      const pending = props.pendingSendRef.current;
+      props.pendingSendRef.current = [];
+      void (async () => {
+        for (const { prompt, attachments } of pending) {
+          await performSend(prompt, attachments);
+        }
+      })();
+    });
+    return () => clearTimeout(timer);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  useEffect(() => {
+    patchUi({ messages: chat.messages });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [chat.messages]);
+
+  // The end of a turn is the client falling idle, not the SDK's onFinish: the
+  // agent loop ends a run per iteration, so onFinish fires while the turn is
+  // still going. Both the tool hand-off and the refetch wait for the whole
+  // exchange.
+  useEffect(() => {
+    patchUi({ isAgentWorking: chat.isLoading });
+
+    if (chat.isLoading) {
+      wasWorking.current = true;
+      return;
+    }
+    if (!wasWorking.current) return;
+
+    wasWorking.current = false;
+    props.onTurnFinished();
+    void settleSession();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [chat.isLoading]);
+
+  return null;
+}

package/src/components/AttachmentQueue.tsx

@@ -0,0 +1,75 @@
+import { useCortex } from '../context';
+import { cx } from '../cx';
+
+export function AttachmentQueue() {
+  const { queue, t } = useCortex();
+
+  if (!queue.items.length) return null;
+
+  return (
+    <div className="cortex-attachment-queue">
+      {queue.items.map((item) => (
+        <div
+          key={item.localId}
+          className={cx(
+            'cortex-attachment-chip',
+            item.status === 'error' && 'cortex-attachment-chip--error',
+          )}
+          title={item.status === 'error' ? t('translate_attachment_rejected') : ''}
+        >
+          {item.status === 'uploading' || item.status === 'deleting' ? (
+            <svg className="cortex-attachment-chip__spinner" viewBox="0 0 16 16" fill="none">
+              <circle
+                cx="8"
+                cy="8"
+                r="6"
+                stroke="currentColor"
+                strokeWidth="2"
+                className="cortex-attachment-chip__spinner-track"
+              />
+              <path
+                d="M14 8a6 6 0 0 0-6-6"
+                stroke="currentColor"
+                strokeWidth="2"
+                strokeLinecap="round"
+              />
+            </svg>
+          ) : (
+            <svg viewBox="0 0 16 16" className="cortex-attachment-chip__icon" fill="none">
+              <path
+                d="M4 1.5h5.172a2 2 0 0 1 1.414.586l2.328 2.328a2 2 0 0 1 .586 1.414V12.5a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2v-9a2 2 0 0 1 2-2Z"
+                stroke="currentColor"
+                strokeWidth="1.25"
+              />
+              <path
+                d="M9.5 1.5v2a2 2 0 0 0 2 2h2"
+                stroke="currentColor"
+                strokeWidth="1.25"
+                strokeLinecap="round"
+              />
+            </svg>
+          )}
+
+          <span className="cortex-attachment-chip__name">{item.filename}</span>
+
+          <button
+            type="button"
+            onClick={() => queue.remove(item.localId)}
+            className="cortex-attachment-chip__remove"
+            disabled={item.status === 'deleting'}
+            aria-label={t('translate_remove_attachment')}
+          >
+            <svg viewBox="0 0 16 16" fill="none">
+              <path
+                d="M4.5 4.5l7 7m0-7l-7 7"
+                stroke="currentColor"
+                strokeWidth="1.5"
+                strokeLinecap="round"
+              />
+            </svg>
+          </button>
+        </div>
+      ))}
+    </div>
+  );
+}