# TaskArtifactHtml

HTML 产物渲染与编辑组件，支持 **文档模式（document）** 和 **网页模式（web）** 两种渲染方式。内容通过 iframe 沙箱加载，编辑态下提供所见即所得的工具栏。

---

## 快速开始

```tsx
import { TaskArtifactHtml } from "@/components/nova-sdk/html-editor";

<TaskArtifactHtml
  taskId="task-123"
  editable={true}
  type="web"
  taskArtifact={{
    path: "/artifacts/page.html",
    file_name: "page.html",
    file_type: "text/html",
  }}
  onStateChange={(state) => {
    // state.canUndo / state.canRedo / state.undo() / state.redo()
    console.log(state);
  }}
/>;
```

> **前置依赖**：组件内部通过 `useNovaKit()` 获取 API 实例来加载远程内容，因此使用前需确保外层已包裹 `<NovaKitProvider>`。

---

## Props

| 属性            | 类型                                 | 必填 | 说明                                                              |
| --------------- | ------------------------------------ | ---- | ----------------------------------------------------------------- |
| `taskId`        | `string`                             | ✅   | 任务 ID，用于关联产物与任务，编辑时也用于保存接口                 |
| `editable`      | `boolean`                            | ❌   | 是否开启编辑模式。`false` 为只读预览，`true` 显示编辑工具栏       |
| `type`          | `'document' \| 'web'`                | ✅   | 渲染模式。`document` 适合富文本文档编辑，`web` 适合网页类产物编辑 |
| `taskArtifact`  | `TaskArtifact`                       | ✅   | 产物数据对象，包含文件路径等信息                                  |
| `onStateChange` | `(state: ArtifactEditState) => void` | ❌   | 编辑状态变化回调，每次 undo/redo 历史变化时触发                   |

### TaskArtifact 类型定义

```ts
interface TaskArtifact {
  path: string; // 产物文件路径
  file_name: string; // 文件名
  file_type: string; // 文件 MIME 类型
  last_modified?: number; // 最后修改时间戳
  url?: string; // 可选的直接访问 URL
  content?: string; // 可选的内联内容
  task_id?: string; // 关联的任务 ID
  event_type?: string; // 工具调用事件类型
  tool_name?: string; // 工具名称
  tool_input?: unknown; // 工具输入
  tool_output?: unknown; // 工具输出
}
```

### ArtifactEditState 类型定义

当传入 `onStateChange` 后，编辑器内部的历史记录发生变化时会通过该回调通知父组件。父组件可据此实现外部的撤销/重做按钮。

```ts
interface ArtifactEditState {
  canUndo: boolean; // 是否可以撤销
  canRedo: boolean; // 是否可以重做
  undo: () => void; // 执行撤销
  redo: () => void; // 执行重做
}
```

---

## 两种模式对比

| 特性     | `document` 模式                            | `web` 模式                                             |
| -------- | ------------------------------------------ | ------------------------------------------------------ |
| 适用场景 | 富文本文档（文章、报告等）                 | 网页类产物（落地页、网站等）                           |
| 编辑方式 | 全局 `contentEditable`，支持文本选区工具栏 | 元素级选取与属性编辑                                   |
| 工具栏   | `toolbar-doc` — 基于文本选区定位           | `toolbar-web` — 基于选中元素定位，更丰富的样式编辑能力 |
| 内部组件 | `TaskHtmlDoc`                              | `TaskHtmlWeb`                                          |

---

## 使用示例

### 只读预览

```tsx
// 简单预览，不显示任何编辑工具栏
<TaskArtifactHtml
  taskId={task.id}
  editable={false}
  type="document"
  taskArtifact={artifact}
/>
```

### 文档编辑模式

```tsx
// 开启编辑，用户可以直接在文档中选中文本进行格式编辑
<TaskArtifactHtml
  taskId={task.id}
  editable={true}
  type="document"
  taskArtifact={artifact}
/>
```

### 网页编辑模式

```tsx
// 开启编辑，用户可以点选网页中的元素进行样式调整
<TaskArtifactHtml
  taskId={task.id}
  editable={true}
  type="web"
  taskArtifact={artifact}
/>
```

### 配合外部撤销/重做按钮

```tsx
const [editState, setEditState] = useState<ArtifactEditState | null>(null);

<>
  <div className="toolbar">
    <button disabled={!editState?.canUndo} onClick={() => editState?.undo()}>
      撤销
    </button>
    <button disabled={!editState?.canRedo} onClick={() => editState?.redo()}>
      重做
    </button>
  </div>

  <TaskArtifactHtml
    taskId={task.id}
    editable={true}
    type="web"
    taskArtifact={artifact}
    onStateChange={setEditState}
  />
</>;
```

---

## 内部架构

```
TaskArtifactHtml (入口)
├── type="document" → TaskHtmlDoc
│   ├── editable=false → Html (只读 iframe)
│   └── editable=true
│       └── PPTEditProvider (编辑状态上下文)
│           ├── PPTEditToolBar (toolbar-doc, 文本选区工具栏)
│           └── HtmlWithEditMode (基础编辑层)
│               ├── useIframeMode  → HTMLEditor 实例
│               ├── useDiff        → 同步编辑状态到 Context
│               └── Html (iframe 渲染)
│
└── type="web" → TaskHtmlWeb
    ├── editable=false → Html (只读 iframe)
    └── editable=true
        └── PPTEditProvider
            ├── PPTEditToolBar (toolbar-web, 元素工具栏)
            └── HtmlWithEditMode (isDoc=false)
```

### 核心模块说明

#### `Html`（`components/html-render/task-html.tsx`）

底层 iframe 渲染组件，接受 HTML 字符串作为 `srcDoc` 注入 iframe。配置了 `sandbox="allow-same-origin allow-scripts allow-popups allow-popups-to-escape-sandbox"`，并自动拦截 iframe 内的 `_blank` 链接和 `window.open` 调用，转发至父窗口打开。

#### `HtmlWithEditMode`（`mode/baseEdit.tsx`）

编辑模式的基础封装层，负责：

- 调用 `useIframeMode` 初始化 `HTMLEditor` 编辑器实例
- 调用 `useDiff` 将编辑器状态同步到 `PPTEditContext`
- 监听历史记录变化，通过 `onStateChange` 向上传递 `ArtifactEditState`（canUndo/canRedo/undo/redo）
- 内容变更时自动防抖保存（1 秒），通过 `saveMarkdown` 接口持久化到服务端

#### `PPTEditProvider`（`context/index.tsx`）

编辑状态上下文 Provider，维护：

- `state` — 当前 `useIframeMode` 的返回值（编辑器实例、选中元素、位置等）
- `setState` — 由 `useDiff` hook 调用，将编辑状态同步至上下文
- `originalSlide` — 原始幻灯片数据的引用（PPT 场景）

工具栏组件通过 `usePPTEditContext()` 消费该上下文，获取编辑器实例和选中元素信息来渲染对应的编辑工具。

---

## Hooks

### `useLoadContent(taskArtifact: TaskArtifact): string`

通过 `useNovaKit()` 提供的 API 加载产物的远程 HTML 内容。先调用 `api.getArtifactUrl()` 获取签名 URL，再 `fetch` 获取文本内容。

### `useIframeMode(id, containerRef, options?, scale?): UseInjectModeReturn`

核心编辑 hook，负责：

- 创建 `HTMLEditor` 实例并注入到 iframe 或普通 DOM 容器
- 管理元素选中状态和位置计算
- 管理 undo/redo 历史记录
- 绑定 `Cmd+Z` / `Cmd+Shift+Z` 快捷键

返回值：

```ts
interface UseInjectModeReturn {
  editor: HTMLEditor | null; // 编辑器实例（ref 值）
  editorIns: HTMLEditor | null; // 编辑器实例（state 值，触发重渲染）
  selectedElement: HTMLElement | null; // 当前选中的 DOM 元素
  position: Position | null; // 选中元素在 iframe 内的位置
  tipPosition: Position | null; // 经过缩放换算后用于定位工具栏的位置
  injectScript: (target: HTMLElement) => Promise<void>; // 手动注入编辑器
  canUndo: boolean;
  canRedo: boolean;
  clearHistory: () => void;
  loadSuccess: boolean; // iframe 内容是否加载/注入成功
}
```

### `useDiff(useIframeReturn, isDoc?)`

区分 document / web 两种模式的差异逻辑，将 `useIframeMode` 的状态同步到 `PPTEditContext`：

- **document 模式**：使用 `useToolPosition` 基于文本选区末尾计算工具栏位置
- **web 模式**：基于选中元素的 `getBoundingClientRect` 定位工具栏；失焦后清除状态

### `useToolPosition(editor, isDoc): Position | null`

仅在 document 模式下生效。监听编辑器内的 `mousedown` / `mouseup` / `scroll` / `resize` 事件，根据当前文本选区（`Selection`）末尾位置计算工具栏坐标。

---

## 服务端接口

### `saveMarkdown`（`server/index.ts`）

编辑模式下内容变更会自动防抖（1 秒）调用此函数保存到服务端：

```ts
POST / v1 / super_agent / chat / write_file;
Body: {
  task_id: string;
  path: string;
  content: string;
}
```

---

## 目录结构

```
html-editor/
├── index.tsx              # 入口组件 TaskArtifactHtml
├── README.md              # 本文档
├── types/
│   └── index.ts           # ArtifactEditState 等类型定义
├── server/
│   └── index.ts           # saveMarkdown 保存接口
├── mode/
│   ├── baseEdit.tsx       # 编辑模式基础层 HtmlWithEditMode
│   ├── html-doc.tsx       # 文档模式 TaskHtmlDoc
│   └── html-web.tsx       # 网页模式 TaskHtmlWeb
├── context/
│   └── index.tsx          # PPTEditProvider / usePPTEditContext
├── hooks/
│   ├── useDiff.ts         # doc/web 差异逻辑
│   ├── useIframeMode.ts   # 核心编辑器 hook
│   ├── useLoadContent.ts  # 远程内容加载
│   └── useToolPostion.ts  # 文本选区工具栏定位
├── components/
│   ├── html-render/       # iframe 渲染组件
│   ├── toolbar-doc/       # 文档模式工具栏
│   └── toolbar-web/       # 网页模式工具栏
├── lib/                   # HTMLEditor 核心库
│   ├── core/              # 编辑器引擎、历史记录管理器
│   ├── types/             # 内部类型定义
│   └── config/            # 编辑器配置
└── assets/                # 图标等静态资源
```
