@vurb/core 3.2.0

package/dist/core/initVurb.d.ts

@@ -0,0 +1,295 @@
+/**
+ * initVurb() — tRPC-Style Context Initialization
+ *
+ * Eliminates the need to pass `<AppContext>` as a generic parameter
+ * everywhere. Define your context type once, and every `f.query()`,
+ * `f.mutation()`, `f.action()` call automatically inherits it.
+ *
+ * @example
+ * ```typescript
+ * // src/vurb.ts — defined once in the project
+ * import { initVurb } from 'vurb';
+ *
+ * interface AppContext {
+ *   db: PrismaClient;
+ *   user: { id: string; role: string };
+ * }
+ *
+ * export const f = initVurb<AppContext>();
+ *
+ * // src/tools/billing.ts — clean fluent API
+ * import { f } from '../vurb';
+ *
+ * export const getInvoice = f.query('billing.get_invoice')
+ *     .describe('Get an invoice by ID')
+ *     .withString('id', 'The invoice ID')
+ *     .handle(async (input, ctx) => {
+ *         return await ctx.db.invoices.findUnique(input.id);
+ *     });
+ * ```
+ *
+ * @module
+ */
+import { type ZodType } from 'zod';
+import { GroupedToolBuilder } from './builder/GroupedToolBuilder.js';
+import { ToolRegistry } from './registry/ToolRegistry.js';
+import { type Presenter } from '../presenter/Presenter.js';
+import { type PresenterConfig } from '../presenter/definePresenter.js';
+import { type MiddlewareDefinition } from './middleware/index.js';
+import { type ToolConfig } from './builder/defineTool.js';
+import { FluentPromptBuilder } from '../prompt/FluentPromptBuilder.js';
+import { type PromptBuilder, type PromptConfig } from '../prompt/types.js';
+import { FluentToolBuilder } from './builder/FluentToolBuilder.js';
+import { FluentRouter } from './builder/FluentRouter.js';
+import { ErrorBuilder } from './builder/ErrorBuilder.js';
+import { StateSyncBuilder } from '../state-sync/StateSyncBuilder.js';
+import { type ErrorCode } from './response.js';
+import { SandboxEngine, type SandboxConfig } from '../sandbox/SandboxEngine.js';
+import { type JsonSerializer } from './serialization/JsonSerializer.js';
+import { StateMachineGate, type FsmConfig } from '../fsm/StateMachineGate.js';
+/**
+ * The initialized Vurb instance.
+ *
+ * Provides context-typed factory methods for tools, presenters,
+ * prompts, middleware, and registry. Every method automatically
+ * inherits the `TContext` defined in `initVurb<TContext>()`.
+ *
+ * @typeParam TContext - The application context type
+ */
+export interface VurbInstance<TContext> {
+    /**
+     * Create a **read-only** query tool (readOnly: true by default).
+     *
+     * @param name - Tool name in `domain.action` format
+     * @returns A type-chaining {@link FluentToolBuilder}
+     *
+     * @example
+     * ```typescript
+     * const listUsers = f.query('users.list')
+     *     .describe('List users from the database')
+     *     .withNumber('limit', 'Max results to return')
+     *     .withOptionalEnum('status', ['active', 'inactive'], 'Filter by status')
+     *     .handle(async (input, ctx) => {
+     *         return ctx.db.user.findMany({ take: input.limit });
+     *     });
+     * ```
+     */
+    query(name: string): FluentToolBuilder<TContext>;
+    /**
+     * Create a **destructive** mutation tool (destructive: true by default).
+     *
+     * @param name - Tool name in `domain.action` format
+     * @returns A type-chaining {@link FluentToolBuilder}
+     *
+     * @example
+     * ```typescript
+     * const deleteUser = f.mutation('users.delete')
+     *     .describe('Delete a user permanently')
+     *     .withString('id', 'User ID to delete')
+     *     .handle(async (input, ctx) => {
+     *         await ctx.db.user.delete({ where: { id: input.id } });
+     *     });
+     * ```
+     */
+    mutation(name: string): FluentToolBuilder<TContext>;
+    /**
+     * Create a **neutral** action tool (no defaults applied).
+     *
+     * @param name - Tool name in `domain.action` format
+     * @returns A type-chaining {@link FluentToolBuilder}
+     *
+     * @example
+     * ```typescript
+     * const updateUser = f.action('users.update')
+     *     .describe('Update user profile')
+     *     .idempotent()
+     *     .withString('id', 'User ID')
+     *     .withOptionalString('name', 'New display name')
+     *     .handle(async (input, ctx) => {
+     *         return ctx.db.user.update({ where: { id: input.id }, data: input });
+     *     });
+     * ```
+     */
+    action(name: string): FluentToolBuilder<TContext>;
+    /**
+     * Define a Presenter with the standard object-config API.
+     *
+     * @example
+     * ```typescript
+     * const InvoicePresenter = f.presenter({
+     *   name: 'Invoice',
+     *   schema: invoiceSchema,
+     *   rules: ['CRITICAL: amount_cents is in CENTS.'],
+     *   ui: (inv) => [ui.echarts({ ... })],
+     * });
+     * ```
+     */
+    presenter<TSchema extends ZodType<any, any, any>>(config: Omit<PresenterConfig<TSchema['_output']>, 'schema'> & {
+        schema: TSchema;
+    }): Presenter<TSchema['_output']>;
+    /**
+     * Define a prompt — fluent builder.
+     *
+     * @example
+     * ```typescript
+     * const greet = f.prompt('greet')
+     *     .describe('Greet a user')
+     *     .withString('name', 'User name')
+     *     .handler(async (ctx, { name }) => ({
+     *         messages: [PromptMessage.user(`Hello ${name}!`)],
+     *     }));
+     * ```
+     */
+    prompt(name: string): FluentPromptBuilder<TContext>;
+    prompt(name: string, config: Omit<PromptConfig<TContext>, 'handler'> & {
+        handler: PromptConfig<TContext>['handler'];
+    }): PromptBuilder<TContext>;
+    /**
+     * Define a context-derivation middleware.
+     *
+     * @example
+     * ```typescript
+     * const withUser = f.middleware(async (ctx) => ({
+     *   user: await ctx.db.users.findUnique(ctx.userId),
+     * }));
+     * ```
+     */
+    middleware<TDerived extends Record<string, unknown>>(derive: (ctx: TContext) => TDerived | Promise<TDerived>): MiddlewareDefinition<TContext, TDerived>;
+    /**
+     * Create a pre-typed ToolRegistry ready for registration.
+     *
+     * @example
+     * ```typescript
+     * const registry = f.registry();
+     * registry.register(listUsers);
+     * ```
+     */
+    registry(): ToolRegistry<TContext>;
+    /**
+     * Create a router that shares prefix, middleware, and tags.
+     *
+     * @param prefix - Common prefix for all tools (e.g. `'users'`)
+     * @returns A {@link FluentRouter} for creating child tools
+     *
+     * @example
+     * ```typescript
+     * const users = f.router('users')
+     *     .describe('User management')
+     *     .use(requireAuth);
+     *
+     * const listUsers = users.query('list')
+     *     .withNumber('limit', 'Max results')
+     *     .handle(async (input) => { ... });
+     * ```
+     */
+    router(prefix: string): FluentRouter<TContext>;
+    /**
+     * Create a fluent, self-healing error builder.
+     *
+     * @param code - Canonical error code
+     * @param message - Human-readable error message
+     * @returns A chaining {@link ErrorBuilder}
+     *
+     * @example
+     * ```typescript
+     * return f.error('NOT_FOUND', `Project "${id}" not found`)
+     *     .suggest('Check the list for valid IDs')
+     *     .actions('projects.list');
+     * ```
+     */
+    error(code: ErrorCode, message: string): ErrorBuilder;
+    /**
+     * Create a fluent builder for centralized State Sync policies.
+     */
+    stateSync(): StateSyncBuilder;
+    /**
+     * Create a tool using the low-level `defineTool()` config.
+     * For internal use and advanced scenarios only.
+     * @internal
+     */
+    defineTool(name: string, config: ToolConfig<TContext>): GroupedToolBuilder<TContext>;
+    /**
+     * Create a standalone SandboxEngine for advanced use cases.
+     *
+     * Use when you need direct control over the sandbox lifecycle,
+     * or when calling it from custom middleware/handlers.
+     *
+     * @param config - Optional sandbox configuration
+     * @returns A new SandboxEngine instance
+     *
+     * @example
+     * ```typescript
+     * const sandbox = f.sandbox({ timeout: 3000, memoryLimit: 64 });
+     * const result = await sandbox.execute(
+     *     '(data) => data.filter(d => d.risk > 90)',
+     *     records,
+     * );
+     * sandbox.dispose();
+     * ```
+     */
+    sandbox(config?: SandboxConfig): SandboxEngine;
+    /**
+     * AOT JSON serializer.
+     *
+     * Compile Zod schemas into hyper-fast stringify functions at boot time.
+     * Used internally by Presenters; exposed here for advanced use cases.
+     *
+     * @example
+     * ```typescript
+     * const stringify = f.serializer.compile(myZodSchema);
+     * if (stringify) {
+     *     return success(data, stringify); // 2-5x faster
+     * }
+     * ```
+     */
+    readonly serializer: JsonSerializer;
+    /**
+     * Create a Finite State Machine gate for temporal anti-hallucination.
+     *
+     * Tools bound to FSM states (via `.bindState()`) are dynamically
+     * filtered from `tools/list` based on the current workflow state.
+     *
+     * @param config - FSM definition (states, transitions, initial state)
+     * @returns A new StateMachineGate instance
+     *
+     * @example
+     * ```typescript
+     * const gate = f.fsm({
+     *     id: 'checkout',
+     *     initial: 'empty',
+     *     states: {
+     *         empty:     { on: { ADD_ITEM: 'has_items' } },
+     *         has_items: { on: { CHECKOUT: 'payment' } },
+     *         payment:   { on: { PAY: 'confirmed' } },
+     *         confirmed: { type: 'final' },
+     *     },
+     * });
+     * ```
+     */
+    fsm(config: FsmConfig): StateMachineGate;
+}
+/**
+ * Initialize a Vurb instance with a fixed context type.
+ *
+ * Call once per project. All factory methods on the returned instance
+ * automatically inherit the context type — zero generic repetition.
+ *
+ * @typeParam TContext - The application-level context type
+ * @returns A {@link VurbInstance} with context-typed factories
+ *
+ * @example
+ * ```typescript
+ * // Single definition, typically in src/vurb.ts
+ * export const f = initVurb<AppContext>();
+ *
+ * // Build tools with the Fluent API
+ * const listUsers = f.query('users.list')
+ *     .describe('List all users')
+ *     .withOptionalNumber('limit', 'Max results (default: 50)')
+ *     .handle(async (input, ctx) => {
+ *         return ctx.db.users.findMany({ take: input.limit ?? 50 });
+ *     });
+ * ```
+ */
+export declare function initVurb<TContext = void>(): VurbInstance<TContext>;
+//# sourceMappingURL=initVurb.d.ts.map

package/dist/core/initVurb.d.ts.map

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

package/dist/core/initVurb.js

@@ -0,0 +1,171 @@
+/**
+ * initVurb() — tRPC-Style Context Initialization
+ *
+ * Eliminates the need to pass `<AppContext>` as a generic parameter
+ * everywhere. Define your context type once, and every `f.query()`,
+ * `f.mutation()`, `f.action()` call automatically inherits it.
+ *
+ * @example
+ * ```typescript
+ * // src/vurb.ts — defined once in the project
+ * import { initVurb } from 'vurb';
+ *
+ * interface AppContext {
+ *   db: PrismaClient;
+ *   user: { id: string; role: string };
+ * }
+ *
+ * export const f = initVurb<AppContext>();
+ *
+ * // src/tools/billing.ts — clean fluent API
+ * import { f } from '../vurb';
+ *
+ * export const getInvoice = f.query('billing.get_invoice')
+ *     .describe('Get an invoice by ID')
+ *     .withString('id', 'The invoice ID')
+ *     .handle(async (input, ctx) => {
+ *         return await ctx.db.invoices.findUnique(input.id);
+ *     });
+ * ```
+ *
+ * @module
+ */
+import {} from 'zod';
+import { GroupedToolBuilder } from './builder/GroupedToolBuilder.js';
+import {} from './response.js';
+import {} from './types.js';
+import { ToolRegistry } from './registry/ToolRegistry.js';
+import {} from '../presenter/Presenter.js';
+import { definePresenter } from '../presenter/definePresenter.js';
+import { defineMiddleware } from './middleware/index.js';
+import { defineTool } from './builder/defineTool.js';
+import { definePrompt } from '../prompt/definePrompt.js';
+import { FluentPromptBuilder } from '../prompt/FluentPromptBuilder.js';
+import {} from '../prompt/types.js';
+import { FluentToolBuilder, QUERY_DEFAULTS, MUTATION_DEFAULTS, ACTION_DEFAULTS, } from './builder/FluentToolBuilder.js';
+import { FluentRouter } from './builder/FluentRouter.js';
+import { ErrorBuilder } from './builder/ErrorBuilder.js';
+import { StateSyncBuilder } from '../state-sync/StateSyncBuilder.js';
+import {} from './response.js';
+import { SandboxEngine } from '../sandbox/SandboxEngine.js';
+import { defaultSerializer } from './serialization/JsonSerializer.js';
+import { StateMachineGate } from '../fsm/StateMachineGate.js';
+// ── Factory ──────────────────────────────────────────────
+/**
+ * Initialize a Vurb instance with a fixed context type.
+ *
+ * Call once per project. All factory methods on the returned instance
+ * automatically inherit the context type — zero generic repetition.
+ *
+ * @typeParam TContext - The application-level context type
+ * @returns A {@link VurbInstance} with context-typed factories
+ *
+ * @example
+ * ```typescript
+ * // Single definition, typically in src/vurb.ts
+ * export const f = initVurb<AppContext>();
+ *
+ * // Build tools with the Fluent API
+ * const listUsers = f.query('users.list')
+ *     .describe('List all users')
+ *     .withOptionalNumber('limit', 'Max results (default: 50)')
+ *     .handle(async (input, ctx) => {
+ *         return ctx.db.users.findMany({ take: input.limit ?? 50 });
+ *     });
+ * ```
+ */
+export function initVurb() {
+    return {
+        // ── Semantic Verbs ────────────────────────────────
+        query(name) {
+            return new FluentToolBuilder(name, QUERY_DEFAULTS);
+        },
+        mutation(name) {
+            return new FluentToolBuilder(name, MUTATION_DEFAULTS);
+        },
+        action(name) {
+            return new FluentToolBuilder(name, ACTION_DEFAULTS);
+        },
+        // ── MVA Presenter ────────────────────────────────
+        presenter(config) {
+            return definePresenter(config);
+        },
+        // ── Prompts ──────────────────────────────────────
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        prompt(name, config) {
+            if (!config) {
+                return new FluentPromptBuilder(name);
+            }
+            return definePrompt(name, config);
+        },
+        // ── Middleware ───────────────────────────────────
+        middleware(derive) {
+            return defineMiddleware(derive);
+        },
+        // ── Registry ─────────────────────────────────────
+        registry() {
+            return new ToolRegistry();
+        },
+        // ── Router ───────────────────────────────────────
+        router(prefix) {
+            return new FluentRouter(prefix);
+        },
+        // ── Error Builder ────────────────────────────────
+        error(code, message) {
+            return new ErrorBuilder(code, message);
+        },
+        // ── State Sync ───────────────────────────────────
+        stateSync() {
+            return new StateSyncBuilder();
+        },
+        // ── Internal / Advanced ──────────────────────────
+        defineTool(name, config) {
+            return defineTool(name, config);
+        },
+        // ── Sandbox ──────────────────────────────────────
+        sandbox(config) {
+            const engine = new SandboxEngine(config);
+            // Bug #141: warn when engines are garbage-collected without dispose().
+            // V8 Isolates hold native memory invisible to the Node GC.
+            _trackSandboxDispose(engine);
+            return engine;
+        },
+        // ── Serialization ────────────────────────────────
+        serializer: defaultSerializer,
+        // ── FSM State Gate ─────────────────────────────
+        fsm(config) {
+            return new StateMachineGate(config);
+        },
+    };
+}
+// ── Bug #141: FinalizationRegistry leak-detection for SandboxEngine ──
+/**
+ * Track SandboxEngine instances and emit a console.warn when one is
+ * garbage-collected without being disposed first. V8 Isolates hold
+ * native C++ memory invisible to the Node.js GC — a forgotten
+ * `.dispose()` silently leaks until process exit.
+ *
+ * Uses `FinalizationRegistry` (ES2021). No-op if the API is unavailable.
+ * The warning is best-effort — GC timing is non-deterministic.
+ * @internal
+ */
+const _sandboxFinalizer = typeof FinalizationRegistry !== 'undefined'
+    ? new FinalizationRegistry((label) => {
+        console.warn(`[vurb] SandboxEngine was garbage-collected without dispose(). ` +
+            `This leaks native V8 Isolate memory. Call engine.dispose() when done. (${label})`);
+    })
+    : undefined;
+/** @internal */
+function _trackSandboxDispose(engine) {
+    if (!_sandboxFinalizer)
+        return;
+    const label = `created at ${new Date().toISOString()}`;
+    _sandboxFinalizer.register(engine, label, engine);
+    // When dispose() is called, unregister so no false warning fires
+    const originalDispose = engine.dispose.bind(engine);
+    engine.dispose = () => {
+        _sandboxFinalizer.unregister(engine);
+        originalDispose();
+    };
+}
+//# sourceMappingURL=initVurb.js.map

package/dist/core/initVurb.js.map

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

package/dist/core/middleware/ContextDerivation.d.ts

@@ -0,0 +1,124 @@
+/**
+ * defineMiddleware() — Context Derivation (tRPC-style)
+ *
+ * Middlewares that return data have that data merged into the context
+ * for downstream handlers. TypeScript infers the derived context type
+ * automatically, so removing a middleware causes a compile error
+ * if the handler accesses properties that middleware provided.
+ *
+ * @example
+ * ```typescript
+ * const requireAuth = defineMiddleware(async (ctx: BaseCtx) => {
+ *     const user = await db.getUser(ctx.token);
+ *     if (!user) throw new Error('Unauthorized');
+ *     return { user };  // ← TS infers: { user: User }
+ * });
+ *
+ * const billing = defineTool('billing', {
+ *     middleware: [requireAuth],
+ *     actions: {
+ *         refund: {
+ *             handler: async (ctx, args) => {
+ *                 // ctx.user EXISTS and is typed! ✅
+ *                 return success(`Refunded by ${ctx.user.id}`);
+ *             },
+ *         },
+ *     },
+ * });
+ * ```
+ *
+ * @module
+ */
+import { type MiddlewareFn } from '../types.js';
+/**
+ * A middleware definition that derives additional context.
+ *
+ * The `derive` function receives the current context and returns
+ * an object whose properties are merged into the context for
+ * downstream middleware and the final handler.
+ *
+ * @typeParam TContextIn - The input context type
+ * @typeParam TDerived - The derived properties to merge
+ */
+export interface MiddlewareDefinition<TContextIn, TDerived extends Record<string, unknown>> {
+    /** Brand for type discrimination */
+    readonly __brand: 'MiddlewareDefinition';
+    /** The derive function */
+    readonly derive: (ctx: TContextIn) => Promise<TDerived> | TDerived;
+    /**
+     * Convert to a standard MiddlewareFn for use in existing pipelines.
+     * The derived properties are merged into `ctx` before calling `next()`.
+     */
+    readonly toMiddlewareFn: () => MiddlewareFn<TContextIn>;
+}
+/**
+ * Utility type: merge a base context with derived properties.
+ *
+ * @example
+ * ```typescript
+ * type Base = { token: string };
+ * type Derived = { user: User };
+ * type Result = MergeContext<Base, Derived>;
+ * // Result = { token: string; user: User }
+ * ```
+ */
+export type MergeContext<TBase, TDerived> = TBase & TDerived;
+/**
+ * Utility type: infer the output context from a MiddlewareDefinition.
+ *
+ * @example
+ * ```typescript
+ * const auth = defineMiddleware(async (ctx: Base) => ({ user }));
+ * type Ctx = InferContextOut<Base, typeof auth>;
+ * // Ctx = Base & { user: User }
+ * ```
+ */
+export type InferContextOut<TContextIn, TMw extends MiddlewareDefinition<TContextIn, Record<string, unknown>>> = TMw extends MiddlewareDefinition<TContextIn, infer TDerived> ? TContextIn & TDerived : never;
+/**
+ * Define a context-deriving middleware.
+ *
+ * The returned object can be used in two ways:
+ * 1. As a type-level constraint (the generics carry the derived context)
+ * 2. As a runtime middleware via `.toMiddlewareFn()` (for the existing pipeline)
+ *
+ * @typeParam TContextIn - The input context type
+ * @typeParam TDerived - Auto-inferred derived properties
+ * @param derive - Function that inspects context and returns derived data
+ * @returns A {@link MiddlewareDefinition} with the derived type encoded
+ *
+ * @example
+ * ```typescript
+ * // Auth middleware that derives `user`
+ * const requireAuth = defineMiddleware(async (ctx: { token: string }) => {
+ *     const user = await db.getUser(ctx.token);
+ *     if (!user) throw new Error('Unauthorized');
+ *     return { user };
+ * });
+ *
+ * // Rate limit middleware that derives `rateLimitInfo`
+ * const rateLimit = defineMiddleware(async (ctx: { ip: string }) => {
+ *     const info = await checkRateLimit(ctx.ip);
+ *     if (info.exceeded) throw new Error('Rate limited');
+ *     return { rateLimitInfo: info };
+ * });
+ * ```
+ *
+ * @see {@link MiddlewareFn} for the standard middleware type
+ */
+export declare function defineMiddleware<TContextIn, TDerived extends Record<string, unknown>>(derive: (ctx: TContextIn) => Promise<TDerived> | TDerived): MiddlewareDefinition<TContextIn, TDerived>;
+/**
+ * Type guard: check if a value is a MiddlewareDefinition.
+ *
+ * Used internally to auto-convert MiddlewareDefinitions to MiddlewareFns
+ * when passed to `defineTool({ middleware: [...] })`.
+ *
+ * @internal
+ */
+export declare function isMiddlewareDefinition<TContext>(value: unknown): value is MiddlewareDefinition<TContext, Record<string, unknown>>;
+/**
+ * Convert a middleware arg (either MiddlewareFn or MiddlewareDefinition) to MiddlewareFn.
+ *
+ * @internal
+ */
+export declare function resolveMiddleware<TContext>(mw: MiddlewareFn<TContext> | MiddlewareDefinition<TContext, Record<string, unknown>>): MiddlewareFn<TContext>;
+//# sourceMappingURL=ContextDerivation.d.ts.map

package/dist/core/middleware/ContextDerivation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContextDerivation.d.ts","sourceRoot":"","sources":["../../../src/core/middleware/ContextDerivation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAMhD;;;;;;;;;GASG;AACH,MAAM,WAAW,oBAAoB,CAAC,UAAU,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACtF,oCAAoC;IACpC,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAC;IACzC,0BAA0B;IAC1B,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,QAAQ,CAAC;IACnE;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,YAAY,CAAC,UAAU,CAAC,CAAC;CAC3D;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,YAAY,CAAC,KAAK,EAAE,QAAQ,IAAI,KAAK,GAAG,QAAQ,CAAC;AAE7D;;;;;;;;;GASG;AACH,MAAM,MAAM,eAAe,CACvB,UAAU,EACV,GAAG,SAAS,oBAAoB,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,IACrE,GAAG,SAAS,oBAAoB,CAAC,UAAU,EAAE,MAAM,QAAQ,CAAC,GAAG,UAAU,GAAG,QAAQ,GAAG,KAAK,CAAC;AAMjG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,gBAAgB,CAC5B,UAAU,EACV,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAExC,MAAM,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,QAAQ,GAC1D,oBAAoB,CAAC,UAAU,EAAE,QAAQ,CAAC,CAwB5C;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAC3C,KAAK,EAAE,OAAO,GACf,KAAK,IAAI,oBAAoB,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAOlE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EACtC,EAAE,EAAE,YAAY,CAAC,QAAQ,CAAC,GAAG,oBAAoB,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACrF,YAAY,CAAC,QAAQ,CAAC,CAKxB"}