@incremark/core 0.2.6 → 0.3.0

package/README.en.md

@@ -1,15 +1,18 @@
 # @incremark/core
 
-Incremental Markdown parser core library.
+High-performance incremental Markdown parser core library, designed specifically for AI streaming output scenarios.
 
 **[🇨🇳 中文](./README.md)** | 🇺🇸 English
 
-## Features
+## Core Advantages
 
-- 🚀 **Incremental Parsing** - Only parse new content, completed blocks are never re-processed
-- 🔄 **Streaming Friendly** - Designed for AI streaming output scenarios
-- 🎯 **Smart Boundary Detection** - Accurate Markdown block boundary recognition
-- 📦 **Framework Agnostic** - Works with any frontend framework
+- 🚀 **O(n) Complexity** - Incremental parsing, each character parsed at most once
+- ⚡ **Dual-Engine Architecture** - Choice between Marked (fast) and Micromark (stable)
+- 🔄 **Stream-Friendly** - Designed for AI streaming output scenarios
+- ⌨️ **Typewriter Effect** - Built-in BlockTransformer for character-by-character display
+- 🎯 **Smart Boundary Detection** - Accurately identifies Markdown block boundaries
+- 📦 **Tree-shaking** - Only bundles Marked engine by default, load on demand
+- 🔌 **Rich Extensions** - Support for footnotes, math formulas, custom containers, HTML parsing
 
 ## Installation
 
@@ -22,7 +25,11 @@ pnpm add @incremark/core
 ```ts
 import { createIncremarkParser } from '@incremark/core'
 
-const parser = createIncremarkParser({ gfm: true })
+const parser = createIncremarkParser({
+  gfm: true,
+  math: true,
+  containers: true
+})
 
 // Simulate streaming input
 parser.append('# Hello\n')
@@ -34,6 +41,45 @@ console.log(parser.getCompletedBlocks())
 console.log(parser.getAst())
 ```
 
+## Dual-Engine Architecture
+
+### Marked Engine (Default)
+
+Fast mode, optimized for streaming scenarios:
+
+```ts
+import { createIncremarkParser } from '@incremark/core'
+
+// Uses Marked engine by default
+const parser = createIncremarkParser({ gfm: true, math: true })
+```
+
+**Features:**
+- 🚀 Ultra-fast parsing, ideal for real-time AI chat
+- 🔧 Custom extensions for footnotes, math, containers, inline HTML
+- 📦 Tree-shaking friendly, default bundle only includes Marked
+
+### Micromark Engine
+
+Stable mode, strict CommonMark compliance:
+
+```ts
+import { createIncremarkParser } from '@incremark/core'
+import { MicromarkAstBuilder } from '@incremark/core/engines/micromark'
+
+// Use Micromark engine
+const parser = createIncremarkParser({
+  astBuilder: MicromarkAstBuilder,
+  gfm: true,
+  math: true
+})
+```
+
+**Features:**
+- ✅ 100% CommonMark compatible
+- 🔌 Rich micromark/mdast plugin ecosystem
+- 🛡️ Battle-tested stability
+
 ## API
 
 ### createIncremarkParser(options)
@@ -42,10 +88,11 @@ Create a parser instance.
 
 ```ts
 interface ParserOptions {
-  gfm?: boolean              // Enable GFM
-  containers?: boolean       // Enable ::: containers
-  extensions?: Extension[]   // micromark extensions
-  mdastExtensions?: Extension[]  // mdast extensions
+  gfm?: boolean                    // Enable GFM (tables, task lists, etc.)
+  math?: boolean                   // Enable math formulas ($..$ and $$..$$)
+  containers?: boolean             // Enable ::: container syntax
+  htmlTree?: boolean               // Enable HTML structured parsing
+  astBuilder?: AstBuilderClass     // Custom AST builder (for engine switching)
 }
 ```
 
@@ -55,56 +102,118 @@ Append content, returns incremental update.
 
 ### parser.finalize()
 
-Complete parsing.
+Complete parsing, mark remaining pending content as completed.
 
 ### parser.reset()
 
-Reset state.
+Reset parser state.
 
 ### parser.render(content)
 
-Render complete Markdown at once (reset + append + finalize).
+One-time render complete Markdown (reset + append + finalize).
 
 ```ts
 const update = parser.render('# Hello World')
-console.log(update.completed) // completed blocks
+console.log(update.completed) // Completed blocks
 ```
 
-### parser.getBuffer()
+### parser.getAst()
 
-Get current buffer content.
+Get complete AST (mdast format).
 
 ### parser.getCompletedBlocks()
 
 Get completed blocks.
 
-### parser.getPendingBlocks()
+### parser.getBuffer()
 
-Get pending blocks.
+Get current buffer content.
 
-### parser.getAst()
+## BlockTransformer
 
-Get complete AST.
+Typewriter effect controller, serves as middleware between parser and renderer.
+
+### Basic Usage
+
+```ts
+import { createBlockTransformer, defaultPlugins } from '@incremark/core'
+
+const transformer = createBlockTransformer({
+  charsPerTick: 2,        // Display 2 characters per tick
+  tickInterval: 50,       // Every 50ms
+  effect: 'fade-in',      // Animation effect: none | fade-in | typing
+  plugins: defaultPlugins,
+  onChange: (displayBlocks) => {
+    render(displayBlocks)
+  }
+})
+
+// Push source blocks
+transformer.push(sourceBlocks)
+
+// Skip animation
+transformer.skip()
+
+// Reset
+transformer.reset()
+
+// Destroy
+transformer.destroy()
+```
+
+### Configuration Options
+
+```ts
+interface TransformerOptions {
+  charsPerTick?: number | [number, number]  // Characters per tick (supports random range)
+  tickInterval?: number                      // Interval in ms
+  effect?: 'none' | 'fade-in' | 'typing'    // Animation effect
+  cursor?: string                            // Cursor character (typing effect)
+  plugins?: TransformerPlugin[]              // Plugin list
+  onChange?: (blocks: DisplayBlock[]) => void
+}
+```
 
 ## Type Definitions
 
 ```ts
 interface ParsedBlock {
   id: string
-  status: 'pending' | 'stable' | 'completed'
+  status: 'pending' | 'completed'
   node: RootContent
   startOffset: number
   endOffset: number
   rawText: string
 }
+
+interface IncrementalUpdate {
+  completed: ParsedBlock[]
+  pending: ParsedBlock[]
+  ast: Root
+  definitions: DefinitionMap
+  footnoteDefinitions: FootnoteDefinitionMap
+  footnoteReferenceOrder: string[]
+}
 ```
 
+## Performance Comparison
+
+Based on benchmark tests with 38 real Markdown documents:
+
+| Comparison | Average Advantage |
+|------------|-------------------|
+| vs Streamdown | ~**6.1x faster** |
+| vs ant-design-x | ~**7.2x faster** |
+| vs markstream-vue | ~**28.3x faster** |
+
+The longer the document, the greater the advantage (O(n) vs O(n²)).
+
 ## Framework Integration
 
 - Vue: [@incremark/vue](../vue)
 - React: [@incremark/react](../react)
+- Svelte: [@incremark/svelte](../svelte)
 
 ## License
 
 MIT
-

package/dist/MarkedAstBuildter-BsjxZko_.d.ts

@@ -0,0 +1,72 @@
+import { Root, RootContent } from 'mdast';
+import { C as ContainerConfig, H as HtmlTreeExtensionOptions, B as BlockStatus, P as ParsedBlock } from './index-mZ7yCqNH.js';
+import { I as IAstBuilder, E as EngineParserOptions } from './types-C_EW5vfp.js';
+
+/**
+ * Marked AST 构建器（极速模式）
+ *
+ * 基于 marked 解析器
+ * 特点：
+ * - 速度更快
+ * - 适合流式渲染场景
+ *
+ */
+
+/**
+ * Marked AST 构建器
+ *
+ * 使用 marked 解析 Markdown，速度更快
+ * 适用于流式渲染和高性能场景
+ */
+declare class MarkedAstBuilder implements IAstBuilder {
+    private options;
+    readonly containerConfig: ContainerConfig | undefined;
+    readonly htmlTreeOptions: HtmlTreeExtensionOptions | undefined;
+    private globalLinks;
+    /** 用户传入的 marked 扩展 */
+    private readonly userExtensions;
+    /** 转换上下文（用于递归转换） */
+    private readonly transformContext;
+    constructor(options?: EngineParserOptions);
+    parse(text: string): Root;
+    /**
+     * 预处理 tokens
+     *
+     * 处理容器指令和遗留的脚注定义（从 paragraph 中提取）
+     */
+    private preprocessTokens;
+    /**
+     * 转换 tokens 为 MDAST 节点（带位置信息）
+     */
+    private transformTokensWithPosition;
+    /**
+     * 转换 tokens 为 MDAST 节点（不带位置信息）
+     */
+    private transformTokens;
+    /**
+     * 转换行内 tokens
+     */
+    private transformInline;
+    /**
+     * 解析脚注内容为 AST 节点
+     */
+    private parseFootnoteContent;
+    /**
+     * 处理 HTML 节点
+     *
+     * 使用 html-extension 的 transformHtmlNodes 来处理：
+     * - 合并被空行分割的 HTML 节点
+     * - 将 HTML 解析为 HtmlElementNode 树结构
+     */
+    private processHtmlNodes;
+    /**
+     * 将 AST 节点转换为 ParsedBlock
+     */
+    nodesToBlocks(nodes: RootContent[], startOffset: number, rawText: string, status: BlockStatus, generateBlockId: () => string): ParsedBlock[];
+}
+/**
+ * AstBuilder 别名（向后兼容）
+ */
+declare const AstBuilder: typeof MarkedAstBuilder;
+
+export { AstBuilder as A, MarkedAstBuilder as M };

package/dist/detector/index.d.ts

@@ -1,4 +1,121 @@
-export { r as createInitialContext, o as detectContainer, p as detectContainerEnd, g as detectFenceEnd, f as detectFenceStart, q as isBlockBoundary, l as isBlockquoteStart, i as isEmptyLine, T as isFootnoteContinuation, S as isFootnoteDefinitionStart, h as isHeading, m as isHtmlBlock, k as isListItemStart, n as isTableDelimiter, j as isThematicBreak, u as updateContext } from '../index-BMUkM7mT.js';
+import { c as BlockContext, C as ContainerConfig, d as ContainerMatch } from '../index-mZ7yCqNH.js';
 import 'mdast';
 import 'micromark-util-types';
 import 'mdast-util-from-markdown';
+
+/**
+ * 块类型检测与边界判断
+ *
+ * Markdown 块级元素的识别规则
+ */
+
+/**
+ * 检测行是否是代码块 fence 开始
+ */
+declare function detectFenceStart(line: string): {
+    char: string;
+    length: number;
+} | null;
+/**
+ * 检测行是否是代码块 fence 结束
+ */
+declare function detectFenceEnd(line: string, context: BlockContext): boolean;
+/**
+ * 检测是否是空行或仅包含空白字符
+ */
+declare function isEmptyLine(line: string): boolean;
+/**
+ * 检测是否是 Setext 标题下划线（=== 或 ---）
+ * @param line 当前行
+ * @param prevLine 前一行
+ * @returns 是否是 Setext 标题下划线
+ */
+declare function isSetextHeadingUnderline(line: string, prevLine?: string): boolean;
+/**
+ * 检测是否是标题行
+ */
+declare function isHeading(line: string): boolean;
+/**
+ * 检测是否是 thematic break（水平线）
+ */
+declare function isThematicBreak(line: string): boolean;
+/**
+ * 检测是否是列表项开始
+ *
+ * CommonMark 规范：列表项可以是以下形式：
+ * - `- text`（无缩进）
+ * - `1. text`（有序列表）
+ * - `    - text`（缩进4个空格，作为上一个列表项的延续）
+ *
+ * 注意：`    - text` 这种形式，虽然 `-` 后面没有空格，
+ * 但因为前面有4个空格的缩进，所以是列表项的有效形式。
+ */
+declare function isListItemStart(line: string): {
+    ordered: boolean;
+    indent: number;
+} | null;
+/**
+ * 检测是否是引用块开始
+ */
+declare function isBlockquoteStart(line: string): boolean;
+/**
+ * 检测是否是 HTML 块
+ */
+declare function isHtmlBlock(line: string): boolean;
+/**
+ * 检测表格分隔行
+ */
+declare function isTableDelimiter(line: string): boolean;
+/**
+ * 检测是否是脚注定义的起始行
+ * 格式: [^id]: content
+ *
+ * @example
+ * isFootnoteDefinitionStart('[^1]: 脚注内容') // true
+ * isFootnoteDefinitionStart('[^note]: 内容') // true
+ * isFootnoteDefinitionStart('    缩进内容')   // false
+ */
+declare function isFootnoteDefinitionStart(line: string): boolean;
+/**
+ * 检测是否是脚注定义的延续行（缩进行）
+ * 至少4个空格或1个tab
+ *
+ * @example
+ * isFootnoteContinuation('    第二行')  // true
+ * isFootnoteContinuation('\t第二行')    // true
+ * isFootnoteContinuation('  两个空格')   // false
+ */
+declare function isFootnoteContinuation(line: string): boolean;
+/**
+ * 检测容器开始或结束
+ *
+ * 支持格式：
+ * - ::: name      开始
+ * - ::: name attr 开始（带属性）
+ * - :::           结束
+ * - :::::: name   开始（更长的标记，用于嵌套）
+ */
+declare function detectContainer(line: string, config?: ContainerConfig): ContainerMatch | null;
+/**
+ * 检测容器结束
+ */
+declare function detectContainerEnd(line: string, context: BlockContext, config?: ContainerConfig): boolean;
+/**
+ * 判断两行之间是否构成块边界
+ */
+declare function isBlockBoundary(prevLine: string, currentLine: string, context: BlockContext): boolean;
+/**
+ * 创建初始上下文
+ */
+declare function createInitialContext(): BlockContext;
+/**
+ * 更新上下文（处理一行后）
+ *
+ * @param line 当前行
+ * @param context 当前上下文
+ * @param containerConfig 容器配置
+ * @returns 更新后的上下文
+ */
+declare function updateContext(line: string, context: BlockContext, containerConfig?: ContainerConfig | boolean): BlockContext;
+
+export { createInitialContext, detectContainer, detectContainerEnd, detectFenceEnd, detectFenceStart, isBlockBoundary, isBlockquoteStart, isEmptyLine, isFootnoteContinuation, isFootnoteDefinitionStart, isHeading, isHtmlBlock, isListItemStart, isSetextHeadingUnderline, isTableDelimiter, isThematicBreak, updateContext };