@m6d/cortex-react 0.11.0 → 0.12.0

package/README.md

@@ -1,6 +1,6 @@
 # @m6d/cortex-react
 
-React chat widget for cortex servers: streaming messages, tool call visualization, composer attachments, syntax highlighting, and i18n. Same features and pixel parity as `@m6d/cortex-angular`.
+React chat widget for Cortex agents: streaming messages, tool call visualization, composer attachments, syntax highlighting, and i18n. `@m6d/cortex-angular` is the same widget for Angular.
 
 ## Usage
 
@@ -12,7 +12,7 @@ import '@m6d/cortex-react/theme.css';
 const config = {
   locale: 'en',
   transport: {
-    baseUrl: '/api/agents/assistant',
+    baseUrl: 'https://engine.cortex.example.com/agents/support',
     getHeaders: () => ({ Authorization: `Bearer ${token}` }),
   },
 } satisfies CortexReactConfig;
@@ -22,16 +22,40 @@ export function Chat() {
 }
 ```
 
-`CortexReactConfig` is the shared `CortexConfig` plus a React-only `toolComponents` field (`Record<string, ComponentType<CortexToolComponentInputs>>`). Every other property, the client tools flow, and the media blocks are documented in [`packages/cortex-angular/README.md`](../cortex-angular/README.md); only the `toolComponents` and `injector` rows are Angular-specific.
+`baseUrl` is the agent's URL: the engine's public origin (`ENGINE_PUBLIC_URL`) plus `/agents/<agent slug>`. Add the page's origin to `ENGINE_CORS_ORIGINS`, or proxy the engine under your own origin as the samples do. The WebSocket URL is `baseUrl` plus `/ws`; set `wsUrl` only to override it, and point it at that same agent-scoped path. The bearer is the end user's token, which Cortex verifies the way the agent's auth says: a JWKS, a shared secret, the agent's server, or nobody for an anonymous agent.
+
+Each widget is self-contained, so one page can render several widgets with different configs. `className` sizes the widget's root element.
+
+## Configuration
+
+`CortexReactConfig` is the shared `CortexConfig` plus one React-only field, `toolComponents`.
+
+| Property                   | Type                                                       | Description                                                                     |
+| -------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| `locale`                   | `'en' \| 'ar'`                                             | Active locale (default: `'en'`)                                                 |
+| `transport.baseUrl`        | `string \| () => string`                                   | The agent's URL, `<engine origin>/agents/<slug>`                                |
+| `transport.getHeaders`     | `() => Headers \| Promise<Headers>`                        | Request headers provider; `Headers` is `Record<string, string>`                 |
+| `wsUrl`                    | `string \| false`                                          | WebSocket URL override; `false` disables the socket (optional)                  |
+| `viewMode`                 | `'helper' \| 'full'`                                       | Compact panel or full layout with a sidebar (default: `'helper'`)               |
+| `theme`                    | `'light' \| 'dark' \| 'system'`                            | Color scheme (default: `'light'`)                                               |
+| `agentName`                | `string \| { en, ar }`                                     | Header title while no thread is selected (optional)                             |
+| `showDebugButton`          | `boolean`                                                  | Show/hide the debug toggle button (default: `false`)                            |
+| `mediaRenderers`           | `Record<string, MediaRenderer>`                            | Replace or add the media fences the assistant can draw (optional)               |
+| `trustSameOriginEmbeds`    | `boolean`                                                  | Allow embedded tool pages served from this page's own origin (default: `false`) |
+| `hooks.onToolCall`         | `(toolCall, context) => unknown`                           | Answers a client tool; return `undefined` for tools you do not own (optional)   |
+| `hooks.onThreadSelected`   | `(thread) => void \| Promise<void>`                        | Runs when a thread opens (optional)                                             |
+| `hooks.onThreadDeselected` | `(thread) => void \| Promise<void>`                        | Runs when a thread closes (optional)                                            |
+| `toolComponents`           | `Record<string, ComponentType<CortexToolComponentInputs>>` | Custom React components for tool rendering (optional)                           |
+
+`transport.getHeaders` returns the headers every call carries, usually a bearer `Authorization`. Called straight from another origin, the engine accepts only `Authorization` and the headers the widget sets itself; route anything else through a same-origin proxy. The WebSocket takes its `token` query param from a bearer `Authorization` header when there is one.
 
 ## Custom parts
 
-With `slots` you draw the widget's parts yourself: `header`, `landing` (the
-blank chat) and `threadList` (the history's list). Each is a component that
-takes the context the default is drawn from as its props, the same one
-Angular's `cortexSlot` templates get (fields listed in the Angular README). The
-landing's `composer` is a React node to place. Define slot components outside
-render: a new component each render remounts the part.
+Pass `slots` to draw one of the widget's parts yourself: `header`, `landing`
+(the blank chat) or `threadList` (the history's list). Each is a component that
+takes the context the default is drawn from as its props. Use only the slots
+you need, and define them outside render: a new component each render remounts
+the part.
 
 ```tsx
 import {
@@ -57,7 +81,12 @@ function Header(chat: CortexHeaderContext) {
 function Landing(landing: CortexLandingContext) {
   return (
     <div className="cortex-widget__landing">
-      <h1>{landing.greeting}</h1>
+      {landing.greeting && <h1>{landing.greeting}</h1>}
+      {landing.suggestions.map((suggestion) => (
+        <button key={suggestion.prompt} onClick={() => landing.send(suggestion.prompt)}>
+          {suggestion.title}
+        </button>
+      ))}
       {landing.composer}
     </div>
   );
@@ -68,9 +97,145 @@ const slots = { header: Header, landing: Landing } satisfies CortexReactSlots;
 <CortexChatWidget config={config} slots={slots} />;
 ```
 
-The theming tokens and the table actions are the same as Angular's.
+A slot replaces the whole part, so its root sits where the default's did: in
+the chat or history screen's column, under the header. The defaults' classes
+are there to reuse: `cortex-widget__chat-header`, `cortex-widget__chat-title`
+and `cortex-widget__header-btn` for a header, `cortex-widget__landing` for a
+centered landing, `cortex-widget__threads-list` for a scrolling list. Utility
+classes such as Tailwind's apply inside the widget; its own reset sits in
+`@layer base.cortex`, below them. `ThreadSummary` and `Suggestion` are exported
+for typing your own rows and chips.
+
+### `header`
+
+One header serves both screens; `screen` says which is showing.
+
+| Field          | Type                  | Description                                                        |
+| -------------- | --------------------- | ------------------------------------------------------------------ |
+| `screen`       | `'chat' \| 'threads'` | Which screen the header is on                                      |
+| `viewMode`     | `'helper' \| 'full'`  | The configured view mode                                           |
+| `title`        | `string \| null`      | The open thread's title; `null` on a new chat                      |
+| `agentName`    | `string \| undefined` | `agentName` in the widget's locale                                 |
+| `threadCount`  | `number \| undefined` | How many conversations the history lists; undefined while it loads |
+| `isWorking`    | `boolean`             | The agent is answering                                             |
+| `debug`        | `{ shown, on }`       | Whether `showDebugButton` is set, and whether debug mode is on     |
+| `newChat`      | `() => void`          | Starts a new chat                                                  |
+| `openHistory`  | `() => void`          | Shows the history: its screen, or the sidebar in full mode         |
+| `closeHistory` | `() => void`          | Returns to the open chat                                           |
+| `toggleDebug`  | `() => void`          | Switches debug mode                                                |
+
+### `landing`
+
+Shown while no thread is open. The first send opens a thread and swaps the
+landing for it.
+
+| Field         | Type                              | Description                                                                                             |
+| ------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `greeting`    | `string`                          | The agent's greeting in the widget's locale, or the built-in one; empty until the handshake answers     |
+| `suggestions` | `{ title, prompt }[]`             | Empty until the handshake answers, and for an agent that takes no messages                              |
+| `threads`     | `ThreadSummary[] \| undefined`    | Newest first; `undefined` while the first load is out                                                   |
+| `composer`    | `ReactNode`                       | The widget's composer, or its "messages disabled" notice; place it in your markup                       |
+| `send`        | `(prompt: string) => void`        | Sends a first message; does nothing until the handshake answers, or for an agent that takes no messages |
+| `openThread`  | `(thread: ThreadSummary) => void` | Opens a thread                                                                                          |
+| `openHistory` | `() => void`                      | Shows the whole history, as the header's `openHistory`                                                  |
+
+### `threadList`
+
+The history's list. Its header is the `header` slot.
+
+| Field              | Type                              | Description                                           |
+| ------------------ | --------------------------------- | ----------------------------------------------------- |
+| `threads`          | `ThreadSummary[] \| undefined`    | Newest first; `undefined` while the first load is out |
+| `selectedThreadId` | `string \| undefined`             | The open thread's id; `undefined` on a new chat       |
+| `openThread`       | `(thread: ThreadSummary) => void` | Opens a thread                                        |
+| `deleteThread`     | `(threadId: string) => void`      | Deletes a thread                                      |
+| `newChat`          | `() => void`                      | Starts a new chat                                     |
+
+## Theming
+
+Every color is a `--cortex-color-*` token whose light and dark defaults ship
+with the widget; `theme` picks the side. `@m6d/cortex-react/theme.css` lists every
+token with its default, and any of them can be overridden on `:root` or on any
+ancestor of the widget. Beside the colors, radius and `--cortex-font-size`,
+four tokens ship unset and fall back when you leave them out:
+
+| Token                            | Falls back to               | Styles                               |
+| -------------------------------- | --------------------------- | ------------------------------------ |
+| `--cortex-font-size-message`     | `--cortex-font-size`        | Message text and the composer        |
+| `--cortex-font-size-header`      | `--cortex-font-size`        | The chat and history titles          |
+| `--cortex-color-send-empty`      | `transparent`               | The send button with nothing to send |
+| `--cortex-color-send-empty-text` | `--cortex-color-text-muted` | Its icon                             |
+
+The composer resets its own focus and disabled styles, so a page's global
+`textarea:focus` ring or disabled fill does not reach it.
+
+## Tables
+
+A markdown table in an answer scrolls sideways rather than squeezing its
+columns. Once it has finished arriving, hovering it (or focusing into it)
+shows two actions at its top end: expand, which opens it in a dialog with room
+for every column, and export, which downloads it as an `.xlsx` file. Numbers
+export as numbers; the header row is bold.
+
+## Client tools
+
+Tools of type `embedded` render inside the chat as an embedded flow (payment,
+signature, ...): the widget asks Cortex to initiate, shows the returned page in
+a sandboxed iframe (inline card or modal, per tool config), and submits the
+page's `cortex:client-tool` postMessage outcome back to the run as-is.
+Anything that must actually be true lives in your backend's own records. No
+widget configuration is needed. One caveat: an embed served from the page's
+**own origin** is refused by default, because a same-origin iframe cannot be
+sandboxed: it could reach into the page, and embed URLs come from the tool's
+definition in Cortex, whose administrator is not necessarily the site owner.
+When both are the same party and the embeds are the site's own pages, set
+`trustSameOriginEmbeds: true` to render them anyway (with full access, as any
+of the site's own pages has).
+
+Other pending tool calls go to `toolComponents` or `hooks.onToolCall`.
+That is how a tool of type `client` ("Answered by your app" in the console)
+works: return its output from `hooks.onToolCall` for that tool name, or draw it
+with a tool component. A `hooks.onToolCall` must return `undefined` for tool
+names it does not own, since answering an unknown pending call would settle an
+embedded flow before the user completes it.
+
+## Media blocks
+
+The assistant can answer with more than text. A fenced block tagged `mermaid`,
+`vega-lite`, `map` or `report` renders as a diagram, chart, map or report
+inside the message, with a placeholder while the block is streaming and an
+error card (with the source) when it cannot be drawn. An image attachment the
+model references as `![alt](attachment#<id>)` on its own line renders inline.
+
+The renderers are peer dependencies your bundler must be able to resolve, but
+they load only when a block of their kind first appears: `mermaid` for
+diagrams, `vega`, `vega-lite` and `vega-embed` for charts, and `leaflet` for
+maps (plus its stylesheet, `leaflet/dist/leaflet.css`, in your page). Maps
+draw OpenStreetMap tiles and need no key. A block whose library fails to load
+shows the error card.
+
+A report is an HTML fragment the agent writes. The widget removes scripts,
+images, links and anything that would load a URL, draws the rest in a shadow
+root that takes its colors from your `--cortex-color-*` theme, and draws each
+`<figure data-chart>` inside it with the chart renderer. Which forms an agent
+writes is its `media` setting in Cortex; reports are off by default.
+
+`mediaRenderers` swaps a renderer or adds a fence tag of your own. A renderer
+draws a closed fence's source into the host element and returns its teardown;
+its context carries the widget's color `scheme` and `locale`:
+
+```ts
+mediaRenderers: {
+  map: async (host, source, { scheme }) => {
+    // draw with Google Maps, Mapbox, MapLibre, ...
+    return () => {
+      /* dispose */
+    };
+  },
+}
+```
 
 ## Requirements
 
 - React 18 or later
-- Peer dependencies: `@tanstack/ai`, `@tanstack/ai-client`, `@tanstack/ai-react`, `marked`, `dompurify`, `highlight.js`, plus the lazily loaded `mermaid`, `vega`, `vega-lite`, `vega-embed`, `leaflet` (and `leaflet/dist/leaflet.css` in your page for maps)
+- Peer dependencies: `@tanstack/ai`, `@tanstack/ai-client`, `@tanstack/ai-react`, `marked`, `dompurify`, `highlight.js`, plus the lazily loaded `mermaid`, `vega`, `vega-lite`, `vega-embed`, `leaflet`

package/dist/index.d.ts

@@ -19,6 +19,14 @@ export type ThreadSummary = {
 		name: string;
 	};
 };
+/**
+ * Body of `POST /threads`. Only a console operator's request is read: its
+ * test thread keeps `variables` as the session the agent's server would
+ * otherwise fill per end user.
+ */
+export type CreateThreadRequest = {
+	variables?: Record<string, string | number | boolean>;
+};
 /**
  * One landing-page chip: the widget shows `title` and sends `prompt` as the
  * first message when clicked. The two may be the same text.
@@ -29,13 +37,19 @@ export type Suggestion = {
 };
 export type CortexHeaders = Record<string, string>;
 /**
- * How the widget reaches its cortex server. `baseUrl` may be a thunk so a host
- * with a reactive origin (an Angular Signal is itself a `() => string`) is read
+ * How the widget reaches Cortex. `baseUrl` may be a thunk so a consumer with
+ * a reactive origin (an Angular Signal is itself a `() => string`) is read
  * at the moment of each request rather than captured once.
  */
 export type CortexTransport = {
 	baseUrl: string | (() => string);
 	getHeaders: () => CortexHeaders | Promise<CortexHeaders>;
+	/**
+	 * Sent with every thread the widget creates. The console's playground puts
+	 * a test thread's variables here; Cortex honours it only from a verified
+	 * console operator.
+	 */
+	threadBody?: CreateThreadRequest;
 };
 export type ColorScheme = "light" | "dark";
 export type MediaRenderContext = {
@@ -59,7 +73,7 @@ export type CortexTheme = "light" | "dark" | "system";
 export type CortexToolCallContext = {
 	threadId: string;
 };
-/** A tool the server left for the client to answer. */
+/** A tool call Cortex left for the client to answer. */
 export type CortexToolCall = {
 	toolCallId: string;
 	toolName: string;
@@ -112,16 +126,16 @@ export type CortexConfig = {
 	 * Render embedded tool pages served from this page's own origin with their
 	 * full identity — which, same-origin, means no effective sandbox at all: such
 	 * an embed can reach into the host page. By default they are refused
-	 * (rendered inert), because embed URLs come from Control Center tool config,
-	 * and whoever administers that is not necessarily whoever owns this site.
-	 * Enable only when both are the same party and the embeds are this site's
-	 * own pages — then a second origin just for embeds is no longer needed.
+	 * (rendered inert), because embed URLs come from the tool's definition in
+	 * Cortex, and whoever administers that is not necessarily whoever owns this
+	 * site. Enable only when both are the same party and the embeds are this
+	 * site's own pages, so the embeds need no origin of their own.
 	 */
 	trustSameOriginEmbeds?: boolean;
 	hooks?: CortexHooks;
 };
 /**
- * What the header receives, the host's own or the widget's: where the widget
+ * What the header receives, the consumer's own or the widget's: where the widget
  * is, what to show, and the actions the default header offers. One header
  * serves both screens; `screen` says which is showing.
  */
@@ -132,10 +146,10 @@ export type CortexHeaderContext = {
 	title: string | null;
 	/** `agentName` in the widget's locale. */
 	agentName: string | undefined;
-	/** How many conversations the history lists; 0 while it loads. */
-	threadCount: number;
+	/** How many conversations the history lists; undefined while the first load is out. */
+	threadCount: number | undefined;
 	isWorking: boolean;
-	/** Whether the host enabled the debug switch, and whether it is on. */
+	/** Whether the consumer enabled the debug switch, and whether it is on. */
 	debug: {
 		shown: boolean;
 		on: boolean;
@@ -148,13 +162,13 @@ export type CortexHeaderContext = {
 	toggleDebug: () => void;
 };
 /**
- * What the blank-chat landing receives, the host's own or the widget's. The
+ * What the blank-chat landing receives, the consumer's own or the widget's. The
  * composer arrives ready to place as the SDK's own view type (`View`), so a
  * custom landing keeps the widget's attachments and send rules. Each SDK
  * exports it as `CortexLandingContext` with its view type filled in.
  */
 export type LandingContext<View> = {
-	/** The agent's greeting in the widget's locale, or the built-in one. */
+	/** The agent's greeting in the widget's locale, or the built-in one; empty until the handshake answers. */
 	greeting: string;
 	/** Empty until the handshake answers, and for an agent that takes no messages. */
 	suggestions: Suggestion[];
@@ -171,7 +185,7 @@ export type LandingContext<View> = {
 	/** Shows the whole history: its screen, or the sidebar in full mode, as the header's `openHistory`. */
 	openHistory: () => void;
 };
-/** What the history's list receives, the host's own or the widget's. Its header is the header slot. */
+/** What the history's list receives, the consumer's own or the widget's. Its header is the header slot. */
 export type CortexThreadListContext = {
 	/** Newest first; undefined while the first load is out. */
 	threads: ThreadSummary[] | undefined;
@@ -181,7 +195,7 @@ export type CortexThreadListContext = {
 	deleteThread: (threadId: string) => void;
 	newChat: () => void;
 };
-/** Each part of the widget a host can draw itself, with the context it receives. */
+/** Each part of the widget a consumer can draw itself, with the context it receives. */
 export type CortexSlotContexts<View> = {
 	header: CortexHeaderContext;
 	landing: LandingContext<View>;
@@ -193,7 +207,7 @@ export type CortexReactConfig = CortexConfig & {
 /** The landing's context, its composer a React node to place. */
 export type CortexLandingContext = LandingContext<ReactNode>;
 /**
- * The parts of the widget a host draws itself: each a component taking the
+ * The parts of the widget a consumer draws itself: each a component taking the
  * part's context as its props, the same type as the widget's default.
  */
 export type CortexReactSlots = {
@@ -202,10 +216,10 @@ export type CortexReactSlots = {
 /** The chat widget: the thread list, the open conversation and its composer, for the agent `config` points at. */
 export declare function CortexChatWidget({ config, className, slots, }: {
 	config: CortexReactConfig;
-	/** Sizing classes for the host. */
+	/** Sizing classes for the widget's root element. */
 	className?: string;
 	/**
-	 * The host's own parts. Each given one replaces the widget's default and
+	 * The consumer's own parts. Each given one replaces the widget's default and
 	 * receives the context the default is drawn from as its props. `header`
 	 * serves both the chat and the history screen. Pass components defined
 	 * outside render: a new one each render remounts the part.