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

package/dist/components/scenes/ai/editor-markdown-extensions.d.ts

@@ -2,10 +2,26 @@ import type { Token, TokenizerAndRendererExtension } from 'marked';
 /**
  * Markdown heading 提取目录时需要一个“纯文本标题”。
  * 这里显式递归常见 inline token，保证 `<hai-span>`、链接、强调等都能回落成纯文本。
+ * @param tokens - Marked token 列表。
+ * @returns 递归提取的纯文本，用于标题和目录生成。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const text = extractPlainTextFromTokens([{ type: 'text', raw: '简介', text: '简介' }])
+ * ```
  */
 export declare function extractPlainTextFromTokens(tokens: Token[] | undefined): string;
 /**
  * ChatWorkspace 编辑器会把“非标准 Markdown”能力写成自定义标签，
  * 这里把它们注册为 marked 扩展，保证普通 Markdown 和编辑器增强能力共享同一条渲染链路。
+ * @returns 受控格式的 Marked tokenizer/renderer 扩展。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const { Marked } = await import('marked')
+ * const extensions = createEditorMarkdownExtensions()
+ * const parser = new Marked({ extensions })
+ * const html = parser.parse('**重点**')
+ * ```
  */
 export declare function createEditorMarkdownExtensions(): TokenizerAndRendererExtension[];

package/dist/components/scenes/ai/editor-markdown-extensions.js

@@ -14,6 +14,13 @@ const HAI_HIGHLIGHT_REGEX = /^==((?:\\.|[\s\S])+?)==/;
 /**
  * Markdown heading 提取目录时需要一个“纯文本标题”。
  * 这里显式递归常见 inline token，保证 `<hai-span>`、链接、强调等都能回落成纯文本。
+ * @param tokens - Marked token 列表。
+ * @returns 递归提取的纯文本，用于标题和目录生成。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const text = extractPlainTextFromTokens([{ type: 'text', raw: '简介', text: '简介' }])
+ * ```
  */
 export function extractPlainTextFromTokens(tokens) {
     if (!tokens || tokens.length === 0) {
@@ -74,6 +81,15 @@ function parseHaiSpanAttributes(rawAttributes) {
 /**
  * ChatWorkspace 编辑器会把“非标准 Markdown”能力写成自定义标签，
  * 这里把它们注册为 marked 扩展，保证普通 Markdown 和编辑器增强能力共享同一条渲染链路。
+ * @returns 受控格式的 Marked tokenizer/renderer 扩展。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const { Marked } = await import('marked')
+ * const extensions = createEditorMarkdownExtensions()
+ * const parser = new Marked({ extensions })
+ * const html = parser.parse('**重点**')
+ * ```
  */
 export function createEditorMarkdownExtensions() {
     return [

package/dist/components/scenes/ai/highlight.d.ts

@@ -11,6 +11,11 @@
  *
  * @param lang - 语言标识符（支持别名如 js、ts、py）
  * @returns 是否支持该语言
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const supported = isLanguageSupported('typescript')
+ * ```
  */
 export declare function isLanguageSupported(lang: string): boolean;
 /**
@@ -22,5 +27,11 @@ export declare function isLanguageSupported(lang: string): boolean;
  * @param text - 代码文本
  * @param lang - 语言标识符
  * @returns 高亮后的 HTML 片段
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const html = highlightCode('const count = 42', 'typescript')
+ * // 返回已转义/高亮后的代码 HTML，未知语言回退安全纯文本。
+ * ```
  */
 export declare function highlightCode(text: string, lang: string): string;

package/dist/components/scenes/ai/highlight.js

@@ -128,6 +128,11 @@ function extractCodeInnerHtml(html) {
  *
  * @param lang - 语言标识符（支持别名如 js、ts、py）
  * @returns 是否支持该语言
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const supported = isLanguageSupported('typescript')
+ * ```
  */
 export function isLanguageSupported(lang) {
     return resolveLang(lang) !== null;
@@ -141,6 +146,12 @@ export function isLanguageSupported(lang) {
  * @param text - 代码文本
  * @param lang - 语言标识符
  * @returns 高亮后的 HTML 片段
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const html = highlightCode('const count = 42', 'typescript')
+ * // 返回已转义/高亮后的代码 HTML，未知语言回退安全纯文本。
+ * ```
  */
 export function highlightCode(text, lang) {
     const resolved = resolveLang(lang);

package/dist/components/scenes/ai/markdown-parse.d.ts

@@ -7,6 +7,12 @@
  */
 /**
  * Markdown 解析配置
+ *
+ * @example
+ * ```ts
+ * import type { MarkdownParseOptions } from '@h-ai/ui'
+ * const example: MarkdownParseOptions = { enableHighlight: true, allowHtmlTags: false, showCopyButton: true }
+ * ```
  */
 export interface MarkdownParseOptions {
     /** 是否启用代码语法高亮（默认 true） */
@@ -27,8 +33,8 @@ export interface MarkdownParseOptions {
  *
  * @example
  * ```ts
- * const html = parseMarkdown('# Hello\n\nWorld')
- * // => '<h1>Hello</h1>\n<p>World</p>\n'
+ * import { parseMarkdown } from '@h-ai/ui'
+ * const html = parseMarkdown('# 简介\n**重点**', { allowHtmlTags: false })
  * ```
  */
 export declare function parseMarkdown(content: string, options?: MarkdownParseOptions): string;

package/dist/components/scenes/ai/markdown-parse.js

@@ -152,8 +152,8 @@ function getOptionsKey(options) {
  *
  * @example
  * ```ts
- * const html = parseMarkdown('# Hello\n\nWorld')
- * // => '<h1>Hello</h1>\n<p>World</p>\n'
+ * import { parseMarkdown } from '@h-ai/ui'
+ * const html = parseMarkdown('# 简介\n**重点**', { allowHtmlTags: false })
  * ```
  */
 export function parseMarkdown(content, options) {

package/dist/components/scenes/ai/mermaid-host-sync.d.ts

@@ -3,6 +3,11 @@
  *
  * Mermaid 图表通过 {@html} 插入占位节点后异步渲染。流式输出时，HTML 占位可能不变，
  * 但源码正文会持续变化，因此必须用源码签名判断是否需要重渲染。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const example: MermaidHostRenderActionInput = { status: 'ready', renderedSignature: 'old-source', nextSignature: 'new-source' }
+ * ```
  */
 export interface MermaidHostRenderActionInput {
     /** 当前 host 上记录的渲染状态。 */
@@ -12,6 +17,14 @@ export interface MermaidHostRenderActionInput {
     /** 本次 Markdown 解析得到的最新源码签名。 */
     nextSignature: string;
 }
+/**
+ * 异步 Mermaid 渲染决策；仅 shouldRender=true 时携带提交 token。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const example: MermaidHostRenderAction = { shouldRender: true, token: 'diagram-1-source' }
+ * ```
+ */
 export type MermaidHostRenderAction = {
     shouldRender: false;
 } | {
@@ -22,13 +35,38 @@ export type MermaidHostRenderAction = {
  * 为 Mermaid block 生成稳定签名。
  *
  * 签名同时包含 block id 与源码正文，避免流式阶段占位 HTML 未变化时漏掉源码更新。
+ * @param blockId - 当前代码块的稳定 ID。
+ * @param code - Mermaid 或待渲染的代码源码。
+ * @returns 绑定块 id 和完整源码的稳定签名。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const signature = createMermaidSourceSignature('diagram-1', 'graph TD; A-->B')
+ * ```
  */
 export declare function createMermaidSourceSignature(blockId: string, code: string): string;
 /**
  * 判断 Mermaid host 是否需要发起一次新的异步渲染。
+ * @param input - 当前状态及目标源码签名。
+ * @returns 是否重渲染的决策，需要时携带提交 token。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const action = getMermaidHostRenderAction({ status: 'ready', renderedSignature: 'old', nextSignature: 'new' })
+ * if (action.shouldRender) { const token = action.token }
+ * ```
  */
 export declare function getMermaidHostRenderAction(input: MermaidHostRenderActionInput): MermaidHostRenderAction;
 /**
  * 判断异步 Mermaid 渲染结果是否仍对应当前 host 源码。
+ * @param renderToken - 异步渲染启动时捕获的 token。
+ * @param currentSignature - 宿主当前源码签名。
+ * @returns 渲染 token 是否仍匹配当前源码签名。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const accepted = isCurrentMermaidRenderToken('current-source', 'current-source')
+ * const stale = isCurrentMermaidRenderToken('old-source', 'current-source')
+ * ```
  */
 export declare function isCurrentMermaidRenderToken(renderToken: string, currentSignature: string | undefined): boolean;

package/dist/components/scenes/ai/mermaid-host-sync.js

@@ -3,17 +3,38 @@
  *
  * Mermaid 图表通过 {@html} 插入占位节点后异步渲染。流式输出时，HTML 占位可能不变，
  * 但源码正文会持续变化，因此必须用源码签名判断是否需要重渲染。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const example: MermaidHostRenderActionInput = { status: 'ready', renderedSignature: 'old-source', nextSignature: 'new-source' }
+ * ```
  */
 /**
  * 为 Mermaid block 生成稳定签名。
  *
  * 签名同时包含 block id 与源码正文，避免流式阶段占位 HTML 未变化时漏掉源码更新。
+ * @param blockId - 当前代码块的稳定 ID。
+ * @param code - Mermaid 或待渲染的代码源码。
+ * @returns 绑定块 id 和完整源码的稳定签名。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const signature = createMermaidSourceSignature('diagram-1', 'graph TD; A-->B')
+ * ```
  */
 export function createMermaidSourceSignature(blockId, code) {
     return JSON.stringify([blockId, code]);
 }
 /**
  * 判断 Mermaid host 是否需要发起一次新的异步渲染。
+ * @param input - 当前状态及目标源码签名。
+ * @returns 是否重渲染的决策，需要时携带提交 token。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const action = getMermaidHostRenderAction({ status: 'ready', renderedSignature: 'old', nextSignature: 'new' })
+ * if (action.shouldRender) { const token = action.token }
+ * ```
  */
 export function getMermaidHostRenderAction(input) {
     const status = input.status?.trim();
@@ -29,6 +50,15 @@ export function getMermaidHostRenderAction(input) {
 }
 /**
  * 判断异步 Mermaid 渲染结果是否仍对应当前 host 源码。
+ * @param renderToken - 异步渲染启动时捕获的 token。
+ * @param currentSignature - 宿主当前源码签名。
+ * @returns 渲染 token 是否仍匹配当前源码签名。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const accepted = isCurrentMermaidRenderToken('current-source', 'current-source')
+ * const stale = isCurrentMermaidRenderToken('old-source', 'current-source')
+ * ```
  */
 export function isCurrentMermaidRenderToken(renderToken, currentSignature) {
     return renderToken === currentSignature;

package/dist/components/scenes/ai/mermaid-render.d.ts

@@ -6,14 +6,37 @@
  */
 /**
  * 判断 fence 语言是否为 mermaid。
+ * @param language - 待识别的语言标记。
+ * @returns 语言标记是否属于 Mermaid。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const supported = isMermaidLanguage('mermaid')
+ * ```
  */
 export declare function isMermaidLanguage(language: string | undefined | null): boolean;
 /**
  * 把 mermaid 源码渲染为 SVG 字符串；语法错误时抛出由调用方兜底展示。
+ * @param code - Mermaid 或待渲染的代码源码。
+ * @returns 严格模式渲染并移除样式节点后的 SVG。
+ * @throws 浏览器渲染、第三方解析或下载失败时抛出异常，由交互边界显示错误。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const svg = await renderMermaidDiagram('graph TD; A-->B')
+ * // 在浏览器异步渲染，失败由调用交互边界处理。
+ * ```
  */
 export declare function renderMermaidDiagram(code: string): Promise<string>;
 /**
  * Mermaid 11.x 会在 SVG 内写入很长的 style 标签内容；在 contenteditable 预览区里，
  * 部分浏览器会把这些 CSS 当成正文显示。这里保留 SVG 图形，剥离内联样式文本。
+ * @param svg - 待移除样式节点的 SVG。
+ * @returns 移除 style 元素后的 SVG 字符串。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const svg = stripMermaidSvgStyleElements('<svg><style>.x{fill:red}</style><path d="M0 0"/></svg>')
+ * ```
  */
 export declare function stripMermaidSvgStyleElements(svg: string): string;

package/dist/components/scenes/ai/mermaid-render.js

@@ -10,6 +10,13 @@ let mermaidLoader = null;
 let renderSeq = 0;
 /**
  * 判断 fence 语言是否为 mermaid。
+ * @param language - 待识别的语言标记。
+ * @returns 语言标记是否属于 Mermaid。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const supported = isMermaidLanguage('mermaid')
+ * ```
  */
 export function isMermaidLanguage(language) {
     return (language ?? '').trim().toLowerCase() === 'mermaid';
@@ -33,6 +40,15 @@ async function loadMermaid() {
 }
 /**
  * 把 mermaid 源码渲染为 SVG 字符串；语法错误时抛出由调用方兜底展示。
+ * @param code - Mermaid 或待渲染的代码源码。
+ * @returns 严格模式渲染并移除样式节点后的 SVG。
+ * @throws 浏览器渲染、第三方解析或下载失败时抛出异常，由交互边界显示错误。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const svg = await renderMermaidDiagram('graph TD; A-->B')
+ * // 在浏览器异步渲染，失败由调用交互边界处理。
+ * ```
  */
 export async function renderMermaidDiagram(code) {
     const mermaid = await loadMermaid();
@@ -43,6 +59,13 @@ export async function renderMermaidDiagram(code) {
 /**
  * Mermaid 11.x 会在 SVG 内写入很长的 style 标签内容；在 contenteditable 预览区里，
  * 部分浏览器会把这些 CSS 当成正文显示。这里保留 SVG 图形，剥离内联样式文本。
+ * @param svg - 待移除样式节点的 SVG。
+ * @returns 移除 style 元素后的 SVG 字符串。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const svg = stripMermaidSvgStyleElements('<svg><style>.x{fill:red}</style><path d="M0 0"/></svg>')
+ * ```
  */
 export function stripMermaidSvgStyleElements(svg) {
     return svg.replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, '');

package/dist/components/scenes/ai/safe-html.d.ts

@@ -1,16 +1,64 @@
 /**
- * @h-ai/ui — Safe HTML helpers for Markdown rendering.
+ * @h-ai/ui — Markdown 渲染的安全 HTML 工具。
  *
- * The Markdown pipeline keeps raw HTML escaped by default.
- * When callers opt in, only a controlled allowlist of safe tags and
- * attributes is reconstructed; unsupported or dangerous markup remains escaped.
+ * Markdown 默认将原始 HTML 当作纯文本转义。
+ * 显式允许 HTML 后，也只重建白名单中的安全标签与
+ * 属性；不支持或危险的标记仍按文字转义。
+ */
+/**
+ * 将候选文本中的 HTML 特殊字符转义为可安全展示的纯文本。
+ * @param text - 待处理文本。
+ * @returns HTML 特殊字符被转义的字符串。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const escaped = escapeHtml('<b>文本</b>')
+ * ```
  */
 export declare function escapeHtml(text: string): string;
+/**
+ * 拒绝脚本等危险协议，只输出允许的链接地址。
+ * @param href - 待验证的链接候选地址。
+ * @returns 允许的链接地址，不安全或空输入返回空字符串。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const safe = sanitizeLinkHref('javascript:alert(1)')
+ * // 不安全协议变为空字符串，不能直接渲染原始 href。
+ * ```
+ */
 export declare function sanitizeLinkHref(href: string | null | undefined): string;
+/**
+ * 识别外部链接，供渲染器添加相应的 rel/target 安全属性。
+ * @param href - 待验证的链接候选地址。
+ * @returns 地址是否为需要外链安全属性的外部链接。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const external = isExternalLinkHref('https://example.com/help')
+ * ```
+ */
 export declare function isExternalLinkHref(href: string): boolean;
+/**
+ * 拒绝危险图片来源，保留允许的远程、相对或受控数据地址。
+ * @param src - 待验证的图片候选地址。
+ * @returns 允许的图片地址，不安全或空输入返回空字符串。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const safe = sanitizeImageSrc('https://example.com/image.png')
+ * ```
+ */
 export declare function sanitizeImageSrc(src: string | null | undefined): string;
 /**
- * Sanitize raw HTML fragments embedded inside Markdown.
- * Safe allowlisted tags are reconstructed, everything else remains escaped.
+ * 消毒 Markdown 中嵌入的原始 HTML 片段。
+ * 只重建白名单标签，其余内容保持转义。
+ * @param fragment - 待消毒的 HTML 片段。
+ * @returns 仅保留白名单标签和安全属性的 HTML。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const safe = sanitizeMarkdownHtml('<p onclick="alert(1)">正文</p>')
+ * ```
  */
 export declare function sanitizeMarkdownHtml(fragment: string): string;

package/dist/components/scenes/ai/safe-html.js

@@ -1,9 +1,9 @@
 /**
- * @h-ai/ui — Safe HTML helpers for Markdown rendering.
+ * @h-ai/ui — Markdown 渲染的安全 HTML 工具。
  *
- * The Markdown pipeline keeps raw HTML escaped by default.
- * When callers opt in, only a controlled allowlist of safe tags and
- * attributes is reconstructed; unsupported or dangerous markup remains escaped.
+ * Markdown 默认将原始 HTML 当作纯文本转义。
+ * 显式允许 HTML 后，也只重建白名单中的安全标签与
+ * 属性；不支持或危险的标记仍按文字转义。
  */
 const SAFE_LINK_HREF_REGEX = /^(?:https?:\/\/|\/|#|mailto:)/i;
 const SAFE_IMAGE_SRC_REGEX = /^(?:https?:\/\/|\/|data:image\/)/i;
@@ -63,6 +63,16 @@ const ALIGNABLE_HTML_TAGS = new Set([
     'td',
     'th',
 ]);
+/**
+ * 将候选文本中的 HTML 特殊字符转义为可安全展示的纯文本。
+ * @param text - 待处理文本。
+ * @returns HTML 特殊字符被转义的字符串。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const escaped = escapeHtml('<b>文本</b>')
+ * ```
+ */
 export function escapeHtml(text) {
     return text
         .replace(/&/g, '&amp;')
@@ -71,13 +81,44 @@ export function escapeHtml(text) {
         .replace(/"/g, '&quot;')
         .replace(/'/g, '&#39;');
 }
+/**
+ * 拒绝脚本等危险协议，只输出允许的链接地址。
+ * @param href - 待验证的链接候选地址。
+ * @returns 允许的链接地址，不安全或空输入返回空字符串。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const safe = sanitizeLinkHref('javascript:alert(1)')
+ * // 不安全协议变为空字符串，不能直接渲染原始 href。
+ * ```
+ */
 export function sanitizeLinkHref(href) {
     const normalized = href?.trim() ?? '';
     return SAFE_LINK_HREF_REGEX.test(normalized) ? normalized : '';
 }
+/**
+ * 识别外部链接，供渲染器添加相应的 rel/target 安全属性。
+ * @param href - 待验证的链接候选地址。
+ * @returns 地址是否为需要外链安全属性的外部链接。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const external = isExternalLinkHref('https://example.com/help')
+ * ```
+ */
 export function isExternalLinkHref(href) {
     return /^https?:\/\//i.test(href);
 }
+/**
+ * 拒绝危险图片来源，保留允许的远程、相对或受控数据地址。
+ * @param src - 待验证的图片候选地址。
+ * @returns 允许的图片地址，不安全或空输入返回空字符串。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const safe = sanitizeImageSrc('https://example.com/image.png')
+ * ```
+ */
 export function sanitizeImageSrc(src) {
     const normalized = src?.trim() ?? '';
     return SAFE_IMAGE_SRC_REGEX.test(normalized) ? normalized : '';
@@ -265,8 +306,15 @@ function sanitizeHtmlTag(rawTag) {
         : `<${tagName}${attributeText}>`;
 }
 /**
- * Sanitize raw HTML fragments embedded inside Markdown.
- * Safe allowlisted tags are reconstructed, everything else remains escaped.
+ * 消毒 Markdown 中嵌入的原始 HTML 片段。
+ * 只重建白名单标签，其余内容保持转义。
+ * @param fragment - 待消毒的 HTML 片段。
+ * @returns 仅保留白名单标签和安全属性的 HTML。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const safe = sanitizeMarkdownHtml('<p onclick="alert(1)">正文</p>')
+ * ```
  */
 export function sanitizeMarkdownHtml(fragment) {
     if (!fragment) {

package/dist/components/scenes/ai/table/AiTableEditor.svelte

@@ -1,4 +1,5 @@
 <!--
+  @component AiTableEditor
   =============================================================================
   @h-ai/ui - AiTableEditor 组件
   =============================================================================
@@ -10,6 +11,16 @@
 
   使用 Svelte 5 Runes ($props, $state, $derived, $effect)
   =============================================================================
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { AiTableEditor } from '@h-ai/ui'
+  const props: ComponentProps<typeof AiTableEditor> = { title: '销量', tableData: { table_columns: [{ key: 'sales', label: '销量', type: 'number' }], table_rows: [{ row_id: 'r1', sales: 42 }] } }
+  const component = mount(AiTableEditor, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { DataAttributes } from '../../../../types.js'
@@ -28,6 +39,14 @@
   import { cn, getDataAttributes } from '../../../../utils.js'
   import AiDocumentDownloadMenu from '../AiDocumentDownloadMenu.svelte'
 
+  /**
+   * 流式表格 JSON 中提取的数组片段；complete=false 时不能当作完整最终数据。
+   *
+   * @example 模块内部上下文
+   * ```ts
+   * const example: ExtractedArrayChunk = { source: '[{"row_id":"r1"}]', complete: true }
+   * ```
+   */
   interface ExtractedArrayChunk {
     /** 从原始字符串里截取到的数组片段（可能是不完整数组）。 */
     source: string
@@ -35,8 +54,24 @@
     complete: boolean
   }
 
+  /**
+   * 拖放行相对目标行的插入方向。
+   *
+   * @example 模块内部上下文
+   * ```ts
+   * const example: AiTableRowDropPosition = 'before'
+   * ```
+   */
   type AiTableRowDropPosition = 'before' | 'after'
 
+  /**
+   * 表格拖放产生的新快照和前后索引；未变更时 nextData 为 null。
+   *
+   * @example 模块内部上下文
+   * ```ts
+   * const example: ReorderedTableResult = { nextData: { table_columns: [{ key: 'sales', label: '销量', type: 'number' }], table_rows: [{ row_id: 'r1', sales: 42 }] }, fromIndex: 1, toIndex: 0 }
+   * ```
+   */
   interface ReorderedTableResult {
     /** 重排后的完整表格快照；未真正变更顺序时为 `null`。 */
     nextData: AiTableData | null
@@ -683,6 +718,19 @@
     clearScheduledCellChange()
   }
 
+  /**
+   * 立即交付尚在防抖窗口中的单元格修改，关闭或保存前可通过组件引用调用。
+   * @returns 无返回值；立即交付最后一份待发送的单元格修改。
+   *
+   * @example
+   * ```ts
+   * import { mount, unmount } from 'svelte'
+   * import { AiTableEditor } from '@h-ai/ui'
+   * const editor = mount(AiTableEditor, { target: document.body, props: { tableData: { table_columns: [{ key: 'sales', label: '销量', type: 'number' }], table_rows: [{ row_id: 'r1', sales: 42 }] } } })
+   * editor.flushPendingTableChange()
+   * await unmount(editor)
+   * ```
+   */
   export function flushPendingTableChange(): void {
     const pendingPayload = pendingCellChangePayload
     if (!pendingPayload) {

package/dist/components/scenes/ai/table/AiTableEditor.svelte.d.ts

@@ -1,6 +1,30 @@
 import type { DataAttributes } from '../../../../types.js';
 import type { AiTableEditorProps } from './table-types.js';
 type $$ComponentProps = AiTableEditorProps & DataAttributes;
+/**
+ * AiTableEditor
+ * =============================================================================
+ * @h-ai/ui - AiTableEditor 组件
+ * =============================================================================
+ * 面向 AI 场景的可编辑表格查看器，支持：
+ * - 从结构化数据或 JSON 文本渲染表格
+ * - 流式残缺 JSON 的增量容错解析（列/行可分段出现）
+ * - 单元格编辑、行新增、行删除、拖拽排序
+ * - 复制表格（TSV）与下载表格（CSV）
+ *
+ * 使用 Svelte 5 Runes ($props, $state, $derived, $effect)
+ * =============================================================================
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { AiTableEditor } from '@h-ai/ui'
+ * const props: ComponentProps<typeof AiTableEditor> = { title: '销量', tableData: { table_columns: [{ key: 'sales', label: '销量', type: 'number' }], table_rows: [{ row_id: 'r1', sales: 42 }] } }
+ * const component = mount(AiTableEditor, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 declare const AiTableEditor: import("svelte").Component<$$ComponentProps, {
     flushPendingTableChange: () => void;
 }, "editorScrollHost">;