@m6d/cortex-angular 0.1.0

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@m6d/cortex-angular",
+  "version": "0.1.0",
+  "description": "Reusable AI agent chat UI library for Angular",
+  "license": "MIT",
+  "sideEffects": false,
+  "exports": {
+    "./theme.css": "./theme.css",
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./types/m6d-cortex-angular.d.ts",
+      "default": "./fesm2022/m6d-cortex-angular.mjs"
+    }
+  },
+  "dependencies": {
+    "tslib": "^2.8.1"
+  },
+  "peerDependencies": {
+    "@angular/common": ">=21.2.0 <23",
+    "@angular/core": ">=21.2.0 <23",
+    "@angular/platform-browser": ">=21.2.0 <23",
+    "@tanstack/ai": ">=0.55.0 <1.0.0",
+    "@tanstack/ai-angular": ">=0.11.0 <1.0.0",
+    "@tanstack/ai-client": ">=0.32.0 <1.0.0",
+    "dompurify": "^3.0.0",
+    "highlight.js": "^11.0.0",
+    "leaflet": "^1.9.0",
+    "marked": "^17.0.0",
+    "mermaid": "^12.0.0",
+    "rxjs": "^7.8.0",
+    "vega": "^6.0.0",
+    "vega-embed": "^7.0.0",
+    "vega-lite": "^6.0.0"
+  },
+  "packageManager": "bun@1.3.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "releaseWatchPaths": [
+    "internal/client",
+    "internal/contracts"
+  ],
+  "module": "fesm2022/m6d-cortex-angular.mjs",
+  "typings": "types/m6d-cortex-angular.d.ts",
+  "type": "module"
+}

package/theme.css

@@ -0,0 +1,71 @@
+/*
+ * Theming surface.
+ *
+ * Every value below is the widget's own default; the compiled stylesheet ships
+ * this same file, so importing it 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);
+
+  /* Code blocks sit a step below the bubble they are in, in either scheme. */
+  --cortex-color-code-surface: light-dark(#e8edf3, #111111);
+  --cortex-color-code-text: light-dark(#334155, #e5e5e5);
+
+  --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/types/m6d-cortex-angular.d.ts

@@ -0,0 +1,412 @@
+// Generated by dts-bundle-generator v9.5.1
+
+import * as i0 from '@angular/core';
+import { Injector, OnInit, Signal, Type } from '@angular/core';
+import { ToolCallPart, UIMessage } from '@tanstack/ai';
+import { Observable } from 'rxjs';
+
+declare const LOCALES: readonly [
+	"en",
+	"ar"
+];
+export type Locale = (typeof LOCALES)[number];
+declare const TOOL_SURFACES: readonly [
+	"inline",
+	"modal"
+];
+export type ToolSurface = (typeof TOOL_SURFACES)[number];
+declare const ATTACHMENT_STATUSES: readonly [
+	"pending",
+	"described",
+	"failed",
+	"skipped"
+];
+declare const ATTACHMENT_ORIGINS: readonly [
+	"upload",
+	"tool"
+];
+export type AttachmentStatus = (typeof ATTACHMENT_STATUSES)[number];
+export type AttachmentOrigin = (typeof ATTACHMENT_ORIGINS)[number];
+export type AttachmentSummary = {
+	id: string;
+	filename: string;
+	contentType: string;
+	sizeBytes: number;
+	status: AttachmentStatus;
+	origin: AttachmentOrigin;
+	description: string | null;
+};
+export type ThreadSummary = {
+	id: string;
+	title: string | null;
+	createdAt: string;
+	updatedAt: string;
+	isRunning: boolean;
+	/** Present on a headless thread a trigger owns. Widgets never list these. */
+	trigger?: {
+		name: string;
+	};
+};
+export type TokenUsage = {
+	input: {
+		noCache: number;
+		cacheRead: number;
+		cacheWrite: number;
+		total: number;
+	};
+	output: {
+		reasoning: number;
+		text: number;
+		total: number;
+	};
+	total: number;
+};
+/**
+ * How to launch one client tool: stamped by the server, per tool name, on
+ * the metadata of an assistant message that may carry its pending call. Kept in
+ * the message so the binding survives server restarts while a run is parked.
+ */
+export type ClientToolBinding = {
+	toolId: string;
+	surface: ToolSurface;
+	embedOrigin: string;
+	/** Variables the initiate call's input reads. */
+	variables: string[];
+};
+/**
+ * What the server offers this agent's clients, fetched once at widget startup.
+ * The widget hides UI for anything absent; enforcement stays server-side.
+ */
+export type AgentCapabilities = {
+	attachments: boolean;
+	/** False when the agent's `message` trigger is off: the widget hides its composer. */
+	messages: boolean;
+	/** Prompt chips on the blank-chat landing per locale; clicking one sends its `prompt` as the first message. */
+	suggestions: Suggestions;
+	/** Headline of the blank-chat landing per locale; "" falls back to the widget's built-in copy. */
+	greeting: Greeting;
+};
+export type MessageMetadata = {
+	/** ISO time the server stored the message; stamped from the row when a transcript is served. */
+	createdAt?: string;
+	modelId?: string;
+	providerMetadata?: unknown;
+	isAborted?: boolean;
+	tokenUsage?: TokenUsage;
+	attachments?: AttachmentSummary[];
+	clientTools?: Record<string, ClientToolBinding>;
+	/** Set on `trigger` messages: the firing that wrote them. */
+	trigger?: TriggerFiringSummary;
+};
+/**
+ * One landing-page chip: the widget shows `title` and sends `prompt` as the
+ * first message when clicked. The two may be the same text.
+ */
+export type Suggestion = {
+	title: string;
+	prompt: string;
+};
+/** The runtime contract's `suggestionsSchema` and `greetingSchema` are built from these. */
+export type Suggestions = Record<Locale, Suggestion[]>;
+export type Greeting = Record<Locale, string>;
+export type TriggerFiringSummary = {
+	name: string;
+	firingId: string;
+	firedAt: string;
+	payload: unknown;
+};
+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
+ * at the moment of each request rather than captured once.
+ */
+export type CortexTransport = {
+	baseUrl: string | (() => string);
+	getHeaders: () => CortexHeaders | Promise<CortexHeaders>;
+};
+export type ColorScheme = "light" | "dark";
+export type MediaRenderContext = {
+	scheme: ColorScheme;
+};
+/**
+ * Draws a closed media fence's `source` into `host`, resolves once drawn, and
+ * returns the teardown. A consumer's `mediaRenderers` config entry has this
+ * shape too: one per fence language, replacing the built-in of the same name
+ * or adding a language of its own.
+ */
+export type MediaRenderer = (host: HTMLElement, source: string, context: MediaRenderContext) => Promise<() => void>;
+export type MediaRenderers = Partial<Record<string, MediaRenderer>>;
+/** One value for every locale, or a map keyed by locale ('en', 'ar'). */
+export type Localized<T> = T | Partial<Record<Locale, T>>;
+export type CortexViewMode = "helper" | "full";
+export type CortexTheme = "light" | "dark" | "system";
+export type CortexToolCallContext = {
+	threadId: string;
+};
+/** A tool the server left for the client to answer. */
+export type CortexToolCall = {
+	toolCallId: string;
+	toolName: string;
+	input: unknown;
+};
+export type CortexHooks = {
+	onToolCall?: (toolCall: CortexToolCall, context: CortexToolCallContext) => unknown;
+	onThreadSelected?: (thread: ThreadSummary) => Promise<void> | void;
+	onThreadDeselected?: (thread: ThreadSummary) => Promise<void> | void;
+};
+/** What the widget hands a consumer-supplied tool component, in either SDK. */
+export type CortexToolComponentInputs = {
+	toolCallPart: ToolCallPart;
+	message: UIMessage;
+	/** Answers the call. Rejects when the delivery failed, so a component can say so and let the user retry. */
+	setOutput: (output: unknown) => Promise<void>;
+};
+/**
+ * The framework-neutral part of the widget's configuration. Each SDK extends it
+ * with its own `toolComponents` slot, which is the one field whose type is
+ * inherently framework-bound.
+ */
+export type CortexConfig = {
+	/** Defaults to `'en'`. */
+	locale?: Locale;
+	transport: CortexTransport;
+	/**
+	 * WebSocket endpoint override, derived from `transport.baseUrl` by default.
+	 * `false` disables the socket entirely (chat still works fully over SSE;
+	 * only cross-tab notify events are lost) — required behind proxies that do
+	 * not forward `/ws`, which would otherwise reconnect forever.
+	 */
+	wsUrl?: string | false;
+	viewMode?: CortexViewMode;
+	/** Color scheme; `'system'` follows the OS preference. Defaults to `'light'`. */
+	theme?: CortexTheme;
+	/**
+	 * Replaces or extends the media fences the assistant's replies draw. Keyed by
+	 * fence tag; `map` swaps the built-in Leaflet map for another provider.
+	 */
+	mediaRenderers?: MediaRenderers;
+	/**
+	 * Chat header title while no thread is selected; defaults to a localized
+	 * "New Chat". Like the other copy props, either one value for every locale
+	 * or a map keyed by locale (`{ en: 'Support', ar: 'الدعم' }`).
+	 */
+	agentName?: Localized<string>;
+	showDebugButton?: boolean;
+	/**
+	 * 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.
+	 */
+	trustSameOriginEmbeds?: boolean;
+	hooks?: CortexHooks;
+};
+export type QueuedAttachment = {
+	localId: string;
+	filename: string;
+	status: "uploading" | "ready" | "deleting" | "error";
+	threadId?: string;
+	attachmentId?: string;
+	summary?: AttachmentSummary;
+};
+declare const ATTACHMENT_STATUSES$1: readonly [
+	"pending",
+	"described",
+	"failed",
+	"skipped"
+];
+declare const ATTACHMENT_ORIGINS$1: readonly [
+	"upload",
+	"tool"
+];
+type AttachmentStatus$1 = (typeof ATTACHMENT_STATUSES$1)[number];
+type AttachmentOrigin$1 = (typeof ATTACHMENT_ORIGINS$1)[number];
+export type AttachmentSummary$1 = {
+	id: string;
+	filename: string;
+	contentType: string;
+	sizeBytes: number;
+	status: AttachmentStatus$1;
+	origin: AttachmentOrigin$1;
+	description: string | null;
+};
+export type CortexAngularConfig = CortexConfig & {
+	toolComponents?: Record<string, Type<CortexToolComponentInputs>>;
+	injector?: Injector;
+};
+declare class AttachmentQueueService {
+	readonly items: import("@angular/core").WritableSignal<QueuedAttachment[]>;
+	private readonly flags;
+	readonly uploading: import("@angular/core").Signal<boolean>;
+	readonly busy: import("@angular/core").Signal<boolean>;
+	readonly hasReady: import("@angular/core").Signal<boolean>;
+	private readonly chatService;
+	readonly store: {
+		getState: () => QueuedAttachment[];
+		subscribe: (listener: () => void) => () => void;
+		accept: (files: File[]) => void;
+		remove: (localId: string) => void;
+		clear: (threadId: string | undefined) => void;
+		consumeReady: () => {
+			status: "ready";
+			summary: AttachmentSummary$1;
+			localId: string;
+			filename: string;
+			threadId?: string;
+			attachmentId?: string;
+		}[];
+		restoreConsumed: (threadId: string | undefined) => void;
+		discardConsumed: () => void;
+	};
+	constructor();
+	static ɵfac: i0.ɵɵFactoryDeclaration<AttachmentQueueService, never>;
+	static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
+declare class CortexChatService {
+	/**
+	 * Selection is the Thread handed to `selectThread`, resolved against the live
+	 * list: the row there receives the title and isRunning updates the server
+	 * pushes, so the selection follows them without hand-syncing. The snapshot
+	 * only answers for a thread the list has not caught up with yet.
+	 */
+	readonly selectedThread: import("@angular/core").Signal<ThreadSummary | undefined>;
+	private readonly chat;
+	/** The open conversation's transcript; empty while nothing is selected. */
+	readonly messages: import("@angular/core").Signal<import("@tanstack/ai-client").UIMessage<readonly import("@tanstack/ai").AnyClientTool[], any>[]>;
+	readonly isLoadingMessages: import("@angular/core").WritableSignal<boolean>;
+	readonly isAgentWorking: import("@angular/core").Signal<boolean>;
+	/**
+	 * Derived, never hand-synced: a call only counts as owed while the stream is
+	 * idle — mid-turn an unsettled call is just a server tool executing. Reading
+	 * straight from the SDK's signals is what brings the composer back the
+	 * instant `addToolResult` settles the call part — the SDK's delivery promise
+	 * only resolves once the continuation turn ends, far too late to gate UI on.
+	 */
+	readonly hasPendingToolCalls: import("@angular/core").Signal<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.
+	 */
+	readonly messageMetadata: import("@angular/core").WritableSignal<ReadonlyMap<string, MessageMetadata>>;
+	/** What the server offers this agent's clients; undefined until the handshake answers. */
+	readonly capabilities: import("@angular/core").WritableSignal<AgentCapabilities | undefined>;
+	private readonly events;
+	private readonly selectedThreadSnapshot;
+	private readonly config;
+	private readonly api;
+	private readonly threadService;
+	private readonly wsService;
+	private readonly destroyRef;
+	private readonly environmentInjector;
+	/** Owns the current thread's chat client; destroying it stops and disposes it. */
+	private chatInjector;
+	/** The turn in flight on the current chat client; replaced with it on every mount. */
+	private lifecycle;
+	private pendingThreadCreation;
+	private refreshing;
+	private stopCapabilities;
+	constructor();
+	/**
+	 * Kicked off by the widget once its `config` input is bound. This cannot happen in
+	 * the constructor: the widget builds its children during its creation pass, which
+	 * Angular runs before it binds inputs, so the transport is not knowable yet.
+	 */
+	start(): void;
+	/**
+	 * Capability-gated controls stay hidden until the handshake answers, so it
+	 * is asked until it does, and afresh after every reconnect: the old answer
+	 * may be stale (a trigger toggled while the socket was down), so it is
+	 * forgotten first.
+	 */
+	private loadCapabilities;
+	get events$(): Observable<"onFinish" | "onError" | "onThreadSelected" | "onSend">;
+	selectThread(thread: ThreadSummary, options?: {
+		skipLoadingMessages?: boolean;
+	}): Observable<ThreadSummary>;
+	deselectThread(): void;
+	/**
+	 * The id of the thread the next message belongs to, creating it when the widget is
+	 * still on a blank chat.
+	 */
+	ensureThread(): Observable<string>;
+	send(prompt: string, attachments?: AttachmentSummary[]): Observable<void>;
+	/** Answers a tool call on behalf of a consumer-supplied tool component.
+	 * Returns the delivery promise so callers (the client tool embed) can
+	 * re-arm on a transient failure instead of stranding the pending call. */
+	addToolResult(toolCallId: string, toolName: string, output: unknown): Promise<void>;
+	/** The user's decision on a server tool the run parked on; the run resumes once delivered. */
+	respondToApproval(approvalId: string, approved: boolean): Promise<void>;
+	abort(): Promise<void>;
+	deleteThread(threadId: string): Observable<void>;
+	/**
+	 * Points the widget at a thread with a chat client of its own. The client is
+	 * server-authoritative: on mount it asks cortex for the transcript and for
+	 * whatever run is still generating, so selecting a thread, reloading the page
+	 * and a second tab all re-attach through one path.
+	 */
+	private mountChat;
+	/**
+	 * Re-mounts the current thread's chat so its hydration re-reads the transcript
+	 * and re-attaches to whatever run is live now. This is how a run another tab
+	 * started, and a websocket that dropped and came back, land in this widget.
+	 * A caller passes the thread when it holds fresher state than the list.
+	 */
+	private reattach;
+	private createConnection;
+	private refreshMessages;
+	private readBackMessages;
+	/**
+	 * Server rows are merged over what is held, never swapped in: the entry this
+	 * client seeded for a message it just sent must outlive a hydration or
+	 * read-back that started before the send.
+	 */
+	private absorbMetadata;
+	private setMetadata;
+	private subscribeToWsEvents;
+	/**
+	 * Only what these events mean for the open conversation — their list-shaped
+	 * side is CortexThreadService's, which absorbs them on its own subscription.
+	 */
+	private onWsEvent;
+	private subscribeToWsConnections;
+	static ɵfac: i0.ɵɵFactoryDeclaration<CortexChatService, never>;
+	static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
+export declare class CortexChatWidgetComponent implements OnInit {
+	readonly config: import("@angular/core").InputSignal<CortexAngularConfig>;
+	protected readonly debugMode: import("@angular/core").WritableSignal<boolean>;
+	protected readonly screen: import("@angular/core").WritableSignal<"threads" | "chat">;
+	protected readonly sidebarOpen: import("@angular/core").WritableSignal<boolean>;
+	protected readonly viewMode: import("@angular/core").Signal<CortexViewMode>;
+	private readonly composer;
+	protected chatService: CortexChatService;
+	protected queue: AttachmentQueueService;
+	private readonly injector;
+	private readonly destroyRef;
+	ngOnInit(): void;
+	protected toggleSidebar(): void;
+	protected closeSidebar(): void;
+	protected toggleDebugMode(): void;
+	protected selectThread(thread: ThreadSummary): void;
+	protected openHistory(): void;
+	protected closeHistory(): void;
+	protected onWidgetDragOver(event: DragEvent): void;
+	protected onWidgetDrop(event: DragEvent): void;
+	protected newChat(): void;
+	static ɵfac: i0.ɵɵFactoryDeclaration<CortexChatWidgetComponent, never>;
+	static ɵcmp: i0.ɵɵComponentDeclaration<CortexChatWidgetComponent, "cortex-chat-widget", never, {
+		"config": {
+			"alias": "config";
+			"required": true;
+			"isSignal": true;
+		};
+	}, {}, never, never, true, never>;
+}
+
+export {};