@h-ai/ui 0.1.0-alpha.67 → 0.1.0-alpha.68

package/dist/components/primitives/ToggleRadio.svelte

@@ -1,4 +1,5 @@
 <!--
+  @component ToggleRadio
   =============================================================================
   @h-ai/ui - ToggleRadio 组件
   =============================================================================
@@ -6,6 +7,16 @@
 
   使用 Svelte 5 Runes ($props, $bindable)
   =============================================================================
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { ToggleRadio } from '@h-ai/ui'
+  const props: ComponentProps<typeof ToggleRadio> = { name: 'section', checked: true }
+  const component = mount(ToggleRadio, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { DataAttributes, ToggleRadioProps } from '../../types.js'

package/dist/components/primitives/ToggleRadio.svelte.d.ts

@@ -1,5 +1,25 @@
 import type { DataAttributes, ToggleRadioProps } from '../../types.js';
 type $$ComponentProps = ToggleRadioProps & DataAttributes;
+/**
+ * ToggleRadio
+ * =============================================================================
+ * @h-ai/ui - ToggleRadio 组件
+ * =============================================================================
+ * 仅渲染 radio input（用于 collapse/accordion 等结构要求）
+ *
+ * 使用 Svelte 5 Runes ($props, $bindable)
+ * =============================================================================
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { ToggleRadio } from '@h-ai/ui'
+ * const props: ComponentProps<typeof ToggleRadio> = { name: 'section', checked: true }
+ * const component = mount(ToggleRadio, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 declare const ToggleRadio: import("svelte").Component<$$ComponentProps, {}, "checked">;
 type ToggleRadio = ReturnType<typeof ToggleRadio>;
 export default ToggleRadio;

package/dist/components/scenes/ai/AiDocumentDownloadMenu.svelte

@@ -1,3 +1,17 @@
+<!--
+  @component AiDocumentDownloadMenu
+  AiDocumentDownloadMenu 组件的公开使用示例。
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { AiDocumentDownloadMenu } from '@h-ai/ui'
+  const props: ComponentProps<typeof AiDocumentDownloadMenu> = { content: '# 报告', title: '报告', actions: [{ id: 'markdown', label: 'Markdown' }] }
+  const component = mount(AiDocumentDownloadMenu, { target: document.body, props })
+  await unmount(component)
+  ```
+-->
 <script lang='ts'>
   import type { DataAttributes } from '../../../types.js'
   import type {
@@ -11,6 +25,19 @@
     resolveDocumentDownloadActions,
   } from './document-download.js'
 
+  /**
+   * AiDocumentDownloadMenu 组件的属性契约；通过公开组件配置使用。
+   *
+   * @example
+   * ```ts
+   * import { mount, unmount } from 'svelte'
+   * import type { ComponentProps } from 'svelte'
+   * import { AiDocumentDownloadMenu } from '@h-ai/ui'
+   * const props: ComponentProps<typeof AiDocumentDownloadMenu> = { content: '# 报告', title: '报告', actions: [{ id: 'markdown', label: 'Markdown' }] }
+   * const component = mount(AiDocumentDownloadMenu, { target: document.body, props })
+   * await unmount(component)
+   * ```
+   */
   interface AiDocumentDownloadMenuProps {
     /** 触发下载时导出的原始内容。 */
     content?: string

package/dist/components/scenes/ai/AiDocumentDownloadMenu.svelte.d.ts

@@ -1,5 +1,18 @@
 import type { DataAttributes } from '../../../types.js';
 import type { MarkdownSourceKind, MarkdownToolbarDownloadAction } from './document-types.js';
+/**
+ * AiDocumentDownloadMenu 组件的属性契约；通过公开组件配置使用。
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { AiDocumentDownloadMenu } from '@h-ai/ui'
+ * const props: ComponentProps<typeof AiDocumentDownloadMenu> = { content: '# 报告', title: '报告', actions: [{ id: 'markdown', label: 'Markdown' }] }
+ * const component = mount(AiDocumentDownloadMenu, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 interface AiDocumentDownloadMenuProps {
     /** 触发下载时导出的原始内容。 */
     content?: string;
@@ -35,6 +48,20 @@ interface AiDocumentDownloadMenuProps {
     itemClass?: string;
 }
 type $$ComponentProps = AiDocumentDownloadMenuProps & DataAttributes;
+/**
+ * AiDocumentDownloadMenu
+ * AiDocumentDownloadMenu 组件的公开使用示例。
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { AiDocumentDownloadMenu } from '@h-ai/ui'
+ * const props: ComponentProps<typeof AiDocumentDownloadMenu> = { content: '# 报告', title: '报告', actions: [{ id: 'markdown', label: 'Markdown' }] }
+ * const component = mount(AiDocumentDownloadMenu, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 declare const AiDocumentDownloadMenu: import("svelte").Component<$$ComponentProps, {}, "">;
 type AiDocumentDownloadMenu = ReturnType<typeof AiDocumentDownloadMenu>;
 export default AiDocumentDownloadMenu;

package/dist/components/scenes/ai/AiDocumentEditor.svelte

@@ -1,4 +1,5 @@
 <!--
+  @component AiDocumentEditor
   =============================================================================
   @h-ai/ui - AiDocumentEditor 组件
   =============================================================================
@@ -9,6 +10,16 @@
   适用于 AI 输出显示、文档预览、代码说明面板等场景。
   使用 Svelte 5 Runes ($props, $state, $derived, $effect)
   =============================================================================
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { AiDocumentEditor } from '@h-ai/ui'
+  const props: ComponentProps<typeof AiDocumentEditor> = { content: '# 报告\n正文', title: '报告', sourceKind: 'document', allowHtmlTags: false, allowUnsafeCodePreview: false }
+  const component = mount(AiDocumentEditor, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { DataAttributes } from '../../../types.js'
@@ -45,6 +56,14 @@
   } from './mermaid-host-sync.js'
   import { renderMermaidDiagram, stripMermaidSvgStyleElements } from './mermaid-render.js'
 
+  /**
+   * 选区工具条在编辑器视口中的坐标和对齐方向。
+   *
+   * @example 模块内部上下文
+   * ```ts
+   * const example: SelectionToolbarPosition = { top: 24, left: 120, placement: 'bottom', alignment: 'left' }
+   * ```
+   */
   interface SelectionToolbarPosition {
     /** 选区工具条相对滚动容器的 top 坐标。 */
     top: number
@@ -56,6 +75,14 @@
     alignment: 'left' | 'center' | 'right'
   }
 
+  /**
+   * 单个代码块的运行进度及结果；错误状态只保留可展示消息。
+   *
+   * @example 模块内部上下文
+   * ```ts
+   * const example: CodePreviewState = { status: 'ready', result: { kind: 'text', content: '2' } }
+   * ```
+   */
   interface CodePreviewState {
     /** 当前代码块预览所处的生命周期阶段。 */
     status: 'running' | 'ready' | 'error'
@@ -65,6 +92,14 @@
     error?: string
   }
 
+  /**
+   * 按块源码签名缓存 Mermaid 渲染状态，避免流式更新重复渲染。
+   *
+   * @example 模块内部上下文
+   * ```ts
+   * const example: MermaidRenderCacheEntry = { signature: JSON.stringify(['diagram-1', 'graph TD; A-->B']), status: 'ready', html: '<svg xmlns="http://www.w3.org/2000/svg"></svg>' }
+   * ```
+   */
   interface MermaidRenderCacheEntry {
     /** 当前 Mermaid 源码签名。 */
     signature: string
@@ -76,6 +111,14 @@
     error?: string
   }
 
+  /**
+   * 当前选区的块级与行内格式快照；不持久化 DOM 节点。
+   *
+   * @example 模块内部上下文
+   * ```ts
+   * const example: SelectionFormatState = { blockFormat: 'paragraph', alignment: 'left', bold: false, strike: false, italic: false, underline: false, highlight: false, code: false, linkHref: '', textColor: null, backgroundColor: null }
+   * ```
+   */
   interface SelectionFormatState {
     /** 当前选区所在段落样式，用于标题/正文下拉默认值。 */
     blockFormat: MarkdownBlockStyleKind
@@ -101,6 +144,18 @@
     backgroundColor: string | null
   }
 
+  /**
+   * 预览 DOM 中选区与范围的临时快照，编辑结束后重新读取。
+   *
+   * @example 模块内部上下文
+   * ```ts
+   * const selection = window.getSelection()
+   * if (selection && selection.rangeCount > 0) {
+   *   const snapshot: PreviewSelectionState = { selection, range: selection.getRangeAt(0).cloneRange(), text: selection.toString() }
+   *   const selectedText = snapshot.text
+   * }
+   * ```
+   */
   interface PreviewSelectionState {
     /** 浏览器当前仍然有效的正文选区。 */
     selection: Selection
@@ -110,6 +165,14 @@
     text: string
   }
 
+  /**
+   * 背景色面板中的清除颜色选项。
+   *
+   * @example 模块内部上下文
+   * ```ts
+   * const example: ColorSwatchOption = { value: null, titleKey: 'markdown_background_none' }
+   * ```
+   */
   interface ColorSwatchOption {
     /** 颜色值；为空表示恢复默认或清除当前维度。 */
     value: string | null
@@ -117,6 +180,14 @@
     titleKey: 'markdown_background_none'
   }
 
+  /**
+   * 悬停链接的受控地址及提示层位置；原始地址不能绕过链接消毒。
+   *
+   * @example 模块内部上下文
+   * ```ts
+   * const example: HoveredLinkState = { element: document.createElement('a'), href: 'https://example.com', rawHref: 'https://example.com', top: 24, left: 120, placement: 'bottom' }
+   * ```
+   */
   interface HoveredLinkState {
     /** 当前悬停的链接元素。 */
     element: HTMLAnchorElement
@@ -132,6 +203,14 @@
     placement: 'top' | 'bottom'
   }
 
+  /**
+   * 选区菜单的互斥操作域。
+   *
+   * @example 模块内部上下文
+   * ```ts
+   * const example: SelectionMenuKind = 'rewrite'
+   * ```
+   */
   type SelectionMenuKind = 'rewrite' | 'block' | 'align' | 'link' | 'color'
 
   const BLOCK_FORMAT_OPTIONS: Array<{

package/dist/components/scenes/ai/AiDocumentEditor.svelte.d.ts

@@ -1,6 +1,29 @@
 import type { DataAttributes } from '../../../types.js';
 import type { AiDocumentEditorProps } from './document-types.js';
 type $$ComponentProps = AiDocumentEditorProps & DataAttributes;
+/**
+ * AiDocumentEditor
+ * =============================================================================
+ * @h-ai/ui - AiDocumentEditor 组件
+ * =============================================================================
+ * 通用 Markdown 渲染器，支持两种模式：
+ * - document：带目录、工具栏、代码运行预览的文档面板
+ * - code: 仅渲染代码块，适用于 AI 代码产物的展示和交互。
+ *
+ * 适用于 AI 输出显示、文档预览、代码说明面板等场景。
+ * 使用 Svelte 5 Runes ($props, $state, $derived, $effect)
+ * =============================================================================
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { AiDocumentEditor } from '@h-ai/ui'
+ * const props: ComponentProps<typeof AiDocumentEditor> = { content: '# 报告\n正文', title: '报告', sourceKind: 'document', allowHtmlTags: false, allowUnsafeCodePreview: false }
+ * const component = mount(AiDocumentEditor, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 declare const AiDocumentEditor: import("svelte").Component<$$ComponentProps, {}, "editorScrollHost" | "previewHost">;
 type AiDocumentEditor = ReturnType<typeof AiDocumentEditor>;
 export default AiDocumentEditor;

package/dist/components/scenes/ai/MarkdownRenderer.svelte

@@ -1,4 +1,5 @@
 <!--
+  @component MarkdownRenderer
   =============================================================================
   @h-ai/ui - MarkdownRenderer 组件
   =============================================================================
@@ -14,6 +15,16 @@
 
   使用 Svelte 5 Runes ($props, $derived, $effect)
   =============================================================================
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { MarkdownRenderer } from '@h-ai/ui'
+  const props: ComponentProps<typeof MarkdownRenderer> = { content: '# 标题\n正文', allowHtmlTags: false }
+  const component = mount(MarkdownRenderer, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { DataAttributes } from '../../../types.js'

package/dist/components/scenes/ai/MarkdownRenderer.svelte.d.ts

@@ -1,6 +1,34 @@
 import type { DataAttributes } from '../../../types.js';
 import type { MarkdownRendererProps } from '../types.js';
 type $$ComponentProps = MarkdownRendererProps & DataAttributes;
+/**
+ * MarkdownRenderer
+ * =============================================================================
+ * @h-ai/ui - MarkdownRenderer 组件
+ * =============================================================================
+ * 通用 Markdown 渲染器，适用于 AI 输出显示、文档预览等场景。
+ *
+ * 功能特性：
+ * - GFM (GitHub Flavored Markdown) 全量支持
+ * - 代码块语法高亮（Shiki，30+ 语言）
+ * - 代码块一键复制
+ * - 响应式表格
+ * - 任务列表
+ * - DaisyUI 主题自适应
+ *
+ * 使用 Svelte 5 Runes ($props, $derived, $effect)
+ * =============================================================================
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { MarkdownRenderer } from '@h-ai/ui'
+ * const props: ComponentProps<typeof MarkdownRenderer> = { content: '# 标题\n正文', allowHtmlTags: false }
+ * const component = mount(MarkdownRenderer, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 declare const MarkdownRenderer: import("svelte").Component<$$ComponentProps, {}, "">;
 type MarkdownRenderer = ReturnType<typeof MarkdownRenderer>;
 export default MarkdownRenderer;

package/dist/components/scenes/ai/code-preview.d.ts

@@ -1,4 +1,12 @@
 import type { MarkdownCodeRunRequest, MarkdownCodeRunResult } from './document-types.js';
+/**
+ * 内置代码预览的安全策略和标题，默认不执行任意代码。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const example: BuiltInCodePreviewOptions = { previewTitle: '预览', allowUnsafeCodePreview: false }
+ * ```
+ */
 export interface BuiltInCodePreviewOptions {
     /**
      * 是否允许执行内置的不安全代码预览。
@@ -13,6 +21,26 @@ export interface BuiltInCodePreviewOptions {
  * 根据运行结果构造 iframe sandbox 值。
  *
  * 默认不允许脚本执行；只有显式声明 `allowScripts` 时才放开 `allow-scripts`。
+ * @param allowScripts - 是否显式允许 iframe 脚本。
+ * @returns iframe sandbox 属性值；默认不开放脚本权限。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const sandbox = resolvePreviewSandbox(false)
+ * // 默认不添加 allow-scripts，只有受信任的显式选择才开放脚本。
+ * ```
  */
 export declare function resolvePreviewSandbox(allowScripts: boolean | undefined): string;
+/**
+ * 按语言创建受控预览；未授权的 HTML/JS/CSS 返回 undefined，需由宿主明确处理。
+ * @param request - 包含来源、内容和动作标识的请求。
+ * @param options - 本次操作的行为与显示选项。
+ * @returns 受控预览结果；未授权或不支持的代码返回 undefined。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const result = createBuiltInCodePreview({ blockId: 'md-1', code: '# 报告', language: 'markdown', sourceKind: 'code' }, { previewTitle: '预览', allowUnsafeCodePreview: false })
+ * if (result) { const markdown = result.content }
+ * ```
+ */
 export declare function createBuiltInCodePreview(request: MarkdownCodeRunRequest, options: BuiltInCodePreviewOptions): MarkdownCodeRunResult | undefined;

package/dist/components/scenes/ai/code-preview.js

@@ -7,10 +7,30 @@ const CSS_LANGUAGE_SET = new Set(['css']);
  * 根据运行结果构造 iframe sandbox 值。
  *
  * 默认不允许脚本执行；只有显式声明 `allowScripts` 时才放开 `allow-scripts`。
+ * @param allowScripts - 是否显式允许 iframe 脚本。
+ * @returns iframe sandbox 属性值；默认不开放脚本权限。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const sandbox = resolvePreviewSandbox(false)
+ * // 默认不添加 allow-scripts，只有受信任的显式选择才开放脚本。
+ * ```
  */
 export function resolvePreviewSandbox(allowScripts) {
     return allowScripts ? 'allow-scripts' : '';
 }
+/**
+ * 按语言创建受控预览；未授权的 HTML/JS/CSS 返回 undefined，需由宿主明确处理。
+ * @param request - 包含来源、内容和动作标识的请求。
+ * @param options - 本次操作的行为与显示选项。
+ * @returns 受控预览结果；未授权或不支持的代码返回 undefined。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const result = createBuiltInCodePreview({ blockId: 'md-1', code: '# 报告', language: 'markdown', sourceKind: 'code' }, { previewTitle: '预览', allowUnsafeCodePreview: false })
+ * if (result) { const markdown = result.content }
+ * ```
+ */
 export function createBuiltInCodePreview(request, options) {
     const language = (request.language ?? '').trim().toLowerCase();
     // mermaid 由 securityLevel:'strict' 渲染为消毒后的 SVG，无需 opt-in 高风险开关。

package/dist/components/scenes/ai/document-download.d.ts

@@ -1,8 +1,23 @@
 import type { MarkdownSourceKind, MarkdownToolbarDownloadAction } from './document-types.js';
 /**
  * 组件内置支持的文档导出格式。
+ *
+ * @example
+ * ```ts
+ * import type { AiDocumentDownloadFormat } from '@h-ai/ui'
+ * const example: AiDocumentDownloadFormat = 'markdown'
+ * ```
  */
 export type AiDocumentDownloadFormat = 'word' | 'markdown' | 'pdf';
+/**
+ * 归一化后的下载菜单项目。
+ *
+ * @example
+ * ```ts
+ * import type { AiDocumentResolvedDownloadAction } from '@h-ai/ui'
+ * const example: AiDocumentResolvedDownloadAction = { id: 'markdown', label: 'Markdown', badgeLabel: 'MD' }
+ * ```
+ */
 export interface AiDocumentResolvedDownloadAction {
     /** 菜单项稳定 id；内置格式直接复用格式名，自定义动作沿用上游传入值。 */
     id: string;
@@ -11,6 +26,15 @@ export interface AiDocumentResolvedDownloadAction {
     /** 可选短标签；保留给外层定制菜单使用。 */
     badgeLabel?: string;
 }
+/**
+ * 文档下载输入；自定义动作应由宿主回调处理。
+ *
+ * @example
+ * ```ts
+ * import type { AiDocumentDownloadRequest } from '@h-ai/ui'
+ * const example: AiDocumentDownloadRequest = { actionId: 'markdown', content: '# 报告\n正文', filename: 'report.md', sourceKind: 'document' }
+ * ```
+ */
 export interface AiDocumentDownloadRequest {
     /** 用户当前选中的下载动作 id。 */
     actionId: string;
@@ -28,13 +52,41 @@ export interface AiDocumentDownloadRequest {
 /**
  * code 类型产物通常只有裸代码正文。
  * 下载和预览都通过同一份规范化逻辑包装成 fenced markdown，避免两边导出的结构不一致。
+ * @param value - 待处理或校验的值。
+ * @param kind - 本次操作输入，具体字段见参数类型。
+ * @param language - 待识别的语言标记。
+ * @returns 保留原文或按代码来源包装后的 Markdown。
+ *
+ * @example
+ * ```ts
+ * import { resolveDocumentMarkdownContent } from '@h-ai/ui'
+ * const markdown = resolveDocumentMarkdownContent('const count = 42', 'code', 'typescript')
+ * // 裸代码会包装成足够长的 Markdown fence，保留源码中的反引号。
+ * ```
  */
 export declare function resolveDocumentMarkdownContent(value: string, kind?: MarkdownSourceKind, language?: string): string;
 /**
  * 把自定义动作和内置动作统一归一成统一的菜单项，保证左右两侧下载菜单展示一致。
+ * @param actions - 宿主提供的动作列表。
+ * @returns 具备显示标签的标准下载动作列表。
+ *
+ * @example
+ * ```ts
+ * import { resolveDocumentDownloadActions } from '@h-ai/ui'
+ * const actions = resolveDocumentDownloadActions([{ id: 'markdown', label: 'Markdown', badgeLabel: 'MD' }])
+ * ```
  */
 export declare function resolveDocumentDownloadActions(actions?: MarkdownToolbarDownloadAction[]): AiDocumentResolvedDownloadAction[];
 /**
  * 执行内置下载动作；未知动作直接跳过，方便外层保留自定义回调扩展口。
+ * @param request - 包含来源、内容和动作标识的请求。
+ * @returns 下载流程的 Promise；SSR 或未知动作无操作。
+ * @throws 浏览器渲染、第三方解析或下载失败时抛出异常，由交互边界显示错误。
+ *
+ * @example
+ * ```ts
+ * import { downloadAiDocument } from '@h-ai/ui'
+ * await downloadAiDocument({ actionId: 'markdown', content: '# 报告\n正文', title: '报告', filename: 'report.md', sourceKind: 'document' })
+ * ```
  */
 export declare function downloadAiDocument(request: AiDocumentDownloadRequest): Promise<void>;

package/dist/components/scenes/ai/document-download.js

@@ -1,4 +1,4 @@
-import { uiM } from '../../../messages.js';
+import { getUILocale, uiM } from '../../../messages.js';
 import { renderMarkdownDocument } from './document-parse.js';
 const DOCUMENT_EXPORT_ROOT_CLASS = 'hai-ai-document-export';
 const BROWSER_PDF_PAGE_HEIGHT_MM = 297;
@@ -32,6 +32,17 @@ function renderDocumentBlocksForExport(blocks) {
 /**
  * code 类型产物通常只有裸代码正文。
  * 下载和预览都通过同一份规范化逻辑包装成 fenced markdown，避免两边导出的结构不一致。
+ * @param value - 待处理或校验的值。
+ * @param kind - 本次操作输入，具体字段见参数类型。
+ * @param language - 待识别的语言标记。
+ * @returns 保留原文或按代码来源包装后的 Markdown。
+ *
+ * @example
+ * ```ts
+ * import { resolveDocumentMarkdownContent } from '@h-ai/ui'
+ * const markdown = resolveDocumentMarkdownContent('const count = 42', 'code', 'typescript')
+ * // 裸代码会包装成足够长的 Markdown fence，保留源码中的反引号。
+ * ```
  */
 export function resolveDocumentMarkdownContent(value, kind = 'markdown', language) {
     if (kind !== 'code') {
@@ -45,6 +56,14 @@ export function resolveDocumentMarkdownContent(value, kind = 'markdown', languag
 }
 /**
  * 把自定义动作和内置动作统一归一成统一的菜单项，保证左右两侧下载菜单展示一致。
+ * @param actions - 宿主提供的动作列表。
+ * @returns 具备显示标签的标准下载动作列表。
+ *
+ * @example
+ * ```ts
+ * import { resolveDocumentDownloadActions } from '@h-ai/ui'
+ * const actions = resolveDocumentDownloadActions([{ id: 'markdown', label: 'Markdown', badgeLabel: 'MD' }])
+ * ```
  */
 export function resolveDocumentDownloadActions(actions = []) {
     if (actions.length === 0) {
@@ -67,6 +86,15 @@ export function resolveDocumentDownloadActions(actions = []) {
 }
 /**
  * 执行内置下载动作；未知动作直接跳过，方便外层保留自定义回调扩展口。
+ * @param request - 包含来源、内容和动作标识的请求。
+ * @returns 下载流程的 Promise；SSR 或未知动作无操作。
+ * @throws 浏览器渲染、第三方解析或下载失败时抛出异常，由交互边界显示错误。
+ *
+ * @example
+ * ```ts
+ * import { downloadAiDocument } from '@h-ai/ui'
+ * await downloadAiDocument({ actionId: 'markdown', content: '# 报告\n正文', title: '报告', filename: 'report.md', sourceKind: 'document' })
+ * ```
  */
 export async function downloadAiDocument(request) {
     if (typeof document === 'undefined') {
@@ -285,7 +313,7 @@ function buildDocumentExportBody(bodyHtml) {
 }
 function buildDocumentExportHtml(title, bodyHtml) {
     return `<!doctype html>
-<html lang="zh-CN">
+<html lang="${escapeExportHtml(getUILocale())}">
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />