@kaleidorg/wallet-engine 1.0.0-beta.4 → 1.0.0-beta.41

package/dist/lib/arkade-swaps-client-manager.js

@@ -0,0 +1,127 @@
+/**
+ * Arkade Swaps Client Manager
+ *
+ * Singleton that owns an `ArkadeSwaps` instance from `@arkade-os/boltz-swap`.
+ * Provides Boltz-based swaps between Arkade VTXOs and Lightning / on-chain BTC.
+ *
+ * Initialization is non-blocking: callers should attempt to use the client
+ * via `getClient()` and gracefully fall back when `isInitialized()` is false
+ * (e.g. on cold-start before the post-unlock init has finished).
+ *
+ * Lifecycle:
+ *   - Arkade adapter connect  → `initialize(wallet)`
+ *   - Arkade adapter disconnect → `dispose()`
+ *
+ * The default repository is IndexedDB-backed so pending submarine / reverse /
+ * chain swaps survive a service-worker restart and are auto-claimed/refunded by
+ * the embedded `SwapManager`. Non-browser hosts (React Native) must inject a
+ * platform-appropriate `swapRepository` via `initialize(wallet, { swapRepository })`.
+ */
+import { ArkadeSwaps, IndexedDbSwapRepository } from "@arkade-os/boltz-swap";
+import { log } from "./log.js";
+/** Default IndexedDB database name for swap persistence. */
+const DEFAULT_DB_NAME = "kaleidoswap-arkade-swaps";
+class ArkadeSwapsClientManager {
+    constructor() {
+        this.client = null;
+        /** Serializes concurrent initialize() calls. */
+        this._initPromise = null;
+        /** Generation of the in-flight _initPromise. */
+        this._initGeneration = 0;
+        /** Bumped by dispose() to invalidate any in-flight init. */
+        this._generation = 0;
+    }
+    /**
+     * Initialize the swaps client with a connected Arkade wallet.
+     * Concurrent calls that belong to the same generation share the in-flight
+     * promise. A dispose() between calls bumps the generation so the old
+     * in-flight is treated as stale and a fresh init is started.
+     */
+    initialize(wallet, opts) {
+        if (this.client)
+            return Promise.resolve();
+        // Reuse in-flight promise only if it belongs to the current generation.
+        if (this._initPromise && this._initGeneration === this._generation) {
+            return this._initPromise;
+        }
+        const generation = this._generation;
+        this._initGeneration = generation;
+        const promise = this._doInitialize(wallet, generation, opts).finally(() => {
+            // Only clear if this promise is still the active one (prevents stale
+            // promises from clearing a newer in-flight init).
+            if (this._initPromise === promise && this._initGeneration === generation) {
+                this._initPromise = null;
+            }
+        });
+        this._initPromise = promise;
+        return this._initPromise;
+    }
+    async _doInitialize(wallet, generation, opts) {
+        try {
+            const swapRepository = opts?.swapRepository ?? new IndexedDbSwapRepository(opts?.dbName ?? DEFAULT_DB_NAME);
+            const client = await ArkadeSwaps.create({
+                wallet,
+                // The SwapManager monitors pending swaps in the background and
+                // auto-claims reverse swaps / auto-refunds failed submarine swaps.
+                swapManager: true,
+                swapRepository,
+            });
+            // Guard: dispose() may have been called while ArkadeSwaps.create was
+            // awaited. If the generation has changed the wallet is stale — discard.
+            if (generation !== this._generation) {
+                try {
+                    await client.dispose();
+                }
+                catch {
+                    /* ignore cleanup errors */
+                }
+                log.warn("[ArkadeSwapsClientManager] Stale init discarded (generation changed during ArkadeSwaps.create)");
+                return;
+            }
+            this.client = client;
+            log.info("[ArkadeSwapsClientManager] Initialized (Boltz swaps ready)");
+        }
+        catch (error) {
+            // Only clear client if this init's generation is still current (prevents
+            // a stale failed init from clearing a newer successful client).
+            if (generation === this._generation) {
+                this.client = null;
+            }
+            const msg = error instanceof Error ? error.message : String(error);
+            log.warn(`[ArkadeSwapsClientManager] Failed to initialize: ${msg}. Lightning swaps will be unavailable until reconnect.`);
+            throw error;
+        }
+    }
+    isInitialized() {
+        return this.client !== null;
+    }
+    /** @throws if not initialized */
+    getClient() {
+        if (!this.client) {
+            throw new Error("Arkade swaps client not initialized. Call initialize() first.");
+        }
+        return this.client;
+    }
+    /**
+     * Stop the embedded SwapManager and release resources. Safe to call when
+     * the client was never initialized.
+     */
+    async dispose() {
+        // Bump generation first so any in-flight _doInitialize sees the change
+        // even if ArkadeSwaps.create() has not returned yet.
+        this._generation++;
+        if (!this.client)
+            return;
+        try {
+            await this.client.dispose();
+        }
+        catch (error) {
+            log.warn("[ArkadeSwapsClientManager] Error during dispose:", error);
+        }
+        finally {
+            this.client = null;
+        }
+    }
+}
+export const arkadeSwapsClientManager = new ArkadeSwapsClientManager();
+//# sourceMappingURL=arkade-swaps-client-manager.js.map

package/dist/lib/arkade-swaps-client-manager.js.map

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

package/dist/lib/arkade-vtxo-lifecycle.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Arkade VTXO Lifecycle + Delegator management (platform-agnostic core).
+ *
+ * This module is deliberately free of any platform API (`chrome.*`, timers,
+ * notifications, storage). Consumers drive it:
+ *   - The browser extension runs `runArkadeVtxoLifecycle()` from a
+ *     `chrome.alarms` tick and maps the result to `chrome.notifications` +
+ *     runtime broadcasts via the `callbacks`.
+ *   - React Native schedules it however it prefers.
+ *
+ * It covers:
+ *   - VTXO auto-renewal      — renew VTXOs approaching expiry
+ *   - Orphan VTXO recovery   — surface recoverable (swept/expired) balance
+ *   - Boarding UTXO expiry   — surface expired boarding UTXOs
+ *   - VTXO delegation        — delegate spendable VTXOs when enabled
+ *
+ * @arkade-os/sdk is referenced by TYPE only (erased at compile time), so this
+ * module is safe to export from the engine's root barrel.
+ */
+import type { VtxoManager, Wallet } from "@arkade-os/sdk";
+/** Delegator service endpoints per network. */
+export declare const ARKADE_DELEGATOR_URLS: {
+    readonly signet: "https://delegator.mutinynet.arkade.sh";
+    readonly mainnet: "https://delegate.arkade.money";
+};
+export declare const DEFAULT_DELEGATOR_URL: "https://delegate.arkade.money";
+/** Seconds before batch expiry at which a VTXO becomes eligible for auto-renewal (3 days). */
+export declare const DEFAULT_VTXO_THRESHOLD_SECONDS = 259200;
+export type ArkadeNetwork = "mainnet" | "signet";
+export interface ArkadeLifecycleSettings {
+    delegatorUrl: string;
+    delegationEnabled: boolean;
+    vtxoThresholdSeconds: number;
+}
+/**
+ * Coerce a raw delegator URL to a safe HTTPS URL, falling back to the
+ * network default when missing / non-HTTPS / unparseable.
+ */
+export declare function sanitizeDelegatorUrl(rawUrl: unknown, network?: ArkadeNetwork): string;
+/** Coerce a raw delegation-enabled flag to a boolean (defaults to true when undefined). */
+export declare function sanitizeDelegationEnabled(rawValue: unknown): boolean;
+/** Coerce a raw threshold to a positive integer of seconds, defaulting to 3 days. */
+export declare function sanitizeVtxoThresholdSeconds(rawValue: unknown): number;
+/**
+ * Sanitize a raw lifecycle-settings object into a clean `ArkadeLifecycleSettings`.
+ * Consumers read platform storage into a raw object and pass it here — storage
+ * key naming stays consumer-side; the normalized shape + validation lives here.
+ */
+export declare function resolveArkadeLifecycleSettings(raw: {
+    delegatorUrl?: unknown;
+    delegationEnabled?: unknown;
+    vtxoThresholdSeconds?: unknown;
+    network?: ArkadeNetwork;
+}): ArkadeLifecycleSettings;
+export interface ArkadeDelegateResult {
+    delegated: number;
+    failed: number;
+}
+export interface ArkadeDelegateInfo {
+    configured: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Delegate all currently-spendable (settled/preconfirmed) VTXOs to the
+ * configured delegator. Returns `{ delegated: 0, failed: 0 }` when delegation
+ * is not configured or there is nothing to delegate.
+ */
+export declare function delegateSpendableVtxos(wallet: Wallet): Promise<ArkadeDelegateResult>;
+/**
+ * Resolve delegate info from the wallet's delegator manager. Returns
+ * `{ configured: false }` when delegation is not configured.
+ */
+export declare function getArkadeDelegateInfo(wallet: Wallet): Promise<ArkadeDelegateInfo>;
+export interface ArkadeLifecycleRunConfig {
+    delegationEnabled?: boolean;
+    delegatorUrl?: string;
+}
+export interface ArkadeLifecycleCallbacks {
+    /** Fired after a successful renewal round with the renewed count + commitment txid. */
+    onVtxosRenewed?(info: {
+        count: number;
+        txid: string;
+    }): void;
+    /** Fired per SDK renewal-progress event (event.type). */
+    onRenewalEvent?(eventType: string): void;
+    /** Fired for any stage error; the run continues to the next stage. */
+    onError?(stage: string, error: unknown): void;
+}
+export interface ArkadeRecoverableBalance {
+    recoverable: bigint;
+    subdust: bigint;
+    includesSubdust: boolean;
+    vtxoCount: number;
+}
+export interface ArkadeVtxoLifecycleResult {
+    renewed: {
+        count: number;
+        txid: string;
+    } | null;
+    recoverable: ArkadeRecoverableBalance | null;
+    expiredBoardingCount: number;
+    delegated: ArkadeDelegateResult | null;
+    errors: string[];
+}
+/**
+ * Run one pass of the VTXO lifecycle. Every stage is best-effort and isolated:
+ * a failure in one stage is recorded in `result.errors` (and reported via
+ * `callbacks.onError`) but never aborts the remaining stages.
+ */
+export declare function runArkadeVtxoLifecycle(args: {
+    vtxoManager: VtxoManager;
+    wallet: Wallet;
+    config?: ArkadeLifecycleRunConfig;
+    callbacks?: ArkadeLifecycleCallbacks;
+}): Promise<ArkadeVtxoLifecycleResult>;
+//# sourceMappingURL=arkade-vtxo-lifecycle.d.ts.map

package/dist/lib/arkade-vtxo-lifecycle.d.ts.map

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

package/dist/lib/arkade-vtxo-lifecycle.js

@@ -0,0 +1,184 @@
+/**
+ * Arkade VTXO Lifecycle + Delegator management (platform-agnostic core).
+ *
+ * This module is deliberately free of any platform API (`chrome.*`, timers,
+ * notifications, storage). Consumers drive it:
+ *   - The browser extension runs `runArkadeVtxoLifecycle()` from a
+ *     `chrome.alarms` tick and maps the result to `chrome.notifications` +
+ *     runtime broadcasts via the `callbacks`.
+ *   - React Native schedules it however it prefers.
+ *
+ * It covers:
+ *   - VTXO auto-renewal      — renew VTXOs approaching expiry
+ *   - Orphan VTXO recovery   — surface recoverable (swept/expired) balance
+ *   - Boarding UTXO expiry   — surface expired boarding UTXOs
+ *   - VTXO delegation        — delegate spendable VTXOs when enabled
+ *
+ * @arkade-os/sdk is referenced by TYPE only (erased at compile time), so this
+ * module is safe to export from the engine's root barrel.
+ */
+// ---------------------------------------------------------------------------
+// Settings — normalized shape + sanitizers + defaults
+// ---------------------------------------------------------------------------
+/** Delegator service endpoints per network. */
+export const ARKADE_DELEGATOR_URLS = {
+    signet: "https://delegator.mutinynet.arkade.sh",
+    mainnet: "https://delegate.arkade.money",
+};
+export const DEFAULT_DELEGATOR_URL = ARKADE_DELEGATOR_URLS.mainnet;
+/** Seconds before batch expiry at which a VTXO becomes eligible for auto-renewal (3 days). */
+export const DEFAULT_VTXO_THRESHOLD_SECONDS = 259200;
+/**
+ * Coerce a raw delegator URL to a safe HTTPS URL, falling back to the
+ * network default when missing / non-HTTPS / unparseable.
+ */
+export function sanitizeDelegatorUrl(rawUrl, network = "mainnet") {
+    const defaultUrl = ARKADE_DELEGATOR_URLS[network];
+    if (typeof rawUrl !== "string")
+        return defaultUrl;
+    const trimmed = rawUrl.trim();
+    if (trimmed.length === 0)
+        return defaultUrl;
+    try {
+        const url = new URL(trimmed);
+        if (url.protocol !== "https:")
+            return defaultUrl;
+    }
+    catch {
+        return defaultUrl;
+    }
+    return trimmed;
+}
+/** Coerce a raw delegation-enabled flag to a boolean (defaults to true when undefined). */
+export function sanitizeDelegationEnabled(rawValue) {
+    if (rawValue === undefined)
+        return true;
+    if (typeof rawValue === "boolean")
+        return rawValue;
+    if (typeof rawValue === "number")
+        return rawValue !== 0 && !Number.isNaN(rawValue);
+    if (typeof rawValue === "string") {
+        const normalized = rawValue.trim().toLowerCase();
+        return normalized === "true" || normalized === "1" || normalized === "yes";
+    }
+    return false;
+}
+/** Coerce a raw threshold to a positive integer of seconds, defaulting to 3 days. */
+export function sanitizeVtxoThresholdSeconds(rawValue) {
+    const parsed = typeof rawValue === "number" ? rawValue : typeof rawValue === "string" ? Number(rawValue) : NaN;
+    return Number.isFinite(parsed) && parsed > 0
+        ? Math.floor(parsed)
+        : DEFAULT_VTXO_THRESHOLD_SECONDS;
+}
+/**
+ * Sanitize a raw lifecycle-settings object into a clean `ArkadeLifecycleSettings`.
+ * Consumers read platform storage into a raw object and pass it here — storage
+ * key naming stays consumer-side; the normalized shape + validation lives here.
+ */
+export function resolveArkadeLifecycleSettings(raw) {
+    const network = raw.network ?? "mainnet";
+    return {
+        delegatorUrl: sanitizeDelegatorUrl(raw.delegatorUrl, network),
+        delegationEnabled: sanitizeDelegationEnabled(raw.delegationEnabled),
+        vtxoThresholdSeconds: sanitizeVtxoThresholdSeconds(raw.vtxoThresholdSeconds),
+    };
+}
+/**
+ * Delegate all currently-spendable (settled/preconfirmed) VTXOs to the
+ * configured delegator. Returns `{ delegated: 0, failed: 0 }` when delegation
+ * is not configured or there is nothing to delegate.
+ */
+export async function delegateSpendableVtxos(wallet) {
+    const delegatorManager = await wallet.getDelegatorManager();
+    if (!delegatorManager) {
+        return { delegated: 0, failed: 0 };
+    }
+    const vtxos = await wallet.getVtxos();
+    const spendable = vtxos.filter((v) => v.virtualStatus?.state === "settled" || v.virtualStatus?.state === "preconfirmed");
+    if (spendable.length === 0) {
+        return { delegated: 0, failed: 0 };
+    }
+    const ownAddress = await wallet.getAddress();
+    // ExtendedVirtualCoin carries all ContractVtxo fields at runtime; the SDK
+    // populates contractScript on delegation-eligible VTXOs.
+    const result = await delegatorManager.delegate(spendable, ownAddress);
+    return { delegated: result.delegated.length, failed: result.failed.length };
+}
+/**
+ * Resolve delegate info from the wallet's delegator manager. Returns
+ * `{ configured: false }` when delegation is not configured.
+ */
+export async function getArkadeDelegateInfo(wallet) {
+    const delegatorManager = await wallet.getDelegatorManager();
+    if (!delegatorManager) {
+        return { configured: false };
+    }
+    const info = await delegatorManager.getDelegateInfo();
+    return { configured: true, ...info };
+}
+/**
+ * Run one pass of the VTXO lifecycle. Every stage is best-effort and isolated:
+ * a failure in one stage is recorded in `result.errors` (and reported via
+ * `callbacks.onError`) but never aborts the remaining stages.
+ */
+export async function runArkadeVtxoLifecycle(args) {
+    const { vtxoManager, wallet, config, callbacks } = args;
+    const result = {
+        renewed: null,
+        recoverable: null,
+        expiredBoardingCount: 0,
+        delegated: null,
+        errors: [],
+    };
+    const record = (stage, error) => {
+        const msg = error instanceof Error ? error.message : String(error);
+        result.errors.push(`${stage}: ${msg}`);
+        callbacks?.onError?.(stage, error);
+    };
+    // 1. Auto-renewal — renew VTXOs approaching expiry.
+    try {
+        const expiringVtxos = await vtxoManager.getExpiringVtxos();
+        if (expiringVtxos.length > 0) {
+            const txid = await vtxoManager.renewVtxos((event) => {
+                callbacks?.onRenewalEvent?.(event.type);
+            });
+            result.renewed = { count: expiringVtxos.length, txid };
+            callbacks?.onVtxosRenewed?.({ count: expiringVtxos.length, txid });
+        }
+    }
+    catch (error) {
+        record("renew", error);
+    }
+    // 2. Orphan recovery — surface recoverable balance.
+    try {
+        const balance = await vtxoManager.getRecoverableBalance();
+        result.recoverable = {
+            recoverable: balance.recoverable,
+            subdust: balance.subdust,
+            includesSubdust: balance.includesSubdust,
+            vtxoCount: balance.vtxoCount,
+        };
+    }
+    catch (error) {
+        record("recoverable", error);
+    }
+    // 3. Boarding UTXO expiry — surface expired boarding UTXOs.
+    try {
+        const expired = await vtxoManager.getExpiredBoardingUtxos();
+        result.expiredBoardingCount = expired.length;
+    }
+    catch (error) {
+        record("boarding-expiry", error);
+    }
+    // 4. Delegation — delegate spendable VTXOs when enabled + configured.
+    if (config?.delegationEnabled && config?.delegatorUrl) {
+        try {
+            result.delegated = await delegateSpendableVtxos(wallet);
+        }
+        catch (error) {
+            record("delegate", error);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=arkade-vtxo-lifecycle.js.map

package/dist/lib/arkade-vtxo-lifecycle.js.map

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

package/dist/lib/flashnet-client-manager.d.ts

@@ -1,23 +1,40 @@
 /**
  * Flashnet Client Manager
- * Manages the lifecycle of a FlashnetClient from @flashnet/sdk.
+ * Singleton managing the lifecycle of a FlashnetClient from `@flashnet/sdk`.
  * Requires an initialized SparkWallet to function.
- * Ported from rate-extension/src/lib/flashnet-client-manager.ts
+ *
+ * Ported from rate-extension/src/protocols/spark/flashnet-client-manager.ts.
+ * The SDK is a value import (optional dependency) — consumers install
+ * `@flashnet/sdk` to use this manager, matching the Spark client-manager convention.
  */
-import { type FlashnetNetwork } from '../types/flashnet';
+import type { SparkWallet } from '@buildonspark/spark-sdk';
+import { FlashnetClient, type WalletBalance } from '@flashnet/sdk';
+import { type FlashnetNetwork } from '../types/flashnet.js';
+import type { SparkConfig } from '../types/spark.js';
 declare class FlashnetClientManager {
     private client;
     private initPromise;
     private poolId;
     private network;
+    initialize(wallet: SparkWallet, sparkNetwork?: SparkConfig['network']): Promise<void>;
+    private doInitialize;
     /**
-     * Initialize with a SparkWallet instance.
-     * @param wallet - SparkWallet from @buildonspark/spark-sdk
-     * @param sparkNetwork - The Spark network ('mainnet' | 'regtest')
+     * Fetch the wallet's AMM swap history and persist the outgoing (token-in)
+     * legs to the sent-token outbox.
+     *
+     * A swap moves a token to the pool via an internal SDK transfer that the
+     * Spark token-transaction query cannot classify as a send. Flashnet's
+     * `GET /v1/swaps/user/{pubkey}` returns every past swap with explicit
+     * direction (assetIn / amountIn / inboundTransferId), so this both fixes
+     * future swaps and recovers ones made before any recording existed.
+     *
+     * Idempotent — records are keyed by transfer hash, so re-running on each
+     * connect simply refreshes them.
      */
-    initialize(wallet: any, sparkNetwork?: string): Promise<void>;
-    private doInitialize;
-    getClient(): any;
+    private backfillSwapHistory;
+    getClient(): FlashnetClient;
+    /** Convenience pass-through so callers don't need to await client.getBalance() through a cast. */
+    getBalance(): Promise<WalletBalance>;
     getPoolId(): string | null;
     getNetwork(): FlashnetNetwork | null;
     getUsdbTokenAddress(): string;

package/dist/lib/flashnet-client-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flashnet-client-manager.d.ts","sourceRoot":"","sources":["../../src/lib/flashnet-client-manager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,mBAAmB,CAAA;AAkB1B,cAAM,qBAAqB;IACzB,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,OAAO,CAA+B;IAE9C;;;;OAIG;IACH,UAAU,CAAC,MAAM,EAAE,GAAG,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAQ/C,YAAY;IAuC1B,SAAS,IAAI,GAAG;IAOhB,SAAS,IAAI,MAAM,GAAG,IAAI;IAI1B,UAAU,IAAI,eAAe,GAAG,IAAI;IAIpC,mBAAmB,IAAI,MAAM;IAO7B,aAAa,IAAI,OAAO;IAIlB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CAalC;AAED,eAAO,MAAM,qBAAqB,uBAA8B,CAAA"}
+{"version":3,"file":"flashnet-client-manager.d.ts","sourceRoot":"","sources":["../../src/lib/flashnet-client-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,EAAE,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,eAAe,CAAA;AAClE,OAAO,EAML,KAAK,eAAe,EACrB,MAAM,mBAAmB,CAAA;AAG1B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAkBjD,cAAM,qBAAqB;IACzB,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,OAAO,CAA+B;IAE9C,UAAU,CAAC,MAAM,EAAE,WAAW,EAAE,YAAY,CAAC,EAAE,WAAW,CAAC,SAAS,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;YAQvE,YAAY;IAqD1B;;;;;;;;;;;;OAYG;YACW,mBAAmB;IA4DjC,SAAS,IAAI,cAAc;IAO3B,kGAAkG;IAC5F,UAAU,IAAI,OAAO,CAAC,aAAa,CAAC;IAI1C,SAAS,IAAI,MAAM,GAAG,IAAI;IAI1B,UAAU,IAAI,eAAe,GAAG,IAAI;IAIpC,mBAAmB,IAAI,MAAM;IAO7B,aAAa,IAAI,OAAO;IAIlB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CAalC;AAED,eAAO,MAAM,qBAAqB,uBAA8B,CAAA"}