@m6d/cortex-angular 0.1.0

package/README.md

@@ -0,0 +1,117 @@
+# @m6d/cortex-angular
+
+Angular AI chat UI library. Provides a self-contained chat widget with streaming messages, tool call visualization, composer attachments, syntax highlighting, and i18n support.
+
+## Usage
+
+```ts
+import { CortexChatWidgetComponent, CortexAngularConfig } from '@m6d/cortex-angular';
+
+@Component({
+  imports: [CortexChatWidgetComponent],
+  template: `<cortex-chat-widget [config]="config" />`,
+})
+export class MyComponent {
+  protected readonly config: CortexAngularConfig = {
+    locale: 'en',
+    transport: {
+      baseUrl: '/api/agents/assistant',
+      getHeaders: () => ({ Authorization: `Bearer ${token}` }),
+    },
+    // The WebSocket URL is derived from baseUrl (…/agents/assistant/ws); set
+    // `wsUrl` only to override it, and point it at that same agent-scoped path.
+  };
+}
+```
+
+No root-level providers needed — each widget instance is fully self-contained. You can render multiple widgets with different configs on the same page.
+
+### Configuration
+
+`CortexAngularConfig` is the shared `CortexConfig` plus two Angular-only slots
+(`toolComponents`, `injector`). `@m6d/cortex-react` takes the same shared shape.
+
+| Property                   | Type                                              | Description                                                                          |
+| -------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `locale`                   | `'en' \| 'ar'`                                    | Active locale (default: `'en'`)                                                      |
+| `transport.baseUrl`        | `string \| () => string`                          | Agent API base URL                                                                   |
+| `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 static 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, Type<CortexToolComponentInputs>>` | Custom Angular components for tool rendering (optional)                              |
+| `injector`                 | `Injector`                                        | Injector for `toolComponents` (optional)                                             |
+
+`transport.getHeaders` can return any request headers needed by the host app. WebSocket auth continues to derive the `token` query param from a bearer `Authorization` header when present.
+
+## Client tools
+
+Control-Center tools published with type "embedded" render inside the chat
+as an embedded flow (payment, signature, ...): the widget asks the server 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 the integrating backend's own records. No widget configuration
+is needed. One caveat: an embed served from the host page's **own origin** is
+refused by default, because a same-origin iframe cannot be sandboxed — it
+could reach into the host page, and embed URLs come from Control Center tool
+config, 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 keep the existing `toolComponents` /
+`hooks.onToolCall` behavior. That hook is also how static client tools work:
+declare an executor-less tool in the server config and answer it here by
+returning its output from `hooks.onToolCall` for that tool name. Consumer `hooks.onToolCall` implementations must
+return `undefined` for tool names they do not own — 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` or `map` renders as a diagram, chart or map inside the message,
+with a placeholder while the block is still 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
+at runtime shows the error card.
+
+Leaflet finds its marker images next to wherever the build put the one the
+stylesheet references, so an Angular build needs the other two copied there as
+well:
+
+```json
+"assets": [
+  { "glob": "marker-*.png", "input": "node_modules/leaflet/dist/images", "output": "media" }
+]
+```
+
+`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:
+
+```ts
+mediaRenderers: {
+  map: async (host, source, { scheme }) => {
+    // draw with Google Maps, Mapbox, MapLibre, ...
+    return () => {
+      /* dispose */
+    };
+  },
+}
+```
+
+## Requirements
+
+- Angular 21.2 or 22
+- Peer dependencies: `@tanstack/ai`, `@tanstack/ai-angular`, `@tanstack/ai-client`, `marked`, `dompurify`, `highlight.js`, `rxjs`, plus the lazily loaded `mermaid`, `vega`, `vega-lite`, `vega-embed`, `leaflet`