@spacesops/wdk-react-native-core 1.0.0-beta.40

package/dist/utils/schemas.js

@@ -0,0 +1,152 @@
+/**
+ * Zod Schemas for Runtime Validation
+ *
+ * Provides Zod schemas for all WDK types to replace manual if/else type guards.
+ * These schemas provide better error messages and are easier to maintain.
+ */
+import { z } from 'zod';
+/**
+ * Ethereum address schema (0x followed by 40 hex characters)
+ */
+export const ethereumAddressSchema = z.string().regex(/^0x[a-fA-F0-9]{40}$/, {
+    message: 'Must be a valid Ethereum address (0x followed by 40 hex characters)',
+});
+/**
+ * Spark address schema (Bech32 format: spark1/sparkt1/sparkrt1 followed by base32 characters)
+ */
+export const sparkAddressSchema = z.string().regex(/^spark(1|t1|rt1|test1)[a-z0-9]+$/, {
+    message: 'Must be a valid Spark address (spark1/sparkt1/sparkrt1 followed by base32 characters)',
+}).min(14).max(90);
+/**
+ * Address schema (Ethereum or Spark)
+ */
+export const addressSchema = z.union([ethereumAddressSchema, sparkAddressSchema]);
+/**
+ * Network configuration schema
+ */
+export const networkConfigSchema = z.object({
+    chainId: z.number().int().positive(),
+    blockchain: z.string().min(1),
+    provider: z.string().min(1).optional(),
+    bundlerUrl: z.string().min(1).optional(),
+    paymasterUrl: z.string().min(1).optional(),
+    paymasterAddress: ethereumAddressSchema.optional(),
+    entryPointAddress: ethereumAddressSchema.optional(),
+    transferMaxFee: z.number().nonnegative().optional(),
+});
+/**
+ * Network configurations schema
+ */
+export const networkConfigsSchema = z.record(z.string().regex(/^[a-zA-Z0-9_-]+$/, {
+    message: 'Network name must contain only alphanumeric characters, hyphens, and underscores',
+}), networkConfigSchema).refine((configs) => Object.keys(configs).length > 0, {
+    message: 'NetworkConfigs must contain at least one network',
+});
+/**
+ * Token configuration schema
+ */
+export const tokenConfigSchema = z.object({
+    symbol: z.string().min(1),
+    name: z.string().min(1),
+    decimals: z.number().int().min(0).max(18),
+    address: z.union([ethereumAddressSchema, z.null()]),
+});
+/**
+ * Network tokens schema
+ */
+export const networkTokensSchema = z.object({
+    native: tokenConfigSchema,
+    tokens: z.array(tokenConfigSchema),
+});
+/**
+ * Token configurations schema
+ */
+export const tokenConfigsSchema = z.record(z.string().min(1), networkTokensSchema).refine((configs) => Object.keys(configs).length > 0, {
+    message: 'TokenConfigs must contain at least one network',
+});
+/**
+ * Account index schema
+ */
+export const accountIndexSchema = z.number().int().nonnegative();
+/**
+ * Network name schema
+ */
+export const networkNameSchema = z.string().regex(/^[a-zA-Z0-9_-]+$/, {
+    message: 'Network name must contain only alphanumeric characters, hyphens, and underscores',
+}).min(1);
+/**
+ * Balance string schema (valid number string)
+ */
+export const balanceStringSchema = z.string().regex(/^-?\d+(\.\d+)?$/, {
+    message: 'Balance must be a valid number string',
+});
+/**
+ * Wallet addresses schema
+ * Maps network -> accountIndex -> address
+ */
+export const walletAddressesSchema = z.record(networkNameSchema, z.record(z.string().transform((val) => {
+    const num = parseInt(val, 10);
+    if (isNaN(num) || num < 0) {
+        throw new Error('Account index must be a non-negative integer');
+    }
+    return num;
+}), addressSchema));
+/**
+ * Wallet balances schema
+ * Maps network -> accountIndex -> tokenAddress -> balance
+ */
+export const walletBalancesSchema = z.record(networkNameSchema, z.record(z.string().transform((val) => {
+    const num = parseInt(val, 10);
+    if (isNaN(num) || num < 0) {
+        throw new Error('Account index must be a non-negative integer');
+    }
+    return num;
+}), z.record(z.string(), balanceStringSchema)));
+/**
+ * Balance loading states schema
+ * Maps "network-accountIndex-tokenAddress" -> boolean
+ */
+export const balanceLoadingStatesSchema = z.record(z.string(), z.boolean());
+/**
+ * Balance fetch result schema
+ */
+export const balanceFetchResultSchema = z.object({
+    success: z.boolean(),
+    network: networkNameSchema,
+    accountIndex: accountIndexSchema,
+    tokenAddress: z.union([ethereumAddressSchema, z.null()]),
+    balance: z.union([balanceStringSchema, z.null()]),
+    error: z.string().optional(),
+});
+/**
+ * Wallet schema
+ */
+export const walletSchema = z.object({
+    accountIndex: accountIndexSchema,
+    identifier: z.string().min(1),
+    name: z.string().min(1),
+    createdAt: z.number().int().nonnegative(),
+    updatedAt: z.number().int().nonnegative(),
+});
+/**
+ * Worklet response schemas for runtime validation
+ */
+export const workletResponseSchema = z.object({
+    result: z.string(),
+    error: z.string().optional(),
+});
+/**
+ * Balance response schema (numeric string)
+ */
+export const balanceResponseSchema = z.string().regex(/^\d+$/, {
+    message: 'Balance must be a numeric string',
+});
+/**
+ * Account method response schema (union of possible return types)
+ */
+export const accountMethodResponseSchema = z.union([
+    balanceResponseSchema,
+    z.string(), // For addresses
+    z.object({}).passthrough(), // For other responses (objects)
+]);
+//# sourceMappingURL=schemas.js.map

package/dist/utils/schemas.js.map

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

package/dist/utils/storeHelpers.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Store helper utilities
+ *
+ * Provides common patterns for accessing and validating store state
+ * to reduce code duplication across services.
+ */
+import type { HRPC } from '@spacesops/pear-wrk-wdk';
+import { asExtendedHRPC } from '../types/hrpc';
+import type { WalletState } from '../store/walletStore';
+/**
+ * Require that worklet is initialized and return HRPC instance
+ *
+ * @throws Error if worklet is not initialized
+ * @returns HRPC instance
+ *
+ * @example
+ * ```typescript
+ * const hrpc = requireInitialized()
+ * await hrpc.callMethod(...)
+ * ```
+ */
+export declare function requireInitialized(): HRPC;
+/**
+ * Require that worklet is initialized and return extended HRPC instance
+ *
+ * @throws Error if worklet is not initialized
+ * @returns Extended HRPC instance
+ *
+ * @example
+ * ```typescript
+ * const hrpc = requireExtendedHRPC()
+ * await hrpc.initializeWDK(...)
+ * ```
+ */
+export declare function requireExtendedHRPC(): ReturnType<typeof asExtendedHRPC>;
+/**
+ * Check if worklet is initialized
+ *
+ * @returns true if worklet is initialized, false otherwise
+ */
+export declare function isInitialized(): boolean;
+/**
+ * Update balance in wallet state (helper for nested state updates)
+ *
+ * @param prev - Previous wallet state
+ * @param walletId - Wallet identifier
+ * @param network - Network name
+ * @param accountIndex - Account index
+ * @param tokenKey - Token key (address or 'native')
+ * @param balance - Balance value
+ * @returns Partial state update
+ */
+export declare function updateBalanceInState(prev: WalletState, walletId: string, network: string, accountIndex: number, tokenKey: string, balance: string): Partial<WalletState>;
+/**
+ * Update address in wallet state (helper for nested state updates)
+ *
+ * @param prev - Previous wallet state
+ * @param walletId - Wallet identifier
+ * @param network - Network name
+ * @param accountIndex - Account index
+ * @param address - Address value
+ * @returns Partial state update
+ */
+export declare function updateAddressInState(prev: WalletState, walletId: string, network: string, accountIndex: number, address: string): Partial<WalletState>;
+/**
+ * Resolve wallet identifier from parameter or store
+ *
+ * This helper function standardizes the pattern for resolving walletId across the codebase.
+ * It checks the provided walletId parameter first, then falls back to activeWalletId from store,
+ * and finally to '__temporary__' if no wallet is active.
+ *
+ * @param walletId - Optional wallet identifier parameter
+ * @returns Resolved wallet identifier (never null)
+ *
+ * @example
+ * ```typescript
+ * const targetWalletId = resolveWalletId(walletId)
+ * // Use targetWalletId for operations
+ * ```
+ */
+export declare function resolveWalletId(walletId?: string): string;
+/**
+ * Safely get nested property from an object
+ *
+ * @param obj - Object to access
+ * @param path - Array of keys representing the path
+ * @param defaultValue - Default value if path doesn't exist
+ * @returns Value at path or default value
+ *
+ * @example
+ * ```typescript
+ * const balance = getNestedState(state.balances, [walletId, network, accountIndex, tokenKey], null)
+ * ```
+ */
+export declare function getNestedState<T>(obj: Record<string, unknown>, path: (string | number)[], defaultValue: T): T;
+/**
+ * Update nested state structure (generic helper for deep state updates)
+ *
+ * Creates a new nested object structure with the updated value at the specified path.
+ * All intermediate objects are shallow copied to maintain immutability.
+ *
+ * @param prev - Previous state object
+ * @param path - Array of keys representing the path to update
+ * @param value - Value to set at the path
+ * @returns New state object with updated value
+ *
+ * @example
+ * ```typescript
+ * const newState = updateNestedState(prev, ['balances', walletId, network, accountIndex, tokenKey], balance)
+ * ```
+ */
+export declare function updateNestedState<T extends Record<string, unknown>>(prev: T, path: (string | number)[], value: unknown): Partial<T>;

package/dist/utils/storeHelpers.js

@@ -0,0 +1,198 @@
+/**
+ * Store helper utilities
+ *
+ * Provides common patterns for accessing and validating store state
+ * to reduce code duplication across services.
+ */
+import { getWorkletStore } from '../store/workletStore';
+import { getWalletStore } from '../store/walletStore';
+import { asExtendedHRPC } from '../types/hrpc';
+/**
+ * Require that worklet is initialized and return HRPC instance
+ *
+ * @throws Error if worklet is not initialized
+ * @returns HRPC instance
+ *
+ * @example
+ * ```typescript
+ * const hrpc = requireInitialized()
+ * await hrpc.callMethod(...)
+ * ```
+ */
+export function requireInitialized() {
+    const state = getWorkletStore().getState();
+    if (!state.isInitialized || !state.hrpc) {
+        throw new Error('WDK not initialized');
+    }
+    return state.hrpc;
+}
+/**
+ * Require that worklet is initialized and return extended HRPC instance
+ *
+ * @throws Error if worklet is not initialized
+ * @returns Extended HRPC instance
+ *
+ * @example
+ * ```typescript
+ * const hrpc = requireExtendedHRPC()
+ * await hrpc.initializeWDK(...)
+ * ```
+ */
+export function requireExtendedHRPC() {
+    const hrpc = requireInitialized();
+    return asExtendedHRPC(hrpc);
+}
+/**
+ * Check if worklet is initialized
+ *
+ * @returns true if worklet is initialized, false otherwise
+ */
+export function isInitialized() {
+    const state = getWorkletStore().getState();
+    return state.isInitialized && state.hrpc !== null;
+}
+/**
+ * Update balance in wallet state (helper for nested state updates)
+ *
+ * @param prev - Previous wallet state
+ * @param walletId - Wallet identifier
+ * @param network - Network name
+ * @param accountIndex - Account index
+ * @param tokenKey - Token key (address or 'native')
+ * @param balance - Balance value
+ * @returns Partial state update
+ */
+export function updateBalanceInState(prev, walletId, network, accountIndex, tokenKey, balance) {
+    const walletBalances = prev.balances[walletId] || {};
+    const networkBalances = walletBalances[network] || {};
+    const accountBalances = networkBalances[accountIndex] || {};
+    return {
+        balances: {
+            ...prev.balances,
+            [walletId]: {
+                ...walletBalances,
+                [network]: {
+                    ...networkBalances,
+                    [accountIndex]: {
+                        ...accountBalances,
+                        [tokenKey]: balance,
+                    },
+                },
+            },
+        },
+    };
+}
+/**
+ * Update address in wallet state (helper for nested state updates)
+ *
+ * @param prev - Previous wallet state
+ * @param walletId - Wallet identifier
+ * @param network - Network name
+ * @param accountIndex - Account index
+ * @param address - Address value
+ * @returns Partial state update
+ */
+export function updateAddressInState(prev, walletId, network, accountIndex, address) {
+    const walletAddresses = prev.addresses[walletId] || {};
+    const networkAddresses = walletAddresses[network] || {};
+    return {
+        addresses: {
+            ...prev.addresses,
+            [walletId]: {
+                ...walletAddresses,
+                [network]: {
+                    ...networkAddresses,
+                    [accountIndex]: address,
+                },
+            },
+        },
+    };
+}
+/**
+ * Resolve wallet identifier from parameter or store
+ *
+ * This helper function standardizes the pattern for resolving walletId across the codebase.
+ * It checks the provided walletId parameter first, then falls back to activeWalletId from store,
+ * and finally to '__temporary__' if no wallet is active.
+ *
+ * @param walletId - Optional wallet identifier parameter
+ * @returns Resolved wallet identifier (never null)
+ *
+ * @example
+ * ```typescript
+ * const targetWalletId = resolveWalletId(walletId)
+ * // Use targetWalletId for operations
+ * ```
+ */
+export function resolveWalletId(walletId) {
+    if (walletId) {
+        return walletId;
+    }
+    const walletStore = getWalletStore();
+    const activeWalletId = walletStore.getState().activeWalletId;
+    return activeWalletId || '__temporary__';
+}
+/**
+ * Safely get nested property from an object
+ *
+ * @param obj - Object to access
+ * @param path - Array of keys representing the path
+ * @param defaultValue - Default value if path doesn't exist
+ * @returns Value at path or default value
+ *
+ * @example
+ * ```typescript
+ * const balance = getNestedState(state.balances, [walletId, network, accountIndex, tokenKey], null)
+ * ```
+ */
+export function getNestedState(obj, path, defaultValue) {
+    let current = obj;
+    for (const key of path) {
+        if (current == null || typeof current !== 'object') {
+            return defaultValue;
+        }
+        if (!(key in current)) {
+            return defaultValue;
+        }
+        current = current[key];
+    }
+    return current ?? defaultValue;
+}
+/**
+ * Update nested state structure (generic helper for deep state updates)
+ *
+ * Creates a new nested object structure with the updated value at the specified path.
+ * All intermediate objects are shallow copied to maintain immutability.
+ *
+ * @param prev - Previous state object
+ * @param path - Array of keys representing the path to update
+ * @param value - Value to set at the path
+ * @returns New state object with updated value
+ *
+ * @example
+ * ```typescript
+ * const newState = updateNestedState(prev, ['balances', walletId, network, accountIndex, tokenKey], balance)
+ * ```
+ */
+export function updateNestedState(prev, path, value) {
+    if (path.length === 0) {
+        if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+            return { ...prev, ...value };
+        }
+        return prev;
+    }
+    const [firstKey, ...restPath] = path;
+    const keyString = String(firstKey);
+    const currentValue = prev[keyString];
+    const currentValueObj = (typeof currentValue === 'object' && currentValue !== null && !Array.isArray(currentValue))
+        ? currentValue
+        : {};
+    const updatedValue = restPath.length > 0
+        ? updateNestedState(currentValueObj, restPath, value)
+        : value;
+    return {
+        ...prev,
+        [keyString]: updatedValue,
+    };
+}
+//# sourceMappingURL=storeHelpers.js.map

package/dist/utils/storeHelpers.js.map

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

package/dist/utils/typeGuards.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Runtime Type Guards
+ *
+ * Provides runtime type checking for critical data paths to ensure type safety
+ * beyond TypeScript's compile-time checks.
+ *
+ * NOTE: These type guards now use Zod schemas internally for validation.
+ * They are kept for backward compatibility but may be deprecated in the future.
+ */
+import type { NetworkConfig, NetworkConfigs, TokenConfig, TokenConfigs, WalletAddresses, WalletBalances } from '../types';
+/**
+ * Type guard to check if a value is a valid NetworkConfig
+ * Uses Zod schema internally for validation
+ */
+export declare function isNetworkConfig(value: unknown): value is NetworkConfig;
+/**
+ * Type guard to check if a value is a valid NetworkConfigs
+ * Uses Zod schema internally for validation
+ */
+export declare function isNetworkConfigs(value: unknown): value is NetworkConfigs;
+/**
+ * Type guard to check if a value is a valid TokenConfig
+ * Uses Zod schema internally for validation
+ */
+export declare function isTokenConfig(value: unknown): value is TokenConfig;
+/**
+ * Type guard to check if a value is a valid TokenConfigs
+ * Uses Zod schema internally for validation
+ */
+export declare function isTokenConfigs(value: unknown): value is TokenConfigs;
+/**
+ * Type guard to check if a value is a valid WalletAddresses structure
+ * Uses Zod schema internally for validation
+ */
+export declare function isWalletAddresses(value: unknown): value is WalletAddresses;
+/**
+ * Type guard to check if a value is a valid WalletBalances structure
+ * Uses Zod schema internally for validation
+ */
+export declare function isWalletBalances(value: unknown): value is WalletBalances;
+/**
+ * Type guard to check if a value is a valid Ethereum address
+ * Uses Zod schema internally for validation
+ */
+export declare function isEthereumAddress(value: unknown): value is string;
+/**
+ * Type guard to check if a value is a valid Spark address (Bech32 format)
+ * Spark addresses start with "spark1" followed by Bech32-encoded characters
+ * Uses Zod schema internally for validation
+ */
+export declare function isSparkAddress(value: unknown): value is string;
+/**
+ * Type guard to check if a value is a valid address (Ethereum or Spark format)
+ */
+export declare function isValidAddress(value: unknown): value is string;
+/**
+ * Type guard to check if a value is a valid account index
+ * Uses Zod schema internally for validation
+ */
+export declare function isValidAccountIndex(value: unknown): value is number;
+/**
+ * Type guard to check if a value is a valid network name
+ * Uses Zod schema internally for validation
+ */
+export declare function isValidNetworkName(value: unknown): value is string;
+/**
+ * Type guard to check if a value is a valid balance string
+ * Uses Zod schema internally for validation
+ */
+export declare function isValidBalanceString(value: unknown): value is string;

package/dist/utils/typeGuards.js

@@ -0,0 +1,95 @@
+/**
+ * Runtime Type Guards
+ *
+ * Provides runtime type checking for critical data paths to ensure type safety
+ * beyond TypeScript's compile-time checks.
+ *
+ * NOTE: These type guards now use Zod schemas internally for validation.
+ * They are kept for backward compatibility but may be deprecated in the future.
+ */
+import { networkConfigSchema, networkConfigsSchema, tokenConfigSchema, tokenConfigsSchema, walletAddressesSchema, walletBalancesSchema, ethereumAddressSchema, sparkAddressSchema, accountIndexSchema, networkNameSchema, balanceStringSchema, } from './schemas';
+/**
+ * Type guard to check if a value is a valid NetworkConfig
+ * Uses Zod schema internally for validation
+ */
+export function isNetworkConfig(value) {
+    return networkConfigSchema.safeParse(value).success;
+}
+/**
+ * Type guard to check if a value is a valid NetworkConfigs
+ * Uses Zod schema internally for validation
+ */
+export function isNetworkConfigs(value) {
+    return networkConfigsSchema.safeParse(value).success;
+}
+/**
+ * Type guard to check if a value is a valid TokenConfig
+ * Uses Zod schema internally for validation
+ */
+export function isTokenConfig(value) {
+    return tokenConfigSchema.safeParse(value).success;
+}
+/**
+ * Type guard to check if a value is a valid TokenConfigs
+ * Uses Zod schema internally for validation
+ */
+export function isTokenConfigs(value) {
+    return tokenConfigsSchema.safeParse(value).success;
+}
+/**
+ * Type guard to check if a value is a valid WalletAddresses structure
+ * Uses Zod schema internally for validation
+ */
+export function isWalletAddresses(value) {
+    return walletAddressesSchema.safeParse(value).success;
+}
+/**
+ * Type guard to check if a value is a valid WalletBalances structure
+ * Uses Zod schema internally for validation
+ */
+export function isWalletBalances(value) {
+    return walletBalancesSchema.safeParse(value).success;
+}
+/**
+ * Type guard to check if a value is a valid Ethereum address
+ * Uses Zod schema internally for validation
+ */
+export function isEthereumAddress(value) {
+    return ethereumAddressSchema.safeParse(value).success;
+}
+/**
+ * Type guard to check if a value is a valid Spark address (Bech32 format)
+ * Spark addresses start with "spark1" followed by Bech32-encoded characters
+ * Uses Zod schema internally for validation
+ */
+export function isSparkAddress(value) {
+    return sparkAddressSchema.safeParse(value).success;
+}
+/**
+ * Type guard to check if a value is a valid address (Ethereum or Spark format)
+ */
+export function isValidAddress(value) {
+    return isEthereumAddress(value) || isSparkAddress(value);
+}
+/**
+ * Type guard to check if a value is a valid account index
+ * Uses Zod schema internally for validation
+ */
+export function isValidAccountIndex(value) {
+    return accountIndexSchema.safeParse(value).success;
+}
+/**
+ * Type guard to check if a value is a valid network name
+ * Uses Zod schema internally for validation
+ */
+export function isValidNetworkName(value) {
+    return networkNameSchema.safeParse(value).success;
+}
+/**
+ * Type guard to check if a value is a valid balance string
+ * Uses Zod schema internally for validation
+ */
+export function isValidBalanceString(value) {
+    return balanceStringSchema.safeParse(value).success;
+}
+//# sourceMappingURL=typeGuards.js.map

package/dist/utils/typeGuards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"typeGuards.js","sourceRoot":"","sources":["../../src/utils/typeGuards.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,WAAW,CAAA;AAUlB;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,mBAAmB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,OAAO,CAAA;AACrD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,oBAAoB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,OAAO,CAAA;AACtD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,iBAAiB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,OAAO,CAAA;AACnD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,kBAAkB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,OAAO,CAAA;AACpD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,OAAO,qBAAqB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,OAAO,CAAA;AACvD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,oBAAoB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,OAAO,CAAA;AACtD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,OAAO,qBAAqB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,OAAO,CAAA;AACvD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,kBAAkB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,OAAO,CAAA;AACpD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,iBAAiB,CAAC,KAAK,CAAC,IAAI,cAAc,CAAC,KAAK,CAAC,CAAA;AAC1D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAChD,OAAO,kBAAkB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,OAAO,CAAA;AACpD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,OAAO,iBAAiB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,OAAO,CAAA;AACnD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAc;IACjD,OAAO,mBAAmB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,OAAO,CAAA;AACrD,CAAC"}