---
url: /playground.md
---

# Playground

Loading the converter and dictionary…




---
url: /guide/intro.md
---

# Introduction

Gukhanmun is a hanja-to-hangul converter for Korean text.  Given mixed-script
input containing hanja (漢字) alongside hangul, it produces hangul-only output
or annotated output in several formats: plain text, Markdown, and HTML
(including `<ruby>` markup).

The converter is backed by the _Standard Korean Dictionary_ (標準國語大辭典) and
supports South Korean (`ko-KR`) and North Korean (`ko-KP`) orthography presets,
configurable segmentation, numeral handling, homophone disambiguation, and
per-character annotation directives.

## Choosing an interface

| Interface  | When to use                                           |
| ---------- | ----------------------------------------------------- |
| CLI        | Convert files from the terminal or in shell pipelines |
| Rust       | Embed the converter in a Rust application or library  |
| JavaScript | Use from Node.js, Deno, Bun, or a browser             |

### CLI

The `gukhanmun` command-line tool reads from files or standard input and
writes to standard output or a file.  It auto-detects the format from the
file extension (_.html_, _.md_) and supports all conversion options via flags.

Start here: [_Installation_](/guide/cli/install.md).

### Rust

The `gukhanmun` crate exposes a `Builder`/`Converter` API.  Build a converter
once, reuse it across calls, and stream output token by token if needed.
Feature flags let you trim the binary size by disabling HTML, Markdown, or the
bundled dictionary.

Start here: [_Installation_](/guide/rust/install.md).

### JavaScript

Two packages cover different environments:

- `@gukhanmun/wasm` runs in any JavaScript runtime via WebAssembly.  Use it
  in browsers, serverless functions, or anywhere native addons are not
  available.
- `@gukhanmun/napi` is a native Node.js addon with higher throughput.  It
  supports Node.js 20+, Deno 2.0+, and Bun 1.0+.

Both share the same `load()` API and accept identical options.

Start here: [_Installation_](/guide/javascript/install.md).



---
url: /guide/cli/install.md
---

# Installation

Gukhanmun is distributed as a single binary with no runtime dependencies.

## Via mise

If you use [mise], install a prebuilt binary with a single command:

```sh
mise use -g aqua:dahlia/gukhanmun
```

The `-g` flag installs it globally.  Omit it to activate the tool only in the
current project directory.

[mise]: https://mise.jdx.dev/

## Via Windows Package Manager (`winget`)

On Windows, install via `winget`:

```powershell
winget install HongMinhee.Gukhanmun
```

## From crates.io

If you have a Rust toolchain installed, install from crates.io:

```sh
cargo install gukhanmun-cli gukhanmun-mkdict
```

This compiles the binaries and places them in _\~/.cargo/bin/_.  Make sure that
directory is on your `PATH`.

## Prebuilt binaries

Prebuilt binaries for Linux (x86\_64, aarch64), macOS (x86\_64, aarch64), and
Windows (x86\_64) are attached to each release on GitHub:

[https://github.com/dahlia/gukhanmun/releases](https://github.com/dahlia/gukhanmun/releases)

Download the archive for your platform, extract it, and place the `gukhanmun`
binary somewhere on your `PATH`.

## The `gukhanmun-mkdict` companion

The mise install and the prebuilt archives also include `gukhanmun-mkdict`, the
tool for compiling [custom dictionaries](/guide/cli/dictionary.md).  No separate
installation step is needed.

## Verify the installation

```sh
gukhanmun --help
gukhanmun-mkdict --help
```



---
url: /guide/cli/start.md
---

# Quick start

Gukhanmun reads text containing hanja and writes the same text with hanja
replaced by their hangul readings.

## Converting a file

Pass a file path as the positional argument:

```sh
gukhanmun input.txt
```

Output goes to standard output by default.  Use `-o` to write to a file
instead:

```sh
gukhanmun -o output.txt input.txt
```

To replace a file in-place, pass the same path for both input and output.
Gukhanmun writes to a temporary file first and replaces the original
atomically, so the original is never left in a partial state:

```sh
gukhanmun -o document.txt document.txt
```

## Reading from standard input

Omit the file argument to read from standard input:

```sh
echo "漢字를 한글로" | gukhanmun
# → 한자를 한글로
```

## Specifying the input format

Gukhanmun infers the format from the file extension:

| Extension          | Format     |
| ------------------ | ---------- |
| _.txt_, _(none)_   | Plain text |
| _.html_, _.htm_    | HTML       |
| _.md_, _.markdown_ | Markdown   |

Override the detected format with `-f`:

```sh
gukhanmun -f text/plain input.html      # treat as plain text
gukhanmun -f text/html  snippet.txt     # treat as HTML
gukhanmun -f text/markdown article.txt  # treat as Markdown
```

The Markdown format also accepts variant parameters:

```sh
gukhanmun -f "text/markdown; variant=GFM" post.md
```

## Verbose logging

Add `-v` to print debug information to standard error:

```sh
gukhanmun -v input.txt
```



---
url: /guide/cli/dictionary.md
---

# Dictionaries

Gukhanmun uses dictionaries to look up the hangul readings of hanja.  The
`ko-kr` preset uses the bundled _Standard Korean Dictionary_ (標準國語大辭典),
and the `ko-kp` preset uses the bundled _Open Korean Dictionary_ (우리말샘)
North Korean category.

## Bundled dictionaries

The bundled dictionary selected by the preset is loaded automatically.  No
extra flags are needed for most Korean text.

To disable every bundled dictionary, for example when you want to rely entirely
on a custom dictionary, pass `--no-bundled-dictionaries`:

```sh
gukhanmun --no-bundled-dictionaries -d my-dict.gukfst input.txt
```

Use the `ko-kp` preset for North Korean orthography.  It disables the initial
sound law and uses the bundled _Open Korean Dictionary_ (우리말샘) North Korean
(北韓語) dictionary:

```sh
gukhanmun --preset ko-kp input.txt
```

## Custom dictionaries

Supply one or more custom dictionaries with `-d` (or `--dictionary`).  The
flag can be repeated:

```sh
gukhanmun -d legal.gukfst input.txt
gukhanmun -d legal.gukfst -d names.gukcdb input.txt
```

Gukhanmun supports two binary dictionary formats:

| Format | Extension | Lookup                  | Notes                                               |
| ------ | --------- | ----------------------- | --------------------------------------------------- |
| FST    | _.gukfst_ | $O(\text\{key length})$ | Preferred for lattice segmentation; smaller on disk |
| CDB    | _.gukcdb_ | $O(1)$                  | Simpler layout; easier to audit by hand             |

Dictionaries are tried in the order they appear on the command line, with the
bundled dictionary consulted last.  The first match wins.

## Building a custom dictionary

The _.gukfst_ and _.gukcdb_ files are compiled artifacts, not something you
edit by hand.  You author your entries as a plain text table and compile them
with `gukhanmun-mkdict`.

The `gukhanmun-mkdict` builder is installed together with `gukhanmun`, whether
you [install via mise](/guide/cli/install.md#via-mise) or
[download a prebuilt archive](/guide/cli/install.md#prebuilt-binaries). If you instead
built from crates.io, install the builder the same way:

```sh
cargo install gukhanmun-mkdict
```

Write your entries as a tab-separated file with a `hanja` key column and a
`hangul` reading column:

```tsv
hanja	hangul
北京	베이징
學校	학교
```

Two optional columns control how renderers treat each entry: set
`require_hanja` to `true` to keep the source hanja visible (for homophones that
need disambiguation), and `require_hangul` to `true` to force a hangul gloss in
the original-script rendering mode.

```tsv
hanja	hangul	require_hanja	require_hangul
北京	베이징	false	false
色깔論	색깔론	false	true
```

Compile the table into an FST dictionary (the default format):

```sh
gukhanmun-mkdict --output legal.gukfst legal.tsv
```

Pass `--format cdb` to produce a _.gukcdb_ file instead.  You can supply
several input files, which are merged in order; `--merge` selects how duplicate
keys are resolved (`error`, `first-wins`, or `last-wins`).  Add `--validate` to
reopen the output and confirm every entry round-trips, and `--metadata KEY=VAL`
to embed provenance such as the source or license.

Then load the result like any other custom dictionary:

```sh
gukhanmun -d legal.gukfst input.txt
```

CSV and JSON Lines inputs are also accepted, and a few more advanced options
are available.  See [the internals section](/internals/dictionary-format.md) for
the full dictionary file format specification.



---
url: /guide/cli/conversion.md
---

# Conversion options

These flags control the linguistic rules applied during conversion.

## Preset

`--preset` selects a preconfigured combination of defaults:

| Preset            | Dictionary     | Initial sound law | Homophone window | Use case                 |
| ----------------- | -------------- | ----------------- | ---------------- | ------------------------ |
| `ko-kr` (default) | Bundled stdict | Enabled           | Per-block        | South Korean orthography |
| `ko-kp`           | None           | Disabled          | Off              | North Korean orthography |

```sh
gukhanmun --preset ko-kp input.txt
```

Individual flags below override the preset's defaults.

## Segmentation strategy

`--segmentation` controls how word boundaries are found:

- `lattice` (default): finds the globally optimal segmentation by evaluating
  all dictionary matches at every position with dynamic programming.  Best for
  accuracy.
- `eager`: greedy left-to-right longest-match.  Faster but may mis-segment
  compound words.

```sh
gukhanmun --segmentation eager input.txt
```

## Numeral handling

`--numerals` controls how hanja numerals are rendered. The CLI defaults to
`smart`; pass `--numerals hangul-phonetic` to keep Seonbi-style phonetic
readings for calendar words such as `六月`.

| Strategy            | 二〇一六年 | 十一月   | 一千二百三十四 |
| ------------------- | ----- | ----- | ------- |
| `hangul-phonetic`   | 이공일륙년 | 십일월   | 일천이백삼십사 |
| `positional-arabic` | 2016년 | (n/a) | (n/a)   |
| `additive-arabic`   | (n/a) | 11월   | 1234    |
| `smart` (default)   | 2016년 | 11월   | 1234    |

```sh
gukhanmun --numerals hangul-phonetic input.txt
```

## Initial sound law

The initial sound law (頭音法則) is enabled by default for `ko-kr` and
disabled for `ko-kp`.  It affects character-by-character fallback readings for
characters not found in any dictionary; dictionary entries already encode their
correct readings.

| Input | Law enabled (`ko-kr`) | Law disabled (`ko-kp`) |
| ----- | --------------------- | ---------------------- |
| 來日    | 내일                    | 래일                     |
| 理由    | 이유                    | 리유                     |
| 女子    | 여자                    | 녀자                     |

Override with explicit flags:

```sh
gukhanmun --no-initial-sound-law input.txt  # disable
gukhanmun --initial-sound-law input.txt     # enable (redundant for ko-kr)
```

## Parenthetical reading annotations

Mixed-script input sometimes spells a word together with an explicit
parenthetical gloss, whether hanja-first (`庫間(곳간)`) or hangul-first
(`곳간(庫間)`).  By default Gukhanmun recognizes such a gloss, removes the now
redundant parenthetical, and shows the word in both scripts:

| Input    | Default output | `--no-collapse-parens` |
| -------- | -------------- | ---------------------- |
| `庫間(곳간)` | `곳간(庫間)`       | `곳간(곳간)`               |
| `곳간(庫間)` | `곳간(庫間)`       | `곳간(곳간)`               |

A parenthetical can also pin an alternative reading.  `數字` normally reads
`숫자`, but `數字(수자)` fixes the reading to `수자` for that occurrence:

```sh
echo '數字(수자)' | gukhanmun  # 수자(數字)
```

A reading annotation is told apart from a definition by two rules.  A
parenthetical that exactly matches the word's reading always collapses (this
covers 사이시옷 readings like `庫間(곳간)`).  Otherwise, an alternative reading
is accepted only when it has one hangul syllable per hanja character, each a
valid Sino-Korean reading of that character (as in `數字(수자)`).  A definition
gloss matches neither rule and passes through untouched:

```sh
echo '庫間(물건을 간직하여 두는 곳)' | gukhanmun
# 곳간(물건을 간직하여 두는 곳)
```

Foreign transliterations are likewise left alone, because they are not valid
per-character readings (for example `蔣介石(장제스)`, where `介` reads `개`, not
`제`).  Pass `--no-collapse-parens` to disable the behaviour entirely.

## Homophone disambiguation

Different hanja words can share the same hangul reading (for example, 連霸 and
連敗 are both 연패).  In the default `hangul-only` rendering mode, Gukhanmun
can keep the hanja in parentheses for such words so readers can tell them
apart. `--disambiguation` sets the scope across which a reading is considered
ambiguous:

| Value                             | Behaviour                                  |
| --------------------------------- | ------------------------------------------ |
| `off`                             | No disambiguation                          |
| `per-block` (default for `ko-kr`) | Reset at paragraph/list/heading boundaries |
| `per-section`                     | Reset at heading boundaries                |
| `per-document`                    | Track across the entire input              |

```sh
gukhanmun --disambiguation per-section input.txt
```

`--homophone-detection` chooses which readings count as ambiguous within the
window:

| Value                     | Behaviour                                                                            |
| ------------------------- | ------------------------------------------------------------------------------------ |
| `context-local` (default) | Gloss a word only when a different-meaning homophone actually appears in the window. |
| `dictionary-wide`         | Also gloss readings shared by other hanja forms anywhere in the dictionary.          |

```sh
gukhanmun --homophone-detection dictionary-wide input.txt
```

`context-local` keeps hangul-only output clean.  `dictionary-wide` is broader,
but with the bundled _Standard Korean Dictionary_ nearly every common reading
has some homophone, so it glosses most Sino-Korean words.  To always gloss a
specific word regardless of context, use the `--require-hanja` flag instead
(see [_User directives_](/guide/cli/directives.md)).

## Only recognized words are disambiguated

Homophone disambiguation operates on words the dictionary recognizes as units.
A hanja sequence with no dictionary entry of its own is not treated as a single
word, and its fallback (non-dictionary) characters are never glossed; any
recognized single-character entries inside it (such as `紫`) are still handled
on their own.  For example, `自由` and `子游` are both bundled entries read
`자유`, so `自由와 子游` becomes `자유(自由)와 자유(子游)`; but `紫楡` has no
entry of its own, so under the default context-local strategy `自由와 紫楡`
becomes `자유와 자유` with no gloss, because the engine never sees a second
`자유` unit to collide with `自由`.  To disambiguate the whole term, add it to
a custom dictionary and load it with `--dictionary` (see
[_Dictionaries_](/guide/cli/dictionary.md)) so the engine treats it as a single unit.

## First-occurrence clearing

`--first-occurrence` removes annotations from characters whose presentation
was already forced earlier in the window:

| Value           | Behaviour                        |
| --------------- | -------------------------------- |
| `off` (default) | Never clear                      |
| `per-block`     | Clear within a paragraph/block   |
| `per-section`   | Clear within a section           |
| `per-document`  | Clear across the entire document |

```sh
gukhanmun --first-occurrence per-section input.txt
```

## Error recovery

`--recovery` controls behaviour when an unrecoverable parse error occurs
(currently relevant for HTML input only):

- `strict` (default) — abort with an error
- `lenient` — skip the problematic fragment and continue

```sh
gukhanmun -f text/html --recovery lenient input.html
```



---
url: /guide/cli/rendering.md
---

# Rendering modes

`--rendering` controls how hanja and their hangul readings appear in the
output.  The default is `hangul-only`.

## Available modes

### `hangul-only` (default)

Replaces each hanja word with its hangul reading.  The original hanja is
discarded.

```sh
echo "漢字" | gukhanmun --rendering hangul-only
# → 한자
```

### `hangul-hanja-parens`

Outputs the hangul reading followed by the original hanja in parentheses.

```sh
echo "漢字" | gukhanmun --rendering hangul-hanja-parens
# → 한자(漢字)
```

### `hanja-hangul-parens`

Outputs the original hanja followed by the hangul reading in parentheses.

```sh
echo "漢字" | gukhanmun --rendering hanja-hangul-parens
# → 漢字(한자)
```

### `ruby-on-hangul`

Wraps the hangul reading in a `<ruby>` element with the hanja as the
annotation.  Requires HTML or Markdown output (`-f text/html` or
`-f text/markdown`); in plain text falls back to parentheses.

```sh
echo "漢字" | gukhanmun -f text/html --rendering ruby-on-hangul
# → <ruby>한자<rp>(</rp><rt>漢字</rt><rp>)</rp></ruby>
```

The `<rp>` elements hold parenthesized fallback text.  Browsers that support
`<ruby>` hide them and stack the annotation above the base, while browsers
without `<ruby>` support display the gloss in parentheses (`한자(漢字)`)
instead of running it into the base text.

### `ruby-on-hanja`

Wraps the original hanja in a `<ruby>` element with the hangul reading as the
annotation.

```sh
echo "漢字" | gukhanmun -f text/html --rendering ruby-on-hanja
# → <ruby>漢字<rp>(</rp><rt>한자</rt><rp>)</rp></ruby>
```

### `original`

Keeps the original hanja in the output and adds a gloss only where needed to
disambiguate homophones.  Use `--original-gloss` to choose the gloss style:

| `--original-gloss` | Output                                           |
| ------------------ | ------------------------------------------------ |
| `parens`           | 漢字(한자)                                           |
| `ruby`             | `<ruby>漢字<rp>(</rp><rt>한자</rt><rp>)</rp></ruby>` |

```sh
echo "漢字" | gukhanmun --rendering original --original-gloss parens
# → 漢字(한자)
```



---
url: /guide/cli/directives.md
---

# Directives

Directives let you override the dictionary's annotation marks for specific
hanja.  You can require that a hanja always show its reading, always show
the original hanja, or skip annotation entirely.

## Inline flags

### `--require-hanja`

Forces the hanja to always appear in the output (relevant for `hangul-only`
mode, where it would otherwise be dropped):

```sh
gukhanmun --require-hanja 漢 --require-hanja 字 input.txt
```

### `--require-hangul`

Forces the hangul reading to appear alongside the hanja (relevant for
`original` mode):

```sh
gukhanmun --rendering original --require-hangul 東 input.txt
```

### `--skip-annotation`

Suppresses any annotation for the hanja, leaving it as-is in the output:

```sh
gukhanmun --skip-annotation 中 input.txt
```

## Glob patterns

Each directive has a `-glob` variant that matches a shell-style glob against
the hanja key:

```sh
gukhanmun --require-hanja-glob "東*" input.txt
gukhanmun --require-hangul-glob "北[京津]" input.txt
gukhanmun --skip-annotation-glob "中*" input.txt
```

## Directives file

For many directives, use a TSV file with `--directives`:

```sh
gukhanmun --directives overrides.tsv input.txt
```

The file has three tab-separated columns:

| Column    | Values                                               |
| --------- | ---------------------------------------------------- |
| `action`  | `require-hanja`, `require-hangul`, `skip-annotation` |
| `pattern` | The hanja string to match                            |
| `kind`    | `literal` or `glob`                                  |

Lines starting with `#` are comments.  Blank lines are ignored.

Example _overrides.tsv_:

```tsv
# Force reading for proper nouns
require-hanja	東京	literal
require-hanja	北京	literal
# Suppress annotation for all middle-dot separated names
skip-annotation	*·*	glob
```



---
url: /guide/cli/html.md
---

# HTML processing

Pass `-f text/html` (or use a _.html_/_.htm_ extension) to convert an HTML
document or fragment.  Gukhanmun parses the HTML, converts hanja in text
nodes and attributes, and serialises the result back to HTML while preserving
all tags and attributes.

## Elements that are always preserved

Gukhanmun never modifies content inside these elements regardless of any
other settings:

- `<code>`, `<kbd>`, `<pre>`, `<samp>` — code and preformatted text
- `<script>`, `<style>` — scripts and stylesheets
- `<textarea>` — user input areas
- Elements with `translate="no"` — explicit opt-out

Content inside `<ruby>` annotations is also left as-is.

## Preserving additional elements by CSS class

Use `--html-preserve-class` to skip conversion inside elements that carry a
specific class.  The flag can be repeated:

```sh
gukhanmun -f text/html \
  --html-preserve-class math \
  --html-preserve-class no-translate \
  input.html
```

Any element with one of those classes (and all of its descendants) is passed
through unchanged.

## Preserving elements by attribute

Use `--html-preserve-attr` to skip conversion based on an attribute name alone
or an `attribute=value` pair.  The flag can be repeated:

```sh
gukhanmun -f text/html \
  --html-preserve-attr data-no-hanja \
  --html-preserve-attr lang=en \
  input.html
```

The first form matches any element that has the attribute (regardless of its
value).  The second form matches only elements whose attribute equals the
given value.

## Ruby markup

Combine `-f text/html` with `--rendering ruby-on-hangul` or
`--rendering ruby-on-hanja` to wrap conversions in `<ruby>` elements:

```sh
echo "<p>漢字</p>" | gukhanmun -f text/html --rendering ruby-on-hangul
# → <p><ruby>한자<rp>(</rp><rt>漢字</rt><rp>)</rp></ruby></p>
```

The annotation is wrapped in `<rp>` (ruby parenthesis) elements.  Browsers
that understand `<ruby>` hide the `<rp>` content and render the reading
stacked above the base; browsers without `<ruby>` support fall back to
showing the parenthesized gloss inline (`한자(漢字)`), which keeps the
output readable everywhere.



---
url: /guide/cli/markdown.md
---

# Markdown processing

Pass `-f text/markdown` (or use a _.md_/_.markdown_ extension) to convert a
Markdown document.  Gukhanmun converts hanja in the Markdown body while leaving
the syntax it has no opinion about untouched.  To enable GitHub Flavored
Markdown (tables, footnotes, strikethrough, task lists), add the `variant`
parameter:

```sh
gukhanmun -f "text/markdown; variant=GFM" input.md
```

## YAML front matter

A leading YAML front matter block (the `---` delimited block at the very top of
a file) is always recognised and split off before conversion, so it is never
mangled by the Markdown converter.  By default it passes through unchanged while
the Markdown body is converted.

To also convert selected front matter values, use
`--markdown-frontmatter-convert` and address them with a [JSONPath] expression.
The flag can be repeated:

```sh
gukhanmun -f text/markdown \
  --markdown-frontmatter-convert '$.hero.tagline' \
  --markdown-frontmatter-convert '$.hero.actions[*].text' \
  page.md
```

Each value matched by a selector is converted from mixed script to hangul.
Only string scalars are converted; numbers, booleans, and other non-string
matches are left untouched, as are any fields no selector points at.

:::note
Without any selector the front matter is preserved byte-for-byte.  As soon as
a selector is given, the block is parsed and re-serialised, so the whole block
is reformatted on output (comments are dropped and quoting style may change),
even though only matched values change.  A leading `---` without a closing
fence stays ordinary Markdown.  This flag is only valid with
`--format text/markdown`.
:::

[JSONPath]: https://www.rfc-editor.org/rfc/rfc9535



---
url: /guide/rust/install.md
---

# Installation

Add `gukhanmun` to your _Cargo.toml_:

```sh
cargo add gukhanmun
```

## Feature flags

All features are enabled by default.  Disable the ones you do not need to
reduce compile time and binary size:

| Feature    | What it adds                                    | Default |
| ---------- | ----------------------------------------------- | ------- |
| `html`     | HTML fragment conversion                        | yes     |
| `markdown` | Markdown conversion                             | yes     |
| `fst`      | FST dictionary backend (_.gukfst_ files)        | yes     |
| `cdb`      | CDB dictionary backend (_.gukcdb_ files)        | yes     |
| `stdict`   | Bundled _Standard Korean Dictionary_ (\~3 MB)   | yes     |
| `opendict` | Bundled _Open Korean Dictionary_ (우리말샘, \~8 MB) | yes     |

To build without the bundled dictionary (useful when you supply your own):

```sh
cargo add gukhanmun --no-default-features -F fst
```

To build a minimal plain-text-only binary:

```sh
cargo add gukhanmun --no-default-features -F stdict
```



---
url: /guide/rust/start.md
---

# Quick start

Gukhanmun's Rust API is built around a `Builder`/`Converter` pair.  `Builder`
collects options; `Converter` is the immutable runtime produced by
`Builder::build()`.

## Minimal example

```rust
use gukhanmun::{Builder, Preset};

fn main() -> gukhanmun::Result<()> {
    let converter = Builder::with_preset(Preset::KoKr).build()?;
    let output = converter.convert_text_to_string("漢字를 한글로")?;
    println!("{output}");  // 한자를 한글로
    Ok(())
}
```

## Builder pattern

`Builder` uses a fluent interface.  Every setter returns `&mut Self`, so you
can chain calls:

```rust
use gukhanmun::{Builder, Preset, RenderMode, NumeralStrategy};

let converter = Builder::with_preset(Preset::KoKr)
    .rendering(RenderMode::HangulHanjaParens)
    .numerals(NumeralStrategy::Smart)
    .build()?;
```

`Builder::new()` creates a builder with no preset applied (all options at
their individual defaults).  `Builder::with_preset(preset)` applies a preset
first and then lets you override individual options.

## Converting different formats

`Converter` has a conversion method for each supported format:

```rust
// Plain text
let text = converter.convert_text_to_string("漢字를 한글로")?;

// HTML fragment (requires the `html` feature)
let html = converter.convert_html_fragment_to_string("<p>漢字</p>")?;

// Markdown (requires the `markdown` feature)
use gukhanmun::MarkdownVariant;
let md = converter.convert_markdown_to_string("# 漢字", MarkdownVariant::CommonMark)?;
```

All methods return `Result<String, gukhanmun::Error>`.



---
url: /guide/rust/dictionary.md
---

# Dictionaries

Gukhanmun looks up hanja readings from one or more `HanjaDictionary`
implementations.  The `gukhanmun` crate ships with FST and CDB backends and
the bundled _Standard Korean Dictionary_, plus the _Open Korean Dictionary_
(우리말샘) North Korean dictionary used by the `ko-kp` preset.

## Using the bundled dictionary

The bundled dictionary selected by the preset is included automatically.  To
disable every bundled dictionary and rely only on user dictionaries or
fallback readings:

```rust
let converter = Builder::with_preset(Preset::KoKr)
    .no_bundled_dictionaries()
    .build()?;
```

Use `no_bundled_stdict()` or `no_bundled_opendict()` to disable only one
bundled dictionary family.  To re-enable the _Standard Korean Dictionary_
explicitly after calling `no_bundled_stdict()`:

```rust
builder.bundled_stdict();
```

Use the `ko-kp` preset for North Korean orthography.  It disables the initial
sound law and includes the bundled _Open Korean Dictionary_ (우리말샘) North
Korean (北韓語) dictionary:

```rust
let converter = Builder::with_preset(Preset::KoKp).build()?;
assert_eq!(converter.convert_text_to_string("歷史와 來日")?, "력사와 래일");
```

To keep the `ko-kp` orthographic options but disable its bundled _Open Korean
Dictionary_ data:

```rust
let converter = Builder::with_preset(Preset::KoKp)
    .no_bundled_opendict()
    .build()?;
```

## Loading a dictionary from a file

Requires the `fst` or `cdb` feature.

```rust
use gukhanmun::FstDictionary;  // or CdbDictionary

let dict = FstDictionary::open("custom.gukfst")?;
let converter = Builder::with_preset(Preset::KoKr)
    .push_dictionary(dict)
    .build()?;
```

Dictionaries added with `push_dictionary` are consulted before the bundled
dictionary.  The first match across the chain wins.

## Zero-copy static dictionaries

Embed a dictionary directly in your binary with `include_bytes!` and load it
without any file I/O:

```rust
use gukhanmun::FstDictionary;

static MY_DICT: &[u8] = include_bytes!("../data/custom.gukfst");

let dict = FstDictionary::from_static_bytes(MY_DICT)?;
```

`from_static_bytes` does not copy the data; it creates a zero-copy view
backed by the static slice.

## Loading from owned bytes

When the bytes come from a runtime source (network, database, etc.) wrap them
in an `Arc<[u8]>`:

```rust
use std::sync::Arc;
use gukhanmun::CdbDictionary;

let bytes: Vec<u8> = std::fs::read("custom.gukcdb")?;
let dict = CdbDictionary::from_bytes(Arc::from(bytes.as_slice()))?;
```

## Chaining multiple dictionaries

`ChainDictionary` lets you compose several dictionaries with explicit priority
ordering.  The first dictionary in the chain that has a match wins:

```rust
use gukhanmun::{ChainDictionary, FstDictionary, CdbDictionary, HanjaDictionary};

let domain_dict = FstDictionary::open("legal.gukfst")?;
let names_dict = CdbDictionary::open("names.gukcdb")?;
let chain = ChainDictionary::from_iter([
    Box::new(domain_dict) as Box<dyn HanjaDictionary>,
    Box::new(names_dict),
]);

let converter = Builder::with_preset(Preset::KoKr)
    .no_bundled_stdict()
    .push_boxed_dictionary(Box::new(chain))
    .build()?;
```

Alternatively, call `push_dictionary` multiple times; dictionaries are probed
in the order they were pushed, before the bundled dictionary.

## Composing Open Korean Dictionary categories

When the `opendict` feature is enabled, Rust callers can load the _Open Korean
Dictionary_ general, North Korean, dialect, and archaic categories directly.
The `ko-kp` preset includes the North Korean category automatically, but
dialect and archaic data are opt-in:

```rust
use gukhanmun::{Builder, ChainDictionary, HanjaDictionary, Preset};

let chain = ChainDictionary::from_iter([
    Box::new(gukhanmun::opendict::dialect()) as Box<dyn HanjaDictionary>,
    Box::new(gukhanmun::opendict::archaic()),
]);

let converter = Builder::with_preset(Preset::KoKr)
    .push_boxed_dictionary(Box::new(chain))
    .build()?;
```

## Building a custom dictionary

The _.gukfst_ and _.gukcdb_ files loaded above are compiled artifacts, built
from a plain text table with the `gukhanmun-mkdict` tool.  See
[_Building a custom dictionary_](/guide/cli/dictionary.md#building-a-custom-dictionary)
in the CLI guide for how to author and compile dictionary sources.



---
url: /guide/rust/conversion.md
---

# Conversion options

All options are set on `Builder` before calling `.build()`.

## Preset

`Builder::with_preset(preset)` configures a coherent set of defaults:

| Preset         | Dictionary     | Initial sound law | Homophone window          |
| -------------- | -------------- | ----------------- | ------------------------- |
| `Preset::KoKr` | Bundled stdict | `true`            | `ContextWindow::PerBlock` |
| `Preset::KoKp` | None           | `false`           | `ContextWindow::Off`      |

Individual options below override the preset.

## Segmentation strategy

```rust
use gukhanmun::SegmentationStrategy;

builder.segmentation(SegmentationStrategy::Lattice);  // default
builder.segmentation(SegmentationStrategy::Eager);
```

`Lattice` finds the globally optimal segmentation using dynamic programming.
`Eager` is a greedy left-to-right longest-match; faster but less accurate for
compound words.

## Numeral handling

`NumeralStrategy` controls how hanja numeral characters such as 二〇一六 are
rendered.  Chinese-style numerals can represent numbers in positional or
additive notation depending on context:

| Variant            | 二〇一六年 | 十一月   | 一千二百三十四 |
| ------------------ | ----- | ----- | ------- |
| `HangulPhonetic`   | 이공일륙년 | 십일월   | 일천이백삼십사 |
| `PositionalArabic` | 2016년 | (n/a) | (n/a)   |
| `AdditiveArabic`   | (n/a) | 11월   | 1234    |
| `Smart`            | 2016년 | 11월   | 1234    |

```rust
use gukhanmun::NumeralStrategy;

builder.numerals(NumeralStrategy::HangulPhonetic);   // default: 이공일륙
builder.numerals(NumeralStrategy::PositionalArabic); // 2016 (year-like)
builder.numerals(NumeralStrategy::AdditiveArabic);   // 11 (additive)
builder.numerals(NumeralStrategy::Smart);            // picks best per context
```

`Smart` chooses positional notation for year-like four-digit sequences and
additive notation for clear quantities, but keeps phonetic fallback readings
for ambiguous word-like sequences such as `百濟` or `十長生`.

## Initial sound law

```rust
builder.initial_sound_law(true);   // enabled (Preset::KoKr default)
builder.initial_sound_law(false);  // disabled (Preset::KoKp default)
```

Applies the South Korean phonetic rule (頭音法則) to fallback readings for
characters not found in any dictionary:

| Input | Law enabled (`KoKr`) | Law disabled (`KoKp`) |
| ----- | -------------------- | --------------------- |
| 來日    | 내일                   | 래일                    |
| 理由    | 이유                   | 리유                    |
| 女子    | 여자                   | 녀자                    |

## Parenthetical reading annotations

```rust
builder.collapse_redundant_parens(true);   // enabled (default)
builder.collapse_redundant_parens(false);  // keep the parenthetical verbatim
```

When a word carries an explicit parenthetical reading gloss, hanja-first
(`庫間(곳간)`) or hangul-first (`곳간(庫間)`), Gukhanmun removes the redundant
parenthetical and marks the annotation so both scripts appear in every render
mode: `곳간(庫間)` in `HangulOnly`, `庫間(곳간)` in `Original`.  A parenthetical
that pins an alternative reading overrides the dictionary reading for that
occurrence, so `數字(수자)` renders `수자(數字)` even though the dictionary
reads `數字` as `숫자`.

A reading annotation is distinguished from a definition by two rules.  A
parenthetical that exactly matches the word's reading always collapses (this
covers 사이시옷 readings like `庫間(곳간)`).  Otherwise, an alternative reading
is accepted only when it has one hangul syllable per hanja character, each a
valid Sino-Korean reading of that character (as in `數字(수자)`).  A definition
gloss such as `庫間(물건을 간직하여 두는 곳)` and a foreign transliteration such
as `蔣介石(장제스)` (where `介` reads `개`, not `제`) match neither rule and are
left untouched.  The `RedundantParenCollapser` middleware runs first, before
homophone marking, so the corrected reading and flags flow through the rest of
the pipeline.

## Homophone disambiguation window

Different hanja words can share the same hangul reading (for example, 連霸 and
連敗 are both 연패).  In `RenderMode::HangulOnly`, Gukhanmun can keep the hanja
in parentheses for such words so readers can tell them apart.
`homophone_window` sets the scope across which a reading is considered
ambiguous:

| Value                                    | Behaviour                                        |
| ---------------------------------------- | ------------------------------------------------ |
| `ContextWindow::Off`                     | No disambiguation tracking                       |
| `ContextWindow::PerBlock` (KoKr default) | Reset at paragraph, list, and heading boundaries |
| `ContextWindow::PerSection`              | Reset at heading boundaries only                 |
| `ContextWindow::PerDocument`             | Track across the entire input                    |

```rust
use gukhanmun::ContextWindow;

builder.homophone_window(ContextWindow::Off);
builder.homophone_window(ContextWindow::PerBlock);    // default for KoKr
builder.homophone_window(ContextWindow::PerSection);
builder.homophone_window(ContextWindow::PerDocument);
```

Wider windows are appropriate for dense hanja texts where readings recur across
many sections.

## Homophone detection strategy

`homophone_detection` chooses _which_ readings count as ambiguous within the
window:

| Value                                        | Behaviour                                                                            |
| -------------------------------------------- | ------------------------------------------------------------------------------------ |
| `HomophoneDetection::ContextLocal` (default) | Gloss a word only when a different-meaning homophone actually appears in the window. |
| `HomophoneDetection::DictionaryWide`         | Also gloss readings shared by other hanja forms anywhere in the dictionary.          |

```rust
use gukhanmun::HomophoneDetection;

builder.homophone_detection(HomophoneDetection::ContextLocal);    // default
builder.homophone_detection(HomophoneDetection::DictionaryWide);
```

`ContextLocal` keeps hangul-only output clean: a word is glossed only when the
surrounding text genuinely makes it ambiguous.  `DictionaryWide` is broader, but
with a large reference dictionary such as the bundled _Standard Korean
Dictionary_ nearly every common reading has some homophone, so it glosses most
Sino-Korean words.  To always gloss a specific word regardless of context, use
a `DirectiveAction::RequireHanja` directive instead (see
[_User directives_](/guide/rust/directives.md)).

## Only recognized words are disambiguated

Homophone disambiguation operates on words the dictionary recognizes as units.
A hanja sequence with no dictionary entry of its own is not treated as a single
word, and its fallback (non-dictionary) characters are never glossed; any
recognized single-character entries inside it (such as `紫`) are still handled
on their own.  For example, `自由` and `子游` are both bundled entries read
`자유`, so `自由와 子游` renders as `자유(自由)와 자유(子游)`; but `紫楡` has no
entry of its own, so under the default context-local strategy `自由와 紫楡`
renders as `자유와 자유` with no gloss, because the engine never sees a second
`자유` unit to collide with `自由`.  To disambiguate the whole term, add it to a
[custom dictionary](/guide/rust/dictionary.md) so the engine treats it as a single unit.

## First-occurrence clearing window

When enabled, first-occurrence clearing stops annotating a hanja after its
first occurrence within the window.  This is useful for documents that
introduce each character once and then use it freely; subsequent occurrences
are left as plain hangul without parenthetical hanja.

| Value                          | Behaviour                              |
| ------------------------------ | -------------------------------------- |
| `ContextWindow::Off` (default) | Never clear; annotate every occurrence |
| `ContextWindow::PerBlock`      | Clear within the same paragraph/block  |
| `ContextWindow::PerSection`    | Clear within the same section          |
| `ContextWindow::PerDocument`   | Clear across the entire document       |

```rust
builder.first_occurrence_window(ContextWindow::Off);        // default
builder.first_occurrence_window(ContextWindow::PerBlock);
builder.first_occurrence_window(ContextWindow::PerSection);
builder.first_occurrence_window(ContextWindow::PerDocument);
```

## Error recovery

```rust
use gukhanmun::Recovery;

builder.recovery(Recovery::Strict);   // default: abort on error
builder.recovery(Recovery::Lenient);  // skip problematic fragments
```

Relevant for HTML conversion; plain text and Markdown do not produce
recoverable errors.



---
url: /guide/rust/rendering.md
---

# Rendering modes

`builder.rendering(mode)` sets how hanja and their hangul readings appear in
the output.

## `RenderMode` variants

```rust
use gukhanmun::RenderMode;

builder.rendering(RenderMode::HangulOnly);          // "한자" (default)
builder.rendering(RenderMode::HangulHanjaParens);   // "한자(漢字)"
builder.rendering(RenderMode::HanjaHangulParens);   // "漢字(한자)"
builder.rendering(RenderMode::RubyOnHangul);        // <ruby>한자<rp>(</rp><rt>漢字</rt><rp>)</rp></ruby>
builder.rendering(RenderMode::RubyOnHanja);         // <ruby>漢字<rp>(</rp><rt>한자</rt><rp>)</rp></ruby>
builder.rendering(RenderMode::Original);            // keep hanja, gloss where needed
```

`RubyOnHangul` and `RubyOnHanja` produce `<ruby>` markup; they are most
useful with HTML or Markdown output.  In plain-text mode they fall back to
parentheses.  The annotation is wrapped in `<rp>` (ruby parenthesis)
elements so that browsers without `<ruby>` support still render the reading
as a parenthesized gloss (`한자(漢字)`) rather than running it into the base
text.

## `Original` mode with a gloss style

`RenderMode::Original` keeps hanja in place and adds a gloss only for
homophones that need disambiguation.  Use `RenderOptions` to also set the
gloss style:

```rust
use gukhanmun::{RenderOptions, RenderMode, OriginalGloss};

builder.rendering(RenderOptions {
    mode: RenderMode::Original,
    original_gloss: Some(OriginalGloss::Parens),  // or OriginalGloss::Ruby
});
```



---
url: /guide/rust/directives.md
---

# Directives

Directives override the dictionary's annotation marks for specific hanja.

## Literal directive

```rust
use gukhanmun::DirectiveAction;

builder
    .directive("漢", DirectiveAction::RequireHanja)
    .directive("字", DirectiveAction::RequireHanja)
    .directive("東", DirectiveAction::RequireHangul)
    .directive("中", DirectiveAction::SkipAnnotation);
```

| Action           | Effect                                                  |
| ---------------- | ------------------------------------------------------- |
| `RequireHanja`   | Always include the hanja in the output                  |
| `RequireHangul`  | Always include the hangul reading (for `Original` mode) |
| `SkipAnnotation` | Suppress the annotation entirely                        |

## Predicate directive

For pattern-based rules supply a closure:

```rust
builder.directive_predicate(
    |hanja: &str| hanja.starts_with('東'),
    DirectiveAction::RequireHanja,
);
```

Predicates are evaluated at conversion time.  Multiple predicates are OR-ed:
the first matching predicate's action wins.

## Replacing all directives at once

`UserDirectives` collects a set of directives and can be applied in bulk:

```rust
use gukhanmun::{UserDirectives, DirectiveAction};

let mut directives = UserDirectives::new();
directives.add_literal("漢", DirectiveAction::RequireHanja);
directives.add_literal("字", DirectiveAction::RequireHanja);

builder.directives(directives);
```

Calling `builder.directives(d)` replaces all previously registered directives.



---
url: /guide/rust/markdown.md
---

# Markdown conversion

Requires the `markdown` feature (enabled by default).

## Converting a Markdown string

```rust
use gukhanmun::{Builder, Preset, MarkdownVariant};

let converter = Builder::with_preset(Preset::KoKr).build()?;

// CommonMark
let output = converter.convert_markdown_to_string(
    "# 漢字\n\nHanja converted to hangul.",
    MarkdownVariant::CommonMark,
)?;

// GitHub Flavored Markdown (tables, task lists, strikethrough)
let output = converter.convert_markdown_to_string(
    "| 漢字 | 한자 |\n|------|------|\n| 東 | 동 |",
    MarkdownVariant::Gfm,
)?;
```

## What gets converted

Gukhanmun converts hanja inside:

- Paragraph text
- Headings
- List items
- Blockquote content
- Table cells (GFM)
- Inline HTML text nodes

The following are left untouched:

- Fenced and indented code blocks
- Inline code spans (`` `…` ``)
- Raw HTML blocks
- Link and image URLs

## Iterator version

Use `convert_markdown_iter` to process the output token by token:

```rust
use gukhanmun::MarkdownVariant;

for token in converter.convert_markdown_iter(source, MarkdownVariant::CommonMark) {
    print!("{}", token.as_str());
}
```



---
url: /guide/rust/html.md
---

# HTML conversion

Requires the `html` feature (enabled by default).

## Converting an HTML fragment

```rust
use gukhanmun::{Builder, Preset};

let converter = Builder::with_preset(Preset::KoKr).build()?;
let output = converter.convert_html_fragment_to_string("<p>漢字</p>")?;
// → "<p>한자</p>"
```

Gukhanmun parses the input as an HTML fragment (not a full document),
converts hanja in text nodes and attributes, and serialises the result while
preserving all tags and attributes exactly.

## Elements that are always preserved

These elements are never modified:

- `<code>`, `<kbd>`, `<pre>`, `<samp>`
- `<script>`, `<style>`, `<textarea>`
- Elements with `translate="no"`
- `<ruby>` annotation content (`<rt>`, `<rp>`)

## Custom preservation rules

Use `builder.html_preserve_when` to register a predicate that receives the
tag name and attributes of each element and returns `true` to skip conversion:

```rust
builder.html_preserve_when(|tag, attrs| {
    // preserve elements with class "math" or attribute "data-no-hanja"
    let has_math_class = attrs.get("class")
        .is_some_and(|c| c.split_whitespace().any(|cls| cls == "math"));
    let has_attr = attrs.contains_key("data-no-hanja");
    has_math_class || has_attr
});
```

Multiple calls to `html_preserve_when` add additional predicates; any
predicate returning `true` causes the element (and its descendants) to be
preserved.



---
url: /guide/rust/streaming.md
---

# Streaming API

All `convert_*_to_string` methods buffer the full output before returning.
The iterator variants let you process the output token by token, which is
useful for large documents or when you need to write to a sink incrementally.

## Text iterator

```rust
use gukhanmun::{Builder, Preset};

let converter = Builder::with_preset(Preset::KoKr).build()?;

let mut output = String::new();
for token in converter.convert_text_iter("漢字를 한글로") {
    output.push_str(token.as_str());
}
```

`convert_text_iter` returns `impl Iterator<Item = RenderedToken>`.  Each
`RenderedToken` carries a string slice with the output text for that token.

## HTML and Markdown iterators

```rust
use gukhanmun::MarkdownVariant;

// HTML
for token in converter.convert_html_fragment_iter("<p>漢字</p>")? {
    print!("{}", token.as_str());
}

// Markdown
for token in converter.convert_markdown_iter("# 漢字", MarkdownVariant::Gfm) {
    print!("{}", token.as_str());
}
```

## Format-agnostic token pipeline

`convert_tokens` accepts any iterator of `InputToken` and returns an iterator
of `RenderedToken`.  This is the lowest-level entry point and lets you supply
pre-tokenised input from a custom reader:

```rust
use gukhanmun::{InputToken, RenderedToken};

let tokens: Vec<InputToken<&str>> = /* your tokeniser output */;
for rendered in converter.convert_tokens(tokens.into_iter()) {
    print!("{}", rendered.as_str());
}
```

The format adapters (`gukhanmun-html`, `gukhanmun-markdown`) use this
internally.

## Token types

| Type            | Description                                                                                    |
| --------------- | ---------------------------------------------------------------------------------------------- |
| `InputToken`    | A unit of input: hanja run, hangul text, mixed text, block boundary, or section boundary       |
| `OutputToken`   | A unit after dictionary lookup and annotation: annotated hanja, plain text, or boundary marker |
| `RenderedToken` | A unit of output text after rendering; carries the final string                                |



---
url: /guide/javascript/install.md
---

# Installation

Gukhanmun ships two JavaScript implementations that share the same API:

| Package           | Environments                               | Notes                               |
| ----------------- | ------------------------------------------ | ----------------------------------- |
| `@gukhanmun/wasm` | Browsers, Node.js 20+, Deno 2.0+, Bun 1.0+ | Recommended for broad compatibility |
| `@gukhanmun/napi` | Node.js 20+, Deno 2.0+, Bun 1.0+           | Faster on server; native code       |

For most projects, use `@gukhanmun/wasm`.  Switch to `@gukhanmun/napi` for
server workloads where throughput matters.

## WebAssembly

For most environments, the WebAssembly implementation is the best choice.
It runs in browsers, Node.js, Deno, and Bun, and does not require native code.
Install it with your package manager of choice:


```sh [npm]
npm add @gukhanmun/wasm
```

```sh [yarn]
yarn add @gukhanmun/wasm
```

```sh [pnpm]
pnpm add @gukhanmun/wasm
```

```sh [bun]
bun add @gukhanmun/wasm
```

```sh [deno]
deno add jsr:@gukhanmun/wasm
```

## Node-API

For Node.js, Deno, or Bun with the native addon:


```sh [npm]
npm add @gukhanmun/napi
```

```sh [yarn]
yarn add @gukhanmun/napi
```

```sh [pnpm]
pnpm add @gukhanmun/napi
```

```sh [bun]
bun add @gukhanmun/napi
```

```sh [deno]
deno add npm:@gukhanmun/napi
```

## Standard Korean Dictionary

The JavaScript packages do not bundle the _Standard Korean Dictionary_.  Install
it separately:


```sh [npm]
npm add @gukhanmun/stdict-fst
```

```sh [yarn]
yarn add @gukhanmun/stdict-fst
```

```sh [pnpm]
pnpm add @gukhanmun/stdict-fst
```

```sh [bun]
bun add @gukhanmun/stdict-fst
```

```sh [deno]
deno add jsr:@gukhanmun/stdict-fst
```


```sh [npm]
npm add @gukhanmun/stdict-cdb
```

```sh [yarn]
yarn add @gukhanmun/stdict-cdb
```

```sh [pnpm]
pnpm add @gukhanmun/stdict-cdb
```

```sh [bun]
bun add @gukhanmun/stdict-cdb
```

```sh [deno]
deno add jsr:@gukhanmun/stdict-cdb
```

Both packages contain the same dictionary; the formats differ in their
lookup characteristics.  For most use cases, prefer the FST package.

## Open Korean Dictionary

The _Open Korean Dictionary_ (우리말샘) packages are split by dictionary format
and expose separate general (一般語), North Korean (北韓語), dialect (方言),
and archaic (옛말) category loaders:


```sh [npm]
npm add @gukhanmun/opendict-fst
```

```sh [yarn]
yarn add @gukhanmun/opendict-fst
```

```sh [pnpm]
pnpm add @gukhanmun/opendict-fst
```

```sh [bun]
bun add @gukhanmun/opendict-fst
```

```sh [deno]
deno add jsr:@gukhanmun/opendict-fst
```


```sh [npm]
npm add @gukhanmun/opendict-cdb
```

```sh [yarn]
yarn add @gukhanmun/opendict-cdb
```

```sh [pnpm]
pnpm add @gukhanmun/opendict-cdb
```

```sh [bun]
bun add @gukhanmun/opendict-cdb
```

```sh [deno]
deno add jsr:@gukhanmun/opendict-cdb
```

## NAPI platform binaries

`@gukhanmun/napi` includes prebuilt binaries for:

- macOS: ARM64, x86\_64
- Windows: ARM64, x86\_64
- Linux (glibc): ARM64, x86\_64

Alpine Linux (musl) requires building from source.



---
url: /guide/javascript/start.md
---

# Quick start

All Gukhanmun implementations export a single async factory function `load`.
Call it once, then use the returned `Gukhanmun` instance for all conversions.

## Minimal example

```ts twoslash
import { load } from "@gukhanmun/wasm";
import { stdictFst } from "@gukhanmun/stdict-fst";

const g = await load({
  dictionaries: [await stdictFst()],
});

console.log(g.convert("漢字를 한글로"));
// → 한자를 한글로
```

## Switching to the NAPI backend

The API is identical; only the import path changes:

```ts twoslash
import { load } from "@gukhanmun/napi";
import { stdictFst } from "@gukhanmun/stdict-fst";

const g = await load({
  dictionaries: [await stdictFst()],
});
```

## The `convert()` method

`g.convert(source)` converts plain text by default.  Pass a format string or
object as the second argument for HTML or Markdown:

```ts twoslash
import type { Gukhanmun } from "@gukhanmun/types";
const g: Gukhanmun = {} as unknown as Gukhanmun;
// ---cut-before---
g.convert("漢字를 한글로");             // plain text (default)
g.convert("<p>漢字</p>", "html");       // HTML fragment
g.convert("# 漢字", "markdown");        // CommonMark
g.convert("# 漢字", { format: "markdown", gfm: true });  // GFM
```

## Error handling

`load()` and `convert()` throw `GukhanmunError` on failure:

```ts twoslash
import { load, GukhanmunError } from "@gukhanmun/wasm";
import { stdictFst } from "@gukhanmun/stdict-fst";

try {
  const g = await load({ dictionaries: [await stdictFst()] });
  g.convert("<invalid html>", "html");
} catch (e) {
  if (e instanceof GukhanmunError) {
    console.error(e.code, e.message);
  }
}
```



---
url: /guide/javascript/dictionary.md
---

# Dictionaries

Pass an array of `DictionarySource` objects in the `dictionaries` option.
Dictionaries are probed in order; the first match wins.

## Standard Korean Dictionary packages

`@gukhanmun/stdict-fst` and `@gukhanmun/stdict-cdb` both ship the bundled
_Standard Korean Dictionary_ (標準國語大辭典) in different binary formats.

```ts twoslash
// @noErrors: 2451
import { load } from "@gukhanmun/wasm";
import { stdictFst } from "@gukhanmun/stdict-fst";
import { stdictCdb } from "@gukhanmun/stdict-cdb";

// FST — preferred; smaller on disk, better for lattice segmentation
const g = await load({ dictionaries: [await stdictFst()] });

// CDB — O(1) lookup; simpler layout
const g = await load({ dictionaries: [await stdictCdb()] });
```

Both `stdictFst()` and `stdictCdb()` return a `Promise<FileDictionarySource>`.

## Open Korean Dictionary packages

`@gukhanmun/opendict-fst` and `@gukhanmun/opendict-cdb` ship the _Open Korean
Dictionary_ (우리말샘) as separate general (一般語), North Korean (北韓語),
dialect (方言), and archaic (옛말) category dictionaries.  JavaScript presets
do not auto-load these packages, so pass the categories you want explicitly:

```ts twoslash
// @noErrors: 2451
import { load } from "@gukhanmun/wasm";
import {
  opendictDialectFst,
  opendictNorthKoreanFst,
} from "@gukhanmun/opendict-fst";

const g = await load({
  preset: "ko-kp",
  dictionaries: [
    await opendictNorthKoreanFst(),
    await opendictDialectFst(),
  ],
});
```

Use the CDB package when you want the same categories in CDB format:

```ts twoslash
// @noErrors: 2451
import { load } from "@gukhanmun/napi";
import { opendictNorthKoreanCdb } from "@gukhanmun/opendict-cdb";

const g = await load({
  preset: "ko-kp",
  dictionaries: [await opendictNorthKoreanCdb()],
});
```

## Custom dictionaries

A `FileDictionarySource` specifies the binary format and the data to load from:

```ts twoslash
interface FileDictionarySource {
  format: "fst" | "cdb";
  data: ArrayBuffer | ArrayBufferView | URL | string;
}
```

The `data` field accepts:

| Type                            | Where              | Notes                                     |
| ------------------------------- | ------------------ | ----------------------------------------- |
| `ArrayBuffer`/`ArrayBufferView` | All environments   | Bytes already in memory                   |
| `URL`                           | All environments   | Remote or local URL; loaded via `fetch()` |
| `string`                        | Node.js, Deno, Bun | Filesystem path                           |

## Load from a URL

```ts twoslash
import { load } from "@gukhanmun/wasm";
// ---cut-before---
const g = await load({
  dictionaries: [{
    format: "fst",
    data: new URL("./legal.gukfst", import.meta.url),
  }],
});
```

In a browser the URL is fetched with `fetch()`.  In Node.js, Deno, and Bun a
`file://` URL is read from disk.

## Load from bytes

```ts twoslash
import { load } from "@gukhanmun/wasm";
// ---cut-before---
const response = await fetch("/custom.gukcdb");
const buf = await response.arrayBuffer();

const g = await load({
  dictionaries: [{ format: "cdb", data: buf }],
});
```

## Load from a file path (Node.js/Deno/Bun)

```ts twoslash
import { load } from "@gukhanmun/napi";
// ---cut-before---
const g = await load({
  dictionaries: [{ format: "fst", data: "/data/domain.gukfst" }],
});
```

Passing a plain string path in a browser throws `GukhanmunError` with code
`"io"`.

## Combining multiple dictionaries

```ts twoslash
import { load } from "@gukhanmun/napi";
import { stdictFst } from "@gukhanmun/stdict-fst";
// ---cut-before---
const g = await load({
  dictionaries: [
    { format: "fst", data: "/data/legal.gukfst" },  // checked first
    await stdictFst(),                               // fallback
  ],
});
```

## Building a custom dictionary

The _.gukfst_ and _.gukcdb_ files loaded above are compiled artifacts, built
from a plain text table with the `gukhanmun-mkdict` tool.  See
[_Building a custom dictionary_](/guide/cli/dictionary.md#building-a-custom-dictionary)
in the CLI guide for how to author and compile dictionary sources.



---
url: /guide/javascript/conversion.md
---

# Conversion options

Pass these as properties of the `GukhanmunOptions` object to `load()`.

## Preset

`preset` selects a preconfigured set of defaults:

| Value               | Dictionary                          | Initial sound law | Homophone window |
| ------------------- | ----------------------------------- | ----------------- | ---------------- |
| `"ko-kr"` (default) | None bundled—load stdict explicitly | `true`            | `"per-block"`    |
| `"ko-kp"`           | None                                | `false`           | `"off"`          |

```ts twoslash
import { load } from "@gukhanmun/wasm";
// ---cut-before---
const g = await load({ preset: "ko-kp", dictionaries: [] });
```

Unlike the Rust crate, the JavaScript packages never include the bundled
dictionary automatically; always pass it via `dictionaries`.

## Segmentation strategy

`segmentation` controls how Gukhanmun finds word boundaries within hanja runs:

- `"lattice"` (default): evaluates all dictionary matches at every position
  and selects the globally optimal segmentation using dynamic programming.
  Most accurate, especially for compound words and ambiguous boundaries.
- `"eager"`: greedy left-to-right longest-match.  Faster, but may
  mis-segment compound words.

```ts twoslash
import { load } from "@gukhanmun/wasm";
// ---cut-before---
const g = await load({
  segmentation: "lattice",  // default: optimal, dynamic programming
  // segmentation: "eager", // greedy, faster but less accurate
});
```

Prefer `"eager"` only when throughput matters more than accuracy.

## Numeral handling

`numerals` controls how hanja numeral characters such as 二〇一六 are rendered.
Chinese-style numerals can represent numbers in multiple ways depending on
whether they encode positions or quantities:

| Value                         | 二〇一六年 | 十一月   | 一千二百三十四 |
| ----------------------------- | ----- | ----- | ------- |
| `"hangul-phonetic"` (default) | 이공일륙년 | 십일월   | 일천이백삼십사 |
| `"positional-arabic"`         | 2016년 | (n/a) | (n/a)   |
| `"additive-arabic"`           | (n/a) | 11월   | 1234    |
| `"smart"`                     | 2016년 | 11월   | 1234    |

```ts twoslash
// @noErrors: 2451
import { load } from "@gukhanmun/wasm";
// ---cut-before---
const g = await load({ numerals: "hangul-phonetic" }); // 이공일륙 (default)
const g = await load({ numerals: "positional-arabic"}); // 2016
const g = await load({ numerals: "additive-arabic" });  // 11 (月), 1234
const g = await load({ numerals: "smart" });            // picks best per context
```

`"smart"` chooses positional notation for year-like four-digit sequences and
additive notation for clear quantities, but keeps phonetic fallback readings
for ambiguous word-like sequences such as `百濟` or `十長生`.

## Initial sound law

The initial sound law (頭音法則) is a South Korean phonological rule
that changes certain initial consonants at the start of a word.  The rule
applies to fallback readings for characters not found in any dictionary;
dictionary entries already encode their correct readings.

| Input | `initialSoundLaw: true` (ko-kr) | `initialSoundLaw: false` (ko-kp) |
| ----- | ------------------------------- | -------------------------------- |
| 來日    | 내일                              | 래일                               |
| 理由    | 이유                              | 리유                               |
| 女子    | 여자                              | 녀자                               |

```ts twoslash
// @noErrors: 2451
import { load } from "@gukhanmun/wasm";
// ---cut-before---
const g = await load({ initialSoundLaw: true });   // default for ko-kr
const g = await load({ initialSoundLaw: false });  // default for ko-kp
```

Disable it for North Korean orthography (`"ko-kp"` preset) or when processing
text that follows North Korean spelling conventions.

## Parenthetical reading annotations

When a word carries an explicit parenthetical reading gloss, hanja-first
(`庫間(곳간)`) or hangul-first (`곳간(庫間)`), Gukhanmun removes the redundant
parenthetical by default and shows the word in both scripts (`곳간(庫間)`).  A
parenthetical that pins an alternative reading overrides the dictionary reading
for that occurrence, so `數字(수자)` becomes `수자(數字)` even though `數字`
normally reads `숫자`.

```ts twoslash
// @noErrors: 2451
import { load } from "@gukhanmun/wasm";
// ---cut-before---
const g = await load({ collapseRedundantParens: true });   // default
const g = await load({ collapseRedundantParens: false });  // keep verbatim
```

A reading annotation is told apart from a definition by two rules.  A
parenthetical that exactly matches the word's reading always collapses (this
covers 사이시옷 readings like `庫間(곳간)`).  Otherwise, an alternative reading
is accepted only when it has one hangul syllable per hanja character, each a
valid Sino-Korean reading of that character (as in `數字(수자)`).  A definition
gloss such as `庫間(물건을 간직하여 두는 곳)` and a foreign transliteration such
as `蔣介石(장제스)` match neither rule and are left untouched.

## Homophone disambiguation window

Different hanja words can share the same hangul reading (for example, 連霸 and
連敗 are both 연패).  In `"hangul-only"` rendering mode, Gukhanmun can keep the
hanja in parentheses for such words so readers can tell them apart.
`homophoneWindow` sets the scope across which a reading is considered ambiguous:

| Value                               | Behaviour                                        |
| ----------------------------------- | ------------------------------------------------ |
| `"off"`                             | No disambiguation tracking                       |
| `"per-block"` (default for `ko-kr`) | Reset at paragraph, list, and heading boundaries |
| `"per-section"`                     | Reset at heading boundaries only                 |
| `"per-document"`                    | Track across the entire input                    |

```ts twoslash
// @noErrors: 2451
import { load } from "@gukhanmun/wasm";
// ---cut-before---
const g = await load({ homophoneWindow: "off" });
const g = await load({ homophoneWindow: "per-block" });    // default for ko-kr
const g = await load({ homophoneWindow: "per-section" });
const g = await load({ homophoneWindow: "per-document" });
```

Wider windows are appropriate for dense hanja texts where readings recur across
many sections.

## Homophone detection strategy

`homophoneDetection` chooses _which_ readings count as ambiguous within the
window:

| Value                       | Behaviour                                                                            |
| --------------------------- | ------------------------------------------------------------------------------------ |
| `"context-local"` (default) | Gloss a word only when a different-meaning homophone actually appears in the window. |
| `"dictionary-wide"`         | Also gloss readings shared by other hanja forms anywhere in the dictionary.          |

```ts twoslash
// @noErrors: 2451
import { load } from "@gukhanmun/wasm";
// ---cut-before---
const g = await load({ homophoneDetection: "context-local" });    // default
const g = await load({ homophoneDetection: "dictionary-wide" });
```

`"context-local"` keeps hangul-only output clean: a word is glossed only when
the surrounding text genuinely makes it ambiguous.  `"dictionary-wide"` is
broader, but with a large reference dictionary such as the _Standard Korean
Dictionary_ nearly every common reading has some homophone, so it glosses most
Sino-Korean words.  To always gloss a specific word regardless of context, use
a `requireHanja` directive instead (see [_User directives_](/guide/javascript/directives.md)).

## Only recognized words are disambiguated

Homophone disambiguation operates on words the dictionary recognizes as units.
A hanja sequence with no dictionary entry of its own is not treated as a single
word, and its fallback (non-dictionary) characters are never glossed; any
recognized single-character entries inside it (such as `紫`) are still handled
on their own.  For example, with the _Standard Korean Dictionary_ loaded, `自由`
and `子游` are both entries read `자유`, so `自由와 子游` renders as
`자유(自由)와 자유(子游)`; but `紫楡` has no entry of its own, so under the
default context-local strategy `自由와 紫楡` renders as `자유와 자유` with no
gloss, because the engine never sees a second `자유` unit to collide with
`自由`.  To disambiguate the whole term, add it to a
[custom dictionary](/guide/javascript/dictionary.md) so the engine treats it as a single unit.

## First-occurrence clearing window

When enabled, first-occurrence clearing stops annotating a hanja after its
first occurrence within the window.  This is useful for documents that
introduce each character once and then use it freely; subsequent occurrences
are left as plain hangul without parenthetical hanja.

| Value             | Behaviour                              |
| ----------------- | -------------------------------------- |
| `"off"` (default) | Never clear; annotate every occurrence |
| `"per-block"`     | Clear within the same paragraph/block  |
| `"per-section"`   | Clear within the same section          |
| `"per-document"`  | Clear across the entire document       |

```ts twoslash
// @noErrors: 2451
import { load } from "@gukhanmun/wasm";
// ---cut-before---
const g = await load({ firstOccurrenceWindow: "off" });        // default
const g = await load({ firstOccurrenceWindow: "per-block" });
const g = await load({ firstOccurrenceWindow: "per-section" });
const g = await load({ firstOccurrenceWindow: "per-document" });
```

## Error recovery

`recovery` controls what happens when the HTML parser encounters markup it
cannot interpret.  It has no effect for plain text or Markdown input.

```ts twoslash
// @noErrors: 2451
import { load } from "@gukhanmun/wasm";
// ---cut-before---
const g = await load({ recovery: "strict" });   // default: throw on error
const g = await load({ recovery: "lenient" });  // skip bad fragments (HTML)
```

Use `"lenient"` when processing HTML from external sources that may contain
fragments or non-standard markup; it skips problematic parts rather than
throwing a `GukhanmunError`.



---
url: /guide/javascript/rendering.md
---

# Rendering modes

Set the `rendering` option in `load` to control how hanja and their hangul
readings appear in the output.

## Available modes

| Value                     | Input | Output                                           |
| ------------------------- | ----- | ------------------------------------------------ |
| `"hangul-only"` (default) | 漢字    | 한자                                               |
| `"hangul-hanja-parens"`   | 漢字    | 한자(漢字)                                           |
| `"hanja-hangul-parens"`   | 漢字    | 漢字(한자)                                           |
| `"ruby-on-hangul"`        | 漢字    | `<ruby>한자<rp>(</rp><rt>漢字</rt><rp>)</rp></ruby>` |
| `"ruby-on-hanja"`         | 漢字    | `<ruby>漢字<rp>(</rp><rt>한자</rt><rp>)</rp></ruby>` |
| `"original"`              | 漢字    | 漢字 (gloss added where needed)                    |

```ts twoslash
import { load } from "@gukhanmun/wasm";
import { stdictFst } from "@gukhanmun/stdict-fst";

const g = await load({
  rendering: "hangul-hanja-parens",
  dictionaries: [await stdictFst()],
});

console.log(g.convert("漢字"));  // 한자(漢字)
```

## Ruby markup

`"ruby-on-hangul"` and `"ruby-on-hanja"` produce `<ruby>` elements.  Use
them with `"html"` or `"markdown"` format; in plain text they fall back to
parentheses.  The annotation is wrapped in `<rp>` (ruby parenthesis)
elements, so browsers without `<ruby>` support still show the reading as a
parenthesized gloss (`한자(漢字)`) instead of running it into the base text:

```ts twoslash
import { load } from "@gukhanmun/wasm";
import { stdictFst } from "@gukhanmun/stdict-fst";
// ---cut-before---
const g = await load({
  rendering: "ruby-on-hangul",
  dictionaries: [await stdictFst()],
});

console.log(g.convert("<p>漢字</p>", "html"));
// → <p><ruby>한자<rp>(</rp><rt>漢字</rt><rp>)</rp></ruby></p>
```

## Original mode with a gloss

Use `"original"` together with `originalGloss` to add a gloss only where
disambiguation is needed:

```ts twoslash
import { load } from "@gukhanmun/wasm";
import { stdictFst } from "@gukhanmun/stdict-fst";
// ---cut-before---
const g = await load({
  rendering: "original",
  originalGloss: "parens",  // or "ruby"
  dictionaries: [await stdictFst()],
});

console.log(g.convert("東京에서 東洋까지"));
// homophones glossed: 東京(동경)에서 東洋(동양)까지
```



---
url: /guide/javascript/directives.md
---

# Directives

The `directives` option lets you override annotation marks for specific hanja
characters.

## Directive interface

```ts twoslash
interface Directives {
  requireHanja?:    string[];  // always show hanja in output
  requireHangul?:   string[];  // always show hangul reading (for "original" mode)
  skipAnnotation?:  string[];  // suppress annotation entirely
}
```

Each array contains hanja strings whose marks you want to override:

```ts twoslash
import { load } from "@gukhanmun/wasm";
import { stdictFst } from "@gukhanmun/stdict-fst";

const g = await load({
  dictionaries: [await stdictFst()],
  directives: {
    requireHanja:   ["漢", "字"],
    requireHangul:  ["東"],
    skipAnnotation: ["中"],
  },
});
```

## Combining with rendering modes

Directives interact with the active rendering mode:

- `requireHanja` is most visible in `"hangul-only"` mode, where it forces
  the hanja to appear alongside the hangul reading.
- `requireHangul` is useful in `"original"` mode to force the hangul gloss
  for specific characters.
- `skipAnnotation` suppresses any annotation regardless of mode.



---
url: /guide/javascript/markdown.md
---

# Markdown conversion

Pass `"markdown"` as the format to `convert()`:

```ts twoslash
import { load } from "@gukhanmun/wasm";
import { stdictFst } from "@gukhanmun/stdict-fst";

const g = await load({ dictionaries: [await stdictFst()] });

const output = g.convert("# 漢字\n\n漢字를 한글로 변환합니다.", "markdown");
// → "# 한자\n\n한자를 한글로 변환합니다."
```

## GitHub Flavored Markdown

Pass a format object with `gfm: true` to enable GFM extensions (tables, task
lists, strikethrough):

```ts twoslash
import type { Gukhanmun } from "@gukhanmun/types";
const g: Gukhanmun = {} as unknown as Gukhanmun;
// ---cut-before---
const output = g.convert(
  "| 漢字 | 讀音 |\n|------|------|\n| 東 | 동 |",
  { format: "markdown", gfm: true },
);
```

## What gets converted

Gukhanmun converts hanja inside paragraph text, headings, list items,
blockquotes, and table cells.

The following are always left untouched:

- Fenced code blocks and indented code blocks
- Inline code spans (`` `…` ``)
- Raw HTML blocks and inline HTML
- Link and image URLs



---
url: /guide/javascript/html.md
---

# HTML processing

Pass `"html"` as the format to `convert()`:

```ts twoslash
import { load } from "@gukhanmun/wasm";
import { stdictFst } from "@gukhanmun/stdict-fst";

const g = await load({ dictionaries: [await stdictFst()] });

console.log(g.convert("<p>漢字</p>", "html"));
// → <p>한자</p>
```

Gukhanmun parses the input as an HTML fragment, converts hanja in text nodes,
and serialises the result while preserving all tags and attributes.

## Elements that are always preserved

These elements and their descendants are never modified:

- `<code>`, `<kbd>`, `<pre>`, `<samp>`
- `<script>`, `<style>`, `<textarea>`
- Elements with `translate="no"`
- `<ruby>` annotation content

## Preserving elements by CSS class

Use `html.preserveClasses` to skip conversion inside elements that carry
specific classes:

```ts twoslash
import { load } from "@gukhanmun/wasm";
import { stdictFst } from "@gukhanmun/stdict-fst";
// ---cut-before---
const g = await load({
  dictionaries: [await stdictFst()],
  html: {
    preserveClasses: ["math", "no-translate"],
  },
});

const html = `
  <p>漢字</p>
  <span class="math">漢字</span>
`;
console.log(g.convert(html, "html"));
// → <p>한자</p>
//   <span class="math">漢字</span>   ← preserved
```

## Preserving elements by attribute

Use `html.preserveAttributes` to skip conversion based on an attribute name
or an attribute name/value pair:

```ts twoslash
import { load } from "@gukhanmun/wasm";
import { stdictFst } from "@gukhanmun/stdict-fst";
// ---cut-before---
const g = await load({
  dictionaries: [await stdictFst()],
  html: {
    preserveAttributes: [
      "data-no-hanja",            // any element with this attribute
      { name: "lang", value: "en" }, // elements with lang="en"
    ],
  },
});
```

## Ruby markup in HTML

Combine `"html"` format with a ruby rendering mode:

```ts twoslash
import { load } from "@gukhanmun/wasm";
import { stdictFst } from "@gukhanmun/stdict-fst";
// ---cut-before---
const g = await load({
  rendering: "ruby-on-hangul",
  dictionaries: [await stdictFst()],
});

console.log(g.convert("<p>漢字</p>", "html"));
// → <p><ruby>한자<rp>(</rp><rt>漢字</rt><rp>)</rp></ruby></p>
```

The `<rp>` (ruby parenthesis) elements provide a fallback: browsers without
`<ruby>` support display the reading in parentheses (`한자(漢字)`) rather
than running it into the base text.



---
url: /guide/javascript/streaming.md
---

# Streaming API

`g.stream(format?)` returns a
[`TransformStream<string, string>`]
that you can pipe through to convert an arbitrarily large document without
buffering it all at once.

[`TransformStream<string, string>`]: https://developer.mozilla.org/en-US/docs/Web/API/TransformStream

## Basic usage

```ts twoslash
import { load } from "@gukhanmun/wasm";
import { stdictFst } from "@gukhanmun/stdict-fst";

const g = await load({ dictionaries: [await stdictFst()] });
const stream = g.stream("html");

const writer = stream.writable.getWriter();
const reader = stream.readable.getReader();

// Write chunks
await writer.write("<p>漢");
await writer.write("字</p>");
await writer.close();

// Read converted output
const parts: string[] = [];
for (;;) {
  const { done, value } = await reader.read();
  if (done) break;
  if (value) parts.push(value);
}
console.log(parts.join(""));  // <p>한자</p>
```

## Format argument

The format argument to `stream` accepts the same values as `convert()`:

```ts twoslash
import type { Gukhanmun } from "@gukhanmun/types";
const g: Gukhanmun = {} as unknown as Gukhanmun;
// ---cut-before---
g.stream();                              // plain text (default)
g.stream("html");                        // HTML
g.stream("markdown");                    // CommonMark
g.stream({ format: "markdown", gfm: true });  // GFM
```

## Piping with the WHATWG Streams API

`TransformStream` integrates with the standard Streams API:

```ts twoslash
import type { Gukhanmun } from "@gukhanmun/types";
const g: Gukhanmun = {} as unknown as Gukhanmun;
// ---cut-before---
const response = await fetch("/large-document.html");
const converted = response.body!
  .pipeThrough(new TextDecoderStream())
  .pipeThrough(g.stream("html"))
  .pipeThrough(new TextEncoderStream());
```

## Streaming guarantee

Concatenating all chunks written to the stream's writable side and all chunks
read from the readable side is equivalent to calling `g.convert()` on the full
concatenated input:

```ts twoslash
import type { Gukhanmun } from "@gukhanmun/types";
const g: Gukhanmun = {} as unknown as Gukhanmun;
const chunkA: string = "";
const chunkB: string = "";
const chunkC: string = "";
// ---cut-before---
// These are always equivalent:
const result1 = g.convert(chunkA + chunkB + chunkC, "html");

// and
const stream = g.stream("html");
const writer = stream.writable.getWriter();
await writer.write(chunkA);
await writer.write(chunkB);
await writer.write(chunkC);
await writer.close();
const result2 = stream.readable
  .getReader()
  .read()
  .then(({ value }) => value || "");

import assert from "node:assert/strict";
assert.strictEqual(result1, result2);
```

The stream may buffer internally at context boundaries (for example,
`"per-document"` homophone tracking reads the entire document before flushing).
With the default `"per-block"` setting, output is flushed after each block
element.



---
url: /api/index.md
---

# API references

Gukhanmun provides two sets of APIs: one is for Rust, and the other is for
JavaScript.

## Rust

You can find the Rust API references from Docs.rs:

- [gukhanmun]
- [gukhanmun-core]
- [gukhanmun-unihan]
- [gukhanmun-stdict]
- [gukhanmun-opendict]
- [gukhanmun-mkdict]
- [gukhanmun-cdb]
- [gukhanmun-fst]
- [gukhanmun-html]
- [gukhanmun-markdown]

[gukhanmun]: https://docs.rs/gukhanmun/

[gukhanmun-core]: https://docs.rs/gukhanmun-core/

[gukhanmun-unihan]: https://docs.rs/gukhanmun-unihan/

[gukhanmun-stdict]: https://docs.rs/gukhanmun-stdict/

[gukhanmun-opendict]: https://docs.rs/gukhanmun-opendict/

[gukhanmun-mkdict]: https://docs.rs/gukhanmun-mkdict/

[gukhanmun-cdb]: https://docs.rs/gukhanmun-cdb/

[gukhanmun-fst]: https://docs.rs/gukhanmun-fst/

[gukhanmun-html]: https://docs.rs/gukhanmun-html/

[gukhanmun-markdown]: https://docs.rs/gukhanmun-markdown/

## JavaScript

You can find the JavaScript API references from the below pages:

- [@gukhanmun/types](/api/js/modules/_gukhanmun_types.md)
- [@gukhanmun/napi](/api/js/modules/_gukhanmun_napi.md)
- [@gukhanmun/wasm](/api/js/modules/_gukhanmun_wasm.md)
- [@gukhanmun/stdict-cdb](/api/js/modules/_gukhanmun_stdict-cdb.md)
- [@gukhanmun/stdict-fst](/api/js/modules/_gukhanmun_stdict-fst.md)
- [@gukhanmun/opendict-cdb](/api/js/modules/_gukhanmun_opendict-cdb.md)
- [@gukhanmun/opendict-fst](/api/js/modules/_gukhanmun_opendict-fst.md)



---
url: /api/changelog.md
---

# 

# Gukhanmun changelog

<!--
Format guide for contributors:

 -  Version heading: “Version x.y.z” as a level-2 heading (—- underline).

 -  Crate sections: “gukhanmun-*” as a level-3 heading (### prefix).

 -  Package sections: “@gukhanmun/*” as a level-3 heading (### prefix).

 -  Add each change as a bullet point inside the relevant crate or package
    section.  Changes that span the whole workspace go directly under the
    version heading without a subsection.

 -  End each bullet with a bracketed issue or pull request number linked to
    its URL, e.g.:

    ~~~~ md
     -  Fixed a crash when input is empty.  [[#42], [#64]]

    [#42]: https://github.com/dahlia/gukhanmun/issues/42
    [#64]: https://github.com/dahlia/gukhanmun/pull/64
    ~~~~
-->

## Version 0.2.0

Released on June 15, 2026.

### gukhanmun

- Collapse redundant parenthetical reading annotations by default.  The new
  `Builder::collapse_redundant_parens` opt-out disables it.  \[[#3], [#4]]
- Added the `opendict` feature and made the `ko-kp` preset include the
  bundled _Open Korean Dictionary_ (우리말샘) North Korean (北韓語) category
  by default.  Added `Builder::no_bundled_dictionaries()` to disable every
  preset-selected bundled dictionary, plus `Builder::no_bundled_stdict()` and
  `Builder::no_bundled_opendict()` for disabling only one bundled dictionary
  family.  \[[#5], [#6]]

[#3]: https://github.com/dahlia/gukhanmun/issues/3

[#4]: https://github.com/dahlia/gukhanmun/pull/4

[#5]: https://github.com/dahlia/gukhanmun/issues/5

[#6]: https://github.com/dahlia/gukhanmun/pull/6

### gukhanmun-core

- Fixed Arabic hanja numeral strategies so dictionary calendar entries no
  longer split numeric normalization.  `NumeralStrategy::PositionalArabic`
  now renders dates such as `二〇二六年 六月 二〇日` as
  `2026년 6월 20일`, while `NumeralStrategy::HangulPhonetic`, the default
  library preset strategy, still keeps lexicalized dictionary readings such
  as `六月` as `유월`.  `NumeralStrategy::Smart` also leaves standalone large
  place markers such as `京` and `萬`, plus ambiguous small-marker words such
  as `百濟` and `十長生`, as fallback readings instead of splitting them into
  numeric text.

- Fixed a bug where proper names and unknown multi-character hanja words
  were split into individual character annotations when the bundled
  dictionary contained single-character entries for some (but not all) of
  the characters.  The segmenter now emits a `TrivialDictionary` segment
  variant for single-character dictionary matches that carry no special
  rendering marks, and the engine merges consecutive `TrivialDictionary`
  and `Fallback` segments into a single annotation without losing
  `from_dictionary` provenance so homophone marking still works.  \[[#7], [#8]]

- Added `RedundantParenCollapser`, a streaming middleware that collapses an
  explicit parenthetical reading annotation into the hanja word it duplicates.
  `庫間(곳간)` and `곳간(庫間)` now render with both scripts in every mode
  instead of duplicating the reading, and a parenthetical that pins an
  alternative reading (such as “數字(수자)”) overrides the dictionary reading
  for that occurrence.  A definition gloss such as
  “庫間(物件을 간직하여 두는 곳)” is left untouched.  Regenerated the bundled
  Unihan reading data to also carry every kHangul reading per character
  (`KHANGUL_ALL_READINGS`), which the collapser uses to validate alternative
  readings.  \[[#3], [#4]]

- Marked `Annotation` `#[non_exhaustive]` so its policy flags can grow without
  a breaking change (it gained a `from_source_gloss` flag here).  Construct it
  from `Annotation::default()` and set the fields you need.  \[[#3], [#4]]

[#7]: https://github.com/dahlia/gukhanmun/issues/7

[#8]: https://github.com/dahlia/gukhanmun/pull/8

### gukhanmun-dict-extract

- Added a shared extraction helper crate for dictionary dump key
  normalization, original-language parsing, and mixed-script key generation.
  `gukhanmun-stdict` and `gukhanmun-opendict` now use the same core
  extraction rules.  \[[#5], [#6]]

### gukhanmun-cli

- Collapse redundant parenthetical reading annotations by default across the
  plain-text, HTML, and Markdown pipelines.  The new `--no-collapse-parens`
  flag disables it.  \[[#3], [#4]]
- Changed the CLI default for `--numerals` to `smart`, so omitted numeral
  options render dates such as `二〇二六年 六月 二〇日` as
  `2026년 6월 20일`.  Pass `--numerals hangul-phonetic` to keep Seonbi-style
  phonetic calendar readings such as `六月` as `유월`.
- The `ko-kp` preset now includes the bundled _Open Korean Dictionary_ North
  Korean (北韓語) category by default.  Added `--no-bundled-dictionaries`,
  which disables every preset-selected bundled dictionary.  \[[#5], [#6]]

### gukhanmun-opendict

- Added a bundled _Open Korean Dictionary_ (우리말샘) crate generated from the
  2026-06-03 JSON dump.  The crate exposes separate `general()`,
  `north_korean()`, `dialect()`, and `archaic()` FST dictionaries so callers
  can compose the categories explicitly with `ChainDictionary`.  \[[#5], [#6]]

### gukhanmun-stdict

- Reused the shared dictionary extraction helper and buffered direct JSON
  shard reads for large dump extraction.  \[[#5], [#6]]
- Fixed “數字” converting to “수자” instead of the orthographically
  prescribed “숫자.”  The six _Standard Korean Orthography §30_ (한글 맞춤法
  第30項) saisiot (사이시옷) compounds (곳간, 셋방, 숫자, 찻간, 툇간, 횟수)
  now win over their saisiot-free homographs regardless of dump order.
  \[[#1], [#2]]
- Regenerated the bundled dictionary so single-hanja foreign-spelling head
  words (such as “元” → “위안” or “円” → “엔”) no longer shadow the
  Sino-Korean reading of those characters; the engine recovers their original
  sound from the bundled unihan readings instead.
- Regenerated the bundled _Standard Korean Language Dictionary_ data from
  the 2026-06-06 JSON dump (260,690 entries, was 260,688).

[#1]: https://github.com/dahlia/gukhanmun/issues/1

[#2]: https://github.com/dahlia/gukhanmun/pull/2

### @gukhanmun/napi

- Collapse redundant parenthetical reading annotations by default; added the
  `collapseRedundantParens` option to disable it.  \[[#3], [#4]]
- Documented that JavaScript presets still do not auto-load bundled
  dictionary data; use the new opendict packages explicitly when desired.
  \[[#5], [#6]]

### @gukhanmun/wasm

- Collapse redundant parenthetical reading annotations by default; added the
  `collapseRedundantParens` option to disable it.  \[[#3], [#4]]
- Documented that JavaScript presets still do not auto-load bundled
  dictionary data; use the new opendict packages explicitly when desired.
  \[[#5], [#6]]

### @gukhanmun/opendict-cdb

- Added a package containing _Open Korean Dictionary_ general (一般語), North
  Korean (北韓語), dialect (方言), and archaic (옛말) categories as CDB
  binaries, with category-specific byte loaders and `FileDictionarySource`
  helpers.  The binaries ship gzip-compressed (as _\*.cdb.gz_) to stay within
  the JSR per-file size limit, and the byte loaders inflate them
  transparently.  \[[#5], [#6]]

### @gukhanmun/opendict-fst

- Added a package containing _Open Korean Dictionary_ general (一般語), North
  Korean (北韓語), dialect (方言), and archaic (옛말) categories as FST
  binaries, with category-specific byte loaders and `FileDictionarySource`
  helpers.  \[[#5], [#6]]

### @gukhanmun/stdict-fst

- Regenerated the bundled FST binary from the 2026-06-06 _Standard Korean
  Language Dictionary_ JSON dump.

### @gukhanmun/stdict-cdb

- Regenerated the bundled CDB binary from the 2026-06-06 _Standard Korean
  Language Dictionary_ JSON dump.

### @gukhanmun/types

- Updated the JavaScript dictionary option documentation to mention the
  opendict packages and clarify that JavaScript presets do not auto-load
  bundled dictionary data.  \[[#5], [#6]]

## Version 0.1.2

Released on June 1, 2026.

- Static-link the Windows release CLI executables against the MSVC C runtime
  so the release archives no longer require Visual C++ runtime DLLs.
- Include the license and root _README.\*.md_ files in CLI release archives.
- Store CLI release archive contents at the archive root instead of wrapping
  them in a top-level directory.

## Version 0.1.1

Released on June 1, 2026.

### gukhanmun

- Fixed ruby rendering inside Markdown shortcut reference links so the
  high-level Markdown conversion API no longer emits an empty `[]:`
  reference definition.

### gukhanmun-cli

- Fixed ruby rendering inside Markdown shortcut reference links so CLI
  Markdown conversion no longer emits an empty `[]:` reference definition.

### gukhanmun-markdown

- Fixed ruby rendering inside Markdown shortcut reference links so the
  Markdown adapter no longer emits an empty `[]:` reference definition.

### @gukhanmun/napi

- Fixed ruby rendering inside Markdown shortcut reference links so Node-API
  Markdown conversion no longer emits an empty `[]:` reference definition.

### @gukhanmun/wasm

- Fixed ruby rendering inside Markdown shortcut reference links so WebAssembly
  Markdown conversion no longer emits an empty `[]:` reference definition.

## Version 0.1.0

Initial release.  Released on May 30, 2026.



---
url: /api/js/index.md
---

# Gukhanmun

## Modules

- [@gukhanmun/napi](/api/js/modules/_gukhanmun_napi.md)
- [@gukhanmun/opendict-cdb](/api/js/modules/_gukhanmun_opendict-cdb.md)
- [@gukhanmun/opendict-fst](/api/js/modules/_gukhanmun_opendict-fst.md)
- [@gukhanmun/stdict-cdb](/api/js/modules/_gukhanmun_stdict-cdb.md)
- [@gukhanmun/stdict-fst](/api/js/modules/_gukhanmun_stdict-fst.md)
- [@gukhanmun/types](/api/js/modules/_gukhanmun_types.md)
- [@gukhanmun/wasm](/api/js/modules/_gukhanmun_wasm.md)



---
url: /api/js/classes/_gukhanmun_napi.GukhanmunError.md
---

# Class: GukhanmunError

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.

## Extends

- `Error`

## Constructors

### Constructor

> **new GukhanmunError**(`code`, `message`, `chain?`): `GukhanmunError`

Creates a new `GukhanmunError`.

#### Parameters

##### code

[`ErrorCode`](/api/js/types/_gukhanmun_napi.ErrorCode.md)

Machine-readable error code.

##### message

`string`

Human-readable description.

##### chain?

readonly `object`\[] = `[]`

Optional causal chain.

#### Returns

`GukhanmunError`

#### Overrides

`Error.constructor`

## Properties

### cause?

> `optional` **cause?**: `unknown`

#### Inherited from

`Error.cause`

***

### chain

> `readonly` **chain**: readonly `object`\[]

Full causal chain from the Rust `Error::source()` traversal, materialised
at the FFI boundary.  The first element is the root cause; the last is
the immediate error.

***

### code

> `readonly` **code**: [`ErrorCode`](/api/js/types/_gukhanmun_napi.ErrorCode.md)

Machine-readable error code.

#### See

[ErrorCode](/api/js/types/_gukhanmun_napi.ErrorCode.md)

***

### message

> **message**: `string`

#### Inherited from

`Error.message`

***

### name

> **name**: `string`

#### Inherited from

`Error.name`

***

### stack?

> `optional` **stack?**: `string`

#### Inherited from

`Error.stack`

***

### stackTraceLimit

> `static` **stackTraceLimit**: `number`

The `Error.stackTraceLimit` property specifies the number of stack frames
collected by a stack trace (whether generated by `new Error().stack` or
`Error.captureStackTrace(obj)`).

The default value is `10` but may be set to any valid JavaScript number. Changes
will affect any stack trace captured _after_ the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will
not capture any frames.

#### Inherited from

`Error.stackTraceLimit`

## Methods

### captureStackTrace()

> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void`

Creates a `.stack` property on `targetObject`, which when accessed returns
a string representing the location in the code at which
`Error.captureStackTrace()` was called.

```js
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`
```

The first line of the trace will be prefixed with
`${myObject.name}: ${myObject.message}`.

The optional `constructorOpt` argument accepts a function. If given, all frames
above `constructorOpt`, including `constructorOpt`, will be omitted from the
generated stack trace.

The `constructorOpt` argument is useful for hiding implementation
details of error generation from the user. For instance:

```js
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
```

#### Parameters

##### targetObject

`object`

##### constructorOpt?

`Function`

#### Returns

`void`

#### Inherited from

`Error.captureStackTrace`

***

### prepareStackTrace()

> `static` **prepareStackTrace**(`err`, `stackTraces`): `any`

#### Parameters

##### err

`Error`

##### stackTraces

`CallSite`\[]

#### Returns

`any`

#### See

[https://v8.dev/docs/stack-trace-api#customizing-stack-traces](https://v8.dev/docs/stack-trace-api#customizing-stack-traces)

#### Inherited from

`Error.prepareStackTrace`



---
url: /api/js/classes/_gukhanmun_types.GukhanmunError.md
---

# Class: GukhanmunError

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.

## Extends

- `Error`

## Constructors

### Constructor

> **new GukhanmunError**(`message?`): `GukhanmunError`

#### Parameters

##### message?

`string`

#### Returns

`GukhanmunError`

#### Inherited from

`Error.constructor`

### Constructor

> **new GukhanmunError**(`message?`, `options?`): `GukhanmunError`

#### Parameters

##### message?

`string`

##### options?

`ErrorOptions`

#### Returns

`GukhanmunError`

#### Inherited from

`Error.constructor`

## Properties

### cause?

> `optional` **cause?**: `unknown`

#### Inherited from

`Error.cause`

***

### chain

> `readonly` **chain**: readonly `object`\[]

Ordered list of underlying causes, derived from the Rust
`std::error::Error::source()` chain.  The first entry is the immediate
cause; subsequent entries are deeper causes.  Empty when there is no
chain.

***

### code

> `readonly` **code**: [`ErrorCode`](/api/js/types/_gukhanmun_types.ErrorCode.md)

Machine-readable discriminant for the error.

#### See

[ErrorCode](/api/js/types/_gukhanmun_types.ErrorCode.md)

***

### message

> **message**: `string`

#### Inherited from

`Error.message`

***

### name

> **name**: `string`

#### Inherited from

`Error.name`

***

### stack?

> `optional` **stack?**: `string`

#### Inherited from

`Error.stack`

***

### stackTraceLimit

> `static` **stackTraceLimit**: `number`

The `Error.stackTraceLimit` property specifies the number of stack frames
collected by a stack trace (whether generated by `new Error().stack` or
`Error.captureStackTrace(obj)`).

The default value is `10` but may be set to any valid JavaScript number. Changes
will affect any stack trace captured _after_ the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will
not capture any frames.

#### Inherited from

`Error.stackTraceLimit`

## Methods

### captureStackTrace()

> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void`

Creates a `.stack` property on `targetObject`, which when accessed returns
a string representing the location in the code at which
`Error.captureStackTrace()` was called.

```js
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`
```

The first line of the trace will be prefixed with
`${myObject.name}: ${myObject.message}`.

The optional `constructorOpt` argument accepts a function. If given, all frames
above `constructorOpt`, including `constructorOpt`, will be omitted from the
generated stack trace.

The `constructorOpt` argument is useful for hiding implementation
details of error generation from the user. For instance:

```js
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
```

#### Parameters

##### targetObject

`object`

##### constructorOpt?

`Function`

#### Returns

`void`

#### Inherited from

`Error.captureStackTrace`

***

### prepareStackTrace()

> `static` **prepareStackTrace**(`err`, `stackTraces`): `any`

#### Parameters

##### err

`Error`

##### stackTraces

`CallSite`\[]

#### Returns

`any`

#### See

[https://v8.dev/docs/stack-trace-api#customizing-stack-traces](https://v8.dev/docs/stack-trace-api#customizing-stack-traces)

#### Inherited from

`Error.prepareStackTrace`



---
url: /api/js/classes/_gukhanmun_wasm.GukhanmunError.md
---

# Class: GukhanmunError

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.

## Extends

- `Error`

## Constructors

### Constructor

> **new GukhanmunError**(`code`, `message`, `chain?`): `GukhanmunError`

Creates a new `GukhanmunError`.

#### Parameters

##### code

[`ErrorCode`](/api/js/types/_gukhanmun_napi.ErrorCode.md)

Machine-readable error code.

##### message

`string`

Human-readable description.

##### chain?

readonly `object`\[] = `[]`

Optional causal chain.

#### Returns

`GukhanmunError`

#### Overrides

`Error.constructor`

## Properties

### cause?

> `optional` **cause?**: `unknown`

#### Inherited from

`Error.cause`

***

### chain

> `readonly` **chain**: readonly `object`\[]

Full causal chain from the Rust `Error::source()` traversal, materialised
at the FFI boundary.  The first element is the root cause; the last is
the immediate error.

***

### code

> `readonly` **code**: [`ErrorCode`](/api/js/types/_gukhanmun_napi.ErrorCode.md)

Machine-readable error code.

#### See

[ErrorCode](/api/js/types/_gukhanmun_napi.ErrorCode.md)

***

### message

> **message**: `string`

#### Inherited from

`Error.message`

***

### name

> **name**: `string`

#### Inherited from

`Error.name`

***

### stack?

> `optional` **stack?**: `string`

#### Inherited from

`Error.stack`

***

### stackTraceLimit

> `static` **stackTraceLimit**: `number`

The `Error.stackTraceLimit` property specifies the number of stack frames
collected by a stack trace (whether generated by `new Error().stack` or
`Error.captureStackTrace(obj)`).

The default value is `10` but may be set to any valid JavaScript number. Changes
will affect any stack trace captured _after_ the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will
not capture any frames.

#### Inherited from

`Error.stackTraceLimit`

## Methods

### captureStackTrace()

> `static` **captureStackTrace**(`targetObject`, `constructorOpt?`): `void`

Creates a `.stack` property on `targetObject`, which when accessed returns
a string representing the location in the code at which
`Error.captureStackTrace()` was called.

```js
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`
```

The first line of the trace will be prefixed with
`${myObject.name}: ${myObject.message}`.

The optional `constructorOpt` argument accepts a function. If given, all frames
above `constructorOpt`, including `constructorOpt`, will be omitted from the
generated stack trace.

The `constructorOpt` argument is useful for hiding implementation
details of error generation from the user. For instance:

```js
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
```

#### Parameters

##### targetObject

`object`

##### constructorOpt?

`Function`

#### Returns

`void`

#### Inherited from

`Error.captureStackTrace`

***

### prepareStackTrace()

> `static` **prepareStackTrace**(`err`, `stackTraces`): `any`

#### Parameters

##### err

`Error`

##### stackTraces

`CallSite`\[]

#### Returns

`any`

#### See

[https://v8.dev/docs/stack-trace-api#customizing-stack-traces](https://v8.dev/docs/stack-trace-api#customizing-stack-traces)

#### Inherited from

`Error.prepareStackTrace`



---
url: /api/js/functions/_gukhanmun_napi.load.md
---

# Function: load()

> **load**(`options?`): `Promise`\<[`Gukhanmun`](/api/js/interfaces/_gukhanmun_napi.Gukhanmun.md)>

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.

## Parameters

### options?

[`GukhanmunOptions`](/api/js/interfaces/_gukhanmun_napi.GukhanmunOptions.md) = `{}`

Conversion options.  All fields are optional; defaults match
the `ko-kr` preset.

## Returns

`Promise`\<[`Gukhanmun`](/api/js/interfaces/_gukhanmun_napi.Gukhanmun.md)>

A `{@link Gukhanmun}` instance.

## Throws

[GukhanmunError](/api/js/classes/_gukhanmun_napi.GukhanmunError.md) on invalid options or dictionary load failure.



---
url: /api/js/functions/_gukhanmun_opendict-cdb.opendictArchaicCdb.md
---

# Function: opendictArchaicCdb()

> **opendictArchaicCdb**(): `Promise`\<[`FileDictionarySource`](/api/js/interfaces/_gukhanmun_napi.FileDictionarySource.md)>

Loads the bundled Open Korean Dictionary 옛말 dictionary.

## Returns

`Promise`\<[`FileDictionarySource`](/api/js/interfaces/_gukhanmun_napi.FileDictionarySource.md)>

A `FileDictionarySource` with `format: "cdb"`.



---
url: /api/js/functions/_gukhanmun_opendict-cdb.opendictArchaicCdbBytes.md
---

# Function: opendictArchaicCdbBytes()

> **opendictArchaicCdbBytes**(`url?`): `Promise`\<`Uint8Array`\<`ArrayBufferLike`>>

Loads the bundled Open Korean Dictionary 옛말 CDB binary as raw bytes.

## Parameters

### url?

`URL` = `opendictArchaicCdbUrl`

Location of the CDB binary to read. Defaults to the bundled
[opendictArchaicCdbUrl](/api/js/variables/_gukhanmun_opendict-cdb.opendictArchaicCdbUrl.md).

## Returns

`Promise`\<`Uint8Array`\<`ArrayBufferLike`>>

The CDB binary as a `Uint8Array`.



---
url: /api/js/functions/_gukhanmun_opendict-cdb.opendictCdbBytes.md
---

# Function: opendictCdbBytes()

> **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.

## Parameters

### url

`URL`

Location of the CDB binary to read.

## Returns

`Promise`\<`Uint8Array`\<`ArrayBufferLike`>>

The CDB binary as a `Uint8Array`.



---
url: /api/js/functions/_gukhanmun_opendict-cdb.opendictDialectCdb.md
---

# Function: opendictDialectCdb()

> **opendictDialectCdb**(): `Promise`\<[`FileDictionarySource`](/api/js/interfaces/_gukhanmun_napi.FileDictionarySource.md)>

Loads the bundled Open Korean Dictionary 방언 dictionary.

## Returns

`Promise`\<[`FileDictionarySource`](/api/js/interfaces/_gukhanmun_napi.FileDictionarySource.md)>

A `FileDictionarySource` with `format: "cdb"`.



---
url: /api/js/functions/_gukhanmun_opendict-cdb.opendictDialectCdbBytes.md
---

# Function: opendictDialectCdbBytes()

> **opendictDialectCdbBytes**(`url?`): `Promise`\<`Uint8Array`\<`ArrayBufferLike`>>

Loads the bundled Open Korean Dictionary 방언 CDB binary as raw bytes.

## Parameters

### url?

`URL` = `opendictDialectCdbUrl`

Location of the CDB binary to read. Defaults to the bundled
[opendictDialectCdbUrl](/api/js/variables/_gukhanmun_opendict-cdb.opendictDialectCdbUrl.md).

## Returns

`Promise`\<`Uint8Array`\<`ArrayBufferLike`>>

The CDB binary as a `Uint8Array`.



---
url: /api/js/functions/_gukhanmun_opendict-cdb.opendictGeneralCdb.md
---

# Function: opendictGeneralCdb()

> **opendictGeneralCdb**(): `Promise`\<[`FileDictionarySource`](/api/js/interfaces/_gukhanmun_napi.FileDictionarySource.md)>

Loads the bundled Open Korean Dictionary 일반어 dictionary.

## Returns

`Promise`\<[`FileDictionarySource`](/api/js/interfaces/_gukhanmun_napi.FileDictionarySource.md)>

A `FileDictionarySource` with `format: "cdb"`.



---
url: /api/js/functions/_gukhanmun_opendict-cdb.opendictGeneralCdbBytes.md
---

# Function: opendictGeneralCdbBytes()

> **opendictGeneralCdbBytes**(`url?`): `Promise`\<`Uint8Array`\<`ArrayBufferLike`>>

Loads the bundled Open Korean Dictionary 일반어 CDB binary as raw bytes.

## Parameters

### url?

`URL` = `opendictGeneralCdbUrl`

Location of the CDB binary to read. Defaults to the bundled
[opendictGeneralCdbUrl](/api/js/variables/_gukhanmun_opendict-cdb.opendictGeneralCdbUrl.md).

## Returns

`Promise`\<`Uint8Array`\<`ArrayBufferLike`>>

The CDB binary as a `Uint8Array`.



---
url: /api/js/functions/_gukhanmun_opendict-cdb.opendictNorthKoreanCdb.md
---

# Function: opendictNorthKoreanCdb()

> **opendictNorthKoreanCdb**(): `Promise`\<[`FileDictionarySource`](/api/js/interfaces/_gukhanmun_napi.FileDictionarySource.md)>

Loads the bundled Open Korean Dictionary 북한어 dictionary.

## Returns

`Promise`\<[`FileDictionarySource`](/api/js/interfaces/_gukhanmun_napi.FileDictionarySource.md)>

A `FileDictionarySource` with `format: "cdb"`.



---
url: /api/js/functions/_gukhanmun_opendict-cdb.opendictNorthKoreanCdbBytes.md
---

# Function: opendictNorthKoreanCdbBytes()

> **opendictNorthKoreanCdbBytes**(`url?`): `Promise`\<`Uint8Array`\<`ArrayBufferLike`>>

Loads the bundled Open Korean Dictionary 북한어 CDB binary as raw bytes.

## Parameters

### url?

`URL` = `opendictNorthKoreanCdbUrl`

Location of the CDB binary to read. Defaults to the bundled
[opendictNorthKoreanCdbUrl](/api/js/variables/_gukhanmun_opendict-cdb.opendictNorthKoreanCdbUrl.md).

## Returns

`Promise`\<`Uint8Array`\<`ArrayBufferLike`>>

The CDB binary as a `Uint8Array`.



---
url: /api/js/functions/_gukhanmun_opendict-fst.opendictArchaicFst.md
---

# Function: opendictArchaicFst()

> **opendictArchaicFst**(): `Promise`\<[`FileDictionarySource`](/api/js/interfaces/_gukhanmun_napi.FileDictionarySource.md)>

Loads the bundled Open Korean Dictionary 옛말 dictionary.

## Returns

`Promise`\<[`FileDictionarySource`](/api/js/interfaces/_gukhanmun_napi.FileDictionarySource.md)>

A `FileDictionarySource` with `format: "fst"`.



---
url: /api/js/functions/_gukhanmun_opendict-fst.opendictArchaicFstBytes.md
---

# Function: opendictArchaicFstBytes()

> **opendictArchaicFstBytes**(`url?`): `Promise`\<`Uint8Array`\<`ArrayBufferLike`>>

Loads the bundled Open Korean Dictionary 옛말 FST binary as raw bytes.

## Parameters

### url?

`URL` = `opendictArchaicFstUrl`

Location of the FST binary to read. Defaults to the bundled
[opendictArchaicFstUrl](/api/js/variables/_gukhanmun_opendict-fst.opendictArchaicFstUrl.md).

## Returns

`Promise`\<`Uint8Array`\<`ArrayBufferLike`>>

The FST binary as a `Uint8Array`.



---
url: /api/js/functions/_gukhanmun_opendict-fst.opendictDialectFst.md
---

# Function: opendictDialectFst()

> **opendictDialectFst**(): `Promise`\<[`FileDictionarySource`](/api/js/interfaces/_gukhanmun_napi.FileDictionarySource.md)>

Loads the bundled Open Korean Dictionary 방언 dictionary.

## Returns

`Promise`\<[`FileDictionarySource`](/api/js/interfaces/_gukhanmun_napi.FileDictionarySource.md)>

A `FileDictionarySource` with `format: "fst"`.



---
url: /api/js/functions/_gukhanmun_opendict-fst.opendictDialectFstBytes.md
---

# Function: opendictDialectFstBytes()

> **opendictDialectFstBytes**(`url?`): `Promise`\<`Uint8Array`\<`ArrayBufferLike`>>

Loads the bundled Open Korean Dictionary 방언 FST binary as raw bytes.

## Parameters

### url?

`URL` = `opendictDialectFstUrl`

Location of the FST binary to read. Defaults to the bundled
[opendictDialectFstUrl](/api/js/variables/_gukhanmun_opendict-fst.opendictDialectFstUrl.md).

## Returns

`Promise`\<`Uint8Array`\<`ArrayBufferLike`>>

The FST binary as a `Uint8Array`.



---
url: /api/js/functions/_gukhanmun_opendict-fst.opendictFstBytes.md
---

# Function: opendictFstBytes()

> **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`.

## Parameters

### url

`URL`

Location of the FST binary to read.

## Returns

`Promise`\<`Uint8Array`\<`ArrayBufferLike`>>

The FST binary as a `Uint8Array`.



---
url: /api/js/functions/_gukhanmun_opendict-fst.opendictGeneralFst.md
---

# Function: opendictGeneralFst()

> **opendictGeneralFst**(): `Promise`\<[`FileDictionarySource`](/api/js/interfaces/_gukhanmun_napi.FileDictionarySource.md)>

Loads the bundled Open Korean Dictionary 일반어 dictionary.

## Returns

`Promise`\<[`FileDictionarySource`](/api/js/interfaces/_gukhanmun_napi.FileDictionarySource.md)>

A `FileDictionarySource` with `format: "fst"`.



---
url: /api/js/functions/_gukhanmun_opendict-fst.opendictGeneralFstBytes.md
---

# Function: opendictGeneralFstBytes()

> **opendictGeneralFstBytes**(`url?`): `Promise`\<`Uint8Array`\<`ArrayBufferLike`>>

Loads the bundled Open Korean Dictionary 일반어 FST binary as raw bytes.

## Parameters

### url?

`URL` = `opendictGeneralFstUrl`

Location of the FST binary to read. Defaults to the bundled
[opendictGeneralFstUrl](/api/js/variables/_gukhanmun_opendict-fst.opendictGeneralFstUrl.md).

## Returns

`Promise`\<`Uint8Array`\<`ArrayBufferLike`>>

The FST binary as a `Uint8Array`.



---
url: /api/js/functions/_gukhanmun_opendict-fst.opendictNorthKoreanFst.md
---

# Function: opendictNorthKoreanFst()

> **opendictNorthKoreanFst**(): `Promise`\<[`FileDictionarySource`](/api/js/interfaces/_gukhanmun_napi.FileDictionarySource.md)>

Loads the bundled Open Korean Dictionary 북한어 dictionary.

## Returns

`Promise`\<[`FileDictionarySource`](/api/js/interfaces/_gukhanmun_napi.FileDictionarySource.md)>

A `FileDictionarySource` with `format: "fst"`.



---
url: /api/js/functions/_gukhanmun_opendict-fst.opendictNorthKoreanFstBytes.md
---

# Function: opendictNorthKoreanFstBytes()

> **opendictNorthKoreanFstBytes**(`url?`): `Promise`\<`Uint8Array`\<`ArrayBufferLike`>>

Loads the bundled Open Korean Dictionary 북한어 FST binary as raw bytes.

## Parameters

### url?

`URL` = `opendictNorthKoreanFstUrl`

Location of the FST binary to read. Defaults to the bundled
[opendictNorthKoreanFstUrl](/api/js/variables/_gukhanmun_opendict-fst.opendictNorthKoreanFstUrl.md).

## Returns

`Promise`\<`Uint8Array`\<`ArrayBufferLike`>>

The FST binary as a `Uint8Array`.



---
url: /api/js/functions/_gukhanmun_stdict-cdb.stdictCdb.md
---

# Function: stdictCdb()

> **stdictCdb**(): `Promise`\<[`FileDictionarySource`](/api/js/interfaces/_gukhanmun_napi.FileDictionarySource.md)>

Loads the bundled Standard Korean Language Dictionary as a
[FileDictionarySource](/api/js/interfaces/_gukhanmun_napi.FileDictionarySource.md) ready to pass to `load({ dictionaries: [...] })`.

## Returns

`Promise`\<[`FileDictionarySource`](/api/js/interfaces/_gukhanmun_napi.FileDictionarySource.md)>

A `FileDictionarySource` with `format: "cdb"`.



---
url: /api/js/functions/_gukhanmun_stdict-cdb.stdictCdbBytes.md
---

# Function: stdictCdbBytes()

> **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](/api/js/variables/_gukhanmun_stdict-cdb.stdictCdbUrl.md)) 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".

## Parameters

### url?

`URL` = `stdictCdbUrl`

Location of the CDB binary to read.  Defaults to the bundled
[stdictCdbUrl](/api/js/variables/_gukhanmun_stdict-cdb.stdictCdbUrl.md); pass another URL to load a relocated copy.

## Returns

`Promise`\<`Uint8Array`\<`ArrayBuffer`>>

The CDB binary as a `Uint8Array`.



---
url: /api/js/functions/_gukhanmun_stdict-fst.stdictFst.md
---

# Function: stdictFst()

> **stdictFst**(): `Promise`\<[`FileDictionarySource`](/api/js/interfaces/_gukhanmun_napi.FileDictionarySource.md)>

Loads the bundled Standard Korean Language Dictionary as a
[FileDictionarySource](/api/js/interfaces/_gukhanmun_napi.FileDictionarySource.md) ready to pass to `load({ dictionaries: [...] })`.

## Returns

`Promise`\<[`FileDictionarySource`](/api/js/interfaces/_gukhanmun_napi.FileDictionarySource.md)>

A `FileDictionarySource` with `format: "fst"`.



---
url: /api/js/functions/_gukhanmun_stdict-fst.stdictFstBytes.md
---

# Function: stdictFstBytes()

> **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](/api/js/variables/_gukhanmun_stdict-fst.stdictFstUrl.md)) 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".

## Parameters

### url?

`URL` = `stdictFstUrl`

Location of the FST binary to read.  Defaults to the bundled
[stdictFstUrl](/api/js/variables/_gukhanmun_stdict-fst.stdictFstUrl.md); pass another URL to load a relocated copy.

## Returns

`Promise`\<`Uint8Array`\<`ArrayBuffer`>>

The FST binary as a `Uint8Array`.



---
url: /api/js/functions/_gukhanmun_wasm.load.md
---

# Function: load()

> **load**(`options?`): `Promise`\<[`Gukhanmun`](/api/js/interfaces/_gukhanmun_napi.Gukhanmun.md)>

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.

## Parameters

### options?

[`GukhanmunOptions`](/api/js/interfaces/_gukhanmun_napi.GukhanmunOptions.md) = `{}`

Conversion options.  All fields are optional; defaults match
the `ko-kr` preset.

## Returns

`Promise`\<[`Gukhanmun`](/api/js/interfaces/_gukhanmun_napi.Gukhanmun.md)>

A `{@link Gukhanmun}` instance.

## Throws

[GukhanmunError](/api/js/classes/_gukhanmun_wasm.GukhanmunError.md) on invalid options or dictionary load failure.



---
url: /api/js/interfaces/_gukhanmun_napi.DictionaryEntry.md
---

# Interface: DictionaryEntry

A single dictionary entry returned by a dictionary lookup.

## Properties

### hanja

> `readonly` **hanja**: `string`

The hanja form (key), e.g. `"漢字"`.

***

### reading

> `readonly` **reading**: `string`

The hangul reading, e.g. `"한자"`.

***

### requireHangul?

> `readonly` `optional` **requireHangul?**: `boolean`

When `true`, the renderer should always show a hangul gloss alongside
the original hanja (used with `rendering: "original"`).

Corresponds to Rust `MatchMark::require_hangul`.

***

### requireHanja?

> `readonly` `optional` **requireHanja?**: `boolean`

When `true`, the renderer should always show the original hanja
alongside the hangul reading, regardless of ambiguity.

Corresponds to Rust `MatchMark::require_hanja`.



---
url: /api/js/interfaces/_gukhanmun_napi.Directives.md
---

# Interface: Directives

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`.

## Properties

### requireHangul?

> `readonly` `optional` **requireHangul?**: readonly `string`\[]

Hanja forms that must always be shown with a hangul gloss alongside the
original hanja (relevant for `rendering: "original"`).

***

### requireHanja?

> `readonly` `optional` **requireHanja?**: readonly `string`\[]

Hanja forms that must always be shown with their original hanja
alongside the hangul reading, as if `requireHanja` were set in the
dictionary.

***

### skipAnnotation?

> `readonly` `optional` **skipAnnotation?**: readonly `string`\[]

Hanja forms whose annotation should be suppressed entirely; the renderer
emits only the primary plain text form (hangul or hanja depending on
`rendering`).



---
url: /api/js/interfaces/_gukhanmun_napi.FileDictionarySource.md
---

# Interface: FileDictionarySource

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`).

## Properties

### data

> `readonly` **data**: `string` | `URL` | `ArrayBuffer` | `ArrayBufferView`\<`ArrayBufferLike`>

The binary dictionary data or a reference to where it can be loaded.

Pass a `BufferSource` for data already in memory, a `URL` for a remote
or local URL (resolved via `fetch` or `readFile`), or a path `string`
for filesystem paths (Node.js / Deno 2.0+ / Bun only).

***

### format

> `readonly` **format**: `"fst"` | `"cdb"`

The on-disk format of the dictionary file.

- `"fst"` — Gukhanmun FST file (`*.gukfst`); preferred for small
  WebAssembly bundles.  Supported in all runtimes.
- `"cdb"` — Gukhanmun CDB-trie file (`*.gukcdb`); preferred when code
  auditability or trivial mmap support matters.  Requires a filesystem
  or in-memory bytes; supported in Node-API and (with `from_bytes`) in
  WASM builds that include the `cdb` feature.

The `"tsv"` format is reserved for future use; passing it throws
`GukhanmunError` with code `"unsupported-content-type"`.



---
url: /api/js/interfaces/_gukhanmun_napi.Gukhanmun.md
---

# Interface: Gukhanmun

A configured hanja-to-hangul converter.  Created by calling
[GukhanmunFactory.load](/api/js/interfaces/_gukhanmun_napi.GukhanmunFactory.md#load) (or the top-level `load` function).

The instance is immutable after creation; call `load` again to obtain a
converter with different options.

## Properties

### options

> `readonly` **options**: `Readonly`\<`Required`\<`Omit`\<[`GukhanmunOptions`](/api/js/interfaces/_gukhanmun_napi.GukhanmunOptions.md), `"dictionaries"` | `"directives"` | `"html"` | `"originalGloss"`>>>

Read-only view of the resolved options (after preset defaults are
applied).  Excludes `dictionaries`, `directives`, `html`, and
`originalGloss`, which are not meaningfully representable as plain
values.

## Methods

### convert()

> **convert**(`source`, `format?`): `string`

Converts `source` to hangul in one shot.  Buffers the entire input
before returning.

#### Parameters

##### source

`string`

The text to convert.

##### format?

[`Format`](/api/js/types/_gukhanmun_napi.Format.md)

Input / output format.  Defaults to `"text"`.

#### Returns

`string`

The converted text.

#### Throws

[GukhanmunError](/api/js/classes/_gukhanmun_napi.GukhanmunError.md) on conversion failure.

***

### stream()

> **stream**(`format?`): `TransformStream`\<`string`, `string`>

Returns a `TransformStream<string, string>` that converts chunks
incrementally.  Chunks are JavaScript strings; byte-level encoding is
the caller's responsibility (`TextDecoderStream` / `TextEncoderStream`).

The stream guarantees that the concatenated output equals the result of
calling `convert` on the concatenated input, regardless of chunk
boundaries.  Document-wide middlewares (e.g., homophone marking with
`homophoneWindow: "per-document"`) buffer until the writable side is
closed.

#### Parameters

##### format?

[`Format`](/api/js/types/_gukhanmun_napi.Format.md)

Input / output format.  Defaults to `"text"`.

#### Returns

`TransformStream`\<`string`, `string`>

A platform `TransformStream<string, string>`.

#### Throws

[GukhanmunError](/api/js/classes/_gukhanmun_napi.GukhanmunError.md) on initialisation failure (not on chunk
errors; those are signalled via the stream's error channel).



---
url: /api/js/interfaces/_gukhanmun_napi.GukhanmunFactory.md
---

# Interface: GukhanmunFactory

Factory interface satisfied by both `@gukhanmun/wasm` and
`@gukhanmun/napi`.

## Example

```ts
import { load } from "@gukhanmun/wasm";
import { stdictFst } from "@gukhanmun/stdict-fst";

const g = await load({
  preset: "ko-kr",
  dictionaries: [await stdictFst()],
});
console.log(g.convert("漢字를 한글로"));
```

## Methods

### load()

> **load**(`options?`): `Promise`\<[`Gukhanmun`](/api/js/interfaces/_gukhanmun_napi.Gukhanmun.md)>

Loads and initialises a [Gukhanmun](/api/js/interfaces/_gukhanmun_napi.Gukhanmun.md) converter with the given
options.

In the WASM implementation this involves asynchronous `.wasm` binary
initialisation; in the Node-API implementation the native addon is
synchronously ready but still returns a `Promise` for API uniformity.
Dictionary sources with `URL` or string `data` are fetched / read during
this call.

#### Parameters

##### options?

[`GukhanmunOptions`](/api/js/interfaces/_gukhanmun_napi.GukhanmunOptions.md)

Conversion options.  All fields are optional; unset
fields inherit defaults from the selected `preset` (or `"ko-kr"` when
no preset is given).

#### Returns

`Promise`\<[`Gukhanmun`](/api/js/interfaces/_gukhanmun_napi.Gukhanmun.md)>

A ready-to-use [Gukhanmun](/api/js/interfaces/_gukhanmun_napi.Gukhanmun.md) instance.

#### Throws

[GukhanmunError](/api/js/classes/_gukhanmun_napi.GukhanmunError.md) when an option value is unrecognised
(`code: "invalid-input"`) or a dictionary fails to load
(`code: "dictionary-load"`).



---
url: /api/js/interfaces/_gukhanmun_napi.GukhanmunOptions.md
---

# Interface: GukhanmunOptions

Full set of options passed to [GukhanmunFactory.load](/api/js/interfaces/_gukhanmun_napi.GukhanmunFactory.md#load) (or the
top-level `load` function) to configure a [Gukhanmun](/api/js/interfaces/_gukhanmun_napi.Gukhanmun.md) 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.

## Properties

### collapseRedundantParens?

> `readonly` `optional` **collapseRedundantParens?**: `boolean`

Whether to collapse redundant parenthetical reading annotations.  Defaults
to `true`.

When enabled, an explicit gloss such as `庫間(곳간)` or `곳간(庫間)` is
recognised, the redundant parenthetical is removed, and the annotation is
shown in both scripts in every render mode.  A parenthetical that pins an
alternative reading (for example `數字(수자)`) overrides the dictionary
reading for that occurrence.  A parenthetical that is a definition rather
than a reading (for example `庫間(물건을 간직하여 두는 곳)`) is left
untouched.

***

### dictionaries?

> `readonly` `optional` **dictionaries?**: readonly [`FileDictionarySource`](/api/js/interfaces/_gukhanmun_napi.FileDictionarySource.md)\[]

Ordered list of dictionary sources.  Sources are queried in order;
earlier entries take precedence.  When omitted (or empty), only the
fallback Unihan character map is used (no bundled dictionaries).

JavaScript presets do **not**
automatically include bundled dictionary data.  To use the _Standard
Korean Language Dictionary_, add `@gukhanmun/stdict-fst` or
`@gukhanmun/stdict-cdb` explicitly.  To use Open Korean Dictionary
categories, add `@gukhanmun/opendict-fst` or
`@gukhanmun/opendict-cdb` explicitly.

#### See

[DictionarySource](/api/js/types/_gukhanmun_napi.DictionarySource.md)

***

### directives?

> `readonly` `optional` **directives?**: [`Directives`](/api/js/interfaces/_gukhanmun_napi.Directives.md)

Per-hanja rendering directives that override dictionary marks.

#### See

[Directives](/api/js/interfaces/_gukhanmun_napi.Directives.md)

***

### firstOccurrenceWindow?

> `readonly` `optional` **firstOccurrenceWindow?**: [`ContextWindow`](/api/js/types/_gukhanmun_napi.ContextWindow.md)

Context window for first-occurrence filtering.  The
`FirstOccurrenceFilter` middleware clears `requireHanja` /
`requireHangul` on repeated occurrences of the same word within this
window, so the gloss appears only the first time.  Defaults to `"off"`
(filter disabled) in both presets.

#### See

[ContextWindow](/api/js/types/_gukhanmun_napi.ContextWindow.md)

***

### homophoneDetection?

> `readonly` `optional` **homophoneDetection?**: [`HomophoneDetection`](/api/js/types/_gukhanmun_napi.HomophoneDetection.md)

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 [homophoneWindow](#homophonewindow).  Use
`"dictionary-wide"` to also gloss readings shared by other dictionary
entries.

#### See

[HomophoneDetection](/api/js/types/_gukhanmun_napi.HomophoneDetection.md)

***

### homophoneWindow?

> `readonly` `optional` **homophoneWindow?**: [`ContextWindow`](/api/js/types/_gukhanmun_napi.ContextWindow.md)

Context window for homophone disambiguation.  The `HomophoneMarker`
middleware sets `homophone = true` on annotations whose hangul reading
collides within this window.  Defaults to `"per-block"`.

#### See

[ContextWindow](/api/js/types/_gukhanmun_napi.ContextWindow.md)

***

### html?

> `readonly` `optional` **html?**: [`HtmlOptions`](/api/js/interfaces/_gukhanmun_napi.HtmlOptions.md)

HTML-specific preservation rules.  Ignored for non-HTML input formats.

#### See

[HtmlOptions](/api/js/interfaces/_gukhanmun_napi.HtmlOptions.md)

***

### initialSoundLaw?

> `readonly` `optional` **initialSoundLaw?**: `boolean`

Whether to apply the Korean initial sound law (頭音法則) to fallback
phonetic readings.  Defaults to `true` for `"ko-kr"` and `false` for
`"ko-kp"`.

Note: dictionary entries are assumed to encode the correct reading
already; this flag only affects the character-by-character fallback path.

***

### numerals?

> `readonly` `optional` **numerals?**: [`NumeralStrategy`](/api/js/types/_gukhanmun_napi.NumeralStrategy.md)

How runs of hanja numerals are converted.  Defaults to
`"hangul-phonetic"`.

#### See

[NumeralStrategy](/api/js/types/_gukhanmun_napi.NumeralStrategy.md)

***

### originalGloss?

> `readonly` `optional` **originalGloss?**: [`OriginalGloss`](/api/js/types/_gukhanmun_napi.OriginalGloss.md)

How glosses are rendered when `rendering` is `"original"`.  Ignored for
all other render modes.  Defaults to `"parens"`.

#### See

[OriginalGloss](/api/js/types/_gukhanmun_napi.OriginalGloss.md)

***

### preset?

> `readonly` `optional` **preset?**: [`Preset`](/api/js/types/_gukhanmun_napi.Preset.md)

Named configuration preset.  Defaults to `"ko-kr"`.

#### See

[Preset](/api/js/types/_gukhanmun_napi.Preset.md)

***

### recovery?

> `readonly` `optional` **recovery?**: [`Recovery`](/api/js/types/_gukhanmun_napi.Recovery.md)

Error recovery policy for HTML scanning.  Defaults to `"strict"`.
Ignored for non-HTML input formats.

#### See

[Recovery](/api/js/types/_gukhanmun_napi.Recovery.md)

***

### rendering?

> `readonly` `optional` **rendering?**: [`RenderMode`](/api/js/types/_gukhanmun_napi.RenderMode.md)

How annotations are rendered into output text or markup.  Defaults to
`"hangul-only"`.

#### See

[RenderMode](/api/js/types/_gukhanmun_napi.RenderMode.md)

***

### segmentation?

> `readonly` `optional` **segmentation?**: [`Segmentation`](/api/js/types/_gukhanmun_napi.Segmentation.md)

Hanja-span segmentation algorithm.  Defaults to `"lattice"`.

#### See

[Segmentation](/api/js/types/_gukhanmun_napi.Segmentation.md)



---
url: /api/js/interfaces/_gukhanmun_napi.HtmlOptions.md
---

# Interface: HtmlOptions

Fine-grained HTML preservation rules passed in
[GukhanmunOptions.html](/api/js/interfaces/_gukhanmun_napi.GukhanmunOptions.md#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.

## Properties

### preserveAttributes?

> `readonly` `optional` **preserveAttributes?**: readonly (`string` | \{ `name`: `string`; `value?`: `string`; })\[]

Attribute matchers; an element is preserved when it carries a matching
attribute.  Each entry is either:

- A bare string — preserve any element that has the attribute, regardless
  of value (e.g. `"data-no-translate"`).
- An object `{ name, value? }` — preserve elements where the attribute
  equals `value`, or has the attribute when `value` is omitted.

Equivalent to `--html-preserve-attr KEY[=VALUE]` on the CLI.

***

### preserveClasses?

> `readonly` `optional` **preserveClasses?**: readonly `string`\[]

Class names whose containing element (and all descendants) should be
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.



---
url: /api/js/interfaces/_gukhanmun_types.DictionaryEntry.md
---

# Interface: DictionaryEntry

A single dictionary entry returned by a dictionary lookup.

## Properties

### hanja

> `readonly` **hanja**: `string`

The hanja form (key), e.g. `"漢字"`.

***

### reading

> `readonly` **reading**: `string`

The hangul reading, e.g. `"한자"`.

***

### requireHangul?

> `readonly` `optional` **requireHangul?**: `boolean`

When `true`, the renderer should always show a hangul gloss alongside
the original hanja (used with `rendering: "original"`).

Corresponds to Rust `MatchMark::require_hangul`.

***

### requireHanja?

> `readonly` `optional` **requireHanja?**: `boolean`

When `true`, the renderer should always show the original hanja
alongside the hangul reading, regardless of ambiguity.

Corresponds to Rust `MatchMark::require_hanja`.



---
url: /api/js/interfaces/_gukhanmun_types.Directives.md
---

# Interface: Directives

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`.

## Properties

### requireHangul?

> `readonly` `optional` **requireHangul?**: readonly `string`\[]

Hanja forms that must always be shown with a hangul gloss alongside the
original hanja (relevant for `rendering: "original"`).

***

### requireHanja?

> `readonly` `optional` **requireHanja?**: readonly `string`\[]

Hanja forms that must always be shown with their original hanja
alongside the hangul reading, as if `requireHanja` were set in the
dictionary.

***

### skipAnnotation?

> `readonly` `optional` **skipAnnotation?**: readonly `string`\[]

Hanja forms whose annotation should be suppressed entirely; the renderer
emits only the primary plain text form (hangul or hanja depending on
`rendering`).



---
url: /api/js/interfaces/_gukhanmun_types.FileDictionarySource.md
---

# Interface: FileDictionarySource

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`).

## Properties

### data

> `readonly` **data**: `string` | `URL` | `ArrayBuffer` | `ArrayBufferView`\<`ArrayBufferLike`>

The binary dictionary data or a reference to where it can be loaded.

Pass a `BufferSource` for data already in memory, a `URL` for a remote
or local URL (resolved via `fetch` or `readFile`), or a path `string`
for filesystem paths (Node.js / Deno 2.0+ / Bun only).

***

### format

> `readonly` **format**: `"fst"` | `"cdb"`

The on-disk format of the dictionary file.

- `"fst"` — Gukhanmun FST file (`*.gukfst`); preferred for small
  WebAssembly bundles.  Supported in all runtimes.
- `"cdb"` — Gukhanmun CDB-trie file (`*.gukcdb`); preferred when code
  auditability or trivial mmap support matters.  Requires a filesystem
  or in-memory bytes; supported in Node-API and (with `from_bytes`) in
  WASM builds that include the `cdb` feature.

The `"tsv"` format is reserved for future use; passing it throws
`GukhanmunError` with code `"unsupported-content-type"`.



---
url: /api/js/interfaces/_gukhanmun_types.Gukhanmun.md
---

# Interface: Gukhanmun

A configured hanja-to-hangul converter.  Created by calling
[GukhanmunFactory.load](/api/js/interfaces/_gukhanmun_types.GukhanmunFactory.md#load) (or the top-level `load` function).

The instance is immutable after creation; call `load` again to obtain a
converter with different options.

## Properties

### options

> `readonly` **options**: `Readonly`\<`Required`\<`Omit`\<[`GukhanmunOptions`](/api/js/interfaces/_gukhanmun_types.GukhanmunOptions.md), `"dictionaries"` | `"directives"` | `"html"` | `"originalGloss"`>>>

Read-only view of the resolved options (after preset defaults are
applied).  Excludes `dictionaries`, `directives`, `html`, and
`originalGloss`, which are not meaningfully representable as plain
values.

## Methods

### convert()

> **convert**(`source`, `format?`): `string`

Converts `source` to hangul in one shot.  Buffers the entire input
before returning.

#### Parameters

##### source

`string`

The text to convert.

##### format?

[`Format`](/api/js/types/_gukhanmun_types.Format.md)

Input / output format.  Defaults to `"text"`.

#### Returns

`string`

The converted text.

#### Throws

[GukhanmunError](/api/js/classes/_gukhanmun_types.GukhanmunError.md) on conversion failure.

***

### stream()

> **stream**(`format?`): `TransformStream`\<`string`, `string`>

Returns a `TransformStream<string, string>` that converts chunks
incrementally.  Chunks are JavaScript strings; byte-level encoding is
the caller's responsibility (`TextDecoderStream` / `TextEncoderStream`).

The stream guarantees that the concatenated output equals the result of
calling `convert` on the concatenated input, regardless of chunk
boundaries.  Document-wide middlewares (e.g., homophone marking with
`homophoneWindow: "per-document"`) buffer until the writable side is
closed.

#### Parameters

##### format?

[`Format`](/api/js/types/_gukhanmun_types.Format.md)

Input / output format.  Defaults to `"text"`.

#### Returns

`TransformStream`\<`string`, `string`>

A platform `TransformStream<string, string>`.

#### Throws

[GukhanmunError](/api/js/classes/_gukhanmun_types.GukhanmunError.md) on initialisation failure (not on chunk
errors; those are signalled via the stream's error channel).



---
url: /api/js/interfaces/_gukhanmun_types.GukhanmunFactory.md
---

# Interface: GukhanmunFactory

Factory interface satisfied by both `@gukhanmun/wasm` and
`@gukhanmun/napi`.

## Example

```ts
import { load } from "@gukhanmun/wasm";
import { stdictFst } from "@gukhanmun/stdict-fst";

const g = await load({
  preset: "ko-kr",
  dictionaries: [await stdictFst()],
});
console.log(g.convert("漢字를 한글로"));
```

## Methods

### load()

> **load**(`options?`): `Promise`\<[`Gukhanmun`](/api/js/interfaces/_gukhanmun_types.Gukhanmun.md)>

Loads and initialises a [Gukhanmun](/api/js/interfaces/_gukhanmun_types.Gukhanmun.md) converter with the given
options.

In the WASM implementation this involves asynchronous `.wasm` binary
initialisation; in the Node-API implementation the native addon is
synchronously ready but still returns a `Promise` for API uniformity.
Dictionary sources with `URL` or string `data` are fetched / read during
this call.

#### Parameters

##### options?

[`GukhanmunOptions`](/api/js/interfaces/_gukhanmun_types.GukhanmunOptions.md)

Conversion options.  All fields are optional; unset
fields inherit defaults from the selected `preset` (or `"ko-kr"` when
no preset is given).

#### Returns

`Promise`\<[`Gukhanmun`](/api/js/interfaces/_gukhanmun_types.Gukhanmun.md)>

A ready-to-use [Gukhanmun](/api/js/interfaces/_gukhanmun_types.Gukhanmun.md) instance.

#### Throws

[GukhanmunError](/api/js/classes/_gukhanmun_types.GukhanmunError.md) when an option value is unrecognised
(`code: "invalid-input"`) or a dictionary fails to load
(`code: "dictionary-load"`).



---
url: /api/js/interfaces/_gukhanmun_types.GukhanmunOptions.md
---

# Interface: GukhanmunOptions

Full set of options passed to [GukhanmunFactory.load](/api/js/interfaces/_gukhanmun_types.GukhanmunFactory.md#load) (or the
top-level `load` function) to configure a [Gukhanmun](/api/js/interfaces/_gukhanmun_types.Gukhanmun.md) 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.

## Properties

### collapseRedundantParens?

> `readonly` `optional` **collapseRedundantParens?**: `boolean`

Whether to collapse redundant parenthetical reading annotations.  Defaults
to `true`.

When enabled, an explicit gloss such as `庫間(곳간)` or `곳간(庫間)` is
recognised, the redundant parenthetical is removed, and the annotation is
shown in both scripts in every render mode.  A parenthetical that pins an
alternative reading (for example `數字(수자)`) overrides the dictionary
reading for that occurrence.  A parenthetical that is a definition rather
than a reading (for example `庫間(물건을 간직하여 두는 곳)`) is left
untouched.

***

### dictionaries?

> `readonly` `optional` **dictionaries?**: readonly [`FileDictionarySource`](/api/js/interfaces/_gukhanmun_types.FileDictionarySource.md)\[]

Ordered list of dictionary sources.  Sources are queried in order;
earlier entries take precedence.  When omitted (or empty), only the
fallback Unihan character map is used (no bundled dictionaries).

JavaScript presets do **not**
automatically include bundled dictionary data.  To use the _Standard
Korean Language Dictionary_, add `@gukhanmun/stdict-fst` or
`@gukhanmun/stdict-cdb` explicitly.  To use Open Korean Dictionary
categories, add `@gukhanmun/opendict-fst` or
`@gukhanmun/opendict-cdb` explicitly.

#### See

[DictionarySource](/api/js/types/_gukhanmun_types.DictionarySource.md)

***

### directives?

> `readonly` `optional` **directives?**: [`Directives`](/api/js/interfaces/_gukhanmun_types.Directives.md)

Per-hanja rendering directives that override dictionary marks.

#### See

[Directives](/api/js/interfaces/_gukhanmun_types.Directives.md)

***

### firstOccurrenceWindow?

> `readonly` `optional` **firstOccurrenceWindow?**: [`ContextWindow`](/api/js/types/_gukhanmun_types.ContextWindow.md)

Context window for first-occurrence filtering.  The
`FirstOccurrenceFilter` middleware clears `requireHanja` /
`requireHangul` on repeated occurrences of the same word within this
window, so the gloss appears only the first time.  Defaults to `"off"`
(filter disabled) in both presets.

#### See

[ContextWindow](/api/js/types/_gukhanmun_types.ContextWindow.md)

***

### homophoneDetection?

> `readonly` `optional` **homophoneDetection?**: [`HomophoneDetection`](/api/js/types/_gukhanmun_types.HomophoneDetection.md)

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 [homophoneWindow](#homophonewindow).  Use
`"dictionary-wide"` to also gloss readings shared by other dictionary
entries.

#### See

[HomophoneDetection](/api/js/types/_gukhanmun_types.HomophoneDetection.md)

***

### homophoneWindow?

> `readonly` `optional` **homophoneWindow?**: [`ContextWindow`](/api/js/types/_gukhanmun_types.ContextWindow.md)

Context window for homophone disambiguation.  The `HomophoneMarker`
middleware sets `homophone = true` on annotations whose hangul reading
collides within this window.  Defaults to `"per-block"`.

#### See

[ContextWindow](/api/js/types/_gukhanmun_types.ContextWindow.md)

***

### html?

> `readonly` `optional` **html?**: [`HtmlOptions`](/api/js/interfaces/_gukhanmun_types.HtmlOptions.md)

HTML-specific preservation rules.  Ignored for non-HTML input formats.

#### See

[HtmlOptions](/api/js/interfaces/_gukhanmun_types.HtmlOptions.md)

***

### initialSoundLaw?

> `readonly` `optional` **initialSoundLaw?**: `boolean`

Whether to apply the Korean initial sound law (頭音法則) to fallback
phonetic readings.  Defaults to `true` for `"ko-kr"` and `false` for
`"ko-kp"`.

Note: dictionary entries are assumed to encode the correct reading
already; this flag only affects the character-by-character fallback path.

***

### numerals?

> `readonly` `optional` **numerals?**: [`NumeralStrategy`](/api/js/types/_gukhanmun_types.NumeralStrategy.md)

How runs of hanja numerals are converted.  Defaults to
`"hangul-phonetic"`.

#### See

[NumeralStrategy](/api/js/types/_gukhanmun_types.NumeralStrategy.md)

***

### originalGloss?

> `readonly` `optional` **originalGloss?**: [`OriginalGloss`](/api/js/types/_gukhanmun_types.OriginalGloss.md)

How glosses are rendered when `rendering` is `"original"`.  Ignored for
all other render modes.  Defaults to `"parens"`.

#### See

[OriginalGloss](/api/js/types/_gukhanmun_types.OriginalGloss.md)

***

### preset?

> `readonly` `optional` **preset?**: [`Preset`](/api/js/types/_gukhanmun_types.Preset.md)

Named configuration preset.  Defaults to `"ko-kr"`.

#### See

[Preset](/api/js/types/_gukhanmun_types.Preset.md)

***

### recovery?

> `readonly` `optional` **recovery?**: [`Recovery`](/api/js/types/_gukhanmun_types.Recovery.md)

Error recovery policy for HTML scanning.  Defaults to `"strict"`.
Ignored for non-HTML input formats.

#### See

[Recovery](/api/js/types/_gukhanmun_types.Recovery.md)

***

### rendering?

> `readonly` `optional` **rendering?**: [`RenderMode`](/api/js/types/_gukhanmun_types.RenderMode.md)

How annotations are rendered into output text or markup.  Defaults to
`"hangul-only"`.

#### See

[RenderMode](/api/js/types/_gukhanmun_types.RenderMode.md)

***

### segmentation?

> `readonly` `optional` **segmentation?**: [`Segmentation`](/api/js/types/_gukhanmun_types.Segmentation.md)

Hanja-span segmentation algorithm.  Defaults to `"lattice"`.

#### See

[Segmentation](/api/js/types/_gukhanmun_types.Segmentation.md)



---
url: /api/js/interfaces/_gukhanmun_types.HtmlOptions.md
---

# Interface: HtmlOptions

Fine-grained HTML preservation rules passed in
[GukhanmunOptions.html](/api/js/interfaces/_gukhanmun_types.GukhanmunOptions.md#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.

## Properties

### preserveAttributes?

> `readonly` `optional` **preserveAttributes?**: readonly (`string` | \{ `name`: `string`; `value?`: `string`; })\[]

Attribute matchers; an element is preserved when it carries a matching
attribute.  Each entry is either:

- A bare string — preserve any element that has the attribute, regardless
  of value (e.g. `"data-no-translate"`).
- An object `{ name, value? }` — preserve elements where the attribute
  equals `value`, or has the attribute when `value` is omitted.

Equivalent to `--html-preserve-attr KEY[=VALUE]` on the CLI.

***

### preserveClasses?

> `readonly` `optional` **preserveClasses?**: readonly `string`\[]

Class names whose containing element (and all descendants) should be
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.



---
url: /api/js/modules/_gukhanmun_napi.md
---

# Module: @gukhanmun/napi

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.

## Example

```ts
import { load } from "@gukhanmun/napi";
import { stdictFst } from "@gukhanmun/stdict-fst";

const g = await load({ dictionaries: [await stdictFst()] });
console.log(g.convert("漢字를 한글로"));  // "한자를 한글로"
```

## Classes

- [GukhanmunError](/api/js/classes/_gukhanmun_napi.GukhanmunError.md)

## Interfaces

- [DictionaryEntry](/api/js/interfaces/_gukhanmun_napi.DictionaryEntry.md)
- [Directives](/api/js/interfaces/_gukhanmun_napi.Directives.md)
- [FileDictionarySource](/api/js/interfaces/_gukhanmun_napi.FileDictionarySource.md)
- [Gukhanmun](/api/js/interfaces/_gukhanmun_napi.Gukhanmun.md)
- [GukhanmunFactory](/api/js/interfaces/_gukhanmun_napi.GukhanmunFactory.md)
- [GukhanmunOptions](/api/js/interfaces/_gukhanmun_napi.GukhanmunOptions.md)
- [HtmlOptions](/api/js/interfaces/_gukhanmun_napi.HtmlOptions.md)

## Type Aliases

- [ContextWindow](/api/js/types/_gukhanmun_napi.ContextWindow.md)
- [DictionarySource](/api/js/types/_gukhanmun_napi.DictionarySource.md)
- [ErrorCode](/api/js/types/_gukhanmun_napi.ErrorCode.md)
- [Format](/api/js/types/_gukhanmun_napi.Format.md)
- [HomophoneDetection](/api/js/types/_gukhanmun_napi.HomophoneDetection.md)
- [NumeralStrategy](/api/js/types/_gukhanmun_napi.NumeralStrategy.md)
- [OriginalGloss](/api/js/types/_gukhanmun_napi.OriginalGloss.md)
- [Preset](/api/js/types/_gukhanmun_napi.Preset.md)
- [Recovery](/api/js/types/_gukhanmun_napi.Recovery.md)
- [RenderMode](/api/js/types/_gukhanmun_napi.RenderMode.md)
- [Segmentation](/api/js/types/_gukhanmun_napi.Segmentation.md)

## Functions

- [load](/api/js/functions/_gukhanmun_napi.load.md)



---
url: /api/js/modules/_gukhanmun_opendict-cdb.md
---

# Module: @gukhanmun/opendict-cdb

Open Korean Dictionary (우리말샘) categories prebuilt as CDB binaries for use
with `{@link load}` from `@gukhanmun/wasm` or `@gukhanmun/napi`.

## Example

```ts
import { load } from "@gukhanmun/napi";
import { opendictNorthKoreanCdb } from "@gukhanmun/opendict-cdb";

const g = await load({
  preset: "ko-kp",
  dictionaries: [await opendictNorthKoreanCdb()],
});
console.log(g.convert("歷史와 來日"));  // "력사와 래일"
```

## Variables

- [opendictArchaicCdbUrl](/api/js/variables/_gukhanmun_opendict-cdb.opendictArchaicCdbUrl.md)
- [opendictDialectCdbUrl](/api/js/variables/_gukhanmun_opendict-cdb.opendictDialectCdbUrl.md)
- [opendictGeneralCdbUrl](/api/js/variables/_gukhanmun_opendict-cdb.opendictGeneralCdbUrl.md)
- [opendictNorthKoreanCdbUrl](/api/js/variables/_gukhanmun_opendict-cdb.opendictNorthKoreanCdbUrl.md)

## Functions

- [opendictArchaicCdb](/api/js/functions/_gukhanmun_opendict-cdb.opendictArchaicCdb.md)
- [opendictArchaicCdbBytes](/api/js/functions/_gukhanmun_opendict-cdb.opendictArchaicCdbBytes.md)
- [opendictCdbBytes](/api/js/functions/_gukhanmun_opendict-cdb.opendictCdbBytes.md)
- [opendictDialectCdb](/api/js/functions/_gukhanmun_opendict-cdb.opendictDialectCdb.md)
- [opendictDialectCdbBytes](/api/js/functions/_gukhanmun_opendict-cdb.opendictDialectCdbBytes.md)
- [opendictGeneralCdb](/api/js/functions/_gukhanmun_opendict-cdb.opendictGeneralCdb.md)
- [opendictGeneralCdbBytes](/api/js/functions/_gukhanmun_opendict-cdb.opendictGeneralCdbBytes.md)
- [opendictNorthKoreanCdb](/api/js/functions/_gukhanmun_opendict-cdb.opendictNorthKoreanCdb.md)
- [opendictNorthKoreanCdbBytes](/api/js/functions/_gukhanmun_opendict-cdb.opendictNorthKoreanCdbBytes.md)

## References

### FileDictionarySource

Re-exports [FileDictionarySource](/api/js/interfaces/_gukhanmun_napi.FileDictionarySource.md)



---
url: /api/js/modules/_gukhanmun_opendict-fst.md
---

# Module: @gukhanmun/opendict-fst

Open Korean Dictionary (우리말샘) categories prebuilt as FST binaries for use
with `{@link load}` from `@gukhanmun/wasm` or `@gukhanmun/napi`.

## Example

```ts
import { load } from "@gukhanmun/wasm";
import { opendictNorthKoreanFst } from "@gukhanmun/opendict-fst";

const g = await load({
  preset: "ko-kp",
  dictionaries: [await opendictNorthKoreanFst()],
});
console.log(g.convert("歷史와 來日"));  // "력사와 래일"
```

## Variables

- [opendictArchaicFstUrl](/api/js/variables/_gukhanmun_opendict-fst.opendictArchaicFstUrl.md)
- [opendictDialectFstUrl](/api/js/variables/_gukhanmun_opendict-fst.opendictDialectFstUrl.md)
- [opendictGeneralFstUrl](/api/js/variables/_gukhanmun_opendict-fst.opendictGeneralFstUrl.md)
- [opendictNorthKoreanFstUrl](/api/js/variables/_gukhanmun_opendict-fst.opendictNorthKoreanFstUrl.md)

## Functions

- [opendictArchaicFst](/api/js/functions/_gukhanmun_opendict-fst.opendictArchaicFst.md)
- [opendictArchaicFstBytes](/api/js/functions/_gukhanmun_opendict-fst.opendictArchaicFstBytes.md)
- [opendictDialectFst](/api/js/functions/_gukhanmun_opendict-fst.opendictDialectFst.md)
- [opendictDialectFstBytes](/api/js/functions/_gukhanmun_opendict-fst.opendictDialectFstBytes.md)
- [opendictFstBytes](/api/js/functions/_gukhanmun_opendict-fst.opendictFstBytes.md)
- [opendictGeneralFst](/api/js/functions/_gukhanmun_opendict-fst.opendictGeneralFst.md)
- [opendictGeneralFstBytes](/api/js/functions/_gukhanmun_opendict-fst.opendictGeneralFstBytes.md)
- [opendictNorthKoreanFst](/api/js/functions/_gukhanmun_opendict-fst.opendictNorthKoreanFst.md)
- [opendictNorthKoreanFstBytes](/api/js/functions/_gukhanmun_opendict-fst.opendictNorthKoreanFstBytes.md)

## References

### FileDictionarySource

Re-exports [FileDictionarySource](/api/js/interfaces/_gukhanmun_napi.FileDictionarySource.md)



---
url: /api/js/modules/_gukhanmun_stdict-cdb.md
---

# Module: @gukhanmun/stdict-cdb

Standard Korean Language Dictionary (標準國語大辭典) prebuilt as a CDB
binary for use with `{@link load}` from `@gukhanmun/wasm` or
`@gukhanmun/napi`.

## Example

```ts
import { load } from "@gukhanmun/wasm";
import { stdictCdb } from "@gukhanmun/stdict-cdb";

const g = await load({ dictionaries: [await stdictCdb()] });
console.log(g.convert("漢字를 한글로"));  // "한자를 한글로"
```

## Variables

- [stdictCdbUrl](/api/js/variables/_gukhanmun_stdict-cdb.stdictCdbUrl.md)

## Functions

- [stdictCdb](/api/js/functions/_gukhanmun_stdict-cdb.stdictCdb.md)
- [stdictCdbBytes](/api/js/functions/_gukhanmun_stdict-cdb.stdictCdbBytes.md)

## References

### FileDictionarySource

Re-exports [FileDictionarySource](/api/js/interfaces/_gukhanmun_napi.FileDictionarySource.md)



---
url: /api/js/modules/_gukhanmun_stdict-fst.md
---

# Module: @gukhanmun/stdict-fst

Standard Korean Language Dictionary (標準國語大辭典) prebuilt as an FST
binary for use with `{@link load}` from `@gukhanmun/wasm` or
`@gukhanmun/napi`.

## Example

```ts
import { load } from "@gukhanmun/wasm";
import { stdictFst } from "@gukhanmun/stdict-fst";

const g = await load({ dictionaries: [await stdictFst()] });
console.log(g.convert("漢字를 한글로"));  // "한자를 한글로"
```

## Variables

- [stdictFstUrl](/api/js/variables/_gukhanmun_stdict-fst.stdictFstUrl.md)

## Functions

- [stdictFst](/api/js/functions/_gukhanmun_stdict-fst.stdictFst.md)
- [stdictFstBytes](/api/js/functions/_gukhanmun_stdict-fst.stdictFstBytes.md)

## References

### FileDictionarySource

Re-exports [FileDictionarySource](/api/js/interfaces/_gukhanmun_napi.FileDictionarySource.md)



---
url: /api/js/modules/_gukhanmun_types.md
---

# Module: @gukhanmun/types

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.

## Classes

- [GukhanmunError](/api/js/classes/_gukhanmun_types.GukhanmunError.md)

## Interfaces

- [DictionaryEntry](/api/js/interfaces/_gukhanmun_types.DictionaryEntry.md)
- [Directives](/api/js/interfaces/_gukhanmun_types.Directives.md)
- [FileDictionarySource](/api/js/interfaces/_gukhanmun_types.FileDictionarySource.md)
- [Gukhanmun](/api/js/interfaces/_gukhanmun_types.Gukhanmun.md)
- [GukhanmunFactory](/api/js/interfaces/_gukhanmun_types.GukhanmunFactory.md)
- [GukhanmunOptions](/api/js/interfaces/_gukhanmun_types.GukhanmunOptions.md)
- [HtmlOptions](/api/js/interfaces/_gukhanmun_types.HtmlOptions.md)

## Type Aliases

- [ContextWindow](/api/js/types/_gukhanmun_types.ContextWindow.md)
- [DictionarySource](/api/js/types/_gukhanmun_types.DictionarySource.md)
- [ErrorCode](/api/js/types/_gukhanmun_types.ErrorCode.md)
- [Format](/api/js/types/_gukhanmun_types.Format.md)
- [HomophoneDetection](/api/js/types/_gukhanmun_types.HomophoneDetection.md)
- [NumeralStrategy](/api/js/types/_gukhanmun_types.NumeralStrategy.md)
- [OriginalGloss](/api/js/types/_gukhanmun_types.OriginalGloss.md)
- [Preset](/api/js/types/_gukhanmun_types.Preset.md)
- [Recovery](/api/js/types/_gukhanmun_types.Recovery.md)
- [RenderMode](/api/js/types/_gukhanmun_types.RenderMode.md)
- [Segmentation](/api/js/types/_gukhanmun_types.Segmentation.md)

## Variables

- [load](/api/js/variables/_gukhanmun_types.load.md)



---
url: /api/js/modules/_gukhanmun_wasm.md
---

# Module: @gukhanmun/wasm

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}`.

## Example

```ts
import { load } from "@gukhanmun/wasm";
import { stdictFst } from "@gukhanmun/stdict-fst";

const g = await load({ dictionaries: [await stdictFst()] });
console.log(g.convert("漢字를 한글로"));  // "한자를 한글로"
```

## Classes

- [GukhanmunError](/api/js/classes/_gukhanmun_wasm.GukhanmunError.md)

## Functions

- [load](/api/js/functions/_gukhanmun_wasm.load.md)

## References

### ContextWindow

Re-exports [ContextWindow](/api/js/types/_gukhanmun_napi.ContextWindow.md)

***

### DictionaryEntry

Re-exports [DictionaryEntry](/api/js/interfaces/_gukhanmun_napi.DictionaryEntry.md)

***

### DictionarySource

Re-exports [DictionarySource](/api/js/types/_gukhanmun_napi.DictionarySource.md)

***

### Directives

Re-exports [Directives](/api/js/interfaces/_gukhanmun_napi.Directives.md)

***

### ErrorCode

Re-exports [ErrorCode](/api/js/types/_gukhanmun_napi.ErrorCode.md)

***

### FileDictionarySource

Re-exports [FileDictionarySource](/api/js/interfaces/_gukhanmun_napi.FileDictionarySource.md)

***

### Format

Re-exports [Format](/api/js/types/_gukhanmun_napi.Format.md)

***

### Gukhanmun

Re-exports [Gukhanmun](/api/js/interfaces/_gukhanmun_napi.Gukhanmun.md)

***

### GukhanmunFactory

Re-exports [GukhanmunFactory](/api/js/interfaces/_gukhanmun_napi.GukhanmunFactory.md)

***

### GukhanmunOptions

Re-exports [GukhanmunOptions](/api/js/interfaces/_gukhanmun_napi.GukhanmunOptions.md)

***

### HomophoneDetection

Re-exports [HomophoneDetection](/api/js/types/_gukhanmun_napi.HomophoneDetection.md)

***

### HtmlOptions

Re-exports [HtmlOptions](/api/js/interfaces/_gukhanmun_napi.HtmlOptions.md)

***

### NumeralStrategy

Re-exports [NumeralStrategy](/api/js/types/_gukhanmun_napi.NumeralStrategy.md)

***

### OriginalGloss

Re-exports [OriginalGloss](/api/js/types/_gukhanmun_napi.OriginalGloss.md)

***

### Preset

Re-exports [Preset](/api/js/types/_gukhanmun_napi.Preset.md)

***

### Recovery

Re-exports [Recovery](/api/js/types/_gukhanmun_napi.Recovery.md)

***

### RenderMode

Re-exports [RenderMode](/api/js/types/_gukhanmun_napi.RenderMode.md)

***

### Segmentation

Re-exports [Segmentation](/api/js/types/_gukhanmun_napi.Segmentation.md)



---
url: /api/js/types/_gukhanmun_napi.ContextWindow.md
---

# Type Alias: ContextWindow

> **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.



---
url: /api/js/types/_gukhanmun_napi.DictionarySource.md
---

# Type Alias: DictionarySource

> **DictionarySource** = [`FileDictionarySource`](/api/js/interfaces/_gukhanmun_napi.FileDictionarySource.md)

A dictionary source accepted by [GukhanmunOptions.dictionaries](/api/js/interfaces/_gukhanmun_napi.GukhanmunOptions.md#dictionaries).

Currently only [FileDictionarySource](/api/js/interfaces/_gukhanmun_napi.FileDictionarySource.md) (binary file / URL / path) is
supported.  Sources are tried in array order; the first match wins.

## Example

```ts
import { stdictFst } from "@gukhanmun/stdict-fst";
const g = await load({ dictionaries: [await stdictFst()] });
```



---
url: /api/js/types/_gukhanmun_napi.ErrorCode.md
---

# Type Alias: ErrorCode

> **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](/api/js/classes/_gukhanmun_napi.GukhanmunError.md).

- `"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.



---
url: /api/js/types/_gukhanmun_napi.Format.md
---

# Type Alias: Format

> **Format** = `"text"` | `"html"` | `"markdown"` | \{ `format`: `"markdown"`; `gfm?`: `boolean`; }

Input / output format for [Gukhanmun.convert](/api/js/interfaces/_gukhanmun_napi.Gukhanmun.md#convert) and
[Gukhanmun.stream](/api/js/interfaces/_gukhanmun_napi.Gukhanmun.md#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"`.



---
url: /api/js/types/_gukhanmun_napi.HomophoneDetection.md
---

# Type Alias: HomophoneDetection

> **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](/api/js/types/_gukhanmun_napi.ContextWindow.md).  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`.



---
url: /api/js/types/_gukhanmun_napi.NumeralStrategy.md
---

# Type Alias: NumeralStrategy

> **NumeralStrategy** = `"hangul-phonetic"` | `"positional-arabic"` | `"additive-arabic"` | `"smart"`

Controls how runs of hanja numerals are converted.  Corresponds to Rust
`NumeralStrategy`.

| Strategy              | `二〇一六年` | `十一月` | `一千二百三十四` |
| --------------------- | ------- | ----- | --------- |
| `"hangul-phonetic"`   | 이공일륙년   | 십일월   | 일천이백삼십사   |
| `"positional-arabic"` | 2016년   | (n/a) | (n/a)     |
| `"additive-arabic"`   | (n/a)   | 11월   | 1234      |
| `"smart"`             | 2016년   | 11월   | 1234      |

- `"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`.



---
url: /api/js/types/_gukhanmun_napi.OriginalGloss.md
---

# Type Alias: OriginalGloss

> **OriginalGloss** = `"parens"` | `"ruby"`

Selects how glosses are rendered when [RenderMode](/api/js/types/_gukhanmun_napi.RenderMode.md) 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"`.



---
url: /api/js/types/_gukhanmun_napi.Preset.md
---

# Type Alias: Preset

> **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](/api/js/interfaces/_gukhanmun_napi.GukhanmunOptions.md) override
the preset.



---
url: /api/js/types/_gukhanmun_napi.Recovery.md
---

# Type Alias: Recovery

> **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.



---
url: /api/js/types/_gukhanmun_napi.RenderMode.md
---

# Type Alias: RenderMode

> **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](/api/js/interfaces/_gukhanmun_napi.GukhanmunOptions.md#originalgloss).  Corresponds to Rust
  `RenderMode::Original`.



---
url: /api/js/types/_gukhanmun_napi.Segmentation.md
---

# Type Alias: Segmentation

> **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`.



---
url: /api/js/types/_gukhanmun_types.ContextWindow.md
---

# Type Alias: ContextWindow

> **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.



---
url: /api/js/types/_gukhanmun_types.DictionarySource.md
---

# Type Alias: DictionarySource

> **DictionarySource** = [`FileDictionarySource`](/api/js/interfaces/_gukhanmun_types.FileDictionarySource.md)

A dictionary source accepted by [GukhanmunOptions.dictionaries](/api/js/interfaces/_gukhanmun_types.GukhanmunOptions.md#dictionaries).

Currently only [FileDictionarySource](/api/js/interfaces/_gukhanmun_types.FileDictionarySource.md) (binary file / URL / path) is
supported.  Sources are tried in array order; the first match wins.

## Example

```ts
import { stdictFst } from "@gukhanmun/stdict-fst";
const g = await load({ dictionaries: [await stdictFst()] });
```



---
url: /api/js/types/_gukhanmun_types.ErrorCode.md
---

# Type Alias: ErrorCode

> **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](/api/js/classes/_gukhanmun_types.GukhanmunError.md).

- `"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.



---
url: /api/js/types/_gukhanmun_types.Format.md
---

# Type Alias: Format

> **Format** = `"text"` | `"html"` | `"markdown"` | \{ `format`: `"markdown"`; `gfm?`: `boolean`; }

Input / output format for [Gukhanmun.convert](/api/js/interfaces/_gukhanmun_types.Gukhanmun.md#convert) and
[Gukhanmun.stream](/api/js/interfaces/_gukhanmun_types.Gukhanmun.md#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"`.



---
url: /api/js/types/_gukhanmun_types.HomophoneDetection.md
---

# Type Alias: HomophoneDetection

> **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](/api/js/types/_gukhanmun_types.ContextWindow.md).  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`.



---
url: /api/js/types/_gukhanmun_types.NumeralStrategy.md
---

# Type Alias: NumeralStrategy

> **NumeralStrategy** = `"hangul-phonetic"` | `"positional-arabic"` | `"additive-arabic"` | `"smart"`

Controls how runs of hanja numerals are converted.  Corresponds to Rust
`NumeralStrategy`.

| Strategy              | `二〇一六年` | `十一月` | `一千二百三十四` |
| --------------------- | ------- | ----- | --------- |
| `"hangul-phonetic"`   | 이공일륙년   | 십일월   | 일천이백삼십사   |
| `"positional-arabic"` | 2016년   | (n/a) | (n/a)     |
| `"additive-arabic"`   | (n/a)   | 11월   | 1234      |
| `"smart"`             | 2016년   | 11월   | 1234      |

- `"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`.



---
url: /api/js/types/_gukhanmun_types.OriginalGloss.md
---

# Type Alias: OriginalGloss

> **OriginalGloss** = `"parens"` | `"ruby"`

Selects how glosses are rendered when [RenderMode](/api/js/types/_gukhanmun_types.RenderMode.md) 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"`.



---
url: /api/js/types/_gukhanmun_types.Preset.md
---

# Type Alias: Preset

> **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](/api/js/interfaces/_gukhanmun_types.GukhanmunOptions.md) override
the preset.



---
url: /api/js/types/_gukhanmun_types.Recovery.md
---

# Type Alias: Recovery

> **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.



---
url: /api/js/types/_gukhanmun_types.RenderMode.md
---

# Type Alias: RenderMode

> **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](/api/js/interfaces/_gukhanmun_types.GukhanmunOptions.md#originalgloss).  Corresponds to Rust
  `RenderMode::Original`.



---
url: /api/js/types/_gukhanmun_types.Segmentation.md
---

# Type Alias: Segmentation

> **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`.



---
url: /api/js/variables/_gukhanmun_opendict-cdb.opendictArchaicCdbUrl.md
---

# Variable: opendictArchaicCdbUrl

> `const` **opendictArchaicCdbUrl**: `URL`

URL of the bundled Open Korean Dictionary 옛말 CDB binary.

Stored gzip-compressed; [opendictCdbBytes](/api/js/functions/_gukhanmun_opendict-cdb.opendictCdbBytes.md) inflates it transparently.



---
url: /api/js/variables/_gukhanmun_opendict-cdb.opendictDialectCdbUrl.md
---

# Variable: opendictDialectCdbUrl

> `const` **opendictDialectCdbUrl**: `URL`

URL of the bundled Open Korean Dictionary 方言 CDB binary.

Stored gzip-compressed; [opendictCdbBytes](/api/js/functions/_gukhanmun_opendict-cdb.opendictCdbBytes.md) inflates it transparently.



---
url: /api/js/variables/_gukhanmun_opendict-cdb.opendictGeneralCdbUrl.md
---

# Variable: opendictGeneralCdbUrl

> `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](/api/js/functions/_gukhanmun_opendict-cdb.opendictCdbBytes.md) inflates it transparently.



---
url: /api/js/variables/_gukhanmun_opendict-cdb.opendictNorthKoreanCdbUrl.md
---

# Variable: opendictNorthKoreanCdbUrl

> `const` **opendictNorthKoreanCdbUrl**: `URL`

URL of the bundled Open Korean Dictionary 北韓語 CDB binary.

Stored gzip-compressed; [opendictCdbBytes](/api/js/functions/_gukhanmun_opendict-cdb.opendictCdbBytes.md) inflates it transparently.



---
url: /api/js/variables/_gukhanmun_opendict-fst.opendictArchaicFstUrl.md
---

# Variable: opendictArchaicFstUrl

> `const` **opendictArchaicFstUrl**: `URL`

URL of the bundled Open Korean Dictionary 옛말 FST binary.



---
url: /api/js/variables/_gukhanmun_opendict-fst.opendictDialectFstUrl.md
---

# Variable: opendictDialectFstUrl

> `const` **opendictDialectFstUrl**: `URL`

URL of the bundled Open Korean Dictionary 방언 FST binary.



---
url: /api/js/variables/_gukhanmun_opendict-fst.opendictGeneralFstUrl.md
---

# Variable: opendictGeneralFstUrl

> `const` **opendictGeneralFstUrl**: `URL`

URL of the bundled Open Korean Dictionary 일반어 FST binary.



---
url: /api/js/variables/_gukhanmun_opendict-fst.opendictNorthKoreanFstUrl.md
---

# Variable: opendictNorthKoreanFstUrl

> `const` **opendictNorthKoreanFstUrl**: `URL`

URL of the bundled Open Korean Dictionary 북한어 FST binary.



---
url: /api/js/variables/_gukhanmun_stdict-cdb.stdictCdbUrl.md
---

# Variable: stdictCdbUrl

> `const` **stdictCdbUrl**: `URL`

URL of the bundled Standard Korean Language Dictionary CDB binary.



---
url: /api/js/variables/_gukhanmun_stdict-fst.stdictFstUrl.md
---

# Variable: stdictFstUrl

> `const` **stdictFstUrl**: `URL`

URL of the bundled Standard Korean Language Dictionary FST binary.



---
url: /api/js/variables/_gukhanmun_types.load.md
---

# Variable: load

> `const` **load**: [`GukhanmunFactory`](/api/js/interfaces/_gukhanmun_types.GukhanmunFactory.md)\[`"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.



---
url: /internals/design.md
---

# 

# Gukhanmun design docs

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.

[Seonbi]: https://github.com/dahlia/seonbi

## Goals and non-goals

The library converts hanja words in Korean text into their hangul readings,
optionally annotating them with the source hanja for disambiguation, ruby
markup, or stylistic reasons. It does so without disturbing structure or
content outside the text it is asked to transform; regions marked as non-Korean
or as preserved (code blocks and the like) pass through untouched. It streams
input and output where possible, with buffering bounded by the size of
contiguous conversion spans that contain hanja and by opt-in cross-context
disambiguation. It accepts pluggable dictionaries that may be in-memory,
mmap-backed, or otherwise opaque to the engine. It ships a default dictionary
derived from the South Korean _Standard Korean Language Dictionary_
(標準國語大辭典). It is usable from Rust, from Node.js via [Node-API], from
browsers and Deno via WebAssembly, and from a command line.

The library deliberately does not provide broader Korean typographic
adjustments such as smart quotes, dashes, ellipses, or citation marks; those
remain Seonbi's job. It does not provide a fully HTML5-conformant parser; the
HTML scanner is fragment-oriented and recovers from minor malformations but is
not a substitute for html5ever. It does not roundtrip Markdown byte-for-byte;
semantic preservation is the contract, and original-form preservation is best
effort. It does not translate between languages or transliterate beyond the
hanja-to-hangul mapping.

[Node-API]: https://nodejs.org/api/n-api.html

## Design principles

Three principles run through the design.

The engine is _format-neutral_. The same engine processes HTML, Markdown, and
plain text because each format is read into a single intermediate
representation and written back from it. Adapters at the boundary handle format
specifics: scanning, serialization, and the format-specific notion of what
counts as a preserved region or a block boundary. The engine never inspects
HTML tag names, Markdown event variants, or anything else that would couple it
to one format. This is what makes a single test fixture meaningful across all
three formats, and what makes adding a new format a contained piece of work.

_Responsibilities are split into independently selectable pipeline stages_. The
_Reader_ parses an input format into the IR. The _Engine_ finds
hanja-containing lexical spans, segments them, and emits annotations.
_Middlewares_ transform the IR stream by adjusting
annotation flags. The _Renderer_ turns annotations into concrete text or
markup. The _Writer_ serializes the IR back to the target format. A user
replacing one stage does not perturb the others; the boundaries are explicit
values, not method calls.

_Streaming is the default where correctness allows it_. Operations that
fundamentally require lookahead buffer until the relevant context boundary. In
HTML and Markdown, the default per-block homophone window usually reaches that
boundary at paragraphs, list items, headings, and similar scopes. Plain text has
no block scopes, so the same default window is document-wide: an annotation on a
later line can force disambiguating hanja on an earlier line, and a byte stream
cannot revise text already written to stdout. Callers that require immediate
plain-text output can disable homophone marking, accepting the corresponding
loss of disambiguation.

Streaming conversion also preserves fallback annotation spans exactly. A
trailing run of fallback hanja is held until a following non-convertible
boundary or EOF, even when the dictionary's maximum word length is shorter.
This can make fallback-only hanja input less eager than dictionary lookahead
alone would require, but it keeps render modes such as `hangul-hanja-parens`
equivalent to one-shot conversion.

## Architecture

The pipeline has five stages.

```mermaid
flowchart LR
    Bytes -->|Reader| InTok[InputToken stream]
    InTok -->|Engine| OutTok[OutputToken stream]
    OutTok -->|Middlewares| OutTok2[OutputToken stream]
    OutTok2 -->|Renderer| OutTok3[OutputToken stream]
    OutTok3 -->|Writer| Bytes2[Bytes]
```

A reader parses bytes into a stream of input tokens. The engine reads input
tokens and emits output tokens, with the difference that output tokens may
include _annotation_ tokens carrying both an original hanja form and its hangul
reading. Middlewares walk the output stream and adjust the flags on those
annotations. The renderer expands each annotation into concrete text or markup
according to the flags and the chosen rendering mode. The writer serializes the
final stream into the output format.

### Intermediate representation

The intermediate representation is a flat stream of tokens parameterized by a
_scope data_ type that belongs to the adapter rather than the engine. The
engine knows the shape of a token, but the contents of the scope payload (raw
HTML attributes, the variant of a pulldown-cmark event, and so on) are opaque
to it.

The token sent into the engine is one of:

- `Open(Scope<S>)`: enter a structural scope, such as an HTML element or a
  Markdown block. The `Scope<S>` carries the adapter's opaque data plus three
  pre-computed flags described below.
- `Close`: leave the most recent scope. The engine maintains the stack
  itself; the adapter does not have to repeat which scope is closing.
- `Text(Cow<str>)`: a chunk of text that the engine may transform.
- `Verbatim(Cow<str>)`: a chunk of text that must pass through untouched,
  such as the contents of an HTML `<code>` element or a Markdown code span.
  The adapter, not the engine, decides what is verbatim.

The token coming out of the engine is one of:

- `Open(Scope<S>)`, `Close`, `Text(Cow<str>)`, `Verbatim(Cow<str>)`: the same
  forms, passed through.
- `Annotated(Annotation)`: a position in the stream where the engine
  converted a hanja word. The annotation carries the original hanja, the
  hangul reading, and flags describing why the conversion happened and what
  subsequent stages might want to do with it.

The `Annotation` carries policy flags. `homophone` is set when the effective
dictionary entry set or the active context indicates another hanja word shares
this hangul reading, so a reader of the rendered output cannot recover the word
from hangul alone. `require_hanja` is set when the source dictionary or a user
directive demands the original hanja be shown alongside the hangul.
`require_hangul` is set in the opposite direction: the source preserves the
hanja in the output, but a hangul gloss is required (used for the _Original_
rendering mode that keeps mixed script as the default presentation).
`skip_annotation` is set by user directives that want the renderer to emit only
the primary plain text form. `first_in_context` is set when this is the first
occurrence of the hanja word within the current context window, where the
window is a block, a section, or the document depending on configuration.
`from_dictionary` distinguishes a dictionary match from a
character-by-character fallback; renderers may choose to mark these differently
for debugging.

The split between `InputToken` and `OutputToken` is the most consequential
shape decision in the IR. The alternative we considered was a single `Token`
enum that includes `Annotated` from the start, with adapters emitting
`Annotated` only as a future possibility. We rejected it for two reasons.
First, it would force the input-side `Annotated` variant to remain a no-op
throughout the reader and engine, polluting every `match` in the codebase with
an unreachable arm. Second, it would obscure the contract that the engine
_produces_ annotations and renderers _consume_ them. Two distinct types make
the dataflow legible at a glance and let the type system enforce that an
unrendered annotation cannot reach a writer.

### Scope data

The opaque scope payload obeys a small trait:

```rust
pub trait ScopeData: Clone + 'static {
    /// Should text inside this scope be left alone?
    fn is_preserve(&self) -> bool;

    /// May the renderer insert inline markup, such as a `<ruby>` element,
    /// inside this scope?
    fn allows_inline_markup(&self) -> bool { true }

    /// Does this scope mark a boundary at which per-block middlewares reset?
    fn is_block_boundary(&self) -> bool { false }
}
```

The engine treats the current scope's `is_preserve()` as the single point of
truth for whether to skip a `Text` token. Adapters that need inheritance encode
the effective answer in each opened scope. The HTML adapter's `ScopeData`
implementation aggregates several concerns into that one flag: the inherited
`lang` attribute compared against a Korean predicate, the current tag and
preserved ancestors (against the preserved-tag list of `pre`, `code`, `kbd`,
`script`, `style`, and `textarea`), and any user-supplied predicate over raw
attributes. The engine itself does not know what a `lang` attribute is.

This is a departure from Seonbi, which threads a parallel `LangHtmlEntity`
annotation through the pipeline. We removed it because the engine never needs
both signals separately; it only ever asks the single question, is this text
skipped? Pushing lang inheritance into the adapter (where the tag-name
preservation list already lives) keeps the engine ignorant of HTML and keeps
the IR free of fields the engine does not consume.

## Engine

The engine has three duties: identify convertible lexical spans that contain
hanja, segment those spans into dictionary and fallback edges, and emit
annotations and fallback text accordingly. Most spans are contiguous runs of
hanja, but dictionary entries may also include Korean native or hangul
fragments around hanja, as in `汽車길` or `色깔論`. It also has a fallback
phoneticizer that maps single hanja characters to hangul and applies the
initial sound law where appropriate, and a numeral converter that translates
hanja digits to either hangul or Arabic numerals depending on configuration.

### Lattice segmentation

Segmenting a hanja-containing span into dictionary words and fallback fragments
is the engine's core decision, and the obvious algorithm is wrong.

The obvious algorithm is _eager longest-match_: scan left to right, at each
position take the longest dictionary entry that starts there, and continue from
its end. This is what Seonbi does. Its failure mode is mis-segmentation when a
longer prefix consumes characters that belong to a more natural split. Consider
a dictionary containing `行事`, `行事場`, `場所`, and `入口`. On the input
`行事場入口`, eager segmentation produces `行事場` + `入口`, which is correct.
On the input `行事場所`, eager segmentation produces `行事場` + `所`, which
leaves `所` to the character-by-character fallback even though the segmentation
`行事` + `場所` would have covered both segments with the dictionary.

The span is not limited to hanja-only text. Some entries in the _Standard Korean
Language Dictionary_ mix native Korean and hanja, such as `汽車길` for
`기찻길`, `祭祀날` for `제삿날`, `洗手대야` for `세숫대야`, `火김` for
`홧김`, and `色깔論` for `색깔론`. A dictionary edge may therefore consume a
mixed-script prefix from the current text cursor. Fallback edges, however, are
still created only for hanja characters that no dictionary edge covers; hangul
that is not part of a dictionary match passes through as ordinary text.

The correct algorithm is dynamic programming over a lattice. For each character
position `i` in the conversion span, the engine queries the dictionary for
every match that starts at `i` and considers a single-hanja fallback edge as a
backup when the current character is hanja. Arabic numeral strategies also add
a plain-text numeral edge when a numeral starts at `i`. A ranking function
compares the alternatives; we choose the best segmentation by Viterbi-style
backtracking from the end of the span.

The ranking function is deliberately simple. It first minimizes the number of
characters left to fallback, so `行事` + `場所` beats `行事場` + `所` because
the former leaves no fallback. Among paths with the same fallback coverage,
Arabic numeral edges are preferred over dictionary matches when the configured
numeral strategy produces them; this is what lets a dictionary calendar entry
such as `六月` normalize to `6월`. After that, the segmenter maximizes
dictionary coverage and then prefers fewer segments, so a whole-word match such
as `天地` beats the component split `天` + `地`. Remaining ties are kept
deterministic by preserving the first candidate that reached the same score.

The cost of lattice segmentation is bounded by the conversion-span length
times the maximum dictionary entry length. In normal Korean text, spans that
contain hanja are short: most are one to four characters, almost never more
than ten, except for rare mixed-script dictionary entries. The dictionary's
maximum entry length is on the order of ten characters. The per-span runtime is
therefore tens of dictionary lookups, which the FST and CDB backends handle in
microseconds.

An _eager_ segmentation strategy remains available as an option for callers who
do not need lattice accuracy and want to reduce per-span overhead. The default
is lattice.

### Fallback phoneticizer

When no dictionary entry covers a hanja character, the fallback phoneticizer
converts the character to hangul by looking up its canonical reading in the
embedded Unihan-derived character map. The character map is built from the
Unicode `kHangul` property and embedded in _gukhanmun-core_ as a generated
sorted table queried by binary search. It covers thousands of hanja and keeps
the default build independent of network access.

For the first character of a word produced by the fallback, that is, the first
character of a fallback-only run or the first character after a dictionary
match, the initial sound law (頭音法則) optionally applies. The law converts a
small set of word-initial hangul syllables that originally began with ㄴ or ㄹ
into their South Korean orthography forms (녀 becomes 여, 려 becomes 여, 례
becomes 예, and so on). The conversion table is small (sixteen entries) and
lives in _gukhanmun-core_. The toggle for the law applies only to the fallback;
dictionary entries are assumed to encode the correct reading already (a South
Korean dictionary stores `來日` as 내일, a North Korean dictionary stores it as
래일).

Two small rules from Seonbi survive in the fallback because they are not
learnable from per-character mappings alone. First, the _ryeol_-_ryul_ rule
(`列`, `律`) is treated as part of the initial sound law: when the law is
enabled and these characters follow a syllable whose final jamo is ㄴ or
absent, their pronunciation glides to 열 or 율 rather than 렬 or 률. When the
law is disabled, as in North Korean orthography, they remain 렬 or 률. Second,
the hanja-numeral rule: a sequence of two or more hanja digits is read as a
single word with the initial sound law applied at its head and not at internal
positions. Both rules are encoded as small parsers over the character stream.

### Numeral conversion

Hanja numerals are a special case because they can be converted to three
different surface forms and the right one depends on context. The library
exposes a `NumeralStrategy` option with four variants:

| Strategy            | Example: `二〇一六年` | Example: `十一月`   | Example: `一千二百三十四` |
| ------------------- | ---------------- | ---------------- | ------------------ |
| `hangul-phonetic`   | 이공일륙년            | 십일월              | 일천이백삼십사            |
| `positional-arabic` | 2016년            | (not applicable) | (not applicable)   |
| `additive-arabic`   | (not applicable) | 11월              | 1234               |
| `smart`             | 2016년            | 11월              | 1234               |

The `hangul-phonetic` strategy is Seonbi's behavior and the default for both
the `ko-kr` and `ko-kp` presets. The command-line interface uses `smart` as
its own default when `--numerals` is omitted, because CLI output is usually a
final human-facing rendering. The `positional-arabic` strategy treats a
digit-only sequence (`〇一二三四五六七八九`, plus their variants) as positional
notation and converts it to Arabic. The `additive-arabic` strategy parses
sequences that contain place markers (`十百千萬億兆京`) using stack-based
accumulation and produces Arabic, handling the Korean convention that `一` is
elidable before `十` (`十一` means 11, not `一十一`). The `smart` strategy
looks at the surrounding context: additive numerals that begin with a digit use
`additive-arabic`, and runs that begin with a small place marker such as `十`,
`百`, or `千` use `additive-arabic` only when the next character is not an
ambiguous non-unit hanja word character. Pure digit runs use
`positional-arabic` when they have length four or more (matching the year
convention) or a unit hanja follows (`年月日時分秒號世紀` and so on). Standalone
large place markers such as `萬` or `京`, and small-place-marker words such as
`百濟` or `十長生`, fall back to `hangul-phonetic`, which prevents unknown
words from being split as numbers.

The `hangul-phonetic` strategy runs inside the fallback path on segments that
the lattice has identified as not matching the dictionary. It emits a fallback
`Annotated` token, preserving the original hanja numeral so renderers such as
`HangulHanjaParens` can still show the source text. Arabic numeral strategies
participate in segmentation as plain-text numeral edges, so numeric
normalization can win over dictionary calendar entries such as `六月` and
`十月`. When such an override is tied to a dictionary match whose suffix is
only recognized unit hanja, the plain-text edge covers that suffix too and
renders it with fallback context; `六月` can therefore normalize to `6월` even
when `月` is not a separate dictionary entry. A numeral edge only starts at the
beginning of a numeral run, so `positional-arabic` does not split additive
forms such as `十一月` by converting only the trailing `一`. A longer dictionary
match that extends beyond the numeral plus recognized unit hanja still protects
the word, so `smart` does not split ordinary dictionary entries such as `北京`
or `一分錢`.

## Dictionaries

A dictionary is anything that can be asked what matches start at a given text
position.

```rust
pub trait HanjaDictionary {
    /// Yield every match that starts at the beginning of `s`.
    fn matches_at<'a>(&'a self, s: &'a str)
        -> Box<dyn Iterator<Item = Match<'a>> + 'a>;

    /// Greatest entry length, in characters, that this dictionary contains.
    /// Used as the lattice termination bound.
    fn max_word_chars(&self) -> Option<usize> { None }

    /// Complete entries, when the backend can enumerate them efficiently
    /// enough to build a batch policy index.
    fn entries<'a>(&'a self)
        -> Option<Box<dyn Iterator<Item = DictionaryRecord> + 'a>>
    { None }

    /// Is there another hanja word with the same hangul reading?
    /// Convenience API; the homophone-marker middleware uses entries() to
    /// avoid repeated full-dictionary scans.
    fn has_homophone(&self, hanja: &str, reading: &str) -> bool { false }
}
```

`matches_at` is the unusual part. The natural signature for a Korean text
application would be `longest_match`, but eager longest-match is exactly the
algorithm we reject in the engine. The trait surfaces _every_ match starting at
a position because the lattice segmenter needs the full set in order to score
alternatives. The input string is the text suffix at the current cursor, not
only a pre-cut hanja run; this lets dictionaries contain mixed-script keys such
as `汽車길` as long as the match itself contains at least one hanja character.

A `Match` carries the matched byte length, the hangul reading, and a
`MatchMark`. `byte_len` is the UTF-8 length of the matched dictionary key,
which may include both hanja and hangul:

```rust
pub struct Match<'a> {
    pub byte_len: usize,
    pub reading: Cow<'a, str>,
    pub mark: MatchMark,
}

pub struct MatchMark {
    /// The dictionary asserts this entry should always be shown with hanja.
    pub require_hanja: bool,
    /// The dictionary asserts this entry should always be shown with hangul.
    pub require_hangul: bool,
}
```

The marks come from the source dictionary's build-time metadata. The bundled
_Standard Korean Language Dictionary_'s CDB and FST files are accompanied by a
rules file that enumerates hard-to-read characters and ambiguous readings that
should be hanja-annotated.

### Built-in implementations

`UnihanCharDict` exposes the per-character Unihan reading table as a
`HanjaDictionary` so callers can compose those readings through the same public
dictionary interface as other sources. It returns canonical pre-initial-sound-
law readings from a generated sorted table built from the Unicode `kHangul`
property; stateful fallback rules such as initial sound law and numeral
grouping remain engine behavior.

`MapDictionary` is the small in-memory dictionary used for tests,
programmatically supplied entries, and custom vocabularies that are already in
process memory. It is backed by an ordered map so it stays dependency-light and
usable in the `no_std` core crate. Callers that need compact serialized data,
mmap-friendly loading, or large static dictionaries should use the
`gukhanmun-fst` backend instead.

`ChainDictionary` composes a sequence of dictionaries with a precedence policy.
A caller can chain a small user dictionary (highest priority), a
domain-specific dictionary, the _Standard Korean Language Dictionary_, and, when
canonical single-character dictionary matches are desired, `UnihanCharDict`
(lowest priority).

### External backends

Two external dictionary backends ship as separate crates.

_gukhanmun-cdb_ wraps a CDB file as a `HanjaDictionary`. CDB is djb's constant
database: a static on-disk hash table with $O(1)$ lookups and trivial format
documentation. The naive use of CDB as a hanja-to-hangul map fails because CDB
is a hash table without prefix iteration; there is no way to ask whether some
key starts with a given byte sequence. We work around this by encoding the
dictionary as a _trie embedded in the CDB key space_. At build time,
_gukhanmun-mkdict_ enumerates every prefix of every entry and stores a record
for each, with a one-byte flag distinguishing complete words from intermediate
prefixes:

```text
key   = utf-8 bytes of a prefix
value = { is_complete: u8, mark: u8, reading_len: u16, reading: utf-8 }
```

Lookup walks one character at a time from the cursor position. On a miss, no
longer match is possible from this position and the walk terminates. On a hit
with `is_complete = 1`, the match is yielded; on a hit with `is_complete = 0`,
the walk continues to look for longer matches. The cost is
$O(\text\{max\_word\_chars})$ CDB lookups per position, and each CDB lookup
is $O(1)$. The size cost is real: every prefix of every entry occupies a
record, so the bundled stdict CDB is roughly twice the size of the source TSV.
The trade-off is that CDB's simplicity (six syscalls of file format,
public-domain reference implementations) makes the backend trivially auditable.

_gukhanmun-fst_ wraps an `fst::Map` as a `HanjaDictionary`. The FST (finite
state transducer) supports prefix iteration natively and compresses better than
CDB-as-trie, but its on-disk format is less universally implemented. We provide
both because users have different priorities; CDB is the choice for
code-auditability and trivial mmap support, while FST is the choice for small
WebAssembly bundles.

### Dictionary tooling

_gukhanmun-mkdict_ is a separate CLI for building CDB and FST dictionary files.
It accepts TSV, CSV, and JSON Lines input, supports merging multiple input
files with a configurable conflict policy, validates the result with a
round-trip pass, and embeds build metadata (source, license, build date) in the
dictionary header.

```text
gukhanmun-mkdict [OPTIONS] -o OUTPUT <INPUT>...

INPUT FORMATS:
    tsv     hanja TAB hangul [TAB flags]
    csv     hanja,hangul[,require_hanja,require_hangul]
    jsonl   {"hanja":..., "hangul":..., "requireHanja":..., ...}

OPTIONS:
    -o, --output PATH               output path
    -f, --format FMT                cdb|fst            (default: fst)
        --merge STRATEGY            first-wins|last-wins|error
        --metadata KEY=VAL          embedded metadata
        --validate                  round-trip verification
        --max-key-bytes N           reject pathologically long entries
        --rules PATH                annotation rules TSV (repeatable)
        --allow-unmatched-rules     accept rules that match no entries
```

A rules file is a TSV with columns `kind`, `pattern`, `require_hanja`,
`require_hangul`, `reason`. The `kind` selects one of three matchers:
`entry` (exact hanja key), `contains` (any entry whose hanja key contains
the hanja substring `pattern`), or `reading` (any entry whose hangul reading
equals `pattern`). `contains` patterns must be hanja-only because dictionary
keys can be mixed-script (e.g. `布告하다`); accepting a hangul substring
would silently mark unrelated entries. Multiple rules touching the same
entry are OR-merged on the mark bits. A rule must set at least one of
`require_hanja` / `require_hangul`, must carry a non-empty `reason`, and
must match at least one entry; unmatched rules fail the build by default so
that the rules file does not drift away from the dictionary it annotates.
`--allow-unmatched-rules` is a hatch for partial dictionaries that share a
rules file with a larger build.

The same binary is invoked by _gukhanmun-stdict_'s build script to produce the
bundled _Standard Korean Language Dictionary_ FST file, so end-users and the
library itself share the build path.  The CDB backend uses the same normalized
inputs and validation path for user-built dictionaries.  Bugs in the build path
get caught by the library's own integration tests before they reach users.

## Middlewares

The renderer's input is an `OutputToken` stream where each `Annotated` token
carries flags. The flags describe what the engine knows about the annotation:
was it from the dictionary, is there a homophone, is this the first time we
have seen this word. What they do not describe is what the renderer should do
about it; that is set by middlewares.

Splitting policy (which annotations should be presented with hanja, which with
hangul only, when does “first” reset) from form (parentheses, ruby, hangul
only) gives us a cleaner pipeline than Seonbi has. In Seonbi, the rendering
function decides both what to present and how. As a result, the
homophone-disambiguating renderer must internally re-implement a
homophone-detecting pass, and there is no way to swap in a different homophone
heuristic without rewriting the renderer. In Gukhanmun the middlewares are
stateful filters on the `OutputToken` stream, and the renderer is a usually
stateless translator from `Annotated` tokens to concrete text and markup.

### Built-in middlewares

`HomophoneMarker` scans the stream and sets `homophone = true` on annotations
whose hangul reading is shared by another hanja form in the effective
dictionary entry set or within the configured context window. It builds a
single reading-to-hanja index from `HanjaDictionary::entries()` when the
backend exposes entries; lookup-only dictionaries fall back to
`has_homophone()` and still get context-local marking. The window is one of
`per-block` (default), `per-document`, or `off`. Per-block windows buffer only
until the next scope whose
`is_block_boundary()` returns true, which is typically a paragraph or a list
item. Per-document windows buffer the whole stream and are appropriate only
when the input is small or when full accuracy matters more than latency.
Plain text has no block scopes, so `per-block` is document-wide there. This is
intentional: if `漢字` appears on line 1 and `翰字` appears on line 100, both
lines must render with disambiguating hanja, and a streaming writer cannot
retroactively rewrite line 1 after line 100 is seen.

`FirstOccurrenceFilter` clears `require_hanja` and `require_hangul` on
annotations after their first occurrence within a configurable context, leaving
the first occurrence as-is so the reader still encounters the gloss once. The
context is one of `per-block`, `per-section`, or `per-document`. The section
variant resets at any heading boundary, which the HTML and Markdown adapters
expose through `is_section_boundary()` on heading scopes.

`UserDirectives` applies a user-supplied set of rules. A rule is a predicate
over the hanja form plus an action: set `require_hanja`, set `require_hangul`,
or skip the annotation entirely (which collapses to plain hangul or plain hanja
text depending on the active renderer). The rule predicate may be a literal
string set, a glob, or an arbitrary closure for Rust callers; JavaScript
callers expose only the literal-set form to avoid the cost of per-token
cross-boundary calls.

### Custom middlewares

A middleware is an `impl Iterator<Item = OutputToken<S>>` taking an upstream
iterator. The trait surface is small enough to write inline. Users who want,
for example, to mark technical-term annotations from a glossary write a
middleware that holds the glossary set and updates `require_hanja` on hits.

## Renderers

The renderer expands `Annotated` tokens into concrete `Text`, `Open`, and
`Close` tokens according to its mode and the annotation's flags. Five renderers
ship with the library.

The `HangulOnly` renderer emits the hangul reading alone. If `require_hanja` or
`homophone` is set, it emits `한글(한자)`. If `require_hangul` is set, the
result is already hangul, so nothing changes.

The `HangulHanjaParens` renderer always emits `한글(한자)`. The
`require_hangul` flag is satisfied by the hangul half, and `require_hanja` by
the hanja half.

The `HanjaHangulParens` renderer always emits `한자(한글)`. This is useful for
academic and historical-document styles that lead with hanja.

The `Ruby` renderer emits a `<ruby>` element with a sub-mode that determines
which side is the base: `<ruby>한글<rp>(</rp><rt>한자</rt><rp>)</rp></ruby>`
for `on-hangul`, and `<ruby>한자<rp>(</rp><rt>한글</rt><rp>)</rp></ruby>` for
`on-hanja`. The `<rp>` elements carry parenthesized fallback text so that
browsers without `<ruby>` support render the annotation inline as
`base(gloss)` (`한글(한자)` for `on-hangul`, `한자(한글)` for `on-hanja`)
rather than running it into the base. If the current scope returns false from
`allows_inline_markup()`, the renderer falls back to parens.

The `Original` renderer emits the original hanja as plain text. Only
annotations with `require_hangul`, or those marked by a user directive, receive
a gloss; the gloss appears in either parens or ruby form depending on a
sub-option. This is the mode for “keep mixed script, gloss only the difficult
characters”, which is the style this very design document uses on its Korean
edition.

Renderers are pure functions over a single `Annotated` token plus the current
scope's `allows_inline_markup()` value. They produce a small fixed-size
sequence of output tokens (one for plain hangul or hanja, three for parens,
between five and nine for ruby). They contain no state and no buffering.

The renderer is the right place to make form decisions because the form depends
on what other tokens are in the stream at the same scope position; for example,
`<ruby>` inside `<pre>` is wrong, and the decision needs the scope stack, which
is what flows through the IR. Putting form decisions elsewhere would either
duplicate the scope tracking or require the renderer to know about other
middlewares.

## Format adapters

Three adapters ship with the library. A new adapter requires only `Reader` and
`Writer` implementations that translate between the format's tokens and the IR.

### HTML

The HTML adapter implements a hand-written scanner that produces
`InputToken<HtmlScopeData>` events. The scanner is a near-direct port of
Seonbi's `Text.Seonbi.Html.Scanner` module, which has been used on real-world
Korean web content for several years. It is fragment-oriented: the input may be
a complete document, a body, or a fragment, and the scanner emits the events it
sees rather than attempting tree construction.

We considered using html5ever or lol\_html. html5ever is the reference HTML5
parser for Rust; it produces a DOM and handles every edge case in the HTML5
specification. lol\_html is Cloudflare's streaming HTML rewriter; it is
selector-driven and integrates with WebAssembly well. We chose a hand-written
scanner because the Seonbi approach has two specific virtues that fit our
model. First, it preserves _raw attribute strings_ rather than parsing them,
which means the writer can serialize an unchanged scope exactly as it appeared
in the input. Second, it is small enough to fit comfortably in a WebAssembly
bundle, where bringing along html5ever would dominate the binary size. The cost
is that our scanner is not HTML5-conformant; we accept the trade-off.

The scanner recovers from minor errors. Unclosed tags pop the most recently
opened scope of the same name, or, if none, are emitted as text. Unrecognized
constructs that begin with `<` but are not valid tag, comment, or CDATA starts
are emitted as text characters. Entirely malformed input still produces a token
stream, just one with structural anomalies; the engine is robust to anomalies
(it does not assume scope matching) and the writer emits whatever scopes it
received.

`HtmlScopeData::is_preserve()` returns true if the current element is one of
`pre`, `code`, `kbd`, `script`, `style`, or `textarea`, or if the inherited
`lang` attribute is not Korean. The lang inheritance is computed inside the
adapter: each `Open` event evaluates its raw attributes for a `lang` value, and
the adapter maintains its own lang stack. This is the only place in the
codebase that knows what `lang` means, and the only place that knows the
preserved-tag list. The engine receives the consequences as `is_preserve()` and
does not reproduce either rule.

### Markdown

The Markdown adapter is a thin layer over `pulldown-cmark`. Each
`pulldown-cmark::Event` becomes one or more IR tokens. `Start(Tag)` and
`End(Tag)` become `Open` and `Close`. `Text` becomes `Text`. `Code` becomes
`Verbatim`. Inline HTML, which `pulldown-cmark` exposes as `Event::Html`, is
passed through a second pass of the HTML scanner so that constructs like
`<q lang="ja">` inside a paragraph receive proper lang handling.

Output is via `pulldown-cmark-to-cmark`, which serializes an event stream back
to Markdown. Semantic preservation is contractual: the output, when re-parsed,
produces the same logical structure. Byte-for-byte preservation is best effort:
setext headings may become ATX, link reference definitions may be inlined, soft
breaks may be regularized. Users who require byte-fidelity should process
rendered HTML rather than Markdown.

We chose `pulldown-cmark` rather than writing a Markdown parser because the
work of CommonMark conformance is large and well-handled by `pulldown-cmark`,
and because the event-stream API is a near-perfect match for our IR. The
alternative was `markdown-rs`, which is more recent and produces an AST rather
than an event stream; we preferred event streams for the streaming property.

### Plain text

The plain-text adapter wraps the entire input in a single scope and emits one
`Text` token. The output is the concatenation of `Text` tokens. Ruby rendering
is not meaningful in plain text and falls back to parens.  The CLI can stream
plain text before EOF only when no document-wide middleware can change already
rendered output. In practice, the `ko-kp` preset streams because homophone
marking is off, while the default `ko-kr` preset keeps the plain-text output
until EOF so cross-line homophones are rendered correctly.

## Distribution

### Rust workspace

The Rust source is organized as a Cargo workspace with the following layout:

- _Cargo.toml_: workspace manifest
- _DESIGN.md_: symbolic link to _DESIGN.en.md_
- _DESIGN.en.md_, _DESIGN.ko-Kore.md_: design documentation
- _crates/_
  - _gukhanmun-core/_: IR types, engine, dictionary trait, lattice
    segmenter, fallback phoneticizer, initial sound law tables, embedded
    `UnihanCharDict`. No I/O, no format-specific code, minimal
    dependencies. Suitable for `no_std` environments with `alloc`.
  - _gukhanmun-html/_: HTML scanner and serializer. `HtmlScopeData`
    implementation.
  - _gukhanmun-markdown/_: Markdown adapter atop `pulldown-cmark`.
  - _gukhanmun-cdb/_: CDB-trie dictionary backend.
  - _gukhanmun-fst/_: FST dictionary backend.
  - _gukhanmun-stdict/_: bundled _Standard Korean Language Dictionary_ as
    an embedded FST byte array.
  - _gukhanmun-mkdict/_: CLI for building CDB and FST dictionaries from
    TSV, CSV, or JSONL inputs.
  - _gukhanmun/_: the umbrella library crate. Re-exports from the others
    under feature flags, exposes the high-level `Builder` API, defines the
    umbrella `Error` enum.
  - _gukhanmun-cli/_: the `gukhanmun` command-line binary.
  - _gukhanmun-wasm/_: WebAssembly bindings via `wasm-bindgen`.
  - _gukhanmun-napi/_: Node-API bindings via `napi-rs`.

The umbrella crate's feature flags compose the others. Default features enable
HTML, Markdown, and the bundled stdict. CDB and FST are individually
selectable. Disabling everything yields a Rust-API-only build with just the
engine and `UnihanCharDict`, suitable for embedded targets.

### JavaScript packages

The JavaScript side is split into a type-only package and one package per
runtime implementation:

- _@gukhanmun/types_ (npm and JSR): TypeScript interfaces, type aliases,
  error class declarations, and the `GukhanmunFactory` interface. Contains no
  runtime code; npm emits declarations only, while JSR receives the _.ts_
  source directly. This is the canonical API contract; both implementations
  satisfy it structurally.
- _@gukhanmun/wasm_ (npm and JSR): WebAssembly implementation. Re-exports the
  types. Loads its _.wasm_ artifact via `import.meta.url` so that Deno and
  browsers can resolve it natively and Node 22+ can resolve it via the
  standard ESM loader.
- _@gukhanmun/napi_ (npm only): Node-API implementation. Re-exports the
  types. Ships per-platform prebuilt binaries through napi-rs's
  optional-dependency packaging.

The data dictionaries ship as separate packages so that the runtime bundle
stays small:

- _@gukhanmun/stdict-fst_ (npm and JSR): the bundled stdict as an FST file,
  exported as a `Uint8Array`.
- _@gukhanmun/stdict-cdb_ (npm and JSR): the same dictionary as a CDB file.
- _@gukhanmun/stdict-min_ (npm and JSR): a reduced FST containing only
  homophonous entries and ambiguous readings, for size-sensitive contexts.

The reason for the type-only package is that the canonical API contract should
live in exactly one place. If the contract lived in _@gukhanmun/wasm_ and
_@gukhanmun/napi_ duplicated the types or imported them from one another,
version skew between the implementations would become a maintenance burden.
With _@gukhanmun/types_ as a `peerDependency` of both implementations, users
get a single source of truth and a single set of types regardless of which
runtime they pick. We considered, and rejected, two alternatives: keeping the
types in the WASM package and having NAPI depend on it directly (asymmetric,
makes NAPI subordinate to WASM); and duplicating the types in both packages
(drift between copies, no obvious home for the canonical TSDoc comments).

Option enums on the JavaScript side are string union types rather than
const-asserted objects. This keeps _@gukhanmun/types_ genuinely type-only: it
emits zero bytes of runtime code, which matters for bundles and which means the
JSR package's source can be a single _.ts_ file with no transpilation step. The
trade-off is that the option strings are stringly typed at runtime; both
implementations validate them at the boundary and throw a `GukhanmunError` with
code `invalid-input` on unrecognized values.

Streaming on the JavaScript side uses the platform
`TransformStream<string, string>` interface, which is available across
browsers, Deno, Node 18+, and Bun. Chunks are JavaScript strings; encoding
concerns (`TextDecoderStream`, `TextEncoderStream`) live outside the gukhanmun
stream. Within the engine, a chunk that ends in the middle of a conversion
span, or close enough to a hanja character that a mixed-script dictionary key
could still cross the boundary, causes that trailing span to be held until the
next chunk arrives; everything before that point is flushed eagerly. The
dictionary lookahead part of that buffer is bounded by the dictionary's
`max_word_chars` plus a small constant for the lattice's outgoing state,
typically a few dozen characters. Fallback-only hanja runs are deliberately not
split at chunk boundaries, because render modes that show source hanja expose
annotation grouping; those runs flush at a later non-convertible boundary or
EOF.

Stateful middlewares can add their own lookahead requirement. A homophone marker
with a document-wide context, including plain-text `per-block` where no block
scopes exist, must buffer until EOF to preserve exact rendering. Disabling that
middleware restores early streaming but also disables cross-line homophone
disambiguation.

We chose strings rather than `Uint8Array` for the streaming type because the
engine fundamentally works on Unicode scalar values: byte-level chunking would
force the adapter to do partial-codepoint reassembly at every boundary, which
the platform's `TextDecoderStream` already does correctly. Users who have a
byte stream chain it through `TextDecoderStream` and then through the gukhanmun
transform.

### Dictionary configuration

The JavaScript dictionary configuration accepts either a file source or an
in-memory map:

```ts
export type DictionarySource = FileDictionarySource | MapDictionarySource;

export interface FileDictionarySource {
  readonly data: BufferSource | string | URL;
  readonly format: "cdb" | "fst" | "tsv";
}

export type MapDictionarySource =
  ReadonlyMap<string, Omit<DictionaryEntry, "hanja">>;
```

The two variants are distinguished by `instanceof Map` at runtime, and by
structural typing at compile time. The `Map` form is convenient for small
custom vocabularies created in code; the file form is for shipped dictionaries.

### Registry matrix

| Package                 | crates.io | npm                     | JSR                |
| ----------------------- | --------- | ----------------------- | ------------------ |
| `gukhanmun-core`        | yes       | no                      | no                 |
| `gukhanmun-html`        | yes       | no                      | no                 |
| `gukhanmun-markdown`    | yes       | no                      | no                 |
| `gukhanmun-cdb`         | yes       | no                      | no                 |
| `gukhanmun-fst`         | yes       | no                      | no                 |
| `gukhanmun-stdict`      | yes       | no                      | no                 |
| `gukhanmun-mkdict`      | yes       | no                      | no                 |
| `gukhanmun`             | yes       | no                      | no                 |
| `gukhanmun-cli`         | yes       | no                      | no                 |
| `gukhanmun-wasm`        | yes       | no                      | no                 |
| `gukhanmun-napi`        | yes       | no                      | no                 |
| `@gukhanmun/types`      | no        | yes (declarations only) | yes (`.ts` source) |
| `@gukhanmun/wasm`       | no        | yes                     | yes                |
| `@gukhanmun/napi`       | no        | yes                     | no                 |
| `@gukhanmun/stdict-fst` | no        | yes                     | yes                |
| `@gukhanmun/stdict-cdb` | no        | yes                     | yes                |
| `@gukhanmun/stdict-min` | no        | yes                     | yes                |

CLI binaries ship as platform releases (Linux x86\_64 and aarch64, macOS arm64
and x86\_64, Windows x86\_64) attached to the GitHub Releases for each version.

Versioning is lockstep across all packages. Every release tag advances every
crate's version (in the Rust workspace) and every JavaScript package's version
in tandem. Some packages have no functional change at a given release; their
version still advances so that the cross-language story is unambiguous. We
chose lockstep over per-package semver because the cost of mis-coordinated
dependency ranges (a user installing _@gukhanmun/wasm\@1.2_ with
_@gukhanmun/types\@1.3_ and getting confusing type errors) outweighs the cost of
an occasional no-op version bump. The CI workflow that fires on tag push
publishes to crates.io, builds the per-platform NAPI prebuilts in parallel,
publishes to npm, and publishes to JSR. Re-running a publish on the same tag is
a no-op against the registries that reject overwriting.

## Engineering policies

### Errors

Each crate defines its own error enum via `thiserror`. The umbrella _gukhanmun_
crate aggregates them with `#[from]` so that callers can use `?` across crate
boundaries without manual conversion. The pattern:

```rust
// gukhanmun-core/src/error.rs
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum Error {
    #[error("dictionary load failed: {0}")]
    DictionaryLoad(String),

    #[error("segmentation failed for {hanja:?}: {reason}")]
    Segmentation { hanja: String, reason: String },

    #[error("invalid hangul reading {reading:?} for hanja {hanja:?}")]
    InvalidReading { hanja: String, reading: String },

    #[error("internal invariant violated: {0}")]
    Internal(&'static str),

    #[error(transparent)]
    Other(#[from] Box<dyn std::error::Error + Send + Sync + 'static>),
}
```

The `#[non_exhaustive]` attribute lets us add new variants in minor releases
without breaking callers; downstream `match` expressions are required to have a
wildcard arm. Each variant carries enough structured data to drive both
human-readable messages and machine consumers. `std::error::Error::source()`
chains are preserved through `#[from]` and `#[source]` so that walking an error
gives a complete trace.

Library crates do not use `anyhow`. The CLI does, because the CLI's job is to
print errors to a human, not to be inspected by other code.

The stream-level recovery policy is configurable. The default is
`Recovery::Strict`: the engine propagates any reader error and stops.
`Recovery::Lenient` causes the engine to log the error via `tracing` and emit a
`Verbatim` token for the unrecognized region so that downstream tokens still
flow.

On the JavaScript side, errors are a single class with a discriminant code:

```ts
export class GukhanmunError extends Error {
  readonly code: ErrorCode;
  readonly chain: readonly { code: ErrorCode; message: string }[];
}

export type ErrorCode =
  | "dictionary-load"
  | "segmentation"
  | "invalid-reading"
  | "html-scan"
  | "html-malformed-attr"
  | "markdown"
  | "unsupported-content-type"
  | "invalid-input"
  | "io"
  | "internal"
  | "other";
```

The bindings walk the Rust `source()` chain at the FFI boundary and materialize
a `chain` property on the error, so JavaScript callers can inspect causes
without needing further FFI calls.

### Logging

_gukhanmun-core_ and its siblings depend on the `tracing` crate
unconditionally. Library code uses `tracing::trace!`, `tracing::debug!`,
`tracing::info!`, `tracing::warn!`, and `tracing::error!` directly. The
overhead when no subscriber is registered is one atomic load and a branch per
call site, well under any threshold worth optimizing for.

Binaries that want to compile out the calls entirely (the WebAssembly build is
the obvious case) enable `tracing`'s `release_max_level_off` feature in their
own _Cargo.toml_. That feature works at the binary level: it replaces every
`tracing::*!` invocation in every dependency with a no-op at compile time,
without requiring library code to be reconfigured.

We considered adding a library-level feature flag to make the `tracing`
dependency itself optional, with stub macros for the off path. The added
complexity (a `log` module per crate that conditionally re-exports tracing's
macros or provides stubs) is larger than the binary savings; we will revisit if
WebAssembly bundle measurements call for it.

### Testing

The test suite has four parts.

_Regression fixtures_ cover specific bug shapes that have appeared in Seonbi or
in early Gukhanmun development. The relevant subset of Seonbi's _test/data/_
directory ports over directly; each fixture is a pair of input and
expected-output files in HTML or Markdown, with a configuration sidecar.

_Snapshot tests_ use `insta` to compare IR serializations against a stored
JSON. They are most useful for the engine and middleware crates, where the
input and output are token streams rather than text. A failed snapshot prints a
colored diff and offers an interactive accept-or-reject prompt.

_Property-based tests_ use `proptest` to assert invariants over generated
inputs. The two invariants that matter most: reader-then-writer roundtrips a
token stream losslessly (modulo the documented Markdown best-effort caveats);
and engine-then-renderer applied to plain-hangul input is a no-op (the engine
should not invent annotations from text without hanja).

_Conformance tests_ run the Markdown adapter against a selected subset of the
CommonMark specification examples to verify that the adapter does not break
syntax that Gukhanmun is not interested in changing.

CI runs all four under stable, beta, and the MSRV (minimum supported Rust
version) of the workspace. The WASM build is also exercised for size
regressions: a fixed size budget per artifact is enforced, and a regression
that exceeds it fails the build.

## Presets

| Option               | `ko-kr`           | `ko-kp`           |
| -------------------- | ----------------- | ----------------- |
| `rendering`          | `hangul-only`     | `hangul-only`     |
| `disambiguation`     | `per-block`       | `off`             |
| `segmentation`       | `lattice`         | `lattice`         |
| `initialSoundLaw`    | `true`            | `false`           |
| `numerals`           | `hangul-phonetic` | `hangul-phonetic` |
| `dictionary.bundled` | `"stdict-ko-kr"`  | `false`           |
| `firstOccurrence`    | (none)            | (none)            |

The `ko-kr` preset matches the orthographic and lexical conventions of South
Korea: dictionary-driven readings, lattice segmentation, the initial sound law
applied to fallback fragments, and per-block homophone disambiguation that
emits hanja in parentheses when the reading is ambiguous within a paragraph.
The `ko-kp` preset matches the North Korean convention of writing Sino-Korean
words in hangul without the initial sound law applied (래일, 류행, 녀자), with
no bundled dictionary because the South Korean stdict's readings would be
incorrect for `ko-KP`.

The CLI exposes both as `--preset ko-kr` and `--preset ko-kp`. Individual
options remain settable to override the preset, for example
`--preset ko-kr --no-stdict` disables the bundled dictionary while keeping the
other South Korean defaults.

## Initial sound law table

The South Korean orthography (한글 맞춤법, Clause 5, Section 52, Chapter 6)
converts a small set of word-initial hangul syllables. The table is reproduced
from Seonbi's `Text.Seonbi.Hanja` module and is the source of truth for
_gukhanmun-core_'s `initial_sound_law_table` constant.

| Original | Converted |
| -------- | --------- |
| 녀        | 여         |
| 뇨        | 요         |
| 뉴        | 유         |
| 니        | 이         |
| 랴        | 야         |
| 려        | 여         |
| 례        | 예         |
| 료        | 요         |
| 류        | 유         |
| 리        | 이         |
| 라        | 나         |
| 래        | 내         |
| 로        | 노         |
| 뢰        | 뇌         |
| 루        | 누         |
| 르        | 느         |

## Hanja numeral table

The fallback phoneticizer and the `additive-arabic` numeral strategy share a
single table of digit and place-marker hanja with their canonical values.

| Hanja                        | Value      | Notes  |
| ---------------------------- | ---------- | ------ |
| `零`, `〇`                     | 0          |        |
| `一`, `壹`, `壱`, `弌`, `夁`      | 1          |        |
| `二`, `貳`, `贰`, `弐`, `弍`, `貮` | 2          |        |
| `三`, `參`, `叁`, `参`, `弎`, `叄` | 3          |        |
| `四`, `肆`, `䦉`                | 4          |        |
| `五`, `伍`                     | 5          |        |
| `六`, `陸`, `陆`                | 6          |        |
| `七`, `柒`, `漆`                | 7          |        |
| `八`, `捌`                     | 8          |        |
| `九`, `玖`                     | 9          |        |
| `十`, `拾`                     | 10         |        |
| `百`, `佰`, `陌`                | 100        |        |
| `千`, `仟`, `阡`                | 1000       |        |
| `萬`, `万`                     | 10000      |        |
| `億`                          | 100000000  | $10^8$ |
| `兆`                          | $10^\{12}$ |        |
| `京`                          | $10^\{16}$ |        |
| `垓`                          | $10^\{20}$ |        |
| `秭`                          | $10^\{24}$ |        |
| `穰`                          | $10^\{28}$ |        |
| `溝`                          | $10^\{32}$ |        |
| `澗`                          | $10^\{36}$ |        |

The `additive-arabic` strategy treats place markers as multipliers and adjacent
digit hanja as multiplicands, with the Korean elision rule that bare `十`,
`百`, `千` mean 10, 100, 1000 respectively (not `一十`, `一百`, `一千`).

## HTML preserved tags

The default `HtmlScopeData::is_preserve()` returns true for the following tag
names regardless of attribute content: `pre`, `code`, `kbd`, `script`, `style`,
`textarea`.

It additionally returns true when the inherited `lang` attribute's primary tag
is anything other than `ko`, `kor`, or a subtag-prefixed Korean form (`ko-KR`,
`ko-Hang`, `ko-Kore`, `kor-KP`, and so on). The Korean predicate matches
Seonbi's `isKorean`.

Users who want to extend the list (for example, to add a project-specific
`class="no-translate"` attribute) pass an `HtmlReaderOptions` value with a
`preserve_when` predicate to `read_html_fragment_with_options`. The predicate
receives an `HtmlElementInfo` view of each opened element—its canonical tag
name, the raw attribute slice from the start tag, and the inherited `lang`
value—and returns `true` to preserve the scope. A predicate-matched scope
inherits its preserve flag to descendants, mirroring how the built-in
preserved tags propagate, so callers do not have to re-assert the rule on
every child. The CLI exposes the two most common shapes of this hook as
`--html-preserve-class CLASS` and `--html-preserve-attr KEY[=VALUE]` (both
repeatable, OR-composed, valid only with `--format text/html`). A
format-neutral skip closure on `EngineOptions` is contemplated for a future
release; it is not implemented today because every adapter that currently
ships can satisfy its preserve needs through its own `ScopeData`.

## CDB-trie key scheme

A CDB-trie database stores one record per prefix of each entry. The key is the
UTF-8 bytes of the prefix. The value layout:

| Offset | Size          | Field                                                                  |
| ------ | ------------- | ---------------------------------------------------------------------- |
| 0      | 1             | `is_complete` (1 if the prefix is itself an entry)                     |
| 1      | 1             | `mark` (bitfield: bit 0 is `require_hanja`, bit 1 is `require_hangul`) |
| 2      | 2             | `reading_len` (little-endian; 0 if `is_complete = 0`)                  |
| 4      | `reading_len` | reading (UTF-8)                                                        |

A separate well-known key, `__gukhanmun_meta__`, stores a small CBOR document
with build metadata: source, license, build date, original entry count, prefix
count, maximum entry length in characters and bytes.

## FST schema

The FST database stores one entry per dictionary word. The key is the UTF-8
bytes of the hanja form; the value is a 64-bit integer whose layout is:

| Bits  | Field                                                        |
| ----- | ------------------------------------------------------------ |
| 0–15  | reading length in UTF-8 bytes                                |
| 16–23 | `mark` (`require_hanja` and `require_hangul` bits as in CDB) |
| 24–63 | offset into a side reading-string table                      |

The reading-string table is a contiguous block of UTF-8 bytes following the FST
itself. The side table is necessary because the FST value type is fixed-size;
we cannot store variable-length readings inline. The `mark` byte sits in the
value rather than the side table because checking it is hot for every lookup.

A metadata header at the file start (eight bytes of magic, version, layout
offsets, and a CBOR metadata blob analogous to the CDB form) precedes the FST
bytes.

## Glossary

| Hangul  | Hanja   | English                                           |
| ------- | ------- | ------------------------------------------------- |
| 한자      | 漢字      | hanja, a Chinese character used in Korean writing |
| 한자어     | 漢字語     | Sino-Korean word                                  |
| 국한문혼용   | 國漢文混用   | mixed-script Korean writing                       |
| 두음법칙    | 頭音法則    | initial sound law                                 |
| 표준국어대사전 | 標準國語大辭典 | _Standard Korean Language Dictionary_             |
| 한글      | 한글      | hangul, the native Korean alphabet                |
| 한글전용    | 한글專用    | hangul-only writing                               |
| 동음이의    | 同音異義    | homophony, distinct words sharing a reading       |



---
url: /internals/dictionary-format.md
---

# Dictionary format

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.

## Canonical TSV input

The primary input format is UTF-8 TSV with a required header row. Each file
must contain at least these columns:

| Column   | Required | Meaning                                 |
| -------- | -------- | --------------------------------------- |
| `hanja`  | yes      | Source spelling used as the lookup key. |
| `hangul` | yes      | Hangul reading emitted for the key.     |

These optional columns are recognized:

| Column           | Default | Meaning                                           |
| ---------------- | ------- | ------------------------------------------------- |
| `require_hanja`  | `false` | Force renderers to keep the source hanja visible. |
| `require_hangul` | `false` | Force renderers to include a hangul gloss.        |

Boolean values are `true`, `false`, `1`, or `0`. Empty optional boolean cells
are treated as `false`.

Additional columns such as `category`, `source`, or `note` are allowed as
future extension space. The current builder does not consume them; it emits a
short warning and ignores their values.

Example:

```tsv
hanja	hangul	require_hanja	require_hangul	category
天地	천지	false	false	basic
漢字	한자	true	false	basic
色깔論	색깔론	false	true	mixed
```

## CSV and JSONL input

`gukhanmun-mkdict` chooses the input parser from each file extension.  _.tsv_
uses the canonical TSV parser, _.csv_ uses the CSV parser, _.jsonl_ uses the
JSON Lines parser, and unknown extensions are treated as TSV for compatibility.

CSV files use the same header names as TSV:

```csv
hanja,hangul,require_hanja,require_hangul
天地,천지,true,false
```

Each JSONL line is one object.  The boolean fields accept either snake\_case or
camelCase spellings:

```json
{"hanja":"漢字","hangul":"한자","requireHanja":false,"requireHangul":true}
```

## Merge policy

When multiple input files are supplied, or when one input file repeats a
`hanja` key, `gukhanmun-mkdict` applies the configured merge policy:

- `error`: fail on the first duplicate key. This is the default.
- `first-wins`: keep the first entry and ignore later duplicates.
- `last-wins`: replace earlier entries with the last duplicate.

After merging, entries are sorted by UTF-8 key bytes before backend encoding.
This makes generated FST and CDB artifacts deterministic for the same
normalized inputs and metadata.

## Build metadata

Every generated backend file embeds CBOR metadata. The minimum keys are:

| Key              | Source                                                                       |
| ---------------- | ---------------------------------------------------------------------------- |
| `source`         | `--metadata source=...`, or an empty string.                                 |
| `license`        | `--metadata license=...`, or an empty string.                                |
| `build_date`     | `--metadata build_date=...`, `SOURCE_DATE_EPOCH`, or `1970-01-01T00:00:00Z`. |
| `entry_count`    | Number of merged dictionary entries.                                         |
| `version`        | Dictionary file format version.                                              |
| `max_word_chars` | Maximum key length in Unicode scalar values.                                 |
| `max_key_bytes`  | Maximum key length in UTF-8 bytes.                                           |
| `prefix_count`   | CDB only: number of prefix records.                                          |

`entry_count`, `version`, `max_word_chars`, `max_key_bytes`, and
`prefix_count` are reserved and cannot be supplied with `--metadata`. Other
`--metadata KEY=VAL` pairs are preserved as string values.

For reproducible builds, the builder does not use the current clock by default.
If `build_date` is not passed explicitly and `SOURCE_DATE_EPOCH` is set, the
epoch is formatted as UTC RFC 3339. If neither value is present, the fixed date
`1970-01-01T00:00:00Z` is used.

## FST backend file

The first implemented backend format is `fst`. The file contains:

1. A fixed 64-byte little-endian header.
2. A CBOR metadata map.
3. `fst::Map` bytes.
4. A contiguous UTF-8 reading string table.

The fixed header fields are:

| Field           | Size | Meaning                                  |
| --------------- | ---- | ---------------------------------------- |
| magic           | 8    | `GUKHMFST`.                              |
| version         | 4    | File format version, currently `1`.      |
| header length   | 4    | Fixed header length, currently `64`.     |
| metadata offset | 8    | Byte offset of the CBOR metadata.        |
| metadata length | 8    | Byte length of the CBOR metadata.        |
| FST offset      | 8    | Byte offset of the `fst::Map` bytes.     |
| FST length      | 8    | Byte length of the `fst::Map` bytes.     |
| readings offset | 8    | Byte offset of the reading string table. |
| readings length | 8    | Byte length of the reading string table. |

Each FST key is the UTF-8 bytes of the `hanja` column. Each FST value is a
64-bit integer:

| Bits  | Field                                                               |
| ----- | ------------------------------------------------------------------- |
| 0-15  | Reading length in UTF-8 bytes.                                      |
| 16-23 | Mark bitfield: bit 0 is `require_hanja`, bit 1 is `require_hangul`. |
| 24-63 | Offset into the reading string table.                               |

The reading bytes are stored in the reading string table, not in the FST value,
because FST values are fixed-width integers.

At runtime, `gukhanmun-fst` decodes the fixed header and CBOR metadata eagerly.
The FST map bytes and contiguous reading table then share a single byte backing
store: owned heap bytes for `FstDictionary::open()` and
`FstDictionary::from_bytes()`, static bytes for
`FstDictionary::from_static_bytes()`. The crate intentionally does not expose a
safe file-backed mmap loader because Rust cannot enforce that another file
descriptor or process will keep the mapped file immutable while the dictionary
is live.
`entries()` and `has_homophone()` enumerate the FST and therefore remain
full-dictionary scans; callers that need repeated homophone checks should use
the core homophone middleware's batch index.

## CDB backend file

The CDB backend format is `cdb`.  It uses a trie embedded in CDB key space:
each prefix of each dictionary key is written as a CDB key.  Prefix records
that are complete dictionary entries carry the reading and mark bits; prefix
records that only lead to longer entries carry no reading.

| Offset | Size          | Field                                                               |
| ------ | ------------- | ------------------------------------------------------------------- |
| 0      | 1             | `is_complete` (`1` if this prefix is itself an entry).              |
| 1      | 1             | Mark bitfield: bit 0 is `require_hanja`, bit 1 is `require_hangul`. |
| 2      | 2             | Reading length in UTF-8 bytes, little-endian; `0` for non-complete. |
| 4      | `reading_len` | Reading bytes.                                                      |

The metadata CBOR map is stored under the reserved key
`__gukhanmun_meta__`.

The runtime CDB backend uses the `cdb` crate's file-backed reader and keeps the
backend opaque behind `HanjaDictionary`.  This already avoids loading the whole
CDB file through a Gukhanmun-owned buffer without adding an unsafe mmap surface.

## Validation

With `--validate`, `gukhanmun-mkdict` writes the output, opens it again with
the selected backend, and checks that every merged entry can be recovered with
the same reading and mark bits. Validation failure is fatal.



---
url: /internals/stdict.md
---

# Standard Korean Language Dictionary

`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_.

## Snapshot

| Field          | Value                                                              |
| -------------- | ------------------------------------------------------------------ |
| Source archive | _전체 내려받기\_표준국어대사전\_JSON\_20260606.zip_                             |
| Dump date      | 2026-06-06                                                         |
| SHA-256        | `7082b9665ed1e01b563e4b5924fb241e455d945b35507910ac53453d7bb91dee` |
| TSV entries    | 260,690                                                            |

## Regeneration

Place the downloaded zip wherever convenient, then run:

```sh
cargo run -p gukhanmun-stdict --bin gukhanmun-stdict-extract -- \
  -o crates/gukhanmun-stdict/data/stdict.tsv \
  --suffix-output crates/gukhanmun-stdict/data/suffix.tsv \
  ~/Downloads/전체\ 내려받기_표준국어대사전_JSON_20260606.zip
```

The extractor writes deterministic UTF-8 TSV sorted by dictionary key.  The
`gukhanmun-stdict` build script then invokes `gukhanmun-mkdict` to build the
embedded FST at compile time.

## Suffix readings

South Korean initial sound law (頭音法則) makes some hanja read differently
word-initially than elsewhere, so `年` reads `연` in `年度` but `년` in
`1998년`. The engine recovers the original sound of a _single_ hanja outside
word-initial position from the bundled unihan readings, so the canonical TSV
needs no extra data for single hanja.

Multi-syllable compounds are different: only the dictionary knows which ones
keep their original leading sound outside word-initial position.  The dictionary
records this through suffix head words (written with a leading hyphen, such as
`-년대`) and bound-noun head words.  The extractor collects these and, for every
hanja-only key of two or more characters whose word-initial reading `I` and
suffix reading `S` differ only in their first syllable, writes a row
`hanja<TAB>I<TAB>S` to _crates/gukhanmun-stdict/data/suffix.tsv_ (for example
`年代<TAB>연대<TAB>년대`).  The first-syllable-only test excludes semantically
distinct readings such as `便` (`편`/`변`).  Single hanja are intentionally
omitted because the engine handles them from the unihan readings.

`gukhanmun_stdict::ko_kr` returns a `KoKrDictionary` that wraps the embedded FST
and attaches each suffix reading to the matching entry, so the engine can pick
the position-correct reading.

## Extraction policy

Only entries whose `word_unit` is `단어` and whose `original_language_info`
can produce at least one hanja-bearing lookup key are included.  The dictionary
reading comes from `word_info.word`, not from `pronunciation_info`; homograph
numbers, hyphens, and `^` separators are removed from the word form.

For native hanja entries, `language_type = "한자"` segments are copied as the
lookup key.  Native Korean (`고유어`) segments may appear around hanja segments,
so mixed-script entries such as native-prefix or native-suffix words are
preserved.  Source notation markers such as `▽` are stripped from lookup keys.
Inline alternate spellings marked with `/` are expanded into separate keys, so
source spellings such as `布告하다/佈告하다` produce both runtime-matchable
forms.

Chinese, Japanese, and unknown-origin loanword segments are included only when
their `original_language` contains a standalone hanja spelling or a bracketed
hanja spelling, such as `Beijing[北京]` or `haiku[俳句]`.  In those cases the
hanja spelling is used as the lookup key and romanized text is discarded.
Foreign-origin segments without such a hanja spelling are skipped so values
like `←lipoic酸` do not become mixed-script keys.  A single hanja borrowed for
a foreign reading (such as `引` from Japanese `引き`) is dropped, however, so it
cannot shadow that character's Sino-Korean reading in every compound that
contains it (`引` → `인`, recovered from the bundled unihan readings, not
`삐끼`).  Multi-character foreign spellings such as `北京` → `베이징` are kept.

Alternate hanja spellings marked with `/(병기)` are expanded into separate TSV
rows.  Duplicate keys keep the highest-priority reading.  Entries whose senses
only redirect to another entry, such as `→ 표지03.`, lose to entries with
substantive definitions for the same hanja spelling.  Multi-character bracketed
loanword hanja spellings are preferred over native Sino-Korean readings for the
same key, and otherwise the first reading encountered in sorted dump shard order
is kept.

The six Sino-Korean compounds that Standard Korean Orthography §30 spells with
a saisiot (사이시옷), namely 곳간(庫間), 셋방(貰房), 숫자(數字), 찻간(車間),
툇간(退間), and 횟수(回數), are promoted above the default priority, so the
prescribed saisiot spelling wins over a saisiot-free homograph for those keys
(數字 → 숫자, not 수자).  The list is closed and named directly by the
orthographic standard, so no general saisiot heuristic is involved.

The extractor itself writes `require_hanja` and `require_hangul` as `false` for
every row.  Annotation marks are layered on later by the rules file (see
below) so the canonical TSV remains a pure hanja↔hangul mapping.

## Annotation rules

_crates/gukhanmun-stdict/data/rules.tsv_ lists hand-curated rules that
OR-merge `require_hanja`/`require_hangul` marks into dictionary entries at
build time.  The stdict crate's _build.rs_ passes the rules file to
`gukhanmun-mkdict`, so the embedded FST ships with the marks already encoded.

The format is a TSV with the columns `kind`, `pattern`, `require_hanja`,
`require_hangul`, `reason`.  Three kinds of rule are supported:

- `entry` — `pattern` matches one dictionary entry whose hanja key equals
  `pattern` exactly.
- `contains` — `pattern` is a hanja substring (one or more characters);
  every entry whose hanja key contains the substring is marked.  Patterns
  must consist only of hanja characters because dictionary keys can be
  mixed-script (e.g. `布告하다`); a hangul or Latin substring would
  silently mark unrelated entries.
- `reading` — `pattern` is a hangul reading; every entry with that reading
  is marked.

A rule must set at least one of `require_hanja`/`require_hangul`, must
include a non-empty `reason`, and must match at least one entry.  Multiple
rules that touch the same entry are OR-merged.  Stale rules that match no
entry fail the build so that the rules file does not drift out of sync with
the dictionary; pass `--allow-unmatched-rules` to `gukhanmun-mkdict` if the
rule file is shared with a smaller dictionary.

To add or edit a rule, update _rules.tsv_ and run:

```sh
cargo test -p gukhanmun-stdict
```

The test suite rebuilds the bundled FST, verifies the marks land on
representative entries, and exercises `convert_plain_text` end to end with
`RenderMode::HangulOnly` to confirm that a marked entry renders as
`한글(漢字)`.



---
url: /internals/opendict.md
---

# Open Korean Dictionary

`gukhanmun-opendict` bundles category snapshots derived from the National
Institute of Korean Language's _Open Korean Dictionary_ (우리말샘) JSON
download.

The source dump is not committed to this repository.  The committed source of
truth is the four canonical TSV files under
_crates/gukhanmun-opendict/data/_, split by the source `senseinfo.type` value:
general (一般語), North Korean (北韓語), dialect (方言), and archaic (옛말).

## Snapshot

| Field          | Value                                                              |
| -------------- | ------------------------------------------------------------------ |
| Source archive | _전체 내려받기\_우리말샘\_json\_20260603.zip_                                |
| Dump date      | 2026-06-03                                                         |
| SHA-256        | `345cfae71f3710cc483975a9af04773985aaaa4ba7ca4855a4bb93f390f63e8e` |
| Data license   | CC BY-SA 2.0 KR                                                    |

| Category     | Source label | TSV file           | Entries | SHA-256                                                            |
| ------------ | ------------ | ------------------ | ------: | ------------------------------------------------------------------ |
| General      | 일반어          | _general.tsv_      | 350,330 | `03a744cc783797e09b0e094bf2649718792edcf7e3254a4010994814ad9a16d9` |
| North Korean | 북한어          | _north-korean.tsv_ |  34,093 | `cdc67c66b3c5febf870a406188e9621dd3a72654b5e878de1e9fb25b40db6256` |
| Dialect      | 방언           | _dialect.tsv_      |   5,714 | `24547f29e78e2b3bc9a1709294e0030940b46c862e503f2f337c2f5609a801a8` |
| Archaic      | 옛말           | _archaic.tsv_      |      16 | `0f77342de48317faf10a997b156955bf73cad442e36d150a91ed19265fea0bdc` |

## Regeneration

Place the downloaded zip or extracted shard directory wherever convenient,
then run:

```sh
cargo run --release -p gukhanmun-opendict --bin gukhanmun-opendict-extract -- \
  ~/Downloads/전체\ 내려받기_우리말샘_json_20260603 \
  --general-output crates/gukhanmun-opendict/data/general.tsv \
  --north-korean-output crates/gukhanmun-opendict/data/north-korean.tsv \
  --dialect-output crates/gukhanmun-opendict/data/dialect.tsv \
  --archaic-output crates/gukhanmun-opendict/data/archaic.tsv
```

The extractor accepts a single JSON file, the official zip archive, or a
directory of JSON shards.  Directory entries and zip members are processed in
lexicographic order.  Each category TSV is deterministic UTF-8 sorted by
dictionary key.

The `gukhanmun-opendict` build script invokes `gukhanmun-mkdict` to build four
embedded FST dictionaries at compile time.  The JavaScript package data tasks
build matching FST and CDB binaries for `@gukhanmun/opendict-fst` and
`@gukhanmun/opendict-cdb`.

## Extraction policy

Only entries whose `word_unit` is `어휘` and whose `original_language_info` can
produce at least one hanja-bearing lookup key are included.  The dictionary
reading comes from `wordinfo.word`; homograph numbers, hyphens, and `^`
separators are removed from the word form.

The extractor reuses the shared key construction logic used by
`gukhanmun-stdict`.  Native hanja segments are copied as lookup keys, native
Korean segments may appear around hanja segments, bracketed foreign hanja
spellings such as `Beijing[北京]` are kept, and foreign-origin segments without
hanja are skipped.  Single-hanja foreign readings are skipped so they cannot
shadow Sino-Korean fallback readings recovered from unihan.

Duplicate keys are resolved within each category only: the first reading
encountered in sorted dump shard order wins for that category.  This keeps the
general (一般語) and North Korean (北韓語) readings independent, so a caller
can place the North Korean dictionary above another dictionary in a
`ChainDictionary` without changing the South Korean general snapshot.

## Runtime use

The Rust crate exposes one loader per category:

- `gukhanmun_opendict::general()`
- `gukhanmun_opendict::north_korean()`
- `gukhanmun_opendict::dialect()`
- `gukhanmun_opendict::archaic()`

`Preset::KoKp` includes the North Korean (北韓語) dictionary by default in Rust
and the CLI. The JavaScript bindings do not auto-load dictionary data for
either preset; use `@gukhanmun/opendict-fst` or `@gukhanmun/opendict-cdb`
explicitly and pass the categories you need through
`load({ dictionaries: [...] })`.



---
url: /index.md
---

# Gukhanmun

> Rust/JavaScript library that converts mixed-script Korean into hangul-only text

[Introduction](./guide/intro) | [CLI](./guide/cli/install) | [Rust](./guide/rust/install) | [JavaScript](./guide/javascript/install)

## Features

- [<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M7.5 21 3 16.5m0 0L7.5 12M3 16.5h13.5m0-13.5L21 7.5m0 0L16.5 12M21 7.5H7.5"/></svg> **Hanja-to-hangul conversion**](./guide/cli/start): Converts mixed-script Korean text containing hanja into hangul-only output, powered by the bundled *Standard Korean Dictionary*.
- [<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M19.5 14.25v-2.625a3.375 3.375 0 0 0-3.375-3.375h-1.5A1.125 1.125 0 0 1 13.5 7.125v-1.5a3.375 3.375 0 0 0-3.375-3.375H8.25m0 12.75h7.5m-7.5 3H12M10.5 2.25H5.625c-.621 0-1.125.504-1.125 1.125v17.25c0 .621.504 1.125 1.125 1.125h12.75c.621 0 1.125-.504 1.125-1.125V11.25a9 9 0 0 0-9-9Z"/></svg> **Multiple output formats**](./guide/cli/rendering): Processes plain text, HTML fragments, and Markdown (CommonMark and GFM). Supports hangul-only, parenthetical, and ruby markup rendering modes.
- [<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M12 6.042A8.967 8.967 0 0 0 6 3.75c-1.052 0-2.062.18-3 .512v14.25A8.987 8.987 0 0 1 6 18c2.305 0 4.408.867 6 2.292m0-14.25a8.966 8.966 0 0 1 6-2.292c1.052 0 2.062.18 3 .512v14.25A8.987 8.987 0 0 0 18 18a8.967 8.967 0 0 0-6 2.292m0-14.25v14.25"/></svg> **Custom dictionaries**](./guide/cli/dictionary): Load domain-specific vocabulary in FST or CDB format alongside the bundled dictionary to handle specialised terminology.
- [<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M10.5 6h9.75M10.5 6a1.5 1.5 0 1 1-3 0m3 0a1.5 1.5 0 1 0-3 0M3.75 6H7.5m3 12h9.75m-9.75 0a1.5 1.5 0 0 1-3 0m3 0a1.5 1.5 0 0 0-3 0m-3.75 0H7.5m9-6h3.75m-3.75 0a1.5 1.5 0 0 1-3 0m3 0a1.5 1.5 0 0 0-3 0m-9.75 0h9.75"/></svg> **Per-hanja directives**](./guide/cli/directives): Force or suppress annotations for specific characters or glob patterns, inline or via a directives file.
- [<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="m6.75 7.5 3 2.25-3 2.25m4.5 0h3m-9 8.25h13.5A2.25 2.25 0 0 0 21 18V6a2.25 2.25 0 0 0-2.25-2.25H5.25A2.25 2.25 0 0 0 3 6v12a2.25 2.25 0 0 0 2.25 2.25Z"/></svg> **CLI, Rust, and JavaScript**](./guide/javascript/start): Use from the command line, embed in a Rust crate, or run in browsers, Node.js, Deno, and Bun via WebAssembly or a native Node.js addon.
- [<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M16.023 9.348h4.992v-.001M2.985 19.644v-4.992m0 0h4.992m-4.993 0 3.181 3.183a8.25 8.25 0 0 0 13.803-3.7M4.031 9.865a8.25 8.25 0 0 1 13.803-3.7l3.181 3.182m0-4.991v4.99"/></svg> **Streaming API**](./guide/javascript/streaming): Process arbitrarily large documents chunk by chunk with a <code>TransformStream</code> interface in JavaScript or an iterator API in Rust.