wasm-cel 0.2.1 → 0.3.0

package/README.md

@@ -1,7 +1,7 @@
 # wasm-cel
 
 WebAssembly module for evaluating CEL (Common Expression Language) expressions
-in Node.js.
+in Node.js and browsers.
 
 ## Installation
 
@@ -15,8 +15,10 @@ yarn add wasm-cel
 
 ## Usage
 
-The library follows the CEL pattern: create an environment, compile an
-expression, and then evaluate it:
+### Node.js
+
+In Node.js, the library automatically loads the WASM module. Just import and
+use:
 
 ```typescript
 import { Env } from "wasm-cel";
@@ -50,6 +52,118 @@ const result3 = await program2.eval({ name: "Alice", age: 30 });
 console.log(result3); // "Alice is 30 years old"
 ```
 
+### Browser
+
+In browsers, you need to initialize the WASM module first by providing the WASM
+bytes or URL.
+
+#### With Vite (Recommended)
+
+Vite can process and optimize the WASM file automatically:
+
+```typescript
+import { init, Env } from "wasm-cel";
+import wasmUrl from "wasm-cel/main.wasm?url";
+
+// Initialize with Vite-processed WASM URL
+await init(wasmUrl);
+
+// Now use the library normally
+const env = await Env.new({
+  variables: [{ name: "x", type: "int" }],
+});
+
+const program = await env.compile("x + 10");
+const result = await program.eval({ x: 5 });
+console.log(result); // 15
+```
+
+**Loading wasm_exec.js with Vite:**
+
+If you need to load `wasm_exec.js` dynamically (it's usually loaded via script
+tag):
+
+```typescript
+import { init, Env } from "wasm-cel";
+import wasmUrl from "wasm-cel/main.wasm?url";
+import wasmExecUrl from "wasm-cel/wasm_exec.js?url";
+
+// Initialize with both WASM and wasm_exec URLs
+await init(wasmUrl, wasmExecUrl);
+
+// Use the library
+const env = await Env.new({ variables: [{ name: "x", type: "int" }] });
+```
+
+#### Without a Bundler (Native ES Modules)
+
+For native ES modules without a bundler, you can import directly:
+
+```html
+<script type="module">
+  import { init, Env } from "./node_modules/wasm-cel/dist/browser.js";
+
+  // Initialize with WASM URL
+  await init("/path/to/main.wasm");
+
+  // Or load wasm_exec.js first via script tag, then just init with WASM
+  await init("/path/to/main.wasm");
+
+  // Use the library
+  const env = await Env.new({ variables: [{ name: "x", type: "int" }] });
+</script>
+```
+
+**Loading wasm_exec.js:**
+
+You can either:
+
+1. Load it via script tag before initializing:
+
+   ```html
+   <script src="/path/to/wasm_exec.js"></script>
+   <script type="module">
+     import { init, Env } from "./node_modules/wasm-cel/dist/browser.js";
+     await init("/path/to/main.wasm");
+   </script>
+   ```
+
+2. Or pass the URL to `init()`:
+   ```typescript
+   await init("/path/to/main.wasm", "/path/to/wasm_exec.js");
+   ```
+
+#### Other Browser Patterns
+
+```typescript
+import { init, Env } from "wasm-cel";
+
+// Using a URL string
+await init("/path/to/main.wasm");
+
+// Using a URL object
+await init(new URL("/main.wasm", window.location.origin));
+
+// Using direct bytes (Uint8Array)
+const response = await fetch("/main.wasm");
+const bytes = new Uint8Array(await response.arrayBuffer());
+await init(bytes);
+
+// Using Response object
+const response = await fetch("/main.wasm");
+await init(response);
+```
+
+### Available Exports
+
+The package exports the following for direct imports:
+
+- `wasm-cel` - Main entry point (auto-selects Node.js or browser)
+- `wasm-cel/browser` - Browser-specific entry point
+- `wasm-cel/main.wasm` - WASM module file
+- `wasm-cel/wasm_exec.js` - Go WASM runtime (for browsers)
+- `wasm-cel/wasm_exec.cjs` - Go WASM runtime (CommonJS, for Node.js)
+
 ## CEL Environment Options
 
 The library supports configurable CEL environment options to enable additional
@@ -481,10 +595,50 @@ program.destroy();
 await expect(program.eval()).rejects.toThrow();
 ```
 
-### `init(): Promise<void>`
+### `init(wasmBytes?, wasmExecUrl?): Promise<void>`
+
+Initializes the WASM module.
+
+**Node.js:**
 
-Initializes the WASM module. This is called automatically by the API functions,
-but can be called manually to pre-initialize the module.
+- No parameters needed - automatically loads from file system
+- Called automatically by API functions, but can be called manually to
+  pre-initialize
+
+**Browser:**
+
+- **Required**: `wasmBytes` - The WASM module. Can be:
+  - `Uint8Array` - Direct bytes
+  - `string` - URL to fetch the WASM file from (supports Vite-processed URLs)
+  - `URL` - URL object pointing to the WASM file
+  - `Response` - Fetch Response object containing WASM bytes
+  - `Promise<Uint8Array>` - Async import of WASM bytes
+- **Optional**: `wasmExecUrl` - URL to `wasm_exec.js` if it needs to be loaded
+  dynamically
+- Must be called before using the library
+
+**Examples:**
+
+```typescript
+// Node.js - no parameters
+await init();
+
+// Browser - with Vite
+import wasmUrl from "wasm-cel/main.wasm?url";
+await init(wasmUrl);
+
+// Browser - with URL
+await init("/path/to/main.wasm");
+
+// Browser - with wasm_exec.js URL
+await init("/path/to/main.wasm", "/path/to/wasm_exec.js");
+
+// Browser - with direct bytes
+const bytes = new Uint8Array(
+  await fetch("/main.wasm").then((r) => r.arrayBuffer()),
+);
+await init(bytes);
+```
 
 ## Memory Management
 
@@ -629,7 +783,8 @@ pnpm run example
 
 ## Requirements
 
-- Node.js >= 18.0.0
+- **Node.js**: >= 18.0.0
+- **Browsers**: Modern browsers with WebAssembly support (all current browsers)
 
 ## Package Type
 
@@ -638,6 +793,21 @@ resolution. If you're using TypeScript, make sure your `tsconfig.json` has
 `"module": "NodeNext"` or `"moduleResolution": "NodeNext"` for proper type
 resolution.
 
+## Environment Detection
+
+The library automatically detects the environment:
+
+- **With bundlers** (Vite, Webpack, Rollup, etc.): Uses `package.json`
+  conditional exports to select the correct entry point at build time
+- **Native ES modules**: Uses runtime detection to select the appropriate module
+- **Node.js**: Automatically uses the Node.js entry point with file system
+  access
+- **Browsers**: Uses the browser entry point that requires explicit WASM
+  initialization
+
+You don't need to change your import statements - the library handles the
+environment detection automatically.
+
 ## License
 
 MIT

package/dist/browser.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Initialize the WASM module (Browser version - requires WASM bytes)
+ * @param wasmBytes - The WASM module bytes. Can be:
+ *   - Uint8Array: Direct bytes
+ *   - string: URL to fetch the WASM file from (supports Vite-processed URLs)
+ *   - URL: URL object pointing to the WASM file
+ *   - Promise<Uint8Array>: Async import of WASM bytes (for Vite `?init` pattern)
+ *   - Response: Fetch Response object containing WASM bytes
+ * @param wasmExecUrl - Optional URL to wasm_exec.js if it needs to be loaded dynamically
+ * @returns {Promise<void>}
+ *
+ * @example
+ * ```typescript
+ * // With Vite - recommended pattern using ?url query parameter
+ * // Vite will process and optimize the WASM file, returning a URL string
+ * import wasmUrl from 'wasm-cel/main.wasm?url';
+ * await init(wasmUrl);
+ *
+ * // With Vite - alternative: fetch the processed URL
+ * import wasmUrl from 'wasm-cel/main.wasm?url';
+ * const response = await fetch(wasmUrl);
+ * await init(response);
+ *
+ * // Traditional URL (works in any environment)
+ * await init('/path/to/main.wasm');
+ *
+ * // Direct bytes
+ * const bytes = await fetch('/main.wasm').then(r => r.arrayBuffer());
+ * await init(new Uint8Array(bytes));
+ *
+ * // URL object
+ * await init(new URL('/main.wasm', window.location.origin));
+ * ```
+ */
+declare function init(wasmBytes: Uint8Array | string | URL | Promise<Uint8Array> | Response, wasmExecUrl?: string | URL): Promise<void>;
+export { Program, Env } from "./core.js";
+export type { CELType, CELTypeDef, CELListType, CELMapType, CELFunctionDefinition, CELFunctionParam, EnvOptions, VariableDeclaration, TypeCheckResult, CompilationIssue, CompilationResult, } from "./types.js";
+export { listType, mapType, CELFunction } from "./functions.js";
+export { Options } from "./options/index.js";
+export type { EnvOptionConfig, OptionalTypesConfig, ValidationIssue, ValidationContext, ValidatorResult, ASTValidatorFunction, ASTValidatorsConfig, } from "./options/index.js";
+export { init };
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../lib/browser.ts"],"names":[],"mappings":"AA0EA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,iBAAe,IAAI,CACjB,SAAS,EAAE,UAAU,GAAG,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,UAAU,CAAC,GAAG,QAAQ,EACrE,WAAW,CAAC,EAAE,MAAM,GAAG,GAAG,GACzB,OAAO,CAAC,IAAI,CAAC,CAwEf;AAMD,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAGzC,YAAY,EACV,OAAO,EACP,UAAU,EACV,WAAW,EACX,UAAU,EACV,qBAAqB,EACrB,gBAAgB,EAChB,UAAU,EACV,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,YAAY,EACV,eAAe,EACf,mBAAmB,EACnB,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,IAAI,EAAE,CAAC"}

package/dist/browser.js

@@ -0,0 +1,155 @@
+import { setInitFunction } from "./core.js";
+let isInitialized = false;
+let initPromise = null;
+/**
+ * Load wasm_exec.js from a URL (if not already loaded)
+ * @param wasmExecUrl - URL to wasm_exec.js (optional, assumes already loaded if not provided)
+ * @returns Promise that resolves when wasm_exec.js is loaded
+ */
+async function loadWasmExec(wasmExecUrl) {
+    // Check if Go is already available
+    const globalObj = typeof globalThis !== "undefined" ? globalThis : global;
+    if (typeof globalObj.Go !== "undefined") {
+        return; // Already loaded
+    }
+    if (!wasmExecUrl) {
+        throw new Error("Go WASM runtime (wasm_exec.js) not found. Please load it before initializing the WASM module. " +
+            "You can either:\n" +
+            "1. Load it via script tag: <script src='path/to/wasm_exec.js'></script>\n" +
+            "2. Or pass wasmExecUrl to init() to load it dynamically.");
+    }
+    // Load wasm_exec.js dynamically
+    const url = typeof wasmExecUrl === "string" ? wasmExecUrl : wasmExecUrl.href;
+    // Check if we're in an environment with document (browser main thread)
+    if (typeof document === "undefined") {
+        throw new Error("document is not available. In environments like Web Workers, please load wasm_exec.js manually before calling init().");
+    }
+    const script = document.createElement("script");
+    script.src = url;
+    script.type = "text/javascript";
+    return new Promise((resolve, reject) => {
+        script.onload = () => {
+            if (typeof globalObj.Go === "undefined") {
+                reject(new Error("wasm_exec.js loaded but Go class not found. Make sure you're using the correct wasm_exec.js file."));
+            }
+            else {
+                resolve();
+            }
+        };
+        script.onerror = () => {
+            reject(new Error(`Failed to load wasm_exec.js from ${url}. Make sure the URL is correct and accessible.`));
+        };
+        document.head.appendChild(script);
+    });
+}
+/**
+ * Internal init function that core will call
+ */
+async function internalInit() {
+    if (!isInitialized) {
+        throw new Error("WASM module not initialized. In browsers, you must call init(wasmBytes) with the WASM module bytes or URL before using the library.");
+    }
+}
+/**
+ * Initialize the WASM module (Browser version - requires WASM bytes)
+ * @param wasmBytes - The WASM module bytes. Can be:
+ *   - Uint8Array: Direct bytes
+ *   - string: URL to fetch the WASM file from (supports Vite-processed URLs)
+ *   - URL: URL object pointing to the WASM file
+ *   - Promise<Uint8Array>: Async import of WASM bytes (for Vite `?init` pattern)
+ *   - Response: Fetch Response object containing WASM bytes
+ * @param wasmExecUrl - Optional URL to wasm_exec.js if it needs to be loaded dynamically
+ * @returns {Promise<void>}
+ *
+ * @example
+ * ```typescript
+ * // With Vite - recommended pattern using ?url query parameter
+ * // Vite will process and optimize the WASM file, returning a URL string
+ * import wasmUrl from 'wasm-cel/main.wasm?url';
+ * await init(wasmUrl);
+ *
+ * // With Vite - alternative: fetch the processed URL
+ * import wasmUrl from 'wasm-cel/main.wasm?url';
+ * const response = await fetch(wasmUrl);
+ * await init(response);
+ *
+ * // Traditional URL (works in any environment)
+ * await init('/path/to/main.wasm');
+ *
+ * // Direct bytes
+ * const bytes = await fetch('/main.wasm').then(r => r.arrayBuffer());
+ * await init(new Uint8Array(bytes));
+ *
+ * // URL object
+ * await init(new URL('/main.wasm', window.location.origin));
+ * ```
+ */
+async function init(wasmBytes, wasmExecUrl) {
+    if (isInitialized) {
+        return;
+    }
+    if (initPromise) {
+        return initPromise;
+    }
+    initPromise = (async () => {
+        // Load wasm_exec.js if needed
+        await loadWasmExec(wasmExecUrl);
+        // Get the Go class
+        const globalObj = typeof globalThis !== "undefined" ? globalThis : global;
+        if (typeof globalObj.Go === "undefined") {
+            throw new Error("Go WASM runtime not available. Please ensure wasm_exec.js is loaded.");
+        }
+        // Load WASM bytes
+        let wasmBuffer;
+        if (wasmBytes instanceof Uint8Array) {
+            // Direct bytes
+            wasmBuffer = wasmBytes;
+        }
+        else if (wasmBytes instanceof Response) {
+            // Response object
+            const arrayBuffer = await wasmBytes.arrayBuffer();
+            wasmBuffer = new Uint8Array(arrayBuffer);
+        }
+        else if (wasmBytes instanceof Promise) {
+            // Promise resolving to Uint8Array (for Vite ?init pattern or async imports)
+            wasmBuffer = await wasmBytes;
+        }
+        else if (wasmBytes instanceof URL) {
+            // URL object
+            const response = await fetch(wasmBytes.href);
+            if (!response.ok) {
+                throw new Error(`Failed to fetch WASM file from ${wasmBytes.href}: ${response.statusText}`);
+            }
+            const arrayBuffer = await response.arrayBuffer();
+            wasmBuffer = new Uint8Array(arrayBuffer);
+        }
+        else if (typeof wasmBytes === "string") {
+            // String URL (supports Vite-processed URLs)
+            const response = await fetch(wasmBytes);
+            if (!response.ok) {
+                throw new Error(`Failed to fetch WASM file from ${wasmBytes}: ${response.statusText}`);
+            }
+            const arrayBuffer = await response.arrayBuffer();
+            wasmBuffer = new Uint8Array(arrayBuffer);
+        }
+        else {
+            throw new Error(`Invalid wasmBytes type. Expected Uint8Array, string, URL, Response, or Promise<Uint8Array>, got ${typeof wasmBytes}`);
+        }
+        // Instantiate WASM
+        const go = new globalObj.Go();
+        // TypeScript needs help with overload resolution - cast through unknown
+        const result = (await WebAssembly.instantiate(wasmBuffer, go.importObject));
+        go.run(result.instance);
+        isInitialized = true;
+    })();
+    return initPromise;
+}
+// Set the init function in core (this is what core will call to check initialization)
+setInitFunction(internalInit);
+// Re-export everything from core
+export { Program, Env } from "./core.js";
+export { listType, mapType, CELFunction } from "./functions.js";
+export { Options } from "./options/index.js";
+// Export init function for browser (requires wasmBytes parameter)
+export { init };
+//# sourceMappingURL=browser.js.map

package/dist/browser.js.map

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

package/dist/core.d.ts

@@ -0,0 +1,160 @@
+import type { EnvOptions, TypeCheckResult } from "./types.js";
+/**
+ * Set the initialization function (called by node.ts or browser.ts)
+ * @internal
+ */
+export declare function setInitFunction(fn: () => Promise<void>): void;
+/**
+ * A compiled CEL program that can be evaluated with variables
+ */
+export declare class Program {
+    private programID;
+    private destroyed;
+    constructor(programID: string);
+    /**
+     * Evaluate the compiled program with the given variables
+     * @param vars - Variables to use in the evaluation
+     * @returns Promise resolving to the evaluation result
+     * @throws Error if evaluation fails or program has been destroyed
+     */
+    eval(vars?: Record<string, any> | null): Promise<any>;
+    /**
+     * Destroy this program and free associated WASM resources.
+     * After calling destroy(), this program instance should not be used.
+     * If FinalizationRegistry is available, resources will be automatically
+     * cleaned up when the object is garbage collected, but explicit cleanup
+     * is recommended.
+     */
+    destroy(): void;
+}
+/**
+ * A CEL environment that holds variable declarations and function definitions
+ */
+export declare class Env {
+    private envID;
+    private destroyed;
+    private constructor();
+    /**
+     * Get the environment ID (useful for debugging or advanced use cases)
+     */
+    getID(): string;
+    /**
+     * Create a new CEL environment
+     * @param options - Options including variable declarations, function definitions, and environment options
+     * @returns Promise resolving to a new Env instance
+     * @throws Error if environment creation fails
+     *
+     * @example
+     * ```typescript
+     * const env = await Env.new({
+     *   variables: [
+     *     { name: "x", type: "int" },
+     *     { name: "y", type: "int" }
+     *   ],
+     *   functions: [
+     *     CELFunction.new("add")
+     *       .param("a", "int")
+     *       .param("b", "int")
+     *       .returns("int")
+     *       .implement((a, b) => a + b)
+     *   ],
+     *   options: [
+     *     Options.optionalTypes()
+     *   ]
+     * });
+     * ```
+     */
+    static new(options?: EnvOptions): Promise<Env>;
+    /**
+     * Compile a CEL expression in this environment
+     * @param expr - The CEL expression to compile
+     * @returns Promise resolving to a compiled Program
+     * @throws Error if compilation fails or environment has been destroyed
+     *
+     * @example
+     * ```typescript
+     * const env = await Env.new({
+     *   variables: [{ name: "x", type: "int" }]
+     * });
+     * const program = await env.compile("x + 10");
+     * const result = await program.eval({ x: 5 });
+     * console.log(result); // 15
+     * ```
+     */
+    compile(expr: string): Promise<Program>;
+    /**
+     * Compile a CEL expression with detailed results including warnings and issues
+     * @param expr - The CEL expression to compile
+     * @returns Promise resolving to detailed compilation results
+     * @throws Error if environment has been destroyed
+     *
+     * @example
+     * ```typescript
+     * const result = await env.compileDetailed("x + y");
+     * if (result.success) {
+     *   console.log("Compiled successfully");
+     *   if (result.issues.length > 0) {
+     *     console.log("Warnings:", result.issues);
+     *   }
+     *   const evalResult = await result.program.eval({ x: 10, y: 20 });
+     * } else {
+     *   console.log("Compilation failed:", result.error);
+     *   console.log("All issues:", result.issues);
+     * }
+     * ```
+     */
+    compileDetailed(expr: string): Promise<import("./types.js").CompilationResult>;
+    /**
+     * Typecheck a CEL expression in this environment without compiling it
+     * @param expr - The CEL expression to typecheck
+     * @returns Promise resolving to the type information
+     * @throws Error if typechecking fails or environment has been destroyed
+     *
+     * @example
+     * ```typescript
+     * const env = await Env.new({
+     *   variables: [{ name: "x", type: "int" }, { name: "y", type: "int" }]
+     * });
+     * const typeInfo = await env.typecheck("x + y");
+     * console.log(typeInfo.type); // "int"
+     *
+     * const listType = await env.typecheck("[1, 2, 3]");
+     * console.log(listType.type); // { kind: "list", elementType: "int" }
+     * ```
+     */
+    typecheck(expr: string): Promise<TypeCheckResult>;
+    /**
+     * Extend this environment with additional CEL environment options
+     * @param options - Array of CEL environment option configurations or complex options with setup
+     * @returns Promise that resolves when the environment has been extended
+     * @throws Error if extension fails or environment has been destroyed
+     *
+     * @example
+     * ```typescript
+     * const env = await Env.new({
+     *   variables: [{ name: "x", type: "int" }]
+     * });
+     *
+     * // Add options after creation
+     * await env.extend([Options.optionalTypes()]);
+     * ```
+     */
+    extend(options: import("./options/index.js").EnvOptionInput[]): Promise<void>;
+    /**
+     * Internal method to extend environment with options
+     * This method delegates to options that implement OptionWithSetup for complex operations
+     * @private
+     */
+    private _extendWithOptions;
+    /**
+     * Destroy this environment and free associated WASM resources.
+     * This will also clean up any registered JavaScript functions associated
+     * with this environment.
+     * After calling destroy(), this environment instance should not be used.
+     * If FinalizationRegistry is available, resources will be automatically
+     * cleaned up when the object is garbage collected, but explicit cleanup
+     * is recommended.
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=core.d.ts.map

package/dist/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../lib/core.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,UAAU,EACV,eAAe,EAChB,MAAM,YAAY,CAAC;AAKpB;;;GAGG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAE7D;AA+ID;;GAEG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,SAAS,CAAkB;gBAEvB,SAAS,EAAE,MAAM;IAQ7B;;;;;OAKG;IACG,IAAI,CAAC,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAW,GAAG,OAAO,CAAC,GAAG,CAAC;IAyBjE;;;;;;OAMG;IACH,OAAO,IAAI,IAAI;CAyBhB;AAED;;GAEG;AACH,qBAAa,GAAG;IACd,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,SAAS,CAAkB;IAEnC,OAAO;IAQP;;OAEG;IACH,KAAK,IAAI,MAAM;IAIf;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;WACU,GAAG,CAAC,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC;IA6CpD;;;;;;;;;;;;;;;OAeG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA+B7C;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,eAAe,CACnB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,OAAO,YAAY,EAAE,iBAAiB,CAAC;IAsDlD;;;;;;;;;;;;;;;;;OAiBG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IA+BvD;;;;;;;;;;;;;;;OAeG;IACG,MAAM,CACV,OAAO,EAAE,OAAO,oBAAoB,EAAE,cAAc,EAAE,GACrD,OAAO,CAAC,IAAI,CAAC;IAIhB;;;;OAIG;YACW,kBAAkB;IAyFhC;;;;;;;;OAQG;IACH,OAAO,IAAI,IAAI;CAyBhB"}