@sophonsai/agent-embed-sdk 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,321 @@
-# Temporary Holding Version
+# @sophonsai/agent-embed-sdk
 
-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.
+## 应用接入
+
+传入服务地址 `endpoint` 和 Agent 的应用接入 `token`；可选 `baseUrl` 默认是 `/e/v1/embed`。
+最终 iframe 地址是 `endpoint + baseUrl + '/' + encodeURIComponent(token)`。
+
+```ts
+const client = createAgentEmbed({ endpoint: 'https://agent.example.com', token: '应用接入Token' })
+await client.mount(document.getElementById('agent-embed')!)
+```
+
+不再接收完整 `url`、旧 `initConfig`、Agent ID 或平台用户凭证。
+`threadId`、外观配置、实例命令和事件回调继续支持。
+
+## 安装
+
+```bash
+# npm
+npm install @sophonsai/agent-embed-sdk
+
+# pnpm
+pnpm add @sophonsai/agent-embed-sdk
+
+# yarn
+yarn add @sophonsai/agent-embed-sdk
+
+# bun
+bun add @sophonsai/agent-embed-sdk
+```
+
+## 快速开始
+
+```html
+<div id="agent-embed" style="height: 640px"></div>
+```
+
+```ts
+import { createAgentEmbed, type AgentAppearance, type AgentEmbedInstance } from '@sophonsai/agent-embed-sdk'
+
+const appearance: AgentAppearance = {
+  theme: { preset: 'glacier-blue' },
+  fontSize: 16,
+  header: {
+    historyButton: true,
+    newConversationButton: true,
+    themeSettingButton: false,
+  },
+}
+
+const client = createAgentEmbed({
+  endpoint: 'https://agent.example.com',
+  token: '应用接入Token',
+  threadId: 'optional-conversation-id',
+  appearance,
+  onReady(instance) {
+    instance.focusInput()
+  },
+  onInitError({ code, message }) {
+    console.error('初始化失败', code, message)
+  },
+  onSettled(result) {
+    console.log('本轮会话结束', result)
+  },
+})
+
+const container = document.getElementById('agent-embed')!
+
+await client.mount(container)
+const instance: AgentEmbedInstance = await client.whenReady()
+
+instance.sendMessage({ text: '你好，请介绍一下自己' })
+```
+
+页面退出或不再使用面板时应主动销毁：
+
+```ts
+client.destroy()
+```
+
+## 初始化配置
+
+| 配置                | 类型                    | 必填 | 说明                                            |
+| ------------------- | ----------------------- | ---- | ----------------------------------------------- |
+| `endpoint`          | `string`                | 是   | Gateway / Extension 服务地址，包含 HTTP(S) 协议 |
+| `token`             | `string`                | 是   | Agent 应用接入凭证                              |
+| `baseUrl`           | `string`                | 否   | 嵌入页面路径，默认 `/e/v1/embed`                |
+| `threadId`          | `string`                | 否   | 初始会话 ID                                     |
+| `runtime_variables` | `AgentRuntimeVariables` | 否   | 新会话绑定的运行时变量，值必须为 JSON           |
+| `appearance`        | `AgentAppearance`       | 否   | 主题、字号与 Header 按钮                        |
+
+`endpoint` 可包含反向代理路径前缀；`baseUrl` 必须是以 `/` 开头的路径。
+凭证只写入 iframe 路径，bridge 初始化消息不再传递凭证或 Agent ID。
+配置与回调在创建 client 时保存为快照；切换接入地址、token、会话或回调时，销毁并重新创建 client。
+外观可以使用 `updateTheme`、`updateFontSize`、`updateHeader` 更新。
+
+## 外观配置
+
+```ts
+const appearance: AgentAppearance = {
+  theme: { preset: 'studio-white' },
+  fontSize: 16,
+  header: {
+    historyButton: true,
+    newConversationButton: true,
+    themeSettingButton: true,
+  },
+}
+```
+
+`header.themeSettingButton` 默认值为 `false`，只有显式设置为 `true` 时才显示主题设置按钮。
+
+### 可用主题
+
+可以使用 `AgentEmbedThemePreset` 枚举式常量设置主题：
+
+```ts
+import { AgentEmbedThemePreset } from '@sophonsai/agent-embed-sdk'
+
+client.updateTheme({ preset: AgentEmbedThemePreset.GlacierBlue })
+```
+
+| 主题名 | preset            | 类型     |
+| ------ | ----------------- | -------- |
+| 曜石紫 | `obsidian-violet` | 深色主题 |
+| 石墨青 | `graphite-cyan`   | 深色主题 |
+| 午夜靛 | `midnight-indigo` | 深色主题 |
+| 深海蓝 | `deep-ocean`      | 深色主题 |
+| 森野绿 | `forest-emerald`  | 深色主题 |
+| 影棚白 | `studio-white`    | 浅色主题 |
+| 珍珠紫 | `pearl-violet`    | 浅色主题 |
+| 冰川蓝 | `glacier-blue`    | 浅色主题 |
+| 暖杏色 | `warm-cream`      | 浅色主题 |
+| 薰衣草 | `lavender-mist`   | 浅色主题 |
+
+### 动态更新
+
+创建 client 后，只有外观支持动态更新：
+
+```ts
+client.updateTheme({ preset: 'warm-cream' })
+client.updateFontSize(18)
+client.updateHeader({
+  historyButton: false,
+  newConversationButton: true,
+  themeSettingButton: false,
+})
+```
+
+传入 `undefined` 会撤销对应的受控配置，让面板恢复内部默认值：
+
+```ts
+client.updateTheme(undefined)
+client.updateFontSize(undefined)
+client.updateHeader(undefined)
+```
+
+面板内部主动切换主题或字号时，会调用 `onThemeChange` 或 `onFontSizeChange`。如果宿主把这些字段作为受控状态，应在回调中同步外部状态，再调用相应的更新方法。
+
+## `mount` 与 `ready`
+
+这两个阶段含义不同：
+
+```text
+挂载面板
+  → mount 完成
+  → 鉴权并加载智能体
+  → 面板就绪
+  → whenReady 完成
+```
+
+### `mount(container)`
+
+`mount()` 会把 SDK 管理的面板挂载到指定容器。`mount()` 完成只表示面板已经启动，不表示面板已经初始化完成。
+
+以下情况会让 `mount()` reject：
+
+- client 已销毁；
+- 同一个 client 被重复挂载；
+- 面板无法挂载到指定容器；
+- 面板启动失败；
+- 在挂载完成前调用了 `destroy()`。
+
+当前没有内置 mount 超时。如果面板持续处于加载中且没有返回错误，Promise 会保持 pending，业务可按需在外层增加超时。
+
+### `whenReady()`
+
+`whenReady()` 等待面板初始化完成，并返回可调用的 `AgentEmbedInstance`。它可以调用多次；ready 后再次调用会立即返回同一个 instance。
+
+在 ready 之前调用 instance 命令会抛出 `AgentEmbed is not ready.`。推荐只保存 `whenReady()` 或 `onReady` 返回的实例。
+
+初始化失败通过 `onInitError` 报告，同时 `whenReady()` reject。Vue 使用 `@init-error`。
+
+## 实例方法
+
+`AgentEmbedInstance` 提供以下命令：
+
+| 方法                                | 说明                                                    |
+| ----------------------------------- | ------------------------------------------------------- |
+| `sendMessage({ text })`             | 立即提交一条消息；正在生成回复时会使用面板的 steer 行为 |
+| `addInputQuery({ text, context? })` | 把文本和可选上下文写入输入框，但不立即提交              |
+| `abortResponse()`                   | 终止当前回复                                            |
+| `openHistoryPanel()`                | 打开历史会话面板                                        |
+| `openThemeSettingsPanel()`          | 打开主题设置面板                                        |
+| `newConversation()`                 | 新建会话                                                |
+| `focusInput()`                      | 聚焦输入框                                              |
+| `scrollToBottom()`                  | 滚动到消息底部                                          |
+
+示例：
+
+```ts
+const agent = await client.whenReady()
+
+agent.addInputQuery({
+  text: '请解释这段内容',
+  context: '用户在页面中选中的文本',
+})
+agent.focusInput()
+```
+
+## 生命周期回调
+
+| 回调               | 参数                  | 说明                 |
+| ------------------ | --------------------- | -------------------- |
+| `onReady`          | `AgentEmbedInstance`  | 面板初始化完成       |
+| `onThemeChange`    | `AgentEmbedTheme`     | 面板内部主题发生变化 |
+| `onFontSizeChange` | `number`              | 面板内部字号发生变化 |
+| `onInitError`      | `AgentEmbedInitError` | 初始化失败           |
+
+### `onReady(instance)`
+
+面板初始化完成后调用，参数与 `whenReady()` 返回值相同。
+
+### `onInitError(error)`
+
+初始化失败时调用一次，`error` 包含 `code` 和 `message`：
+
+| code                | 含义                  |
+| ------------------- | --------------------- |
+| `invalid_token`     | 凭证无效或已失效      |
+| `forbidden`         | 当前凭证无访问权限    |
+| `agent_not_found`   | 智能体不存在          |
+| `request_failed`    | 网络或服务请求失败    |
+| `frame_load_failed` | iframe 加载或挂载失败 |
+
+失败后不会触发 `onReady`，当前与后续 `whenReady()` 都会 reject，拒绝值为包含相同 `code`、`message` 的 `Error`。握手前失败还会使 `mount()` reject；已完成的 `mount()` 不受影响。聊天运行失败仍使用 `onError`。
+
+## 会话事件
+
+可以在 `createAgentEmbed()` 中传入以下全部运行事件回调：
+
+| 回调                        | 参数                                                            | 说明                                        |
+| --------------------------- | --------------------------------------------------------------- | ------------------------------------------- |
+| `onConcurrentSend`          | 无                                                              | 回复生成期间再次发送消息                    |
+| `onEvent`                   | `AgentServerEvent`                                              | 接收原始服务端事件                          |
+| `onSessionContextReady`     | `AgentSessionContext`                                           | 会话上下文可用，包含 `threadId` 和 `turnId` |
+| `onToolCallCreated`         | `AgentToolCallCreatedEvent`, `AgentSessionEventContext`         | 创建一个工具调用                            |
+| `onToolApprovalRequested`   | `AgentToolApprovalRequestedEvent`, `AgentSessionEventContext`   | 一组工具调用需要确认                        |
+| `onToolCallStarted`         | `AgentToolCallStartedEvent`, `AgentSessionEventContext`         | 工具调用开始                                |
+| `onToolCallProgressUpdated` | `AgentToolCallProgressUpdatedEvent`, `AgentSessionEventContext` | 工具调用进度更新                            |
+| `onToolCallBackgrounded`    | `AgentToolCallBackgroundedEvent`, `AgentSessionEventContext`    | 工具调用转为后台执行                        |
+| `onToolCallSucceeded`       | `AgentToolCallSucceededEvent`, `AgentSessionEventContext`       | 工具调用成功                                |
+| `onToolCallFailed`          | `AgentToolCallFailedEvent`, `AgentSessionEventContext`          | 工具调用失败                                |
+| `onToolCallCancelled`       | `AgentToolCallCancelledEvent`, `AgentSessionEventContext`       | 工具调用取消                                |
+| `onClientActionRequest`     | `AgentClientActionRequestEvent`, `AgentSessionEventContext`     | 智能体请求宿主执行客户端动作                |
+| `onUserFeedbackConsumed`    | `AgentUserFeedbackConsumedEvent`, `AgentSessionEventContext`    | 用户反馈已被处理                            |
+| `onUserSteerConsumed`       | `AgentUserSteerConsumedEvent`, `AgentSessionEventContext`       | 用户 steer 指令已被处理                     |
+| `onUserSteerCancelled`      | `AgentUserSteerCancelledEvent`, `AgentSessionRunEventContext`   | 用户 steer 指令已取消                       |
+| `onUserInputSubmitted`      | `AgentUserInputSubmittedEvent`, `AgentSessionEventContext`      | 用户输入已提交                              |
+| `onSessionTurnStarted`      | `AgentSessionTurnStartedEvent`, `AgentSessionEventContext`      | Turn 开始执行                               |
+| `onSessionTurnSucceeded`    | `AgentSessionTurnSucceededEvent`, `AgentSessionEventContext`    | Turn 执行成功                               |
+| `onSessionTurnFailed`       | `AgentSessionTurnFailedEvent`, `AgentSessionEventContext`       | Turn 执行失败                               |
+| `onSessionTurnCancelled`    | `AgentSessionTurnCancelledEvent`, `AgentSessionEventContext`    | Turn 已取消                                 |
+| `onSessionRunStarted`       | `AgentSessionRunStartedEvent`, `AgentSessionRunEventContext`    | Run 已开始                                  |
+| `onSessionRunIdled`         | `AgentSessionRunIdledEvent`, `AgentSessionRunEventContext`      | Run 已空闲                                  |
+| `onSessionRunEnded`         | `AgentSessionRunEndedEvent`, `AgentSessionRunEventContext`      | Run 已结束                                  |
+| `onSystemMessageConsumed`   | `AgentSystemMessageConsumedEvent`, `AgentSessionEventContext`   | 系统消息已被处理                            |
+| `onSuccess`                 | `AgentSessionSuccess`                                           | 本轮会话成功结束                            |
+| `onError`                   | `AgentSessionFailure`                                           | 本轮会话失败                                |
+| `onCancelled`               | `AgentSessionCancelled`                                         | 本轮会话取消                                |
+| `onSettled`                 | `AgentSessionSettlement`                                        | 本轮会话以任意状态结束                      |
+
+所有事件、事件参数及上下文类型都从包中导出，可以直接用于 TypeScript 标注。
+
+```ts
+const client = createAgentEmbed({
+  endpoint,
+  token,
+  onToolCallFailed(event, context) {
+    console.error(context.turnId, event.toolName, event.error)
+  },
+  onSettled(result) {
+    if (result.status === 'failure') console.error(result.error)
+  },
+})
+```
+
+用户回调内部抛出的异常会被 SDK 隔离，不会影响其他回调或面板后续运行。
+
+## 销毁与清理
+
+```ts
+client.destroy()
+```
+
+`destroy()` 会：
+
+- 移除面板；
+- 注销浏览器事件监听器；
+- 拒绝尚未完成的 mount/ready 等待；
+- 使 client 和已经获得的 instance 失效。
+
+重复调用 `destroy()` 是安全的。销毁后调用外观更新或实例命令会抛错，销毁后的 client 也不能重新挂载。
+
+### 运行时变量
+
+`runtime_variables` 是可选的 JSON 对象，名称须与智能体声明的运行时变量一致。仅创建新会话时发送，已有会话沿用已绑定的变量；同一面板新建会话时复用初始化值。参数在初始化时生成快照，改变值需要重建面板。数据通过 iframe 消息传递，不写入接入 URL。
+
+```ts
+const panel = createAgentEmbed({ endpoint, token, runtime_variables: { customer_id: 'customer-1' } })
+```

package/dist/index.d.mts

@@ -0,0 +1,54 @@
+import { AgentAppearance as AgentAppearance$1, AgentEmbedHeaderAppearance, AgentEmbedInitError, AgentEmbedInstance, AgentEmbedTheme as AgentEmbedTheme$1, AgentEvents, AgentRuntimeVariables } from "@sophonsai/agent-embed-core";
+export * from "@sophonsai/agent-embed-core";
+//#region src/theme-presets.d.ts
+declare const AgentEmbedThemePreset: {
+  readonly ObsidianViolet: "obsidian-violet";
+  readonly GraphiteCyan: "graphite-cyan";
+  readonly MidnightIndigo: "midnight-indigo";
+  readonly DeepOcean: "deep-ocean";
+  readonly ForestEmerald: "forest-emerald";
+  readonly StudioWhite: "studio-white";
+  readonly PearlViolet: "pearl-violet";
+  readonly GlacierBlue: "glacier-blue";
+  readonly WarmCream: "warm-cream";
+  readonly LavenderMist: "lavender-mist";
+};
+type AgentEmbedThemePreset = (typeof AgentEmbedThemePreset)[keyof typeof AgentEmbedThemePreset];
+//#endregion
+//#region src/index.d.ts
+interface AgentEmbedTheme extends Omit<AgentEmbedTheme$1, 'preset'> {
+  preset: AgentEmbedThemePreset;
+}
+interface AgentAppearance extends Omit<AgentAppearance$1, 'theme'> {
+  theme?: AgentEmbedTheme;
+}
+interface AgentEmbedOptions extends AgentEvents {
+  appearance?: AgentAppearance;
+  onReady?: (instance: AgentEmbedInstance) => void;
+  onThemeChange?: (theme: AgentEmbedTheme) => void;
+  onFontSizeChange?: (fontSize: number) => void;
+  onInitError?: (error: AgentEmbedInitError) => void;
+}
+interface CreateAgentEmbedOptions extends AgentEmbedOptions {
+  /** Gateway / Extension service address, including HTTP or HTTPS scheme. */
+  endpoint: string;
+  /** Shared Agent access token. */
+  token: string;
+  /** Embed page path. Defaults to /e/v1/embed. */
+  baseUrl?: string;
+  threadId?: string;
+  /** JSON values bound to each new conversation; snapshotted at client creation. */
+  runtime_variables?: AgentRuntimeVariables;
+}
+interface AgentEmbedClient {
+  mount(container: HTMLElement): Promise<void>;
+  whenReady(): Promise<AgentEmbedInstance>;
+  updateTheme(theme: AgentEmbedTheme | undefined): void;
+  updateFontSize(fontSize: number | undefined): void;
+  updateHeader(header: AgentEmbedHeaderAppearance | undefined): void;
+  destroy(): void;
+}
+declare const DEFAULT_AGENT_EMBED_BASE_URL = "/e/v1/embed";
+declare const createAgentEmbed: (options: CreateAgentEmbedOptions) => AgentEmbedClient;
+//#endregion
+export { AgentAppearance, AgentEmbedClient, AgentEmbedTheme, AgentEmbedThemePreset, CreateAgentEmbedOptions, DEFAULT_AGENT_EMBED_BASE_URL, createAgentEmbed };

package/dist/index.mjs

@@ -0,0 +1,273 @@
+import { AGENT_EMBED_BRIDGE, AGENT_EMBED_BRIDGE_VERSION, AGENT_EMBED_QUERY_PARAMS, AGENT_EVENT_NAMES, isAgentEmbedFrameMessage, isAgentRuntimeVariables } from "@sophonsai/agent-embed-core";
+export * from "@sophonsai/agent-embed-core";
+//#region src/theme-presets.ts
+const AgentEmbedThemePreset = {
+	ObsidianViolet: "obsidian-violet",
+	GraphiteCyan: "graphite-cyan",
+	MidnightIndigo: "midnight-indigo",
+	DeepOcean: "deep-ocean",
+	ForestEmerald: "forest-emerald",
+	StudioWhite: "studio-white",
+	PearlViolet: "pearl-violet",
+	GlacierBlue: "glacier-blue",
+	WarmCream: "warm-cream",
+	LavenderMist: "lavender-mist"
+};
+//#endregion
+//#region src/index.ts
+const DEFAULT_AGENT_EMBED_BASE_URL = "/e/v1/embed";
+const createInstanceId = () => `agent-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+const pickAgentEvents = (source) => Object.fromEntries(AGENT_EVENT_NAMES.map((name) => [name, source[name]]));
+const cloneAppearance = (appearance) => {
+	const result = {};
+	if (appearance?.theme) result.theme = { ...appearance.theme };
+	if (appearance?.fontSize !== void 0) result.fontSize = appearance.fontSize;
+	if (appearance?.header) result.header = { ...appearance.header };
+	return result;
+};
+var AgentEmbedClientImpl = class {
+	constructor(options) {
+		this.instanceId = createInstanceId();
+		this.mounted = false;
+		this.initialized = false;
+		this.ready = false;
+		this.destroyed = false;
+		this.readyWaiters = /* @__PURE__ */ new Set();
+		this.handleFrameError = () => {
+			this.failInitialization({
+				code: "frame_load_failed",
+				message: "Failed to load AgentEmbed iframe."
+			});
+		};
+		this.handleMessage = (event) => {
+			if (event.source !== this.iframe.contentWindow || event.origin !== this.targetOrigin) return;
+			if (!isAgentEmbedFrameMessage(event.data)) return;
+			const message = event.data;
+			if (message.type === "hello") {
+				const firstInitialization = !this.initialized;
+				this.initialized = true;
+				this.postInit();
+				if (firstInitialization) {
+					this.settleMount?.();
+					this.clearMountSettlement();
+				}
+				return;
+			}
+			if (message.instanceId !== this.instanceId) return;
+			if (message.type === "ready") {
+				if (this.ready || this.destroyed || this.initError) return;
+				this.ready = true;
+				this.resolveReadyWaiters();
+				try {
+					this.onReady?.(this.instance);
+				} catch {}
+				return;
+			}
+			if (message.type !== "callback" || !message.callback) return;
+			if (message.callback === "onThemeChange") {
+				try {
+					this.onThemeChange?.(message.args?.[0]);
+				} catch {}
+				return;
+			}
+			if (message.callback === "onFontSizeChange") {
+				try {
+					this.onFontSizeChange?.(message.args?.[0]);
+				} catch {}
+				return;
+			}
+			if (message.callback === "onInitError") {
+				this.failInitialization(message.args?.[0]);
+				return;
+			}
+			const callback = this.events[message.callback];
+			try {
+				callback?.(...message.args ?? []);
+			} catch {}
+		};
+		if (typeof options.token !== "string" || !options.token.trim() || options.token === "." || options.token === "..") throw new Error("A valid Agent access token is required.");
+		const endpoint = new URL(options.endpoint);
+		if (endpoint.protocol !== "https:" && endpoint.protocol !== "http:") throw new Error("Panel endpoint must use HTTP or HTTPS.");
+		const baseUrl = options.baseUrl ?? "/e/v1/embed";
+		if (!baseUrl.startsWith("/") || /[?#\s]/.test(baseUrl)) throw new Error("Panel baseUrl must be a pathname starting with /.");
+		const basePath = baseUrl.replace(/^\/+|\/+$/g, "");
+		endpoint.pathname = `${endpoint.pathname.replace(/\/+$/, "")}/${basePath ? `${basePath}/` : ""}${encodeURIComponent(options.token)}`;
+		endpoint.search = "";
+		endpoint.hash = "";
+		this.url = endpoint.toString();
+		if (options.runtime_variables !== void 0 && !isAgentRuntimeVariables(options.runtime_variables)) throw new Error("runtime_variables must be a JSON object.");
+		this.runtimeVariables = options.runtime_variables === void 0 ? void 0 : JSON.parse(JSON.stringify(options.runtime_variables));
+		this.threadId = options.threadId;
+		this.targetOrigin = endpoint.origin;
+		this.appearance = cloneAppearance(options.appearance);
+		this.events = pickAgentEvents(options);
+		this.onReady = options.onReady;
+		this.onThemeChange = options.onThemeChange;
+		this.onFontSizeChange = options.onFontSizeChange;
+		this.onInitError = options.onInitError;
+		this.instance = {
+			sendMessage: (input) => this.command("sendMessage", [{ text: input.text }]),
+			addInputQuery: (input) => this.command("addInputQuery", [input.context === void 0 ? { text: input.text } : {
+				text: input.text,
+				context: input.context
+			}]),
+			abortResponse: () => this.command("abortResponse", []),
+			openHistoryPanel: () => this.command("openHistoryPanel", []),
+			openThemeSettingsPanel: () => this.command("openThemeSettingsPanel", []),
+			newConversation: () => this.command("newConversation", []),
+			focusInput: () => this.command("focusInput", []),
+			scrollToBottom: () => this.command("scrollToBottom", [])
+		};
+		this.iframe = document.createElement("iframe");
+		this.iframe.title = "Agent chat";
+		this.iframe.allow = "microphone";
+		this.iframe.style.cssText = "display:block;width:100%;height:100%;border:0;background:transparent;";
+		this.iframe.src = this.createSrc();
+	}
+	mount(container) {
+		if (this.destroyed) return Promise.reject(/* @__PURE__ */ new Error("AgentEmbed has been destroyed."));
+		if (this.mounted) return Promise.reject(/* @__PURE__ */ new Error("AgentEmbed has already been mounted."));
+		this.mounted = true;
+		window.addEventListener("message", this.handleMessage);
+		this.iframe.addEventListener("error", this.handleFrameError);
+		const promise = new Promise((resolve, reject) => {
+			this.settleMount = resolve;
+			this.rejectMount = reject;
+		});
+		try {
+			container.appendChild(this.iframe);
+		} catch (error) {
+			this.failInitialization({
+				code: "frame_load_failed",
+				message: error instanceof Error ? error.message : "Failed to mount AgentEmbed."
+			});
+		}
+		return promise;
+	}
+	whenReady() {
+		if (this.destroyed) return Promise.reject(/* @__PURE__ */ new Error("AgentEmbed has been destroyed."));
+		if (this.initError) return Promise.reject(this.initError);
+		if (this.ready) return Promise.resolve(this.instance);
+		return new Promise((resolve, reject) => {
+			this.readyWaiters.add({
+				resolve,
+				reject
+			});
+		});
+	}
+	updateTheme(theme) {
+		this.updateAppearance({ theme: theme ? { ...theme } : null });
+	}
+	updateFontSize(fontSize) {
+		this.updateAppearance({ fontSize: fontSize ?? null });
+	}
+	updateHeader(header) {
+		this.updateAppearance({ header: header ? { ...header } : null });
+	}
+	destroy() {
+		if (this.destroyed) return;
+		const wasInitialized = this.initialized;
+		this.destroyed = true;
+		this.initialized = false;
+		this.ready = false;
+		window.removeEventListener("message", this.handleMessage);
+		this.iframe.removeEventListener("error", this.handleFrameError);
+		this.iframe.remove();
+		const error = /* @__PURE__ */ new Error(wasInitialized ? "AgentEmbed was destroyed before becoming ready." : "AgentEmbed was destroyed before mounting completed.");
+		this.rejectMount?.(error);
+		this.rejectReadyWaiters(error);
+		this.clearMountSettlement();
+	}
+	createSrc() {
+		const url = new URL(this.url);
+		if (this.threadId) url.searchParams.set(AGENT_EMBED_QUERY_PARAMS.threadId, this.threadId);
+		if (this.appearance.theme) url.searchParams.set(AGENT_EMBED_QUERY_PARAMS.theme, this.appearance.theme.preset);
+		if (this.appearance.fontSize !== void 0) url.searchParams.set(AGENT_EMBED_QUERY_PARAMS.fontSize, String(this.appearance.fontSize));
+		const headerParams = [
+			[AGENT_EMBED_QUERY_PARAMS.headerHistoryButton, this.appearance.header?.historyButton],
+			[AGENT_EMBED_QUERY_PARAMS.headerNewConversationButton, this.appearance.header?.newConversationButton],
+			[AGENT_EMBED_QUERY_PARAMS.headerThemeSettingButton, this.appearance.header?.themeSettingButton]
+		];
+		for (const [name, value] of headerParams) if (value !== void 0) url.searchParams.set(name, String(value));
+		return url.toString();
+	}
+	assertActive() {
+		if (this.destroyed) throw new Error("AgentEmbed has been destroyed.");
+	}
+	updateAppearance(patch) {
+		this.assertActive();
+		const appearance = cloneAppearance(this.appearance);
+		const messagePatch = {};
+		if (Object.prototype.hasOwnProperty.call(patch, "theme")) {
+			appearance.theme = patch.theme ? { ...patch.theme } : void 0;
+			messagePatch.theme = patch.theme ? { ...patch.theme } : null;
+		}
+		if (Object.prototype.hasOwnProperty.call(patch, "fontSize")) {
+			appearance.fontSize = patch.fontSize ?? void 0;
+			messagePatch.fontSize = patch.fontSize ?? null;
+		}
+		if (Object.prototype.hasOwnProperty.call(patch, "header")) {
+			appearance.header = patch.header ? { ...patch.header } : void 0;
+			messagePatch.header = patch.header ? { ...patch.header } : null;
+		}
+		this.appearance = appearance;
+		if (this.initialized) this.post({
+			type: "update-appearance",
+			appearance: messagePatch
+		});
+	}
+	command(action, args) {
+		this.assertActive();
+		if (!this.ready) throw new Error("AgentEmbed is not ready.");
+		this.post({
+			type: "command",
+			action,
+			args
+		});
+	}
+	postInit() {
+		this.post({
+			type: "init",
+			config: {
+				mode: "url",
+				threadId: this.threadId,
+				appearance: this.appearance,
+				...this.runtimeVariables === void 0 ? {} : { runtime_variables: this.runtimeVariables }
+			}
+		});
+	}
+	post(payload) {
+		this.iframe.contentWindow?.postMessage({
+			bridge: AGENT_EMBED_BRIDGE,
+			version: AGENT_EMBED_BRIDGE_VERSION,
+			instanceId: this.instanceId,
+			...payload
+		}, this.targetOrigin);
+	}
+	clearMountSettlement() {
+		this.settleMount = void 0;
+		this.rejectMount = void 0;
+	}
+	resolveReadyWaiters() {
+		for (const waiter of this.readyWaiters) waiter.resolve(this.instance);
+		this.readyWaiters.clear();
+	}
+	rejectReadyWaiters(error) {
+		for (const waiter of this.readyWaiters) waiter.reject(error);
+		this.readyWaiters.clear();
+	}
+	failInitialization(failure) {
+		if (this.destroyed || this.ready || this.initError) return;
+		const error = Object.assign(new Error(failure.message), failure);
+		this.initError = error;
+		this.rejectMount?.(error);
+		this.rejectReadyWaiters(error);
+		this.clearMountSettlement();
+		try {
+			this.onInitError?.(failure);
+		} catch {}
+	}
+};
+const createAgentEmbed = (options) => new AgentEmbedClientImpl(options);
+//#endregion
+export { AgentEmbedThemePreset, DEFAULT_AGENT_EMBED_BASE_URL, createAgentEmbed };

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@sophonsai/agent-embed-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Framework-independent browser SDK for integrating Sophon Agent Embed.",
+  "type": "module",
+  "keywords": [
+    "sophonsai",
+    "agent",
+    "agent-embed",
+    "sdk"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "types": "./dist/index.d.mts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@sophonsai/agent-embed-core": "0.1.0"
+  },
+  "devDependencies": {
+    "jsdom": "^27.4.0",
+    "tsdown": "^0.22.14"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --format esm --dts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --config vitest.config.ts"
+  }
 }