playwright-director 0.2.0

package/dist/tts-provider.js

@@ -0,0 +1,182 @@
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import { existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+const execAsync = promisify(exec);
+/** Get audio duration using ffprobe */
+async function getAudioDuration(filePath) {
+    try {
+        const { stdout } = await execAsync(`ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 "${filePath}"`);
+        return Math.ceil(parseFloat(stdout.trim()) * 1000);
+    }
+    catch {
+        // Fallback: estimate based on text length (80ms per character at normal rate)
+        return 3000;
+    }
+}
+/**
+ * Command-based TTS provider. Defaults to macOS `say`, can be overridden
+ * via TUTORIAL_TTS_CMD env var.
+ * Supports placeholders: {lang}, {text}, {output}.
+ * If {text}/{output} are present they are substituted in-place; otherwise
+ * the legacy "-o <output> <text>" suffix is appended automatically.
+ * Examples:
+ *   TUTORIAL_TTS_CMD='qsay --my-voice jadou -l {lang} {text} -o {output}'
+ *   TUTORIAL_TTS_CMD='say -v Thomas'   (legacy: appends -o <out> "<text>")
+ */
+export class CommandTTSProvider {
+    name;
+    command;
+    options;
+    static VOICES = {
+        fr: 'Thomas',
+        en: 'Samantha',
+        ar: 'Maged'
+    };
+    static LANG_NAMES = {
+        fr: 'french',
+        en: 'english',
+        ar: 'arabic'
+    };
+    static _logged = false;
+    constructor(options) {
+        this.options = options;
+        const ttsCmd = process.env.TUTORIAL_TTS_CMD;
+        if (!CommandTTSProvider._logged) {
+            console.log(`[TTS] TUTORIAL_TTS_CMD=${ttsCmd ?? '(not set)'}`);
+            CommandTTSProvider._logged = true;
+        }
+        if (ttsCmd) {
+            const langName = CommandTTSProvider.LANG_NAMES[options.lang] || options.lang;
+            this.command = ttsCmd.replace('{lang}', langName);
+            this.name = `tts:${this.command.split(/\s/)[0]}`;
+        }
+        else {
+            const voice = options.voice || CommandTTSProvider.VOICES[options.lang] || 'Samantha';
+            const rate = Math.round((options.rate || 1) * 175);
+            this.command = `say -v "${voice}" -r ${rate} --data-format=LEI16@44100`;
+            this.name = 'macos-say';
+        }
+    }
+    async isAvailable() {
+        const binary = this.command.split(/\s/)[0];
+        try {
+            await execAsync(`which ${binary}`);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async synthesize(text, outputPath) {
+        const escapedText = text.replace(/"/g, '\\"');
+        const hasPlaceholders = this.command.includes('{text}') || this.command.includes('{output}');
+        const cmd = hasPlaceholders
+            ? this.command.replace('{text}', `"${escapedText}"`).replace('{output}', `"${outputPath}"`)
+            : `${this.command} -o "${outputPath}" "${escapedText}"`;
+        console.log(`[TTS] Running: ${cmd}`);
+        await execAsync(cmd);
+        const duration = await getAudioDuration(outputPath);
+        return { filePath: outputPath, duration };
+    }
+}
+/** Edge TTS provider using Microsoft's free TTS API */
+export class EdgeTTSProvider {
+    name = 'edge-tts';
+    options;
+    static VOICES = {
+        fr: 'fr-FR-HenriNeural',
+        en: 'en-US-GuyNeural',
+        ar: 'ar-SA-HamedNeural'
+    };
+    constructor(options) {
+        this.options = options;
+    }
+    async isAvailable() {
+        try {
+            await execAsync('which edge-tts');
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async synthesize(text, outputPath) {
+        const voice = this.options.voice || EdgeTTSProvider.VOICES[this.options.lang] || 'en-US-GuyNeural';
+        const rate = this.options.rate || 1;
+        const ratePercent = rate >= 1 ? `+${Math.round((rate - 1) * 100)}%` : `-${Math.round((1 - rate) * 100)}%`;
+        await execAsync(`edge-tts --voice "${voice}" --rate="${ratePercent}" --text "${text.replace(/"/g, '\\"')}" --write-media "${outputPath}"`);
+        const duration = await getAudioDuration(outputPath);
+        return { filePath: outputPath, duration };
+    }
+}
+/** Auto-detect and create the best available TTS provider */
+export async function createTTSProvider(options) {
+    // Command provider: custom TUTORIAL_TTS_CMD or macOS say
+    const cmdProvider = new CommandTTSProvider(options);
+    if (await cmdProvider.isAvailable()) {
+        return cmdProvider;
+    }
+    // Fallback to edge-tts
+    const edgeProvider = new EdgeTTSProvider(options);
+    if (await edgeProvider.isAvailable()) {
+        return edgeProvider;
+    }
+    throw new Error('No TTS provider available. Install edge-tts: pip install edge-tts');
+}
+/** Manages TTS audio generation and tracking for tutorials */
+export class TTSManager {
+    provider = null;
+    options;
+    outputDir;
+    segments = [];
+    recordingStartTime = 0;
+    constructor(options, outputDir) {
+        this.options = options;
+        this.outputDir = outputDir;
+    }
+    async initialize() {
+        if (!existsSync(this.outputDir)) {
+            mkdirSync(this.outputDir, { recursive: true });
+        }
+        this.provider = await createTTSProvider(this.options);
+        console.log(`[TTS] Using provider: ${this.provider.name}`);
+    }
+    startRecording() {
+        this.recordingStartTime = Date.now();
+        this.segments = [];
+    }
+    async speak(text) {
+        if (!this.provider) {
+            await this.initialize();
+        }
+        const timestamp = Date.now() - this.recordingStartTime;
+        const filename = `voice_${timestamp}.mp3`;
+        const filePath = join(this.outputDir, filename);
+        const result = await this.provider.synthesize(text, filePath);
+        this.segments.push({
+            filePath: result.filePath,
+            timestamp,
+            duration: result.duration,
+            text
+        });
+        return result.duration;
+    }
+    getSegments() {
+        return [...this.segments];
+    }
+    /** Generate a manifest file for post-processing */
+    async writeManifest(videoPath) {
+        const manifestPath = join(this.outputDir, 'audio-manifest.json');
+        const manifest = {
+            videoPath,
+            recordingStart: this.recordingStartTime,
+            segments: this.segments,
+            provider: this.provider?.name
+        };
+        const { writeFileSync } = await import('fs');
+        writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+        return manifestPath;
+    }
+}
+//# sourceMappingURL=tts-provider.js.map

package/dist/tts-provider.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,109 @@
+export interface TutorialOptions {
+    /** Tutorial title shown in overlay */
+    title: string;
+    /** Test name for output files (default: auto-generated) */
+    testName?: string;
+    /** Raw test title as passed to `test(...)` — the i18n key. Used by the reporter
+     *  to match this tutorial to its Playwright testCase without re-deriving. */
+    testTitle?: string;
+    /** Test file path (e.g., "free/01_company.init.ts") */
+    testFile?: string;
+    /** Playwright project name (e.g., "setup-free-init") */
+    projectName?: string;
+    /** Language for UI text and TTS (default: 'en') */
+    lang?: string;
+    /** Translation function — pass your i18n `t()`. Falls back to identity. */
+    translate?: (key: string) => string;
+    /** Base URL for serving audio files (default: 'http://localhost:5173') */
+    audioBaseUrl?: string;
+    /** Delay between steps in ms (default: 500) */
+    stepDelay?: number;
+    /** Duration of highlight animation in ms (default: 800) */
+    highlightDuration?: number;
+    /** Mouse movement speed - steps for smooth movement (default: 25) */
+    mouseSteps?: number;
+    /** Pause after mouse reaches target in ms (default: 300) */
+    pauseBeforeClick?: number;
+    /** Enable voice narration using Web Speech API */
+    enableVoice?: boolean;
+    /** Voice name to use (e.g., 'Google français', 'Microsoft David') */
+    voiceName?: string;
+    /** Voice rate (0.1 to 10, default: 0.9) */
+    voiceRate?: number;
+    /** Voice pitch (0 to 2, default: 1) */
+    voicePitch?: number;
+    /** Background music URL (relative to public folder or absolute URL) */
+    backgroundMusic?: string;
+    /** Background music volume (0 to 1, default: 0.15) */
+    musicVolume?: number;
+    /** Voice narration volume multiplier (default: 2.5) */
+    voiceVolume?: number;
+    /** Custom CSS to inject (overrides default styles) */
+    customStyles?: string;
+    /** Play audio in browser during test for live viewing (default: true) */
+    playAudioInBrowser?: boolean;
+    /** Feature tag (e.g., 'payroll') — sourced from @feature:* test tag */
+    feature?: string;
+    /** Named scenes, each an iframe of its own origin, shown as browser-like tabs.
+     *  Distinct origins are what let two user profiles stay logged in at once. */
+    scenes?: Record<string, SceneOptions>;
+    /** Scene(s) active when the stage is mounted (default: the first one) */
+    focus?: SceneFocus;
+    /** Scene switch animation */
+    sceneTransition?: {
+        duration?: number;
+    };
+    /** Overlay position: TL (top-left), TR (top-right, default), BL (bottom-left), BR (bottom-right) */
+    overlayPosition?: OverlayPosition;
+    /** Variant suffix appended to testName — `<testName>-<variant>` — so a second
+     *  recording of the same tutorial (video, timeline, transcript, screenshots)
+     *  never overwrites the first. Defaults to process.env.TUTORIAL_VARIANT.
+     *  The variant `'mobile'` also switches to a compact overlay and, with 2+
+     *  scenes, a permanent split stage (all scenes visible, ratios ignored). */
+    variant?: string;
+}
+export interface SceneOptions {
+    /** Label shown on the scene's tab — keep it a person, not a URL */
+    label: string;
+    /** Origin that relative `goto` paths resolve against */
+    baseUrl?: string;
+}
+/** One scene fills the stage; two share it side by side.
+ *  In an array, the first scene is the one acting — it carries the cursor. */
+export type SceneFocus = string | string[];
+export interface FocusOptions {
+    /** Flex ratio for each active scene, e.g. [30, 70]. Must match the number of scenes. */
+    ratio?: number[];
+}
+export interface StepOptions {
+    /** Optional description shown below step title */
+    description?: string;
+    /** Skip mouse movement for this step */
+    skipMouse?: boolean;
+    /** Custom delay after this step */
+    delay?: number;
+    /** Custom text for voice narration (if different from title/description) */
+    voiceText?: string;
+    /** Skip voice for this step */
+    skipVoice?: boolean;
+    /** Short action narration (defaults to title) */
+    do?: string;
+    /** Explanation that plays during action (two-phase timing) */
+    explain?: string;
+    /** Scene(s) this step plays on. The stage switches before the action runs,
+     *  because a hidden scene cannot be interacted with. */
+    scene?: SceneFocus;
+    /** Override overlay position for this step */
+    overlayPosition?: OverlayPosition;
+}
+export type OverlayPosition = 'TL' | 'TR' | 'BL' | 'BR';
+export type ContextStyle = 'goal' | 'clarification' | 'attention';
+export interface ContextOptions {
+    /** Description shown below title */
+    text?: string;
+    /** Custom voice text (defaults to title + text) */
+    voiceText?: string;
+    /** Context style: goal (🎯), clarification (💡), attention (⚠️) */
+    style?: ContextStyle;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/dist/voice-prerender.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Voice pre-rendering — generate the narration clips OUTSIDE of any test run,
+ * where TTS synthesis is slow and serial. Texts are collected from the
+ * artifacts that record them verbatim:
+ *
+ *  - `tutorials/transcripts/*.md` — one per tutorial, survives every run;
+ *  - `tutorials/output/*_timeline.json` — fresh but wiped by Playwright runs.
+ */
+export interface NarrationText {
+    lang: string;
+    text: string;
+}
+export interface VoiceSources {
+    timelineDir?: string;
+    transcriptDir?: string;
+}
+/** Same naming scheme as the runtime voice cache (voice.ts). */
+export declare function audioFilename(lang: string, text: string): string;
+/** All known narration texts, deduplicated. */
+export declare function collectVoices(sources?: VoiceSources): NarrationText[];
+export interface RegenOptions extends VoiceSources {
+    lang?: string;
+    /** Parallel TTS syntheses (default 2) */
+    workers?: number;
+    /** Re-synthesize cached clips too (after a voice settings change). Default: missing only. */
+    force?: boolean;
+}
+/**
+ * Pre-render the voice cache without running any test: collect every known
+ * narration text, synthesize the missing clips (all of them with `force`) with
+ * the CURRENT TTS settings, in parallel. The audio dir may have been deleted
+ * entirely — it is recreated. Videos are not remixed; a `TUTORIAL_MODE=true`
+ * run picks the clips up from cache.
+ */
+export declare function regenVoices(audioDir: string, options?: RegenOptions): Promise<{
+    total: number;
+    cached: number;
+    done: number;
+    failed: number;
+}>;
+//# sourceMappingURL=voice-prerender.d.ts.map

package/dist/voice-prerender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice-prerender.d.ts","sourceRoot":"","sources":["../src/voice-prerender.ts"],"names":[],"mappings":"AAOA;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,YAAY;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,gEAAgE;AAChE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAIhE;AAoCD,+CAA+C;AAC/C,wBAAgB,aAAa,CAAC,OAAO,GAAE,YAAiB,GAAG,aAAa,EAAE,CAiBzE;AAUD,MAAM,WAAW,YAAa,SAAQ,YAAY;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6FAA6F;IAC7F,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAChC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,YAAiB,GACxB,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CA4C1E"}

package/dist/voice-prerender.js

@@ -0,0 +1,122 @@
+import { createHash } from 'crypto';
+import { existsSync, readFileSync, rmSync, mkdirSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { createTTSProvider } from './tts-provider.js';
+import { parseTranscript } from './transcript.js';
+/** Same naming scheme as the runtime voice cache (voice.ts). */
+export function audioFilename(lang, text) {
+    const hash = createHash('md5').update(`${lang}:${text}`).digest('hex').slice(0, 12);
+    const ext = process.platform === 'darwin' ? 'wav' : 'mp3';
+    return `${hash}.${ext}`;
+}
+function collectFromTimelines(timelineDir) {
+    if (!existsSync(timelineDir))
+        return [];
+    const entries = [];
+    for (const file of readdirSync(timelineDir).filter((f) => f.endsWith('_timeline.json'))) {
+        try {
+            const data = JSON.parse(readFileSync(join(timelineDir, file), 'utf-8'));
+            for (const step of data.steps) {
+                if (step.audioFile && step.text?.trim())
+                    entries.push({ lang: data.lang, text: step.text });
+            }
+        }
+        catch {
+            console.warn(`[Voice] Skipping unreadable timeline: ${file}`);
+        }
+    }
+    return entries;
+}
+function collectFromTranscripts(transcriptDir) {
+    if (!existsSync(transcriptDir))
+        return [];
+    const entries = [];
+    for (const file of readdirSync(transcriptDir).filter((f) => f.endsWith('.md'))) {
+        try {
+            const markdown = readFileSync(join(transcriptDir, file), 'utf-8');
+            const lang = markdown.match(/^- \*\*Language:\*\* (\S+)/m)?.[1];
+            if (!lang)
+                continue;
+            for (const entry of parseTranscript(markdown)) {
+                if (entry.text.trim())
+                    entries.push({ lang, text: entry.text });
+            }
+        }
+        catch {
+            console.warn(`[Voice] Skipping unreadable transcript: ${file}`);
+        }
+    }
+    return entries;
+}
+/** All known narration texts, deduplicated. */
+export function collectVoices(sources = {}) {
+    const timelineDir = sources.timelineDir ?? process.env.TUTORIAL_OUTPUT_DIR ?? join(process.cwd(), 'tutorials', 'output');
+    const transcriptDir = sources.transcriptDir ??
+        process.env.TUTORIAL_TRANSCRIPT_DIR ??
+        join(process.cwd(), 'tutorials', 'transcripts');
+    const seen = new Set();
+    const all = [];
+    for (const entry of [...collectFromTranscripts(transcriptDir), ...collectFromTimelines(timelineDir)]) {
+        const key = `${entry.lang}:${entry.text}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        all.push(entry);
+    }
+    return all;
+}
+async function pool(items, limit, fn) {
+    const queue = [...items];
+    const workers = Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, async () => {
+        while (queue.length)
+            await fn(queue.shift());
+    });
+    await Promise.all(workers);
+}
+/**
+ * Pre-render the voice cache without running any test: collect every known
+ * narration text, synthesize the missing clips (all of them with `force`) with
+ * the CURRENT TTS settings, in parallel. The audio dir may have been deleted
+ * entirely — it is recreated. Videos are not remixed; a `TUTORIAL_MODE=true`
+ * run picks the clips up from cache.
+ */
+export async function regenVoices(audioDir, options = {}) {
+    const all = collectVoices(options).filter((e) => !options.lang || e.lang === options.lang);
+    const todo = options.force
+        ? all
+        : all.filter((e) => !existsSync(join(audioDir, audioFilename(e.lang, e.text))));
+    const result = { total: all.length, cached: all.length - todo.length, done: 0, failed: 0 };
+    console.log(`[Voice] ${all.length} narration(s) known, ${todo.length} to synthesize` +
+        (options.force ? ' (force)' : `, ${result.cached} already cached`));
+    if (todo.length === 0)
+        return result;
+    mkdirSync(audioDir, { recursive: true });
+    // One provider per language — the provider resolves voice/rate from the env.
+    const providers = new Map();
+    for (const lang of new Set(todo.map((e) => e.lang))) {
+        const provider = await createTTSProvider({
+            lang,
+            voice: process.env.TUTORIAL_VOICE_NAME || undefined,
+            rate: 1.0
+        });
+        console.log(`[Voice] ${lang}: TTS provider ${provider.name}`);
+        providers.set(lang, provider);
+    }
+    await pool(todo, options.workers ?? 2, async ({ lang, text }) => {
+        const filePath = join(audioDir, audioFilename(lang, text));
+        try {
+            // Remove first: a failed synthesis must not leave a stale clip
+            // pretending to be regenerated.
+            rmSync(filePath, { force: true });
+            await providers.get(lang).synthesize(text, filePath);
+            result.done++;
+            console.log(`  ✔ [${result.done}/${todo.length}] ${lang} ${text.slice(0, 60)}${text.length > 60 ? '…' : ''}`);
+        }
+        catch (error) {
+            result.failed++;
+            console.error(`  ✖ ${lang} ${text.slice(0, 40)}… ${error}`);
+        }
+    });
+    return result;
+}
+//# sourceMappingURL=voice-prerender.js.map

package/dist/voice-prerender.js.map

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

package/dist/voice.d.ts

@@ -0,0 +1,76 @@
+import type { Page } from '@playwright/test';
+export interface VoiceOptions {
+    lang: string;
+    voiceName: string;
+    voiceRate: number;
+    voicePitch: number;
+    playInBrowser?: boolean;
+    audioBaseUrl?: string;
+}
+export interface PreloadedAudio {
+    text: string;
+    filename: string;
+    filePath: string;
+    url: string;
+    durationMs: number;
+}
+/**
+ * TTS voice generation for tutorials.
+ * Pre-generates audio files and tracks their durations.
+ * Optionally plays audio in browser during test.
+ */
+export declare class TutorialVoice {
+    private page;
+    private options;
+    private ttsProvider;
+    private preloadedAudio;
+    constructor(page: Page, options: VoiceOptions);
+    switchPage(page: Page): void;
+    /**
+     * Pre-generate a single audio file (non-blocking).
+     * Returns a promise that resolves when preload is complete.
+     * No-op when TUTORIAL_MODE is not enabled.
+     */
+    preloadSingle(text: string): Promise<void>;
+    /**
+     * Pre-generate all audio files before the test runs.
+     * No-op when TUTORIAL_MODE is not enabled.
+     */
+    preload(texts: string[]): Promise<void>;
+    /**
+     * Get audio info for a text (must be preloaded first)
+     */
+    getAudio(text: string): PreloadedAudio | undefined;
+    /**
+     * Get duration in ms for a text (must be preloaded)
+     */
+    getDuration(text: string): number;
+    /**
+     * Get the filename for a text (for timeline)
+     */
+    getFilename(text: string): string;
+    /**
+     * Start audio playback without waiting for it to finish.
+     * Returns the clip duration in ms — the caller owns the wall clock
+     * (action offset + clamp to duration), so headed playback and the
+     * ffmpeg merge stay in sync.
+     * No-op when TUTORIAL_MODE is not enabled (returns 0).
+     */
+    startPlayback(text: string): Promise<number>;
+    /**
+     * Play audio in browser (optional, for live viewing)
+     * Returns duration in ms
+     * Will generate audio on-demand if not preloaded.
+     * No-op when TUTORIAL_MODE is not enabled (returns 0).
+     */
+    play(text: string): Promise<number>;
+    /**
+     * Generate audio for a single text on demand
+     */
+    private generateAudio;
+    /**
+     * Get audio duration using ffprobe or file stats
+     */
+    private getAudioDuration;
+}
+//# sourceMappingURL=voice.d.ts.map

package/dist/voice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice.d.ts","sourceRoot":"","sources":["../src/voice.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAQ7C,MAAM,WAAW,YAAY;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAeD,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,qBAAa,aAAa;IACzB,OAAO,CAAC,IAAI,CAAO;IACnB,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,WAAW,CAA4B;IAC/C,OAAO,CAAC,cAAc,CAA0C;gBAEpD,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY;IAY7C,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAI5B;;;;OAIG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK1C;;;OAGG;IACG,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAiD7C;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAIlD;;OAEG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAIjC;;OAEG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAMjC;;;;;;OAMG;IACG,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAyBlD;;;;;OAKG;IACG,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAiCzC;;OAEG;YACW,aAAa;IAgD3B;;OAEG;YACW,gBAAgB;CAiB9B"}