@tooluminati/diagnostics 0.1.0

package/dist/mounted-forms.d.ts

@@ -0,0 +1,26 @@
+import type { JsonSchema, WebMcpToolDescriptor } from '@tooluminati/core';
+export interface MountedFormSummary {
+    name: string;
+    submitting?: boolean | undefined;
+    validating?: boolean | undefined;
+    dirty?: boolean | undefined;
+    touched?: boolean | undefined;
+    errors: Array<{
+        path: string;
+        message: string;
+        kind?: string | undefined;
+    }>;
+    schema?: JsonSchema | undefined;
+}
+export interface MountedFormsRegistry {
+    register(summary: MountedFormSummary): () => void;
+    unregister(name: string): void;
+    list(): MountedFormSummary[];
+}
+/** @experimental */
+export declare function createMountedFormsRegistry(): MountedFormsRegistry;
+/** @experimental */
+export declare function createMountedFormsSummaryTool(registry: MountedFormsRegistry, name?: string): WebMcpToolDescriptor<Record<string, never>, {
+    forms: MountedFormSummary[];
+}>;
+//# sourceMappingURL=mounted-forms.d.ts.map

package/dist/mounted-forms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mounted-forms.d.ts","sourceRoot":"","sources":["../src/mounted-forms.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,oBAAoB,EACrB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACjC,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACjC,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,MAAM,EAAE,KAAK,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KAC3B,CAAC,CAAC;IACH,MAAM,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;CACjC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,IAAI,CAAC;IAClD,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,IAAI,IAAI,kBAAkB,EAAE,CAAC;CAC9B;AAED,oBAAoB;AACpB,wBAAgB,0BAA0B,IAAI,oBAAoB,CAiBjE;AAED,oBAAoB;AACpB,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,oBAAoB,EAC9B,IAAI,SAA8B,GACjC,oBAAoB,CACrB,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EACrB;IAAE,KAAK,EAAE,kBAAkB,EAAE,CAAA;CAAE,CAChC,CAaA"}

package/dist/mounted-forms.js

@@ -0,0 +1,32 @@
+/** @experimental */
+export function createMountedFormsRegistry() {
+    const forms = new Map();
+    return {
+        register(summary) {
+            forms.set(summary.name, summary);
+            return () => {
+                forms.delete(summary.name);
+            };
+        },
+        unregister(name) {
+            forms.delete(name);
+        },
+        list() {
+            return [...forms.values()];
+        },
+    };
+}
+/** @experimental */
+export function createMountedFormsSummaryTool(registry, name = 'get_mounted_forms_summary') {
+    return {
+        name,
+        description: 'Returns summaries of mounted form diagnostics registered in the app.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: true },
+        execute: () => ({ forms: registry.list() }),
+    };
+}

package/dist/timeline.d.ts

@@ -0,0 +1,99 @@
+import type { WebMcpToolDescriptor } from '@tooluminati/core';
+import type { ClientErrorBuffer } from './errors';
+export type TroubleshootingEventCategory = 'client_error' | 'fetch_failure' | 'route_change' | 'action_blocked' | 'tool_activated' | 'tool_cancelled' | 'agent_form_submit' | 'toolchange' | 'custom';
+export interface TroubleshootingEventBase {
+    id: string;
+    category: TroubleshootingEventCategory;
+    timestamp: string;
+    title: string;
+    detail?: string | undefined;
+    metadata?: Record<string, string> | undefined;
+    untrusted?: boolean | undefined;
+}
+export interface ClientErrorTimelineEvent extends TroubleshootingEventBase {
+    category: 'client_error';
+    message: string;
+    source?: string | undefined;
+}
+export interface FetchFailureTimelineEvent extends TroubleshootingEventBase {
+    category: 'fetch_failure';
+    method: string;
+    url: string;
+    status?: number | undefined;
+    durationMs?: number | undefined;
+}
+export interface RouteChangeTimelineEvent extends TroubleshootingEventBase {
+    category: 'route_change';
+    from?: string | undefined;
+    to: string;
+}
+export interface ActionBlockedTimelineEvent extends TroubleshootingEventBase {
+    category: 'action_blocked';
+    actionId: string;
+    reasons: string[];
+}
+export interface ToolLifecycleTimelineEvent extends TroubleshootingEventBase {
+    category: 'tool_activated' | 'tool_cancelled' | 'agent_form_submit';
+    toolName?: string | undefined;
+    formId?: string | undefined;
+}
+export interface ToolChangeTimelineEvent extends TroubleshootingEventBase {
+    category: 'toolchange';
+    added: string[];
+    removed: string[];
+}
+export interface CustomTimelineEvent extends TroubleshootingEventBase {
+    category: 'custom';
+}
+export type TroubleshootingEvent = ClientErrorTimelineEvent | FetchFailureTimelineEvent | RouteChangeTimelineEvent | ActionBlockedTimelineEvent | ToolLifecycleTimelineEvent | ToolChangeTimelineEvent | CustomTimelineEvent;
+export interface TroubleshootingTimelineBufferOptions {
+    maxSize?: number;
+    redact?: (event: TroubleshootingEvent) => TroubleshootingEvent;
+}
+export type TroubleshootingEventInput = Omit<ClientErrorTimelineEvent, 'id' | 'timestamp'> | Omit<FetchFailureTimelineEvent, 'id' | 'timestamp'> | Omit<RouteChangeTimelineEvent, 'id' | 'timestamp'> | Omit<ActionBlockedTimelineEvent, 'id' | 'timestamp'> | Omit<ToolLifecycleTimelineEvent, 'id' | 'timestamp'> | Omit<ToolChangeTimelineEvent, 'id' | 'timestamp'> | Omit<CustomTimelineEvent, 'id' | 'timestamp'>;
+export declare class TroubleshootingTimelineBuffer {
+    private readonly events;
+    private readonly maxSize;
+    private readonly redact?;
+    constructor(options?: TroubleshootingTimelineBufferOptions | number);
+    push(event: TroubleshootingEventInput & {
+        id?: string;
+        timestamp?: string;
+    }): TroubleshootingEvent;
+    list(options?: {
+        categories?: TroubleshootingEventCategory[];
+        since?: string;
+        limit?: number;
+    }): TroubleshootingEvent[];
+    summary(events?: TroubleshootingEvent[]): {
+        total: number;
+        byCategory: Record<string, number>;
+    };
+    clear(): void;
+}
+export interface FetchFailureTrackerOptions {
+    buffer: TroubleshootingTimelineBuffer;
+    enabled?: boolean;
+    redactBody?: boolean;
+    ignoreUrls?: RegExp;
+}
+export declare function createFetchFailureTracker(options: FetchFailureTrackerOptions): () => void;
+export declare function createTimelineFromErrorBuffer(buffer: ClientErrorBuffer, timeline: TroubleshootingTimelineBuffer): () => void;
+export interface WebMcpLifecycleCollectorOptions {
+    buffer: TroubleshootingTimelineBuffer;
+    enabled?: boolean;
+}
+export declare function createWebMcpLifecycleCollector(options: WebMcpLifecycleCollectorOptions): () => void;
+export interface TroubleshootingTimelineToolInput {
+    categories?: string[];
+    since?: string;
+    limit?: number;
+}
+export declare function createTroubleshootingTimelineTool(buffer: TroubleshootingTimelineBuffer, name?: string): WebMcpToolDescriptor<TroubleshootingTimelineToolInput, {
+    events: TroubleshootingEvent[];
+    summary: {
+        total: number;
+        byCategory: Record<string, number>;
+    };
+}>;
+//# sourceMappingURL=timeline.d.ts.map

package/dist/timeline.d.ts.map

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

package/dist/timeline.js

@@ -0,0 +1,302 @@
+const DEFAULT_MAX_SIZE = 50;
+const DEFAULT_TOOL_LIMIT = 20;
+const VALID_CATEGORIES = new Set([
+    'client_error',
+    'fetch_failure',
+    'route_change',
+    'action_blocked',
+    'tool_activated',
+    'tool_cancelled',
+    'agent_form_submit',
+    'toolchange',
+    'custom',
+]);
+let nextEventId = 0;
+function createEventId() {
+    nextEventId += 1;
+    return `tlm-${nextEventId}`;
+}
+function stripQuerySecrets(url) {
+    try {
+        const parsed = new URL(url, 'http://local');
+        parsed.search = '';
+        return parsed.pathname + (parsed.hash || '');
+    }
+    catch {
+        return url.split('?')[0] ?? url;
+    }
+}
+export class TroubleshootingTimelineBuffer {
+    events = [];
+    maxSize;
+    redact;
+    constructor(options = {}) {
+        if (typeof options === 'number') {
+            this.maxSize = options;
+        }
+        else {
+            this.maxSize = options.maxSize ?? DEFAULT_MAX_SIZE;
+            if (options.redact) {
+                this.redact = options.redact;
+            }
+        }
+    }
+    push(event) {
+        const stored = {
+            ...event,
+            id: event.id ?? createEventId(),
+            timestamp: event.timestamp ?? new Date().toISOString(),
+        };
+        const finalEvent = this.redact?.(stored) ?? stored;
+        this.events.unshift(finalEvent);
+        this.events.splice(this.maxSize);
+        return finalEvent;
+    }
+    list(options) {
+        const limit = Math.max(0, Math.min(options?.limit ?? DEFAULT_TOOL_LIMIT, DEFAULT_TOOL_LIMIT));
+        let result = [...this.events];
+        if (options?.since) {
+            const sinceMs = Date.parse(options.since);
+            if (Number.isNaN(sinceMs)) {
+                return [];
+            }
+            result = result.filter((e) => Date.parse(e.timestamp) >= sinceMs);
+        }
+        if (options?.categories?.length) {
+            const cats = new Set(options.categories);
+            result = result.filter((e) => cats.has(e.category));
+        }
+        return result.slice(0, limit);
+    }
+    summary(events = this.events) {
+        const byCategory = {};
+        for (const event of events) {
+            byCategory[event.category] = (byCategory[event.category] ?? 0) + 1;
+        }
+        return { total: events.length, byCategory };
+    }
+    clear() {
+        this.events.splice(0);
+    }
+}
+let fetchTrackerCount = 0;
+let originalFetch;
+export function createFetchFailureTracker(options) {
+    if (options.enabled === false || typeof window === 'undefined') {
+        return () => { };
+    }
+    if (fetchTrackerCount === 0) {
+        originalFetch = window.fetch.bind(window);
+    }
+    fetchTrackerCount += 1;
+    const baseFetch = originalFetch;
+    window.fetch = async (input, init) => {
+        const started = performance.now();
+        const method = (init?.method ?? 'GET').toUpperCase();
+        const url = typeof input === 'string'
+            ? input
+            : input instanceof URL
+                ? input.toString()
+                : input.url;
+        if (options.ignoreUrls?.test(url)) {
+            return baseFetch(input, init);
+        }
+        try {
+            const response = await baseFetch(input, init);
+            if (!response.ok) {
+                const detail = options.redactBody === false
+                    ? `HTTP request failed before UI state updated.`
+                    : 'HTTP request failed before UI state updated.';
+                options.buffer.push({
+                    category: 'fetch_failure',
+                    title: `${method} ${stripQuerySecrets(url)} — ${response.status}`,
+                    method,
+                    url: stripQuerySecrets(url),
+                    status: response.status,
+                    durationMs: Math.round(performance.now() - started),
+                    detail,
+                    metadata: {
+                        host: safeHost(url),
+                        status: String(response.status),
+                    },
+                });
+            }
+            return response;
+        }
+        catch (error) {
+            options.buffer.push({
+                category: 'fetch_failure',
+                title: `${method} ${stripQuerySecrets(url)} — network error`,
+                method,
+                url: stripQuerySecrets(url),
+                durationMs: Math.round(performance.now() - started),
+                detail: error instanceof Error ? error.message : 'Network request failed.',
+                metadata: { host: safeHost(url) },
+            });
+            throw error;
+        }
+    };
+    return () => {
+        fetchTrackerCount = Math.max(0, fetchTrackerCount - 1);
+        if (fetchTrackerCount === 0 && originalFetch) {
+            window.fetch = originalFetch;
+            originalFetch = undefined;
+        }
+    };
+}
+function safeHost(url) {
+    try {
+        return new URL(url, window.location.origin).host;
+    }
+    catch {
+        return 'unknown';
+    }
+}
+export function createTimelineFromErrorBuffer(buffer, timeline) {
+    const originalPush = buffer.push.bind(buffer);
+    buffer.push = (error) => {
+        originalPush(error);
+        timeline.push({
+            category: 'client_error',
+            title: error.message,
+            message: error.message,
+            source: error.source,
+            detail: 'Client error captured by diagnostics buffer.',
+            metadata: {
+                source: error.source,
+                ...(error.route ? { route: error.route } : {}),
+            },
+            untrusted: true,
+        });
+    };
+    return () => {
+        buffer.push = originalPush;
+    };
+}
+export function createWebMcpLifecycleCollector(options) {
+    if (options.enabled === false || typeof window === 'undefined') {
+        return () => { };
+    }
+    const cleanups = [];
+    const onToolActivated = (event) => {
+        const detail = event.detail;
+        options.buffer.push({
+            category: 'tool_activated',
+            title: `agent activated ${detail?.toolName ?? 'form tool'}`,
+            toolName: detail?.toolName,
+            formId: detail?.form?.id,
+            detail: 'Declarative form tool activated by the agent.',
+        });
+    };
+    const onToolCancel = (event) => {
+        const detail = event.detail;
+        options.buffer.push({
+            category: 'tool_cancelled',
+            title: `agent cancelled ${detail?.toolName ?? 'form tool'}`,
+            toolName: detail?.toolName,
+            detail: 'Agent cancelled a declarative form tool.',
+        });
+    };
+    const onAgentFormSubmit = (event) => {
+        const submitEvent = event;
+        if (!submitEvent.agentInvoked) {
+            return;
+        }
+        const form = event.target;
+        const toolName = form?.getAttribute('toolname') ?? 'form';
+        options.buffer.push({
+            category: 'agent_form_submit',
+            title: `agent submitted ${toolName}`,
+            toolName,
+            formId: form?.id,
+            detail: 'Agent invoked declarative form submit.',
+        });
+    };
+    const onToolChange = () => {
+        options.buffer.push({
+            category: 'toolchange',
+            title: 'tool registry changed',
+            added: [],
+            removed: [],
+            detail: 'WebMCP tool registry changed on document.modelContext.',
+        });
+    };
+    window.addEventListener('toolactivated', onToolActivated);
+    window.addEventListener('toolcancel', onToolCancel);
+    window.addEventListener('submit', onAgentFormSubmit, true);
+    cleanups.push(() => {
+        window.removeEventListener('toolactivated', onToolActivated);
+        window.removeEventListener('toolcancel', onToolCancel);
+        window.removeEventListener('submit', onAgentFormSubmit, true);
+    });
+    const modelContext = document.modelContext;
+    if (modelContext?.addEventListener) {
+        modelContext.addEventListener('toolchange', onToolChange);
+        cleanups.push(() => {
+            modelContext.removeEventListener('toolchange', onToolChange);
+        });
+    }
+    return () => {
+        for (const cleanup of cleanups) {
+            cleanup();
+        }
+    };
+}
+export function createTroubleshootingTimelineTool(buffer, name = 'get_troubleshooting_timeline') {
+    return {
+        name,
+        description: 'Returns a bounded, redacted timeline of recent runtime incidents.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                categories: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Optional event categories to include.',
+                },
+                since: {
+                    type: 'string',
+                    description: 'ISO timestamp; only events after this time.',
+                },
+                limit: {
+                    type: 'integer',
+                    maximum: DEFAULT_TOOL_LIMIT,
+                    description: 'Max events to return (cap 20).',
+                },
+            },
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: true, untrustedContentHint: true },
+        validateArgs(args) {
+            if (typeof args !== 'object' || args === null) {
+                return {};
+            }
+            const input = args;
+            if (input.categories?.length) {
+                const invalid = input.categories.filter((category) => !VALID_CATEGORIES.has(category));
+                if (invalid.length) {
+                    throw new Error(`Unknown timeline categories: ${invalid.join(', ')}`);
+                }
+            }
+            if (input.limit !== undefined && input.limit < 0) {
+                throw new Error('limit must be >= 0.');
+            }
+            return input;
+        },
+        execute: (input) => {
+            const events = buffer.list({
+                ...(input.categories?.length
+                    ? {
+                        categories: input.categories,
+                    }
+                    : {}),
+                ...(input.since ? { since: input.since } : {}),
+                ...(input.limit !== undefined ? { limit: input.limit } : {}),
+            });
+            return {
+                events,
+                summary: buffer.summary(events),
+            };
+        },
+    };
+}

package/dist/timeline.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=timeline.test.d.ts.map

package/dist/timeline.test.d.ts.map

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

package/dist/timeline.test.js

@@ -0,0 +1,94 @@
+import { describe, expect, it, vi } from 'vitest';
+import { TroubleshootingTimelineBuffer, createFetchFailureTracker, createTroubleshootingTimelineTool, } from './timeline';
+describe('TroubleshootingTimelineBuffer', () => {
+    it('stores events newest first with limit enforcement', () => {
+        const buffer = new TroubleshootingTimelineBuffer({ maxSize: 2 });
+        buffer.push({
+            category: 'route_change',
+            title: 'a',
+            to: '/a',
+        });
+        buffer.push({
+            category: 'route_change',
+            title: 'b',
+            to: '/b',
+        });
+        buffer.push({
+            category: 'route_change',
+            title: 'c',
+            to: '/c',
+        });
+        const events = buffer.list();
+        expect(events).toHaveLength(2);
+        expect(events[0]?.title).toBe('c');
+    });
+    it('filters by category and respects tool limit cap', () => {
+        const buffer = new TroubleshootingTimelineBuffer();
+        for (let i = 0; i < 25; i += 1) {
+            buffer.push({
+                category: 'client_error',
+                title: `err-${i}`,
+                message: `err-${i}`,
+            });
+        }
+        const filtered = buffer.list({
+            categories: ['client_error'],
+            limit: 100,
+        });
+        expect(filtered).toHaveLength(20);
+    });
+    it('redacts events when configured', () => {
+        const buffer = new TroubleshootingTimelineBuffer({
+            redact: (event) => ({
+                ...event,
+                title: event.title.replace(/secret/gi, '[redacted]'),
+            }),
+        });
+        buffer.push({
+            category: 'custom',
+            title: 'secret value',
+        });
+        expect(buffer.list()[0]?.title).toBe('[redacted] value');
+    });
+});
+describe('createFetchFailureTracker', () => {
+    it('records non-ok fetch responses', async () => {
+        const buffer = new TroubleshootingTimelineBuffer();
+        vi.stubGlobal('fetch', vi.fn(async () => ({ ok: false, status: 403 })));
+        const restore = createFetchFailureTracker({ buffer });
+        await fetch('/api/checkout?token=abc');
+        restore();
+        vi.unstubAllGlobals();
+        const events = buffer.list({ categories: ['fetch_failure'] });
+        expect(events).toHaveLength(1);
+        expect(events[0]?.title).toContain('403');
+        const fetchEvent = events[0];
+        if (fetchEvent?.category === 'fetch_failure') {
+            expect(fetchEvent.url).not.toContain('token');
+        }
+    });
+});
+describe('createTroubleshootingTimelineTool', () => {
+    it('returns bounded events and summary', async () => {
+        const buffer = new TroubleshootingTimelineBuffer();
+        buffer.push({
+            category: 'action_blocked',
+            title: 'submit blocked',
+            actionId: 'submit',
+            reasons: ['invalid'],
+        });
+        buffer.push({
+            category: 'client_error',
+            title: 'err',
+            message: 'err',
+        });
+        const tool = createTroubleshootingTimelineTool(buffer);
+        const result = await tool.execute({ categories: ['action_blocked'] }, {});
+        expect(result.events).toHaveLength(1);
+        expect(result.summary.total).toBe(1);
+    });
+    it('rejects negative limits', () => {
+        const tool = createTroubleshootingTimelineTool(new TroubleshootingTimelineBuffer());
+        expect(() => tool.validateArgs?.({ limit: -1 })).toThrow('limit must be >= 0');
+    });
+});

package/dist/troubleshooting-guidance.d.ts

@@ -0,0 +1,15 @@
+import type { TroubleshootingEvent } from './timeline';
+import type { ClientErrorSummary } from './errors';
+import type { WebMcpEnvironmentCheck } from './webmcp-environment';
+export interface TroubleshootingGuidanceEntry {
+    title: string;
+    hint: string;
+    severity: 'info' | 'warn' | 'error';
+}
+export declare const TROUBLESHOOTING_GUIDANCE: Record<string, TroubleshootingGuidanceEntry>;
+export declare function getGuidanceForEnvironmentCheck(check: WebMcpEnvironmentCheck): TroubleshootingGuidanceEntry | undefined;
+export declare function getGuidanceForTimelineEvent(event: TroubleshootingEvent): TroubleshootingGuidanceEntry | undefined;
+export declare function getGuidanceForClientError(error: ClientErrorSummary): TroubleshootingGuidanceEntry | undefined;
+export type TimelineFilterGroup = 'all' | 'failures' | 'blocked' | 'tools' | 'nav';
+export declare function timelineEventGroup(category: TroubleshootingEvent['category']): TimelineFilterGroup;
+//# sourceMappingURL=troubleshooting-guidance.d.ts.map

package/dist/troubleshooting-guidance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"troubleshooting-guidance.d.ts","sourceRoot":"","sources":["../src/troubleshooting-guidance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AACnD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAEnE,MAAM,WAAW,4BAA4B;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;CACrC;AAED,eAAO,MAAM,wBAAwB,EAAE,MAAM,CAAC,MAAM,EAAE,4BAA4B,CA8F/E,CAAC;AAEJ,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,sBAAsB,GAC5B,4BAA4B,GAAG,SAAS,CAc1C;AAED,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,oBAAoB,GAC1B,4BAA4B,GAAG,SAAS,CAS1C;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,kBAAkB,GACxB,4BAA4B,GAAG,SAAS,CAO1C;AAED,MAAM,MAAM,mBAAmB,GAC3B,KAAK,GACL,UAAU,GACV,SAAS,GACT,OAAO,GACP,KAAK,CAAC;AAEV,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,oBAAoB,CAAC,UAAU,CAAC,GACzC,mBAAmB,CAkBrB"}