speechready 0.0.1 → 0.1.0

package/dist/profiles/index.js

@@ -0,0 +1,72 @@
+/** Provider profiles: data files that say what each TTS model accepts.
+ *
+ * The YAML files live in the repository's `spec/profiles`. The build step turns
+ * them into `data.ts` so the package needs no YAML parser at runtime. Each
+ * profile states the intent renderings, the request limit, the escaping rules
+ * and whether unknown bracket tags pass through.
+ */
+import { PROFILE_DATA } from "./data.js";
+function fromDict(data) {
+    const limit = (data.limit ?? {});
+    const lexicon = (data.lexicon ?? {});
+    const profile = {
+        id: String(data.id),
+        provider: String(data.provider),
+        models: (data.models ?? []).map(String),
+        syntax: data.syntax ?? "plain",
+        escape: data.escape ?? "none",
+        limitUnit: limit.unit ?? "chars",
+        limitMax: limit.max ?? null,
+        limitPerModel: { ...(limit.per_model ?? {}) },
+        intents: { ...(data.intents ?? {}) },
+        audioTags: Boolean(data.audio_tags ?? false),
+        lexiconFormat: String(lexicon.format ?? "none"),
+        lexiconAlphabet: String(lexicon.alphabet ?? "ipa"),
+        default: Boolean(data.default ?? false),
+        notes: data.notes ?? "",
+        sources: (data.sources ?? []).map(String),
+        verified: String(data.verified ?? ""),
+        raw: data,
+        limitFor(model) {
+            if (model && model in this.limitPerModel)
+                return this.limitPerModel[model];
+            return this.limitMax;
+        },
+    };
+    return profile;
+}
+let cache = null;
+function all() {
+    if (!cache)
+        cache = PROFILE_DATA.map(fromDict);
+    return cache;
+}
+export function listProfiles() {
+    return [...all()];
+}
+export function loadProfile(profileId) {
+    for (const p of all())
+        if (p.id === profileId)
+            return p;
+    throw new Error(`unknown profile ${JSON.stringify(profileId)}; known: ${all().map((p) => p.id).join(", ")}`);
+}
+/** Pick the profile for a provider and model. No provider = the `plain` profile. */
+export function resolveProfile(provider, model) {
+    if (!provider && !model)
+        return loadProfile("plain");
+    const matches = all().filter((p) => !provider || p.provider === provider);
+    if (model) {
+        for (const p of matches)
+            if (p.models.includes(model))
+                return p;
+        if (!provider)
+            throw new Error(`no profile lists model ${JSON.stringify(model)}`);
+    }
+    for (const p of matches)
+        if (p.default)
+            return p;
+    if (matches.length)
+        return matches[0];
+    const known = [...new Set(all().map((p) => p.provider))].sort();
+    throw new Error(`no profile for provider ${JSON.stringify(provider)}; known providers: ${known.join(", ")}`);
+}

package/dist/util.d.ts

@@ -0,0 +1,53 @@
+/** Small helpers that make the TypeScript port line up with the Python reference.
+ *
+ * Python's `re` is Unicode-aware by default: `\w` matches letters in any script
+ * and `\b` is a boundary next to them. JavaScript's `\w` and `\b` are ASCII only,
+ * so every pattern in this package is written with `W` and `B` instead and
+ * compiled with the `u` flag.
+ */
+/** Python's `\w` under Unicode: letters, digits, underscore. Use inside a character class. */
+export declare const W = "\\p{L}\\p{N}_";
+/** Python's `\b` under Unicode. */
+export declare const B = "(?:(?<=[\\p{L}\\p{N}_])(?![\\p{L}\\p{N}_])|(?<![\\p{L}\\p{N}_])(?=[\\p{L}\\p{N}_]))";
+/** Compile a pattern with the `u` flag (plus `g`, which every helper here expects). */
+export declare function re(source: string, flags?: string): RegExp;
+/** A match as the Python-style callbacks see it: `m[0]`, `m[1]`..., `m.index`, `m.groups`. */
+export type Match = RegExpExecArray;
+/** `pattern.sub(fn, text)`: every match replaced by `fn(match)`. */
+export declare function sub(pattern: RegExp, text: string, fn: (m: Match) => string): string;
+/** `pattern.sub(repl, text)` with a plain string replacement (no `$` expansion). */
+export declare function subs(pattern: RegExp, text: string, repl: string): string;
+/** First match anywhere, or null. Safe on global patterns. */
+export declare function search(pattern: RegExp, text: string): Match | null;
+/** `pattern.match(text)`: a match anchored at the start, or null. */
+export declare function matchStart(pattern: RegExp, text: string): Match | null;
+/** `re.fullmatch(pattern, text)`. */
+export declare function fullmatch(pattern: RegExp, text: string): Match | null;
+export declare function test(pattern: RegExp, text: string): boolean;
+/** All matches, in order. */
+export declare function finditer(pattern: RegExp, text: string): Match[];
+export declare function findall(pattern: RegExp, text: string): string[];
+/** `re.escape`: escape what is special in a pattern (letters are left alone, which the `u` flag requires). */
+export declare function escapeRe(s: string): string;
+export declare function group(m: Match, i: number): string | undefined;
+export declare function strip(s: string, chars?: string): string;
+export declare function lstrip(s: string, chars?: string): string;
+export declare function rstrip(s: string, chars?: string): string;
+export declare function partition(s: string, sep: string): [string, string, string];
+export declare function rpartition(s: string, sep: string): [string, string, string];
+export declare function isDigit(s: string): boolean;
+export declare function isUpper(ch: string): boolean;
+export declare function isAlpha(s: string): boolean;
+export declare function isSpace(ch: string): boolean;
+export declare function chars(s: string): string[];
+/** Python's `round()`: ties go to the even neighbour. */
+export declare function roundHalfEven(x: number): number;
+/** Python's `divmod` for non-negative integers. */
+export declare function divmod(n: number, d: number): [number, number];
+/** `str.format` for the small templates in provider profiles: `{ms}`, `{s}`, `{text}`, `{ipa}`. */
+export declare function format(template: string, values: Record<string, string | number>): string;
+export declare function escapeXml(text: string): string;
+/** `len(text.encode("utf-8"))`. */
+export declare function utf8Length(text: string): number;
+/** `len(text)` in code points, as Python counts. */
+export declare function codePoints(text: string): number;

package/dist/util.js

@@ -0,0 +1,146 @@
+/** Small helpers that make the TypeScript port line up with the Python reference.
+ *
+ * Python's `re` is Unicode-aware by default: `\w` matches letters in any script
+ * and `\b` is a boundary next to them. JavaScript's `\w` and `\b` are ASCII only,
+ * so every pattern in this package is written with `W` and `B` instead and
+ * compiled with the `u` flag.
+ */
+/** Python's `\w` under Unicode: letters, digits, underscore. Use inside a character class. */
+export const W = "\\p{L}\\p{N}_";
+/** Python's `\b` under Unicode. */
+export const B = `(?:(?<=[${W}])(?![${W}])|(?<![${W}])(?=[${W}]))`;
+/** Compile a pattern with the `u` flag (plus `g`, which every helper here expects). */
+export function re(source, flags = "") {
+    let f = flags;
+    if (!f.includes("u"))
+        f += "u";
+    if (!f.includes("g"))
+        f += "g";
+    return new RegExp(source, f);
+}
+/** `pattern.sub(fn, text)`: every match replaced by `fn(match)`. */
+export function sub(pattern, text, fn) {
+    pattern.lastIndex = 0;
+    return text.replace(pattern, (...args) => {
+        const groups = typeof args[args.length - 1] === "object" ? args.pop() : undefined;
+        args.pop(); // the whole string
+        const index = args.pop();
+        const m = args;
+        m.index = index;
+        m.groups = groups;
+        return fn(m);
+    });
+}
+/** `pattern.sub(repl, text)` with a plain string replacement (no `$` expansion). */
+export function subs(pattern, text, repl) {
+    return sub(pattern, text, () => repl);
+}
+/** First match anywhere, or null. Safe on global patterns. */
+export function search(pattern, text) {
+    pattern.lastIndex = 0;
+    const m = pattern.exec(text);
+    pattern.lastIndex = 0;
+    return m;
+}
+/** `pattern.match(text)`: a match anchored at the start, or null. */
+export function matchStart(pattern, text) {
+    const m = search(pattern, text);
+    return m && m.index === 0 ? m : null;
+}
+/** `re.fullmatch(pattern, text)`. */
+export function fullmatch(pattern, text) {
+    const anchored = new RegExp(`^(?:${pattern.source})$`, pattern.flags.replace("g", ""));
+    return anchored.exec(text);
+}
+export function test(pattern, text) {
+    return search(pattern, text) !== null;
+}
+/** All matches, in order. */
+export function finditer(pattern, text) {
+    pattern.lastIndex = 0;
+    const out = [];
+    for (const m of text.matchAll(pattern))
+        out.push(m);
+    return out;
+}
+export function findall(pattern, text) {
+    return finditer(pattern, text).map((m) => m[0]);
+}
+/** `re.escape`: escape what is special in a pattern (letters are left alone, which the `u` flag requires). */
+export function escapeRe(s) {
+    return s.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
+}
+export function group(m, i) {
+    return m[i] === undefined ? undefined : m[i];
+}
+// --- strings -----------------------------------------------------------------
+export function strip(s, chars) {
+    return rstrip(lstrip(s, chars), chars);
+}
+export function lstrip(s, chars) {
+    let i = 0;
+    while (i < s.length && (chars === undefined ? /\s/u.test(s[i]) : chars.includes(s[i])))
+        i++;
+    return s.slice(i);
+}
+export function rstrip(s, chars) {
+    let j = s.length;
+    while (j > 0 && (chars === undefined ? /\s/u.test(s[j - 1]) : chars.includes(s[j - 1])))
+        j--;
+    return s.slice(0, j);
+}
+export function partition(s, sep) {
+    const i = s.indexOf(sep);
+    return i < 0 ? [s, "", ""] : [s.slice(0, i), sep, s.slice(i + sep.length)];
+}
+export function rpartition(s, sep) {
+    const i = s.lastIndexOf(sep);
+    return i < 0 ? ["", "", s] : [s.slice(0, i), sep, s.slice(i + sep.length)];
+}
+export function isDigit(s) {
+    return s.length > 0 && /^\p{Nd}+$/u.test(s);
+}
+export function isUpper(ch) {
+    return /\p{Lu}/u.test(ch);
+}
+export function isAlpha(s) {
+    return s.length > 0 && /^\p{L}+$/u.test(s);
+}
+export function isSpace(ch) {
+    return /\s/u.test(ch);
+}
+export function chars(s) {
+    return Array.from(s);
+}
+/** Python's `round()`: ties go to the even neighbour. */
+export function roundHalfEven(x) {
+    const f = Math.floor(x);
+    const diff = x - f;
+    if (diff > 0.5)
+        return f + 1;
+    if (diff < 0.5)
+        return f;
+    return f % 2 === 0 ? f : f + 1;
+}
+/** Python's `divmod` for non-negative integers. */
+export function divmod(n, d) {
+    return [Math.floor(n / d), n % d];
+}
+/** `str.format` for the small templates in provider profiles: `{ms}`, `{s}`, `{text}`, `{ipa}`. */
+export function format(template, values) {
+    return template.replace(/\{(\w+)\}/g, (whole, key) => (key in values ? String(values[key]) : whole));
+}
+export function escapeXml(text) {
+    return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+/** `len(text.encode("utf-8"))`. */
+export function utf8Length(text) {
+    return new TextEncoder().encode(text).length;
+}
+/** `len(text)` in code points, as Python counts. */
+export function codePoints(text) {
+    let n = 0;
+    for (const _ of text)
+        n++;
+    return n;
+}

package/dist/verbalize/en.d.ts

@@ -0,0 +1,3 @@
+/** English verbalization rules, in the order they run. */
+import { Rule } from "./index.js";
+export declare const RULES: Rule[];

package/dist/verbalize/en.js

@@ -0,0 +1,219 @@
+/** English verbalization rules, in the order they run. */
+import { B, W, escapeRe, findall, fullmatch, group, isDigit, re, rpartition } from "../util.js";
+import { option, registerRules, rule } from "./index.js";
+import { cardinal, decimal, digits, ordinal, year } from "./numbers_en.js";
+const MONTHS = [
+    "January", "February", "March", "April", "May", "June", "July", "August",
+    "September", "October", "November", "December",
+];
+const DAY_FIRST_LOCALES = new Set(["en-GB", "en-AU", "en-NZ", "en-IE", "en-IN", "en-ZA"]);
+const dayFirst = (locale) => DAY_FIRST_LOCALES.has(locale);
+function dateWords(y, m, d) {
+    if (!(m >= 1 && m <= 12 && d >= 1 && d <= 31))
+        return null;
+    let yy = y;
+    if (yy < 100)
+        yy += yy < 70 ? 2000 : 1900;
+    return `${MONTHS[m - 1]} ${ordinal(d)}, ${year(yy)}`;
+}
+const int = (s) => parseInt((s ?? "").replace(/,/g, ""), 10);
+// --- dates -----------------------------------------------------------------------
+const dateIso = (m) => dateWords(int(m[1]), int(m[2]), int(m[3]));
+function dateSlash(m, locale) {
+    const a = int(m[1]);
+    const b = int(m[2]);
+    const y = int(m[3]);
+    if (dayFirst(locale))
+        return dateWords(y, b, a);
+    return dateWords(y, a, b);
+}
+const dateDot = (m) => dateWords(int(m[3]), int(m[2]), int(m[1]));
+// --- digit strings ---------------------------------------------------------------
+function digitGroups(m) {
+    const raw = m[0];
+    const count = (raw.match(/\d/g) ?? []).length;
+    if (count < 7 || count > 16)
+        return null;
+    const groups = raw.split(/[\s.\-()]+/u).filter((g) => g);
+    return groups.map(digits).join(", ");
+}
+const longDigits = (m) => digits(m[0]);
+// --- time ----------------------------------------------------------------------------
+function time(m) {
+    const hour = m[1];
+    const minute = m[2];
+    const suffix = group(m, 3);
+    if (suffix)
+        return null; // "2:30 pm" is read correctly as it stands
+    const h = parseInt(hour, 10);
+    if (h >= 13)
+        return `${h - 12}:${minute} PM`;
+    if (h === 0)
+        return `12:${minute} AM`;
+    if (hour.startsWith("0"))
+        return `${h}:${minute} AM`;
+    return null;
+}
+// --- currency --------------------------------------------------------------------------
+const CURRENCY = {
+    $: ["dollar", "dollars", "cent", "cents"],
+    "€": ["euro", "euros", "cent", "cents"],
+    "£": ["pound", "pounds", "penny", "pence"],
+    "¥": ["yen", "yen", null, null],
+    "₺": ["lira", "lira", "kuruş", "kuruş"],
+    USD: ["dollar", "dollars", "cent", "cents"],
+    EUR: ["euro", "euros", "cent", "cents"],
+    GBP: ["pound", "pounds", "penny", "pence"],
+    TRY: ["lira", "lira", "kuruş", "kuruş"],
+    TL: ["lira", "lira", "kuruş", "kuruş"],
+};
+const MAGNITUDE = {
+    k: "thousand", m: "million", bn: "billion", b: "billion", thousand: "thousand", million: "million", billion: "billion",
+};
+function moneyWords(symbol, whole, frac, magnitude) {
+    const [one, many, centOne, centMany] = CURRENCY[symbol];
+    const amount = int(whole);
+    if (magnitude)
+        return `${decimal(whole, frac)} ${MAGNITUDE[magnitude.toLowerCase()]} ${many}`;
+    if (frac !== undefined && centOne) {
+        const cents = parseInt(frac.padEnd(2, "0").slice(0, 2), 10);
+        const main = amount === 0 ? "" : `${cardinal(amount)} ${amount === 1 ? one : many}`;
+        if (cents === 0)
+            return main || `zero ${many}`;
+        const tail = `${cardinal(cents)} ${cents === 1 ? centOne : centMany}`;
+        return main ? `${main} and ${tail}` : tail;
+    }
+    if (frac !== undefined)
+        return `${decimal(whole, frac)} ${many}`;
+    return `${cardinal(amount)} ${amount === 1 ? one : many}`;
+}
+function currencyRange(m) {
+    const [, many] = CURRENCY[m[1]];
+    return `${cardinal(int(m[2]))} to ${cardinal(int(m[3]))} ${many}`;
+}
+const currencyPrefix = (m) => moneyWords(m[1], m[2], group(m, 3), group(m, 4));
+const currencyCode = (m) => moneyWords(m[3].toUpperCase(), m[1], group(m, 2), undefined);
+// --- percent, units, fractions, ranges ----------------------------------------------------
+const UNITS = {
+    "km/h": ["kilometer per hour", "kilometers per hour"],
+    km: ["kilometer", "kilometers"],
+    cm: ["centimeter", "centimeters"],
+    mm: ["millimeter", "millimeters"],
+    kg: ["kilogram", "kilograms"],
+    mg: ["milligram", "milligrams"],
+    lbs: ["pound", "pounds"],
+    lb: ["pound", "pounds"],
+    oz: ["ounce", "ounces"],
+    mph: ["mile per hour", "miles per hour"],
+    mi: ["mile", "miles"],
+    ft: ["foot", "feet"],
+    GB: ["gigabyte", "gigabytes"],
+    MB: ["megabyte", "megabytes"],
+    KB: ["kilobyte", "kilobytes"],
+    TB: ["terabyte", "terabytes"],
+    ms: ["millisecond", "milliseconds"],
+    min: ["minute", "minutes"],
+    hrs: ["hour", "hours"],
+    hr: ["hour", "hours"],
+    kWh: ["kilowatt hour", "kilowatt hours"],
+    kHz: ["kilohertz", "kilohertz"],
+    MHz: ["megahertz", "megahertz"],
+    GHz: ["gigahertz", "gigahertz"],
+    Hz: ["hertz", "hertz"],
+    fps: ["frame per second", "frames per second"],
+    "°C": ["degree Celsius", "degrees Celsius"],
+    "°F": ["degree Fahrenheit", "degrees Fahrenheit"],
+    "°": ["degree", "degrees"],
+};
+const UNIT_ALTERNATION = Object.keys(UNITS).sort((a, b) => b.length - a.length).map(escapeRe).join("|");
+function unit(m) {
+    const number = m[1];
+    const [one, many] = UNITS[m[2]];
+    const isOne = number === "1" || number === "1.0";
+    return `${number} ${isOne ? one : many}`;
+}
+const FRACTIONS = {
+    2: ["half", "halves"], 3: ["third", "thirds"], 4: ["quarter", "quarters"],
+    5: ["fifth", "fifths"], 8: ["eighth", "eighths"], 10: ["tenth", "tenths"],
+};
+function fraction(m) {
+    const num = parseInt(m[1], 10);
+    const den = parseInt(m[2], 10);
+    if (num >= den)
+        return null;
+    if (option("fractions", "spoken") === "division")
+        return `${cardinal(num)} over ${cardinal(den)}`;
+    if (!(den in FRACTIONS))
+        return null;
+    const [one, many] = FRACTIONS[den];
+    return `${cardinal(num)} ${num === 1 ? one : many}`;
+}
+const YEAR_LIKE = re(String.raw `(19|20)\d\d`);
+function range(m) {
+    const a = m[1];
+    const b = m[2];
+    const short = a.replace(/\./g, "").length <= 3 && b.replace(/\./g, "").length <= 3;
+    const years = fullmatch(YEAR_LIKE, a) && fullmatch(YEAR_LIKE, b);
+    if (!(short || years))
+        return null;
+    return `${a} to ${b}`;
+}
+// --- years and ordinals -----------------------------------------------------------------------
+const yearInContext = (m) => `${m[1]} ${year(parseInt(m[2], 10))}`;
+function decade(m) {
+    const words = year(parseInt(m[1], 10));
+    const [head, , last] = rpartition(words, " ");
+    const plural = last.endsWith("y") ? last.slice(0, -1) + "ies" : last + "s";
+    return (head ? head + " " : "") + plural;
+}
+const ordinalRule = (m) => ordinal(parseInt(m[1], 10));
+// --- alphanumeric identifiers ------------------------------------------------------------------
+const VOWELS = new Set("AEIOUY");
+const RUNS = re("[A-Z]+|\\d+");
+function alnum(m) {
+    const token = m[0];
+    if (token.replace(/-/g, "").length < 4)
+        return null;
+    const out = [];
+    const runs = findall(RUNS, token);
+    for (const run of runs) {
+        if (isDigit(run))
+            out.push(runs.length === 2 && run.length <= 2 ? cardinal(parseInt(run, 10)) : digits(run));
+        else if (run.length >= 3 && Array.from(run).some((c) => VOWELS.has(c)))
+            out.push(run);
+        else
+            out.push(Array.from(run).join(" "));
+    }
+    return out.join(" ");
+}
+// a separator inside a phone number: space, dash, or a dot that is not followed by whitespace
+const SEP = String.raw `(?:[ \-]|\.(?!\s))`;
+const timeRange = (m) => `${m[1]} to ${m[2]}`;
+const PER = {
+    mo: "month", month: "month", yr: "year", year: "year", hr: "hour", hour: "hour",
+    min: "minute", minute: "minute", day: "day", week: "week", wk: "week",
+};
+export const RULES = [
+    rule("verbalize.date.iso", re(String.raw `${B}(\d{4})-(\d{2})-(\d{2})${B}`), dateIso, "ISO date read as month, day, year"),
+    rule("verbalize.date.slash", re(String.raw `${B}(\d{1,2})/(\d{1,2})/(\d{2}|\d{4})${B}`), dateSlash, "numeric date read in the locale's order"),
+    rule("verbalize.date.dot", re(String.raw `${B}(\d{1,2})\.(\d{1,2})\.(\d{4})${B}`), dateDot, "dotted date read as day, month, year"),
+    rule("verbalize.phone", re(String.raw `(?<![${W}.])(?:\+?\d{1,3}${SEP})?(?:\(\d{2,4}\)[ \-]?|\d{2,4}${SEP})(?:\d{2,4}${SEP}){1,4}\d{2,4}(?![${W}\-]|[.,]\d)`), digitGroups, "digit groups read digit by digit with a pause between groups"),
+    rule("verbalize.number_sign", re(String.raw `#(?=\d)`), () => "number ", "number sign read as a word"),
+    rule("verbalize.digits.long", re(String.raw `(?<![${W}.,])\d{7,}(?![${W}]|[.,]\d)`), longDigits, "long digit string read digit by digit"),
+    rule("verbalize.time.range", re(String.raw `${B}(\d{1,2}:\d{2})\s?[-–]\s?(\d{1,2}:\d{2})${B}`), timeRange, "time range read with 'to'"),
+    rule("verbalize.time", re(String.raw `${B}([01]?\d|2[0-3]):([0-5]\d)${B}(?!:)(?:\s?(am|pm|AM|PM|a\.m\.|p\.m\.))?`), time, "24-hour time read as 12-hour"),
+    rule("verbalize.currency.range", re(String.raw `([$€£¥₺])\s?(\d[\d,]*)\s?[-–]\s?[$€£¥₺]?\s?(\d[\d,]*)(?![\d]|[.,]\d)`), currencyRange, "currency range read as words"),
+    rule("verbalize.currency", re(String.raw `([$€£¥₺])\s?(\d[\d,]*)(?:\.(\d{1,2}))?\s?(k|K|m|M|bn|B|thousand|million|billion)?(?![${W}]|[.,]\d)`), currencyPrefix, "currency amount read as words"),
+    rule("verbalize.currency.code", re(String.raw `(?<![${W}.])(\d[\d,]*)(?:\.(\d{1,2}))?\s?(USD|EUR|GBP|TRY|TL)${B}`), currencyCode, "currency code read as words"),
+    rule("verbalize.per", re(String.raw `${B}(dollars?|cents?|euros?|pounds?|\d)/(mo|month|yr|year|hr|hour|min|minute|day|week|wk)${B}`), (m) => `${m[1]} per ${PER[m[2]]}`, "slash before a period read as 'per'"),
+    rule("verbalize.percent", re(String.raw `(?<![${W}.])(\d+(?:\.\d+)?)\s?%|%\s?(\d+(?:\.\d+)?)`), (m) => `${group(m, 1) ?? group(m, 2)} percent`, "percent sign read as a word"),
+    rule("verbalize.unit", re(String.raw `(?<![${W}.])(\d+(?:\.\d+)?)\s?(${UNIT_ALTERNATION})(?![${W}/])`), unit, "unit abbreviation read as a word"),
+    rule("verbalize.fraction", re(String.raw `(?<![\d/])([1-9])/([2-9]|10)(?![\d/])`), fraction, "fraction read as words"),
+    rule("verbalize.range", re(String.raw `(?<![${W}.,\-/:])(\d+(?:\.\d+)?)\s?[-–]\s?(\d+(?:\.\d+)?)(?![${W}\-/:]|[.,]\d)`), range, "number range read with 'to'"),
+    rule("verbalize.year", re(String.raw `${B}(in|In|since|Since|by|from|until|till|before|after|during|circa|year|est\.|©)\s+(1[1-9]\d\d|20\d\d)${B}(?![${W}.,]?\d)`), yearInContext, "year read as a year"),
+    rule("verbalize.decade", re(String.raw `${B}(1[1-9]\d0|20\d0)s${B}`), decade, "decade read as a year"),
+    rule("verbalize.ordinal", re(String.raw `${B}(\d{1,4})(?:st|nd|rd|th)${B}`), ordinalRule, "ordinal read as words"),
+    rule("verbalize.minus", re(String.raw `(?<![${W}.)\-–])[-–](?=\d)`), () => "minus ", "leading minus read as a word"),
+    rule("verbalize.alnum", re(String.raw `${B}(?=[A-Z0-9-]*\d)(?=[A-Z0-9-]*[A-Z])[A-Z0-9]+(?:-[A-Z0-9]+)*${B}`), alnum, "identifier spelled out"),
+];
+registerRules("en", RULES);

package/dist/verbalize/index.d.ts

@@ -0,0 +1,22 @@
+/** Stage 2: verbalize. Rewrite only the tokens a TTS model is likely to misread.
+ *
+ * Each language has an ordered list of rules. A rule is a regex and a function
+ * that returns the spoken form; it fires only on the pattern, so ordinary prose
+ * and ordinary numbers are left for the model, which reads them well.
+ * Sentinels from the intent stage are never touched.
+ */
+import { Recorder } from "../changes.js";
+import { Options } from "../clean.js";
+import { Match } from "../util.js";
+export interface Rule {
+    id: string;
+    pattern: RegExp;
+    /** (match, locale) -> replacement, or null to leave the match alone */
+    render: (m: Match, locale: string) => string | null;
+    note: string;
+}
+export declare function rule(id: string, pattern: RegExp, render: Rule["render"], note?: string): Rule;
+/** Read a field of the Options the current verbalize() call runs with. */
+export declare function option<K extends keyof Options>(name: K, fallback: Options[K]): Options[K];
+export declare function registerRules(lang: string, rules: Rule[]): void;
+export declare function verbalize(text: string, locale?: string, recorder?: Recorder, opts?: Partial<Options> | null): string;

package/dist/verbalize/index.js

@@ -0,0 +1,75 @@
+/** Stage 2: verbalize. Rewrite only the tokens a TTS model is likely to misread.
+ *
+ * Each language has an ordered list of rules. A rule is a regex and a function
+ * that returns the spoken form; it fires only on the pattern, so ordinary prose
+ * and ordinary numbers are left for the model, which reads them well.
+ * Sentinels from the intent stage are never touched.
+ */
+import { Recorder } from "../changes.js";
+import { SENTINEL_CLOSE, SENTINEL_OPEN } from "../intents.js";
+import { finditer, re, sub } from "../util.js";
+const STAGE = "verbalize";
+export function rule(id, pattern, render, note = "") {
+    return { id, pattern, render, note };
+}
+const SENTINEL = re(`${SENTINEL_OPEN}\\d+${SENTINEL_CLOSE}`);
+let currentOptions = null;
+/** Read a field of the Options the current verbalize() call runs with. */
+export function option(name, fallback) {
+    const o = currentOptions;
+    return o && o[name] !== undefined ? o[name] : fallback;
+}
+let rulesEn = null;
+let rulesTr = null;
+export function registerRules(lang, rules) {
+    if (lang === "en")
+        rulesEn = rules;
+    else if (lang === "tr")
+        rulesTr = rules;
+}
+function rulesFor(locale) {
+    const lang = (locale || "en").split("-")[0].split("_")[0].toLowerCase();
+    if (lang === "en")
+        return rulesEn ?? [];
+    if (lang === "tr")
+        return rulesTr ?? [];
+    return [];
+}
+export function verbalize(text, locale = "en-US", recorder, opts) {
+    const rec = recorder ?? new Recorder();
+    const rules = rulesFor(locale);
+    if (!rules.length)
+        return text;
+    const previous = currentOptions;
+    currentOptions = opts;
+    try {
+        return run(text, rules, locale, rec);
+    }
+    finally {
+        currentOptions = previous;
+    }
+}
+function run(text, rules, locale, rec) {
+    const sentinels = finditer(SENTINEL, text).map((m) => m[0]);
+    const parts = text.split(SENTINEL);
+    const out = [];
+    parts.forEach((segment, i) => {
+        out.push(apply(segment, rules, locale, rec));
+        if (i < sentinels.length)
+            out.push(sentinels[i]);
+    });
+    return out.join("");
+}
+function apply(segment, rules, locale, rec) {
+    let work = segment;
+    for (const r of rules) {
+        work = sub(r.pattern, work, (m) => {
+            const next = r.render(m, locale);
+            if (next === null || next === undefined || next === m[0])
+                return m[0];
+            rec.add(STAGE, r.id, m[0], next, r.note);
+            return next;
+        });
+    }
+    return work;
+}

package/dist/verbalize/numbers_en.d.ts

@@ -0,0 +1,8 @@
+/** English number words: cardinals, ordinals, years, digit strings. */
+export declare function cardinal(n: number): string;
+export declare function ordinal(n: number): string;
+/** Spoken year: 1999 -> nineteen ninety-nine, 2005 -> two thousand five, 2026 -> twenty twenty-six. */
+export declare function year(n: number): string;
+/** Each digit as a word; non-digits pass through as their spoken form where known. */
+export declare function digits(s: string): string;
+export declare function decimal(whole: string, frac: string | null | undefined): string;