@ahmedramez-org/nexus-chat 0.0.0-stage → 1.0.0-beta.2

package/contract/index.d.ts

@@ -0,0 +1,394 @@
+export declare const NEXUS_CHAT_CONTRACT_VERSION: 2;
+export type NexusChatContractVersion = typeof NEXUS_CHAT_CONTRACT_VERSION;
+export type HostTheme = 'light' | 'dark';
+export type HostDirection = 'ltr' | 'rtl';
+export type ArtifactPlacement = 'inline' | 'canvas';
+export type ArtifactView = 'chart' | 'table';
+export interface NexusChatConnection {
+    /**
+     * The IncortaCopilot client this host is (`general` for Incorta, `hikari`
+     * for Hikari). Copilot picks the welcome text, agents and contexts from it.
+     */
+    client: string;
+    /** IncortaCopilot's root, for example `/incorta/copilot` (Incorta) or `/copilot` (Hikari). */
+    copilotUrl: string;
+    /** Agent used when the Copilot handshake names no default agent for this client. */
+    agent?: string;
+    /** Headers every request carries (auth, CSRF). Re-read before each attempt. */
+    headers?(): Readonly<Record<string, string>> | Promise<Readonly<Record<string, string>>>;
+    credentials?: RequestCredentials;
+    /**
+     * Called once after a 401/403; resolve `true` when a retry can succeed.
+     * Absent: the failure surfaces to the user.
+     */
+    refreshAuth?(): Promise<boolean>;
+    /** Poll tuning; hosts normally omit both (defaults 1500 ms / 1000 ms). */
+    pollIntervalMs?: number;
+    initialPollDelayMs?: number;
+}
+export interface HostUser {
+    id?: string | number;
+    name?: string;
+}
+/**
+ * Plain host state. `get` may return a fresh object on every call: the chat
+ * compares the fields itself.
+ */
+export interface NexusChatEnvironmentSnapshot {
+    theme: HostTheme;
+    locale: string;
+    /** Absent: follows `locale` (Arabic, Hebrew, Persian and Urdu are right-to-left). */
+    direction?: HostDirection;
+    tenantId?: string;
+    user?: HostUser;
+}
+export interface NexusChatEnvironment {
+    get(): NexusChatEnvironmentSnapshot;
+    /** Call `onChange` whenever `get` may return something different. */
+    subscribe(onChange: () => void): () => void;
+}
+export type ContextKind = 'business-view' | 'physical-table' | 'insight' | 'file' | 'knowledge-store' | 'ai-container';
+/** One row in a context browser. */
+export interface ContextItem {
+    id: string;
+    label: string;
+    description?: string;
+    /** A folder the user can open; its children load with `parentId: id`. */
+    hasChildren?: boolean;
+    /** Shown greyed out with this reason. */
+    disabledReason?: string;
+    /**
+     * What Copilot receives when the item is attached, sent as
+     * `{ type, data: dataset }` (`type` follows the kind: `business_view`,
+     * `insight`, `space`, `ai_container`; a physical table travels as a
+     * `business_view`, as Copilot reads it). An item without one cannot be picked.
+     */
+    dataset?: Readonly<Record<string, unknown>>;
+}
+/** A host-owned context browser: the host loads the rows, the chat does the rest. */
+export interface ContextSource {
+    kind: Exclude<ContextKind, 'file'>;
+    load(request: {
+        parentId?: string;
+        query: string;
+    }, signal: AbortSignal): Promise<readonly ContextItem[]>;
+    /**
+     * Re-reads an attached item's `dataset` before every send (a retry asks
+     * again), so the question carries what the host shows now: a dashboard
+     * insight re-applies the current runtime filters. A rejection fails the
+     * send. Absent: the dataset goes as picked.
+     */
+    resolve?(dataset: Readonly<Record<string, unknown>>, signal: AbortSignal): Promise<Readonly<Record<string, unknown>>>;
+}
+/** `'file'` is the chat's own upload browser; every other kind is a host source. */
+export type ContextSpec = 'file' | ContextSource;
+export interface ColumnSummary {
+    id: string;
+    name: string;
+    label?: string;
+    type?: string;
+}
+export interface ValueMatch {
+    value: string | number | boolean | null;
+    label: string;
+    fieldId?: string;
+    fieldLabel?: string;
+    dataType?: string;
+    complete?: boolean;
+}
+/**
+ * A composer trigger character. Both search inside the one attached business
+ * view (`viewId` is that context's `id`); with none or several attached the
+ * character stays plain text.
+ *
+ * - `@` mentions a column. Asked once per view; the chat filters as you type.
+ * - `#` searches the view's values for the typed text.
+ */
+export type TriggerSpec = {
+    char: '@';
+    search(request: {
+        viewId: string;
+    }, signal: AbortSignal): Promise<readonly ColumnSummary[]>;
+} | {
+    char: '#';
+    search(request: {
+        viewId: string;
+        query: string;
+        limit: number;
+    }, signal: AbortSignal): Promise<readonly ValueMatch[]>;
+};
+/** Switches for things the chat builds itself. Each one defaults to `true`. */
+export interface NexusChatFeatures {
+    /**
+     * Follow running answers over one SSE stream instead of polling. A backend
+     * that refuses the stream falls back to polling.
+     */
+    streaming?: boolean;
+    /**
+     * `false` when the host page's CSP blocks the `blob:` frame a PDF preview
+     * needs (Hikari serves `frame-src 'none'`); PDF cards then offer Download.
+     */
+    inlinePdfPreview?: boolean;
+}
+export interface NexusArtifact {
+    id: string;
+    /**
+     * Artifact type. New kinds SHOULD use the namespaced `vendor.name` form
+     * (e.g. `incorta.insight`, `hikari.dashboard`) so two hosts can never
+     * collide on a bare name; `parseArtifactKind` reads that convention.
+     * Existing bare kinds (`insight`, …) remain valid.
+     */
+    kind: string;
+    /**
+     * Version of the payload shape under `data`, independent of the contract
+     * version. A renderer that does not recognise a kind's schemaVersion must
+     * decline it synchronously (`canRender` → false) so the portable fallback
+     * renders — never guess at a payload. Absent means "unversioned legacy
+     * payload", which hosts may continue to accept.
+     */
+    schemaVersion?: number;
+    data: unknown;
+    metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Reads the namespaced-kind convention. Returns null for bare legacy kinds.
+ * Framework-free on purpose: hosts use this inside `canRender` to route by
+ * vendor without re-implementing the convention.
+ */
+export declare function parseArtifactKind(kind: string): {
+    namespace: string;
+    name: string;
+} | null;
+/**
+ * True when the artifact carries the given payload schema version (or is an
+ * unversioned legacy payload and `acceptUnversioned` allows it). The guard a
+ * host renderer should call first in `canRender`.
+ */
+export declare function artifactMatchesSchema(artifact: Pick<NexusArtifact, 'schemaVersion'>, supportedVersion: number, options?: {
+    acceptUnversioned?: boolean;
+}): boolean;
+/** The appearance the remote is rendering under, so a host renderer can match it without reading the DOM. */
+export interface HostArtifactRendererAppearance {
+    theme: HostTheme;
+    direction: HostDirection;
+    locale: string;
+}
+export interface HostArtifactRenderRequest {
+    artifact: NexusArtifact;
+    messageId: string;
+    sessionId?: string;
+    userQuestion?: string;
+    taskId?: string;
+    placement: ArtifactPlacement;
+    /** Optional canvas presentation. Unsupported views fall back to the host's default. */
+    view?: ArtifactView;
+    /**
+     * Optional, per-mount callback: report the views this artifact actually has,
+     * including after asynchronous preparation. Never report after signal abort.
+     * Omit calls to retain the default canvas without a view-switching menu.
+     */
+    onSupportedViewsChange?(views: readonly ArtifactView[]): void;
+    isHistorical: boolean;
+    cachedData?: unknown;
+    metadata?: Readonly<Record<string, unknown>>;
+    /** Re-sent on every `update`: a theme switch arrives as an update with a new appearance. */
+    appearance?: HostArtifactRendererAppearance;
+    /** Aborted when the remote unmounts this renderer; stable across updates. */
+    signal?: AbortSignal;
+    /**
+     * Live answers only (absent when `isHistorical`): fields to merge into the
+     * artifact's `data` on the backend once its task finishes, so a reopened
+     * conversation replays the artifact without re-running it (an Incorta
+     * insight reports its `cached_data`). The first report per artifact wins.
+     */
+    onDataReady?(patch: Readonly<Record<string, unknown>>): void;
+}
+export interface HostArtifactRendererMount {
+    update(request: HostArtifactRenderRequest): void;
+    unmount(): void;
+}
+/** Host-native charts, painted into an element the chat owns. */
+export interface HostArtifactRendererCapability {
+    /** Optional synchronous, side-effect-free title from a host-owned payload. No I/O or rendering. */
+    getTitle?(artifact: NexusArtifact): string | undefined;
+    canRender(request: HostArtifactRenderRequest): boolean;
+    mount(element: HTMLElement, request: HostArtifactRenderRequest): HostArtifactRendererMount;
+}
+/** What a host adds to one question on its way to Copilot. */
+export interface SendAddition {
+    /** Replaces the text sent to Copilot; the user still sees what they typed. */
+    prompt?: string;
+    /** Extra `client_context` fields (a notebook's code `language`); `datasets` and `params` stay the chat's. */
+    clientContext?: Readonly<Record<string, unknown>>;
+}
+export interface NexusChatChat {
+    /** What the user can attach. Absent or empty: no contexts. */
+    contexts?: readonly ContextSpec[];
+    /** Absent or empty: `@` and `#` stay plain text. `/` (agents) always works. */
+    triggers?: readonly TriggerSpec[];
+    /** Absent: tables use the chat's own renderer, other host kinds show as unsupported. */
+    renderers?: HostArtifactRendererCapability;
+    features?: NexusChatFeatures;
+    /**
+     * Called before each question is sent (a retry calls it again). A notebook
+     * wraps the active paragraph's code into the prompt and adds its language.
+     * A rejection fails the send. Absent: questions go as typed.
+     */
+    beforeSend?(request: {
+        prompt: string;
+    }): SendAddition | Promise<SendAddition>;
+}
+export type OpenIntent = {
+    type: 'open-dashboard';
+    dashboardId: string;
+    tabId?: string;
+} | {
+    type: 'open-insight';
+    insightId: string;
+    dashboardId?: string;
+    tabId?: string;
+} | {
+    type: 'open-external';
+    url: string;
+} | {
+    type: 'open-host-artifact';
+    artifact: NexusArtifact;
+    target: 'view' | 'edit';
+};
+/** `can` decides, synchronously, whether the control shows; `run` handles the click. */
+export interface HostAction<T, R = void> {
+    can(target: T): boolean;
+    run(target: T): R | Promise<R>;
+}
+/** An artifact to share, with Copilot's own task and artifact ids (what `POST /copilot/email` takes). */
+export interface ShareTarget {
+    artifact: NexusArtifact;
+    taskId: string;
+    artifactId: string;
+}
+export interface CodeSnippet {
+    code: string;
+    language?: string;
+}
+export interface NexusChatActions {
+    /** Absent: source links and Open/Edit buttons are hidden. */
+    open?: HostAction<OpenIntent>;
+    /**
+     * Save a generated draft in the host's catalog. `run` resolves to the fields
+     * of `artifact.data` the save changed; the chat writes them back so the
+     * conversation replays the artifact as saved. Absent: no Save button.
+     */
+    save?: HostAction<NexusArtifact, Record<string, unknown>>;
+    /**
+     * Share an artifact through the host's own dialog; `run` resolves `true`
+     * once shared. Shown in the canvas and the card menu wherever `can` accepts
+     * the target. Absent: no Share.
+     */
+    share?: HostAction<ShareTarget, boolean>;
+    /** Insert an answer's code block into the host (a notebook paragraph). Absent: no Insert button. */
+    insertCode?: HostAction<CodeSnippet>;
+}
+export interface NexusChatUserActivity {
+    type: 'prompt' | 'human-input' | 'cancel' | 'upload' | 'history-mutation';
+    occurredAt: number;
+}
+/**
+ * Where a contained failure happened. `scope` is a stable slug the remote
+ * owns (`task`, `upload`, `poll-budget`, `render-region/thread`,
+ * `host-renderer`, …); the ids are present when the failure belongs to one
+ * conversation or task.
+ */
+export interface NexusChatErrorContext {
+    scope: string;
+    sessionId?: string;
+    taskId?: string;
+    remoteTaskId?: string;
+}
+export interface NexusChatEvents {
+    /** A contained failure; the user already sees it inline. Absent: logged to the console. */
+    onError?(error: NexusChatPublicError, context: NexusChatErrorContext): void;
+    /** The mount cannot continue; the host should tear it down and show its fallback. */
+    onFatal?(error: NexusChatPublicError): void;
+    onActivity?(activity: NexusChatUserActivity): void;
+    /**
+     * An answer is being produced: keep the user's host session alive until the
+     * returned release runs (the answer settled, or the mount ended). A long
+     * answer the user only watches must not sign them out. Absent: nothing held.
+     */
+    keepSessionAlive?(): () => void;
+    /**
+     * The chat entered or left fullscreen; the host hides or restores its own
+     * chrome. Always called with `false` before the mount's cleanup completes.
+     */
+    onFullscreen?(active: boolean): void;
+}
+/**
+ * Everything a host passes to one NexusChat mount. Only plain data and
+ * functions cross this boundary — no React node, store, router or provider —
+ * which is what lets the chat run its own React. `connection` and
+ * `environment` are required; everything else is optional, and the chat hides
+ * what it drives when absent.
+ */
+export interface NexusChatOptions {
+    version: NexusChatContractVersion;
+    connection: NexusChatConnection;
+    environment: NexusChatEnvironment;
+    chat?: NexusChatChat;
+    actions?: NexusChatActions;
+    events?: NexusChatEvents;
+    /**
+     * Stable identity for this mount location, keying route-return recovery so
+     * two simultaneous mounts never share a checkpoint. Hosts that render one
+     * NexusChat at a time omit it (docs/architecture/adr/checkpoint-lifecycle.md).
+     */
+    instanceId?: string;
+    /**
+     * The host sizes the mount and owns its window (a page-covering overlay, a
+     * docked side panel) and draws its frame. Present: the chat hides its own
+     * fullscreen toggle and its edge border, and shows a dock toggle while
+     * `canDock`, and a close button. Absent: the chat's own fullscreen toggle,
+     * and no close button.
+     */
+    window?: NexusChatWindow;
+}
+export interface NexusChatWindowState {
+    /** The mount is the docked side panel (the toggle shows pressed). */
+    docked: boolean;
+    /** The host page allows docking now; `false` hides the dock toggle. */
+    canDock: boolean;
+}
+export interface NexusChatWindow {
+    /** May return a fresh object on every call: the chat compares the fields. */
+    get(): NexusChatWindowState;
+    /** Call `onChange` whenever `get` may return something different. */
+    subscribe(onChange: () => void): () => void;
+    setDocked(docked: boolean): void;
+    close(): void;
+}
+/** What `mount` returns: the host's handle on one running chat. */
+export interface NexusChatHandle {
+    /** Tears the chat down and restores the element. Idempotent. */
+    unmount(): void;
+    /**
+     * Sends a question as if the user typed it and pressed Send (same gates: it
+     * is ignored while an answer is running). `prompt` replaces the text sent to
+     * Copilot, so a host can send a prepared request under a readable question.
+     */
+    ask(question: string, options?: {
+        prompt?: string;
+    }): void;
+    /**
+     * Attaches a host context to the composer as if the user picked it (same
+     * gates: the agent must support the kind; `false` when refused).
+     */
+    attach(kind: Exclude<ContextKind, 'file'>, item: ContextItem): boolean;
+}
+/** The federated entry point `nexusChat/mount`. */
+export type NexusChatMount = (element: HTMLElement, options: NexusChatOptions) => NexusChatHandle;
+export declare class NexusChatPublicError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string, options?: ErrorOptions);
+}
+export declare function assertCompatibleHost(options: Pick<NexusChatOptions, 'version'>): asserts options is Pick<NexusChatOptions, 'version'> & {
+    version: NexusChatContractVersion;
+};

package/contract/index.js

@@ -0,0 +1,35 @@
+export const NEXUS_CHAT_CONTRACT_VERSION = 2;
+/**
+ * Reads the namespaced-kind convention. Returns null for bare legacy kinds.
+ * Framework-free on purpose: hosts use this inside `canRender` to route by
+ * vendor without re-implementing the convention.
+ */
+export function parseArtifactKind(kind) {
+    const separator = kind.indexOf('.');
+    if (separator <= 0 || separator === kind.length - 1)
+        return null;
+    return { namespace: kind.slice(0, separator), name: kind.slice(separator + 1) };
+}
+/**
+ * True when the artifact carries the given payload schema version (or is an
+ * unversioned legacy payload and `acceptUnversioned` allows it). The guard a
+ * host renderer should call first in `canRender`.
+ */
+export function artifactMatchesSchema(artifact, supportedVersion, options) {
+    if (artifact.schemaVersion === undefined)
+        return options?.acceptUnversioned ?? false;
+    return artifact.schemaVersion === supportedVersion;
+}
+export class NexusChatPublicError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = 'NexusChatPublicError';
+        this.code = code;
+    }
+}
+export function assertCompatibleHost(options) {
+    if (options.version !== NEXUS_CHAT_CONTRACT_VERSION) {
+        throw new NexusChatPublicError('INCOMPATIBLE_HOST_CONTRACT', `NexusChat requires host contract ${NEXUS_CHAT_CONTRACT_VERSION}; received ${String(options.version)}.`);
+    }
+}

package/index.d.ts

@@ -0,0 +1,31 @@
+import type { NexusChatHandle, NexusChatMount, NexusChatOptions } from './contract/index.js';
+
+export type * from './contract/index.js';
+
+export interface NexusChatSource {
+  /** IncortaCopilot's root as this page reaches it; the chat loads from `<copilotUrl>/nexus-chat/`. */
+  copilotUrl?: string;
+  /**
+   * Where the chat files are served instead (pinned): the app's own copy of
+   * this package's `remote/` folder, or a CDN URL. Absent: from Copilot.
+   */
+  assetsUrl?: string;
+  /** Deadline for loading the chat, retry included. Default 20 000 ms. */
+  timeoutMs?: number;
+}
+
+/** The host contract options; `version` is filled in for you. */
+export type MountNexusChatOptions = Omit<NexusChatOptions, 'version'> &
+  Omit<NexusChatSource, 'copilotUrl'>;
+
+/** The host contract shape this connector speaks. */
+export const CONTRACT_VERSION: 2;
+
+/** Loads the chat once per source (one retry, one deadline) and resolves to its `mount`. */
+export function loadNexusChat(source: NexusChatSource): Promise<NexusChatMount>;
+
+/** Loads the chat and mounts it into `element`. */
+export function mountNexusChat(
+  element: HTMLElement,
+  options: MountNexusChatOptions,
+): Promise<NexusChatHandle>;

package/index.js

@@ -0,0 +1,87 @@
+// @incorta/nexus-chat — the connector that loads and mounts NexusChat in any
+// app, on any framework. The chat itself is a prebuilt Module Federation
+// remote with its own React (`shared: {}`), loaded at runtime from one of:
+//
+// - IncortaCopilot (default): `<copilotUrl>/nexus-chat/`, always the version
+//   that Copilot runs, so the UI matches its backend;
+// - this package's own `remote/` folder, served by the app (pinned to the
+//   installed version);
+// - any URL that serves a `remote/` folder, such as a CDN (pinned by its URL).
+//
+// `assetsUrl` picks the source; without it the chat comes from Copilot.
+// The host contract ships alongside: its types here, its values and helpers
+// under `./contract`, `./conformance` and `./host`, and a React component
+// under `./react`.
+
+/** The host contract shape this connector speaks (`NEXUS_CHAT_CONTRACT_VERSION`). */
+export const CONTRACT_VERSION = 2;
+
+const RETRY_DELAY_MS = 1_000;
+const DEFAULT_TIMEOUT_MS = 20_000;
+
+const loads = new Map();
+const attempts = new Map();
+
+function entryUrl({ copilotUrl, assetsUrl }) {
+  const base = assetsUrl ?? (copilotUrl && `${copilotUrl.replace(/\/+$/, '')}/nexus-chat/`);
+  if (!base) throw new Error('NexusChat needs a copilotUrl or an assetsUrl.');
+  return new URL('remoteEntry.js', new URL(base, window.location.href)).href;
+}
+
+async function importMount(entry) {
+  // The browser remembers a failed import by URL, so every attempt after the
+  // first asks for a new one, or it would never reach the network again.
+  const attempt = attempts.get(entry) ?? 0;
+  attempts.set(entry, attempt + 1);
+  const url = new URL(entry);
+  if (attempt) url.searchParams.set('nexus-chat-attempt', String(attempt));
+  const remote = await import(/* @vite-ignore */ /* webpackIgnore: true */ url.href);
+  await remote.init({});
+  const factory = await remote.get('./mount');
+  const module = await factory();
+  if (typeof module?.default !== 'function') {
+    throw new Error('NexusChat remote did not expose a mount function.');
+  }
+  return module.default;
+}
+
+/**
+ * Loads the chat once per source and resolves to its `mount` function. One
+ * retry, since a single failure (a 502 during a rolling restart) is not an
+ * outage, and one deadline over both, so a stalled load never hangs. A failed
+ * load is forgotten: the next call tries again. Calling it early (for example
+ * when the page is idle) makes the first open instant.
+ */
+export function loadNexusChat(options) {
+  const entry = entryUrl(options);
+  let load = loads.get(entry);
+  if (!load) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    load = Promise.race([
+      importMount(entry).catch(async () => {
+        await new Promise((resolve) => setTimeout(resolve, RETRY_DELAY_MS));
+        return importMount(entry);
+      }),
+      new Promise((_, reject) =>
+        setTimeout(() => reject(new Error('Timed out loading NexusChat.')), timeoutMs),
+      ),
+    ]);
+    load.catch(() => loads.delete(entry));
+    loads.set(entry, load);
+  }
+  return load;
+}
+
+/**
+ * Loads the chat (from `assetsUrl`, else `connection.copilotUrl`) and mounts
+ * it into `element` with the host contract options. The chat fills the
+ * element, so the element's box decides the presentation.
+ */
+export async function mountNexusChat(element, { assetsUrl, timeoutMs, ...options }) {
+  const mount = await loadNexusChat({
+    copilotUrl: options.connection?.copilotUrl,
+    assetsUrl,
+    timeoutMs,
+  });
+  return mount(element, { version: CONTRACT_VERSION, ...options });
+}

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@ahmedramez-org/nexus-chat",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0-beta.2",
+  "description": "NexusChat for any app: a connector and React component that load the prebuilt chat from IncortaCopilot (or a pinned copy), the host contract types and checks, and the chat bundle itself.",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Incorta/nexus-chat-ui.git",
+    "directory": "packages/nexus-chat"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./react": {
+      "types": "./react.d.ts",
+      "default": "./react.js"
+    },
+    "./contract": {
+      "types": "./contract/index.d.ts",
+      "default": "./contract/index.js"
+    },
+    "./conformance": {
+      "types": "./contract/conformance.d.ts",
+      "default": "./contract/conformance.js"
+    },
+    "./host": {
+      "types": "./contract/host.d.ts",
+      "default": "./contract/host.js"
+    },
+    "./remote/*": "./remote/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "react.js",
+    "react.d.ts",
+    "contract",
+    "remote",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  }
+}

package/react.d.ts

@@ -0,0 +1,42 @@
+import type { CSSProperties, ReactElement } from 'react';
+
+import type {
+  HostDirection,
+  HostTheme,
+  HostUser,
+  MountNexusChatOptions,
+  NexusChatHandle,
+} from './index.js';
+
+export interface NexusChatProps extends Omit<MountNexusChatOptions, 'environment' | 'window'> {
+  theme: HostTheme;
+  /** Default: the browser's language. */
+  locale?: string;
+  /** Absent: follows `locale`. */
+  direction?: HostDirection;
+  tenantId?: string;
+  user?: HostUser;
+  /**
+   * The app owns the chat's window (a docked panel, an overlay): the chat
+   * shows a dock toggle while `canDock`, and a close button.
+   */
+  window?: {
+    docked: boolean;
+    canDock: boolean;
+    setDocked(docked: boolean): void;
+    close(): void;
+  };
+  /** The chat is mounted: `ask` and `attach` are available. */
+  onReady?(chat: NexusChatHandle): void;
+  /** The chat could not load (after its retry and deadline). */
+  onLoadError?(error: Error): void;
+  className?: string;
+  style?: CSSProperties;
+}
+
+/**
+ * The chat as a React component. It fills its box. `connection`, `chat`,
+ * `actions`, `events`, `instanceId`, `assetsUrl` and `timeoutMs` are read
+ * once at mount; the other props update the running chat.
+ */
+export function NexusChat(props: NexusChatProps): ReactElement;