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

package/README.md

@@ -1,3 +1,192 @@
-# Temporary Holding Version
+# @incorta/nexus-chat
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+NexusChat, the IncortaCopilot chat UI, for any app on any framework: one `<script>` tag for any
+site, `<NexusChat />` for React, `mountNexusChat()` for everything else.
+
+The chat always runs as a prebuilt Module Federation bundle with its own React and isolated
+styles, never re-compiled by the app's bundler, so it never collides with the app's React, its
+dependencies or its CSS. The connector adds about 6 KB gzipped to an app (half of it the Incorta
+Intelligence mark its loading skeleton draws), and the React component about 7 KB more. The chat
+build itself is not in this package: Copilot serves it, and each GitHub Release attaches it as
+`nexus-chat-dist.tar.gz`.
+
+## Any site: one script
+
+```html
+<script src="https://<incorta>/incorta/copilot/nexus-chat/widget.js" defer></script>
+```
+
+Incorta serves this script next to `embed.html`; it is not in this package and needs no build. It
+draws the Incorta Intelligence launcher at the bottom right and opens the embedded chat (below)
+floating, docked or full screen, on the user's Incorta session, so the page holds no token. It is
+one classic script with no imports, so a page on any origin loads it without CORS.
+
+Optional `data-` attributes set it up: `data-theme="dark"`, `data-modes="floating,docked"` (the
+windows allowed, in that order; default all three), `data-default-mode="docked"` (open on load;
+default only the launcher) and `data-locale="fr"`. The page drives it afterwards through
+`window.NexusChatWidget`: `open()`, `close()`, `setMode('docked')`, `setTheme('dark')`.
+
+## React
+
+Two ways in: **direct**, where the chat mounts into the page and shares its session (Incorta's own
+UIs), and **embedded**, where it runs in an iframe served by Incorta on the user's Incorta session,
+so the app never holds a token (generated apps, other sites).
+
+### Embedded
+
+```tsx
+import { NexusChat } from '@incorta/nexus-chat/react';
+
+<NexusChat embedUrl={`${incortaUrl}/copilot/nexus-chat/embed.html`} theme="dark" />;
+```
+
+It draws its own window: an Incorta Intelligence launcher at the bottom right opens the chat
+floating (a card lifted off the page, opening out of the launcher, which stays under it to hide
+it) or docked flush on the right (the page makes room). The chat's own top bar switches between
+the windows (Float, Dock to the side, Enter full screen: every allowed one but the current) and
+closes it back to the launcher; nothing sits above the chat. `modes` limits the windows (default
+all three, in that order) and `defaultMode` opens one on load. Below 768px wide the chat covers
+the page. The chat is drawn smaller in a small window, and a skeleton holds the window while the
+chat loads. `theme` is followed live; `locale` is read when the chat first opens.
+
+The Incorta cluster needs `iframe.inclusion.enabled` (and `frame-ancestors` set to the app's
+domains). Where the browser keeps the Incorta session from the iframe (Safari, Firefox, private
+windows), the chat shows Continue with Incorta: the browser asks the user to allow it once, and
+the chat starts on their Incorta session. A user not signed in to Incorta signs in through a small
+Incorta window that closes itself afterwards. No browser setting is needed.
+
+While the user clicks or types in the app, the component tells the chat at most every ten seconds,
+so Incorta's own idle timeout does not end the chat's session while the app is in use. A page that
+places the iframe itself can do the same: `iframe.contentWindow.postMessage({ nexusChat: 'active' },
+'<incorta origin>')`. If the session ends anyway, the chat shows Sign in to Incorta.
+
+### Direct
+
+```ts
+// Copilot answers 400 without the signed-in user's token: read it from Incorta's
+// session, and read it again after a 401 or 403.
+let session;
+const incortaHeaders = () =>
+  (session ??= fetch('/incorta/service/user/isLoggedIn', { credentials: 'include' }).then(
+    async (response) => ({
+      Authorization: `Bearer ${(await response.json()).accessToken}`,
+      'X-XSRF-TOKEN': response.headers.get('X-XSRF-TOKEN') ?? '',
+    }),
+  ));
+```
+
+```tsx
+<NexusChat
+  connection={{
+    client: 'general',
+    copilotUrl: '/incorta/copilot',
+    credentials: 'include',
+    headers: incortaHeaders, // read before each request
+    refreshAuth: async () => ((session = undefined), true), // after a 401 or 403: read again, retry
+  }}
+  theme="dark"
+  user={{ id: user.sub, name: user.name }}
+  onLoadError={(error) => setError(error.message)}
+/>
+```
+
+The chat fills the component's box; the app draws any frame around it. Until the chat is mounted, a skeleton holds the box (the embedded window's loading face: the Incorta Intelligence mark and two lines, after 300 ms), and it fades once the chat mounts, or leaves at once when `onLoadError` fires, so the app's own failure takes the box. `theme`, `locale` (default:
+the browser's), `direction`, `tenantId`, `user` and `window` update the running chat;
+`connection`, `chat`, `actions`, `events`, `instanceId`, `assetsUrl` and `timeoutMs` are read once
+at mount. `window` (`docked`, `canDock`, `setDocked`, `close`) hands the chat's window to the app:
+the chat shows a dock toggle and a close button; with `mode`, `modes` and `setMode` (read at
+mount) it shows a button per other mode instead of the toggle. An app that already builds the contract's
+`environment` or `window` passes it as is. `onReady` receives the handle (`ask`, `attach`), and
+`null` once the chat unmounts; `loadedNexusChatVersion()` names the loaded build for error reports.
+
+### Direct, in a window
+
+```tsx
+<NexusChat
+  connection={{
+    client: 'general',
+    copilotUrl: '/incorta/copilot',
+    credentials: 'include',
+    headers: incortaHeaders, // as above
+    refreshAuth: async () => ((session = undefined), true),
+  }}
+  theme="dark"
+  modes={['floating', 'docked', 'fullscreen']}
+  defaultMode="floating"
+/>
+```
+
+`modes` or `defaultMode` instead of `window` gives the direct chat the embedded window: the
+launcher, floating, docked (the page makes room) and full-screen windows, full screen below 768px.
+The chat's own top bar switches windows and closes it to the launcher, where the conversation
+stays. `modes` limits the windows (default all three, in that order); `defaultMode` opens one on
+load, else only the launcher shows. The other props are the direct ones, and an app passing
+`window` keeps drawing its own frame.
+
+## Any framework
+
+```ts
+import { mountNexusChat } from '@incorta/nexus-chat';
+
+const chat = await mountNexusChat(element, {
+  connection: { client: 'general', copilotUrl: '/api/ai' },
+  environment: {
+    get: () => ({ theme: 'light', locale: navigator.language }),
+    subscribe: () => () => {},
+  },
+});
+chat.ask('What changed last month?');
+chat.unmount();
+```
+
+The options are the host contract: `connection` and `environment` are required; `chat`, `actions`,
+`events` and `window` are optional, and the chat hides what a host leaves out. The chat fills
+`element`. Until it is mounted the React component's skeleton holds the element (after 300 ms, in
+the `environment`'s theme), and it leaves at once if the chat cannot load, so the app's own failure
+takes its place. Mount in the browser only, never during SSR.
+
+`chat={{ contexts: ['business-view', 'ai-container', 'file'] }}` lets users attach contexts, in
+that menu order: `'file'` uploads, and each other built-in kind (`business-view`, `physical-table`,
+`ai-container`, `knowledge-store`) is loaded by the chat from Incorta through
+`connection.incortaApi` (for example, `{ type: 'bff', baseUrl: '/incorta/bff/v1' }`). Without
+`incortaApi`, a bare kind is left out with a console warning; the public API has no Knowledge
+Stores. A `ContextSource` of a kind replaces the chat's loader for it.
+
+`loadNexusChat(source)` only loads the chat and resolves to its `mount`. It loads once per source,
+retries once, and gives up after `timeoutMs` (default 20 s, counted while the page is visible: a
+hidden tab gets a fresh deadline once it shows); a failed load is forgotten so the next
+call tries again. Call it when the page is idle to make the first open instant.
+
+## Where the chat comes from
+
+| Mode                     | Options                      | UI version                | App setup                                                              |
+| ------------------------ | ---------------------------- | ------------------------- | ---------------------------------------------------------------------- |
+| Always updated (default) | `connection.copilotUrl` only | what that Copilot runs    | none: Copilot serves `<copilotUrl>/nexus-chat/`                        |
+| Pinned                   | `assetsUrl: '/nexus-chat/'`  | the release you extracted | serve that release's `nexus-chat-dist.tar.gz`, extracted, at that path |
+
+A pinned copy serves `remoteEntry.js` with revalidation (`no-cache`) and `assets/` as immutable.
+
+A pinned UI keeps talking to a Copilot that keeps moving; the default mode keeps the two in step.
+
+## Everything in the package
+
+React and other apps need only the first two imports; the rest serve hosts that federate the chat
+themselves (web-react, Hikari).
+
+| Import                            | What                                                        |
+| --------------------------------- | ----------------------------------------------------------- |
+| `@incorta/nexus-chat`             | the connector (`mountNexusChat`, `loadNexusChat`) and types |
+| `@incorta/nexus-chat/react`       | `<NexusChat />` for React 18 and 19 apps                    |
+| `@incorta/nexus-chat/contract`    | the host contract's values (`NEXUS_CHAT_CONTRACT_VERSION`…) |
+| `@incorta/nexus-chat/conformance` | checks a host bridge against the contract                   |
+| `@incorta/nexus-chat/host`        | host helpers (`createElementRootAdapter`…)                  |
+
+## Versions
+
+Every NexusChat release publishes this package (the repository README → Releasing). `@beta`
+installs the newest prerelease. To try a build published under another scope without changing
+imports, alias it:
+
+```json
+"@incorta/nexus-chat": "npm:@someone/nexus-chat@beta"
+```

package/contract/conformance.d.ts

@@ -0,0 +1,51 @@
+import { type HostArtifactRendererCapability, type NexusArtifact, type NexusChatOptions } from './index.js';
+/**
+ * Executable conformance checks for the NexusChat host contract.
+ *
+ * Every host builds its options in its own stack — web-react with Redux,
+ * Hikari with TanStack Query — so "it compiles against the types" proves very
+ * little. These checks exercise what the remote actually depends on: a valid
+ * environment, subscription teardown, well-formed contexts, triggers and
+ * actions, and the mount lifecycle of a host-native renderer.
+ *
+ * Deliberately free of any test framework. Consumers run it from whatever
+ * runner they already have and assert on the report, and the remote can expose
+ * it over federation so a consumer verifies the exact build it loads.
+ */
+export type ContractCheckStatus = 'passed' | 'failed' | 'skipped';
+export interface ContractCheckResult {
+    id: string;
+    title: string;
+    status: ContractCheckStatus;
+    /** Why it failed, or why there was nothing to check. */
+    detail?: string;
+}
+export interface HostContractReport {
+    results: readonly ContractCheckResult[];
+    failures: readonly ContractCheckResult[];
+    skipped: readonly ContractCheckResult[];
+    passed: boolean;
+}
+export interface ArtifactRendererContractOptions {
+    /**
+     * Artifacts the consumer claims to render natively. At least one is required:
+     * the lifecycle cannot be observed without a payload the host accepts.
+     */
+    artifacts: readonly NexusArtifact[];
+    /** Overridable so a consumer can supply a container inside its own tree. */
+    createElement?: () => HTMLElement;
+}
+export interface HostContractOptions {
+    renderer?: ArtifactRendererContractOptions;
+    /** Consumer test hook that changes one environment source (theme, locale) in place. */
+    triggerEnvironmentChange?: () => void | Promise<void>;
+}
+/**
+ * Verifies the mount lifecycle the remote relies on: the host paints only into
+ * the element it is given, keeps that element across an update, and leaves it
+ * empty on unmount so the remote can reuse or discard it.
+ */
+export declare function checkArtifactRendererContract(capability: HostArtifactRendererCapability, options: ArtifactRendererContractOptions): Promise<HostContractReport>;
+export declare function checkHostContract(options: NexusChatOptions, checkOptions?: HostContractOptions): Promise<HostContractReport>;
+/** Human-readable summary for a consumer's test failure output. */
+export declare function formatHostContractReport(report: HostContractReport): string;

package/contract/conformance.js

@@ -0,0 +1,306 @@
+import { BUILT_IN_CONTEXT_KINDS, NEXUS_CHAT_CONTRACT_VERSION, } from './index.js';
+class CheckCollector {
+    results = [];
+    async run(id, title, check) {
+        try {
+            await check();
+            this.results.push({ id, title, status: 'passed' });
+            return true;
+        }
+        catch (cause) {
+            this.results.push({
+                id,
+                title,
+                status: 'failed',
+                detail: cause instanceof Error ? cause.message : String(cause),
+            });
+            return false;
+        }
+    }
+    skip(id, title, detail) {
+        this.results.push({ id, title, status: 'skipped', detail });
+    }
+}
+function ensure(condition, message) {
+    if (!condition)
+        throw new Error(message);
+}
+function toReport(results) {
+    const failures = results.filter((result) => result.status === 'failed');
+    return {
+        results,
+        failures,
+        skipped: results.filter((result) => result.status === 'skipped'),
+        passed: failures.length === 0,
+    };
+}
+function renderRequest(artifact, placement) {
+    return {
+        artifact,
+        messageId: 'contract-check-message',
+        taskId: 'contract-check-task',
+        placement,
+        isHistorical: false,
+        appearance: { theme: 'light', direction: 'ltr', locale: 'en' },
+    };
+}
+/**
+ * Verifies the mount lifecycle the remote relies on: the host paints only into
+ * the element it is given, keeps that element across an update, and leaves it
+ * empty on unmount so the remote can reuse or discard it.
+ */
+export async function checkArtifactRendererContract(capability, options) {
+    const checks = new CheckCollector();
+    const createElement = options.createElement ?? (() => document.createElement('div'));
+    const accepted = options.artifacts.filter((artifact) => {
+        try {
+            return capability.canRender(renderRequest(artifact, 'canvas'));
+        }
+        catch {
+            return false;
+        }
+    });
+    await checks.run('renderer.canRender.total', 'canRender never throws', () => {
+        options.artifacts.forEach((artifact) => {
+            capability.canRender(renderRequest(artifact, 'canvas'));
+            capability.canRender(renderRequest(artifact, 'inline'));
+            const title = capability.getTitle?.(artifact);
+            ensure(title === undefined || (typeof title === 'string' && title.trim().length > 0), 'The optional renderer title must be a non-empty string or undefined.');
+        });
+    });
+    await checks.run('renderer.canRender.declines', 'canRender declines unknown artifact kinds', () => {
+        const declined = capability.canRender(renderRequest({ id: 'contract-check-unknown', kind: 'contract-check-unknown', data: null }, 'canvas'));
+        ensure(declined === false, 'canRender accepted an artifact of an unknown kind; the remote would render an empty frame.');
+    });
+    if (accepted.length === 0) {
+        const detail = 'No supplied artifact was accepted by canRender, so the mount lifecycle could not be observed.';
+        [
+            'renderer.mount.paints',
+            'renderer.mount.isolated',
+            'renderer.update.keepsElement',
+            'renderer.unmount.empties',
+            'renderer.unmount.idempotent',
+        ].forEach((id) => checks.skip(id, id, detail));
+        return toReport(checks.results);
+    }
+    const artifact = accepted[0];
+    await checks.run('renderer.mount.paints', 'mount paints into the supplied element', async () => {
+        const element = createElement();
+        const mount = capability.mount(element, renderRequest(artifact, 'canvas'));
+        const painted = await paintsWithin(element);
+        mount.unmount();
+        await settle();
+        ensure(painted, 'mount produced no DOM inside the element supplied by the remote.');
+    });
+    await checks.run('renderer.mount.isolated', 'mount touches no element but its own', async () => {
+        const scope = document.createElement('div');
+        const element = createElement();
+        scope.appendChild(element);
+        const bodyChildren = new Set(document.body.children);
+        const headChildren = new Set(document.head.children);
+        document.body.appendChild(scope);
+        try {
+            const mount = capability.mount(element, renderRequest(artifact, 'canvas'));
+            await settle();
+            const leakedToBody = [...document.body.children].some((child) => child !== scope && !bodyChildren.has(child));
+            const leakedInsideScope = [...scope.children].some((child) => child !== element);
+            // A new <style> in the head is not a leak. Every CSS-in-JS host injects
+            // one on first render — antd's token sheet, emotion, styled-components —
+            // and that sheet is how the host's own BI content gets styled at all. It
+            // is deduplicated by the library and shared with the rest of the host
+            // page. What must not appear is anything else: a script, an iframe, or a
+            // stylesheet <link> the remote never asked for.
+            const leakedToHead = [...document.head.children].some((child) => !headChildren.has(child) && child.tagName !== 'STYLE');
+            mount.unmount();
+            await settle();
+            ensure(!leakedToBody && !leakedInsideScope && !leakedToHead, 'mount wrote DOM outside the element supplied by the remote.');
+        }
+        finally {
+            scope.remove();
+        }
+    });
+    await checks.run('renderer.update.keepsElement', 'update re-paints in place', async () => {
+        const element = createElement();
+        let supportedViews = [];
+        const request = {
+            ...renderRequest(artifact, 'canvas'),
+            onSupportedViewsChange: (views) => {
+                supportedViews = views;
+            },
+        };
+        const mount = capability.mount(element, request);
+        try {
+            await paintsWithin(element);
+            ensure(Array.isArray(supportedViews) &&
+                supportedViews.every((view) => view === 'chart' || view === 'table') &&
+                new Set(supportedViews).size === supportedViews.length, 'The renderer advertised invalid or duplicate artifact views.');
+            for (const view of supportedViews) {
+                mount.update({ ...request, view });
+                ensure(await paintsStablyWithin(element), `The advertised ${view} view did not remain painted.`);
+            }
+            mount.update(renderRequest(artifact, 'inline'));
+            ensure(await paintsStablyWithin(element), 'update emptied the element instead of re-painting it.');
+        }
+        finally {
+            mount.unmount();
+            await settle();
+        }
+    });
+    await checks.run('renderer.unmount.empties', 'unmount leaves the element empty', async () => {
+        const element = createElement();
+        const mount = capability.mount(element, renderRequest(artifact, 'canvas'));
+        await settle();
+        mount.unmount();
+        await settle();
+        ensure(element.childElementCount === 0, 'unmount left DOM behind; the remote reuses and removes these elements.');
+    });
+    await checks.run('renderer.unmount.idempotent', 'unmount and post-unmount update are safe', async () => {
+        const element = createElement();
+        const mount = capability.mount(element, renderRequest(artifact, 'canvas'));
+        await settle();
+        mount.unmount();
+        await settle();
+        mount.unmount();
+        mount.update(renderRequest(artifact, 'canvas'));
+        await settle();
+        ensure(element.childElementCount === 0, 'an update after unmount re-painted a detached element.');
+    });
+    return toReport(checks.results);
+}
+/** Lets a host root commit and flush its own microtask-deferred teardown. */
+function settle() {
+    return new Promise((resolve) => setTimeout(resolve, 0));
+}
+const RENDER_STABILITY_MS = 50;
+/**
+ * Polls for the element to paint, bounded. A host UI framework schedules its
+ * first commit, and in a real browser that can land a frame or two after
+ * `mount` returns — the contract requires painting, not painting within one
+ * macrotask (found by Hikari's built-remote e2e, the first consumer to run
+ * the renderer checks in a real browser). Timers only, so it behaves the same
+ * headless and under jsdom, where an immediate commit returns on the first
+ * probe.
+ */
+async function paintsWithin(element, timeoutMs = 2_000) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        if (element.childElementCount > 0)
+            return true;
+        if (Date.now() >= deadline)
+            return false;
+        await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+}
+/**
+ * An update starts with DOM from the previous render. Looking immediately can
+ * therefore miss a scheduled clear. Cross one scheduler boundary before
+ * probing, then require the element to remain painted for a defined stability
+ * window. This checks lifecycle continuity, not whether visual content changed.
+ */
+async function paintsStablyWithin(element) {
+    await settle();
+    if (!(await paintsWithin(element)))
+        return false;
+    await new Promise((resolve) => setTimeout(resolve, RENDER_STABILITY_MS));
+    return element.childElementCount > 0;
+}
+const CONTEXT_KINDS = [
+    'business-view',
+    'physical-table',
+    'insight',
+    'knowledge-store',
+    'ai-container',
+];
+const TRIGGER_CHARS = ['@', '#'];
+export async function checkHostContract(options, checkOptions = {}) {
+    const checks = new CheckCollector();
+    const { connection, environment, chat, actions } = options;
+    await checks.run('version', 'declares the supported contract version', () => {
+        ensure(options.version === NEXUS_CHAT_CONTRACT_VERSION, `version must be ${NEXUS_CHAT_CONTRACT_VERSION}; received ${String(options.version)}.`);
+    });
+    await checks.run('connection', 'connection names a client and a Copilot root', async () => {
+        ensure(typeof connection?.client === 'string' && connection.client.trim().length > 0, 'connection.client is required.');
+        ensure(typeof connection.copilotUrl === 'string', 'connection.copilotUrl is required.');
+        ensure(!/\/a2a\/?$/i.test(connection.copilotUrl.trim()), `connection.copilotUrl is Copilot's root, without /a2a; received ${JSON.stringify(connection.copilotUrl)}.`);
+        if (connection.headers) {
+            const headers = await connection.headers();
+            ensure(headers && typeof headers === 'object', 'connection.headers() must return an object.');
+        }
+    });
+    await checks.run('environment', 'environment.get returns a theme and a locale', () => {
+        const snapshot = environment.get();
+        ensure(snapshot && typeof snapshot === 'object', 'environment.get did not return an object.');
+        ensure(snapshot.theme === 'light' || snapshot.theme === 'dark', `theme must be "light" or "dark"; received ${JSON.stringify(snapshot.theme)}.`);
+        ensure(typeof snapshot.locale === 'string' && snapshot.locale.length > 0, 'locale is required.');
+    });
+    await checks.run('environment.subscribe', 'subscribe returns a working unsubscribe', async () => {
+        let notifications = 0;
+        const unsubscribe = environment.subscribe(() => {
+            notifications += 1;
+        });
+        ensure(typeof unsubscribe === 'function', 'subscribe did not return an unsubscribe function.');
+        if (checkOptions.triggerEnvironmentChange) {
+            await checkOptions.triggerEnvironmentChange();
+            await settle();
+            ensure(notifications > 0, 'subscribe did not notify after an environment source changed.');
+        }
+        unsubscribe();
+        // NexusChat unsubscribes on unmount, and a host may tear a mount down
+        // twice; the second call must not throw.
+        unsubscribe();
+        if (checkOptions.triggerEnvironmentChange) {
+            const before = notifications;
+            await checkOptions.triggerEnvironmentChange();
+            await settle();
+            ensure(notifications === before, 'unsubscribe did not detach the listener.');
+        }
+    });
+    await checks.run('chat.contexts', 'each context is a built-in kind or a source with a loader', () => {
+        const kinds = (chat?.contexts ?? []).map((spec) => {
+            if (typeof spec === 'string') {
+                ensure(BUILT_IN_CONTEXT_KINDS.includes(spec), `unknown context ${JSON.stringify(spec)}; a bare string is one of the built-in kinds: ${BUILT_IN_CONTEXT_KINDS.join(', ')}.`);
+                return spec;
+            }
+            ensure(CONTEXT_KINDS.includes(spec.kind), `unknown context kind ${JSON.stringify(spec.kind)}.`);
+            ensure(typeof spec.load === 'function', `the ${spec.kind} source has no load().`);
+            return spec.kind;
+        });
+        ensure(new Set(kinds).size === kinds.length, 'a context kind is listed twice (a source replaces its bare kind: list only the source).');
+    });
+    await checks.run('chat.triggers', 'each trigger is @ or # with a search', () => {
+        const chars = (chat?.triggers ?? []).map((trigger) => {
+            ensure(TRIGGER_CHARS.includes(trigger.char), `unknown trigger ${JSON.stringify(trigger.char)}.`);
+            ensure(typeof trigger.search === 'function', `the ${trigger.char} trigger has no search().`);
+            return trigger.char;
+        });
+        ensure(new Set(chars).size === chars.length, 'a trigger is listed twice.');
+    });
+    await checks.run('actions', 'each action has can() and run()', () => {
+        Object.entries(actions ?? {}).forEach(([name, action]) => {
+            if (action === undefined)
+                return;
+            ensure(typeof action.can === 'function' && typeof action.run === 'function', `actions.${name} needs both can() and run(). Omit it rather than supplying a placeholder.`);
+        });
+    });
+    const renderer = chat?.renderers;
+    if (!renderer) {
+        checks.skip('renderers', 'provides a host-native renderer', 'No renderer declared.');
+    }
+    else if (!checkOptions.renderer) {
+        checks.skip('renderers', 'provides a host-native renderer', 'No renderable artifacts were supplied, so the renderer lifecycle was not exercised.');
+    }
+    else {
+        const report = await checkArtifactRendererContract(renderer, checkOptions.renderer);
+        checks.results.push(...report.results);
+    }
+    return toReport(checks.results);
+}
+/** Human-readable summary for a consumer's test failure output. */
+export function formatHostContractReport(report) {
+    return report.results
+        .map((result) => {
+        const mark = result.status === 'passed' ? '✓' : result.status === 'failed' ? '✗' : '–';
+        return `${mark} ${result.id} — ${result.title}${result.detail ? `\n    ${result.detail}` : ''}`;
+    })
+        .join('\n');
+}

package/contract/host.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Host-side helpers for implementing NexusChat capabilities. Framework-free,
+ * like the rest of the contract: nothing here knows about React, only about
+ * elements, generations, and microtasks.
+ *
+ * `@incorta/nexus-chat-contract/host`
+ */
+import type { HostArtifactRendererCapability, HostArtifactRenderRequest } from './index.js';
+/**
+ * What an element-root adapter needs from the host: how to create a root inside
+ * a NexusChat-owned element, how to paint a request into it, and how to tear
+ * it down. `TRoot` is whatever the host's UI framework hands back — a React 18
+ * or 19 root, a hub entry, a vanilla controller.
+ */
+export interface ElementRootAdapter<TRoot> {
+    /** Declines an artifact the host cannot draw natively; the remote falls back to its portable renderers. */
+    canRender(request: HostArtifactRenderRequest): boolean;
+    /** Called once per element while a root is live; a newer mount on the same element reuses the root. */
+    createRoot(element: HTMLElement): TRoot;
+    /** Paints (or repaints) one request into the root. Runs for `mount` and every `update`. */
+    render(root: TRoot, request: HostArtifactRenderRequest, element: HTMLElement): void;
+    /** Tears the root down. Runs in a microtask after the remote's disposing commit, only if no newer mount claimed the element. */
+    unmount(root: TRoot, element: HTMLElement): void;
+    /** Where a throwing teardown is reported; defaults to `console.error`. */
+    onUnmountError?(error: unknown, element: HTMLElement): void;
+}
+/**
+ * The renderer lifecycle every host used to hand-copy, in one place:
+ *
+ * - **one root per element, generation-counted** — the remote re-mounts the
+ *   same container on an artifact swap and React runs effects twice in
+ *   StrictMode, so `mount` arrives again on an element that already has a
+ *   root; creating a second one orphans the first, so the newer mount reuses
+ *   it and wins;
+ * - **deferred, guarded teardown** — the remote can dispose a renderer from
+ *   inside its own commit; unmounting is queued as a microtask and skipped
+ *   when a newer generation has claimed the element in the meantime;
+ * - **a swallowed teardown throw** — a failing unmount is reported, never
+ *   rethrown into the remote's React tree.
+ *
+ * Hosts implement only the four framework-specific calls above.
+ */
+export declare function createElementRootAdapter<TRoot>(adapter: ElementRootAdapter<TRoot>): HostArtifactRendererCapability;
+/** A Business View named by its schema and view. */
+export interface BusinessViewRef {
+    schema: string;
+    view: string;
+}
+/**
+ * Splits a `<schema>.<view>` id (Incorta's asset-path form) at the FIRST dot:
+ * a view name may contain a dot, a schema name may not. Null for anything that
+ * is not two non-empty halves.
+ */
+export declare function splitBusinessViewId(id: string | undefined): BusinessViewRef | null;