@m6d/cortex-react 1.0.0

package/src/components/LlmUsageChips.tsx

@@ -0,0 +1,37 @@
+import type { TokenUsage } from '@cortex/contracts/wire';
+import { cachePercent } from '@cortex/client';
+import { num } from '../format';
+
+type LlmUsageChipsProps = {
+  usage: TokenUsage;
+};
+
+/**
+ * The one-line token summary on a collapsed LLM request: in, out, and how much of
+ * the input came from cache.
+ */
+export function LlmUsageChips({ usage }: LlmUsageChipsProps) {
+  const percent = cachePercent(usage);
+
+  // The outer span stands in for Angular's <cortex-llm-usage-chips> host: as
+  // the flex item it keeps the metrics span itself out of flex-item
+  // blockification (display and auto-margin resolution differ otherwise).
+  return (
+    <span>
+      <span className="cortex-llm-inspector__step-metrics">
+        <span className="cortex-llm-inspector__metric">
+          <span className="cortex-llm-inspector__dot cortex-llm-inspector__dot--input"></span>
+          {num(usage.input.total)}
+        </span>
+        <span className="cortex-llm-inspector__metric">
+          <span className="cortex-llm-inspector__dot cortex-llm-inspector__dot--output"></span>
+          {num(usage.output.total)}
+        </span>
+        {/* Not a truthiness check: a genuine 0% is falsy and would silently vanish. */}
+        {percent !== null ? (
+          <span className="cortex-llm-inspector__cache-pct">{percent}%</span>
+        ) : null}
+      </span>
+    </span>
+  );
+}

package/src/components/Message.tsx

@@ -0,0 +1,81 @@
+import type { UIMessage } from '@tanstack/ai';
+import { isHiddenInAnimatedMode, newestAssistantMessage } from '@cortex/client';
+import { useCortex } from '../context';
+import { MessageAbortedFlag } from './MessageAbortedFlag';
+import { MessageAttachments } from './MessageAttachments';
+import { MessageLlmInspector } from './MessageLlmInspector';
+import { MessagePart } from './MessagePart';
+import { MessageTokenUsage } from './MessageTokenUsage';
+
+type MessageProps = {
+  message: UIMessage;
+  debugMode?: boolean;
+  animate?: boolean;
+};
+
+export function Message(props: MessageProps) {
+  const { message, debugMode = false, animate = false } = props;
+  const { messages, isAgentWorking, messageMetadata } = useCortex();
+
+  const isStreaming = isAgentWorking && newestAssistantMessage(messages)?.id === message.id;
+  const isAssistant = message.role === 'assistant';
+
+  const parts = message.parts;
+  const visibleParts = parts.filter((part, index) => {
+    // A tool result is already rendered as the outcome of the call it answers.
+    if (part.type === 'tool-result') return false;
+
+    return debugMode || !isHiddenInAnimatedMode(part, index === parts.length - 1, isStreaming);
+  });
+
+  /** Only a streaming message's last part can still be receiving text. */
+  const streamingPartIndex = isStreaming ? visibleParts.length - 1 : -1;
+
+  /**
+   * Usage, model id, the aborted flag and attachments are cortex's own envelope
+   * around the SDK's message rather than fields on it, so they are looked up by
+   * id against the transcript the server served.
+   */
+  const metadata = messageMetadata.get(message.id);
+  const isAborted = Boolean(metadata?.isAborted);
+  const tokenUsage = metadata?.tokenUsage;
+  const attachments = message.role === 'user' ? (metadata?.attachments ?? []) : [];
+
+  /**
+   * The debug strip only makes sense once the message has settled, and only where
+   * there is something to show: usage figures, or an assistant turn whose LLM
+   * requests can be inspected.
+   */
+  const showsDebugZone = debugMode && !isStreaming && (Boolean(tokenUsage) || isAssistant);
+
+  return (
+    <div className="cortex-message">
+      {visibleParts.length > 0 && (
+        <div className="cortex-message-parts">
+          {visibleParts.map((part, index) => (
+            <MessagePart
+              key={index}
+              part={part}
+              message={message}
+              debugMode={debugMode}
+              animate={animate}
+              streaming={index === streamingPartIndex}
+            />
+          ))}
+
+          {attachments.length > 0 && <MessageAttachments attachments={attachments} />}
+
+          {isAborted && <MessageAbortedFlag />}
+
+          {showsDebugZone && (
+            <div className="cortex-message-debug-zone">
+              {tokenUsage && <MessageTokenUsage usage={tokenUsage} modelId={metadata?.modelId} />}
+
+              {isAssistant && <MessageLlmInspector messageId={message.id} />}
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/MessageAbortedFlag.tsx

@@ -0,0 +1,29 @@
+import { useCortex } from '../context';
+
+export function MessageAbortedFlag() {
+  const { t } = useCortex();
+
+  return (
+    <div className="cortex-aborted-flag">
+      <span className="cortex-aborted-flag__line" />
+      <span className="cortex-aborted-flag__label">
+        <svg
+          className="cortex-aborted-flag__icon"
+          width="12"
+          height="12"
+          viewBox="0 0 12 12"
+          fill="none"
+        >
+          <path
+            d="M6 1.5v5M6 8.75v.5"
+            stroke="currentColor"
+            strokeWidth="1.4"
+            strokeLinecap="round"
+          />
+        </svg>
+        {t('translate_aborted')}
+      </span>
+      <span className="cortex-aborted-flag__line" />
+    </div>
+  );
+}

package/src/components/MessageAttachments.tsx

@@ -0,0 +1,55 @@
+import type { AttachmentSummary } from '@cortex/contracts/wire';
+import { saveBlob } from '@cortex/client';
+import { useCortex } from '../context';
+
+type MessageAttachmentsProps = {
+  attachments: AttachmentSummary[];
+};
+
+/** The files a user message was sent with, as recorded by the server. */
+export function MessageAttachments(props: MessageAttachmentsProps) {
+  const { api, t } = useCortex();
+
+  async function download(id: string) {
+    const { blob, name } = await api.downloadAttachment(id);
+    saveBlob(blob, name);
+  }
+
+  return (
+    <div className="cortex-message-attachments">
+      {props.attachments.map((attachment) => (
+        <button
+          key={attachment.id}
+          type="button"
+          onClick={() => void download(attachment.id)}
+          className="cortex-message-attachment"
+          aria-label={`${t('translate_download')}: ${attachment.filename}`}
+        >
+          <svg viewBox="0 0 16 16" className="cortex-message-attachment__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-message-attachment__name">{attachment.filename}</span>
+          <svg viewBox="0 0 16 16" className="cortex-message-attachment__dl-icon" fill="none">
+            <path
+              d="M8 3v7m0 0L5.5 7.5M8 10l2.5-2.5M3 13h10"
+              stroke="currentColor"
+              strokeWidth="1.5"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+            />
+          </svg>
+        </button>
+      ))}
+    </div>
+  );
+}

package/src/components/MessageList.tsx

@@ -0,0 +1,102 @@
+import { useEffect, useRef, useState } from 'react';
+import { useCortex } from '../context';
+import { Message } from './Message';
+
+type MessageListProps = {
+  className?: string;
+  debugMode: boolean;
+};
+
+export function MessageList(props: MessageListProps) {
+  const { messages, selectedThread } = useCortex();
+
+  const containerRef = useRef<HTMLDivElement>(null);
+  const shouldScrollToBottom = useRef(true);
+  const isNearBottom = useRef(true);
+  const scrollToBottomQueued = useRef(false);
+  const [animateNewParts, setAnimateNewParts] = useState(false);
+
+  function scrollToBottom() {
+    const el = containerRef.current;
+    if (el) el.scrollTop = el.scrollHeight;
+  }
+
+  function scheduleScrollToBottom() {
+    if (scrollToBottomQueued.current) return;
+
+    scrollToBottomQueued.current = true;
+
+    queueMicrotask(() => {
+      scrollToBottomQueued.current = false;
+      scrollToBottom();
+      shouldScrollToBottom.current = false;
+    });
+  }
+
+  useEffect(() => {
+    const el = containerRef.current;
+    scheduleScrollToBottom();
+    setAnimateNewParts(true);
+
+    if (!el || typeof MutationObserver === 'undefined') return;
+
+    const observer = new MutationObserver(() => {
+      if (!shouldScrollToBottom.current && !isNearBottom.current) return;
+
+      scheduleScrollToBottom();
+    });
+
+    observer.observe(el, { childList: true, subtree: true, characterData: true });
+
+    return () => observer.disconnect();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // There is no event bus here, so selecting a thread IS Angular's
+  // `onThreadSelected`: the transcript it loads arrives unanimated.
+  const threadId = selectedThread?.id;
+  useEffect(() => {
+    setAnimateNewParts(false);
+    shouldScrollToBottom.current = true;
+    queueMicrotask(() => setAnimateNewParts(true));
+  }, [threadId]);
+
+  // ...and a message appearing under the user's name IS `onSend`.
+  const lastMessage = messages[messages.length - 1];
+  const lastUserMessageId = lastMessage?.role === 'user' ? lastMessage.id : undefined;
+  useEffect(() => {
+    if (lastUserMessageId) shouldScrollToBottom.current = true;
+  }, [lastUserMessageId]);
+
+  useEffect(() => {
+    if (!shouldScrollToBottom.current && !isNearBottom.current) return;
+
+    scheduleScrollToBottom();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [messages]);
+
+  function onScroll() {
+    const el = containerRef.current;
+    if (!el) return;
+    isNearBottom.current = el.scrollHeight - el.scrollTop - el.clientHeight < 100;
+  }
+
+  // Two nested elements on purpose: Angular's host carried the widget's
+  // `cortex-widget__messages` (flex sizing, overflow hidden) around the
+  // scrolling `cortex-message-list`. Merging them would stack conflicting
+  // overflow rules on one node.
+  return (
+    <div className={props.className}>
+      <div ref={containerRef} className="cortex-message-list" onScroll={onScroll}>
+        {messages.map((message) => (
+          <Message
+            key={message.id}
+            message={message}
+            debugMode={props.debugMode}
+            animate={animateNewParts}
+          />
+        ))}
+      </div>
+    </div>
+  );
+}

package/src/components/MessageLlmInspector.tsx

@@ -0,0 +1,184 @@
+import { useRef, useState } from 'react';
+import { parseJsonText, prettyJsonText, type LlmRequest } from '@cortex/client';
+import { useCortex } from '../context';
+import { cx } from '../cx';
+import { CopyButton } from './CopyButton';
+import { JsonTree } from './JsonTree';
+import { LlmUsageBreakdown } from './LlmUsageBreakdown';
+import { LlmUsageChips } from './LlmUsageChips';
+
+type MessageLlmInspectorProps = {
+  messageId: string;
+};
+
+export function MessageLlmInspector({ messageId }: MessageLlmInspectorProps) {
+  const { t, api } = useCortex();
+
+  const [open, setOpen] = useState(false);
+  const [loading, setLoading] = useState(false);
+  const [requests, setRequests] = useState<LlmRequest[]>([]);
+  const [expandedStep, setExpandedStep] = useState<string | null>(null);
+  const [activeTab, setActiveTab] = useState<Record<string, 'prompt' | 'response'>>({});
+
+  const loaded = useRef(false);
+
+  async function toggle() {
+    if (!loaded.current) {
+      setLoading(true);
+      try {
+        setRequests(await api.listLlmRequests(messageId));
+      } finally {
+        setLoading(false);
+        loaded.current = true;
+      }
+    }
+
+    setOpen((v) => !v);
+  }
+
+  function toggleStep(id: string) {
+    setExpandedStep((current) => (current === id ? null : id));
+  }
+
+  function getTab(id: string) {
+    return activeTab[id] ?? 'prompt';
+  }
+
+  function setTab(id: string, tab: 'prompt' | 'response') {
+    setActiveTab((current) => ({ ...current, [id]: tab }));
+  }
+
+  return (
+    <div className={cx('cortex-llm-inspector', open && 'cortex-llm-inspector--open')}>
+      <button className="cortex-llm-inspector__trigger" onClick={() => void toggle()}>
+        <svg
+          className="cortex-llm-inspector__icon"
+          width="14"
+          height="14"
+          viewBox="0 0 16 16"
+          fill="none"
+        >
+          <path
+            d="M6 2a4 4 0 1 0 0 8 4 4 0 0 0 0-8ZM0 6a6 6 0 1 1 10.89 3.477l4.817 4.816a1 1 0 0 1-1.414 1.414l-4.816-4.816A6 6 0 0 1 0 6Z"
+            fill="currentColor"
+          />
+        </svg>
+        <span>{t('translate_inspect_llm_requests')}</span>
+
+        {loading ? (
+          <span className="cortex-llm-inspector__loading">{t('translate_loading')}</span>
+        ) : requests.length > 0 ? (
+          <span className="cortex-llm-inspector__badge">{requests.length}</span>
+        ) : null}
+
+        <svg
+          className="cortex-llm-inspector__chevron"
+          width="12"
+          height="12"
+          viewBox="0 0 12 12"
+          fill="none"
+        >
+          <path
+            d="M3 4.5L6 7.5L9 4.5"
+            stroke="currentColor"
+            strokeWidth="1.25"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+          />
+        </svg>
+      </button>
+
+      <div className="cortex-llm-inspector__panel-wrapper">
+        <div className="cortex-llm-inspector__panel-inner">
+          <div className="cortex-llm-inspector__panel">
+            {requests.length === 0 && !loading ? (
+              <div className="cortex-llm-inspector__empty">{t('translate_no_llm_requests')}</div>
+            ) : null}
+
+            {requests.map((req, idx) => (
+              <div
+                key={req.id}
+                className={cx(
+                  'cortex-llm-inspector__step',
+                  expandedStep === req.id && 'cortex-llm-inspector__step--expanded',
+                )}
+              >
+                <button
+                  className="cortex-llm-inspector__step-header"
+                  onClick={() => toggleStep(req.id)}
+                >
+                  <span className="cortex-llm-inspector__step-label">
+                    {t('translate_step_n', { number: idx + 1 })}
+                  </span>
+
+                  {req.tokenUsage ? <LlmUsageChips usage={req.tokenUsage} /> : null}
+
+                  <svg
+                    className="cortex-llm-inspector__step-chevron"
+                    width="10"
+                    height="10"
+                    viewBox="0 0 12 12"
+                    fill="none"
+                  >
+                    <path
+                      d="M3 4.5L6 7.5L9 4.5"
+                      stroke="currentColor"
+                      strokeWidth="1.25"
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                    />
+                  </svg>
+                </button>
+
+                <div className="cortex-llm-inspector__step-body-wrapper">
+                  <div className="cortex-llm-inspector__step-body-inner">
+                    <div className="cortex-llm-inspector__step-body">
+                      {req.tokenUsage ? <LlmUsageBreakdown usage={req.tokenUsage} /> : null}
+
+                      <div className="cortex-llm-inspector__tabs">
+                        <button
+                          className={cx(
+                            'cortex-llm-inspector__tab',
+                            getTab(req.id) === 'prompt' && 'cortex-llm-inspector__tab--active',
+                          )}
+                          onClick={() => setTab(req.id, 'prompt')}
+                        >
+                          {t('translate_request')}
+                        </button>
+                        <button
+                          className={cx(
+                            'cortex-llm-inspector__tab',
+                            getTab(req.id) === 'response' && 'cortex-llm-inspector__tab--active',
+                          )}
+                          onClick={() => setTab(req.id, 'response')}
+                        >
+                          {t('translate_response')}
+                        </button>
+                      </div>
+
+                      <div className="cortex-llm-inspector__json-pane">
+                        <CopyButton
+                          className="cortex-llm-inspector__json-copy"
+                          value={
+                            getTab(req.id) === 'prompt'
+                              ? prettyJsonText(req.prompt)
+                              : prettyJsonText(req.output)
+                          }
+                        />
+                        {getTab(req.id) === 'prompt' ? (
+                          <JsonTree data={parseJsonText(req.prompt)} expandDepth={2} />
+                        ) : (
+                          <JsonTree data={parseJsonText(req.output)} expandDepth={2} />
+                        )}
+                      </div>
+                    </div>
+                  </div>
+                </div>
+              </div>
+            ))}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/MessagePart.tsx

@@ -0,0 +1,54 @@
+import type { MessagePart as MessagePartData, UIMessage } from '@tanstack/ai';
+import { useCortex } from '../context';
+import { cx } from '../cx';
+import { MessageReasoningAnimated } from './MessageReasoningAnimated';
+import { MessageReasoningPart } from './MessageReasoningPart';
+import { MessageTextPart } from './MessageTextPart';
+import { MessageToolCallPart } from './MessageToolCallPart';
+import { ToolAnimation } from './ToolAnimation';
+
+type MessagePartProps = {
+  message: UIMessage;
+  part: MessagePartData;
+  debugMode?: boolean;
+  animate?: boolean;
+  /** A part carries no state of its own, so being live is decided by position. */
+  streaming?: boolean;
+};
+
+export function MessagePart(props: MessagePartProps) {
+  const { message, part, debugMode = false, animate = false, streaming = false } = props;
+  const { t } = useCortex();
+
+  function renderPart() {
+    switch (part.type) {
+      case 'text':
+        return <MessageTextPart textPart={part} role={message.role} streaming={streaming} />;
+      case 'thinking':
+        return debugMode ? (
+          <MessageReasoningPart reasoningPart={part} streaming={streaming} />
+        ) : (
+          <MessageReasoningAnimated />
+        );
+      case 'tool-call':
+        return debugMode ? (
+          <MessageToolCallPart toolCallPart={part} />
+        ) : (
+          <ToolAnimation toolCallPart={part} message={message} />
+        );
+      default:
+        // A part kind this widget does not know how to draw.
+        return (
+          <p className="cortex-unhandled-type">
+            {t('translate_unhandled_type')} {part.type}
+          </p>
+        );
+    }
+  }
+
+  return (
+    <div className={cx('cortex-message-part', animate && 'cortex-message-part--animated')}>
+      {renderPart()}
+    </div>
+  );
+}

package/src/components/MessageReasoningAnimated.tsx

@@ -0,0 +1,12 @@
+import { activityLabelKeys } from '@cortex/client';
+import { SubtleActivity } from './SubtleActivity';
+
+const LABELS = activityLabelKeys('reasoning');
+
+export function MessageReasoningAnimated() {
+  return (
+    <div className="cortex-reasoning-animated">
+      <SubtleActivity labels={LABELS} />
+    </div>
+  );
+}

package/src/components/MessageReasoningPart.tsx

@@ -0,0 +1,76 @@
+import type { ThinkingPart } from '@tanstack/ai';
+import { useCortex } from '../context';
+import { cx } from '../cx';
+
+type MessageReasoningPartProps = {
+  reasoningPart: ThinkingPart;
+  streaming?: boolean;
+};
+
+export function MessageReasoningPart(props: MessageReasoningPartProps) {
+  const { reasoningPart, streaming = false } = props;
+  const { t } = useCortex();
+
+  return (
+    <details className="cortex-reasoning-details">
+      <summary className="cortex-reasoning-details__summary">
+        <div className="cortex-reasoning-details__header">
+          <span className="cortex-reasoning-details__icon">
+            <svg width="14" height="14" viewBox="0 0 20 20" fill="none" aria-hidden="true">
+              <path
+                d="M10 2C6.686 2 4 4.686 4 8c0 1.655.672 3.154 1.757 4.243.362.363.576.858.576 1.371V14.5a1 1 0 0 0 1 1h5.334a1 1 0 0 0 1-1v-.886c0-.513.214-1.008.576-1.371A5.978 5.978 0 0 0 16 8c0-3.314-2.686-6-6-6Z"
+                stroke="currentColor"
+                strokeWidth="1.4"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+              />
+              <path
+                d="M7.5 17.5h5M8.5 8a2 2 0 0 1 2-2"
+                stroke="currentColor"
+                strokeWidth="1.4"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+              />
+            </svg>
+          </span>
+
+          <div className="cortex-reasoning-details__title-group">
+            <div className="cortex-reasoning-details__title-row">
+              <div className="cortex-reasoning-details__title">{t('translate_reasoning')}</div>
+              <span
+                className={cx(
+                  'cortex-reasoning-details__badge',
+                  streaming
+                    ? 'cortex-reasoning-details__badge--streaming'
+                    : 'cortex-reasoning-details__badge--done',
+                )}
+              >
+                {streaming ? 'Streaming' : 'Done'}
+              </span>
+            </div>
+          </div>
+        </div>
+
+        <span className="cortex-reasoning-details__chevron" aria-hidden="true">
+          <svg width="14" height="14" viewBox="0 0 20 20" fill="none">
+            <path
+              d="m5.75 8.25 4.25 4.25 4.25-4.25"
+              stroke="currentColor"
+              strokeWidth="1.5"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+            />
+          </svg>
+        </span>
+      </summary>
+
+      <div className="cortex-reasoning-details__body">
+        <div className="cortex-reasoning-details__content">
+          <pre className="cortex-reasoning-details__pre">
+            {reasoningPart.content.trim() ? reasoningPart.content : 'No reasoning provided.'}
+          </pre>
+        </div>
+      </div>
+    </details>
+  );
+}