@hainiva/agent-sdk 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -7,9 +7,32 @@ release (`0.2.0`) may change the API; a patch release (`0.1.1`) never does.
 
 ## [Unreleased]
 
-## [0.2.0]
+## [0.3.1] - 2026-11-15
 
-Preview, not yet published.
+- README: the product is named HAINIVA; new Documentation section linking the
+  developer docs, the API reference and the sibling SDKs. No code changes.
+
+## [0.3.0] - 2026-11-14
+
+- `@hainiva/agent-sdk/embed`: `mountDesk(container, { agent, appId, baseUrl,
+  theme?, locale?, onEnded?, onDial?, onDialer?, onOpenUrl?, onMediaError? })`
+  shows the HAINIVA desk in a sandboxed iframe signed in with your agent
+  session and returns `{ destroy(), setTheme(), setLocale(), iframe }`. The
+  handshake checks `event.source` and the desk origin, posts to the desk origin
+  only, supplies and refreshes the desk token (single flight), and ends on a
+  refused session or when the desk does not load (`load_failed`). Exports the
+  protocol (`DeskToHost`, `HostToDesk`, `parseDeskMessage`), `DESK_SANDBOX`,
+  `DESK_ALLOW` and `deskUrl()`.
+- `@hainiva/agent-sdk/react-native`: `<HainivaDesk agent appId baseUrl onDial …/>`
+  in a `react-native-webview` WebView (optional peer, or pass `WebView`):
+  bridge injected before the desk's scripts on the desk origin only,
+  `originWhitelist` limited to the desk, no `window.open` passthrough; calls
+  are handed to your app (`onDial`, `onDialer`).
+- `agent.desk.session()` / `AgentRestClient.deskSession()`:
+  `POST /agent/v1/desk-session` → `AgentDeskSessionDto {token, expiresAt}`.
+- Optional peers `react` and `react-native-webview` (only for `<HainivaDesk/>`).
+
+## [0.2.0] - 2026-11-14
 
 - `HainivaAgent`: one object for a staff member's app — `connect()`, `me`,
   `setStatus`, `rings.pending`, `calls.accept/decline/end/hold/mute/transfer`,
@@ -33,7 +56,7 @@ Preview, not yet published.
 
 ## [0.1.0]
 
-Preview, not yet published.
+Not published to npm; its contents shipped in 0.2.0.
 
 - `SessionManager`: sign-in with a fresh assertion from your backend every
   time, pluggable `SessionStore` (memory by default), single-flight refresh
@@ -49,6 +72,8 @@ Preview, not yet published.
 - `/react-native`: `secureStoreSessionStore`, `joinCallRoom` (LiveKit).
 - `/embed`: placeholder, throws.
 
-[Unreleased]: https://github.com/hainiva/agent-sdk/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/hainiva/agent-sdk/compare/v0.3.1...HEAD
+[0.3.1]: https://github.com/hainiva/agent-sdk/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/hainiva/agent-sdk/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/hainiva/agent-sdk/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/hainiva/agent-sdk/releases/tag/v0.1.0

package/README.md

@@ -1,6 +1,6 @@
 # @hainiva/agent-sdk
 
-Build **your own staff app** on [HAINIVA AICC](https://hainiva.com): your staff
+Build **your own staff app** on [HAINIVA](https://hainiva.com): your staff
 sign in with an assertion from your backend, receive their rings and
 conversations over one reconnecting socket, and take calls with LiveKit — in a
 browser, in React Native, or in Node.
@@ -11,8 +11,8 @@ browser, in React Native, or in Node.
 | --- | --- | --- |
 | `@hainiva/agent-sdk` | `HainivaAgent`, the REST client, the socket, the call state machine, redaction | nothing (no LiveKit, DOM or React Native) |
 | `@hainiva/agent-sdk/web` | `joinCallRoom` (LiveKit), `localStorageStore` (opt-in) | `livekit-client` |
-| `@hainiva/agent-sdk/react-native` | `joinCallRoom`, `secureStoreSessionStore` | `livekit-client`, `@livekit/react-native`, `expo-secure-store` |
-| `@hainiva/agent-sdk/embed` | the embeddable desk | not yet available (throws) |
+| `@hainiva/agent-sdk/react-native` | `joinCallRoom`, `secureStoreSessionStore`, `<HainivaDesk/>` | `livekit-client`, `@livekit/react-native`, `expo-secure-store`; `react-native-webview` for `<HainivaDesk/>` |
+| `@hainiva/agent-sdk/embed` | `mountDesk()`: the full HAINIVA desk inside your web page | a browser |
 
 Native ringing on phones (CallKit / Android call notification) is
 [`@hainiva/react-native-call`](https://github.com/hainiva/react-native-call).
@@ -72,7 +72,7 @@ member with **your own** login, it signs a short assertion:
 
 | | |
 | --- | --- |
-| header | `alg: "ES256"` (or `RS256`), `kid`: the key id you registered |
+| header | `alg: "ES256"` (or `RS256`), `kid`: the key id you registered. `HS256` works only for a test app on a sandbox organisation. |
 | `iss` | your agent app id |
 | `sub` | the member's `externalId` (`PUT /v1/members/by-external-id/:externalId`) |
 | `aud` | `hainiva-agent` |
@@ -88,8 +88,17 @@ for key generation and a complete signer.
 expires (one refresh however many requests are waiting; the refresh token
 rotates). A request answered `401 token_expired` refreshes and is retried once.
 A refused refresh (expired, revoked, reused) signs in again with a new
-assertion. `401 session_revoked` — signed out elsewhere, member suspended, app
-paused — is final: the SDK forgets the session and emits `revoked`.
+assertion. `401 session_revoked` (signed out elsewhere, sessions revoked,
+member suspended, role changed, app paused) ends this session: the SDK forgets
+it and emits `revoked`.
+
+**Revoking sessions does not cut a member off.** The next `connect()`, or the
+embedded desk asking for a token, signs in again with a fresh assertion, and
+your backend still vouches for the member, so it succeeds. To stop someone
+working, suspend or delete the member (`PATCH /v1/members/:id
+{"status":"suspended"}`, `DELETE /v1/members/:id`) or pause the agent app; then
+sign-in is refused (`401 session_refused`, `403 agent_app_paused`). Stop
+signing assertions for them on your side too.
 
 ## Events
 
@@ -154,15 +163,21 @@ Phones ring through **your** app with **your** Firebase / APNs credentials.
    before signing out anyway.
 3. **Show the ring** with `@hainiva/react-native-call` — Android: the FCM data
    message `{type: "call", tenantId, interactionId, conversationId, path,
-   caller, line, expiresAt}` (and `call_cancel`); iPhone: a VoIP push to
-   `<topic>.voip` with the same fields, reported to CallKit natively. See
+   caller, line, expiresAt, transferMode?}` (all strings; `expiresAt` in Unix
+   milliseconds) and `{type: "call_cancel", tenantId, interactionId, reason}`;
+   iPhone: a VoIP push to `<topic>.voip` with the same fields, reported to
+   CallKit natively (ring ends come over the socket, not as a push). See
    [`examples/expo-agent-app`](./examples/expo-agent-app).
 
 ## Web
 
 Add your page's exact origin to the agent app's `allowedOrigins`. HAINIVA
 answers the browser's CORS preflight only for origins an agent app lists, and
-checks every request against the origins of the app its session belongs to.
+checks every request against the origins of the app its session belongs to
+(`403 origin_not_allowed`). A page on an origin that no app lists is refused at
+the preflight, before any sign-in: `connect()` fails with a
+`HainivaAgentError` of status `0` (`network_error`), which in the browser's
+network panel is a CORS error.
 
 The session is kept **in memory** by default: a reload signs in again with a
 fresh assertion. `localStorageStore()` keeps it across reloads, but **any
@@ -182,6 +197,82 @@ that wakes a locked phone finds it; never migrated to another device) or the
 Android Keystore. There is no fallback to a plain store. Call
 `registerGlobals()` from `@livekit/react-native` once at startup.
 
+## The embedded desk
+
+Show the whole HAINIVA desk inside your product, signed in as your staff
+member with **your** agent session — no HAINIVA login screen, no password.
+
+```ts
+import { mountDesk } from "@hainiva/agent-sdk/embed";
+
+await agent.connect();
+const desk = mountDesk(document.getElementById("desk")!, {
+  agent,                                   // your connected HainivaAgent
+  appId: "YOUR_AGENT_APP_ID",
+  baseUrl: "https://app.hainiva.com",      // the HAINIVA desk
+  theme: "light", locale: "vi",
+  onEnded: (reason) => showSignedOut(reason),
+});
+desk.setTheme("dark");
+desk.destroy();
+```
+
+- **Your page's origin must be in the agent app's `allowedOrigins`.** That list
+  is also the desk's CSP `frame-ancestors`: any other site gets a blank frame
+  (and `onEnded("load_failed")`). Adding an origin lets that site embed the desk
+  for this app's staff — list only sites you control.
+- The SDK exchanges your agent session for a 15-minute **desk token**
+  (`POST /agent/v1/desk-session`, `agent.desk.session()`) and hands it to the
+  desk over `postMessage` — never in the URL, never stored. The desk asks for a
+  new one before it expires. When your session ends for good (sign-out,
+  member suspended or deleted, app paused) the desk shows "ended" at once and
+  `onEnded` fires. Revoking sessions alone does not end the desk: the SDK signs
+  in again with a fresh assertion (see Sessions above).
+- The desk token works only for the desk's own work (conversations, calls,
+  contacts, tickets…). Settings, team, billing, developer and admin pages are
+  refused, and it can never switch organisation.
+- The iframe is created with
+  `sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox allow-downloads allow-modals"`
+  (never top navigation: the desk cannot navigate your page) and
+  `allow="microphone; camera; autoplay; clipboard-write"`. On the web **the desk
+  carries calls itself (WebRTC)**; if your own iframe or Permissions-Policy does
+  not delegate the microphone, or the person refuses it, `onMediaError(name)`
+  tells you.
+- Messages are read only from that iframe's window **and** the desk origin, and
+  only in the documented shapes; everything is sent to the desk origin only.
+
+React Native — calls stay native in your app (`@hainiva/react-native-call`),
+the desk hands them to you:
+
+```tsx
+import { WebView } from "react-native-webview";
+import { HainivaDesk } from "@hainiva/agent-sdk/react-native";
+
+<HainivaDesk agent={agent} appId={APP_ID} baseUrl="https://app.hainiva.com" WebView={WebView}
+  onDial={(number, contactId) => placeCall(number, contactId)}
+  onDialer={(prefill) => openDialer(prefill)}
+  onOpenUrl={(url) => Linking.openURL(url)}
+  onEnded={(reason) => signOut(reason)} />
+```
+
+The WebView stays on the desk origin (`originWhitelist`, every other URL goes
+to `onOpenUrl`), opens no windows, and gets its bridge before the desk's
+scripts, on the desk origin only.
+
+## Documentation
+
+- [HAINIVA developer docs](https://hainiva.com/en/developers/docs) — start with
+  [Quickstart: your own staff app](https://hainiva.com/en/developers/docs/quickstart-staff-app), then
+  [Staff sign-in and agent apps](https://hainiva.com/en/developers/docs/staff-sign-in),
+  [Agent API](https://hainiva.com/en/developers/docs/agent-api), [Events](https://hainiva.com/en/developers/docs/events),
+  [Push setup](https://hainiva.com/en/developers/docs/push-setup) and [Embedded desk](https://hainiva.com/en/developers/docs/embedded-desk).
+- [API reference](https://api.hainiva.com/docs/) — every endpoint, request and
+  error code.
+- [Troubleshooting](https://hainiva.com/en/developers/docs/troubleshooting).
+- Sibling SDKs: [`@hainiva/react-native-call`](https://github.com/hainiva/react-native-call)
+  (native ringing) and [`@hainiva/app-sdk`](https://github.com/hainiva/app-sdk)
+  (your customers' app, the App channel).
+
 ## Security
 
 - **No tokens in URLs or logs.** Tokens travel in the `Authorization` header or

package/dist/cjs/agent.cjs

@@ -33,6 +33,10 @@ class HainivaAgent {
         this.meDto = null;
         this.media = new Map();
         this.offs = [];
+        this.desk = {
+            /** A desk token for the embedded desk (`@hainiva/agent-sdk/embed` mountDesk / `<HainivaDesk/>` call this). */
+            session: () => this.guard(this.rest.deskSession()),
+        };
         this.rings = {
             /** Rings waiting for you now (also fed into the call state). */
             pending: () => this.syncRings(),

package/dist/cjs/agent.d.cts

@@ -12,7 +12,7 @@
  * (`media`, `WebSocket`, `store`), so the core runs in Node too.
  */
 import { CallStore, type CallEffect, type CallsState, type TransferTarget } from "./calls.cjs";
-import type { AgentAcceptDto, AgentCallEndedData, AgentCallRingingData, AgentConversationDto, AgentDispositionDto, AgentMeDto, AgentMessageDto, AgentPage, AgentPushSubscriptionDto, AgentPushSubscriptionInput, AgentRingDto, AgentSessionDto, SupervisorAgentDto, SupervisorLiveCallDto, SupervisorSuperviseDto } from "./contract.cjs";
+import type { AgentAcceptDto, AgentCallEndedData, AgentDeskSessionDto, AgentCallRingingData, AgentConversationDto, AgentDispositionDto, AgentMeDto, AgentMessageDto, AgentPage, AgentPushSubscriptionDto, AgentPushSubscriptionInput, AgentRingDto, AgentSessionDto, SupervisorAgentDto, SupervisorLiveCallDto, SupervisorSuperviseDto } from "./contract.cjs";
 import { TypedEmitter } from "./emitter.cjs";
 import { HainivaAgentError } from "./errors.cjs";
 import { type AgentEventFrame } from "./events.cjs";
@@ -131,6 +131,10 @@ export declare class HainivaAgent {
     setStatus(status: AgentStatus, o?: RequestOptions): Promise<{
         status: AgentStatus;
     }>;
+    readonly desk: {
+        /** A desk token for the embedded desk (`@hainiva/agent-sdk/embed` mountDesk / `<HainivaDesk/>` call this). */
+        session: () => Promise<AgentDeskSessionDto>;
+    };
     readonly rings: {
         /** Rings waiting for you now (also fed into the call state). */
         pending: () => Promise<AgentRingDto[]>;

package/dist/cjs/contract.d.cts

@@ -142,6 +142,16 @@ export interface AgentSessionDto {
     /** The event socket on the host the app reached; SDKs derive their own from their base URL. */
     wsUrl: string;
 }
+/**
+ * POST /agent/v1/desk-session (201) — partner platform S4, the embeddable desk.
+ * A 15-minute token for the HAINIVA desk shown inside the partner's product,
+ * handed to the desk over postMessage only (never in a URL, never stored).
+ * Bound to the agent session it came from: ends when that session ends.
+ */
+export interface AgentDeskSessionDto {
+    token: string;
+    expiresAt: string;
+}
 /** POST /agent/v1/calls/:id/accept. `media` is null for a call without a room (chat). */
 export interface AgentAcceptDto {
     callId: string;

package/dist/cjs/embed.cjs

@@ -1,11 +1,253 @@
 "use strict";
-/**
- * @hainiva/agent-sdk/embed — the embeddable HAINIVA desk (iframe / WebView with a
- * postMessage bridge). Planned for milestone M3; not part of this release.
- */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DESK_ALLOW = exports.DESK_SANDBOX = exports.DeskHost = void 0;
+exports.parseDeskMessage = parseDeskMessage;
+exports.deskUrl = deskUrl;
 exports.mountDesk = mountDesk;
-/** Not yet available: throws. */
-function mountDesk(_options) {
-    throw new Error("@hainiva/agent-sdk/embed is not yet available");
+const errors_js_1 = require("./errors.cjs");
+const url_js_1 = require("./url.cjs");
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const END_REASONS = new Set(["not_embedded", "no_host", "expired", "revoked", "host_ended", "misconfigured"]);
+const PHONE = /^[0-9+*#() .-]{1,40}$/;
+function keysAre(o, required, optional = []) {
+    const k = Object.keys(o);
+    return required.every((r) => k.includes(r)) && k.every((x) => required.includes(x) || optional.includes(x));
+}
+const optId = (v) => v === undefined || (typeof v === "string" && UUID.test(v));
+/** Exactly one of the desk's messages, or null. */
+function parseDeskMessage(data) {
+    let d = data;
+    if (typeof d === "string") {
+        if (d.length > 8192)
+            return null;
+        try {
+            d = JSON.parse(d);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!d || typeof d !== "object" || Array.isArray(d))
+        return null;
+    const o = d;
+    if (o["v"] !== 1)
+        return null;
+    switch (o["type"]) {
+        case "hainiva:ready":
+            return keysAre(o, ["v", "type", "appId"]) && typeof o["appId"] === "string" && UUID.test(o["appId"]) ? { v: 1, type: "hainiva:ready", appId: o["appId"] } : null;
+        case "hainiva:token-request":
+            return keysAre(o, ["v", "type", "reason"]) && (o["reason"] === "expiring" || o["reason"] === "unauthorized") ? { v: 1, type: "hainiva:token-request", reason: o["reason"] } : null;
+        case "hainiva:ended":
+            return keysAre(o, ["v", "type", "reason"]) && typeof o["reason"] === "string" && END_REASONS.has(o["reason"])
+                ? { v: 1, type: "hainiva:ended", reason: o["reason"] } : null;
+        case "hainiva:dial":
+            if (!keysAre(o, ["v", "type", "number"], ["contactId"]) || typeof o["number"] !== "string" || !PHONE.test(o["number"]) || !optId(o["contactId"]))
+                return null;
+            return { v: 1, type: "hainiva:dial", number: o["number"], ...(o["contactId"] ? { contactId: o["contactId"] } : {}) };
+        case "hainiva:dialer":
+            if (!keysAre(o, ["v", "type"], ["number", "contactId"]) || !optId(o["contactId"]))
+                return null;
+            if (o["number"] !== undefined && (typeof o["number"] !== "string" || !PHONE.test(o["number"])))
+                return null;
+            return { v: 1, type: "hainiva:dialer", ...(o["number"] ? { number: o["number"] } : {}), ...(o["contactId"] ? { contactId: o["contactId"] } : {}) };
+        case "hainiva:open-url": {
+            if (!keysAre(o, ["v", "type", "url"]) || typeof o["url"] !== "string" || o["url"].length > 2048)
+                return null;
+            let u;
+            try {
+                u = new URL(o["url"]);
+            }
+            catch {
+                return null;
+            }
+            return ["https:", "http:", "mailto:", "tel:"].includes(u.protocol) ? { v: 1, type: "hainiva:open-url", url: u.href } : null;
+        }
+        case "hainiva:media-error":
+            return keysAre(o, ["v", "type", "name"]) && typeof o["name"] === "string" && o["name"].length <= 60 ? { v: 1, type: "hainiva:media-error", name: o["name"] } : null;
+        default:
+            return null;
+    }
+}
+/**
+ * The host side of the desk protocol, transport-agnostic: `mountDesk` (iframe)
+ * and `<HainivaDesk/>` (React Native WebView) both drive one.
+ * @internal exported for the React Native entry and tests.
+ */
+class DeskHost {
+    constructor(appId, source, send, cb) {
+        this.appId = appId;
+        this.source = source;
+        this.send = send;
+        this.cb = cb;
+        this.ended = false;
+        this.ready = false;
+        this.inflight = null;
+    }
+    get isReady() { return this.ready; }
+    get isEnded() { return this.ended; }
+    /** A raw message from the desk (already origin/source-checked by the transport). */
+    receive(raw) {
+        if (this.ended)
+            return;
+        const m = parseDeskMessage(raw);
+        if (!m)
+            return;
+        switch (m.type) {
+            case "hainiva:ready":
+                if (m.appId.toLowerCase() !== this.appId.toLowerCase())
+                    return;
+                this.ready = true;
+                void this.supplyToken();
+                return;
+            case "hainiva:token-request":
+                void this.supplyToken();
+                return;
+            case "hainiva:ended":
+                this.finish(m.reason, false);
+                return;
+            case "hainiva:dial":
+                this.cb.onDial?.(m.number, m.contactId);
+                return;
+            case "hainiva:dialer":
+                this.cb.onDialer?.({ ...(m.number ? { number: m.number } : {}), ...(m.contactId ? { contactId: m.contactId } : {}) });
+                return;
+            case "hainiva:open-url":
+                this.cb.onOpenUrl?.(m.url);
+                return;
+            case "hainiva:media-error":
+                this.cb.onMediaError?.(m.name);
+                return;
+        }
+    }
+    /** One desk-session request at a time; the token goes to the desk only. */
+    supplyToken() {
+        if (this.ended)
+            return Promise.resolve();
+        this.inflight ?? (this.inflight = (async () => {
+            try {
+                const d = await this.source.desk.session();
+                if (!this.ended)
+                    this.send({ v: 1, type: "hainiva:token", token: d.token, expiresAt: d.expiresAt });
+            }
+            catch (e) {
+                // A final refusal of the agent session: the desk ends with it. A
+                // transient failure: the desk asks again (or ends on its own timeout).
+                const final = e instanceof errors_js_1.HainivaAgentError && (e.status === 401 || e.status === 403);
+                if (final)
+                    this.finish("session_ended", true);
+            }
+            finally {
+                this.inflight = null;
+            }
+        })());
+        return this.inflight;
+    }
+    setTheme(mode) { if (mode === "light" || mode === "dark")
+        this.send({ v: 1, type: "hainiva:theme", mode }); }
+    setLocale(locale) { if (locale === "vi" || locale === "en")
+        this.send({ v: 1, type: "hainiva:locale", locale }); }
+    finish(reason, tellDesk) {
+        if (this.ended)
+            return;
+        if (tellDesk) {
+            try {
+                this.send({ v: 1, type: "hainiva:end" });
+            }
+            catch { /* gone */ }
+        }
+        this.ended = true;
+        this.cb.onEnded?.(reason);
+    }
+}
+exports.DeskHost = DeskHost;
+/** The desk page for an app. The URL carries the app id ONLY. */
+function deskUrl(baseUrl, appId, opts = {}) {
+    if (!UUID.test(appId))
+        throw new errors_js_1.HainivaAgentError(0, "invalid_id", { field: "appId" });
+    const base = (0, url_js_1.assertSafeUrl)(baseUrl, { kind: "http", ...(opts.allowInsecureLocalhost ? { allowInsecureLocalhost: true } : {}) });
+    const u = new URL("/embed", base.origin);
+    u.searchParams.set("app", appId.toLowerCase());
+    return u;
+}
+// ── Web: the iframe ──────────────────────────────────────────────────────────
+/**
+ * The iframe's sandbox — every flag the desk needs and nothing more:
+ *   allow-scripts                 the desk is an application;
+ *   allow-same-origin             the desk keeps ITS OWN origin (app.hainiva.com):
+ *                                 its same-origin API calls, its session storage
+ *                                 and the gateway's Origin check depend on it. It
+ *                                 gives the desk no access to your page — that is
+ *                                 a different origin;
+ *   allow-forms                   the composer and every dialog submit forms;
+ *   allow-popups                  links, recordings and help open in a new tab…
+ *   allow-popups-to-escape-sandbox …as normal pages, not sandboxed copies;
+ *   allow-downloads               call recordings, attachments, exports;
+ *   allow-modals                  the desk confirms destructive actions (confirm()).
+ * Deliberately NOT: allow-top-navigation(-by-user-activation) — the desk can
+ * never navigate your page; allow-pointer-lock, allow-presentation,
+ * allow-orientation-lock, allow-storage-access-by-user-activation.
+ */
+exports.DESK_SANDBOX = "allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox allow-downloads allow-modals";
+/** Calls in the iframe are WebRTC: the microphone (and camera for video) must be delegated. */
+exports.DESK_ALLOW = "microphone; camera; autoplay; clipboard-write";
+/** Show the HAINIVA desk in `container`, signed in as your agent session's staff member. */
+function mountDesk(container, o) {
+    if (!container || typeof container.appendChild !== "function")
+        throw new errors_js_1.HainivaAgentError(0, "invalid_container", {});
+    if (!o?.agent?.desk || typeof o.agent.desk.session !== "function")
+        throw new errors_js_1.HainivaAgentError(0, "invalid_agent", {});
+    const url = deskUrl(o.baseUrl, o.appId, o.allowInsecureLocalhost ? { allowInsecureLocalhost: true } : {});
+    const deskOrigin = url.origin;
+    const doc = container.ownerDocument ?? globalThis.document;
+    const win = (doc?.defaultView ?? globalThis);
+    if (!doc)
+        throw new errors_js_1.HainivaAgentError(0, "no_document", {});
+    if (win.location?.origin === deskOrigin)
+        throw new errors_js_1.HainivaAgentError(0, "same_origin_host", { origin: deskOrigin });
+    const iframe = doc.createElement("iframe");
+    iframe.setAttribute("sandbox", exports.DESK_SANDBOX);
+    iframe.setAttribute("allow", exports.DESK_ALLOW);
+    iframe.setAttribute("title", o.title ?? "HAINIVA");
+    iframe.setAttribute("referrerpolicy", "origin");
+    iframe.style.border = "0";
+    iframe.style.width = "100%";
+    iframe.style.height = "100%";
+    const host = new DeskHost(o.appId, o.agent, (m) => { iframe.contentWindow?.postMessage(m, deskOrigin); }, {
+        ...o,
+        onEnded: (r) => { clearTimeout(loadTimer); o.onEnded?.(r); },
+    });
+    const onMessage = (e) => {
+        if (e.source !== iframe.contentWindow || e.origin !== deskOrigin)
+            return;
+        const wasReady = host.isReady;
+        host.receive(e.data);
+        if (!wasReady && host.isReady) {
+            clearTimeout(loadTimer);
+            if (o.theme)
+                host.setTheme(o.theme);
+            if (o.locale)
+                host.setLocale(o.locale);
+        }
+    };
+    win.addEventListener("message", onMessage);
+    const loadTimer = setTimeout(() => { if (!host.isReady)
+        host.finish("load_failed", false); }, o.loadTimeoutMs ?? 20000);
+    iframe.setAttribute("src", url.href);
+    container.appendChild(iframe);
+    return {
+        iframe,
+        setTheme: (m) => host.setTheme(m),
+        setLocale: (l) => host.setLocale(l),
+        destroy: () => {
+            clearTimeout(loadTimer);
+            if (!host.isEnded) {
+                try {
+                    iframe.contentWindow?.postMessage({ v: 1, type: "hainiva:end" }, deskOrigin);
+                }
+                catch { /* gone */ }
+            }
+            win.removeEventListener("message", onMessage);
+            iframe.remove();
+        },
+    };
 }