playwright-recast 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrik Szewczyk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,282 @@
+# playwright-recast
+
+**Transform Playwright traces into stunning demo videos — automatically.**
+
+[![npm version](https://img.shields.io/npm/v/playwright-recast)](https://www.npmjs.com/package/playwright-recast)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+> Your Playwright tests already capture everything — traces, screenshots, network activity, cursor positions. **playwright-recast** turns those artifacts into polished, narrated product videos with a single fluent pipeline.
+
+![Demo — Google Search with ElevenLabs voiceover](demo/output/demo.mp4)
+
+---
+
+## Why?
+
+Recording product demos is painful. Every UI change means re-recording. Manual voiceover and subtitling takes hours. Timing is always off.
+
+**playwright-recast** flips this:** your Playwright tests become your video source.** Write tests once, regenerate polished videos on every deploy.
+
+```typescript
+import { Recast, ElevenLabsProvider } from 'playwright-recast'
+
+await Recast
+  .from('./test-results/trace.zip')
+  .parse()
+  .speedUp({ duringIdle: 3.0, duringUserAction: 1.0 })
+  .subtitlesFromSrt('./narration.srt')
+  .voiceover(ElevenLabsProvider({ voiceId: 'daniel' }))
+  .render({ format: 'mp4', resolution: '1080p' })
+  .toFile('demo.mp4')
+```
+
+**That's it.** Trace in, polished video out.
+
+---
+
+## Features
+
+- **Fluent pipeline API** — Chainable, immutable, lazy-evaluated. Build complex pipelines that read like English.
+- **Trace-based processing** — Parses Playwright trace.zip (actions, screenshots, network, cursor positions). No manual recording needed.
+- **Smart speed control** — Automatically speeds up idle time, network waits, and navigation while keeping user actions at normal speed.
+- **TTS voiceover** — Generate narration with OpenAI TTS or ElevenLabs. Properly timed with silence padding.
+- **Subtitle generation** — SRT and WebVTT output. Import external SRT or generate from trace BDD step titles.
+- **playwright-bdd support** — First-class integration with playwright-bdd Gherkin steps. Doc strings become voiceover narration.
+- **Step helpers** — `narrate()`, `zoom()`, `pace()` — importable helpers for Playwright step definitions.
+- **CLI included** — `npx playwright-recast -i trace.zip -o demo.mp4` — no code needed.
+- **Zero lock-in** — Every stage is optional. Use just the trace parser, just the subtitle generator, or the full pipeline.
+
+---
+
+## Quick Start
+
+### Install
+
+```bash
+npm install playwright-recast
+# or
+bun add playwright-recast
+```
+
+**System requirement:** `ffmpeg` and `ffprobe` must be on your PATH.
+
+```bash
+# macOS
+brew install ffmpeg
+
+# Ubuntu
+sudo apt install ffmpeg
+```
+
+### CLI Usage
+
+```bash
+# Basic — trace to video
+npx playwright-recast -i ./test-results/trace.zip -o demo.mp4
+
+# With speed processing
+npx playwright-recast -i ./traces --speed-idle 4.0 --speed-action 1.0
+
+# With external SRT subtitles
+npx playwright-recast -i ./traces --srt narration.srt --burn-subs
+
+# With TTS voiceover (OpenAI)
+npx playwright-recast -i ./traces --srt narration.srt --provider openai --voice nova
+
+# With TTS voiceover (ElevenLabs)
+npx playwright-recast -i ./traces --srt narration.srt --provider elevenlabs --voice onwK4e9ZLuTAKqWW03F9
+```
+
+### Programmatic API
+
+```typescript
+import { Recast, OpenAIProvider } from 'playwright-recast'
+
+// Minimal — just trace to video
+await Recast.from('./traces').parse().render().toFile('output.mp4')
+
+// Full pipeline
+await Recast
+  .from('./test-results/')
+  .parse()
+  .hideSteps(s => s.keyword === 'Given' && s.text?.includes('logged in'))
+  .speedUp({
+    duringIdle: 4.0,
+    duringUserAction: 1.0,
+    duringNetworkWait: 2.0,
+    minSegmentDuration: 500,
+  })
+  .subtitlesFromSrt('./narration.srt')
+  .voiceover(OpenAIProvider({
+    voice: 'nova',
+    speed: 1.2,
+    instructions: 'Professional product demo narration.',
+  }))
+  .render({ format: 'mp4', resolution: '1080p', burnSubtitles: true })
+  .toFile('demo.mp4')
+```
+
+### playwright-bdd Integration
+
+Use `narrate()` and `pace()` in your BDD step definitions:
+
+```typescript
+// steps/fixtures.ts
+import { test } from 'playwright-bdd'
+import { setupRecast, narrate, pace } from 'playwright-recast'
+
+setupRecast(test)
+export { narrate, pace }
+
+// steps/my-steps.ts
+import { Given, When, Then } from './fixtures'
+import { narrate, pace } from 'playwright-recast'
+
+Given('the user opens the dashboard', async ({ page }, docString?: string) => {
+  narrate(docString)
+  await page.goto('/dashboard')
+  await pace(page, 4000)
+})
+```
+
+```gherkin
+Feature: Dashboard demo
+
+  Scenario: View analytics
+    Given the user opens the dashboard
+      """
+      Let's open the analytics dashboard to see real-time metrics.
+      """
+    When the user clicks the revenue chart
+      """
+      Clicking on the revenue chart reveals detailed breakdown.
+      """
+```
+
+---
+
+## Pipeline Stages
+
+Every stage is optional and composable:
+
+| Stage | Description |
+|-------|-------------|
+| `.parse()` | Parse Playwright trace.zip into structured data (actions, frames, network, cursor) |
+| `.hideSteps(predicate)` | Remove steps from the output (e.g., login, setup) |
+| `.speedUp(config)` | Adjust video speed based on activity (idle, action, network) |
+| `.subtitles(textFn)` | Generate subtitles from trace actions |
+| `.subtitlesFromSrt(path)` | Load subtitles from an external SRT file |
+| `.subtitlesFromTrace()` | Auto-generate subtitles from BDD step titles in trace |
+| `.voiceover(provider)` | Generate TTS audio from subtitle text |
+| `.render(config)` | Render final video (format, resolution, burn subtitles) |
+| `.toFile(path)` | Execute pipeline and write output |
+
+---
+
+## TTS Providers
+
+### OpenAI TTS
+
+```typescript
+import { OpenAIProvider } from 'playwright-recast/providers/openai'
+
+OpenAIProvider({
+  voice: 'nova',          // alloy, echo, fable, onyx, nova, shimmer
+  model: 'gpt-4o-mini-tts',
+  speed: 1.2,
+  instructions: 'Calm, professional demo narration.',
+})
+```
+
+Requires `OPENAI_API_KEY` environment variable or `apiKey` option.
+
+### ElevenLabs
+
+```typescript
+import { ElevenLabsProvider } from 'playwright-recast/providers/elevenlabs'
+
+ElevenLabsProvider({
+  voiceId: 'onwK4e9ZLuTAKqWW03F9',  // Daniel
+  modelId: 'eleven_multilingual_v2',
+})
+```
+
+Requires `ELEVENLABS_API_KEY` environment variable or `apiKey` option.
+
+---
+
+## Speed Processing
+
+The speed processor classifies every moment of the trace:
+
+| Activity | Default Speed | Description |
+|----------|---------------|-------------|
+| **User Action** | 1.0x | Clicks, fills, keyboard input — real-time |
+| **Navigation** | 2.0x | Page loads, redirects — slightly faster |
+| **Network Wait** | 2.0x | API calls in flight — compress wait time |
+| **Idle** | 4.0x | Nothing happening — skip quickly |
+
+```typescript
+.speedUp({
+  duringIdle: 4.0,
+  duringUserAction: 1.0,
+  duringNetworkWait: 2.0,
+  duringNavigation: 2.0,
+  minSegmentDuration: 500,  // Avoid jarring speed changes
+  maxSpeed: 8.0,            // Safety cap
+})
+```
+
+---
+
+## Architecture
+
+```
+Trace.zip → ParsedTrace → FilteredTrace → SpeedMappedTrace → SubtitledTrace → VoiceoveredTrace → MP4
+               ↑               ↑                ↑                  ↑                 ↑              ↑
+            parse()       hideSteps()        speedUp()         subtitles()       voiceover()     render()
+```
+
+The pipeline is **lazy** — calling chain methods builds a pipeline description. Nothing executes until `.toFile()` or `.toBuffer()` is called.
+
+Each pipeline instance is **immutable** — every method returns a new pipeline, so you can branch:
+
+```typescript
+const base = Recast.from('./traces').parse().speedUp({ duringIdle: 3.0 })
+
+// Branch A: with voiceover
+await base.subtitlesFromSrt('./en.srt').voiceover(openai).render().toFile('demo-en.mp4')
+
+// Branch B: subtitles only
+await base.subtitlesFromSrt('./cs.srt').render({ burnSubtitles: true }).toFile('demo-cs.mp4')
+```
+
+---
+
+## Roadmap
+
+- [ ] **Smooth zoom transitions** — Animated crop-and-zoom on elements during specific steps
+- [ ] **Edge TTS provider** — Free TTS without API key using Microsoft Edge's online voices
+- [ ] **Playwright Reporter plugin** — Auto-generate demo videos as part of your test run
+- [ ] **Multi-language support** — Generate video variants from the same trace with different SRT/voiceover per language
+- [ ] **Intro/outro cards** — Configurable title cards, branding overlays, and end screens
+- [ ] **Background music** — Mix ambient music track under voiceover with auto-ducking
+
+---
+
+## Contributing
+
+Contributions welcome! Please check the [issues](https://github.com/ThePatriczek/playwright-recast/issues) for open tasks.
+
+```bash
+git clone https://github.com/ThePatriczek/playwright-recast.git
+cd playwright-recast
+npm install
+npm test
+```
+
+---
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { Pipeline as Recast } from './pipeline/pipeline';
+const help = `
+playwright-recast — Convert Playwright traces to polished demo videos
+
+USAGE
+  playwright-recast --input <trace-dir-or-zip> [options]
+
+OPTIONS
+  -i, --input          Trace directory or zip path (required)
+  -o, --output         Output file path (default: ./recast-output.mp4)
+      --srt            External SRT subtitle file path
+      --speed-idle     Speed for idle periods (default: 3.0)
+      --speed-action   Speed for user actions (default: 1.0)
+      --speed-network  Speed for network waits (default: 2.0)
+      --no-speed       Disable speed processing
+      --provider       TTS provider: openai | elevenlabs | none (default: none)
+      --voice          Voice ID for TTS provider
+      --model          Model ID for TTS provider
+      --tts-speed      TTS speech speed multiplier
+      --format         Output format: mp4 | webm (default: mp4)
+      --resolution     Output resolution: 720p | 1080p (default: 1080p)
+      --burn-subs      Burn subtitles into video
+  -h, --help           Show this help message
+
+EXAMPLES
+  playwright-recast -i ./test-results -o demo.mp4
+  playwright-recast -i trace.zip --speed-idle 4 --burn-subs
+  playwright-recast -i ./traces --srt narration.srt --provider openai --voice nova
+`.trim();
+function fatal(message) {
+    console.error(`Error: ${message}`);
+    process.exit(1);
+}
+async function main() {
+    const { values } = parseArgs({
+        options: {
+            input: { type: 'string', short: 'i' },
+            output: { type: 'string', short: 'o' },
+            srt: { type: 'string' },
+            'speed-idle': { type: 'string' },
+            'speed-action': { type: 'string' },
+            'speed-network': { type: 'string' },
+            'no-speed': { type: 'boolean', default: false },
+            provider: { type: 'string' },
+            voice: { type: 'string' },
+            model: { type: 'string' },
+            'tts-speed': { type: 'string' },
+            format: { type: 'string' },
+            resolution: { type: 'string' },
+            'burn-subs': { type: 'boolean', default: false },
+            help: { type: 'boolean', short: 'h', default: false },
+        },
+        strict: true,
+        allowPositionals: false,
+    });
+    if (values.help) {
+        console.log(help);
+        process.exit(0);
+    }
+    const input = values.input;
+    if (!input) {
+        fatal('--input / -i is required. Use --help for usage information.');
+    }
+    const output = values.output ?? './recast-output.mp4';
+    const format = values.format ?? 'mp4';
+    const resolution = values.resolution ?? '1080p';
+    const burnSubtitles = values['burn-subs'] ?? false;
+    // Build the pipeline
+    let pipeline = Recast.from(input).parse();
+    // Speed processing
+    if (!values['no-speed']) {
+        const speedIdle = values['speed-idle'] ? Number(values['speed-idle']) : 3.0;
+        const speedAction = values['speed-action'] ? Number(values['speed-action']) : 1.0;
+        const speedNetwork = values['speed-network'] ? Number(values['speed-network']) : 2.0;
+        if (Number.isNaN(speedIdle))
+            fatal('--speed-idle must be a number');
+        if (Number.isNaN(speedAction))
+            fatal('--speed-action must be a number');
+        if (Number.isNaN(speedNetwork))
+            fatal('--speed-network must be a number');
+        pipeline = pipeline.speedUp({
+            duringIdle: speedIdle,
+            duringUserAction: speedAction,
+            duringNetworkWait: speedNetwork,
+        });
+    }
+    // Subtitles
+    if (values.srt) {
+        pipeline = pipeline.subtitlesFromSrt(values.srt);
+    }
+    else {
+        pipeline = pipeline.subtitles((action) => action.docString ?? action.text);
+    }
+    // Voiceover
+    const providerName = values.provider ?? 'none';
+    if (providerName !== 'none') {
+        const ttsSpeed = values['tts-speed'] ? Number(values['tts-speed']) : undefined;
+        if (values['tts-speed'] && Number.isNaN(ttsSpeed)) {
+            fatal('--tts-speed must be a number');
+        }
+        if (providerName === 'openai') {
+            const { OpenAIProvider } = await import('./voiceover/providers/openai');
+            pipeline = pipeline.voiceover(OpenAIProvider({
+                voice: values.voice,
+                model: values.model,
+                speed: ttsSpeed,
+            }));
+        }
+        else if (providerName === 'elevenlabs') {
+            const { ElevenLabsProvider } = await import('./voiceover/providers/elevenlabs');
+            pipeline = pipeline.voiceover(ElevenLabsProvider({
+                voiceId: values.voice,
+                modelId: values.model,
+            }));
+        }
+        else {
+            fatal(`Unknown provider: ${providerName}. Use openai, elevenlabs, or none.`);
+        }
+    }
+    // Render
+    pipeline = pipeline.render({
+        format,
+        resolution,
+        burnSubtitles,
+    });
+    // Execute
+    console.log(`Processing trace: ${input}`);
+    console.log(`Output: ${output} (${format}, ${resolution})`);
+    await pipeline.toFile(output);
+    console.log(`Done! Video saved to: ${output}`);
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`Fatal error: ${message}`);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/filter/step-filter.d.ts

@@ -0,0 +1,7 @@
+import type { ParsedTrace, FilteredTrace, TraceAction } from '../types/trace';
+/**
+ * Filter out actions matching the predicate.
+ * Hidden actions are removed from the action list and their time ranges are recorded.
+ */
+export declare function filterSteps(trace: ParsedTrace, predicate: (action: TraceAction) => boolean): FilteredTrace;
+//# sourceMappingURL=step-filter.d.ts.map

package/dist/filter/step-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step-filter.d.ts","sourceRoot":"","sources":["../../src/filter/step-filter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAe,MAAM,gBAAgB,CAAA;AAE1F;;;GAGG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,WAAW,EAClB,SAAS,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,GAC1C,aAAa,CAkBf"}

package/dist/filter/step-filter.js

@@ -0,0 +1,23 @@
+/**
+ * Filter out actions matching the predicate.
+ * Hidden actions are removed from the action list and their time ranges are recorded.
+ */
+export function filterSteps(trace, predicate) {
+    const hidden = [];
+    const visible = [];
+    for (const action of trace.actions) {
+        if (predicate(action)) {
+            hidden.push({ start: action.startTime, end: action.endTime });
+        }
+        else {
+            visible.push(action);
+        }
+    }
+    return {
+        ...trace,
+        originalActions: trace.actions,
+        actions: visible,
+        hiddenRanges: hidden,
+    };
+}
+//# sourceMappingURL=step-filter.js.map

package/dist/filter/step-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"step-filter.js","sourceRoot":"","sources":["../../src/filter/step-filter.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,UAAU,WAAW,CACzB,KAAkB,EAClB,SAA2C;IAE3C,MAAM,MAAM,GAAoD,EAAE,CAAA;IAClE,MAAM,OAAO,GAAkB,EAAE,CAAA;IAEjC,KAAK,MAAM,MAAM,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QACnC,IAAI,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YACtB,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,SAAS,EAAE,GAAG,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAA;QAC/D,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QACtB,CAAC;IACH,CAAC;IAED,OAAO;QACL,GAAG,KAAK;QACR,eAAe,EAAE,KAAK,CAAC,OAAO;QAC9B,OAAO,EAAE,OAAO;QAChB,YAAY,EAAE,MAAM;KACrB,CAAA;AACH,CAAC"}

package/dist/helpers.d.ts

@@ -0,0 +1,41 @@
+import type { Page, Locator, TestInfo } from '@playwright/test';
+/**
+ * Initialize playwright-recast helpers with the test instance.
+ * Call once in your fixtures file:
+ *
+ * ```typescript
+ * import { test } from 'playwright-bdd'
+ * import { setupRecast } from '@workspace/playwright-recast/helpers'
+ * setupRecast(test)
+ * ```
+ */
+export declare function setupRecast(testInstance: {
+    info: () => TestInfo;
+}): void;
+/**
+ * Attach voiceover narration text to the current step.
+ * Call from EVERY step definition (even without doc string) so
+ * the reporter can match annotations to steps by sequential index.
+ *
+ * @param text Doc string content (voiceover text). Pass undefined if none.
+ * @param opts.hidden Mark step as hidden (not recorded, excluded from SRT)
+ */
+export declare function narrate(text: string | undefined, opts?: {
+    hidden?: boolean;
+}): void;
+/**
+ * Zoom into a Playwright element during this step.
+ * Gets the element's bounding box and stores relative coordinates as annotation.
+ * The renderer applies crop+scale during this step's time window.
+ *
+ * @param locator Playwright Locator to zoom into
+ * @param level Zoom level (1.0 = no zoom, 1.5 = 1.5x closer)
+ */
+export declare function zoom(locator: Locator, level?: number): Promise<void>;
+/**
+ * Ensure a demo step takes at least `ms` milliseconds.
+ * Call at the END of a step to pad with a visual pause
+ * so the video has enough time for voiceover narration.
+ */
+export declare function pace(page: Page, ms: number): Promise<void>;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAgB/D;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;CAAE,GAAG,IAAI,CAExE;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CACrB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAC1B,IAAI,CAUN;AAED;;;;;;;GAOG;AACH,wBAAsB,IAAI,CACxB,OAAO,EAAE,OAAO,EAChB,KAAK,GAAE,MAAY,GAClB,OAAO,CAAC,IAAI,CAAC,CAef;AAED;;;;GAIG;AACH,wBAAsB,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhE"}

package/dist/helpers.js

@@ -0,0 +1,73 @@
+/**
+ * Get current test info — works in both playwright-bdd and standard Playwright.
+ * Must be called from within a test context.
+ */
+function getTestInfo() {
+    // @playwright/test provides test.info() but we can't import 'test' generically.
+    // Instead, we use the global __test_info__ or accept it as parameter.
+    throw new Error('getTestInfo() must be overridden. Call Recast.setup(test) first.');
+}
+let _getTestInfo = getTestInfo;
+/**
+ * Initialize playwright-recast helpers with the test instance.
+ * Call once in your fixtures file:
+ *
+ * ```typescript
+ * import { test } from 'playwright-bdd'
+ * import { setupRecast } from '@workspace/playwright-recast/helpers'
+ * setupRecast(test)
+ * ```
+ */
+export function setupRecast(testInstance) {
+    _getTestInfo = () => testInstance.info();
+}
+/**
+ * Attach voiceover narration text to the current step.
+ * Call from EVERY step definition (even without doc string) so
+ * the reporter can match annotations to steps by sequential index.
+ *
+ * @param text Doc string content (voiceover text). Pass undefined if none.
+ * @param opts.hidden Mark step as hidden (not recorded, excluded from SRT)
+ */
+export function narrate(text, opts) {
+    const hidden = opts?.hidden ?? text?.includes('@hidden') ?? false;
+    const cleanText = text?.replace(/@hidden\s*/g, '').trim() || '';
+    const info = _getTestInfo();
+    info.annotations.push({ type: 'voiceover', description: cleanText });
+    info.annotations.push({
+        type: 'voiceover-hidden',
+        description: hidden ? '1' : '0',
+    });
+}
+/**
+ * Zoom into a Playwright element during this step.
+ * Gets the element's bounding box and stores relative coordinates as annotation.
+ * The renderer applies crop+scale during this step's time window.
+ *
+ * @param locator Playwright Locator to zoom into
+ * @param level Zoom level (1.0 = no zoom, 1.5 = 1.5x closer)
+ */
+export async function zoom(locator, level = 1.5) {
+    const page = locator.page();
+    const viewport = page.viewportSize();
+    if (!viewport)
+        return;
+    const box = await locator.boundingBox();
+    if (!box)
+        return;
+    const x = (box.x + box.width / 2) / viewport.width;
+    const y = (box.y + box.height / 2) / viewport.height;
+    _getTestInfo().annotations.push({
+        type: 'zoom',
+        description: JSON.stringify({ x, y, level }),
+    });
+}
+/**
+ * Ensure a demo step takes at least `ms` milliseconds.
+ * Call at the END of a step to pad with a visual pause
+ * so the video has enough time for voiceover narration.
+ */
+export async function pace(page, ms) {
+    await page.waitForTimeout(ms);
+}
+//# sourceMappingURL=helpers.js.map

package/dist/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,SAAS,WAAW;IAClB,gFAAgF;IAChF,sEAAsE;IACtE,MAAM,IAAI,KAAK,CACb,kEAAkE,CACnE,CAAA;AACH,CAAC;AAED,IAAI,YAAY,GAAmB,WAAW,CAAA;AAE9C;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,YAAsC;IAChE,YAAY,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,CAAA;AAC1C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,OAAO,CACrB,IAAwB,EACxB,IAA2B;IAE3B,MAAM,MAAM,GAAG,IAAI,EAAE,MAAM,IAAI,IAAI,EAAE,QAAQ,CAAC,SAAS,CAAC,IAAI,KAAK,CAAA;IACjE,MAAM,SAAS,GAAG,IAAI,EAAE,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,CAAA;IAE/D,MAAM,IAAI,GAAG,YAAY,EAAE,CAAA;IAC3B,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC,CAAA;IACpE,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;QACpB,IAAI,EAAE,kBAAkB;QACxB,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG;KAChC,CAAC,CAAA;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,IAAI,CACxB,OAAgB,EAChB,QAAgB,GAAG;IAEnB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,CAAA;IAC3B,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,EAAE,CAAA;IACpC,IAAI,CAAC,QAAQ;QAAE,OAAM;IAErB,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,WAAW,EAAE,CAAA;IACvC,IAAI,CAAC,GAAG;QAAE,OAAM;IAEhB,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAA;IAClD,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAA;IAEpD,YAAY,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC;QAC9B,IAAI,EAAE,MAAM;QACZ,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC;KAC7C,CAAC,CAAA;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,IAAU,EAAE,EAAU;IAC/C,MAAM,IAAI,CAAC,cAAc,CAAC,EAAE,CAAC,CAAA;AAC/B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { Pipeline as Recast } from './pipeline/pipeline';
+export { setupRecast, narrate, zoom, pace } from './helpers';
+export { OpenAIProvider } from './voiceover/providers/openai';
+export { ElevenLabsProvider } from './voiceover/providers/elevenlabs';
+export type { ParsedTrace, FilteredTrace, TraceAction, TraceAnnotation, KnownAnnotationType, TraceResource, TraceEvent, ScreencastFrame, CursorPosition, FrameReader, MonotonicMs, } from './types/trace';
+export type { SpeedConfig, SpeedSegment, SpeedRule, SpeedRuleContext, ActivityType, TimeRemapFn, SpeedMappedTrace, } from './types/speed';
+export type { SubtitleEntry, SubtitleFormat, SubtitleOptions, SubtitledTrace, } from './types/subtitle';
+export type { TtsProvider, TtsOptions, AudioSegment, VoiceoverEntry, VoiceoveredTrace, } from './types/voiceover';
+export type { RenderConfig, SubtitleStyle, ZoomKeyframe } from './types/render';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,IAAI,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAGxD,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAG5D,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAA;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAA;AAGrE,YAAY,EACV,WAAW,EACX,aAAa,EACb,WAAW,EACX,eAAe,EACf,mBAAmB,EACnB,aAAa,EACb,UAAU,EACV,eAAe,EACf,cAAc,EACd,WAAW,EACX,WAAW,GACZ,MAAM,eAAe,CAAA;AAEtB,YAAY,EACV,WAAW,EACX,YAAY,EACZ,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,gBAAgB,GACjB,MAAM,eAAe,CAAA;AAEtB,YAAY,EACV,aAAa,EACb,cAAc,EACd,eAAe,EACf,cAAc,GACf,MAAM,kBAAkB,CAAA;AAEzB,YAAY,EACV,WAAW,EACX,UAAU,EACV,YAAY,EACZ,cAAc,EACd,gBAAgB,GACjB,MAAM,mBAAmB,CAAA;AAE1B,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/index.js

@@ -0,0 +1,8 @@
+// Public API
+export { Pipeline as Recast } from './pipeline/pipeline';
+// Step helpers (narrate, zoom, pace)
+export { setupRecast, narrate, zoom, pace } from './helpers';
+// Providers
+export { OpenAIProvider } from './voiceover/providers/openai';
+export { ElevenLabsProvider } from './voiceover/providers/elevenlabs';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,aAAa;AACb,OAAO,EAAE,QAAQ,IAAI,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAExD,qCAAqC;AACrC,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAE5D,YAAY;AACZ,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAA;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAA"}