@lifi/perps-sdk 0.1.1-alpha.9 → 1.0.0

package/dist/esm/websocket/WsProviderBase.js

@@ -0,0 +1,246 @@
+import { wsLog } from './wsLog.js';
+/**
+ * Linger before tearing a channel off the wire after its last listener
+ * releases. A re-subscribe to the same key within this window cancels the
+ * pending teardown, so React StrictMode's synchronous unmount→remount (ref
+ * count 1→0→1) and fast route flips collapse to one wire subscription rather
+ * than a subscribe→unsubscribe→subscribe churn the venue would reject.
+ *
+ * @public
+ */
+export const WS_CHANNEL_TEARDOWN_LINGER_MS = 250;
+/**
+ * Base for per-provider realtime transports. Owns the {@link
+ * ReconnectingWebSocket}, the fan-out lifecycle — ref-counted multi-listener
+ * subscription per channel key, deferred teardown, status fan-out — so any
+ * number of consumers (and StrictMode double-mounts) collapse to exactly one
+ * wire subscribe/unsubscribe per key, and the wire-subscription registry:
+ * subs recorded via {@link WsProviderBase.registerSub} are sent only while
+ * connected and replayed (failure-isolated) on every (re)open. Subclasses own
+ * everything wire-specific via {@link WsProviderBase.openChannel}, {@link
+ * WsProviderBase.sendSubscribe} and {@link WsProviderBase.handleMessage}:
+ * payload framing, frame validation and dispatch.
+ *
+ * `TSub` is the per-subscription state {@link WsProviderBase.sendSubscribe}
+ * needs to (re)build one subscribe frame.
+ *
+ * @public
+ */
+export class WsProviderBase {
+    rws;
+    providerKey;
+    channels = new Map();
+    statusListeners = new Map();
+    wireSubs = new Map();
+    constructor(rws, providerKey) {
+        this.providerKey = providerKey;
+        this.rws = rws;
+        this.rws.on('message', (data) => this.handleMessage(data));
+        this.rws.on('open', () => {
+            void this.replaySubs();
+        });
+        this.rws.onStatus((status) => {
+            for (const fn of this.statusListeners.keys()) {
+                this.callListener('status', fn, status);
+            }
+        });
+    }
+    async subscribe(sub, listener, onStatus) {
+        this.reconnect();
+        const key = this.toKey(sub);
+        await this.acquireChannel(key, sub, listener);
+        if (onStatus) {
+            this.statusListeners.set(onStatus, (this.statusListeners.get(onStatus) ?? 0) + 1);
+            onStatus(this.rws.getStatus());
+        }
+        return () => {
+            if (onStatus) {
+                const remaining = (this.statusListeners.get(onStatus) ?? 0) - 1;
+                if (remaining > 0) {
+                    this.statusListeners.set(onStatus, remaining);
+                }
+                else {
+                    this.statusListeners.delete(onStatus);
+                }
+            }
+            this.releaseChannel(key, listener);
+        };
+    }
+    reconnect() {
+        if (this.rws.getStatus() !== 'disconnected') {
+            return;
+        }
+        this.rws.reconnect();
+    }
+    close() {
+        for (const entry of this.channels.values()) {
+            if (entry.pendingTeardown !== undefined) {
+                clearTimeout(entry.pendingTeardown);
+            }
+        }
+        this.onClose();
+        this.rws.close();
+        this.channels.clear();
+        this.statusListeners.clear();
+        this.wireSubs.clear();
+    }
+    /** Deliver an event to every listener on `key`. */
+    emit(key, event) {
+        const entry = this.channels.get(key);
+        if (entry === undefined) {
+            return;
+        }
+        for (const fn of entry.listeners.keys()) {
+            this.callListener(`subscription:${key}`, fn, event);
+        }
+    }
+    /**
+     * Tear `key` off the wire immediately if no listener holds it — i.e. it is
+     * lingering in the deferred-teardown window (or its open is still
+     * unwinding). Returns `true` when the key is free (absent or just torn
+     * down), `false` — leaving the channel untouched — while live listeners
+     * hold it. Lets a subclass that enforces an exclusivity invariant across
+     * keys reclaim a released channel without waiting out the linger.
+     */
+    closeChannelIfIdle(key) {
+        const entry = this.channels.get(key);
+        if (entry === undefined) {
+            return true;
+        }
+        if (entry.listeners.size > 0) {
+            return false;
+        }
+        if (entry.pendingTeardown !== undefined) {
+            clearTimeout(entry.pendingTeardown);
+        }
+        entry.teardown?.();
+        this.channels.delete(key);
+        return true;
+    }
+    /**
+     * Record a wire subscription for replay-on-(re)open and, when the socket is
+     * already connected, send its subscribe frame via {@link sendSubscribe}.
+     * While the socket is down the replay loop on the next open is the sole
+     * sender — sending in both places would double-subscribe. A failed send
+     * removes the sub again so a rejected open leaves no registry entry behind.
+     */
+    async registerSub(key, state) {
+        this.wireSubs.set(key, state);
+        if (this.rws.getStatus() !== 'connected') {
+            return;
+        }
+        try {
+            await this.sendSubscribe(state);
+        }
+        catch (err) {
+            this.wireSubs.delete(key);
+            throw err;
+        }
+    }
+    /** Forget a wire subscription so the next (re)open no longer replays it. */
+    unregisterSub(key) {
+        this.wireSubs.delete(key);
+    }
+    async replaySubs() {
+        for (const [key, state] of this.wireSubs) {
+            // Isolate each resubscribe: a send can reject (e.g. an auth-token fetch
+            // after reconnect), and one sub's failure must not abort the rest of
+            // the loop or escape as an unhandled rejection.
+            try {
+                await this.sendSubscribe(state);
+            }
+            catch (err) {
+                wsLog.subscribeFailure(this.providerKey, key, err);
+            }
+        }
+    }
+    /** Release subclass-only resources on {@link close} (keep-alive, cached state). */
+    onClose() { }
+    callListener(listenerType, listener, ...args) {
+        try {
+            listener(...args);
+        }
+        catch (error) {
+            wsLog.listenerFailure(this.providerKey, listenerType, error);
+        }
+    }
+    async acquireChannel(key, sub, listener) {
+        let entry = this.channels.get(key);
+        if (entry === undefined) {
+            entry = { listeners: new Map() };
+            this.channels.set(key, entry);
+        }
+        // Register first (ref-counted) so a frame arriving during an in-flight open
+        // is delivered; cancel any pending teardown (re-subscribe within the linger).
+        entry.listeners.set(listener, (entry.listeners.get(listener) ?? 0) + 1);
+        if (entry.pendingTeardown !== undefined) {
+            clearTimeout(entry.pendingTeardown);
+            entry.pendingTeardown = undefined;
+        }
+        if (entry.teardown !== undefined) {
+            return;
+        }
+        if (entry.opening !== undefined) {
+            await entry.opening;
+            return;
+        }
+        const opening = this.openChannel(sub);
+        entry.opening = opening;
+        try {
+            const teardown = await opening;
+            const current = this.channels.get(key);
+            if (current === undefined || current.listeners.size === 0) {
+                // Every listener released while opening — unwind immediately.
+                teardown();
+                this.channels.delete(key);
+                return;
+            }
+            current.teardown = teardown;
+            current.opening = undefined;
+        }
+        catch (err) {
+            // Open failed: drop the channel so all (concurrent) subscribers reject
+            // cleanly and a later subscribe re-opens.
+            this.channels.delete(key);
+            throw err;
+        }
+    }
+    releaseChannel(key, listener) {
+        const entry = this.channels.get(key);
+        if (entry === undefined) {
+            return;
+        }
+        const remaining = (entry.listeners.get(listener) ?? 0) - 1;
+        if (remaining > 0) {
+            entry.listeners.set(listener, remaining);
+            return;
+        }
+        entry.listeners.delete(listener);
+        if (entry.listeners.size > 0) {
+            return;
+        }
+        if (entry.teardown === undefined) {
+            // Open not resolved yet — acquireChannel's post-open check unwinds it.
+            if (entry.opening === undefined) {
+                this.channels.delete(key);
+            }
+            return;
+        }
+        if (entry.pendingTeardown !== undefined) {
+            return;
+        }
+        entry.pendingTeardown = setTimeout(() => {
+            const e = this.channels.get(key);
+            if (e === undefined) {
+                return;
+            }
+            if (e.listeners.size > 0) {
+                e.pendingTeardown = undefined;
+                return;
+            }
+            e.teardown?.();
+            this.channels.delete(key);
+        }, WS_CHANNEL_TEARDOWN_LINGER_MS);
+    }
+}
+//# sourceMappingURL=WsProviderBase.js.map

package/dist/esm/websocket/WsProviderBase.js.map

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

package/dist/esm/websocket/cachePromise.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Single-flight a promise through a caller-owned cache slot, evicting the
+ * cached promise if it rejects so the next call retries cleanly.
+ *
+ * Concurrent callers share the one in-flight promise; the rejection still
+ * propagates to every awaiter that triggered it. Only a settled rejection is
+ * evicted — a resolved promise stays cached.
+ *
+ * @param read - Returns the currently cached promise, or `undefined` if none.
+ * @param write - Stores (or with `undefined`, clears) the cached promise.
+ * @param factory - Creates the promise when the slot is empty.
+ */
+export declare function cachePromise<T>(read: () => Promise<T> | undefined, write: (promise: Promise<T> | undefined) => void, factory: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=cachePromise.d.ts.map

package/dist/esm/websocket/cachePromise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cachePromise.d.ts","sourceRoot":"","sources":["../../../src/websocket/cachePromise.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,EAClC,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,KAAK,IAAI,EAChD,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACxB,OAAO,CAAC,CAAC,CAAC,CAaZ"}

package/dist/esm/websocket/cachePromise.js

@@ -0,0 +1,27 @@
+/**
+ * Single-flight a promise through a caller-owned cache slot, evicting the
+ * cached promise if it rejects so the next call retries cleanly.
+ *
+ * Concurrent callers share the one in-flight promise; the rejection still
+ * propagates to every awaiter that triggered it. Only a settled rejection is
+ * evicted — a resolved promise stays cached.
+ *
+ * @param read - Returns the currently cached promise, or `undefined` if none.
+ * @param write - Stores (or with `undefined`, clears) the cached promise.
+ * @param factory - Creates the promise when the slot is empty.
+ */
+export function cachePromise(read, write, factory) {
+    const cached = read();
+    if (cached) {
+        return cached;
+    }
+    const promise = factory();
+    promise.catch(() => {
+        if (read() === promise) {
+            write(undefined);
+        }
+    });
+    write(promise);
+    return promise;
+}
+//# sourceMappingURL=cachePromise.js.map

package/dist/esm/websocket/cachePromise.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cachePromise.js","sourceRoot":"","sources":["../../../src/websocket/cachePromise.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,YAAY,CAC1B,IAAkC,EAClC,KAAgD,EAChD,OAAyB;IAEzB,MAAM,MAAM,GAAG,IAAI,EAAE,CAAA;IACrB,IAAI,MAAM,EAAE,CAAC;QACX,OAAO,MAAM,CAAA;IACf,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,EAAE,CAAA;IACzB,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE;QACjB,IAAI,IAAI,EAAE,KAAK,OAAO,EAAE,CAAC;YACvB,KAAK,CAAC,SAAS,CAAC,CAAA;QAClB,CAAC;IACH,CAAC,CAAC,CAAA;IACF,KAAK,CAAC,OAAO,CAAC,CAAA;IACd,OAAO,OAAO,CAAA;AAChB,CAAC"}

package/dist/esm/websocket/types.d.ts

@@ -0,0 +1,60 @@
+import type { Subscription, SubscriptionEvent } from '@lifi/perps-types';
+import type { ProviderGetQuoteParams, QuoteListener } from '../types/provider.js';
+/**
+ * The concrete {@link SubscriptionEvent} variant a given subscription `S`
+ * emits, narrowed by its `channel`.
+ *
+ * @public
+ */
+export type EventForSubscription<S extends Subscription> = Extract<SubscriptionEvent, {
+    channel: S['channel'];
+}>;
+/**
+ * Listener invoked with each realtime {@link SubscriptionEvent}.
+ *
+ * @public
+ */
+export type SubscriptionListener = (event: SubscriptionEvent) => void;
+/**
+ * Health of a provider's underlying WS connection.
+ *
+ * - `connected` — socket open, live data flowing.
+ * - `reconnecting` — socket dropped; auto-reconnect with backoff in progress.
+ *   Data may be stale until it returns to `connected`.
+ * - `disconnected` — reconnection abandoned after the retry cap. The
+ *   connection is permanently dead and will not recover on its own; the
+ *   subscription's data is stale. Terminal.
+ *
+ * @public
+ */
+export type WsConnectionStatus = 'connected' | 'reconnecting' | 'disconnected';
+/**
+ * Listener invoked when the underlying WS connection's health changes.
+ *
+ * @public
+ */
+export type WsStatusListener = (status: WsConnectionStatus) => void;
+/**
+ * Per-provider realtime transport contract used by {@link PerpsWsClient}.
+ * Implemented by the provider packages' WS plugins.
+ *
+ * @public
+ */
+export interface WsProvider {
+    subscribe(sub: Subscription, listener: SubscriptionListener, onStatus?: WsStatusListener): Promise<() => void>;
+    /**
+     * Recover a terminally exhausted connection. Safe no-op unless status is
+     * `disconnected`.
+     */
+    reconnect(): void;
+    /**
+     * Stream live fill {@link Quote}s for `params.size` USD notional of
+     * `params.symbol` on this venue, layered on the orderbook channel: the
+     * provider resolves the symbol against its own markets and re-runs the
+     * one-shot quote transform on each (throttled) book update, applying its
+     * public base fee tier. Returns an idempotent unsubscribe.
+     */
+    subscribeQuote(params: ProviderGetQuoteParams, onQuote: QuoteListener): Promise<() => void>;
+    close(): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/websocket/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/websocket/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AACxE,OAAO,KAAK,EACV,sBAAsB,EACtB,aAAa,EACd,MAAM,sBAAsB,CAAA;AAE7B;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,SAAS,YAAY,IAAI,OAAO,CAChE,iBAAiB,EACjB;IAAE,OAAO,EAAE,CAAC,CAAC,SAAS,CAAC,CAAA;CAAE,CAC1B,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAA;AAErE;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,cAAc,GAAG,cAAc,CAAA;AAE9E;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,kBAAkB,KAAK,IAAI,CAAA;AAEnE;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,SAAS,CACP,GAAG,EAAE,YAAY,EACjB,QAAQ,EAAE,oBAAoB,EAC9B,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,OAAO,CAAC,MAAM,IAAI,CAAC,CAAA;IACtB;;;OAGG;IACH,SAAS,IAAI,IAAI,CAAA;IACjB;;;;;;OAMG;IACH,cAAc,CACZ,MAAM,EAAE,sBAAsB,EAC9B,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,IAAI,CAAC,CAAA;IACtB,KAAK,IAAI,IAAI,CAAA;CACd"}

package/dist/{cjs/realtime → esm/websocket}/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/realtime/types.ts"],"names":[],"mappings":""}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/websocket/types.ts"],"names":[],"mappings":""}

package/dist/esm/websocket/wsLog.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Structured logger for WS message-handling and subscription failures, shared
+ * by the provider packages so a malformed frame, a throwing mapper, or a failed
+ * resubscribe never vanishes silently.
+ *
+ * @internal
+ */
+export declare const wsLog: {
+    /**
+     * A single frame that could not be parsed as JSON. Expected to recur on a
+     * noisy stream, so logged at `warn` with a truncated payload — never fatal.
+     */
+    readonly parseFailure: (provider: string, raw: string) => void;
+    /**
+     * A frame parsed but its handler threw (mapper bug, `MarketNotFound`, …).
+     * This is unexpected and must surface; the frame is skipped so one bad
+     * frame does not stall the stream or starve other channels.
+     */
+    readonly handlerFailure: (provider: string, error: unknown) => void;
+    /**
+     * An `error`-channel frame the server pushed (e.g. a rejected or duplicate
+     * subscription). The frame parsed fine — this is the venue reporting a
+     * problem, not a malformed frame — so surface it at `error` with the
+     * server's own text rather than mislabelling it a parse failure.
+     */
+    readonly serverError: (provider: string, message: string) => void;
+    /**
+     * A channel's (re)subscribe threw while (re)opening the socket — e.g. an
+     * auth-token fetch rejected after a reconnect. Surfaced at `error`; the
+     * channel is skipped so one failure does not abort the others.
+     */
+    readonly subscribeFailure: (provider: string, channel: string, error: unknown) => void;
+    /**
+     * A frame item referenced a market id missing from the registry (e.g.
+     * listed after the snapshot). The item is skipped — never the whole frame —
+     * so logged at `warn`.
+     */
+    readonly unknownMarket: (provider: string, marketId: string) => void;
+    /**
+     * A background market-registry refetch rejected. Unknown-market items keep
+     * being skipped until the next cooldown-gated retry, so logged at `warn`.
+     */
+    readonly marketRefreshFailure: (provider: string, error: unknown) => void;
+    /**
+     * A consumer listener callback threw during fan-out. Logged and skipped so
+     * one bad listener cannot starve sibling listeners or break socket flow.
+     */
+    readonly listenerFailure: (provider: string, listenerType: string, error: unknown) => void;
+};
+//# sourceMappingURL=wsLog.d.ts.map

package/dist/esm/websocket/wsLog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wsLog.d.ts","sourceRoot":"","sources":["../../../src/websocket/wsLog.ts"],"names":[],"mappings":"AAOA;;;;;;GAMG;AACH,eAAO,MAAM,KAAK;IAChB;;;OAGG;sCACoB,MAAM,OAAO,MAAM,KAAG,IAAI;IAGjD;;;;OAIG;wCACsB,MAAM,SAAS,OAAO,KAAG,IAAI;IAGtD;;;;;OAKG;qCACmB,MAAM,WAAW,MAAM,KAAG,IAAI;IAGpD;;;;OAIG;0CACwB,MAAM,WAAW,MAAM,SAAS,OAAO,KAAG,IAAI;IAMzE;;;;OAIG;uCACqB,MAAM,YAAY,MAAM,KAAG,IAAI;IAKvD;;;OAGG;8CAC4B,MAAM,SAAS,OAAO,KAAG,IAAI;IAG5D;;;OAGG;yCAES,MAAM,gBACF,MAAM,SACb,OAAO,KACb,IAAI;CAMC,CAAA"}

package/dist/esm/websocket/wsLog.js

@@ -0,0 +1,68 @@
+const MAX_PAYLOAD_CHARS = 512;
+const truncate = (raw) => raw.length > MAX_PAYLOAD_CHARS
+    ? `${raw.slice(0, MAX_PAYLOAD_CHARS)}…(${raw.length} chars)`
+    : raw;
+/**
+ * Structured logger for WS message-handling and subscription failures, shared
+ * by the provider packages so a malformed frame, a throwing mapper, or a failed
+ * resubscribe never vanishes silently.
+ *
+ * @internal
+ */
+export const wsLog = {
+    /**
+     * A single frame that could not be parsed as JSON. Expected to recur on a
+     * noisy stream, so logged at `warn` with a truncated payload — never fatal.
+     */
+    parseFailure(provider, raw) {
+        console.warn(`[${provider}:ws] dropping unparseable frame`, truncate(raw));
+    },
+    /**
+     * A frame parsed but its handler threw (mapper bug, `MarketNotFound`, …).
+     * This is unexpected and must surface; the frame is skipped so one bad
+     * frame does not stall the stream or starve other channels.
+     */
+    handlerFailure(provider, error) {
+        console.error(`[${provider}:ws] message handler threw`, error);
+    },
+    /**
+     * An `error`-channel frame the server pushed (e.g. a rejected or duplicate
+     * subscription). The frame parsed fine — this is the venue reporting a
+     * problem, not a malformed frame — so surface it at `error` with the
+     * server's own text rather than mislabelling it a parse failure.
+     */
+    serverError(provider, message) {
+        console.error(`[${provider}:ws] server error`, message);
+    },
+    /**
+     * A channel's (re)subscribe threw while (re)opening the socket — e.g. an
+     * auth-token fetch rejected after a reconnect. Surfaced at `error`; the
+     * channel is skipped so one failure does not abort the others.
+     */
+    subscribeFailure(provider, channel, error) {
+        console.error(`[${provider}:ws] resubscribe failed for channel '${channel}'; it will not receive updates until the next reconnect.`, error);
+    },
+    /**
+     * A frame item referenced a market id missing from the registry (e.g.
+     * listed after the snapshot). The item is skipped — never the whole frame —
+     * so logged at `warn`.
+     */
+    unknownMarket(provider, marketId) {
+        console.warn(`[${provider}:ws] skipping item for unknown market '${marketId}'`);
+    },
+    /**
+     * A background market-registry refetch rejected. Unknown-market items keep
+     * being skipped until the next cooldown-gated retry, so logged at `warn`.
+     */
+    marketRefreshFailure(provider, error) {
+        console.warn(`[${provider}:ws] market registry refresh failed`, error);
+    },
+    /**
+     * A consumer listener callback threw during fan-out. Logged and skipped so
+     * one bad listener cannot starve sibling listeners or break socket flow.
+     */
+    listenerFailure(provider, listenerType, error) {
+        console.error(`[${provider}:ws] listener threw during '${listenerType}' fan-out`, error);
+    },
+};
+//# sourceMappingURL=wsLog.js.map

package/dist/esm/websocket/wsLog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wsLog.js","sourceRoot":"","sources":["../../../src/websocket/wsLog.ts"],"names":[],"mappings":"AAAA,MAAM,iBAAiB,GAAG,GAAG,CAAA;AAE7B,MAAM,QAAQ,GAAG,CAAC,GAAW,EAAU,EAAE,CACvC,GAAG,CAAC,MAAM,GAAG,iBAAiB;IAC5B,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,iBAAiB,CAAC,KAAK,GAAG,CAAC,MAAM,SAAS;IAC5D,CAAC,CAAC,GAAG,CAAA;AAET;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB;;;OAGG;IACH,YAAY,CAAC,QAAgB,EAAE,GAAW;QACxC,OAAO,CAAC,IAAI,CAAC,IAAI,QAAQ,iCAAiC,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAA;IAC5E,CAAC;IACD;;;;OAIG;IACH,cAAc,CAAC,QAAgB,EAAE,KAAc;QAC7C,OAAO,CAAC,KAAK,CAAC,IAAI,QAAQ,4BAA4B,EAAE,KAAK,CAAC,CAAA;IAChE,CAAC;IACD;;;;;OAKG;IACH,WAAW,CAAC,QAAgB,EAAE,OAAe;QAC3C,OAAO,CAAC,KAAK,CAAC,IAAI,QAAQ,mBAAmB,EAAE,OAAO,CAAC,CAAA;IACzD,CAAC;IACD;;;;OAIG;IACH,gBAAgB,CAAC,QAAgB,EAAE,OAAe,EAAE,KAAc;QAChE,OAAO,CAAC,KAAK,CACX,IAAI,QAAQ,wCAAwC,OAAO,0DAA0D,EACrH,KAAK,CACN,CAAA;IACH,CAAC;IACD;;;;OAIG;IACH,aAAa,CAAC,QAAgB,EAAE,QAAgB;QAC9C,OAAO,CAAC,IAAI,CACV,IAAI,QAAQ,0CAA0C,QAAQ,GAAG,CAClE,CAAA;IACH,CAAC;IACD;;;OAGG;IACH,oBAAoB,CAAC,QAAgB,EAAE,KAAc;QACnD,OAAO,CAAC,IAAI,CAAC,IAAI,QAAQ,qCAAqC,EAAE,KAAK,CAAC,CAAA;IACxE,CAAC;IACD;;;OAGG;IACH,eAAe,CACb,QAAgB,EAChB,YAAoB,EACpB,KAAc;QAEd,OAAO,CAAC,KAAK,CACX,IAAI,QAAQ,+BAA+B,YAAY,WAAW,EAClE,KAAK,CACN,CAAA;IACH,CAAC;CACO,CAAA"}