@prabhask5/stellar-engine 1.1.11 → 1.1.13

package/dist/diagnostics.d.ts

@@ -0,0 +1,217 @@
+/**
+ * @fileoverview Unified Diagnostics Module
+ *
+ * Provides a single entry point for inspecting the internal state of the
+ * stellar-engine sync system. The main `getDiagnostics()` function returns a
+ * comprehensive JSON snapshot covering sync cycles, egress, queue, realtime,
+ * network, conflict history, errors, and configuration.
+ *
+ * Each call returns a **point-in-time snapshot** — the data is not reactive.
+ * For a live dashboard, the consumer app should poll `getDiagnostics()` at the
+ * desired frequency (e.g., via `setInterval` or `onSyncComplete` callback).
+ *
+ * Sub-category functions (`getSyncDiagnostics`, `getRealtimeDiagnostics`, etc.)
+ * are also exported for lightweight access to specific sections without
+ * incurring the cost of async operations (queue/conflict reads).
+ *
+ * **Dependency direction:** This module imports from engine, realtime, queue,
+ * conflicts, config, deviceId, stores, and utils. No module imports from
+ * diagnostics — this guarantees zero circular dependency risk.
+ *
+ * @module diagnostics
+ * @see {@link ./engine.ts} for the core sync engine
+ * @see {@link ./realtime.ts} for WebSocket connection management
+ * @see {@link ./conflicts.ts} for conflict resolution history
+ */
+import type { ConflictHistoryEntry, SyncStatus } from './types';
+import type { RealtimeConnectionState } from './realtime';
+import type { SyncError } from './stores/sync';
+/**
+ * Comprehensive diagnostics snapshot returned by {@link getDiagnostics}.
+ *
+ * Contains every observable aspect of the sync engine's runtime state,
+ * structured into logical sections for easy consumption by dashboards,
+ * logging pipelines, or browser console inspection.
+ */
+export interface DiagnosticsSnapshot {
+    /** ISO 8601 timestamp of when this snapshot was captured */
+    timestamp: string;
+    /** Engine prefix (e.g., `"engine"` or `"stellar"`) */
+    prefix: string;
+    /** Stable device identifier for this browser/device */
+    deviceId: string;
+    /** Sync cycle statistics and cursor state */
+    sync: {
+        status: SyncStatus;
+        totalCycles: number;
+        lastSyncTime: string | null;
+        lastSuccessfulSyncTimestamp: string | null;
+        syncMessage: string | null;
+        recentCycles: Array<{
+            timestamp: string;
+            trigger: string;
+            pushedItems: number;
+            pulledTables: number;
+            pulledRecords: number;
+            egressBytes: number;
+            durationMs: number;
+        }>;
+        cyclesLastMinute: number;
+        hasHydrated: boolean;
+        schemaValidated: boolean;
+        pendingCount: number;
+    };
+    /** Cumulative egress (bandwidth) statistics for the current session */
+    egress: {
+        sessionStart: string;
+        totalBytes: number;
+        totalFormatted: string;
+        totalRecords: number;
+        byTable: Record<string, {
+            bytes: number;
+            formatted: string;
+            records: number;
+            percentage: string;
+        }>;
+    };
+    /** Pending sync queue state */
+    queue: {
+        pendingOperations: number;
+        pendingEntityIds: string[];
+        byTable: Record<string, number>;
+        byOperationType: Record<string, number>;
+        oldestPendingTimestamp: string | null;
+        itemsInBackoff: number;
+    };
+    /** Realtime WebSocket connection state */
+    realtime: {
+        connectionState: RealtimeConnectionState;
+        healthy: boolean;
+        reconnectAttempts: number;
+        lastError: string | null;
+        userId: string | null;
+        deviceId: string;
+        recentlyProcessedCount: number;
+        operationInProgress: boolean;
+        reconnectScheduled: boolean;
+    };
+    /** Browser network connectivity */
+    network: {
+        online: boolean;
+    };
+    /** Engine-internal state (locks, visibility, auth) */
+    engine: {
+        isTabVisible: boolean;
+        tabHiddenAt: string | null;
+        lockHeld: boolean;
+        lockHeldForMs: number | null;
+        recentlyModifiedCount: number;
+        wasOffline: boolean;
+        authValidatedAfterReconnect: boolean;
+    };
+    /** Recent conflict resolution history */
+    conflicts: {
+        recentHistory: ConflictHistoryEntry[];
+        totalCount: number;
+    };
+    /** Error state from the sync status store */
+    errors: {
+        lastError: string | null;
+        lastErrorDetails: string | null;
+        recentErrors: SyncError[];
+    };
+    /** Engine configuration summary */
+    config: {
+        tableCount: number;
+        tableNames: string[];
+        syncDebounceMs: number;
+        syncIntervalMs: number;
+        tombstoneMaxAgeDays: number;
+    };
+}
+/**
+ * Capture a comprehensive diagnostics snapshot of the sync engine.
+ *
+ * This async function reads from all engine subsystems and returns a single
+ * JSON-serializable object. The async operations (queue reads, conflict
+ * history) are run in parallel for minimal latency.
+ *
+ * @returns A complete {@link DiagnosticsSnapshot}
+ *
+ * @example
+ * ```ts
+ * const snapshot = await getDiagnostics();
+ * console.log(JSON.stringify(snapshot, null, 2));
+ * ```
+ */
+export declare function getDiagnostics(): Promise<DiagnosticsSnapshot>;
+/**
+ * Get sync cycle and egress diagnostics (synchronous).
+ *
+ * @returns Sync stats, egress totals, and per-table breakdown
+ */
+export declare function getSyncDiagnostics(): Pick<DiagnosticsSnapshot, 'sync' | 'egress'>;
+/**
+ * Get realtime WebSocket connection diagnostics (synchronous).
+ *
+ * @returns Current realtime connection state and metadata
+ */
+export declare function getRealtimeDiagnostics(): {
+    connectionState: RealtimeConnectionState;
+    healthy: boolean;
+    reconnectAttempts: number;
+    lastError: string | null;
+    userId: string | null;
+    deviceId: string;
+    recentlyProcessedCount: number;
+    operationInProgress: boolean;
+    reconnectScheduled: boolean;
+};
+/**
+ * Get pending sync queue diagnostics (async — reads IndexedDB).
+ *
+ * @returns Pending operation count, entity IDs, and breakdowns by table/operation type
+ */
+export declare function getQueueDiagnostics(): Promise<DiagnosticsSnapshot['queue']>;
+/**
+ * Get conflict resolution history diagnostics (async — reads IndexedDB).
+ *
+ * @returns Recent conflict entries and total count
+ */
+export declare function getConflictDiagnostics(): Promise<{
+    recentHistory: ConflictHistoryEntry[];
+    totalCount: number;
+}>;
+/**
+ * Get engine-internal state diagnostics (synchronous).
+ *
+ * @returns Lock state, visibility, auth validation status
+ */
+export declare function getEngineDiagnostics(): {
+    isTabVisible: boolean;
+    tabHiddenAt: string | null;
+    lockHeld: boolean;
+    lockHeldForMs: number | null;
+    recentlyModifiedCount: number;
+    wasOffline: boolean;
+    authValidatedAfterReconnect: boolean;
+};
+/**
+ * Get network connectivity diagnostics (synchronous).
+ *
+ * @returns Current online/offline status
+ */
+export declare function getNetworkDiagnostics(): {
+    online: boolean;
+};
+/**
+ * Get error state diagnostics (synchronous).
+ *
+ * @returns Latest error info and recent error history
+ */
+export declare function getErrorDiagnostics(): {
+    lastError: string | null;
+    lastErrorDetails: string | null;
+    recentErrors: SyncError[];
+};
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/diagnostics.d.ts.map

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

package/dist/diagnostics.js

@@ -0,0 +1,266 @@
+/**
+ * @fileoverview Unified Diagnostics Module
+ *
+ * Provides a single entry point for inspecting the internal state of the
+ * stellar-engine sync system. The main `getDiagnostics()` function returns a
+ * comprehensive JSON snapshot covering sync cycles, egress, queue, realtime,
+ * network, conflict history, errors, and configuration.
+ *
+ * Each call returns a **point-in-time snapshot** — the data is not reactive.
+ * For a live dashboard, the consumer app should poll `getDiagnostics()` at the
+ * desired frequency (e.g., via `setInterval` or `onSyncComplete` callback).
+ *
+ * Sub-category functions (`getSyncDiagnostics`, `getRealtimeDiagnostics`, etc.)
+ * are also exported for lightweight access to specific sections without
+ * incurring the cost of async operations (queue/conflict reads).
+ *
+ * **Dependency direction:** This module imports from engine, realtime, queue,
+ * conflicts, config, deviceId, stores, and utils. No module imports from
+ * diagnostics — this guarantees zero circular dependency risk.
+ *
+ * @module diagnostics
+ * @see {@link ./engine.ts} for the core sync engine
+ * @see {@link ./realtime.ts} for WebSocket connection management
+ * @see {@link ./conflicts.ts} for conflict resolution history
+ */
+import { _getEngineDiagnostics } from './engine';
+import { _getRealtimeDiagnostics } from './realtime';
+import { _getRecentConflictHistory } from './conflicts';
+import { getPendingSync, getPendingEntityIds } from './queue';
+import { getEngineConfig } from './config';
+import { getDeviceId } from './deviceId';
+import { syncStatusStore } from './stores/sync';
+import { isOnline } from './stores/network';
+import { formatBytes } from './utils';
+import { get } from 'svelte/store';
+// =============================================================================
+// Main Diagnostics Function
+// =============================================================================
+/**
+ * Capture a comprehensive diagnostics snapshot of the sync engine.
+ *
+ * This async function reads from all engine subsystems and returns a single
+ * JSON-serializable object. The async operations (queue reads, conflict
+ * history) are run in parallel for minimal latency.
+ *
+ * @returns A complete {@link DiagnosticsSnapshot}
+ *
+ * @example
+ * ```ts
+ * const snapshot = await getDiagnostics();
+ * console.log(JSON.stringify(snapshot, null, 2));
+ * ```
+ */
+export async function getDiagnostics() {
+    const config = getEngineConfig();
+    const engineState = _getEngineDiagnostics();
+    const realtimeState = _getRealtimeDiagnostics();
+    const syncState = get(syncStatusStore);
+    // Run async operations in parallel
+    const [queueData, conflictData] = await Promise.all([
+        getQueueDiagnostics(),
+        getConflictDiagnostics()
+    ]);
+    // Build egress section with formatted values
+    const egressByTable = {};
+    for (const [table, stats] of Object.entries(engineState.egressStats.byTable)) {
+        const pct = engineState.egressStats.totalBytes > 0
+            ? ((stats.bytes / engineState.egressStats.totalBytes) * 100).toFixed(1)
+            : '0.0';
+        egressByTable[table] = {
+            bytes: stats.bytes,
+            formatted: formatBytes(stats.bytes),
+            records: stats.records,
+            percentage: `${pct}%`
+        };
+    }
+    // Count cycles in the last minute
+    const oneMinuteAgo = Date.now() - 60000;
+    const cyclesLastMinute = engineState.syncStats.filter((s) => new Date(s.timestamp).getTime() > oneMinuteAgo).length;
+    return {
+        timestamp: new Date().toISOString(),
+        prefix: config.prefix || 'engine',
+        deviceId: getDeviceId(),
+        sync: {
+            status: syncState.status,
+            totalCycles: engineState.totalSyncCycles,
+            lastSyncTime: syncState.lastSyncTime,
+            lastSuccessfulSyncTimestamp: engineState.lastSuccessfulSyncTimestamp
+                ? new Date(engineState.lastSuccessfulSyncTimestamp).toISOString()
+                : null,
+            syncMessage: syncState.syncMessage,
+            recentCycles: engineState.syncStats,
+            cyclesLastMinute,
+            hasHydrated: engineState.hasHydrated,
+            schemaValidated: engineState.schemaValidated,
+            pendingCount: syncState.pendingCount
+        },
+        egress: {
+            sessionStart: engineState.egressStats.sessionStart,
+            totalBytes: engineState.egressStats.totalBytes,
+            totalFormatted: formatBytes(engineState.egressStats.totalBytes),
+            totalRecords: engineState.egressStats.totalRecords,
+            byTable: egressByTable
+        },
+        queue: queueData,
+        realtime: realtimeState,
+        network: getNetworkDiagnostics(),
+        engine: {
+            isTabVisible: engineState.isTabVisible,
+            tabHiddenAt: engineState.tabHiddenAt ? new Date(engineState.tabHiddenAt).toISOString() : null,
+            lockHeld: engineState.lockHeld,
+            lockHeldForMs: engineState.lockHeldForMs,
+            recentlyModifiedCount: engineState.recentlyModifiedCount,
+            wasOffline: engineState.wasOffline,
+            authValidatedAfterReconnect: engineState.authValidatedAfterReconnect
+        },
+        conflicts: conflictData,
+        errors: getErrorDiagnostics(),
+        config: {
+            tableCount: config.tables.length,
+            tableNames: config.tables.map((t) => t.supabaseName),
+            syncDebounceMs: config.syncDebounceMs ?? 2000,
+            syncIntervalMs: config.syncIntervalMs ?? 900000,
+            tombstoneMaxAgeDays: config.tombstoneMaxAgeDays ?? 7
+        }
+    };
+}
+// =============================================================================
+// Sub-Category Diagnostics Functions
+// =============================================================================
+/**
+ * Get sync cycle and egress diagnostics (synchronous).
+ *
+ * @returns Sync stats, egress totals, and per-table breakdown
+ */
+export function getSyncDiagnostics() {
+    const engineState = _getEngineDiagnostics();
+    const syncState = get(syncStatusStore);
+    const egressByTable = {};
+    for (const [table, stats] of Object.entries(engineState.egressStats.byTable)) {
+        const pct = engineState.egressStats.totalBytes > 0
+            ? ((stats.bytes / engineState.egressStats.totalBytes) * 100).toFixed(1)
+            : '0.0';
+        egressByTable[table] = {
+            bytes: stats.bytes,
+            formatted: formatBytes(stats.bytes),
+            records: stats.records,
+            percentage: `${pct}%`
+        };
+    }
+    const oneMinuteAgo = Date.now() - 60000;
+    const cyclesLastMinute = engineState.syncStats.filter((s) => new Date(s.timestamp).getTime() > oneMinuteAgo).length;
+    return {
+        sync: {
+            status: syncState.status,
+            totalCycles: engineState.totalSyncCycles,
+            lastSyncTime: syncState.lastSyncTime,
+            lastSuccessfulSyncTimestamp: engineState.lastSuccessfulSyncTimestamp
+                ? new Date(engineState.lastSuccessfulSyncTimestamp).toISOString()
+                : null,
+            syncMessage: syncState.syncMessage,
+            recentCycles: engineState.syncStats,
+            cyclesLastMinute,
+            hasHydrated: engineState.hasHydrated,
+            schemaValidated: engineState.schemaValidated,
+            pendingCount: syncState.pendingCount
+        },
+        egress: {
+            sessionStart: engineState.egressStats.sessionStart,
+            totalBytes: engineState.egressStats.totalBytes,
+            totalFormatted: formatBytes(engineState.egressStats.totalBytes),
+            totalRecords: engineState.egressStats.totalRecords,
+            byTable: egressByTable
+        }
+    };
+}
+/**
+ * Get realtime WebSocket connection diagnostics (synchronous).
+ *
+ * @returns Current realtime connection state and metadata
+ */
+export function getRealtimeDiagnostics() {
+    return _getRealtimeDiagnostics();
+}
+/**
+ * Get pending sync queue diagnostics (async — reads IndexedDB).
+ *
+ * @returns Pending operation count, entity IDs, and breakdowns by table/operation type
+ */
+export async function getQueueDiagnostics() {
+    const pending = await getPendingSync();
+    const entityIds = await getPendingEntityIds();
+    // Breakdown by table
+    const byTable = {};
+    const byOperationType = {};
+    let oldestTimestamp = null;
+    let itemsInBackoff = 0;
+    for (const item of pending) {
+        byTable[item.table] = (byTable[item.table] || 0) + 1;
+        byOperationType[item.operationType] = (byOperationType[item.operationType] || 0) + 1;
+        if (!oldestTimestamp || item.timestamp < oldestTimestamp) {
+            oldestTimestamp = item.timestamp;
+        }
+        if (item.retries > 0) {
+            itemsInBackoff++;
+        }
+    }
+    return {
+        pendingOperations: pending.length,
+        pendingEntityIds: Array.from(entityIds),
+        byTable,
+        byOperationType,
+        oldestPendingTimestamp: oldestTimestamp,
+        itemsInBackoff
+    };
+}
+/**
+ * Get conflict resolution history diagnostics (async — reads IndexedDB).
+ *
+ * @returns Recent conflict entries and total count
+ */
+export async function getConflictDiagnostics() {
+    const { entries, totalCount } = await _getRecentConflictHistory();
+    return { recentHistory: entries, totalCount };
+}
+/**
+ * Get engine-internal state diagnostics (synchronous).
+ *
+ * @returns Lock state, visibility, auth validation status
+ */
+export function getEngineDiagnostics() {
+    const engineState = _getEngineDiagnostics();
+    return {
+        isTabVisible: engineState.isTabVisible,
+        tabHiddenAt: engineState.tabHiddenAt ? new Date(engineState.tabHiddenAt).toISOString() : null,
+        lockHeld: engineState.lockHeld,
+        lockHeldForMs: engineState.lockHeldForMs,
+        recentlyModifiedCount: engineState.recentlyModifiedCount,
+        wasOffline: engineState.wasOffline,
+        authValidatedAfterReconnect: engineState.authValidatedAfterReconnect
+    };
+}
+/**
+ * Get network connectivity diagnostics (synchronous).
+ *
+ * @returns Current online/offline status
+ */
+export function getNetworkDiagnostics() {
+    return {
+        online: get(isOnline)
+    };
+}
+/**
+ * Get error state diagnostics (synchronous).
+ *
+ * @returns Latest error info and recent error history
+ */
+export function getErrorDiagnostics() {
+    const syncState = get(syncStatusStore);
+    return {
+        lastError: syncState.lastError,
+        lastErrorDetails: syncState.lastErrorDetails,
+        recentErrors: syncState.syncErrors
+    };
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/diagnostics.js.map

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

package/dist/engine.d.ts

@@ -73,6 +73,16 @@
  * ```
  */
 export declare function clearPendingSyncQueue(): Promise<number>;
+/** Stats captured for each sync cycle (push + pull) */
+interface SyncCycleStats {
+    timestamp: string;
+    trigger: string;
+    pushedItems: number;
+    pulledTables: number;
+    pulledRecords: number;
+    egressBytes: number;
+    durationMs: number;
+}
 /**
  * Mark an entity as recently modified to protect it from being overwritten by pull.
  *
@@ -82,6 +92,39 @@ export declare function clearPendingSyncQueue(): Promise<number>;
  * @param entityId - The UUID of the entity that was just modified locally
  */
 export declare function markEntityModified(entityId: string): void;
+/**
+ * Return a snapshot of engine-internal state for diagnostics.
+ *
+ * This function is prefixed with `_` to signal that it exposes module-private
+ * state and should only be consumed by the diagnostics module.
+ *
+ * @returns A plain object containing current engine state values
+ */
+export declare function _getEngineDiagnostics(): {
+    syncStats: SyncCycleStats[];
+    totalSyncCycles: number;
+    egressStats: {
+        byTable: {
+            [x: string]: {
+                bytes: number;
+                records: number;
+            };
+        };
+        totalBytes: number;
+        totalRecords: number;
+        sessionStart: string;
+    };
+    hasHydrated: boolean;
+    schemaValidated: boolean;
+    isTabVisible: boolean;
+    tabHiddenAt: number | null;
+    lockHeld: boolean;
+    lockHeldForMs: number | null;
+    recentlyModifiedCount: number;
+    wasOffline: boolean;
+    authValidatedAfterReconnect: boolean;
+    lastSuccessfulSyncTimestamp: number;
+};
 /**
  * Register a callback to be invoked when a sync cycle completes.
  *
@@ -145,16 +188,16 @@ export declare function runFullSync(quiet?: boolean, skipPull?: boolean): Promis
  * This is the main "boot" function for the sync engine. It:
  * 1. Ensures the Dexie DB is open and upgraded
  * 2. Cleans up any existing listeners (idempotent restart support)
- * 3. Sets up debug window utilities
- * 4. Subscribes to Supabase auth state changes (handles sign-out/token-refresh)
- * 5. Registers online/offline handlers with auth validation
- * 6. Registers visibility change handler for smart tab-return syncing
- * 7. Starts realtime WebSocket subscriptions
- * 8. Starts periodic background sync interval
- * 9. Validates Supabase schema (one-time)
- * 10. Runs initial hydration (if local DB is empty) or full sync
- * 11. Runs initial cleanup (tombstones, conflicts, failed items)
- * 12. Starts the watchdog timer
+ * 3. Subscribes to Supabase auth state changes (handles sign-out/token-refresh)
+ * 4. Registers online/offline handlers with auth validation
+ * 5. Registers visibility change handler for smart tab-return syncing
+ * 6. Starts realtime WebSocket subscriptions
+ * 7. Starts periodic background sync interval
+ * 8. Validates Supabase schema (one-time)
+ * 9. Runs initial hydration (if local DB is empty) or full sync
+ * 10. Runs initial cleanup (tombstones, conflicts, failed items)
+ * 11. Starts the watchdog timer
+ * 12. Registers debug window utilities (Tombstones, Sync, Diagnostics)
  *
  * **Must be called after `initEngine()`** — requires configuration to be set.
  * Safe to call multiple times (previous listeners are cleaned up first).
@@ -183,4 +226,5 @@ export declare function stopSyncEngine(): Promise<void>;
  * database is still open when clearing tables.
  */
 export declare function clearLocalCache(): Promise<void>;
+export {};
 //# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AA8KH;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,MAAM,CAAC,CAW7D;AA4TD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAEzD;AA4KD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAO/D;AAuCD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAavC;AAu7BD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,WAAW,CAC/B,KAAK,GAAE,OAAe,EACtB,QAAQ,GAAE,OAAe,GACxB,OAAO,CAAC,IAAI,CAAC,CA0Mf;AAilBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CA6ZrD;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAuDpD;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CA2BrD"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AA+KH;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,MAAM,CAAC,CAW7D;AAuCD,uDAAuD;AACvD,UAAU,cAAc;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAgLD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAEzD;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB;;;;;;uBAxLF,MAAM;yBAAW,MAAM;;;oBAF5C,MAAM;sBACJ,MAAM;sBAEN,MAAM;;;;;;;;;;;;EAuMrB;AAgLD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAO/D;AAuCD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAavC;AA67BD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,WAAW,CAC/B,KAAK,GAAE,OAAe,EACtB,QAAQ,GAAE,OAAe,GACxB,OAAO,CAAC,IAAI,CAAC,CA0Mf;AAolBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAuYrD;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CA+DpD;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CA2BrD"}