@t3lnet/sceneforge 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,706 @@
+import { z } from 'zod';
+import { Page } from '@playwright/test';
+
+/**
+ * Core type definitions for demo YAML format.
+ * These types define the schema used by demo definition YAML files
+ * and are shared between all tools (CLI, extension, etc).
+ */
+/**
+ * Complete demo definition matching the YAML schema.
+ */
+interface DemoDefinition {
+    version: number;
+    name: string;
+    title: string;
+    description?: string;
+    steps: DemoStep[];
+    /** Media configuration for intro/outro and background music */
+    media?: MediaConfig;
+}
+/**
+ * A logical step in the demo with a script and multiple actions.
+ */
+interface DemoStep {
+    id: string;
+    script: string;
+    actions: DemoAction[];
+}
+/**
+ * A single action within a step.
+ */
+interface DemoAction {
+    action: ActionType;
+    path?: string;
+    target?: StepTarget;
+    text?: string;
+    file?: string;
+    duration?: number;
+    highlight?: boolean;
+    waitFor?: WaitCondition;
+    drag?: DragConfig;
+}
+/**
+ * Supported action types.
+ */
+type ActionType = "navigate" | "click" | "type" | "upload" | "wait" | "hover" | "scroll" | "scrollTo" | "drag";
+/**
+ * Target element specification.
+ */
+interface StepTarget {
+    type: "button" | "link" | "input" | "text" | "selector";
+    text?: string;
+    selector?: string;
+    name?: string;
+}
+/**
+ * Wait condition configuration.
+ */
+interface WaitCondition {
+    type: "text" | "selector" | "navigation" | "idle" | "selectorHidden" | "textHidden";
+    value?: string;
+    timeout?: number;
+}
+/**
+ * Drag action configuration.
+ */
+interface DragConfig {
+    deltaX: number;
+    deltaY: number;
+    steps?: number;
+}
+/**
+ * Element information captured during recording.
+ */
+interface ElementInfo {
+    tagName: string;
+    id?: string;
+    className?: string;
+    textContent?: string;
+    ariaLabel?: string;
+    placeholder?: string;
+    name?: string;
+    type?: string;
+    href?: string;
+    role?: string;
+    dataTestId?: string;
+    boundingRect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/**
+ * A recorded user interaction (used during recording).
+ */
+interface RecordedInteraction {
+    type: "click" | "input" | "navigation" | "scroll" | "drag";
+    timestamp: number;
+    selector: string;
+    selectorCandidates: SelectorCandidate[];
+    elementInfo: ElementInfo;
+    value?: string;
+    url?: string;
+    scrollDelta?: {
+        deltaX: number;
+        deltaY: number;
+    };
+    dragDelta?: {
+        deltaX: number;
+        deltaY: number;
+        duration: number;
+    };
+}
+/**
+ * Selector generation strategy.
+ */
+type SelectorStrategy = "data-testid" | "aria-label" | "role-text" | "placeholder" | "css-class" | "xpath" | "text" | "id";
+/**
+ * A selector candidate with priority and strategy info.
+ */
+interface SelectorCandidate {
+    selector: string;
+    priority: number;
+    strategy: SelectorStrategy | string;
+    description?: string;
+}
+/**
+ * Recording privacy configuration for the extension.
+ */
+interface PrivacyConfig {
+    redactSensitiveInputs: boolean;
+    allowlist: string[];
+    denylist: string[];
+}
+/**
+ * Selector strategy configuration for the extension.
+ */
+interface SelectorConfig {
+    enabledStrategies: string[];
+}
+/**
+ * Recording state for the extension.
+ */
+interface RecordingState {
+    isRecording: boolean;
+    isPicking: boolean;
+    isPaused: boolean;
+    privacyConfig: PrivacyConfig;
+    selectorConfig: SelectorConfig;
+    lastError?: {
+        message: string;
+        time: string;
+    };
+    currentDemo: DemoDefinition | null;
+    currentStepIndex: number;
+}
+/**
+ * Result of element picker.
+ */
+interface PickerResult {
+    selector: string;
+    selectorCandidates: SelectorCandidate[];
+    elementInfo: ElementInfo;
+}
+/**
+ * Result of testing a selector.
+ */
+interface TestSelectorResponse {
+    found: boolean;
+    count: number;
+    elementInfo?: {
+        tagName: string;
+        textContent?: string;
+    };
+}
+/**
+ * Intro/outro video segment configuration.
+ */
+interface VideoSegment {
+    /** Path to the video file (relative to YAML or absolute) */
+    file: string;
+    /** Optional duration in seconds (uses full length if omitted) */
+    duration?: number;
+    /** Whether to fade in/out the segment */
+    fade?: boolean;
+    /** Fade duration in seconds (default: 0.5) */
+    fadeDuration?: number;
+}
+/**
+ * Background music configuration.
+ */
+interface BackgroundMusic {
+    /** Path to the audio file (relative to YAML or absolute) */
+    file: string;
+    /** Volume level 0.0-1.0 (default: 0.15 for background) */
+    volume?: number;
+    /** When to start the music */
+    startAt?: MusicStartPoint;
+    /** When to stop the music */
+    endAt?: MusicEndPoint;
+    /** Whether to loop the audio if it's shorter than the video */
+    loop?: boolean;
+    /** Fade in duration in seconds */
+    fadeIn?: number;
+    /** Fade out duration in seconds */
+    fadeOut?: number;
+}
+/**
+ * Music start point configuration.
+ */
+type MusicStartPoint = {
+    type: "beginning";
+} | {
+    type: "afterIntro";
+} | {
+    type: "step";
+    stepId: string;
+} | {
+    type: "time";
+    seconds: number;
+};
+/**
+ * Music end point configuration.
+ */
+type MusicEndPoint = {
+    type: "end";
+} | {
+    type: "beforeOutro";
+} | {
+    type: "step";
+    stepId: string;
+} | {
+    type: "time";
+    seconds: number;
+};
+/**
+ * Media configuration for final video production.
+ */
+interface MediaConfig {
+    /** Intro video segment to prepend */
+    intro?: VideoSegment;
+    /** Outro video segment to append */
+    outro?: VideoSegment;
+    /** Background music configuration */
+    backgroundMusic?: BackgroundMusic;
+}
+
+/**
+ * YAML parsing and serialization for demo definitions.
+ * Shared between CLI and extension.
+ */
+
+/**
+ * Parses a YAML string into a DemoDefinition.
+ */
+declare function parseFromYAML(yamlString: string, options?: {
+    resolveSecrets?: (key: string) => string | undefined;
+}): DemoDefinition;
+/**
+ * Serializes a DemoDefinition to a YAML string.
+ */
+declare function serializeToYAML(demo: DemoDefinition): string;
+/**
+ * Validates a demo definition, throwing on errors.
+ */
+declare function validateDemoDefinition(definition: DemoDefinition): void;
+/**
+ * Creates a default empty demo definition.
+ */
+declare function createEmptyDemo(): DemoDefinition;
+/**
+ * Creates a default empty step.
+ */
+declare function createEmptyStep(id?: string): DemoStep;
+
+declare const DEMO_SCHEMA_VERSION = 1;
+type DemoDefinitionInput = Omit<DemoDefinition, "version"> & {
+    version?: number;
+};
+declare const demoDefinitionSchema: z.ZodType<DemoDefinition, z.ZodTypeDef, DemoDefinitionInput>;
+declare function formatValidationError(error: unknown): string;
+declare function parseDemoDefinition(input: unknown): DemoDefinition;
+declare function safeParseDemoDefinition(input: unknown): z.SafeParseReturnType<DemoDefinitionInput, DemoDefinition>;
+
+/**
+ * Target resolution utilities.
+ * Converts StepTarget configurations to CSS/Playwright selectors.
+ */
+
+/**
+ * Resolves a target configuration to a selector string.
+ * Works with both Playwright locators and standard CSS selectors.
+ */
+declare function resolveTarget(target: StepTarget): string;
+/**
+ * Replaces template variables in paths.
+ * Supports: {baseURL}.
+ */
+declare function resolvePath(pathTemplate: string, variables: Record<string, string | undefined>): string;
+
+/**
+ * Helper functions for creating common actions.
+ */
+
+/**
+ * Creates a click action.
+ */
+declare function createClickAction(selector: string, highlight?: boolean): DemoAction;
+/**
+ * Creates a type/input action.
+ */
+declare function createTypeAction(selector: string, text: string): DemoAction;
+/**
+ * Creates a navigate action.
+ */
+declare function createNavigateAction(path: string): DemoAction;
+/**
+ * Creates a wait action with a fixed duration.
+ */
+declare function createWaitAction(duration: number): DemoAction;
+/**
+ * Creates a wait action with a condition.
+ */
+declare function createWaitForAction(type: WaitCondition["type"], value?: string, timeout?: number): DemoAction;
+/**
+ * Creates an upload action.
+ * Note: selector is optional - defaults to first file input on page.
+ */
+declare function createUploadAction(file: string, selector?: string): DemoAction;
+/**
+ * Creates a hover action.
+ */
+declare function createHoverAction(selector: string): DemoAction;
+/**
+ * Creates a scroll action.
+ */
+declare function createScrollAction(duration?: number): DemoAction;
+/**
+ * Creates a scroll-to action.
+ */
+declare function createScrollToAction(selector: string): DemoAction;
+/**
+ * Creates a drag action.
+ */
+declare function createDragAction(selector: string, deltaX: number, deltaY: number, steps?: number): DemoAction;
+
+/**
+ * Demo runner for Playwright.
+ * Executes demo definitions using Playwright for video recording.
+ */
+
+/**
+ * Context passed to the demo runner.
+ */
+interface DemoContext {
+    page: Page;
+    baseURL: string;
+    outputDir: string;
+    videoPath?: string;
+    videoRecordingStartTime?: number;
+    assetBaseDir?: string;
+}
+/**
+ * Result of running a demo.
+ */
+interface DemoResult {
+    success: boolean;
+    demoName: string;
+    videoPath?: string;
+    scriptPath?: string;
+    error?: Error;
+    duration: number;
+}
+interface RunDemoOptions {
+    generateScripts?: boolean;
+    scriptOutputDir?: string;
+}
+/**
+ * Step timing info for video splitting.
+ */
+interface StepTiming {
+    id: string;
+    script: string;
+    startTime: number;
+    endTime?: number;
+}
+/**
+ * Loads and parses a YAML demo definition file.
+ */
+declare function loadDemoDefinition(filePath: string, options?: {
+    resolveSecrets?: (key: string) => string | undefined;
+}): Promise<DemoDefinition>;
+/**
+ * Runs a complete demo from a definition.
+ */
+declare function runDemo(definition: DemoDefinition, context: DemoContext, options?: RunDemoOptions): Promise<DemoResult>;
+/**
+ * Runs a demo from a YAML file path.
+ */
+declare function runDemoFromFile(definitionPath: string, context: DemoContext, options?: RunDemoOptions): Promise<DemoResult>;
+/**
+ * Discovers all demo definition files in a directory.
+ */
+declare function discoverDemos(demoDir: string): Promise<string[]>;
+
+/**
+ * Injects the demo cursor overlay into the page.
+ * Call this once after page load.
+ */
+declare function injectCursorOverlay(page: Page): Promise<void>;
+/**
+ * Smoothly moves the demo cursor to specified coordinates using actual mouse movement.
+ * This creates a visible animation in the recorded video.
+ */
+declare function moveCursorTo(page: Page, x: number, y: number, options?: {
+    steps?: number;
+    trailEnabled?: boolean;
+}): Promise<void>;
+/**
+ * Triggers the click ripple animation at the current cursor position.
+ */
+declare function triggerClickRipple(page: Page): Promise<void>;
+/**
+ * Highlights an element with a pulsing ring effect.
+ */
+declare function highlightElement(page: Page, selector: string): Promise<void>;
+/**
+ * Removes the demo cursor overlay.
+ */
+declare function removeCursorOverlay(page: Page): Promise<void>;
+/**
+ * Performs a demo click action with visible cursor movement:
+ * 1. Moves cursor smoothly to element center
+ * 2. Optionally highlights element
+ * 3. Triggers click ripple
+ * 4. Performs actual click
+ */
+declare function demoClick(page: Page, selector: string, options?: {
+    highlight?: boolean;
+    delayAfter?: number;
+    delayBefore?: number;
+    timeoutMs?: number;
+}): Promise<void>;
+/**
+ * Performs a demo hover action with visible cursor movement.
+ */
+declare function demoHover(page: Page, selector: string, options?: {
+    highlight?: boolean;
+    timeoutMs?: number;
+}): Promise<void>;
+/**
+ * Types text with visible cursor at the input location.
+ */
+declare function demoType(page: Page, selector: string, text: string, options?: {
+    highlight?: boolean;
+    delayBetweenChars?: number;
+}): Promise<void>;
+
+interface RetryOptions {
+    retries?: number;
+    minDelayMs?: number;
+    maxDelayMs?: number;
+}
+/**
+ * Configuration for voice synthesis
+ */
+interface VoiceSynthesisConfig {
+    apiKey: string;
+    voiceId: string;
+    modelId?: string;
+    outputFormat?: "mp3_44100_128" | "mp3_44100_192" | "pcm_16000" | "pcm_22050" | "pcm_24000";
+}
+/**
+ * Script segment from the generated JSON
+ */
+interface ScriptSegment$1 {
+    stepId: string;
+    text: string;
+    startTimeMs: number;
+    endTimeMs: number;
+    estimatedDurationMs: number;
+    pauseBeforeMs?: number;
+    pauseAfterMs?: number;
+}
+/**
+ * Generated script JSON structure
+ */
+interface GeneratedScript {
+    demoName: string;
+    title: string;
+    generatedAt: string;
+    totalDurationMs: number;
+    segments: ScriptSegment$1[];
+}
+/**
+ * Result of synthesizing a segment
+ */
+interface SynthesizedSegment {
+    stepId: string;
+    audioPath: string;
+    durationMs: number;
+    text: string;
+}
+/**
+ * Result of full voice synthesis
+ */
+interface VoiceSynthesisResult {
+    demoName: string;
+    segments: SynthesizedSegment[];
+    combinedAudioPath?: string;
+    soundEffectsPath?: string;
+    backgroundMusicPath?: string;
+}
+/**
+ * ElevenLabs voice synthesizer for demo narration
+ */
+declare class VoiceSynthesizer {
+    private client;
+    private config;
+    constructor(config: VoiceSynthesisConfig);
+    /**
+     * List available voices (useful for finding voice IDs)
+     */
+    listVoices(): Promise<Array<{
+        voiceId: string;
+        name: string;
+        category: string;
+    }>>;
+    /**
+     * Synthesize a single text segment to audio
+     */
+    synthesizeSegment(text: string, outputPath: string, options?: {
+        stability?: number;
+        similarityBoost?: number;
+        style?: number;
+        useSpeakerBoost?: boolean;
+    }): Promise<{
+        durationMs: number;
+    }>;
+    /**
+     * Generate a sound effect from text description
+     */
+    generateSoundEffect(description: string, outputPath: string, options?: {
+        durationSeconds?: number;
+        promptInfluence?: number;
+        retry?: RetryOptions;
+    }): Promise<void>;
+    /**
+     * Synthesize all segments from a script JSON file
+     */
+    synthesizeScript(scriptPath: string, outputDir: string, options?: {
+        voiceSettings?: {
+            stability?: number;
+            similarityBoost?: number;
+            style?: number;
+        };
+        generateClickSounds?: boolean;
+        onProgress?: (current: number, total: number, stepId: string) => void;
+        maxConcurrency?: number;
+        retry?: RetryOptions;
+    }): Promise<VoiceSynthesisResult>;
+    /**
+     * Generate a UI click sound effect
+     */
+    generateClickSound(outputPath: string): Promise<void>;
+    /**
+     * Generate ambient background music
+     */
+    generateBackgroundMusic(outputPath: string, options?: {
+        style?: "corporate" | "tech" | "calm" | "upbeat";
+        durationSeconds?: number;
+    }): Promise<void>;
+}
+/**
+ * Create a timing manifest for video editing
+ * Maps audio files to their intended start times in the video
+ */
+interface AudioTimingManifest {
+    demoName: string;
+    segments: Array<{
+        stepId: string;
+        audioFile: string;
+        videoStartTimeMs: number;
+        audioDurationMs: number;
+        text: string;
+    }>;
+    soundEffects?: {
+        clickSound?: string;
+    };
+    backgroundMusic?: string;
+}
+/**
+ * Generate a timing manifest from synthesized results and original script
+ */
+declare function generateTimingManifest(scriptPath: string, synthesisResult: VoiceSynthesisResult, outputPath: string): Promise<AudioTimingManifest>;
+/**
+ * Default export for easy instantiation
+ */
+declare function createVoiceSynthesizer(config: VoiceSynthesisConfig): VoiceSynthesizer;
+
+/**
+ * A single segment of narration with timing information.
+ */
+interface ScriptSegment {
+    stepId: string;
+    text: string;
+    startTimeMs: number;
+    endTimeMs: number;
+    estimatedDurationMs: number;
+    pauseBeforeMs?: number;
+    pauseAfterMs?: number;
+}
+/**
+ * Video step boundary for splitting videos per step.
+ */
+interface StepBoundary {
+    stepId: string;
+    stepIndex: number;
+    videoStartMs: number;
+    videoEndMs: number;
+}
+/**
+ * Complete script output with metadata.
+ */
+interface ScriptOutput {
+    demoName: string;
+    title: string;
+    generatedAt: string;
+    totalDurationMs: number;
+    segments: ScriptSegment[];
+    stepBoundaries: StepBoundary[];
+    videoMetadata?: {
+        videoPath: string;
+        durationMs: number;
+        alignmentOffsetMs: number;
+        recordingStartTimeMs?: number;
+        alignedAt?: string;
+    };
+}
+/**
+ * Tracks narration segments during demo execution.
+ */
+declare class ScriptGenerator {
+    private segments;
+    private stepBoundaries;
+    private currentStepId;
+    private currentStepStartMs;
+    private demoName;
+    private title;
+    private startTime;
+    constructor(demoName: string, title: string, startTimeMs?: number);
+    /**
+     * Marks the start of a step (for video splitting).
+     */
+    startStep(stepId: string): void;
+    /**
+     * Marks the end of all steps (call at demo completion).
+     */
+    finishAllSteps(): void;
+    /**
+     * Estimates reading duration for text.
+     * Based on ~150 words per minute average speaking rate.
+     */
+    private estimateReadingDuration;
+    /**
+     * Adds a narration segment with automatic timing.
+     */
+    addSegment(stepId: string, text: string, options?: {
+        timing?: "on_start" | "on_complete";
+        pauseBeforeMs?: number;
+        pauseAfterMs?: number;
+    }): void;
+    /**
+     * Updates the end time of the last segment.
+     * Call this when a step completes to capture actual duration.
+     */
+    completeLastSegment(): void;
+    /**
+     * Generates the complete script output.
+     */
+    getOutput(): ScriptOutput;
+    /**
+     * Exports script as JSON.
+     */
+    exportJSON(outputPath: string): Promise<void>;
+    /**
+     * Exports script as SRT subtitle format.
+     */
+    exportSRT(outputPath: string): Promise<void>;
+    /**
+     * Exports script in a format suitable for AI voice generation services.
+     * Includes SSML-like pause markers.
+     */
+    exportAIVoiceScript(outputPath: string): Promise<void>;
+    /**
+     * Exports script as human-readable markdown for voice actors.
+     */
+    exportMarkdown(outputPath: string): Promise<void>;
+}
+/**
+ * Creates a new ScriptGenerator instance.
+ */
+declare function createScriptGenerator(demoName: string, title: string, startTimeMs?: number): ScriptGenerator;
+
+export { type ActionType, type AudioTimingManifest, DEMO_SCHEMA_VERSION, type DemoAction, type DemoContext, type DemoDefinition, type DemoResult, type DemoStep, type DragConfig, type ElementInfo, type GeneratedScript, type PickerResult, type PrivacyConfig, type RecordedInteraction, type RecordingState, type RunDemoOptions, ScriptGenerator, type ScriptOutput, type ScriptSegment, type SelectorCandidate, type SelectorConfig, type SelectorStrategy, type StepBoundary, type StepTarget, type StepTiming, type SynthesizedSegment, type TestSelectorResponse, type ScriptSegment$1 as VoiceScriptSegment, type VoiceSynthesisConfig, type VoiceSynthesisResult, VoiceSynthesizer, type WaitCondition, createClickAction, createDragAction, createEmptyDemo, createEmptyStep, createHoverAction, createNavigateAction, createScriptGenerator, createScrollAction, createScrollToAction, createTypeAction, createUploadAction, createVoiceSynthesizer, createWaitAction, createWaitForAction, demoClick, demoDefinitionSchema, demoHover, demoType, discoverDemos, formatValidationError, generateTimingManifest, highlightElement, injectCursorOverlay, loadDemoDefinition, moveCursorTo, parseDemoDefinition, parseFromYAML, removeCursorOverlay, resolvePath, resolveTarget, runDemo, runDemoFromFile, safeParseDemoDefinition, serializeToYAML, triggerClickRipple, validateDemoDefinition };