craftdriver 1.2.0 → 1.4.0

package/dist/lib/electronMainLogs.js

@@ -0,0 +1,176 @@
+/**
+ * Main-process console/error capture for Electron — the `browser.electron.mainLogs`
+ * counterpart to the renderer's `browser.logs`. It buffers what the app's **main
+ * process** writes to `console.*`, delivered over the same Node inspector socket as
+ * `executeMain` via CDP `Runtime.consoleAPICalled` events (see ElectronMainBridge).
+ *
+ * Why console-based (measured against the real app, 2026-07-11): in the Electron
+ * main process `Runtime.exceptionThrown` is *not* a reliable error signal — Electron
+ * installs its own uncaught-exception handling, and unhandled promise rejections are
+ * emitted by Node as `UnhandledPromiseRejectionWarning`s routed through
+ * `console.error`. So `console.error(...)` (and those warnings) are captured as
+ * error-level entries; any `exceptionThrown` that *does* arrive is surfaced too, as a
+ * best-effort `type: 'exception'` entry.
+ *
+ * Capture is always-on once the session is launched with `electron.mainProcess: true`
+ * (the bridge connects and enables the Runtime domain at launch), mirroring the
+ * always-on renderer log capture.
+ */
+import { CraftdriverError, ErrorCode } from './errors.js';
+import { DEFAULT_NAVIGATION_TIMEOUT_MS } from './timing.js';
+const MAX_LOGS = 1000;
+/** Map a CDP console `type` to a normalized level (aligned with @wdio/electron-service). */
+function mapConsoleLevel(type) {
+    switch (type) {
+        case 'error':
+        case 'assert':
+            return 'error';
+        case 'warning':
+            return 'warn';
+        case 'info':
+            return 'info';
+        case 'debug':
+        case 'trace':
+            return 'debug';
+        case 'log':
+            return 'log';
+        default:
+            return 'log';
+    }
+}
+function deserializeArg(o) {
+    if (o.type === 'undefined')
+        return undefined;
+    if (o.subtype === 'null')
+        return null;
+    if (o.type === 'string' || o.type === 'number' || o.type === 'boolean')
+        return o.value;
+    // objects, functions, errors, bigint, …: the description is the portable, console-like form.
+    return o.description ?? (o.subtype ? `[${o.subtype}]` : `[${o.type}]`);
+}
+function argToText(o) {
+    if (o.type === 'undefined')
+        return 'undefined';
+    if (o.subtype === 'null')
+        return 'null';
+    if (o.type === 'string' || o.type === 'number' || o.type === 'boolean')
+        return String(o.value);
+    return o.description ?? (o.subtype ? `[${o.subtype}]` : `[${o.type}]`);
+}
+function formatStackTrace(trace) {
+    if (!trace?.callFrames?.length)
+        return undefined;
+    return trace.callFrames
+        .map((f) => `  at ${f.functionName || '<anonymous>'} (${f.url ?? ''}:${f.lineNumber ?? 0}:${f.columnNumber ?? 0})`)
+        .join('\n');
+}
+/**
+ * Buffers and dispatches main-process log entries. Reachable via
+ * `browser.electron.mainLogs`; its public surface mirrors the renderer
+ * {@link LogMonitor} so console monitoring reads the same in both processes.
+ */
+export class ElectronMainLogMonitor {
+    #logs = [];
+    #handlers = new Set();
+    #errorHandlers = new Set();
+    /** Feed a CDP `Runtime.consoleAPICalled` event. */
+    ingestConsoleEvent(params) {
+        const args = params.args ?? [];
+        this.#record({
+            type: 'console',
+            level: mapConsoleLevel(params.type),
+            text: args.map(argToText).join(' '),
+            args: args.map(deserializeArg),
+            timestamp: params.timestamp ? new Date(params.timestamp) : new Date(),
+            method: params.type,
+            stackTrace: formatStackTrace(params.stackTrace),
+        });
+    }
+    /** Feed a CDP `Runtime.exceptionThrown` event (best-effort in Electron main). */
+    ingestExceptionEvent(params) {
+        const details = params.exceptionDetails;
+        const text = details?.exception?.description ?? details?.text ?? 'uncaught exception';
+        this.#record({
+            type: 'exception',
+            level: 'error',
+            text,
+            args: [],
+            timestamp: params.timestamp ? new Date(params.timestamp) : new Date(),
+            stackTrace: formatStackTrace(details?.stackTrace),
+        });
+    }
+    /** All captured entries (console + exceptions), oldest first. */
+    getLogs() {
+        return [...this.#logs];
+    }
+    /** Only error-level entries: `console.error`/`console.assert` and every reported exception. */
+    getErrors() {
+        return this.#logs.filter((l) => l.level === 'error');
+    }
+    /** Drop everything captured so far. */
+    clearLogs() {
+        this.#logs = [];
+    }
+    /** Subscribe to every entry. Returns an unsubscribe function. */
+    onLog(handler) {
+        this.#handlers.add(handler);
+        return () => this.#handlers.delete(handler);
+    }
+    /** Subscribe to error-level entries only. Returns an unsubscribe function. */
+    onError(handler) {
+        this.#errorHandlers.add(handler);
+        return () => this.#errorHandlers.delete(handler);
+    }
+    /** Resolve with the first entry matching `predicate` (checked against already-buffered entries first). */
+    waitForLog(predicate, timeout = DEFAULT_NAVIGATION_TIMEOUT_MS) {
+        return this.#waitFor(this.#logs, this.onLog.bind(this), predicate, timeout, 'log');
+    }
+    /** Resolve with the first error-level entry matching `predicate` (default: any error). */
+    waitForError(predicate = () => true, timeout = DEFAULT_NAVIGATION_TIMEOUT_MS) {
+        return this.#waitFor(this.getErrors(), this.onError.bind(this), predicate, timeout, 'error');
+    }
+    /** Throw if any error-level entry was captured — a fail-fast assertion for tests. */
+    assertNoErrors() {
+        const errors = this.getErrors();
+        if (errors.length > 0) {
+            throw new CraftdriverError(ErrorCode.ELECTRON_MAIN_THREW, `Electron main process reported ${errors.length} error(s):\n${errors.map((e) => e.text).join('\n')}`);
+        }
+    }
+    #record(log) {
+        this.#logs.push(log);
+        if (this.#logs.length > MAX_LOGS)
+            this.#logs.shift();
+        this.#notify(this.#handlers, log);
+        if (log.level === 'error')
+            this.#notify(this.#errorHandlers, log);
+    }
+    #notify(handlers, log) {
+        for (const handler of handlers) {
+            try {
+                handler(log);
+            }
+            catch {
+                // A subscriber's own failure must never break capture or other subscribers.
+            }
+        }
+    }
+    #waitFor(buffered, subscribe, predicate, timeout, kind) {
+        const existing = buffered.find(predicate);
+        if (existing)
+            return Promise.resolve(existing);
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                unsubscribe();
+                reject(new CraftdriverError(ErrorCode.TIMEOUT, `Timed out after ${timeout}ms waiting for a matching Electron main-process ${kind}.`));
+            }, timeout);
+            const unsubscribe = subscribe((log) => {
+                if (!predicate(log))
+                    return;
+                clearTimeout(timer);
+                unsubscribe();
+                resolve(log);
+            });
+        });
+    }
+}
+//# sourceMappingURL=electronMainLogs.js.map

package/dist/lib/electronMainLogs.js.map

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

package/dist/lib/electronMock.d.ts

@@ -0,0 +1,52 @@
+/** One recorded invocation of a mocked Electron main-process method. */
+export interface ElectronMockCall {
+    /** The (JSON-safe) arguments the app passed to the mocked method. */
+    args: unknown[];
+}
+interface MainExecutor {
+    executeMain<T = unknown>(fn: (electron: unknown, ...args: unknown[]) => T | Promise<T>, ...args: unknown[]): Promise<T>;
+}
+/**
+ * A replacement for a single `electron.<api>.<fn>` main-process method, returned
+ * by `browser.electron.mock()`. Records every call, returns a scripted value, and
+ * restores the original method on `restore()` or `browser.quit()`.
+ *
+ * This is the general primitive behind the typed `mockDialog()` convenience: use
+ * it for any `electron` module method (`app.getPath`, `shell.openExternal`,
+ * `safeStorage.encryptString`, …) whose real behavior you want to replace during a
+ * test.
+ */
+export interface ElectronMock {
+    /** The `electron` module namespace, e.g. `'app'`, `'shell'`, `'dialog'`. */
+    readonly api: string;
+    /** The method name on that namespace, e.g. `'getPath'`, `'openExternal'`. */
+    readonly fn: string;
+    /** Every recorded call, oldest first. Args are JSON-safe copies. */
+    getCalls(): Promise<ElectronMockCall[]>;
+    /** How many times the mocked method was called. */
+    getCallCount(): Promise<number>;
+    /** Re-script the value the mocked method returns from now on. */
+    mockReturnValue(value: unknown): Promise<void>;
+    /** Clear recorded calls without changing the scripted return value. */
+    clearCalls(): Promise<void>;
+    /** Restore the original method. Safe to call more than once. */
+    restore(): Promise<void>;
+}
+/** Internal implementation; users receive the public {@link ElectronMock} interface. */
+export declare class ElectronMockHandle implements ElectronMock {
+    #private;
+    readonly api: string;
+    readonly fn: string;
+    constructor(executor: MainExecutor, api: string, fn: string, id: string, onRestore: () => void);
+    getCalls(): Promise<ElectronMockCall[]>;
+    getCallCount(): Promise<number>;
+    mockReturnValue(value: unknown): Promise<void>;
+    clearCalls(): Promise<void>;
+    restore(): Promise<void>;
+}
+/** Reject obviously wrong `api`/`fn` before touching the main process. */
+export declare function validateMockTarget(api: string, fn: string): void;
+/** The `Symbol.for` key string, exported so {@link ElectronRemote} can install the registry. */
+export declare const ELECTRON_MOCK_REGISTRY_KEY = "craftdriver.electron.apiMocks";
+export {};
+//# sourceMappingURL=electronMock.d.ts.map

package/dist/lib/electronMock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"electronMock.d.ts","sourceRoot":"","sources":["../../src/lib/electronMock.ts"],"names":[],"mappings":"AAEA,wEAAwE;AACxE,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,IAAI,EAAE,OAAO,EAAE,CAAC;CACjB;AAED,UAAU,YAAY;IACpB,WAAW,CAAC,CAAC,GAAG,OAAO,EACrB,EAAE,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAC7D,GAAG,IAAI,EAAE,OAAO,EAAE,GACjB,OAAO,CAAC,CAAC,CAAC,CAAC;CACf;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,QAAQ,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAC;IACxC,mDAAmD;IACnD,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAChC,iEAAiE;IACjE,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,uEAAuE;IACvE,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,gEAAgE;IAChE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAKD,wFAAwF;AACxF,qBAAa,kBAAmB,YAAW,YAAY;;IACrD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;gBAQlB,QAAQ,EAAE,YAAY,EACtB,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,MAAM,IAAI;IAUjB,QAAQ,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAmBvC,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IAI/B,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAyB9C,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB3B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAoC/B;AAED,0EAA0E;AAC1E,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAahE;AAED,gGAAgG;AAChG,eAAO,MAAM,0BAA0B,kCAAsB,CAAC"}

package/dist/lib/electronMock.js

@@ -0,0 +1,96 @@
+import { CraftdriverError, ErrorCode } from './errors.js';
+/** Symbol under which every active mock's state lives in the main process. */
+const REGISTRY_SYMBOL_KEY = 'craftdriver.electron.apiMocks';
+/** Internal implementation; users receive the public {@link ElectronMock} interface. */
+export class ElectronMockHandle {
+    api;
+    fn;
+    #key;
+    #id;
+    #executor;
+    #onRestore;
+    #restored = false;
+    constructor(executor, api, fn, id, onRestore) {
+        this.#executor = executor;
+        this.api = api;
+        this.fn = fn;
+        this.#key = `${api}.${fn}`;
+        this.#id = id;
+        this.#onRestore = onRestore;
+    }
+    async getCalls() {
+        this.#assertActive();
+        return this.#executor.executeMain((_electron, registryKey, entryKey, id) => {
+            const key = Symbol.for(registryKey);
+            const registry = globalThis[key];
+            const entry = registry?.[entryKey];
+            if (!entry || entry.id !== id)
+                throw new Error(`Mock ${entryKey} is no longer active.`);
+            return entry.calls;
+        }, REGISTRY_SYMBOL_KEY, this.#key, this.#id);
+    }
+    async getCallCount() {
+        return (await this.getCalls()).length;
+    }
+    async mockReturnValue(value) {
+        this.#assertActive();
+        // `value` rides across the wire as an executeMain arg (validated JSON-safe there).
+        // `undefined` can't cross that validation, so carry a presence flag and let the
+        // callback restore undefined — makes mockReturnValue(undefined) work too.
+        const hasValue = value !== undefined;
+        await this.#executor.executeMain((_electron, registryKey, entryKey, id, present, next) => {
+            const key = Symbol.for(registryKey);
+            const registry = globalThis[key];
+            const entry = registry?.[entryKey];
+            if (!entry || entry.id !== id)
+                throw new Error(`Mock ${entryKey} is no longer active.`);
+            entry.result = present ? next : undefined;
+        }, REGISTRY_SYMBOL_KEY, this.#key, this.#id, hasValue, hasValue ? value : null);
+    }
+    async clearCalls() {
+        this.#assertActive();
+        await this.#executor.executeMain((_electron, registryKey, entryKey, id) => {
+            const key = Symbol.for(registryKey);
+            const registry = globalThis[key];
+            const entry = registry?.[entryKey];
+            if (!entry || entry.id !== id)
+                throw new Error(`Mock ${entryKey} is no longer active.`);
+            entry.calls.length = 0;
+        }, REGISTRY_SYMBOL_KEY, this.#key, this.#id);
+    }
+    async restore() {
+        if (this.#restored)
+            return;
+        await this.#executor.executeMain((electron, registryKey, apiName, funcName, id) => {
+            const entryKey = `${apiName}.${funcName}`;
+            const key = Symbol.for(registryKey);
+            const registry = globalThis[key];
+            const entry = registry?.[entryKey];
+            if (!entry || entry.id !== id)
+                return;
+            const api = electron[apiName];
+            if (api && api[funcName] === entry.replacement)
+                api[funcName] = entry.original;
+            delete registry[entryKey];
+        }, REGISTRY_SYMBOL_KEY, this.api, this.fn, this.#id);
+        this.#restored = true;
+        this.#onRestore();
+    }
+    #assertActive() {
+        if (this.#restored) {
+            throw new CraftdriverError(ErrorCode.STATE_INVALID, `The electron.${this.#key} mock has already been restored.`);
+        }
+    }
+}
+/** Reject obviously wrong `api`/`fn` before touching the main process. */
+export function validateMockTarget(api, fn) {
+    if (typeof api !== 'string' || api.length === 0) {
+        throw new CraftdriverError(ErrorCode.INVALID_ARGUMENT, 'electron.mock(api, fn): api must be a non-empty string (e.g. "app", "shell", "dialog").');
+    }
+    if (typeof fn !== 'string' || fn.length === 0) {
+        throw new CraftdriverError(ErrorCode.INVALID_ARGUMENT, `electron.mock('${api}', fn): fn must be a non-empty string (e.g. "getPath", "openExternal").`);
+    }
+}
+/** The `Symbol.for` key string, exported so {@link ElectronRemote} can install the registry. */
+export const ELECTRON_MOCK_REGISTRY_KEY = REGISTRY_SYMBOL_KEY;
+//# sourceMappingURL=electronMock.js.map

package/dist/lib/electronMock.js.map

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

package/dist/lib/electronRemote.d.ts

@@ -0,0 +1,106 @@
+import { ElectronMainLogMonitor } from './electronMainLogs.js';
+import { type ElectronDialogMock, type ElectronMessageBoxResult, type ElectronOpenDialogResult, type ElectronSaveDialogResult } from './electronDialogMock.js';
+import { type ElectronMock } from './electronMock.js';
+export interface ElectronMainConnectInfo {
+    host: string;
+    port: number;
+}
+/** Extra context ElectronRemote needs beyond the inspector endpoint. */
+export interface ElectronRemoteOptions {
+    /** The launched app's executable path — required to route deep links on Windows. */
+    appBinaryPath?: string;
+}
+/** A function evaluated in the Electron main process; receives the `electron` module. */
+export type MainProcessCallback<T> = (electron: unknown, ...args: unknown[]) => T | Promise<T>;
+/**
+ * Run code in the Electron main process via `browser.electron.executeMain`.
+ * Named `executeMain` (not WDIO's `execute`) so the process boundary is loud:
+ * `browser.evaluate()` is the renderer, `executeMain()` the main process.
+ */
+export declare class ElectronRemote {
+    #private;
+    /** `connect` is undefined for non-Electron sessions or when `mainProcess` wasn't enabled. */
+    constructor(connect?: ElectronMainConnectInfo, options?: ElectronRemoteOptions);
+    /**
+     * Captured **main-process** console output and errors — the main-process
+     * counterpart to `browser.logs`. Populated from launch when the session was
+     * started with `electron: { mainProcess: true }` (empty otherwise). See
+     * {@link ElectronMainLogMonitor}.
+     *
+     * ```ts
+     * await browser.electron.executeMain((electron) => console.log('ready', electron.app.getName()));
+     * const [entry] = browser.electron.mainLogs.getLogs();
+     * ```
+     */
+    get mainLogs(): ElectronMainLogMonitor;
+    /**
+     * Open the main-process bridge now (rather than lazily on first `executeMain`)
+     * so `mainLogs` captures from launch. No-op without a main-process inspector;
+     * best-effort — the caller (Browser.launch) swallows failures so a disabled
+     * inspector fuse never breaks renderer automation.
+     */
+    connect(): Promise<void>;
+    /**
+     * Run `fn` in the Electron **main process**. `fn` receives the `electron`
+     * module first, then your `args` (which must be JSON-serializable). The return
+     * value is passed back by value, so it must be JSON-serializable too.
+     *
+     * ```ts
+     * const version = await browser.electron.executeMain(
+     *   (electron) => electron.app.getVersion(),
+     * );
+     * ```
+     */
+    executeMain<T = unknown>(fn: MainProcessCallback<T>, ...args: unknown[]): Promise<T>;
+    /**
+     * Replace any `electron.<api>.<fn>` **main-process** method with a scripted
+     * return value and call recorder. The general primitive behind the typed
+     * {@link mockDialog} convenience — reach for it for `shell.openExternal`,
+     * `app.getPath`, `safeStorage.encryptString`, and other Electron APIs.
+     *
+     * The app is not modified: the replacement lives in its main process for this
+     * session and is restored by `mock.restore()` or `browser.quit()`. The scripted
+     * value is returned **as-is** (not wrapped in a Promise), so it works for both
+     * synchronous methods and `await`ed asynchronous ones. Provide the resolved
+     * value for an async method; recorded call args and the return value must be
+     * JSON-serializable.
+     *
+     * ```ts
+     * const openExternal = await browser.electron.mock('shell', 'openExternal', true);
+     * await browser.click(By.testId('open-docs'));
+     * expect(await openExternal.getCalls()).toEqual([{ args: ['https://example.com/docs'] }]);
+     * ```
+     */
+    mock(api: string, fn: string, returnValue?: unknown): Promise<ElectronMock>;
+    /**
+     * Open a custom-protocol **deep link** (`myapp://…`) against the running app,
+     * exactly as the OS would when another app or the browser hands off the URL —
+     * so your app's real `open-url` (macOS) / `second-instance` (Windows, Linux)
+     * handler runs. Fire-and-forget: it resolves once the OS launcher is spawned;
+     * assert the effect through your app afterwards (e.g. `waitForLog`, a renderer
+     * assertion, or `executeMain`).
+     *
+     * Your app must register the protocol (`app.setAsDefaultProtocolClient(...)`)
+     * and take the single-instance lock. On Windows and Linux a raw deep link would
+     * spawn a *second* instance; craftdriver appends the running app's user-data dir
+     * as a `userData` query parameter so the second instance can route the URL to
+     * the test instance (auto-detected via the main process when available).
+     *
+     * ```ts
+     * await browser.electron.triggerDeeplink('myapp://open?file=test.txt');
+     * const entry = await browser.electron.mainLogs.waitForLog((l) => l.text.includes('open-url'));
+     * ```
+     */
+    triggerDeeplink(url: string): Promise<void>;
+    /**
+     * Replace an asynchronous native Electron dialog with a deterministic result.
+     * The app is not modified: the replacement lives in its main process for this
+     * session and is restored by `mock.restore()` or `browser.quit()`.
+     */
+    mockDialog(method: 'showOpenDialog', result: ElectronOpenDialogResult): Promise<ElectronDialogMock>;
+    mockDialog(method: 'showSaveDialog', result: ElectronSaveDialogResult): Promise<ElectronDialogMock>;
+    mockDialog(method: 'showMessageBox', result: ElectronMessageBoxResult): Promise<ElectronDialogMock>;
+    /** Close the underlying inspector connection. Called from `Browser.quit()`. */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=electronRemote.d.ts.map

package/dist/lib/electronRemote.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"electronRemote.d.ts","sourceRoot":"","sources":["../../src/lib/electronRemote.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,sBAAsB,EAGvB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAEL,KAAK,kBAAkB,EAEvB,KAAK,wBAAwB,EAC7B,KAAK,wBAAwB,EAC7B,KAAK,wBAAwB,EAE9B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAEL,KAAK,YAAY,EAElB,MAAM,mBAAmB,CAAC;AAS3B,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wEAAwE;AACxE,MAAM,WAAW,qBAAqB;IACpC,oFAAoF;IACpF,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,yFAAyF;AACzF,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AA8D/F;;;;GAIG;AACH,qBAAa,cAAc;;IASzB,6FAA6F;gBACjF,OAAO,CAAC,EAAE,uBAAuB,EAAE,OAAO,CAAC,EAAE,qBAAqB;IAK9E;;;;;;;;;;OAUG;IACH,IAAI,QAAQ,IAAI,sBAAsB,CAErC;IAED;;;;;OAKG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAK9B;;;;;;;;;;OAUG;IACG,WAAW,CAAC,CAAC,GAAG,OAAO,EAAE,EAAE,EAAE,mBAAmB,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC;IA2B1F;;;;;;;;;;;;;;;;;;OAkBG;IACG,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC;IA6FjF;;;;;;;;;;;;;;;;;;OAkBG;IACG,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BjD;;;;OAIG;IACG,UAAU,CACd,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,wBAAwB,GAC/B,OAAO,CAAC,kBAAkB,CAAC;IACxB,UAAU,CACd,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,wBAAwB,GAC/B,OAAO,CAAC,kBAAkB,CAAC;IACxB,UAAU,CACd,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,wBAAwB,GAC/B,OAAO,CAAC,kBAAkB,CAAC;IA6J9B,+EAA+E;IACzE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAU7B"}