@predicatelabs/sdk 0.99.9

package/dist/utils/llm-response-builder.js

@@ -0,0 +1,130 @@
+"use strict";
+/**
+ * LLMResponseBuilder - Helper for consistent LLM response building
+ *
+ * Provides standardized response building and error handling across LLM providers
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LLMResponseBuilder = void 0;
+/**
+ * LLMResponseBuilder provides static methods for building and validating LLM responses
+ */
+class LLMResponseBuilder {
+    /**
+     * Build a standardized LLMResponse from provider-specific response data
+     *
+     * @param content - Response content text
+     * @param modelName - Model name/identifier
+     * @param usage - Token usage data (provider-specific format)
+     * @param providerType - Provider type for usage extraction
+     * @returns Standardized LLMResponse
+     *
+     * @example
+     * ```typescript
+     * // OpenAI format
+     * const response = LLMResponseBuilder.build(
+     *   'CLICK(1)',
+     *   'gpt-4o',
+     *   { prompt_tokens: 100, completion_tokens: 20, total_tokens: 120 },
+     *   'openai'
+     * );
+     *
+     * // Anthropic format
+     * const response = LLMResponseBuilder.build(
+     *   'CLICK(1)',
+     *   'claude-3-5-sonnet',
+     *   { input_tokens: 100, output_tokens: 20 },
+     *   'anthropic'
+     * );
+     * ```
+     */
+    static build(content, modelName, usage, providerType = 'generic') {
+        let promptTokens;
+        let completionTokens;
+        let totalTokens;
+        switch (providerType) {
+            case 'openai':
+                promptTokens = usage?.prompt_tokens;
+                completionTokens = usage?.completion_tokens;
+                totalTokens = usage?.total_tokens;
+                break;
+            case 'anthropic':
+                promptTokens = usage?.input_tokens;
+                completionTokens = usage?.output_tokens;
+                totalTokens = (usage?.input_tokens || 0) + (usage?.output_tokens || 0);
+                break;
+            case 'glm':
+                promptTokens = usage?.prompt_tokens;
+                completionTokens = usage?.completion_tokens;
+                totalTokens = usage?.total_tokens;
+                break;
+            case 'gemini':
+                promptTokens = usage?.promptTokenCount;
+                completionTokens = usage?.candidatesTokenCount;
+                totalTokens = usage?.totalTokenCount;
+                break;
+            case 'generic':
+            default:
+                // Try common field names
+                promptTokens = usage?.prompt_tokens || usage?.input_tokens || usage?.promptTokenCount;
+                completionTokens =
+                    usage?.completion_tokens || usage?.output_tokens || usage?.candidatesTokenCount;
+                totalTokens =
+                    usage?.total_tokens ||
+                        usage?.totalTokenCount ||
+                        (promptTokens || 0) + (completionTokens || 0);
+                break;
+        }
+        return {
+            content: content || '',
+            promptTokens,
+            completionTokens,
+            totalTokens,
+            modelName,
+        };
+    }
+    /**
+     * Validate that an LLMResponse has required fields
+     *
+     * @param response - LLMResponse to validate
+     * @returns True if valid, false otherwise
+     */
+    static validate(response) {
+        if (!response || typeof response.content !== 'string') {
+            return false;
+        }
+        if (response.modelName && typeof response.modelName !== 'string') {
+            return false;
+        }
+        // Token counts are optional but should be numbers if present
+        if (response.promptTokens !== undefined && typeof response.promptTokens !== 'number') {
+            return false;
+        }
+        if (response.completionTokens !== undefined && typeof response.completionTokens !== 'number') {
+            return false;
+        }
+        if (response.totalTokens !== undefined && typeof response.totalTokens !== 'number') {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Create an error response
+     *
+     * @param error - Error message or Error object
+     * @param modelName - Optional model name
+     * @returns LLMResponse with error content
+     */
+    static createErrorResponse(error, modelName) {
+        const errorMessage = error instanceof Error ? error.message : error;
+        return {
+            content: `Error: ${errorMessage}`,
+            modelName: modelName || 'unknown',
+            promptTokens: 0,
+            completionTokens: 0,
+            totalTokens: 0,
+        };
+    }
+}
+exports.LLMResponseBuilder = LLMResponseBuilder;
+//# sourceMappingURL=llm-response-builder.js.map

package/dist/utils/llm-response-builder.js.map

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

package/dist/utils/selector-utils.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Utility functions for working with QuerySelector
+ */
+import { QuerySelector } from '../types';
+/**
+ * Convert a QuerySelector to a string representation for error messages
+ *
+ * @param selector - QuerySelector (string or object)
+ * @returns String representation
+ */
+export declare function selectorToString(selector: QuerySelector): string;
+//# sourceMappingURL=selector-utils.d.ts.map

package/dist/utils/selector-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selector-utils.d.ts","sourceRoot":"","sources":["../../src/utils/selector-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,CAgBhE"}

package/dist/utils/selector-utils.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * Utility functions for working with QuerySelector
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectorToString = selectorToString;
+/**
+ * Convert a QuerySelector to a string representation for error messages
+ *
+ * @param selector - QuerySelector (string or object)
+ * @returns String representation
+ */
+function selectorToString(selector) {
+    if (typeof selector === 'string') {
+        return selector;
+    }
+    // Convert QuerySelectorObject to string representation
+    const obj = selector;
+    const parts = [];
+    if (obj.role)
+        parts.push(`role=${obj.role}`);
+    if (obj.text)
+        parts.push(`text="${obj.text}"`);
+    if (obj.name)
+        parts.push(`name="${obj.name}"`);
+    if (obj.clickable !== undefined)
+        parts.push(`clickable=${obj.clickable}`);
+    if (obj.isPrimary !== undefined)
+        parts.push(`isPrimary=${obj.isPrimary}`);
+    return parts.length > 0 ? parts.join(' ') : JSON.stringify(obj);
+}
+//# sourceMappingURL=selector-utils.js.map

package/dist/utils/selector-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selector-utils.js","sourceRoot":"","sources":["../../src/utils/selector-utils.ts"],"names":[],"mappings":";AAAA;;GAEG;;AAUH,4CAgBC;AAtBD;;;;;GAKG;AACH,SAAgB,gBAAgB,CAAC,QAAuB;IACtD,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACjC,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,uDAAuD;IACvD,MAAM,GAAG,GAAG,QAAQ,CAAC;IACrB,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,IAAI,GAAG,CAAC,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;IAC7C,IAAI,GAAG,CAAC,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,SAAS,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC;IAC/C,IAAI,GAAG,CAAC,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,SAAS,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC;IAC/C,IAAI,GAAG,CAAC,SAAS,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,aAAa,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC;IAC1E,IAAI,GAAG,CAAC,SAAS,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,aAAa,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC;IAE1E,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;AAClE,CAAC"}

package/dist/utils/snapshot-event-builder.d.ts

@@ -0,0 +1,28 @@
+/**
+ * SnapshotEventBuilder - Helper for building snapshot trace events
+ *
+ * Extracted from SentienceAgent to reduce complexity
+ */
+import { Snapshot } from '../types';
+import { TraceEventData } from '../tracing/types';
+/**
+ * SnapshotEventBuilder provides static methods for building snapshot trace events
+ */
+export declare class SnapshotEventBuilder {
+    /**
+     * Build snapshot trace event data from snapshot
+     *
+     * @param snap - Snapshot to build event from
+     * @param stepId - Optional step ID
+     * @returns Trace event data for snapshot
+     */
+    static buildSnapshotEventData(snap: Snapshot, stepId?: string): TraceEventData;
+    /**
+     * Extract base64 string from screenshot data URL
+     *
+     * @param screenshot - Screenshot data URL or base64 string
+     * @returns Base64 string without data URL prefix
+     */
+    private static extractScreenshotBase64;
+}
+//# sourceMappingURL=snapshot-event-builder.d.ts.map

package/dist/utils/snapshot-event-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-event-builder.d.ts","sourceRoot":"","sources":["../../src/utils/snapshot-event-builder.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,EAAE,cAAc,EAAgB,MAAM,kBAAkB,CAAC;AAEhE;;GAEG;AACH,qBAAa,oBAAoB;IAC/B;;;;;;OAMG;IACH,MAAM,CAAC,sBAAsB,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,cAAc;IA2D9E;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,uBAAuB;CAOvC"}

package/dist/utils/snapshot-event-builder.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * SnapshotEventBuilder - Helper for building snapshot trace events
+ *
+ * Extracted from SentienceAgent to reduce complexity
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SnapshotEventBuilder = void 0;
+/**
+ * SnapshotEventBuilder provides static methods for building snapshot trace events
+ */
+class SnapshotEventBuilder {
+    /**
+     * Build snapshot trace event data from snapshot
+     *
+     * @param snap - Snapshot to build event from
+     * @param stepId - Optional step ID
+     * @returns Trace event data for snapshot
+     */
+    static buildSnapshotEventData(snap, stepId) {
+        // Normalize importance values to importance_score (0-1 range) per snapshot
+        const importanceValues = snap.elements.map(el => el.importance);
+        const minImportance = importanceValues.length > 0 ? Math.min(...importanceValues) : 0;
+        const maxImportance = importanceValues.length > 0 ? Math.max(...importanceValues) : 0;
+        const importanceRange = maxImportance - minImportance;
+        // Include ALL elements with full data for DOM tree display
+        const elements = snap.elements.map(el => {
+            // Compute normalized importance_score
+            let importanceScore;
+            if (importanceRange > 0) {
+                importanceScore = (el.importance - minImportance) / importanceRange;
+            }
+            else {
+                // If all elements have same importance, set to 0.5
+                importanceScore = 0.5;
+            }
+            return {
+                id: el.id,
+                role: el.role,
+                text: el.text,
+                bbox: el.bbox,
+                importance: el.importance,
+                importance_score: importanceScore,
+                visual_cues: el.visual_cues,
+                in_viewport: el.in_viewport,
+                is_occluded: el.is_occluded,
+                z_index: el.z_index,
+                fused_rank_index: el.fused_rank_index,
+                heuristic_index: el.heuristic_index,
+                ml_probability: el.ml_probability,
+                ml_score: el.ml_score,
+                diff_status: el.diff_status,
+            };
+        });
+        const snapshotData = {
+            url: snap.url,
+            element_count: snap.elements.length,
+            timestamp: snap.timestamp,
+            elements,
+        };
+        if (stepId) {
+            snapshotData.step_id = stepId;
+        }
+        // Always include screenshot in trace event for studio viewer compatibility
+        if (snap.screenshot) {
+            snapshotData.screenshot_base64 = this.extractScreenshotBase64(snap.screenshot);
+            if (snap.screenshot_format) {
+                snapshotData.screenshot_format = snap.screenshot_format;
+            }
+        }
+        return snapshotData;
+    }
+    /**
+     * Extract base64 string from screenshot data URL
+     *
+     * @param screenshot - Screenshot data URL or base64 string
+     * @returns Base64 string without data URL prefix
+     */
+    static extractScreenshotBase64(screenshot) {
+        if (screenshot.startsWith('data:image')) {
+            // Format: "data:image/jpeg;base64,{base64_string}"
+            return screenshot.includes(',') ? screenshot.split(',', 2)[1] : screenshot;
+        }
+        return screenshot;
+    }
+}
+exports.SnapshotEventBuilder = SnapshotEventBuilder;
+//# sourceMappingURL=snapshot-event-builder.js.map

package/dist/utils/snapshot-event-builder.js.map

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

package/dist/utils/snapshot-processor.d.ts

@@ -0,0 +1,27 @@
+/**
+ * SnapshotProcessor - Helper for processing snapshots in agent
+ *
+ * Extracted from SentienceAgent to reduce complexity
+ */
+import { Snapshot } from '../types';
+export interface ProcessedSnapshot {
+    original: Snapshot;
+    withDiff: Snapshot;
+    filtered: Snapshot;
+}
+/**
+ * SnapshotProcessor provides static methods for processing snapshots
+ */
+export declare class SnapshotProcessor {
+    /**
+     * Process a snapshot: compute diff status, filter elements
+     *
+     * @param snap - Original snapshot
+     * @param previousSnapshot - Previous snapshot for diff computation
+     * @param goal - Goal/task description for filtering
+     * @param snapshotLimit - Maximum elements to include
+     * @returns Processed snapshot with diff status and filtered elements
+     */
+    static process(snap: Snapshot, previousSnapshot: Snapshot | undefined, goal: string, snapshotLimit: number): ProcessedSnapshot;
+}
+//# sourceMappingURL=snapshot-processor.d.ts.map

package/dist/utils/snapshot-processor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-processor.d.ts","sourceRoot":"","sources":["../../src/utils/snapshot-processor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAIpC,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,QAAQ,CAAC;IACnB,QAAQ,EAAE,QAAQ,CAAC;IACnB,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED;;GAEG;AACH,qBAAa,iBAAiB;IAC5B;;;;;;;;OAQG;IACH,MAAM,CAAC,OAAO,CACZ,IAAI,EAAE,QAAQ,EACd,gBAAgB,EAAE,QAAQ,GAAG,SAAS,EACtC,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,MAAM,GACpB,iBAAiB;CAyBrB"}

package/dist/utils/snapshot-processor.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * SnapshotProcessor - Helper for processing snapshots in agent
+ *
+ * Extracted from SentienceAgent to reduce complexity
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SnapshotProcessor = void 0;
+const snapshot_diff_1 = require("../snapshot-diff");
+const element_filter_1 = require("./element-filter");
+/**
+ * SnapshotProcessor provides static methods for processing snapshots
+ */
+class SnapshotProcessor {
+    /**
+     * Process a snapshot: compute diff status, filter elements
+     *
+     * @param snap - Original snapshot
+     * @param previousSnapshot - Previous snapshot for diff computation
+     * @param goal - Goal/task description for filtering
+     * @param snapshotLimit - Maximum elements to include
+     * @returns Processed snapshot with diff status and filtered elements
+     */
+    static process(snap, previousSnapshot, goal, snapshotLimit) {
+        // Compute diff_status by comparing with previous snapshot
+        const elementsWithDiff = snapshot_diff_1.SnapshotDiff.computeDiffStatus(snap, previousSnapshot);
+        // Create snapshot with diff_status populated
+        const snapWithDiff = {
+            ...snap,
+            elements: elementsWithDiff,
+        };
+        // Apply element filtering based on goal using ElementFilter
+        const filteredElements = element_filter_1.ElementFilter.filterByGoal(snapWithDiff, goal, snapshotLimit);
+        // Create filtered snapshot
+        const filteredSnap = {
+            ...snapWithDiff,
+            elements: filteredElements,
+        };
+        return {
+            original: snap,
+            withDiff: snapWithDiff,
+            filtered: filteredSnap,
+        };
+    }
+}
+exports.SnapshotProcessor = SnapshotProcessor;
+//# sourceMappingURL=snapshot-processor.js.map

package/dist/utils/snapshot-processor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-processor.js","sourceRoot":"","sources":["../../src/utils/snapshot-processor.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAGH,oDAAgD;AAChD,qDAAiD;AAQjD;;GAEG;AACH,MAAa,iBAAiB;IAC5B;;;;;;;;OAQG;IACH,MAAM,CAAC,OAAO,CACZ,IAAc,EACd,gBAAsC,EACtC,IAAY,EACZ,aAAqB;QAErB,0DAA0D;QAC1D,MAAM,gBAAgB,GAAG,4BAAY,CAAC,iBAAiB,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;QAEhF,6CAA6C;QAC7C,MAAM,YAAY,GAAa;YAC7B,GAAG,IAAI;YACP,QAAQ,EAAE,gBAAgB;SAC3B,CAAC;QAEF,4DAA4D;QAC5D,MAAM,gBAAgB,GAAG,8BAAa,CAAC,YAAY,CAAC,YAAY,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC;QAEvF,2BAA2B;QAC3B,MAAM,YAAY,GAAa;YAC7B,GAAG,YAAY;YACf,QAAQ,EAAE,gBAAgB;SAC3B,CAAC;QAEF,OAAO;YACL,QAAQ,EAAE,IAAI;YACd,QAAQ,EAAE,YAAY;YACtB,QAAQ,EAAE,YAAY;SACvB,CAAC;IACJ,CAAC;CACF;AAxCD,8CAwCC"}

package/dist/utils/trace-event-builder.d.ts

@@ -0,0 +1,122 @@
+/**
+ * TraceEventBuilder - Common trace event building patterns
+ *
+ * This utility class extracts common trace event building logic to reduce duplication
+ * and ensure consistency across different parts of the codebase.
+ */
+import { TraceEventData } from '../tracing/types';
+import { Snapshot } from '../types';
+import { AgentActResult } from '../agent';
+import { LLMResponse } from '../llm-provider';
+/**
+ * TraceEventBuilder provides static methods for building trace events
+ */
+export declare class TraceEventBuilder {
+    /**
+     * Compute SHA256 hash of text
+     *
+     * @param text - Text to hash
+     * @returns SHA256 hash as hex string
+     *
+     * @private
+     */
+    private static computeHash;
+    /**
+     * Build snapshot digest from snapshot data
+     *
+     * @param snapshot - Snapshot to compute digest for
+     * @returns Digest string in format "sha256:..."
+     */
+    static buildSnapshotDigest(snapshot: Snapshot): string;
+    /**
+     * Build LLM usage data from LLM response
+     *
+     * @param llmResponse - LLM response object
+     * @returns LLM usage data for trace event
+     */
+    static buildLLMData(llmResponse: LLMResponse): TraceEventData['llm'];
+    /**
+     * Build execution data from action result
+     *
+     * @param result - Agent action result
+     * @param snapshot - Snapshot used for the action
+     * @returns Execution data for trace event
+     */
+    static buildExecutionData(result: AgentActResult, snapshot: Snapshot): TraceEventData['exec'];
+    /**
+     * Build verify data from action result
+     *
+     * @param result - Agent action result
+     * @param snapshot - Snapshot used for the action
+     * @returns Verify data for trace event
+     */
+    static buildVerifyData(result: AgentActResult, snapshot: Snapshot): TraceEventData['verify'];
+    /**
+     * Build complete step_end event data
+     *
+     * @param params - Parameters for building step_end event
+     * @returns Complete step_end event data
+     */
+    static buildStepEndData(params: {
+        stepId: string;
+        stepIndex: number;
+        goal: string;
+        attempt: number;
+        preUrl: string;
+        postUrl: string | null;
+        postSnapshotDigest?: string;
+        snapshot: Snapshot;
+        llmResponse: LLMResponse;
+        result: AgentActResult;
+    }): TraceEventData;
+    /**
+     * Build step_end event data for AgentRuntime (verification loop).
+     */
+    static buildRuntimeStepEndData(params: {
+        stepId: string;
+        stepIndex: number;
+        goal: string;
+        attempt: number;
+        preUrl: string;
+        postUrl: string;
+        preSnapshotDigest?: string;
+        postSnapshotDigest?: string;
+        execData: TraceEventData['exec'];
+        verifyData: TraceEventData['verify'];
+        assertions?: NonNullable<TraceEventData['verify']>['signals']['assertions'];
+        taskDone?: boolean;
+        taskDoneLabel?: string;
+    }): TraceEventData;
+    /**
+     * Build snapshot event data
+     *
+     * @param snapshot - Snapshot to build event data for
+     * @param goal - Optional goal/task description
+     * @returns Snapshot event data
+     */
+    static buildSnapshotData(snapshot: Snapshot, goal?: string): TraceEventData;
+    /**
+     * Build partial step_end event data for failed steps
+     *
+     * This is used when a step fails after collecting some data (snapshot, LLM response, etc.)
+     * but before completing execution. It ensures diff_status and other fields are preserved
+     * in traces even when the agent run fails.
+     *
+     * @param params - Parameters for building partial step_end event
+     * @returns Partial step_end event data
+     */
+    static buildPartialStepEndData(params: {
+        stepId: string;
+        stepIndex: number;
+        goal: string;
+        attempt: number;
+        preUrl: string | null;
+        postUrl: string | null;
+        postSnapshotDigest?: string;
+        snapshot?: Snapshot | null;
+        llmResponse?: LLMResponse | null;
+        error: string;
+        durationMs: number;
+    }): TraceEventData;
+}
+//# sourceMappingURL=trace-event-builder.d.ts.map

package/dist/utils/trace-event-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-event-builder.d.ts","sourceRoot":"","sources":["../../src/utils/trace-event-builder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAgB,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAE,QAAQ,EAAW,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAG9C;;GAEG;AACH,qBAAa,iBAAiB;IAC5B;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,WAAW;IAI1B;;;;;OAKG;IACH,MAAM,CAAC,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM;IAKtD;;;;;OAKG;IACH,MAAM,CAAC,YAAY,CAAC,WAAW,EAAE,WAAW,GAAG,cAAc,CAAC,KAAK,CAAC;IAgBpE;;;;;;OAMG;IACH,MAAM,CAAC,kBAAkB,CAAC,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,QAAQ,GAAG,cAAc,CAAC,MAAM,CAAC;IA+C7F;;;;;;OAMG;IACH,MAAM,CAAC,eAAe,CAAC,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,QAAQ,GAAG,cAAc,CAAC,QAAQ,CAAC;IAmC5F;;;;;OAKG;IACH,MAAM,CAAC,gBAAgB,CAAC,MAAM,EAAE;QAC9B,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QACvB,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,QAAQ,EAAE,QAAQ,CAAC;QACnB,WAAW,EAAE,WAAW,CAAC;QACzB,MAAM,EAAE,cAAc,CAAC;KACxB,GAAG,cAAc;IA2ElB;;OAEG;IACH,MAAM,CAAC,uBAAuB,CAAC,MAAM,EAAE;QACrC,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,QAAQ,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;QACjC,UAAU,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;QACrC,UAAU,CAAC,EAAE,WAAW,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,YAAY,CAAC,CAAC;QAC5E,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,GAAG,cAAc;IAmDlB;;;;;;OAMG;IACH,MAAM,CAAC,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,cAAc;IAqC3E;;;;;;;;;OASG;IACH,MAAM,CAAC,uBAAuB,CAAC,MAAM,EAAE;QACrC,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QACvB,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;QAC3B,WAAW,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;QACjC,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;KACpB,GAAG,cAAc;CA+FnB"}