ds-markdown 0.1.2-beta.3 → 0.1.2

package/README.en.md

@@ -18,6 +18,57 @@ A React component designed specifically for modern AI applications, providing sm
 
 ---
 
+## 📋 Table of Contents
+
+- [✨ Core Features](#-core-features)
+- [📦 Quick Installation](#-quick-installation)
+- [🚀 5-Minute Quick Start](#-5-minute-quick-start)
+  - [Basic Usage](#basic-usage)
+  - [Disable Typing Animation](#disable-typing-animation)
+  - [Mathematical Formula Support](#mathematical-formula-support)
+  - [AI Conversation Scenario](#ai-conversation-scenario)
+  - [🎯 Advanced Callback Control](#-advanced-callback-control)
+  - [🔄 Restart Animation Demo](#-restart-animation-demo)
+  - [▶️ Manual Start Animation Demo](#️-manual-start-animation-demo)
+- [📚 Complete API Documentation](#-complete-api-documentation)
+- [🧮 Mathematical Formula Usage Guide](#-mathematical-formula-usage-guide)
+- [🔌 Plugin System](#-plugin-system)
+- [🎛️ Timer Mode Details](#️-timer-mode-details)
+- [💡 Practical Examples](#-practical-examples)
+- [🔧 Best Practices](#-best-practices)
+
+---
+
+## ❓ Why use ds-markdown?
+
+- **Ultimate AI Chat Experience**  
+  Faithfully recreates the typing animation and streaming response of leading AI chat interfaces (like DeepSeek), delivering a truly immersive "AI is thinking/answering" experience.
+
+- **Perfect for Streaming Backend Data**  
+  Many AI/LLM backends (OpenAI, DeepSeek, etc.) send data chunks containing multiple characters at once.  
+  **ds-markdown automatically splits each chunk into single characters and animates them one by one, ensuring smooth typing even if the backend sends several characters at a time.**
+
+- **Full Markdown & Math Formula Support**  
+  Built-in KaTeX, supports all major Markdown syntax and math formulas—ideal for technical Q&A, education, and knowledge bases.
+
+- **Excellent Developer Experience**  
+  Rich imperative API, supports streaming data, async callbacks, and plugin extensions for flexible animation and content control.
+
+- **Lightweight & High Performance**  
+  Small bundle size, fast, mobile and desktop ready. The only core dependency is [react-markdown](https://github.com/remarkjs/react-markdown) (a widely used, mature Markdown renderer). No other heavy dependencies—works out of the box.
+
+- **Multi-theme & Plugin Architecture**  
+  Light/dark theme switching, remark/rehype plugin compatibility, and advanced extensibility.
+
+- **Wide Range of Use Cases**
+  - AI chatbots/assistants
+  - Real-time Q&A/knowledge bases
+  - Education/math/programming content
+  - Product demos, interactive docs
+  - Any scenario needing "typewriter" animation and streaming Markdown rendering
+
+---
+
 ## ✨ Core Features
 
 ### 🤖 **AI Conversation Scenarios**
@@ -184,6 +235,227 @@ Let's explore these new features together!`);
 }
 ```
 
+### 🎯 Advanced Callback Control
+
+```tsx
+import { useRef, useState } from 'react';
+import { MarkdownCMD, MarkdownCMDRef } from 'ds-markdown';
+
+function AdvancedCallbackDemo() {
+  const markdownRef = useRef<MarkdownCMDRef>(null);
+  const [typingStats, setTypingStats] = useState({ progress: 0, currentChar: '', totalChars: 0 });
+
+  const handleBeforeTypedChar = async (data) => {
+    // Perform async operations before character typing
+    console.log('About to type:', data.currentChar);
+
+    // Can perform network requests, data validation, etc.
+    if (data.currentChar === '!') {
+      await new Promise((resolve) => setTimeout(resolve, 500)); // Simulate delay
+    }
+  };
+
+  const handleTypedChar = (data) => {
+    // Update typing statistics
+    setTypingStats({
+      progress: Math.round(data.percent),
+      currentChar: data.currentChar,
+      totalChars: data.currentIndex + 1,
+    });
+
+    // Can add sound effects, animations, etc.
+    if (data.currentChar === '.') {
+      // Play period sound effect
+      console.log('Play period sound effect');
+    }
+  };
+
+  const handleStart = (data) => {
+    console.log('Start typing:', data.currentChar);
+  };
+
+  const handleEnd = (data) => {
+    console.log('Typing complete:', data.str);
+  };
+
+  const startDemo = () => {
+    markdownRef.current?.clear();
+    markdownRef.current?.push(
+      '# Advanced Callback Demo\n\n' +
+        'This example shows how to use `onBeforeTypedChar` and `onTypedChar` callbacks:\n\n' +
+        '- 🎯 **Pre-typing callback**: Can perform async operations before character display\n' +
+        '- 📊 **Post-typing callback**: Can update progress in real-time and add effects\n' +
+        '- ⚡ **Performance optimization**: Supports async operations without affecting typing smoothness\n\n' +
+        'Current progress: ' +
+        typingStats.progress +
+        '%\n' +
+        'Characters typed: ' +
+        typingStats.totalChars +
+        '\n\n' +
+        'This is a very powerful feature!',
+      'answer',
+    );
+  };
+
+  return (
+    <div>
+      <button onClick={startDemo}>🚀 Start Advanced Demo</button>
+
+      <div style={{ margin: '10px 0', padding: '10px', background: '#f5f5f5', borderRadius: '4px' }}>
+        <strong>Typing Stats:</strong> Progress {typingStats.progress}% | Current char: "{typingStats.currentChar}" | Total chars: {typingStats.totalChars}
+      </div>
+
+      <MarkdownCMD ref={markdownRef} interval={30} onBeforeTypedChar={handleBeforeTypedChar} onTypedChar={handleTypedChar} onStart={handleStart} onEnd={handleEnd} />
+    </div>
+  );
+}
+```
+
+### 🔄 Restart Animation Demo
+
+```tsx
+import { useRef, useState } from 'react';
+import { MarkdownCMD, MarkdownCMDRef } from 'ds-markdown';
+
+function RestartDemo() {
+  const markdownRef = useRef<MarkdownCMDRef>(null);
+  const [isPlaying, setIsPlaying] = useState(false);
+  const [hasStarted, setHasStarted] = useState(false);
+
+  const startContent = () => {
+    markdownRef.current?.clear();
+    markdownRef.current?.push(
+      '# Restart Animation Demo\n\n' +
+        'This example shows how to use the `restart()` method:\n\n' +
+        '- 🔄 **Restart**: Play current content from the beginning\n' +
+        '- ⏸️ **Pause/Resume**: Can pause and resume at any time\n' +
+        '- 🎯 **Precise Control**: Complete control over animation playback state\n\n' +
+        'Current state: ' +
+        (isPlaying ? 'Playing' : 'Paused') +
+        '\n\n' +
+        'This is a very practical feature!',
+      'answer',
+    );
+    setIsPlaying(true);
+  };
+
+  const handleStart = () => {
+    if (hasStarted) {
+      // If already started, restart
+      markdownRef.current?.restart();
+    } else {
+      // First time start
+      markdownRef.current?.start();
+      setHasStarted(true);
+    }
+    setIsPlaying(true);
+  };
+
+  const handleStop = () => {
+    markdownRef.current?.stop();
+    setIsPlaying(false);
+  };
+
+  const handleResume = () => {
+    markdownRef.current?.resume();
+    setIsPlaying(true);
+  };
+
+  const handleRestart = () => {
+    markdownRef.current?.restart();
+    setIsPlaying(true);
+  };
+
+  const handleEnd = () => {
+    setIsPlaying(false);
+  };
+
+  return (
+    <div>
+      <div style={{ marginBottom: '10px', display: 'flex', gap: '10px', flexWrap: 'wrap' }}>
+        <button onClick={startContent}>🚀 Start Content</button>
+        <button onClick={handleStart} disabled={isPlaying}>
+          {hasStarted ? '🔄 Restart' : '▶️ Start'}
+        </button>
+        <button onClick={handleStop} disabled={!isPlaying}>
+          ⏸️ Pause
+        </button>
+        <button onClick={handleResume} disabled={isPlaying}>
+          ▶️ Resume
+        </button>
+        <button onClick={handleRestart}>🔄 Restart</button>
+      </div>
+
+      <div style={{ margin: '10px 0', padding: '10px', background: '#f5f5f5', borderRadius: '4px' }}>
+        <strong>Animation State:</strong> {isPlaying ? '🟢 Playing' : '🔴 Paused'}
+      </div>
+
+      <MarkdownCMD ref={markdownRef} interval={25} onEnd={handleEnd} />
+    </div>
+  );
+}
+```
+
+### ▶️ Manual Start Animation Demo
+
+```tsx
+import { useRef, useState } from 'react';
+import { MarkdownCMD, MarkdownCMDRef } from 'ds-markdown';
+
+function StartDemo() {
+  const markdownRef = useRef<MarkdownCMDRef>(null);
+  const [isPlaying, setIsPlaying] = useState(false);
+  const [hasStarted, setHasStarted] = useState(false);
+
+  const loadContent = () => {
+    markdownRef.current?.clear();
+    markdownRef.current?.push(
+      '# Manual Start Animation Demo\n\n' +
+        'This example shows how to use the `start()` method:\n\n' +
+        '- 🎯 **Manual Control**: When `autoStartTyping=false`, need to manually call `start()`\n' +
+        '- ⏱️ **Delayed Start**: Can start animation after user interaction\n' +
+        '- 🎮 **Gamification**: Suitable for scenarios requiring user initiative\n\n' +
+        'Click the "Start Animation" button to manually trigger the typing effect!',
+      'answer',
+    );
+    setIsPlaying(false);
+  };
+
+  const handleStart = () => {
+    if (hasStarted) {
+      // If already started, restart
+      markdownRef.current?.restart();
+    } else {
+      // First time start
+      markdownRef.current?.start();
+      setHasStarted(true);
+    }
+    setIsPlaying(true);
+  };
+
+  const handleEnd = () => {
+    setIsPlaying(false);
+  };
+
+  return (
+    <div>
+      <div style={{ marginBottom: '10px', display: 'flex', gap: '10px', flexWrap: 'wrap' }}>
+        <button onClick={loadContent}>📝 Load Content</button>
+        <button onClick={handleStart} disabled={isPlaying}>
+          {hasStarted ? '🔄 Restart' : '▶️ Start Animation'}
+        </button>
+      </div>
+
+      <div style={{ margin: '10px 0', padding: '10px', background: '#f5f5f5', borderRadius: '4px' }}>
+        <strong>State:</strong> {isPlaying ? '🟢 Animation Playing' : '🔴 Waiting to Start'}
+      </div>
+
+      <MarkdownCMD ref={markdownRef} interval={30} autoStartTyping={false} onEnd={handleEnd} />
+    </div>
+  );
+}
+```
+
 ---
 
 ## 📚 Complete API Documentation
@@ -639,6 +911,7 @@ import { MarkdownCMD, MarkdownCMDRef } from 'ds-markdown';
 function RestartDemo() {
   const markdownRef = useRef<MarkdownCMDRef>(null);
   const [isPlaying, setIsPlaying] = useState(false);
+  const [hasStarted, setHasStarted] = useState(false);
 
   const startContent = () => {
     markdownRef.current?.clear();
@@ -658,7 +931,14 @@ function RestartDemo() {
   };
 
   const handleStart = () => {
-    markdownRef.current?.start();
+    if (hasStarted) {
+      // If already started, restart
+      markdownRef.current?.restart();
+    } else {
+      // First time start
+      markdownRef.current?.start();
+      setHasStarted(true);
+    }
     setIsPlaying(true);
   };
 
@@ -686,7 +966,7 @@ function RestartDemo() {
       <div style={{ marginBottom: '10px', display: 'flex', gap: '10px', flexWrap: 'wrap' }}>
         <button onClick={startContent}>🚀 Start Content</button>
         <button onClick={handleStart} disabled={isPlaying}>
-          ▶️ Start
+          {hasStarted ? '🔄 Restart' : '▶️ Start'}
         </button>
         <button onClick={handleStop} disabled={!isPlaying}>
           ⏸️ Pause
@@ -716,6 +996,7 @@ import { MarkdownCMD, MarkdownCMDRef } from 'ds-markdown';
 function StartDemo() {
   const markdownRef = useRef<MarkdownCMDRef>(null);
   const [isPlaying, setIsPlaying] = useState(false);
+  const [hasStarted, setHasStarted] = useState(false);
 
   const loadContent = () => {
     markdownRef.current?.clear();
@@ -732,7 +1013,14 @@ function StartDemo() {
   };
 
   const handleStart = () => {
-    markdownRef.current?.start();
+    if (hasStarted) {
+      // If already started, restart
+      markdownRef.current?.restart();
+    } else {
+      // First time start
+      markdownRef.current?.start();
+      setHasStarted(true);
+    }
     setIsPlaying(true);
   };
 
@@ -745,7 +1033,7 @@ function StartDemo() {
       <div style={{ marginBottom: '10px', display: 'flex', gap: '10px', flexWrap: 'wrap' }}>
         <button onClick={loadContent}>📝 Load Content</button>
         <button onClick={handleStart} disabled={isPlaying}>
-          ▶️ Start Animation
+          {hasStarted ? '🔄 Restart' : '▶️ Start Animation'}
         </button>
       </div>
 

package/README.ja.md

@@ -18,6 +18,57 @@
 
 ---
 
+## 📋 目次
+
+- [✨ コア機能](#-コア機能)
+- [📦 クイックインストール](#-クイックインストール)
+- [🚀 5分クイックスタート](#-5分クイックスタート)
+  - [基本的な使用法](#基本的な使用法)
+  - [タイピングアニメーションの無効化](#タイピングアニメーションの無効化)
+  - [数式サポート](#数式サポート)
+  - [AI 会話シナリオ](#ai-会話シナリオ)
+  - [🎯 高度なコールバック制御](#-高度なコールバック制御)
+  - [🔄 アニメーション再開デモ](#-アニメーション再開デモ)
+  - [▶️ 手動開始アニメーションデモ](#️-手動開始アニメーションデモ)
+- [📚 完全 API ドキュメント](#-完全-api-ドキュメント)
+- [🧮 数式使用ガイド](#-数式使用ガイド)
+- [🔌 プラグインシステム](#-プラグインシステム)
+- [🎛️ タイマーモード詳細](#️-タイマーモード詳細)
+- [💡 実戦例](#-実戦例)
+- [🔧 ベストプラクティス](#-ベストプラクティス)
+
+---
+
+## ❓ なぜ ds-markdown を使うのか？
+
+- **AI チャット体験を完全再現**  
+  DeepSeek などの主要な AI チャット UI のタイピングアニメーションとストリーミング応答を1:1で再現し、「AI が考え中/回答中」のリアルな体験を提供します。
+
+- **バックエンドのストリーミングデータに完全対応**  
+  多くの AI/LLM バックエンド（OpenAI、DeepSeek など）は、一度に複数文字を含む chunk を送信します。  
+  **ds-markdown は各 chunk を自動的に1文字ずつ分割し、どんなにまとめて送られても滑らかに1文字ずつアニメーション表示します。**
+
+- **Markdown & 数式完全対応**  
+  KaTeX 内蔵、主要な Markdown 構文と数式をすべてサポート。技術 Q&A、教育、ナレッジベースに最適。
+
+- **優れた開発体験**  
+  豊富な命令型 API、ストリーミングデータ・非同期コールバック・プラグイン拡張に対応し、柔軟な制御が可能。
+
+- **軽量・高性能**  
+  小さなバンドルサイズ、高速、モバイル・デスクトップ両対応。コア依存は [react-markdown](https://github.com/remarkjs/react-markdown)（業界標準の成熟した Markdown レンダラー）のみで、他に重い依存はありません。すぐに使えます。
+
+- **多テーマ・プラグインアーキテクチャ**  
+  ライト/ダークテーマ切替、remark/rehype プラグイン互換、拡張性抜群。
+
+- **幅広い用途**
+  - AI チャットボット/アシスタント
+  - リアルタイム Q&A/ナレッジベース
+  - 教育/数学/プログラミングコンテンツ
+  - プロダクトデモ、インタラクティブドキュメント
+  - 「タイプライター」アニメーションやストリーミング Markdown が必要なあらゆる場面
+
+---
+
 ## ✨ コア機能
 
 ### 🤖 **AI 会話シナリオ**
@@ -179,6 +230,195 @@ React 19 は多くのエキサイティングな新機能をもたらします
 }
 ```
 
+### 🎯 高度なコールバック制御
+
+```tsx
+import { useRef } from 'react';
+import { MarkdownCMD, MarkdownCMDRef } from 'ds-markdown';
+
+function AdvancedCallbackDemo() {
+  const markdownRef = useRef<MarkdownCMDRef>(null);
+
+  const handleStart = () => {
+    markdownRef.current?.start();
+  };
+
+  const handleStop = () => {
+    markdownRef.current?.stop();
+  };
+
+  const handleResume = () => {
+    markdownRef.current?.resume();
+  };
+
+  const handleRestart = () => {
+    markdownRef.current?.restart();
+  };
+
+  const handleEnd = (data: EndData) => {
+    console.log('セクション完了:', data);
+  };
+
+  return (
+    <div>
+      <div style={{ marginBottom: '10px', display: 'flex', gap: '10px', flexWrap: 'wrap' }}>
+        <button onClick={handleStart}>🚀 コンテンツ開始</button>
+        <button onClick={handleStop}>⏸️ 一時停止</button>
+        <button onClick={handleResume}>▶️ 再開</button>
+        <button onClick={handleRestart}>🔄 再開</button>
+      </div>
+
+      <MarkdownCMD ref={markdownRef} interval={20} onEnd={handleEnd} />
+    </div>
+  );
+}
+```
+
+### 🔄 アニメーション再開デモ
+
+```tsx
+import { useRef, useState } from 'react';
+import { MarkdownCMD, MarkdownCMDRef } from 'ds-markdown';
+
+function RestartDemo() {
+  const markdownRef = useRef<MarkdownCMDRef>(null);
+  const [isPlaying, setIsPlaying] = useState(false);
+  const [hasStarted, setHasStarted] = useState(false);
+
+  const startContent = () => {
+    markdownRef.current?.clear();
+    markdownRef.current?.push(
+      '# アニメーション再開デモ\n\n' +
+        'この例は `restart()` メソッドの使用方法を示しています：\n\n' +
+        '- 🔄 **再開**：現在のコンテンツを最初から再生\n' +
+        '- ⏸️ **一時停止/再開**：いつでも一時停止と再開が可能\n' +
+        '- 🎯 **精密制御**：アニメーション再生状態の完全制御\n\n' +
+        '現在の状態：' +
+        (isPlaying ? '再生中' : '一時停止') +
+        '\n\n' +
+        'これは非常に実用的な機能です！',
+      'answer',
+    );
+    setIsPlaying(true);
+  };
+
+  const handleStart = () => {
+    if (hasStarted) {
+      // 既に開始されている場合は再開
+      markdownRef.current?.restart();
+    } else {
+      // 初回開始
+      markdownRef.current?.start();
+      setHasStarted(true);
+    }
+    setIsPlaying(true);
+  };
+
+  const handleStop = () => {
+    markdownRef.current?.stop();
+    setIsPlaying(false);
+  };
+
+  const handleResume = () => {
+    markdownRef.current?.resume();
+    setIsPlaying(true);
+  };
+
+  const handleRestart = () => {
+    markdownRef.current?.restart();
+    setIsPlaying(true);
+  };
+
+  const handleEnd = () => {
+    setIsPlaying(false);
+  };
+
+  return (
+    <div>
+      <div style={{ marginBottom: '10px', display: 'flex', gap: '10px', flexWrap: 'wrap' }}>
+        <button onClick={startContent}>🚀 コンテンツ開始</button>
+        <button onClick={handleStart} disabled={isPlaying}>
+          {hasStarted ? '🔄 再開' : '▶️ 開始'}
+        </button>
+        <button onClick={handleStop} disabled={!isPlaying}>
+          ⏸️ 一時停止
+        </button>
+        <button onClick={handleResume} disabled={isPlaying}>
+          ▶️ 再開
+        </button>
+        <button onClick={handleRestart}>🔄 再開</button>
+      </div>
+
+      <div style={{ margin: '10px 0', padding: '10px', background: '#f5f5f5', borderRadius: '4px' }}>
+        <strong>アニメーション状態：</strong> {isPlaying ? '🟢 再生中' : '🔴 一時停止'}
+      </div>
+
+      <MarkdownCMD ref={markdownRef} interval={25} onEnd={handleEnd} />
+    </div>
+  );
+}
+```
+
+### ▶️ 手動開始アニメーションデモ
+
+```tsx
+import { useRef, useState } from 'react';
+import { MarkdownCMD, MarkdownCMDRef } from 'ds-markdown';
+
+function StartDemo() {
+  const markdownRef = useRef<MarkdownCMDRef>(null);
+  const [isPlaying, setIsPlaying] = useState(false);
+  const [hasStarted, setHasStarted] = useState(false);
+
+  const loadContent = () => {
+    markdownRef.current?.clear();
+    markdownRef.current?.push(
+      '# 手動開始アニメーションデモ\n\n' +
+        'この例は `start()` メソッドの使用方法を示しています：\n\n' +
+        '- 🎯 **手動制御**：`autoStartTyping=false` の場合、手動で `start()` を呼び出す必要があります\n' +
+        '- ⏱️ **遅延開始**：ユーザーインタラクション後にアニメーションを開始できます\n' +
+        '- 🎮 **ゲーミフィケーション**：ユーザーの積極性を必要とするシナリオに適しています\n\n' +
+        '"アニメーション開始"ボタンをクリックしてタイピング効果を手動でトリガーしてください！',
+      'answer',
+    );
+    setIsPlaying(false);
+  };
+
+  const handleStart = () => {
+    if (hasStarted) {
+      // 既に開始されている場合は再開
+      markdownRef.current?.restart();
+    } else {
+      // 初回開始
+      markdownRef.current?.start();
+      setHasStarted(true);
+    }
+    setIsPlaying(true);
+  };
+
+  const handleEnd = () => {
+    setIsPlaying(false);
+  };
+
+  return (
+    <div>
+      <div style={{ marginBottom: '10px', display: 'flex', gap: '10px', flexWrap: 'wrap' }}>
+        <button onClick={loadContent}>📝 コンテンツ読み込み</button>
+        <button onClick={handleStart} disabled={isPlaying}>
+          {hasStarted ? '🔄 再開' : '▶️ アニメーション開始'}
+        </button>
+      </div>
+
+      <div style={{ margin: '10px 0', padding: '10px', background: '#f5f5f5', borderRadius: '4px' }}>
+        <strong>状態：</strong> {isPlaying ? '🟢 アニメーション再生中' : '🔴 開始待機中'}
+      </div>
+
+      <MarkdownCMD ref={markdownRef} interval={30} autoStartTyping={false} onEnd={handleEnd} />
+    </div>
+  );
+}
+```
+
 ---
 
 ## 📚 完全 API ドキュメント

package/README.ko.md

@@ -18,6 +18,57 @@
 
 ---
 
+## 📋 목차
+
+- [✨ 핵심 기능](#-핵심-기능)
+- [📦 빠른 설치](#-빠른-설치)
+- [🚀 5분 빠른 시작](#-5분-빠른-시작)
+  - [기본 사용법](#기본-사용법)
+  - [타이핑 애니메이션 비활성화](#타이핑-애니메이션-비활성화)
+  - [수학 공식 지원](#수학-공식-지원)
+  - [AI 대화 시나리오](#ai-대화-시나리오)
+  - [🎯 고급 콜백 제어](#-고급-콜백-제어)
+  - [🔄 애니메이션 재시작 데모](#-애니메이션-재시작-데모)
+  - [▶️ 수동 시작 애니메이션 데모](#️-수동-시작-애니메이션-데모)
+- [📚 완전 API 문서](#-완전-api-문서)
+- [🧮 수학 공식 사용 가이드](#-수학-공식-사용-가이드)
+- [🔌 플러그인 시스템](#-플러그인-시스템)
+- [🎛️ 타이머 모드 상세](#️-타이머-모드-상세)
+- [💡 실전 예제](#-실전-예제)
+- [🔧 모범 사례](#-모범-사례)
+
+---
+
+## ❓ 왜 ds-markdown을 써야 하나요?
+
+- **AI 채팅 경험 완벽 재현**  
+  DeepSeek 등 주요 AI 채팅 UI의 타이핑 애니메이션과 스트리밍 응답을 1:1로 재현, "AI가 생각/답변 중"인 진짜 같은 경험을 제공합니다.
+
+- **백엔드 스트리밍 데이터 완벽 대응**  
+  많은 AI/LLM 백엔드(OpenAI, DeepSeek 등)는 한 번에 여러 글자가 포함된 chunk를 보냅니다.  
+  **ds-markdown은 각 chunk를 자동으로 한 글자씩 분리해, 백엔드가 여러 글자를 한 번에 보내도 항상 부드럽게 한 글자씩 타이핑 애니메이션을 보여줍니다.**
+
+- **완벽한 Markdown & 수식 지원**  
+  KaTeX 내장, 모든 주요 Markdown 구문과 수식 지원—기술 Q&A, 교육, 지식베이스에 최적.
+
+- **최고의 개발 경험**  
+  풍부한 명령형 API, 스트리밍 데이터, 비동기 콜백, 플러그인 확장 등으로 유연한 제어 가능.
+
+- **가볍고 고성능**  
+  작은 용량, 빠른 속도, 모바일/데스크탑 모두 지원. 핵심 의존성은 [react-markdown](https://github.com/remarkjs/react-markdown) (업계 표준의 성숙한 Markdown 렌더러) 하나뿐이며, 그 외 무거운 의존성은 없습니다. 바로 사용 가능합니다.
+
+- **다중 테마 및 플러그인 아키텍처**  
+  라이트/다크 테마 전환, remark/rehype 플러그인 호환, 고급 확장성.
+
+- **다양한 활용 사례**
+  - AI 챗봇/어시스턴트
+  - 실시간 Q&A/지식베이스
+  - 교육/수학/프로그래밍 콘텐츠
+  - 제품 데모, 인터랙티브 문서
+  - "타자기" 애니메이션과 스트리밍 Markdown이 필요한 모든 상황
+
+---
+
 ## ✨ 핵심 기능
 
 ### 🤖 **AI 대화 시나리오**
@@ -607,3 +658,148 @@ import { MarkdownCMDRef } from 'ds-markdown';
 const ref = useRef<MarkdownCMDRef>(null);
 // 완전한 TypeScript 타입 힌트
 ```
+
+### 🔄 애니메이션 재시작 데모
+
+```tsx
+import { useRef, useState } from 'react';
+import { MarkdownCMD, MarkdownCMDRef } from 'ds-markdown';
+
+function RestartDemo() {
+  const markdownRef = useRef<MarkdownCMDRef>(null);
+  const [isPlaying, setIsPlaying] = useState(false);
+  const [hasStarted, setHasStarted] = useState(false);
+
+  const startContent = () => {
+    markdownRef.current?.clear();
+    markdownRef.current?.push(
+      '# 애니메이션 재시작 데모\n\n' +
+        '이 예제는 `restart()` 메서드의 사용법을 보여줍니다:\n\n' +
+        '- 🔄 **재시작**: 현재 콘텐츠를 처음부터 재생\n' +
+        '- ⏸️ **일시정지/재개**: 언제든지 일시정지와 재개 가능\n' +
+        '- 🎯 **정밀 제어**: 애니메이션 재생 상태의 완전한 제어\n\n' +
+        '현재 상태: ' +
+        (isPlaying ? '재생 중' : '일시정지') +
+        '\n\n' +
+        '이는 매우 실용적인 기능입니다!',
+      'answer',
+    );
+    setIsPlaying(true);
+  };
+
+  const handleStart = () => {
+    if (hasStarted) {
+      // 이미 시작된 경우 재시작
+      markdownRef.current?.restart();
+    } else {
+      // 첫 번째 시작
+      markdownRef.current?.start();
+      setHasStarted(true);
+    }
+    setIsPlaying(true);
+  };
+
+  const handleStop = () => {
+    markdownRef.current?.stop();
+    setIsPlaying(false);
+  };
+
+  const handleResume = () => {
+    markdownRef.current?.resume();
+    setIsPlaying(true);
+  };
+
+  const handleRestart = () => {
+    markdownRef.current?.restart();
+    setIsPlaying(true);
+  };
+
+  const handleEnd = () => {
+    setIsPlaying(false);
+  };
+
+  return (
+    <div>
+      <div style={{ marginBottom: '10px', display: 'flex', gap: '10px', flexWrap: 'wrap' }}>
+        <button onClick={startContent}>🚀 콘텐츠 시작</button>
+        <button onClick={handleStart} disabled={isPlaying}>
+          {hasStarted ? '🔄 재시작' : '▶️ 시작'}
+        </button>
+        <button onClick={handleStop} disabled={!isPlaying}>
+          ⏸️ 일시정지
+        </button>
+        <button onClick={handleResume} disabled={isPlaying}>
+          ▶️ 재개
+        </button>
+        <button onClick={handleRestart}>🔄 재시작</button>
+      </div>
+
+      <div style={{ margin: '10px 0', padding: '10px', background: '#f5f5f5', borderRadius: '4px' }}>
+        <strong>애니메이션 상태:</strong> {isPlaying ? '🟢 재생 중' : '🔴 일시정지'}
+      </div>
+
+      <MarkdownCMD ref={markdownRef} interval={25} onEnd={handleEnd} />
+    </div>
+  );
+}
+```
+
+### ▶️ 수동 시작 애니메이션 데모
+
+```tsx
+import { useRef, useState } from 'react';
+import { MarkdownCMD, MarkdownCMDRef } from 'ds-markdown';
+
+function StartDemo() {
+  const markdownRef = useRef<MarkdownCMDRef>(null);
+  const [isPlaying, setIsPlaying] = useState(false);
+  const [hasStarted, setHasStarted] = useState(false);
+
+  const loadContent = () => {
+    markdownRef.current?.clear();
+    markdownRef.current?.push(
+      '# 수동 시작 애니메이션 데모\n\n' +
+        '이 예제는 `start()` 메서드의 사용법을 보여줍니다:\n\n' +
+        '- 🎯 **수동 제어**: `autoStartTyping=false`일 때 수동으로 `start()`를 호출해야 합니다\n' +
+        '- ⏱️ **지연 시작**: 사용자 상호작용 후 애니메이션을 시작할 수 있습니다\n' +
+        '- 🎮 **게임화**: 사용자의 적극성이 필요한 시나리오에 적합합니다\n\n' +
+        '"애니메이션 시작" 버튼을 클릭하여 타이핑 효과를 수동으로 트리거하세요!',
+      'answer',
+    );
+    setIsPlaying(false);
+  };
+
+  const handleStart = () => {
+    if (hasStarted) {
+      // 이미 시작된 경우 재시작
+      markdownRef.current?.restart();
+    } else {
+      // 첫 번째 시작
+      markdownRef.current?.start();
+      setHasStarted(true);
+    }
+    setIsPlaying(true);
+  };
+
+  const handleEnd = () => {
+    setIsPlaying(false);
+  };
+
+  return (
+    <div>
+      <div style={{ marginBottom: '10px', display: 'flex', gap: '10px', flexWrap: 'wrap' }}>
+        <button onClick={loadContent}>📝 콘텐츠 로드</button>
+        <button onClick={handleStart} disabled={isPlaying}>
+          {hasStarted ? '🔄 재시작' : '▶️ 애니메이션 시작'}
+        </button>
+      </div>
+
+      <div style={{ margin: '10px 0', padding: '10px', background: '#f5f5f5', borderRadius: '4px' }}>
+        <strong>상태:</strong> {isPlaying ? '🟢 애니메이션 재생 중' : '🔴 시작 대기 중'}
+      </div>
+
+      <MarkdownCMD ref={markdownRef} interval={30} autoStartTyping={false} onEnd={handleEnd} />
+    </div>
+  );
+}
+```

package/README.md

@@ -18,6 +18,57 @@
 
 ---
 
+## ❓ 为什么要用 ds-markdown？
+
+- **AI 聊天体验极致还原**  
+  1:1 复刻 DeepSeek 等主流 AI 聊天界面的打字动画和流式响应，带来真实的"AI 正在思考/回答"体验，极大提升用户沉浸感。
+
+- **后端流式数据完美适配**  
+  很多 AI/LLM 后端接口（如 OpenAI、DeepSeek 等）推送的数据 chunk 往往一次包含多个字符，普通打字机实现会出现卡顿、跳字等问题。  
+  **ds-markdown 会自动将每个 chunk 拆分为单个字符，逐字流畅渲染动画，无论后端一次推送多少字，都能保证每个字都流畅打字。**
+
+- **完整 Markdown & 数学公式支持**  
+  内置 KaTeX，支持所有主流 Markdown 语法和数学公式，适合技术问答、教育、知识库等内容丰富的应用。
+
+- **极致开发体验**  
+  丰富的命令式 API，支持流式数据、异步回调、插件扩展，开发者可灵活控制动画和内容。
+
+- **轻量高性能**  
+  体积小、性能优，适配移动端和桌面端。核心依赖 [react-markdown](https://github.com/remarkjs/react-markdown)（业界主流、成熟的 Markdown 渲染库），无其它重量级依赖，开箱即用。
+
+- **多主题与插件化架构**  
+  支持亮/暗主题切换，兼容 remark/rehype 插件，满足个性化和高级扩展需求。
+
+- **适用场景广泛**
+  - AI 聊天机器人/助手
+  - 实时问答/知识库
+  - 教育/数学/编程内容展示
+  - 产品演示、交互式文档
+  - 任何需要"打字机"动画和流式 Markdown 渲染的场景
+
+---
+
+## 📋 目录
+
+- [✨ 核心特性](#-核心特性)
+- [📦 快速安装](#-快速安装)
+- [🚀 5分钟上手](#-5分钟上手)
+  - [基础用法](#基础用法)
+  - [禁用打字动画](#禁用打字动画)
+  - [数学公式支持](#数学公式支持)
+  - [AI 对话场景](#ai-对话场景)
+  - [🎯 高级回调控制](#-高级回调控制)
+  - [🔄 重新开始动画演示](#-重新开始动画演示)
+  - [▶️ 手动开始动画演示](#️-手动开始动画演示)
+- [📚 完整 API 文档](#-完整-api-文档)
+- [🧮 数学公式使用指南](#-数学公式使用指南)
+- [🔌 插件系统](#-插件系统)
+- [🎛️ 定时器模式详解](#️-定时器模式详解)
+- [💡 实战示例](#-实战示例)
+- [🔧 最佳实践](#-最佳实践)
+
+---
+
 ## ✨ 核心特性
 
 ### 🤖 **AI 对话场景**
@@ -267,6 +318,7 @@ import { MarkdownCMD, MarkdownCMDRef } from 'ds-markdown';
 function RestartDemo() {
   const markdownRef = useRef<MarkdownCMDRef>(null);
   const [isPlaying, setIsPlaying] = useState(false);
+  const [hasStarted, setHasStarted] = useState(false);
 
   const startContent = () => {
     markdownRef.current?.clear();
@@ -286,7 +338,14 @@ function RestartDemo() {
   };
 
   const handleStart = () => {
-    markdownRef.current?.start();
+    if (hasStarted) {
+      // 如果已经开始过，则重新开始
+      markdownRef.current?.restart();
+    } else {
+      // 第一次开始
+      markdownRef.current?.start();
+      setHasStarted(true);
+    }
     setIsPlaying(true);
   };
 
@@ -314,7 +373,7 @@ function RestartDemo() {
       <div style={{ marginBottom: '10px', display: 'flex', gap: '10px', flexWrap: 'wrap' }}>
         <button onClick={startContent}>🚀 开始内容</button>
         <button onClick={handleStart} disabled={isPlaying}>
-          ▶️ 开始
+          {hasStarted ? '🔄 重新开始' : '▶️ 开始'}
         </button>
         <button onClick={handleStop} disabled={!isPlaying}>
           ⏸️ 暂停
@@ -344,6 +403,7 @@ import { MarkdownCMD, MarkdownCMDRef } from 'ds-markdown';
 function StartDemo() {
   const markdownRef = useRef<MarkdownCMDRef>(null);
   const [isPlaying, setIsPlaying] = useState(false);
+  const [hasStarted, setHasStarted] = useState(false);
 
   const loadContent = () => {
     markdownRef.current?.clear();
@@ -360,7 +420,14 @@ function StartDemo() {
   };
 
   const handleStart = () => {
-    markdownRef.current?.start();
+    if (hasStarted) {
+      // 如果已经开始过，则重新开始
+      markdownRef.current?.restart();
+    } else {
+      // 第一次开始
+      markdownRef.current?.start();
+      setHasStarted(true);
+    }
     setIsPlaying(true);
   };
 
@@ -373,7 +440,7 @@ function StartDemo() {
       <div style={{ marginBottom: '10px', display: 'flex', gap: '10px', flexWrap: 'wrap' }}>
         <button onClick={loadContent}>📝 加载内容</button>
         <button onClick={handleStart} disabled={isPlaying}>
-          ▶️ 开始动画
+          {hasStarted ? '🔄 重新开始' : '▶️ 开始动画'}
         </button>
       </div>
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ds-markdown",
   "private": false,
-  "version": "0.1.2-beta.3",
+  "version": "0.1.2",
   "main": "./dist/cjs/index.js",
   "types": "./dist/cjs/index.d.ts",
   "module": "./dist/esm/index.js",
@@ -125,6 +125,6 @@
     "react-markdown"
   ],
   "publishConfig": {
-    "tag": "beta"
+    "tag": "latest"
   }
 }