@incremark/core 0.0.4 → 0.0.5

package/README.md

@@ -8,6 +8,7 @@
 
 - 🚀 **增量解析** - 只解析新增内容，已完成的块不再重复处理
 - 🔄 **流式友好** - 专为 AI 流式输出场景设计
+- ⌨️ **打字机效果** - 内置 BlockTransformer 实现逐字符显示
 - 🎯 **智能边界检测** - 准确识别 Markdown 块边界
 - 📦 **框架无关** - 可与任何前端框架配合使用
 
@@ -86,6 +87,70 @@ console.log(update.completed) // 已完成的块
 
 获取完整 AST。
 
+## BlockTransformer
+
+打字机效果控制器，作为解析器和渲染器之间的中间层。
+
+### 基本用法
+
+```ts
+import { createBlockTransformer, defaultPlugins } from '@incremark/core'
+
+const transformer = createBlockTransformer({
+  charsPerTick: 2,      // 每次显示 2 个字符
+  tickInterval: 50,     // 每 50ms 显示一次
+  plugins: defaultPlugins,
+  onChange: (displayBlocks) => {
+    // 更新 UI
+    render(displayBlocks)
+  }
+})
+
+// 推送源 blocks
+transformer.push(sourceBlocks)
+
+// 跳过动画
+transformer.skip()
+
+// 重置
+transformer.reset()
+
+// 销毁
+transformer.destroy()
+```
+
+### 配置选项
+
+```ts
+interface TransformerOptions {
+  charsPerTick?: number       // 每次显示的字符数（默认：2）
+  tickInterval?: number       // 显示间隔 ms（默认：50）
+  plugins?: TransformerPlugin[] // 插件列表
+  onChange?: (blocks: DisplayBlock[]) => void
+}
+```
+
+### 插件系统
+
+```ts
+import {
+  defaultPlugins,  // 默认插件（图片、分隔线立即显示）
+  allPlugins,      // 完整插件（代码块等整体显示）
+  codeBlockPlugin,
+  mermaidPlugin,
+  imagePlugin,
+  mathPlugin,
+  thematicBreakPlugin,
+  createPlugin
+} from '@incremark/core'
+
+// 自定义插件
+const myPlugin = createPlugin('my-plugin', 
+  (node) => node.type === 'myType',
+  { countChars: () => 1 }
+)
+```
+
 ## 类型定义
 
 ```ts
@@ -97,6 +162,23 @@ interface ParsedBlock {
   endOffset: number
   rawText: string
 }
+
+interface SourceBlock {
+  id: string
+  node: RootContent
+  status: 'pending' | 'stable' | 'completed'
+  meta?: unknown
+}
+
+interface DisplayBlock {
+  id: string
+  sourceNode: RootContent
+  displayNode: RootContent
+  displayedChars: number
+  totalChars: number
+  isDisplayComplete: boolean
+  meta?: unknown
+}
 ```
 
 ## 与框架集成
@@ -107,4 +189,3 @@ interface ParsedBlock {
 ## License
 
 MIT
-

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { P as ParserOptions, I as IncrementalUpdate, a as ParsedBlock, b as ParserState } from './index-i_qABRHQ.js';
 export { c as BlockContext, B as BlockStatus, e as BlockTypeInfo, C as ContainerConfig, d as ContainerMatch, r as createInitialContext, o as detectContainer, p as detectContainerEnd, g as detectFenceEnd, f as detectFenceStart, q as isBlockBoundary, l as isBlockquoteStart, i as isEmptyLine, h as isHeading, m as isHtmlBlock, k as isListItemStart, n as isTableDelimiter, j as isThematicBreak, u as updateContext } from './index-i_qABRHQ.js';
-import { Root } from 'mdast';
+import { Root, RootContent } from 'mdast';
 export { Root, RootContent } from 'mdast';
 export { calculateLineOffset, generateId, joinLines, resetIdCounter, splitLines } from './utils/index.js';
 import 'micromark-util-types';
@@ -92,4 +92,293 @@ declare class IncremarkParser {
  */
 declare function createIncremarkParser(options?: ParserOptions): IncremarkParser;
 
-export { IncremarkParser, IncrementalUpdate, ParsedBlock, ParserOptions, ParserState, createIncremarkParser };
+/**
+ * 源 Block 类型（来自解析器）
+ */
+interface SourceBlock<T = unknown> {
+    /** 唯一标识 */
+    id: string;
+    /** AST 节点 */
+    node: RootContent;
+    /** 块状态 */
+    status: 'pending' | 'stable' | 'completed';
+    /** 用户自定义元数据 */
+    meta?: T;
+}
+/**
+ * 显示用的 Block（转换后）
+ */
+interface DisplayBlock<T = unknown> extends SourceBlock<T> {
+    /** 用于显示的 AST 节点（可能是截断的） */
+    displayNode: RootContent;
+    /** 显示进度 0-1 */
+    progress: number;
+    /** 是否已完成显示 */
+    isDisplayComplete: boolean;
+}
+/**
+ * 动画效果类型
+ * - 'none': 无动画效果
+ * - 'typing': 打字机光标效果（需配合 CSS）
+ */
+type AnimationEffect = 'none' | 'typing';
+/**
+ * Transformer 插件
+ */
+interface TransformerPlugin {
+    /** 插件名称 */
+    name: string;
+    /**
+     * 判断是否处理此节点
+     * 返回 true 表示这个插件要处理此节点
+     */
+    match?: (node: RootContent) => boolean;
+    /**
+     * 自定义字符数计算
+     * 返回 undefined 则使用默认逻辑
+     * 返回 0 表示立即显示（不参与逐字符效果）
+     */
+    countChars?: (node: RootContent) => number | undefined;
+    /**
+     * 自定义截断逻辑
+     * @param node 原始节点
+     * @param displayedChars 当前应显示的字符数
+     * @param totalChars 该节点的总字符数
+     * @returns 截断后的节点，null 表示不显示
+     */
+    sliceNode?: (node: RootContent, displayedChars: number, totalChars: number) => RootContent | null;
+    /**
+     * 节点显示完成时的回调
+     */
+    onComplete?: (node: RootContent) => void;
+}
+/**
+ * Transformer 配置选项
+ */
+interface TransformerOptions {
+    /**
+     * 每 tick 增加的字符数
+     * - number: 固定步长（默认 1）
+     * - [min, max]: 随机步长区间（更自然的打字效果）
+     */
+    charsPerTick?: number | [number, number];
+    /** tick 间隔 (ms)，默认 20 */
+    tickInterval?: number;
+    /** 动画效果，默认 'none' */
+    effect?: AnimationEffect;
+    /** 插件列表 */
+    plugins?: TransformerPlugin[];
+    /** 状态变化回调 */
+    onChange?: (displayBlocks: DisplayBlock[]) => void;
+    /**
+     * 是否在页面不可见时自动暂停
+     * 默认 true，节省资源
+     */
+    pauseOnHidden?: boolean;
+}
+/**
+ * Transformer 内部状态
+ */
+interface TransformerState<T = unknown> {
+    /** 已完成显示的 blocks */
+    completedBlocks: SourceBlock<T>[];
+    /** 当前正在显示的 block */
+    currentBlock: SourceBlock<T> | null;
+    /** 当前 block 已显示的字符数 */
+    currentProgress: number;
+    /** 等待显示的 blocks */
+    pendingBlocks: SourceBlock<T>[];
+}
+
+/**
+ * Block Transformer
+ *
+ * 用于控制 blocks 的逐步显示（打字机效果）
+ * 作为解析器和渲染器之间的中间层
+ *
+ * 特性：
+ * - 使用 requestAnimationFrame 实现流畅动画
+ * - 支持随机步长，模拟真实打字效果
+ * - 支持 typing 动画效果
+ * - 页面不可见时自动暂停，节省资源
+ * - 插件系统支持自定义节点处理
+ *
+ * @example
+ * ```typescript
+ * const transformer = new BlockTransformer({
+ *   charsPerTick: [1, 3],  // 随机 1-3 个字符
+ *   tickInterval: 30,
+ *   effect: 'typing',
+ *   onChange: (displayBlocks) => {
+ *     // 更新 UI
+ *   }
+ * })
+ *
+ * // 推入新 blocks
+ * transformer.push(blocks)
+ *
+ * // 获取当前显示状态
+ * const displayBlocks = transformer.getDisplayBlocks()
+ * ```
+ */
+declare class BlockTransformer<T = unknown> {
+    private state;
+    private options;
+    private rafId;
+    private lastTickTime;
+    private isRunning;
+    private isPaused;
+    private visibilityHandler;
+    constructor(options?: TransformerOptions);
+    /**
+     * 推入新的 blocks
+     * 会自动过滤已存在的 blocks
+     */
+    push(blocks: SourceBlock<T>[]): void;
+    /**
+     * 更新指定 block（用于 pending block 内容增加时）
+     */
+    update(block: SourceBlock<T>): void;
+    /**
+     * 跳过所有动画，直接显示全部内容
+     */
+    skip(): void;
+    /**
+     * 重置状态
+     */
+    reset(): void;
+    /**
+     * 暂停动画
+     */
+    pause(): void;
+    /**
+     * 恢复动画
+     */
+    resume(): void;
+    /**
+     * 获取用于渲染的 display blocks
+     */
+    getDisplayBlocks(): DisplayBlock<T>[];
+    /**
+     * 是否正在处理中
+     */
+    isProcessing(): boolean;
+    /**
+     * 是否已暂停
+     */
+    isPausedState(): boolean;
+    /**
+     * 获取内部状态（用于调试）
+     */
+    getState(): Readonly<TransformerState<T>>;
+    /**
+     * 动态更新配置
+     */
+    setOptions(options: Partial<Pick<TransformerOptions, 'charsPerTick' | 'tickInterval' | 'effect' | 'pauseOnHidden'>>): void;
+    /**
+     * 获取当前配置
+     */
+    getOptions(): {
+        charsPerTick: number | [number, number];
+        tickInterval: number;
+        effect: AnimationEffect;
+    };
+    /**
+     * 获取当前动画效果
+     */
+    getEffect(): AnimationEffect;
+    /**
+     * 销毁，清理资源
+     */
+    destroy(): void;
+    private getAllBlockIds;
+    private setupVisibilityHandler;
+    private removeVisibilityHandler;
+    private startIfNeeded;
+    private scheduleNextFrame;
+    private animationFrame;
+    private tick;
+    private getStep;
+    private processNext;
+    private cancelRaf;
+    private stop;
+    private emit;
+    private countChars;
+    private sliceNode;
+    private notifyComplete;
+}
+/**
+ * 创建 BlockTransformer 实例的工厂函数
+ */
+declare function createBlockTransformer<T = unknown>(options?: TransformerOptions): BlockTransformer<T>;
+
+/**
+ * 计算 AST 节点的总字符数
+ */
+declare function countChars(node: RootContent): number;
+/**
+ * 截断 AST 节点，只保留前 maxChars 个字符
+ *
+ * @param node 原始节点
+ * @param maxChars 最大字符数
+ * @returns 截断后的节点，如果 maxChars <= 0 返回 null
+ */
+declare function sliceAst(node: RootContent, maxChars: number): RootContent | null;
+/**
+ * 深拷贝 AST 节点
+ */
+declare function cloneNode<T extends RootContent>(node: T): T;
+
+/**
+ * 代码块插件：整体出现，不逐字符显示
+ *
+ * 注意：默认不启用，代码块默认参与打字机效果
+ * 如需整体显示代码块，可手动添加此插件
+ */
+declare const codeBlockPlugin: TransformerPlugin;
+/**
+ * Mermaid 图表插件：整体出现
+ *
+ * 注意：默认不启用，mermaid 默认参与打字机效果
+ * 如需整体显示 mermaid，可手动添加此插件
+ */
+declare const mermaidPlugin: TransformerPlugin;
+/**
+ * 图片插件：立即显示（不参与打字机效果）
+ * 图片没有文本内容，应立即显示
+ */
+declare const imagePlugin: TransformerPlugin;
+/**
+ * 数学公式插件：整体出现
+ *
+ * 注意：默认不启用，数学公式默认参与打字机效果
+ * 如需整体显示公式，可手动添加此插件
+ */
+declare const mathPlugin: TransformerPlugin;
+/**
+ * 分割线插件：立即显示
+ * 分隔线没有文本内容，应立即显示
+ */
+declare const thematicBreakPlugin: TransformerPlugin;
+/**
+ * 默认插件集合
+ *
+ * 只包含确实需要特殊处理的节点：
+ * - 图片：无文本内容，立即显示
+ * - 分隔线：无文本内容，立即显示
+ *
+ * 代码块、mermaid、数学公式默认参与打字机效果
+ * 如需整体显示，可手动添加对应插件
+ */
+declare const defaultPlugins: TransformerPlugin[];
+/**
+ * 完整插件集合（所有特殊节点整体显示）
+ * 包含代码块、mermaid、数学公式等的整体显示
+ */
+declare const allPlugins: TransformerPlugin[];
+/**
+ * 创建自定义插件的辅助函数
+ */
+declare function createPlugin(name: string, matcher: (node: RootContent) => boolean, options?: Partial<Omit<TransformerPlugin, 'name' | 'match'>>): TransformerPlugin;
+
+export { type AnimationEffect, BlockTransformer, type DisplayBlock, IncremarkParser, IncrementalUpdate, ParsedBlock, ParserOptions, ParserState, type SourceBlock, type TransformerOptions, type TransformerPlugin, type TransformerState, allPlugins, cloneNode, codeBlockPlugin, countChars, createBlockTransformer, createIncremarkParser, createPlugin, defaultPlugins, imagePlugin, mathPlugin, mermaidPlugin, sliceAst, thematicBreakPlugin };