playwright-director 0.2.0

package/dist/timeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline.d.ts","sourceRoot":"","sources":["../src/timeline.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,YAAY;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB;8DAC0D;IAC1D,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB;2FACuF;IACvF,SAAS,EAAE,MAAM,CAAC;IAClB,yFAAyF;IACzF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;IACpB;;sEAEkE;IAClE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,+BAA+B;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;sEAEkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,qBAAa,gBAAgB;IAC5B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,SAAS,CAAa;IAC9B,OAAO,CAAC,WAAW,CAAa;IAChC,OAAO,CAAC,UAAU,CAAkB;IACpC,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,SAAS,CAAc;gBAG9B,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,MAAW,EACrB,WAAW,GAAE,MAAW,EACxB,IAAI,GAAE,MAAa,EACnB,SAAS,GAAE,MAAW,EACtB,OAAO,GAAE,MAAW,EACpB,YAAY,GAAE,oBAAyB,EACvC,KAAK,GAAE,MAAW,EAClB,OAAO,GAAE,MAAW;IAarB;;OAEG;IACH,KAAK,CAAC,WAAW,GAAE,MAAU,EAAE,UAAU,GAAE,OAAe,GAAG,IAAI;IAOjE;;OAEG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIhC;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI;IAe5J;;OAEG;IACH,OAAO,IAAI,YAAY;IA2BvB;;OAEG;IACH,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;CAY9B"}

package/dist/timeline.js

@@ -0,0 +1,108 @@
+import { writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+import { buildMergeCommand } from './merge.js';
+import { buildTranscriptMarkdown } from './transcript.js';
+/**
+ * Tracks timing of tutorial steps for post-processing audio merge.
+ */
+export class TutorialTimeline {
+    testName;
+    testTitle;
+    title = '';
+    testFile;
+    projectName;
+    lang;
+    feature = '';
+    variant = '';
+    musicOptions;
+    startTime = 0;
+    videoTrimMs = 0;
+    syncMarker = false;
+    steps = [];
+    videoPath = '';
+    constructor(testName, testFile = '', projectName = '', lang = 'fr', testTitle = '', feature = '', musicOptions = {}, title = '', variant = '') {
+        this.variant = variant;
+        this.testName = testName;
+        this.testTitle = testTitle;
+        this.title = title;
+        this.testFile = testFile;
+        this.projectName = projectName;
+        this.lang = lang;
+        this.feature = feature;
+        this.musicOptions = musicOptions;
+    }
+    /**
+     * Mark the start of the tutorial (second 0 for video)
+     */
+    start(videoTrimMs = 0, syncMarker = false) {
+        this.startTime = Date.now();
+        this.videoTrimMs = videoTrimMs;
+        this.syncMarker = syncMarker;
+        console.log(`[Timeline] Started at ${new Date().toISOString()} (trim ${videoTrimMs}ms from video start)`);
+    }
+    /**
+     * Set the video path (from Playwright's page.video()?.path())
+     */
+    setVideoPath(path) {
+        this.videoPath = path;
+    }
+    /**
+     * Record a step at a specific timestamp (for accurate voice timing)
+     */
+    addStep(step, title, audioFile, durationMs, timestamp, text, key, scene) {
+        const startMs = timestamp - this.startTime;
+        this.steps.push({
+            step,
+            title,
+            ...(text ? { text } : {}),
+            ...(key ? { key } : {}),
+            ...(scene ? { scene } : {}),
+            audioFile,
+            startMs,
+            durationMs
+        });
+        console.log(`[Timeline] Step ${step}: "${title}" at ${startMs}ms (${durationMs}ms audio)`);
+    }
+    /**
+     * Get the timeline data with merge command
+     */
+    getData() {
+        const data = {
+            testName: this.testName,
+            testTitle: this.testTitle,
+            title: this.title || undefined,
+            testFile: this.testFile,
+            projectName: this.projectName,
+            lang: this.lang,
+            feature: this.feature || undefined,
+            variant: this.variant || undefined,
+            totalDurationMs: Date.now() - this.startTime,
+            videoTrimMs: this.videoTrimMs,
+            syncMarker: this.syncMarker || undefined,
+            steps: this.steps,
+            videoPath: this.videoPath
+        };
+        // Output filename is already language-specific (testName = slugified translated title).
+        // No `-en` / `-ar` suffix needed — each locale produces its own SEO-friendly slug.
+        const { command } = buildMergeCommand(data, this.videoPath, `tutorials/videos/${this.testName}.webm`, this.musicOptions);
+        return {
+            ...data,
+            mergeCommand: command
+        };
+    }
+    /**
+     * Save timeline to JSON file and auto-generate transcript markdown.
+     */
+    save(outputPath) {
+        const data = this.getData();
+        writeFileSync(outputPath, JSON.stringify(data, null, 2));
+        console.log(`[Timeline] Saved to ${outputPath}`);
+        const transcriptDir = join(process.cwd(), 'tutorials/transcripts');
+        if (!existsSync(transcriptDir))
+            mkdirSync(transcriptDir, { recursive: true });
+        const transcriptPath = join(transcriptDir, `${data.testName}.md`);
+        writeFileSync(transcriptPath, buildTranscriptMarkdown(data), 'utf-8');
+        console.log(`[Timeline] Transcript: tutorials/transcripts/${data.testName}.md`);
+    }
+}
+//# sourceMappingURL=timeline.js.map

package/dist/timeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline.js","sourceRoot":"","sources":["../src/timeline.ts"],"names":[],"mappings":"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"}

package/dist/transcript.d.ts

@@ -0,0 +1,87 @@
+import type { TimelineData } from './timeline.js';
+/** One narrated entry of a transcript markdown file. */
+export interface TranscriptEntry {
+    kind: 'context' | 'step' | 'complete';
+    /** i18n key of the step/context (from the `**key:**` line, when present) */
+    key?: string;
+    /** Step title (from the `### Step N: <title>` heading) */
+    title?: string;
+    /** Narration text */
+    text: string;
+}
+/**
+ * Build the transcript markdown for a timeline. Shared by the automatic
+ * generation in `TutorialTimeline.save()` and the `tutorial-transcript` CLI,
+ * so both always produce the same format `parseTranscript` reads back.
+ */
+export declare function buildTranscriptMarkdown(data: TimelineData): string;
+/**
+ * Parse a transcript markdown file back into its narrated entries.
+ * Tolerant of surrounding noise (header, comments, separators): only the
+ * `**[Context]**`, `**[Complete]**`, `### Step N:` and `**key:**` markers
+ * plus step body text are significant.
+ */
+export declare function parseTranscript(markdown: string): TranscriptEntry[];
+/**
+ * Narration overrides loaded from an edited transcript
+ * (`tutorials/transcripts/<testName>.corrections.md`).
+ *
+ * Entries are matched by kind + key, consumed in file order so a key used
+ * twice corrects each occurrence in turn. Entries without a key (older
+ * transcript files) fall back to kind-order matching.
+ */
+export declare class TranscriptCorrections {
+    private queues;
+    constructor(entries: TranscriptEntry[]);
+    /** Load corrections from a file; null when the file does not exist. */
+    static load(path: string): TranscriptCorrections | null;
+    /**
+     * Consume the next correction for this kind (+ key). Exact key match
+     * first, then keyless entries of the same kind as an ordered fallback.
+     */
+    next(kind: TranscriptEntry['kind'], key?: string): string | undefined;
+    /** Corrections that never matched a narrated step — likely stale keys. */
+    get remaining(): number;
+    describeRemaining(): string[];
+}
+export interface ApplyChange {
+    kind: TranscriptEntry['kind'];
+    key?: string;
+    file: string;
+    from: string;
+    to: string;
+}
+export interface ApplyProblem extends ApplyChange {
+    reason: string;
+}
+export interface ApplyReport {
+    /** Replacements written into source files */
+    applied: ApplyChange[];
+    /** Corrections that could not be applied automatically */
+    manual: ApplyProblem[];
+    /** Narrated steps whose text was not edited */
+    unchanged: number;
+    /** Files that were modified */
+    files: string[];
+    /** True when step texts changed in the timeline data (caller should re-save the JSON) */
+    timelineUpdated: boolean;
+}
+/** Filesystem boundary, injectable for deterministic tests. */
+export interface ApplyIO {
+    read(path: string): string | null;
+    write(path: string, content: string): void;
+}
+/**
+ * Write edited transcript texts back into the test source file.
+ *
+ * Each narrated timeline step is paired with its transcript entry (kind + key,
+ * in order). When the edited text differs, the original text is located in
+ * `data.testFile` as a quoted string literal and replaced. A narration composed
+ * as `` `${do}. ${explain}` `` (or title + description) is handled by replacing
+ * both halves, splitting old and new at the first sentence boundary. Texts that
+ * cannot be found (e.g. coming from an i18n catalog) are reported for manual
+ * correction with their key. Applied texts are also written back into the
+ * timeline data, keeping a second `apply` run idempotent.
+ */
+export declare function applyCorrections(data: TimelineData, entries: TranscriptEntry[], io: ApplyIO): ApplyReport;
+//# sourceMappingURL=transcript.d.ts.map

package/dist/transcript.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcript.d.ts","sourceRoot":"","sources":["../src/transcript.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,wDAAwD;AACxD,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,UAAU,CAAC;IACtC,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;CACb;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAqClE;AAOD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,EAAE,CAqDnE;AAED;;;;;;;GAOG;AACH,qBAAa,qBAAqB;IACjC,OAAO,CAAC,MAAM,CAA+B;gBAEjC,OAAO,EAAE,eAAe,EAAE;IAStC,uEAAuE;IACvE,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,qBAAqB,GAAG,IAAI;IAMvD;;;OAGG;IACH,IAAI,CAAC,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAUrE,0EAA0E;IAC1E,IAAI,SAAS,IAAI,MAAM,CAItB;IAED,iBAAiB,IAAI,MAAM,EAAE;CAS7B;AAID,MAAM,WAAW,WAAW;IAC3B,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACX;AAED,MAAM,WAAW,YAAa,SAAQ,WAAW;IAChD,MAAM,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC3B,6CAA6C;IAC7C,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,0DAA0D;IAC1D,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,+BAA+B;IAC/B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,yFAAyF;IACzF,eAAe,EAAE,OAAO,CAAC;CACzB;AAED,+DAA+D;AAC/D,MAAM,WAAW,OAAO;IACvB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAClC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3C;AAmCD;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC/B,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,eAAe,EAAE,EAC1B,EAAE,EAAE,OAAO,GACT,WAAW,CAgGb"}

package/dist/transcript.js

@@ -0,0 +1,291 @@
+import { readFileSync, existsSync } from 'fs';
+/**
+ * Build the transcript markdown for a timeline. Shared by the automatic
+ * generation in `TutorialTimeline.save()` and the `tutorial-transcript` CLI,
+ * so both always produce the same format `parseTranscript` reads back.
+ */
+export function buildTranscriptMarkdown(data) {
+    const lines = [];
+    lines.push(`# ${data.testName}`);
+    lines.push('');
+    lines.push(`- **Test:** \`${data.testTitle}\``);
+    lines.push(`- **Language:** ${data.lang}`);
+    lines.push(`- **Duration:** ${(data.totalDurationMs / 1000).toFixed(1)}s`);
+    lines.push('');
+    lines.push('<!-- Edit the narration texts below, then run `npx tutorial-transcript apply`');
+    lines.push('     to write the corrections back into the test source. -->');
+    lines.push('');
+    lines.push('---');
+    lines.push('');
+    let stepNum = 0;
+    for (const step of data.steps) {
+        // Unvoiced steps (empty audioFile) have no narration to correct.
+        if (!step.text || !step.audioFile)
+            continue;
+        if (step.step === 0 && step.title === 'Context') {
+            lines.push(`**[Context]** ${step.text}`);
+            if (step.key)
+                lines.push(`**key:** \`${step.key}\``);
+            lines.push('');
+        }
+        else if (step.title === 'Complete') {
+            lines.push(`**[Complete]** ${step.text}`);
+            lines.push('');
+        }
+        else {
+            stepNum++;
+            lines.push(`### Step ${stepNum}: ${step.title}`);
+            if (step.key)
+                lines.push(`**key:** \`${step.key}\``);
+            lines.push('');
+            lines.push(step.text);
+            lines.push('');
+        }
+    }
+    return lines.join('\n');
+}
+const KEY_LINE = /^\*\*key:\*\* `(.+)`\s*$/;
+const STEP_HEADING = /^### Step \d+: (.*)$/;
+const CONTEXT_LINE = /^\*\*\[Context\]\*\* (.*)$/;
+const COMPLETE_LINE = /^\*\*\[Complete\]\*\* (.*)$/;
+/**
+ * Parse a transcript markdown file back into its narrated entries.
+ * Tolerant of surrounding noise (header, comments, separators): only the
+ * `**[Context]**`, `**[Complete]**`, `### Step N:` and `**key:**` markers
+ * plus step body text are significant.
+ */
+export function parseTranscript(markdown) {
+    const entries = [];
+    let current = null;
+    let bodyLines = [];
+    const flush = () => {
+        if (current && current.kind === 'step') {
+            current.text = bodyLines.join(' ').replace(/\s+/g, ' ').trim();
+        }
+        if (current && current.text)
+            entries.push(current);
+        current = null;
+        bodyLines = [];
+    };
+    for (const rawLine of markdown.split('\n')) {
+        const line = rawLine.trimEnd();
+        const context = line.match(CONTEXT_LINE);
+        if (context) {
+            flush();
+            current = { kind: 'context', text: context[1].trim() };
+            continue;
+        }
+        const complete = line.match(COMPLETE_LINE);
+        if (complete) {
+            flush();
+            current = { kind: 'complete', text: complete[1].trim() };
+            continue;
+        }
+        const heading = line.match(STEP_HEADING);
+        if (heading) {
+            flush();
+            current = { kind: 'step', title: heading[1].trim(), text: '' };
+            continue;
+        }
+        const keyLine = line.match(KEY_LINE);
+        if (keyLine) {
+            if (current)
+                current.key = keyLine[1];
+            continue;
+        }
+        // Everything else is either step body text or ignorable scaffolding.
+        if (current?.kind === 'step') {
+            if (line.startsWith('#') || line.startsWith('---') || line.startsWith('<!--'))
+                continue;
+            if (line.trim())
+                bodyLines.push(line.trim());
+        }
+    }
+    flush();
+    return entries;
+}
+/**
+ * Narration overrides loaded from an edited transcript
+ * (`tutorials/transcripts/<testName>.corrections.md`).
+ *
+ * Entries are matched by kind + key, consumed in file order so a key used
+ * twice corrects each occurrence in turn. Entries without a key (older
+ * transcript files) fall back to kind-order matching.
+ */
+export class TranscriptCorrections {
+    queues = new Map();
+    constructor(entries) {
+        for (const entry of entries) {
+            const bucket = `${entry.kind}:${entry.key ?? ''}`;
+            const queue = this.queues.get(bucket) ?? [];
+            queue.push(entry.text);
+            this.queues.set(bucket, queue);
+        }
+    }
+    /** Load corrections from a file; null when the file does not exist. */
+    static load(path) {
+        if (!existsSync(path))
+            return null;
+        const entries = parseTranscript(readFileSync(path, 'utf-8'));
+        return entries.length > 0 ? new TranscriptCorrections(entries) : null;
+    }
+    /**
+     * Consume the next correction for this kind (+ key). Exact key match
+     * first, then keyless entries of the same kind as an ordered fallback.
+     */
+    next(kind, key) {
+        const exact = this.queues.get(`${kind}:${key ?? ''}`);
+        if (exact && exact.length > 0)
+            return exact.shift();
+        if (key) {
+            const keyless = this.queues.get(`${kind}:`);
+            if (keyless && keyless.length > 0)
+                return keyless.shift();
+        }
+        return undefined;
+    }
+    /** Corrections that never matched a narrated step — likely stale keys. */
+    get remaining() {
+        let count = 0;
+        for (const queue of this.queues.values())
+            count += queue.length;
+        return count;
+    }
+    describeRemaining() {
+        const out = [];
+        for (const [bucket, queue] of this.queues) {
+            for (const text of queue) {
+                out.push(`[${bucket}] ${text.slice(0, 60)}${text.length > 60 ? '…' : ''}`);
+            }
+        }
+        return out;
+    }
+}
+const QUOTES = ["'", '"', '`'];
+function escapeLiteral(text, quote) {
+    return text.split('\\').join('\\\\').split(quote).join('\\' + quote);
+}
+/** Find `oldText` as a complete quoted string literal and swap it for `newText`.
+ *  Searches from `cursor` first (source order follows step order), then from 0. */
+function replaceQuoted(content, cursor, oldText, newText) {
+    for (const start of cursor > 0 ? [cursor, 0] : [0]) {
+        let best = null;
+        for (const quote of QUOTES) {
+            const needle = quote + escapeLiteral(oldText, quote) + quote;
+            const at = content.indexOf(needle, start);
+            if (at !== -1 && (!best || at < best.at))
+                best = { at, quote };
+        }
+        if (best) {
+            const needle = best.quote + escapeLiteral(oldText, best.quote) + best.quote;
+            const replacement = best.quote + escapeLiteral(newText, best.quote) + best.quote;
+            return {
+                content: content.slice(0, best.at) + replacement + content.slice(best.at + needle.length),
+                at: best.at
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Write edited transcript texts back into the test source file.
+ *
+ * Each narrated timeline step is paired with its transcript entry (kind + key,
+ * in order). When the edited text differs, the original text is located in
+ * `data.testFile` as a quoted string literal and replaced. A narration composed
+ * as `` `${do}. ${explain}` `` (or title + description) is handled by replacing
+ * both halves, splitting old and new at the first sentence boundary. Texts that
+ * cannot be found (e.g. coming from an i18n catalog) are reported for manual
+ * correction with their key. Applied texts are also written back into the
+ * timeline data, keeping a second `apply` run idempotent.
+ */
+export function applyCorrections(data, entries, io) {
+    const corrections = new TranscriptCorrections(entries);
+    const report = { applied: [], manual: [], unchanged: 0, files: [], timelineUpdated: false };
+    let content = data.testFile ? io.read(data.testFile) : null;
+    let dirty = false;
+    let cursor = 0;
+    for (const step of data.steps) {
+        if (!step.text || !step.audioFile)
+            continue;
+        const kind = step.step === 0 && step.title === 'Context' ? 'context'
+            : step.title === 'Complete' ? 'complete'
+                : 'step';
+        const corrected = corrections.next(kind, step.key);
+        if (!corrected || corrected === step.text) {
+            report.unchanged++;
+            continue;
+        }
+        const change = { kind, key: step.key, file: data.testFile, from: step.text, to: corrected };
+        if (content === null) {
+            report.manual.push({ ...change, reason: `test file not found: ${data.testFile || '(unknown)'}` });
+            continue;
+        }
+        // 1. The whole narration as one literal (voiceText, do-only, plain title…)
+        let result = replaceQuoted(content, cursor, step.text, corrected);
+        // 2. Two-part narration: `${do}. ${explain}` / `${title}. ${description}` —
+        //    replace each half, splitting old and new at the first sentence boundary.
+        let keyEditBlocked = false;
+        if (!result) {
+            const oldSplit = step.text.indexOf('. ');
+            const newSplit = corrected.indexOf('. ');
+            if (oldSplit > 0 && newSplit > 0) {
+                const oldFirst = step.text.slice(0, oldSplit);
+                const newFirst = corrected.slice(0, newSplit);
+                const oldRest = step.text.slice(oldSplit + 2);
+                const newRest = corrected.slice(newSplit + 2);
+                if (oldFirst === step.key) {
+                    // The first sentence IS the i18n key rendered verbatim (identity
+                    // translate). Rewriting it would break the key — only the rest
+                    // may be edited from the transcript.
+                    if (newFirst === oldFirst) {
+                        result = replaceQuoted(content, cursor, oldRest, newRest);
+                    }
+                    else {
+                        keyEditBlocked = true;
+                    }
+                }
+                else {
+                    const first = replaceQuoted(content, cursor, oldFirst, newFirst);
+                    if (first) {
+                        const second = replaceQuoted(first.content, cursor, oldRest, newRest);
+                        if (second)
+                            result = { content: second.content, at: Math.max(first.at, second.at) };
+                    }
+                }
+            }
+        }
+        if (result) {
+            content = result.content;
+            cursor = result.at;
+            dirty = true;
+            step.text = corrected;
+            report.timelineUpdated = true;
+            report.applied.push(change);
+        }
+        else if (keyEditBlocked) {
+            report.manual.push({
+                ...change,
+                reason: `the first sentence is the step key \`${step.key}\` — rename the key in the test (or fix its translation) instead of editing it here`
+            });
+        }
+        else {
+            const hint = step.key
+                ? ` — probably an i18n text (key \`${step.key}\`), fix it in the translation catalog`
+                : '';
+            report.manual.push({ ...change, reason: `text not found as a string literal in ${data.testFile}${hint}` });
+        }
+    }
+    for (const desc of corrections.describeRemaining()) {
+        report.manual.push({
+            kind: 'step', file: data.testFile, from: '', to: desc,
+            reason: 'transcript entry matches no narrated step (stale key after a test change?)'
+        });
+    }
+    if (dirty && content !== null) {
+        io.write(data.testFile, content);
+        report.files.push(data.testFile);
+    }
+    return report;
+}
+//# sourceMappingURL=transcript.js.map

package/dist/transcript.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcript.js","sourceRoot":"","sources":["../src/transcript.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAc9C;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAkB;IACzD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;IACjC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,iBAAiB,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC;IAChD,KAAK,CAAC,IAAI,CAAC,mBAAmB,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IAC3C,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC3E,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,+EAA+E,CAAC,CAAC;IAC5F,KAAK,CAAC,IAAI,CAAC,8DAA8D,CAAC,CAAC;IAC3E,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QAC/B,iEAAiE;QACjE,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS;YAAE,SAAS;QAE5C,IAAI,IAAI,CAAC,IAAI,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YACjD,KAAK,CAAC,IAAI,CAAC,iBAAiB,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;YACzC,IAAI,IAAI,CAAC,GAAG;gBAAE,KAAK,CAAC,IAAI,CAAC,cAAc,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;YACrD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAChB,CAAC;aAAM,IAAI,IAAI,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;YACtC,KAAK,CAAC,IAAI,CAAC,kBAAkB,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;YAC1C,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAChB,CAAC;aAAM,CAAC;YACP,OAAO,EAAE,CAAC;YACV,KAAK,CAAC,IAAI,CAAC,YAAY,OAAO,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;YACjD,IAAI,IAAI,CAAC,GAAG;gBAAE,KAAK,CAAC,IAAI,CAAC,cAAc,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;YACrD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACtB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAChB,CAAC;IACF,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC;AAED,MAAM,QAAQ,GAAG,0BAA0B,CAAC;AAC5C,MAAM,YAAY,GAAG,sBAAsB,CAAC;AAC5C,MAAM,YAAY,GAAG,4BAA4B,CAAC;AAClD,MAAM,aAAa,GAAG,6BAA6B,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC/C,MAAM,OAAO,GAAsB,EAAE,CAAC;IACtC,IAAI,OAAO,GAA2B,IAAI,CAAC;IAC3C,IAAI,SAAS,GAAa,EAAE,CAAC;IAE7B,MAAM,KAAK,GAAG,GAAG,EAAE;QAClB,IAAI,OAAO,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YACxC,OAAO,CAAC,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;QAChE,CAAC;QACD,IAAI,OAAO,IAAI,OAAO,CAAC,IAAI;YAAE,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACnD,OAAO,GAAG,IAAI,CAAC;QACf,SAAS,GAAG,EAAE,CAAC;IAChB,CAAC,CAAC;IAEF,KAAK,MAAM,OAAO,IAAI,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;QAE/B,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;QACzC,IAAI,OAAO,EAAE,CAAC;YACb,KAAK,EAAE,CAAC;YACR,OAAO,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;YACvD,SAAS;QACV,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;QAC3C,IAAI,QAAQ,EAAE,CAAC;YACd,KAAK,EAAE,CAAC;YACR,OAAO,GAAG,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;YACzD,SAAS;QACV,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;QACzC,IAAI,OAAO,EAAE,CAAC;YACb,KAAK,EAAE,CAAC;YACR,OAAO,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;YAC/D,SAAS;QACV,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QACrC,IAAI,OAAO,EAAE,CAAC;YACb,IAAI,OAAO;gBAAE,OAAO,CAAC,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;YACtC,SAAS;QACV,CAAC;QAED,qEAAqE;QACrE,IAAI,OAAO,EAAE,IAAI,KAAK,MAAM,EAAE,CAAC;YAC9B,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;gBAAE,SAAS;YACxF,IAAI,IAAI,CAAC,IAAI,EAAE;gBAAE,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QAC9C,CAAC;IACF,CAAC;IACD,KAAK,EAAE,CAAC;IAER,OAAO,OAAO,CAAC;AAChB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,qBAAqB;IACzB,MAAM,GAAG,IAAI,GAAG,EAAoB,CAAC;IAE7C,YAAY,OAA0B;QACrC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC7B,MAAM,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,GAAG,IAAI,EAAE,EAAE,CAAC;YAClD,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YAC5C,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACvB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAChC,CAAC;IACF,CAAC;IAED,uEAAuE;IACvE,MAAM,CAAC,IAAI,CAAC,IAAY;QACvB,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QACnC,MAAM,OAAO,GAAG,eAAe,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;QAC7D,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,qBAAqB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACvE,CAAC;IAED;;;OAGG;IACH,IAAI,CAAC,IAA6B,EAAE,GAAY;QAC/C,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,IAAI,GAAG,IAAI,EAAE,EAAE,CAAC,CAAC;QACtD,IAAI,KAAK,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC,KAAK,EAAE,CAAC;QACpD,IAAI,GAAG,EAAE,CAAC;YACT,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC;YAC5C,IAAI,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;gBAAE,OAAO,OAAO,CAAC,KAAK,EAAE,CAAC;QAC3D,CAAC;QACD,OAAO,SAAS,CAAC;IAClB,CAAC;IAED,0EAA0E;IAC1E,IAAI,SAAS;QACZ,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE;YAAE,KAAK,IAAI,KAAK,CAAC,MAAM,CAAC;QAChE,OAAO,KAAK,CAAC;IACd,CAAC;IAED,iBAAiB;QAChB,MAAM,GAAG,GAAa,EAAE,CAAC;QACzB,KAAK,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAC3C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBAC1B,GAAG,CAAC,IAAI,CAAC,IAAI,MAAM,KAAK,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC5E,CAAC;QACF,CAAC;QACD,OAAO,GAAG,CAAC;IACZ,CAAC;CACD;AAmCD,MAAM,MAAM,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAU,CAAC;AAExC,SAAS,aAAa,CAAC,IAAY,EAAE,KAAa;IACjD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC;AACtE,CAAC;AAED;mFACmF;AACnF,SAAS,aAAa,CACrB,OAAe,EACf,MAAc,EACd,OAAe,EACf,OAAe;IAEf,KAAK,MAAM,KAAK,IAAI,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACpD,IAAI,IAAI,GAAyC,IAAI,CAAC;QACtD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC5B,MAAM,MAAM,GAAG,KAAK,GAAG,aAAa,CAAC,OAAO,EAAE,KAAK,CAAC,GAAG,KAAK,CAAC;YAC7D,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;YAC1C,IAAI,EAAE,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,IAAI,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;gBAAE,IAAI,GAAG,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;QAChE,CAAC;QACD,IAAI,IAAI,EAAE,CAAC;YACV,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,GAAG,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC;YAC5E,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,GAAG,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC;YACjF,OAAO;gBACN,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,CAAC,GAAG,WAAW,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC;gBACzF,EAAE,EAAE,IAAI,CAAC,EAAE;aACX,CAAC;QACH,CAAC;IACF,CAAC;IACD,OAAO,IAAI,CAAC;AACb,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAC/B,IAAkB,EAClB,OAA0B,EAC1B,EAAW;IAEX,MAAM,WAAW,GAAG,IAAI,qBAAqB,CAAC,OAAO,CAAC,CAAC;IACvD,MAAM,MAAM,GAAgB,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,eAAe,EAAE,KAAK,EAAE,CAAC;IAEzG,IAAI,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC5D,IAAI,KAAK,GAAG,KAAK,CAAC;IAClB,IAAI,MAAM,GAAG,CAAC,CAAC;IAEf,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QAC/B,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS;YAAE,SAAS;QAE5C,MAAM,IAAI,GACT,IAAI,CAAC,IAAI,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS;YACvD,CAAC,CAAC,IAAI,CAAC,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,UAAU;gBACxC,CAAC,CAAC,MAAM,CAAC;QAEV,MAAM,SAAS,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;QACnD,IAAI,CAAC,SAAS,IAAI,SAAS,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC;YAC3C,MAAM,CAAC,SAAS,EAAE,CAAC;YACnB,SAAS;QACV,CAAC;QAED,MAAM,MAAM,GAAgB,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC;QAEzG,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACtB,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,wBAAwB,IAAI,CAAC,QAAQ,IAAI,WAAW,EAAE,EAAE,CAAC,CAAC;YAClG,SAAS;QACV,CAAC;QAED,2EAA2E;QAC3E,IAAI,MAAM,GAAG,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QAElE,4EAA4E;QAC5E,8EAA8E;QAC9E,IAAI,cAAc,GAAG,KAAK,CAAC;QAC3B,IAAI,CAAC,MAAM,EAAE,CAAC;YACb,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACzC,MAAM,QAAQ,GAAG,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACzC,IAAI,QAAQ,GAAG,CAAC,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;gBAClC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;gBAC9C,MAAM,QAAQ,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;gBAC9C,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC;gBAC9C,MAAM,OAAO,GAAG,SAAS,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC;gBAE9C,IAAI,QAAQ,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC;oBAC3B,iEAAiE;oBACjE,+DAA+D;oBAC/D,qCAAqC;oBACrC,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;wBAC3B,MAAM,GAAG,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;oBAC3D,CAAC;yBAAM,CAAC;wBACP,cAAc,GAAG,IAAI,CAAC;oBACvB,CAAC;gBACF,CAAC;qBAAM,CAAC;oBACP,MAAM,KAAK,GAAG,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;oBACjE,IAAI,KAAK,EAAE,CAAC;wBACX,MAAM,MAAM,GAAG,aAAa,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;wBACtE,IAAI,MAAM;4BAAE,MAAM,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;oBACrF,CAAC;gBACF,CAAC;YACF,CAAC;QACF,CAAC;QAED,IAAI,MAAM,EAAE,CAAC;YACZ,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;YACzB,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;YACnB,KAAK,GAAG,IAAI,CAAC;YACb,IAAI,CAAC,IAAI,GAAG,SAAS,CAAC;YACtB,MAAM,CAAC,eAAe,GAAG,IAAI,CAAC;YAC9B,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC7B,CAAC;aAAM,IAAI,cAAc,EAAE,CAAC;YAC3B,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;gBAClB,GAAG,MAAM;gBACT,MAAM,EAAE,wCAAwC,IAAI,CAAC,GAAG,qFAAqF;aAC7I,CAAC,CAAC;QACJ,CAAC;aAAM,CAAC;YACP,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG;gBACpB,CAAC,CAAC,mCAAmC,IAAI,CAAC,GAAG,wCAAwC;gBACrF,CAAC,CAAC,EAAE,CAAC;YACN,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,yCAAyC,IAAI,CAAC,QAAQ,GAAG,IAAI,EAAE,EAAE,CAAC,CAAC;QAC5G,CAAC;IACF,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,iBAAiB,EAAE,EAAE,CAAC;QACpD,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;YAClB,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,EAAE,IAAI;YACrD,MAAM,EAAE,4EAA4E;SACpF,CAAC,CAAC;IACJ,CAAC;IAED,IAAI,KAAK,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QAC/B,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACjC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAClC,CAAC;IAED,OAAO,MAAM,CAAC;AACf,CAAC"}

package/dist/tts-provider.d.ts

@@ -0,0 +1,69 @@
+export interface TTSResult {
+    filePath: string;
+    duration: number;
+}
+export interface TTSProvider {
+    readonly name: string;
+    synthesize(text: string, outputPath: string): Promise<TTSResult>;
+    isAvailable(): Promise<boolean>;
+}
+export interface TTSProviderOptions {
+    lang: string;
+    voice?: string;
+    rate?: number;
+}
+/**
+ * Command-based TTS provider. Defaults to macOS `say`, can be overridden
+ * via TUTORIAL_TTS_CMD env var.
+ * Supports placeholders: {lang}, {text}, {output}.
+ * If {text}/{output} are present they are substituted in-place; otherwise
+ * the legacy "-o <output> <text>" suffix is appended automatically.
+ * Examples:
+ *   TUTORIAL_TTS_CMD='qsay --my-voice jadou -l {lang} {text} -o {output}'
+ *   TUTORIAL_TTS_CMD='say -v Thomas'   (legacy: appends -o <out> "<text>")
+ */
+export declare class CommandTTSProvider implements TTSProvider {
+    readonly name: string;
+    private command;
+    private options;
+    private static VOICES;
+    private static LANG_NAMES;
+    private static _logged;
+    constructor(options: TTSProviderOptions);
+    isAvailable(): Promise<boolean>;
+    synthesize(text: string, outputPath: string): Promise<TTSResult>;
+}
+/** Edge TTS provider using Microsoft's free TTS API */
+export declare class EdgeTTSProvider implements TTSProvider {
+    readonly name = "edge-tts";
+    private options;
+    private static VOICES;
+    constructor(options: TTSProviderOptions);
+    isAvailable(): Promise<boolean>;
+    synthesize(text: string, outputPath: string): Promise<TTSResult>;
+}
+/** Auto-detect and create the best available TTS provider */
+export declare function createTTSProvider(options: TTSProviderOptions): Promise<TTSProvider>;
+/** Audio segment info for later merging */
+export interface AudioSegment {
+    filePath: string;
+    timestamp: number;
+    duration: number;
+    text: string;
+}
+/** Manages TTS audio generation and tracking for tutorials */
+export declare class TTSManager {
+    private provider;
+    private options;
+    private outputDir;
+    private segments;
+    private recordingStartTime;
+    constructor(options: TTSProviderOptions, outputDir: string);
+    initialize(): Promise<void>;
+    startRecording(): void;
+    speak(text: string): Promise<number>;
+    getSegments(): AudioSegment[];
+    /** Generate a manifest file for post-processing */
+    writeManifest(videoPath: string): Promise<string>;
+}
+//# sourceMappingURL=tts-provider.d.ts.map

package/dist/tts-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tts-provider.d.ts","sourceRoot":"","sources":["../src/tts-provider.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,SAAS;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IACjE,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAeD;;;;;;;;;GASG;AACH,qBAAa,kBAAmB,YAAW,WAAW;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAqB;IAEpC,OAAO,CAAC,MAAM,CAAC,MAAM,CAInB;IAEF,OAAO,CAAC,MAAM,CAAC,UAAU,CAIvB;IAEF,OAAO,CAAC,MAAM,CAAC,OAAO,CAAS;gBAEnB,OAAO,EAAE,kBAAkB;IAmBjC,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAU/B,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;CAWtE;AAED,uDAAuD;AACvD,qBAAa,eAAgB,YAAW,WAAW;IAClD,QAAQ,CAAC,IAAI,cAAc;IAC3B,OAAO,CAAC,OAAO,CAAqB;IAEpC,OAAO,CAAC,MAAM,CAAC,MAAM,CAInB;gBAEU,OAAO,EAAE,kBAAkB;IAIjC,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAS/B,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;CAYtE;AAED,6DAA6D;AAC7D,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC,CAczF;AAED,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACb;AAED,8DAA8D;AAC9D,qBAAa,UAAU;IACtB,OAAO,CAAC,QAAQ,CAA4B;IAC5C,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAsB;IACtC,OAAO,CAAC,kBAAkB,CAAa;gBAE3B,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM;IAKpD,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAQjC,cAAc,IAAI,IAAI;IAKhB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAqB1C,WAAW,IAAI,YAAY,EAAE;IAI7B,mDAAmD;IAC7C,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAavD"}