pair-mcp 0.0.0-stage → 0.1.0

package/dist/server/server/src/index.js

@@ -0,0 +1,378 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { Workspace } from "./files.js";
+import { Hub } from "./hub.js";
+import { resolveScript, writtenStyle } from "./script.js";
+import { harnessName } from "./sessions.js";
+import { freshness, loadWalkthrough, prepareShared, publishGist, publishToPr, sharedHandler } from "./share.js";
+import { outline, supportsSymbols } from "./symbols.js";
+const argv = process.argv.slice(2);
+const flag = (name) => {
+    const i = argv.indexOf(`--${name}`);
+    return i === -1 ? undefined : argv[i + 1];
+};
+// `pair install [harness]` runs the bundled installer, which registers this package with the harnesses.
+if (argv[0] === "install") {
+    const script = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../../install.sh");
+    const r = spawnSync("bash", [script, ...argv.slice(1)], { stdio: "inherit" });
+    process.exit(r.status ?? 1);
+}
+const explicitRoot = flag("root") ?? process.env.PAIR_ROOT;
+const port = Number(flag("port") ?? process.env.PAIR_PORT ?? 7420);
+const ws = new Workspace(path.resolve(explicitRoot ?? process.cwd()));
+const hub = new Hub(ws);
+const anchor = {
+    path: z.string().optional().describe("Repo-relative file path. Defaults to the most recently opened file."),
+    symbol: z.string().optional().describe('Qualified symbol, e.g. "ReplicationManager.syncLoop". Preferred for classes/functions.'),
+    lines: z.tuple([z.number().int(), z.number().int()]).optional().describe("1-based inclusive [start, end]."),
+    match: z.string().optional().describe("Exact code snippet copied from the file (whitespace-insensitive). Must be unique."),
+};
+const at = z.string().optional().describe("Marker id from the narration ({id}); the action fires as that word is spoken. Omit to fire at segment start.");
+const action = z.discriminatedUnion("do", [
+    z.object({ do: z.literal("open"), path: z.string(), at }),
+    z.object({ do: z.literal("reveal"), at, ...anchor }),
+    z.object({ do: z.literal("highlight"), at, keep: z.boolean().optional().describe("Keep earlier highlights instead of replacing them."), ...anchor }),
+    z.object({ do: z.literal("clear"), at }),
+]);
+const segments = z
+    .array(z.object({
+    narration: z
+        .string()
+        .describe("Spoken aloud by TTS, so write what you'd say, not what you'd type: no markdown, backticks, paths, or call syntax. Say identifiers as words ('the sync loop', \"this 'likes dash video ID' right here\") and let highlights show the code. Embed {id} markers right before the words that should trigger actions."),
+    actions: z.array(action).optional(),
+}))
+    .min(1);
+/** Where the paused main walkthrough stands, so the agent can offer it by name. */
+function mainSummary() {
+    const main = hub.pausedMain();
+    if (!main)
+        return null;
+    const seg = main.script.segments[main.index];
+    return `the main walkthrough "${main.script.title}" (paused at part ${main.index + 1} of ${main.script.segments.length}: ${JSON.stringify(seg?.text.slice(0, 120) ?? "")})`;
+}
+const ASK_NEXT = "Don't resume or change direction on your own. Ask where to go next with await_user: a short spoken prompt plus 2-3 options, " +
+    "e.g. go deeper on what you just showed, or return to the main walkthrough (name it and where you were).";
+const IF_DONE = "If their answer means they're finished (\"that covered it\", \"thanks\", \"I'm good\"), call end_session with a short spoken goodbye. " +
+    "Never just stop: the UI shows the user a spinner until you do something.";
+function describeOutcome(o, played) {
+    switch (o.status) {
+        case "completed": {
+            if (played?.aside) {
+                const main = mainSummary();
+                return [
+                    "The aside finished playing.",
+                    main ? `The user stepped away from ${main}.` : "",
+                    ASK_NEXT,
+                    main ? "If they choose to go back, call resume_walkthrough with an intro that bridges back (one or two spoken sentences)." : "",
+                ].filter(Boolean).join("\n");
+            }
+            return "Walkthrough finished playing. Call await_user with a spoken prompt and a few follow-up options, including one to finish (e.g. \"That covers it\"). When the user is done, call end_session.";
+        }
+        case "interrupted":
+            return [
+                `The user paused at segment ${o.index} and asked: ${JSON.stringify(o.question)}`,
+                played?.segments[o.index] ? `They were hearing: ${JSON.stringify(played.segments[o.index].text)}` : "",
+                `What they could see: ${JSON.stringify(o.context)}`,
+                "",
+                "Investigate if needed, then answer with present_walkthrough (aside_for set to their question; keep it short and show the code you mention).",
+                "When the aside finishes, don't resume automatically: ask whether to dig further or return, with await_user.",
+            ].filter(Boolean).join("\n");
+        case "question": {
+            const main = mainSummary();
+            return [
+                o.choice !== undefined ? `The user picked option ${o.choice + 1}: ${JSON.stringify(o.question)}` : `The user asked: ${JSON.stringify(o.question)}`,
+                `What they could see: ${JSON.stringify(o.context)}`,
+                main ? `Still paused: ${main}. If they chose to go back, call resume_walkthrough (with an intro).` : "",
+                "",
+                IF_DONE,
+                "Otherwise investigate, answer with present_walkthrough (aside_for set to the question), and when it finishes ask where to go next with await_user.",
+            ].filter(Boolean).join("\n");
+        }
+        case "return": {
+            const main = hub.pausedMain();
+            return main
+                ? `The user clicked "Back to: ${main.script.title}". Call resume_walkthrough now (it picks up at part ${main.index + 1}), with a one- or two-sentence intro that bridges back to where you were.`
+                : "The user asked to go back, but there's no paused walkthrough. Ask what they'd like next with await_user.";
+        }
+        case "ended":
+            return "The user ended the walkthrough session. Stop presenting.";
+        case "idle":
+            return "No question arrived before the timeout. Call end_session with a short goodbye (or await_user again if you expect more).";
+        case "cancelled":
+            return "Playback was cancelled (superseded or the request was aborted).";
+        case "shared":
+            return `The user opened a shared walkthrough from a link in the UI: ${o.source}\nCall play_shared_walkthrough with that source now. Don't investigate or write your own.`;
+    }
+}
+const text = (t, isError = false) => ({ content: [{ type: "text", text: t }], isError });
+/** The authored form of the latest main walkthrough, kept so it can be shared. */
+let lastMain = null;
+/** Plays a validated script, reporting per-segment progress to the client, and describes the outcome. */
+async function playResolved(script, extra) {
+    const token = extra._meta?.progressToken;
+    const total = script.segments.length;
+    const outcome = await hub.play(script, 0, extra.signal, (i) => {
+        if (token !== undefined) {
+            extra.sendNotification({ method: "notifications/progress", params: { progressToken: token, progress: i + 1, total } }).catch(() => { });
+        }
+    });
+    return describeOutcome(outcome, script);
+}
+const warningList = (warnings) => (warnings.length ? `\n\nWarnings:\n- ${warnings.join("\n- ")}` : "");
+const server = new McpServer({ name: "pair", version: "0.1.0" });
+server.registerTool("show_status", {
+    description: "Open the walkthrough UI (if not already open) and show a status line while you investigate, e.g. 'Looking into how regional replication works…'. Call this first so the user knows you're working.",
+    inputSchema: { message: z.string() },
+}, async ({ message }) => {
+    hub.touch();
+    const connected = await hub.ensureOpen();
+    hub.setStatus(message);
+    return text(connected ? `Status shown at ${hub.url}.` : `Status set, but no browser connected yet. Ask the user to open ${hub.url}.`);
+});
+server.registerTool("outline", {
+    description: "List the symbols (classes, functions, methods) in a file with their line ranges, to pick valid symbol anchors.",
+    inputSchema: { path: z.string() },
+}, async ({ path: p }) => {
+    hub.touch();
+    try {
+        const rel = ws.rel(p);
+        if (!supportsSymbols(rel))
+            return text(`No symbol support for ${rel}; use match or lines anchors.`, true);
+        const syms = await outline(rel, await ws.read(rel));
+        return text(syms.map((s) => `${s.qualified}  [${s.kind}]  L${s.start}-${s.end}`).join("\n") || "(no symbols found)");
+    }
+    catch (e) {
+        return text(e.message, true);
+    }
+});
+server.registerTool("present_walkthrough", {
+    description: [
+        "Play a narrated, visual code walkthrough in the user's editor UI. Do your investigation first; this call performs a finished script.",
+        "Every path, symbol, line range, and snippet is validated against the repo before anything plays; on errors nothing plays and you get the list to fix.",
+        "Blocks until playback finishes, the user pauses to ask a question, or ends the session, and returns which.",
+    ].join(" "),
+    inputSchema: {
+        title: z.string(),
+        segments,
+        aside_for: z.string().optional().describe("Set to the user's question when this answers an interjection; the main walkthrough is kept for resume_walkthrough."),
+    },
+}, async ({ title, segments, aside_for }, extra) => {
+    hub.touch();
+    const script = { title, segments };
+    const result = await resolveScript(ws, script, aside_for ? { question: aside_for } : undefined);
+    if (!result.script)
+        return text(`Script not played. Fix these and call again:\n- ${result.errors.join("\n- ")}`, true);
+    if (!(await hub.ensureOpen()))
+        return text(`No browser connected. Ask the user to open ${hub.url}, then retry.`, true);
+    if (!aside_for)
+        lastMain = script;
+    return text((await playResolved(result.script, extra)) + warningList(result.warnings));
+});
+server.registerTool("share_walkthrough", {
+    description: [
+        "Publish the most recent main walkthrough (not asides) so teammates with pair can replay it without regenerating it.",
+        "Only call this when the user asks to share or publish a walkthrough. Uses the gh CLI.",
+        "By default it's posted as a comment on the pull request (visible to anyone who can see the repo); reviewers then just ask to play the walkthrough on that PR.",
+        "With to: \"gist\" it's a secret gist instead: unlisted, but readable by anyone with the link, including code snippets used as anchors.",
+    ].join(" "),
+    inputSchema: {
+        to: z.enum(["pr", "gist"]).optional().describe('Default "pr".'),
+        pr: z.string().optional().describe("PR number or URL. Defaults to the PR for the current branch."),
+    },
+}, async ({ to, pr }) => {
+    hub.touch();
+    if (!lastMain)
+        return text("There's no walkthrough to share yet. Present one with present_walkthrough first.", true);
+    try {
+        if (to === "gist") {
+            const { url, warnings } = await publishGist(ws.root, lastMain);
+            return text(`Published "${lastMain.title}" as a secret gist: ${url}` + warningList(warnings));
+        }
+        const { url, warnings } = await publishToPr(ws.root, lastMain, pr);
+        return text(`Posted "${lastMain.title}" on the PR: ${url}\nReviewers can ask their agent to play the walkthrough on that PR.` + warningList(warnings));
+    }
+    catch (e) {
+        return text(e.message, true);
+    }
+});
+server.registerTool("play_shared_walkthrough", {
+    description: [
+        "Play a walkthrough someone already shared (a PR number or URL, a gist URL or id, a raw URL, or a local .json file) exactly as written, instead of investigating and writing a new one.",
+        "It's re-validated against this checkout. Blocks and returns outcomes like present_walkthrough, and questions are handled the same way (answer with asides).",
+    ].join(" "),
+    inputSchema: {
+        source: z.string().describe('e.g. "123" or a PR URL (plays the latest walkthrough posted on it), a gist URL, or a path to a walkthrough .json file.'),
+    },
+}, async ({ source }, extra) => {
+    hub.touch();
+    let prepared;
+    try {
+        prepared = await prepareShared(ws, source);
+    }
+    catch (e) {
+        return text(e.message, true);
+    }
+    const { shared, stale, result } = prepared;
+    if (!result.script) {
+        return text([
+            "The shared walkthrough can't play here, so nothing played:",
+            `- ${result.errors.join("\n- ")}`,
+            stale ? `\n${stale}` : "",
+            "\nTell the user what's wrong (usually: check out the branch or commit it was written against). Don't write a replacement walkthrough unless they ask.",
+        ].join("\n"), true);
+    }
+    if (!(await hub.ensureOpen()))
+        return text(`No browser connected. Ask the user to open ${hub.url}, then retry.`, true);
+    lastMain = { title: shared.title, segments: shared.segments };
+    const note = (shared.origin ? `\n\nLoaded from ${shared.origin}.` : "") + (stale ? `\n\nHeads-up for the user: ${stale}` : "");
+    return text((await playResolved(result.script, extra)) + note + warningList(result.warnings));
+});
+hub.shared = sharedHandler(ws, (s) => (lastMain = s));
+server.registerTool("resume_walkthrough", {
+    description: "Return to the main walkthrough after an aside, once the user has said they want to. Blocks like present_walkthrough.",
+    inputSchema: {
+        from_segment: z.number().int().optional().describe("Defaults to the segment the user paused on."),
+        intro: z
+            .string()
+            .optional()
+            .describe("One or two spoken sentences that bridge back, e.g. \"Okay, back to the sync loop. We'd just seen how the change log gets pulled.\""),
+    },
+}, async ({ from_segment, intro }, extra) => {
+    hub.touch();
+    const main = hub.mainScript();
+    if (!main)
+        return text("There is no walkthrough to resume.", true);
+    const from = Math.max(0, Math.min(from_segment ?? main.index, main.script.segments.length - 1));
+    let bridge;
+    if (intro?.trim()) {
+        const r = await resolveScript(ws, { title: "", segments: [{ narration: intro }] });
+        if (!r.script)
+            return text(`Intro not played. Fix these and call again:\n- ${r.errors.join("\n- ")}`, true);
+        bridge = { ...r.script, transition: true };
+    }
+    if (!(await hub.ensureOpen()))
+        return text(`No browser connected. Ask the user to open ${hub.url}.`, true);
+    if (bridge) {
+        const o = await hub.play(bridge, 0, extra.signal);
+        if (o.status !== "completed")
+            return text(describeOutcome(o, bridge));
+    }
+    const outcome = await hub.play(main.script, from, extra.signal);
+    return text(describeOutcome(outcome, main.script));
+});
+server.registerTool("await_user", {
+    description: "Ask the user where to go next and wait for their answer in the UI. The prompt is spoken aloud and shown as your turn in the transcript; options appear as buttons, and the user can also type anything. Use it after an aside, at the end of a walkthrough, or before changing direction. Returns their answer, 'ended', or 'idle' on timeout.",
+    inputSchema: {
+        prompt: z
+            .string()
+            .optional()
+            .describe("Spoken, conversational question, e.g. \"Want me to show an example run, or head back to the sync walkthrough?\""),
+        options: z
+            .array(z.string())
+            .max(4)
+            .optional()
+            .describe('Short button labels, e.g. ["Show an example run", "Back to the sync walkthrough"]. At the end of a walkthrough, include a way to finish, e.g. "That covers it" (then call end_session if chosen).'),
+        timeout_seconds: z.number().int().optional().describe("Default 600."),
+    },
+}, async ({ prompt, options, timeout_seconds }, extra) => {
+    hub.touch();
+    if (!(await hub.ensureOpen()))
+        return text(`No browser connected. Ask the user to open ${hub.url}.`, true);
+    const outcome = await hub.awaitQuestion(prompt ?? null, options?.length ? options : undefined, (timeout_seconds ?? 600) * 1000, extra.signal);
+    return text(describeOutcome(outcome));
+});
+server.registerTool("end_session", {
+    description: "Close the walkthrough session when the user is done: the goodbye is spoken and shown, and the UI stops taking questions. Call this instead of ending your turn silently.",
+    inputSchema: {
+        message: z.string().optional().describe('A short spoken goodbye, e.g. "Glad that helped. Happy hacking!"'),
+    },
+}, async ({ message }) => {
+    hub.touch();
+    const goodbye = message?.trim() || null;
+    const written = goodbye && writtenStyle(goodbye);
+    if (written)
+        return text(`Not sent: the goodbye is spoken aloud but contains ${written}. Rewrite it as speech.`, true);
+    hub.endSession(goodbye);
+    return text("Session ended. The user sees your goodbye; you can end your turn.");
+});
+/** `pair play <script.json | PR | gist URL> [--root dir]`: run a script without an agent. */
+async function playFile(source) {
+    hub.harness = "pair play (no agent)";
+    await hub.listen(port);
+    const shared = await loadWalkthrough(source, ws.root, process.cwd());
+    const stale = await freshness(ws.root, shared);
+    if (stale)
+        console.error("note:", stale);
+    const result = await resolveScript(ws, { title: shared.title, segments: shared.segments });
+    result.warnings.forEach((w) => console.error("warning:", w));
+    if (!result.script) {
+        result.errors.forEach((e) => console.error("error:", e));
+        process.exit(1);
+    }
+    console.error(`Opening ${hub.url} …`);
+    await hub.ensureOpen();
+    let script = result.script;
+    let outcome = await hub.play(script, 0);
+    for (;;) {
+        if (outcome.status === "interrupted") {
+            console.error(`User asked at segment ${outcome.index}: ${outcome.question}\n(no agent in play mode; resuming)`);
+            outcome = await hub.play(script, outcome.index);
+        }
+        else if (outcome.status === "shared") {
+            // A "Play in pair" link was opened: switch to that walkthrough.
+            console.error(`Playing shared walkthrough from ${outcome.source}`);
+            try {
+                script = await hub.shared.resolve(outcome.source);
+            }
+            catch (e) {
+                console.error("error:", e.message);
+                break;
+            }
+            outcome = await hub.play(script, 0);
+        }
+        else
+            break;
+    }
+    console.error(`Outcome: ${outcome.status}`);
+    process.exit(0);
+}
+async function main() {
+    if (argv[0] === "play") {
+        if (!argv[1])
+            throw new Error("usage: pair play <script.json | PR number or URL | gist URL> [--root dir]");
+        return playFile(argv[1]);
+    }
+    await hub.listen(port);
+    server.server.oninitialized = async () => {
+        hub.harness = harnessName(server.server.getClientVersion()?.name);
+        hub.sessions.update({ harness: hub.harness });
+        // Without an explicit root, prefer the client's workspace root over our cwd.
+        if (explicitRoot || !server.server.getClientCapabilities()?.roots)
+            return;
+        try {
+            const { roots } = await server.server.listRoots();
+            const first = roots.find((r) => r.uri.startsWith("file://"));
+            if (first) {
+                ws.setRoot(fileURLToPath(first.uri));
+                await hub.sessions.setRoot(ws.root);
+            }
+        }
+        catch {
+            /* keep cwd */
+        }
+    };
+    // The agent is gone: stop serving, so the UI port and session list don't point at a dead session.
+    // The stdio transport doesn't report stdin closing, so watch it directly.
+    server.server.onclose = () => process.exit(0);
+    process.stdin.once("end", () => process.exit(0));
+    await server.connect(new StdioServerTransport());
+}
+main().catch((e) => {
+    console.error("[pair]", e);
+    process.exit(1);
+});

package/dist/server/server/src/kokoro.js

@@ -0,0 +1,157 @@
+// Optional local neural TTS (Kokoro-82M via kokoro-js / onnxruntime).
+// Nothing is installed until the user switches the UI to Kokoro; then the
+// package goes into ~/.cache/pair/kokoro and the model is downloaded once.
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+const HOME = process.env.PAIR_KOKORO_DIR ?? path.join(os.homedir(), ".cache", "pair", "kokoro");
+const PACKAGE = "kokoro-js@1.2.1";
+// This export adds a per-phoneme `durations` output, which is what lets us time words.
+const MODEL = "onnx-community/Kokoro-82M-v1.0-ONNX-timestamped";
+const SAMPLE_RATE = 24_000;
+const FRAMES_PER_SEC = 40;
+const MAX_CHARS = 400;
+const log = (...args) => console.error("[pair:kokoro]", ...args);
+export class Kokoro {
+    status = { state: "off" };
+    onStatus = () => { };
+    tts = null;
+    phonemize = null;
+    lengths = new Map();
+    starting = null;
+    queue = Promise.resolve();
+    set(status) {
+        this.status = status;
+        this.onStatus(status);
+    }
+    /** Installs (first time only) and loads the model. Safe to call repeatedly. */
+    enable() {
+        if (this.tts)
+            return Promise.resolve();
+        this.starting ??= this.start().catch((e) => {
+            log(e);
+            this.set({ state: "error", message: e.message });
+            this.starting = null;
+        });
+        return this.starting;
+    }
+    async start() {
+        if (!existsSync(path.join(HOME, "node_modules", "kokoro-js", "package.json")))
+            await this.install();
+        this.set({ state: "loading", message: "Loading the Kokoro model…" });
+        const require = createRequire(path.join(HOME, "package.json"));
+        const mod = await import(pathToFileURL(require.resolve("kokoro-js")).href);
+        // kokoro-js's own phonemizer; used to estimate each word's share of the audio.
+        this.phonemize = (await import(pathToFileURL(require.resolve("phonemizer")).href)).phonemize;
+        let lastReport = 0;
+        this.tts = (await mod.KokoroTTS.from_pretrained(MODEL, {
+            dtype: "fp32",
+            device: "cpu",
+            progress_callback: (p) => {
+                // Only the .onnx weights are big enough to be worth reporting.
+                if (p.status !== "progress" || !p.file?.endsWith(".onnx") || Date.now() - lastReport < 250)
+                    return;
+                lastReport = Date.now();
+                this.set({ state: "loading", message: "Downloading the Kokoro model (one time, ~330 MB)…", progress: (p.progress ?? 0) / 100 });
+            },
+        }));
+        this.set({ state: "ready" });
+    }
+    install() {
+        this.set({ state: "installing", message: "Installing Kokoro (one time)…" });
+        mkdirSync(HOME, { recursive: true });
+        if (!existsSync(path.join(HOME, "package.json")))
+            writeFileSync(path.join(HOME, "package.json"), '{ "private": true }\n');
+        // Use the npm that ships with the Node running us, so PATH quirks don't matter.
+        const nodeDir = path.dirname(process.execPath);
+        const npm = existsSync(path.join(nodeDir, "npm")) ? path.join(nodeDir, "npm") : "npm";
+        return new Promise((resolve, reject) => {
+            const child = spawn(npm, ["install", "--no-audit", "--no-fund", "--loglevel=error", PACKAGE], {
+                cwd: HOME,
+                env: { ...process.env, PATH: `${nodeDir}${path.delimiter}${process.env.PATH ?? ""}` },
+                stdio: ["ignore", "ignore", "pipe"],
+            });
+            let stderr = "";
+            child.stderr.on("data", (d) => (stderr += d));
+            child.on("error", reject);
+            child.on("exit", (code) => (code === 0 ? resolve() : reject(new Error(`npm install ${PACKAGE} failed: ${stderr.trim().split("\n").pop() ?? code}`))));
+        });
+    }
+    async phonemeLength(word) {
+        // All-caps acronyms are spelled out by kokoro-js; approximate ~2 phonemes per letter.
+        if (/^[A-Z0-9]{2,6}[.,!?;:]*$/.test(word) && /[A-Z]/.test(word))
+            return strip(word).length * 2;
+        const key = word.toLowerCase();
+        if (!this.lengths.has(key)) {
+            const out = this.phonemize ? await this.phonemize(word, "en-us").catch(() => [word]) : [word];
+            this.lengths.set(key, strip(out.join(" ")).length);
+        }
+        return this.lengths.get(key);
+    }
+    /** Synthesizes text (one sentence or so) and times each word. Calls are serialized. */
+    speak(text, voice, speed) {
+        const run = this.queue.then(() => this.synth(text.slice(0, MAX_CHARS), voice, speed));
+        this.queue = run.catch(() => { });
+        return run;
+    }
+    async synth(text, voice, speed) {
+        const tts = this.tts;
+        if (!tts)
+            throw new Error("Kokoro isn't ready");
+        // generate() doesn't expose the phonemes or the durations output, so capture them in passing.
+        let phonemes = "";
+        let outputs = {};
+        const { tokenizer, model } = tts;
+        tts.tokenizer = (p, o) => ((phonemes = p), tokenizer(p, o));
+        tts.model = async (i) => (outputs = await model(i));
+        let audio;
+        try {
+            audio = await tts.generate(text, { voice, speed });
+        }
+        finally {
+            tts.tokenizer = tokenizer;
+            tts.model = model;
+        }
+        const duration = audio.audio.length / SAMPLE_RATE;
+        let words = [];
+        if (outputs.durations) {
+            const lengths = await Promise.all([...text.matchAll(/\S+/g)].map((m) => this.phonemeLength(m[0])));
+            words = alignWords(text, phonemes, Array.from(outputs.durations.data, Number), duration, lengths);
+        }
+        return { audio: Buffer.from(audio.toWav()).toString("base64"), duration, words };
+    }
+}
+// Stress marks, spacing and punctuation don't take time on their own.
+const strip = (s) => s.replace(/[ˈˌː\s.,!?;:"'()\[\]—–-]/g, "");
+/**
+ * Maps per-phoneme durations back onto the words of the original text.
+ * Phoneme words don't line up 1:1 with text words ("in the" → "ɪnðə"), so each
+ * text word's expected phoneme length (from phonemizing it alone) is laid
+ * cumulatively over the actual phoneme string, scaled to fit.
+ */
+export function alignWords(text, phonemes, durations, audioSeconds, wordLengths) {
+    // durations = [start pad, one per phoneme char, end pad]
+    const starts = [];
+    let t = durations[0] ?? 0;
+    for (let i = 0; i < phonemes.length; i++) {
+        starts.push(t);
+        t += durations[i + 1] ?? 0;
+    }
+    const total = durations.reduce((a, b) => a + b, 0) / FRAMES_PER_SEC;
+    const scale = total > 0 ? audioSeconds / total : 1;
+    const timeAt = (c) => ((starts[c] ?? t) / FRAMES_PER_SEC) * scale;
+    // Positions in `phonemes` of the characters that carry sound.
+    const voiced = [...phonemes].flatMap((ch, i) => (strip(ch) ? [i] : []));
+    const words = [...text.matchAll(/\S+/g)];
+    const expected = words.map((_, i) => Math.max(1, wordLengths[i] ?? 1));
+    const fit = voiced.length / expected.reduce((a, b) => a + b, 0);
+    let cum = 0;
+    return words.map((m, i) => {
+        const at = Math.min(voiced.length - 1, Math.round(cum * fit));
+        cum += expected[i];
+        return { offset: m.index, start: Number(timeAt(voiced[Math.max(0, at)] ?? 0).toFixed(3)) };
+    });
+}