# Gukhanmun

## Playground

- [Playground](/playground.md): Interactive demo for converting mixed-script Korean (國漢文混用體) to hangul in real time. Supports plain text, Markdown, and HTML input, with configurable rendering modes and options.

## Guide

- [Introduction](/guide/intro.md): An overview of Gukhanmun and how to choose between the CLI, Rust, and
JavaScript interfaces.
- [Installation](/guide/cli/install.md): How to install the Gukhanmun command-line tool.
- [Quick start](/guide/cli/start.md): Basic usage of the Gukhanmun command-line tool.
- [Dictionaries](/guide/cli/dictionary.md): Using the bundled dictionary and loading custom dictionaries from the CLI.
- [Conversion options](/guide/cli/conversion.md): Flags that control how Gukhanmun converts hanja to hangul.
- [Rendering modes](/guide/cli/rendering.md): How to control how Gukhanmun presents hanja and their hangul readings in the output.
- [Directives](/guide/cli/directives.md): Per-hanja overrides that force or suppress annotations for specific characters.
- [HTML processing](/guide/cli/html.md): How Gukhanmun handles HTML input and which elements it always skips.
- [Markdown processing](/guide/cli/markdown.md): How Gukhanmun converts Markdown documents, including selected YAML front
matter fields.
- [Installation](/guide/rust/install.md): Adding Gukhanmun as a Rust dependency.
- [Quick start](/guide/rust/start.md): Basic usage of the Gukhanmun Rust library.
- [Dictionaries](/guide/rust/dictionary.md): Loading and composing dictionaries in the Gukhanmun Rust library.
- [Conversion options](/guide/rust/conversion.md): Builder methods that control how Gukhanmun converts hanja to hangul.
- [Rendering modes](/guide/rust/rendering.md): Controlling how Gukhanmun presents hanja and hangul readings in Rust.
- [Directives](/guide/rust/directives.md): Per-hanja annotation overrides in the Gukhanmun Rust library.
- [Markdown conversion](/guide/rust/markdown.md): Converting Markdown documents with the Gukhanmun Rust library.
- [HTML conversion](/guide/rust/html.md): Converting HTML documents with the Gukhanmun Rust library.
- [Streaming API](/guide/rust/streaming.md): Processing large documents incrementally with Gukhanmun's iterator API.
- [Installation](/guide/javascript/install.md): Installing Gukhanmun for JavaScript, TypeScript, Node.js, Deno, and browsers.
- [Quick start](/guide/javascript/start.md): Basic usage of the Gukhanmun JavaScript library.
- [Dictionaries](/guide/javascript/dictionary.md): Loading and using dictionaries with the Gukhanmun JavaScript library.
- [Conversion options](/guide/javascript/conversion.md): Options that control how Gukhanmun converts hanja to hangul in JavaScript.
- [Rendering modes](/guide/javascript/rendering.md): Controlling how Gukhanmun presents hanja and hangul readings in JavaScript.
- [Directives](/guide/javascript/directives.md): Per-hanja annotation overrides in the Gukhanmun JavaScript library.
- [Markdown conversion](/guide/javascript/markdown.md): Converting Markdown documents with the Gukhanmun JavaScript library.
- [HTML processing](/guide/javascript/html.md): Converting HTML and preserving specific elements in the Gukhanmun JavaScript library.
- [Streaming API](/guide/javascript/streaming.md): Processing large documents chunk by chunk with Gukhanmun's TransformStream API.

## References

- [API references](/api/index.md): Gukhanmun provides two sets of APIs: one is for Rust, and the other is for JavaScript.
- [Changelog](/api/changelog.md)
- [Gukhanmun](/api/js/index.md)
- [Class: GukhanmunError](/api/js/classes/_gukhanmun_napi.GukhanmunError.md): Error thrown by {@link load}, {@link Gukhanmun.convert}, and {@link Gukhanmun.stream} when the Rust engine reports a failure. code identifies the failure class; chain carries the full causal chain materialised at the FFI boundary so callers do not need additional round trips.
- [Class: GukhanmunError](/api/js/classes/_gukhanmun_types.GukhanmunError.md): Error class thrown by all Gukhanmun operations. Declared here as a declare class so this package remains purely type-level.  The actual class (with identical shape) is provided by each runtime package (@gukhanmun/wasm and @gukhanmun/napi). The chain property exposes the Rust Error::source() chain materialised at the FFI boundary, allowing callers to inspect underlying causes without additional FFI calls.
- [Class: GukhanmunError](/api/js/classes/_gukhanmun_wasm.GukhanmunError.md): Error thrown by {@link load}, {@link Gukhanmun.convert}, and {@link Gukhanmun.stream} when the Rust engine reports a failure. code identifies the failure class; chain carries the full causal chain materialised at the FFI boundary so callers do not need additional round trips.
- [Function: load()](/api/js/functions/_gukhanmun_napi.load.md): load(options?): Promise<Gukhanmun> Creates a Gukhanmun converter with the given options. The native addon is synchronously ready; dictionaries supplied via {@link GukhanmunOptions.dictionaries} are fetched or read from disk and passed to the Rust engine as FileDictionarySource values. Note: unlike the Rust ko-kr preset, the JavaScript preset never includes a bundled dictionary.  Pass dictionaries: [await stdictFst()] to include the Standard Korean Language Dictionary.
- [Function: opendictArchaicCdb()](/api/js/functions/_gukhanmun_opendict-cdb.opendictArchaicCdb.md): opendictArchaicCdb(): Promise<FileDictionarySource> Loads the bundled Open Korean Dictionary 옛말 dictionary.
- [Function: opendictArchaicCdbBytes()](/api/js/functions/_gukhanmun_opendict-cdb.opendictArchaicCdbBytes.md): opendictArchaicCdbBytes(url?): Promise<Uint8Array<ArrayBufferLike>> Loads the bundled Open Korean Dictionary 옛말 CDB binary as raw bytes.
- [Function: opendictCdbBytes()](/api/js/functions/_gukhanmun_opendict-cdb.opendictCdbBytes.md): opendictCdbBytes(url): Promise<Uint8Array<ArrayBufferLike>> Loads an Open Korean Dictionary CDB binary as raw bytes. A file: URL is read from disk with node:fs/promises when running in Node.js, Deno, or Bun; in other runtimes (e.g. browsers) and for all other schemes the bytes are retrieved with fetch. The bundled binaries are stored gzip-compressed to stay within registry per-file size limits. Bytes that begin with the gzip magic number are therefore inflated transparently, so the returned value is always the raw CDB ready to hand to load; bytes that are not gzip-compressed are returned unchanged.
- [Function: opendictDialectCdb()](/api/js/functions/_gukhanmun_opendict-cdb.opendictDialectCdb.md): opendictDialectCdb(): Promise<FileDictionarySource> Loads the bundled Open Korean Dictionary 방언 dictionary.
- [Function: opendictDialectCdbBytes()](/api/js/functions/_gukhanmun_opendict-cdb.opendictDialectCdbBytes.md): opendictDialectCdbBytes(url?): Promise<Uint8Array<ArrayBufferLike>> Loads the bundled Open Korean Dictionary 방언 CDB binary as raw bytes.
- [Function: opendictGeneralCdb()](/api/js/functions/_gukhanmun_opendict-cdb.opendictGeneralCdb.md): opendictGeneralCdb(): Promise<FileDictionarySource> Loads the bundled Open Korean Dictionary 일반어 dictionary.
- [Function: opendictGeneralCdbBytes()](/api/js/functions/_gukhanmun_opendict-cdb.opendictGeneralCdbBytes.md): opendictGeneralCdbBytes(url?): Promise<Uint8Array<ArrayBufferLike>> Loads the bundled Open Korean Dictionary 일반어 CDB binary as raw bytes.
- [Function: opendictNorthKoreanCdb()](/api/js/functions/_gukhanmun_opendict-cdb.opendictNorthKoreanCdb.md): opendictNorthKoreanCdb(): Promise<FileDictionarySource> Loads the bundled Open Korean Dictionary 북한어 dictionary.
- [Function: opendictNorthKoreanCdbBytes()](/api/js/functions/_gukhanmun_opendict-cdb.opendictNorthKoreanCdbBytes.md): opendictNorthKoreanCdbBytes(url?): Promise<Uint8Array<ArrayBufferLike>> Loads the bundled Open Korean Dictionary 북한어 CDB binary as raw bytes.
- [Function: opendictArchaicFst()](/api/js/functions/_gukhanmun_opendict-fst.opendictArchaicFst.md): opendictArchaicFst(): Promise<FileDictionarySource> Loads the bundled Open Korean Dictionary 옛말 dictionary.
- [Function: opendictArchaicFstBytes()](/api/js/functions/_gukhanmun_opendict-fst.opendictArchaicFstBytes.md): opendictArchaicFstBytes(url?): Promise<Uint8Array<ArrayBufferLike>> Loads the bundled Open Korean Dictionary 옛말 FST binary as raw bytes.
- [Function: opendictDialectFst()](/api/js/functions/_gukhanmun_opendict-fst.opendictDialectFst.md): opendictDialectFst(): Promise<FileDictionarySource> Loads the bundled Open Korean Dictionary 방언 dictionary.
- [Function: opendictDialectFstBytes()](/api/js/functions/_gukhanmun_opendict-fst.opendictDialectFstBytes.md): opendictDialectFstBytes(url?): Promise<Uint8Array<ArrayBufferLike>> Loads the bundled Open Korean Dictionary 방언 FST binary as raw bytes.
- [Function: opendictFstBytes()](/api/js/functions/_gukhanmun_opendict-fst.opendictFstBytes.md): opendictFstBytes(url): Promise<Uint8Array<ArrayBufferLike>> Loads an Open Korean Dictionary FST binary as raw bytes. A file: URL is read from disk with node:fs/promises when running in Node.js, Deno, or Bun; in other runtimes (e.g. browsers) and for all other schemes the bytes are retrieved with fetch.
- [Function: opendictGeneralFst()](/api/js/functions/_gukhanmun_opendict-fst.opendictGeneralFst.md): opendictGeneralFst(): Promise<FileDictionarySource> Loads the bundled Open Korean Dictionary 일반어 dictionary.
- [Function: opendictGeneralFstBytes()](/api/js/functions/_gukhanmun_opendict-fst.opendictGeneralFstBytes.md): opendictGeneralFstBytes(url?): Promise<Uint8Array<ArrayBufferLike>> Loads the bundled Open Korean Dictionary 일반어 FST binary as raw bytes.
- [Function: opendictNorthKoreanFst()](/api/js/functions/_gukhanmun_opendict-fst.opendictNorthKoreanFst.md): opendictNorthKoreanFst(): Promise<FileDictionarySource> Loads the bundled Open Korean Dictionary 북한어 dictionary.
- [Function: opendictNorthKoreanFstBytes()](/api/js/functions/_gukhanmun_opendict-fst.opendictNorthKoreanFstBytes.md): opendictNorthKoreanFstBytes(url?): Promise<Uint8Array<ArrayBufferLike>> Loads the bundled Open Korean Dictionary 북한어 FST binary as raw bytes.
- [Function: stdictCdb()](/api/js/functions/_gukhanmun_stdict-cdb.stdictCdb.md): stdictCdb(): Promise<FileDictionarySource> Loads the bundled Standard Korean Language Dictionary as a FileDictionarySource ready to pass to load({ dictionaries: [...] }).
- [Function: stdictCdbBytes()](/api/js/functions/_gukhanmun_stdict-cdb.stdictCdbBytes.md): stdictCdbBytes(url?): Promise<Uint8Array<ArrayBuffer>> Loads the bundled Standard Korean Language Dictionary as raw bytes. The access strategy is chosen from the URL scheme, not from the host runtime.  A file: URL is read from disk with node:fs/promises (Node.js, Deno, and Bun all provide it, and it is the only option since Node.js's fetch rejects file: URLs); any other scheme is retrieved with fetch. Branching on the scheme is what makes a JSR install work on Deno: there import.meta.url (and therefore stdictCdbUrl) is an https: URL, yet Deno also exposes process.versions.node, so a runtime sniff would wrongly take the node:fs path and readFile would reject the https: URL with "The URL must be of scheme file".
- [Function: stdictFst()](/api/js/functions/_gukhanmun_stdict-fst.stdictFst.md): stdictFst(): Promise<FileDictionarySource> Loads the bundled Standard Korean Language Dictionary as a FileDictionarySource ready to pass to load({ dictionaries: [...] }).
- [Function: stdictFstBytes()](/api/js/functions/_gukhanmun_stdict-fst.stdictFstBytes.md): stdictFstBytes(url?): Promise<Uint8Array<ArrayBuffer>> Loads the bundled Standard Korean Language Dictionary as raw bytes. The access strategy is chosen from the URL scheme, not from the host runtime.  A file: URL is read from disk with node:fs/promises (Node.js, Deno, and Bun all provide it, and it is the only option since Node.js's fetch rejects file: URLs); any other scheme is retrieved with fetch. Branching on the scheme is what makes a JSR install work on Deno: there import.meta.url (and therefore stdictFstUrl) is an https: URL, yet Deno also exposes process.versions.node, so a runtime sniff would wrongly take the node:fs path and readFile would reject the https: URL with "The URL must be of scheme file".
- [Function: load()](/api/js/functions/_gukhanmun_wasm.load.md): load(options?): Promise<Gukhanmun> Creates a Gukhanmun converter with the given options. Initialises the WASM module on the first call (subsequent calls reuse the cached module).  Dictionaries supplied via {@link GukhanmunOptions.dictionaries} are fetched and passed to the Rust engine as FileDictionarySource values. Note: unlike the Rust ko-kr preset, the JavaScript preset never includes a bundled dictionary.  Pass dictionaries: [await stdictFst()] to include the Standard Korean Language Dictionary.
- [Interface: DictionaryEntry](/api/js/interfaces/_gukhanmun_napi.DictionaryEntry.md): A single dictionary entry returned by a dictionary lookup.
- [Interface: Directives](/api/js/interfaces/_gukhanmun_napi.Directives.md): Per-hanja rendering directives that override the dictionary's own marks. Each list contains hanja forms (exact string matches, e.g. "漢字"). JavaScript bindings expose only the literal-set form; glob and predicate variants are available in the Rust API only. Corresponds to Rust UserDirectives with DirectiveAction::RequireHanja, DirectiveAction::RequireHangul, and DirectiveAction::SkipAnnotation.
- [Interface: FileDictionarySource](/api/js/interfaces/_gukhanmun_napi.FileDictionarySource.md): Specifies a dictionary loaded from a binary file or URL. The data field accepts: A BufferSource (ArrayBuffer or ArrayBufferView) — supported in all environments.A URL — resolved via fetch in browsers; via node:fs/promises in Node.js, Deno 2.0+, and Bun.A string — treated as a filesystem path; supported in Node.js, Deno 2.0+, and Bun only.  Throws in browser environments. At runtime, a FileDictionarySource is distinguished from other values by the presence of a format property ("format" in source).
- [Interface: Gukhanmun](/api/js/interfaces/_gukhanmun_napi.Gukhanmun.md): A configured hanja-to-hangul converter.  Created by calling GukhanmunFactory.load (or the top-level load function). The instance is immutable after creation; call load again to obtain a converter with different options.
- [Interface: GukhanmunFactory](/api/js/interfaces/_gukhanmun_napi.GukhanmunFactory.md): Factory interface satisfied by both @gukhanmun/wasm and @gukhanmun/napi.
- [Interface: GukhanmunOptions](/api/js/interfaces/_gukhanmun_napi.GukhanmunOptions.md): Full set of options passed to GukhanmunFactory.load (or the top-level load function) to configure a Gukhanmun instance. All fields are optional.  When a preset is specified it supplies defaults; individual fields override those defaults.  When no preset is given, "ko-kr" is implicitly used.
- [Interface: HtmlOptions](/api/js/interfaces/_gukhanmun_napi.HtmlOptions.md): Fine-grained HTML preservation rules passed in GukhanmunOptions.html. These are additive: a scope is preserved when any rule matches.  They correspond to the CLI flags --html-preserve-class and --html-preserve-attr, and to the Rust Builder::html_preserve_when predicate.
- [Interface: DictionaryEntry](/api/js/interfaces/_gukhanmun_types.DictionaryEntry.md): A single dictionary entry returned by a dictionary lookup.
- [Interface: Directives](/api/js/interfaces/_gukhanmun_types.Directives.md): Per-hanja rendering directives that override the dictionary's own marks. Each list contains hanja forms (exact string matches, e.g. "漢字"). JavaScript bindings expose only the literal-set form; glob and predicate variants are available in the Rust API only. Corresponds to Rust UserDirectives with DirectiveAction::RequireHanja, DirectiveAction::RequireHangul, and DirectiveAction::SkipAnnotation.
- [Interface: FileDictionarySource](/api/js/interfaces/_gukhanmun_types.FileDictionarySource.md): Specifies a dictionary loaded from a binary file or URL. The data field accepts: A BufferSource (ArrayBuffer or ArrayBufferView) — supported in all environments.A URL — resolved via fetch in browsers; via node:fs/promises in Node.js, Deno 2.0+, and Bun.A string — treated as a filesystem path; supported in Node.js, Deno 2.0+, and Bun only.  Throws in browser environments. At runtime, a FileDictionarySource is distinguished from other values by the presence of a format property ("format" in source).
- [Interface: Gukhanmun](/api/js/interfaces/_gukhanmun_types.Gukhanmun.md): A configured hanja-to-hangul converter.  Created by calling GukhanmunFactory.load (or the top-level load function). The instance is immutable after creation; call load again to obtain a converter with different options.
- [Interface: GukhanmunFactory](/api/js/interfaces/_gukhanmun_types.GukhanmunFactory.md): Factory interface satisfied by both @gukhanmun/wasm and @gukhanmun/napi.
- [Interface: GukhanmunOptions](/api/js/interfaces/_gukhanmun_types.GukhanmunOptions.md): Full set of options passed to GukhanmunFactory.load (or the top-level load function) to configure a Gukhanmun instance. All fields are optional.  When a preset is specified it supplies defaults; individual fields override those defaults.  When no preset is given, "ko-kr" is implicitly used.
- [Interface: HtmlOptions](/api/js/interfaces/_gukhanmun_types.HtmlOptions.md): Fine-grained HTML preservation rules passed in GukhanmunOptions.html. These are additive: a scope is preserved when any rule matches.  They correspond to the CLI flags --html-preserve-class and --html-preserve-attr, and to the Rust Builder::html_preserve_when predicate.
- [Module: @gukhanmun/napi](/api/js/modules/_gukhanmun_napi.md): Node.js native addon (napi-rs) implementation of the Gukhanmun hanja-to-hangul converter. Provides the same {@link load} / {@link Gukhanmun} contract as @gukhanmun/wasm but uses a precompiled native addon for maximum throughput.  Node.js 20+ is required.  The native addon binary (gukhanmun_napi.node) must be present in the package directory; build it 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 the only async part.
- [Module: @gukhanmun/opendict-cdb](/api/js/modules/_gukhanmun_opendict-cdb.md): Open Korean Dictionary (우리말샘) categories prebuilt as CDB binaries for use with {@link load} from @gukhanmun/wasm or @gukhanmun/napi.
- [Module: @gukhanmun/opendict-fst](/api/js/modules/_gukhanmun_opendict-fst.md): Open Korean Dictionary (우리말샘) categories prebuilt as FST binaries for use with {@link load} from @gukhanmun/wasm or @gukhanmun/napi.
- [Module: @gukhanmun/stdict-cdb](/api/js/modules/_gukhanmun_stdict-cdb.md): Standard Korean Language Dictionary (標準國語大辭典) prebuilt as a CDB binary for use with {@link load} from @gukhanmun/wasm or @gukhanmun/napi.
- [Module: @gukhanmun/stdict-fst](/api/js/modules/_gukhanmun_stdict-fst.md): Standard Korean Language Dictionary (標準國語大辭典) prebuilt as an FST binary for use with {@link load} from @gukhanmun/wasm or @gukhanmun/napi.
- [Module: @gukhanmun/types](/api/js/modules/_gukhanmun_types.md): Canonical TypeScript API contract for Gukhanmun. This package contains only TypeScript type declarations and carries no runtime code.  Both @gukhanmun/wasm and @gukhanmun/napi satisfy this contract structurally.  All TSDoc lives here as the single source of truth for the JavaScript API.
- [Module: @gukhanmun/wasm](/api/js/modules/_gukhanmun_wasm.md): WebAssembly implementation of the Gukhanmun hanja-to-hangul converter. Provides the same {@link load} / {@link Gukhanmun} contract as @gukhanmun/napi but runs in any WebAssembly-capable environment—browsers, Deno 2.0+, Node 20+, and Bun 1.0+. The WASM module is initialised lazily on the first load() call and cached for subsequent calls.  Dictionary data (FST format) must be supplied explicitly via {@link GukhanmunOptions.dictionaries}.
- [Type Alias: ContextWindow](/api/js/types/_gukhanmun_napi.ContextWindow.md): ContextWindow = "off" | "per-block" | "per-section" | "per-document" Defines the scope within which the homophone marker and first-occurrence filter track previously seen readings.  Corresponds to Rust ContextWindow. "off" — Disable the corresponding middleware entirely."per-block" — Reset at each block boundary (paragraph, list item, heading, …).  This is the default for both homophone marking and first- occurrence filtering.  In plain text, which has no block scopes, per-block is document-wide."per-section" — Reset at each heading boundary (HTML <h1>–<h6>, Markdown ATX/setext headings)."per-document" — Track across the entire document.  This buffers the entire token stream and is appropriate only for small inputs or when full accuracy matters more than latency.
- [Type Alias: DictionarySource](/api/js/types/_gukhanmun_napi.DictionarySource.md): DictionarySource = FileDictionarySource A dictionary source accepted by GukhanmunOptions.dictionaries. Currently only FileDictionarySource (binary file / URL / path) is supported.  Sources are tried in array order; the first match wins.
- [Type Alias: ErrorCode](/api/js/types/_gukhanmun_napi.ErrorCode.md): ErrorCode = "dictionary-load" | "segmentation" | "invalid-reading" | "html-scan" | "html-malformed-attr" | "markdown" | "unsupported-content-type" | "invalid-input" | "io" | "internal" | "other" Discriminant code carried by every GukhanmunError. "dictionary-load" — A dictionary file could not be opened, read, or decoded."segmentation" — The lattice segmenter encountered an internal inconsistency."invalid-reading" — A dictionary entry's hangul reading is not valid hangul."html-scan" — The HTML scanner encountered an unrecoverable error."html-malformed-attr" — An HTML attribute string could not be parsed."markdown" — The Markdown adapter encountered a parsing error."unsupported-content-type" — An unrecognised format string was passed to convert or stream."invalid-input" — An option value is not in the expected set (e.g. an unrecognised preset or render mode string)."io" — An I/O error occurred (file read, network, …)."internal" — An internal invariant was violated; this is a bug."other" — Any other error not covered by the above codes.
- [Type Alias: Format](/api/js/types/_gukhanmun_napi.Format.md): Format = "text" | "html" | "markdown" | { format: "markdown"; gfm?: boolean; } Input / output format for Gukhanmun.convert and Gukhanmun.stream. "text" — Plain text (default).  No markup interpretation; ruby rendering falls back to parentheses."html" — HTML fragment.  The scanner is fragment-oriented and recovers from minor malformations."markdown" — CommonMark Markdown (GFM disabled by default).{ format: "markdown"; gfm?: boolean } — Markdown with optional GFM extensions.  Set gfm: true to enable GitHub Flavored Markdown tables, strikethrough, and task lists. The object form { format: "markdown" } is equivalent to the string "markdown".
- [Type Alias: HomophoneDetection](/api/js/types/_gukhanmun_napi.HomophoneDetection.md): HomophoneDetection = "context-local" | "dictionary-wide" 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 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 Alias: NumeralStrategy](/api/js/types/_gukhanmun_napi.NumeralStrategy.md): NumeralStrategy = "hangul-phonetic" | "positional-arabic" | "additive-arabic" | "smart" Controls how runs of hanja numerals are converted.  Corresponds to Rust NumeralStrategy. "hangul-phonetic" — Read every digit character-by-character in Korean phonetics.  This is Seonbi's behaviour and the preset default. Corresponds to Rust NumeralStrategy::HangulPhonetic."positional-arabic" — Treat a run of digit-only hanja (〇一二三四五六七八九 and variants) as positional (place-value) notation and convert to Arabic.  Corresponds to Rust NumeralStrategy::PositionalArabic."additive-arabic" — Parse sequences containing place markers (十百千萬億兆京) using stack-based accumulation and produce Arabic, respecting the Korean convention that bare 十 means 10 not 一十. Corresponds to Rust NumeralStrategy::AdditiveArabic."smart" — Uses "additive-arabic" for additive numerals that begin with a digit, and for small-place-marker starts (十, 百, 千) unless the next character is an ambiguous non-unit hanja word character; uses "positional-arabic" for pure-digit runs of four or more characters (year convention) or when a unit hanja follows the digit run (年月日時分秒號世紀 and others); otherwise falls back to "hangul-phonetic".  Corresponds to Rust NumeralStrategy::Smart.
- [Type Alias: OriginalGloss](/api/js/types/_gukhanmun_napi.OriginalGloss.md): OriginalGloss = "parens" | "ruby" Selects how glosses are rendered when RenderMode is "original". "parens" — Wrap the gloss in parentheses: 漢字(한글) (default). Corresponds to Rust OriginalGloss::Parens."ruby" — Wrap the gloss in a <ruby> element.  Falls back to parentheses in scopes that do not permit inline markup.  Corresponds to Rust OriginalGloss::Ruby. This option is ignored when rendering is not "original".
- [Type Alias: Preset](/api/js/types/_gukhanmun_napi.Preset.md): Preset = "ko-kr" | "ko-kp" Named configuration preset that sets orthographic and lexical defaults. "ko-kr" — South Korean orthography: dictionary-driven readings, the initial sound law applied to fallback fragments, per-block homophone disambiguation, and the bundled Standard Korean Language Dictionary (標準國語大辭典).  Corresponds to Rust Preset::KoKr."ko-kp" — North Korean orthography: no initial sound law (래일, 류행, 녀자), no bundled dictionary data.  Corresponds to Rust Preset::KoKp. Both presets default rendering to "hangul-only" and segmentation to "lattice".  Individual options passed to GukhanmunOptions override the preset.
- [Type Alias: Recovery](/api/js/types/_gukhanmun_napi.Recovery.md): Recovery = "strict" | "lenient" Controls how the pipeline handles reader errors encountered during HTML scanning.  Corresponds to Rust Recovery. "strict" — Propagate the error and stop (default)."lenient" — Log the error via tracing and emit a verbatim token for the unrecognised region so that downstream tokens continue to flow. This option is meaningful only for format: "html".  Markdown parsing does not produce recoverable errors, so this option is ignored for Markdown input.
- [Type Alias: RenderMode](/api/js/types/_gukhanmun_napi.RenderMode.md): RenderMode = "hangul-only" | "hangul-hanja-parens" | "hanja-hangul-parens" | "ruby-on-hangul" | "ruby-on-hanja" | "original" Controls how the renderer expands each converted hanja annotation into output text or markup.  Corresponds to Rust RenderMode. "hangul-only" — Emit only the hangul reading.  When homophone or require_hanja is set on an annotation the reading is followed by the original hanja in parentheses: 한글(漢字).  Corresponds to Rust RenderMode::HangulOnly."hangul-hanja-parens" — Always emit 한글(漢字).  Corresponds to Rust RenderMode::HangulHanjaParens."hanja-hangul-parens" — Always emit 漢字(한글).  Useful for academic and historical-document styles.  Corresponds to Rust RenderMode::HanjaHangulParens."ruby-on-hangul" — Emit <ruby>한글<rt>漢字</rt></ruby>.  Falls back to parentheses when the current scope does not permit inline markup (e.g., inside <pre>).  Corresponds to Rust RenderMode::Ruby(RubyBase::OnHangul)."ruby-on-hanja" — Emit <ruby>漢字<rt>한글</rt></ruby>. Corresponds to Rust RenderMode::Ruby(RubyBase::OnHanja)."original" — Keep the original mixed-script form; only annotations with require_hangul or a user directive receive a hangul gloss, which appears either in parentheses or as a ruby element depending on GukhanmunOptions.originalGloss.  Corresponds to Rust RenderMode::Original.
- [Type Alias: Segmentation](/api/js/types/_gukhanmun_napi.Segmentation.md): Segmentation = "lattice" | "eager" Controls how the engine segments a hanja-containing span into dictionary words and fallback fragments.  Corresponds to Rust SegmentationStrategy. "lattice" — Dynamic programming over all possible dictionary matches at each position; selects the segmentation that maximises dictionary coverage and then prefers fewer segments.  This is the default and produces better results than greedy approaches when a longer prefix would leave a suffix uncovered by the dictionary.  Corresponds to Rust SegmentationStrategy::Lattice."eager" — Left-to-right longest-match (greedy).  Lower overhead per span at the cost of occasional mis-segmentation.  Corresponds to Rust SegmentationStrategy::Eager.
- [Type Alias: ContextWindow](/api/js/types/_gukhanmun_types.ContextWindow.md): ContextWindow = "off" | "per-block" | "per-section" | "per-document" Defines the scope within which the homophone marker and first-occurrence filter track previously seen readings.  Corresponds to Rust ContextWindow. "off" — Disable the corresponding middleware entirely."per-block" — Reset at each block boundary (paragraph, list item, heading, …).  This is the default for both homophone marking and first- occurrence filtering.  In plain text, which has no block scopes, per-block is document-wide."per-section" — Reset at each heading boundary (HTML <h1>–<h6>, Markdown ATX/setext headings)."per-document" — Track across the entire document.  This buffers the entire token stream and is appropriate only for small inputs or when full accuracy matters more than latency.
- [Type Alias: DictionarySource](/api/js/types/_gukhanmun_types.DictionarySource.md): DictionarySource = FileDictionarySource A dictionary source accepted by GukhanmunOptions.dictionaries. Currently only FileDictionarySource (binary file / URL / path) is supported.  Sources are tried in array order; the first match wins.
- [Type Alias: ErrorCode](/api/js/types/_gukhanmun_types.ErrorCode.md): ErrorCode = "dictionary-load" | "segmentation" | "invalid-reading" | "html-scan" | "html-malformed-attr" | "markdown" | "unsupported-content-type" | "invalid-input" | "io" | "internal" | "other" Discriminant code carried by every GukhanmunError. "dictionary-load" — A dictionary file could not be opened, read, or decoded."segmentation" — The lattice segmenter encountered an internal inconsistency."invalid-reading" — A dictionary entry's hangul reading is not valid hangul."html-scan" — The HTML scanner encountered an unrecoverable error."html-malformed-attr" — An HTML attribute string could not be parsed."markdown" — The Markdown adapter encountered a parsing error."unsupported-content-type" — An unrecognised format string was passed to convert or stream."invalid-input" — An option value is not in the expected set (e.g. an unrecognised preset or render mode string)."io" — An I/O error occurred (file read, network, …)."internal" — An internal invariant was violated; this is a bug."other" — Any other error not covered by the above codes.
- [Type Alias: Format](/api/js/types/_gukhanmun_types.Format.md): Format = "text" | "html" | "markdown" | { format: "markdown"; gfm?: boolean; } Input / output format for Gukhanmun.convert and Gukhanmun.stream. "text" — Plain text (default).  No markup interpretation; ruby rendering falls back to parentheses."html" — HTML fragment.  The scanner is fragment-oriented and recovers from minor malformations."markdown" — CommonMark Markdown (GFM disabled by default).{ format: "markdown"; gfm?: boolean } — Markdown with optional GFM extensions.  Set gfm: true to enable GitHub Flavored Markdown tables, strikethrough, and task lists. The object form { format: "markdown" } is equivalent to the string "markdown".
- [Type Alias: HomophoneDetection](/api/js/types/_gukhanmun_types.HomophoneDetection.md): HomophoneDetection = "context-local" | "dictionary-wide" 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 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 Alias: NumeralStrategy](/api/js/types/_gukhanmun_types.NumeralStrategy.md): NumeralStrategy = "hangul-phonetic" | "positional-arabic" | "additive-arabic" | "smart" Controls how runs of hanja numerals are converted.  Corresponds to Rust NumeralStrategy. "hangul-phonetic" — Read every digit character-by-character in Korean phonetics.  This is Seonbi's behaviour and the preset default. Corresponds to Rust NumeralStrategy::HangulPhonetic."positional-arabic" — Treat a run of digit-only hanja (〇一二三四五六七八九 and variants) as positional (place-value) notation and convert to Arabic.  Corresponds to Rust NumeralStrategy::PositionalArabic."additive-arabic" — Parse sequences containing place markers (十百千萬億兆京) using stack-based accumulation and produce Arabic, respecting the Korean convention that bare 十 means 10 not 一十. Corresponds to Rust NumeralStrategy::AdditiveArabic."smart" — Uses "additive-arabic" for additive numerals that begin with a digit, and for small-place-marker starts (十, 百, 千) unless the next character is an ambiguous non-unit hanja word character; uses "positional-arabic" for pure-digit runs of four or more characters (year convention) or when a unit hanja follows the digit run (年月日時分秒號世紀 and others); otherwise falls back to "hangul-phonetic".  Corresponds to Rust NumeralStrategy::Smart.
- [Type Alias: OriginalGloss](/api/js/types/_gukhanmun_types.OriginalGloss.md): OriginalGloss = "parens" | "ruby" Selects how glosses are rendered when RenderMode is "original". "parens" — Wrap the gloss in parentheses: 漢字(한글) (default). Corresponds to Rust OriginalGloss::Parens."ruby" — Wrap the gloss in a <ruby> element.  Falls back to parentheses in scopes that do not permit inline markup.  Corresponds to Rust OriginalGloss::Ruby. This option is ignored when rendering is not "original".
- [Type Alias: Preset](/api/js/types/_gukhanmun_types.Preset.md): Preset = "ko-kr" | "ko-kp" Named configuration preset that sets orthographic and lexical defaults. "ko-kr" — South Korean orthography: dictionary-driven readings, the initial sound law applied to fallback fragments, per-block homophone disambiguation, and the bundled Standard Korean Language Dictionary (標準國語大辭典).  Corresponds to Rust Preset::KoKr."ko-kp" — North Korean orthography: no initial sound law (래일, 류행, 녀자), no bundled dictionary data.  Corresponds to Rust Preset::KoKp. Both presets default rendering to "hangul-only" and segmentation to "lattice".  Individual options passed to GukhanmunOptions override the preset.
- [Type Alias: Recovery](/api/js/types/_gukhanmun_types.Recovery.md): Recovery = "strict" | "lenient" Controls how the pipeline handles reader errors encountered during HTML scanning.  Corresponds to Rust Recovery. "strict" — Propagate the error and stop (default)."lenient" — Log the error via tracing and emit a verbatim token for the unrecognised region so that downstream tokens continue to flow. This option is meaningful only for format: "html".  Markdown parsing does not produce recoverable errors, so this option is ignored for Markdown input.
- [Type Alias: RenderMode](/api/js/types/_gukhanmun_types.RenderMode.md): RenderMode = "hangul-only" | "hangul-hanja-parens" | "hanja-hangul-parens" | "ruby-on-hangul" | "ruby-on-hanja" | "original" Controls how the renderer expands each converted hanja annotation into output text or markup.  Corresponds to Rust RenderMode. "hangul-only" — Emit only the hangul reading.  When homophone or require_hanja is set on an annotation the reading is followed by the original hanja in parentheses: 한글(漢字).  Corresponds to Rust RenderMode::HangulOnly."hangul-hanja-parens" — Always emit 한글(漢字).  Corresponds to Rust RenderMode::HangulHanjaParens."hanja-hangul-parens" — Always emit 漢字(한글).  Useful for academic and historical-document styles.  Corresponds to Rust RenderMode::HanjaHangulParens."ruby-on-hangul" — Emit <ruby>한글<rt>漢字</rt></ruby>.  Falls back to parentheses when the current scope does not permit inline markup (e.g., inside <pre>).  Corresponds to Rust RenderMode::Ruby(RubyBase::OnHangul)."ruby-on-hanja" — Emit <ruby>漢字<rt>한글</rt></ruby>. Corresponds to Rust RenderMode::Ruby(RubyBase::OnHanja)."original" — Keep the original mixed-script form; only annotations with require_hangul or a user directive receive a hangul gloss, which appears either in parentheses or as a ruby element depending on GukhanmunOptions.originalGloss.  Corresponds to Rust RenderMode::Original.
- [Type Alias: Segmentation](/api/js/types/_gukhanmun_types.Segmentation.md): Segmentation = "lattice" | "eager" Controls how the engine segments a hanja-containing span into dictionary words and fallback fragments.  Corresponds to Rust SegmentationStrategy. "lattice" — Dynamic programming over all possible dictionary matches at each position; selects the segmentation that maximises dictionary coverage and then prefers fewer segments.  This is the default and produces better results than greedy approaches when a longer prefix would leave a suffix uncovered by the dictionary.  Corresponds to Rust SegmentationStrategy::Lattice."eager" — Left-to-right longest-match (greedy).  Lower overhead per span at the cost of occasional mis-segmentation.  Corresponds to Rust SegmentationStrategy::Eager.
- [Variable: opendictArchaicCdbUrl](/api/js/variables/_gukhanmun_opendict-cdb.opendictArchaicCdbUrl.md): const opendictArchaicCdbUrl: URL URL of the bundled Open Korean Dictionary 옛말 CDB binary. Stored gzip-compressed; opendictCdbBytes inflates it transparently.
- [Variable: opendictDialectCdbUrl](/api/js/variables/_gukhanmun_opendict-cdb.opendictDialectCdbUrl.md): const opendictDialectCdbUrl: URL URL of the bundled Open Korean Dictionary 方言 CDB binary. Stored gzip-compressed; opendictCdbBytes inflates it transparently.
- [Variable: opendictGeneralCdbUrl](/api/js/variables/_gukhanmun_opendict-cdb.opendictGeneralCdbUrl.md): const opendictGeneralCdbUrl: URL URL of the bundled Open Korean Dictionary 一般語 CDB binary. The bundled artifact is stored gzip-compressed (hence the .cdb.gz extension) to stay within registry per-file size limits; opendictCdbBytes inflates it transparently.
- [Variable: opendictNorthKoreanCdbUrl](/api/js/variables/_gukhanmun_opendict-cdb.opendictNorthKoreanCdbUrl.md): const opendictNorthKoreanCdbUrl: URL URL of the bundled Open Korean Dictionary 北韓語 CDB binary. Stored gzip-compressed; opendictCdbBytes inflates it transparently.
- [Variable: opendictArchaicFstUrl](/api/js/variables/_gukhanmun_opendict-fst.opendictArchaicFstUrl.md): const opendictArchaicFstUrl: URL URL of the bundled Open Korean Dictionary 옛말 FST binary.
- [Variable: opendictDialectFstUrl](/api/js/variables/_gukhanmun_opendict-fst.opendictDialectFstUrl.md): const opendictDialectFstUrl: URL URL of the bundled Open Korean Dictionary 방언 FST binary.
- [Variable: opendictGeneralFstUrl](/api/js/variables/_gukhanmun_opendict-fst.opendictGeneralFstUrl.md): const opendictGeneralFstUrl: URL URL of the bundled Open Korean Dictionary 일반어 FST binary.
- [Variable: opendictNorthKoreanFstUrl](/api/js/variables/_gukhanmun_opendict-fst.opendictNorthKoreanFstUrl.md): const opendictNorthKoreanFstUrl: URL URL of the bundled Open Korean Dictionary 북한어 FST binary.
- [Variable: stdictCdbUrl](/api/js/variables/_gukhanmun_stdict-cdb.stdictCdbUrl.md): const stdictCdbUrl: URL URL of the bundled Standard Korean Language Dictionary CDB binary.
- [Variable: stdictFstUrl](/api/js/variables/_gukhanmun_stdict-fst.stdictFstUrl.md): const stdictFstUrl: URL URL of the bundled Standard Korean Language Dictionary FST binary.
- [Variable: load](/api/js/variables/_gukhanmun_types.load.md): const load: GukhanmunFactory["load"] Top-level entry point exported by both @gukhanmun/wasm and @gukhanmun/napi as a named export. Equivalent to new GukhanmunFactory().load(options).  Declared here so that code that import { load } from either implementation package type-checks against the same signature.

## Internals

- [Design](/internals/design.md): Gukhanmun is a library for converting Korean text written in mixed script (國漢文混用體) into hangul-only text. It is the successor to Seonbi, narrowed in scope to the hanja conversion pipeline and broadened along several axes: streaming I/O, pluggable dictionaries, lattice-based segmentation, and a wider range of output formats. The project is implemented in Rust and exposed as a Rust library, a command-line tool, WebAssembly bindings, and Node-API bindings.
- [Dictionary format](/internals/dictionary-format.md): This document specifies the normalized dictionary input formats consumed by gukhanmun-mkdict and the FST/CDB dictionary file layouts produced from those inputs. It is the boundary between dictionary extractors, user-maintained glossaries, and backend builders.
- [Standard Korean Language Dictionary](/internals/stdict.md): gukhanmun-stdict bundles a snapshot derived from the National Institute of Korean Language's Standard Korean Language Dictionary (標準國語大辭典) JSON download. The source dump is not committed to this repository.  The download requires a login on the dictionary website, and the archive is much larger than the normalized data used by the build.  The committed source of truth is instead the canonical TSV file at crates/gukhanmun-stdict/data/stdict.tsv.
- [Open Korean Dictionary](/internals/opendict.md): Provenance, extraction policy, and runtime use for bundled Open Korean Dictionary snapshots.