@m6d/cortex-react 0.13.0 → 0.14.1

package/README.md

@@ -32,14 +32,14 @@ Each widget is self-contained, so one page can render several widgets with diffe
 
 | Property                   | Type                                                       | Description                                                                     |
 | -------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------- |
-| `locale`                   | `'en' \| 'ar'`                                             | Active locale (default: `'en'`)                                                 |
+| `locale`                   | `'en' \| 'ar'`                                             | Active locale; the widget lays out in its direction (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`)                            |
+| `thread`                   | `string`                                                   | A thread id to open on mount (optional)                                         |
 | `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)   |
@@ -47,7 +47,7 @@ Each widget is self-contained, so one page can render several widgets with diffe
 | `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.
+`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. The debug toggle shows only when Cortex offers this caller the debug view: always to a console operator, and to everyone only where the engine runs with `ENGINE_DEBUG=true`. Anyone else gets only what the widget's normal view draws, and so does a `toolComponents` entry for one of the agent's server tools: the model's line for the user as the call's input, and only whether it failed (or a dataset read's row count) as its output.
 
 ## Custom parts
 
@@ -110,19 +110,19 @@ for typing your own rows and chips.
 
 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                                                |
+| 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 Cortex offers the debug view, and whether it is on           |
+| `newChat`      | `() => void`          | Starts a new chat; absent until Cortex confirms the caller may write |
+| `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`
 
@@ -143,13 +143,13 @@ landing for it.
 
 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                                     |
+| 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; absent until Cortex confirms the caller may write  |
+| `newChat`          | `() => void`                      | Starts a new chat; absent until Cortex confirms the caller may write |
 
 ## Theming
 
@@ -197,7 +197,10 @@ 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.
+embedded flow before the user completes it. A tool component draws a pending
+call only once Cortex confirms the caller may send; until then, and always for
+an operator inspecting a thread, the call shows as the widget's own line, and
+the component draws it once it settles.
 
 ## Media blocks
 
@@ -221,8 +224,10 @@ root that takes its colors from your `--cortex-color-*` theme, and draws each
 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`:
+(`MediaRenderer`) draws a closed fence's source into the host element and
+returns its teardown; its context (`MediaRenderContext`) carries the widget's
+color `scheme` and `locale`. The field's map of tags to renderers is
+`MediaRenderers`. The package exports all three types:
 
 ```ts
 mediaRenderers: {
@@ -238,4 +243,4 @@ mediaRenderers: {
 ## 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`
+- Peer dependencies: `@tanstack/ai`, `@tanstack/ai-client`, `marked`, `dompurify`, `highlight.js`, plus the lazily loaded `mermaid`, `vega`, `vega-lite`, `vega-embed`, `leaflet`

package/dist/index.d.ts

@@ -121,7 +121,11 @@ export type CortexConfig = {
 	 * or a map keyed by locale (`{ en: 'Support', ar: 'الدعم' }`).
 	 */
 	agentName?: Localized<string>;
-	showDebugButton?: boolean;
+	/**
+	 * A thread to open when the widget mounts, by id, once the thread list holds
+	 * it: a deep link into one conversation, such as the console's inspector.
+	 */
+	thread?: string;
 	/**
 	 * 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
@@ -149,12 +153,13 @@ export type CortexHeaderContext = {
 	/** How many conversations the history lists; undefined while the first load is out. */
 	threadCount: number | undefined;
 	isWorking: boolean;
-	/** Whether the consumer enabled the debug switch, and whether it is on. */
+	/** Whether Cortex offers this caller the debug view, and whether it is on. */
 	debug: {
 		shown: boolean;
 		on: boolean;
 	};
-	newChat: () => void;
+	/** Absent until the handshake says the caller may write; an operator inspecting a thread only reads. */
+	newChat?: () => void;
 	/** Shows the history: the history screen, or in full mode the sidebar where it is hidden. */
 	openHistory: () => void;
 	/** Returns to the open chat from wherever `openHistory` went. */
@@ -192,8 +197,9 @@ export type CortexThreadListContext = {
 	/** The open thread's id; undefined on a new chat. */
 	selectedThreadId: string | undefined;
 	openThread: (thread: ThreadSummary) => void;
-	deleteThread: (threadId: string) => void;
-	newChat: () => void;
+	/** Both absent until the handshake says the caller may write; an operator inspecting a thread only reads. */
+	deleteThread?: (threadId: string) => void;
+	newChat?: () => void;
 };
 /** Each part of the widget a consumer can draw itself, with the context it receives. */
 export type CortexSlotContexts<View> = {