demowright 2.3.0 → 2.5.0

package/dist/helpers.d.mts

@@ -34,6 +34,23 @@ declare function clickEl(page: Page, selector: string): Promise<void>;
  *   If omitted, uses `document.activeElement`.
  */
 declare function typeKeys(page: Page, text: string, delay?: number, inputSelector?: string): Promise<void>;
+/**
+ * Pre-fetch TTS audio for all narration texts in parallel.
+ * Call this at the start of a test to eliminate per-annotate wait times.
+ *
+ * ```ts
+ * const narrations = [
+ *   "Welcome to the demo",
+ *   "Now clicking the button",
+ *   "That wraps up the tour",
+ * ];
+ * await prefetchTts(page, narrations);
+ *
+ * // All subsequent annotate/narrate calls hit the cache instantly
+ * await annotate(page, narrations[0], async () => { ... });
+ * ```
+ */
+declare function prefetchTts(page: Page, texts: string[]): Promise<void>;
 /**
  * Speak `text` via the configured TTS provider, or fall back to
  * the browser's speechSynthesis API.
@@ -92,4 +109,4 @@ declare function annotate(page: Page, text: string, callbackOrOptions?: (() => P
   voice?: string;
 }, callback?: () => Promise<void>): Promise<void>;
 //#endregion
-export { annotate, caption, clickEl, hudWait, moveTo, moveToEl, narrate, subtitle, typeKeys };
+export { annotate, caption, clickEl, hudWait, moveTo, moveToEl, narrate, prefetchTts, subtitle, typeKeys };

package/dist/helpers.mjs

@@ -129,16 +129,48 @@ async function typeKeys(page, text, delay = 65, inputSelector) {
 		await page.waitForTimeout(delay);
 	}
 }
-/** Fetch audio from a TTS provider. Returns a WAV Buffer. */
+const ttsCache = /* @__PURE__ */ new Map();
+/** Fetch audio from a TTS provider. Returns a WAV Buffer (cached). */
 async function fetchTtsAudio(text, provider) {
+	const cached = ttsCache.get(text);
+	if (cached) return cached;
+	let buf;
 	if (typeof provider === "string") {
 		const url = provider.replace(/%s/g, encodeURIComponent(text));
 		const res = await fetch(url);
 		if (!res.ok) throw new Error(`TTS fetch ${res.status}`);
-		return Buffer.from(await res.arrayBuffer());
+		buf = Buffer.from(await res.arrayBuffer());
+	} else {
+		const result = await provider(text);
+		buf = Buffer.isBuffer(result) ? result : Buffer.from(result);
 	}
-	const result = await provider(text);
-	return Buffer.isBuffer(result) ? result : Buffer.from(result);
+	ttsCache.set(text, buf);
+	return buf;
+}
+/**
+* Pre-fetch TTS audio for all narration texts in parallel.
+* Call this at the start of a test to eliminate per-annotate wait times.
+*
+* ```ts
+* const narrations = [
+*   "Welcome to the demo",
+*   "Now clicking the button",
+*   "That wraps up the tour",
+* ];
+* await prefetchTts(page, narrations);
+*
+* // All subsequent annotate/narrate calls hit the cache instantly
+* await annotate(page, narrations[0], async () => { ... });
+* ```
+*/
+async function prefetchTts(page, texts) {
+	const provider = getTtsProvider(page);
+	if (!provider) return;
+	const uncached = texts.filter((t) => !ttsCache.has(t));
+	if (uncached.length === 0) return;
+	console.log(`[demowright] Prefetching ${uncached.length} TTS segments...`);
+	const failed = (await Promise.allSettled(uncached.map((text) => fetchTtsAudio(text, provider)))).filter((r) => r.status === "rejected").length;
+	if (failed > 0) console.warn(`[demowright] ${failed}/${uncached.length} TTS prefetch failed`);
 }
 /** Parse WAV and return { float32, sampleRate, channels, durationMs }. */
 function parseWav(wavBuf) {
@@ -318,4 +350,4 @@ async function annotate(page, text, callbackOrOptions, callback) {
 	}, cb)]);
 }
 //#endregion
-export { annotate, caption, clickEl, hudWait, moveTo, moveToEl, narrate, subtitle, typeKeys };
+export { annotate, caption, clickEl, hudWait, moveTo, moveToEl, narrate, prefetchTts, subtitle, typeKeys };

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { installAutoAnnotate } from "./auto-annotate.mjs";
 import { a as AudioWriter, n as TtsProvider, r as applyHud, t as QaHudOptions } from "./setup-8X-3F3M7.mjs";
-import { annotate, caption, clickEl, hudWait, moveTo, moveToEl, narrate, subtitle, typeKeys } from "./helpers.mjs";
+import { annotate, caption, clickEl, hudWait, moveTo, moveToEl, narrate, prefetchTts, subtitle, typeKeys } from "./helpers.mjs";
 import { OutroOptions, PaceFn, RenderOptions, TimelineEntry, TitleOptions, VideoScriptResult, buildFfmpegCommand, createVideoScript } from "./video-script.mjs";
 import { Page as Page$1, expect } from "@playwright/test";
 import * as _$electron from "electron";
@@ -54041,4 +54041,4 @@ declare const test: TestType<PlaywrightTestArgs & PlaywrightTestOptions & {
  */
 declare function getGlobalTtsProvider(): TtsProvider;
 //#endregion
-export { AudioWriter, type OutroOptions, type PaceFn, type QaHudOptions, type RenderOptions, type TimelineEntry, type TitleOptions, type TtsProvider, type VideoScriptResult, annotate, applyHud, buildFfmpegCommand, caption, clickEl, createVideoScript, expect, getGlobalTtsProvider, hudWait, installAutoAnnotate, moveTo, moveToEl, narrate, subtitle, test, typeKeys };
+export { AudioWriter, type OutroOptions, type PaceFn, type QaHudOptions, type RenderOptions, type TimelineEntry, type TitleOptions, type TtsProvider, type VideoScriptResult, annotate, applyHud, buildFfmpegCommand, caption, clickEl, createVideoScript, expect, getGlobalTtsProvider, hudWait, installAutoAnnotate, moveTo, moveToEl, narrate, prefetchTts, subtitle, test, typeKeys };

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import { r as AudioWriter, t as applyHud } from "./setup-c_UpOQ7a.mjs";
 import { i as getGlobalTtsProvider, s as init_hud_registry } from "./hud-registry-Wfd4b4Nu.mjs";
 import { buildFfmpegCommand, createVideoScript, t as init_video_script } from "./video-script.mjs";
-import { annotate, caption, clickEl, hudWait, moveTo, moveToEl, narrate, subtitle, typeKeys } from "./helpers.mjs";
+import { annotate, caption, clickEl, hudWait, moveTo, moveToEl, narrate, prefetchTts, subtitle, typeKeys } from "./helpers.mjs";
 import { installAutoAnnotate } from "./auto-annotate.mjs";
 import { expect, test as test$1 } from "@playwright/test";
 //#region src/fixture.ts
@@ -26,4 +26,4 @@ const test = test$1.extend({
 init_video_script();
 init_hud_registry();
 //#endregion
-export { AudioWriter, annotate, applyHud, buildFfmpegCommand, caption, clickEl, createVideoScript, expect, getGlobalTtsProvider, hudWait, installAutoAnnotate, moveTo, moveToEl, narrate, subtitle, test, typeKeys };
+export { AudioWriter, annotate, applyHud, buildFfmpegCommand, caption, clickEl, createVideoScript, expect, getGlobalTtsProvider, hudWait, installAutoAnnotate, moveTo, moveToEl, narrate, prefetchTts, subtitle, test, typeKeys };

package/dist/video-script.d.mts

@@ -20,6 +20,8 @@ interface SegmentStep {
   kind: "segment";
   text: string;
   action?: SegmentAction;
+  /** Runs BEFORE narration starts — use for navigation, page.goto(), scrolls, etc. */
+  setup?: () => Promise<void>;
 }
 interface TransitionStep {
   kind: "transition";
@@ -104,9 +106,18 @@ declare class VideoScriptImpl {
   title(text: string, opts?: TitleOptions): this;
   /**
    * Add a narrated segment — TTS audio drives timing, callback runs paced actions.
-   * Same as NarrationPlan's `.annotate()` but named `.segment()` for clarity.
+   *
+   * Two signatures (backwards-compatible):
+   *   .segment("narration", async (pace) => { ... })
+   *   .segment("narration", { setup: async () => { ... }, action: async (pace) => { ... } })
+   *
+   * `setup` runs BEFORE narration starts — use for page.goto(), scrolling, etc.
+   * `action` runs DURING narration — use for visual actions like safeMove, hover.
    */
-  segment(text: string, action?: SegmentAction): this;
+  segment(text: string, actionOrOpts?: SegmentAction | {
+    setup?: () => Promise<void>;
+    action?: SegmentAction;
+  }): this;
   /**
    * Add a transition between segments.
    * Applied as an ffmpeg filter during render.

package/dist/video-script.mjs

@@ -282,13 +282,29 @@ var init_video_script = __esmMin((() => {
 		}
 		/**
 		* Add a narrated segment — TTS audio drives timing, callback runs paced actions.
-		* Same as NarrationPlan's `.annotate()` but named `.segment()` for clarity.
+		*
+		* Two signatures (backwards-compatible):
+		*   .segment("narration", async (pace) => { ... })
+		*   .segment("narration", { setup: async () => { ... }, action: async (pace) => { ... } })
+		*
+		* `setup` runs BEFORE narration starts — use for page.goto(), scrolling, etc.
+		* `action` runs DURING narration — use for visual actions like safeMove, hover.
 		*/
-		segment(text, action) {
-			this.steps.push({
+		segment(text, actionOrOpts) {
+			if (typeof actionOrOpts === "function") this.steps.push({
+				kind: "segment",
+				text,
+				action: actionOrOpts
+			});
+			else if (actionOrOpts && typeof actionOrOpts === "object") this.steps.push({
 				kind: "segment",
 				text,
-				action
+				action: actionOrOpts.action,
+				setup: actionOrOpts.setup
+			});
+			else this.steps.push({
+				kind: "segment",
+				text
 			});
 			return this;
 		}
@@ -459,7 +475,7 @@ var init_video_script = __esmMin((() => {
 			let segmentIndex = 0;
 			for (let i = 0; i < this.steps.length; i++) {
 				const step = this.steps[i];
-				const stepStartMs = Date.now();
+				let stepStartMs = Date.now();
 				if (step.kind === "title" || step.kind === "outro") {
 					const bg = step.background ?? DEFAULT_BG;
 					const cardTts = step.narration ? this.prepared.get(`card-${i}`) : void 0;
@@ -499,6 +515,10 @@ var init_video_script = __esmMin((() => {
 						overrunMs: 0
 					});
 				} else if (step.kind === "segment") {
+					if (step.setup) {
+						await step.setup();
+						stepStartMs = Date.now();
+					}
 					const segId = `step-${segmentIndex}`;
 					segmentIndex++;
 					const segment = this.prepared.get(segId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "demowright",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "Playwright video production plugin — cursor overlay, keystroke badges, TTS narration, and narration-driven video scripts for test recordings",
   "license": "MIT",
   "repository": {