kanji-recognizer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kanji Recognizer Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,355 @@
+# Kanji Recognizer
+
+A lightweight, dependency-free JavaScript library for Kanji stroke order recognition and validation using KanjiVG data.
+
+[![npm version](https://img.shields.io/npm/v/kanji-recognizer.svg)](https://www.npmjs.com/package/kanji-recognizer)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+## ✨ Features
+
+- **🎯 Accurate Recognition** - Uses geometric resampling algorithm to compare user strokes against KanjiVG data
+- **📝 Stroke-by-Stroke Validation** - Enforces correct stroke order for proper kanji learning
+- **🎨 Fully Customizable** - Easy to style colors, animations, and recognition sensitivity
+- **⚡ Lightweight** - Zero dependencies, pure SVG-based rendering
+- **📱 Mobile-Friendly** - Touch-optimized with pointer events
+- **🌐 Browser Compatible** - Works in Chrome, Firefox, Safari, and Edge
+
+## 📦 Installation
+
+```bash
+npm install kanji-recognizer
+```
+
+Or use directly in browser:
+
+```html
+<script type="module">
+  import { KanjiWriter, KanjiVGParser } from './kanji-recognizer/src/index.js';
+</script>
+```
+
+## 🚀 Quick Start
+
+```javascript
+import { KanjiWriter, KanjiVGParser } from 'kanji-recognizer';
+
+// 1. Fetch kanji data from KanjiVG
+const kanjiData = await KanjiVGParser.fetchData('日');
+
+// 2. Create a writer instance
+const writer = new KanjiWriter('container-id', kanjiData, {
+    width: 300,
+    height: 300
+});
+
+// 3. Listen for events
+writer.onCorrect = () => console.log("Correct stroke!");
+writer.onComplete = () => console.log("Kanji complete!");
+```
+
+## 📖 API Reference
+
+### KanjiWriter
+
+Creates an interactive kanji writing canvas.
+
+```javascript
+const writer = new KanjiWriter(elementId, kanjiData, options);
+```
+
+#### Parameters
+
+- **elementId** `string` - DOM element ID to mount the canvas
+- **kanjiData** `string[]` - Array of SVG path strings from KanjiVG
+- **options** `object` - Configuration options (optional)
+
+#### Options
+
+```javascript
+{
+  // Dimensions
+  width: 300,                    // Canvas width in pixels
+  height: 300,                   // Canvas height in pixels
+  
+  // Colors
+  strokeColor: '#333',           // Main stroke color
+  correctColor: '#4CAF50',       // Success feedback color
+  incorrectColor: '#F44336',     // Error feedback color
+  hintColor: 'cyan',             // Hint animation color
+  gridColor: '#ddd',             // Background grid color
+  ghostColor: '#ff0000',         // Next stroke guide color
+  
+  // Appearance
+  strokeWidth: 4,                // Width of drawn strokes
+  gridWidth: 0.5,                // Grid line width
+  ghostOpacity: '0.1',           // Ghost guide opacity
+  
+  // Behavior
+  showGhost: true,               // Show red guide for next stroke
+  showGrid: true,                // Show background grid
+  
+  // Recognition (Adjustable!)
+  passThreshold: 15,             // Lower = stricter (10-20 recommended)
+  startDistThreshold: 40,        // Start point tolerance in pixels
+  lengthRatioMin: 0.5,           // Minimum stroke length ratio
+  lengthRatioMax: 1.5,           // Maximum stroke length ratio
+  
+  // Animations
+  stepDuration: 500,             // Animation speed in ms
+  hintDuration: 800,             // Hint display duration
+  snapDuration: 200              // Snap-to-correct duration
+}
+```
+
+#### Methods
+
+##### `clear()`
+Reset the canvas and start over.
+
+```javascript
+writer.clear();
+```
+
+##### `hint()`
+Show animated hint for the next expected stroke.
+
+```javascript
+writer.hint();
+```
+
+##### `animate()`
+Animate the complete kanji stroke-by-stroke.
+
+```javascript
+await writer.animate();
+```
+
+##### `setOptions(newOptions)`
+Update configuration options dynamically.
+
+```javascript
+writer.setOptions({ 
+  strokeColor: '#000',
+  passThreshold: 20  // Make recognition more lenient
+});
+```
+
+##### `destroy()`
+Clean up resources and remove event listeners.
+
+```javascript
+writer.destroy();
+```
+
+#### Event Callbacks
+
+```javascript
+writer.onCorrect = () => { /* Fired on correct stroke */ };
+writer.onIncorrect = () => { /* Fired on incorrect stroke */ };
+writer.onComplete = () => { /* Fired when kanji is complete */ };
+writer.onClear = () => { /* Fired when canvas is cleared */ };
+
+// Error handling
+writer.container.addEventListener('kanji:error', (e) => {
+  console.error('Error:', e.detail);
+});
+```
+
+### KanjiVGParser
+
+Utilities for fetching and parsing KanjiVG SVG data.
+
+#### `KanjiVGParser.fetchData(char)`
+
+Fetch kanji stroke data by character.
+
+```javascript
+const strokes = await KanjiVGParser.fetchData('日');
+// Returns: ['M25,32...', 'M12,80...']
+```
+
+#### `KanjiVGParser.parse(svgContent)`
+
+Parse raw KanjiVG SVG into stroke paths.
+
+```javascript
+const strokes = KanjiVGParser.parse(svgString);
+```
+
+#### `KanjiVGParser.baseUrl`
+
+Set custom base URL for KanjiVG files.
+
+```javascript
+KanjiVGParser.baseUrl = 'https://example.com/kanjivg/';
+```
+
+## 💡 Usage Examples
+
+### Basic Kanji Practice
+
+```javascript
+import { KanjiWriter, KanjiVGParser } from 'kanji-recognizer';
+
+// Load kanji
+const kanjiData = await KanjiVGParser.fetchData('愛');
+
+// Create writer
+const writer = new KanjiWriter('practice-area', kanjiData);
+
+// Add event listeners
+writer.onCorrect = () => {
+  document.getElementById('feedback').textContent = '正解！';
+};
+
+writer.onComplete = () => {
+  document.getElementById('feedback').textContent = '完成！';
+  confetti(); // Celebrate!
+};
+```
+
+### Beginner Mode (Lenient Recognition)
+
+```javascript
+const writer = new KanjiWriter('container', kanjiData, {
+  passThreshold: 20,        // More forgiving
+  startDistThreshold: 50,   // Allow imprecise starts
+  showGhost: true,          // Show guides
+  hintColor: '#00ff00'      // Bright hints
+});
+```
+
+### Expert Mode (Strict Recognition)
+
+```javascript
+const writer = new KanjiWriter('container', kanjiData, {
+  passThreshold: 8,         // Very strict
+  startDistThreshold: 25,   // Precise starts required
+  showGhost: false,         // No guides
+  strokeColor: '#000'       // Professional look
+});
+```
+
+### Custom Styling
+
+```javascript
+const writer = new KanjiWriter('container', kanjiData, {
+  width: 500,
+  height: 500,
+  strokeColor: '#2c3e50',
+  correctColor: '#27ae60',
+  incorrectColor: '#e74c3c',
+  gridColor: '#ecf0f1',
+  strokeWidth: 6
+});
+```
+
+### Multiple Kanji Practice
+
+```javascript
+const kanjis = ['日', '月', '火', '水', '木', '金', '土'];
+let currentIndex = 0;
+
+async function nextKanji() {
+  if (writer) writer.destroy(); // Clean up previous
+  
+  const data = await KanjiVGParser.fetchData(kanjis[currentIndex]);
+  writer = new KanjiWriter('container', data);
+  
+  writer.onComplete = () => {
+    currentIndex++;
+    if (currentIndex < kanjis.length) {
+      setTimeout(nextKanji, 1000);
+    }
+  };
+}
+
+nextKanji();
+```
+
+## 🎨 Demo
+
+Check out the included demo:
+
+```bash
+cd kanji-recognizer
+python3 -m http.server 8000
+# Open http://localhost:8000/demo/index.html
+```
+
+## 🔧 Requirements
+
+- Modern browser with ES6 module support
+- KanjiVG SVG files (not included in npm package)
+
+### Getting KanjiVG Data
+
+Download from [KanjiVG Project](https://github.com/KanjiVG/kanjivg):
+
+```bash
+git clone https://github.com/KanjiVG/kanjivg.git
+```
+
+Or use a CDN:
+
+```javascript
+KanjiVGParser.baseUrl = 'https://cdn.example.com/kanjivg/';
+```
+
+## 🌐 Browser Support
+
+- Chrome/Edge: ✅ Latest
+- Firefox: ✅ Latest
+- Safari: ✅ 14+
+- Safari iOS: ✅ 14+
+- Chrome Mobile: ✅ Latest
+
+## 🤝 Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+See [docs/README_REVIEW.md](docs/README_REVIEW.md) for development documentation.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- [KanjiVG](https://kanjivg.tagaini.net/) - Kanji stroke order data
+- Inspired by Japanese language learning tools
+
+## 📚 Related Projects
+
+- [KanjiVG](https://github.com/KanjiVG/kanjivg) - Kanji stroke order graphics
+- [kanji-data](https://github.com/davidluzgouveia/kanji-data) - Comprehensive kanji dataset
+
+## 🐛 Known Issues
+
+- None currently! Report issues on [GitHub](https://github.com/mxggle/kanji-recognizer/issues)
+
+## 📈 Roadmap
+
+- [ ] TypeScript definitions
+- [ ] React component wrapper
+- [ ] Vue component wrapper
+- [ ] Bundled common kanji data
+- [ ] Offline support with Service Worker
+- [ ] Haptic feedback for mobile
+- [ ] Audio pronunciation integration
+
+## 💬 Support
+
+- 📧 Email: your.email@example.com
+- 🐛 Issues: [GitHub Issues](https://github.com/mxggle/kanji-recognizer/issues)
+- 💬 Discussions: [GitHub Discussions](https://github.com/mxggle/kanji-recognizer/discussions)
+
+---
+
+**Made with ❤️ for Japanese learners worldwide**

package/package.json

@@ -0,0 +1,44 @@
+{
+    "name": "kanji-recognizer",
+    "version": "0.1.0",
+    "description": "A robust Kanji stroke order recognition and validation library using KanjiVG data.",
+    "main": "src/index.js",
+    "type": "module",
+    "exports": {
+        ".": {
+            "import": "./src/index.js"
+        }
+    },
+    "files": [
+        "src",
+        "README.md",
+        "LICENSE"
+    ],
+    "scripts": {
+        "start": "vite",
+        "build": "vite build",
+        "dev": "vite"
+    },
+    "keywords": [
+        "kanji",
+        "recognition",
+        "stroke-order",
+        "japanese",
+        "kanjivg",
+        "handwriting",
+        "svg"
+    ],
+    "author": "Antigravity",
+    "license": "MIT",
+    "devDependencies": {
+        "vite": "^5.0.0"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/mxggle/kanji-recognizer.git"
+    },
+    "bugs": {
+        "url": "https://github.com/mxggle/kanji-recognizer/issues"
+    },
+    "homepage": "https://github.com/mxggle/kanji-recognizer#readme"
+}

package/src/GeometryUtil.js

@@ -0,0 +1,88 @@
+export class GeometryUtil {
+    /**
+     * Calculate distance between two points
+     */
+    static distance(p1, p2) {
+        const dx = p1.x - p2.x;
+        const dy = p1.y - p2.y;
+        return Math.sqrt(dx * dx + dy * dy);
+    }
+
+    /**
+     * Get total length of a path of points
+     */
+    static getPathLength(points) {
+        let len = 0;
+        for (let i = 1; i < points.length; i++) {
+            len += this.distance(points[i - 1], points[i]);
+        }
+        return len;
+    }
+
+    /**
+     * Resample points to a fixed number of equidistant points
+     */
+    static resample(points, numPoints = 64) {
+        if (points.length <= 1) return points;
+
+        const pathLen = this.getPathLength(points);
+        const step = pathLen / (numPoints - 1);
+
+        const newPoints = [points[0]];
+        let currentLen = 0;
+        let nextStep = step;
+
+        for (let i = 1; i < points.length; i++) {
+            let p1 = points[i - 1];
+            let p2 = points[i];
+            let dist = this.distance(p1, p2);
+
+            while (currentLen + dist >= nextStep) {
+                let t = (nextStep - currentLen) / dist;
+                let newX = p1.x + (p2.x - p1.x) * t;
+                let newY = p1.y + (p2.y - p1.y) * t;
+                newPoints.push({ x: newX, y: newY });
+                nextStep += step;
+
+                // Safety break if floating point issues cause infinite loop
+                if (newPoints.length >= numPoints) break;
+            }
+            currentLen += dist;
+        }
+
+        while (newPoints.length < numPoints) {
+            newPoints.push(points[points.length - 1]);
+        }
+
+        return newPoints;
+    }
+
+    /**
+     * Compare two strokes. Returns a score (lower is better, 0 is perfect).
+     * Checks shape and direction.
+     * @param {Array} userPoints - User's drawn points
+     * @param {Array} targetPoints - Target stroke points
+     * @param {number} startDistThreshold - Maximum allowed start point distance (default: 40)
+     */
+    static compareStrokes(userPoints, targetPoints, startDistThreshold = 40) {
+        const resampledUser = this.resample(userPoints);
+        const resampledTarget = this.resample(targetPoints);
+
+        // 1. Direction Check: Check if start and end points match roughly
+        const startDist = this.distance(resampledUser[0], resampledTarget[0]);
+        const endDist = this.distance(resampledUser[resampledUser.length - 1], resampledTarget[resampledTarget.length - 1]);
+
+        // If start is far from start, it's definitely wrong (or drawn backwards)
+        // We penalize this heavily.
+        if (startDist > startDistThreshold) return Infinity; // Way off
+
+        // 2. Shape Check: Average distance between points
+        let totalDist = 0;
+        for (let i = 0; i < resampledUser.length; i++) {
+            totalDist += this.distance(resampledUser[i], resampledTarget[i]);
+        }
+        const avgDist = totalDist / resampledUser.length;
+
+        return avgDist;
+    }
+}

package/src/KanjiVGParser.js

@@ -0,0 +1,87 @@
+export class KanjiVGParser {
+    /**
+     * Parse a KanjiVG SVG string and return an array of stroke paths.
+     * @param {string} svgContent - The raw XML content of the SVG file
+     * @returns {string[]} Array of path data strings (d attributes) ordered by stroke index
+     */
+    static parse(svgContent) {
+        const parser = new DOMParser();
+        const doc = parser.parseFromString(svgContent, "image/svg+xml");
+
+        // KanjiVG stores strokes as paths with ids like "kvg:XXXXX-s1", "kvg:XXXXX-s2", etc.
+        // We can find all paths that look like stroke paths.
+        // However, sometimes paths are nested in groups.
+        // A reliable way is to query all paths and sort them by their id number.
+
+        const paths = Array.from(doc.querySelectorAll('path[id*="-s"]'));
+
+        // Sort by the stroke number at the end of the id (e.g. "kvg:04e8c-s1" -> 1)
+        paths.sort((a, b) => {
+            const getNum = (el) => {
+                const match = el.id.match(/-s(\d+)$/);
+                return match ? parseInt(match[1], 10) : 999;
+            };
+            return getNum(a) - getNum(b);
+        });
+
+        return paths.map(p => p.getAttribute('d'));
+    }
+
+    // Default base URL for KanjiVG files (can be local or remote)
+    static baseUrl = "kanjivg/kanji/";
+
+    /**
+     * Convert a character to its unicode hex string (lowercase, 5 chars usually).
+     * @param {string} char 
+     * @returns {string} e.g. "6c49"
+     */
+    static getHex(char) {
+        if (typeof char !== 'string' || char.length === 0) {
+            throw new Error('Invalid character: must be a non-empty string');
+        }
+
+        let code = char.charCodeAt(0).toString(16);
+        while (code.length < 5) code = "0" + code;
+        return code;
+    }
+
+    /**
+     * Fetch standard KanjiVG data for a given character using the configured baseUrl.
+     * @param {string} char - A single kanji character (e.g. "漢") or directly the hex code.
+     */
+    static async fetchData(char) {
+        if (!char || typeof char !== 'string') {
+            throw new Error('Invalid character: must be a non-empty string');
+        }
+
+        let hex = char;
+        // If it looks like a single character, convert to hex
+        if (char.length === 1 && char.charCodeAt(0) > 255) {
+            hex = this.getHex(char);
+        }
+
+        // Validate hex format (basic check)
+        if (!/^[0-9a-f]{5}$/i.test(hex)) {
+            // If not valid hex, might be a character - try converting
+            if (char.length === 1) {
+                hex = this.getHex(char);
+            } else {
+                throw new Error(`Invalid kanji hex code: ${hex}`);
+            }
+        }
+
+        const url = `${this.baseUrl}${hex}.svg`;
+        return this.fetchAndParse(url);
+    }
+
+    /**
+     * Fetch a KanjiVG file from a URL/Path and parse it.
+     * @param {string} url - URL to the .svg file
+     */
+    static async fetchAndParse(url) {
+        const response = await fetch(url);
+        if (!response.ok) throw new Error(`Failed to fetch kanji: ${response.statusText}`);
+        const text = await response.text();
+        return this.parse(text);
+    }
+}

package/src/KanjiWriter.js

@@ -0,0 +1,392 @@
+import { StrokeRecognizer } from './StrokeRecognizer.js';
+
+export class KanjiWriter {
+    constructor(elementId, kanjiData, options = {}) {
+        this.container = document.getElementById(elementId);
+        this.kanjiData = kanjiData; // Expects array of path strings
+        this.options = {
+            width: 109,
+            height: 109,
+            // Colors
+            strokeColor: "#333",          // Main stroke color
+            correctColor: "#4CAF50",      // Green flash on success
+            incorrectColor: "#F44336",    // Red stroke on error
+            hintColor: "cyan",            // Hint animation color
+            gridColor: "#ddd",            // Background grid color
+            ghostColor: "#ff0000",        // Color of next stroke ghost
+
+            // Toggles
+            showGhost: true,              // Show red guide for next stroke
+            showGrid: true,               // Show the background grid
+
+            // Appearance
+            strokeWidth: 4,
+            gridWidth: 0.5,
+            ghostOpacity: "0.1",
+
+            // Animations
+            stepDuration: 500,
+            hintDuration: 800,
+            snapDuration: 200,
+
+            ...options
+        };
+
+        // Initialize recognizer with threshold options
+        this.recognizer = new StrokeRecognizer({
+            passThreshold: this.options.passThreshold || 15,
+            startDistThreshold: this.options.startDistThreshold || 40,
+            lengthRatioMin: this.options.lengthRatioMin || 0.5,
+            lengthRatioMax: this.options.lengthRatioMax || 1.5,
+            resamplingPoints: this.options.resamplingPoints || 64
+        });
+
+        this.currentStrokeIndex = 0;
+        this.isDrawing = false;
+        this.currentPoints = [];
+
+        // Use options.width/height in initSVG
+        this.width = this.options.width;
+        this.height = this.options.height;
+
+        console.log("Kanji data loaded:", kanjiData);
+
+        this.initSVG();
+        this.attachEvents();
+        this.drawGrid();
+        this.renderUpcomingStrokes(); // Show ghosts or just hint
+    }
+
+    initSVG() {
+        this.svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+        // KanjiVG uses a standard 109x109 viewBox coordinate system
+        // We keep this fixed regardless of container size for correct rendering
+        this.svg.setAttribute("viewBox", "0 0 109 109");
+        this.svg.style.width = "100%";
+        this.svg.style.height = "100%";
+        this.svg.style.border = "1px solid #ccc";
+        this.svg.style.touchAction = "none"; // Prevent scrolling
+        this.svg.style.background = "#fff";
+
+        // Groups
+        this.gridGroup = document.createElementNS("http://www.w3.org/2000/svg", "g");
+        this.bgGroup = document.createElementNS("http://www.w3.org/2000/svg", "g"); // For background/ghost characters
+        this.drawnGroup = document.createElementNS("http://www.w3.org/2000/svg", "g"); // Completed correct strokes
+        this.currentGroup = document.createElementNS("http://www.w3.org/2000/svg", "g"); // Current active stroke
+
+        this.svg.appendChild(this.gridGroup);
+        this.svg.appendChild(this.bgGroup);
+        this.svg.appendChild(this.drawnGroup);
+        this.svg.appendChild(this.currentGroup);
+
+        this.container.appendChild(this.svg);
+    }
+
+    drawGrid() {
+        if (!this.options.showGrid) return;
+
+        const opts = { stroke: this.options.gridColor, "stroke-width": this.options.gridWidth, "stroke-dasharray": "3,3" };
+        // Use KanjiVG's 109x109 coordinate system
+        const size = 109;
+        // Diagonal lines
+        this.addLine(0, 0, size, size, this.gridGroup, opts);
+        this.addLine(size, 0, 0, size, this.gridGroup, opts);
+        // Center lines
+        this.addLine(size / 2, 0, size / 2, size, this.gridGroup, opts);
+        this.addLine(0, size / 2, size, size / 2, this.gridGroup, opts);
+    }
+
+    addLine(x1, y1, x2, y2, parent, attrs = {}) {
+        const line = document.createElementNS("http://www.w3.org/2000/svg", "line");
+        line.setAttribute("x1", x1);
+        line.setAttribute("y1", y1);
+        line.setAttribute("x2", x2);
+        line.setAttribute("y2", y2);
+        for (const [k, v] of Object.entries(attrs)) {
+            line.setAttribute(k, v);
+        }
+        parent.appendChild(line);
+    }
+
+    renderUpcomingStrokes() {
+        // Optional: render faint outline of the next stroke
+        this.bgGroup.innerHTML = '';
+
+        if (!this.options.showGhost) return;
+
+        // If we want to show the full ghost:
+        this.kanjiData.forEach((d, i) => {
+            const path = document.createElementNS("http://www.w3.org/2000/svg", "path");
+            path.setAttribute("d", d);
+            path.setAttribute("fill", "none");
+            path.setAttribute("stroke", i === this.currentStrokeIndex ? this.options.ghostColor : "#eee");
+            path.setAttribute("stroke-width", "2");
+            path.style.opacity = i === this.currentStrokeIndex ? this.options.ghostOpacity : "0.1";
+            this.bgGroup.appendChild(path);
+        });
+    }
+
+    getPointerPos(e) {
+        const pt = this.svg.createSVGPoint();
+        pt.x = e.clientX;
+        pt.y = e.clientY;
+        return pt.matrixTransform(this.svg.getScreenCTM().inverse());
+    }
+
+    attachEvents() {
+        // Store bound functions as instance properties for cleanup
+        this.boundStart = (e) => {
+            if (this.currentStrokeIndex >= this.kanjiData.length) return; // Finished
+            e.preventDefault();
+            this.isDrawing = true;
+            this.currentPoints = [];
+            const pos = this.getPointerPos(e);
+            this.currentPoints.push(pos);
+
+            // Start visual path
+            this.currentPath = document.createElementNS("http://www.w3.org/2000/svg", "path");
+            this.currentPath.setAttribute("fill", "none");
+            this.currentPath.setAttribute("stroke", this.options.strokeColor);
+            this.currentPath.setAttribute("stroke-width", this.options.strokeWidth);
+            this.currentPath.setAttribute("stroke-linecap", "round");
+            this.currentPath.setAttribute("stroke-linejoin", "round");
+            this.currentPath.setAttribute("d", `M ${pos.x} ${pos.y}`);
+            this.currentGroup.appendChild(this.currentPath);
+        };
+
+        this.boundMove = (e) => {
+            if (!this.isDrawing) return;
+            e.preventDefault();
+            const pos = this.getPointerPos(e);
+            this.currentPoints.push(pos);
+
+            // Update visual path
+            const d = this.currentPath.getAttribute("d");
+            this.currentPath.setAttribute("d", `${d} L ${pos.x} ${pos.y}`);
+        };
+
+        this.boundEnd = (e) => {
+            if (!this.isDrawing) return;
+            this.isDrawing = false;
+            this.evaluateStroke();
+        };
+
+        this.svg.addEventListener('pointerdown', this.boundStart);
+        this.svg.addEventListener('pointermove', this.boundMove);
+        this.svg.addEventListener('pointerup', this.boundEnd);
+        this.svg.addEventListener('pointerleave', this.boundEnd);
+    }
+
+    /**
+     * Clean up resources and remove event listeners
+     * Call this before destroying the writer instance
+     * @public
+     */
+    destroy() {
+        if (this.svg && this.boundStart) {
+            this.svg.removeEventListener('pointerdown', this.boundStart);
+            this.svg.removeEventListener('pointermove', this.boundMove);
+            this.svg.removeEventListener('pointerup', this.boundEnd);
+            this.svg.removeEventListener('pointerleave', this.boundEnd);
+        }
+
+        // Clear all content
+        if (this.container) {
+            this.container.innerHTML = '';
+        }
+
+        // Clear references
+        this.boundStart = null;
+        this.boundMove = null;
+        this.boundEnd = null;
+        this.svg = null;
+        this.recognizer = null;
+    }
+
+    evaluateStroke() {
+        const targetD = this.kanjiData[this.currentStrokeIndex];
+        if (!targetD) return;
+
+        const result = this.recognizer.evaluate(this.currentPoints, targetD);
+        console.log("Evaluation result:", result);
+
+        if (result.success) {
+            this.onCorrect();
+        } else {
+            this.onIncorrect();
+        }
+    }
+
+    async onCorrect() {
+        // 1. Visual feedback on user stroke (Green)
+        this.currentPath.setAttribute("stroke", this.options.correctColor);
+
+        // 2. Fade out user stroke
+        const userPath = this.currentPath;
+        userPath.style.transition = "opacity 0.3s";
+        userPath.style.opacity = "0";
+        setTimeout(() => userPath.remove(), 300);
+
+        // 3. Animate the perfect stroke taking its place
+        const targetD = this.kanjiData[this.currentStrokeIndex];
+
+        // We block interaction briefly for the animation
+        this.isDrawing = false;
+
+        await this.animateStroke(targetD, {
+            duration: this.options.snapDuration, // Fast snap
+            color: this.options.strokeColor,
+            removeAfter: false,
+            targetGroup: this.drawnGroup
+        });
+
+        this.currentStrokeIndex++;
+        this.renderUpcomingStrokes();
+
+        if (this.currentStrokeIndex >= this.kanjiData.length) {
+            console.log("Kanji Complete!");
+            if (this.onComplete) this.onComplete();
+        }
+    }
+
+    onIncorrect() {
+        this.currentPath.setAttribute("stroke", this.options.incorrectColor);
+        // Fade out and remove
+        const pathRef = this.currentPath;
+        pathRef.style.transition = "opacity 0.5s";
+        setTimeout(() => { pathRef.style.opacity = "0"; }, 100);
+        setTimeout(() => { pathRef.remove(); }, 600);
+    }
+
+    /**
+     * Public API: Clear the canvas and reset progress
+     */
+    clear() {
+        this.currentStrokeIndex = 0;
+        this.drawnGroup.innerHTML = '';
+        this.currentGroup.innerHTML = '';
+        this.bgGroup.innerHTML = '';
+        this.renderUpcomingStrokes();
+        console.log("Canvas cleared");
+        if (this.onClear) this.onClear();
+    }
+
+    /**
+     * Public API: Update options
+     */
+    setOptions(newOptions) {
+        this.options = { ...this.options, ...newOptions };
+        this.renderUpcomingStrokes(); // Re-render to reflect changes (e.g. ghost visibility)
+        // Need to redraw grid if grid settings changed or toggled
+        this.gridGroup.innerHTML = '';
+        this.drawGrid();
+    }
+
+    /**
+     * Public API: Briefly show the next expected stroke
+     */
+    hint() {
+        if (this.currentStrokeIndex >= this.kanjiData.length) return;
+
+        const d = this.kanjiData[this.currentStrokeIndex];
+        if (!d) return;
+
+        this.animateStroke(d, {
+            duration: this.options.hintDuration,
+            color: this.options.hintColor,
+            strokeOpacity: "0.5",
+            removeAfter: true,
+            targetGroup: this.bgGroup
+        });
+    }
+
+    /**
+     * Public API: Animate the correct strokes
+     */
+    async animate() {
+        this.clear(); // Start fresh
+
+        // Disable interaction during animation
+        const originalPointerEvents = this.svg.style.pointerEvents;
+        this.svg.style.pointerEvents = "none";
+
+        for (let i = 0; i < this.kanjiData.length; i++) {
+            await this.animateStroke(this.kanjiData[i], {
+                duration: this.options.stepDuration,
+                color: this.options.strokeColor,
+                removeAfter: false,
+                targetGroup: this.drawnGroup
+            });
+        }
+
+        // Re-enable interaction
+        this.svg.style.pointerEvents = originalPointerEvents;
+        this.currentStrokeIndex = this.kanjiData.length; // Mark as done
+        if (this.onComplete) this.onComplete();
+    }
+
+    animateStroke(d, options = {}) {
+        const {
+            duration = 500,
+            color = "#333",
+            removeAfter = true,
+            strokeWidth = 4,
+            strokeOpacity = "1",
+            targetGroup = this.currentGroup
+        } = options;
+
+        return new Promise((resolve, reject) => {
+            try {
+                // Validate path data
+                if (!d || typeof d !== 'string') {
+                    throw new Error('Invalid path data: must be a non-empty string');
+                }
+
+                const path = document.createElementNS("http://www.w3.org/2000/svg", "path");
+                path.setAttribute("d", d);
+                path.setAttribute("fill", "none");
+                path.setAttribute("stroke", color);
+                path.setAttribute("stroke-width", strokeWidth);
+                path.setAttribute("stroke-opacity", strokeOpacity);
+                path.setAttribute("stroke-linecap", "round");
+                path.setAttribute("stroke-linejoin", "round");
+
+                targetGroup.appendChild(path);
+
+                const length = path.getTotalLength();
+
+                // Validate length
+                if (!length || length === 0 || isNaN(length)) {
+                    path.remove();
+                    throw new Error('Invalid path: unable to calculate length');
+                }
+
+                path.style.strokeDasharray = length;
+                path.style.strokeDashoffset = length; // Hidden initially
+
+                // Trigger reflow
+                path.getBoundingClientRect();
+
+                path.style.transition = `stroke-dashoffset ${duration}ms ease-in-out`;
+                path.style.strokeDashoffset = "0"; // Show
+
+                setTimeout(() => {
+                    if (removeAfter) {
+                        path.remove();
+                    }
+                    resolve(path);
+                }, duration + 50);
+
+            } catch (error) {
+                console.error('Animation error:', error);
+                // Dispatch error event for UI handling
+                if (this.container) {
+                    this.container.dispatchEvent(
+                        new CustomEvent('kanji:error', { detail: error })
+                    );
+                }
+                reject(error);
+            }
+        });
+    }
+}

package/src/StrokeRecognizer.js

@@ -0,0 +1,79 @@
+import { GeometryUtil } from './GeometryUtil.js';
+
+export class StrokeRecognizer {
+    constructor(options = {}) {
+        // Configuration options
+        this.options = {
+            passThreshold: 15,           // Average pixel deviation allowed for success
+            startDistThreshold: 40,      // Max pixels start point can be off
+            lengthRatioMin: 0.5,         // Minimum length ratio (user/target)
+            lengthRatioMax: 1.5,         // Maximum length ratio (user/target)
+            resamplingPoints: 64,        // Number of points to resample to
+            ...options
+        };
+
+        // Create or reuse hidden SVG container (singleton pattern)
+        if (!StrokeRecognizer.hiddenSVG) {
+            const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+            svg.style.position = 'absolute';
+            svg.style.visibility = 'hidden';
+            svg.style.width = '0';
+            svg.style.height = '0';
+            svg.setAttribute('aria-hidden', 'true');
+            document.body.appendChild(svg);
+            StrokeRecognizer.hiddenSVG = svg;
+        }
+
+        // Create measurement path and attach to DOM for reliable calculations
+        this.measurePath = document.createElementNS("http://www.w3.org/2000/svg", "path");
+        StrokeRecognizer.hiddenSVG.appendChild(this.measurePath);
+    }
+
+    /**
+     * Convert an SVG path data string (d attribute) into an array of points.
+     */
+    getPathPoints(dString, numPoints = null) {
+        // Use configured resampling points if not specified
+        const pointCount = numPoints !== null ? numPoints : this.options.resamplingPoints;
+
+        this.measurePath.setAttribute('d', dString);
+        const totalLength = this.measurePath.getTotalLength();
+        const points = [];
+
+        for (let i = 0; i < pointCount; i++) {
+            const point = this.measurePath.getPointAtLength((i / (pointCount - 1)) * totalLength);
+            points.push({ x: point.x, y: point.y });
+        }
+        return points;
+    }
+
+    /**
+     * Evaluate a user's stroke against the target kanji data.
+     * @param {Array<{x, y}>} userMsgPoints - Raw points from mouse/touch
+     * @param {string} targetD - The SVG path data of the *expected* next stroke
+     */
+    evaluate(userPoints, targetD) {
+        if (!userPoints || userPoints.length < 2) {
+            return { success: false, score: Infinity, message: "Too short" };
+        }
+
+        const targetPoints = this.getPathPoints(targetD);
+
+        // Check basic length ratio to prevent tiny ticks passing for long lines
+        const userLen = GeometryUtil.getPathLength(userPoints);
+        const targetLen = GeometryUtil.getPathLength(targetPoints);
+        const ratio = userLen / targetLen;
+
+        if (ratio < this.options.lengthRatioMin || ratio > this.options.lengthRatioMax) {
+            return { success: false, score: 100, message: "Length mismatch" };
+        }
+
+        const score = GeometryUtil.compareStrokes(userPoints, targetPoints, this.options.startDistThreshold);
+
+        return {
+            success: score < this.options.passThreshold,
+            score: score,
+            message: score < this.options.passThreshold ? "Good!" : "Try again"
+        };
+    }
+}

package/src/index.js

@@ -0,0 +1,4 @@
+export { KanjiWriter } from './KanjiWriter.js';
+export { StrokeRecognizer } from './StrokeRecognizer.js';
+export { GeometryUtil } from './GeometryUtil.js';
+export { KanjiVGParser } from './KanjiVGParser.js';