nodepyx 1.0.0

package/dist/index.js

@@ -0,0 +1,393 @@
+"use strict";
+/**
+ * nodepyx — Main Entry Point
+ *
+ * Run Python libraries from Node.js as if they were Native.
+ * Embeds CPython in-process via N-API addon with full TypeScript types,
+ * Proxy-based API, async/await support, and Next.js integration.
+ *
+ * @example
+ * ```typescript
+ * import { init, py } from 'nodepyx';
+ *
+ * await init({
+ *   virtualenv: {
+ *     path: './.venv',
+ *     packages: ['pandas', 'numpy'],
+ *     autoInstall: true,
+ *   },
+ * });
+ *
+ * const pd = await py.import('pandas');
+ * const df = await pd.read_csv('data.csv');
+ * const result = await df.describe().to_dict('records');
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PluginManager = exports.PackageInstaller = exports.CondaManager = exports.VenvManager = exports.PythonDetector = exports.TypeGenerator = exports.isPythonErrorOfType = exports.isPythonError = exports.translatePythonError = exports.nodepyxShutdownError = exports.nodepyxNotInitializedError = exports.PythonTimeoutError = exports.PythonStopIteration = exports.PythonMemoryError = exports.PythonRuntimeError = exports.PythonPermissionError = exports.PythonFileNotFoundError = exports.PythonModuleNotFoundError = exports.PythonImportError = exports.PythonAttributeError = exports.PythonIndexError = exports.PythonKeyError = exports.PythonTypeError = exports.PythonValueError = exports.PythonError = exports.DataFrameBridge = exports.NumpyBridge = exports.Serializer = exports.PyContext = exports.PyIterator = exports.PyCallable = exports.PyModule = exports.PyProxy = exports.PyRuntime = exports.py = void 0;
+exports.init = init;
+exports.shutdown = shutdown;
+exports.isInitialized = isInitialized;
+exports.getRuntime = getRuntime;
+exports.importModule = importModule;
+exports.evalPython = evalPython;
+exports.execPython = execPython;
+exports.runFile = runFile;
+exports.installPackages = installPackages;
+exports.getMemoryStats = getMemoryStats;
+exports.collectGarbage = collectGarbage;
+const PyRuntime_1 = require("./core/PyRuntime");
+const Logger_1 = require("./utils/Logger");
+const ErrorTranslator_1 = require("./utils/ErrorTranslator");
+// ─── Singleton Runtime Management ──────────────────────────────────────────
+let _runtime = null;
+let _initializing = false;
+let _initPromise = null;
+const _logger = new Logger_1.Logger('nodepyx');
+// ─── Main py Object (Proxy over PyRuntime) ─────────────────────────────────
+/**
+ * The main `py` object — a proxy over the PyRuntime singleton.
+ * Provides access to all PyRuntime methods after initialization.
+ *
+ * @throws {nodepyxNotInitializedError} if accessed before calling `init()`
+ */
+exports.py = new Proxy({}, {
+    get(_target, prop) {
+        if (!_runtime) {
+            // Provide helpful error for common misuse
+            if (prop === 'then') {
+                // Prevent silent "awaiting py" mistakes
+                return undefined;
+            }
+            throw new ErrorTranslator_1.nodepyxNotInitializedError(`Cannot access py.${String(prop)} — nodepyx is not initialized. ` +
+                `Call 'await nodepyx.init()' before using 'py'.`);
+        }
+        const value = _runtime[prop];
+        if (typeof value === 'function') {
+            return value.bind(_runtime);
+        }
+        return value;
+    },
+    set(_target, prop, value) {
+        if (!_runtime) {
+            throw new ErrorTranslator_1.nodepyxNotInitializedError('nodepyx is not initialized.');
+        }
+        _runtime[prop] = value;
+        return true;
+    },
+    has(_target, prop) {
+        if (!_runtime) {
+            return false;
+        }
+        return prop in _runtime;
+    },
+});
+// ─── Lifecycle Functions ────────────────────────────────────────────────────
+/**
+ * Initialize the nodepyx runtime.
+ * Must be called before using `py` or any other nodepyx API.
+ *
+ * Calling `init()` multiple times is safe — subsequent calls are no-ops
+ * unless `shutdown()` was called first, or `force: true` is passed.
+ *
+ * @param config - nodepyx configuration options
+ * @param options - Additional initialization options
+ * @returns Promise that resolves when Python is ready
+ *
+ * @example
+ * ```typescript
+ * await init({
+ *   virtualenv: { path: '.venv', packages: ['pandas'], autoInstall: true },
+ *   logLevel: 'info',
+ * });
+ * ```
+ */
+async function init(config, options) {
+    // Already initialized
+    if (_runtime && !options?.force) {
+        _logger.debug('nodepyx already initialized, skipping');
+        return;
+    }
+    // Initialization in progress — wait for it
+    if (_initializing && _initPromise) {
+        return _initPromise;
+    }
+    // Force re-init: shut down first
+    if (_runtime && options?.force) {
+        await shutdown();
+    }
+    _initializing = true;
+    _initPromise = _doInit(config);
+    try {
+        await _initPromise;
+    }
+    finally {
+        _initializing = false;
+        _initPromise = null;
+    }
+}
+async function _doInit(config) {
+    _logger.info('Initializing nodepyx runtime...');
+    const startTime = performance.now();
+    try {
+        _runtime = await PyRuntime_1.PyRuntime.create(config);
+        const elapsed = (performance.now() - startTime).toFixed(0);
+        _logger.success(`nodepyx runtime ready in ${elapsed}ms`);
+    }
+    catch (err) {
+        _runtime = null;
+        _logger.error('Failed to initialize nodepyx runtime', err);
+        throw err;
+    }
+}
+/**
+ * Shut down the nodepyx runtime and release all Python resources.
+ * After calling this, `py` is no longer accessible until `init()` is called again.
+ *
+ * @example
+ * ```typescript
+ * await shutdown();
+ * ```
+ */
+async function shutdown() {
+    if (!_runtime) {
+        _logger.debug('nodepyx not initialized, nothing to shut down');
+        return;
+    }
+    _logger.info('Shutting down nodepyx runtime...');
+    const runtime = _runtime;
+    _runtime = null;
+    try {
+        await runtime.shutdown();
+        _logger.success('nodepyx runtime shut down');
+    }
+    catch (err) {
+        _logger.error('Error during nodepyx shutdown', err);
+        throw err;
+    }
+}
+/**
+ * Check if nodepyx is initialized and ready to use.
+ */
+function isInitialized() {
+    return _runtime !== null && _runtime.isRunning();
+}
+/**
+ * Get the current PyRuntime instance.
+ * @throws {nodepyxNotInitializedError} if not initialized
+ */
+function getRuntime() {
+    if (!_runtime) {
+        throw new ErrorTranslator_1.nodepyxNotInitializedError();
+    }
+    return _runtime;
+}
+// ─── Convenience API ────────────────────────────────────────────────────────
+/**
+ * Import a Python module and return a Proxy.
+ * Shorthand for `py.import(moduleName)`.
+ *
+ * @example
+ * ```typescript
+ * const np = await importModule('numpy');
+ * const arr = await np.array([1, 2, 3]);
+ * ```
+ */
+async function importModule(moduleName) {
+    if (!_runtime) {
+        throw new ErrorTranslator_1.nodepyxNotInitializedError();
+    }
+    return _runtime.import(moduleName);
+}
+/**
+ * Evaluate a Python expression and return the result.
+ * Shorthand for `py.eval(expression)`.
+ *
+ * @example
+ * ```typescript
+ * const result = await evalPython('1 + 2 + 3');
+ * // result === 6
+ * ```
+ */
+async function evalPython(expression) {
+    if (!_runtime) {
+        throw new ErrorTranslator_1.nodepyxNotInitializedError();
+    }
+    return _runtime.eval(expression);
+}
+/**
+ * Execute Python code (statements, not expressions).
+ * Shorthand for `py.exec(code)`.
+ *
+ * @example
+ * ```typescript
+ * await execPython(`
+ *   import sys
+ *   print(f"Python {sys.version}")
+ * `);
+ * ```
+ */
+async function execPython(code) {
+    if (!_runtime) {
+        throw new ErrorTranslator_1.nodepyxNotInitializedError();
+    }
+    return _runtime.exec(code);
+}
+/**
+ * Run a Python script file.
+ */
+async function runFile(filePath) {
+    if (!_runtime) {
+        throw new ErrorTranslator_1.nodepyxNotInitializedError();
+    }
+    return _runtime.runFile(filePath);
+}
+/**
+ * Install Python packages into the configured virtualenv.
+ *
+ * @example
+ * ```typescript
+ * await installPackages(['pandas', 'numpy>=1.24.0', 'scikit-learn']);
+ * ```
+ */
+async function installPackages(packages) {
+    if (!_runtime) {
+        throw new ErrorTranslator_1.nodepyxNotInitializedError();
+    }
+    return _runtime.installPackages(packages);
+}
+/**
+ * Get memory statistics for the Python heap.
+ */
+async function getMemoryStats() {
+    if (!_runtime) {
+        throw new ErrorTranslator_1.nodepyxNotInitializedError();
+    }
+    return _runtime.getMemoryStats();
+}
+/**
+ * Trigger Python garbage collection.
+ */
+async function collectGarbage() {
+    if (!_runtime) {
+        throw new ErrorTranslator_1.nodepyxNotInitializedError();
+    }
+    return _runtime.collectGarbage();
+}
+// ─── Auto-cleanup on process exit ──────────────────────────────────────────
+let _cleanupRegistered = false;
+function _registerCleanup() {
+    if (_cleanupRegistered) {
+        return;
+    }
+    _cleanupRegistered = true;
+    const cleanup = async () => {
+        if (_runtime) {
+            try {
+                await shutdown();
+            }
+            catch {
+                // Ignore errors during cleanup
+            }
+        }
+    };
+    process.on('exit', () => {
+        // Synchronous cleanup on exit (best-effort)
+        if (_runtime) {
+            try {
+                _runtime.shutdownSync();
+            }
+            catch {
+                // ignore
+            }
+        }
+    });
+    process.on('SIGINT', async () => {
+        await cleanup();
+        process.exit(0);
+    });
+    process.on('SIGTERM', async () => {
+        await cleanup();
+        process.exit(0);
+    });
+    process.on('uncaughtException', async (err) => {
+        _logger.error('Uncaught exception, shutting down nodepyx', err);
+        await cleanup();
+        throw err;
+    });
+}
+// Register cleanup automatically
+_registerCleanup();
+// ─── Exports ───────────────────────────────────────────────────────────────
+// Core
+var PyRuntime_2 = require("./core/PyRuntime");
+Object.defineProperty(exports, "PyRuntime", { enumerable: true, get: function () { return PyRuntime_2.PyRuntime; } });
+var PyProxy_1 = require("./core/PyProxy");
+Object.defineProperty(exports, "PyProxy", { enumerable: true, get: function () { return PyProxy_1.PyProxy; } });
+var PyModule_1 = require("./core/PyModule");
+Object.defineProperty(exports, "PyModule", { enumerable: true, get: function () { return PyModule_1.PyModule; } });
+var PyCallable_1 = require("./core/PyCallable");
+Object.defineProperty(exports, "PyCallable", { enumerable: true, get: function () { return PyCallable_1.PyCallable; } });
+var PyIterator_1 = require("./core/PyIterator");
+Object.defineProperty(exports, "PyIterator", { enumerable: true, get: function () { return PyIterator_1.PyIterator; } });
+var PyContext_1 = require("./core/PyContext");
+Object.defineProperty(exports, "PyContext", { enumerable: true, get: function () { return PyContext_1.PyContext; } });
+// Serialization
+var Serializer_1 = require("./serialization/Serializer");
+Object.defineProperty(exports, "Serializer", { enumerable: true, get: function () { return Serializer_1.Serializer; } });
+var NumpyBridge_1 = require("./serialization/NumpyBridge");
+Object.defineProperty(exports, "NumpyBridge", { enumerable: true, get: function () { return NumpyBridge_1.NumpyBridge; } });
+var DataFrameBridge_1 = require("./serialization/DataFrameBridge");
+Object.defineProperty(exports, "DataFrameBridge", { enumerable: true, get: function () { return DataFrameBridge_1.DataFrameBridge; } });
+// Error types
+var ErrorTranslator_2 = require("./utils/ErrorTranslator");
+Object.defineProperty(exports, "PythonError", { enumerable: true, get: function () { return ErrorTranslator_2.PythonError; } });
+Object.defineProperty(exports, "PythonValueError", { enumerable: true, get: function () { return ErrorTranslator_2.PythonValueError; } });
+Object.defineProperty(exports, "PythonTypeError", { enumerable: true, get: function () { return ErrorTranslator_2.PythonTypeError; } });
+Object.defineProperty(exports, "PythonKeyError", { enumerable: true, get: function () { return ErrorTranslator_2.PythonKeyError; } });
+Object.defineProperty(exports, "PythonIndexError", { enumerable: true, get: function () { return ErrorTranslator_2.PythonIndexError; } });
+Object.defineProperty(exports, "PythonAttributeError", { enumerable: true, get: function () { return ErrorTranslator_2.PythonAttributeError; } });
+Object.defineProperty(exports, "PythonImportError", { enumerable: true, get: function () { return ErrorTranslator_2.PythonImportError; } });
+Object.defineProperty(exports, "PythonModuleNotFoundError", { enumerable: true, get: function () { return ErrorTranslator_2.PythonModuleNotFoundError; } });
+Object.defineProperty(exports, "PythonFileNotFoundError", { enumerable: true, get: function () { return ErrorTranslator_2.PythonFileNotFoundError; } });
+Object.defineProperty(exports, "PythonPermissionError", { enumerable: true, get: function () { return ErrorTranslator_2.PythonPermissionError; } });
+Object.defineProperty(exports, "PythonRuntimeError", { enumerable: true, get: function () { return ErrorTranslator_2.PythonRuntimeError; } });
+Object.defineProperty(exports, "PythonMemoryError", { enumerable: true, get: function () { return ErrorTranslator_2.PythonMemoryError; } });
+Object.defineProperty(exports, "PythonStopIteration", { enumerable: true, get: function () { return ErrorTranslator_2.PythonStopIteration; } });
+Object.defineProperty(exports, "PythonTimeoutError", { enumerable: true, get: function () { return ErrorTranslator_2.PythonTimeoutError; } });
+Object.defineProperty(exports, "nodepyxNotInitializedError", { enumerable: true, get: function () { return ErrorTranslator_2.nodepyxNotInitializedError; } });
+Object.defineProperty(exports, "nodepyxShutdownError", { enumerable: true, get: function () { return ErrorTranslator_2.nodepyxShutdownError; } });
+Object.defineProperty(exports, "translatePythonError", { enumerable: true, get: function () { return ErrorTranslator_2.translatePythonError; } });
+Object.defineProperty(exports, "isPythonError", { enumerable: true, get: function () { return ErrorTranslator_2.isPythonError; } });
+Object.defineProperty(exports, "isPythonErrorOfType", { enumerable: true, get: function () { return ErrorTranslator_2.isPythonErrorOfType; } });
+// Type generation
+var TypeGenerator_1 = require("./types/TypeGenerator");
+Object.defineProperty(exports, "TypeGenerator", { enumerable: true, get: function () { return TypeGenerator_1.TypeGenerator; } });
+// Environment management
+var PythonDetector_1 = require("./env/PythonDetector");
+Object.defineProperty(exports, "PythonDetector", { enumerable: true, get: function () { return PythonDetector_1.PythonDetector; } });
+var VenvManager_1 = require("./env/VenvManager");
+Object.defineProperty(exports, "VenvManager", { enumerable: true, get: function () { return VenvManager_1.VenvManager; } });
+var CondaManager_1 = require("./env/CondaManager");
+Object.defineProperty(exports, "CondaManager", { enumerable: true, get: function () { return CondaManager_1.CondaManager; } });
+var PackageInstaller_1 = require("./env/PackageInstaller");
+Object.defineProperty(exports, "PackageInstaller", { enumerable: true, get: function () { return PackageInstaller_1.PackageInstaller; } });
+// Plugins
+var PluginManager_1 = require("./plugins/PluginManager");
+Object.defineProperty(exports, "PluginManager", { enumerable: true, get: function () { return PluginManager_1.PluginManager; } });
+// Default export
+exports.default = {
+    init,
+    shutdown,
+    isInitialized,
+    getRuntime,
+    py: exports.py,
+    import: importModule,
+    eval: evalPython,
+    exec: execPython,
+    runFile,
+    installPackages,
+    getMemoryStats,
+    collectGarbage,
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/plugins/Plugin.interface.d.ts

@@ -0,0 +1,41 @@
+/**
+ * nodepyx — Plugin Interface
+ *
+ * Every nodepyx plugin must implement this interface. Plugins can:
+ *   - Transform Python object values as they cross the JS boundary
+ *   - Register custom type mappings
+ *   - Hook into lifecycle events (init, shutdown)
+ *   - Add convenience methods to PyProxy instances
+ */
+import type { SerializedValue } from '../types/python';
+export type PythonTypeName = string;
+export interface PluginInitContext {
+    runtimeVersion: string;
+    pythonVersion: {
+        major: number;
+        minor: number;
+        patch: number;
+    };
+    registerTypeHandler(typeName: PythonTypeName, handler: TypeTransformHandler): void;
+}
+export type TypeTransformHandler = (raw: SerializedValue, typeHint: string, metadata: Record<string, unknown>) => unknown | null;
+export interface nodepyxPlugin {
+    readonly name: string;
+    readonly version: string;
+    readonly supportedModules: readonly string[];
+    readonly handledTypes?: readonly PythonTypeName[];
+    readonly description?: string;
+    readonly homepage?: string;
+    onInit?(ctx: PluginInitContext): Promise<void> | void;
+    onShutdown?(): Promise<void> | void;
+    onModuleImported?(moduleName: string, moduleOid: number): Promise<void> | void;
+    transformResult?: TypeTransformHandler;
+    serializeValue?(value: unknown, targetTypeName?: string): SerializedValue | null;
+}
+export interface PluginRegistration {
+    plugin: nodepyxPlugin;
+    active: boolean;
+    loadedAt: number;
+    modulesBound: Set<string>;
+}
+//# sourceMappingURL=Plugin.interface.d.ts.map

package/dist/plugins/Plugin.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Plugin.interface.d.ts","sourceRoot":"","sources":["../../src/plugins/Plugin.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAIvD,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC;AAEpC,MAAM,WAAW,iBAAiB;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/D,mBAAmB,CAAC,QAAQ,EAAE,cAAc,EAAE,OAAO,EAAE,oBAAoB,GAAG,IAAI,CAAC;CACpF;AAED,MAAM,MAAM,oBAAoB,GAAG,CACjC,GAAG,EAAO,eAAe,EACzB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC9B,OAAO,GAAG,IAAI,CAAC;AAEpB,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAc,MAAM,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAW,MAAM,CAAC;IAClC,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,QAAQ,CAAC,YAAY,CAAC,EAAK,SAAS,cAAc,EAAE,CAAC;IACrD,QAAQ,CAAC,WAAW,CAAC,EAAM,MAAM,CAAC;IAClC,QAAQ,CAAC,QAAQ,CAAC,EAAS,MAAM,CAAC;IAElC,MAAM,CAAC,CAAC,GAAG,EAAE,iBAAiB,GAAwB,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3E,UAAU,CAAC,IAA2C,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3E,gBAAgB,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAE/E,eAAe,CAAC,EAAE,oBAAoB,CAAC;IACvC,cAAc,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAAC;CAClF;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAQ,aAAa,CAAC;IAC5B,MAAM,EAAQ,OAAO,CAAC;IACtB,QAAQ,EAAM,MAAM,CAAC;IACrB,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC3B"}

package/dist/plugins/Plugin.interface.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * nodepyx — Plugin Interface
+ *
+ * Every nodepyx plugin must implement this interface. Plugins can:
+ *   - Transform Python object values as they cross the JS boundary
+ *   - Register custom type mappings
+ *   - Hook into lifecycle events (init, shutdown)
+ *   - Add convenience methods to PyProxy instances
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=Plugin.interface.js.map

package/dist/plugins/Plugin.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Plugin.interface.js","sourceRoot":"","sources":["../../src/plugins/Plugin.interface.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG"}

package/dist/plugins/PluginManager.d.ts

@@ -0,0 +1,26 @@
+/**
+ * nodepyx — PluginManager
+ *
+ * Manages registration, lifecycle, and dispatch of nodepyx plugins.
+ * PyRuntime holds a single PluginManager instance.
+ */
+import type { nodepyxPlugin, PluginRegistration, PluginInitContext } from './Plugin.interface';
+import type { SerializedValue } from '../types/python';
+export declare class PluginManager {
+    private readonly _plugins;
+    private readonly _typeMap;
+    private readonly _moduleMap;
+    register(plugin: nodepyxPlugin): this;
+    registerBuiltins(): Promise<void>;
+    initAll(ctx: PluginInitContext): Promise<void>;
+    shutdownAll(): Promise<void>;
+    onModuleImported(moduleName: string, moduleOid: number): Promise<void>;
+    transformResult(value: SerializedValue, typeName: string, metadata?: Record<string, unknown>): unknown | null;
+    serializeValue(value: unknown, targetTypeName?: string): SerializedValue | null;
+    get names(): string[];
+    getPlugin(name: string): PluginRegistration | undefined;
+    get active(): PluginRegistration[];
+    get all(): PluginRegistration[];
+    isActive(name: string): boolean;
+}
+//# sourceMappingURL=PluginManager.d.ts.map

package/dist/plugins/PluginManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PluginManager.d.ts","sourceRoot":"","sources":["../../src/plugins/PluginManager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EACV,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EAGlB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAIvD,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2C;IACpE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuD;IAChF,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsC;IAIjE,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;IA+B/B,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAajC,OAAO,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAqB9C,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAY5B,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAa5E,eAAe,CACb,KAAK,EAAK,eAAe,EACzB,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACrC,OAAO,GAAG,IAAI;IAajB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI;IAe/E,IAAI,KAAK,IAAI,MAAM,EAAE,CAAsC;IAC3D,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IACvD,IAAI,MAAM,IAAI,kBAAkB,EAAE,CAAgE;IAClG,IAAI,GAAG,IAAI,kBAAkB,EAAE,CAAwC;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;CAChC"}