@hgt-weprotalk/mira-client 0.1.8

package/README.dev.md

@@ -0,0 +1,194 @@
+# mira-client（内部开发说明）
+
+> **仓库维护者请看本文档。** npm 包页面与 GitHub 首页默认展示 [`README.md`](./README.md)（对外接入说明）。
+
+Mira 用户侧 **Chat Widget（聊天挂件）** 前端工程。
+
+本仓库用 **React 19 + Vite 8 + TypeScript** 搭建开发基座，用于本地预览与联调；**生产交付物**通过 npm 包 `@hgt-weprotalk/mira-client` 发布，宿主（Next.js 独立站）按场景选择三种接入方式之一。
+
+需求文档见 [docs/mira-v1/](./docs/mira-v1/README.md)。
+
+| 层级 | 说明 |
+|------|------|
+| **npm 交付物** | `@hgt-weprotalk/mira-client` — React 库 + Embed 静态资源（`dist/` 仅发布 npm，不进 GitHub） |
+| **基座（Demo Shell）** | `Layout`、`pages/`、`index.html` / `use-cases*.html` — 仅开发预览，非生产交付 |
+| **服务层** | `src/services/` — Java Agent API、Zendesk、反馈、转人工等适配 |
+
+## 架构概览
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  Demo Shell（本地预览）                                    │
+│    首页：React 组件直接挂载 ChatWidget（= 方式 1 生产接入）   │
+│    用例A / 用例B：模拟独立站 script / iframe 接入             │
+└──────────────────────────────────────────────────────────┘
+
+┌──────────────────────────────────────────────────────────┐
+│  Chat Widget                                              │
+│    ChatWidget → useHandoff / useChat → chatApi             │
+│         ↓                                                  │
+│    agentAdapter  ←→  /client/agentChat/*  (SSE + REST)     │
+│    zendesk/*     ←→  Smooch Web Messenger（转人工）          │
+└──────────────────────────────────────────────────────────┘
+```
+
+**分层原则**：UI / Hook 只依赖 `services/` 门面（如 `chatApi`），切换后端时改 adapter 与导出入口即可，Widget UI 无需改动。
+
+## 宿主接入（三种方式）
+
+安装 npm 包：
+
+```bash
+pnpm add @hgt-weprotalk/mira-client
+```
+
+| # | 方式 | 适用 | 说明 |
+|---|------|------|------|
+| **1** | **React 组件** | Next.js App Router（**推荐**） | `import { ChatWidget } from "@hgt-weprotalk/mira-client"`，与本地 Home 页一致 |
+| **2** | **Script Embed（用例 A）** | launcher 弹窗、非 React 页 | 同步 `dist/embed/` → `public/embed/`，加载 `chat-widget.js` + `mira-chat-host.js` |
+| **3** | **Inline iframe（用例 B）** | 宿主自控布局（抽屉/侧栏） | 自行放置 `<iframe src="/embed/frame.html?...">` + host bridge |
+
+详细文档：[20-npm包发布与三种接入方式](./docs/mira-v1/chat-widget/20-npm包发布与三种接入方式.md) · [19-宿主SDK接口](./docs/mira-v1/chat-widget/19-宿主SDK接口.md)（Embed 模式 SDK）
+
+### 方式 1 — React 组件（Next.js 推荐）
+
+参考 `src/reference/nextjs/MiraChatLauncher.tsx`（Valerion 独立站真实接入）：
+
+```tsx
+"use client";
+
+import { ChatWidget, type Locale } from "@hgt-weprotalk/mira-client";
+import "@hgt-weprotalk/mira-client/style.css";
+
+export function MiraChat({ site = "en" }: { site?: string }) {
+  return (
+    <ChatWidget
+      agentName="after_sales_assistant"
+      site={site}
+      apiBaseUrl={process.env.NEXT_PUBLIC_AGENT_API_BASE ?? "/prod-api"}
+      locale={"en-US" satisfies Locale}
+    />
+  );
+}
+```
+
+### 方式 2 — Script Embed（用例 A：launcher 弹窗）
+
+npm 安装后，将 embed 资源同步至 `public/embed/`（推荐 postinstall，见 [20 文档 §1.2](./docs/mira-v1/chat-widget/20-npm包发布与三种接入方式.md#12-方式-2--script-embed用例-alauncher-弹窗)），然后：
+
+```html
+<script
+  src="/embed/chat-widget.js"
+  data-agent-name="after_sales_assistant"
+  data-site="en"
+  defer
+></script>
+<script src="/embed/mira-chat-host.js" defer></script>
+```
+
+用例 A 采用**分离渲染**：宿主页 `chat-widget.js` 负责右下角 launcher 按钮，iframe 内仅渲染聊天面板（`panelOnly`）。本地演示：[use-cases.html](./use-cases.html)
+
+### 方式 3 — Inline iframe（用例 B）
+
+```html
+<iframe
+  id="mira-chat-inline-frame"
+  src="/embed/frame.html?agentName=after_sales_assistant&site=en&parentOrigin={ORIGIN}&layout=inline"
+  style="width: 100%; height: 100%; min-height: 700px; border: 0"
+  allow="clipboard-write"
+></iframe>
+<script src="/embed/mira-chat-host.js" defer></script>
+```
+
+本地演示：[use-cases-b.html](./use-cases-b.html)
+
+### `window.MiraChat` SDK（方式 2 / 3）
+
+| 方法 | 说明 |
+|------|------|
+| `bindUser({ loginUserId, userNickname? })` | 登录后绑定 visitor 历史（`POST /bindUser`） |
+| `setContext({ loginUserId?, userNickname?, product? })` | 传递用户 / 商品上下文 |
+| `open()` / `close()` | 打开 / 关闭聊天容器 |
+| `on("ready" \| "navigate" \| "error", handler)` | 监听 iframe 事件 |
+
+方式 1 直接使用 `setMiraChatUser` / `bindMiraChatUser` 等 import，无需 `window.MiraChat`。
+
+## 目录结构
+
+```
+mira-client/
+├── README.md                  # npm / GitHub 首页（对外）
+├── README.dev.md              # 本文件（内部）
+├── index.html                 # 首页基座（方式 1 预览）
+├── use-cases.html             # 用例A：launcher 弹窗（方式 2）
+├── use-cases-b.html           # 用例B：inline iframe（方式 3）
+├── vite.config.ts             # 开发基座 + /agent-api 代理
+├── vite.lib.config.ts         # npm 库构建
+├── vite.embed*.config.ts      # embed 脚本构建
+│
+├── src/
+│   ├── index.ts               # ★ npm 包公共入口
+│   ├── components/chat-widget/  # ★ Widget UI 源码
+│   ├── embed/                 # launcher / host-bridge / frame 源码
+│   ├── reference/nextjs/      # Next.js 宿主接入参考
+│   ├── hooks/                 # useChat、useHandoff、useZendesk
+│   ├── services/              # chat、zendesk、feedback、handoff
+│   └── pages/                 # Home、UseCases、UseCasesB（基座）
+│
+├── dist/                      # 构建产物（.gitignore，npm publish 时上传）
+└── docs/mira-v1/              # 需求与接口文档
+```
+
+## 配置与环境变量
+
+**重要**：npm 包与 embed 交付物**不依赖**宿主项目的 `.env`。生产环境由独立站通过 **React props**（方式 1）或 **script `data-*` / iframe URL 参数**（方式 2/3）传入运行时配置；本仓库 `.env` **仅用于本地 Demo Shell 开发联调**。
+
+### 开发 vs 生产
+
+| 配置项 | 本地开发（`.env`） | 生产（宿主传参） |
+|--------|-------------------|------------------|
+| Agent 名称 | `VITE_AGENT_NAME` | `agentName` prop 或 `data-agent-name` / URL `agentName` |
+| 站点 | `VITE_AGENT_SITE` | `site` prop 或 `data-site` / URL `site` |
+| Agent API 前缀 | `VITE_AGENT_API_BASE` | `apiBaseUrl` prop 或 `data-api-base-url` / URL `apiBaseUrl` |
+| 代理到 Java 后端 | `VITE_AGENT_API_TARGET`（仅 Vite dev） | **不适用** — 由宿主自行处理 |
+
+### 本地开发 `.env`（示例）
+
+```env
+VITE_AGENT_NAME=after_sales_assistant
+VITE_AGENT_SITE=en
+VITE_AGENT_API_BASE=/agent-api
+VITE_AGENT_API_TARGET=http://localhost:8080
+```
+
+### 生产：后端请求由宿主负责
+
+Widget 内所有 Agent API 请求发往 **`{apiBaseUrl}/client/agentChat/*`**。**如何连到 Java C 端 API 完全由独立站决定**（同域名反代 / BFF / 绝对路径等）。
+
+## 常用命令
+
+```bash
+npm install                 # 安装依赖
+npm run dev                 # 启动开发服务器
+npm run build               # 类型检查 + 库构建 + embed 构建
+npm run build:lib           # 仅 React 库
+npm run build:embed         # 仅 embed 脚本
+npm run typecheck           # TypeScript 检查
+npm run lint                # oxlint
+npm run test:chat-handoff   # 转人工 Playwright 冒烟
+```
+
+**发版（维护者）：**
+
+```bash
+node scripts/release-version.mjs   # bump → npm publish → tag → push
+```
+
+**用例页本地验证**：先 `npm run build:embed`，再 `npm run dev`，访问 `/use-cases.html` 或 `/use-cases-b.html`。
+
+## 生产部署注意
+
+- 宿主通过 `pnpm add @hgt-weprotalk/mira-client@x.y.z` 安装；`dist/` 在 npm 包内，不在 GitHub 仓库。
+- Next.js 推荐 **方式 1**（React 组件），接入与本地 Home 页一致。
+- 方式 2/3 需 postinstall 将 `node_modules/@hgt-weprotalk/mira-client/dist/embed/` 同步至 `public/embed/`。
+- `agentName`、`site`、`apiBaseUrl` 由宿主在接入时传参，**不要在生产依赖本仓库 `.env`**。

package/README.md

@@ -0,0 +1,112 @@
+# @hgt-weprotalk/mira-client
+
+Mira Chat Widget — embeddable AI chat for React / Next.js sites.
+
+## Install
+
+```bash
+pnpm add @hgt-weprotalk/mira-client
+# or
+npm install @hgt-weprotalk/mira-client
+```
+
+**Peer dependencies:** `react` ^18 || ^19, `react-dom` ^18 || ^19
+
+## Integration options
+
+| Mode | Use case |
+|------|----------|
+| **React component** (recommended) | Next.js App Router — import `ChatWidget` directly |
+| **Script embed** | Floating launcher + iframe panel |
+| **Inline iframe** | Host-controlled layout (drawer, sidebar, etc.) |
+
+### React component (Next.js)
+
+```tsx
+"use client";
+
+import { ChatWidget, type Locale } from "@hgt-weprotalk/mira-client";
+import "@hgt-weprotalk/mira-client/style.css";
+
+export function MiraChat({ site = "en" }: { site?: string }) {
+  return (
+    <ChatWidget
+      agentName="your_agent_name"
+      site={site}
+      apiBaseUrl="/prod-api"
+      locale={"en-US" satisfies Locale}
+    />
+  );
+}
+```
+
+For logged-in users, use the exported helpers:
+
+```tsx
+import { setMiraChatUser } from "@hgt-weprotalk/mira-client";
+
+await setMiraChatUser({
+  loginUserId: customer.id,
+  name: customer.name,
+  email: customer.email,
+});
+```
+
+Use `dynamic(..., { ssr: false })` if the host page is server-rendered.
+
+### Script embed (launcher)
+
+Copy embed assets from the package to your static directory (e.g. `public/embed/`):
+
+```bash
+cp -r node_modules/@hgt-weprotalk/mira-client/dist/embed public/embed
+```
+
+```html
+<script
+  src="/embed/chat-widget.js"
+  data-agent-name="your_agent_name"
+  data-site="en"
+  defer
+></script>
+<script src="/embed/mira-chat-host.js" defer></script>
+```
+
+Host SDK: `window.MiraChat` (bindUser, setUser, open, close, on).
+
+### Inline iframe
+
+```html
+<iframe
+  src="/embed/frame.html?agentName=your_agent_name&site=en&parentOrigin=https://example.com&layout=inline"
+  style="width: 100%; height: 100%; min-height: 700px; border: 0"
+  allow="clipboard-write"
+></iframe>
+<script src="/embed/mira-chat-host.js" defer></script>
+```
+
+## Exports
+
+| Import | Description |
+|--------|-------------|
+| `@hgt-weprotalk/mira-client` | `ChatWidget`, runtime helpers, types |
+| `@hgt-weprotalk/mira-client/style.css` | Widget styles |
+| `@hgt-weprotalk/mira-client/embed/*` | Static embed files |
+
+## Configuration (runtime)
+
+The widget does **not** read the host app's `.env`. Pass config via props or embed attributes:
+
+| Prop / attribute | Description |
+|------------------|-------------|
+| `agentName` / `data-agent-name` | Agent identifier |
+| `site` / `data-site` | Site code (e.g. `en`, `de`) |
+| `apiBaseUrl` / `data-api-base-url` | Base URL for `{apiBaseUrl}/client/agentChat/*` |
+| `locale` | UI locale (`en-US`, `zh-CN`) |
+
+## Links
+
+- [Repository](https://github.com/HGT-Weprotalk/mira-client)
+- [Issues](https://github.com/HGT-Weprotalk/mira-client/issues)
+
+> Maintainers: see [README.dev.md](./README.dev.md) for internal architecture and release docs.

package/dist/components/chat-widget/AgentAvatar.d.ts

@@ -0,0 +1,9 @@
+interface AgentAvatarProps {
+    avatar?: string;
+    name: string;
+    className?: string;
+}
+/** Agent 头像：支持 URL 图片或首字 fallback */
+declare const AgentAvatar: ({ avatar, name, className }: AgentAvatarProps) => import("react").JSX.Element;
+export default AgentAvatar;
+//# sourceMappingURL=AgentAvatar.d.ts.map

package/dist/components/chat-widget/AgentAvatar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentAvatar.d.ts","sourceRoot":"","sources":["../../../src/components/chat-widget/AgentAvatar.tsx"],"names":[],"mappings":"AAAA,UAAU,gBAAgB;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAQD,qCAAqC;AACrC,QAAA,MAAM,WAAW,GAAI,6BAA6B,gBAAgB,gCAoBjE,CAAC;AAEF,eAAe,WAAW,CAAC"}

package/dist/components/chat-widget/ChatHeader.d.ts

@@ -0,0 +1,25 @@
+import type { HeaderStatusBadge } from "../../hooks/useHandoff";
+interface ChatHeaderProps {
+    /** 当前视图：list 列表页 / chat 对话页 */
+    panelView: "list" | "chat";
+    /** Agent 名称 */
+    agentName: string;
+    /** Agent 头像 URL */
+    agentAvatar?: string;
+    /** 副标题文案（无状态徽标时展示） */
+    subtitle: string;
+    /** 状态徽标（优先于 subtitle） */
+    statusBadge?: HeaderStatusBadge | null;
+    /** 是否展示返回按钮 */
+    showBackButton?: boolean;
+    /** 返回按钮是否带未读红点 */
+    hasBackUnread?: boolean;
+    /** 返回回调 */
+    onBack?: () => void;
+    /** 关闭面板回调 */
+    onClose: () => void;
+}
+/** 面板顶栏：列表页居中 meta；对话页 leading 头像 + 名称 + 关闭 */
+declare const ChatHeader: ({ panelView, agentName, agentAvatar, subtitle, statusBadge, showBackButton, hasBackUnread, onBack, onClose, }: ChatHeaderProps) => import("react").JSX.Element;
+export default ChatHeader;
+//# sourceMappingURL=ChatHeader.d.ts.map

package/dist/components/chat-widget/ChatHeader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChatHeader.d.ts","sourceRoot":"","sources":["../../../src/components/chat-widget/ChatHeader.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAKhE,UAAU,eAAe;IACvB,+BAA+B;IAC/B,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,eAAe;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,mBAAmB;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sBAAsB;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,yBAAyB;IACzB,WAAW,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACvC,eAAe;IACf,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,kBAAkB;IAClB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,WAAW;IACX,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,aAAa;IACb,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,+CAA+C;AAC/C,QAAA,MAAM,UAAU,GAAI,+GAUjB,eAAe,gCAoFjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/components/chat-widget/ChatInput.d.ts

@@ -0,0 +1,23 @@
+import { type ReactNode } from "react";
+interface ChatInputProps {
+    /** 输入框当前值 */
+    value: string;
+    /** 占位文案 */
+    placeholder: string;
+    /** AI 正在响应（切换为停止按钮） */
+    isResponding: boolean;
+    /** 输入框禁用（转人工流程 / 关闭态等） */
+    isDisabled?: boolean;
+    /** 输入值变更回调 */
+    onChange: (value: string) => void;
+    /** 发送回调（Enter 或点击发送按钮） */
+    onSubmit: () => void;
+    /** 停止生成回调 */
+    onStop: () => void;
+    /** 输入框上方插槽（快捷入口等） */
+    topSlot?: ReactNode;
+}
+/** 底部输入区：自适应高度 textarea + 圆形发送 / 停止按钮 */
+declare const ChatInput: ({ value, placeholder, isResponding, isDisabled, onChange, onSubmit, onStop, topSlot, }: ChatInputProps) => import("react").JSX.Element;
+export default ChatInput;
+//# sourceMappingURL=ChatInput.d.ts.map

package/dist/components/chat-widget/ChatInput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChatInput.d.ts","sourceRoot":"","sources":["../../../src/components/chat-widget/ChatInput.tsx"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAIf,UAAU,cAAc;IACtB,aAAa;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,uBAAuB;IACvB,YAAY,EAAE,OAAO,CAAC;IACtB,0BAA0B;IAC1B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,cAAc;IACd,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,0BAA0B;IAC1B,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,aAAa;IACb,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,qBAAqB;IACrB,OAAO,CAAC,EAAE,SAAS,CAAC;CACrB;AAKD,yCAAyC;AACzC,QAAA,MAAM,SAAS,GAAI,wFAShB,cAAc,gCAiFhB,CAAC;AAEF,eAAe,SAAS,CAAC"}

package/dist/components/chat-widget/ChatMessage.d.ts

@@ -0,0 +1,20 @@
+import type { ChatMessage as ChatMessageType } from "../../types/chat";
+import type { DislikeReasonKey } from "../../types/feedback";
+interface ChatMessageProps {
+    /** 单条消息数据 */
+    message: ChatMessageType;
+    /** AI 发送者展示名 */
+    agentDisplayName: string;
+    /** 是否为流式生成中的最后一条 assistant 气泡 */
+    isStreaming?: boolean;
+    /** 点赞该消息 */
+    onLike?: (messageId: string) => Promise<boolean>;
+    /** 点踩第一步：创建反馈 */
+    onDislikeInit?: (messageId: string) => Promise<boolean>;
+    /** 点踩第二步：补充原因（other 可带自定义文本） */
+    onDislikeReason?: (messageId: string, reasonKey: DislikeReasonKey, otherText?: string) => Promise<boolean>;
+}
+/** 单条聊天气泡：bubble-stack（sender + bubble + time） */
+declare const ChatMessage: ({ message, agentDisplayName, isStreaming, onLike, onDislikeInit, onDislikeReason, }: ChatMessageProps) => import("react").JSX.Element;
+export default ChatMessage;
+//# sourceMappingURL=ChatMessage.d.ts.map

package/dist/components/chat-widget/ChatMessage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChatMessage.d.ts","sourceRoot":"","sources":["../../../src/components/chat-widget/ChatMessage.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,IAAI,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAK7D,UAAU,gBAAgB;IACxB,aAAa;IACb,OAAO,EAAE,eAAe,CAAC;IACzB,gBAAgB;IAChB,gBAAgB,EAAE,MAAM,CAAC;IACzB,iCAAiC;IACjC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY;IACZ,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACjD,iBAAiB;IACjB,aAAa,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACxD,gCAAgC;IAChC,eAAe,CAAC,EAAE,CAChB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,gBAAgB,EAC3B,SAAS,CAAC,EAAE,MAAM,KACf,OAAO,CAAC,OAAO,CAAC,CAAC;CACvB;AAED,kDAAkD;AAClD,QAAA,MAAM,WAAW,GAAI,qFAOlB,gBAAgB,gCA+DlB,CAAC;AAEF,eAAe,WAAW,CAAC"}

package/dist/components/chat-widget/ChatMessageList.d.ts

@@ -0,0 +1,59 @@
+import type { ChatMessage as ChatMessageItem } from "../../types/chat";
+import type { DislikeReasonKey } from "../../types/feedback";
+import type { HandoffProfile } from "../../types/handoff";
+interface ChatMessageListProps {
+    /** 当前展示的消息流（不含开场白 UI） */
+    messages: ChatMessageItem[];
+    /** Agent 开场白（固定 UI，不计入历史） */
+    openingStatement: string;
+    /** AI 发送者展示名 */
+    agentDisplayName: string;
+    /** AI 正在响应（流式生成中） */
+    isResponding: boolean;
+    /** 思考动画进行中 */
+    isThinking: boolean;
+    /** 当前思考阶段索引（0/1/2） */
+    thinkingStageIndex: number;
+    /** 是否展示转人工留资表单 */
+    showHandoffForm: boolean;
+    /** 是否展示等待条 */
+    showWaitingBanner: boolean;
+    /** 是否展示转人工失败提示 */
+    showHandoffFailed: boolean;
+    /** 转人工失败错误文案 */
+    handoffError?: string | null;
+    /** 是否展示会话已关闭提示 */
+    showClosedNotice?: boolean;
+    /** 本地缓存的留资信息（表单回填） */
+    storedProfile: HandoffProfile | null;
+    /** 正在创建 Zendesk 会话 */
+    connecting: boolean;
+    /** Zendesk SDK 初始化中 */
+    sdkLoading: boolean;
+    /** Zendesk SDK 已就绪 */
+    sdkReady: boolean;
+    /** 推荐问题列表（固定 UI，不计入历史） */
+    suggestedQuestions: string[];
+    /** 点击推荐问题 */
+    onSelectSuggestedQuestion: (question: string) => void;
+    /** 取消留资表单 / 关闭失败提示 */
+    onDismissHandoffForm: () => void;
+    /** 提交留资表单 */
+    onSubmitHandoffForm: (profile: HandoffProfile) => Promise<boolean | void>;
+    /** 转人工失败重试 */
+    onRetryHandoff?: () => void;
+    /** 点赞某条 AI 消息 */
+    onLikeMessage?: (messageId: string) => Promise<boolean>;
+    /** 点踩第一步：创建反馈 */
+    onDislikeInitMessage?: (messageId: string) => Promise<boolean>;
+    /** 点踩第二步：补充原因 */
+    onDislikeReasonMessage?: (messageId: string, reasonKey: DislikeReasonKey, otherText?: string) => Promise<boolean>;
+    /** 滚动到底部信号（递增计数驱动 effect） */
+    scrollToBottomSignal?: number;
+    /** 图片预览可见性变化回调 */
+    onPhotoPreviewVisibleChange?: (visible: boolean) => void;
+}
+/** 消息列表：顶栏固定开场白 + 推荐问，下方为会话历史与其它 UI */
+declare const ChatMessageList: ({ messages, openingStatement, agentDisplayName, isResponding, isThinking, thinkingStageIndex, showHandoffForm, showWaitingBanner, showHandoffFailed, handoffError, showClosedNotice, storedProfile, connecting, sdkLoading, sdkReady, suggestedQuestions, onSelectSuggestedQuestion, onDismissHandoffForm, onSubmitHandoffForm, onRetryHandoff, onLikeMessage, onDislikeInitMessage, onDislikeReasonMessage, scrollToBottomSignal, onPhotoPreviewVisibleChange, }: ChatMessageListProps) => import("react").JSX.Element;
+export default ChatMessageList;
+//# sourceMappingURL=ChatMessageList.d.ts.map

package/dist/components/chat-widget/ChatMessageList.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChatMessageList.d.ts","sourceRoot":"","sources":["../../../src/components/chat-widget/ChatMessageList.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,IAAI,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAO1D,UAAU,oBAAoB;IAC5B,yBAAyB;IACzB,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,6BAA6B;IAC7B,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB;IAChB,gBAAgB,EAAE,MAAM,CAAC;IACzB,qBAAqB;IACrB,YAAY,EAAE,OAAO,CAAC;IACtB,cAAc;IACd,UAAU,EAAE,OAAO,CAAC;IACpB,sBAAsB;IACtB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,kBAAkB;IAClB,eAAe,EAAE,OAAO,CAAC;IACzB,cAAc;IACd,iBAAiB,EAAE,OAAO,CAAC;IAC3B,kBAAkB;IAClB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,gBAAgB;IAChB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,kBAAkB;IAClB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,sBAAsB;IACtB,aAAa,EAAE,cAAc,GAAG,IAAI,CAAC;IACrC,sBAAsB;IACtB,UAAU,EAAE,OAAO,CAAC;IACpB,uBAAuB;IACvB,UAAU,EAAE,OAAO,CAAC;IACpB,sBAAsB;IACtB,QAAQ,EAAE,OAAO,CAAC;IAClB,0BAA0B;IAC1B,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,aAAa;IACb,yBAAyB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACtD,sBAAsB;IACtB,oBAAoB,EAAE,MAAM,IAAI,CAAC;IACjC,aAAa;IACb,mBAAmB,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IAC1E,cAAc;IACd,cAAc,CAAC,EAAE,MAAM,IAAI,CAAC;IAC5B,iBAAiB;IACjB,aAAa,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACxD,iBAAiB;IACjB,oBAAoB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/D,iBAAiB;IACjB,sBAAsB,CAAC,EAAE,CACvB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,gBAAgB,EAC3B,SAAS,CAAC,EAAE,MAAM,KACf,OAAO,CAAC,OAAO,CAAC,CAAC;IACtB,6BAA6B;IAC7B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,kBAAkB;IAClB,2BAA2B,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;CAC1D;AAcD,uCAAuC;AACvC,QAAA,MAAM,eAAe,GAAI,mcA0BtB,oBAAoB,gCAiLtB,CAAC;AAEF,eAAe,eAAe,CAAC"}

package/dist/components/chat-widget/ChatPanel.d.ts

@@ -0,0 +1,122 @@
+import type { HeaderStatusBadge } from "../../hooks/useHandoff";
+import type { ChatMessage } from "../../types/chat";
+import type { DislikeReasonKey } from "../../types/feedback";
+import type { HandoffProfile } from "../../types/handoff";
+import type { PanelView, SessionListItem } from "../../types/history";
+import type { QuickEntry } from "../../types/quickEntry";
+interface ChatPanelProps {
+    /** 当前视图：list 会话列表 / chat 对话页 */
+    panelView: PanelView;
+    /** 顶栏展示的 Agent 名称（来自配置 name，如 Tammy Campbell2） */
+    agentName: string;
+    /** 消息列表中 AI 发送者展示名（统一为「智能客服」） */
+    messageAgentDisplayName: string;
+    /** Agent 头像 URL（无则用首字母 fallback） */
+    agentAvatar?: string;
+    /** 顶栏副标题文案 */
+    agentSubtitle: string;
+    /** 顶栏状态徽标（online/transferred/closed），优先于 subtitle 展示 */
+    headerStatusBadge?: HeaderStatusBadge | null;
+    /** 历史会话列表 */
+    sessions: SessionListItem[];
+    /** 会话列表加载中 */
+    isLoadingSessions: boolean;
+    /** 当前会话历史消息加载中 */
+    isLoadingHistory: boolean;
+    /** 是否展示返回按钮（对话页可返回列表时为 true） */
+    showBackButton: boolean;
+    /** 返回列表是否需二次确认（仅 TRANSFERRING / TRANSFERRED 会话） */
+    requiresLeaveHandoffConfirm: boolean;
+    /** 当前展示的消息流（AI + Zendesk 合并） */
+    messages: ChatMessage[];
+    /** 输入框当前值 */
+    inputValue: string;
+    /** 初始化中（拉取 Agent 配置 / 会话列表） */
+    isInitializing: boolean;
+    /** AI 正在响应（流式生成中） */
+    isResponding: boolean;
+    /** 思考动画进行中 */
+    isThinking: boolean;
+    /** 当前思考阶段索引（0/1/2） */
+    thinkingStageIndex: number;
+    /** 输入框是否禁用（转人工流程 / 关闭态 / 初始化中等） */
+    isInputDisabled: boolean;
+    /** 输入框占位文案（随通道 / 状态切换） */
+    inputPlaceholder: string;
+    /** 错误横幅文案（无则不展示） */
+    error: string | null;
+    /** 是否展示转人工留资表单 */
+    showHandoffForm: boolean;
+    /** 是否展示「正在接入人工客服」等待条 */
+    showWaitingBanner: boolean;
+    /** 是否展示转人工失败提示（含重试按钮） */
+    showHandoffFailed: boolean;
+    /** 转人工失败时的错误文案 */
+    handoffError?: string | null;
+    /** 是否展示会话已关闭只读提示 */
+    showClosedNotice?: boolean;
+    /** 返回按钮是否带未读红点 */
+    hasBackUnread?: boolean;
+    /** Zendesk 各 conversationId 的未读标记（列表角标用） */
+    zendeskUnreadByConversationId?: Record<string, boolean>;
+    /** 本地缓存的留资信息（表单回填用） */
+    storedProfile: HandoffProfile | null;
+    /** 正在创建 Zendesk 会话（转人工提交中） */
+    connecting: boolean;
+    /** Zendesk SDK 初始化中 */
+    sdkLoading: boolean;
+    /** Zendesk SDK 已就绪 */
+    sdkReady: boolean;
+    /** 推荐问题列表（固定 UI，不计入历史） */
+    suggestedQuestions: string[];
+    /** Agent 开场白（固定 UI，不计入历史） */
+    openingStatement: string;
+    /** 快捷入口列表（输入区上方，按 rounds 展示） */
+    quickEntries: QuickEntry[];
+    /** 是否展示快捷入口（AI 对话且未关闭） */
+    showQuickEntries: boolean;
+    /** 输入框值变更回调 */
+    onInputChange: (value: string) => void;
+    /** 发送消息回调 */
+    onSend: () => void;
+    /** 停止生成回调 */
+    onStop: () => void;
+    /** 关闭面板回调 */
+    onClose: () => void;
+    /** 新建对话 / 重置回调 */
+    onReset: () => void;
+    /** 返回列表回调 */
+    onBack: () => void;
+    /** 选中某个历史会话 */
+    onSelectSession: (session: SessionListItem) => void;
+    /** 删除某个会话 */
+    onDeleteSession: (sessionId: number) => void;
+    /** 点击推荐问题 */
+    onSelectSuggestedQuestion: (question: string) => void;
+    /** 取消留资表单 / 关闭失败提示 */
+    onDismissHandoffForm: () => void;
+    /** 提交留资表单 */
+    onSubmitHandoffForm: (profile: HandoffProfile) => Promise<boolean | void>;
+    /** 转人工失败后重试 */
+    onRetryHandoff?: () => void;
+    /** 点赞某条 AI 消息 */
+    onLikeMessage?: (messageId: string) => Promise<boolean>;
+    /** 点踩第一步：创建反馈并返回 feedbackId */
+    onDislikeInitMessage?: (messageId: string) => Promise<boolean>;
+    /** 点踩第二步：补充原因（other 可带自定义文本） */
+    onDislikeReasonMessage?: (messageId: string, reasonKey: DislikeReasonKey, otherText?: string) => Promise<boolean>;
+    /** iframe 模式下鼠标离开对话框区域回调 */
+    onDialogPointerLeave?: () => void;
+    /** 滚动到底部信号（递增计数驱动 effect） */
+    scrollToBottomSignal?: number;
+    /** 面板进入动画信号（递增计数，embed 模式由 panel-open 触发） */
+    panelEnterAnimationSignal?: number;
+    /** 面板是否正在播放关闭动画 */
+    isClosing?: boolean;
+    /** 图片预览可见性变化回调（iframe 模式通知宿主页） */
+    onPhotoPreviewVisibleChange?: (visible: boolean) => void;
+}
+/** 客服面板：会话列表 / 对话页 + 输入区 */
+declare const ChatPanel: ({ panelView, agentName, messageAgentDisplayName, agentAvatar, agentSubtitle, headerStatusBadge, sessions, isLoadingSessions, isLoadingHistory, showBackButton, requiresLeaveHandoffConfirm, messages, inputValue, isInitializing, isResponding, isThinking, thinkingStageIndex, isInputDisabled, inputPlaceholder, error, showHandoffForm, showWaitingBanner, showHandoffFailed, handoffError, showClosedNotice, hasBackUnread, zendeskUnreadByConversationId, storedProfile, connecting, sdkLoading, sdkReady, suggestedQuestions, openingStatement, quickEntries, showQuickEntries, onInputChange, onSend, onStop, onClose, onReset, onBack, onSelectSession, onDeleteSession, onSelectSuggestedQuestion, onDismissHandoffForm, onSubmitHandoffForm, onRetryHandoff, onLikeMessage, onDislikeInitMessage, onDislikeReasonMessage, onDialogPointerLeave, scrollToBottomSignal, panelEnterAnimationSignal, isClosing, onPhotoPreviewVisibleChange, }: ChatPanelProps) => import("react").JSX.Element;
+export default ChatPanel;
+//# sourceMappingURL=ChatPanel.d.ts.map

package/dist/components/chat-widget/ChatPanel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChatPanel.d.ts","sourceRoot":"","sources":["../../../src/components/chat-widget/ChatPanel.tsx"],"names":[],"mappings":"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"}

package/dist/components/chat-widget/ChatToast.d.ts

@@ -0,0 +1,10 @@
+interface ChatToastProps {
+    /** 提示文案 */
+    message: string;
+    /** 是否展示 */
+    visible: boolean;
+}
+/** 气泡式短提示（如「已复制」） */
+declare const ChatToast: ({ message, visible }: ChatToastProps) => import("react").JSX.Element | null;
+export default ChatToast;
+//# sourceMappingURL=ChatToast.d.ts.map

package/dist/components/chat-widget/ChatToast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChatToast.d.ts","sourceRoot":"","sources":["../../../src/components/chat-widget/ChatToast.tsx"],"names":[],"mappings":"AAAA,UAAU,cAAc;IACtB,WAAW;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW;IACX,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,qBAAqB;AACrB,QAAA,MAAM,SAAS,GAAI,sBAAsB,cAAc,uCAUtD,CAAC;AAEF,eAAe,SAAS,CAAC"}

package/dist/components/chat-widget/ChatToastContext.d.ts

@@ -0,0 +1,15 @@
+import { type ReactNode } from "react";
+interface ChatToastContextValue {
+    showToast: (message: string) => void;
+    toastMessage: string | null;
+}
+interface ChatToastProviderProps {
+    children: ReactNode;
+}
+/** 面板级 Toast 状态（供消息复制等场景触发） */
+export declare const ChatToastProvider: ({ children }: ChatToastProviderProps) => import("react").JSX.Element;
+/** 挂载在 ChatHeader 下方，水平居中展示 Toast */
+export declare const ChatToastHost: () => import("react").JSX.Element | null;
+export declare const useChatToast: () => ChatToastContextValue;
+export {};
+//# sourceMappingURL=ChatToastContext.d.ts.map

package/dist/components/chat-widget/ChatToastContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChatToastContext.d.ts","sourceRoot":"","sources":["../../../src/components/chat-widget/ChatToastContext.tsx"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAKf,UAAU,qBAAqB;IAC7B,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAID,UAAU,sBAAsB;IAC9B,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,+BAA+B;AAC/B,eAAO,MAAM,iBAAiB,GAAI,cAAc,sBAAsB,gCA8BrE,CAAC;AAEF,qCAAqC;AACrC,eAAO,MAAM,aAAa,0CAYzB,CAAC;AAEF,eAAO,MAAM,YAAY,QAAO,qBAQ/B,CAAC"}