@gukhanmun/types 0.1.0-dev.16 → 0.1.0-dev.18

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`.
@@ -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-dev.18",
   "description": "TypeScript API contract for Gukhanmun (type declarations only, no runtime code).",
   "type": "module",
   "exports": {