speechready 0.0.0-stage → 0.1.0

package/dist/clean.js

@@ -0,0 +1,323 @@
+/** Stage 1: clean. Turn markdown, code, emoji, URLs and invisible Unicode into plain prose.
+ *
+ * Block structure is preserved as one block per line: headings, paragraphs,
+ * list items and table rows each become a line, and a block that ends without
+ * terminal punctuation gets a full stop so the model pauses after it. Hard-wrapped
+ * lines inside a paragraph are joined with a space.
+ */
+import { Recorder } from "./changes.js";
+import { SENTINEL_CLOSE } from "./intents.js";
+import { W, escapeRe, isDigit, matchStart, re, rstrip, sub, test } from "./util.js";
+const STAGE = "clean";
+export const DEFAULT_OPTIONS = Object.freeze({
+    code_blocks: "drop",
+    code_block_mention: null,
+    tables: "rows",
+    urls: "domain",
+    emails: "keep",
+    emoji: "drop",
+    emphasis: "strip",
+    list_numbers: "keep",
+    strip_tags: ["think", "thinking", "reasoning"],
+    terminal_punctuation: ".",
+    html: "strip",
+    fractions: "spoken",
+    foreign_acronyms: true,
+    extra: {},
+});
+/** Fill in defaults. Unknown keys throw, so a camelCase typo is not silently ignored. */
+export function options(partial) {
+    if (!partial)
+        return DEFAULT_OPTIONS;
+    for (const key of Object.keys(partial)) {
+        if (!(key in DEFAULT_OPTIONS)) {
+            throw new TypeError(`unknown option ${JSON.stringify(key)}; options use the same snake_case names as the Python package: ${Object.keys(DEFAULT_OPTIONS).join(", ")}`);
+        }
+    }
+    return { ...DEFAULT_OPTIONS, ...partial };
+}
+// what `code_blocks: "mention"` says in place of a fenced block, by language
+const MENTION = { en: "See the code block.", tr: "Kod bloğuna bakın." };
+const TERMINAL = ".!?…:;,";
+const CLOSERS = "\"'”’)]»";
+const ZERO_WIDTH = re("[​‌‍⁠­]");
+const SPACES = re("[           　]");
+const CONTROL = re("[\\x00-\\x08\\x0b\\x0c\\x0e-\\x1f\\x7f]");
+const FENCE = re(String.raw `^\s*(${"```"}|~~~)`);
+const HEADING = re(String.raw `^\s{0,3}(#{1,6})\s+(.*?)\s*#*\s*$`);
+const SETEXT = re(String.raw `^\s{0,3}(=+|-+)\s*$`);
+const HR = re(String.raw `^\s{0,3}([-*_])(\s*\1){2,}\s*$`);
+const LIST = re(String.raw `^(\s*)([-*+•]|\d{1,3}[.)])\s+(.*)$`);
+const TASK = re(String.raw `^\[( |x|X)\]\s+`);
+const QUOTE = re(String.raw `^\s{0,3}>\s?`);
+const TABLE_SEP = re(String.raw `^\s*\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)*\|?\s*$`);
+const TABLE_ROW = re(String.raw `^\s*\|.*\|\s*$`);
+const IMAGE = re(String.raw `!\[([^\]]*)\]\([^)]*\)`);
+const LINK = re(String.raw `\[([^\]]+)\]\(\s*<?([^)\s>]*)>?(?:\s+"[^"]*")?\s*\)`);
+const AUTOLINK = re(String.raw `<((?:https?|mailto):[^>\s]+)>`);
+const REF_LINK = re(String.raw `\[([^\]]+)\]\[[^\]]*\]`);
+const CODE_SPAN = re(String.raw `(${"`"}+)(.+?)\1`);
+const BOLD = re(String.raw `(\*\*|__)(?=\S)(.+?)(?<=\S)\1`);
+const ITALIC = re(String.raw `(?<![${W}*])(\*|_)(?=\S)(.+?)(?<=\S)\1(?![${W}*])`);
+const STRIKE = re(String.raw `~~(?=\S)(.+?)(?<=\S)~~`);
+const ESCAPE = re(String.raw `\\([\\${"`"}*_{}\[\]()#+\-.!>~|])`);
+const HTML_TAG = re(String.raw `</?[A-Za-z][A-Za-z0-9-]*(?:\s[^<>]*)?/?>`);
+const URL = re(String.raw `(?<![${W}@/])(?:https?://|www\.)([^\s<>()"']+)`);
+const EMAIL = re(String.raw `[${W}.+-]+@[${W}-]+(?:\.[${W}-]+)+`);
+const FOOTNOTE = re(String.raw `\[\^[^\]]+\]`);
+// a backslash-escaped marker is swapped for a private-use character while the
+// markdown rules run, so it can never be read as markdown, and swapped back after
+const ESCAPABLE = "\\`*_{}[]()#+-.!>~|";
+const ESC_TO_PUA = new Map(Array.from(ESCAPABLE).map((c, i) => [c, String.fromCharCode(0xe100 + i)]));
+const PUA_TO_ESC = new Map(Array.from(ESC_TO_PUA.entries()).map(([k, v]) => [v, k]));
+const PUA_RANGE = re("[-]");
+// Emoji and pictographs: symbols (So), variation selectors, ZWJ, skin tones, keycaps, flags.
+const EMOJI = re("(?:[\\u{1F000}-\\u{1FAFF}\\u2600-\\u27BF\\u2B00-\\u2BFF\\u{1F1E6}-\\u{1F1FF}\\uFE0F\\u200D\\u20E3\\u{1F3FB}-\\u{1F3FF}]|[\\u2190-\\u21FF])+");
+// Other pictographic symbols in the U+2000-U+32FF blocks, except letterlike symbols (U+2100-U+214F).
+const SYMBOLS = re("(?:(?=[\\u2000-\\u20FF\\u2150-\\u32FF])\\p{So})+");
+/** Run the clean stage on `text`; returns the cleaned text and records changes.
+ *
+ * `locale` only picks the sentence that `{code_blocks: "mention"}` speaks.
+ */
+export function clean(text, opts, recorder, locale = "en-US") {
+    const o = options(opts);
+    const rec = recorder ?? new Recorder();
+    let work = unicode(text, rec);
+    work = stripReasoning(work, o, rec);
+    const blocks = splitBlocks(work, o, rec, locale);
+    let lines = blocks.map((b) => inline(b, o, rec));
+    lines = lines.filter((l) => l.trim()).map((l) => terminate(l, o, rec));
+    return lines.join("\n");
+}
+// --- character level ---------------------------------------------------------
+function unicode(text, rec) {
+    let out = text.normalize("NFC");
+    out = out.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+    out = sub(ZERO_WIDTH, out, () => "");
+    out = sub(SPACES, out, () => " ");
+    out = sub(CONTROL, out, () => "");
+    if (out !== text)
+        rec.add(STAGE, "clean.unicode.invisible", text, out, "removed invisible or non-standard whitespace characters");
+    return out;
+}
+function stripReasoning(text, o, rec) {
+    let work = text;
+    for (const tag of o.strip_tags) {
+        const pattern = re(`<${escapeRe(tag)}${B_WORD}[^>]*>[\\s\\S]*?</${escapeRe(tag)}\\s*>`, "i");
+        const next = sub(pattern, work, () => "");
+        if (next !== work) {
+            rec.add(STAGE, `clean.tags.${tag}`, work, next, `dropped <${tag}> block`);
+            work = next;
+        }
+    }
+    return work;
+}
+const B_WORD = `(?![${W}])`; // `\b` right after a tag name
+// --- block level ---------------------------------------------------------------
+/** Split markdown into blocks: one string per heading, paragraph, list item, table row. */
+function splitBlocks(text, o, rec, locale) {
+    const blocks = [];
+    let para = [];
+    let inFence = false;
+    let lastWasList = false;
+    let fenceLines = [];
+    const lines = text.split("\n");
+    const flush = () => {
+        if (para.length) {
+            blocks.push(para.map((s) => s.trim()).join(" "));
+            para = [];
+        }
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const raw = lines[i];
+        let line = raw;
+        if (matchStart(FENCE, line)) {
+            if (inFence) {
+                inFence = false;
+                const body = fenceLines.join("\n");
+                if (o.code_blocks === "keep") {
+                    blocks.push(...fenceLines.filter((s) => s.trim()));
+                    rec.add(STAGE, "clean.markdown.code_block", "```\n" + body + "\n```", body, "kept code block as plain lines");
+                }
+                else if (o.code_blocks === "mention") {
+                    const said = o.code_block_mention || MENTION[locale.split("-")[0].toLowerCase()] || MENTION.en;
+                    blocks.push(said);
+                    rec.add(STAGE, "clean.markdown.code_block", "```\n" + body + "\n```", said, "code block replaced by a mention");
+                }
+                else {
+                    rec.add(STAGE, "clean.markdown.code_block", "```\n" + body + "\n```", "", "dropped code block");
+                }
+                fenceLines = [];
+            }
+            else {
+                flush();
+                inFence = true;
+            }
+            continue;
+        }
+        if (inFence) {
+            fenceLines.push(line);
+            continue;
+        }
+        const quoted = matchStart(QUOTE, line);
+        if (quoted) {
+            line = line.slice(quoted[0].length);
+            rec.add(STAGE, "clean.markdown.blockquote", raw, line, "removed blockquote marker");
+        }
+        if (!line.trim()) {
+            flush();
+            continue;
+        }
+        if (matchStart(HR, line)) {
+            flush();
+            rec.add(STAGE, "clean.markdown.rule", line, "", "dropped horizontal rule");
+            continue;
+        }
+        if (matchStart(SETEXT, line) && para.length) {
+            // underline under a paragraph line = setext heading
+            const heading = para.map((s) => s.trim()).join(" ");
+            para = [];
+            blocks.push(heading);
+            rec.add(STAGE, "clean.markdown.heading", `${heading}\n${line}`, heading, "setext heading to plain line");
+            continue;
+        }
+        const h = matchStart(HEADING, line);
+        if (h) {
+            flush();
+            blocks.push(h[2]);
+            rec.add(STAGE, "clean.markdown.heading", line, h[2], "heading marker removed");
+            continue;
+        }
+        if (matchStart(TABLE_SEP, line)) {
+            flush();
+            rec.add(STAGE, "clean.markdown.table", line, "", "dropped table separator row");
+            continue;
+        }
+        if (matchStart(TABLE_ROW, line)) {
+            flush();
+            if (o.tables === "drop") {
+                rec.add(STAGE, "clean.markdown.table", line, "", "dropped table row");
+                continue;
+            }
+            const inner = line.trim().replace(/^\|+/, "").replace(/\|+$/, "");
+            const cells = inner.split("|").map((c) => c.trim());
+            const row = cells.filter((c) => c).join(", ");
+            blocks.push(row);
+            rec.add(STAGE, "clean.markdown.table", line, row, "table row read as a comma list");
+            continue;
+        }
+        let li = matchStart(LIST, line);
+        if (li && isDigit(li[2].slice(0, -1)) && li[2].slice(0, -1) !== "1" && !lastWasList) {
+            // "3. madde" at the start of a text is an ordinal, not a list that begins at three:
+            // a numbered item counts as a list only when it starts at 1, continues a list,
+            // or is followed by another numbered item.
+            const nxt = lines.slice(i + 1).find((l) => l.trim()) ?? "";
+            const m2 = matchStart(LIST, nxt);
+            if (!(m2 && isDigit(m2[2].slice(0, -1))))
+                li = null;
+        }
+        if (li) {
+            flush();
+            lastWasList = true;
+            let item = li[3];
+            const task = matchStart(TASK, item);
+            if (task)
+                item = item.slice(task[0].length);
+            const marker = li[2];
+            if (isDigit(marker.slice(0, -1)) && o.list_numbers === "keep") {
+                item = `${marker.slice(0, -1)}. ${item}`;
+                rec.add(STAGE, "clean.markdown.list", line, item, "numbered item kept with its number");
+            }
+            else {
+                rec.add(STAGE, "clean.markdown.list", line, item, "list marker removed");
+            }
+            blocks.push(item);
+            continue;
+        }
+        para.push(line);
+        lastWasList = false;
+    }
+    flush();
+    if (inFence && fenceLines.length) {
+        // unterminated fence: treat as dropped code
+        rec.add(STAGE, "clean.markdown.code_block", fenceLines.join("\n"), "", "dropped unterminated code block");
+    }
+    return blocks;
+}
+// --- inline level ---------------------------------------------------------------
+function inline(block, o, rec) {
+    let text = block;
+    const apply = (pattern, repl, rule, note) => {
+        const next = sub(pattern, text, repl);
+        if (next !== text) {
+            rec.add(STAGE, rule, text, next, note);
+            text = next;
+        }
+    };
+    // protect backslash escapes so an escaped marker is never read as markdown
+    text = sub(ESCAPE, text, (m) => ESC_TO_PUA.get(m[1]) ?? m[0]);
+    apply(IMAGE, (m) => m[1], "clean.markdown.image", "image replaced by its alt text");
+    apply(LINK, (m) => m[1], "clean.markdown.link", "link replaced by its text");
+    apply(REF_LINK, (m) => m[1], "clean.markdown.link", "reference link replaced by its text");
+    apply(AUTOLINK, (m) => m[1], "clean.markdown.link", "autolink brackets removed");
+    apply(FOOTNOTE, () => "", "clean.markdown.footnote", "footnote marker removed");
+    apply(CODE_SPAN, (m) => m[2], "clean.markdown.code_span", "inline code backticks removed");
+    apply(STRIKE, (m) => m[1], "clean.markdown.emphasis", "strikethrough markers removed");
+    if (o.emphasis === "intent") {
+        apply(BOLD, (m) => `[em ${m[2]}]`, "clean.markdown.emphasis", "bold turned into an emphasis intent");
+        apply(ITALIC, (m) => `[em ${m[2]}]`, "clean.markdown.emphasis", "italic turned into an emphasis intent");
+    }
+    else {
+        apply(BOLD, (m) => m[2], "clean.markdown.emphasis", "bold markers removed");
+        apply(ITALIC, (m) => m[2], "clean.markdown.emphasis", "italic markers removed");
+    }
+    if (test(PUA_RANGE, text)) {
+        const next = sub(PUA_RANGE, text, (m) => PUA_TO_ESC.get(m[0]) ?? m[0]);
+        rec.add(STAGE, "clean.markdown.escape", block, next, "backslash escape removed");
+        text = next;
+    }
+    if (o.html === "strip")
+        apply(HTML_TAG, () => "", "clean.html.tag", "HTML tag removed");
+    if (o.emails === "drop")
+        apply(EMAIL, () => "", "clean.email", "email address dropped");
+    if (o.urls === "domain")
+        apply(URL, domainOf, "clean.url", "URL reduced to its domain");
+    else if (o.urls === "drop")
+        apply(URL, () => "", "clean.url", "URL dropped");
+    if (o.emoji === "drop") {
+        apply(EMOJI, () => "", "clean.emoji", "emoji removed");
+        apply(SYMBOLS, () => "", "clean.emoji", "pictographic symbol removed");
+    }
+    text = whitespace(text);
+    return text;
+}
+function domainOf(m) {
+    const rest = m[1];
+    let host = rest.split("/", 1)[0].split("?", 1)[0].split("#", 1)[0];
+    const at = host.split("@");
+    host = at[at.length - 1].split(":")[0];
+    return host;
+}
+function whitespace(text) {
+    let t = text.replace(/[ \t]+/g, " ");
+    t = t.replace(/ ([,.;:!?])(?!\d)/gu, "$1"); // "word ." -> "word."
+    t = t.replace(/\( /g, "(");
+    t = t.replace(/ \)/g, ")");
+    return t.trim();
+}
+/** A block that ends without punctuation gets a full stop so the model pauses after it. */
+function terminate(line, o, rec) {
+    if (!o.terminal_punctuation)
+        return line;
+    const stripped = rstrip(line, CLOSERS + " ");
+    if (!stripped)
+        return line;
+    const last = stripped[stripped.length - 1];
+    if (TERMINAL.includes(last) || last === SENTINEL_CLOSE)
+        return line;
+    if ("-–—".includes(last))
+        return line;
+    const next = line + o.terminal_punctuation;
+    rec.add(STAGE, "clean.block.terminal", line, next, "added a full stop at the end of a block");
+    return next;
+}

package/dist/compile.d.ts

@@ -0,0 +1,5 @@
+/** Stage 3: compile. Render pacing intents in the target provider's syntax and escape text. */
+import { Recorder } from "./changes.js";
+import { Intent } from "./intents.js";
+import { Profile } from "./profiles/index.js";
+export declare function compileText(text: string, intents: Intent[], profile: Profile, recorder?: Recorder): string;

package/dist/compile.js

@@ -0,0 +1,116 @@
+/** Stage 3: compile. Render pacing intents in the target provider's syntax and escape text. */
+import { Recorder } from "./changes.js";
+import { splitOnSentinels } from "./intents.js";
+import { escapeXml, format, fullmatch, isSpace, re, rstrip, sub } from "./util.js";
+const STAGE = "compile";
+const UNKNOWN_TAG = re(String.raw `\[([^\[\]\n]{1,60})\]`);
+const WORDY = re("[A-Za-zÀ-ÿĞğİıŞşÇçÖöÜü ,'\\-]+");
+function spec(profile, name) {
+    return (profile.intents[name] ?? {});
+}
+/** Render a pause as punctuation. `prev` is the text so far (used to avoid doubling). */
+function punctuationPause(prev, ms) {
+    const tail = rstrip(prev);
+    if (!tail)
+        return ""; // a pause before any text: nothing to pause after
+    const last = tail[tail.length - 1];
+    if (ms <= 300) {
+        if (".!?,;:…".includes(last))
+            return " ";
+        return ", ";
+    }
+    if (".!?…".includes(last))
+        return ms <= 1000 ? " " : "\n";
+    if (ms <= 1000)
+        return "... ";
+    return "...\n";
+}
+function renderPause(ms, s, prev) {
+    const render = s.render ?? "punctuation";
+    if (render === "punctuation")
+        return punctuationPause(prev, ms);
+    const lo = s.min_ms ?? 0;
+    const hi = s.max_ms;
+    let v = Math.max(ms, lo);
+    if (hi !== undefined && hi !== null)
+        v = Math.min(v, hi);
+    const seconds = String(v / 1000);
+    return format(render, { ms: v, s: seconds });
+}
+function renderSpell(text, s) {
+    const render = s.render ?? "spaced";
+    if (render === "spaced")
+        return Array.from(text).filter((ch) => !isSpace(ch)).map((ch) => ch.toUpperCase()).join(" ");
+    return format(render, { text });
+}
+function renderEm(text, s) {
+    const render = s.render ?? "{text}";
+    return format(render, { text });
+}
+/** Phoneme tag where the provider takes one, else the respelling, else the word. */
+function renderPhoneme(intent, profile) {
+    const esc = profile.escape === "xml" ? escapeXml : (t) => t;
+    const s = spec(profile, "phoneme");
+    if (intent.ipa && s.render)
+        return format(s.render, { text: esc(intent.text), ipa: esc(intent.ipa) });
+    if (intent.say)
+        return esc(intent.say);
+    return esc(intent.text);
+}
+export function compileText(text, intents, profile, recorder) {
+    const rec = recorder ?? new Recorder();
+    const out = [];
+    for (const [segment, idx] of splitOnSentinels(text)) {
+        if (idx === null) {
+            let seg = unknownTags(segment, profile, rec);
+            if (profile.escape === "xml") {
+                const esc = escapeXml(seg);
+                rec.add(STAGE, "compile.escape.xml", seg, esc, "escaped & < > for SSML");
+                seg = esc;
+            }
+            out.push(seg);
+            continue;
+        }
+        const intent = intents[idx];
+        const prev = out.join("");
+        let rendered;
+        if (intent.kind === "pause") {
+            rendered = renderPause(intent.ms, spec(profile, "pause"), prev);
+            if (out.length && (rendered.startsWith(",") || rendered.startsWith(".")) && prev.endsWith(" ")) {
+                out[out.length - 1] = rstrip(out[out.length - 1], " ");
+            }
+            rec.add(STAGE, "compile.pause", `[pause ${intent.ms}ms]`, rendered, `pause rendered for ${profile.id}`);
+        }
+        else if (intent.kind === "phoneme") {
+            rendered = renderPhoneme(intent, profile);
+            rec.add(STAGE, "compile.phoneme", intent.text, rendered, `pronunciation rendered for ${profile.id}`);
+        }
+        else if (intent.kind === "spell") {
+            const body = profile.escape === "xml" ? escapeXml(intent.text) : intent.text;
+            rendered = renderSpell(body, spec(profile, "spell"));
+            rec.add(STAGE, "compile.spell", `[spell ${intent.text}]`, rendered, `spell-out rendered for ${profile.id}`);
+        }
+        else {
+            const body = profile.escape === "xml" ? escapeXml(intent.text) : intent.text;
+            rendered = renderEm(body, spec(profile, "emphasis"));
+            rec.add(STAGE, "compile.emphasis", `[em ${intent.text}]`, rendered, `emphasis rendered for ${profile.id}`);
+        }
+        out.push(rendered);
+    }
+    let result = out.join("");
+    result = result.replace(/[ \t]{2,}/g, " ");
+    result = result.replace(/ +\n/g, "\n");
+    result = result.replace(/\n +/g, "\n");
+    return result.trim();
+}
+/** Bracket tags the pipeline does not know: pass through on audio-tag models, drop elsewhere. */
+function unknownTags(segment, profile, rec) {
+    return sub(UNKNOWN_TAG, segment, (m) => {
+        const body = m[1].trim();
+        const wordy = fullmatch(WORDY, body) !== null;
+        if (profile.audioTags && wordy)
+            return m[0];
+        rec.add(STAGE, "compile.unknown_tag", m[0], "", "bracket tag removed; this model does not read audio tags");
+        return "";
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/** speechready: prepare text for text-to-speech.
+ *
+ * Clean LLM output, verbalize ambiguous tokens, compile pacing intents to a
+ * provider's own syntax, and chunk under the model's request limit. Deterministic,
+ * no network calls, every rewrite reported as a Change.
+ */
+export type { Change } from "./changes.js";
+export { Segmenter, pack, splitSentences } from "./chunk.js";
+export { DEFAULT_OPTIONS, clean, options } from "./clean.js";
+export type { Options } from "./clean.js";
+export { Lexicon } from "./lexicon.js";
+export type { Entry, EntryInput } from "./lexicon.js";
+export { prepare } from "./pipeline.js";
+export type { Prepared, PrepareInit } from "./pipeline.js";
+export { listProfiles, loadProfile, resolveProfile } from "./profiles/index.js";
+export type { Profile } from "./profiles/index.js";
+export { verbalize } from "./verbalize/index.js";
+import "./verbalize/en.js";
+import "./verbalize/tr.js";
+export { version } from "./version.js";

package/dist/index.js

@@ -0,0 +1,15 @@
+/** speechready: prepare text for text-to-speech.
+ *
+ * Clean LLM output, verbalize ambiguous tokens, compile pacing intents to a
+ * provider's own syntax, and chunk under the model's request limit. Deterministic,
+ * no network calls, every rewrite reported as a Change.
+ */
+export { Segmenter, pack, splitSentences } from "./chunk.js";
+export { DEFAULT_OPTIONS, clean, options } from "./clean.js";
+export { Lexicon } from "./lexicon.js";
+export { prepare } from "./pipeline.js";
+export { listProfiles, loadProfile, resolveProfile } from "./profiles/index.js";
+export { verbalize } from "./verbalize/index.js";
+import "./verbalize/en.js";
+import "./verbalize/tr.js";
+export { version } from "./version.js";

package/dist/intents.d.ts

@@ -0,0 +1,34 @@
+/** Pacing intents written inline in the input and carried through the pipeline.
+ *
+ * Developers write `[pause 500ms]`, `[spell AB12]` or `[em really]` in their text,
+ * or an SSML `<break time="500ms"/>` they already had. `extract` replaces each one
+ * with a private-use sentinel so cleaning and verbalizing leave it alone; the
+ * compile stage renders every sentinel in the target provider's own syntax.
+ */
+export declare const SENTINEL_OPEN = "\uE000";
+export declare const SENTINEL_CLOSE = "\uE001";
+export declare const DEFAULT_PAUSE_MS = 500;
+export interface Intent {
+    kind: "pause" | "spell" | "em" | "phoneme";
+    /** pause only */
+    ms: number;
+    /** spell, em and phoneme: the words as written */
+    text: string;
+    /** phoneme: IPA transcription */
+    ipa: string;
+    /** phoneme: respelling fallback for providers without phoneme tags */
+    say: string;
+}
+export declare function intent(kind: Intent["kind"], fields?: Partial<Omit<Intent, "kind">>): Intent;
+/** '1.5s', '500ms', '2' (seconds) -> milliseconds. Unparseable -> the default. */
+export declare function parseDurationMs(value: string | undefined | null): number;
+/** Replace every inline intent with a sentinel; return the text and the intents in order.
+ *
+ * Pass an existing list to append to it (the pipeline runs a second pass after
+ * cleaning, because the cleaner can turn markdown emphasis into `[em ...]`).
+ */
+export declare function extract(text: string, intents?: Intent[]): [string, Intent[]];
+/** Split text into [segment, intentIndex] pairs; plain text has index null. */
+export declare function splitOnSentinels(text: string): [string, number | null][];
+export declare function stripSentinels(text: string): string;
+export declare function sentinelPattern(): RegExp;

package/dist/intents.js

@@ -0,0 +1,92 @@
+/** Pacing intents written inline in the input and carried through the pipeline.
+ *
+ * Developers write `[pause 500ms]`, `[spell AB12]` or `[em really]` in their text,
+ * or an SSML `<break time="500ms"/>` they already had. `extract` replaces each one
+ * with a private-use sentinel so cleaning and verbalizing leave it alone; the
+ * compile stage renders every sentinel in the target provider's own syntax.
+ */
+import { fullmatch, partition, re, roundHalfEven, sub } from "./util.js";
+export const SENTINEL_OPEN = "";
+export const SENTINEL_CLOSE = "";
+const INTENT_TAG = re(String.raw `\[(?<kind>pause|spell|em|ipa)(?:\s+(?<arg>[^\]]*?))?\s*\](?!\()`, "i");
+const SSML_BREAK = re(String.raw `<break\s+(?:time\s*=\s*["'](?<time>[^"']+)["']|strength\s*=\s*["'](?<strength>[^"']+)["'])[^>]*/?>`, "i");
+const SENTINEL = re(`${SENTINEL_OPEN}(\\d+)${SENTINEL_CLOSE}`);
+const DURATION = re(String.raw `(\d+(?:\.\d+)?)\s*(ms|s)?`);
+const STRENGTH_MS = { "x-weak": 250, weak: 500, medium: 750, strong: 1000, "x-strong": 1250 };
+export const DEFAULT_PAUSE_MS = 500;
+export function intent(kind, fields = {}) {
+    return { kind, ms: 0, text: "", ipa: "", say: "", ...fields };
+}
+/** '1.5s', '500ms', '2' (seconds) -> milliseconds. Unparseable -> the default. */
+export function parseDurationMs(value) {
+    if (!value)
+        return DEFAULT_PAUSE_MS;
+    const v = value.trim().toLowerCase();
+    const m = fullmatch(DURATION, v);
+    if (!m)
+        return DEFAULT_PAUSE_MS;
+    const number = parseFloat(m[1]);
+    const unit = m[2];
+    if (unit === "ms")
+        return roundHalfEven(number);
+    return roundHalfEven(number * 1000);
+}
+/** Replace every inline intent with a sentinel; return the text and the intents in order.
+ *
+ * Pass an existing list to append to it (the pipeline runs a second pass after
+ * cleaning, because the cleaner can turn markdown emphasis into `[em ...]`).
+ */
+export function extract(text, intents) {
+    const list = intents ?? [];
+    const add = (it) => {
+        list.push(it);
+        return `${SENTINEL_OPEN}${list.length - 1}${SENTINEL_CLOSE}`;
+    };
+    const ssml = (m) => {
+        const g = m.groups ?? {};
+        if (g.time)
+            return add(intent("pause", { ms: parseDurationMs(g.time) }));
+        return add(intent("pause", { ms: STRENGTH_MS[(g.strength ?? "").toLowerCase()] ?? DEFAULT_PAUSE_MS }));
+    };
+    const tag = (m) => {
+        const g = m.groups ?? {};
+        const kind = (g.kind ?? "").toLowerCase();
+        const arg = (g.arg ?? "").trim();
+        if (kind === "pause")
+            return add(intent("pause", { ms: parseDurationMs(arg) }));
+        if (!arg)
+            return "";
+        if (kind === "ipa") {
+            const [word, , transcription] = partition(arg, " ");
+            if (!transcription)
+                return word;
+            return add(intent("phoneme", { text: word, ipa: transcription.trim() }));
+        }
+        return add(intent(kind, { text: arg }));
+    };
+    let out = sub(SSML_BREAK, text, ssml);
+    out = sub(INTENT_TAG, out, tag);
+    return [out, list];
+}
+/** Split text into [segment, intentIndex] pairs; plain text has index null. */
+export function splitOnSentinels(text) {
+    const parts = [];
+    let pos = 0;
+    SENTINEL.lastIndex = 0;
+    for (const m of text.matchAll(SENTINEL)) {
+        const start = m.index ?? 0;
+        if (start > pos)
+            parts.push([text.slice(pos, start), null]);
+        parts.push(["", parseInt(m[1], 10)]);
+        pos = start + m[0].length;
+    }
+    if (pos < text.length)
+        parts.push([text.slice(pos), null]);
+    return parts;
+}
+export function stripSentinels(text) {
+    return sub(SENTINEL, text, () => "");
+}
+export function sentinelPattern() {
+    return re(`${SENTINEL_OPEN}(\\d+)${SENTINEL_CLOSE}`);
+}

package/dist/lexicon.d.ts

@@ -0,0 +1,53 @@
+/** One pronunciation lexicon, applied in the pipeline and exported to each vendor's format.
+ *
+ * An entry says how a word is pronounced in one of three ways:
+ * - `ipa`: an IPA transcription, rendered as a phoneme tag where the provider
+ *   accepts one (Azure, Google, Polly) and exported to lexicon files;
+ * - `say`: a respelling or alias ("engine X", "sequel") that replaces the word in
+ *   the text, which works on every provider;
+ * - `spell: true`: the word is read letter by letter.
+ *
+ * When a provider cannot take a phoneme tag, an entry falls back to `say`, then
+ * to `spell`, then leaves the word alone.
+ */
+import { Intent } from "./intents.js";
+import { Profile } from "./profiles/index.js";
+export interface Entry {
+    word: string;
+    ipa: string;
+    say: string;
+    spell: boolean;
+    case_sensitive: boolean;
+}
+export type EntryInput = Partial<Entry> & {
+    word: string;
+};
+export declare function entry(e: EntryInput): Entry;
+export declare class Lexicon {
+    entries: Entry[];
+    locale: string;
+    constructor(entries?: EntryInput[], locale?: string);
+    static fromEntries(entries: EntryInput[], locale?: string): Lexicon;
+    /** Build from a parsed lexicon document (`{locale, entries}`), e.g. `JSON.parse` of a lexicon file. */
+    static fromObject(data: {
+        locale?: string;
+        entries?: EntryInput[];
+    }): Lexicon;
+    /** Read a `.json` lexicon file, or a `.yaml` one when the optional `yaml` package is installed. Node only. */
+    static load(path: string): Promise<Lexicon>;
+    toObject(): {
+        locale: string;
+        entries: Record<string, unknown>[];
+    };
+    /** Replace every lexicon word in `text` with an intent sentinel; appends to `intents`. */
+    apply(text: string, intents: Intent[]): string;
+    /** Pronunciation Lexicon Specification XML, accepted by ElevenLabs, Azure and Amazon Polly. */
+    toPls(alphabet?: string): string;
+    /** Google Cloud TTS custom pronunciations (v1beta1 `customPronunciations`). IPA entries only. */
+    toGoogleJson(): string;
+    toJson(): string;
+    /** The upload file for a provider profile, or null when the provider takes no lexicon. */
+    exportFor(profile: Profile): string | null;
+    /** `pls`, `google`, or `json`. */
+    export(fmt: string, alphabet?: string): string;
+}