@incremark/react 0.0.4 → 0.1.0

package/README.md

@@ -7,6 +7,7 @@ Incremark 的 React 18+ 集成库。
 ## 特性
 
 - 📦 **开箱即用** - 提供 `useIncremark` hook 和 `<Incremark>` 组件
+- ⌨️ **打字机效果** - 内置 `useBlockTransformer` 实现逐字符显示
 - 🎨 **可定制** - 支持自定义渲染组件
 - ⚡ **高性能** - 利用 React 的 reconciliation 机制
 - 🔧 **DevTools** - 内置开发者工具
@@ -71,11 +72,96 @@ function App() {
 | `blocks` | `Block[]` | 所有块 |
 | `completedBlocks` | `Block[]` | 已完成块 |
 | `pendingBlocks` | `Block[]` | 待处理块 |
+| `isLoading` | `boolean` | 是否正在加载 |
 | `append` | `Function` | 追加内容 |
 | `finalize` | `Function` | 完成解析 |
 | `reset` | `Function` | 重置状态 |
 | `render` | `Function` | 一次性渲染（reset + append + finalize） |
 
+### useBlockTransformer(sourceBlocks, options)
+
+打字机效果 hook。作为解析器和渲染器之间的中间层，控制内容的逐步显示。
+
+**参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `sourceBlocks` | `SourceBlock[]` | 源 blocks（通常来自 `completedBlocks`） |
+| `options.charsPerTick` | `number` | 每次显示的字符数（默认：2） |
+| `options.tickInterval` | `number` | 每次显示的间隔时间 ms（默认：50） |
+| `options.plugins` | `TransformerPlugin[]` | 插件列表（用于特殊块的处理） |
+
+**返回值：**
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `displayBlocks` | `DisplayBlock[]` | 用于渲染的 blocks |
+| `isProcessing` | `boolean` | 是否正在处理中 |
+| `skip` | `Function` | 跳过动画，立即显示全部内容 |
+| `reset` | `Function` | 重置状态 |
+| `setOptions` | `Function` | 动态更新配置 |
+
+**使用示例：**
+
+```tsx
+import { useMemo, useState, useEffect } from 'react'
+import { useIncremark, useBlockTransformer, Incremark, defaultPlugins } from '@incremark/react'
+
+function App() {
+  const { completedBlocks, append, finalize, reset: resetParser } = useIncremark()
+  
+  // 配置打字机速度
+  const [typewriterSpeed, setTypewriterSpeed] = useState(2)
+  const [typewriterInterval, setTypewriterInterval] = useState(50)
+
+  // 转换为 SourceBlock 格式
+  const sourceBlocks = useMemo(() => 
+    completedBlocks.map(block => ({
+      id: block.id,
+      node: block.node,
+      status: block.status
+    })),
+    [completedBlocks]
+  )
+
+  // 使用 BlockTransformer
+  const { 
+    displayBlocks, 
+    isProcessing, 
+    skip, 
+    reset: resetTransformer,
+    setOptions 
+  } = useBlockTransformer(sourceBlocks, {
+    charsPerTick: typewriterSpeed,
+    tickInterval: typewriterInterval,
+    plugins: defaultPlugins
+  })
+
+  // 监听配置变化
+  useEffect(() => {
+    setOptions({ charsPerTick: typewriterSpeed, tickInterval: typewriterInterval })
+  }, [typewriterSpeed, typewriterInterval, setOptions])
+
+  // 转换为渲染格式
+  const renderBlocks = useMemo(() => 
+    displayBlocks.map(db => ({
+      ...db,
+      stableId: db.id,
+      node: db.displayNode,
+      status: db.isDisplayComplete ? 'completed' : 'pending'
+    })),
+    [displayBlocks]
+  )
+
+  return (
+    <div>
+      <Incremark blocks={renderBlocks} />
+      {isProcessing && <button onClick={skip}>跳过</button>}
+    </div>
+  )
+}
+```
+
 ### useDevTools(incremark)
 
 启用 DevTools。
@@ -93,9 +179,18 @@ useDevTools(incremark)
 <Incremark 
   blocks={blocks}
   components={{ heading: MyHeading }}
+  showBlockStatus={true}
 />
 ```
 
+**Props：**
+
+| Prop | 类型 | 说明 |
+|------|------|------|
+| `blocks` | `Block[]` | 要渲染的 blocks |
+| `components` | `object` | 自定义组件映射 |
+| `showBlockStatus` | `boolean` | 是否显示块状态（pending/completed） |
+
 ## 自定义组件
 
 ```tsx
@@ -114,6 +209,44 @@ function App() {
 }
 ```
 
+## 插件系统
+
+BlockTransformer 支持插件来处理特殊类型的块：
+
+```tsx
+import { 
+  defaultPlugins,
+  codeBlockPlugin,
+  imagePlugin,
+  mermaidPlugin,
+  mathPlugin,
+  thematicBreakPlugin,
+  createPlugin
+} from '@incremark/react'
+
+// 使用默认插件集
+const { displayBlocks } = useBlockTransformer(sourceBlocks, {
+  plugins: defaultPlugins
+})
+
+// 或自定义插件
+const myPlugin = createPlugin({
+  name: 'my-plugin',
+  match: (node) => node.type === 'myType',
+  transform: (node) => ({ displayNode: node, isComplete: true })
+})
+```
+
+**内置插件：**
+
+| 插件 | 说明 |
+|------|------|
+| `codeBlockPlugin` | 代码块整体显示 |
+| `imagePlugin` | 图片整体显示 |
+| `mermaidPlugin` | Mermaid 图表整体显示 |
+| `mathPlugin` | 数学公式整体显示 |
+| `thematicBreakPlugin` | 分隔线整体显示 |
+
 ## 与 React Query 集成
 
 ```tsx
@@ -143,7 +276,61 @@ function StreamingContent() {
 }
 ```
 
+## AutoScrollContainer
+
+自动滚动容器组件，适用于流式内容场景：
+
+```tsx
+import { useRef, useState } from 'react'
+import { AutoScrollContainer, Incremark, type AutoScrollContainerRef } from '@incremark/react'
+
+function App() {
+  const scrollRef = useRef<AutoScrollContainerRef>(null)
+  const [autoScrollEnabled, setAutoScrollEnabled] = useState(true)
+
+  return (
+    <div>
+      <AutoScrollContainer 
+        ref={scrollRef} 
+        enabled={autoScrollEnabled}
+        threshold={50}
+        behavior="smooth"
+      >
+        <Incremark blocks={blocks} />
+      </AutoScrollContainer>
+      
+      {/* 显示滚动状态 */}
+      {scrollRef.current?.isUserScrolledUp() && (
+        <span>用户已暂停自动滚动</span>
+      )}
+      
+      {/* 强制滚动到底部 */}
+      <button onClick={() => scrollRef.current?.scrollToBottom()}>
+        滚动到底部
+      </button>
+    </div>
+  )
+}
+```
+
+**Props：**
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `enabled` | `boolean` | `true` | 是否启用自动滚动 |
+| `threshold` | `number` | `50` | 触发自动滚动的底部阈值（像素） |
+| `behavior` | `ScrollBehavior` | `'instant'` | 滚动行为 |
+| `className` | `string` | - | 容器类名 |
+| `style` | `CSSProperties` | - | 容器样式 |
+
+**Ref 方法（通过 useRef）：**
+
+| 方法 | 说明 |
+|------|------|
+| `scrollToBottom()` | 强制滚动到底部 |
+| `isUserScrolledUp()` | 返回用户是否手动向上滚动了 |
+| `container` | 容器 DOM 元素引用 |
+
 ## License
 
 MIT
-

package/dist/index.d.ts

@@ -1,32 +1,85 @@
-import { ParserOptions, ParsedBlock, Root, IncrementalUpdate, IncremarkParser, RootContent } from '@incremark/core';
-export { IncrementalUpdate, ParsedBlock, ParserOptions, Root, RootContent } from '@incremark/core';
+import { ParserOptions, AnimationEffect, TransformerPlugin, ParsedBlock, Root, IncrementalUpdate, IncremarkParser, SourceBlock, TransformerOptions, DisplayBlock, BlockTransformer, RootContent } from '@incremark/core';
+export { AnimationEffect, BlockTransformer, DisplayBlock, IncrementalUpdate, ParsedBlock, ParserOptions, Root, RootContent, SourceBlock, TransformerOptions, TransformerPlugin, TransformerState, allPlugins, cloneNode, codeBlockPlugin, countChars, createBlockTransformer, createPlugin, defaultPlugins, imagePlugin, mathPlugin, mermaidPlugin, sliceAst, thematicBreakPlugin } from '@incremark/core';
 import * as _incremark_devtools from '@incremark/devtools';
 import { DevToolsOptions } from '@incremark/devtools';
 import React from 'react';
 
+/** 打字机效果配置 */
+interface TypewriterOptions {
+    /** 是否启用打字机效果（可动态切换） */
+    enabled?: boolean;
+    /** 每次显示的字符数，可以是固定值或范围 [min, max] */
+    charsPerTick?: number | [number, number];
+    /** 更新间隔 (ms) */
+    tickInterval?: number;
+    /** 动画效果: 'none' | 'fade-in' | 'typing' */
+    effect?: AnimationEffect;
+    /** 光标字符（仅 typing 效果使用） */
+    cursor?: string;
+    /** 页面不可见时暂停 */
+    pauseOnHidden?: boolean;
+    /** 自定义插件 */
+    plugins?: TransformerPlugin[];
+}
 interface UseIncremarkOptions extends ParserOptions {
+    /** 打字机配置，传入即创建 transformer（可通过 enabled 控制是否启用） */
+    typewriter?: TypewriterOptions;
 }
 interface BlockWithStableId$1 extends ParsedBlock {
     stableId: string;
 }
+/** 打字机控制对象 */
+interface TypewriterControls {
+    /** 是否启用 */
+    enabled: boolean;
+    /** 设置启用状态 */
+    setEnabled: (enabled: boolean) => void;
+    /** 是否正在处理中 */
+    isProcessing: boolean;
+    /** 是否已暂停 */
+    isPaused: boolean;
+    /** 当前动画效果 */
+    effect: AnimationEffect;
+    /** 跳过动画，直接显示全部 */
+    skip: () => void;
+    /** 暂停动画 */
+    pause: () => void;
+    /** 恢复动画 */
+    resume: () => void;
+    /** 动态更新配置 */
+    setOptions: (options: Partial<TypewriterOptions>) => void;
+}
 /**
  * React Hook: Incremark 流式 Markdown 解析器
  *
  * @example
  * ```tsx
- * import { useIncremark } from '@incremark/react'
+ * import { useIncremark, Incremark } from '@incremark/react'
  *
  * function App() {
- *   const { markdown, blocks, append, finalize, reset } = useIncremark()
+ *   // 基础用法
+ *   const { blocks, append, finalize } = useIncremark()
  *
- *   async function handleStream(stream) {
- *     for await (const chunk of stream) {
- *       append(chunk)
+ *   // 启用打字机效果
+ *   const { blocks, append, finalize, typewriter } = useIncremark({
+ *     typewriter: {
+ *       enabled: true,       // 可动态切换
+ *       charsPerTick: [1, 3],
+ *       tickInterval: 30,
+ *       effect: 'typing',
+ *       cursor: '|'
  *     }
- *     finalize()
- *   }
+ *   })
  *
- *   return <div>{markdown.length} 字符</div>
+ *   // 动态切换打字机效果
+ *   typewriter.setEnabled(false)
+ *
+ *   return (
+ *     <>
+ *       <Incremark blocks={blocks} />
+ *       {typewriter.isProcessing && <button onClick={typewriter.skip}>跳过</button>}
+ *     </>
+ *   )
  * }
  * ```
  */
@@ -39,7 +92,7 @@ declare function useIncremark(options?: UseIncremarkOptions): {
     pendingBlocks: ParsedBlock[];
     /** 当前完整的 AST */
     ast: Root;
-    /** 所有块（完成 + 待处理），带稳定 ID */
+    /** 用于渲染的 blocks（根据打字机设置自动处理） */
     blocks: BlockWithStableId$1[];
     /** 是否正在加载 */
     isLoading: boolean;
@@ -49,12 +102,14 @@ declare function useIncremark(options?: UseIncremarkOptions): {
     finalize: () => IncrementalUpdate;
     /** 强制中断 */
     abort: () => IncrementalUpdate;
-    /** 重置解析器 */
+    /** 重置解析器和打字机 */
     reset: () => void;
     /** 一次性渲染（reset + append + finalize） */
     render: (content: string) => IncrementalUpdate;
     /** 解析器实例 */
     parser: IncremarkParser;
+    /** 打字机控制 */
+    typewriter: TypewriterControls;
 };
 type UseIncremarkReturn = ReturnType<typeof useIncremark>;
 
@@ -77,8 +132,78 @@ interface UseDevToolsOptions extends DevToolsOptions {
  */
 declare function useDevTools(incremark: UseIncremarkReturn, options?: UseDevToolsOptions): _incremark_devtools.IncremarkDevTools | null;
 
+interface UseBlockTransformerOptions extends Omit<TransformerOptions, 'onChange'> {
+}
+interface UseBlockTransformerReturn<T = unknown> {
+    /** 用于渲染的 display blocks */
+    displayBlocks: DisplayBlock<T>[];
+    /** 是否正在处理中 */
+    isProcessing: boolean;
+    /** 是否已暂停 */
+    isPaused: boolean;
+    /** 当前动画效果 */
+    effect: AnimationEffect;
+    /** 跳过所有动画 */
+    skip: () => void;
+    /** 重置状态 */
+    reset: () => void;
+    /** 暂停动画 */
+    pause: () => void;
+    /** 恢复动画 */
+    resume: () => void;
+    /** 动态更新配置 */
+    setOptions: (options: Partial<Pick<TransformerOptions, 'charsPerTick' | 'tickInterval' | 'effect' | 'pauseOnHidden'>>) => void;
+    /** transformer 实例（用于高级用法） */
+    transformer: BlockTransformer<T>;
+}
+/**
+ * React Hook: Block Transformer
+ *
+ * 用于控制 blocks 的逐步显示（打字机效果）
+ * 作为解析器和渲染器之间的中间层
+ *
+ * 特性：
+ * - 使用 requestAnimationFrame 实现流畅动画
+ * - 支持随机步长 `charsPerTick: [1, 3]`
+ * - 支持动画效果 `effect: 'typing'`
+ * - 页面不可见时自动暂停
+ *
+ * @example
+ * ```tsx
+ * import { useIncremark, useBlockTransformer, defaultPlugins } from '@incremark/react'
+ *
+ * function App() {
+ *   const { completedBlocks, append, finalize } = useIncremark()
+ *
+ *   // 转换为 SourceBlock 格式
+ *   const sourceBlocks = useMemo(() => completedBlocks.map(block => ({
+ *     id: block.id,
+ *     node: block.node,
+ *     status: block.status
+ *   })), [completedBlocks])
+ *
+ *   // 添加打字机效果
+ *   const { displayBlocks, isProcessing, skip, effect } = useBlockTransformer(sourceBlocks, {
+ *     charsPerTick: [1, 3],  // 随机步长
+ *     tickInterval: 30,
+ *     effect: 'typing',      // 光标效果
+ *     plugins: defaultPlugins
+ *   })
+ *
+ *   return (
+ *     <div className={effect === 'typing' ? 'typing' : ''}>
+ *       <Incremark blocks={displayBlocks} />
+ *       {isProcessing && <button onClick={skip}>跳过</button>}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+declare function useBlockTransformer<T = unknown>(sourceBlocks: SourceBlock<T>[], options?: UseBlockTransformerOptions): UseBlockTransformerReturn<T>;
+
 interface BlockWithStableId extends ParsedBlock {
     stableId: string;
+    isLastPending?: boolean;
 }
 interface IncremarkProps {
     /** 要渲染的块列表 */
@@ -110,7 +235,7 @@ declare const Incremark: React.FC<IncremarkProps>;
 interface IncremarkRendererProps {
     node: RootContent;
     components?: Partial<Record<string, React.ComponentType<{
-        node: any;
+        node: RootContent;
     }>>>;
 }
 /**
@@ -118,4 +243,46 @@ interface IncremarkRendererProps {
  */
 declare const IncremarkRenderer: React.FC<IncremarkRendererProps>;
 
-export { Incremark, type IncremarkProps, IncremarkRenderer, type IncremarkRendererProps, type UseDevToolsOptions, type UseIncremarkOptions, type UseIncremarkReturn, useDevTools, useIncremark };
+interface AutoScrollContainerProps {
+    /** 子元素 */
+    children: React.ReactNode;
+    /** 是否启用自动滚动 */
+    enabled?: boolean;
+    /** 触发自动滚动的底部阈值（像素） */
+    threshold?: number;
+    /** 滚动行为 */
+    behavior?: ScrollBehavior;
+    /** 容器样式 */
+    style?: React.CSSProperties;
+    /** 容器类名 */
+    className?: string;
+}
+interface AutoScrollContainerRef {
+    /** 强制滚动到底部 */
+    scrollToBottom: () => void;
+    /** 是否用户手动向上滚动了 */
+    isUserScrolledUp: () => boolean;
+    /** 容器元素引用 */
+    container: HTMLDivElement | null;
+}
+/**
+ * 自动滚动容器
+ *
+ * 当内容更新时自动滚动到底部。
+ * 如果用户手动向上滚动，则暂停自动滚动，直到用户再次滚动到底部。
+ *
+ * @example
+ * ```tsx
+ * const scrollRef = useRef<AutoScrollContainerRef>(null)
+ *
+ * <AutoScrollContainer ref={scrollRef} enabled={true}>
+ *   <Incremark blocks={blocks} />
+ * </AutoScrollContainer>
+ *
+ * // 强制滚动到底部
+ * scrollRef.current?.scrollToBottom()
+ * ```
+ */
+declare const AutoScrollContainer: React.ForwardRefExoticComponent<AutoScrollContainerProps & React.RefAttributes<AutoScrollContainerRef>>;
+
+export { AutoScrollContainer, type AutoScrollContainerProps, type AutoScrollContainerRef, Incremark, type IncremarkProps, IncremarkRenderer, type IncremarkRendererProps, type TypewriterControls, type TypewriterOptions, type UseBlockTransformerOptions, type UseBlockTransformerReturn, type UseDevToolsOptions, type UseIncremarkOptions, type UseIncremarkReturn, useBlockTransformer, useDevTools, useIncremark };

package/dist/index.js

@@ -1,31 +1,125 @@
 // src/hooks/useIncremark.ts
-import { useState, useCallback, useMemo, useRef } from "react";
+import { useState, useCallback, useMemo, useRef, useEffect } from "react";
 import {
-  createIncremarkParser
+  createIncremarkParser,
+  createBlockTransformer,
+  defaultPlugins
 } from "@incremark/core";
 function useIncremark(options = {}) {
   const parserRef = useRef(null);
+  const transformerRef = useRef(null);
+  const hasTypewriterConfig = !!options.typewriter;
+  const cursorRef = useRef(options.typewriter?.cursor ?? "|");
   if (!parserRef.current) {
     parserRef.current = createIncremarkParser(options);
   }
+  if (hasTypewriterConfig && !transformerRef.current) {
+    const twOptions = options.typewriter;
+    transformerRef.current = createBlockTransformer({
+      charsPerTick: twOptions.charsPerTick ?? [1, 3],
+      tickInterval: twOptions.tickInterval ?? 30,
+      effect: twOptions.effect ?? "none",
+      pauseOnHidden: twOptions.pauseOnHidden ?? true,
+      plugins: twOptions.plugins ?? defaultPlugins,
+      onChange: () => {
+        setForceUpdateCount((c) => c + 1);
+      }
+    });
+  }
   const parser = parserRef.current;
+  const transformer = transformerRef.current;
   const [markdown, setMarkdown] = useState("");
   const [completedBlocks, setCompletedBlocks] = useState([]);
   const [pendingBlocks, setPendingBlocks] = useState([]);
   const [isLoading, setIsLoading] = useState(false);
-  const blocks = useMemo(() => {
-    const result = [];
-    for (const block of completedBlocks) {
-      result.push({ ...block, stableId: block.id });
+  const [forceUpdateCount, setForceUpdateCount] = useState(0);
+  const [typewriterEnabled, setTypewriterEnabled] = useState(options.typewriter?.enabled ?? hasTypewriterConfig);
+  const [isTypewriterProcessing, setIsTypewriterProcessing] = useState(false);
+  const [isTypewriterPaused, setIsTypewriterPaused] = useState(false);
+  const [typewriterEffect, setTypewriterEffect] = useState(
+    options.typewriter?.effect ?? "none"
+  );
+  const sourceBlocks = useMemo(
+    () => completedBlocks.map((block) => ({
+      id: block.id,
+      node: block.node,
+      status: block.status
+    })),
+    [completedBlocks]
+  );
+  useEffect(() => {
+    if (!transformer) return;
+    transformer.push(sourceBlocks);
+    const displayBlocks = transformer.getDisplayBlocks();
+    const currentDisplaying = displayBlocks.find((b) => !b.isDisplayComplete);
+    if (currentDisplaying) {
+      const updated = sourceBlocks.find((b) => b.id === currentDisplaying.id);
+      if (updated) {
+        transformer.update(updated);
+      }
     }
-    for (let i = 0; i < pendingBlocks.length; i++) {
-      result.push({
-        ...pendingBlocks[i],
-        stableId: `pending-${i}`
-      });
+    setIsTypewriterProcessing(transformer.isProcessing());
+    setIsTypewriterPaused(transformer.isPausedState());
+  }, [sourceBlocks, transformer]);
+  const addCursorToNode = useCallback((node, cursor) => {
+    const cloned = JSON.parse(JSON.stringify(node));
+    function addToLast(n) {
+      if (n.children && n.children.length > 0) {
+        for (let i = n.children.length - 1; i >= 0; i--) {
+          if (addToLast(n.children[i])) {
+            return true;
+          }
+        }
+        n.children.push({ type: "text", value: cursor });
+        return true;
+      }
+      if (n.type === "text" && typeof n.value === "string") {
+        n.value += cursor;
+        return true;
+      }
+      if (typeof n.value === "string") {
+        n.value += cursor;
+        return true;
+      }
+      return false;
+    }
+    addToLast(cloned);
+    return cloned;
+  }, []);
+  const blocks = useMemo(() => {
+    if (!typewriterEnabled || !transformer) {
+      const result = [];
+      for (const block of completedBlocks) {
+        result.push({ ...block, stableId: block.id });
+      }
+      for (let i = 0; i < pendingBlocks.length; i++) {
+        result.push({
+          ...pendingBlocks[i],
+          stableId: `pending-${i}`
+        });
+      }
+      return result;
     }
-    return result;
-  }, [completedBlocks, pendingBlocks]);
+    const displayBlocks = transformer.getDisplayBlocks();
+    return displayBlocks.map((db, index) => {
+      const isPending = !db.isDisplayComplete;
+      const isLastPending = isPending && index === displayBlocks.length - 1;
+      let node = db.displayNode;
+      if (typewriterEffect === "typing" && isLastPending) {
+        node = addCursorToNode(db.displayNode, cursorRef.current);
+      }
+      return {
+        id: db.id,
+        stableId: db.id,
+        status: db.isDisplayComplete ? "completed" : "pending",
+        isLastPending,
+        node,
+        startOffset: 0,
+        endOffset: 0,
+        rawText: ""
+      };
+    });
+  }, [completedBlocks, pendingBlocks, typewriterEnabled, typewriterEffect, addCursorToNode, forceUpdateCount]);
   const ast = useMemo(
     () => ({
       type: "root",
@@ -65,7 +159,8 @@ function useIncremark(options = {}) {
     setPendingBlocks([]);
     setMarkdown("");
     setIsLoading(false);
-  }, [parser]);
+    transformer?.reset();
+  }, [parser, transformer]);
   const render = useCallback(
     (content) => {
       const update = parser.render(content);
@@ -77,6 +172,59 @@ function useIncremark(options = {}) {
     },
     [parser]
   );
+  const skip = useCallback(() => {
+    transformer?.skip();
+    setIsTypewriterProcessing(false);
+  }, [transformer]);
+  const pause = useCallback(() => {
+    transformer?.pause();
+    setIsTypewriterPaused(true);
+  }, [transformer]);
+  const resume = useCallback(() => {
+    transformer?.resume();
+    setIsTypewriterPaused(false);
+  }, [transformer]);
+  const setTypewriterOptions = useCallback(
+    (opts) => {
+      if (opts.enabled !== void 0) {
+        setTypewriterEnabled(opts.enabled);
+      }
+      if (opts.charsPerTick !== void 0 || opts.tickInterval !== void 0 || opts.effect !== void 0 || opts.pauseOnHidden !== void 0) {
+        transformer?.setOptions({
+          charsPerTick: opts.charsPerTick,
+          tickInterval: opts.tickInterval,
+          effect: opts.effect,
+          pauseOnHidden: opts.pauseOnHidden
+        });
+      }
+      if (opts.effect !== void 0) {
+        setTypewriterEffect(opts.effect);
+      }
+      if (opts.cursor !== void 0) {
+        cursorRef.current = opts.cursor;
+      }
+    },
+    [transformer]
+  );
+  const typewriter = useMemo(
+    () => ({
+      enabled: typewriterEnabled,
+      setEnabled: setTypewriterEnabled,
+      isProcessing: isTypewriterProcessing,
+      isPaused: isTypewriterPaused,
+      effect: typewriterEffect,
+      skip,
+      pause,
+      resume,
+      setOptions: setTypewriterOptions
+    }),
+    [typewriterEnabled, isTypewriterProcessing, isTypewriterPaused, typewriterEffect, skip, pause, resume, setTypewriterOptions]
+  );
+  useEffect(() => {
+    return () => {
+      transformer?.destroy();
+    };
+  }, [transformer]);
   return {
     /** 已收集的完整 Markdown 字符串 */
     markdown,
@@ -86,7 +234,7 @@ function useIncremark(options = {}) {
     pendingBlocks,
     /** 当前完整的 AST */
     ast,
-    /** 所有块（完成 + 待处理），带稳定 ID */
+    /** 用于渲染的 blocks（根据打字机设置自动处理） */
     blocks,
     /** 是否正在加载 */
     isLoading,
@@ -96,22 +244,24 @@ function useIncremark(options = {}) {
     finalize,
     /** 强制中断 */
     abort,
-    /** 重置解析器 */
+    /** 重置解析器和打字机 */
     reset,
     /** 一次性渲染（reset + append + finalize） */
     render,
     /** 解析器实例 */
-    parser
+    parser,
+    /** 打字机控制 */
+    typewriter
   };
 }
 
 // src/hooks/useDevTools.ts
-import { useEffect, useRef as useRef2 } from "react";
+import { useEffect as useEffect2, useRef as useRef2 } from "react";
 import { createDevTools } from "@incremark/devtools";
 function useDevTools(incremark, options = {}) {
   const devtoolsRef = useRef2(null);
   const optionsRef = useRef2(options);
-  useEffect(() => {
+  useEffect2(() => {
     const devtools = createDevTools(optionsRef.current);
     devtoolsRef.current = devtools;
     incremark.parser.setOnChange((state) => {
@@ -137,15 +287,103 @@ function useDevTools(incremark, options = {}) {
   return devtoolsRef.current;
 }
 
+// src/hooks/useBlockTransformer.ts
+import { useState as useState2, useCallback as useCallback2, useRef as useRef3, useEffect as useEffect3 } from "react";
+import {
+  createBlockTransformer as createBlockTransformer2
+} from "@incremark/core";
+function useBlockTransformer(sourceBlocks, options = {}) {
+  const [displayBlocks, setDisplayBlocks] = useState2([]);
+  const [isProcessing, setIsProcessing] = useState2(false);
+  const [isPaused, setIsPaused] = useState2(false);
+  const [effect, setEffect] = useState2(options.effect ?? "none");
+  const transformerRef = useRef3(null);
+  if (!transformerRef.current) {
+    transformerRef.current = createBlockTransformer2({
+      ...options,
+      onChange: (blocks) => {
+        setDisplayBlocks(blocks);
+        setIsProcessing(transformerRef.current?.isProcessing() ?? false);
+        setIsPaused(transformerRef.current?.isPausedState() ?? false);
+      }
+    });
+  }
+  const transformer = transformerRef.current;
+  useEffect3(() => {
+    transformer.push(sourceBlocks);
+    const currentDisplaying = displayBlocks.find((b) => !b.isDisplayComplete);
+    if (currentDisplaying) {
+      const updated = sourceBlocks.find((b) => b.id === currentDisplaying.id);
+      if (updated) {
+        transformer.update(updated);
+      }
+    }
+  }, [sourceBlocks, transformer]);
+  useEffect3(() => {
+    return () => {
+      transformer.destroy();
+    };
+  }, [transformer]);
+  const skip = useCallback2(() => {
+    transformer.skip();
+  }, [transformer]);
+  const reset = useCallback2(() => {
+    transformer.reset();
+  }, [transformer]);
+  const pause = useCallback2(() => {
+    transformer.pause();
+    setIsPaused(true);
+  }, [transformer]);
+  const resume = useCallback2(() => {
+    transformer.resume();
+    setIsPaused(false);
+  }, [transformer]);
+  const setOptionsCallback = useCallback2(
+    (opts) => {
+      transformer.setOptions(opts);
+      if (opts.effect !== void 0) {
+        setEffect(opts.effect);
+      }
+    },
+    [transformer]
+  );
+  return {
+    displayBlocks,
+    isProcessing,
+    isPaused,
+    effect,
+    skip,
+    reset,
+    pause,
+    resume,
+    setOptions: setOptionsCallback,
+    transformer
+  };
+}
+
 // src/components/IncremarkRenderer.tsx
 import React from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
+function getStableText(node) {
+  if (!node.chunks || node.chunks.length === 0) {
+    return node.value;
+  }
+  return node.value.slice(0, node.stableLength ?? 0);
+}
 function renderInlineChildren(children) {
   if (!children) return null;
   return children.map((child, i) => {
     switch (child.type) {
-      case "text":
-        return /* @__PURE__ */ jsx(React.Fragment, { children: child.value }, i);
+      case "text": {
+        const textNode = child;
+        if (textNode.chunks && textNode.chunks.length > 0) {
+          return /* @__PURE__ */ jsxs(React.Fragment, { children: [
+            getStableText(textNode),
+            textNode.chunks.map((chunk) => /* @__PURE__ */ jsx("span", { className: "incremark-fade-in", children: chunk.text }, chunk.createdAt))
+          ] }, i);
+        }
+        return /* @__PURE__ */ jsx(React.Fragment, { children: textNode.value }, i);
+      }
       case "strong":
         return /* @__PURE__ */ jsx("strong", { children: renderInlineChildren(child.children) }, i);
       case "emphasis":
@@ -162,6 +400,8 @@ function renderInlineChildren(children) {
         return /* @__PURE__ */ jsx("del", { children: renderInlineChildren(child.children) }, i);
       case "paragraph":
         return /* @__PURE__ */ jsx(React.Fragment, { children: renderInlineChildren(child.children) }, i);
+      case "html":
+        return /* @__PURE__ */ jsx("span", { dangerouslySetInnerHTML: { __html: child.value } }, i);
       default:
         return /* @__PURE__ */ jsx("span", { children: child.value || "" }, i);
     }
@@ -180,7 +420,7 @@ var DefaultList = ({ node }) => {
   const Tag = node.ordered ? "ol" : "ul";
   return /* @__PURE__ */ jsx(Tag, { className: "incremark-list", children: node.children?.map((item, i) => /* @__PURE__ */ jsx("li", { children: renderInlineChildren(item.children) }, i)) });
 };
-var DefaultBlockquote = ({ node }) => /* @__PURE__ */ jsx("blockquote", { className: "incremark-blockquote", children: node.children?.map((child, i) => /* @__PURE__ */ jsx(React.Fragment, { children: child.type === "paragraph" ? /* @__PURE__ */ jsx("p", { children: renderInlineChildren(child.children) }) : renderInlineChildren(child.children || []) }, i)) });
+var DefaultBlockquote = ({ node }) => /* @__PURE__ */ jsx("blockquote", { className: "incremark-blockquote", children: node.children?.map((child, i) => /* @__PURE__ */ jsx(React.Fragment, { children: child.type === "paragraph" ? /* @__PURE__ */ jsx("p", { children: renderInlineChildren(child.children) }) : "children" in child && Array.isArray(child.children) ? renderInlineChildren(child.children) : null }, i)) });
 var DefaultTable = ({ node }) => /* @__PURE__ */ jsx("div", { className: "incremark-table-wrapper", children: /* @__PURE__ */ jsxs("table", { className: "incremark-table", children: [
   /* @__PURE__ */ jsx("thead", { children: node.children?.[0] && /* @__PURE__ */ jsx("tr", { children: node.children[0].children?.map((cell, i) => /* @__PURE__ */ jsx("th", { children: renderInlineChildren(cell.children) }, i)) }) }),
   /* @__PURE__ */ jsx("tbody", { children: node.children?.slice(1).map((row, i) => /* @__PURE__ */ jsx("tr", { children: row.children?.map((cell, j) => /* @__PURE__ */ jsx("td", { children: renderInlineChildren(cell.children) }, j)) }, i)) })
@@ -210,18 +450,176 @@ var Incremark = ({
   showBlockStatus = true,
   className = ""
 }) => {
-  return /* @__PURE__ */ jsx2("div", { className: `incremark ${className}`, children: blocks.map((block) => /* @__PURE__ */ jsx2(
-    "div",
-    {
-      className: `incremark-block ${showBlockStatus && block.status === "pending" ? "pending" : ""}`,
-      children: /* @__PURE__ */ jsx2(IncremarkRenderer, { node: block.node, components })
-    },
-    block.stableId
-  )) });
+  return /* @__PURE__ */ jsx2("div", { className: `incremark ${className}`, children: blocks.map((block) => {
+    const isPending = block.status === "pending";
+    const classes = [
+      "incremark-block",
+      isPending ? "incremark-pending" : "incremark-completed",
+      block.isLastPending ? "incremark-last-pending" : ""
+    ].filter(Boolean).join(" ");
+    return /* @__PURE__ */ jsx2("div", { className: classes, children: /* @__PURE__ */ jsx2(IncremarkRenderer, { node: block.node, components }) }, block.stableId);
+  }) });
 };
+
+// src/components/AutoScrollContainer.tsx
+import {
+  useRef as useRef4,
+  useEffect as useEffect4,
+  useCallback as useCallback3,
+  useState as useState3,
+  forwardRef,
+  useImperativeHandle
+} from "react";
+import { jsx as jsx3 } from "react/jsx-runtime";
+var AutoScrollContainer = forwardRef(
+  ({
+    children,
+    enabled = true,
+    threshold = 50,
+    behavior = "instant",
+    style,
+    className
+  }, ref) => {
+    const containerRef = useRef4(null);
+    const [isUserScrolledUp, setIsUserScrolledUp] = useState3(false);
+    const lastScrollTopRef = useRef4(0);
+    const lastScrollHeightRef = useRef4(0);
+    const isNearBottom = useCallback3(() => {
+      const container = containerRef.current;
+      if (!container) return true;
+      const { scrollTop, scrollHeight, clientHeight } = container;
+      return scrollHeight - scrollTop - clientHeight <= threshold;
+    }, [threshold]);
+    const scrollToBottom = useCallback3(
+      (force = false) => {
+        const container = containerRef.current;
+        if (!container) return;
+        if (isUserScrolledUp && !force) return;
+        container.scrollTo({
+          top: container.scrollHeight,
+          behavior
+        });
+      },
+      [isUserScrolledUp, behavior]
+    );
+    const hasScrollbar = useCallback3(() => {
+      const container = containerRef.current;
+      if (!container) return false;
+      return container.scrollHeight > container.clientHeight;
+    }, []);
+    const handleScroll = useCallback3(() => {
+      const container = containerRef.current;
+      if (!container) return;
+      const { scrollTop, scrollHeight, clientHeight } = container;
+      if (scrollHeight <= clientHeight) {
+        setIsUserScrolledUp(false);
+        lastScrollTopRef.current = 0;
+        lastScrollHeightRef.current = scrollHeight;
+        return;
+      }
+      if (isNearBottom()) {
+        setIsUserScrolledUp(false);
+      } else {
+        const isScrollingUp = scrollTop < lastScrollTopRef.current;
+        const isContentUnchanged = scrollHeight === lastScrollHeightRef.current;
+        if (isScrollingUp && isContentUnchanged) {
+          setIsUserScrolledUp(true);
+        }
+      }
+      lastScrollTopRef.current = scrollTop;
+      lastScrollHeightRef.current = scrollHeight;
+    }, [isNearBottom]);
+    useEffect4(() => {
+      const container = containerRef.current;
+      if (container) {
+        lastScrollTopRef.current = container.scrollTop;
+        lastScrollHeightRef.current = container.scrollHeight;
+      }
+    }, []);
+    useEffect4(() => {
+      const container = containerRef.current;
+      if (!container || !enabled) return;
+      const observer = new MutationObserver(() => {
+        requestAnimationFrame(() => {
+          if (!containerRef.current) return;
+          const { scrollHeight, clientHeight } = containerRef.current;
+          if (scrollHeight <= clientHeight) {
+            setIsUserScrolledUp(false);
+          }
+          lastScrollHeightRef.current = scrollHeight;
+          if (!isUserScrolledUp) {
+            scrollToBottom();
+          }
+        });
+      });
+      observer.observe(container, {
+        childList: true,
+        subtree: true,
+        characterData: true
+      });
+      return () => observer.disconnect();
+    }, [enabled, isUserScrolledUp, scrollToBottom]);
+    useImperativeHandle(
+      ref,
+      () => ({
+        scrollToBottom: () => scrollToBottom(true),
+        isUserScrolledUp: () => isUserScrolledUp,
+        container: containerRef.current
+      }),
+      [scrollToBottom, isUserScrolledUp]
+    );
+    return /* @__PURE__ */ jsx3(
+      "div",
+      {
+        ref: containerRef,
+        className,
+        style: {
+          overflowY: "auto",
+          height: "100%",
+          ...style
+        },
+        onScroll: handleScroll,
+        children
+      }
+    );
+  }
+);
+AutoScrollContainer.displayName = "AutoScrollContainer";
+
+// src/index.ts
+import {
+  BlockTransformer as BlockTransformer2,
+  createBlockTransformer as createBlockTransformer3,
+  countChars,
+  sliceAst,
+  cloneNode,
+  codeBlockPlugin,
+  mermaidPlugin,
+  imagePlugin,
+  mathPlugin,
+  thematicBreakPlugin,
+  defaultPlugins as defaultPlugins2,
+  allPlugins,
+  createPlugin
+} from "@incremark/core";
 export {
+  AutoScrollContainer,
+  BlockTransformer2 as BlockTransformer,
   Incremark,
   IncremarkRenderer,
+  allPlugins,
+  cloneNode,
+  codeBlockPlugin,
+  countChars,
+  createBlockTransformer3 as createBlockTransformer,
+  createPlugin,
+  defaultPlugins2 as defaultPlugins,
+  imagePlugin,
+  mathPlugin,
+  mermaidPlugin,
+  sliceAst,
+  thematicBreakPlugin,
+  useBlockTransformer,
   useDevTools,
   useIncremark
 };

package/dist/styles.css

@@ -189,3 +189,18 @@
   font-size: 11px;
 }
 
+/* ============ 渐入动画效果 ============ */
+
+.incremark-fade-in {
+  animation: incremark-fade-in 0.4s ease-out;
+}
+
+@keyframes incremark-fade-in {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@incremark/react",
-  "version": "0.0.4",
+  "version": "0.1.0",
   "license": "MIT",
   "description": "Incremark React integration - Incremental Markdown parser for AI streaming",
   "type": "module",
@@ -19,10 +19,10 @@
   ],
   "peerDependencies": {
     "react": ">=18.0.0",
-    "@incremark/core": "0.0.4"
+    "@incremark/core": "0.1.0"
   },
   "dependencies": {
-    "@incremark/devtools": "0.0.4"
+    "@incremark/devtools": "0.1.0"
   },
   "devDependencies": {
     "@types/react": "^18.2.0",