@vurb/core 3.2.0

package/dist/core/registry/ToolRegistry.js

@@ -0,0 +1,343 @@
+/**
+ * ToolRegistry — Centralized Tool Registration & Routing
+ *
+ * The single place where all tool builders are registered and where
+ * incoming MCP calls are routed to the correct handler.
+ *
+ * @example
+ * ```typescript
+ * import { ToolRegistry, createTool, success } from 'vurb';
+ *
+ * const registry = new ToolRegistry<AppContext>();
+ *
+ * registry.register(
+ *     createTool<AppContext>('projects').action({ name: 'list', handler: listProjects }),
+ * );
+ *
+ * // Attach to any MCP server (duck-typed):
+ * const detach = registry.attachToServer(server, {
+ *     contextFactory: (extra) => createAppContext(extra),
+ * });
+ *
+ * // Clean teardown (e.g. in tests):
+ * detach();
+ * ```
+ *
+ * @see {@link createTool} for building tools
+ * @see {@link GroupedToolBuilder} for the builder API
+ *
+ * @module
+ */
+import {} from '@modelcontextprotocol/sdk/types.js';
+import { toolError } from '../response.js';
+import {} from '../types.js';
+import {} from '../../observability/DebugObserver.js';
+import {} from '../../observability/TelemetryEvent.js';
+import { SpanStatusCode } from '../../observability/Tracing.js';
+import { filterTools } from './ToolFilterEngine.js';
+import { attachToServer as attachToServerStrategy, } from '../../server/ServerAttachment.js';
+import {} from '../execution/ProgressHelper.js';
+// ============================================================================
+// ToolRegistry
+// ============================================================================
+/**
+ * Centralized registry for MCP tool builders.
+ *
+ * Manages tool registration, filtered retrieval, call routing,
+ * and MCP server attachment.
+ *
+ * @typeParam TContext - Application context type shared across all tools
+ *
+ * @example
+ * ```typescript
+ * const registry = new ToolRegistry<AppContext>();
+ *
+ * // Register individually
+ * registry.register(projectsTool);
+ *
+ * // Register multiple at once
+ * registry.registerAll(usersTool, billingTool, adminTool);
+ *
+ * // Query registered tools
+ * registry.has('projects');  // true
+ * registry.size;             // 4
+ * ```
+ */
+export class ToolRegistry {
+    _builders = new Map();
+    _debug;
+    _tracer;
+    _telemetrySink;
+    /**
+     * Register a single tool builder.
+     *
+     * Validates that the tool name is unique and triggers
+     * {@link GroupedToolBuilder.buildToolDefinition} to compile
+     * the tool definition at registration time.
+     *
+     * @param builder - A built or unbuilt tool builder
+     * @throws If a tool with the same name is already registered
+     *
+     * @example
+     * ```typescript
+     * registry.register(
+     *     createTool<AppContext>('projects')
+     *         .action({ name: 'list', handler: listProjects })
+     * );
+     * ```
+     */
+    register(builder) {
+        const name = builder.getName();
+        if (this._builders.has(name)) {
+            throw new Error(`Tool "${name}" is already registered.`);
+        }
+        builder.buildToolDefinition();
+        this._builders.set(name, builder);
+        // Propagate active observability features to the new builder (Bug #12)
+        this._propagateObservability(builder);
+    }
+    /**
+     * Register multiple tool builders at once.
+     *
+     * @param builders - One or more tool builders
+     *
+     * @example
+     * ```typescript
+     * registry.registerAll(usersTool, projectsTool, billingTool);
+     * ```
+     */
+    registerAll(...builders) {
+        for (const builder of builders) {
+            this.register(builder);
+        }
+    }
+    /**
+     * Get all registered MCP tool definitions.
+     *
+     * Returns the compiled `McpTool` objects for all registered builders.
+     *
+     * @returns Array of MCP Tool objects
+     */
+    getAllTools() {
+        const tools = [];
+        for (const builder of this._builders.values()) {
+            tools.push(builder.buildToolDefinition());
+        }
+        return tools;
+    }
+    /**
+     * Get an iterable of all registered tool builders.
+     *
+     * Used by the introspection module to extract action
+     * metadata and presenter information from each builder.
+     *
+     * @returns Iterable of registered ToolBuilder instances
+     */
+    getBuilders() {
+        return this._builders.values();
+    }
+    /**
+     * Get tool definitions filtered by tags.
+     *
+     * Uses the {@link ToolFilter} to include/exclude tools
+     * based on their capability tags.
+     *
+     * @param filter - Tag-based filter configuration
+     * @returns Filtered array of MCP Tool objects
+     *
+     * @example
+     * ```typescript
+     * // Only core tools
+     * const coreTools = registry.getTools({ tags: ['core'] });
+     *
+     * // Everything except internal tools
+     * const publicTools = registry.getTools({ exclude: ['internal'] });
+     * ```
+     *
+     * @see {@link ToolFilter} for filter options
+     */
+    getTools(filter) {
+        return filterTools(this._builders.values(), filter);
+    }
+    /**
+     * Route an incoming tool call to the correct builder.
+     *
+     * Looks up the builder by name and delegates to its `execute()` method.
+     * Returns an error response if the tool is not found.
+     *
+     * @param ctx - Application context
+     * @param name - Tool name from the incoming MCP call
+     * @param args - Raw arguments from the LLM
+     * @param progressSink - Optional callback for streaming progress notifications.
+     *   When called from `attachToServer()`, this is automatically wired to
+     *   MCP `notifications/progress`. When omitted, progress events are silently consumed.
+     * @returns The handler's response
+     *
+     * @example
+     * ```typescript
+     * const response = await registry.routeCall(ctx, 'projects', {
+     *     action: 'list',
+     *     workspace_id: 'ws_123',
+     * });
+     * ```
+     */
+    async routeCall(ctx, name, args, progressSink, signal) {
+        const builder = this._builders.get(name);
+        if (!builder) {
+            if (this._tracer) {
+                const span = this._tracer.startSpan(`mcp.tool.${name}`, {
+                    attributes: { 'mcp.system': 'vurb', 'mcp.tool': name, 'mcp.error_type': 'unknown_tool' },
+                });
+                span.setStatus({ code: SpanStatusCode.UNSET, message: `Unknown tool: "${name}"` });
+                span.end();
+            }
+            if (this._debug) {
+                this._debug({ type: 'error', tool: name, action: '?', error: `Unknown tool: "${name}"`, step: 'route', timestamp: Date.now() });
+            }
+            return toolError('UNKNOWN_TOOL', {
+                message: `Tool "${name}" does not exist.`,
+                suggestion: 'Check the available tools via tools/list and call a valid one.',
+            });
+        }
+        return builder.execute(ctx, args, progressSink, signal);
+    }
+    /**
+     * Attach this registry to an MCP server.
+     *
+     * Registers `tools/list` and `tools/call` handlers on the server.
+     * Supports both `McpServer` (high-level SDK) and `Server` (low-level SDK)
+     * via duck-type detection.
+     *
+     * @param server - Any MCP server instance (duck-typed)
+     * @param options - Attachment options (context factory, tag filter)
+     * @returns A detach function for clean teardown
+     *
+     * @example
+     * ```typescript
+     * // Basic attachment
+     * const detach = registry.attachToServer(server, {
+     *     contextFactory: (extra) => createAppContext(extra),
+     * });
+     *
+     * // With tag filtering
+     * registry.attachToServer(server, {
+     *     contextFactory: (extra) => createAppContext(extra),
+     *     filter: { tags: ['core'] },
+     * });
+     *
+     * // Clean teardown (e.g. in tests)
+     * detach();
+     * ```
+     *
+     * @see {@link DetachFn} for the teardown function type
+     * @see {@link AttachOptions} for all options
+     */
+    async attachToServer(server, options = {}) {
+        return attachToServerStrategy(server, this, options);
+    }
+    /** Check if a tool with the given name is registered. */
+    has(name) { return this._builders.has(name); }
+    /** Remove all registered tools. */
+    clear() { this._builders.clear(); }
+    /** Number of registered tools. */
+    get size() { return this._builders.size; }
+    /**
+     * Enable debug observability for ALL registered tools.
+     *
+     * Propagates the debug observer to every registered builder that
+     * supports it (duck-typed via `.debug()` method).
+     *
+     * Also enables registry-level debug events (unknown tool errors).
+     *
+     * @param observer - A {@link DebugObserverFn} created by `createDebugObserver()`
+     *
+     * @example
+     * ```typescript
+     * const debug = createDebugObserver();
+     * registry.enableDebug(debug);
+     * // Now ALL tools + registry routing emit debug events
+     * ```
+     */
+    enableDebug(observer) {
+        if (this._tracer) {
+            console.warn('[vurb] Both tracing and debug are enabled. Tracing takes precedence; debug events will not be emitted.');
+        }
+        this._debug = observer;
+        for (const builder of this._builders.values()) {
+            // Duck-type: call .debug() if it exists on the builder
+            if ('debug' in builder && typeof builder.debug === 'function') {
+                builder.debug(observer);
+            }
+        }
+    }
+    /**
+     * Enable OpenTelemetry-compatible tracing for ALL registered tools.
+     *
+     * Propagates the tracer to every registered builder that supports
+     * it (duck-typed via `.tracing()` method).
+     *
+     * Also enables registry-level tracing for unknown tool routing errors.
+     *
+     * **Important**: When both `enableDebug()` and `enableTracing()` are active,
+     * tracing takes precedence and debug events are NOT emitted from tool builders.
+     *
+     * @param tracer - A {@link VurbTracer} (or OTel `Tracer`) instance
+     *
+     * @example
+     * ```typescript
+     * import { trace } from '@opentelemetry/api';
+     *
+     * const tracer = trace.getTracer('vurb');
+     * registry.enableTracing(tracer);
+     * // Now ALL tools + registry routing emit OTel spans
+     * ```
+     *
+     * @see {@link VurbTracer} for the tracer interface contract
+     * @see {@link SpanStatusCode} for status code semantics
+     */
+    enableTracing(tracer) {
+        if (this._debug) {
+            console.warn('[vurb] Both tracing and debug are enabled. Tracing takes precedence; debug events will not be emitted.');
+        }
+        this._tracer = tracer;
+        for (const builder of this._builders.values()) {
+            // Duck-type: call .tracing() if it exists on the builder
+            if ('tracing' in builder && typeof builder.tracing === 'function') {
+                builder.tracing(tracer);
+            }
+        }
+    }
+    /**
+     * Enable telemetry emission for ALL registered tools.
+     *
+     * Propagates the TelemetrySink to every registered builder that supports
+     * it (duck-typed via `.telemetry()` method). This enables real-time
+     * event emission to the Inspector TUI via Shadow Socket IPC.
+     *
+     * @param sink - A {@link TelemetrySink} from `startServer()` or `TelemetryBus`
+     */
+    enableTelemetry(sink) {
+        this._telemetrySink = sink;
+        for (const builder of this._builders.values()) {
+            if ('telemetry' in builder && typeof builder.telemetry === 'function') {
+                builder.telemetry(sink);
+            }
+        }
+    }
+    /**
+     * Propagate active debug/tracing/telemetry to a newly registered builder.
+     * @internal
+     */
+    _propagateObservability(builder) {
+        if (this._debug && 'debug' in builder && typeof builder.debug === 'function') {
+            builder.debug(this._debug);
+        }
+        if (this._tracer && 'tracing' in builder && typeof builder.tracing === 'function') {
+            builder.tracing(this._tracer);
+        }
+        if (this._telemetrySink && 'telemetry' in builder && typeof builder.telemetry === 'function') {
+            builder.telemetry(this._telemetrySink);
+        }
+    }
+}
+//# sourceMappingURL=ToolRegistry.js.map

package/dist/core/registry/ToolRegistry.js.map

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

package/dist/core/registry/index.d.ts

@@ -0,0 +1,4 @@
+/** Registry Bounded Context — Barrel Export */
+export { ToolRegistry } from './ToolRegistry.js';
+export type { ToolFilter } from './ToolFilterEngine.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/registry/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/registry/index.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,YAAY,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/core/registry/index.js

@@ -0,0 +1,3 @@
+/** Registry Bounded Context — Barrel Export */
+export { ToolRegistry } from './ToolRegistry.js';
+//# sourceMappingURL=index.js.map

package/dist/core/registry/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/registry/index.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/core/response.d.ts

@@ -0,0 +1,289 @@
+/**
+ * Response Helpers
+ *
+ * Universal MCP response builders. No API coupling.
+ * These produce the standard MCP ToolResponse format.
+ *
+ * @example
+ * ```typescript
+ * import { success, error, toonSuccess } from 'vurb';
+ *
+ * // String response
+ * return success('Project created');
+ *
+ * // Object response (auto JSON.stringify)
+ * return success({ id: '123', name: 'My Project' });
+ *
+ * // Error response
+ * return error('Project not found');
+ *
+ * // TOON-encoded response (~40% fewer tokens)
+ * return toonSuccess(users);
+ * ```
+ *
+ * @see {@link ToolResponse} for the response shape
+ * @see {@link toonSuccess} for token-optimized responses
+ *
+ * @module
+ */
+import { type EncodeOptions } from '@toon-format/toon';
+import { type StringifyFn } from './serialization/JsonSerializer.js';
+/**
+ * Non-enumerable brand symbol stamped on all helper-created ToolResponse objects.
+ * Used by FluentToolBuilder to reliably distinguish framework responses from
+ * domain data that coincidentally matches the ToolResponse shape (Bug #127).
+ *
+ * @internal
+ */
+export declare const TOOL_RESPONSE_BRAND: unique symbol;
+/**
+ * Escape XML structural characters for element content.
+ *
+ * Only `&` and `<` are mandatory escapes in XML element content.
+ * `>` is preserved for LLM readability (e.g. `>= 1`, `Must be > 0`).
+ * Single and double quotes are also preserved since they have no
+ * special meaning outside attribute values.
+ *
+ * @internal
+ */
+export declare function escapeXml(str: string): string;
+/**
+ * Escape XML special characters for use inside attribute values.
+ *
+ * Attribute values are delimited by `"` or `'` and must also
+ * escape `<`, `>`, and `&`. All 5 XML special characters are handled.
+ *
+ * @internal
+ */
+export declare function escapeXmlAttr(str: string): string;
+/**
+ * Standard MCP tool response.
+ *
+ * Every handler in vurb must return this shape.
+ * Use the helper functions ({@link success}, {@link error}, {@link toonSuccess})
+ * instead of constructing this manually.
+ *
+ * @example
+ * ```typescript
+ * // ✅ Preferred — use helpers
+ * return success({ id: '123', name: 'Acme' });
+ *
+ * // ⚠️ Manual construction (avoid unless custom content types needed)
+ * const response: ToolResponse = {
+ *     content: [{ type: 'text', text: 'Hello' }],
+ * };
+ * ```
+ */
+export interface ToolResponse {
+    readonly content: ReadonlyArray<{
+        readonly type: "text";
+        readonly text: string;
+    }>;
+    readonly isError?: boolean;
+}
+/**
+ * Create a success response from text or a JSON-serializable object.
+ *
+ * - Strings are returned verbatim (empty strings become `"OK"`)
+ * - Objects are serialized with `JSON.stringify(data, null, 2)`
+ *
+ * @param data - A string message or any JSON-serializable object
+ * @returns A {@link ToolResponse} with `isError` unset
+ *
+ * @example
+ * ```typescript
+ * // String response
+ * return success('Task completed');
+ *
+ * // Object response (pretty-printed JSON)
+ * const project = await db.projects.create({ name: 'Acme' });
+ * return success(project);
+ *
+ * // Array response
+ * const users = await db.users.findMany();
+ * return success(users);
+ * ```
+ *
+ * @see {@link error} for error responses
+ * @see {@link toonSuccess} for token-optimized array responses
+ */
+export declare function success(data: string | object, compiledStringify?: StringifyFn): ToolResponse;
+/**
+ * Create an error response.
+ *
+ * Sets `isError: true` so the MCP client and LLM recognize the failure.
+ * The LLM will typically retry or ask the user for clarification.
+ *
+ * @param message - Human-readable error description
+ * @returns A {@link ToolResponse} with `isError: true`
+ *
+ * @example
+ * ```typescript
+ * // Simple error
+ * return error('Project not found');
+ *
+ * // Contextual error
+ * return error(`User "${userId}" does not have access to workspace "${wsId}"`);
+ *
+ * // In a handler with early return
+ * handler: async (ctx, args) => {
+ *     const project = await ctx.db.projects.findUnique(args.id);
+ *     if (!project) return error(`Project "${args.id}" not found`);
+ *     return success(project);
+ * }
+ * ```
+ *
+ * @see {@link required} for missing field errors
+ * @see {@link success} for success responses
+ */
+export declare function error(message: string, code?: ErrorCode): ToolResponse;
+/**
+ * Create a validation error for a missing required field.
+ *
+ * Convenience shortcut for `error(\`Error: ${field} required\`)`.
+ * Typically used in handlers that accept dynamic or optional schemas.
+ *
+ * @param field - Name of the missing required field
+ * @returns A {@link ToolResponse} with `isError: true`
+ *
+ * @example
+ * ```typescript
+ * handler: async (ctx, args) => {
+ *     if (!args.workspace_id) return required('workspace_id');
+ *     // ...
+ * }
+ * ```
+ *
+ * @see {@link error} for general error responses
+ */
+export declare function required(field: string): ToolResponse;
+/**
+ * Create a success response with TOON-encoded payload.
+ *
+ * Encodes structured data using TOON (Token-Oriented Object Notation)
+ * for ~40-50% token reduction compared to `JSON.stringify()`.
+ * Ideal for list/tabular responses (arrays of uniform objects).
+ *
+ * @param data - Any JSON-serializable value (objects, arrays, primitives)
+ * @param options - Optional TOON encode options (default: pipe delimiter)
+ * @returns A {@link ToolResponse} with TOON-encoded text
+ *
+ * @example
+ * ```typescript
+ * // Array response — saves ~40% tokens vs JSON
+ * const users = await db.users.findMany();
+ * return toonSuccess(users);
+ * // Output: "id|name|email\n1|Alice|alice@co.io\n2|Bob|bob@co.io"
+ *
+ * // With custom delimiter
+ * return toonSuccess(data, { delimiter: ',' });
+ *
+ * // Single object (still valid, but savings are smaller)
+ * return toonSuccess({ id: 1, name: 'Alice' });
+ * ```
+ *
+ * @see {@link success} for standard JSON responses
+ */
+export declare function toonSuccess(data: unknown, options?: EncodeOptions): ToolResponse;
+/**
+ * Canonical error codes for deterministic agent self-correction.
+ *
+ * Provides compile-time autocomplete while allowing custom codes
+ * via the `string` fallback. Constants cover the most common
+ * failure modes in agentic pipelines.
+ *
+ * @example
+ * ```typescript
+ * return toolError('VALIDATION_ERROR', { message: '...' });
+ * return toolError('RateLimited', { message: '...' }); // custom code — also valid
+ * ```
+ */
+export type ErrorCode = 'MISSING_DISCRIMINATOR' | 'UNKNOWN_ACTION' | 'VALIDATION_ERROR' | 'MISSING_REQUIRED_FIELD' | 'INTERNAL_ERROR' | 'RATE_LIMITED' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'NOT_FOUND' | 'CONFLICT' | 'TIMEOUT' | 'SERVER_BUSY' | 'DEPRECATED' | 'AUTH_REQUIRED' | (string & {});
+/**
+ * Error severity level.
+ *
+ * - `'warning'`  — Non-fatal. The operation succeeded but with caveats
+ *   (e.g. deprecated tool, partial results, soft quota approaching).
+ * - `'error'`    — The operation failed. Agent should attempt recovery.
+ * - `'critical'` — Unrecoverable. Agent should escalate to the user.
+ */
+export type ErrorSeverity = 'warning' | 'error' | 'critical';
+/**
+ * Options for a self-healing error response.
+ *
+ * @see {@link toolError} for usage
+ */
+export interface ToolErrorOptions {
+    /** Human-readable error description */
+    message: string;
+    /** Recovery suggestion for the LLM agent */
+    suggestion?: string;
+    /** Action names the agent should try instead */
+    availableActions?: string[];
+    /**
+     * Error severity.
+     *
+     * Defaults to `'error'` when omitted.
+     *
+     * @example `'warning'` for deprecation notices
+     */
+    severity?: ErrorSeverity;
+    /**
+     * Structured metadata about the error (e.g. the invalid value,
+     * the entity ID that wasn't found, or constraint violations).
+     *
+     * Rendered as `<details>` child elements in the XML envelope.
+     *
+     * @example `{ entity_id: 'inv_123', expected_type: 'string' }`
+     */
+    details?: Record<string, string>;
+    /**
+     * Suggested retry delay in seconds for transient errors.
+     *
+     * Rendered as `<retry_after>{n} seconds</retry_after>` in the
+     * XML envelope. Useful for rate-limit and concurrency errors.
+     */
+    retryAfter?: number;
+}
+/**
+ * Create a self-healing error response with recovery instructions.
+ *
+ * Unlike {@link error}, this provides structured guidance so the LLM
+ * agent can self-correct instead of hallucinating or giving up.
+ * The response includes an error code, message, suggestion, and
+ * available actions — all formatted for optimal LLM comprehension.
+ *
+ * @param code - Short error code (e.g. `'ProjectNotFound'`, `'Unauthorized'`)
+ * @param options - Error details and recovery instructions
+ * @returns A {@link ToolResponse} with `isError: true` and recovery guidance
+ *
+ * @example
+ * ```typescript
+ * handler: async (ctx, args) => {
+ *     const project = await ctx.db.get(args.project_id);
+ *
+ *     if (!project) {
+ *         return toolError('ProjectNotFound', {
+ *             message: `Project '${args.project_id}' does not exist.`,
+ *             suggestion: 'Call projects.list first to get valid IDs, then retry.',
+ *             availableActions: ['projects.list'],
+ *         });
+ *     }
+ *
+ *     return success(project);
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Minimal usage (no suggestion)
+ * return toolError('RateLimited', {
+ *     message: 'Too many requests. Wait 30 seconds.',
+ * });
+ * ```
+ *
+ * @see {@link error} for simple error responses
+ * @see {@link required} for missing field errors
+ */
+export declare function toolError(code: ErrorCode, options: ToolErrorOptions): ToolResponse;
+//# sourceMappingURL=response.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../src/core/response.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EAAU,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,mCAAmC,CAAC;AAErE;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,EAAE,OAAO,MAAwC,CAAC;AAMlF;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI7C;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAOjD;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,YAAY;IACzB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClF,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC9B;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,iBAAiB,CAAC,EAAE,WAAW,GAAG,YAAY,CAO5F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,SAAS,GAAG,YAAY,CAQrE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAWpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,YAAY,CAMhF;AAMD;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,SAAS,GACf,uBAAuB,GACvB,gBAAgB,GAChB,kBAAkB,GAClB,wBAAwB,GACxB,gBAAgB,GAChB,cAAc,GACd,cAAc,GACd,WAAW,GACX,WAAW,GACX,UAAU,GACV,SAAS,GACT,aAAa,GACb,YAAY,GACZ,eAAe,GACf,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAEpB;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,OAAO,GAAG,UAAU,CAAC;AAE7D;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC7B,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,gBAAgB,GAAG,YAAY,CAuClF"}