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

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

@@ -1,38 +1,76 @@
 /**
- * @h-ai/ui — Markdown document parsing helpers
+ * @h-ai/ui — Markdown 文档解析工具
  *
- * Extracts HTML, outline, and code block metadata for document-mode rendering.
+ * 为文档模式提取安全 HTML、目录和代码块元信息。
  */
 import type { MarkdownCodeBlockItem, MarkdownOutlineItem } from './document-types.js';
+/**
+ * 安全 Markdown 文档解析选项；运行按钮不等于允许执行代码。
+ *
+ * @example
+ * ```ts
+ * import type { MarkdownDocumentParseOptions } from '@h-ai/ui'
+ * const example: MarkdownDocumentParseOptions = { enableHighlight: true, allowHtmlTags: false, showRunButton: false, breaks: true }
+ * ```
+ */
 export interface MarkdownDocumentParseOptions {
-    /** Whether to enable syntax highlighting for code blocks. */
+    /** 是否启用代码块语法高亮。 */
     enableHighlight?: boolean;
-    /** Whether to render the copy button in code blocks. */
+    /** 是否渲染代码块复制按钮。 */
     showCopyButton?: boolean;
-    /** Whether to render the run button and preview slot. */
+    /** 是否渲染运行按钮和预览槽；实际运行由宿主授权。 */
     showRunButton?: boolean;
-    /** Whether to render code/preview tabs in code-block headers. */
+    /** 是否渲染代码块头部的代码/预览切换。 */
     showCodePreviewToggle?: boolean;
-    /** Label used for the "code" tab when preview toggle is enabled. */
+    /** 启用预览切换时的代码页签文案。 */
     codeViewCodeLabel?: string;
-    /** Label used for the "preview" tab when preview toggle is enabled. */
+    /** 启用预览切换时的预览页签文案。 */
     codeViewPreviewLabel?: string;
-    /** Optional helper text displayed beside language in code headers. */
+    /** 代码块头部语言标签旁的提示文案。 */
     codePreviewHint?: string;
-    /** Whether soft line breaks are converted to <br>. */
+    /** 是否将普通换行转换成 br。 */
     breaks?: boolean;
-    /** Whether raw HTML tags are parsed through a safe allowlist. */
+    /** 是否按安全白名单解析原始 HTML 标签。 */
     allowHtmlTags?: boolean;
 }
+/**
+ * 一次文档解析生成的安全渲染块、目录和原始代码块信息。
+ *
+ * @example
+ * ```ts
+ * import { renderMarkdownDocument } from '@h-ai/ui'
+ * import type { MarkdownRenderResult } from '@h-ai/ui'
+ * const result: MarkdownRenderResult = renderMarkdownDocument('# 简介\n正文')
+ * const headings = result.outline
+ * ```
+ */
 export interface MarkdownRenderResult {
-    /** Extracted outline items for navigation. */
+    /** 供目录导航使用的标题条目。 */
     outline: MarkdownOutlineItem[];
-    /** Extracted code blocks for run/copy features. */
+    /** 供运行/复制功能使用的代码块元信息。 */
     codeBlocks: MarkdownCodeBlockItem[];
     /** 阅读态使用的稳定块列表，避免流式更新销毁重型块 DOM。 */
     blocks: MarkdownDocumentBlock[];
 }
+/**
+ * 文档渲染块的可辨识联合；HTML 块和 Mermaid 源码块分开更新。
+ *
+ * @example
+ * ```ts
+ * import type { MarkdownDocumentBlock } from '@h-ai/ui'
+ * const example: MarkdownDocumentBlock = { kind: 'html', id: 'paragraph-1', html: '<p>正文</p>' }
+ * ```
+ */
 export type MarkdownDocumentBlock = MarkdownDocumentHtmlBlock | MarkdownDocumentMermaidBlock;
+/**
+ * 已经过安全策略处理的 Markdown HTML 块；不要填入未消毒输入。
+ *
+ * @example
+ * ```ts
+ * import type { MarkdownDocumentHtmlBlock } from '@h-ai/ui'
+ * const example: MarkdownDocumentHtmlBlock = { kind: 'html', id: 'paragraph-1', html: '<p>正文</p>' }
+ * ```
+ */
 export interface MarkdownDocumentHtmlBlock {
     /** 普通 Markdown HTML 块。 */
     kind: 'html';
@@ -41,6 +79,15 @@ export interface MarkdownDocumentHtmlBlock {
     /** 已按现有安全策略渲染后的 HTML。 */
     html: string;
 }
+/**
+ * 完整 Mermaid 块的源码与签名，等待异步严格模式渲染。
+ *
+ * @example
+ * ```ts
+ * import type { MarkdownDocumentMermaidBlock } from '@h-ai/ui'
+ * const example: MarkdownDocumentMermaidBlock = { kind: 'mermaid', id: 'diagram-1', codeBlockId: 'code-1', code: 'graph TD; A-->B', language: 'mermaid', signature: JSON.stringify(['diagram-1', 'graph TD; A-->B']) }
+ * ```
+ */
 export interface MarkdownDocumentMermaidBlock {
     /** 已闭合 Mermaid fence 块。 */
     kind: 'mermaid';
@@ -56,6 +103,16 @@ export interface MarkdownDocumentMermaidBlock {
     signature: string;
 }
 /**
- * Render markdown into HTML and extract outline + code block metadata.
+ * 安全渲染 Markdown，同时提取目录和代码块元信息。
+ * @param content - Markdown 或文档正文。
+ * @param options - 本次操作的行为与显示选项。
+ * @returns 已消毒渲染块、目录和代码元信息。
+ *
+ * @example
+ * ```ts
+ * import { renderMarkdownDocument } from '@h-ai/ui'
+ * const result = renderMarkdownDocument('# 简介\n正文', { allowHtmlTags: false, enableHighlight: true })
+ * const firstHeading = result.outline[0]?.text
+ * ```
  */
 export declare function renderMarkdownDocument(content: string, options?: MarkdownDocumentParseOptions): MarkdownRenderResult;

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

@@ -1,14 +1,14 @@
 /**
- * @h-ai/ui — Markdown document parsing helpers
+ * @h-ai/ui — Markdown 文档解析工具
  *
- * Extracts HTML, outline, and code block metadata for document-mode rendering.
+ * 为文档模式提取安全 HTML、目录和代码块元信息。
  */
 import { Marked } from 'marked';
 import { createEditorMarkdownExtensions, extractPlainTextFromTokens, } from './editor-markdown-extensions.js';
 import { highlightCode, isLanguageSupported } from './highlight.js';
 import { isMermaidLanguage } from './mermaid-render.js';
 import { escapeHtml, isExternalLinkHref, sanitizeImageSrc, sanitizeLinkHref, sanitizeMarkdownHtml, } from './safe-html.js';
-/** Default parsing options for document mode. */
+/** 文档模式的默认解析选项。 */
 const DEFAULT_OPTIONS = {
     enableHighlight: true,
     showCopyButton: true,
@@ -64,7 +64,7 @@ function isClosedFencedCodeBlock(token) {
         && [...closingFence].every(char => char === markerChar);
 }
 /**
- * Create a URL-safe heading slug while keeping letters and digits.
+ * 生成保留字母和数字的 URL 安全标题 slug。
  */
 function slugifyHeading(text) {
     // normalized slug used as the base key for headings.
@@ -78,7 +78,7 @@ function slugifyHeading(text) {
     return normalized || 'section';
 }
 /**
- * Generate a stable heading id, de-duplicating repeated titles.
+ * 为标题生成稳定 ID，并对重复标题去重。
  */
 function createHeadingId(state, text) {
     // base slug before de-duplication.
@@ -89,7 +89,7 @@ function createHeadingId(state, text) {
     return nextCount === 1 ? base : `${base}-${nextCount}`;
 }
 /**
- * Add numeric prefixes (1, 1.1, 1.1.1) to outline items.
+ * 为目录条目添加 1、1.1 等层级编号。
  */
 function createNumberedOutline(outline) {
     // counters track the current numbering state per heading depth.
@@ -113,7 +113,7 @@ function createNumberedOutline(outline) {
     });
 }
 /**
- * Build the marked renderer with outline extraction and code metadata.
+ * 构建同时提取目录与代码元信息的 Marked renderer。
  */
 function createRendererObject(options, state) {
     return {
@@ -264,7 +264,7 @@ function createRendererObject(options, state) {
     };
 }
 /**
- * Create a marked instance tied to a specific render state.
+ * 创建绑定本次临时解析状态的 Marked 实例。
  */
 function createMarkedInstance(options, state) {
     return new Marked({
@@ -368,7 +368,17 @@ function renderMarkdownDocumentBlocks(content, options) {
     return blocks;
 }
 /**
- * Render markdown into HTML and extract outline + code block metadata.
+ * 安全渲染 Markdown，同时提取目录和代码块元信息。
+ * @param content - Markdown 或文档正文。
+ * @param options - 本次操作的行为与显示选项。
+ * @returns 已消毒渲染块、目录和代码元信息。
+ *
+ * @example
+ * ```ts
+ * import { renderMarkdownDocument } from '@h-ai/ui'
+ * const result = renderMarkdownDocument('# 简介\n正文', { allowHtmlTags: false, enableHighlight: true })
+ * const firstHeading = result.outline[0]?.text
+ * ```
  */
 export function renderMarkdownDocument(content, options) {
     if (!content) {

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

@@ -1,46 +1,87 @@
 import type { DataAttributes } from '../../../types.js';
 /**
- * Markdown source type, used to distinguish plain markdown, document panel, or code-only rendering.
+ * 内容来源种类，用于区分 Markdown 正文、文档面板和纯代码展示。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const example: MarkdownSourceKind = 'document'
+ * ```
  */
 export type MarkdownSourceKind = 'markdown' | 'document' | 'code';
+/**
+ * 文档目录节点，绑定稳定锚点、标题级别和编号标题。
+ *
+ * @example
+ * ```ts
+ * import type { MarkdownOutlineItem } from '@h-ai/ui'
+ * const example: MarkdownOutlineItem = { id: 'intro', text: '简介', level: 1, numberedTitle: '1 简介' }
+ * ```
+ */
 export interface MarkdownOutlineItem {
-    /** Anchor id for outline navigation and heading sync. */
+    /** 目录导航与标题同步使用的稳定锚点 ID。 */
     id: string;
-    /** Plain heading text without inline markdown formatting. */
+    /** 不含行内 Markdown 格式的纯文本标题。 */
     text: string;
-    /** Heading level (1-6), mapping to h1-h6. */
+    /** 标题级别 1..6，对应 h1..h6。 */
     level: number;
-    /** Numbered heading text for outline display. */
+    /** 用于目录展示的编号标题。 */
     numberedTitle: string;
 }
+/**
+ * 代码块的原始源码及语言标记，供复制和预览复用。
+ *
+ * @example
+ * ```ts
+ * import type { MarkdownCodeBlockItem } from '@h-ai/ui'
+ * const example: MarkdownCodeBlockItem = { id: 'code-1', code: 'const count = 42', language: 'typescript' }
+ * ```
+ */
 export interface MarkdownCodeBlockItem {
-    /** Stable code block id used by preview and DOM bindings. */
+    /** 预览与 DOM 关联使用的稳定代码块 ID。 */
     id: string;
-    /** Raw code text before highlighting. */
+    /** 语法高亮前的原始源码。 */
     code: string;
-    /** Detected language label, if any. */
+    /** 解析到的语言标记，可省略。 */
     language?: string;
 }
+/**
+ * 代码块运行请求；由宿主按来源和语言决定是否允许执行。
+ *
+ * @example
+ * ```ts
+ * import type { MarkdownCodeRunRequest } from '@h-ai/ui'
+ * const example: MarkdownCodeRunRequest = { blockId: 'code-1', code: '1 + 1', language: 'javascript', sourceKind: 'code' }
+ * ```
+ */
 export interface MarkdownCodeRunRequest {
-    /** Code block id for mapping results back to the preview slot. */
+    /** 用于将运行结果写回对应预览槽的代码块 ID。 */
     blockId: string;
-    /** Raw code text. */
+    /** 原始代码文本。 */
     code: string;
-    /** Code language for runtime branching. */
+    /** 供宿主选择运行方式的代码语言。 */
     language?: string;
-    /** Current document title for preview metadata or logging. */
+    /** 用于预览元信息的当前文档标题。 */
     title?: string;
-    /** Source kind for contextual runtime decisions. */
+    /** 供宿主判断运行权限与上下文的内容来源。 */
     sourceKind: MarkdownSourceKind;
 }
+/**
+ * 宿主返回的预览内容及渲染种类；HTML 脚本必须显式授权。
+ *
+ * @example
+ * ```ts
+ * import type { MarkdownCodeRunResult } from '@h-ai/ui'
+ * const example: MarkdownCodeRunResult = { kind: 'text', content: '2', title: '计算结果', allowScripts: false }
+ * ```
+ */
 export interface MarkdownCodeRunResult {
-    /** Output kind that drives preview rendering. */
+    /** 预览渲染使用的输出种类。 */
     kind?: 'text' | 'markdown' | 'html' | 'mermaid';
-    /** Preview output content. */
+    /** 预览输出正文。 */
     content: string;
-    /** Preview title; default text is used when omitted. */
+    /** 预览标题，省略时使用默认文案。 */
     title?: string;
-    /** Optional preview description. */
+    /** 可选的预览说明。 */
     description?: string;
     /**
      * 预览 iframe 是否允许执行脚本。
@@ -50,49 +91,105 @@ export interface MarkdownCodeRunResult {
      */
     allowScripts?: boolean;
 }
+/**
+ * 选区改写菜单的稳定动作标识和已本地化文案。
+ *
+ * @example
+ * ```ts
+ * import type { MarkdownRewriteAction } from '@h-ai/ui'
+ * const example: MarkdownRewriteAction = { id: 'shorten', label: '精简' }
+ * ```
+ */
 export interface MarkdownRewriteAction {
-    /** Rewrite action id used in callbacks. */
+    /** 回调使用的改写动作标识。 */
     id: string;
-    /** User-facing label for the rewrite action. */
+    /** 已经本地化的改写动作名称。 */
     label: string;
 }
+/**
+ * 绑定动作、选中文本和当前全文的改写请求。
+ *
+ * @example
+ * ```ts
+ * import type { MarkdownRewriteRequest } from '@h-ai/ui'
+ * const example: MarkdownRewriteRequest = { actionId: 'shorten', selectedText: '需要精简的段落', content: '# 报告\n需要精简的段落' }
+ * ```
+ */
 export interface MarkdownRewriteRequest {
-    /** Rewrite action id associated with the UI action. */
+    /** 当前界面操作关联的改写动作标识。 */
     actionId: string;
-    /** The selected source text. */
+    /** 当前选中的原文。 */
     selectedText: string;
-    /** Full document content at the time of the request. */
+    /** 触发请求时的完整文档内容。 */
     content: string;
-    /** Current document title. */
+    /** 当前文档标题。 */
     title?: string;
 }
 /**
- * Legacy block-level format actions preserved for backward compatibility.
+ * 块级快捷操作种类：标题或列表。
+ *
+ * @example
+ * ```ts
+ * import type { MarkdownBlockFormatKind } from '@h-ai/ui'
+ * const example: MarkdownBlockFormatKind = 'heading'
+ * ```
  */
 export type MarkdownBlockFormatKind = 'heading' | 'bullet';
 /**
- * Rich block-style actions used by the current editor toolbar.
+ * 当前工具栏支持的具体段落和标题样式。
+ *
+ * @example
+ * ```ts
+ * import type { MarkdownBlockStyleKind } from '@h-ai/ui'
+ * const example: MarkdownBlockStyleKind = 'heading2'
+ * ```
  */
 export type MarkdownBlockStyleKind = 'paragraph' | 'heading1' | 'heading2' | 'heading3' | 'heading4' | 'orderedList' | 'bulletList';
 /**
- * Inline format actions for the editor toolbar.
- * `highlight` and `link` stay in the public union so older integrations keep compiling.
+ * 选区工具栏提供的行内格式操作。
+ * 高亮与链接同样通过选区操作回调交给宿主处理。
+ *
+ * @example
+ * ```ts
+ * import type { MarkdownInlineFormatKind } from '@h-ai/ui'
+ * const example: MarkdownInlineFormatKind = 'bold'
+ * ```
  */
 export type MarkdownInlineFormatKind = 'bold' | 'italic' | 'strike' | 'underline' | 'code' | 'highlight' | 'link';
 /**
- * Paragraph alignment actions for the editor toolbar.
+ * 选区工具栏提供的段落对齐方式。
+ *
+ * @example
+ * ```ts
+ * import type { MarkdownTextAlignKind } from '@h-ai/ui'
+ * const example: MarkdownTextAlignKind = 'center'
+ * ```
  */
 export type MarkdownTextAlignKind = 'left' | 'center' | 'right' | 'justify';
+/**
+ * 纯文本选区偏移快照，DOM 变化后用于恢复或回退定位。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const example: MarkdownSelectionSnapshot = { start: 0, end: 4, text: '示例文本' }
+ * ```
+ */
 export interface MarkdownSelectionSnapshot {
-    /** Selection start offset within the plain-text document. */
+    /** 选区在文档纯文本中的起始偏移。 */
     start: number;
-    /** Selection end offset within the plain-text document. */
+    /** 选区在文档纯文本中的结束偏移。 */
     end: number;
-    /** Selected plain text, used as a fallback when structure changes. */
+    /** 选中纯文本，用于结构变化后的回退定位。 */
     text: string;
 }
 /**
  * 颜色面板一次只会修改前景色或背景色中的一个维度。
+ *
+ * @example
+ * ```ts
+ * import type { MarkdownColorFormatRequest } from '@h-ai/ui'
+ * const example: MarkdownColorFormatRequest = { target: 'text', value: '#2563eb', selectedText: '重点' }
+ * ```
  */
 export interface MarkdownColorFormatRequest {
     /** `text` 表示文字颜色，`background` 表示文本底色。 */
@@ -104,6 +201,14 @@ export interface MarkdownColorFormatRequest {
     /** 当前工具条记住的精确选区偏移，优先用于重复文本场景的恢复。 */
     selectionSnapshot?: MarkdownSelectionSnapshot;
 }
+/**
+ * 添加、修改或移除选区链接的请求；href=null 表示移除链接。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const example: MarkdownLinkFormatRequest = { href: 'https://example.com/help', selectedText: '帮助' }
+ * ```
+ */
 export interface MarkdownLinkFormatRequest {
     /** 为空时表示移除当前链接。 */
     href: string | null;
@@ -112,41 +217,70 @@ export interface MarkdownLinkFormatRequest {
     /** 当前工具条记住的选中文本，供宿主做文本兜底。 */
     selectedText?: string;
 }
+/**
+ * 文档下载菜单动作；内置格式直接使用对应格式名，自定义动作交给宿主处理。
+ *
+ * @example
+ * ```ts
+ * import type { MarkdownToolbarDownloadAction } from '@h-ai/ui'
+ * const example: MarkdownToolbarDownloadAction = { id: 'markdown', label: 'Markdown', badgeLabel: 'MD' }
+ * ```
+ */
 export interface MarkdownToolbarDownloadAction {
-    /** Action id used to identify the download target. */
+    /** 下载动作标识。 */
     id: string;
-    /** Label shown in the download menu. */
+    /** 下载菜单显示的已本地化文案。 */
     label: string;
-    /** Optional short badge displayed beside the menu label. */
+    /** 菜单文案旁可选的短标签。 */
     badgeLabel?: string;
 }
 /**
- * Callback props are exposed to Svelte consumers, so we keep parameter checks bivariant.
- * This lets older handlers with narrower unions remain assignable while the component gains new APIs.
+ * Svelte 事件属性使用双变型参数检查，保留组件回调的推导方式。
+ * 该类型仅约束回调签名，不负责验证宿主执行权限或业务数据。
+ * @typeParam Args - 回调参数元组类型。
+ * @typeParam Return - 转换结果的数据类型。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const example: BivariantCallback<[string], void> = value => { document.body.setAttribute('data-format', value) }
+ * ```
  */
 type BivariantCallback<Args extends unknown[], Return = void> = {
     bivarianceHack: (...args: Args) => Return;
 }['bivarianceHack'];
+/**
+ * 文档编辑器的数据、预览安全策略和宿主交互回调；不在组件中实现 AI 业务请求。
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { AiDocumentEditor } from '@h-ai/ui'
+ *   import type { AiDocumentEditorProps } from '@h-ai/ui'
+ *   const props: AiDocumentEditorProps = { content: '# 报告\n正文', title: '报告', sourceKind: 'document', allowHtmlTags: false, allowUnsafeCodePreview: false }
+ * </script>
+ * <AiDocumentEditor {...props} />
+ * ```
+ */
 export interface AiDocumentEditorProps extends DataAttributes {
-    /** Markdown source content. */
+    /** Markdown 原始正文。 */
     content?: string;
-    /** Document title displayed in the header. */
+    /** 头部展示的文档标题。 */
     title?: string;
-    /** Source kind that affects rendering and interactions. */
+    /** 影响渲染与交互的内容来源。 */
     sourceKind?: MarkdownSourceKind;
-    /** Default language when sourceKind is `code`. */
+    /** sourceKind=code 时的默认语言。 */
     codeLanguage?: string;
-    /** Content font size. Numbers are interpreted as px. */
+    /** 正文字号；数字按 px 解释。 */
     fontSize?: string | number;
-    /** Custom class for the outer container. */
+    /** 外层容器类名。 */
     class?: string;
-    /** Whether to show the copy button on code blocks. */
+    /** 是否显示代码块复制按钮。 */
     showCopyButton?: boolean;
-    /** Whether to show the run button on code blocks. */
+    /** 是否显示代码块运行按钮；是否执行仍由宿主授权。 */
     showRunButton?: boolean;
-    /** Whether to show the code/preview toggle on code blocks. */
+    /** 是否显示代码/预览切换。 */
     showCodePreviewToggle?: boolean;
-    /** Whether to parse raw HTML tags through a safe allowlist. */
+    /** 是否按安全白名单解析原始 HTML。 */
     allowHtmlTags?: boolean;
     /**
      * 是否启用内置的高风险代码预览。
@@ -155,93 +289,93 @@ export interface AiDocumentEditorProps extends DataAttributes {
      * 需要宿主显式开启，或由宿主通过 `oncoderun` 自行提供受控沙箱结果。
      */
     allowUnsafeCodePreview?: boolean;
-    /** Optional helper text displayed beside language when preview toggle is enabled. */
+    /** 启用预览切换时语言标签旁的提示。 */
     codePreviewHint?: string;
-    /** Whether syntax highlighting is enabled. */
+    /** 是否启用语法高亮。 */
     enableHighlight?: boolean;
-    /** Whether soft line breaks are rendered as <br>. */
+    /** 是否将普通换行渲染为 br。 */
     breaks?: boolean;
-    /** Whether to show the left outline panel. */
+    /** 是否显示左侧目录。 */
     showOutline?: boolean;
-    /** Whether to show numbering prefixes in outline items. */
+    /** 是否显示目录编号。 */
     showOutlineNumbering?: boolean;
-    /** Whether to show the top toolbar. */
+    /** 是否显示顶部工具栏。 */
     showToolbar?: boolean;
-    /** Initial outline collapsed state. */
+    /** 目录的初始折叠状态。 */
     initialOutlineCollapsed?: boolean;
-    /** Status text shown in the header or toolbar. */
+    /** 头部或工具栏显示的状态文案。 */
     statusText?: string;
-    /** Whether a rewrite flow is in progress. */
+    /** 改写流程是否正在执行。 */
     rewritePending?: boolean;
-    /** Available rewrite actions; empty hides the menu. */
+    /** 可用改写动作，空列表隐藏菜单。 */
     rewriteActions?: MarkdownRewriteAction[];
-    /** Callback fired when the close action is clicked. */
+    /** 点击关闭时通知宿主。 */
     onclose?: () => void;
-    /** Whether the close / back action should render as disabled. */
+    /** 是否禁用关闭/返回操作。 */
     closeDisabled?: boolean;
-    /** Callback fired when the undo action is clicked. */
+    /** 点击撤销时通知宿主。 */
     onundo?: () => void;
-    /** Whether the undo button should render as disabled. */
+    /** 是否禁用撤销操作。 */
     undoDisabled?: boolean;
-    /** Callback fired when the redo action is clicked. */
+    /** 点击重做时通知宿主。 */
     onredo?: () => void;
-    /** Whether the redo button should render as disabled. */
+    /** 是否禁用重做操作。 */
     redoDisabled?: boolean;
-    /** Code run handler that returns preview results. */
+    /** 由宿主执行并返回预览结果的代码回调。 */
     oncoderun?: (request: MarkdownCodeRunRequest) => MarkdownCodeRunResult | void | Promise<MarkdownCodeRunResult | void>;
-    /** Selection rewrite handler for external processing. */
+    /** 宿主处理选区改写的回调。 */
     onrewrite?: (request: MarkdownRewriteRequest) => void | Promise<void>;
-    /** Exposes the scroll container for external synchronization. */
+    /** 向宿主暴露滚动容器以同步滚动。 */
     editorScrollHost?: HTMLDivElement | null;
-    /** Exposes the content container for editable reads. */
+    /** 向宿主暴露可编辑内容容器。 */
     previewHost?: HTMLElement | null;
-    /** Eyebrow label shown above the title. */
+    /** 标题上方的辅助标签。 */
     eyebrow?: string;
-    /** Primary header text, shown with higher priority. */
+    /** 优先显示的头部说明。 */
     metaText?: string;
-    /** Pill status text shown near the title. */
+    /** 标题附近的状态标签。 */
     saveState?: string;
-    /** Whether the document body is contenteditable. */
+    /** 正文是否允许 contenteditable 编辑。 */
     editable?: boolean;
-    /** Download menu items; defaults are used when empty. */
+    /** 下载菜单项，空列表使用内置动作。 */
     downloadActions?: MarkdownToolbarDownloadAction[];
-    /** Label for the history action. */
+    /** 历史记录操作文案。 */
     historyActionLabel?: string;
-    /** Label for the view version action. */
+    /** 查看版本操作文案。 */
     versionActionLabel?: string;
-    /** Scroll callback for syncing external state. */
+    /** 向宿主同步滚动状态的回调。 */
     ondocumentscroll?: (event: Event) => void;
-    /** Mouseup callback to sync selection state. */
+    /** 鼠标释放时同步选区的回调。 */
     onpreviewmouseup?: () => void;
-    /** Input callback for contenteditable changes. */
+    /** 可编辑正文发生输入时的回调。 */
     onpreviewinput?: (event: Event) => void;
-    /** Blur callback for committing edits. */
+    /** 失焦时提交编辑的回调。 */
     onpreviewblur?: () => void;
-    /** Callback fired when a download action is chosen. */
+    /** 选择下载动作时的回调。 */
     ondownload?: (actionId: string) => void;
-    /** Callback fired when the history action is clicked. */
+    /** 点击历史记录时的回调。 */
     onhistory?: () => void;
-    /** Custom full-document copy handler. */
+    /** 宿主自定义的整篇复制操作。 */
     oncopydocument?: () => void | Promise<void>;
-    /** Legacy block-format action handler for older heading / bullet integrations. */
+    /** 标题/列表快捷格式操作回调。 */
     onapplyblockformat?: BivariantCallback<[kind: MarkdownBlockFormatKind], void>;
-    /** Rich block-style handler for paragraph and concrete heading-level changes. */
+    /** 切换段落或具体标题级别的回调。 */
     onapplyblockstyle?: BivariantCallback<[kind: MarkdownBlockStyleKind], void>;
-    /** Inline-format action handler from the selection toolbar. */
+    /** 选区工具栏的行内格式回调。 */
     onapplyinlineformat?: BivariantCallback<[kind: MarkdownInlineFormatKind], void>;
-    /** Paragraph alignment handler from the selection toolbar. */
+    /** 选区工具栏的段落对齐回调。 */
     onapplyalignment?: (kind: MarkdownTextAlignKind) => void;
-    /** Link add / edit / remove handler from the selection toolbar. */
+    /** 选区工具栏添加、编辑或移除链接的回调。 */
     onapplylink?: BivariantCallback<[
         href: string | null,
         selectionSnapshot?: MarkdownSelectionSnapshot,
         selectedText?: string
     ], void>;
-    /** Text or background color handler from the selection toolbar. */
+    /** 选区工具栏修改文字色或背景色的回调。 */
     onapplycolor?: (request: MarkdownColorFormatRequest) => void;
-    /** Selection copy handler for custom behavior. */
+    /** 宿主自定义的选区复制操作。 */
     oncopyselection?: () => void | Promise<void>;
-    /** Selection annotation handler. */
+    /** 宿主处理选区注释的回调。 */
     onannotation?: () => void | Promise<void>;
 }
 export {};