opencc-wasm 0.3.0 → 0.4.0

package/README.md

@@ -1,74 +1,330 @@
 # opencc-wasm
 
-This package provides a WebAssembly backend for OpenCC, fully compatible with the `opencc-js` public API. It bundles the OpenCC C++ core (plus marisa) compiled via Emscripten, plus the official OpenCC configs and prebuilt `.ocd2` dictionaries (placed under `dist/data/` at build time).
-License: Apache-2.0 (see LICENSE).
+[![npm version](https://img.shields.io/npm/v/opencc-wasm.svg)](https://www.npmjs.com/package/opencc-wasm)
+[![CDN](https://img.shields.io/badge/CDN-jsDelivr-orange.svg)](https://cdn.jsdelivr.net/npm/opencc-wasm@latest/dist/esm/index.js)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 
-## Features
-- Same API surface as `opencc-js`: `OpenCC.Converter`, `CustomConverter`, `ConverterFactory`, and locale presets.
-- No native bindings required; runs in Node.js and modern browsers (ESM), with a CommonJS build for legacy `require`.
-- On-demand loading of configs and dictionaries from the package’s `data/` directory into the Emscripten FS; each config/dict is cached after first use.
+[繁體中文](README.zh.md)
+
+> 🚀 **Out-of-the-box Chinese text conversion library** - 3 lines of code, auto-loads configs and dictionaries from CDN!
+
+WebAssembly port of OpenCC (Open Chinese Convert) with full API compatibility. Bundles the official OpenCC C++ core compiled via Emscripten, plus all official configs and prebuilt `.ocd2` dictionaries.
+
+**License:** Apache-2.0
+
+## ✨ Features
+
+- 🎯 **Zero Configuration** - Auto-loads all configs and dictionaries from CDN
+- 🔥 **3 Lines to Start** - Simplest API, just import and use
+- 🌐 **CDN Ready** - Use directly from jsDelivr/unpkg without bundler
+- 📦 **All-in-One** - Includes all 14+ official conversion types
+- ⚡ **Auto Caching** - Resources cached after first load
+- 🔧 **Full Compatibility** - Compatible with `opencc-js` API
+- 🚫 **No Native Bindings** - Pure WASM, cross-platform
+- 💻 **Universal** - Works in Node.js, browsers, Deno, etc.
+
+## 🚀 Quick Start
+
+### Browser (CDN - Zero Install!)
+
+```html
+<script type="module">
+  // 1. Import from CDN
+  import OpenCC from "https://cdn.jsdelivr.net/npm/opencc-wasm@0.4.0/dist/esm/index.js";
+
+  // 2. Create converter (auto-downloads everything!)
+  const converter = OpenCC.Converter({ from: "cn", to: "tw" });
+
+  // 3. Convert - Done!
+  const result = await converter("简体中文");
+  console.log(result);  // 簡體中文
+</script>
+```
+
+**That's it!** All configs and dictionaries are automatically downloaded from CDN.
+
+### CDN (Converter API)
+
+```javascript
+import OpenCC from "https://cdn.jsdelivr.net/npm/opencc-wasm@0.4.0/dist/esm/index.js";
+
+const converter = OpenCC.Converter({ from: "cn", to: "t" });
+const result = await converter("简体中文");
+console.log(result); // 簡體中文
+```
+
+Example source: `test/cdn-simple.mjs`
+
+### Node.js (NPM)
 
-## Installation
 ```bash
 npm install opencc-wasm
 ```
 
-## Usage
-```js
+```javascript
 import OpenCC from "opencc-wasm";
 
-// Convert Traditional Chinese (HK) to Simplified (CN)
-const converter = OpenCC.Converter({ from: "hk", to: "cn" });
-console.log(await converter("漢語")); // => 汉语
+const converter = OpenCC.Converter({ from: "cn", to: "tw" });
+const result = await converter("简体中文");
+console.log(result);  // 簡體中文
+```
+
+## 📖 API Reference
+
+### OpenCC.Converter() - Create Converter
+
+Two ways to specify conversions:
+
+#### Method 1: Using `config` parameter (Recommended)
+
+Directly specify OpenCC config file name:
+
+```javascript
+// Simplified → Traditional (Taiwan phrases)
+const converter = OpenCC.Converter({ config: "s2twp" });
+const result = await converter("服务器软件");  // 伺服器軟體
+```
+
+**Supported configs:**
+
+| Config | Description | Example |
+|--------|-------------|---------|
+| `s2t` | Simplified → Traditional | 简体 → 簡體 |
+| `s2tw` | Simplified → Taiwan | 软件 → 軟件 |
+| `s2twp` | Simplified → Taiwan (phrases) | 软件 → 軟體 |
+| `s2hk` | Simplified → Hong Kong | 打印机 → 打印機 |
+| `t2s` | Traditional → Simplified | 繁體 → 繁体 |
+| `t2tw` | Traditional → Taiwan | 台灣 → 臺灣 |
+| `t2hk` | Traditional → Hong Kong | 香港 → 香港 |
+| `t2jp` | Traditional → Japanese Shinjitai | 繁體 → 繁体 |
+| `tw2s` | Taiwan → Simplified | 軟體 → 软件 |
+| `tw2sp` | Taiwan → Simplified (phrases) | 滑鼠 → 鼠标 |
+| `tw2t` | Taiwan → Traditional | 臺灣 → 台灣 |
+| `hk2s` | Hong Kong → Simplified | 打印機 → 打印机 |
+| `hk2t` | Hong Kong → Traditional | 香港 → 香港 |
+| `jp2t` | Japanese Shinjitai → Traditional | 繁体 → 繁體 |
+| `t2cngov` | Traditional → CN Gov Standard | 潮溼 → 潮湿 |
+| `t2cngov_keep_simp` | Traditional → CN Gov (Keep Simp) | 简体繁體 → 简体繁體 |
 
-// Custom dictionary
-const custom = OpenCC.CustomConverter([
-  ["“", "「"],
-  ["”", "」"],
-  ["‘", "『"],
-  ["’", "』"],
+#### Method 2: Using `from`/`to` parameters (Legacy)
+
+Specify source and target locales:
+
+```javascript
+const converter = OpenCC.Converter({ from: "cn", to: "twp" });
+const result = await converter("服务器");  // 伺服器
+```
+
+**Locale codes:**
+
+| Code | Description |
+|------|-------------|
+| `cn` | Simplified Chinese (Mainland) |
+| `tw` | Traditional Chinese (Taiwan) |
+| `twp` | Taiwan with phrases |
+| `hk` | Traditional Chinese (Hong Kong) |
+| `t` | Traditional Chinese (general) |
+| `s` | Simplified Chinese (alias) |
+| `sp` | Simplified with phrases |
+| `jp` | Japanese Shinjitai |
+
+**Both methods work identically!** Choose what you prefer.
+
+### OpenCC.ConverterFactory() - With Custom Dictionary
+
+```javascript
+const converter = OpenCC.ConverterFactory(
+  "cn",        // from
+  "tw",        // to
+  [            // custom dictionaries
+    [["服务器", "伺服器"], ["文件", "檔案"]],
+    "網路 网络 | 檔案 文件"
+  ]
+);
+
+const result = await converter("服务器上的文件通过网络传输");
+// Output: 伺服器上的檔案通過網路傳輸
+```
+
+### OpenCC.CustomConverter() - Pure Custom Converter
+
+```javascript
+const converter = OpenCC.CustomConverter([
+  [""", "「"],
+  [""", "」"],
+  ["'", "『"],
+  ["'", "』"],
 ]);
-console.log(custom("悟空道：“师父又来了。怎么叫做‘水中捞月’？”"));
-// => 悟空道：「師父又來了。怎麼叫做『水中撈月』？」
+
+const result = converter("这是"引号"和'单引号'");
+// Output: 这是「引号」和『单引号』
+```
+
+## 💡 Usage Examples
+
+### React
+
+```jsx
+import { useState } from 'react';
+import OpenCC from 'opencc-wasm';
+
+function App() {
+  const [output, setOutput] = useState('');
+
+  const handleConvert = async () => {
+    const converter = OpenCC.Converter({ config: "s2tw" });
+    setOutput(await converter("简体中文"));
+  };
+
+  return (
+    <div>
+      <button onClick={handleConvert}>Convert</button>
+      <div>{output}</div>
+    </div>
+  );
+}
+```
+
+### Vue 3
+
+```vue
+<script setup>
+import { ref } from 'vue';
+import OpenCC from 'opencc-wasm';
+
+const output = ref('');
+
+async function handleConvert() {
+  const converter = OpenCC.Converter({ config: "s2tw" });
+  output.value = await converter("简体中文");
+}
+</script>
+
+<template>
+  <button @click="handleConvert">Convert</button>
+  <div>{{ output }}</div>
+</template>
 ```
 
-### Node (CommonJS)
-```js
-const OpenCC = require("opencc-wasm").default;
+### Node.js CLI
+
+```javascript
+#!/usr/bin/env node
+import OpenCC from 'opencc-wasm';
+
+const text = process.argv[2] || "简体中文";
+const converter = OpenCC.Converter({ config: "s2tw" });
+console.log(await converter(text));
 ```
 
-## Build
+### Web Worker
 
-The project uses a two-stage build process with semantic separation:
+```javascript
+// worker.js
+import OpenCC from 'opencc-wasm';
 
-### Stage 1: Build WASM (intermediate artifacts)
+let converters = {};
+
+self.onmessage = async (e) => {
+  const { config, text } = e.data;
+
+  if (!converters[config]) {
+    converters[config] = OpenCC.Converter({ config });
+  }
+
+  const result = await converters[config](text);
+  self.postMessage(result);
+};
+```
+
+```javascript
+// main.js
+const worker = new Worker('worker.js', { type: 'module' });
+
+worker.onmessage = (e) => {
+  console.log('Result:', e.data);
+};
+
+worker.postMessage({ config: 's2tw', text: '简体中文' });
+```
+
+## 🔧 Best Practices
+
+### ✅ Reuse Converter Instances
+
+```javascript
+// ✅ Good: Create once, use many times
+const converter = OpenCC.Converter({ config: "s2tw" });
+
+for (const text of manyTexts) {
+  await converter(text);  // Fast!
+}
+```
+
+```javascript
+// ❌ Avoid: Creating new instances every time
+for (const text of manyTexts) {
+  const converter = OpenCC.Converter({ config: "s2tw" });  // Slow!
+  await converter(text);
+}
+```
+
+### Multiple Converters (Auto-cached)
+
+```javascript
+// Create multiple converters (resources auto-cached)
+const s2t = OpenCC.Converter({ config: "s2t" });
+const s2tw = OpenCC.Converter({ config: "s2tw" });
+const t2s = OpenCC.Converter({ config: "t2s" });
+
+// Use independently
+console.log(await s2t("简体"));   // 簡體
+console.log(await s2tw("软件"));  // 軟體
+console.log(await t2s("繁體"));   // 繁体
+```
+
+### TypeScript
+
+```typescript
+import OpenCC from 'opencc-wasm';
+
+type ConfigName = 's2t' | 's2tw' | 's2twp' | 't2s';
+
+async function convert(config: ConfigName, text: string): Promise<string> {
+  const converter = OpenCC.Converter({ config });
+  return await converter(text);
+}
+
+const result = await convert('s2tw', '简体中文');
+```
+
+## 🏗️ Build
+
+The project uses a two-stage build process:
+
+### Stage 1: Build WASM
 
 ```bash
 ./build.sh
 ```
 
-Compiles OpenCC + marisa-trie to WASM and generates intermediate build artifacts in `build/`:
-- `build/opencc-wasm.esm.js` - ESM WASM glue (for tests/development)
-- `build/opencc-wasm.cjs` - CJS WASM glue (for tests/development)
+Compiles OpenCC + marisa-trie to WASM, outputs to `build/`:
+- `build/opencc-wasm.esm.js` - ESM WASM glue
+- `build/opencc-wasm.cjs` - CJS WASM glue
 - `build/opencc-wasm.wasm` - WASM binary
 
-**Semantic: `build/` = internal intermediate artifacts, not for publishing**
-
-### Stage 2: Build API wrappers (publishable dist)
+### Stage 2: Build API
 
 ```bash
 node scripts/build-api.js
 ```
 
 Generates publishable distribution in `dist/`:
-- Copies WASM artifacts from `build/` to `dist/esm/` and `dist/cjs/`
-- Transforms source `index.js` to `dist/esm/index.js` with production paths
-- Generates `dist/cjs/index.cjs` with CJS-compatible wrapper
+- Copies WASM files to `dist/esm/` and `dist/cjs/`
+- Transforms source to production paths
 - Copies data files to `dist/data/`
 
-**Semantic: `dist/` = publishable artifacts for npm**
-
-### Complete build
+### Complete Build
 
 ```bash
 npm run build
@@ -76,54 +332,101 @@ npm run build
 
 Runs both stages automatically.
 
-## Testing
+## 🧪 Testing
+
 ```bash
 npm test
 ```
 
-Tests import from source `index.js`, which references `build/` artifacts.
-This ensures tests validate the actual build output, not stale dist files.
-
-Runs the upstream OpenCC testcases (converted to JSON) against the WASM build.
+Runs the upstream OpenCC test cases against the WASM build.
 
-## Project Structure
+## 📁 Project Structure
 
 ```
 wasm-lib/
-├── build/              ← Intermediate WASM artifacts (gitignored, for tests)
-│   ├── opencc-wasm.esm.js
-│   ├── opencc-wasm.cjs
-│   └── opencc-wasm.wasm
-├── dist/               ← Publishable distribution (committed to git)
+├── build/              ← Intermediate WASM artifacts (gitignored)
+├── dist/               ← Publishable distribution (committed)
 │   ├── esm/
 │   │   ├── index.js
-│   │   └── opencc-wasm.js
+│   │   ├── opencc-wasm.js
+│   │   └── opencc-wasm.wasm
 │   ├── cjs/
 │   │   ├── index.cjs
-│   │   └── opencc-wasm.cjs
-│   ├── opencc-wasm.wasm
-│   └── data/           ← OpenCC config + dict files
-├── index.js            ← Source API (references build/ for tests)
+│   │   ├── opencc-wasm.cjs
+│   │   └── opencc-wasm.wasm
+│   └── data/           ← OpenCC configs + dicts
+├── index.js            ← Source API
 ├── index.d.ts          ← TypeScript definitions
 └── scripts/
-    └── build-api.js    ← Transforms build/ → dist/
+    └── build-api.js    ← Build script
 ```
 
-**Invariants:**
-- Tests import source (`index.js`) → loads from `build/`
-- Published package exports `dist/` only
-- `build/` = internal, `dist/` = publishable
+## ❓ FAQ
+
+**Q: Do configs and dicts auto-load or do I need to download them?**
+
+A: Auto-load! The high-level API (`OpenCC.Converter()`) automatically downloads everything from CDN.
+
+**Q: Does it re-download every time?**
+
+A: No! Resources are cached after first load.
+
+**Q: Works offline?**
+
+A: Yes! If installed via npm, all resources are bundled. For browsers, use Service Worker for offline caching.
+
+**Q: Which method to use: `config` or `from`/`to`?**
+
+A: Both work identically. Use `config` if you know OpenCC config names, or `from`/`to` for locale-based approach.
+
+**Q: Why is the first conversion slow?**
+
+A: Initial load downloads configs + dicts (~1-2MB). Subsequent conversions are fast (cached).
+
+## 📝 Notes
+
+- Uses persistent OpenCC handles to avoid reloading configs
+- Dictionaries stored in `/data/dict/` in virtual FS
+- Memory grows on demand (`ALLOW_MEMORY_GROWTH=1`)
+- Performance: Focuses on fidelity and compatibility with official OpenCC. May be slower than pure-JS implementations for raw throughput, but guarantees full OpenCC behavior.
+
+## 📜 Changelog
+
+### 0.4.0 - 2026-01-04
+
+**Added:**
+- `config` parameter in `Converter()` for direct OpenCC config names
+- New CN Government Standard conversions: `t2cngov`, `t2cngov_keep_simp`
+- New demo page and regression tests for new configs
+
+**Fixed:**
+- s2twp duplication bug (issue #950)
+- tw2sp `方程式` conversion regression and dictionary sync
+- Missing cngov configs/dicts in wasm-lib distribution
+
+### 0.3.0 - 2026-01-03
+
+**🚨 BREAKING: New Distribution Layout**
+
+`.wasm` files moved to be co-located with glue code:
+- `dist/esm/opencc-wasm.wasm` (was: `dist/opencc-wasm.esm.wasm`)
+- `dist/cjs/opencc-wasm.wasm` (was: `dist/opencc-wasm.cjs.wasm`)
+
+**Added:**
+- CDN support for direct browser usage
+- Comprehensive test suite
+- Auto-loading of configs and dictionaries
+
+### 0.2.1
+
+- Ship both wasm filenames for compatibility
+
+### 0.2.0
 
-## Notes
-- Internally uses persistent OpenCC handles (`opencc_create/convert/destroy`) to avoid reloading configs.
-- Dictionaries are written under `/data/dict/` in the virtual FS; configs under `/data/config/`. Paths inside configs are rewritten automatically.
-- Memory grows on demand (`ALLOW_MEMORY_GROWTH=1`); no native dependencies needed.
-- Performance note: opencc-wasm focuses on fidelity and compatibility (uses official configs and `.ocd2`, matches Node OpenCC output 1:1). Raw throughput can be slower than pure JS implementations like `opencc-js`, but the WASM version guarantees full OpenCC behavior and config coverage.
+- Rebuilt from OpenCC commit [`36c7cbbc`](https://github.com/frankslin/OpenCC/commit/36c7cbbc9702d2a46a89ea7a55ff8ba5656455df)
+- New dist layout with ESM/CJS separation
+- Tests rewritten using `node:test`
 
-## 0.2.1 changes
-- Ship both wasm filenames (`opencc-wasm.wasm` and `opencc-wasm.esm.wasm`) in `dist/` so either glue name resolves without patches; glues remain at `dist/esm/opencc-wasm.js` and `dist/cjs/opencc-wasm.cjs`.
+---
 
-## 0.2.0 changes
-- Conversion rules and bundled dictionaries are rebuilt from OpenCC commit [`36c7cbbc`](https://github.com/frankslin/OpenCC/commit/36c7cbbc9702d2a46a89ea7a55ff8ba5656455df). This aligns the WASM build with the upstream configs in that revision (including updated `.ocd2` data).
-- Output layout now mirrors the new `dist/` structure: ESM glue under `dist/esm/`, CJS glue under `dist/cjs/`, shared `opencc-wasm.wasm` at `dist/opencc-wasm.wasm`, and configs/dicts in `dist/data/`. Adjust your bundler/static hosting paths accordingly.
-- Tests are rewritten to use `node:test` with data-driven cases (`test/testcases.json`) instead of ad-hoc assertions, keeping coverage aligned with upstream OpenCC fixtures.
+**Made with ❤️ for the Chinese NLP community**

package/README.zh.md

@@ -0,0 +1,432 @@
+# opencc-wasm
+
+[![npm version](https://img.shields.io/npm/v/opencc-wasm.svg)](https://www.npmjs.com/package/opencc-wasm)
+[![CDN](https://img.shields.io/badge/CDN-jsDelivr-orange.svg)](https://cdn.jsdelivr.net/npm/opencc-wasm@latest/dist/esm/index.js)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+
+[English](README.md)
+
+> 🚀 **開箱即用的中文簡繁轉換程式庫** - 3 行程式碼搞定，自動從 CDN 載入設定和字典！
+
+OpenCC（Open Chinese Convert）的 WebAssembly 移植版本，完全相容原版 API。內建官方 OpenCC C++ 核心（透過 Emscripten 編譯），以及所有官方設定檔和預先建置的 `.ocd2` 字典檔。
+
+**授權條款：** Apache-2.0
+
+## ✨ 特色功能
+
+- 🎯 **零設定** - 自動從 CDN 載入所有設定檔和字典檔
+- 🔥 **3 行開始** - 最簡單的 API，匯入即用
+- 🌐 **CDN 就緒** - 可直接從 jsDelivr/unpkg 使用，無需打包工具
+- 📦 **一應俱全** - 包含所有 14+ 種官方轉換類型
+- ⚡ **自動快取** - 資源首次載入後自動快取
+- 🔧 **完全相容** - 相容 `opencc-js` API
+- 🚫 **無需原生綁定** - 純 WASM，跨平台
+- 💻 **通用支援** - 支援 Node.js、瀏覽器、Deno 等環境
+
+## 🚀 快速開始
+
+### 瀏覽器（CDN - 零安裝！）
+
+```html
+<script type="module">
+  // 1. 從 CDN 匯入
+  import OpenCC from "https://cdn.jsdelivr.net/npm/opencc-wasm@0.4.0/dist/esm/index.js";
+
+  // 2. 建立轉換器（自動下載所有資源！）
+  const converter = OpenCC.Converter({ from: "cn", to: "tw" });
+
+  // 3. 轉換 - 完成！
+  const result = await converter("简体中文");
+  console.log(result);  // 簡體中文
+</script>
+```
+
+**就是這麼簡單！** 所有設定檔和字典檔都會自動從 CDN 下載。
+
+### CDN（Converter API）
+
+```javascript
+import OpenCC from "https://cdn.jsdelivr.net/npm/opencc-wasm@0.4.0/dist/esm/index.js";
+
+const converter = OpenCC.Converter({ from: "cn", to: "t" });
+const result = await converter("简体中文");
+console.log(result); // 繁體中文
+```
+
+範例來源：`test/cdn-simple.mjs`
+
+### Node.js（NPM）
+
+```bash
+npm install opencc-wasm
+```
+
+```javascript
+import OpenCC from "opencc-wasm";
+
+const converter = OpenCC.Converter({ from: "cn", to: "tw" });
+const result = await converter("简体中文");
+console.log(result);  // 簡體中文
+```
+
+## 📖 API 參考
+
+### OpenCC.Converter() - 建立轉換器
+
+兩種方式指定轉換：
+
+#### 方式 1：使用 `config` 參數（推薦）
+
+直接指定 OpenCC 設定檔名稱：
+
+```javascript
+// 簡體 → 繁體（台灣慣用詞）
+const converter = OpenCC.Converter({ config: "s2twp" });
+const result = await converter("服务器软件");  // 伺服器軟體
+```
+
+**支援的設定檔：**
+
+| 設定檔 | 說明 | 範例 |
+|--------|------|------|
+| `s2t` | 簡體 → 繁體 | 简体 → 簡體 |
+| `s2tw` | 簡體 → 台灣正體 | 软件 → 軟件 |
+| `s2twp` | 簡體 → 台灣正體（慣用詞） | 软件 → 軟體 |
+| `s2hk` | 簡體 → 香港繁體 | 打印机 → 打印機 |
+| `t2s` | 繁體 → 簡體 | 繁體 → 繁体 |
+| `t2tw` | 繁體 → 台灣正體 | 台灣 → 臺灣 |
+| `t2hk` | 繁體 → 香港繁體 | 香港 → 香港 |
+| `t2jp` | 繁體 → 日文新字體 | 繁體 → 繁体 |
+| `tw2s` | 台灣 → 簡體 | 軟體 → 软件 |
+| `tw2sp` | 台灣 → 簡體（慣用詞） | 滑鼠 → 鼠标 |
+| `tw2t` | 台灣 → 繁體 | 臺灣 → 台灣 |
+| `hk2s` | 香港 → 簡體 | 打印機 → 打印机 |
+| `hk2t` | 香港 → 繁體 | 香港 → 香港 |
+| `jp2t` | 日文新字體 → 繁體 | 繁体 → 繁體 |
+| `t2cngov` | 繁體 → 大陸政府標準繁體 | 潮溼 → 潮湿 |
+| `t2cngov_keep_simp` | 繁體 → 大陸政府標準（保留簡體） | 简体繁體 → 简体繁體 |
+
+#### 方式 2：使用 `from`/`to` 參數（傳統）
+
+指定來源和目標語系：
+
+```javascript
+const converter = OpenCC.Converter({ from: "cn", to: "twp" });
+const result = await converter("服务器");  // 伺服器
+```
+
+**語系代碼：**
+
+| 代碼 | 說明 |
+|------|------|
+| `cn` | 簡體中文（中國大陸） |
+| `tw` | 繁體中文（台灣） |
+| `twp` | 台灣正體（含慣用詞） |
+| `hk` | 繁體中文（香港） |
+| `t` | 繁體中文（通用） |
+| `s` | 簡體中文（別名） |
+| `sp` | 簡體（含慣用詞） |
+| `jp` | 日文新字體 |
+
+**兩種方式功能完全相同！** 選擇您喜歡的即可。
+
+### OpenCC.ConverterFactory() - 含自訂字典的轉換器
+
+```javascript
+const converter = OpenCC.ConverterFactory(
+  "cn",        // from
+  "tw",        // to
+  [            // 自訂字典
+    [["服务器", "伺服器"], ["文件", "檔案"]],
+    "網路 网络 | 檔案 文件"
+  ]
+);
+
+const result = await converter("服务器上的文件通过网络传输");
+// 輸出：伺服器上的檔案通過網路傳輸
+```
+
+### OpenCC.CustomConverter() - 純自訂轉換器
+
+```javascript
+const converter = OpenCC.CustomConverter([
+  [""", "「"],
+  [""", "」"],
+  ["'", "『"],
+  ["'", "』"],
+]);
+
+const result = converter("这是"引号"和'单引号'");
+// 輸出：这是「引号」和『单引号』
+```
+
+## 💡 使用範例
+
+### React
+
+```jsx
+import { useState } from 'react';
+import OpenCC from 'opencc-wasm';
+
+function App() {
+  const [output, setOutput] = useState('');
+
+  const handleConvert = async () => {
+    const converter = OpenCC.Converter({ config: "s2tw" });
+    setOutput(await converter("简体中文"));
+  };
+
+  return (
+    <div>
+      <button onClick={handleConvert}>轉換</button>
+      <div>{output}</div>
+    </div>
+  );
+}
+```
+
+### Vue 3
+
+```vue
+<script setup>
+import { ref } from 'vue';
+import OpenCC from 'opencc-wasm';
+
+const output = ref('');
+
+async function handleConvert() {
+  const converter = OpenCC.Converter({ config: "s2tw" });
+  output.value = await converter("简体中文");
+}
+</script>
+
+<template>
+  <button @click="handleConvert">轉換</button>
+  <div>{{ output }}</div>
+</template>
+```
+
+### Node.js CLI 工具
+
+```javascript
+#!/usr/bin/env node
+import OpenCC from 'opencc-wasm';
+
+const text = process.argv[2] || "简体中文";
+const converter = OpenCC.Converter({ config: "s2tw" });
+console.log(await converter(text));
+```
+
+### Web Worker
+
+```javascript
+// worker.js
+import OpenCC from 'opencc-wasm';
+
+let converters = {};
+
+self.onmessage = async (e) => {
+  const { config, text } = e.data;
+
+  if (!converters[config]) {
+    converters[config] = OpenCC.Converter({ config });
+  }
+
+  const result = await converters[config](text);
+  self.postMessage(result);
+};
+```
+
+```javascript
+// main.js
+const worker = new Worker('worker.js', { type: 'module' });
+
+worker.onmessage = (e) => {
+  console.log('結果：', e.data);
+};
+
+worker.postMessage({ config: 's2tw', text: '简体中文' });
+```
+
+## 🔧 最佳實務
+
+### ✅ 重複使用轉換器實例
+
+```javascript
+// ✅ 好：建立一次，多次使用
+const converter = OpenCC.Converter({ config: "s2tw" });
+
+for (const text of manyTexts) {
+  await converter(text);  // 快！
+}
+```
+
+```javascript
+// ❌ 避免：每次都建立新實例
+for (const text of manyTexts) {
+  const converter = OpenCC.Converter({ config: "s2tw" });  // 慢！
+  await converter(text);
+}
+```
+
+### 多個轉換器（自動快取）
+
+```javascript
+// 建立多個轉換器（資源自動快取）
+const s2t = OpenCC.Converter({ config: "s2t" });
+const s2tw = OpenCC.Converter({ config: "s2tw" });
+const t2s = OpenCC.Converter({ config: "t2s" });
+
+// 獨立使用
+console.log(await s2t("简体"));   // 簡體
+console.log(await s2tw("软件"));  // 軟體
+console.log(await t2s("繁體"));   // 繁体
+```
+
+### TypeScript
+
+```typescript
+import OpenCC from 'opencc-wasm';
+
+type ConfigName = 's2t' | 's2tw' | 's2twp' | 't2s';
+
+async function convert(config: ConfigName, text: string): Promise<string> {
+  const converter = OpenCC.Converter({ config });
+  return await converter(text);
+}
+
+const result = await convert('s2tw', '简体中文');
+```
+
+## 🏗️ 建置
+
+專案使用兩階段建置流程：
+
+### 階段 1：建置 WASM
+
+```bash
+./build.sh
+```
+
+編譯 OpenCC + marisa-trie 成 WASM，輸出至 `build/`：
+- `build/opencc-wasm.esm.js` - ESM WASM 膠合程式
+- `build/opencc-wasm.cjs` - CJS WASM 膠合程式
+- `build/opencc-wasm.wasm` - WASM 二進位檔
+
+### 階段 2：建置 API
+
+```bash
+node scripts/build-api.js
+```
+
+產生可發佈的發行版至 `dist/`：
+- 複製 WASM 檔案至 `dist/esm/` 和 `dist/cjs/`
+- 轉換原始碼至生產環境路徑
+- 複製資料檔至 `dist/data/`
+
+### 完整建置
+
+```bash
+npm run build
+```
+
+自動執行兩個階段。
+
+## 🧪 測試
+
+```bash
+npm test
+```
+
+執行上游 OpenCC 測試案例來驗證 WASM 建置。
+
+## 📁 專案結構
+
+```
+wasm-lib/
+├── build/              ← 中間產物（gitignored）
+├── dist/               ← 可發佈版本（已提交）
+│   ├── esm/
+│   │   ├── index.js
+│   │   ├── opencc-wasm.js
+│   │   └── opencc-wasm.wasm
+│   ├── cjs/
+│   │   ├── index.cjs
+│   │   ├── opencc-wasm.cjs
+│   │   └── opencc-wasm.wasm
+│   └── data/           ← OpenCC 設定檔 + 字典
+├── index.js            ← 原始碼 API
+├── index.d.ts          ← TypeScript 型別定義
+└── scripts/
+    └── build-api.js    ← 建置腳本
+```
+
+## ❓ 常見問題
+
+**Q：設定檔和字典會自動載入嗎？還是需要我手動下載？**
+
+A：自動載入！高階 API（`OpenCC.Converter()`）會自動從 CDN 下載所有需要的檔案。
+
+**Q：每次轉換都會重新下載嗎？**
+
+A：不會！資源在首次載入後會快取起來。
+
+**Q：可以離線使用嗎？**
+
+A：可以！透過 npm 安裝時，所有資源都已包含在套件中。瀏覽器環境可使用 Service Worker 實現離線快取。
+
+**Q：應該用 `config` 還是 `from`/`to` 參數？**
+
+A：兩者功能完全相同。如果您熟悉 OpenCC 設定檔名稱，用 `config`；若偏好語系導向的方式，用 `from`/`to`。
+
+**Q：為什麼第一次轉換比較慢？**
+
+A：首次載入需要下載設定檔和字典檔（約 1-2MB）。後續轉換會很快（已快取）。
+
+## 📝 注意事項
+
+- 使用持久的 OpenCC 控制代碼避免重複載入設定
+- 字典儲存在虛擬檔案系統的 `/data/dict/` 中
+- 記憶體按需成長（`ALLOW_MEMORY_GROWTH=1`）
+- 效能：專注於精確度和與官方 OpenCC 的相容性。原始吞吐量可能比純 JavaScript 實作慢，但保證完整的 OpenCC 行為。
+
+## 📜 變更歷史
+
+### 0.4.0 - 2026-01-04
+
+**新增：**
+- `Converter()` 新增 `config` 參數，可直接使用 OpenCC 設定檔名稱
+- 新增中國政府規範字轉換：`t2cngov`、`t2cngov_keep_simp`
+- 新增示範頁與回歸測試，涵蓋新設定
+
+**修正：**
+- 修復 s2twp 重複字元問題（issue #950）
+- 修正 tw2sp `方程式` 轉換錯誤並同步字典
+- 補齊 wasm-lib 發行包中的 cngov 設定與字典
+
+### 0.3.0 - 2026-01-03
+
+**🚨 重大變更：新的發行版佈局**
+
+`.wasm` 檔案已移至與膠合程式同目錄：
+- `dist/esm/opencc-wasm.wasm`（舊：`dist/opencc-wasm.esm.wasm`）
+- `dist/cjs/opencc-wasm.wasm`（舊：`dist/opencc-wasm.cjs.wasm`）
+
+**新增：**
+- CDN 支援，可直接在瀏覽器中使用
+- 完整測試套件
+- 自動載入設定檔和字典檔
+
+### 0.2.1
+
+- 提供兩種 wasm 檔名以相容性
+
+### 0.2.0
+
+- 從 OpenCC commit [`36c7cbbc`](https://github.com/frankslin/OpenCC/commit/36c7cbbc9702d2a46a89ea7a55ff8ba5656455df) 重新建置
+- 新的 dist 佈局，ESM/CJS 分離
+- 測試改用 `node:test` 重寫
+
+---
+
+**用 ❤️ 為中文 NLP 社群打造**

package/dist/data/config/t2cngov.json

@@ -0,0 +1,29 @@
+{
+  "name": "Traditional Chinese to CN Government Standard",
+  "author": "TerryTian-tech",
+  "license": "Apache License 2.0",
+  "source": "https://github.com/TerryTian-tech/OpenCC-Traditional-Chinese-characters-according-to-Chinese-government-standards",
+  "contributors": ["TerryTian-tech", "Yi Jianpeng", "Hu Xinmei", "Duan Yatong"],
+  "reference": "《通用规范汉字表》(2013)",
+  "description": "Converts traditional Chinese (from various standards) to China's government standard traditional characters. Includes simplified-to-standard conversion for mixed documents.",
+
+  "segmentation": {
+    "type": "mmseg",
+    "dict": {
+      "type": "ocd2",
+      "file": "cngov/TGPhrases.ocd2"
+    }
+  },
+  "conversion_chain": [{
+    "dict": {
+      "type": "group",
+      "dicts": [{
+        "type": "ocd2",
+        "file": "cngov/TGPhrases.ocd2"
+      }, {
+        "type": "ocd2",
+        "file": "cngov/TGCharacters.ocd2"
+      }]
+    }
+  }]
+}

package/dist/data/config/t2cngov_keep_simp.json

@@ -0,0 +1,29 @@
+{
+  "name": "Traditional Chinese to CN Government Standard (Keep Simplified)",
+  "author": "TerryTian-tech",
+  "license": "Apache License 2.0",
+  "source": "https://github.com/TerryTian-tech/OpenCC-Traditional-Chinese-characters-according-to-Chinese-government-standards",
+  "contributors": ["TerryTian-tech", "Yi Jianpeng", "Hu Xinmei", "Duan Yatong"],
+  "reference": "《通用规范汉字表》(2013)",
+  "description": "Conservative conversion that preserves intentional simplified characters in mixed documents while standardizing traditional characters only.",
+
+  "segmentation": {
+    "type": "mmseg",
+    "dict": {
+      "type": "ocd2",
+      "file": "cngov/TGPhrases.ocd2"
+    }
+  },
+  "conversion_chain": [{
+    "dict": {
+      "type": "group",
+      "dicts": [{
+        "type": "ocd2",
+        "file": "cngov/TGPhrases.ocd2"
+      }, {
+        "type": "ocd2",
+        "file": "cngov/TGCharacters_keep_simp.ocd2"
+      }]
+    }
+  }]
+}

package/dist/esm/index.js

@@ -29,11 +29,37 @@ const readFileBuffer = (url) => {
 
 // 预设映射：from -> to -> config 文件名
 const CONFIG_MAP = {
-  cn: { t: "s2t.json", tw: "s2tw.json", hk: "s2hk.json", cn: null },
-  tw: { cn: "tw2s.json", t: "tw2t.json", tw: null },
-  hk: { cn: "hk2s.json", t: "hk2t.json", hk: null },
-  t: { cn: "t2s.json", tw: "t2tw.json", hk: "t2hk.json", jp: "t2jp.json", t: null },
-  jp: { t: "jp2t.json" },
+  cn: {
+    t: "s2t.json",
+    tw: "s2tw.json",
+    twp: "s2twp.json",  // 台湾惯用词
+    hk: "s2hk.json",
+    cn: null
+  },
+  tw: {
+    cn: "tw2s.json",
+    s: "tw2s.json",     // 别名
+    sp: "tw2sp.json",   // 简体惯用词
+    t: "tw2t.json",
+    tw: null
+  },
+  hk: {
+    cn: "hk2s.json",
+    s: "hk2s.json",     // 别名
+    t: "hk2t.json",
+    hk: null
+  },
+  t: {
+    cn: "t2s.json",
+    s: "t2s.json",      // 别名
+    tw: "t2tw.json",
+    hk: "t2hk.json",
+    jp: "t2jp.json",
+    t: null
+  },
+  jp: {
+    t: "jp2t.json"
+  },
 };
 
 // 缓存已加载的配置/字典与打开的句柄，避免重复加载和重复构建
@@ -158,7 +184,19 @@ function resolveConfig(from, to) {
 }
 
 function createConverter({ from, to, config }) {
-  const configName = config || resolveConfig(from, to);
+  // Support direct config name (e.g., "s2twp.json" or "s2twp")
+  let configName;
+
+  if (config) {
+    // Direct config parameter takes priority
+    configName = config.endsWith('.json') ? config : `${config}.json`;
+  } else if (from && to) {
+    // Legacy from/to parameters
+    configName = resolveConfig(from, to);
+  } else {
+    throw new Error('Either "config" or both "from" and "to" must be specified');
+  }
+
   return async (text) => {
     if (configName === null) return text; // no-op
     const handle = await ensureConfig(configName);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencc-wasm",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "WebAssembly backend for OpenCC with opencc-js compatible API and official configs/ocd2 dictionaries.",
   "keywords": [
     "opencc",