@furifont/core 0.2.0 → 0.4.0

package/dist/index.d.mts

@@ -10,14 +10,8 @@ export declare const DEFAULTS: {
   readonly plan: {
     readonly family: "Furifont Sans";
     readonly rubyScript: "hiragana";
-    /** Newspaper frequency buckets, nf01 to nf48: the window of words that get ruby. All of them: it adds about 400 glyphs. */
-    readonly nfMin: 1;
-    readonly nfMax: 48;
-    /** JMdict priority tags that select a word whatever its bucket: the first tier of each list, which JMdict marks as common. */
-    readonly selectTags: readonly ["ichi1", "news1", "spec1", "gai1"];
-    /** Uses in Tatoeba's example sentences that select a word whatever its bucket: about 1,000 more words, and 50 glyphs. */
-    readonly minTatoeba: 3;
-    readonly places: true;
+    /** No word is left bare for being common; every word of every source gets ruby. */
+    readonly skip: 0;
     readonly isolated: true;
     readonly isolatedMinShare: 0.8;
     /** Sizes in em, relative to the base font. */
@@ -71,7 +65,7 @@ export declare const PREBUILT: {
     readonly style: "VF";
     readonly weights: readonly [250, 900];
   };
-  /** Options set on every prebuilt font over the defaults above, such as `{ nfMax: 24 }`. */
+  /** Options set on every prebuilt font over the defaults above, such as `{ take: 20000 }`. */
   readonly options: {};
 };
 /**
@@ -85,76 +79,31 @@ export declare const VERSION_PROBE: {
   readonly selector: 65024;
 };
 //#endregion
-//#region src/dictionary.d.ts
-/** One (written form, reading) pair, as compiled by `@furifont/dictionary`. */
-interface DictionaryEntry {
-  form: string;
-  /** JmdictFurigana alignment: `0:に;1:ほん`, or `0-1:きょう` for a reading spanning characters. */
-  furigana: string;
-  /** The form's newspaper frequency bucket (nf01..nf48), 0 when unranked. */
-  nf: number;
-  /** The reading's JMdict priority tags, space separated; empty for uncommon readings. */
-  priority: string;
-  /** Position of the reading among the form's readings, in JMdict order. */
-  order: number;
-  /** `来る`-type verb, whose kanji reads differently as it conjugates. */
-  conjugatesReading?: boolean;
-  /** The JLPT level whose word list has this pair: 5 for N5 down to 1 for N1. */
-  jlpt?: number;
-  /** How many times Tatoeba's example sentences use the pair, spelled this way. */
-  tatoeba?: number;
-}
-interface Dictionary {
-  entries: DictionaryEntry[];
-  /** Kanji to its on'yomi, in hiragana. */
-  onyomi: Record<string, string[]>;
-  /** Source datasets and the version each was compiled from. */
-  sources: Record<string, string>;
-  /** Written forms never to annotate, such as 月, whose reading alone is a guess; users' removals add to them. */
-  bare?: string[];
-  /** Curated default readings in inline notation, for words the data ranks wrong; pins override them. */
-  defaults?: string[];
-  /** Place names, each with the one reading to show; common words take precedence over them. */
-  places?: {
-    form: string;
-    furigana: string;
-  }[];
-}
-/** A ruby annotation over characters `[start, end)` of a run. */
-interface RubySpan {
-  start: number;
-  end: number;
-  ruby: string;
-}
-/** A maximal sequence of Han characters with its reading, the unit a shaper sees. */
-interface HanRun {
-  text: string;
-  spans: RubySpan[];
-}
-export declare function isHan(char: string): boolean;
-export declare function parseFurigana(furigana: string): RubySpan[];
-/**
- * Splits a form into its Han runs. Browsers itemize text by script before
- * shaping, so a font only ever sees one run at a time: okurigana and other
- * kana are never visible as context. Runs with an unannotated kanji or an
- * annotation leaking outside the run are dropped.
- */
-export declare function hanRuns(form: string, spans: readonly RubySpan[]): HanRun[];
-/**
- * Parses the inline notation for custom words: `日[に]本[ほん]` for one reading
- * per kanji, `今日[きょう]` for a reading over several kanji, kana as written.
- */
-export declare function parseNotation(notation: string): {
-  form: string;
-  spans: RubySpan[];
-};
-export declare function formatNotation(text: string, spans: readonly RubySpan[]): string;
-//#endregion
 //#region src/schema.d.ts
 export declare const RUBY_SCRIPTS: readonly ["hiragana", "katakanaOn", "hepburn"];
-export declare const PRIORITY_TAGS: readonly ["ichi1", "ichi2", "news1", "news2", "spec1", "spec2", "gai1", "gai2"];
+/** The dictionary's manually maintained sources. */
+export declare const MANUAL_SOURCES: readonly ["mahjong-yaku", "jr-stations", "yojijukugo", "japan-post"];
+type ManualSource = typeof MANUAL_SOURCES[number];
+/**
+ * The sources a plan takes words from: any JMdict word; JMdict's priority
+ * lists (both tiers of each) and its newspaper ranking; words Tatoeba's
+ * sentences use at least three times; JMnedict's place names; the manual lists.
+ */
+export declare const WORD_SOURCES: readonly ["jmdict", "ichi", "news", "spec", "gai", "nf", "tatoeba", "place", "mahjong-yaku", "jr-stations", "yojijukugo", "japan-post"];
+type WordSource = typeof WORD_SOURCES[number];
 /** Easiest first. */
 export declare const JLPT_LEVELS: readonly ["N5", "N4", "N3", "N2", "N1"];
+/**
+ * Every source a reading may have, a bit each in this order: the word
+ * sources, then the easiest JLPT level listing it, `inflecting` (a kanji read
+ * before okurigana in a JMdict word no list tags, such as 奉る) and `default`,
+ * the dictionary's curated default.
+ */
+export declare const SOURCES: readonly ["jmdict", "ichi", "news", "spec", "gai", "nf", "tatoeba", "place", "mahjong-yaku", "jr-stations", "yojijukugo", "japan-post", "N5", "N4", "N3", "N2", "N1", "inflecting", "default"];
+type Source = typeof SOURCES[number];
+export declare const sourceBit: (source: Source) => number;
+/** The sources a mask of `SOURCES` bits names. */
+export declare const sourcesIn: (mask: number) => Source[];
 type RubyScript = typeof RUBY_SCRIPTS[number];
 /** Sizes in em, relative to the base font. */
 declare const RubyMetricsSchema: v.ObjectSchema<{
@@ -168,38 +117,17 @@ declare const RubyMetricsSchema: v.ObjectSchema<{
   readonly maxRubyWidth: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 3, undefined>]>, 1.5>;
 }, undefined>;
 type RubyMetrics = v.InferOutput<typeof RubyMetricsSchema>;
-/** `schema`, checking that its frequency window `nfMin..nfMax` holds a bucket; for schemas that extend the options too. */
-export declare function withNfWindow<T extends v.GenericSchema<unknown, {
-  nfMin: number;
-  nfMax: number;
-}>>(schema: T): v.SchemaWithPipe<readonly [T, v.CheckAction<v.InferOutput<T>, string>]>;
-export declare const PlanOptionsSchema: v.SchemaWithPipe<readonly [v.ObjectSchema<{
+export declare const PlanOptionsSchema: v.ObjectSchema<{
   readonly family: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.NonEmptyAction<string, undefined>, v.CheckAction<string, "Source is a reserved font name of the base font">]>, "Furifont Sans">;
   readonly rubyScript: v.OptionalSchema<v.PicklistSchema<readonly ["hiragana", "katakanaOn", "hepburn"], undefined>, "hiragana">;
-  /**
-   * Words whose newspaper frequency bucket is below this stay bare: the most
-   * common ones, which a reader knows. Tags don't bring them back.
-   */
-  readonly nfMin: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 48, undefined>]>, 1>;
-  /** Words whose newspaper frequency bucket is at most this are annotated. */
-  readonly nfMax: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 48, undefined>]>, 48>;
-  /**
-   * JMdict priority tags that select a word whatever its frequency bucket:
-   * `spec1` catches words like 日本 that the newspaper ranking misses.
-   */
-  readonly selectTags: v.OptionalSchema<v.ArraySchema<v.PicklistSchema<readonly ["ichi1", "ichi2", "news1", "news2", "spec1", "spec2", "gai1", "gai2"], undefined>, undefined>, () => ("ichi1" | "news1" | "spec1" | "gai1")[]>;
-  /**
-   * Words of two or more kanji that Tatoeba's example sentences use at least
-   * this many times are annotated whatever their bucket: everyday words that
-   * no list tags, such as 留守中, which would otherwise be bare or read as a
-   * place name (国中 くになか, not くにじゅう). The sentences also decide how a
-   * lone kanji reads, where they use it alone often enough. 0 turns them off.
-   */
-  readonly minTatoeba: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, 3>;
+  /** The sources whose words get ruby. */
+  readonly sources: v.OptionalSchema<v.ArraySchema<v.PicklistSchema<readonly ["jmdict", "ichi", "news", "spec", "gai", "nf", "tatoeba", "place", "mahjong-yaku", "jr-stations", "yojijukugo", "japan-post"], undefined>, undefined>, () => ("mahjong-yaku" | "jr-stations" | "yojijukugo" | "japan-post" | "jmdict" | "ichi" | "news" | "spec" | "gai" | "nf" | "tatoeba" | "place")[]>;
+  /** The most common words left bare, by score: a reader knows them. Lone kanji count too. */
+  readonly skip: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, 0>;
+  /** How many words get ruby after those skipped, by score; all of them when left out. */
+  readonly take: v.OptionalSchema<v.SchemaWithPipe<readonly [v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, v.MinValueAction<number, 1, undefined>]>, undefined>;
   /** Words on the JLPT lists of this level and every easier one stay bare. */
   readonly skipJlpt: v.OptionalSchema<v.PicklistSchema<readonly ["N5", "N4", "N3", "N2", "N1"], undefined>, undefined>;
-  /** Annotate place names from the dictionary where no common word claims the run. */
-  readonly places: v.OptionalSchema<v.BooleanSchema<undefined>, true>;
   /** Annotate a kanji alone in its run, or one no word claims after another kanji (a suffix); when off, only selectors give them ruby. */
   readonly isolated: v.OptionalSchema<v.BooleanSchema<undefined>, true>;
   /** A kanji alone in its run is annotated only when one reading has this share of the evidence. */
@@ -222,29 +150,7 @@ export declare const PlanOptionsSchema: v.SchemaWithPipe<readonly [v.ObjectSchem
     /** Widest a ruby may get, overhanging its base symmetrically. */
     readonly maxRubyWidth: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 3, undefined>]>, 1.5>;
   }, undefined>, {}>;
-}, undefined>, v.CheckAction<{
-  family: string;
-  rubyScript: "hiragana" | "hepburn" | "katakanaOn";
-  nfMin: number;
-  nfMax: number;
-  selectTags: ("ichi1" | "news1" | "spec1" | "gai1" | "ichi2" | "news2" | "spec2" | "gai2")[];
-  minTatoeba: number;
-  skipJlpt?: "N5" | "N4" | "N3" | "N2" | "N1" | undefined;
-  places: boolean;
-  isolated: boolean;
-  isolatedMinShare: number;
-  words: {
-    add: string[];
-    remove: string[];
-    pin: string[];
-  };
-  metrics: {
-    rubyScale: number;
-    rubyGap: number;
-    compressionFloor: number;
-    maxRubyWidth: number;
-  };
-}, string>]>;
+}, undefined>;
 type PlanOptions = v.InferOutput<typeof PlanOptionsSchema>;
 type PlanOptionsInput = v.InferInput<typeof PlanOptionsSchema>;
 export declare function resolveOptions(input?: PlanOptionsInput): PlanOptions;
@@ -298,6 +204,128 @@ export declare const PlanSchema: v.ObjectSchema<{
 }, undefined>;
 type Plan = v.InferOutput<typeof PlanSchema>;
 type PlanGlyph = Plan['glyphs'][number];
+/**
+ * The bounds of a reading's score, 0 to 100: above `tagged`, a word JMdict's
+ * lists tag, by its weight; above `used`, one Tatoeba's sentences use (20 and
+ * its uses, up to 50); above `listed`, one a manual list (15) or JMnedict (10)
+ * names; any other JMdict word scores `listed`.
+ */
+export declare const SCORE: {
+  readonly tagged: 50;
+  readonly used: 20;
+  readonly listed: 5;
+};
+/**
+ * The score of a tagged reading of corpus weight `weight`, at most 1: 1 / its
+ * newspaper bucket, or a lone kanji's share of its uses. It is 100 for 1, 92
+ * for 1/2, 54 for 1/48; a weight too small to score above `tagged` scores 0.
+ */
+export declare function scoreOf(weight: number): number;
+/** The corpus weight of a reading's score, which `scoreOf` gives; 0 for one no list tags. */
+export declare const weightOf: (score: number) => number;
+/** A reading's score, higher for a more common one, and its sources as a mask of `SOURCES` bits. */
+type Reading = [score: number, sources: number];
+type Table = Record<string, Record<string, Reading>>;
+/**
+ * The compiled dictionary, the contract between `@furifont/dictionary` and
+ * the planner: readings by the Han run a font sees, each with its score and
+ * sources. A run's readings come ranked, the default first. Run readings are
+ * JmdictFurigana alignments within the run.
+ */
+export declare const DictionarySchema: v.ObjectSchema<{
+  /** Source datasets and the version each was compiled from. */
+  readonly versions: v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>;
+  /** The bit of each source in the readings' masks. */
+  readonly sources: v.CustomSchema<Record<string, number>, v.ErrorMessage<v.CustomIssue> | undefined>;
+  /** Kanji to its on'yomi, in hiragana. */
+  readonly onyomi: v.RecordSchema<v.StringSchema<undefined>, v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
+  /** Runs of two or more kanji, then their alignments: `{ 日本: { '0-1:にほん': [75, 61] } }`. */
+  readonly runs: v.CustomSchema<Table, v.ErrorMessage<v.CustomIssue> | undefined>;
+  /** Kanji alone in a run, then their readings: `{ 来: { く: [98, 2101] } }`. */
+  readonly kanji: v.CustomSchema<Table, v.ErrorMessage<v.CustomIssue> | undefined>;
+  /** Written forms never to annotate, such as 月, whose reading alone is a guess; users' removals add to them. */
+  readonly bare: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+type Dictionary = v.InferOutput<typeof DictionarySchema>;
+/** The file `DictionarySchema` reads: an entry a line. */
+export declare function formatDictionary(dictionary: Dictionary): string;
+//#endregion
+//#region src/dictionary.d.ts
+/** One (written form, reading) pair of JMdict, aligned by JmdictFurigana. */
+interface DictionaryEntry {
+  form: string;
+  /** JmdictFurigana alignment: `0:に;1:ほん`, or `0-1:きょう` for a reading spanning characters. */
+  furigana: string;
+  /** The form's newspaper frequency bucket (nf01..nf48), 0 when unranked. */
+  nf: number;
+  /** The reading's JMdict priority tags, space separated; empty for uncommon readings. */
+  priority: string;
+  /** Position of the reading among the form's readings, in JMdict order. */
+  order: number;
+  /** `来る`-type verb, whose kanji reads differently as it conjugates. */
+  conjugatesReading?: boolean;
+  /** The JLPT level whose word list has this pair: 5 for N5 down to 1 for N1. */
+  jlpt?: number;
+  /** How many times Tatoeba's example sentences use the pair, spelled this way. */
+  tatoeba?: number;
+}
+/** Everything `fuseDictionary` merges into a `Dictionary`. */
+interface DictionarySources {
+  versions: Record<string, string>;
+  onyomi: Record<string, string[]>;
+  entries: DictionaryEntry[];
+  /** Place names, each with the one reading to show; common words take precedence over them. */
+  places: {
+    form: string;
+    furigana: string;
+  }[];
+  /** Word lists kept by hand, by source name, in inline notation; like place names, they fill runs no common word claims. */
+  manual: Partial<Record<ManualSource, string[]>>;
+  /** Curated default readings in inline notation, for words the data ranks wrong; pins override them. */
+  defaults: string[];
+  bare: string[];
+}
+/** A ruby annotation over characters `[start, end)` of a run. */
+interface RubySpan {
+  start: number;
+  end: number;
+  ruby: string;
+}
+/** A maximal sequence of Han characters with its reading, the unit a shaper sees. */
+interface HanRun {
+  text: string;
+  spans: RubySpan[];
+}
+export declare function isHan(char: string): boolean;
+/** Spans of a JmdictFurigana alignment; a loop, not splits, as the planner parses the 400,000 readings of the dictionary as it starts. */
+export declare function parseFurigana(furigana: string): RubySpan[];
+/**
+ * Splits a form into its Han runs. Browsers itemize text by script before
+ * shaping, so a font only ever sees one run at a time: okurigana and other
+ * kana are never visible as context. Runs with an unannotated kanji or an
+ * annotation leaking outside the run are dropped.
+ */
+export declare function hanRuns(form: string, spans: readonly RubySpan[]): HanRun[];
+/**
+ * Parses the inline notation for custom words: `日[に]本[ほん]` for one reading
+ * per kanji, `今日[きょう]` for a reading over several kanji, kana as written.
+ */
+export declare function parseNotation(notation: string): {
+  form: string;
+  spans: RubySpan[];
+};
+export declare function formatNotation(text: string, spans: readonly RubySpan[]): string;
+//#endregion
+//#region src/fuse.d.ts
+/** Spans as a JmdictFurigana alignment: `0:に;1:ほん`, `0-1:きょう`. */
+export declare function formatFurigana(spans: readonly RubySpan[]): string;
+/**
+ * Merges every source into the readings of the Han runs a font sees, each
+ * reading with its score and sources. What no plan can use is left out: a
+ * word's runs with an unannotated kanji, lone kanji of the lists or of words
+ * no list tags but before okurigana, and the on'yomi of kanji no reading uses.
+ */
+export declare function fuseDictionary(sources: DictionarySources): Dictionary;
 //#endregion
 //#region src/glyphs.d.ts
 export declare function glyphName(codepoint: number): string;
@@ -356,10 +384,10 @@ interface PlanResult {
   report: PlanReport;
 }
 /**
- * Indexes the dictionary once into Han runs, then plans fonts from it. Every
+ * Indexes the compiled dictionary once, then plans fonts from it. Every
  * decision about readings happens here: which words get ruby, which reading
  * is the default, which longer words must be protected from a shorter match.
  */
 export declare function createFontPlanner(dictionary: Dictionary): (options: PlanOptions, coverage: ReadonlySet<number>, previewText?: string) => PlanResult;
 //#endregion
-export type { Dictionary, DictionaryEntry, HanRun, Plan, PlanGlyph, PlanOptions, PlanOptionsInput, PlanReport, PlanResult, RubyMetrics, RubyScript, RubySpan };
+export type { Dictionary, DictionaryEntry, DictionarySources, HanRun, ManualSource, Plan, PlanGlyph, PlanOptions, PlanOptionsInput, PlanReport, PlanResult, Reading, RubyMetrics, RubyScript, RubySpan, Source, WordSource };