opencc-wasm 0.6.3 → 0.8.0

package/README.md

@@ -73,17 +73,35 @@ const converter = OpenCC.Converter({ config: "s2twp" });
 const result = await converter("服务器软件");  // 伺服器軟體
 ```
 
+`Converter()` also exposes an inspection helper:
+
+```javascript
+const converter = OpenCC.Converter({ config: "s2twp" });
+const inspected = await converter.inspect("勇敢的士兵");
+console.log(inspected.segments); // Segmentation result
+console.log(inspected.stages);   // Per-stage conversion output
+console.log(inspected.output);   // Final converted output
+```
+
+The same API also works with the CN Government Standard Jieba configs:
+
+```javascript
+const converter = OpenCC.Converter({ config: "t2cngov_jieba" });
+console.log(await converter("測試简体混繁體")); // 測試簡體混繁體
+
+const keepSimp = OpenCC.Converter({ config: "t2cngov_keep_simp_jieba" });
+console.log(await keepSimp("測試简体混繁體")); // 測試简体混繁體
+```
+
 **Supported configs:**
 
 | Config | Description | Example |
 |--------|-------------|---------|
 | `s2twp` | Simplified → Taiwan Traditional (with regional phrases) | 软件 → 軟體 |
-| `s2twp_jieba` | Simplified → Taiwan Traditional (jieba segmentation) | 城堡的士兵 → 城堡的士兵 |
 | `s2tw` | Simplified → Taiwan Traditional | 心里 → 心裡 |
 | `s2hk` | Simplified → Hong Kong Traditional | 心里  → 心裏 |
 | `s2t` | Simplified → OpenCC Standard Traditional | 简体 → 簡體 |
 | `tw2sp` | Taiwan → Simplified (with regional phrases) | 滑鼠 → 鼠标 |
-| `tw2sp_jieba` | Taiwan → Simplified (jieba segmentation) | 慰藉著 → 慰藉着 |
 | `tw2s` | Taiwan → Simplified | 軟體 → 软件 |
 | `tw2t` | Taiwan → Traditional | 吃飯 → 喫飯 |
 | `hk2s` | Hong Kong → Simplified | 打印機 → 打印机 |
@@ -95,6 +113,8 @@ const result = await converter("服务器软件");  // 伺服器軟體
 | `t2jp` | Traditional → Japanese Shinjitai | 櫻花 → 桜花 |
 | `t2cngov` | Traditional → CN Gov Standard | 潮溼 → 潮湿 |
 | `t2cngov_keep_simp` | Traditional → CN Gov (Keep Simp) | 简体繁體 → 简体繁體 |
+| `t2cngov_jieba` | Traditional → CN Gov Standard (Jieba segmentation) | 測試简体混繁體 → 測試簡體混繁體 |
+| `t2cngov_keep_simp_jieba` | Traditional → CN Gov (Keep Simp, Jieba segmentation) | 測試简体混繁體 → 測試简体混繁體 |
 
 #### Method 2: Using `from`/`to` parameters (compatible with `opencc-js`)
 
@@ -278,7 +298,7 @@ console.log(await t2s("繁體"));   // 繁体
 ```typescript
 import OpenCC from 'opencc-wasm';
 
-type ConfigName = 's2t' | 's2tw' | 's2twp' | 's2twp_jieba' | 't2s' | 'tw2sp_jieba';
+type ConfigName = 's2t' | 's2tw' | 's2twp' | 't2s';
 
 async function convert(config: ConfigName, text: string): Promise<string> {
   const converter = OpenCC.Converter({ config });
@@ -344,7 +364,7 @@ wasm-lib/
 │   │   ├── index.cjs
 │   │   ├── opencc-wasm.cjs
 │   │   └── opencc-wasm.wasm
-│   └── data/           ← OpenCC configs + dicts (+ jieba files if enabled)
+│   └── data/           ← OpenCC configs + dicts
 ├── index.js            ← Source API
 ├── index.d.ts          ← TypeScript definitions
 └── scripts/
@@ -377,12 +397,30 @@ A: Initial load downloads configs + dicts (~1-2MB). Subsequent conversions are f
 
 - Uses persistent OpenCC handles to avoid reloading configs
 - Dictionaries stored in `/data/dict/` in virtual FS
-- Jieba assets stored in `/data/jieba_dict/` (dict, hmm_model, user dict, idf, stop_words)
 - 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.8.0 - 2026-04-22
+
+- Added `converter.inspect(text)` to the WASM API, returning segmentation, per-stage conversion output, and the final output as structured JSON
+- Exposed the new inspect entry point from the Emscripten module and regenerated publishable `dist/` artifacts
+- Added typings, tests, and documentation for the inspect workflow
+
+### 0.7.0 - 2026-04-13
+
+- Rebased the wasm branch onto upstream `master`
+- Switched WASM Jieba support to reuse the upstream plugin implementation
+- Registered the Jieba plugin statically inside the WASM module instead of using dynamic loading
+- Restored bundled Jieba configs, dictionaries, and comparison tests in `wasm-lib` / `dist`
+- Regenerated release artifacts and revalidated the full Node test suite
+
+### 0.6.3 - 2026-03-31
+
+- Upstream alignment and cngov dictionary refresh
+- Rebuilt publishable `dist/` artifacts after the dictionary sync
+
 ### 0.6.0 - 2026-01-17
 
 - Added Jieba segmentation support (cppjieba) for improved phrase handling

package/README.zh.md

@@ -73,17 +73,35 @@ const converter = OpenCC.Converter({ config: "s2twp" });
 const result = await converter("服务器软件");  // 伺服器軟體
 ```
 
+`Converter()` 也提供 inspect 輔助方法：
+
+```javascript
+const converter = OpenCC.Converter({ config: "s2twp" });
+const inspected = await converter.inspect("勇敢的士兵");
+console.log(inspected.segments); // 分詞結果
+console.log(inspected.stages);   // 每一階段的轉換結果
+console.log(inspected.output);   // 最終輸出
+```
+
+同樣的 API 也可直接用在大陸政府標準繁體的 Jieba 設定：
+
+```javascript
+const converter = OpenCC.Converter({ config: "t2cngov_jieba" });
+console.log(await converter("測試简体混繁體")); // 測試簡體混繁體
+
+const keepSimp = OpenCC.Converter({ config: "t2cngov_keep_simp_jieba" });
+console.log(await keepSimp("測試简体混繁體")); // 測試简体混繁體
+```
+
 **支援的設定檔：**
 
 | 設定檔 | 說明 | 範例 |
 |--------|------|------|
 | `s2twp` | 簡體 → 台灣正體（含地域用詞轉換） | 軟體 → 軟體 |
-| `s2twp_jieba` | 簡體 → 台灣正體（jieba 分詞） | 城堡的士兵 → 城堡的士兵 |
 | `s2tw` | 簡體 → 台灣正體 | 心里 → 心裡 |
 | `s2hk` | 簡體 → 香港繁體 | 心里  → 心裏 |
 | `s2t` | 簡體 → OpenCC 標準繁體 | 简体 → 簡體 |
 | `tw2sp` | 台灣正體 → 簡體（含地域用詞轉換） | 滑鼠 → 鼠标 |
-| `tw2sp_jieba` | 台灣正體 → 簡體（jieba 分詞） | 慰藉著 → 慰藉着 |
 | `tw2s` | 台灣正體 → 簡體 | 軟體 → 软件 |
 | `tw2t` | 台灣正體 → OpenCC 標準繁體 | 吃飯 → 喫飯 |
 | `hk2s` | 香港繁體 → 簡體 | 打印機 → 打印机 |
@@ -95,6 +113,8 @@ const result = await converter("服务器软件");  // 伺服器軟體
 | `t2jp` | 日文舊字體 → 日文新字體 | 櫻花 → 桜花 |
 | `t2cngov` | 繁體 → 大陸政府標準繁體 | 潮溼 → 潮湿 |
 | `t2cngov_keep_simp` | 繁體 → 大陸政府標準繁體（保留簡體） | 简体繁體 → 简体繁體 |
+| `t2cngov_jieba` | 繁體 → 大陸政府標準繁體（Jieba 分詞） | 測試简体混繁體 → 測試簡體混繁體 |
+| `t2cngov_keep_simp_jieba` | 繁體 → 大陸政府標準繁體（保留簡體，Jieba 分詞） | 測試简体混繁體 → 測試简体混繁體 |
 
 #### 方式 2：使用 `from`/`to` 參數（与 `opencc-js` 相容）
 
@@ -278,7 +298,7 @@ console.log(await t2s("繁體"));   // 繁体
 ```typescript
 import OpenCC from 'opencc-wasm';
 
-type ConfigName = 's2t' | 's2tw' | 's2twp' | 's2twp_jieba' | 't2s' | 'tw2sp_jieba';
+type ConfigName = 's2t' | 's2tw' | 's2twp' | 't2s';
 
 async function convert(config: ConfigName, text: string): Promise<string> {
   const converter = OpenCC.Converter({ config });
@@ -377,12 +397,30 @@ A：首次載入需要下載設定檔和字典檔（約 1-2MB）。後續轉換
 
 - 使用持久的 OpenCC 控制代碼避免重複載入設定
 - 字典儲存在虛擬檔案系統的 `/data/dict/` 中
-- Jieba 資產儲存在 `/data/jieba_dict/`（詞典、hmm_model、user dict、idf、stop_words）
 - 記憶體按需成長（`ALLOW_MEMORY_GROWTH=1`）
 - 效能：專注於精確度和與官方 OpenCC 的相容性。原始吞吐量可能比純 JavaScript 實作慢，但保證完整的 OpenCC 行為。
 
 ## 📜 變更歷史
 
+### 0.8.0 - 2026-04-22
+
+- 在 WASM API 中新增 `converter.inspect(text)`，可回傳分詞結果、每個階段的轉換輸出，以及最終輸出的結構化 JSON
+- 從 Emscripten 模組匯出新的 inspect 入口，並重新產生可發布的 `dist/` 產物
+- 補上 inspect 流程的型別、測試與文件
+
+### 0.7.0 - 2026-04-13
+
+- 將 wasm 分支重新 rebase 到 upstream `master`
+- WASM 的 Jieba 支援改為直接復用上游插件實作
+- 在 WASM 模組內靜態註冊 Jieba 插件，不再依賴動態載入
+- 在 `wasm-lib` / `dist` 中重新納入 Jieba 設定、詞典與對照測試
+- 重新產生發行產物並完整驗證 Node 測試套件
+
+### 0.6.3 - 2026-03-31
+
+- 與上游狀態對齊並同步 cngov 詞典
+- 在字典同步後重新產生可發布的 `dist/` 產物
+
 ### 0.6.0 - 2026-01-17
 
 - 新增 Jieba 分詞支援（cppjieba）以改善詞組切分效果

package/dist/cjs/index.cjs

@@ -18,6 +18,7 @@ const CONFIG_MAP = {
 
 const loadedConfigs = new Set();
 const loadedDicts = new Set();
+const loadedResources = new Set();
 const handles = new Map();
 let modulePromise = null;
 let api = null;
@@ -37,6 +38,7 @@ async function getApi() {
     api = {
       create: mod.cwrap("opencc_create", "number", ["string"]),
       convert: mod.cwrap("opencc_convert", "string", ["number", "string"]),
+      inspect: mod.cwrap("opencc_inspect", "string", ["number", "string"]),
       destroy: mod.cwrap("opencc_destroy", null, ["number"]),
     };
   }
@@ -59,6 +61,19 @@ function collectOcd2Files(node, acc) {
   }
 }
 
+function collectSegmentationResources(segmentation, acc) {
+  if (!segmentation || typeof segmentation !== "object") return;
+  const resources = segmentation.resources;
+  if (!resources || typeof resources !== "object") return;
+  Object.values(resources).forEach((value) => {
+    if (typeof value === "string" && value) acc.add(value);
+  });
+  if (segmentation.type === "jieba") {
+    acc.add("jieba_dict/idf.utf8");
+    acc.add("jieba_dict/stop_words.utf8");
+  }
+}
+
 async function fetchText(urlObj) {
   if (urlObj.protocol === "file:") return readFileText(urlObj);
   const resp = await fetch(urlObj.href);
@@ -81,7 +96,9 @@ async function ensureConfig(configName) {
   const cfgJson = JSON.parse(await fetchText(cfgUrl));
 
   const dicts = new Set();
+  const resources = new Set();
   collectOcd2Files(cfgJson.segmentation?.dict, dicts);
+  collectSegmentationResources(cfgJson.segmentation, resources);
   if (Array.isArray(cfgJson.conversion_chain)) {
     cfgJson.conversion_chain.forEach((item) => collectOcd2Files(item?.dict, dicts));
   }
@@ -94,6 +111,15 @@ async function ensureConfig(configName) {
     mod.FS.writeFile(dictPath, buf);
     loadedDicts.add(file);
   }
+  for (const file of resources) {
+    if (loadedResources.has(file)) continue;
+    const resourceUrl = new URL("../data/" + file, BASE_URL);
+    const buf = await fetchBuffer(resourceUrl);
+    const resourcePath = "/data/" + file;
+    ensureParentDir(mod, resourcePath);
+    mod.FS.writeFile(resourcePath, buf);
+    loadedResources.add(file);
+  }
   const patchPaths = (node) => {
     if (!node || typeof node !== "object") return;
     if (node.type === "ocd2" && node.file) node.file = "/data/dict/" + node.file;
@@ -121,7 +147,16 @@ function resolveConfig(from, to) {
 }
 
 function createConverter({ from, to, config }) {
-  const configName = config || resolveConfig(from, to);
+  let configName;
+
+  if (config) {
+    configName = config.endsWith(".json") ? config : `${config}.json`;
+  } else if (from && to) {
+    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;
     const handle = await ensureConfig(configName);
@@ -130,6 +165,32 @@ function createConverter({ from, to, config }) {
   };
 }
 
+function createInspector({ from, to, config }) {
+  let configName;
+
+  if (config) {
+    configName = config.endsWith(".json") ? config : `${config}.json`;
+  } else if (from && to) {
+    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 {
+        input: text,
+        segments: text.length === 0 ? [] : [text],
+        stages: [],
+        output: text,
+      };
+    }
+    const handle = await ensureConfig(configName);
+    const { api: apiFns } = await getApi();
+    return JSON.parse(apiFns.inspect(handle, text));
+  };
+}
+
 function CustomConverter(dictOrString) {
   let pairs = [];
   if (typeof dictOrString === "string") {
@@ -168,7 +229,10 @@ function ConverterFactory(fromLocale, toLocale, extraDicts = []) {
 const OpenCC = {
   Converter(opts) {
     const fn = createConverter(opts);
-    return (text) => fn(text);
+    const inspect = createInspector(opts);
+    const converter = (text) => fn(text);
+    converter.inspect = (text) => inspect(text);
+    return converter;
   },
   CustomConverter,
   ConverterFactory,