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

package/index.js

@@ -4,9 +4,8 @@
 //
 // - 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).
+// - any URL that serves a release's chat build (`nexus-chat-dist.tar.gz` on
+//   the GitHub Release, extracted), pinned to that release.
 //
 // `assetsUrl` picks the source; without it the chat comes from Copilot.
 // The host contract ships alongside: its types here, its values and helpers
@@ -21,18 +20,91 @@ const DEFAULT_TIMEOUT_MS = 20_000;
 
 const loads = new Map();
 const attempts = new Map();
+/** Stylesheets of the chat that failed to load, reloaded by the next attempt. */
+const failedStylesheets = new Set();
+let loadedVersion;
+
+// A loop, not `/\/+$/`: that regex backtracks quadratically on many slashes.
+function withoutTrailingSlashes(url) {
+  let end = url.length;
+  while (url[end - 1] === '/') end -= 1;
+  return url.slice(0, end);
+}
 
 function entryUrl({ copilotUrl, assetsUrl }) {
-  const base = assetsUrl ?? (copilotUrl && `${copilotUrl.replace(/\/+$/, '')}/nexus-chat/`);
+  const base = assetsUrl ?? (copilotUrl && `${withoutTrailingSlashes(copilotUrl)}/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;
 }
 
+// A failed CSS chunk rejects the load, and Vite's preload never asks for a
+// sheet it has seen again. Remember the chat's failed sheets so the next
+// attempt requests them anew. A sheet failing again fails that attempt but is
+// forgotten, so one a deploy removed blocks a single attempt, not every one.
+function captureFailedStylesheets(base) {
+  if (captureFailedStylesheets.installed) return;
+  captureFailedStylesheets.installed = true;
+  window.addEventListener(
+    'error',
+    ({ target }) => {
+      if (!(target instanceof HTMLLinkElement) || target.rel !== 'stylesheet') return;
+      if (target.dataset.nexusChatRetry === undefined && target.href.startsWith(base)) {
+        failedStylesheets.add(target.href);
+      }
+    },
+    true,
+  );
+}
+
+function reloadFailedStylesheets() {
+  const reloads = [...failedStylesheets].map((href) => {
+    failedStylesheets.delete(href);
+    document.querySelectorAll('link[rel="stylesheet"]').forEach((link) => {
+      if (link.href === href) link.remove();
+    });
+    return new Promise((resolve, reject) => {
+      const link = Object.assign(document.createElement('link'), { rel: 'stylesheet', href });
+      link.dataset.nexusChatRetry = '';
+      link.onload = resolve;
+      link.onerror = () => {
+        link.remove();
+        reject(new Error(`NexusChat stylesheet failed to load: ${href}`));
+      };
+      document.head.append(link);
+    });
+  });
+  return Promise.all(reloads);
+}
+
+// A chat served by its Vite dev server ships React Fast Refresh code, which
+// throws unless the page ran @vitejs/plugin-react's preamble. Only a local
+// dev server can be one, so only there is it probed (GET; Vite ignores HEAD).
+async function installReactRefreshPreamble(base) {
+  if (window.__vite_plugin_react_preamble_installed__) return;
+  if (!/^(localhost|127\.0\.0\.1|\[::1\])$|\.localhost$/.test(new URL(base).hostname)) return;
+  try {
+    const url = new URL('@react-refresh', base).href;
+    const probe = await fetch(url, { signal: AbortSignal.timeout(3_000) });
+    if (!probe.ok || !probe.headers.get('content-type')?.includes('javascript')) return;
+    const runtime = await import(/* @vite-ignore */ /* webpackIgnore: true */ url);
+    runtime.default.injectIntoGlobalHook(window);
+    window.$RefreshReg$ = () => {};
+    window.$RefreshSig$ = () => (type) => type;
+    window.__vite_plugin_react_preamble_installed__ = true;
+  } catch {
+    // Not a dev-served chat.
+  }
+}
+
 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 base = new URL('.', entry).href;
+  captureFailedStylesheets(base);
+  await installReactRefreshPreamble(base);
+  if (attempt) await reloadFailedStylesheets();
   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);
@@ -42,9 +114,43 @@ async function importMount(entry) {
   if (typeof module?.default !== 'function') {
     throw new Error('NexusChat remote did not expose a mount function.');
   }
+  loadedVersion =
+    typeof module.NEXUS_CHAT_VERSION === 'string' ? module.NEXUS_CHAT_VERSION : undefined;
   return module.default;
 }
 
+/**
+ * Forgets a loaded chat, so the next load fetches it again: after it failed
+ * while running (a redeploy can leave it asking for files that are gone).
+ */
+export function forgetNexusChat(source) {
+  // A source with no URL was never loaded.
+  if (source.copilotUrl || source.assetsUrl) loads.delete(entryUrl(source));
+}
+
+/** The version the last loaded chat reports (for error reports); undefined before a load. */
+export function loadedNexusChatVersion() {
+  return loadedVersion;
+}
+
+/**
+ * Rejects after `timeoutMs`, counted while the page can be seen: a hidden tab
+ * runs its timers and requests slowly (Chrome throttles background tabs), so
+ * a chat loading there gets a fresh deadline once the tab shows. Internal to
+ * this package.
+ */
+export function loadDeadline(timeoutMs) {
+  return new Promise((_, reject) => {
+    const expire = () => {
+      if (!document.hidden) return reject(new Error('Timed out loading NexusChat.'));
+      document.addEventListener('visibilitychange', () => setTimeout(expire, timeoutMs), {
+        once: true,
+      });
+    };
+    setTimeout(expire, timeoutMs);
+  });
+}
+
 /**
  * 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
@@ -62,9 +168,7 @@ export function loadNexusChat(options) {
         await new Promise((resolve) => setTimeout(resolve, RETRY_DELAY_MS));
         return importMount(entry);
       }),
-      new Promise((_, reject) =>
-        setTimeout(() => reject(new Error('Timed out loading NexusChat.')), timeoutMs),
-      ),
+      loadDeadline(timeoutMs),
     ]);
     load.catch(() => loads.delete(entry));
     loads.set(entry, load);
@@ -75,13 +179,133 @@ export function loadNexusChat(options) {
 /**
  * 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.
+ * element, so the element's box decides the presentation. Until the chat is
+ * up the skeleton holds the element; it leaves at once if the chat cannot load.
  */
 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 });
+  const skeleton = showNexusChatSkeleton(element, options.environment?.get().theme);
+  let handle;
+  try {
+    const mount = await loadNexusChat({
+      copilotUrl: options.connection?.copilotUrl,
+      assetsUrl,
+      timeoutMs,
+    });
+    handle = mount(element, { version: CONTRACT_VERSION, ...options });
+  } catch (error) {
+    skeleton.remove();
+    throw error;
+  }
+  skeleton.done();
+  return {
+    ...handle,
+    unmount() {
+      skeleton.remove();
+      handle.unmount();
+    },
+  };
+}
+
+// ---- the loading face every app shows until the chat is up (<NexusChat> draws it too)
+
+/** Fast loads show no skeleton; one that shows stays long enough to read, then cross-fades. */
+const SKELETON_DELAY_MS = 300;
+const SKELETON_MIN_MS = 400;
+const SKELETON_FADE_MS = 150;
+
+/** The chat's own ground (so the swap does not flash), its line fill, its window edge. */
+export const PALETTE = {
+  light: { ground: '#fcfdfe', fill: '#efeff2', line: '#e4e4e7' },
+  dark: { ground: '#151515', fill: '#242426', line: '#2c2c2e' },
+};
+
+export const reducedMotion = () => window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
+
+/** The Incorta Intelligence mark. */
+export const ICON = `data:image/svg+xml,${encodeURIComponent(
+  "<svg width='107' height='120' viewBox='0 0 107 120' fill='none' xmlns='http://www.w3.org/2000/svg'><g clip-path='url(#clip0_108_873)'><path d='M84 35.4C89.8 37.6 95.2 41.2 99.8 45.9C102.4 48.6 104.6 51.5 106.5 54.6L106.7 35.4C106.7 32 104.9 28.8 102 27L63.1 3.9C66.2 5.8 69.1 8.1 71.7 10.9C78.5 17.8 82.6 26.4 84 35.4Z' fill='url(#paint0_linear_108_873)'/><path d='M22.9 84.8C17.1 82.5 11.7 79 7.1 74.3C4.4 71.5 2.1 68.4 0.2 65.2L0 84.6C0 88.1 1.7 91.2 4.7 93L43.9 116.3C40.8 114.4 37.9 112.1 35.2 109.3C28.4 102.4 24.3 93.8 22.9 84.8Z' fill='url(#paint1_linear_108_873)'/><path d='M106.1 85.8L106.5 54.6C104.6 51.5 102.4 48.6 99.8 45.9C95.2 41.2 89.8 37.6 84 35.4C86.3 49.4 81.9 64.3 71 75C57.9 87.9 38.9 91.1 22.9 84.8C24.3 93.8 28.4 102.4 35.2 109.3C37.9 112.1 40.8 114.4 43.9 116.3L45.2 117.1L47.9 118.7C48.9 119.3 49.9 119.7 51 119.9C53.2 120.3 55.5 119.9 57.5 118.8L101.3 94.1C104.2 92.4 106.1 89.2 106.1 85.8V85.8Z' fill='url(#paint2_linear_108_873)'/><path d='M35.9 45.2C49 32.3 68 29.1 84 35.4C82.6 26.4 78.5 17.8 71.7 10.8C69.1 8.1 66.2 5.8 63.1 3.9L61.7 3.1L58.8 1.3C57.7 0.7 56.6 0.3 55.4 0.1C53.3 -0.2 51.1 0.2 49.2 1.2L5.4 26C2.4 27.6 0.6 30.8 0.6 34.2L0.2 65.2C2.1 68.4 4.4 71.5 7.1 74.3C11.7 79 17.1 82.5 22.9 84.8C20.7 70.7 25 55.9 35.9 45.2V45.2Z' fill='#00A098'/><path d='M22.9 84.8C23 85.3 23.1 85.8 23.2 86.3C23.2 86.5 23.2 86.7 23.3 86.8C23.3 87.2 23.4 87.5 23.5 87.9C23.5 88 23.6 88.2 23.6 88.4C23.7 88.8 23.8 89.1 23.9 89.4C23.9 89.6 24 89.8 24 90C24.1 90.4 24.2 90.8 24.4 91.1C24.4 91.4 24.5 91.6 24.6 91.9C24.7 92.2 24.8 92.5 24.9 92.8C25 93.1 25.1 93.3 25.2 93.6C25.3 93.8 25.4 94 25.5 94.2C25.6 94.5 25.7 94.8 25.8 95C25.9 95.2 25.9 95.4 26 95.6C26.2 95.9 26.3 96.2 26.4 96.5C26.5 96.6 26.5 96.7 26.5 96.7C26.9 97.4 27.2 98.1 27.6 98.8C27.6 98.9 27.6 98.9 27.7 99C27.9 99.3 28 99.7 28.2 100C28.3 100.1 28.4 100.2 28.4 100.3C28.6 100.7 28.8 101 29 101.3C29 101.4 29.1 101.5 29.1 101.6C29.8 102.7 30.6 103.8 31.4 104.9C31.8 104.9 92.7 102.9 96.2 42.5C96.6 36.7 96.4 30.2 95.5 23.2L63.1 3.9C66.2 5.8 69.1 8.1 71.7 10.9C78.5 17.8 82.6 26.4 84 35.4C86.3 49.4 81.9 64.3 71 75C57.9 87.9 38.9 91.1 22.9 84.8V84.8Z' fill='url(#paint3_linear_108_873)'/><path d='M84 35.4C84 34.9 83.9 34.4 83.8 33.8C83.7 33.7 83.7 33.5 83.7 33.4C83.6 33 83.5 32.7 83.4 32.3C83.4 32.1 83.3 31.9 83.3 31.7C83.2 31.4 83.1 31.1 83.1 30.8C83 30.6 83 30.4 82.9 30.2C82.8 29.8 82.7 29.4 82.6 29C82.5 28.8 82.4 28.5 82.3 28.3C82.2 28 82.1 27.7 82 27.4C81.9 27.1 81.8 26.9 81.7 26.6C81.6 26.4 81.5 26.2 81.5 25.9C81.4 25.7 81.2 25.4 81.1 25.1C81.1 24.9 81 24.7 80.9 24.6C80.8 24.3 80.6 24 80.5 23.7C80.5 23.6 80.4 23.5 80.4 23.4C80.1 22.7 79.7 22.1 79.4 21.4C79.3 21.3 79.3 21.2 79.2 21.2C79.1 20.8 78.9 20.5 78.7 20.2C78.6 20.1 78.6 20 78.5 19.9C78.3 19.5 78.1 19.2 77.9 18.9C77.9 18.8 77.8 18.7 77.8 18.6C77.1 17.5 76.3 16.4 75.5 15.3C75.1 15.3 14.2 17.3 10.7 77.6C10.4 83.5 10.6 90 11.4 97L43.8 116.2C40.7 114.3 37.8 112 35.2 109.3C28.4 102.4 24.3 93.8 22.9 84.8C20.7 70.8 25 55.9 35.9 45.2C49 32.3 68 29.1 84 35.4V35.4Z' fill='url(#paint4_linear_108_873)'/></g><defs><linearGradient id='paint0_linear_108_873' x1='104.6' y1='41.1' x2='52.2' y2='1.6' gradientUnits='userSpaceOnUse'><stop stop-color='#4854FE'/><stop offset='1' stop-color='#241C55'/></linearGradient><linearGradient id='paint1_linear_108_873' x1='0' y1='90.8' x2='43.9' y2='90.8' gradientUnits='userSpaceOnUse'><stop stop-color='#4854FE'/><stop offset='1' stop-color='#241C55'/></linearGradient><linearGradient id='paint2_linear_108_873' x1='31.5' y1='40.6' x2='92.7' y2='102.9' gradientUnits='userSpaceOnUse'><stop stop-color='white'/><stop offset='1' stop-color='#4854FE'/></linearGradient><linearGradient id='paint3_linear_108_873' x1='86.3' y1='19.1' x2='41.6' y2='98.7' gradientUnits='userSpaceOnUse'><stop stop-color='#4854FE' stop-opacity='0.93'/><stop offset='1' stop-color='#006EF0' stop-opacity='0'/></linearGradient><linearGradient id='paint4_linear_108_873' x1='19.9' y1='103.3' x2='61' y2='27.5' gradientUnits='userSpaceOnUse'><stop stop-color='#006EF0'/><stop offset='1' stop-color='#006EF0' stop-opacity='0'/></linearGradient><clipPath id='clip0_108_873'><rect width='106.7' height='120' fill='white'/></clipPath></defs></svg>",
+)}`;
+
+/**
+ * Draws the skeleton over `box`: the mark and two lines centred in it,
+ * pulsing together, revealed only once loading has taken SKELETON_DELAY_MS.
+ * It stays on top of whatever renders into `box` (the chat's React empties its
+ * element when it first paints) until `done` fades it out (after showing for
+ * SKELETON_MIN_MS) or `remove` drops it at once. Internal to this package.
+ */
+export function showNexusChatSkeleton(box, theme) {
+  const root = document.createElement('div');
+  root.setAttribute('role', 'status');
+  root.setAttribute('aria-label', 'Loading Incorta Intelligence');
+  root.style.cssText =
+    'position:absolute;inset:0;box-sizing:border-box;padding:24px;display:flex;align-items:center;justify-content:center;pointer-events:none';
+  const line = (width, height) =>
+    `<span style="display:block;width:${width};height:${height}px;border-radius:${height / 2}px"></span>`;
+  root.innerHTML = `<div style="width:100%;max-width:280px"><div style="display:flex;flex-direction:column;align-items:center;gap:20px"><img alt="" width="32" height="34"><div style="display:flex;flex-direction:column;align-items:center;gap:10px;width:100%">${line('100%', 14)}${line('64%', 10)}</div></div></div>`;
+  root.querySelector('img').src = ICON;
+  const setTheme = (next) => {
+    const palette = PALETTE[next === 'dark' ? 'dark' : 'light'];
+    root.style.background = palette.ground;
+    for (const span of root.querySelectorAll('span')) span.style.background = palette.fill;
+  };
+  setTheme(theme);
+
+  // An unpositioned box becomes the skeleton's containing block while it shows.
+  const position = box.style.position;
+  const unpositioned = getComputedStyle(box).position === 'static';
+  if (unpositioned) box.style.position = 'relative';
+  box.append(root);
+  const stay = new MutationObserver(() => root.parentNode === box || box.append(root));
+  stay.observe(box, { childList: true });
+
+  const shownAt = Date.now() + SKELETON_DELAY_MS;
+  const stack = root.firstChild;
+  const animations = [
+    stack.animate?.([{ opacity: 0 }, { opacity: 1 }], {
+      duration: SKELETON_FADE_MS,
+      delay: SKELETON_DELAY_MS,
+      fill: 'backwards',
+    }),
+    reducedMotion()
+      ? undefined
+      : stack.firstChild.animate?.([{ opacity: 1 }, { opacity: 0.45 }, { opacity: 1 }], {
+          duration: 1600,
+          easing: 'ease-in-out',
+          iterations: Infinity,
+        }),
+  ];
+  let timer;
+  let gone = false;
+  const remove = () => {
+    if (gone) return;
+    gone = true;
+    clearTimeout(timer);
+    stay.disconnect();
+    animations.forEach((animation) => animation?.cancel());
+    root.remove();
+    if (unpositioned) box.style.position = position;
+  };
+  return {
+    setTheme,
+    remove,
+    done() {
+      if (gone || timer !== undefined) return;
+      const sinceShown = Date.now() - shownAt;
+      // Never shown (a fast load): gone at once, before its reveal can start.
+      if (sinceShown < 0) return remove();
+      // Shown: for at least SKELETON_MIN_MS, then it fades.
+      timer = setTimeout(
+        () => {
+          const fade = root.animate?.([{ opacity: 1 }, { opacity: 0 }], {
+            duration: SKELETON_FADE_MS,
+            fill: 'forwards',
+          });
+          if (!fade) return remove();
+          animations.push(fade);
+          fade.onfinish = remove;
+        },
+        Math.max(0, SKELETON_MIN_MS - sinceShown),
+      );
+    },
+  };
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ahmedramez-org/nexus-chat",
-  "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.",
+  "version": "1.0.0-beta.20",
+  "description": "NexusChat for any app: a connector and React component that load the prebuilt chat from IncortaCopilot (or a pinned copy), and the host contract types and checks.",
   "license": "UNLICENSED",
   "repository": {
     "type": "git",
@@ -31,16 +31,31 @@
       "types": "./contract/host.d.ts",
       "default": "./contract/host.js"
     },
-    "./remote/*": "./remote/*",
     "./package.json": "./package.json"
   },
+  "typesVersions": {
+    "*": {
+      "react": [
+        "./react.d.ts"
+      ],
+      "contract": [
+        "./contract/index.d.ts"
+      ],
+      "conformance": [
+        "./contract/conformance.d.ts"
+      ],
+      "host": [
+        "./contract/host.d.ts"
+      ]
+    }
+  },
   "files": [
     "index.js",
     "index.d.ts",
     "react.js",
+    "window.js",
     "react.d.ts",
     "contract",
-    "remote",
     "README.md"
   ],
   "publishConfig": {

package/react.d.ts

@@ -5,38 +5,98 @@ import type {
   HostTheme,
   HostUser,
   MountNexusChatOptions,
+  NexusChatEnvironment,
   NexusChatHandle,
+  NexusChatWindow,
+  NexusChatWindowMode,
 } from './index.js';
 
-export interface NexusChatProps extends Omit<MountNexusChatOptions, 'environment' | 'window'> {
-  theme: HostTheme;
+interface DirectChatProps extends Omit<MountNexusChatOptions, 'environment' | 'window'> {
+  embedUrl?: undefined;
+  /** Required unless `environment` is given. */
+  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 app's own contract environment, used as is instead of the props above. */
+  environment?: NexusChatEnvironment;
+  /** The chat is mounted (`ask` and `attach` are available); `null` once it unmounts. */
+  onReady?(chat: NexusChatHandle | null): void;
   /** The chat could not load (after its retry and deadline). */
   onLoadError?(error: Error): void;
   className?: string;
   style?: CSSProperties;
 }
 
+/** The chat mounted into this page, sharing its session. It fills its box. */
+export interface DirectNexusChatProps extends DirectChatProps {
+  /**
+   * The app owns the chat's window (a docked panel, an overlay): the chat
+   * shows a dock toggle while `canDock` (or, with `mode`, `modes` and
+   * `setMode`, a button per other mode), and a close button. `setMode` is
+   * read at mount. A contract `NexusChatWindow` is used as is.
+   */
+  window?:
+    | {
+        docked: boolean;
+        canDock: boolean;
+        mode?: NexusChatMode;
+        modes?: readonly NexusChatMode[];
+        /** Minimized but still mounted: a dictation in progress ends. */
+        hidden?: boolean;
+        setDocked(docked: boolean): void;
+        setMode?(mode: NexusChatMode): void;
+        close(): void;
+      }
+    | NexusChatWindow;
+  modes?: undefined;
+  defaultMode?: undefined;
+}
+
+/**
+ * The chat mounted into this page, sharing its session, in a window drawn
+ * here as for `embedUrl`: a launcher icon that opens it floating, docked on
+ * the right, or fullscreen. Giving `modes` or `defaultMode` instead of a
+ * `window` opts in.
+ */
+export interface WindowedNexusChatProps extends DirectChatProps {
+  /** Where the chat may open, in launcher order. Default: all three. */
+  modes?: NexusChatMode[];
+  /** Open on load in this mode. Default: the launcher icon only. */
+  defaultMode?: NexusChatMode;
+  window?: undefined;
+}
+
+export type NexusChatMode = NexusChatWindowMode;
+
+/**
+ * The chat in an <iframe> served by Incorta, on the user's own Incorta
+ * session (the app never holds a token). It draws its window: a launcher
+ * icon that opens the chat floating, docked on the right, or fullscreen.
+ */
+export interface EmbeddedNexusChatProps {
+  /** Incorta's chat page: `<incorta>/copilot/nexus-chat/embed.html`. */
+  embedUrl: string;
+  /** Where the chat may open, in launcher order. Default: all three. */
+  modes?: NexusChatMode[];
+  /** Open on load in this mode. Default: the launcher icon only. */
+  defaultMode?: NexusChatMode;
+  /** Default `'light'`; followed live. */
+  theme?: HostTheme;
+  /** Read once, when the chat first opens. Default: the browser's language. */
+  locale?: string;
+}
+
+export type NexusChatProps = DirectNexusChatProps | WindowedNexusChatProps | EmbeddedNexusChatProps;
+
 /**
- * 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.
+ * The chat as a React component. Direct: it fills its box; `connection`,
+ * `chat`, `actions`, `events`, `instanceId`, `assetsUrl` and `timeoutMs` are
+ * read once at mount, and the other props update the running chat. With
+ * `modes` or `defaultMode` (and no `window`), or embedded (`embedUrl`): it
+ * draws its own window.
  */
 export function NexusChat(props: NexusChatProps): ReactElement;