demowright 2.4.0 → 2.5.0

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.4.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": {