playwright-director 0.2.0

package/dist/styles.css

@@ -0,0 +1,637 @@
+/* Tutorial overlay styles - injected in tutorial mode */
+/* Uses scoped CSS variables for easy customization */
+
+:root {
+	/* Colors */
+	--tutorial-primary: #0066fd;
+	--tutorial-primary-light: rgba(59, 130, 246, 0.5);
+	--tutorial-primary-lighter: rgba(59, 130, 246, 0.3);
+	--tutorial-secondary: #8b5cf6;
+	--tutorial-bg-start: #1e293b;
+	--tutorial-bg-end: #0f172a;
+	--tutorial-border: rgb(231, 234, 239.5);
+	--tutorial-text: #000000;
+	--tutorial-text-muted: #1b1b1b;
+	--tutorial-text-bright: #000000;
+	--tutorial-shadow: rgba(0, 0, 0, 0.5);
+	--tutorial-cursor-stroke: #1e293b;
+
+	/* Sizing */
+	--tutorial-overlay-width: 320px;
+	--tutorial-overlay-top: 20px;
+	--tutorial-overlay-offset: 20px;
+	--tutorial-border-radius: 12px;
+	--tutorial-padding: 20px;
+	--tutorial-z-index: 999999;
+
+	/* Overlay surface — override --tutorial-overlay-bg with an rgba() for transparency */
+	--tutorial-overlay-bg: #fff;
+	--tutorial-overlay-blur: 12px;
+	--tutorial-overlay-shadow: 0 25px 50px -12px var(--tutorial-shadow), 0 0 0 1px rgba(255, 255, 255, 0.05) inset;
+	--tutorial-icon-size: 24px;
+	--tutorial-context-max-width: 500px;
+	--tutorial-scene-inactive-opacity: 0.55;
+
+	/* Animation */
+	--tutorial-animation-duration: 0.3s;
+	--tutorial-pulse-duration: 1.5s;
+
+	/* Multi-scene stage (tab bar + scene panes) */
+	--tutorial-stage-bg: #1e293b;
+	--tutorial-stage-gap: 4px;
+	--tutorial-scene-bg: #ffffff;
+	--tutorial-tabbar-padding: 8px 8px 0;
+	--tutorial-tab-bg: #334155;
+	--tutorial-tab-text: #94a3b8;
+	--tutorial-tab-bg-active: #f8fafc;
+	--tutorial-tab-text-active: #0f172a;
+	--tutorial-tab-dot: #64748b;
+	--tutorial-tab-dot-active: #22c55e;
+	--tutorial-tab-padding: 10px 20px;
+	--tutorial-tab-radius: 10px 10px 0 0;
+	--tutorial-tab-size: 15px;
+	--tutorial-tab-transition: 250ms;
+
+	/* Typography */
+	--tutorial-font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+	--tutorial-title-size: 14px;
+	--tutorial-step-title-size: 18px;
+	--tutorial-description-size: 14px;
+	--tutorial-badge-size: 12px;
+
+	/* Mobile variant values — the html[data-tutorial-variant='mobile'] block below
+	   only remaps the base variables to these, so tuning the mobile look from a
+	   consuming project is a plain `:root { ... }` override. */
+	--tutorial-overlay-width-mobile: min(250px, calc(100vw - 2 * var(--tutorial-overlay-offset)));
+	--tutorial-overlay-top-mobile: 12px;
+	--tutorial-overlay-offset-mobile: 12px;
+	--tutorial-padding-mobile: 12px;
+	--tutorial-title-size-mobile: 12px;
+	--tutorial-step-title-size-mobile: 14px;
+	--tutorial-description-size-mobile: 12px;
+	--tutorial-badge-size-mobile: 10px;
+	--tutorial-icon-size-mobile: 16px;
+	--tutorial-overlay-blur-mobile: 6px;
+	--tutorial-overlay-shadow-mobile: 0 10px 25px -8px var(--tutorial-shadow);
+	--tutorial-context-max-width-mobile: min(420px, 85vw);
+	/* Lightened content: icon and step badge hidden — bring them back with
+	   `:root { --tutorial-icon-display-mobile: inline-flex; }` */
+	--tutorial-icon-display-mobile: none;
+	--tutorial-badge-display-mobile: none;
+}
+
+/* ── Mobile variant (data-tutorial-variant set by the Tutorial class) ──────
+   Compact overlay for phone-sized panes: pure variable remaps + two display
+   toggles, nothing structural. */
+html[data-tutorial-variant='mobile'] {
+	--tutorial-overlay-width: var(--tutorial-overlay-width-mobile);
+	--tutorial-overlay-top: var(--tutorial-overlay-top-mobile);
+	--tutorial-overlay-offset: var(--tutorial-overlay-offset-mobile);
+	--tutorial-padding: var(--tutorial-padding-mobile);
+	--tutorial-title-size: var(--tutorial-title-size-mobile);
+	--tutorial-step-title-size: var(--tutorial-step-title-size-mobile);
+	--tutorial-description-size: var(--tutorial-description-size-mobile);
+	--tutorial-badge-size: var(--tutorial-badge-size-mobile);
+	--tutorial-icon-size: var(--tutorial-icon-size-mobile);
+	--tutorial-overlay-blur: var(--tutorial-overlay-blur-mobile);
+	--tutorial-overlay-shadow: var(--tutorial-overlay-shadow-mobile);
+	--tutorial-context-max-width: var(--tutorial-context-max-width-mobile);
+}
+
+html[data-tutorial-variant='mobile'] .tutorial-icon {
+	display: var(--tutorial-icon-display-mobile);
+}
+
+html[data-tutorial-variant='mobile'] .tutorial-step-badge {
+	display: var(--tutorial-badge-display-mobile);
+}
+
+html[data-tutorial-variant='mobile'] .tutorial-header {
+	margin-bottom: 8px;
+	padding-bottom: 6px;
+}
+
+html[data-tutorial-variant='mobile'] .tutorial-progress {
+	margin-top: 8px;
+	height: 3px;
+}
+
+@keyframes tutorial-pulse {
+	0%, 100% {
+		box-shadow: 0 0 0 4px var(--tutorial-primary-light);
+	}
+	50% {
+		box-shadow: 0 0 0 8px var(--tutorial-primary-lighter), 0 0 20px var(--tutorial-primary-light);
+	}
+}
+
+@keyframes tutorial-fade-in {
+	from {
+		opacity: 0;
+		transform: translateY(-10px);
+	}
+	to {
+		opacity: 1;
+		transform: translateY(0);
+	}
+}
+
+@keyframes tutorial-fade-in-center {
+	from {
+		opacity: 0;
+		transform: translate(-50%, calc(-50% - 10px));
+	}
+	to {
+		opacity: 1;
+		transform: translate(-50%, -50%);
+	}
+}
+
+@keyframes tutorial-fade-in-bottom {
+	from {
+		opacity: 0;
+		transform: translateY(10px);
+	}
+	to {
+		opacity: 1;
+		transform: translateY(0);
+	}
+}
+
+@keyframes cursor-click {
+	0%, 100% {
+		transform: translate(-50%, -50%) scale(1);
+	}
+	50% {
+		transform: translate(-50%, -50%) scale(0.8);
+	}
+}
+
+.tutorial-overlay {
+	position: fixed;
+	top: var(--tutorial-overlay-top);
+	left: var(--tutorial-overlay-offset);
+	width: var(--tutorial-overlay-width);
+	background: var(--tutorial-overlay-bg);
+	backdrop-filter: blur(var(--tutorial-overlay-blur));
+	-webkit-backdrop-filter: blur(var(--tutorial-overlay-blur));
+	border: 1px solid rgba(255, 255, 255, 0.1);
+	border-radius: var(--tutorial-border-radius);
+	padding: var(--tutorial-padding);
+	z-index: var(--tutorial-z-index);
+	font-family: var(--tutorial-font-family);
+	color: var(--tutorial-text);
+	box-shadow: var(--tutorial-overlay-shadow);
+	animation: tutorial-fade-in var(--tutorial-animation-duration) ease-out;
+	/* Never swallow clicks on app elements behind the overlay — the tutorial
+	 * is read-only and narrating, not interactive. Without this, fixed-position
+	 * UI that overlaps the overlay (e.g. the top-right scan-fab) becomes
+	 * un-clickable and tutorial.click() times out. */
+	pointer-events: none;
+}
+
+.tutorial-overlay-rtl {
+	left: auto;
+	right: var(--tutorial-overlay-offset);
+	direction: rtl;
+}
+
+.tutorial-overlay-tr {
+	left: auto;
+	right: var(--tutorial-overlay-offset);
+}
+
+.tutorial-overlay-bl {
+	top: auto;
+	bottom: var(--tutorial-overlay-top);
+}
+
+.tutorial-overlay-br {
+	left: auto;
+	right: var(--tutorial-overlay-offset);
+	top: auto;
+	bottom: var(--tutorial-overlay-top);
+}
+
+.tutorial-overlay-bl,
+.tutorial-overlay-br {
+	animation: tutorial-fade-in-bottom var(--tutorial-animation-duration) ease-out;
+}
+
+.tutorial-overlay-context {
+	/* Context overlay: centered, larger, more prominent */
+	top: 50%;
+	left: 50%;
+	right: auto;
+	transform: translate(-50%, -50%);
+	width: auto;
+	min-width: var(--tutorial-overlay-width);
+	max-width: var(--tutorial-context-max-width);
+	text-align: center;
+	padding: calc(var(--tutorial-padding) * 1.5);
+	background: var(--tutorial-overlay-bg);
+	border: 1px solid var(--tutorial-border);
+	box-shadow: 0 25px 80px -12px var(--tutorial-shadow), 0 0 40px var(--tutorial-primary-lighter);
+	animation: tutorial-fade-in-center var(--tutorial-animation-duration) ease-out;
+}
+
+.tutorial-overlay-context .tutorial-header {
+	justify-content: center;
+	border-bottom: none;
+	margin-bottom: 12px;
+	padding-bottom: 0;
+}
+
+.tutorial-overlay-context .tutorial-icon {
+	font-size: 32px;
+}
+
+.tutorial-overlay-context .tutorial-title {
+	font-size: calc(var(--tutorial-title-size) + 2px);
+	color: var(--tutorial-text);
+	flex: none;
+}
+
+.tutorial-overlay-context .tutorial-step-title {
+	font-size: calc(var(--tutorial-step-title-size) + 2px);
+	color: var(--tutorial-text-bright);
+}
+
+.tutorial-context-text {
+	font-size: var(--tutorial-description-size);
+	color: var(--tutorial-text-muted);
+	margin: 8px 0 0 0;
+	line-height: 1.5;
+}
+
+/* Context style variations */
+.tutorial-context-goal {
+	box-shadow: 0 25px 80px -12px var(--tutorial-shadow), 0 0 40px rgba(59, 130, 246, 0.3);
+}
+
+.tutorial-context-clarification {
+	box-shadow: 0 25px 80px -12px var(--tutorial-shadow), 0 0 40px rgba(250, 204, 21, 0.2);
+}
+
+.tutorial-context-clarification .tutorial-icon {
+	filter: drop-shadow(0 0 8px rgba(250, 204, 21, 0.5));
+}
+
+.tutorial-context-attention {
+	box-shadow: 0 25px 80px -12px var(--tutorial-shadow), 0 0 40px rgba(239, 68, 68, 0.2);
+	border-color: rgba(239, 68, 68, 0.3);
+}
+
+.tutorial-context-attention .tutorial-icon {
+	filter: drop-shadow(0 0 8px rgba(239, 68, 68, 0.5));
+}
+
+.tutorial-header {
+	display: flex;
+	align-items: center;
+	gap: 10px;
+	margin-bottom: 16px;
+	padding-bottom: 12px;
+	border-bottom: 1px solid var(--tutorial-border);
+}
+
+.tutorial-icon {
+	font-size: var(--tutorial-icon-size);
+}
+
+.tutorial-title {
+	font-size: var(--tutorial-title-size);
+	font-weight: 600;
+	color: var(--tutorial-text-muted);
+	margin: 0;
+	flex: 1;
+}
+
+.tutorial-step-badge {
+	background: var(--tutorial-primary);
+	color: white;
+	font-size: var(--tutorial-badge-size);
+	font-weight: 700;
+	padding: 4px 10px;
+	border-radius: 20px;
+}
+
+.tutorial-step-title {
+	font-size: var(--tutorial-step-title-size);
+	font-weight: 600;
+	color: var(--tutorial-text-bright);
+	margin: 0 0 8px 0;
+	line-height: 1.3;
+}
+
+.tutorial-step-description {
+	font-size: var(--tutorial-description-size);
+	color: var(--tutorial-text-muted);
+	margin: 0;
+	line-height: 1.5;
+}
+
+.tutorial-progress {
+	margin-top: 16px;
+	height: 4px;
+	background: var(--tutorial-border);
+	border-radius: 2px;
+	overflow: hidden;
+}
+
+.tutorial-progress-bar {
+	height: 100%;
+	background: linear-gradient(90deg, var(--tutorial-primary), var(--tutorial-secondary));
+	border-radius: 2px;
+	transition: width var(--tutorial-animation-duration) ease;
+}
+
+.tutorial-highlight {
+	position: relative;
+	z-index: calc(var(--tutorial-z-index) - 1);
+	animation: tutorial-pulse var(--tutorial-pulse-duration) ease-in-out infinite;
+	border-radius: 4px;
+}
+
+.tutorial-cursor {
+	position: fixed;
+	width: 24px;
+	height: 24px;
+	pointer-events: none;
+	z-index: var(--tutorial-z-index);
+	transform: translate(-50%, -50%);
+	transition: none;
+}
+
+.tutorial-cursor-clicking {
+	animation: cursor-click 0.15s ease-out;
+}
+
+.tutorial-cursor svg {
+	width: 100%;
+	height: 100%;
+	filter: drop-shadow(2px 2px 2px var(--tutorial-shadow));
+}
+
+.tutorial-spotlight {
+	position: fixed;
+	top: 0;
+	left: 0;
+	width: 100vw;
+	height: 100vh;
+	background: var(--tutorial-shadow);
+	z-index: calc(var(--tutorial-z-index) - 2);
+	pointer-events: none;
+	opacity: 0;
+	transition: opacity var(--tutorial-animation-duration) ease;
+}
+
+.tutorial-spotlight.active {
+	opacity: 1;
+}
+
+/* Email preview popup - simulates receiving an email */
+.tutorial-email-preview {
+	position: fixed;
+	top: 50%;
+	left: 50%;
+	transform: translate(-50%, -50%);
+	z-index: calc(var(--tutorial-z-index) + 1);
+	font-family: var(--tutorial-font-family);
+	animation: tutorial-fade-in-center var(--tutorial-animation-duration) ease-out;
+}
+
+.tutorial-email-window {
+	width: 900px;
+	max-width: 90vw;
+	background: #ffffff;
+	border-radius: 12px;
+	box-shadow: 0 25px 80px -12px rgba(0, 0, 0, 0.5), 0 0 0 1px rgba(0, 0, 0, 0.1);
+	overflow: hidden;
+}
+
+.tutorial-email-titlebar {
+	display: flex;
+	align-items: center;
+	gap: 8px;
+	padding: 12px 16px;
+	background: linear-gradient(180deg, #f7f7f7 0%, #e8e8e8 100%);
+	border-bottom: 1px solid #d1d1d1;
+}
+
+.tutorial-email-dot {
+	width: 12px;
+	height: 12px;
+	border-radius: 50%;
+}
+
+.tutorial-email-dot.red { background: #ff5f57; }
+.tutorial-email-dot.yellow { background: #ffbd2e; }
+.tutorial-email-dot.green { background: #28c840; }
+
+.tutorial-email-app {
+	margin-left: auto;
+	font-size: 13px;
+	color: #666;
+	font-weight: 500;
+}
+
+.tutorial-email-header {
+	padding: 16px;
+	background: #fafafa;
+	border-bottom: 1px solid #e5e5e5;
+	font-size: 13px;
+	color: #333;
+}
+
+.tutorial-email-field {
+	margin-bottom: 4px;
+}
+
+.tutorial-email-field:last-child {
+	margin-bottom: 0;
+}
+
+.tutorial-email-field strong {
+	color: #666;
+	font-weight: 500;
+	margin-right: 8px;
+}
+
+.tutorial-email-body-container {
+	background: #fff;
+	max-height: 350px;
+	overflow: hidden;
+}
+
+/* The email body is an isolated iframe — sizing the outer iframe gives the
+ * preview a fixed viewport; the inner document scrolls via requestAnimationFrame. */
+.tutorial-email-iframe {
+	width: 100%;
+	height: 350px;
+	border: none;
+	display: block;
+	background: #fff;
+}
+
+.tutorial-email-code {
+	background: #fff3cd;
+	color: #856404;
+	padding: 4px 12px;
+	border-radius: 4px;
+	font-weight: 700;
+	font-size: 18px;
+	letter-spacing: 2px;
+	display: inline-block;
+	margin: 8px 0;
+	border: 2px solid #ffc107;
+	animation: tutorial-pulse 1.5s ease-in-out infinite;
+}
+
+.tutorial-email-preview.tutorial-overlay-rtl .tutorial-email-field strong {
+	margin-right: 0;
+	margin-left: 8px;
+}
+
+/* ── Multi-scene stage ──────────────────────────────────────
+   A browser-like tab bar over a row of iframes. Every value is a
+   --tutorial-* variable, like the rest of this file: override them in
+   `customStyles` to match the product being demonstrated. */
+
+.tutorial-stage {
+	position: fixed;
+	inset: 0;
+	display: flex;
+	flex-direction: column;
+	background: var(--tutorial-stage-bg);
+	z-index: 0;
+}
+
+.tutorial-tabbar {
+	display: flex;
+	gap: var(--tutorial-stage-gap);
+	padding: var(--tutorial-tabbar-padding);
+	flex: 0 0 auto;
+	font-family: var(--tutorial-font-family);
+}
+
+/* Hide the shared tab bar in split mode — per-scene labels take over */
+.tutorial-stage[data-split='true'] .tutorial-tabbar {
+	display: none;
+}
+
+.tutorial-tab {
+	display: flex;
+	align-items: center;
+	gap: 8px;
+	padding: var(--tutorial-tab-padding);
+	border-radius: var(--tutorial-tab-radius);
+	background: var(--tutorial-tab-bg);
+	color: var(--tutorial-tab-text);
+	font-size: var(--tutorial-tab-size);
+	font-weight: 500;
+	white-space: nowrap;
+	transition: background var(--tutorial-tab-transition) ease,
+		color var(--tutorial-tab-transition) ease;
+}
+
+.tutorial-tab[data-active='true'] {
+	background: var(--tutorial-tab-bg-active);
+	color: var(--tutorial-tab-text-active);
+	font-weight: 600;
+}
+
+.tutorial-tab-dot {
+	width: 8px;
+	height: 8px;
+	border-radius: 50%;
+	background: var(--tutorial-tab-dot);
+	transition: background var(--tutorial-tab-transition) ease;
+}
+
+.tutorial-tab[data-active='true'] .tutorial-tab-dot {
+	background: var(--tutorial-tab-dot-active);
+}
+
+.tutorial-scenes {
+	flex: 1 1 auto;
+	display: flex;
+	gap: 0;
+	min-height: 0;
+}
+
+.tutorial-stage[data-split='true'] .tutorial-scenes {
+	gap: var(--tutorial-stage-gap);
+	background: var(--tutorial-stage-bg);
+}
+
+.tutorial-scene {
+	flex: 1 1 0;
+	min-width: 0;
+	display: flex;
+	flex-direction: column;
+}
+
+.tutorial-scene[data-active='false'] {
+	display: none;
+}
+
+/* Per-scene label: hidden in single mode, visible in split mode */
+.tutorial-scene-label {
+	display: none;
+	align-items: center;
+	justify-content: center;
+	gap: 8px;
+	padding: 8px 16px;
+	background: var(--tutorial-tab-bg-active);
+	color: var(--tutorial-tab-text-active);
+	font-size: var(--tutorial-tab-size);
+	font-weight: 600;
+	font-family: var(--tutorial-font-family);
+	white-space: nowrap;
+	flex: 0 0 auto;
+}
+
+.tutorial-stage[data-split='true'] .tutorial-scene-label {
+	display: flex;
+}
+
+.tutorial-scene-label .tutorial-tab-dot {
+	background: var(--tutorial-tab-dot-active);
+}
+
+.tutorial-scene iframe {
+	flex: 1 1 auto;
+	width: 100%;
+	height: 100%;
+	border: 0;
+	background: var(--tutorial-scene-bg);
+}
+
+/* ── Pinned split (mobile multi-scene) ──────────────────────
+   Every scene stays visible at equal width for the whole tutorial: the tab
+   bar never shows, per-scene labels take over, and focus() only dims the
+   inactive labels. Set via data-layout="split" by the Tutorial class. */
+
+.tutorial-stage[data-layout='split'] .tutorial-tabbar {
+	display: none;
+}
+
+.tutorial-stage[data-layout='split'] .tutorial-scenes {
+	gap: var(--tutorial-stage-gap);
+	background: var(--tutorial-stage-bg);
+}
+
+.tutorial-stage[data-layout='split'] .tutorial-scene,
+.tutorial-stage[data-layout='split'] .tutorial-scene[data-active='false'] {
+	display: flex;
+	flex: 1 1 0;
+}
+
+.tutorial-stage[data-layout='split'] .tutorial-scene-label {
+	display: flex;
+}
+
+.tutorial-stage[data-layout='split'] .tutorial-scene[data-active='false'] .tutorial-scene-label {
+	opacity: var(--tutorial-scene-inactive-opacity);
+}

package/dist/timeline.d.ts

@@ -0,0 +1,87 @@
+export interface TimelineStep {
+    step: number;
+    title: string;
+    text?: string;
+    key?: string;
+    audioFile: string;
+    startMs: number;
+    durationMs: number;
+    /** Scene(s) on stage for this step — tells a transcript reader who was on
+     *  screen. An array means two scenes shared the stage. */
+    scene?: string | string[];
+}
+export interface TimelineData {
+    testName: string;
+    /** Raw test title passed to Playwright's `test(...)` — the i18n key.
+     *  Lets the reporter match a timeline to its testCase without re-deriving testName. */
+    testTitle: string;
+    /** Display title from the Tutorial options — what the gallery site shows on the card. */
+    title?: string;
+    testFile: string;
+    projectName: string;
+    lang: string;
+    totalDurationMs: number;
+    /** Milliseconds to trim from video start (preload time) */
+    videoTrimMs: number;
+    /** True when a full-screen black sync marker was recorded right before
+     *  timeline zero — the reporter then computes the exact trim from the
+     *  video itself (blackdetect) instead of trusting videoTrimMs. */
+    syncMarker?: boolean;
+    steps: TimelineStep[];
+    /** Video file path from Playwright */
+    videoPath: string;
+    /** Pre-built ffmpeg command */
+    mergeCommand: string;
+    /** Feature name sourced from @feature:* test tag */
+    feature?: string;
+    /** Recording variant (e.g. 'mobile') — testName already carries its suffix.
+     *  Lets the reporter pick the right timeline when the same test was recorded
+     *  in several variants, and the site filter videos by variant. */
+    variant?: string;
+}
+export interface TimelineMusicOptions {
+    musicFile?: string;
+    musicVolume?: number;
+    voiceVolume?: number;
+}
+/**
+ * Tracks timing of tutorial steps for post-processing audio merge.
+ */
+export declare class TutorialTimeline {
+    private testName;
+    private testTitle;
+    private title;
+    private testFile;
+    private projectName;
+    private lang;
+    private feature;
+    private variant;
+    private musicOptions;
+    private startTime;
+    private videoTrimMs;
+    private syncMarker;
+    private steps;
+    private videoPath;
+    constructor(testName: string, testFile?: string, projectName?: string, lang?: string, testTitle?: string, feature?: string, musicOptions?: TimelineMusicOptions, title?: string, variant?: string);
+    /**
+     * Mark the start of the tutorial (second 0 for video)
+     */
+    start(videoTrimMs?: number, syncMarker?: boolean): void;
+    /**
+     * Set the video path (from Playwright's page.video()?.path())
+     */
+    setVideoPath(path: string): void;
+    /**
+     * Record a step at a specific timestamp (for accurate voice timing)
+     */
+    addStep(step: number, title: string, audioFile: string, durationMs: number, timestamp: number, text?: string, key?: string, scene?: string | string[]): void;
+    /**
+     * Get the timeline data with merge command
+     */
+    getData(): TimelineData;
+    /**
+     * Save timeline to JSON file and auto-generate transcript markdown.
+     */
+    save(outputPath: string): void;
+}
+//# sourceMappingURL=timeline.d.ts.map