@jokerized/decksmith 0.1.0

package/dist/types/index.d.ts

@@ -0,0 +1,200 @@
+import { type DeckNarration } from "./emit/composition.js";
+import type { Cut } from "./plan/select.js";
+import { type Format, type Source, type Storyboard } from "./types.js";
+/**
+ * Markdown (and LaTeX-ish markdown) in, typed `Source` out. The one parser we
+ * have; a consumer that already holds structured text can skip it and hand
+ * `sourceSchema.parse(...)` straight to the planner.
+ */
+export { parseMarkdown } from "./source/markdown.js";
+export type { ParseOptions } from "./source/markdown.js";
+/**
+ * Figures referenced by URL, downloaded beside the source. Separate from
+ * `parseMarkdown` because it touches the network and a server may want to fetch
+ * through its own client instead.
+ */
+export { fetchFigures } from "./source/assets.js";
+/**
+ * Subset a CJK webfont over the glyphs a deck actually renders. Exported
+ * because invariant 9 — a font stack naming a family the bundle does not
+ * declare falls back silently — is not something a consumer can debug from the
+ * outside, and `buildDeck` calls it for you only for its own output directory.
+ */
+export { bundleFont } from "./source/fonts.js";
+export type { FontBundle } from "./source/fonts.js";
+/**
+ * The planner. `Runner` is exported with it on purpose: `codexPlanner` shells
+ * to the Codex CLI by default, which is wrong for a server, and substituting a
+ * runner is the supported way to drive it from an SDK instead of a subprocess.
+ */
+export { codexPlanner } from "./plan/codex.js";
+export type { CodexOptions, Runner } from "./plan/codex.js";
+/**
+ * Fails loudly when a beat cites a figure, table or equation the source does
+ * not contain. `buildDeck` does not call it — a caller assembling a storyboard
+ * by hand wants this before it spends a render on a dangling ref.
+ */
+export { assertInsideResolves, assertRefsResolve } from "./plan/refs.js";
+/** The prompt, so a consumer driving its own model can reproduce our planning. */
+export { renderSource, systemPrompt } from "./plan/prompt.js";
+/**
+ * The three exposed length knobs — `duration`, `slides`, `narration.density` —
+ * turned into the two derived ones. Pure arithmetic over preferences, so a
+ * caller can ask what a target costs before spending a plan on it.
+ */
+export { COMFORTABLE_CPS, durationPlan, slidesFor, LAST_HOLD_SECONDS, MAX_PLAYBACK, MIN_SENTENCE_CHARS, MOTION_SHARE, p95CueRate, playbackFactor, playbackWarning, SPEAKING_STOPS, SPEECH_CPS, STOPS_PER_BEAT, tempoChain, } from "./plan/duration.js";
+export type { DurationPlan } from "./plan/duration.js";
+/**
+ * Text-to-speech over a storyboard. Needs the `edge-tts` binary on PATH, which
+ * is why it is a separate call and not a `buildDeck` option.
+ */
+export { narrate } from "./narrate/narrate.js";
+export type { NarrateOpts } from "./narrate/narrate.js";
+export { narratableLangs, pickVoice } from "./narrate/voices.js";
+/**
+ * The synthesiser, behind an interface.
+ *
+ * edge-tts is an unofficial client of Edge's Read Aloud endpoint — no terms, no
+ * SLA, and a signed-token scheme that has broken clients before. So it is one
+ * implementation of `SpeechProvider` rather than the shape of the code: hand
+ * `synthesize` a provider and nothing else here knows the difference. Register
+ * a new one in `PROVIDERS`, or select at runtime with DECKSMITH_TTS.
+ */
+export { edgeProvider, parseCues, PROVIDERS, resolveProvider, synthesize, } from "./narrate/tts.js";
+export type { SpeechProvider, SpeechRequest, SpeechResult, SynthOpts, } from "./narrate/tts.js";
+/**
+ * The pure core: storyboard + source + format → HTML strings, no I/O. Exported
+ * beneath `buildDeck` for callers that write to something other than a
+ * filesystem — object storage, a response body, a test.
+ */
+export { DECK_PAGE, emitComposition, emitDeck, planCut, PLAYER_FILE } from "./emit/composition.js";
+export type { Deck, DeckNarration, DeckOptions } from "./emit/composition.js";
+/**
+ * Which beats a format keeps and why the rest went. `emitDeck` returns one on
+ * every build; `planCut` answers the same question without emitting a deck, for
+ * a caller costing a cut before committing to it. `selectBeats` is the rule
+ * itself, exported so it can be run against a budget no `Format` states.
+ */
+export { selectBeats } from "./plan/select.js";
+export type { Cut, Dangling, Dropped, DropRule, SelectionBudget } from "./plan/select.js";
+/** Themes are a named, closed set; a consumer needs to enumerate and validate. */
+export { resolveTheme, THEME_NAMES, THEMES } from "./emit/themes/index.js";
+export type { DeckTheme } from "./emit/themes/index.js";
+/**
+ * The gates. `verify` is ours plus HyperFrames'; `check` is HyperFrames' alone
+ * and needs its CLI. A build that never opens a browser can still run `verify`
+ * for the determinism and narration scans, which are pure string work.
+ */
+export { verify } from "./verify/index.js";
+/**
+ * The storyboard advisory `plan` prints and `verify` folds in: a headline that
+ * recites the visual's own labels as a list. Exported because it is pure over a
+ * storyboard — no browser, no built deck — so a caller can run it on a plan
+ * before spending anything on it, which is the only moment it is worth acting on.
+ */
+export { scanHeadlines, scanNarrationLead, scanRepeatedObject } from "./verify/index.js";
+export { check, parseCheckReport, sampleTimes } from "./verify/check.js";
+export type { CheckOptions } from "./verify/check.js";
+/**
+ * The chart-collision rule. Exported for the same reason `inkBelow` is: the
+ * predicate is pure over a list of measured text runs, so what counts as a
+ * collision is something a caller can read and test rather than infer from a
+ * verdict. `verify` runs it; nothing else has to.
+ */
+export { gradeOverprint, MIN_OVERLAP, overprints } from "./verify/overprint.js";
+export type { Overprint, Overprinted, TextRun } from "./verify/overprint.js";
+/**
+ * The determinism gate: render the deck twice and compare. Separate from
+ * `verify` because it costs two full renders — minutes, not milliseconds — so
+ * it is a thing you schedule, not a thing you run on a request path. `identical`
+ * is only honest on an image-free deck with no camera; see
+ * `demo/fixtures/plain.storyboard.json` and .planning/EXPERIMENT-006.
+ */
+export { drift, FLOOR_DB } from "./verify/index.js";
+export type { DriftMode, DriftOptions, DriftReport } from "./verify/index.js";
+/**
+ * Deck directory in, mp4 out. Needs Chrome and ffmpeg, so — like `verify` —
+ * this is the batch half of the library, not the request path. `planTiming` and
+ * `framePlan` are exported beside it because they are pure arithmetic: a caller
+ * sizing a job, or costing a render before paying for it, wants the frame count
+ * without spawning anything.
+ */
+export { render } from "./render/render.js";
+export type { RenderOptions, RenderResult, SubtitleMode } from "./render/render.js";
+export { framePlan, planTiming, TIMING_FILE, toSrt } from "./render/timing.js";
+export type { FramePlan, Timing, TimingInput, TimedScene, TimedSegment } from "./render/timing.js";
+/** The .deck container. Read and write, because a server does both. */
+export { openPack, readPack, writePack } from "./pack/pack.js";
+export type { Pack, PackFiles } from "./pack/pack.js";
+export { mediaSummary, planMedia } from "./pack/media.js";
+export type { AssetRequest, Fetcher, Media, MediaPlan } from "./pack/media.js";
+/**
+ * `decksmith.config.json` and its defaults. `prefsFromFlags` is deliberately
+ * NOT here — it translates commander's flag object, which is the CLI's problem.
+ */
+export { CONFIG_FILE, loadPrefs } from "./prefs.js";
+export type { Prefs, PrefsPatch } from "./prefs.js";
+/**
+ * Every schema and type. Unusually broad for this file, and justified: `types.ts`
+ * is nothing but the wire format — what `source.json`, `storyboard.json`,
+ * `narration.json` and `.deck` already are on disk. It is a published contract
+ * whether or not this file re-exports it, so hiding half of it would only make
+ * consumers restate the halves they need.
+ */
+export * from "./types.js";
+/** Where the emitted deck's parts came from and where they went. */
+export interface BuildResult {
+    /** Absolute path of the directory written. */
+    out: string;
+    /** `deck.html` was written — true for navigable formats only. */
+    navigable: boolean;
+    /** Every path written, absolute, for a caller that wants to upload them. */
+    files: string[];
+    /**
+     * Which beats were drawn and why the rest were not.
+     *
+     * A caller with no terminal — a server, a queue worker — gets the same answer
+     * `build` prints, because "the short came out three minutes" is not a useful
+     * thing to learn without "and here is what it cost".
+     */
+    cut: Cut;
+}
+export interface BuildDeckOptions {
+    /**
+     * Called when one beat cannot be drawn, instead of failing the whole build.
+     * Absent, the emitter's error propagates — see `DeckOptions.onBeatError`.
+     */
+    onBeatError?: (beatId: string, err: Error) => void;
+    /** Any name in `THEME_NAMES`. Overrides `storyboard.theme`. */
+    theme?: string;
+    /** Multiplies every duration and hold. 1 leaves the bytes untouched. */
+    speed?: number;
+    /** Default `FORMATS["deck-16x9"]`. */
+    format?: Format;
+    /** From `narrate`. `dir` is where the mp3s sit relative to `deck.html`. */
+    narration?: DeckNarration;
+    /** Directory holding those mp3s now; they are copied into the deck. */
+    audioFrom?: string;
+    /** Directory whose `assets/` is copied in. Defaults to `out`'s neighbours. */
+    assetsFrom?: string;
+    /** Progress lines. Silent by default: a library that prints is a library you
+     *  cannot run inside a request handler. */
+    onStep?: (message: string) => void;
+}
+/**
+ * The `build` verb, minus argv: emit the deck and write everything it needs to
+ * open with no network — the composition, the navigable page, the player, the
+ * KaTeX CSS and fonts, the source's assets, the narration audio, and a refreshed
+ * font subset.
+ *
+ * It does NOT run the gates. `verify` needs the HyperFrames CLI and a browser,
+ * which a caller may not have and may not want on the request path; call it
+ * yourself when you do.
+ *
+ * NOTE: this is the same sequence as `build` in src/cli.ts, written out a second
+ * time rather than shared, because that file is owned elsewhere this pass. The
+ * next person to touch cli.ts should delete its copy and call this — two
+ * implementations of "what a deck directory contains" is exactly the kind of
+ * drift that ends in a deck that opens locally and 404s in production.
+ */
+export declare function buildDeck(storyboard: Storyboard, source: Source, outDir: string, opts?: BuildDeckOptions): Promise<BuildResult>;

package/dist/types/mcp/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/types/mcp/prereqs.d.ts

@@ -0,0 +1,22 @@
+export interface Prereq {
+    name: string;
+    ok: boolean;
+    /** The stage that cannot run without it. */
+    neededFor: string;
+    /** What to type. Named because "install ffmpeg" is not an instruction. */
+    install: string;
+    /** Version string when it answered, so a wrong-version bug is visible. */
+    version?: string;
+}
+/**
+ * Chrome is the odd one out: `hyperframes check` and the renderer each resolve
+ * their OWN browser, so probing one binary cannot prove either will find it.
+ * `npx puppeteer browsers install chrome` is what fixes it either way, and the
+ * probe is therefore advisory — hence the honest `neededFor` naming both stages.
+ */
+export declare function prereqs(): Promise<Prereq[]>;
+/** The ones a job with these options actually needs, and which are missing. */
+export declare function missingFor(found: readonly Prereq[], opts: {
+    narrate: boolean;
+    video: boolean;
+}): Prereq[];

package/dist/types/mcp/tools.d.ts

@@ -0,0 +1,212 @@
+import { z } from "zod";
+import { type Prereq } from "./prereqs.js";
+/**
+ * The settings surface, mirroring `prefsSchema` and validated by it downstream.
+ *
+ * Every field optional and NONE with a default — see the header. The
+ * descriptions carry what six sessions of measurement learned, because a tool
+ * schema is the only documentation an agent reads.
+ */
+export declare const settingsSchema: z.ZodObject<{
+    format: z.ZodOptional<z.ZodEnum<{
+        [x: string]: string;
+    }>>;
+    theme: z.ZodOptional<z.ZodEnum<{
+        [x: string]: string;
+    }>>;
+    lang: z.ZodOptional<z.ZodString>;
+    tone: z.ZodOptional<z.ZodEnum<{
+        plain: "plain";
+        academic: "academic";
+        conversational: "conversational";
+        punchy: "punchy";
+    }>>;
+    density: z.ZodOptional<z.ZodEnum<{
+        sparse: "sparse";
+        normal: "normal";
+        dense: "dense";
+    }>>;
+    duration: z.ZodOptional<z.ZodNumber>;
+    slides: z.ZodOptional<z.ZodInt>;
+    animation_speed: z.ZodOptional<z.ZodNumber>;
+    narrate: z.ZodOptional<z.ZodBoolean>;
+    voice: z.ZodOptional<z.ZodString>;
+    rate: z.ZodOptional<z.ZodString>;
+    pitch: z.ZodOptional<z.ZodString>;
+    narration_density: z.ZodOptional<z.ZodEnum<{
+        high: "high";
+        medium: "medium";
+        low: "low";
+    }>>;
+    video: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type Settings = z.infer<typeof settingsSchema>;
+export declare const capabilitiesSchema: z.ZodObject<{}, z.core.$strip>;
+export declare const estimateSchema: z.ZodObject<{
+    settings: z.ZodObject<{
+        format: z.ZodOptional<z.ZodEnum<{
+            [x: string]: string;
+        }>>;
+        theme: z.ZodOptional<z.ZodEnum<{
+            [x: string]: string;
+        }>>;
+        lang: z.ZodOptional<z.ZodString>;
+        tone: z.ZodOptional<z.ZodEnum<{
+            plain: "plain";
+            academic: "academic";
+            conversational: "conversational";
+            punchy: "punchy";
+        }>>;
+        density: z.ZodOptional<z.ZodEnum<{
+            sparse: "sparse";
+            normal: "normal";
+            dense: "dense";
+        }>>;
+        duration: z.ZodOptional<z.ZodNumber>;
+        slides: z.ZodOptional<z.ZodInt>;
+        animation_speed: z.ZodOptional<z.ZodNumber>;
+        narrate: z.ZodOptional<z.ZodBoolean>;
+        voice: z.ZodOptional<z.ZodString>;
+        rate: z.ZodOptional<z.ZodString>;
+        pitch: z.ZodOptional<z.ZodString>;
+        narration_density: z.ZodOptional<z.ZodEnum<{
+            high: "high";
+            medium: "medium";
+            low: "low";
+        }>>;
+        video: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const createSchema: z.ZodObject<{
+    document_path: z.ZodOptional<z.ZodString>;
+    document_text: z.ZodOptional<z.ZodString>;
+    settings: z.ZodOptional<z.ZodObject<{
+        format: z.ZodOptional<z.ZodEnum<{
+            [x: string]: string;
+        }>>;
+        theme: z.ZodOptional<z.ZodEnum<{
+            [x: string]: string;
+        }>>;
+        lang: z.ZodOptional<z.ZodString>;
+        tone: z.ZodOptional<z.ZodEnum<{
+            plain: "plain";
+            academic: "academic";
+            conversational: "conversational";
+            punchy: "punchy";
+        }>>;
+        density: z.ZodOptional<z.ZodEnum<{
+            sparse: "sparse";
+            normal: "normal";
+            dense: "dense";
+        }>>;
+        duration: z.ZodOptional<z.ZodNumber>;
+        slides: z.ZodOptional<z.ZodInt>;
+        animation_speed: z.ZodOptional<z.ZodNumber>;
+        narrate: z.ZodOptional<z.ZodBoolean>;
+        voice: z.ZodOptional<z.ZodString>;
+        rate: z.ZodOptional<z.ZodString>;
+        pitch: z.ZodOptional<z.ZodString>;
+        narration_density: z.ZodOptional<z.ZodEnum<{
+            high: "high";
+            medium: "medium";
+            low: "low";
+        }>>;
+        video: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    wait_seconds: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const statusSchema: z.ZodObject<{
+    job_id: z.ZodString;
+    wait_seconds: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export interface McpOptions {
+    /** Documents must live under here. Nothing outside is readable. */
+    root: string;
+    /** Where jobs write. Defaults under the OS temp dir. */
+    work: string;
+    /** Injected in tests so no test reaches the network or the clock. */
+    now?: () => number;
+    /**
+     * Injected for the same reason as `now`: which binaries a machine happens to
+     * have is not what a test is about, and CI has no Codex. Defaults to the real
+     * probe, so the server itself is unchanged.
+     */
+    probe?: () => Promise<Prereq[]>;
+}
+/**
+ * The four tools, over one queue.
+ *
+ * Returned as plain functions rather than registered against a transport so the
+ * tests can call them directly — the protocol is `main.ts`'s business and every
+ * behaviour worth checking is here.
+ */
+export declare function deckTools(opts: McpOptions): {
+    /** Formats, themes, every setting's range, and what is actually installed. */
+    capabilities(): Promise<{
+        prerequisites: Prereq[];
+        root: string;
+        work: string;
+    }>;
+    /**
+     * What a duration/slides/density combination costs, before a minute of Codex
+     * is spent finding out. Pure arithmetic — no job, no browser, instant.
+     *
+     * Returns `durationPlan`'s warnings VERBATIM. They are the product telling
+     * the author what their settings cost ("60s over 12 slides leaves 85
+     * characters a slide, which is one sentence"), and an MCP that swallowed
+     * them would ship the exact failure this project keeps having.
+     */
+    estimate(input: z.infer<typeof estimateSchema>): {
+        slides: number;
+        format: string;
+        seconds_per_slide: number | undefined;
+        animation_speed: number;
+        narration_rate: string;
+        characters_per_slide: number | undefined;
+        sentences_per_slide: number | undefined;
+        speech_seconds_per_slide: number | undefined;
+        warnings: string[];
+    };
+    /** Submit a document, wait a bounded slice, report. */
+    create(input: z.infer<typeof createSchema>): Promise<{
+        next: string;
+        deck_path?: string | undefined;
+        slides?: number | undefined;
+        duration_seconds?: number | undefined;
+        warnings?: string[] | undefined;
+        storyboard_path: string;
+        error?: import("../server/errors.js").JobError | undefined;
+        job_id: string;
+        state: import("../server/queue.js").JobState;
+        stage: import("../server/queue.js").Stage | undefined;
+        queue_position: number | undefined;
+        elapsed_seconds: number;
+        steps: {
+            name: import("../server/queue.js").Stage;
+            state: import("../server/queue.js").StepState;
+        }[];
+        log: string[];
+    }>;
+    /** Poll, blocking up to `wait_seconds` for the job to move on. */
+    status(input: z.infer<typeof statusSchema>): Promise<{
+        next: string;
+        deck_path?: string | undefined;
+        slides?: number | undefined;
+        duration_seconds?: number | undefined;
+        warnings?: string[] | undefined;
+        storyboard_path: string;
+        error?: import("../server/errors.js").JobError | undefined;
+        job_id: string;
+        state: import("../server/queue.js").JobState;
+        stage: import("../server/queue.js").Stage | undefined;
+        queue_position: number | undefined;
+        elapsed_seconds: number;
+        steps: {
+            name: import("../server/queue.js").Stage;
+            state: import("../server/queue.js").StepState;
+        }[];
+        log: string[];
+    }>;
+};
+/** Where jobs write when nobody said. */
+export declare function defaultWork(): string;

package/dist/types/narrate/narrate.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Storyboard plus preferences, spoken.
+ *
+ * The unit of narration is the STOP, not the beat. A beat's stops are where a
+ * presenter pauses — its landing, then each reveal the emitter recorded a hold
+ * for — and giving each one its own audio file is what lets the deck advance on
+ * speech rather than on a number somebody guessed into `beat.seconds`. Arrive at
+ * a stop, play its segment, step when it ends.
+ *
+ * Which means the stop count is not ours to decide: it belongs to the emitter
+ * that draws the scene. So this asks — it calls `emitScene` and counts the holds
+ * exactly the way `buildStops` will at playback — rather than assuming a beat has
+ * as many stops as it has sentences, which would silently desynchronise every
+ * archetype whose reveal count depends on its params.
+ */
+import type { z } from "zod";
+import type { Source, Storyboard } from "../types.js";
+import { type Beat, type Format, type prefsSchema, type segmentSchema } from "../types.js";
+import { type Runner } from "./tts.js";
+type Prefs = z.infer<typeof prefsSchema>;
+type Segment = z.infer<typeof segmentSchema>;
+type Narration = {
+    voice: string;
+    beats: Record<string, Segment[]>;
+};
+/**
+ * How many stops a beat has.
+ *
+ * Mirrors `buildStops`: the holds are deduplicated, a hold at the scene's own
+ * start is dropped (seeking there shows the frame before the entrance, i.e.
+ * nothing), the first survivor is the landing and the rest are steps. A scene
+ * with no holds at all is one stop — the slide itself.
+ */
+export declare function stopCount(holds: readonly number[]): number;
+/**
+ * Ask the emitter how the beat is staged. Cheap: emitters build strings.
+ *
+ * A beat the emitter REFUSES answers one stop rather than throwing. Narration
+ * runs before the build and is not the stage that gets to decide a deck is dead:
+ * `planCut` emits every beat again and drops the refused ones through
+ * `onBeatError`, which is where a missing slide is reported and where a caller
+ * without that hook still gets the error. Throwing here instead killed the whole
+ * job one stage early, with the hook the caller had passed never reached.
+ */
+export declare function stopsFor(beat: Beat, source: Source, format: Format, sid?: string): number;
+/**
+ * Split narration into sentences.
+ *
+ * The Latin terminators need whitespace or the end after them, so "0.5" and a
+ * trailing "et al." mid-clause stay whole; the CJK ones do not, because Chinese
+ * and Japanese put no space after 。 and a rule that waited for one would never
+ * split at all. Abbreviations like "e.g. " will still split — the cost is one
+ * clause landing on the wrong stop, which is a beat of drift, not a broken deck.
+ */
+export declare function splitSentences(text: string): string[];
+/**
+ * Lay sentences over stops, one each, in order.
+ *
+ * Two mismatches, two rules. Fewer sentences than stops: hand out what there is
+ * and leave the later stops SILENT — a deck that invents a sentence to fill a
+ * reveal is a deck that says something the author did not. More sentences than
+ * stops: the surplus joins the last one, so the tail is spoken over the beat's
+ * final state instead of being dropped.
+ *
+ * Returns one entry per stop; `""` means nothing is said there.
+ */
+export declare function planSegments(text: string, stops: number): string[];
+export interface NarrateOpts {
+    /** Directory the audio is written into. Returned paths are relative to it. */
+    dir: string;
+    /** Injected in tests so no test reaches the network. */
+    runner?: Runner;
+    /** Staging differs by canvas, so the stop count does too. */
+    format?: Format;
+}
+/**
+ * Narrate every beat that has something to say.
+ *
+ * Beats below a format's `minWeight` are narrated too: narration is stored in
+ * the pack, one storyboard renders as several formats, and re-synthesising the
+ * same sentence because a short dropped it is the one cost the cache exists to
+ * avoid. A beat with no `narration` text produces no segments at all rather than
+ * an empty array, so `Object.keys(narration.beats)` is the list of beats that
+ * actually speak.
+ */
+export declare function narrate(storyboard: Storyboard, source: Source, prefs: Prefs, opts: NarrateOpts): Promise<Narration>;
+export {};

package/dist/types/narrate/tts.d.ts

@@ -0,0 +1,134 @@
+import type { z } from "zod";
+import type { cueSchema } from "../types.js";
+type Cue = z.infer<typeof cueSchema>;
+/** One synthesis job, with the two files edge-tts is asked to write. */
+export interface SpeakJob {
+    text: string;
+    voice: string;
+    /** edge-tts prosody, e.g. "+10%" / "-5%". */
+    rate: string;
+    pitch: string;
+    /** Absolute path for the mp3. */
+    audio: string;
+    /** Absolute path for the SRT-shaped subtitle file. */
+    subs: string;
+}
+/**
+ * The two external programs, behind one seam.
+ *
+ * Injected rather than imported so no test needs the network — and so a caller
+ * with a different synthesiser can supply one without this module knowing.
+ *
+ * This is the LOW-level seam and it is edge-tts-shaped on purpose: two files on
+ * disk, one of them SRT. `SpeechProvider` below is the one to implement against
+ * for a different service.
+ */
+export interface Runner {
+    speak(job: SpeakJob): Promise<void>;
+    /** Seconds of rendered audio, or 0 when it cannot be measured. */
+    measure(audio: string): Promise<number>;
+}
+/** What a synthesiser is asked for. Paths are absolute; the mp3 must be written. */
+export interface SpeechRequest {
+    text: string;
+    voice: string;
+    /** Prosody, in the SSML-ish notation edge-tts uses: "+10%", "-5Hz". */
+    rate: string;
+    pitch: string;
+    /** Where to write the audio. */
+    audio: string;
+}
+/** What comes back. `cues` may be empty; the deck then shows no subtitles. */
+export interface SpeechResult {
+    seconds: number;
+    cues: Cue[];
+}
+/**
+ * A speech service, whole.
+ *
+ * The seam that matters for replacing edge-tts, and deliberately higher than
+ * `Runner`: a provider is handed text and hands back audio plus timing, and how
+ * it got the timing is its own business. `Runner` makes the caller write an SRT
+ * file and parse it, which is edge-tts's implementation showing through — a
+ * hosted API returning JSON word timings would have to fabricate a subtitle file
+ * to satisfy it.
+ *
+ * `check` is separate from `speak` so a missing binary or a bad key is reported
+ * before a job is accepted rather than a minute into one.
+ */
+export interface SpeechProvider {
+    readonly id: string;
+    check(): Promise<void>;
+    speak(req: SpeechRequest): Promise<SpeechResult>;
+}
+/**
+ * Find edge-tts, or say how to install it.
+ *
+ * A missing binary otherwise surfaces as ENOENT from `spawn` halfway through a
+ * build, which tells the user nothing they can act on. Memoised: the probe is a
+ * process launch, and a deck asks for dozens of segments.
+ */
+export declare function resolveEdgeTts(can?: (argv: string[]) => Promise<boolean>): Promise<string[]>;
+/** edge-tts over the network, ffprobe over the file. The production `Runner`. */
+export declare const edgeTts: Runner;
+/**
+ * Parse edge-tts' subtitle file into cues.
+ *
+ * Deliberately forgiving about the block numbers and about blank-line spacing:
+ * the file is machine-written, but it is also the one thing here we did not
+ * write, and a cue lost to a strict parser is a subtitle that silently vanishes.
+ */
+export declare function parseCues(srt: string): Cue[];
+export interface SynthOpts {
+    voice: string;
+    rate?: string;
+    pitch?: string;
+    /** Directory the mp3 and its sidecar are written into. Created if absent. */
+    dir: string;
+    /** The low-level edge-tts seam. Ignored when `provider` is given. */
+    runner?: Runner;
+    /** A whole synthesiser. The seam to use for anything that is not edge-tts. */
+    provider?: SpeechProvider;
+}
+export interface Speech {
+    /** Absolute path to the mp3. */
+    audio: string;
+    /** Its filename, which is also the cache key — what a caller stores. */
+    file: string;
+    seconds: number;
+    cues: Cue[];
+}
+/**
+ * edge-tts as a provider: it writes the mp3 and an SRT beside it, this parses
+ * the SRT and measures the mp3, and the SRT is gone before anyone sees it.
+ *
+ * Everything edge-tts-specific ends here. A second provider implements `speak`
+ * and returns its own timings; nothing upstream changes.
+ */
+export declare function edgeProvider(runner?: Runner): SpeechProvider;
+/**
+ * Providers by name, and how one is chosen.
+ *
+ * A record rather than a switch, so adding a service is adding an entry. The
+ * environment variable exists so a deployment can change synthesiser without a
+ * rebuild — which is the whole reason this seam is here.
+ */
+export declare const PROVIDERS: Record<string, () => SpeechProvider>;
+export declare function resolveProvider(name?: string): SpeechProvider;
+/**
+ * The cache key, and therefore the filename.
+ *
+ * Content-addressed on everything that changes the sound, so re-narrating an
+ * edited deck re-synthesises only the beats whose words moved. That is the
+ * difference between a four-second edit loop and a three-minute one, and it is
+ * also why two beats that say the same sentence share one file.
+ */
+export declare function cacheKey(text: string, voice: string, rate: string, pitch: string): string;
+/**
+ * Speak `text`, and return where it landed and how long it takes.
+ *
+ * `seconds` is measured, never estimated — it is what lets a stop last exactly
+ * as long as the sentence spoken at it.
+ */
+export declare function synthesize(text: string, opts: SynthOpts): Promise<Speech>;
+export {};