@portel/photon-core 2.11.0 → 2.13.0

package/dist/photon-loader-lite.js

@@ -0,0 +1,436 @@
+/**
+ * Photon Loader Lite — Direct TypeScript API
+ *
+ * Load a .photon.ts file and get a fully-enhanced instance with all
+ * runtime features: middleware, memory, scheduling, events, __meta.
+ *
+ * @example
+ * ```typescript
+ * import { photon } from '@portel/photon-core';
+ *
+ * const todo = await photon('./todo.photon.ts');
+ * await todo.add({ title: 'Buy milk' });
+ * // ✅ @cached, @throttled, @retry all work
+ * // ✅ this.memory, this.schedule work
+ * // ✅ @stateful events emitted, __meta attached
+ * // ✅ @photon dependencies recursively loaded
+ * ```
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { pathToFileURL } from 'url';
+import { compilePhotonTS } from './compiler.js';
+import { findPhotonClass } from './class-detection.js';
+import { SchemaExtractor } from './schema-extractor.js';
+import { buildMiddlewareChain, builtinRegistry, MiddlewareRegistry, } from './middleware.js';
+import { withPhotonCapabilities } from './mixins.js';
+import { toEnvVarName, parseEnvValue } from './env-utils.js';
+// ═══════════════════════════════════════════════════════════════════
+// Loading state (cycle detection, caching)
+// ═══════════════════════════════════════════════════════════════════
+/** Currently-loading photon paths for cycle detection */
+const loadingPaths = new Set();
+/** Cache of loaded photon instances (keyed by absolutePath::instanceName) */
+const instanceCache = new Map();
+/** Dedup concurrent loads */
+const loadPromises = new Map();
+// ═══════════════════════════════════════════════════════════════════
+// Main API
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * Load a .photon.ts file and return a fully-enhanced instance.
+ *
+ * The returned object has all methods working with middleware (@cached, @retry, etc.),
+ * memory, scheduling, @stateful event emission, and cross-photon calls.
+ *
+ * @param filePath Path to the .photon.ts file (absolute or relative to cwd)
+ * @param options Optional configuration
+ * @returns Enhanced photon instance with all runtime features
+ */
+export async function photon(filePath, options = {}) {
+    // Resolve to absolute path
+    const absolutePath = path.isAbsolute(filePath)
+        ? filePath
+        : path.resolve(process.cwd(), filePath);
+    const instanceName = options.instanceName || '';
+    const cacheKey = instanceName ? `${absolutePath}::${instanceName}` : absolutePath;
+    // Cycle detection (must come before dedup check to avoid deadlock)
+    if (loadingPaths.has(absolutePath)) {
+        const chain = Array.from(loadingPaths).concat(absolutePath).join(' → ');
+        throw new Error(`Circular @photon dependency: ${chain}`);
+    }
+    // Return cached instance
+    if (instanceCache.has(cacheKey)) {
+        return instanceCache.get(cacheKey);
+    }
+    // Dedup concurrent loads
+    if (loadPromises.has(cacheKey)) {
+        return loadPromises.get(cacheKey);
+    }
+    const promise = loadPhotonInternal(absolutePath, cacheKey, options);
+    loadPromises.set(cacheKey, promise);
+    try {
+        const result = await promise;
+        instanceCache.set(cacheKey, result);
+        return result;
+    }
+    finally {
+        loadPromises.delete(cacheKey);
+    }
+}
+/**
+ * Clear the photon instance cache. Useful for testing.
+ */
+export function clearPhotonCache() {
+    instanceCache.clear();
+}
+// ═══════════════════════════════════════════════════════════════════
+// Internal pipeline
+// ═══════════════════════════════════════════════════════════════════
+async function loadPhotonInternal(absolutePath, cacheKey, options) {
+    loadingPaths.add(absolutePath);
+    try {
+        // 1. Read source
+        const source = await fs.readFile(absolutePath, 'utf-8');
+        // 2. Compile TypeScript → JavaScript
+        const homeDir = process.env.HOME || process.env.USERPROFILE || '';
+        const cacheDir = path.join(homeDir, '.photon', 'cache');
+        const compiledPath = await compilePhotonTS(absolutePath, { cacheDir });
+        // 3. Import compiled module
+        const moduleUrl = pathToFileURL(compiledPath).href;
+        const module = await import(moduleUrl);
+        // 4. Find the Photon class
+        const PhotonClass = findPhotonClass(module);
+        if (!PhotonClass) {
+            throw new Error(`No Photon class found in ${absolutePath}`);
+        }
+        // 5. Derive photon name from file path
+        const photonName = derivePhotonName(absolutePath);
+        // 6. Extract schema for middleware and metadata
+        const extractor = new SchemaExtractor();
+        const metadata = extractor.extractAllFromSource(source);
+        const toolSchemas = metadata.tools;
+        // 7. Resolve constructor injections
+        const injections = extractor.resolveInjections(source, photonName);
+        const constructorArgs = await resolveConstructorArgs(injections, photonName, absolutePath, options);
+        // 8. Enhance class with capabilities (for plain classes)
+        const EnhancedClass = withPhotonCapabilities(PhotonClass);
+        // 9. Instantiate
+        const instance = new EnhancedClass(...constructorArgs);
+        // 10. Set photon identity
+        instance._photonName = photonName;
+        if (options.instanceName) {
+            instance.instanceName = options.instanceName;
+        }
+        if (options.sessionId) {
+            instance._sessionId = options.sessionId;
+        }
+        // 11. Wire reactive collections
+        wireReactiveCollections(instance);
+        // 12. Wrap @stateful methods (event emission + __meta)
+        wrapStatefulMethods(instance, source, options.onEvent);
+        // 13. Inject MCP factory if provided
+        if (options.mcpFactory && typeof instance.setMCPFactory === 'function') {
+            instance.setMCPFactory(options.mcpFactory);
+        }
+        // 14. Inject cross-photon call handler (in-process resolution)
+        instance._callHandler = async (targetPhotonName, method, params) => {
+            const targetPath = resolvePhotonPath(targetPhotonName, absolutePath);
+            const target = await photon(targetPath, {
+                baseDir: options.baseDir,
+                mcpFactory: options.mcpFactory,
+                sessionId: options.sessionId,
+            });
+            return target[method](params);
+        };
+        // 15. Call onInitialize lifecycle hook
+        if (typeof instance.onInitialize === 'function') {
+            await instance.onInitialize();
+        }
+        // 16. Build middleware proxy
+        const proxy = buildMiddlewareProxy(instance, photonName, toolSchemas, options);
+        return proxy;
+    }
+    finally {
+        loadingPaths.delete(absolutePath);
+    }
+}
+// ═══════════════════════════════════════════════════════════════════
+// Constructor injection
+// ═══════════════════════════════════════════════════════════════════
+async function resolveConstructorArgs(injections, photonName, currentPath, options) {
+    const values = [];
+    const missing = [];
+    for (const injection of injections) {
+        const { param, injectionType } = injection;
+        switch (injectionType) {
+            case 'photon': {
+                // Recursive photon loading
+                const dep = injection.photonDependency;
+                const depPath = resolvePhotonDepPath(dep.source, dep.sourceType, currentPath);
+                const depInstance = await photon(depPath, {
+                    baseDir: options.baseDir,
+                    mcpFactory: options.mcpFactory,
+                    instanceName: dep.instanceName,
+                    sessionId: options.sessionId,
+                });
+                values.push(depInstance);
+                break;
+            }
+            case 'mcp': {
+                // MCP dependencies require a factory
+                if (!options.mcpFactory) {
+                    throw new Error(`Photon "${photonName}" requires MCP dependency "${param.name}" but no mcpFactory was provided. ` +
+                        `Pass { mcpFactory } in the options to photon().`);
+                }
+                // Will be resolved by the instance's mcp() method at call time
+                values.push(undefined);
+                break;
+            }
+            case 'env': {
+                const envVarName = injection.envVarName || toEnvVarName(photonName, param.name);
+                const envValue = process.env[envVarName];
+                if (envValue !== undefined) {
+                    values.push(parseEnvValue(envValue, param.type));
+                }
+                else if (param.hasDefault || param.isOptional) {
+                    values.push(undefined);
+                }
+                else {
+                    missing.push({ paramName: param.name, envVarName, type: param.type });
+                    values.push(undefined);
+                }
+                break;
+            }
+            case 'state': {
+                // State injection — use default value (state is loaded by the class itself)
+                values.push(undefined);
+                break;
+            }
+            default:
+                values.push(undefined);
+        }
+    }
+    if (missing.length > 0) {
+        const envList = missing.map(m => `  ${m.envVarName} (${m.paramName}: ${m.type})`).join('\n');
+        console.warn(`⚠️  ${photonName}: Missing environment variables:\n${envList}\n` +
+            `Some methods may fail until these are set.`);
+    }
+    return values;
+}
+// ═══════════════════════════════════════════════════════════════════
+// Reactive collection wiring
+// ═══════════════════════════════════════════════════════════════════
+function wireReactiveCollections(instance) {
+    const emit = typeof instance.emit === 'function'
+        ? instance.emit.bind(instance)
+        : null;
+    if (!emit)
+        return;
+    for (const key of Object.keys(instance)) {
+        const value = instance[key];
+        if (!value || typeof value !== 'object')
+            continue;
+        const ctorName = value.constructor?.name;
+        if (ctorName === 'ReactiveArray' ||
+            ctorName === 'ReactiveMap' ||
+            ctorName === 'ReactiveSet' ||
+            ctorName === 'Collection') {
+            value._propertyName = key;
+            value._emitter = emit;
+        }
+    }
+}
+// ═══════════════════════════════════════════════════════════════════
+// @stateful method wrapping
+// ═══════════════════════════════════════════════════════════════════
+function wrapStatefulMethods(instance, source, onEvent) {
+    if (!/@stateful\b/i.test(source))
+        return;
+    // Skip framework-injected methods from withPhotonCapabilities
+    const frameworkMethods = new Set([
+        'emit', 'call', 'mcp', 'setMCPFactory', 'onInitialize', 'onShutdown',
+    ]);
+    // Walk the prototype chain to find all public methods
+    // (withPhotonCapabilities creates a subclass, so methods may be on grandparent prototype)
+    const methodNames = [];
+    const seen = new Set();
+    let proto = Object.getPrototypeOf(instance);
+    while (proto && proto !== Object.prototype) {
+        for (const name of Object.getOwnPropertyNames(proto)) {
+            if (seen.has(name) || name === 'constructor' || name.startsWith('_'))
+                continue;
+            if (frameworkMethods.has(name))
+                continue;
+            seen.add(name);
+            const descriptor = Object.getOwnPropertyDescriptor(proto, name);
+            if (descriptor && typeof descriptor.value === 'function') {
+                methodNames.push(name);
+            }
+        }
+        proto = Object.getPrototypeOf(proto);
+    }
+    if (methodNames.length === 0)
+        return;
+    for (const methodName of methodNames) {
+        const original = instance[methodName];
+        if (typeof original !== 'function')
+            continue;
+        instance[methodName] = function (...args) {
+            const paramNames = extractParamNames(original);
+            const params = Object.fromEntries(paramNames.map((name, i) => [name, args[i]]));
+            const result = original.apply(this, args);
+            // Handle both sync and async results
+            const attachMeta = (res) => {
+                if (res && typeof res === 'object' && !Array.isArray(res) && !res.__meta) {
+                    const timestamp = new Date().toISOString();
+                    Object.defineProperty(res, '__meta', {
+                        value: {
+                            createdAt: timestamp,
+                            createdBy: methodName,
+                            modifiedAt: null,
+                            modifiedBy: null,
+                            modifications: [],
+                        },
+                        enumerable: false,
+                        writable: true,
+                        configurable: true,
+                    });
+                }
+                // Emit event
+                if (onEvent) {
+                    const event = {
+                        method: methodName,
+                        params,
+                        result: res,
+                        timestamp: new Date().toISOString(),
+                    };
+                    if (this.instanceName) {
+                        event.instance = this.instanceName;
+                    }
+                    onEvent(event);
+                }
+                return res;
+            };
+            // Support async methods (most common case)
+            if (result && typeof result.then === 'function') {
+                return result.then(attachMeta);
+            }
+            return attachMeta(result);
+        };
+    }
+}
+/**
+ * Extract parameter names from a function signature string
+ */
+function extractParamNames(fn) {
+    const fnStr = fn.toString();
+    const match = fnStr.match(/\(([^)]*)\)/);
+    if (!match?.[1])
+        return [];
+    return match[1]
+        .split(',')
+        .map(param => {
+        const cleaned = param
+            .trim()
+            .split('=')[0] // Remove default value
+            .split(':')[0] // Remove type annotations
+            .trim();
+        return cleaned;
+    })
+        .filter(name => name && name !== 'this');
+}
+// ═══════════════════════════════════════════════════════════════════
+// Middleware proxy
+// ═══════════════════════════════════════════════════════════════════
+function buildMiddlewareProxy(instance, photonName, toolSchemas, options) {
+    // Build tool lookup: method name → schema
+    const toolMap = new Map();
+    for (const schema of toolSchemas) {
+        toolMap.set(schema.name, schema);
+    }
+    // Middleware state stores (shared across calls)
+    const stateStores = new Map();
+    // Build combined registry (builtins only for now; custom middleware can be added later)
+    const registry = new MiddlewareRegistry();
+    for (const name of builtinRegistry.names()) {
+        registry.register(builtinRegistry.get(name));
+    }
+    return new Proxy(instance, {
+        get(target, prop, receiver) {
+            const value = Reflect.get(target, prop, receiver);
+            if (typeof value !== 'function')
+                return value;
+            if (typeof prop !== 'string')
+                return value;
+            // Skip internal/private methods
+            if (prop.startsWith('_') || prop === 'constructor') {
+                return value.bind(target);
+            }
+            const schema = toolMap.get(prop);
+            const declarations = schema?.middleware || [];
+            // No middleware — return bound method directly
+            if (declarations.length === 0) {
+                return value.bind(target);
+            }
+            // Return a function that applies middleware on each call
+            return (...args) => {
+                const ctx = {
+                    photon: photonName,
+                    tool: prop,
+                    instance: options.instanceName || 'default',
+                    params: args[0] ?? {},
+                };
+                const execute = () => value.apply(target, args);
+                const chain = buildMiddlewareChain(execute, declarations, registry, stateStores, ctx);
+                return chain();
+            };
+        },
+    });
+}
+// ═══════════════════════════════════════════════════════════════════
+// Path utilities
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * Derive a photon name from a file path.
+ * e.g., '/path/to/todo.photon.ts' → 'todo'
+ */
+function derivePhotonName(filePath) {
+    const basename = path.basename(filePath);
+    return basename
+        .replace(/\.photon\.(ts|js|mjs)$/, '')
+        .replace(/\.(ts|js|mjs)$/, '');
+}
+/**
+ * Resolve a photon dependency source to an absolute path.
+ */
+function resolvePhotonDepPath(source, sourceType, currentPhotonPath) {
+    if (sourceType === 'local') {
+        if (source.startsWith('./') || source.startsWith('../')) {
+            return path.resolve(path.dirname(currentPhotonPath), source);
+        }
+        return source;
+    }
+    // For marketplace photons, look in ~/.photon/photons/<name>/
+    if (sourceType === 'marketplace') {
+        const homeDir = process.env.HOME || process.env.USERPROFILE || '';
+        return path.join(homeDir, '.photon', 'photons', source, `${source}.photon.ts`);
+    }
+    // npm and github sources — for now, throw a helpful error
+    throw new Error(`Cannot resolve ${sourceType} photon dependency "${source}" in lite loader. ` +
+        `Only local paths and marketplace photons are supported. ` +
+        `Use the full runtime for npm/github dependencies.`);
+}
+/**
+ * Resolve a photon name to a path for cross-photon calls.
+ * Searches: sibling files, then ~/.photon/photons/
+ */
+function resolvePhotonPath(photonName, callerPath) {
+    // Try sibling file first
+    const dir = path.dirname(callerPath);
+    const siblingPath = path.join(dir, `${photonName}.photon.ts`);
+    // We can't do sync fs.existsSync in an async context cleanly,
+    // so just return the sibling path — the load will fail with a clear error if not found
+    return siblingPath;
+}
+//# sourceMappingURL=photon-loader-lite.js.map

package/dist/photon-loader-lite.js.map

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

package/dist/schedule.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Runtime Scheduling System
+ *
+ * Programmatic scheduling for photons — create, pause, resume, and cancel
+ * scheduled tasks at runtime. Available as `this.schedule` on Photon.
+ *
+ * Complements static `@scheduled`/`@cron` JSDoc tags with dynamic scheduling.
+ * Schedules persist to disk; the daemon reads and executes them.
+ *
+ * Storage: ~/.photon/schedules/{photonId}/{taskId}.json
+ *
+ * @example
+ * ```typescript
+ * export default class Cleanup extends Photon {
+ *   async setup() {
+ *     await this.schedule.create({
+ *       name: 'nightly-cleanup',
+ *       schedule: '0 0 * * *',
+ *       method: 'purge',
+ *       params: { olderThan: 30 },
+ *     });
+ *   }
+ *
+ *   async purge({ olderThan }: { olderThan: number }) {
+ *     // ... cleanup logic
+ *   }
+ * }
+ * ```
+ */
+export type ScheduleStatus = 'active' | 'paused' | 'completed' | 'error';
+export interface ScheduledTask {
+    /** Unique task ID */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Optional description */
+    description?: string;
+    /** Cron expression (5-field: minute hour day month weekday) */
+    cron: string;
+    /** Method name on this photon to call */
+    method: string;
+    /** Parameters to pass to the method */
+    params: Record<string, any>;
+    /** Execute once then mark completed */
+    fireOnce: boolean;
+    /** Maximum number of executions (0 = unlimited) */
+    maxExecutions: number;
+    /** Current status */
+    status: ScheduleStatus;
+    /** ISO timestamp of creation */
+    createdAt: string;
+    /** ISO timestamp of last execution */
+    lastExecutionAt?: string;
+    /** Total execution count */
+    executionCount: number;
+    /** Error message if status is 'error' */
+    errorMessage?: string;
+    /** Photon that owns this task */
+    photonId: string;
+}
+export interface CreateScheduleOptions {
+    /** Human-readable name (must be unique per photon) */
+    name: string;
+    /** Cron expression (5-field) or shorthand: '@hourly', '@daily', '@weekly', '@monthly' */
+    schedule: string;
+    /** Method name on this photon to invoke */
+    method: string;
+    /** Parameters to pass to the method */
+    params?: Record<string, any>;
+    /** Optional description */
+    description?: string;
+    /** Execute once then auto-complete (default: false) */
+    fireOnce?: boolean;
+    /** Maximum executions before auto-complete (0 = unlimited, default: 0) */
+    maxExecutions?: number;
+}
+export interface UpdateScheduleOptions {
+    /** New cron schedule */
+    schedule?: string;
+    /** New method name */
+    method?: string;
+    /** New parameters */
+    params?: Record<string, any>;
+    /** New description */
+    description?: string;
+    /** Update fire-once flag */
+    fireOnce?: boolean;
+    /** Update max executions */
+    maxExecutions?: number;
+}
+/**
+ * Runtime Schedule Provider
+ *
+ * Provides CRUD operations for scheduled tasks.
+ * Tasks are persisted as JSON files that the daemon watches and executes.
+ */
+export declare class ScheduleProvider {
+    private _photonId;
+    constructor(photonId: string);
+    /**
+     * Create a new scheduled task
+     *
+     * @example
+     * ```typescript
+     * await this.schedule.create({
+     *   name: 'daily-report',
+     *   schedule: '0 9 * * *',
+     *   method: 'generate',
+     *   params: { format: 'pdf' },
+     * });
+     * ```
+     */
+    create(options: CreateScheduleOptions): Promise<ScheduledTask>;
+    /**
+     * Get a scheduled task by ID
+     */
+    get(taskId: string): Promise<ScheduledTask | null>;
+    /**
+     * Get a scheduled task by name
+     */
+    getByName(name: string): Promise<ScheduledTask | null>;
+    /**
+     * List all scheduled tasks, optionally filtered by status
+     */
+    list(status?: ScheduleStatus): Promise<ScheduledTask[]>;
+    /**
+     * Update an existing scheduled task
+     */
+    update(taskId: string, updates: UpdateScheduleOptions): Promise<ScheduledTask>;
+    /**
+     * Pause a scheduled task (stops execution until resumed)
+     */
+    pause(taskId: string): Promise<ScheduledTask>;
+    /**
+     * Resume a paused scheduled task
+     */
+    resume(taskId: string): Promise<ScheduledTask>;
+    /**
+     * Cancel (delete) a scheduled task
+     */
+    cancel(taskId: string): Promise<boolean>;
+    /**
+     * Cancel a scheduled task by name
+     */
+    cancelByName(name: string): Promise<boolean>;
+    /**
+     * Check if a schedule with the given name exists
+     */
+    has(name: string): Promise<boolean>;
+    /**
+     * Cancel all scheduled tasks for this photon
+     */
+    cancelAll(): Promise<number>;
+    /** @internal */
+    private _save;
+}
+//# sourceMappingURL=schedule.d.ts.map

package/dist/schedule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule.d.ts","sourceRoot":"","sources":["../src/schedule.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AASH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,GAAG,WAAW,GAAG,OAAO,CAAC;AAEzE,MAAM,WAAW,aAAa;IAC5B,qBAAqB;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,2BAA2B;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5B,uCAAuC;IACvC,QAAQ,EAAE,OAAO,CAAC;IAClB,mDAAmD;IACnD,aAAa,EAAE,MAAM,CAAC;IACtB,qBAAqB;IACrB,MAAM,EAAE,cAAc,CAAC;IACvB,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,4BAA4B;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,yCAAyC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,yFAAyF;IACzF,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC7B,2BAA2B;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,0EAA0E;IAC1E,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,wBAAwB;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sBAAsB;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC7B,sBAAsB;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4BAA4B;IAC5B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,4BAA4B;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA6DD;;;;;GAKG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,SAAS,CAAS;gBAEd,QAAQ,EAAE,MAAM;IAI5B;;;;;;;;;;;;OAYG;IACG,MAAM,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,aAAa,CAAC;IA4BpE;;OAEG;IACG,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAUxD;;OAEG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAK5D;;OAEG;IACG,IAAI,CAAC,MAAM,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IA2B7D;;OAEG;IACG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,aAAa,CAAC;IAmBpF;;OAEG;IACG,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAWnD;;OAEG;IACG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAWpD;;OAEG;IACG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAU9C;;OAEG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAMlD;;OAEG;IACG,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKzC;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC;IASlC,gBAAgB;YACF,KAAK;CAKpB"}