@incremark/core 0.1.0 → 0.1.2

package/src/parser/IncremarkParser.ts

@@ -50,7 +50,7 @@ export class IncremarkParser {
   private context: BlockContext
   private options: ParserOptions
   /** 缓存的容器配置，避免重复计算 */
-  private cachedContainerConfig: ContainerConfig | undefined | null = null
+  private readonly containerConfig: ContainerConfig | undefined
   /** 上次 append 返回的 pending blocks，用于 getAst 复用 */
   private lastPendingBlocks: ParsedBlock[] = []
 
@@ -60,8 +60,8 @@ export class IncremarkParser {
       ...options
     }
     this.context = createInitialContext()
-    // 初始化容器配置缓存
-    this.cachedContainerConfig = this.computeContainerConfig()
+    // 初始化容器配置（构造时计算一次）
+    this.containerConfig = this.computeContainerConfig()
   }
 
   private generateBlockId(): string {
@@ -74,10 +74,6 @@ export class IncremarkParser {
     return containers === true ? {} : containers
   }
 
-  private getContainerConfig(): ContainerConfig | undefined {
-    return this.cachedContainerConfig ?? undefined
-  }
-
   private parse(text: string): Root {
     const extensions: MicromarkExtension[] = []
     const mdastExtensions: MdastExtension[] = []
@@ -148,7 +144,6 @@ export class IncremarkParser {
     let stableLine = -1
     let stableContext: BlockContext = this.context
     let tempContext = { ...this.context }
-    const containerConfig = this.getContainerConfig()
 
     for (let i = this.pendingStartLine; i < this.lines.length; i++) {
       const line = this.lines[i]
@@ -156,7 +151,7 @@ export class IncremarkParser {
       const wasInContainer = tempContext.inContainer
       const wasContainerDepth = tempContext.containerDepth
 
-      tempContext = updateContext(line, tempContext, containerConfig)
+      tempContext = updateContext(line, tempContext, this.containerConfig)
 
       if (wasInFencedCode && !tempContext.inFencedCode) {
         if (i < this.lines.length - 1) {
@@ -182,7 +177,7 @@ export class IncremarkParser {
         continue
       }
 
-      const stablePoint = this.checkStability(i, containerConfig)
+      const stablePoint = this.checkStability(i)
       if (stablePoint >= 0) {
         stableLine = stablePoint
         stableContext = { ...tempContext }
@@ -192,10 +187,7 @@ export class IncremarkParser {
     return { line: stableLine, contextAtLine: stableContext }
   }
 
-  private checkStability(
-    lineIndex: number,
-    containerConfig: ContainerConfig | undefined
-  ): number {
+  private checkStability(lineIndex: number): number {
     // 第一行永远不稳定
     if (lineIndex === 0) {
       return -1
@@ -237,10 +229,10 @@ export class IncremarkParser {
       }
 
       // 新容器开始
-      if (containerConfig !== undefined) {
-        const container = detectContainer(line, containerConfig)
+      if (this.containerConfig !== undefined) {
+        const container = detectContainer(line, this.containerConfig)
         if (container && !container.isEnd) {
-          const prevContainer = detectContainer(prevLine, containerConfig)
+          const prevContainer = detectContainer(prevLine, this.containerConfig)
           if (!prevContainer || prevContainer.isEnd) {
             return lineIndex - 1
           }

package/src/transformer/BlockTransformer.ts

@@ -1,4 +1,5 @@
 import type { RootContent } from 'mdast'
+import type { AstNode } from '../types'
 import type {
   SourceBlock,
   DisplayBlock,
@@ -7,7 +8,7 @@ import type {
   TransformerPlugin,
   AnimationEffect
 } from './types'
-import { countChars as defaultCountChars, sliceAst as defaultSliceAst, type TextChunk, type AccumulatedChunks } from './utils'
+import { countChars as defaultCountChars, sliceAst as defaultSliceAst, appendToAst, type TextChunk, type AccumulatedChunks } from './utils'
 
 /**
  * Block Transformer
@@ -56,6 +57,14 @@ export class BlockTransformer<T = unknown> {
   private isPaused = false
   private chunks: TextChunk[] = []  // 累积的 chunks（用于 fade-in 动画）
   private visibilityHandler: (() => void) | null = null
+  
+  // ============ 性能优化：缓存机制 ============
+  /** 缓存的已截断 displayNode（稳定的部分，避免重复遍历） */
+  private cachedDisplayNode: RootContent | null = null
+  /** 缓存的字符数（避免重复计算） */
+  private cachedTotalChars: number | null = null
+  /** 当前缓存的进度（对应 cachedDisplayNode） */
+  private cachedProgress: number = 0
 
   constructor(options: TransformerOptions = {}) {
     this.options = {
@@ -99,7 +108,10 @@ export class BlockTransformer<T = unknown> {
     if (this.state.currentBlock) {
       const updated = blocks.find((b) => b.id === this.state.currentBlock!.id)
       if (updated && updated.node !== this.state.currentBlock.node) {
-        const oldTotal = this.countChars(this.state.currentBlock.node)
+        // 内容更新，清除缓存
+        this.clearCache()
+        
+        const oldTotal = this.cachedTotalChars ?? this.countChars(this.state.currentBlock.node)
         const newTotal = this.countChars(updated.node)
         
         // 如果字符数减少了（AST 结构变化，如 **xxx 变成 **xxx**）
@@ -125,13 +137,15 @@ export class BlockTransformer<T = unknown> {
    */
   update(block: SourceBlock<T>): void {
     if (this.state.currentBlock?.id === block.id) {
-      const oldTotal = this.countChars(this.state.currentBlock.node)
+      const oldTotal = this.cachedTotalChars ?? this.countChars(this.state.currentBlock.node)
       const newTotal = this.countChars(block.node)
 
       this.state.currentBlock = block
 
       // 如果内容增加了且之前暂停了，继续
       if (newTotal > oldTotal && !this.rafId && !this.isPaused && this.state.currentProgress >= oldTotal) {
+        // 内容变化，清除缓存
+        this.clearCache()
         this.startIfNeeded()
       }
     }
@@ -156,6 +170,7 @@ export class BlockTransformer<T = unknown> {
       pendingBlocks: []
     }
     this.chunks = []
+    this.clearCache()
 
     this.emit()
   }
@@ -172,6 +187,7 @@ export class BlockTransformer<T = unknown> {
       pendingBlocks: []
     }
     this.chunks = []
+    this.clearCache()
     this.emit()
   }
 
@@ -195,6 +211,7 @@ export class BlockTransformer<T = unknown> {
 
   /**
    * 获取用于渲染的 display blocks
+   * 优化：使用缓存的 displayNode，避免重复遍历已稳定的节点
    */
   getDisplayBlocks(): DisplayBlock<T>[] {
     const result: DisplayBlock<T>[] = []
@@ -211,22 +228,17 @@ export class BlockTransformer<T = unknown> {
 
     // 当前正在显示的 block
     if (this.state.currentBlock) {
-      const total = this.countChars(this.state.currentBlock.node)
-      // fade-in 效果：传入累积的 chunks
-      const accumulatedChunks: AccumulatedChunks | undefined = 
-        this.options.effect === 'fade-in' && this.chunks.length > 0
-          ? { stableChars: 0, chunks: this.chunks }
-          : undefined
+      // 使用缓存的字符数
+      const total = this.getTotalChars()
       
-      const displayNode = this.sliceNode(
-        this.state.currentBlock.node, 
-        this.state.currentProgress,
-        accumulatedChunks
-      )
+      // 如果进度变化了或缓存无效，更新缓存的 displayNode
+      if (this.state.currentProgress !== this.cachedProgress || !this.cachedDisplayNode) {
+        this.updateCachedDisplayNode()
+      }
 
       result.push({
         ...this.state.currentBlock,
-        displayNode: displayNode || { type: 'paragraph', children: [] },
+        displayNode: this.cachedDisplayNode || { type: 'paragraph', children: [] },
         progress: total > 0 ? this.state.currentProgress / total : 1,
         isDisplayComplete: false
       })
@@ -346,6 +358,7 @@ export class BlockTransformer<T = unknown> {
     if (!this.state.currentBlock && this.state.pendingBlocks.length > 0) {
       this.state.currentBlock = this.state.pendingBlocks.shift()!
       this.state.currentProgress = 0
+      this.clearCache() // 新 block，清除缓存
     }
 
     if (this.state.currentBlock) {
@@ -387,7 +400,8 @@ export class BlockTransformer<T = unknown> {
       return
     }
 
-    const total = this.countChars(block.node)
+    // 使用缓存的字符数，避免重复计算
+    const total = this.getTotalChars()
     const step = this.getStep()
     const prevProgress = this.state.currentProgress
     
@@ -408,12 +422,13 @@ export class BlockTransformer<T = unknown> {
     this.emit()
 
     if (this.state.currentProgress >= total) {
-      // 当前 block 完成，清空 chunks
+      // 当前 block 完成，清空 chunks 和缓存
       this.notifyComplete(block.node)
       this.state.completedBlocks.push(block)
       this.state.currentBlock = null
       this.state.currentProgress = 0
       this.chunks = []
+      this.clearCache()
       this.processNext()
     }
   }
@@ -425,12 +440,6 @@ export class BlockTransformer<T = unknown> {
     let result = ''
     let charIndex = 0
 
-    interface AstNode {
-      type: string
-      value?: string
-      children?: AstNode[]
-    }
-
     function traverse(n: AstNode): boolean {
       if (charIndex >= end) return false
 
@@ -477,6 +486,7 @@ export class BlockTransformer<T = unknown> {
       this.state.currentBlock = this.state.pendingBlocks.shift()!
       this.state.currentProgress = 0
       this.chunks = []
+      this.clearCache() // 新 block，清除缓存
       this.emit()
       // 继续运行（rAF 已经在调度中）
     } else {
@@ -537,6 +547,84 @@ export class BlockTransformer<T = unknown> {
       }
     }
   }
+
+  // ============ 缓存管理方法 ============
+
+  /**
+   * 更新缓存的 displayNode
+   * 使用真正的增量追加模式：只处理新增部分，不重复遍历已稳定的节点
+   */
+  private updateCachedDisplayNode(): void {
+    const block = this.state.currentBlock
+    if (!block) {
+      this.cachedDisplayNode = null
+      this.cachedProgress = 0
+      return
+    }
+
+    const currentProgress = this.state.currentProgress
+
+    // 如果进度减少了（内容更新导致），需要重新截断
+    if (currentProgress < this.cachedProgress) {
+      this.cachedDisplayNode = this.sliceNode(
+        block.node,
+        currentProgress,
+        this.getAccumulatedChunks()
+      )
+      this.cachedProgress = currentProgress
+      return
+    }
+
+    // 如果进度增加了，使用增量追加模式
+    if (currentProgress > this.cachedProgress && this.cachedDisplayNode) {
+      // 真正的增量追加：只处理新增部分，不重复遍历已稳定的节点
+      this.cachedDisplayNode = appendToAst(
+        this.cachedDisplayNode,
+        block.node,
+        this.cachedProgress,
+        currentProgress,
+        this.getAccumulatedChunks()
+      )
+      this.cachedProgress = currentProgress
+    } else if (!this.cachedDisplayNode) {
+      // 首次截断
+      this.cachedDisplayNode = this.sliceNode(
+        block.node,
+        currentProgress,
+        this.getAccumulatedChunks()
+      )
+      this.cachedProgress = currentProgress
+    }
+  }
+
+  /**
+   * 获取总字符数（带缓存）
+   */
+  private getTotalChars(): number {
+    if (this.cachedTotalChars === null && this.state.currentBlock) {
+      this.cachedTotalChars = this.countChars(this.state.currentBlock.node)
+    }
+    return this.cachedTotalChars ?? 0
+  }
+
+  /**
+   * 清除缓存（当 block 切换或内容更新时）
+   */
+  private clearCache(): void {
+    this.cachedDisplayNode = null
+    this.cachedTotalChars = null
+    this.cachedProgress = 0
+  }
+
+  /**
+   * 获取累积的 chunks（用于 fade-in 效果）
+   */
+  private getAccumulatedChunks(): AccumulatedChunks | undefined {
+    if (this.options.effect === 'fade-in' && this.chunks.length > 0) {
+      return { stableChars: 0, chunks: this.chunks }
+    }
+    return undefined
+  }
 }
 
 /**

package/src/transformer/types.ts

@@ -1,4 +1,5 @@
 import type { RootContent } from 'mdast'
+import type { BlockStatus } from '../types'
 
 /**
  * 源 Block 类型（来自解析器）
@@ -9,7 +10,7 @@ export interface SourceBlock<T = unknown> {
   /** AST 节点 */
   node: RootContent
   /** 块状态 */
-  status: 'pending' | 'stable' | 'completed'
+  status: BlockStatus
   /** 用户自定义元数据 */
   meta?: T
 }

package/src/transformer/utils.ts

@@ -1,4 +1,5 @@
-import type { RootContent, Text, Parent } from 'mdast'
+import type { RootContent, Text } from 'mdast'
+import type { AstNode } from '../types'
 
 /**
  * 文本块片段（用于渐入动画）
@@ -21,34 +22,28 @@ export interface TextNodeWithChunks extends Text {
 }
 
 /**
- * AST 节点的通用类型（文本节点或容器节点）
+ * 计算 AST 节点的总字符数
  */
-interface AstNode {
-  type: string
-  value?: string
-  children?: AstNode[]
+export function countChars(node: RootContent): number {
+  return countCharsInNode(node as AstNode)
 }
 
 /**
- * 计算 AST 节点的总字符数
+ * 计算单个 AST 节点的字符数（内部辅助函数）
  */
-export function countChars(node: RootContent): number {
-  let count = 0
-
-  function traverse(n: AstNode): void {
-    if (n.value && typeof n.value === 'string') {
-      count += n.value.length
-      return
-    }
-    if (n.children && Array.isArray(n.children)) {
-      for (const child of n.children) {
-        traverse(child)
-      }
+function countCharsInNode(n: AstNode): number {
+  if (n.value && typeof n.value === 'string') {
+    return n.value.length
+  }
+  if (n.children && Array.isArray(n.children)) {
+    let count = 0
+    for (const child of n.children) {
+      count += countCharsInNode(child)
     }
+    return count
   }
-
-  traverse(node as AstNode)
-  return count
+  // 其他节点（如 thematicBreak, image）算作 1 个字符
+  return 1
 }
 
 /**
@@ -71,20 +66,24 @@ interface ChunkRange {
 /**
  * 截断 AST 节点，只保留前 maxChars 个字符
  * 支持 chunks（用于渐入动画）
+ * 支持增量模式：跳过已处理的字符，只处理新增部分
  * 
  * @param node 原始节点
  * @param maxChars 最大字符数
  * @param accumulatedChunks 累积的 chunks 信息（用于渐入动画）
+ * @param skipChars 跳过前 N 个字符（已处理的部分，用于增量追加）
  * @returns 截断后的节点，如果 maxChars <= 0 返回 null
  */
 export function sliceAst(
   node: RootContent, 
   maxChars: number,
-  accumulatedChunks?: AccumulatedChunks
+  accumulatedChunks?: AccumulatedChunks,
+  skipChars: number = 0
 ): RootContent | null {
   if (maxChars <= 0) return null
+  if (skipChars >= maxChars) return null
 
-  let remaining = maxChars
+  let remaining = maxChars - skipChars  // 只处理新增部分
   let charIndex = 0
   
   // 计算 chunks 在文本中的范围
@@ -106,14 +105,23 @@ export function sliceAst(
 
     // 文本类节点：截断 value，可能添加 chunks
     if (n.value && typeof n.value === 'string') {
-      const take = Math.min(n.value.length, remaining)
+      const nodeStart = charIndex
+      const nodeEnd = charIndex + n.value.length
+      
+      // 如果整个节点都在 skipChars 之前，跳过
+      if (nodeEnd <= skipChars) {
+        charIndex = nodeEnd
+        return null
+      }
+      
+      // 如果节点跨越 skipChars，需要从 skipChars 位置开始取
+      const skipInNode = Math.max(0, skipChars - nodeStart)
+      const take = Math.min(n.value.length - skipInNode, remaining)
       remaining -= take
       if (take === 0) return null
 
-      const slicedValue = n.value.slice(0, take)
-      const nodeStart = charIndex
-      const nodeEnd = charIndex + take
-      charIndex += take
+      const slicedValue = n.value.slice(skipInNode, skipInNode + take)
+      charIndex = nodeEnd
       
       const result: AstNode & { stableLength?: number; chunks?: TextChunk[] } = { 
         ...n, 
@@ -126,14 +134,14 @@ export function sliceAst(
         let firstChunkLocalStart = take  // 第一个 chunk 在节点中的起始位置
         
         for (const range of chunkRanges) {
-          // 计算 chunk 与当前节点的交集
-          const overlapStart = Math.max(range.start, nodeStart)
-          const overlapEnd = Math.min(range.end, nodeEnd)
+          // 计算 chunk 与当前节点的交集（考虑 skipChars）
+          const overlapStart = Math.max(range.start, nodeStart + skipInNode)
+          const overlapEnd = Math.min(range.end, nodeStart + skipInNode + take)
           
           if (overlapStart < overlapEnd) {
-            // 有交集，提取对应的文本
-            const localStart = overlapStart - nodeStart
-            const localEnd = overlapEnd - nodeStart
+            // 有交集，提取对应的文本（相对于 slicedValue）
+            const localStart = overlapStart - (nodeStart + skipInNode)
+            const localEnd = overlapEnd - (nodeStart + skipInNode)
             const chunkText = slicedValue.slice(localStart, localEnd)
             
             if (chunkText.length > 0) {
@@ -161,13 +169,36 @@ export function sliceAst(
     // 容器节点：递归处理 children
     if (n.children && Array.isArray(n.children)) {
       const newChildren: AstNode[] = []
+      let childCharIndex = charIndex
+      
       for (const child of n.children) {
         if (remaining <= 0) break
+        
+        // 计算子节点的字符范围
+        const childChars = countCharsInNode(child as AstNode)
+        const childStart = childCharIndex
+        const childEnd = childCharIndex + childChars
+        
+        // 如果子节点完全在 skipChars 之前，跳过
+        if (childEnd <= skipChars) {
+          childCharIndex = childEnd
+          continue
+        }
+        
+        // 如果子节点跨越 skipChars，需要处理
+        // 临时更新 charIndex 以便子节点正确处理 skipChars
+        const savedCharIndex = charIndex
+        charIndex = childStart
         const processed = process(child)
+        charIndex = savedCharIndex
+        
         if (processed) {
           newChildren.push(processed)
         }
+        
+        childCharIndex = childEnd
       }
+      
       if (newChildren.length === 0) {
         return null
       }
@@ -183,9 +214,151 @@ export function sliceAst(
   return process(node as AstNode) as RootContent | null
 }
 
+/**
+ * 增量追加：将新增的字符范围追加到现有的 displayNode
+ * 这是真正的增量追加实现，只处理新增部分，不重复遍历已稳定的节点
+ * 
+ * @param baseNode 已截断的基础节点（稳定的部分）
+ * @param sourceNode 原始完整节点
+ * @param startChars 起始字符位置（已处理的字符数）
+ * @param endChars 结束字符位置（新的进度）
+ * @param accumulatedChunks 累积的 chunks 信息（用于渐入动画）
+ * @returns 追加后的完整节点
+ */
+export function appendToAst(
+  baseNode: RootContent,
+  sourceNode: RootContent,
+  startChars: number,
+  endChars: number,
+  accumulatedChunks?: AccumulatedChunks
+): RootContent {
+  // 如果新增字符数为 0，直接返回 baseNode
+  if (endChars <= startChars) {
+    return baseNode
+  }
+
+  // 从 sourceNode 中提取新增的字符范围（跳过已处理的部分）
+  const newChars = endChars - startChars
+  const newPart = sliceAst(sourceNode, endChars, accumulatedChunks, startChars)
+  
+  // 如果提取失败，返回 baseNode
+  if (!newPart) {
+    return baseNode
+  }
+
+  // 将新增部分合并到 baseNode
+  return mergeAstNodes(baseNode, newPart)
+}
+
+/**
+ * 合并两个 AST 节点
+ * 将 newPart 追加到 baseNode 的最后一个可追加节点中
+ */
+function mergeAstNodes(baseNode: RootContent, newPart: RootContent): RootContent {
+  // 如果两个节点类型不同，无法合并，返回 baseNode
+  if (baseNode.type !== newPart.type) {
+    return baseNode
+  }
+
+  const base = baseNode as AstNode
+  const part = newPart as AstNode
+
+  // 如果是文本节点，合并文本和 chunks
+  if (base.value && typeof base.value === 'string' && part.value && typeof part.value === 'string') {
+    const baseChunks = (base as TextNodeWithChunks).chunks || []
+    const partChunks = (part as TextNodeWithChunks).chunks || []
+    
+    // 合并所有 chunks：累积所有读取的 chunks
+    // chunks 数组包含每次读取的新文本片段，它们 join 到一起就是 value
+    const mergedChunks = [...baseChunks, ...partChunks]
+    
+    // 根据设计：value = stableText + chunks[0].text + chunks[1].text + ... + chunks[n].text
+    // base.value = baseStableText + baseChunks[0].text + ... + baseChunks[n].text
+    // part.value = partStableText + partChunks[0].text + ... + partChunks[m].text
+    // 合并后：value = base.value + part.value（完整文本）
+    const mergedValue = base.value + part.value
+    
+    // stableLength 是稳定部分的长度（不需要动画的部分）
+    // base 的稳定部分保持不变，base 的 chunks 和 part 的 chunks 都需要动画
+    const baseStableLength = (base as TextNodeWithChunks).stableLength ?? 0
+    
+    // 验证：mergedValue 应该等于 baseStableText + 所有 chunks 的文本
+    // baseStableText = base.value.slice(0, baseStableLength)
+    // 所有 chunks 的文本 = baseChunks + partChunks 的文本
+    const result = {
+      ...base,
+      value: mergedValue,
+      stableLength: mergedChunks.length > 0 ? baseStableLength : undefined,
+      chunks: mergedChunks.length > 0 ? mergedChunks : undefined
+    } as TextNodeWithChunks
+    
+    return result as RootContent
+  }
+
+  // 如果是容器节点，合并 children
+  if (base.children && Array.isArray(base.children) && part.children && Array.isArray(part.children)) {
+    // 如果 base 的最后一个子节点和 part 的第一个子节点类型相同，尝试合并
+    if (base.children.length > 0 && part.children.length > 0) {
+      const lastBaseChild = base.children[base.children.length - 1]
+      const firstPartChild = part.children[0]
+      
+      if (lastBaseChild.type === firstPartChild.type) {
+        // 尝试合并最后一个和第一个子节点
+        const merged = mergeAstNodes(lastBaseChild as RootContent, firstPartChild as RootContent)
+        return {
+          ...base,
+          children: [
+            ...base.children.slice(0, -1),
+            merged as AstNode,
+            ...part.children.slice(1)
+          ]
+        } as RootContent
+      }
+    }
+
+    // 否则直接追加所有子节点
+    return {
+      ...base,
+      children: [...base.children, ...part.children]
+    } as RootContent
+  }
+
+  // 其他情况，返回 baseNode（无法合并）
+  return baseNode
+}
+
 /**
  * 深拷贝 AST 节点
+ * 使用递归浅拷贝实现，比 JSON.parse/stringify 更高效
+ * 且保持对象结构完整性
  */
 export function cloneNode<T extends RootContent>(node: T): T {
-  return JSON.parse(JSON.stringify(node))
+  // 优先使用 structuredClone（Node 17+ / 现代浏览器）
+  if (typeof structuredClone === 'function') {
+    return structuredClone(node)
+  }
+  
+  // 回退到递归拷贝
+  return deepClone(node) as T
+}
+
+/**
+ * 递归深拷贝对象
+ */
+function deepClone<T>(obj: T): T {
+  if (obj === null || typeof obj !== 'object') {
+    return obj
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map(item => deepClone(item)) as T
+  }
+
+  const cloned = {} as T
+  for (const key in obj) {
+    if (Object.prototype.hasOwnProperty.call(obj, key)) {
+      cloned[key] = deepClone(obj[key])
+    }
+  }
+  return cloned
 }

package/src/types/index.ts

@@ -10,6 +10,17 @@ export type BlockStatus =
   | 'stable'     // 可能完整，但下一个 chunk 可能会改变它
   | 'completed'  // 确认完成，不会再改变
 
+/**
+ * AST 节点的通用接口（用于遍历）
+ * 统一定义，避免各模块重复声明
+ */
+export interface AstNode {
+  type: string
+  value?: string
+  children?: AstNode[]
+  [key: string]: unknown
+}
+
 /**
  * 解析出的块
  */