@gukhanmun/types 0.1.0-dev.16 → 0.1.0

package/README.md

@@ -1,10 +1,21 @@
 @gukhanmun/types
 ================
 
+[![JSR][JSR badge]][JSR]
+[![npm][npm badge]][npm]
+[![License: GPL-3.0-only][GPL badge]][GPL]
+
 TypeScript type declarations for the Gukhanmun JavaScript API. This package
 carries no runtime code; it exists so that both `@gukhanmun/wasm` and
 `@gukhanmun/napi` can share the same type definitions without duplicating them.
 
+[JSR badge]: https://jsr.io/badges/@gukhanmun/types
+[JSR]: https://jsr.io/@gukhanmun/types
+[npm badge]: https://img.shields.io/npm/v/@gukhanmun/types?logo=npm
+[npm]: https://www.npmjs.com/package/@gukhanmun/types
+[GPL badge]: https://img.shields.io/npm/l/%40gukhanmun%2Ftypes
+[GPL]: https://www.gnu.org/licenses/gpl-3.0.html
+
 
 Installation
 ------------

package/dist/index.d.ts

@@ -122,6 +122,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`.
@@ -220,7 +233,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.
@@ -323,13 +336,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` /
@@ -533,4 +555,4 @@ declare class GukhanmunError extends Error {
   }[];
 }
 //#endregion
-export { ContextWindow, DictionaryEntry, DictionarySource, Directives, ErrorCode, FileDictionarySource, Format, Gukhanmun, GukhanmunError, GukhanmunFactory, GukhanmunOptions, HtmlOptions, NumeralStrategy, OriginalGloss, Preset, Recovery, RenderMode, Segmentation, load };
+export { ContextWindow, DictionaryEntry, DictionarySource, Directives, ErrorCode, FileDictionarySource, Format, Gukhanmun, GukhanmunError, GukhanmunFactory, GukhanmunOptions, HomophoneDetection, HtmlOptions, NumeralStrategy, OriginalGloss, Preset, Recovery, RenderMode, Segmentation, load };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gukhanmun/types",
-  "version": "0.1.0-dev.16",
+  "version": "0.1.0",
   "description": "TypeScript API contract for Gukhanmun (type declarations only, no runtime code).",
   "type": "module",
   "exports": {