@gukhanmun/wasm 0.4.0-dev.236 → 0.4.0-dev.248

package/dist/index.d.ts

@@ -1,687 +1,4 @@
-//#region ../types/dist/index.d.ts
-//#region index.d.ts
-/**
- * Canonical TypeScript API contract for Gukhanmun.
- *
- * This package contains only TypeScript type declarations and carries no
- * runtime code.  Both `@gukhanmun/wasm` and `@gukhanmun/napi` satisfy this
- * contract structurally.  All TSDoc lives here as the single source of
- * truth for the JavaScript API.
- *
- * @module @gukhanmun/types
- */
-/**
- * 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 {@link GukhanmunOptions} override
- * the preset.
- */
-type Preset = "ko-kr" | "ko-kp";
-/**
- * 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
- *   {@link GukhanmunOptions.originalGloss}.  Corresponds to Rust
- *   `RenderMode::Original`.
- */
-type RenderMode = "hangul-only" | "hangul-hanja-parens" | "hanja-hangul-parens" | "ruby-on-hangul" | "ruby-on-hanja" | "original";
-/** The hanja variant set applied after dictionary recognition. */
-type HanjaVariantSet = "as-dictionary" | "shinjitai" | "kanxi" | "simplified" | "asahimoji";
-/**
- * Selects how glosses are rendered when {@link RenderMode} is `"original"`.
- *
- * - `"parens"` — Wrap the gloss in parentheses: `漢字(한글)` (default).
- *   Corresponds to Rust `OriginalGloss::Parens`.
- * - `"ruby"` — Wrap the gloss in a `<ruby>` element.  Falls back to
- *   parentheses in scopes that do not permit inline markup.  Corresponds to
- *   Rust `OriginalGloss::Ruby`.
- *
- * This option is ignored when `rendering` is not `"original"`.
- */
-type OriginalGloss = "parens" | "ruby";
-/**
- * Controls how the engine segments a hanja-containing span into dictionary
- * words and fallback fragments.  Corresponds to Rust `SegmentationStrategy`.
- *
- * - `"lattice"` — Dynamic programming over all possible dictionary matches
- *   at each position; selects the segmentation that maximises dictionary
- *   coverage and then prefers fewer segments.  This is the default and
- *   produces better results than greedy approaches when a longer prefix
- *   would leave a suffix uncovered by the dictionary.  Corresponds to Rust
- *   `SegmentationStrategy::Lattice`.
- * - `"eager"` — Left-to-right longest-match (greedy).  Lower overhead per
- *   span at the cost of occasional mis-segmentation.  Corresponds to Rust
- *   `SegmentationStrategy::Eager`.
- */
-type Segmentation = "lattice" | "eager";
-/**
- * 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`.
- */
-type NumeralStrategy = "hangul-phonetic" | "positional-arabic" | "additive-arabic" | "smart";
-/**
- * Defines the scope within which the homophone marker and first-occurrence
- * filter track previously seen readings.  Corresponds to Rust `ContextWindow`.
- *
- * - `"off"` — Disable the corresponding middleware entirely.
- * - `"per-block"` — Reset at each block boundary (paragraph, list item,
- *   heading, …).  This is the default for both homophone marking and first-
- *   occurrence filtering.  In plain text, which has no block scopes, `per-block`
- *   is document-wide.
- * - `"per-section"` — Reset at each heading boundary (HTML `<h1>`–`<h6>`,
- *   Markdown ATX/setext headings).
- * - `"per-document"` — Track across the entire document.  This buffers the
- *   entire token stream and is appropriate only for small inputs or when full
- *   accuracy matters more than latency.
- */
-type ContextWindow = "off" | "per-block" | "per-section" | "per-document";
-/**
- * Selects how the homophone marker decides that a reading needs its hanja shown
- * in `rendering: "hangul-only"`.  Corresponds to Rust `HomophoneDetection`.
- *
- * - `"context-local"` — Gloss a reading only when a different-meaning homophone
- *   actually appears within the {@link ContextWindow}.  This keeps hangul-only
- *   output clean and is the default.
- * - `"dictionary-wide"` — Also gloss readings shared by other hanja forms
- *   anywhere in the dictionary, even when no homophone appears in the text.
- *   With a large reference dictionary this glosses most Sino-Korean words; words
- *   that should always be glossed are better expressed with `requireHanja`.
- */
-type HomophoneDetection = "context-local" | "dictionary-wide";
-/**
- * Controls how the pipeline handles reader errors encountered during HTML
- * scanning.  Corresponds to Rust `Recovery`.
- *
- * - `"strict"` — Propagate the error and stop (default).
- * - `"lenient"` — Log the error via `tracing` and emit a verbatim token for
- *   the unrecognised region so that downstream tokens continue to flow.
- *
- * This option is meaningful only for `format: "html"`.  Markdown parsing does
- * not produce recoverable errors, so this option is ignored for Markdown input.
- */
-type Recovery = "strict" | "lenient";
-/**
- * A single dictionary entry: a hanja key with one hangul reading.
- *
- * Callers pass these in {@link MapDictionarySource.entries} to build a
- * dictionary at runtime.  Fields mirror the Rust `ReadingCandidate` type plus
- * the hanja key.
- */
-interface DictionaryEntry {
-  /** The hanja form (dictionary key), e.g. `"漢字"`. */
-  readonly hanja: string;
-  /** The word-initial hangul reading, e.g. `"한자"`. */
-  readonly reading: string;
-  /**
-   * The reading used when the match is not word-initial, when it differs from
-   * {@link reading}.  For example a `年代` entry with `reading: "연대"` and
-   * `suffixReading: "년대"` reads `1990年代` as `1990년대` but `年代` alone as
-   * `연대`.
-   *
-   * Corresponds to Rust `ReadingCandidate::suffix_reading`.
-   */
-  readonly suffixReading?: string;
-  /**
-   * Relative default preference for this reading within its hanja key, a
-   * non-negative integer.  Larger values win, so an entry listed twice with
-   * different preferences keeps competing readings and uses the higher one by
-   * default.  Absent means `0`.
-   *
-   * List order never selects the default: when two readings share a preference
-   * the tie is broken by reading spelling.  Set distinct preferences to choose
-   * a default deliberately.
-   *
-   * Corresponds to Rust `ReadingCandidate::preference`.
-   */
-  readonly preference?: number;
-  /**
-   * When `true`, the renderer should always show the original hanja
-   * alongside the hangul reading, regardless of ambiguity.
-   *
-   * Corresponds to Rust `MatchMark::require_hanja`.
-   */
-  readonly requireHanja?: 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`.
-   */
-  readonly requireHangul?: boolean;
-}
-/**
- * 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 absence of an `entries` property (`"entries" in source` selects a
- * {@link MapDictionarySource}).
- */
-interface FileDictionarySource {
-  /**
-   * 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).
-   */
-  readonly data: ArrayBuffer | ArrayBufferView | URL | string;
-  /**
-   * 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 and never accepted.  Pass entries in memory
-   * through {@link MapDictionarySource} instead of compiling a table.
-   */
-  readonly format: "fst" | "cdb";
-}
-/**
- * A dictionary built from entries computed at runtime, such as per-document
- * reading overrides.
- *
- * Use this instead of compiling a TSV file with `gukhanmun-mkdict` when the
- * entries do not exist on disk, for example in a browser, an edge runtime, or a
- * site generator that derives entries per document.
- *
- * A source is distinguished from a {@link FileDictionarySource} by the presence
- * of an `entries` property.
- *
- * @example
- * ```ts
- * import { stdictFst } from "@gukhanmun/stdict-fst";
- * const g = await load({
- *   dictionaries: [
- *     {
- *       entries: [
- *         { hanja: "高橋", reading: "다카하시" },
- *         { hanja: "東京", reading: "도쿄", preference: 10 },
- *         { hanja: "年代", reading: "연대", suffixReading: "년대" },
- *       ],
- *     },
- *     await stdictFst(),
- *   ],
- * });
- * ```
- */
-interface MapDictionarySource {
-  /**
-   * The entries of this dictionary.
-   *
-   * Repeated `hanja` keys append competing readings instead of replacing each
-   * other, and {@link DictionaryEntry.preference} decides which reading is the
-   * context-free default.  Several readings for one key also let the engine
-   * pick a reading from a following particle (`東京을` versus `東京를`).
-   *
-   * An empty list contributes nothing, which is a convenient way to express
-   * "this document has no overrides".
-   */
-  readonly entries: readonly DictionaryEntry[];
-}
-/**
- * A dictionary source accepted by {@link GukhanmunOptions.dictionaries}.
- *
- * Sources are tried in array order; the first match for a hanja key wins, and
- * every source listed before a compiled dictionary overrides that dictionary
- * for the keys it carries.
- *
- * @example
- * ```ts
- * import { stdictFst } from "@gukhanmun/stdict-fst";
- * const g = await load({ dictionaries: [await stdictFst()] });
- * ```
- */
-type DictionarySource = FileDictionarySource | MapDictionarySource;
-/**
- * Fine-grained HTML preservation rules passed in
- * {@link GukhanmunOptions.html}.
- *
- * These are additive: a scope is preserved when *any* rule matches.  They
- * correspond to the CLI flags `--html-preserve-class` and
- * `--html-preserve-attr`, and to the Rust `Builder::html_preserve_when`
- * predicate.
- */
-interface HtmlOptions {
-  /**
-   * 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.
-   */
-  readonly preserveClasses?: readonly 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.
-   */
-  readonly preserveAttributes?: readonly (string | {
-    readonly name: string;
-    readonly value?: string;
-  })[];
-}
-/**
- * Per-hanja rendering directives that override the dictionary's own marks.
- *
- * Each list contains hanja forms (exact string matches, e.g. `"漢字"`).
- * JavaScript bindings expose only the literal-set form; glob and predicate
- * variants are available in the Rust API only.
- *
- * Corresponds to Rust `UserDirectives` with `DirectiveAction::RequireHanja`,
- * `DirectiveAction::RequireHangul`, and `DirectiveAction::SkipAnnotation`.
- */
-interface Directives {
-  /**
-   * Hanja forms that must always be shown with their original hanja
-   * alongside the hangul reading, as if `requireHanja` were set in the
-   * dictionary.
-   */
-  readonly requireHanja?: readonly string[];
-  /**
-   * Hanja forms that must always be shown with a hangul gloss alongside the
-   * original hanja (relevant for `rendering: "original"`).
-   */
-  readonly requireHangul?: 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`).
-   */
-  readonly skipAnnotation?: readonly string[];
-}
-/** Policy for ordinary spaces following an eligible stop. */
-type SpaceAfter = "preserve" | "remove" | "single";
-/** Built-in output style; input recognition is independent of this choice. */
-type PunctuationPreset = "preserve" | "modern" | "traditional" | "traditional-vertical";
-/** A single Unicode scalar and its following U+0020 policy. */
-interface StopStyle {
-  /** One Unicode scalar, validated by the shared profile resolver. */
-  readonly mark: string;
-  /** Policy applied only to U+0020 following this stop. */
-  readonly after: SpaceAfter;
-}
-/** Opening and closing Unicode punctuation scalars. */
-interface DelimiterStyle {
-  /** Opening scalar with Unicode category Ps or Pi. */
-  readonly open: string;
-  /** Closing scalar with Unicode category Pe or Pf. */
-  readonly close: string;
-}
-/** Partial overrides; omitted roles inherit, null preserves the role. */
-interface CustomPunctuationProfile {
-  /** Inherited preset, defaulting to preserve. */
-  readonly base?: PunctuationPreset;
-  /** Comma style; omitted inherits, null preserves. */
-  readonly comma?: StopStyle | null;
-  /** Period style; omitted inherits, null preserves. */
-  readonly period?: StopStyle | null;
-  /** Single delimiters; omitted inherits, null preserves. */
-  readonly single?: DelimiterStyle | null;
-  /** Double delimiters; omitted inherits, null preserves. */
-  readonly double?: DelimiterStyle | null;
-}
-/** Fully resolved styles, copied and deeply frozen by each binding. */
-interface ResolvedPunctuationProfile {
-  /** Comma style, or null for preservation. */
-  readonly comma: StopStyle | null;
-  /** Period style, or null for preservation. */
-  readonly period: StopStyle | null;
-  /** Single delimiters, or null for preservation. */
-  readonly single: DelimiterStyle | null;
-  /** Double delimiters, or null for preservation. */
-  readonly double: DelimiterStyle | null;
-}
-/**
- * Full set of options passed to {@link GukhanmunFactory.load} (or the
- * top-level `load` function) to configure a {@link Gukhanmun} instance.
- *
- * All fields are optional.  When a `preset` is specified it supplies
- * defaults; individual fields override those defaults.  When no preset is
- * given, `"ko-kr"` is implicitly used.
- */
-interface GukhanmunOptions {
-  /** Independent output punctuation policy. Defaults to preserve. */
-  readonly punctuation?: PunctuationPreset | CustomPunctuationProfile;
-  /**
-   * Named configuration preset.  Defaults to `"ko-kr"`.
-   *
-   * @see {@link Preset}
-   */
-  readonly preset?: Preset;
-  /**
-   * How annotations are rendered into output text or markup.  Defaults to
-   * `"hangul-only"`.
-   *
-   * @see {@link RenderMode}
-   */
-  readonly rendering?: RenderMode;
-  /**
-   * How glosses are rendered when `rendering` is `"original"`.  Ignored for
-   * all other render modes.  Defaults to `"parens"`.
-   *
-   * @see {@link OriginalGloss}
-   */
-  readonly originalGloss?: OriginalGloss;
-  /** The hanja variant set. Defaults to `"as-dictionary"`. */
-  readonly hanjaVariantSet?: HanjaVariantSet;
-  /**
-   * Hanja-span segmentation algorithm.  Defaults to `"lattice"`.
-   *
-   * @see {@link Segmentation}
-   */
-  readonly segmentation?: Segmentation;
-  /**
-   * How runs of hanja numerals are converted.  Defaults to
-   * `"hangul-phonetic"`.
-   *
-   * @see {@link NumeralStrategy}
-   */
-  readonly numerals?: NumeralStrategy;
-  /**
-   * 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.
-   */
-  readonly initialSoundLaw?: boolean;
-  /**
-   * 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 {@link ContextWindow}
-   */
-  readonly homophoneWindow?: ContextWindow;
-  /**
-   * Strategy that decides which readings count as homophones needing a hanja
-   * gloss.  Defaults to `"context-local"`, which glosses a reading only when a
-   * different-meaning homophone appears within {@link homophoneWindow}.  Use
-   * `"dictionary-wide"` to also gloss readings shared by other dictionary
-   * entries.
-   *
-   * @see {@link HomophoneDetection}
-   */
-  readonly homophoneDetection?: HomophoneDetection;
-  /**
-   * Context window for first-occurrence filtering.  The
-   * `FirstOccurrenceFilter` middleware clears `requireHanja` /
-   * `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 {@link ContextWindow}
-   */
-  readonly firstOccurrenceWindow?: ContextWindow;
-  /**
-   * 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.
-   */
-  readonly collapseRedundantParens?: boolean;
-  /**
-   * Error recovery policy for HTML scanning.  Defaults to `"strict"`.
-   * Ignored for non-HTML input formats.
-   *
-   * @see {@link Recovery}
-   */
-  readonly recovery?: Recovery;
-  /**
-   * 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. For NIKL loanword examples, load
-   * `@gukhanmun/loanwords-fst` or `@gukhanmun/loanwords-cdb`. Put user
-   * dictionaries first, then loanwords, then the preset dictionaries.
-   *
-   * Entries computed at runtime need no package and no `gukhanmun-mkdict` run:
-   * pass {@link MapDictionarySource} (`{ entries: [...] }`) at the position
-   * where those overrides should take precedence.
-   *
-   * @see {@link DictionarySource}
-   */
-  readonly dictionaries?: readonly DictionarySource[];
-  /**
-   * Per-hanja rendering directives that override dictionary marks.
-   *
-   * @see {@link Directives}
-   */
-  readonly directives?: Directives;
-  /**
-   * HTML-specific preservation rules.  Ignored for non-HTML input formats.
-   *
-   * @see {@link HtmlOptions}
-   */
-  readonly html?: HtmlOptions;
-}
-/**
- * Input / output format for {@link Gukhanmun.convert} and
- * {@link Gukhanmun.stream}.
- *
- * - `"text"` — Plain text (default).  No markup interpretation; ruby
- *   rendering falls back to parentheses.
- * - `"html"` — HTML fragment.  The scanner is fragment-oriented and recovers
- *   from minor malformations.
- * - `"markdown"` — CommonMark Markdown (GFM disabled by default).
- * - `{ format: "markdown"; gfm?: boolean }` — Markdown with optional GFM
- *   extensions.  Set `gfm: true` to enable GitHub Flavored Markdown tables,
- *   strikethrough, and task lists.
- *
- * The object form `{ format: "markdown" }` is equivalent to the string
- * `"markdown"`.
- */
-type Format = "text" | "html" | "markdown" | {
-  readonly format: "markdown";
-  readonly gfm?: boolean;
-};
-/**
- * A configured hanja-to-hangul converter.  Created by calling
- * {@link GukhanmunFactory.load} (or the top-level `load` function).
- *
- * The instance is immutable after creation; call `load` again to obtain a
- * converter with different options.
- */
-interface Gukhanmun {
-  /**
-   * Converts `source` to hangul in one shot.  Buffers the entire input
-   * before returning.
-   *
-   * @param source - The text to convert.
-   * @param format - Input / output format.  Defaults to `"text"`.
-   * @returns The converted text.
-   * @throws {@link GukhanmunError} on conversion failure.
-   */
-  convert(source: string, format?: Format): 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.
-   *
-   * @param format - Input / output format.  Defaults to `"text"`.
-   * @returns A platform `TransformStream<string, string>`.
-   * @throws {@link GukhanmunError} on initialisation failure (not on chunk
-   *   errors; those are signalled via the stream's error channel).
-   */
-  stream(format?: Format): TransformStream<string, string>;
-  /**
-   * 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.
-   */
-  readonly options: Readonly<Required<Omit<GukhanmunOptions, "dictionaries" | "directives" | "html" | "originalGloss" | "punctuation">> & {
-    readonly punctuation: ResolvedPunctuationProfile;
-  }>;
-}
-/**
- * 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("漢字를 한글로"));
- * ```
- */
-interface GukhanmunFactory {
-  /**
-   * Loads and initialises a {@link Gukhanmun} 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.
-   *
-   * @param options - Conversion options.  All fields are optional; unset
-   *   fields inherit defaults from the selected `preset` (or `"ko-kr"` when
-   *   no preset is given).
-   * @returns A ready-to-use {@link Gukhanmun} instance.
-   * @throws {@link GukhanmunError} when an option value is unrecognised
-   *   (`code: "invalid-input"`) or a dictionary fails to load
-   *   (`code: "dictionary-load"`).
-   */
-  load(options?: GukhanmunOptions): Promise<Gukhanmun>;
-}
-/**
- * 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.
- */
-
-/**
- * Discriminant code carried by every {@link GukhanmunError}.
- *
- * - `"dictionary-load"` — A dictionary file could not be opened, read, or
- *   decoded.
- * - `"segmentation"` — The lattice segmenter encountered an internal
- *   inconsistency.
- * - `"invalid-reading"` — A dictionary entry's hangul reading is not valid
- *   hangul.
- * - `"html-scan"` — The HTML scanner encountered an unrecoverable error.
- * - `"html-malformed-attr"` — An HTML attribute string could not be parsed.
- * - `"markdown"` — The Markdown adapter encountered a parsing error.
- * - `"unsupported-content-type"` — An unrecognised format string was passed
- *   to `convert` or `stream`.
- * - `"invalid-input"` — An option value is not in the expected set (e.g. an
- *   unrecognised preset or render mode string).
- * - `"io"` — An I/O error occurred (file read, network, …).
- * - `"internal"` — An internal invariant was violated; this is a bug.
- * - `"other"` — Any other error not covered by the above codes.
- */
-type ErrorCode = "dictionary-load" | "segmentation" | "invalid-reading" | "html-scan" | "html-malformed-attr" | "markdown" | "unsupported-content-type" | "invalid-input" | "io" | "internal" | "other";
-/**
- * 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.
- */
-//#endregion
-//#region index.d.ts
+import { ContextWindow, CustomPunctuationProfile, DelimiterStyle, DictionaryEntry, DictionarySource, Directives, ErrorCode, ErrorCode as ErrorCode$1, FileDictionarySource, Format, Gukhanmun, Gukhanmun as Gukhanmun$1, GukhanmunFactory, GukhanmunOptions, GukhanmunOptions as GukhanmunOptions$1, HanjaVariantSet, HomophoneDetection, HtmlOptions, MapDictionarySource, NumeralStrategy, OriginalGloss, Preset, PunctuationPreset, Recovery, RenderMode, ResolvedPunctuationProfile, Segmentation, SourcePolicy, SourceRole, SpaceAfter, StopStyle } from "@gukhanmun/types";
 /**
  * Error thrown by `{@link load}`, `{@link Gukhanmun.convert}`, and
  * `{@link Gukhanmun.stream}` when the Rust engine reports a failure.
@@ -690,20 +7,20 @@ type ErrorCode = "dictionary-load" | "segmentation" | "invalid-reading" | "html-
  * materialised at the FFI boundary so callers do not need additional round
  * trips.
  */
-declare class GukhanmunError extends Error {
+export declare class GukhanmunError extends Error {
   /**
    * Machine-readable error code.
    *
    * @see {@link ErrorCode}
    */
-  readonly code: ErrorCode;
+  readonly code: ErrorCode$1;
   /**
    * 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.
    */
   readonly chain: readonly {
-    readonly code: ErrorCode;
+    readonly code: ErrorCode$1;
     readonly message: string;
   }[];
   /**
@@ -713,8 +30,8 @@ declare class GukhanmunError extends Error {
    * @param message - Human-readable description.
    * @param chain - Optional causal chain.
    */
-  constructor(code: ErrorCode, message: string, chain?: readonly {
-    code: ErrorCode;
+  constructor(code: ErrorCode$1, message: string, chain?: readonly {
+    code: ErrorCode$1;
     message: string;
   }[]);
 }
@@ -736,6 +53,5 @@ declare class GukhanmunError extends Error {
  * @returns A `{@link Gukhanmun}` instance.
  * @throws {@link GukhanmunError} on invalid options or dictionary load failure.
  */
-declare function load(options?: GukhanmunOptions): Promise<Gukhanmun>;
-//#endregion
-export { type ContextWindow, type CustomPunctuationProfile, type DelimiterStyle, type DictionaryEntry, type DictionarySource, type Directives, type ErrorCode, type FileDictionarySource, type Format, type Gukhanmun, GukhanmunError, type GukhanmunFactory, type GukhanmunOptions, type HanjaVariantSet, type HomophoneDetection, type HtmlOptions, type MapDictionarySource, type NumeralStrategy, type OriginalGloss, type Preset, type PunctuationPreset, type Recovery, type RenderMode, type ResolvedPunctuationProfile, type Segmentation, type SpaceAfter, type StopStyle, load };
+export declare function load(options?: GukhanmunOptions$1): Promise<Gukhanmun$1>;
+export type { ContextWindow, CustomPunctuationProfile, DelimiterStyle, DictionaryEntry, DictionarySource, Directives, ErrorCode, FileDictionarySource, Format, Gukhanmun, GukhanmunFactory, GukhanmunOptions, HanjaVariantSet, HomophoneDetection, HtmlOptions, MapDictionarySource, NumeralStrategy, OriginalGloss, Preset, PunctuationPreset, Recovery, RenderMode, ResolvedPunctuationProfile, Segmentation, SourcePolicy, SourceRole, SpaceAfter, StopStyle };

package/dist/index.js

@@ -1,4 +1,4 @@
-//#region index.ts
+// index.ts
 function isNodeLike() {
 	return typeof globalThis.process?.versions?.node === "string";
 }
@@ -121,18 +121,25 @@ function encodeEntries(entries) {
 }
 async function resolveDictionary(source) {
 	if (typeof source !== "object" || source === null) throw new GukhanmunError("invalid-input", "Each dictionary must be an object");
+	const role = source.role;
+	if (role !== void 0 && role !== "override" && role !== "reference" && role !== "loanword") throw new GukhanmunError("invalid-input", `Unknown dictionary source role: ${String(role)}`);
 	if ("entries" in source) {
 		if ("format" in source || "data" in source) throw new GukhanmunError("invalid-input", "A dictionary must not combine 'entries' with 'format' or 'data'");
-		return { entriesJson: encodeEntries(source.entries) };
+		return {
+			entriesJson: encodeEntries(source.entries),
+			role
+		};
 	}
 	if (source.data instanceof ArrayBuffer) return {
 		format: source.format,
+		role,
 		bytes: new Uint8Array(source.data)
 	};
 	if (ArrayBuffer.isView(source.data)) {
 		const view = source.data;
 		return {
 			format: source.format,
+			role,
 			bytes: new Uint8Array(view.buffer, view.byteOffset, view.byteLength)
 		};
 	}
@@ -160,6 +167,7 @@ async function resolveDictionary(source) {
 		}
 		return {
 			format: source.format,
+			role,
 			bytes: new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength)
 		};
 	}
@@ -172,6 +180,7 @@ async function resolveDictionary(source) {
 	if (!response.ok) throw new GukhanmunError("dictionary-load", `Failed to fetch dictionary: HTTP ${response.status}`);
 	return {
 		format: source.format,
+		role,
 		bytes: new Uint8Array(await response.arrayBuffer())
 	};
 }
@@ -257,6 +266,8 @@ function resolveOptions(opts = {}) {
 		rendering: opts.rendering ?? "hangul-only",
 		hanjaVariantSet: opts.hanjaVariantSet ?? "as-dictionary",
 		segmentation: opts.segmentation ?? "lattice",
+		sourcePolicy: opts.sourcePolicy ?? "reference-authorized",
+		referenceOnly: opts.referenceOnly ?? false,
 		numerals: opts.numerals ?? "hangul-phonetic",
 		initialSoundLaw: opts.initialSoundLaw ?? (koKp ? false : true),
 		homophoneWindow: opts.homophoneWindow ?? (koKp ? "off" : "per-block"),
@@ -311,6 +322,8 @@ function buildRawOptions(opts, resolved) {
 		rendering: resolved.rendering,
 		hanjaVariantSet: resolved.hanjaVariantSet,
 		segmentation: resolved.segmentation,
+		sourcePolicy: resolved.sourcePolicy,
+		referenceOnly: resolved.referenceOnly,
 		numerals: resolved.numerals,
 		initialSoundLaw: resolved.initialSoundLaw,
 		homophoneWindow: resolved.homophoneWindow,
@@ -345,5 +358,4 @@ function punctuationJson(value) {
 		throw new GukhanmunError("invalid-input", error instanceof Error ? error.message : String(error));
 	}
 }
-//#endregion
 export { GukhanmunError, load };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gukhanmun/wasm",
-  "version": "0.4.0-dev.236",
+  "version": "0.4.0-dev.248",
   "description": "WebAssembly implementation of the Gukhanmun hanja-to-hangul converter.",
   "type": "module",
   "exports": {
@@ -54,7 +54,7 @@
     "@gukhanmun/types": "*"
   },
   "devDependencies": {
-    "@gukhanmun/types": "0.4.0-dev.236+75afc34"
+    "@gukhanmun/types": "0.4.0-dev.248+36997e7"
   },
   "scripts": {
     "build": "tsdown && node -e \"const fs=require('node:fs'),p=require('node:path');fs.cpSync('wasm','dist/wasm',{recursive:true,force:true,filter:(s)=>p.basename(s)!=='.gitignore'})\""