@h-ai/ui 0.1.0-alpha.10 → 0.1.0-alpha.12

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

@@ -395,8 +395,8 @@
 
   .hai-markdown :global(.hai-md-code-block code) {
     /* ─── 基础色 ─── */
-    --hai-hl-fg: oklch(var(--nc));
-    --hai-hl-bg: transparent;
+    --hai-hl-foreground: oklch(var(--nc));
+    --hai-hl-background: transparent;
 
     /* ─── Token 颜色（DaisyUI oklch 自适应） ─── */
     --hai-hl-token-keyword: oklch(0.7 0.15 280);

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

@@ -1,5 +1,18 @@
 import { 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;
+const BROWSER_PDF_VIEWPORT_WIDTH_PX = 794;
+const BROWSER_PDF_MARGIN_MM = [14, 12, 14, 12];
+const BROWSER_PDF_CONTENT_WIDTH_MM = 210 - BROWSER_PDF_MARGIN_MM[1] - BROWSER_PDF_MARGIN_MM[3];
+const BROWSER_PDF_CONTENT_HEIGHT_MM = BROWSER_PDF_PAGE_HEIGHT_MM - BROWSER_PDF_MARGIN_MM[0] - BROWSER_PDF_MARGIN_MM[2];
+const BROWSER_PDF_PAGE_BREAK_SEARCH_RATIO = 0.12;
+const BROWSER_PDF_PAGE_BREAK_SEARCH_MAX_PX = 160;
+const BROWSER_PDF_PAGE_BREAK_SEARCH_MIN_PX = 24;
+const BROWSER_PDF_PAGE_BREAK_SAMPLE_STEP_PX = 4;
+const BROWSER_PDF_PAGE_BREAK_WHITE_THRESHOLD = 246;
+const BROWSER_PDF_PAGE_BREAK_ALPHA_THRESHOLD = 12;
+const BROWSER_PDF_PAGE_BREAK_EMPTY_ROW_MAX_INK = 1;
 /**
  * code 类型产物通常只有裸代码正文。
  * 下载和预览都通过同一份规范化逻辑包装成 fenced markdown，避免两边导出的结构不一致。
@@ -69,7 +82,7 @@ export async function downloadAiDocument(request) {
         }), `${baseName}.doc`);
         return;
     }
-    await printDocumentAsPdf(htmlToPdfTitle(exportTitle), exportHtml);
+    await downloadDocumentAsPdf(htmlToPdfFilename(exportTitle), rendered.html);
 }
 function createBuiltInDownloadAction(format) {
     switch (format) {
@@ -130,19 +143,10 @@ function escapeHtml(value) {
         .replace(/"/g, '"')
         .replace(/'/g, ''');
 }
-function buildDocumentExportHtml(title, bodyHtml) {
-    return `<!doctype html>
-<html lang="zh-CN">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>${escapeHtml(title)}</title>
-    <style>
-      :root {
+function buildDocumentExportStyles() {
+    return `
+      .${DOCUMENT_EXPORT_ROOT_CLASS} {
         color-scheme: light;
-      }
-
-      body {
         margin: 0;
         padding: 0;
         font-family:
@@ -152,60 +156,60 @@ function buildDocumentExportHtml(title, bodyHtml) {
         background: #ffffff;
       }
 
-      main {
+      .${DOCUMENT_EXPORT_ROOT_CLASS} main {
         max-width: 860px;
         margin: 0 auto;
         padding: 40px 32px 72px;
       }
 
-      h1,
-      h2,
-      h3,
-      h4,
-      h5,
-      h6 {
+      .${DOCUMENT_EXPORT_ROOT_CLASS} h1,
+      .${DOCUMENT_EXPORT_ROOT_CLASS} h2,
+      .${DOCUMENT_EXPORT_ROOT_CLASS} h3,
+      .${DOCUMENT_EXPORT_ROOT_CLASS} h4,
+      .${DOCUMENT_EXPORT_ROOT_CLASS} h5,
+      .${DOCUMENT_EXPORT_ROOT_CLASS} h6 {
         margin: 1.5em 0 0.7em;
         line-height: 1.28;
         color: #101827;
       }
 
-      h1 {
+      .${DOCUMENT_EXPORT_ROOT_CLASS} h1 {
         font-size: 30px;
         padding-bottom: 0.42em;
         border-bottom: 1px solid #dbe4f0;
       }
 
-      h2 {
+      .${DOCUMENT_EXPORT_ROOT_CLASS} h2 {
         font-size: 24px;
       }
 
-      h3 {
+      .${DOCUMENT_EXPORT_ROOT_CLASS} h3 {
         font-size: 20px;
       }
 
-      p,
-      li,
-      blockquote,
-      td,
-      th {
+      .${DOCUMENT_EXPORT_ROOT_CLASS} p,
+      .${DOCUMENT_EXPORT_ROOT_CLASS} li,
+      .${DOCUMENT_EXPORT_ROOT_CLASS} blockquote,
+      .${DOCUMENT_EXPORT_ROOT_CLASS} td,
+      .${DOCUMENT_EXPORT_ROOT_CLASS} th {
         font-size: 15px;
         line-height: 1.82;
       }
 
-      a {
+      .${DOCUMENT_EXPORT_ROOT_CLASS} a {
         color: #2259d1;
         text-decoration: none;
       }
 
-      code,
-      pre,
-      kbd {
+      .${DOCUMENT_EXPORT_ROOT_CLASS} code,
+      .${DOCUMENT_EXPORT_ROOT_CLASS} pre,
+      .${DOCUMENT_EXPORT_ROOT_CLASS} kbd {
         font-family:
           ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas,
           "Liberation Mono", monospace;
       }
 
-      pre {
+      .${DOCUMENT_EXPORT_ROOT_CLASS} pre {
         padding: 16px;
         border-radius: 18px;
         overflow: auto;
@@ -213,40 +217,40 @@ function buildDocumentExportHtml(title, bodyHtml) {
         color: #f8fafc;
       }
 
-      code {
+      .${DOCUMENT_EXPORT_ROOT_CLASS} code {
         white-space: pre-wrap;
       }
 
-      :not(pre) > code {
+      .${DOCUMENT_EXPORT_ROOT_CLASS} :not(pre) > code {
         padding: 0.18em 0.42em;
         border-radius: 7px;
         background: #eef2f8;
         color: #132238;
       }
 
-      blockquote {
+      .${DOCUMENT_EXPORT_ROOT_CLASS} blockquote {
         margin: 1.1em 0;
         padding: 0.9em 1.1em;
         border-left: 4px solid #7fa4ff;
         background: #f6f8fd;
       }
 
-      table {
+      .${DOCUMENT_EXPORT_ROOT_CLASS} table {
         width: 100%;
         border-collapse: collapse;
       }
 
-      th,
-      td {
+      .${DOCUMENT_EXPORT_ROOT_CLASS} th,
+      .${DOCUMENT_EXPORT_ROOT_CLASS} td {
         padding: 12px 14px;
         border: 1px solid #dbe4f0;
       }
 
-      thead {
+      .${DOCUMENT_EXPORT_ROOT_CLASS} thead {
         background: #f5f7fb;
       }
 
-      img {
+      .${DOCUMENT_EXPORT_ROOT_CLASS} img {
         max-width: 100%;
         height: auto;
       }
@@ -255,46 +259,216 @@ function buildDocumentExportHtml(title, bodyHtml) {
         size: auto;
         margin: 14mm 12mm;
       }
-    </style>
-  </head>
-  <body>
-    <main>
+  `;
+}
+function buildDocumentExportBody(bodyHtml) {
+    return `<main>
       ${bodyHtml}
-    </main>
+    </main>`;
+}
+function buildDocumentExportHtml(title, bodyHtml) {
+    return `<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${escapeHtml(title)}</title>
+    <style>${buildDocumentExportStyles()}</style>
+  </head>
+  <body class="${DOCUMENT_EXPORT_ROOT_CLASS}">
+    ${buildDocumentExportBody(bodyHtml)}
   </body>
 </html>`;
 }
-function htmlToPdfTitle(title) {
+function htmlToPdfFilename(title) {
     return title.endsWith('.pdf') ? title : `${title}.pdf`;
 }
-async function printDocumentAsPdf(pdfTitle, html) {
-    const iframe = document.createElement('iframe');
-    iframe.setAttribute('aria-hidden', 'true');
-    iframe.style.position = 'fixed';
-    iframe.style.right = '0';
-    iframe.style.bottom = '0';
-    iframe.style.width = '0';
-    iframe.style.height = '0';
-    iframe.style.border = '0';
-    document.body.append(iframe);
-    await new Promise((resolve) => {
-        iframe.onload = () => resolve();
-        iframe.srcdoc = html;
-    });
-    const previewWindow = iframe.contentWindow;
-    if (!previewWindow) {
-        iframe.remove();
-        return;
+function createBrowserPdfRenderHost(bodyHtml) {
+    const frame = document.createElement('iframe');
+    frame.setAttribute('aria-hidden', 'true');
+    frame.tabIndex = -1;
+    frame.style.position = 'fixed';
+    frame.style.left = '-10000px';
+    frame.style.top = '0';
+    frame.style.width = `${BROWSER_PDF_VIEWPORT_WIDTH_PX}px`;
+    frame.style.height = '1px';
+    frame.style.border = '0';
+    frame.style.opacity = '0';
+    frame.style.pointerEvents = 'none';
+    frame.style.background = '#ffffff';
+    document.body.append(frame);
+    const frameDocument = frame.contentDocument;
+    const frameWindow = frame.contentWindow;
+    if (!frameDocument || !frameWindow) {
+        frame.remove();
+        throw new Error('Failed to create PDF export iframe');
+    }
+    frameDocument.open();
+    frameDocument.write(buildDocumentExportHtml('PDF Export', bodyHtml));
+    frameDocument.close();
+    const renderRoot = frameDocument.querySelector(`.${DOCUMENT_EXPORT_ROOT_CLASS}`);
+    if (!renderRoot) {
+        frame.remove();
+        throw new Error('Failed to prepare PDF export document');
     }
-    previewWindow.document.title = pdfTitle;
-    previewWindow.focus();
-    // PDF 导出当前走浏览器打印能力，让用户在不额外引入 PDF 库的前提下使用系统“另存为 PDF”。
-    const cleanup = () => {
-        window.setTimeout(() => {
-            iframe.remove();
-        }, 240);
+    for (const image of Array.from(frameDocument.images)) {
+        image.loading = 'eager';
+        image.decoding = 'sync';
+    }
+    return {
+        cleanup: () => frame.remove(),
+        frameElement: frame,
+        frameDocument,
+        frameWindow,
+        renderRoot,
     };
-    previewWindow.addEventListener('afterprint', cleanup, { once: true });
-    previewWindow.print();
-    window.setTimeout(cleanup, 1200);
+}
+function syncBrowserPdfRenderHostSize(frameElement, renderRoot) {
+    const renderHeight = Math.max(renderRoot.scrollHeight, renderRoot.offsetHeight, renderRoot.clientHeight, 1);
+    frameElement.style.height = `${Math.ceil(renderHeight)}px`;
+}
+function waitForNextPaint(view) {
+    return new Promise((resolve) => {
+        const requestAnimationFrame = view?.requestAnimationFrame?.bind(view) ?? window.requestAnimationFrame;
+        if (typeof requestAnimationFrame !== 'function') {
+            resolve();
+            return;
+        }
+        requestAnimationFrame(() => resolve());
+    });
+}
+async function waitForBrowserPdfRenderReady(frameElement, frameDocument, frameWindow, renderRoot) {
+    await waitForNextPaint(frameWindow);
+    await waitForNextPaint(frameWindow);
+    const imageElements = Array.from(frameDocument.querySelectorAll('img'));
+    await Promise.all(imageElements.map((image) => {
+        if (image.complete) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            image.addEventListener('load', () => resolve(), { once: true });
+            image.addEventListener('error', () => resolve(), { once: true });
+        });
+    }));
+    if (typeof frameDocument.fonts?.ready?.then === 'function') {
+        await frameDocument.fonts.ready;
+    }
+    syncBrowserPdfRenderHostSize(frameElement, renderRoot);
+    await waitForNextPaint(frameWindow);
+}
+function createPagedPdfFromCanvas(JsPdfConstructor, canvas) {
+    const pdfDocument = new JsPdfConstructor({
+        unit: 'mm',
+        format: 'a4',
+        orientation: 'portrait',
+        compress: true,
+    });
+    const pageCanvas = document.createElement('canvas');
+    const pageContext = pageCanvas.getContext('2d');
+    if (!pageContext) {
+        throw new Error('Failed to prepare PDF page canvas');
+    }
+    const pixelsPerMillimeter = canvas.width / BROWSER_PDF_CONTENT_WIDTH_MM;
+    const pageHeightPx = Math.max(1, Math.floor(BROWSER_PDF_CONTENT_HEIGHT_MM * pixelsPerMillimeter));
+    const sourceContext = canvas.getContext('2d', { willReadFrequently: true });
+    for (let pageIndex = 0, sourceY = 0; sourceY < canvas.height; pageIndex += 1) {
+        const remainingHeightPx = canvas.height - sourceY;
+        const sliceHeightPx = remainingHeightPx > pageHeightPx && sourceContext
+            ? resolveCanvasPageSliceHeight(sourceContext, canvas, sourceY, pageHeightPx)
+            : Math.min(pageHeightPx, remainingHeightPx);
+        pageCanvas.width = canvas.width;
+        pageCanvas.height = sliceHeightPx;
+        pageContext.fillStyle = '#ffffff';
+        pageContext.fillRect(0, 0, pageCanvas.width, pageCanvas.height);
+        pageContext.drawImage(canvas, 0, sourceY, canvas.width, sliceHeightPx, 0, 0, canvas.width, sliceHeightPx);
+        if (pageIndex > 0) {
+            pdfDocument.addPage();
+        }
+        pdfDocument.addImage(pageCanvas.toDataURL('image/png'), 'PNG', BROWSER_PDF_MARGIN_MM[3], BROWSER_PDF_MARGIN_MM[0], BROWSER_PDF_CONTENT_WIDTH_MM, sliceHeightPx / pixelsPerMillimeter, undefined, 'FAST');
+        sourceY += sliceHeightPx;
+    }
+    return pdfDocument.output('blob');
+}
+function resolveCanvasPageSliceHeight(sourceContext, canvas, sourceY, pageHeightPx) {
+    const searchRadiusPx = Math.max(BROWSER_PDF_PAGE_BREAK_SEARCH_MIN_PX, Math.min(BROWSER_PDF_PAGE_BREAK_SEARCH_MAX_PX, Math.floor(pageHeightPx * BROWSER_PDF_PAGE_BREAK_SEARCH_RATIO)));
+    const scanStartY = Math.max(sourceY + 1, sourceY + pageHeightPx - searchRadiusPx);
+    const scanEndY = Math.min(sourceY + pageHeightPx, canvas.height);
+    const scanHeight = scanEndY - scanStartY;
+    if (scanHeight <= 0) {
+        return Math.min(pageHeightPx, canvas.height - sourceY);
+    }
+    const imageData = sourceContext.getImageData(0, scanStartY, canvas.width, scanHeight);
+    const bestBreakY = findCanvasPageBreakY(imageData, scanStartY);
+    return Math.max(1, Math.min(bestBreakY - sourceY, canvas.height - sourceY));
+}
+function findCanvasPageBreakY(imageData, scanStartY) {
+    const rowWidth = imageData.width;
+    const rowHeight = imageData.height;
+    const rowStride = rowWidth * 4;
+    let bestEmptyRowY = 0;
+    let bestInkRowY = 0;
+    let lowestInkScore = Number.POSITIVE_INFINITY;
+    for (let rowIndex = 0; rowIndex < rowHeight; rowIndex += 1) {
+        const rowInkScore = measureCanvasRowInk(imageData.data, rowIndex * rowStride, rowWidth);
+        if (rowInkScore <= BROWSER_PDF_PAGE_BREAK_EMPTY_ROW_MAX_INK) {
+            bestEmptyRowY = scanStartY + rowIndex + 1;
+        }
+        if (rowInkScore <= lowestInkScore) {
+            lowestInkScore = rowInkScore;
+            bestInkRowY = scanStartY + rowIndex + 1;
+        }
+    }
+    return bestEmptyRowY || bestInkRowY || (scanStartY + rowHeight);
+}
+function measureCanvasRowInk(pixels, rowOffset, rowWidth) {
+    let inkScore = 0;
+    for (let column = 0; column < rowWidth; column += BROWSER_PDF_PAGE_BREAK_SAMPLE_STEP_PX) {
+        const pixelOffset = rowOffset + (column * 4);
+        const alpha = pixels[pixelOffset + 3];
+        if (alpha < BROWSER_PDF_PAGE_BREAK_ALPHA_THRESHOLD) {
+            continue;
+        }
+        const red = pixels[pixelOffset];
+        const green = pixels[pixelOffset + 1];
+        const blue = pixels[pixelOffset + 2];
+        if (red < BROWSER_PDF_PAGE_BREAK_WHITE_THRESHOLD
+            || green < BROWSER_PDF_PAGE_BREAK_WHITE_THRESHOLD
+            || blue < BROWSER_PDF_PAGE_BREAK_WHITE_THRESHOLD) {
+            inkScore += 1;
+        }
+    }
+    return inkScore;
+}
+async function renderBrowserPdfCanvas(renderHost) {
+    syncBrowserPdfRenderHostSize(renderHost.frameElement, renderHost.renderRoot);
+    const { default: html2canvas } = await import('html2canvas');
+    return html2canvas(renderHost.renderRoot, {
+        backgroundColor: '#ffffff',
+        useCORS: true,
+        scale: 2,
+        logging: false,
+        width: Math.max(renderHost.renderRoot.scrollWidth, renderHost.renderRoot.clientWidth, BROWSER_PDF_VIEWPORT_WIDTH_PX),
+        height: Math.max(renderHost.renderRoot.scrollHeight, renderHost.renderRoot.clientHeight, 1),
+        windowWidth: Math.max(renderHost.renderRoot.scrollWidth, renderHost.renderRoot.clientWidth, BROWSER_PDF_VIEWPORT_WIDTH_PX),
+        windowHeight: Math.max(renderHost.renderRoot.scrollHeight, renderHost.renderRoot.clientHeight, 1),
+    });
+}
+let jsPdfModulePromise;
+async function loadJsPdf() {
+    jsPdfModulePromise ??= import('jspdf');
+    return jsPdfModulePromise;
+}
+async function downloadDocumentAsPdf(filename, bodyHtml) {
+    const renderHost = createBrowserPdfRenderHost(bodyHtml);
+    try {
+        await waitForBrowserPdfRenderReady(renderHost.frameElement, renderHost.frameDocument, renderHost.frameWindow, renderHost.renderRoot);
+        const [{ jsPDF }, canvas] = await Promise.all([
+            loadJsPdf(),
+            renderBrowserPdfCanvas(renderHost),
+        ]);
+        downloadBlob(createPagedPdfFromCanvas(jsPDF, canvas), filename);
+    }
+    finally {
+        renderHost.cleanup();
+    }
 }

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

@@ -11,6 +11,14 @@ export interface MarkdownDocumentParseOptions {
     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>. */
     breaks?: boolean;
 }

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

@@ -4,12 +4,17 @@
  * Extracts HTML, outline, and code block metadata for document-mode rendering.
  */
 import { Marked } from 'marked';
+import { createEditorMarkdownExtensions, extractPlainTextFromTokens, } from './editor-markdown-extensions.js';
 import { highlightCode, isLanguageSupported } from './highlight.js';
 /** Default parsing options for document mode. */
 const DEFAULT_OPTIONS = {
     enableHighlight: true,
     showCopyButton: true,
     showRunButton: false,
+    showCodePreviewToggle: false,
+    codeViewCodeLabel: 'Code',
+    codeViewPreviewLabel: 'Preview',
+    codePreviewHint: '',
     breaks: true,
 };
 const SAFE_LINK_HREF_REGEX = /^(?:https?:\/\/|\/|#|mailto:)/i;
@@ -82,8 +87,8 @@ function createRendererObject(options, state) {
         heading(token) {
             // depth is clamped to the valid heading range.
             const depth = Math.max(1, Math.min(6, token.depth));
-            // text is the plain heading text used for outline labels.
-            const text = token.text.trim();
+            // text 需要剥离自定义 span / 强调等 inline token，保证目录显示的是用户可见标题。
+            const text = extractPlainTextFromTokens(token.tokens).trim();
             // id is the stable anchor for outline navigation.
             const id = createHeadingId(state, text);
             state.outline.push({
@@ -121,17 +126,28 @@ function createRendererObject(options, state) {
             const copyBtn = options.showCopyButton
                 ? `<button type="button" class="hai-md-code-action hai-md-copy-btn" data-copy-code aria-label="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2" ry="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg></button>`
                 : '';
-            // runBtn exposes the run action when enabled.
-            const runBtn = options.showRunButton
+            // codePreviewToggle replaces run when enabled to provide a cleaner code/preview switch.
+            const codePreviewToggle = options.showCodePreviewToggle
+                ? `<div class="hai-md-code-view-switch" role="group" aria-label="${escapeHtml(options.codeViewPreviewLabel)}">`
+                    + `<button type="button" class="hai-md-code-view-btn" data-code-view-toggle data-code-view="code" data-code-block-id="${escapeHtml(codeBlockId)}" aria-pressed="true">${escapeHtml(options.codeViewCodeLabel)}</button>`
+                    + `<button type="button" class="hai-md-code-view-btn" data-code-view-toggle data-code-view="preview" data-code-block-id="${escapeHtml(codeBlockId)}" aria-pressed="false">${escapeHtml(options.codeViewPreviewLabel)}</button>`
+                    + `</div>`
+                : '';
+            // hint text is optional and only rendered when the toggle is present.
+            const previewHint = options.showCodePreviewToggle && options.codePreviewHint
+                ? `<span class="hai-md-code-preview-hint">${escapeHtml(options.codePreviewHint)}</span>`
+                : '';
+            // runBtn exposes the run action when enabled and no toggle is active.
+            const runBtn = options.showRunButton && !options.showCodePreviewToggle
                 ? `<button type="button" class="hai-md-code-action hai-md-run-btn" data-run-code data-code-block-id="${escapeHtml(codeBlockId)}" aria-label="Run code"><svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="currentColor"><path d="M8 5.14v14l11-7z"/></svg></button>`
                 : '';
-            // previewHost reserves the DOM slot for run previews.
-            const previewHost = options.showRunButton
+            // previewHost reserves the DOM slot for run previews or code/preview toggle mode.
+            const previewHost = options.showRunButton || options.showCodePreviewToggle
                 ? `<div class="hai-md-code-preview-slot" data-code-preview-host="${escapeHtml(codeBlockId)}"></div>`
                 : '';
-            return `<div class="hai-md-code-block" data-code-block-id="${escapeHtml(codeBlockId)}">`
+            return `<div class="hai-md-code-block" data-code-block-id="${escapeHtml(codeBlockId)}" data-code-view="code">`
                 + `<div class="hai-md-code-header">`
-                + `<div class="hai-md-code-header-main">${langLabel}</div>`
+                + `<div class="hai-md-code-header-main">${codePreviewToggle}${langLabel}${previewHint}</div>`
                 + `<div class="hai-md-code-actions">${runBtn}${copyBtn}</div>`
                 + `</div>`
                 + `<pre><code class="hai-hl${highlightLanguage ? ` language-${escapeHtml(highlightLanguage)}` : ''}">${highlighted}</code></pre>`
@@ -205,6 +221,7 @@ function createRendererObject(options, state) {
 function createMarkedInstance(options, state) {
     return new Marked({
         renderer: createRendererObject(options, state),
+        extensions: createEditorMarkdownExtensions(),
         gfm: true,
         breaks: options.breaks,
     });

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

@@ -59,13 +59,31 @@ export interface MarkdownRewriteRequest {
     title?: string;
 }
 /**
- * Block-level format actions for the editor toolbar.
+ * Legacy block-level format actions preserved for backward compatibility.
  */
 export type MarkdownBlockFormatKind = 'heading' | 'bullet';
+/**
+ * Rich block-style actions used by the current editor toolbar.
+ */
+export type MarkdownBlockStyleKind = 'paragraph' | 'heading1' | 'heading2' | 'heading3' | 'heading4';
 /**
  * Inline format actions for the editor toolbar.
+ * `highlight` and `link` stay in the public union so older integrations keep compiling.
  */
 export type MarkdownInlineFormatKind = 'bold' | 'italic' | 'strike' | 'underline' | 'code' | 'highlight' | 'link';
+/**
+ * Paragraph alignment actions for the editor toolbar.
+ */
+export type MarkdownTextAlignKind = 'left' | 'center' | 'right' | 'justify';
+/**
+ * 颜色面板一次只会修改前景色或背景色中的一个维度。
+ */
+export interface MarkdownColorFormatRequest {
+    /** `text` 表示文字颜色，`background` 表示文本底色。 */
+    target: 'text' | 'background';
+    /** 颜色值为空时表示恢复默认。 */
+    value: string | null;
+}
 export interface MarkdownToolbarDownloadAction {
     /** Action id used to identify the download target. */
     id: string;
@@ -74,6 +92,13 @@ export interface MarkdownToolbarDownloadAction {
     /** 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.
+ */
+type BivariantCallback<Args extends unknown[], Return = void> = {
+    bivarianceHack: (...args: Args) => Return;
+}['bivarianceHack'];
 export interface AiDocumentEditorProps {
     /** Markdown source content. */
     content?: string;
@@ -89,6 +114,10 @@ export interface AiDocumentEditorProps {
     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;
+    /** 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>. */
@@ -153,12 +182,21 @@ export interface AiDocumentEditorProps {
     onhistory?: () => void;
     /** Custom full-document copy handler. */
     oncopydocument?: () => void | Promise<void>;
-    /** Block-format action handler from the selection toolbar. */
-    onapplyblockformat?: (kind: MarkdownBlockFormatKind) => 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?: (kind: MarkdownInlineFormatKind) => void;
+    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?: (href: string | null) => 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 {};

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

@@ -0,0 +1,11 @@
+import type { Token, TokenizerAndRendererExtension } from 'marked';
+/**
+ * Markdown heading 提取目录时需要一个“纯文本标题”。
+ * 这里显式递归常见 inline token，保证 `<hai-span>`、链接、强调等都能回落成纯文本。
+ */
+export declare function extractPlainTextFromTokens(tokens: Token[] | undefined): string;
+/**
+ * ChatWorkspace 编辑器会把“非标准 Markdown”能力写成自定义标签，
+ * 这里把它们注册为 marked 扩展，保证普通 Markdown 和编辑器增强能力共享同一条渲染链路。
+ */
+export declare function createEditorMarkdownExtensions(): TokenizerAndRendererExtension[];