@gukhanmun/napi 0.1.0-dev.16 → 0.1.0

package/README.md

@@ -1,10 +1,18 @@
 @gukhanmun/napi
 ===============
 
+[![npm][npm badge]][npm]
+[![License: GPL-3.0-only][GPL badge]][GPL]
+
 Node.js native addon implementation of the Gukhanmun hanja-to-hangul converter,
 built with napi-rs. Requires Node.js 20+. For environments other than Node.js
 (browsers, Deno, Bun via WASM), use `@gukhanmun/wasm` instead.
 
+[npm badge]: https://img.shields.io/npm/v/@gukhanmun/napi?logo=npm
+[npm]: https://www.npmjs.com/package/@gukhanmun/napi
+[GPL badge]: https://img.shields.io/npm/l/%40gukhanmun%2Fnapi
+[GPL]: https://www.gnu.org/licenses/gpl-3.0.html
+
 
 Installation
 ------------

package/dist/index.d.ts

@@ -123,6 +123,19 @@ type NumeralStrategy = "hangul-phonetic" | "positional-arabic" | "additive-arabi
  *   accuracy matters more than latency.
  */
 type ContextWindow = "off" | "per-block" | "per-section" | "per-document";
+/**
+ * Selects how the homophone marker decides that a reading needs its hanja shown
+ * in `rendering: "hangul-only"`.  Corresponds to Rust `HomophoneDetection`.
+ *
+ * - `"context-local"` — Gloss a reading only when a different-meaning homophone
+ *   actually appears within the {@link ContextWindow}.  This keeps hangul-only
+ *   output clean and is the default.
+ * - `"dictionary-wide"` — Also gloss readings shared by other hanja forms
+ *   anywhere in the dictionary, even when no homophone appears in the text.
+ *   With a large reference dictionary this glosses most Sino-Korean words; words
+ *   that should always be glossed are better expressed with `requireHanja`.
+ */
+type HomophoneDetection = "context-local" | "dictionary-wide";
 /**
  * Controls how the pipeline handles reader errors encountered during HTML
  * scanning.  Corresponds to Rust `Recovery`.
@@ -221,7 +234,7 @@ type DictionarySource = FileDictionarySource;
 interface HtmlOptions {
   /**
    * Class names whose containing element (and all descendants) should be
-   * treated as a preserved region — the engine skips their text content.
+   * treated as a preserved region—the engine skips their text content.
    *
    * Equivalent to passing `--html-preserve-class NAME` to the CLI one or
    * more times.
@@ -324,13 +337,22 @@ interface GukhanmunOptions {
   readonly initialSoundLaw?: boolean;
   /**
    * Context window for homophone disambiguation.  The `HomophoneMarker`
-   * middleware sets `homophone = true` on annotations whose hangul reading is
-   * shared by another hanja form within this window.  Defaults to
-   * `"per-block"`.
+   * middleware sets `homophone = true` on annotations whose hangul reading
+   * collides within this window.  Defaults to `"per-block"`.
    *
    * @see {@link ContextWindow}
    */
   readonly homophoneWindow?: ContextWindow;
+  /**
+   * Strategy that decides which readings count as homophones needing a hanja
+   * gloss.  Defaults to `"context-local"`, which glosses a reading only when a
+   * different-meaning homophone appears within {@link homophoneWindow}.  Use
+   * `"dictionary-wide"` to also gloss readings shared by other dictionary
+   * entries.
+   *
+   * @see {@link HomophoneDetection}
+   */
+  readonly homophoneDetection?: HomophoneDetection;
   /**
    * Context window for first-occurrence filtering.  The
    * `FirstOccurrenceFilter` middleware clears `requireHanja` /
@@ -571,4 +593,4 @@ declare class GukhanmunError extends Error {
  */
 declare function load(options?: GukhanmunOptions): Promise<Gukhanmun>;
 //#endregion
-export { type ContextWindow, type DictionaryEntry, type DictionarySource, type Directives, type ErrorCode, type FileDictionarySource, type Format, type Gukhanmun, GukhanmunError, type GukhanmunFactory, type GukhanmunOptions, type HtmlOptions, type NumeralStrategy, type OriginalGloss, type Preset, type Recovery, type RenderMode, type Segmentation, load };
+export { type ContextWindow, type DictionaryEntry, type DictionarySource, type Directives, type ErrorCode, type FileDictionarySource, type Format, type Gukhanmun, GukhanmunError, type GukhanmunFactory, type GukhanmunOptions, type HomophoneDetection, type HtmlOptions, type NumeralStrategy, type OriginalGloss, type Preset, type Recovery, type RenderMode, type Segmentation, load };

package/dist/index.js

@@ -13,7 +13,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 * locally with `mise run napi-build`.
 *
 * The `load()` factory is asynchronous for API uniformity with the WASM
-* backend, but the native addon is synchronously ready — dictionary data is
+* backend, but the native addon is synchronously ready—dictionary data is
 * the only async part.
 *
 * @example
@@ -45,19 +45,22 @@ function detectPlatformPackage() {
 /**
 * Loads the native addon at module initialisation time.
 *
-* When installed from npm the platform-specific optional dependency is tried
-* first.  Falls back to a locally-built binary (produced by
-* `mise run napi-build`) for development.
+* A locally-built binary (produced by `mise run napi-build`) is tried first so
+* development and CI exercise the freshly compiled addon; a stale platform
+* optional-dependency binary must never shadow it.  A published install ships
+* only `dist/` (see the package `files` field), so no local binary is present
+* there and resolution falls through to the platform-specific optional
+* dependency.
 */
 const nativeAddon = (() => {
 	const req = createRequire(import.meta.url);
 	try {
-		return req(detectPlatformPackage());
+		return req("./gukhanmun_napi.node");
 	} catch {
 		try {
-			return req("./gukhanmun_napi.node");
-		} catch {
 			return req("../gukhanmun_napi.node");
+		} catch {
+			return req(detectPlatformPackage());
 		}
 	}
 })();
@@ -154,6 +157,7 @@ function resolveOptions(opts = {}) {
 		numerals: opts.numerals ?? "hangul-phonetic",
 		initialSoundLaw: opts.initialSoundLaw ?? (koKp ? false : true),
 		homophoneWindow: opts.homophoneWindow ?? (koKp ? "off" : "per-block"),
+		homophoneDetection: opts.homophoneDetection ?? "context-local",
 		firstOccurrenceWindow: opts.firstOccurrenceWindow ?? "off",
 		recovery: opts.recovery ?? "strict"
 	};
@@ -166,6 +170,7 @@ function buildRawOptions(opts, resolved) {
 		numerals: resolved.numerals,
 		initialSoundLaw: resolved.initialSoundLaw,
 		homophoneWindow: resolved.homophoneWindow,
+		homophoneDetection: resolved.homophoneDetection,
 		firstOccurrenceWindow: resolved.firstOccurrenceWindow,
 		recovery: resolved.recovery
 	};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gukhanmun/napi",
-  "version": "0.1.0-dev.16",
+  "version": "0.1.0",
   "description": "Node.js native addon (napi-rs) for the Gukhanmun hanja-to-hangul converter.",
   "type": "module",
   "exports": {
@@ -14,12 +14,12 @@
     "dist"
   ],
   "optionalDependencies": {
-    "@gukhanmun/napi-aarch64-apple-darwin": "0.1.0-dev.16+395401fa8b3429703127c66d1db02c435606d87b",
-    "@gukhanmun/napi-x86_64-apple-darwin": "0.1.0-dev.16+395401fa8b3429703127c66d1db02c435606d87b",
-    "@gukhanmun/napi-x86_64-pc-windows-msvc": "0.1.0-dev.16+395401fa8b3429703127c66d1db02c435606d87b",
-    "@gukhanmun/napi-aarch64-pc-windows-msvc": "0.1.0-dev.16+395401fa8b3429703127c66d1db02c435606d87b",
-    "@gukhanmun/napi-aarch64-unknown-linux-gnu": "0.1.0-dev.16+395401fa8b3429703127c66d1db02c435606d87b",
-    "@gukhanmun/napi-x86_64-unknown-linux-gnu": "0.1.0-dev.16+395401fa8b3429703127c66d1db02c435606d87b"
+    "@gukhanmun/napi-x86_64-apple-darwin": "0.1.0",
+    "@gukhanmun/napi-x86_64-pc-windows-msvc": "0.1.0",
+    "@gukhanmun/napi-aarch64-apple-darwin": "0.1.0",
+    "@gukhanmun/napi-aarch64-unknown-linux-gnu": "0.1.0",
+    "@gukhanmun/napi-aarch64-pc-windows-msvc": "0.1.0",
+    "@gukhanmun/napi-x86_64-unknown-linux-gnu": "0.1.0"
   },
   "homepage": "https://github.com/dahlia/gukhanmun",
   "bugs": "https://github.com/dahlia/gukhanmun/issues",
@@ -52,7 +52,7 @@
     "@gukhanmun/types": "*"
   },
   "devDependencies": {
-    "@gukhanmun/types": "0.1.0-dev.16+395401fa8b3429703127c66d1db02c435606d87b"
+    "@gukhanmun/types": "0.1.0"
   },
   "scripts": {
     "build": "tsdown"