tywrap 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 tywrap contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,319 @@
+# tywrap
+
+[![npm version](https://img.shields.io/npm/v/tywrap.svg)](https://www.npmjs.com/package/tywrap)
+[![CI](https://github.com/bbopen/tywrap/actions/workflows/ci.yml/badge.svg)](https://github.com/bbopen/tywrap/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+TypeScript wrapper for Python libraries with full type safety.
+
+> **Warning: Experimental Software**
+> **Version 0.1.0** - This project is in early experimental development. APIs may change significantly between versions. Not recommended for production use until version 1.0.0.
+
+TypeScript is great, but many robust libraries exist only in Python, especially for data science and machine learning. Wouldn't it be great if you could use those libraries in your TypeScript project?
+
+tywrap is a build-time code generation system that creates TypeScript wrappers for Python libraries, giving you type safety and IDE autocomplete for Python code.
+
+## Features
+
+- **Full Type Safety** - TypeScript type definitions generated from Python source analysis
+- **Multi-Runtime Support** - Works in Node.js (subprocess) and browsers (via Pyodide)
+- **IR-First Generation** - Python Intermediate Representation (IR) extractor analyzes modules and emits structured type information
+- **Rich Data Type Support** - Native handling for numpy, pandas, scipy, torch, sklearn, and Python stdlib types
+- **Efficient Serialization** - Apache Arrow binary format for high-performance data transfer (with JSON fallback)
+- **Optional Caching** - Intelligent result caching system (opt-in via config)
+
+## Requirements
+
+- Node.js 20+ (or Bun 1.1+ / Deno 1.46+)
+- Python 3.10+
+
+## Quick Start
+
+```bash
+npm install tywrap
+```
+
+### Initialize a Config
+
+```bash
+npx tywrap init
+```
+
+This creates a `tywrap.config.ts` file. Edit it to specify which Python modules to wrap.
+
+### Generate Wrappers
+
+```bash
+npx tywrap generate
+```
+
+### Basic Usage
+
+```typescript
+import { NodeBridge } from 'tywrap/node';
+import { setRuntimeBridge } from 'tywrap/runtime';
+import * as math from './generated/math.generated.js';
+
+// Create a "bridge" - the runtime adapter that executes Python code
+const bridge = new NodeBridge({
+  pythonPath: 'python3',
+  virtualEnv: './venv'
+});
+
+// Set as the active bridge for generated wrappers
+setRuntimeBridge(bridge);
+
+// Call Python functions with full type safety
+const result = await math.sqrt(16);
+console.log(result); // 4
+```
+
+## Runtime Support
+
+tywrap provides **bridge** implementations—runtime adapters that handle communication between TypeScript and Python.
+
+### Node.js (Primary)
+
+The Node.js bridge spawns a Python subprocess and communicates via JSON-RPC:
+
+```typescript
+import { NodeBridge } from 'tywrap/node';
+import { setRuntimeBridge } from 'tywrap/runtime';
+
+const bridge = new NodeBridge({
+  pythonPath: 'python3',
+  virtualEnv: './venv',
+  timeout: 30000  // Optional: request timeout in ms
+});
+
+setRuntimeBridge(bridge);
+```
+
+### Browser (Pyodide)
+
+The browser bridge uses [Pyodide](https://pyodide.org/) to run Python in WebAssembly:
+
+```typescript
+import { PyodideBridge } from 'tywrap/pyodide';
+import { setRuntimeBridge } from 'tywrap/runtime';
+
+const bridge = new PyodideBridge({
+  indexURL: 'https://cdn.jsdelivr.net/pyodide/v0.24.1/full/'
+});
+
+await bridge.init();
+setRuntimeBridge(bridge);
+```
+
+### Deno / Bun
+
+Deno and Bun can use the Node.js bridge. Import via npm specifier:
+
+```typescript
+// Deno
+import { NodeBridge, setRuntimeBridge } from 'npm:tywrap';
+
+// Bun (same as Node.js)
+import { NodeBridge, setRuntimeBridge } from 'tywrap';
+
+const bridge = new NodeBridge({ pythonPath: 'python3' });
+setRuntimeBridge(bridge);
+```
+
+### Working with Classes
+
+Generated class wrappers use async factory methods:
+
+```typescript
+import { Counter } from './generated/collections.generated';
+
+// Create instance (async because it calls Python)
+const counter = await Counter.create(['a', 'b', 'b', 'c', 'b']);
+
+// Call methods
+const mostCommon = await counter.mostCommon(2);
+console.log(mostCommon); // [['b', 3], ['c', 1]]
+
+// Clean up when done
+await counter.disposeHandle();
+```
+
+## Configuration
+
+Create a `tywrap.config.ts` file:
+
+```typescript
+import { defineConfig } from 'tywrap';
+
+export default defineConfig({
+  pythonModules: {
+    'pandas': {
+      version: '2.1.0',
+      classes: ['DataFrame'],
+      functions: ['read_csv', 'concat']
+    },
+    'numpy': {
+      version: '1.24.0',
+      alias: 'np'
+    },
+    './custom_module.py': {
+      // Local modules work too
+    }
+  },
+
+  output: {
+    dir: './src/generated',
+    format: 'esm',
+    declaration: true
+  },
+
+  performance: {
+    caching: true,  // Enable result caching
+    batching: true  // Batch multiple calls
+  },
+
+  debug: false  // Set true for verbose logging
+});
+```
+
+Config file resolution: `tywrap.config.ts`, `.mts`, `.js`, `.mjs`, `.cjs`, `.json`.
+
+See the [Configuration Guide](./docs/configuration.md) for all options.
+
+## How It Works
+
+1. **Python IR Extraction** - The `tywrap_ir` tool analyzes Python modules using AST parsing and emits a versioned JSON Intermediate Representation (IR) containing function signatures, class definitions, and type annotations.
+
+2. **Type Mapping** - The IR is transformed into TypeScript types. Python's `int` becomes `number`, `List[str]` becomes `string[]`, etc.
+
+3. **Code Generation** - TypeScript wrapper code is generated with proper async handling and bridge integration.
+
+4. **Runtime Execution** - At runtime, the bridge serializes calls to Python and deserializes results back to JavaScript.
+
+## Documentation
+
+- [Getting Started Guide](./docs/getting-started.md) - Detailed setup instructions
+- [Configuration Reference](./docs/configuration.md) - All configuration options
+- [Node.js Runtime](./docs/runtimes/nodejs.md) - Node.js bridge details
+- [Browser Runtime](./docs/runtimes/browser.md) - Pyodide integration
+- [API Reference](./docs/api/README.md) - Complete API documentation
+- [Examples](./docs/examples/README.md) - Real-world usage examples
+- [Troubleshooting](./docs/troubleshooting/README.md) - Common issues and solutions
+- [Release Notes](./docs/release.md) - Version history and upgrade guides
+
+## Data Type Support
+
+tywrap automatically serializes Python data types to JavaScript. The Python bridge wraps complex types in **envelopes**—metadata wrappers that preserve type information.
+
+### Supported Types
+
+| Python Type | JS/TS Type | Encoding | Notes |
+|-------------|-----------|----------|-------|
+| `numpy.ndarray` | `Uint8Array` or `array` | Arrow or JSON | Shape preserved |
+| `pandas.DataFrame` | Arrow Table or `object[]` | Arrow or JSON | Column types preserved |
+| `pandas.Series` | Arrow Table or `array` | Arrow or JSON | Name preserved |
+| `scipy.sparse.*` | `SparseMatrix` | JSON | CSR, CSC, COO formats |
+| `torch.Tensor` | `TorchTensor` | ndarray wrapper | CPU only by default |
+| `sklearn estimator` | `SklearnEstimator` | JSON | Params only (no pickle) |
+| `datetime.*` | `string` | ISO format | datetime, date, time |
+| `timedelta` | `number` | seconds | Total seconds as float |
+| `Decimal` | `string` | string | Preserves precision |
+| `UUID` | `string` | string | Standard format |
+| `Path` | `string` | string | Platform-neutral |
+
+### Arrow Encoding (Recommended)
+
+For numpy/pandas data, Arrow binary format is more efficient than JSON. Register a decoder at app startup:
+
+```typescript
+import { registerArrowDecoder } from 'tywrap';
+import { tableFromIPC } from 'apache-arrow';
+
+registerArrowDecoder(bytes => tableFromIPC(bytes));
+```
+
+### Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `TYWRAP_CODEC_FALLBACK=json` | Use JSON instead of Arrow (for dev or constrained environments) |
+| `TYWRAP_TORCH_ALLOW_COPY=1` | Allow GPU→CPU transfer and non-contiguous tensor copying |
+
+### Envelope Format
+
+```json
+{"__tywrap__": "dataframe", "encoding": "arrow", "b64": "..."}
+{"__tywrap__": "ndarray", "encoding": "json", "data": [...], "shape": [3, 4]}
+{"__tywrap__": "scipy.sparse", "format": "csr", "data": [...], "indices": [...]}
+{"__tywrap__": "torch.tensor", "value": {...}, "dtype": "float32", "device": "cpu"}
+{"__tywrap__": "sklearn.estimator", "className": "LinearRegression", "params": {...}}
+```
+
+See [codec-roadmap.md](./docs/codec-roadmap.md) for encoding details and planned features.
+
+## Roadmap
+
+### Implemented
+- [x] Core TypeScript generation from Python IR
+- [x] Node.js runtime bridge (subprocess)
+- [x] Browser runtime bridge (Pyodide)
+- [x] Python AST analysis and type extraction
+- [x] Codec support: numpy, pandas, scipy sparse, torch tensors, sklearn estimators
+- [x] Apache Arrow binary encoding (with JSON fallback)
+- [x] Python stdlib type conversions (datetime, Decimal, UUID, Path)
+- [x] Result caching system (opt-in)
+
+### Planned
+- [ ] Build tool plugins (Vite, Webpack, Rollup)
+- [ ] Hot reload / watch mode
+- [ ] Source map generation
+- [ ] IDE extensions
+- [ ] SharedArrayBuffer for zero-copy transfers
+- [ ] Streaming results for large datasets
+
+## Versioning
+
+tywrap follows [Semantic Versioning](https://semver.org/):
+
+- **0.x.x** - Experimental releases. Breaking changes may occur in any release.
+- **1.x.x** - Stable API. Breaking changes only in major versions.
+
+### Current Status (v0.1.0)
+
+| Feature | Status |
+|---------|--------|
+| TypeScript generation | ✅ Working |
+| Node.js bridge | ✅ Working |
+| Pyodide bridge | ✅ Working |
+| Type safety | ✅ Working |
+| numpy/pandas codecs | ✅ Working |
+| scipy/torch/sklearn codecs | ✅ Working |
+| Deno/Bun | ⚠️ Uses Node bridge |
+| API stability | ⚠️ May change |
+
+## Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+
+To run tests locally:
+
+```bash
+npm install
+npm test
+```
+
+For the full test matrix including Python library integration:
+
+```bash
+npm run test:python:suite:core
+```
+
+## License
+
+MIT © [tywrap contributors](LICENSE)
+
+## Links
+
+- [GitHub Repository](https://github.com/bbopen/tywrap)
+- [npm Package](https://www.npmjs.com/package/tywrap)
+- [Issue Tracker](https://github.com/bbopen/tywrap/issues)

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

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

package/dist/cli.js

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import { resolveConfig } from './config/index.js';
+import { getComponentLogger } from './utils/logger.js';
+const log = getComponentLogger('CLI');
+const DEFAULT_CONFIG_FILES = [
+    'tywrap.config.ts',
+    'tywrap.config.mts',
+    'tywrap.config.js',
+    'tywrap.config.mjs',
+    'tywrap.config.cjs',
+    'tywrap.config.json',
+];
+function resolveConfigPath(explicitPath) {
+    const cwd = process.cwd();
+    if (explicitPath) {
+        const resolved = resolve(cwd, explicitPath);
+        return { configPath: resolved, explicit: true };
+    }
+    for (const name of DEFAULT_CONFIG_FILES) {
+        const candidate = resolve(cwd, name);
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- config discovery uses user-controlled paths
+        if (existsSync(candidate)) {
+            return { configPath: candidate, explicit: false };
+        }
+    }
+    return { configPath: undefined, explicit: false };
+}
+function parseModules(modulesList) {
+    if (!modulesList) {
+        return [];
+    }
+    return modulesList
+        .split(',')
+        .map(m => m.trim())
+        .filter(Boolean);
+}
+function buildModulesConfig(modules, runtime) {
+    return Object.fromEntries(modules.map(name => [name, { runtime, typeHints: 'strict' }]));
+}
+function renderConfigTemplate(options) {
+    const modules = options.modules.length > 0 ? options.modules : ['math'];
+    if (options.format === 'json') {
+        const config = {
+            pythonModules: buildModulesConfig(modules, options.runtime),
+            output: { dir: options.outputDir, format: 'esm', declaration: false, sourceMap: false },
+            runtime: { node: { pythonPath: 'python3' } },
+            types: { presets: ['stdlib'] },
+        };
+        return `${JSON.stringify(config, null, 2)}\n`;
+    }
+    const moduleLines = modules
+        .map(name => `    ${JSON.stringify(name)}: { runtime: '${options.runtime}', typeHints: 'strict' },`)
+        .join('\n');
+    return `import { defineConfig } from 'tywrap';
+
+export default defineConfig({
+  pythonModules: {
+${moduleLines}
+  },
+  output: {
+    dir: '${options.outputDir}',
+    format: 'esm',
+    declaration: false,
+    sourceMap: false
+  },
+  runtime: {
+    node: {
+      pythonPath: 'python3'
+    }
+  },
+  types: {
+    presets: ['stdlib']
+  }
+});
+`;
+}
+async function main() {
+    await yargs(hideBin(process.argv))
+        .scriptName('tywrap')
+        .command('generate', 'Generate TypeScript wrappers', (y) => y
+        .option('config', {
+        alias: 'c',
+        type: 'string',
+        describe: 'Path to config file (defaults to tywrap.config.* if present)',
+    })
+        .option('modules', {
+        type: 'string',
+        describe: 'Comma-separated list of Python modules to wrap',
+    })
+        .option('runtime', {
+        type: 'string',
+        choices: ['node', 'pyodide', 'http', 'auto'],
+        default: 'node',
+        describe: 'Runtime to use when --modules is provided',
+    })
+        .option('python', {
+        type: 'string',
+        describe: 'Path to Python executable',
+    })
+        .option('output-dir', {
+        type: 'string',
+        describe: 'Directory for generated wrappers',
+    })
+        .option('format', {
+        type: 'string',
+        choices: ['esm', 'cjs', 'both'],
+        describe: 'Output module format',
+    })
+        .option('declaration', {
+        type: 'boolean',
+        describe: 'Emit TypeScript declaration files',
+    })
+        .option('source-map', {
+        type: 'boolean',
+        describe: 'Emit source maps for generated files',
+    })
+        .option('use-cache', {
+        alias: 'cache',
+        type: 'boolean',
+        describe: 'Enable on-disk caching (use --no-cache to disable)',
+    })
+        .option('debug', {
+        type: 'boolean',
+        describe: 'Enable debug logging',
+    })
+        .option('fail-on-warn', {
+        type: 'boolean',
+        default: false,
+        describe: 'Exit with code 2 if generation emits warnings',
+    })
+        .strict(), async (argv) => {
+        const { configPath, explicit } = resolveConfigPath(argv.config);
+        const modules = parseModules(argv.modules);
+        const overrides = {};
+        if (modules.length > 0) {
+            overrides.pythonModules = buildModulesConfig(modules, argv.runtime);
+        }
+        if (argv.outputDir ||
+            argv.format ||
+            typeof argv.declaration === 'boolean' ||
+            typeof argv.sourceMap === 'boolean') {
+            overrides.output = {
+                ...(argv.outputDir ? { dir: argv.outputDir } : {}),
+                ...(argv.format ? { format: argv.format } : {}),
+                ...(typeof argv.declaration === 'boolean' ? { declaration: argv.declaration } : {}),
+                ...(typeof argv.sourceMap === 'boolean' ? { sourceMap: argv.sourceMap } : {}),
+            };
+        }
+        if (typeof argv.useCache === 'boolean') {
+            overrides.performance = {
+                caching: argv.useCache,
+            };
+        }
+        if (argv.python) {
+            overrides.runtime = {
+                node: { pythonPath: argv.python },
+            };
+        }
+        if (typeof argv.debug === 'boolean') {
+            overrides.debug = argv.debug;
+        }
+        if (!configPath && modules.length === 0) {
+            log.error('No config file found and no modules provided. Create a config with `tywrap init` or pass --modules.');
+            process.exit(1);
+        }
+        const { generate } = await import('./tywrap.js');
+        try {
+            const options = await resolveConfig({
+                configFile: configPath,
+                overrides,
+                requireConfig: explicit,
+            });
+            if (!options.pythonModules || Object.keys(options.pythonModules).length === 0) {
+                log.error('No pythonModules configured. Use --modules or update your config.');
+                process.exit(1);
+            }
+            const res = await generate(options);
+            process.stdout.write(`Generated: ${res.written.join(', ')}\n`);
+            if (argv.failOnWarn && res.warnings.length > 0) {
+                log.error(`Warnings encountered (count ${res.warnings.length}). Failing due to --fail-on-warn.`);
+                process.exit(2);
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            log.error('Generation failed', { error: message });
+            process.exit(1);
+        }
+    })
+        .command('init', 'Create a starter tywrap.config file', (y) => y
+        .option('config', {
+        alias: 'c',
+        type: 'string',
+        describe: 'Path for the new config file',
+    })
+        .option('format', {
+        type: 'string',
+        choices: ['ts', 'json'],
+        default: 'ts',
+        describe: 'Config file format',
+    })
+        .option('modules', {
+        type: 'string',
+        describe: 'Comma-separated list of Python modules to wrap',
+    })
+        .option('runtime', {
+        type: 'string',
+        choices: ['node', 'pyodide', 'http', 'auto'],
+        default: 'node',
+        describe: 'Runtime for generated module entries',
+    })
+        .option('output-dir', {
+        type: 'string',
+        default: './generated',
+        describe: 'Output directory for generated wrappers',
+    })
+        .option('force', {
+        type: 'boolean',
+        default: false,
+        describe: 'Overwrite existing config file',
+    })
+        .strict(), async (argv) => {
+        const modules = parseModules(argv.modules);
+        const defaultName = argv.format === 'json' ? 'tywrap.config.json' : 'tywrap.config.ts';
+        const targetPath = resolve(process.cwd(), argv.config ?? defaultName);
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- config path is user-controlled
+        if (!argv.force && existsSync(targetPath)) {
+            log.error('Config file already exists. Use --force to overwrite.', { path: targetPath });
+            process.exit(1);
+        }
+        const content = renderConfigTemplate({
+            format: argv.format,
+            modules,
+            runtime: argv.runtime,
+            outputDir: argv.outputDir,
+        });
+        try {
+            // eslint-disable-next-line security/detect-non-literal-fs-filename -- config path is user-controlled
+            await writeFile(targetPath, content, 'utf-8');
+            process.stdout.write(`Created ${targetPath}\n`);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            log.error('Failed to write config', { error: message });
+            process.exit(1);
+        }
+    })
+        .demandCommand(1, 'Please specify a command')
+        .strict()
+        .help()
+        .version()
+        .parse();
+}
+main().catch(err => {
+    log.error('Unexpected error', { error: err instanceof Error ? err.message : String(err) });
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/config/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Configuration system
+ *
+ * Loads configuration from defaults, optional config file and CLI overrides
+ * with basic validation of known options.
+ */
+import type { TywrapOptions } from '../types/index.js';
+/**
+ * Public configuration type. Currently identical to {@link TywrapOptions}.
+ */
+export type TywrapConfig = TywrapOptions;
+type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends Array<infer U> ? Array<U> : T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+/**
+ * Create a configuration object by merging defaults with overrides.
+ *
+ * @param overrides CLI or programmatic overrides
+ */
+export declare function createConfig(overrides?: DeepPartial<TywrapOptions>): TywrapConfig;
+export interface ResolveConfigOptions {
+    configFile?: string;
+    overrides?: DeepPartial<TywrapOptions>;
+    cwd?: string;
+    requireConfig?: boolean;
+}
+/**
+ * Resolve configuration by loading a config file (JSON/JS/TS) and merging
+ * defaults with any overrides.
+ */
+export declare function resolveConfig(options?: ResolveConfigOptions): Promise<TywrapConfig>;
+/**
+ * Load a tywrap config file. Supports JSON, JS/CJS/ESM, and TS files.
+ */
+export declare function loadConfigFile(configFile: string): Promise<Partial<TywrapOptions>>;
+/**
+ * Type helper for authoring tywrap configs with full type inference.
+ */
+export declare function defineConfig(config: TywrapConfig): TywrapConfig;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,KAAK,EACV,aAAa,EAKd,MAAM,mBAAmB,CAAC;AAG3B;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,aAAa,CAAC;AAEzC,KAAK,WAAW,CAAC,CAAC,IAAI;KACnB,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,KAAK,CAAC,MAAM,CAAC,CAAC,GACxC,KAAK,CAAC,CAAC,CAAC,GACR,CAAC,CAAC,CAAC,CAAC,SAAS,MAAM,GACjB,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GACjB,CAAC,CAAC,CAAC,CAAC;CACX,CAAC;AA2IF;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,SAAS,GAAE,WAAW,CAAC,aAAa,CAAM,GAAG,YAAY,CAIrF;AAED,MAAM,WAAW,oBAAoB;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,WAAW,CAAC,aAAa,CAAC,CAAC;IACvC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAsB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,YAAY,CAAC,CAmB7F;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CA2DxF;AAOD;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAE/D"}