@kensio/pinyinjs 1.2.2 → 1.4.0

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/script/conversion.d.ts

@@ -0,0 +1,102 @@
+import type { Syllable } from "../syllable/syllable.js";
+/**
+ * How one character converts into the other script.
+ *
+ * A default, plus the readings that take a different form. The readings are
+ * what make this more than a lookup table: 发 is 發 by default and 髮 when read
+ * `fà`, and no table without the reading can tell 头发 from 出发.
+ */
+export interface CharacterConversion {
+    /** The form taken when no reading is known, or none of them applies. */
+    readonly to: string;
+    /** Forms taken at particular readings, keyed by numbered pinyin. */
+    readonly byReading?: ReadonlyMap<string, string>;
+    /**
+     * Other forms this character is commonly written as, with no reading to tell
+     * them apart.
+     *
+     * These never change what a conversion *does* — the default or a reading
+     * decides that — but they are what makes it honest. 面 and 麵 read alike, so
+     * only a word settles which is meant; without these the conversion would
+     * report 面粉 as locked while 下面 came out differently, claiming certainty it
+     * does not have. Rare variants are excluded, or every 和 would be doubtful on
+     * account of 咊.
+     */
+    readonly also?: readonly string[];
+}
+/**
+ * Everything needed to convert between the scripts, in either direction.
+ *
+ * Words come before characters. A word the table names is converted as a whole,
+ * because the evidence for a whole word is direct — some source wrote it that
+ * way — whereas a character conversion is an inference from how that character
+ * behaved elsewhere. Only words the character tables get *wrong* are stored, so
+ * the word tables are exception lists rather than dictionaries.
+ */
+export interface ScriptTables {
+    readonly toTraditional: ReadonlyMap<string, CharacterConversion>;
+    readonly toSimplified: ReadonlyMap<string, CharacterConversion>;
+    /** 简体 words whose 繁體 form the characters would get wrong. */
+    readonly traditionalWords: ReadonlyMap<string, string>;
+    /** 繁體 words whose 简体 form the characters would get wrong. */
+    readonly simplifiedWords: ReadonlyMap<string, string>;
+    /** Characters written only in 简体, for `detectScript`. */
+    readonly hansOnly: ReadonlySet<string>;
+    /** Characters written only in 繁體, for `detectScript`. */
+    readonly hantOnly: ReadonlySet<string>;
+}
+/**
+ * The key a reading is stored under: numbered pinyin, or the empty string.
+ *
+ * 儿化 is dropped because the r suffix never bears on which variant is meant,
+ * and a toneless syllable keys separately from a toned one rather than matching
+ * it, since a source that wrote no tone is not evidence about a particular one.
+ */
+export declare function conversionKey(syllable: Syllable | undefined): string;
+/**
+ * The form a character takes, given the syllable it is read as.
+ */
+export declare function convertCharacter(table: ReadonlyMap<string, CharacterConversion>, character: string, syllable: Syllable | undefined): string;
+/**
+ * Whether a character's conversion depends on how it is read.
+ *
+ * True where the table holds a reading that disagrees with the default, which
+ * is exactly where a conversion made without a reading is a guess.
+ */
+export declare function isAmbiguousCharacter(table: ReadonlyMap<string, CharacterConversion>, character: string): boolean;
+/**
+ * Every form a character is known to take, likeliest first.
+ */
+export declare function formsOf(conversion: CharacterConversion | undefined): readonly string[];
+/**
+ * Convert a word character by character, using the readings where it has them.
+ *
+ * Readings line up with characters by position. A position with no reading
+ * behind it takes the default, which is the right answer for the overwhelming
+ * majority and a flagged guess for the rest.
+ */
+export declare function convertCharacters(table: ReadonlyMap<string, CharacterConversion>, word: string, readings?: readonly (Syllable | undefined)[]): string;
+/**
+ * Write the tables as the artifact text.
+ *
+ * One line per mapping, tagged by which table it belongs to, so the whole of
+ * script conversion is a single file to fetch and a single scan to read. The
+ * format is the same shape as the dictionary's: separators rather than syntax,
+ * so that reading it back is a split rather than a parse.
+ */
+export declare function writeScriptTables(tables: ScriptTables): string;
+/**
+ * Read the tables back from the artifact text.
+ *
+ * Unknown tags are skipped rather than rejected, so that a future table can be
+ * added without an older reader refusing the file outright.
+ */
+export declare function readScriptTables(text: string): ScriptTables;
+/**
+ * Parse a stored reading key back into a syllable.
+ *
+ * Used by the round-trip check rather than by conversion, which keys on the
+ * written form directly and never needs the syllable back.
+ */
+export declare function readConversionKey(key: string): Syllable | undefined;
+//# sourceMappingURL=conversion.d.ts.map

package/dist/script/conversion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversion.d.ts","sourceRoot":"","sources":["../../src/script/conversion.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAIxD;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,QAAQ,CAAC,SAAS,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjD;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IACjE,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IAChE,6DAA6D;IAC7D,QAAQ,CAAC,gBAAgB,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvD,6DAA6D;IAC7D,QAAQ,CAAC,eAAe,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtD,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACvC,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACxC;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,SAAS,GAAG,MAAM,CAMpE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,mBAAmB,CAAC,EAC/C,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,QAAQ,GAAG,SAAS,GAC7B,MAAM,CAOR;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,mBAAmB,CAAC,EAC/C,SAAS,EAAE,MAAM,GAChB,OAAO,CAQT;AAED;;GAEG;AACH,wBAAgB,OAAO,CACrB,UAAU,EAAE,mBAAmB,GAAG,SAAS,GAC1C,SAAS,MAAM,EAAE,CAWnB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,mBAAmB,CAAC,EAC/C,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,SAAS,CAAC,QAAQ,GAAG,SAAS,CAAC,EAAO,GAC/C,MAAM,CAMR;AA4CD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAkB9D;AAyBD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CA0C3D;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAEnE"}

package/dist/script/conversion.js

@@ -0,0 +1,194 @@
+import { readSyllable, writeSyllable } from "../syllable/syllable.js";
+import { toCharacters } from "./characters.js";
+/**
+ * The key a reading is stored under: numbered pinyin, or the empty string.
+ *
+ * 儿化 is dropped because the r suffix never bears on which variant is meant,
+ * and a toneless syllable keys separately from a toned one rather than matching
+ * it, since a source that wrote no tone is not evidence about a particular one.
+ */
+export function conversionKey(syllable) {
+    if (syllable === undefined) {
+        return "";
+    }
+    // 儿化 is dropped by writing the syllable without it.
+    return writeSyllable({ ...syllable, erhua: false }, "numbers");
+}
+/**
+ * The form a character takes, given the syllable it is read as.
+ */
+export function convertCharacter(table, character, syllable) {
+    const conversion = table.get(character);
+    if (conversion === undefined) {
+        return character;
+    }
+    const key = conversionKey(syllable);
+    return conversion.byReading?.get(key) ?? conversion.to;
+}
+/**
+ * Whether a character's conversion depends on how it is read.
+ *
+ * True where the table holds a reading that disagrees with the default, which
+ * is exactly where a conversion made without a reading is a guess.
+ */
+export function isAmbiguousCharacter(table, character) {
+    const conversion = table.get(character);
+    if (conversion === undefined) {
+        return false;
+    }
+    return ((conversion.byReading?.size ?? 0) > 0 || (conversion.also?.length ?? 0) > 0);
+}
+/**
+ * Every form a character is known to take, likeliest first.
+ */
+export function formsOf(conversion) {
+    if (conversion === undefined) {
+        return [];
+    }
+    return [
+        ...new Set([
+            conversion.to,
+            ...(conversion.byReading?.values() ?? []),
+            ...(conversion.also ?? []),
+        ]),
+    ];
+}
+/**
+ * Convert a word character by character, using the readings where it has them.
+ *
+ * Readings line up with characters by position. A position with no reading
+ * behind it takes the default, which is the right answer for the overwhelming
+ * majority and a flagged guess for the rest.
+ */
+export function convertCharacters(table, word, readings = []) {
+    let converted = "";
+    for (const [at, character] of toCharacters(word).entries()) {
+        converted += convertCharacter(table, character, readings[at]);
+    }
+    return converted;
+}
+const COLUMN = "\t";
+const LINE = "\n";
+const READING = ",";
+const READING_FORM = "=";
+/**
+ * Line tags, one per table, so that all six ship as one fetchable file.
+ */
+const TAGS = {
+    toTraditional: "t",
+    toSimplified: "s",
+    traditionalWord: "w",
+    simplifiedWord: "x",
+    hansOnly: "h",
+    hantOnly: "H",
+};
+/**
+ * Write one character table's lines.
+ */
+function writeCharacterTable(tag, table) {
+    return [...table].map(([character, conversion]) => {
+        const readings = [...(conversion.byReading ?? [])]
+            .map(([key, form]) => `${key}${READING_FORM}${form}`)
+            .join(READING);
+        const also = (conversion.also ?? []).join("");
+        const columns = [tag, character, conversion.to, readings, also];
+        // Trailing empty columns say nothing and are dropped, which is most lines:
+        // the common case is a character with one form and no reading to condition.
+        while (columns.at(-1) === "") {
+            columns.pop();
+        }
+        return columns.join(COLUMN);
+    });
+}
+/**
+ * Write the tables as the artifact text.
+ *
+ * One line per mapping, tagged by which table it belongs to, so the whole of
+ * script conversion is a single file to fetch and a single scan to read. The
+ * format is the same shape as the dictionary's: separators rather than syntax,
+ * so that reading it back is a split rather than a parse.
+ */
+export function writeScriptTables(tables) {
+    return [
+        ...writeCharacterTable(TAGS.toTraditional, tables.toTraditional),
+        ...writeCharacterTable(TAGS.toSimplified, tables.toSimplified),
+        ...[...tables.traditionalWords].map(([hans, hant]) => [TAGS.traditionalWord, hans, hant].join(COLUMN)),
+        ...[...tables.simplifiedWords].map(([hant, hans]) => [TAGS.simplifiedWord, hant, hans].join(COLUMN)),
+        ...[...tables.hansOnly].map((character) => [TAGS.hansOnly, character].join(COLUMN)),
+        ...[...tables.hantOnly].map((character) => [TAGS.hantOnly, character].join(COLUMN)),
+        "",
+    ].join(LINE);
+}
+/**
+ * Read one character table line into its conversion.
+ */
+function readConversion(to, readings, also) {
+    const pairs = readings === "" ? [] : readings.split(READING);
+    const byReading = new Map();
+    for (const pair of pairs) {
+        const [key = "", form = ""] = pair.split(READING_FORM);
+        if (form !== "") {
+            byReading.set(key, form);
+        }
+    }
+    return {
+        to,
+        ...(byReading.size > 0 && { byReading }),
+        ...(also !== "" && { also: toCharacters(also) }),
+    };
+}
+/**
+ * Read the tables back from the artifact text.
+ *
+ * Unknown tags are skipped rather than rejected, so that a future table can be
+ * added without an older reader refusing the file outright.
+ */
+export function readScriptTables(text) {
+    const toTraditional = new Map();
+    const toSimplified = new Map();
+    const traditionalWords = new Map();
+    const simplifiedWords = new Map();
+    const hansOnly = new Set();
+    const hantOnly = new Set();
+    const characterTables = new Map([
+        [TAGS.toTraditional, toTraditional],
+        [TAGS.toSimplified, toSimplified],
+    ]);
+    const wordTables = new Map([
+        [TAGS.traditionalWord, traditionalWords],
+        [TAGS.simplifiedWord, simplifiedWords],
+    ]);
+    const characterSets = new Map([
+        [TAGS.hansOnly, hansOnly],
+        [TAGS.hantOnly, hantOnly],
+    ]);
+    for (const line of text.split(LINE)) {
+        const [tag = "", from = "", to = "", readings = "", also = ""] = line.split(COLUMN);
+        if (from === "") {
+            continue;
+        }
+        // Dispatching on a map rather than a switch keeps an unknown tag a no-op,
+        // so a file written by a later version reads as much as this one knows.
+        characterTables.get(tag)?.set(from, readConversion(to, readings, also));
+        wordTables.get(tag)?.set(from, to);
+        characterSets.get(tag)?.add(from);
+    }
+    return {
+        toTraditional,
+        toSimplified,
+        traditionalWords,
+        simplifiedWords,
+        hansOnly,
+        hantOnly,
+    };
+}
+/**
+ * Parse a stored reading key back into a syllable.
+ *
+ * Used by the round-trip check rather than by conversion, which keys on the
+ * written form directly and never needs the syllable back.
+ */
+export function readConversionKey(key) {
+    return key === "" ? undefined : readSyllable(key);
+}
+//# sourceMappingURL=conversion.js.map

package/dist/script/conversion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversion.js","sourceRoot":"","sources":["../../src/script/conversion.ts"],"names":[],"mappings":"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"}

package/dist/script/glyphs.d.ts

@@ -0,0 +1,95 @@
+import type { Syllable } from "../syllable/syllable.js";
+/**
+ * The regional 繁體 orthographies this package writes.
+ *
+ * A third axis, independent of the script and locale axes in `script.ts`:
+ * Taiwan and Hong Kong write the same characters with the same readings, and
+ * disagree about the standard form of 58 of them. See SCRIPTS-AND-LOCALES.md.
+ */
+export declare const REGIONS: readonly ["TW", "HK"];
+/**
+ * A regional 繁體 orthography: `TW` for 教育部標準字體 or `HK` for 常用字字形表.
+ *
+ * Only meaningful under `Hant`. Singapore and Malaysia differ from the PRC
+ * lexically rather than orthographically, so there is no second 简体 standard.
+ */
+export type Region = (typeof REGIONS)[number];
+/**
+ * The 繁體 orthography written when the caller does not name one.
+ *
+ * There is no region-free 繁體 to fall back on: converting character by
+ * character from OpenCC's baseline yields 爲, 衆, 峯, 羣, 裏, 麪, which are the
+ * Hong Kong forms. Declining to choose would mean choosing Hong Kong silently,
+ * so a region is always applied and always named.
+ *
+ * Taiwan wins it on population, and more to the point because it is the one
+ * polity where 繁體 orthography and Mandarin as the spoken standard coincide —
+ * which is the intersection a pinyin package serves.
+ */
+export declare const DEFAULT_REGION = "TW";
+/**
+ * Variant 繁體 forms mapped to the canonical form, as a table.
+ *
+ * Exported so the data pipeline can recompute it from OpenCC and fail the build
+ * if the two have drifted — these tables are code rather than an artifact, so
+ * nothing else would notice an upstream release that moved a character.
+ */
+export declare const CANONICAL_FORMS: ReadonlyMap<string, string>;
+/**
+ * Canonical 繁體 forms mapped to Hong Kong's, as a table. Verified like
+ * {@link CANONICAL_FORMS}.
+ */
+export declare const HONG_KONG_FORMS: ReadonlyMap<string, string>;
+/**
+ * Whether a character's regional form depends on how it is read.
+ *
+ * Exposed so that a conversion can report the choice as uncertain when it had
+ * no reading to go on, rather than presenting a default as though it were
+ * settled.
+ */
+export declare function isReadingSensitive(character: string): boolean;
+/**
+ * Normalise one 繁體 character to the canonical form the dictionary stores.
+ *
+ * Characters no table knows are returned unchanged, which is the right answer
+ * for nearly all of them: the two standards agree about everything except the
+ * 58 characters {@link HONG_KONG_FORMS} lists.
+ */
+export declare function toCanonicalGlyph(character: string): string;
+/**
+ * Normalise a whole 繁體 text to the canonical forms the dictionary stores.
+ *
+ * Safe to run over 简体 or mixed text, but only because the table is built to
+ * make it so: every variant that is also a current 简体 character is excluded,
+ * since many Hong Kong forms and mainland simplified forms are the same
+ * character. See {@link CANONICAL_FORMS}.
+ *
+ * Returns the original string when nothing needs normalising, which is nearly
+ * always. This sits on the dictionary lookup path, where it is called once per
+ * candidate word at every position of a run, so the common case has to cost a
+ * scan rather than an allocation.
+ *
+ * The mapping is one character to one character, which is what makes it safe
+ * here: normalising a prefix gives the same answer as taking the prefix of the
+ * normalised text, so a lattice scan that prunes on prefixes cannot disagree
+ * with the lookup that follows it.
+ */
+export declare function toCanonicalGlyphs(text: string): string;
+/**
+ * Write one canonical character in a region's orthography.
+ *
+ * The syllable is used only where the character is one the two standards split
+ * on a reading; everywhere else it is ignored, because a glyph choice never
+ * changes how a character is read.
+ */
+export declare function toRegionalGlyph(character: string, region: Region, syllable?: Syllable): string;
+/**
+ * Write a whole canonical text in a region's orthography.
+ *
+ * Readings are matched to characters by position, so a caller with a decoded
+ * reading can pass it and a caller without one can leave it out. A position
+ * with no syllable behind it falls back to the region's default form, which is
+ * what {@link isReadingSensitive} lets the caller flag.
+ */
+export declare function toRegionalGlyphs(text: string, region: Region, readings?: readonly (Syllable | undefined)[]): string;
+//# sourceMappingURL=glyphs.d.ts.map

package/dist/script/glyphs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glyphs.d.ts","sourceRoot":"","sources":["../../src/script/glyphs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAGxD;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,YAAI,IAAI,EAAE,IAAI,CAAU,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,OAAwB,CAAC;AAiFpD;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,6BAA6B,CAAC;AAE1D;;;GAGG;AACH,eAAO,MAAM,eAAe,6BAA6B,CAAC;AAsC1D;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAE7D;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE1D;AAcD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAStD;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,QAAQ,GAClB,MAAM,CAUR;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,QAAQ,GAAE,SAAS,CAAC,QAAQ,GAAG,SAAS,CAAC,EAAO,GAC/C,MAAM,CASR"}

package/dist/script/glyphs.js

@@ -0,0 +1,236 @@
+import { toCharacters } from "./characters.js";
+/**
+ * The regional 繁體 orthographies this package writes.
+ *
+ * A third axis, independent of the script and locale axes in `script.ts`:
+ * Taiwan and Hong Kong write the same characters with the same readings, and
+ * disagree about the standard form of 58 of them. See SCRIPTS-AND-LOCALES.md.
+ */
+export const REGIONS = ["TW", "HK"];
+/**
+ * The 繁體 orthography written when the caller does not name one.
+ *
+ * There is no region-free 繁體 to fall back on: converting character by
+ * character from OpenCC's baseline yields 爲, 衆, 峯, 羣, 裏, 麪, which are the
+ * Hong Kong forms. Declining to choose would mean choosing Hong Kong silently,
+ * so a region is always applied and always named.
+ *
+ * Taiwan wins it on population, and more to the point because it is the one
+ * polity where 繁體 orthography and Mandarin as the spoken standard coincide —
+ * which is the intersection a pinyin package serves.
+ */
+export const DEFAULT_REGION = "TW";
+/**
+ * Read a table written as a flat run of `from`/`to` character pairs.
+ *
+ * Pairs rather than a `Record` so that the tables stay legible as data and cost
+ * one string each: these are code rather than an artifact to fetch, for the
+ * same reason the transcription tables are — 133 mappings do not justify a
+ * download, and they must be available before any dictionary has loaded.
+ */
+function readPairs(pairs) {
+    const characters = toCharacters(pairs);
+    const table = new Map();
+    for (let at = 0; at + 1 < characters.length; at += 2) {
+        /* c8 ignore next 2 -- both indices are in range while at + 1 < length */
+        table.set(characters[at] ?? "", characters[at + 1] ?? "");
+    }
+    return table;
+}
+/**
+ * Variant 繁體 forms, mapped to the canonical form this package stores.
+ *
+ * The canonical form is Taiwan's, because that is what the dictionary's 繁體
+ * keys already are: measured on CC-CEDICT's traditional column, 裡 outnumbers
+ * 裏 116 to 8, 群 outnumbers 羣 175 to 1 and 麵 outnumbers 麪 138 to 1. So
+ * normalisation means mapping toward `TW`, and only Hong Kong output needs a
+ * pass away from what is stored.
+ *
+ * This is what lets Hong Kong text find dictionary keys. 羣眾 and 麪包 are not
+ * keys and never will be, so they would otherwise fall back to converting
+ * character by character — the same loss 臺灣 had before `hantVariants`.
+ * Measured: of the 9,833 dictionary keys with a distinct Hong Kong spelling,
+ * 2,358 are already keys and normalisation reaches a further 5,439. The 2,036
+ * still out of reach are mostly 臺 written as 台, which the exclusions below
+ * deliberately decline to reverse.
+ *
+ * Nineteen mappings OpenCC makes are deliberately **excluded**, because the
+ * variant is itself current in the corpus the dictionary is built from and
+ * rewriting it would corrupt legitimate text. Two different reasons, and the
+ * second is the one that is easy to miss:
+ *
+ * 1. The variant is a live 繁體 spelling. 台 is the clearest — OpenCC maps it to
+ *    臺, but CC-CEDICT writes 台 164 times against 臺's 208, so it is a spelling
+ *    someone chose rather than a Hong Kong-ism. Also 污, 濕, 睾, 祕, 泄.
+ * 2. **The variant is a current 简体 character.** Many Hong Kong standard forms
+ *    are exactly the mainland simplified form, because the PRC simplification
+ *    adopted the same 新字形 conventions Hong Kong did: 着, 温, 脱, 户, 税, 卧,
+ *    悦, 兑, 葱, 幺, 棱, 檐, 痹. Normalising those would rewrite 简体 text, and
+ *    走着 `zǒuzhe` is the case that caught it.
+ *
+ * Excluding them costs almost nothing, because a variant current in either
+ * script is a key in its own right and resolves without any help from here.
+ * Reversing a merge is ambiguous in exactly the way 简→繁 is, and where the
+ * evidence says the variant is current, the safe answer is to leave it alone.
+ */
+const CANONICAL_PAIRS = "僞偽衹只啓啟喫吃粧妝嫺嫻嬀媯峯峰捝挩敍敘枴柺棁梲" +
+    "樑梁枱檯涚涗潙溈潨潀爲為牀床癡痴皁皂竈灶糉粽糭粽" +
+    "綫線緼縕繮韁纔才羣群脣唇蒀蒕蔘參蔿蒍藴蘊衆眾衞衛" +
+    "裏裡覈核説說輼轀醖醞鉢缽鈎鉤鋭銳鍼針閲閱鮎鯰鰛鰮" +
+    "麪麵齶顎";
+/**
+ * Canonical 繁體 forms, mapped to the form Hong Kong writes.
+ *
+ * The 58 characters the two standards genuinely disagree about, measured over
+ * the 86 that appear in either of OpenCC's variant tables. The other 28 are
+ * agreements rather than differences — 爲 → 為 and 衆 → 眾 are both moves *both*
+ * standards make, which is easy to get backwards by reading either table alone.
+ *
+ * Taiwan needs no table of its own: the canonical form is already Taiwan's, so
+ * `zh-Hant-TW` output is what the dictionary stores, unaltered.
+ */
+const HONG_KONG_PAIRS = "兌兑叄叁啟啓囪囱媼媪嫻嫺峰峯么幺悅悦慍愠戶户挩捝" +
+    "搵揾敓敚敘敍柺枴梲棁榲榅梁樑簷檐檯枱氳氲汙污洩泄" +
+    "涗涚溫温溼濕熅煴床牀痺痹著着睪睾稅税縕緼韁繮群羣" +
+    "脫脱膃腽臥卧臺台菸煙蒕蒀參蔘蔥葱蘊藴蛻蜕衛衞裡裏" +
+    "說説轀輼醞醖鉤鈎銳鋭閱閲鯰鮎鰮鰛麵麪顎齶";
+/**
+ * Variant 繁體 forms mapped to the canonical form, as a table.
+ *
+ * Exported so the data pipeline can recompute it from OpenCC and fail the build
+ * if the two have drifted — these tables are code rather than an artifact, so
+ * nothing else would notice an upstream release that moved a character.
+ */
+export const CANONICAL_FORMS = readPairs(CANONICAL_PAIRS);
+/**
+ * Canonical 繁體 forms mapped to Hong Kong's, as a table. Verified like
+ * {@link CANONICAL_FORMS}.
+ */
+export const HONG_KONG_FORMS = readPairs(HONG_KONG_PAIRS);
+/**
+ * The one glyph mapping whose answer depends on how the character is read.
+ *
+ * Taiwan writes 著 for every sense; Hong Kong splits it, writing 着 for the
+ * aspect particle and its relatives and keeping 著 for `zhù`. CC-CEDICT records
+ * the same split in its 简体 column — `著 着 [zhe5]` against `著 著 [zhu4]` —
+ * which is independent confirmation that the divide is real and where it falls.
+ *
+ * OpenCC resolves this with a phrase table. We resolve it with the reading,
+ * which is the point of difference this feature exists for, and which
+ * generalises to words no phrase table lists.
+ *
+ * `zhuó` is deliberately absent, and that is not an oversight: CC-CEDICT writes
+ * it both ways — `著 着 [zhuo2]` for wearing or applying, `著 著 [zhuo2]` for
+ * 執著 — so the reading genuinely does not settle it. It falls through to the
+ * default below and is reported as uncertain rather than guessed at silently.
+ */
+const READING_SPLITS = new Map([["著", new Map([["zhu", "著"]])]]);
+/**
+ * A reading key ignoring tone and 儿化, which never bear on a glyph choice.
+ *
+ * Tone is dropped because the split that needs it — 著 — divides `zhù` from
+ * `zhe` and `zháo`, and those differ in their vowels as well, so the initial
+ * and final are enough and are what sources agree on most.
+ */
+function readingKey(syllable) {
+    if (syllable === undefined) {
+        return undefined;
+    }
+    return `${syllable.initial}${syllable.final}`;
+}
+/**
+ * Whether a character's regional form depends on how it is read.
+ *
+ * Exposed so that a conversion can report the choice as uncertain when it had
+ * no reading to go on, rather than presenting a default as though it were
+ * settled.
+ */
+export function isReadingSensitive(character) {
+    return READING_SPLITS.has(character);
+}
+/**
+ * Normalise one 繁體 character to the canonical form the dictionary stores.
+ *
+ * Characters no table knows are returned unchanged, which is the right answer
+ * for nearly all of them: the two standards agree about everything except the
+ * 58 characters {@link HONG_KONG_FORMS} lists.
+ */
+export function toCanonicalGlyph(character) {
+    return CANONICAL_FORMS.get(character) ?? character;
+}
+/**
+ * Whether any character of a text has a canonical form other than itself.
+ */
+function hasVariantGlyph(text) {
+    for (const character of text) {
+        if (CANONICAL_FORMS.has(character)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Normalise a whole 繁體 text to the canonical forms the dictionary stores.
+ *
+ * Safe to run over 简体 or mixed text, but only because the table is built to
+ * make it so: every variant that is also a current 简体 character is excluded,
+ * since many Hong Kong forms and mainland simplified forms are the same
+ * character. See {@link CANONICAL_FORMS}.
+ *
+ * Returns the original string when nothing needs normalising, which is nearly
+ * always. This sits on the dictionary lookup path, where it is called once per
+ * candidate word at every position of a run, so the common case has to cost a
+ * scan rather than an allocation.
+ *
+ * The mapping is one character to one character, which is what makes it safe
+ * here: normalising a prefix gives the same answer as taking the prefix of the
+ * normalised text, so a lattice scan that prunes on prefixes cannot disagree
+ * with the lookup that follows it.
+ */
+export function toCanonicalGlyphs(text) {
+    if (!hasVariantGlyph(text)) {
+        return text;
+    }
+    let normalised = "";
+    for (const character of toCharacters(text)) {
+        normalised += toCanonicalGlyph(character);
+    }
+    return normalised;
+}
+/**
+ * Write one canonical character in a region's orthography.
+ *
+ * The syllable is used only where the character is one the two standards split
+ * on a reading; everywhere else it is ignored, because a glyph choice never
+ * changes how a character is read.
+ */
+export function toRegionalGlyph(character, region, syllable) {
+    if (region === DEFAULT_REGION) {
+        return character;
+    }
+    const split = READING_SPLITS.get(character);
+    const kept = split?.get(readingKey(syllable) ?? "");
+    if (kept !== undefined) {
+        return kept;
+    }
+    return HONG_KONG_FORMS.get(character) ?? character;
+}
+/**
+ * Write a whole canonical text in a region's orthography.
+ *
+ * Readings are matched to characters by position, so a caller with a decoded
+ * reading can pass it and a caller without one can leave it out. A position
+ * with no syllable behind it falls back to the region's default form, which is
+ * what {@link isReadingSensitive} lets the caller flag.
+ */
+export function toRegionalGlyphs(text, region, readings = []) {
+    if (region === DEFAULT_REGION) {
+        return text;
+    }
+    let written = "";
+    for (const [at, character] of toCharacters(text).entries()) {
+        written += toRegionalGlyph(character, region, readings[at]);
+    }
+    return written;
+}
+//# sourceMappingURL=glyphs.js.map