playwright-director 0.2.0

package/dist/merge.js

@@ -0,0 +1,65 @@
+import { existsSync } from 'fs';
+import { join } from 'path';
+const DEFAULT_OPTIONS = {
+    audioDir: 'static/audio/tutorial-voice',
+    musicFile: 'static/audio/tutorial-background.mp3',
+    musicVolume: 0.15,
+    voiceVolume: 2.5
+};
+/**
+ * Build the ffmpeg command to merge video with audio
+ */
+export function buildMergeCommand(timeline, videoPath, outputPath, options = {}) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const fileExists = opts.checkFileExists ?? existsSync;
+    const videoDuration = (timeline.totalDurationMs / 1000).toFixed(3);
+    const inputs = [videoPath];
+    const filterParts = [];
+    const audioLabels = [];
+    let audioIdx = 1;
+    // Add background music
+    if (opts.musicFile && fileExists(opts.musicFile)) {
+        inputs.push(opts.musicFile);
+        filterParts.push(`[1:a]atrim=0:${videoDuration},asetpts=PTS-STARTPTS,volume=${opts.musicVolume}[bg]`);
+        audioLabels.push('[bg]');
+        audioIdx = 2;
+    }
+    // Add voice clips — unvoiced steps (empty audioFile) carry no narration
+    for (const step of timeline.steps) {
+        if (!step.audioFile)
+            continue;
+        const audioPath = join(opts.audioDir, step.audioFile);
+        if (!fileExists(audioPath)) {
+            console.warn(`Missing audio: ${step.audioFile}`);
+            continue;
+        }
+        inputs.push(audioPath);
+        filterParts.push(`[${audioIdx}:a]volume=${opts.voiceVolume},adelay=${step.startMs}|${step.startMs}[v${audioIdx}]`);
+        audioLabels.push(`[v${audioIdx}]`);
+        audioIdx++;
+    }
+    // Build mix filter
+    const totalStreams = audioLabels.length;
+    let filter;
+    if (totalStreams === 0) {
+        filter = 'anullsrc=r=48000:cl=stereo[aout]';
+    }
+    else if (totalStreams === 1) {
+        filter = `${filterParts.join(';')};${audioLabels[0]}anull[aout]`;
+    }
+    else {
+        filter = `${filterParts.join(';')};${audioLabels.join('')}amix=inputs=${totalStreams}:duration=longest:dropout_transition=0:normalize=0[aout]`;
+    }
+    // Build input args
+    const inputArgs = inputs.map((input, i) => {
+        if (i === 1 && input === opts.musicFile) {
+            return `-stream_loop -1 -i "${input}"`;
+        }
+        return `-i "${input}"`;
+    }).join(' ');
+    // Trim dead time from video start (preload period)
+    const trimSs = timeline.videoTrimMs ? `-ss ${(timeline.videoTrimMs / 1000).toFixed(3)}` : '';
+    const command = `ffmpeg -y ${trimSs} ${inputArgs} -filter_complex "${filter}" -map 0:v -map "[aout]" -c:v libvpx-vp9 -b:v 330k -crf 40 -row-mt 1 -cpu-used 4 -c:a libopus -b:a 64k -t ${videoDuration} "${outputPath}"`;
+    return { command, inputs, filter };
+}
+//# sourceMappingURL=merge.js.map

package/dist/merge.js.map

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

package/dist/music.d.ts

@@ -0,0 +1,29 @@
+import type { Page } from '@playwright/test';
+export interface MusicOptions {
+    backgroundMusic: string;
+    musicVolume: number;
+}
+/**
+ * In-browser music for live viewing during test execution.
+ * Note: Music is NOT captured via MediaRecorder - it's added in post-processing
+ * by the merge script (scripts/merge-tutorial-audio.sh) for continuous playback.
+ *
+ * All playback methods are no-ops when TUTORIAL_MODE is not enabled,
+ * ensuring no audio plays during regular test runs.
+ */
+export declare class TutorialMusic {
+    private page;
+    private options;
+    private initialized;
+    constructor(page: Page, options: MusicOptions);
+    switchPage(page: Page): void;
+    get isInitialized(): boolean;
+    /**
+     * Ensure music is still playing (restart after page navigation)
+     */
+    ensurePlaying(): Promise<void>;
+    start(): Promise<void>;
+    stop(fadeOut?: boolean): Promise<void>;
+    setVolume(volume: number): Promise<void>;
+}
+//# sourceMappingURL=music.d.ts.map

package/dist/music.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"music.d.ts","sourceRoot":"","sources":["../src/music.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAI7C,MAAM,WAAW,YAAY;IAC5B,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,qBAAa,aAAa;IACzB,OAAO,CAAC,IAAI,CAAO;IACnB,OAAO,CAAC,OAAO,CAAe;IAC9B,OAAO,CAAC,WAAW,CAAS;gBAEhB,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY;IAK7C,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAI5B,IAAI,aAAa,IAAI,OAAO,CAE3B;IAED;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB9B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAkCtB,IAAI,CAAC,OAAO,UAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BnC,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAW9C"}

package/dist/music.js

@@ -0,0 +1,107 @@
+const TUTORIAL_MODE = process.env.TUTORIAL_MODE === 'true';
+/**
+ * In-browser music for live viewing during test execution.
+ * Note: Music is NOT captured via MediaRecorder - it's added in post-processing
+ * by the merge script (scripts/merge-tutorial-audio.sh) for continuous playback.
+ *
+ * All playback methods are no-ops when TUTORIAL_MODE is not enabled,
+ * ensuring no audio plays during regular test runs.
+ */
+export class TutorialMusic {
+    page;
+    options;
+    initialized = false;
+    constructor(page, options) {
+        this.page = page;
+        this.options = options;
+    }
+    switchPage(page) {
+        this.page = page;
+    }
+    get isInitialized() {
+        return this.initialized;
+    }
+    /**
+     * Ensure music is still playing (restart after page navigation)
+     */
+    async ensurePlaying() {
+        if (!TUTORIAL_MODE)
+            return;
+        if (!this.initialized || !this.options.backgroundMusic)
+            return;
+        const isPlaying = await this.page.evaluate(() => {
+            const audio = document.getElementById('tutorial-music');
+            return audio && !audio.paused;
+        });
+        if (!isPlaying) {
+            console.log('[Music] Lost after navigation, restarting...');
+            this.initialized = false;
+            await this.start();
+        }
+    }
+    async start() {
+        if (!TUTORIAL_MODE)
+            return;
+        if (!this.options.backgroundMusic || this.initialized)
+            return;
+        const result = await this.page.evaluate(({ musicUrl, volume }) => {
+            const existing = document.getElementById('tutorial-music');
+            if (existing)
+                existing.remove();
+            const audio = document.createElement('audio');
+            audio.id = 'tutorial-music';
+            audio.src = musicUrl;
+            audio.loop = true;
+            audio.volume = volume;
+            audio.style.display = 'none';
+            document.body.appendChild(audio);
+            return audio
+                .play()
+                .then(() => ({ success: true, error: null }))
+                .catch((e) => ({ success: false, error: e.message }));
+        }, { musicUrl: this.options.backgroundMusic, volume: this.options.musicVolume });
+        if (result?.success) {
+            console.log('[Music] Background music playing (live only, will be added in post-processing)');
+        }
+        else if (result?.error) {
+            console.warn(`[Music] Autoplay blocked: ${result.error}`);
+        }
+        this.initialized = true;
+    }
+    async stop(fadeOut = true) {
+        if (!this.initialized)
+            return;
+        await this.page.evaluate(({ fadeOut }) => {
+            const audio = document.getElementById('tutorial-music');
+            if (!audio)
+                return;
+            if (fadeOut) {
+                const fadeInterval = setInterval(() => {
+                    if (audio.volume > 0.01) {
+                        audio.volume = Math.max(0, audio.volume - 0.01);
+                    }
+                    else {
+                        clearInterval(fadeInterval);
+                        audio.pause();
+                        audio.remove();
+                    }
+                }, 20);
+            }
+            else {
+                audio.pause();
+                audio.remove();
+            }
+        }, { fadeOut });
+        this.initialized = false;
+    }
+    async setVolume(volume) {
+        if (!this.initialized)
+            return;
+        await this.page.evaluate(({ volume }) => {
+            const audio = document.getElementById('tutorial-music');
+            if (audio)
+                audio.volume = Math.max(0, Math.min(1, volume));
+        }, { volume });
+    }
+}
+//# sourceMappingURL=music.js.map

package/dist/music.js.map

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

package/dist/overlay-html.d.ts

@@ -0,0 +1,44 @@
+import type { ContextStyle, OverlayPosition, SceneOptions } from './types.js';
+/**
+ * The multi-scene stage: a browser-like tab bar over a row of iframes.
+ *
+ * Every scene stays mounted for the whole tutorial — hidden, never unloaded —
+ * so a profile logged in behind one tab is still logged in when we come back
+ * to it. Tabs are always all visible: that is how a viewer knows who else is
+ * in the story and who is speaking now.
+ */
+export declare function renderStage(scenes: Record<string, SceneOptions>, active: string[], pinnedSplit?: boolean): string;
+export declare const CURSOR_SVG = "\n<svg viewBox=\"0 0 24 24\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\">\n\t<path d=\"M4 4L10.5 20.5L13 13L20.5 10.5L4 4Z\" fill=\"white\" stroke=\"var(--tutorial-cursor-stroke, #1e293b)\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/>\n</svg>\n";
+export interface StepOverlayParams {
+    tutorialTitle: string;
+    step: number;
+    title: string;
+    description?: string;
+    isRtl?: boolean;
+    progressPercent?: number;
+    position?: OverlayPosition;
+}
+export declare function renderStepOverlay(params: StepOverlayParams): string;
+export interface ContextOverlayParams {
+    tutorialTitle: string;
+    contextTitle: string;
+    text?: string;
+    style: ContextStyle;
+    isRtl?: boolean;
+}
+export declare function renderContextOverlay(params: ContextOverlayParams): string;
+export interface CompleteOverlayParams {
+    title: string;
+    message: string;
+}
+export declare function renderCompleteOverlay(params: CompleteOverlayParams): string;
+export interface EmailPreviewParams {
+    subject: string;
+    from?: string;
+    to?: string;
+    body: string;
+    highlightCode?: string;
+    isRtl?: boolean;
+}
+export declare function renderEmailPreview(params: EmailPreviewParams): string;
+//# sourceMappingURL=overlay-html.d.ts.map

package/dist/overlay-html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay-html.d.ts","sourceRoot":"","sources":["../src/overlay-html.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAK9E;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,EACpC,MAAM,EAAE,MAAM,EAAE,EAChB,WAAW,UAAQ,GACjB,MAAM,CAmCR;AAED,eAAO,MAAM,UAAU,2RAItB,CAAC;AAgBF,MAAM,WAAW,iBAAiB;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC3B;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAenE;AAED,MAAM,WAAW,oBAAoB;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,YAAY,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAazE;AAED,MAAM,WAAW,qBAAqB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,CAW3E;AAED,MAAM,WAAW,kBAAkB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CA+DrE"}

package/dist/overlay-html.js

@@ -0,0 +1,150 @@
+const escapeHtml = (s) => s.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
+/**
+ * The multi-scene stage: a browser-like tab bar over a row of iframes.
+ *
+ * Every scene stays mounted for the whole tutorial — hidden, never unloaded —
+ * so a profile logged in behind one tab is still logged in when we come back
+ * to it. Tabs are always all visible: that is how a viewer knows who else is
+ * in the story and who is speaking now.
+ */
+export function renderStage(scenes, active, pinnedSplit = false) {
+    const isActive = (name) => active.includes(name);
+    const tabs = Object.entries(scenes)
+        .map(([name, scene]) => `<div class="tutorial-tab" data-tutorial-tab="${name}" data-active="${isActive(name)}">
+			<span class="tutorial-tab-dot"></span>${escapeHtml(scene.label)}
+		</div>`)
+        .join('\n\t\t');
+    const panes = Object.entries(scenes)
+        .map(([name, scene]) => `<div class="tutorial-scene" data-tutorial-scene="${name}" data-active="${isActive(name)}">
+			<div class="tutorial-scene-label" data-tutorial-scene-label="${name}">
+				<span class="tutorial-tab-dot"></span>${escapeHtml(scene.label)}
+			</div>
+			<iframe data-tutorial-frame="${name}" src="about:blank"></iframe>
+		</div>`)
+        .join('\n\t\t');
+    const isSplit = pinnedSplit || active.length > 1;
+    const layoutAttr = pinnedSplit ? ` data-layout="split"` : '';
+    return `<div class="tutorial-stage" id="tutorial-stage" data-split="${isSplit}"${layoutAttr}>
+	<div class="tutorial-tabbar">
+		${tabs}
+	</div>
+	<div class="tutorial-scenes">
+		${panes}
+	</div>
+</div>`;
+}
+export const CURSOR_SVG = `
+<svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+	<path d="M4 4L10.5 20.5L13 13L20.5 10.5L4 4Z" fill="white" stroke="var(--tutorial-cursor-stroke, #1e293b)" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>
+`;
+const CONTEXT_ICONS = {
+    goal: '\uD83C\uDFAF',
+    clarification: '\uD83D\uDCA1',
+    attention: '\u26A0\uFE0F'
+};
+function positionClass(position, isRtl) {
+    const effective = isRtl
+        ? { TL: 'TR', TR: 'TL', BL: 'BR', BR: 'BL' }[position]
+        : position;
+    if (effective === 'TL')
+        return '';
+    return `tutorial-overlay-${effective.toLowerCase()}`;
+}
+export function renderStepOverlay(params) {
+    const { tutorialTitle, step, title, description, isRtl, progressPercent = 0, position = 'TR' } = params;
+    const rtlClass = isRtl ? 'tutorial-overlay-rtl' : '';
+    const posClass = positionClass(position, !!isRtl);
+    return `<div id="tutorial-overlay" class="tutorial-overlay ${rtlClass} ${posClass}">
+	<div class="tutorial-header">
+		<span class="tutorial-icon">\uD83D\uDCCC</span>
+		<h3 class="tutorial-title">${tutorialTitle}</h3>
+		<span class="tutorial-step-badge">Step ${step}</span>
+	</div>
+	<h4 class="tutorial-step-title">${title}</h4>
+	${description ? `<p class="tutorial-step-description">${description}</p>` : ''}
+	${progressPercent > 0 ? `<div class="tutorial-progress"><div class="tutorial-progress-bar" style="width: ${progressPercent}%"></div></div>` : ''}
+</div>`;
+}
+export function renderContextOverlay(params) {
+    const { tutorialTitle, contextTitle, text, style, isRtl } = params;
+    const icon = CONTEXT_ICONS[style];
+    const rtlClass = isRtl ? 'tutorial-overlay-rtl' : '';
+    return `<div id="tutorial-overlay" class="tutorial-overlay tutorial-overlay-context tutorial-context-${style} ${rtlClass}">
+	<div class="tutorial-header">
+		<span class="tutorial-icon">${icon}</span>
+		<h3 class="tutorial-title">${tutorialTitle}</h3>
+	</div>
+	<h4 class="tutorial-step-title">${contextTitle}</h4>
+	${text ? `<p class="tutorial-context-text">${text}</p>` : ''}
+</div>`;
+}
+export function renderCompleteOverlay(params) {
+    const { title, message } = params;
+    return `<div id="tutorial-overlay" class="tutorial-overlay">
+	<div class="tutorial-header">
+		<span class="tutorial-icon">\u2705</span>
+		<h3 class="tutorial-title">${title}</h3>
+	</div>
+	<h4 class="tutorial-step-title">${message}</h4>
+	<div class="tutorial-progress"><div class="tutorial-progress-bar" style="width: 100%"></div></div>
+</div>`;
+}
+export function renderEmailPreview(params) {
+    const { subject, from, to, body, highlightCode, isRtl } = params;
+    const rtlClass = isRtl ? 'tutorial-overlay-rtl' : '';
+    let displayBody = body;
+    if (highlightCode) {
+        const highlightStyle = `
+			<style>
+				.tutorial-code-highlight {
+					background: #fff3cd !important;
+					color: #856404 !important;
+					padding: 4px 12px !important;
+					border-radius: 4px !important;
+					font-weight: 700 !important;
+					font-size: 18px !important;
+					letter-spacing: 2px !important;
+					display: inline-block !important;
+					margin: 8px 0 !important;
+					border: 2px solid #ffc107 !important;
+					animation: pulse 1.5s ease-in-out infinite !important;
+				}
+				@keyframes pulse {
+					0%, 100% { box-shadow: 0 0 0 4px rgba(255, 193, 7, 0.3); }
+					50% { box-shadow: 0 0 0 8px rgba(255, 193, 7, 0.5), 0 0 20px rgba(255, 193, 7, 0.3); }
+				}
+			</style>
+		`;
+        displayBody = highlightStyle + body.replace(new RegExp(`(${highlightCode})`, 'g'), `<span class="tutorial-code-highlight">$1</span>`);
+    }
+    // Render inside an iframe via srcdoc so the email's own CSS doesn't collide
+    // with the app stylesheet (was causing missing icons / broken layout) and so
+    // images with absolute URLs load normally. `srcdoc` is same-origin, so the
+    // scroll animation in Tutorial.ts can still access the iframe body.
+    const srcdoc = `<!doctype html><html><head><meta charset="utf-8"><style>
+		html, body { margin: 0; padding: 0; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; font-size: 14px; line-height: 1.5; color: #333; background: #fff; }
+		body { padding: 16px; }
+		img { max-width: 100%; height: auto; }
+	</style></head><body>${displayBody}</body></html>`;
+    const srcdocAttr = srcdoc.replace(/"/g, '&quot;');
+    return `<div id="tutorial-email-preview" class="tutorial-email-preview ${rtlClass}">
+	<div class="tutorial-email-window">
+		<div class="tutorial-email-titlebar">
+			<span class="tutorial-email-dot red"></span>
+			<span class="tutorial-email-dot yellow"></span>
+			<span class="tutorial-email-dot green"></span>
+			<span class="tutorial-email-app">\uD83D\uDCE7 Email</span>
+		</div>
+		<div class="tutorial-email-header">
+			${from ? `<div class="tutorial-email-field"><strong>From:</strong> ${from}</div>` : ''}
+			${to ? `<div class="tutorial-email-field"><strong>To:</strong> ${to}</div>` : ''}
+			<div class="tutorial-email-field"><strong>Subject:</strong> ${subject}</div>
+		</div>
+		<div class="tutorial-email-body-container">
+			<iframe class="tutorial-email-body tutorial-email-iframe" srcdoc="${srcdocAttr}" sandbox="allow-same-origin"></iframe>
+		</div>
+	</div>
+</div>`;
+}
+//# sourceMappingURL=overlay-html.js.map

package/dist/overlay-html.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay-html.js","sourceRoot":"","sources":["../src/overlay-html.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,GAAG,CAAC,CAAS,EAAU,EAAE,CACxC,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAE,CAAC,CAAC;AAE9F;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAC1B,MAAoC,EACpC,MAAgB,EAChB,WAAW,GAAG,KAAK;IAEnB,MAAM,QAAQ,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAEzD,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;SACjC,GAAG,CACH,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CACjB,gDAAgD,IAAI,kBAAkB,QAAQ,CAAC,IAAI,CAAC;2CAC7C,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC;SACzD,CACN;SACA,IAAI,CAAC,QAAQ,CAAC,CAAC;IAEjB,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;SAClC,GAAG,CACH,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CACjB,oDAAoD,IAAI,kBAAkB,QAAQ,CAAC,IAAI,CAAC;kEAC1B,IAAI;4CAC1B,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC;;kCAEjC,IAAI;SAC7B,CACN;SACA,IAAI,CAAC,QAAQ,CAAC,CAAC;IAEjB,MAAM,OAAO,GAAG,WAAW,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;IACjD,MAAM,UAAU,GAAG,WAAW,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,EAAE,CAAC;IAE7D,OAAO,+DAA+D,OAAO,IAAI,UAAU;;IAExF,IAAI;;;IAGJ,KAAK;;OAEF,CAAC;AACR,CAAC;AAED,MAAM,CAAC,MAAM,UAAU,GAAG;;;;CAIzB,CAAC;AAEF,MAAM,aAAa,GAAiC;IACnD,IAAI,EAAE,cAAc;IACpB,aAAa,EAAE,cAAc;IAC7B,SAAS,EAAE,cAAc;CACzB,CAAC;AAEF,SAAS,aAAa,CAAC,QAAyB,EAAE,KAAc;IAC/D,MAAM,SAAS,GAAG,KAAK;QACtB,CAAC,CAAE,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAY,CAAC,QAAQ,CAAC;QACjE,CAAC,CAAC,QAAQ,CAAC;IACZ,IAAI,SAAS,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IAClC,OAAO,oBAAoB,SAAS,CAAC,WAAW,EAAE,EAAE,CAAC;AACtD,CAAC;AAYD,MAAM,UAAU,iBAAiB,CAAC,MAAyB;IAC1D,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,eAAe,GAAG,CAAC,EAAE,QAAQ,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;IACxG,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,EAAE,CAAC;IACrD,MAAM,QAAQ,GAAG,aAAa,CAAC,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;IAElD,OAAO,sDAAsD,QAAQ,IAAI,QAAQ;;;+BAGnD,aAAa;2CACD,IAAI;;mCAEZ,KAAK;GACrC,WAAW,CAAC,CAAC,CAAC,wCAAwC,WAAW,MAAM,CAAC,CAAC,CAAC,EAAE;GAC5E,eAAe,GAAG,CAAC,CAAC,CAAC,CAAC,mFAAmF,eAAe,iBAAiB,CAAC,CAAC,CAAC,EAAE;OAC1I,CAAC;AACR,CAAC;AAUD,MAAM,UAAU,oBAAoB,CAAC,MAA4B;IAChE,MAAM,EAAE,aAAa,EAAE,YAAY,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;IACnE,MAAM,IAAI,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAClC,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,EAAE,CAAC;IAErD,OAAO,gGAAgG,KAAK,IAAI,QAAQ;;gCAEzF,IAAI;+BACL,aAAa;;mCAET,YAAY;GAC5C,IAAI,CAAC,CAAC,CAAC,oCAAoC,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE;OACtD,CAAC;AACR,CAAC;AAOD,MAAM,UAAU,qBAAqB,CAAC,MAA6B;IAClE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;IAElC,OAAO;;;+BAGuB,KAAK;;mCAED,OAAO;;OAEnC,CAAC;AACR,CAAC;AAWD,MAAM,UAAU,kBAAkB,CAAC,MAA0B;IAC5D,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;IACjE,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,EAAE,CAAC;IAErD,IAAI,WAAW,GAAG,IAAI,CAAC;IACvB,IAAI,aAAa,EAAE,CAAC;QACnB,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;GAoBtB,CAAC;QACF,WAAW,GAAG,cAAc,GAAG,IAAI,CAAC,OAAO,CAC1C,IAAI,MAAM,CAAC,IAAI,aAAa,GAAG,EAAE,GAAG,CAAC,EACrC,iDAAiD,CACjD,CAAC;IACH,CAAC;IAED,4EAA4E;IAC5E,6EAA6E;IAC7E,2EAA2E;IAC3E,oEAAoE;IACpE,MAAM,MAAM,GAAG;;;;wBAIQ,WAAW,gBAAgB,CAAC;IAEnD,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAElD,OAAO,kEAAkE,QAAQ;;;;;;;;;KAS7E,IAAI,CAAC,CAAC,CAAC,4DAA4D,IAAI,QAAQ,CAAC,CAAC,CAAC,EAAE;KACpF,EAAE,CAAC,CAAC,CAAC,0DAA0D,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE;iEAClB,OAAO;;;uEAGD,UAAU;;;OAG1E,CAAC;AACR,CAAC"}

package/dist/overlay.d.ts

@@ -0,0 +1,39 @@
+import type { Page, Locator } from '@playwright/test';
+import type { ContextStyle, OverlayPosition } from './types.js';
+export interface OverlayOptions {
+    title: string;
+    lang: string;
+    highlightDuration: number;
+    position: OverlayPosition;
+}
+export declare class TutorialOverlay {
+    private page;
+    private options;
+    private currentStep;
+    private totalSteps;
+    constructor(page: Page, options: OverlayOptions);
+    switchPage(page: Page): void;
+    setTotalSteps(total: number): void;
+    setCurrentStep(step: number): void;
+    incrementStep(): number;
+    get step(): number;
+    showStep(title: string, description?: string, position?: OverlayPosition): Promise<void>;
+    showContext(contextTitle: string, text?: string, style?: ContextStyle): Promise<void>;
+    showComplete(message: string): Promise<void>;
+    /**
+     * Show a simulated email preview popup with HTML rendering
+     */
+    showEmailPreview(options: {
+        subject: string;
+        from?: string;
+        to?: string;
+        body: string;
+        highlightCode?: string;
+        isHtml?: boolean;
+    }): Promise<void>;
+    hideEmailPreview(): Promise<void>;
+    hide(): Promise<void>;
+    highlight(selector: string | Locator, duration?: number): Promise<void>;
+    unhighlight(selector: string | Locator): Promise<void>;
+}
+//# sourceMappingURL=overlay.d.ts.map

package/dist/overlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay.d.ts","sourceRoot":"","sources":["../src/overlay.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAQhE,MAAM,WAAW,cAAc;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,eAAe,CAAC;CAC1B;AAED,qBAAa,eAAe;IAC3B,OAAO,CAAC,IAAI,CAAO;IACnB,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,UAAU,CAAK;gBAEX,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,cAAc;IAK/C,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAI5B,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIlC,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIlC,aAAa,IAAI,MAAM;IAIvB,IAAI,IAAI,IAAI,MAAM,CAEjB;IAEK,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAwBxF,WAAW,CAChB,YAAY,EAAE,MAAM,EACpB,IAAI,CAAC,EAAE,MAAM,EACb,KAAK,GAAE,YAAqB,GAC1B,OAAO,CAAC,IAAI,CAAC;IAqBV,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBlD;;OAEG;IACG,gBAAgB,CAAC,OAAO,EAAE;QAC/B,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,MAAM,CAAC,EAAE,OAAO,CAAC;KACjB,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBX,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAOjC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAOrB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMvE,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;CAQ5D"}

package/dist/overlay.js

@@ -0,0 +1,134 @@
+import { renderStepOverlay, renderContextOverlay, renderCompleteOverlay, renderEmailPreview } from './overlay-html.js';
+export class TutorialOverlay {
+    page;
+    options;
+    currentStep = 0;
+    totalSteps = 0;
+    constructor(page, options) {
+        this.page = page;
+        this.options = options;
+    }
+    switchPage(page) {
+        this.page = page;
+    }
+    setTotalSteps(total) {
+        this.totalSteps = total;
+    }
+    setCurrentStep(step) {
+        this.currentStep = step;
+    }
+    incrementStep() {
+        return ++this.currentStep;
+    }
+    get step() {
+        return this.currentStep;
+    }
+    async showStep(title, description, position) {
+        const isRtl = this.options.lang === 'ar';
+        const progressPercent = this.totalSteps > 0 ? (this.currentStep / this.totalSteps) * 100 : 0;
+        const html = renderStepOverlay({
+            tutorialTitle: this.options.title,
+            step: this.currentStep,
+            title,
+            description,
+            isRtl,
+            progressPercent,
+            position: position ?? this.options.position
+        });
+        await this.page.evaluate((html) => {
+            const existing = document.getElementById('tutorial-overlay');
+            if (existing)
+                existing.remove();
+            const container = document.createElement('div');
+            container.innerHTML = html;
+            const overlay = container.firstElementChild;
+            document.body.appendChild(overlay);
+        }, html);
+    }
+    async showContext(contextTitle, text, style = 'goal') {
+        const isRtl = this.options.lang === 'ar';
+        const html = renderContextOverlay({
+            tutorialTitle: this.options.title,
+            contextTitle,
+            text,
+            style,
+            isRtl
+        });
+        await this.page.evaluate((html) => {
+            const existing = document.getElementById('tutorial-overlay');
+            if (existing)
+                existing.remove();
+            const container = document.createElement('div');
+            container.innerHTML = html;
+            const overlay = container.firstElementChild;
+            document.body.appendChild(overlay);
+        }, html);
+    }
+    async showComplete(message) {
+        const html = renderCompleteOverlay({
+            title: this.options.title,
+            message
+        });
+        await this.page.evaluate((html) => {
+            const overlay = document.getElementById('tutorial-overlay');
+            if (overlay) {
+                const container = document.createElement('div');
+                container.innerHTML = html;
+                const newOverlay = container.firstElementChild;
+                overlay.replaceWith(newOverlay);
+            }
+        }, html);
+    }
+    /**
+     * Show a simulated email preview popup with HTML rendering
+     */
+    async showEmailPreview(options) {
+        const isRtl = this.options.lang === 'ar';
+        const html = renderEmailPreview({
+            subject: options.subject,
+            from: options.from,
+            to: options.to,
+            body: options.body,
+            highlightCode: options.highlightCode,
+            isRtl
+        });
+        await this.page.evaluate((html) => {
+            const existing = document.getElementById('tutorial-email-preview');
+            if (existing)
+                existing.remove();
+            const container = document.createElement('div');
+            container.innerHTML = html;
+            const preview = container.firstElementChild;
+            document.body.appendChild(preview);
+        }, html);
+    }
+    async hideEmailPreview() {
+        await this.page.evaluate(() => {
+            const preview = document.getElementById('tutorial-email-preview');
+            if (preview)
+                preview.remove();
+        });
+    }
+    async hide() {
+        await this.page.evaluate(() => {
+            const overlay = document.getElementById('tutorial-overlay');
+            if (overlay)
+                overlay.remove();
+        });
+    }
+    async highlight(selector, duration) {
+        const locator = typeof selector === 'string' ? this.page.locator(selector) : selector;
+        await locator.evaluate((el) => el.classList.add('tutorial-highlight'));
+        await this.page.waitForTimeout(duration ?? this.options.highlightDuration);
+    }
+    async unhighlight(selector) {
+        const locator = typeof selector === 'string' ? this.page.locator(selector) : selector;
+        try {
+            await locator.evaluate((el) => el.classList.remove('tutorial-highlight'), null, { timeout: 2000 });
+        }
+        catch {
+            // Element may have been removed after click (dialog closed, navigation, etc.)
+        }
+    }
+}
+//# sourceMappingURL=overlay.js.map

package/dist/overlay.js.map

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

package/dist/postinstall.d.ts

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

package/dist/postinstall.d.ts.map

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