playwright-mimic 0.1.0 → 0.1.1

package/dist/agentic/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Agentic System Entry Point
+ *
+ * Exports for the agentic browser automation system.
+ */
+export { Agent } from './agent.js';
+export type { AgentState, AgentConfig, ActionRecord, ActionReflection, PlanningResult, PlanStep, ReasoningResult, DecidedAction, ErrorRecord, } from './types.js';
+export { createPlan, refinePlan } from './planner.js';
+export { reasonAndDecide, validateAction } from './react.js';
+export { reflectOnAction, reflectOnProgress } from './reflection.js';
+export { determineRecoveryStrategy, classifyError, getRetryDelay, shouldRetryBasedOnError } from './recovery.js';
+export { smartWait, waitForLoadersToDisappear, detectLoadingIndicators, isPageLoading, } from './wait.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agentic/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EACV,UAAU,EACV,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,QAAQ,EACR,eAAe,EACf,aAAa,EACb,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACrE,OAAO,EACL,yBAAyB,EACzB,aAAa,EACb,aAAa,EACb,uBAAuB,EACxB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,SAAS,EACT,yBAAyB,EACzB,uBAAuB,EACvB,aAAa,GACd,MAAM,WAAW,CAAC"}

package/dist/agentic/index.js

@@ -0,0 +1,12 @@
+/**
+ * Agentic System Entry Point
+ *
+ * Exports for the agentic browser automation system.
+ */
+export { Agent } from './agent.js';
+export { createPlan, refinePlan } from './planner.js';
+export { reasonAndDecide, validateAction } from './react.js';
+export { reflectOnAction, reflectOnProgress } from './reflection.js';
+export { determineRecoveryStrategy, classifyError, getRetryDelay, shouldRetryBasedOnError } from './recovery.js';
+export { smartWait, waitForLoadersToDisappear, detectLoadingIndicators, isPageLoading, } from './wait.js';
+//# sourceMappingURL=index.js.map

package/dist/agentic/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agentic/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAYnC,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACrE,OAAO,EACL,yBAAyB,EACzB,aAAa,EACb,aAAa,EACb,uBAAuB,EACxB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,SAAS,EACT,yBAAyB,EACzB,uBAAuB,EACvB,aAAa,GACd,MAAM,WAAW,CAAC"}

package/dist/agentic/planner.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Planning Module
+ *
+ * Implements the Planning Pattern for agentic systems.
+ * Breaks down high-level goals into actionable steps with dependencies.
+ */
+import { type LanguageModel } from 'ai';
+import type { PlanningResult } from './types.js';
+/**
+ * Create an execution plan from a high-level goal
+ *
+ * Uses AI to decompose a goal into actionable steps with dependencies,
+ * success criteria, and risk assessment.
+ *
+ * @param brain - Language model for planning
+ * @param goal - High-level goal or objective
+ * @param currentState - Current state of the page/agent (optional)
+ * @returns Promise resolving to a structured plan
+ */
+export declare function createPlan(brain: LanguageModel, goal: string, currentState?: {
+    url?: string;
+    pageTitle?: string;
+    availableElements?: number;
+}): Promise<PlanningResult>;
+/**
+ * Refine a plan based on execution feedback
+ *
+ * Updates the plan when steps fail or when new information is discovered.
+ *
+ * @param brain - Language model for planning
+ * @param originalPlan - The original plan that needs refinement
+ * @param feedback - Feedback from execution (failures, discoveries, etc.)
+ * @returns Promise resolving to a refined plan
+ */
+export declare function refinePlan(brain: LanguageModel, originalPlan: PlanningResult, feedback: {
+    failedStep?: number;
+    failureReason?: string;
+    discoveredInfo?: string;
+    currentState?: string;
+}): Promise<PlanningResult>;
+//# sourceMappingURL=planner.d.ts.map

package/dist/agentic/planner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner.d.ts","sourceRoot":"","sources":["../../src/agentic/planner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,aAAa,EAAwB,MAAM,IAAI,CAAC;AAE9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAwBjD;;;;;;;;;;GAUG;AACH,wBAAsB,UAAU,CAC9B,KAAK,EAAE,aAAa,EACpB,IAAI,EAAE,MAAM,EACZ,YAAY,CAAC,EAAE;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,GACA,OAAO,CAAC,cAAc,CAAC,CA2DzB;AAED;;;;;;;;;GASG;AACH,wBAAsB,UAAU,CAC9B,KAAK,EAAE,aAAa,EACpB,YAAY,EAAE,cAAc,EAC5B,QAAQ,EAAE;IACR,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GACA,OAAO,CAAC,cAAc,CAAC,CAgCzB"}

package/dist/agentic/planner.js

@@ -0,0 +1,136 @@
+/**
+ * Planning Module
+ *
+ * Implements the Planning Pattern for agentic systems.
+ * Breaks down high-level goals into actionable steps with dependencies.
+ */
+import { generateText, Output } from 'ai';
+import { z } from 'zod';
+import { countTokens } from '../utils/token-counter.js';
+/**
+ * Schema for planning result validation
+ *
+ * Note: All fields must be required (no .default()) for AI SDK structured output compatibility.
+ * Empty arrays should be provided by the AI model when there are no values.
+ */
+const zPlanStep = z.object({
+    order: z.number().int().positive().describe('Step number in execution order'),
+    description: z.string().describe('Clear description of what this step should accomplish'),
+    expectedActionType: z.enum(['navigation', 'click', 'form', 'assertion', 'wait']).describe('Type of action expected for this step'),
+    successCriteria: z.string().describe('How to determine if this step was successful'),
+    dependencies: z.array(z.number().int().positive()).describe('Step numbers this step depends on (provide empty array [] if no dependencies)'),
+});
+const zPlanningResult = z.object({
+    steps: z.array(zPlanStep).min(1).describe('Ordered list of steps to achieve the goal'),
+    complexity: z.enum(['low', 'medium', 'high']).describe('Estimated complexity of the overall plan'),
+    challenges: z.array(z.string()).describe('Potential challenges or risks identified (provide empty array [] if none)'),
+    prerequisites: z.array(z.string()).describe('Prerequisites or requirements before starting (provide empty array [] if none)'),
+});
+/**
+ * Create an execution plan from a high-level goal
+ *
+ * Uses AI to decompose a goal into actionable steps with dependencies,
+ * success criteria, and risk assessment.
+ *
+ * @param brain - Language model for planning
+ * @param goal - High-level goal or objective
+ * @param currentState - Current state of the page/agent (optional)
+ * @returns Promise resolving to a structured plan
+ */
+export async function createPlan(brain, goal, currentState) {
+    const stateContext = currentState
+        ? `
+Current State:
+- URL: ${currentState.url || 'unknown'}
+- Page Title: ${currentState.pageTitle || 'unknown'}
+- Available Interactive Elements: ${currentState.availableElements || 0}
+`
+        : '';
+    const prompt = `You are an expert test automation planner specializing in browser automation using Playwright.
+
+Your task is to break down a high-level goal into a structured, executable plan.
+
+**Goal:**
+${goal}
+
+${stateContext}
+
+**Instructions:**
+1. Break the goal into logical, sequential steps
+2. Each step should be:
+   - Specific and actionable
+   - Have clear success criteria
+   - Identify dependencies on previous steps
+   - Specify the expected action type (navigation, click, form, assertion, wait)
+3. Consider potential challenges (dynamic content, timing issues, element availability)
+4. Identify any prerequisites (e.g., "must be logged in", "must be on specific page")
+5. Assess overall complexity (low: 1-3 steps, medium: 4-7 steps, high: 8+ steps or complex interactions)
+
+**Action Types:**
+- navigation: Moving to a new page or URL
+- click: Clicking buttons, links, or interactive elements
+- form: Filling forms, selecting options, entering data
+- assertion: Verifying state, content, or conditions
+- wait: Waiting for conditions, loading, or timing
+
+**Output Format:**
+Return a structured plan with:
+- Ordered steps (each with description, expected action type, success criteria, dependencies)
+  - dependencies: array of step numbers this step depends on (use empty array [] if no dependencies)
+- Overall complexity assessment
+- Potential challenges (use empty array [] if none)
+- Prerequisites (use empty array [] if none)
+
+**Important:** Always provide all fields, including empty arrays [] when there are no dependencies, challenges, or prerequisites.
+
+Think step-by-step and create a comprehensive plan.`;
+    const result = await generateText({
+        model: brain,
+        prompt,
+        maxRetries: 3,
+        output: Output.object({ schema: zPlanningResult, name: 'executionPlan' }),
+    });
+    await countTokens(result);
+    return result.output;
+}
+/**
+ * Refine a plan based on execution feedback
+ *
+ * Updates the plan when steps fail or when new information is discovered.
+ *
+ * @param brain - Language model for planning
+ * @param originalPlan - The original plan that needs refinement
+ * @param feedback - Feedback from execution (failures, discoveries, etc.)
+ * @returns Promise resolving to a refined plan
+ */
+export async function refinePlan(brain, originalPlan, feedback) {
+    const prompt = `You are refining an execution plan based on feedback from execution.
+
+**Original Plan:**
+${JSON.stringify(originalPlan, null, 2)}
+
+**Execution Feedback:**
+${feedback.failedStep ? `Step ${feedback.failedStep} failed: ${feedback.failureReason}` : ''}
+${feedback.discoveredInfo ? `New information discovered: ${feedback.discoveredInfo}` : ''}
+${feedback.currentState ? `Current state: ${feedback.currentState}` : ''}
+
+**Instructions:**
+1. Analyze why the plan failed or what new information was discovered
+2. Refine the plan by:
+   - Adjusting failed steps (fix approach, add prerequisites, break into smaller steps)
+   - Adding new steps if needed based on discoveries
+   - Updating dependencies if step order needs to change
+   - Revising complexity assessment if needed
+3. Maintain the overall goal while adapting to new information
+
+Return a refined plan that addresses the feedback.`;
+    const result = await generateText({
+        model: brain,
+        prompt,
+        maxRetries: 3,
+        output: Output.object({ schema: zPlanningResult, name: 'refinedPlan' }),
+    });
+    await countTokens(result);
+    return result.output;
+}
+//# sourceMappingURL=planner.js.map

package/dist/agentic/planner.js.map

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

package/dist/agentic/react.d.ts

@@ -0,0 +1,35 @@
+/**
+ * ReAct Module (Reasoning and Acting)
+ *
+ * Implements the ReAct pattern: combines reasoning with real-time action execution.
+ * The agent observes, thinks, and decides what action to take next.
+ */
+import { type LanguageModel } from 'ai';
+import type { ReasoningResult, DecidedAction, AgentState } from './types.js';
+/**
+ * Reason about the current state and decide on the next action
+ *
+ * Implements the ReAct pattern: Observe → Think → Act
+ *
+ * @param brain - Language model for reasoning
+ * @param state - Current agent state
+ * @param currentStep - Current step from the plan (if planning is enabled)
+ * @returns Promise resolving to reasoning result with decided action
+ */
+export declare function reasonAndDecide(brain: LanguageModel, state: AgentState, currentStep?: {
+    description: string;
+    expectedActionType: string;
+    successCriteria: string;
+}): Promise<ReasoningResult>;
+/**
+ * Validate that a decided action is feasible given the current state
+ *
+ * @param action - The action to validate
+ * @param state - Current agent state
+ * @returns Whether the action is feasible and why
+ */
+export declare function validateAction(action: DecidedAction, state: AgentState): {
+    feasible: boolean;
+    reason: string;
+};
+//# sourceMappingURL=react.d.ts.map

package/dist/agentic/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../../src/agentic/react.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,aAAa,EAAwB,MAAM,IAAI,CAAC;AAE9D,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAsB7E;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,UAAU,EACjB,WAAW,CAAC,EAAE;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,eAAe,EAAE,MAAM,CAAC;CACzB,GACA,OAAO,CAAC,eAAe,CAAC,CAsF1B;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,UAAU,GAAG;IACxE,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB,CAqDA"}

package/dist/agentic/react.js

@@ -0,0 +1,170 @@
+/**
+ * ReAct Module (Reasoning and Acting)
+ *
+ * Implements the ReAct pattern: combines reasoning with real-time action execution.
+ * The agent observes, thinks, and decides what action to take next.
+ */
+import { generateText, Output } from 'ai';
+import { z } from 'zod';
+import { countTokens } from '../utils/token-counter.js';
+/**
+ * Schema for reasoning result validation
+ */
+const zDecidedAction = z.object({
+    type: z.enum(['navigation', 'click', 'form', 'assertion', 'wait', 'retry', 'abort']).describe('Type of action to take'),
+    description: z.string().describe('Human-readable description of the action'),
+    parameters: z.record(z.string(), z.unknown()).describe('Parameters needed to execute this action'),
+    expectedOutcome: z.string().describe('What should happen after this action'),
+    rationale: z.string().describe('Why this action was chosen'),
+});
+const zReasoningResult = z.object({
+    observation: z.string().describe('What the agent observed about the current state'),
+    thought: z.string().describe('What the agent is thinking about the situation'),
+    action: zDecidedAction.describe('The action the agent decided to take'),
+    confidence: z.number().min(0).max(1).describe('Confidence level in this decision (0-1)'),
+    alternatives: z.array(zDecidedAction).default([]).describe('Alternative actions that were considered'),
+});
+/**
+ * Reason about the current state and decide on the next action
+ *
+ * Implements the ReAct pattern: Observe → Think → Act
+ *
+ * @param brain - Language model for reasoning
+ * @param state - Current agent state
+ * @param currentStep - Current step from the plan (if planning is enabled)
+ * @returns Promise resolving to reasoning result with decided action
+ */
+export async function reasonAndDecide(brain, state, currentStep) {
+    // Build context from state
+    const actionHistory = state.actionHistory
+        .slice(-5) // Last 5 actions for context
+        .map(a => `- ${a.description} (${a.success ? 'success' : 'failed'})`)
+        .join('\n');
+    const recentErrors = state.errors
+        .slice(-3) // Last 3 errors
+        .map(e => `- ${e.type}: ${e.message}`)
+        .join('\n');
+    const stepContext = currentStep
+        ? `
+**Current Plan Step:**
+- Description: ${currentStep.description}
+- Expected Action Type: ${currentStep.expectedActionType}
+- Success Criteria: ${currentStep.successCriteria}
+`
+        : '';
+    const prompt = `You are an intelligent browser automation agent using the ReAct (Reasoning and Acting) pattern.
+
+**Your Goal:**
+${state.overallObjective}
+
+**Current State:**
+- URL: ${state.currentUrl}
+- Page Title: ${state.pageTitle}
+- Available Interactive Elements: ${state.availableElements.length}
+- Actions Taken: ${state.actionHistory.length}
+- Goal Achieved: ${state.goalAchieved ? 'Yes' : 'No'}
+- Page Loading: ${state.isLoading ? `Yes (${state.loadingIndicatorCount} indicator(s) visible)` : 'No'}
+
+${stepContext}
+
+**Recent Action History:**
+${actionHistory || 'No actions taken yet'}
+
+**Recent Errors:**
+${recentErrors || 'No errors'}
+
+**Available Elements Summary:**
+${state.availableElements.slice(0, 10).map((el, i) => `${i + 1}. ${el.tag} - ${el.text || el.ariaLabel || el.label || 'no text'}`).join('\n')}
+${state.availableElements.length > 10 ? `... and ${state.availableElements.length - 10} more` : ''}
+
+**Instructions:**
+1. **Observe**: Analyze the current state - what do you see? What's the situation?
+2. **Think**: What should you do next? Consider:
+   - Are you closer to the goal?
+   - What actions are available?
+   - What worked or didn't work before?
+   - What's the best next step?
+3. **Act**: Decide on a specific action to take:
+   - navigation: Navigate to a URL
+   - click: Click on an element (specify which one in parameters)
+   - form: Fill a form field (specify field and value in parameters)
+   - assertion: Verify something (specify what to check in parameters)
+   - wait: Wait for loading to complete or a specific condition
+     * Use wait when you detect loading indicators, need to wait for dynamic content,
+       or after actions that might trigger async operations
+     * Parameters: waitType ("smart" to detect loaders, "fixed" for fixed timeout, "network" for network idle)
+     * duration: fallback timeout in ms (default: 2000)
+     * loaderTimeout: max time to wait for loaders (default: 10000)
+   - retry: Retry a previous action with modifications
+   - abort: Give up if goal seems unachievable
+
+**Important**: If you see loading indicators, spinners, or expect dynamic content to load after an action, use a "wait" action. The system will automatically detect and wait for loading indicators to disappear.
+
+4. Consider alternatives - what other actions could work?
+5. Assess your confidence in this decision
+
+Think step-by-step using the ReAct pattern: Observe → Think → Act.`;
+    const result = await generateText({
+        model: brain,
+        prompt,
+        maxRetries: 3,
+        output: Output.object({ schema: zReasoningResult, name: 'reasoningResult' }),
+    });
+    await countTokens(result);
+    return result.output;
+}
+/**
+ * Validate that a decided action is feasible given the current state
+ *
+ * @param action - The action to validate
+ * @param state - Current agent state
+ * @returns Whether the action is feasible and why
+ */
+export function validateAction(action, state) {
+    // Check if we've exceeded max actions
+    if (state.metadata.stepCount > (state.metadata.stepCount + 100)) {
+        return {
+            feasible: false,
+            reason: 'Maximum action limit reached',
+        };
+    }
+    // Check if goal is already achieved
+    if (state.goalAchieved && action.type !== 'assertion') {
+        return {
+            feasible: false,
+            reason: 'Goal already achieved, no further actions needed',
+        };
+    }
+    // Validate action-specific requirements
+    switch (action.type) {
+        case 'navigation':
+            if (!action.parameters.url) {
+                return {
+                    feasible: false,
+                    reason: 'Navigation action requires a URL parameter',
+                };
+            }
+            break;
+        case 'click':
+            if (state.availableElements.length === 0) {
+                return {
+                    feasible: false,
+                    reason: 'No clickable elements available on the page',
+                };
+            }
+            break;
+        case 'form':
+            if (state.availableElements.filter(el => el.tag === 'input' || el.tag === 'textarea' || el.tag === 'select').length === 0) {
+                return {
+                    feasible: false,
+                    reason: 'No form elements available on the page',
+                };
+            }
+            break;
+    }
+    return {
+        feasible: true,
+        reason: 'Action is feasible',
+    };
+}
+//# sourceMappingURL=react.js.map

package/dist/agentic/react.js.map

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

package/dist/agentic/recovery.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Error Recovery Module
+ *
+ * Implements error recovery strategies and retry logic for the agentic system.
+ */
+import { type LanguageModel } from 'ai';
+import type { ErrorRecord, ActionRecord, AgentState } from './types.js';
+/**
+ * Analyze an error and determine recovery strategy
+ *
+ * @param brain - Language model for recovery planning
+ * @param error - The error that occurred
+ * @param failedAction - The action that failed
+ * @param state - Current agent state
+ * @returns Promise resolving to recovery strategy
+ */
+export declare function determineRecoveryStrategy(brain: LanguageModel, error: ErrorRecord, failedAction: ActionRecord, state: AgentState): Promise<{
+    shouldRetry: boolean;
+    retryAction?: string;
+    alternativeApproach?: string;
+    skipAndContinue: boolean;
+    abort: boolean;
+    reasoning: string;
+}>;
+/**
+ * Classify error type for appropriate recovery
+ *
+ * @param error - The error record
+ * @returns Error classification
+ */
+export declare function classifyError(error: ErrorRecord): {
+    category: 'transient' | 'permanent' | 'environment' | 'logic' | 'unknown';
+    recoverable: boolean;
+    suggestedWait?: number;
+};
+/**
+ * Get retry delay based on attempt number
+ *
+ * Implements exponential backoff for retries.
+ *
+ * @param attemptNumber - Current retry attempt (1-based)
+ * @param baseDelay - Base delay in milliseconds (default: 1000)
+ * @returns Delay in milliseconds
+ */
+export declare function getRetryDelay(attemptNumber: number, baseDelay?: number): number;
+/**
+ * Check if an action should be retried based on error classification
+ *
+ * @param error - The error that occurred
+ * @param retryCount - Number of times this action has been retried
+ * @param maxRetries - Maximum number of retries allowed
+ * @returns Whether to retry
+ */
+export declare function shouldRetryBasedOnError(error: ErrorRecord, retryCount: number, maxRetries: number): boolean;
+//# sourceMappingURL=recovery.d.ts.map

package/dist/agentic/recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery.d.ts","sourceRoot":"","sources":["../../src/agentic/recovery.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,aAAa,EAAwB,MAAM,IAAI,CAAC;AAE9D,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAexE;;;;;;;;GAQG;AACH,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,WAAW,EAClB,YAAY,EAAE,YAAY,EAC1B,KAAK,EAAE,UAAU,GAChB,OAAO,CAAC;IACT,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,eAAe,EAAE,OAAO,CAAC;IACzB,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC,CAkFD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,GAAG;IACjD,QAAQ,EAAE,WAAW,GAAG,WAAW,GAAG,aAAa,GAAG,OAAO,GAAG,SAAS,CAAC;IAC1E,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CA+DA;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,GAAE,MAAa,GAAG,MAAM,CAIrF;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,WAAW,EAClB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,OAAO,CA4BT"}