@kensio/pinyinjs 1.5.3 → 1.7.0

package/dist/dictionary/tiers.d.ts

@@ -37,7 +37,8 @@ export declare const STANDARD_TIER_WORDS = 50000;
  * makes a dictionary usable at all: they cover roughly half of running text on
  * their own, and they are the fallback for every position no word matches.
  * Tiering cuts the phrase tail and the unused characters, never a character
- * that some word is written with.
+ * that some word is written with — and never one the tier is keyed for anyway,
+ * which is what {@link charactersHeld} adds on top.
  *
  * `full` holds everything, including the characters no source uses in a word.
  * They cost little there and are the difference between reading a rare

package/dist/dictionary/tiers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tiers.d.ts","sourceRoot":"","sources":["../../src/dictionary/tiers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK,YAAI,MAAM,EAAE,UAAU,EAAE,MAAM,CAAU,CAAC;AAE3D;;GAEG;AACH,MAAM,MAAM,IAAI,GAAG,CAAC,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1C;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,SAAwB,CAAC;AAElD;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,QAAS,CAAC;AA6C1C;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,SAAS,eAAe,EAAE,EACnC,IAAI,EAAE,IAAI,GACT,SAAS,eAAe,EAAE,CAkB5B"}
+{"version":3,"file":"tiers.d.ts","sourceRoot":"","sources":["../../src/dictionary/tiers.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK,YAAI,MAAM,EAAE,UAAU,EAAE,MAAM,CAAU,CAAC;AAE3D;;GAEG;AACH,MAAM,MAAM,IAAI,GAAG,CAAC,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1C;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,SAAwB,CAAC;AAElD;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAqH1C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,SAAS,eAAe,EAAE,EACnC,IAAI,EAAE,IAAI,GACT,SAAS,eAAe,EAAE,CAkB5B"}

package/dist/dictionary/tiers.js

@@ -1,4 +1,5 @@
 import { isSingleCharacter, toCharacters } from "../script/characters.js";
+import { traditionalForms } from "./artifact.js";
 /**
  * The dictionary tiers, smallest first and each contained in the next.
  *
@@ -65,6 +66,71 @@ function charactersInUse(entries) {
     }
     return inUse;
 }
+/**
+ * The characters a tier holds: the ones in use, and the ones it has to answer.
+ *
+ * "In use" alone is not enough, because a tier is keyed by more than the
+ * headwords it holds — an entry claims every 繁體 spelling attested for it, and
+ * some of those spellings are rare characters with entries of their own. A tier
+ * holding 卒 is keyed for 䘚 whether or not it holds 䘚, so without the
+ * character's own entry it answers that key from the 卒 that reached it
+ * sideways and reads `zú`, where `full` lets 䘚's own entry win the key and
+ * reads `zhú`. Neither reading is wrong — 䘚 written for 卒 really is `zú` —
+ * but which one you get must not depend on how much of the dictionary has
+ * loaded, or the documented upgrade path contradicts itself mid-paragraph.
+ *
+ * Admitting the entry is all it takes: the artifact's `claimKeys` puts
+ * headwords ahead of 繁體 aliases in every tier, so once 䘚 is present it wins
+ * its own key exactly as it does in `full`.
+ *
+ * It repeats to a fixpoint because an admitted character claims spellings of
+ * its own, and one of those can be another character with an entry behind it.
+ * On the current sources it settles at once — 242 characters admitted, then a
+ * confirming pass that admits none — but nothing in the merge rules a chain
+ * out, and the pass is a set lookup per entry against a build that reads four
+ * source files.
+ */
+function charactersHeld(entries, words) {
+    const headed = new Set();
+    for (const entry of entries) {
+        if (isSingleCharacter(entry.hans)) {
+            headed.add(entry.hans);
+        }
+    }
+    const inUse = charactersInUse(entries);
+    const held = new Set();
+    for (const character of headed) {
+        if (inUse.has(character)) {
+            held.add(character);
+        }
+    }
+    /**
+     * Admit the characters this entry claims the key of, reporting any news.
+     */
+    const admitClaims = (entry) => {
+        let admitted = false;
+        for (const form of traditionalForms(entry)) {
+            if (headed.has(form) && !held.has(form)) {
+                held.add(form);
+                admitted = true;
+            }
+        }
+        return admitted;
+    };
+    for (const entry of words) {
+        admitClaims(entry);
+    }
+    let growing = true;
+    while (growing) {
+        growing = false;
+        for (const entry of entries) {
+            if (isSingleCharacter(entry.hans) && held.has(entry.hans)) {
+                growing = admitClaims(entry) || growing;
+            }
+        }
+    }
+    return held;
+}
 /**
  * The entries a tier contains.
  *
@@ -72,7 +138,8 @@ function charactersInUse(entries) {
  * makes a dictionary usable at all: they cover roughly half of running text on
  * their own, and they are the fallback for every position no word matches.
  * Tiering cuts the phrase tail and the unused characters, never a character
- * that some word is written with.
+ * that some word is written with — and never one the tier is keyed for anyway,
+ * which is what {@link charactersHeld} adds on top.
  *
  * `full` holds everything, including the characters no source uses in a word.
  * They cost little there and are the difference between reading a rare
@@ -82,15 +149,14 @@ export function selectTier(entries, tier) {
     if (tier === "full") {
         return entries;
     }
-    const inUse = charactersInUse(entries);
-    const characters = entries.filter((entry) => isSingleCharacter(entry.hans) && inUse.has(entry.hans));
-    if (tier === "core") {
-        return characters;
-    }
-    const words = entries
-        .filter((entry) => !isSingleCharacter(entry.hans))
-        .toSorted(byFrequency)
-        .slice(0, STANDARD_TIER_WORDS);
-    return [...characters, ...words];
+    const words = tier === "core"
+        ? []
+        : entries
+            .filter((entry) => !isSingleCharacter(entry.hans))
+            .toSorted(byFrequency)
+            .slice(0, STANDARD_TIER_WORDS);
+    const held = charactersHeld(entries, words);
+    const characters = entries.filter((entry) => isSingleCharacter(entry.hans) && held.has(entry.hans));
+    return tier === "core" ? characters : [...characters, ...words];
 }
 //# sourceMappingURL=tiers.js.map

package/dist/dictionary/tiers.js.map

@@ -1 +1 @@
-{"version":3,"file":"tiers.js","sourceRoot":"","sources":["../../src/dictionary/tiers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAG1E;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,CAAU,CAAC;AAO3D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,MAAqB,CAAC;AAElD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAE1C;;GAEG;AACH,SAAS,WAAW,CAAC,IAAqB,EAAE,KAAsB;IAChE,IAAI,IAAI,CAAC,SAAS,KAAK,KAAK,CAAC,SAAS,EAAE,CAAC;QACvC,OAAO,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;IAC1C,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAS,eAAe,CACtB,OAAmC;IAEnC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,iBAAiB,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YAClC,IAAI,KAAK,CAAC,SAAS,GAAG,CAAC,EAAE,CAAC;gBACxB,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACxB,CAAC;YACD,SAAS;QACX,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YAC5C,KAAK,MAAM,SAAS,IAAI,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC3C,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YACvB,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,UAAU,CACxB,OAAmC,EACnC,IAAU;IAEV,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACpB,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,MAAM,KAAK,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IACvC,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAC/B,CAAC,KAAK,EAAE,EAAE,CAAC,iBAAiB,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAClE,CAAC;IACF,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACpB,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,MAAM,KAAK,GAAG,OAAO;SAClB,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,iBAAiB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;SACjD,QAAQ,CAAC,WAAW,CAAC;SACrB,KAAK,CAAC,CAAC,EAAE,mBAAmB,CAAC,CAAC;IACjC,OAAO,CAAC,GAAG,UAAU,EAAE,GAAG,KAAK,CAAC,CAAC;AACnC,CAAC"}
+{"version":3,"file":"tiers.js","sourceRoot":"","sources":["../../src/dictionary/tiers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAGjD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,CAAU,CAAC;AAO3D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,MAAqB,CAAC;AAElD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAE1C;;GAEG;AACH,SAAS,WAAW,CAAC,IAAqB,EAAE,KAAsB;IAChE,IAAI,IAAI,CAAC,SAAS,KAAK,KAAK,CAAC,SAAS,EAAE,CAAC;QACvC,OAAO,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;IAC1C,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAS,eAAe,CACtB,OAAmC;IAEnC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,iBAAiB,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YAClC,IAAI,KAAK,CAAC,SAAS,GAAG,CAAC,EAAE,CAAC;gBACxB,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACxB,CAAC;YACD,SAAS;QACX,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YAC5C,KAAK,MAAM,SAAS,IAAI,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC3C,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YACvB,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,SAAS,cAAc,CACrB,OAAmC,EACnC,KAAiC;IAEjC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;IACjC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,iBAAiB,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YAClC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;IAED,MAAM,KAAK,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IACvC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,SAAS,IAAI,MAAM,EAAE,CAAC;QAC/B,IAAI,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YACzB,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;IAED;;OAEG;IACH,MAAM,WAAW,GAAG,CAAC,KAAsB,EAAW,EAAE;QACtD,IAAI,QAAQ,GAAG,KAAK,CAAC;QACrB,KAAK,MAAM,IAAI,IAAI,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3C,IAAI,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBACxC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;gBACf,QAAQ,GAAG,IAAI,CAAC;YAClB,CAAC;QACH,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC,CAAC;IAEF,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;QAC1B,WAAW,CAAC,KAAK,CAAC,CAAC;IACrB,CAAC;IACD,IAAI,OAAO,GAAG,IAAI,CAAC;IACnB,OAAO,OAAO,EAAE,CAAC;QACf,OAAO,GAAG,KAAK,CAAC;QAChB,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,IAAI,iBAAiB,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC1D,OAAO,GAAG,WAAW,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC;YAC1C,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,UAAU,CACxB,OAAmC,EACnC,IAAU;IAEV,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACpB,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,MAAM,KAAK,GACT,IAAI,KAAK,MAAM;QACb,CAAC,CAAC,EAAE;QACJ,CAAC,CAAC,OAAO;aACJ,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,iBAAiB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;aACjD,QAAQ,CAAC,WAAW,CAAC;aACrB,KAAK,CAAC,CAAC,EAAE,mBAAmB,CAAC,CAAC;IAEvC,MAAM,IAAI,GAAG,cAAc,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC5C,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAC/B,CAAC,KAAK,EAAE,EAAE,CAAC,iBAAiB,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CACjE,CAAC;IACF,OAAO,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,UAAU,EAAE,GAAG,KAAK,CAAC,CAAC;AAClE,CAAC"}

package/dist/format/html.d.ts

@@ -35,6 +35,38 @@ export interface HtmlOptions extends ConvertOptions {
  * once and render more than one way.
  */
 export declare function toHtml(pieces: readonly ConvertedPiece[], options?: HtmlOptions): string;
+/**
+ * Mark up a converted text as hanzi with its reading above, syllable by
+ * syllable.
+ *
+ * The output every other mode cannot give: `convert` and {@link toHtml} write
+ * the pinyin *instead of* the hanzi, and a learner's text, a subtitle and a
+ * dictionary entry all want both at once. The markup is `<ruby>`, which every
+ * current browser lays out natively and which degrades to parentheses through
+ * `<rp>` where it is not supported.
+ *
+ * ```html
+ * <ruby lang="zh">银<rp>(</rp><rt><span …>yín</span></rt><rp>)</rp></ruby>
+ * ```
+ *
+ * Each `<rt>` holds whatever {@link toHtml} would have written for those
+ * syllables, so tone classes and uncertainty marking work inside an annotation
+ * exactly as they do outside one.
+ *
+ * **A base is not always one character.** 玩儿 is two characters and the one
+ * syllable `wánr`, and a read number reverses on the way — 95% is
+ * `bǎifēnzhījiǔshíwǔ` — so both are annotated whole. Splitting them per
+ * character is what everything that emits ruby from a pinyin library gets
+ * wrong, and it is why {@link ConvertedPiece.source} exists.
+ */
+export declare function toAnnotatedHtml(pieces: readonly ConvertedPiece[], options?: HtmlOptions): string;
+/**
+ * Convert hanzi to pinyin as HTML, hanzi and reading together.
+ *
+ * {@link toAnnotatedHtml} applied to a fresh conversion; see it for what the
+ * markup is and why a base is not always one character.
+ */
+export declare function convertToAnnotatedHtml(dictionary: Dictionary, text: string, options?: HtmlOptions): string;
 /**
  * Convert hanzi to pinyin as HTML, one element per syllable.
  *

package/dist/format/html.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["../../src/format/html.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,cAAc,EAEpB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAI9D;;GAEG;AACH,MAAM,WAAW,WAAY,SAAQ,cAAc;IACjD;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACzB;AA+HD;;;;;GAKG;AACH,wBAAgB,MAAM,CACpB,MAAM,EAAE,SAAS,cAAc,EAAE,EACjC,OAAO,GAAE,WAAgB,GACxB,MAAM,CAER;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,WAAgB,GACxB,MAAM,CAER"}
+{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["../../src/format/html.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,cAAc,EAEpB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAI9D;;GAEG;AACH,MAAM,WAAW,WAAY,SAAQ,cAAc;IACjD;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACzB;AA+HD;;;;;GAKG;AACH,wBAAgB,MAAM,CACpB,MAAM,EAAE,SAAS,cAAc,EAAE,EACjC,OAAO,GAAE,WAAgB,GACxB,MAAM,CAER;AA+HD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,cAAc,EAAE,EACjC,OAAO,GAAE,WAAgB,GACxB,MAAM,CAIR;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,WAAgB,GACxB,MAAM,CAER;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,WAAgB,GACxB,MAAM,CAER"}

package/dist/format/html.js

@@ -122,6 +122,150 @@ function writePiece(piece, options) {
 export function toHtml(pieces, options = {}) {
     return pieces.map((piece) => writePiece(piece, options)).join("");
 }
+/**
+ * What the characters being annotated declare themselves to be.
+ *
+ * The mirror of {@link languageTag}: inside an annotation the base is hanzi and
+ * only the reading is pinyin, so on an English page the two need different tags
+ * and neither can be left to inherit.
+ *
+ * **`zh`, with no script subtag, and that is deliberate.** `Hans` or `Hant`
+ * would be better for font selection, and neither can be known here. The
+ * conversion's locale does not settle it — script and locale are separate axes,
+ * and a mainland edition of a classical text is 繁體 read as `zh-CN` — and
+ * detecting it from the characters needs the script tables, which load
+ * separately from the dictionary precisely so that converting does not pay for
+ * them. A tag that is merely unspecific is worth more than one that is wrong,
+ * so a caller who knows the script should wrap the output and say so there.
+ */
+const BASE_TAG = "zh";
+/**
+ * Gather pieces into the bases they are readings of.
+ *
+ * A piece naming characters opens a group and every piece after it that names
+ * none reads on into the same one, which is how 玩儿 keeps `wánr` over both
+ * characters and 95% keeps `bǎifēnzhījiǔshíwǔ` over all three. Pieces writing
+ * no reading at all — the spaces between words, and runs that were never Han —
+ * are their own groups, with nothing to annotate.
+ */
+function annotationsOf(pieces) {
+    const groups = [];
+    for (const [at, piece] of pieces.entries()) {
+        const open = groups.at(-1);
+        if (open?.source !== undefined && continues(piece, pieces[at + 1])) {
+            groups[groups.length - 1] = {
+                source: open.source,
+                pieces: [...open.pieces, piece],
+            };
+            continue;
+        }
+        groups.push({ source: piece.source, pieces: [piece] });
+    }
+    return groups;
+}
+/**
+ * Whether a piece belongs to the annotation the group before it opened.
+ *
+ * Three kinds do:
+ *
+ * - A **syllable naming no characters** is reading on into the ones already
+ *   named, which is 儿化 and every syllable of a read number after the first.
+ * - A **separator that is not a space** is a mark *inside* one orthographic
+ *   word rather than a gap between two — the hyphen of `gāngān-jìngjìng`, the
+ *   only one GB/T 16159 writes — so it belongs beside the syllables it divides.
+ * - A **space with more of the same reading after it**. 1988 is read
+ *   `yī jiǔ bā bā`, four syllables over one base, and the spaces between them
+ *   are inside that reading rather than between two of them.
+ *
+ * That last one is why this needs the piece after it. A space is written the
+ * same way whether it separates two words or two syllables of one number, and
+ * what tells them apart is whether what follows is still reading the same
+ * characters. Told apart wrongly, the reading escapes its own annotation:
+ * 1988年 came out as `1988` over `yī` with `jiǔ bā bā` loose beside it.
+ *
+ * A space between two words is the case that does not continue, and dropping it
+ * is the point: the hanzi it annotates has no space in it, and each base is
+ * already its own group on the page.
+ */
+function continues(piece, next) {
+    if (piece.syllable !== undefined) {
+        return piece.source === undefined;
+    }
+    if (piece.source !== undefined) {
+        return false;
+    }
+    return (piece.text.trim() !== "" ||
+        (next?.syllable !== undefined && next.source === undefined));
+}
+/**
+ * Mark up one base and its reading.
+ */
+function writeAnnotation(annotation, options) {
+    const { lang = true } = options;
+    const { source, pieces } = annotation;
+    if (pieces.every((piece) => piece.syllable === undefined)) {
+        // Nothing is read here. Either it is source text that simply has no
+        // reading — punctuation, a Latin word — and is written as the author wrote
+        // it, or it is pinyin orthography with no source behind it at all: the
+        // space between two words, and the hyphen in `gāngān-jìngjìng`. Writing
+        // those into the hanzi would annotate 干干净净 as 干干-净净.
+        return source === undefined ? "" : escape(source);
+    }
+    if (source === undefined) {
+        // A reading whose piece never named what it reads. Nothing a conversion
+        // builds looks like this — every group is opened by a piece carrying its
+        // characters — but {@link toAnnotatedHtml} takes pieces from the caller,
+        // and there is no base to hang an annotation on, so it is written as the
+        // plain markup it would have got from {@link toHtml}.
+        return pieces.map((piece) => writePiece(piece, options)).join("");
+    }
+    const reading = pieces.map((piece) => writePiece(piece, options)).join("");
+    // The tag goes on the <ruby> rather than around the base, and the syllables
+    // inside the <rt> override it with their own. `<rb>` would be the obvious
+    // place for it and is not an element any more: the WHATWG parser drops it,
+    // leaving the base as bare text, so writing one would mean emitting markup
+    // that no browser keeps.
+    const opening = lang ? `<ruby lang="${BASE_TAG}">` : "<ruby>";
+    return `${opening}${escape(source)}<rp>(</rp><rt>${reading}</rt><rp>)</rp></ruby>`;
+}
+/**
+ * Mark up a converted text as hanzi with its reading above, syllable by
+ * syllable.
+ *
+ * The output every other mode cannot give: `convert` and {@link toHtml} write
+ * the pinyin *instead of* the hanzi, and a learner's text, a subtitle and a
+ * dictionary entry all want both at once. The markup is `<ruby>`, which every
+ * current browser lays out natively and which degrades to parentheses through
+ * `<rp>` where it is not supported.
+ *
+ * ```html
+ * <ruby lang="zh">银<rp>(</rp><rt><span …>yín</span></rt><rp>)</rp></ruby>
+ * ```
+ *
+ * Each `<rt>` holds whatever {@link toHtml} would have written for those
+ * syllables, so tone classes and uncertainty marking work inside an annotation
+ * exactly as they do outside one.
+ *
+ * **A base is not always one character.** 玩儿 is two characters and the one
+ * syllable `wánr`, and a read number reverses on the way — 95% is
+ * `bǎifēnzhījiǔshíwǔ` — so both are annotated whole. Splitting them per
+ * character is what everything that emits ruby from a pinyin library gets
+ * wrong, and it is why {@link ConvertedPiece.source} exists.
+ */
+export function toAnnotatedHtml(pieces, options = {}) {
+    return annotationsOf(pieces)
+        .map((annotation) => writeAnnotation(annotation, options))
+        .join("");
+}
+/**
+ * Convert hanzi to pinyin as HTML, hanzi and reading together.
+ *
+ * {@link toAnnotatedHtml} applied to a fresh conversion; see it for what the
+ * markup is and why a base is not always one character.
+ */
+export function convertToAnnotatedHtml(dictionary, text, options = {}) {
+    return toAnnotatedHtml(convertPieces(dictionary, text, options), options);
+}
 /**
  * Convert hanzi to pinyin as HTML, one element per syllable.
  *

package/dist/format/html.js.map

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

package/dist/grade/check.d.ts

@@ -0,0 +1,156 @@
+import { type ConvertOptions } from "../decode/convert.js";
+import type { Dictionary } from "../dictionary/dictionary.js";
+import { type Syllable } from "../syllable/syllable.js";
+/**
+ * What one syllable of a typed transcription turned out to be.
+ *
+ * `toneless` is deliberately separate from `tone`: {@link Syllable.tone} says
+ * whether a tone was written at all, so "you left the tones off" is a different
+ * thing to report than "you wrote the wrong one", and only the second is a
+ * mistake about the language. {@link CheckOptions.tones} decides which of them
+ * counts against the score.
+ */
+export type PinyinVerdict = "correct" | "toneless" | "tone" | "wrong" | "missing" | "extra";
+/**
+ * Where a typed syllable falls against the word boundaries the reading has.
+ *
+ * `split` is a word written as two — `yín háng` for 银行 — and `joined` is two
+ * words run into one. Both are reported whatever {@link CheckOptions.spacing}
+ * says, so an application can show them without having to grade them.
+ */
+export type SpacingVerdict = "correct" | "split" | "joined";
+/**
+ * Whether one dimension of the writing has to be right for a perfect score.
+ *
+ * `optional` still reports the verdict and counts the syllable correct anyway;
+ * `required` counts it wrong. Both dimensions this applies to — tones and word
+ * spacing — are things an exercise may or may not be teaching yet.
+ */
+export type CheckRequirement = "optional" | "required";
+/**
+ * How a transcription should be checked.
+ *
+ * Every {@link ConvertOptions} field is accepted and passed to the conversion
+ * the answer is read from, which is what `readings` is worth having here for:
+ * an exercise knows which sense of 长 its own sentence uses, where the decoder
+ * can only weigh the evidence.
+ */
+export interface CheckOptions extends ConvertOptions {
+    /** Whether a tone has to be written. Defaults to `optional`. */
+    readonly tones?: CheckRequirement;
+    /**
+     * Whether the word spacing has to be right. Defaults to `optional`.
+     *
+     * Off by default because the 分词连写 this grades against is not a complete
+     * 正词法 implementation — see [orthography](../../docs/orthography/) for
+     * where it stops — so a learner can write a word the standard writes
+     * differently from the way this does. On for an exercise teaching the
+     * spacing, where getting it right is the point.
+     */
+    readonly spacing?: CheckRequirement;
+}
+/**
+ * One syllable of the check: what was expected there, and what was typed.
+ */
+export interface CheckedSyllable {
+    readonly verdict: PinyinVerdict;
+    /**
+     * Where this syllable falls against the word boundaries, where both a reading
+     * and a typed syllable met here.
+     *
+     * A separate axis from {@link CheckedSyllable.verdict}, because it is a
+     * separate mistake: `yín háng` reads 银行 perfectly and writes it as two
+     * words. Undefined for a syllable that was only expected or only typed.
+     */
+    readonly spacing: SpacingVerdict | undefined;
+    /** Whether this counts as right in {@link PinyinCheck.score}. */
+    readonly isCorrect: boolean;
+    /** The reading expected here, or undefined where nothing was expected. */
+    readonly expected: Syllable | undefined;
+    /**
+     * What was typed here, parsed, or undefined where nothing was typed.
+     *
+     * Also undefined for something typed that is not a syllable at all, which
+     * {@link CheckedSyllable.text} still reports as written.
+     */
+    readonly actual: Syllable | undefined;
+    /** What was typed here, exactly as written, or empty where nothing was. */
+    readonly text: string;
+    /**
+     * The characters the expected syllable reads.
+     *
+     * Undefined where a syllable reads on into the characters named before it,
+     * exactly as {@link ConvertedPiece.source} is, and where nothing was
+     * expected at all.
+     */
+    readonly source: string | undefined;
+    /**
+     * Where those characters start, in code points from the start of the text.
+     *
+     * What highlighting the mistake in the text itself needs, and counted the way
+     * {@link import("../decode/segment.js").Segment.at} counts.
+     */
+    readonly at: number | undefined;
+}
+/**
+ * A typed transcription marked against the text it was written for.
+ */
+export interface PinyinCheck {
+    /** One entry per syllable expected or typed, in order. */
+    readonly syllables: readonly CheckedSyllable[];
+    /** Whether every syllable counted as correct. */
+    readonly isCorrect: boolean;
+    /**
+     * The share of the syllables that counted as correct, from 0 to 1.
+     *
+     * Over the entries reported rather than over the expected reading, so that
+     * inventing a syllable costs as much as dropping one: an answer with an extra
+     * syllable in it has more entries than the reading has syllables.
+     */
+    readonly score: number;
+    /** The reading that was expected, as the conversion writes it. */
+    readonly reading: readonly Syllable[];
+}
+/**
+ * Mark a typed pinyin transcription against the text it was written for.
+ *
+ * ```ts
+ * check(dictionary, "北京", "bei3jing3").syllables.map((one) => one.verdict);
+ * // ["correct", "tone"]
+ * ```
+ *
+ * **The point of doing this with a dictionary is being fair in the ways a
+ * string comparison cannot be**, and every one of these is a learner being
+ * marked wrong for being right:
+ *
+ * - **Either notation, mixed freely.** `běi` and `bei3` are the same syllable
+ *   and both parse, so `bei3jīng` is not a spelling mistake.
+ * - **A reading the decoder itself was unsure of.** Where another reading of
+ *   the same character was there for the taking, it is accepted — see
+ *   {@link rejectedReadings}. 银行 is not one of those: the word settles both
+ *   syllables, so `yínxíng` really is wrong.
+ * - **Sandhi either way.** 你好 is written `nǐ hǎo` and said `ní hǎo`, and 不是
+ *   is `bú shì` written and `bù shì` underneath. Both pass.
+ * - **Tones written or not.** A syllable typed with no tone is `toneless`
+ *   rather than `tone`, and {@link CheckOptions.tones} says whether that counts
+ *   against the score. A neutral tone typed without a mark is simply correct,
+ *   because that is how pinyin writes it.
+ * - **Apostrophes.** Not a word boundary and not a sound: `nǐhǎo`, `nǐ hǎo` and
+ *   `nǐ'hǎo` all read the same, and check the same.
+ *
+ * Word spacing is graded on its own axis, reported as
+ * {@link CheckedSyllable.spacing} and counted only where
+ * {@link CheckOptions.spacing} asks for it — and tolerant in the same spirit,
+ * since 分词连写 and the words the dictionary knows are two conventions this
+ * package writes and a learner may have been taught either.
+ *
+ * What comes back is one {@link CheckedSyllable} per syllable expected or
+ * typed, in order, each naming the characters it reads and where they are, so
+ * that a mistake can be shown against the text rather than against the answer.
+ *
+ * This is {@link import("../accuracy/score.js").scoreCase} — the scorer that
+ * marks the decoder against the gold corpus — pointed at a person instead, and
+ * it costs three conversions of the text.
+ */
+export declare function check(dictionary: Dictionary, text: string, typed: string, options?: CheckOptions): PinyinCheck;
+//# sourceMappingURL=check.d.ts.map

package/dist/grade/check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/grade/check.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,cAAc,EAGpB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,EAEL,KAAK,QAAQ,EAEd,MAAM,yBAAyB,CAAC;AAGjC;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GACrB,SAAS,GACT,UAAU,GACV,MAAM,GACN,OAAO,GACP,SAAS,GACT,OAAO,CAAC;AAEZ;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,UAAU,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,WAAW,YAAa,SAAQ,cAAc;IAClD,gEAAgE;IAChE,QAAQ,CAAC,KAAK,CAAC,EAAE,gBAAgB,CAAC;IAClC;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,SAAS,CAAC;IAC7C,iEAAiE;IACjE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,SAAS,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,SAAS,CAAC;IACtC,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,EAAE,SAAS,eAAe,EAAE,CAAC;IAC/C,iDAAiD;IACjD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,SAAS,QAAQ,EAAE,CAAC;CACvC;AAqaD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,KAAK,CACnB,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,YAAiB,GACzB,WAAW,CAuBb"}