tetherdb 0.1.0

package/dist/client/auth.d.cts

@@ -0,0 +1,155 @@
+import { EventRegistry } from './shared/event.cjs';
+import type { Storage } from './storage.cjs';
+/**
+ * Data reconciliation and persistence strategy for auth and session operations.
+ */
+export declare enum DataMode {
+    /** Overwrite local data with remote server snapshot. */
+    Remote = 0,
+    /** Preserve local data and upload/reconcile with remote. */
+    Local = 1,
+    /** Merge local and remote changes using Last-Write-Wins. */
+    Merge = 2,
+    /** Wipe local data tables and reset sync sequence. */
+    Clear = 3
+}
+/**
+ * Authentication lifecycle states of the client.
+ */
+export declare enum AuthStatus {
+    /** No active session. */
+    SignedOut = 0,
+    /** Authenticating or restoring remembered session. */
+    SigningIn = 1,
+    /** Authenticated and ready for synchronized operations. */
+    SignedIn = 2,
+    /** Authentication failed (e.g. invalid credentials or expired session). */
+    Error = 3
+}
+/**
+ * Options for registering a new user account.
+ */
+export interface RegisterOptions {
+    /** Unique username (required). */
+    username: string;
+    /** Account password (required). */
+    password: string;
+    /** Persist session in IndexedDB for automatic login across sessions (default: false). */
+    remember?: boolean;
+    /** Local data handling mode (defaults to DataMode.Local when signed out, or DataMode.Clear when already signed in). */
+    dataMode?: DataMode;
+}
+/**
+ * Options for logging into an existing user account.
+ */
+export interface LoginOptions {
+    /** Unique username (optional if already remembered). */
+    username?: string;
+    /** Account password (optional if already remembered). */
+    password?: string;
+    /** Persist session for automatic login across sessions (default: false). */
+    remember?: boolean;
+    /** Data reconciliation mode (default: DataMode.Remote). */
+    dataMode?: DataMode;
+}
+/**
+ * Options for logging out of the current user session.
+ */
+export interface LogoutOptions {
+    /** Data preservation mode (default: DataMode.Clear to wipe local data). */
+    dataMode?: DataMode;
+}
+/**
+ * Result returned upon successful user registration or login.
+ */
+export interface AuthResult {
+    /** Unique user identifier (UUID). */
+    userId: string;
+    /** User's unique username. */
+    username: string;
+    /** Signed session authentication token for sync and API calls. */
+    token: string;
+}
+/**
+ * Internal persisted session representation in IndexedDB metadata.
+ */
+export interface StoredAuthSession {
+    token: string;
+    userId: string;
+    username: string;
+}
+/**
+ * Internal dependencies provided to Auth by TetherClient.
+ */
+export interface AuthDependencies {
+    baseUrl: string;
+    storage: Storage;
+    fetchFn?: typeof fetch;
+}
+/**
+ * Authentication coordinator managing user sessions, HTTP requests,
+ * metadata persistence, and reconciliation state transitions.
+ */
+export declare class Auth {
+    /** Base URL for remote authentication REST API endpoints. */
+    readonly baseUrl: string;
+    /** Reactive event registry triggered whenever the authentication status changes. */
+    readonly onStatusChange: EventRegistry<AuthStatus>;
+    private storage;
+    private fetchFn;
+    private currentAuthStatus;
+    private currentUsername?;
+    private currentUserId?;
+    private currentToken?;
+    private autoRestorePromise;
+    constructor(dependencies: AuthDependencies);
+    /**
+     * Current authentication lifecycle status.
+     */
+    get status(): AuthStatus;
+    /**
+     * The authenticated user's username, or `undefined` if signed out.
+     */
+    get username(): string | undefined;
+    /**
+     * The authenticated user's ID, or `undefined` if signed out.
+     */
+    get userId(): string | undefined;
+    /**
+     * The active authentication session token, or `undefined` if signed out.
+     */
+    get token(): string | undefined;
+    /**
+     * Restores any remembered session from IndexedDB metadata on startup.
+     */
+    restoreSession(): Promise<void>;
+    /**
+     * Registers a new user account, applies local data mode, and notifies listeners.
+     */
+    register(options: RegisterOptions): Promise<boolean>;
+    /**
+     * Logs into an account (or reconnects with remembered credentials), applies data mode, and notifies listeners.
+     */
+    login(options?: LoginOptions): Promise<boolean>;
+    /**
+     * Logs out of the current session, removes stored credentials, and applies data mode.
+     */
+    logout(options?: LogoutOptions): Promise<boolean>;
+    /**
+     * Updates the in-memory and persisted session token when refreshed by the server.
+     *
+     * @param token - The new refreshed session token.
+     */
+    handleTokenRefresh(token: string): Promise<void>;
+    /**
+     * Cleans up local session and transitions to SignedOut when authentication fails or expires.
+     *
+     * @param _message - Optional error message from the server.
+     */
+    handleAuthError(_message?: string): Promise<void>;
+    private sendAuthRequest;
+    private applyDataMode;
+    private updateStoredAuth;
+    private setStatus;
+}
+//# sourceMappingURL=auth.d.ts.map

package/dist/client/auth.d.ts

@@ -0,0 +1,155 @@
+import { EventRegistry } from './shared/event.js';
+import type { Storage } from './storage.js';
+/**
+ * Data reconciliation and persistence strategy for auth and session operations.
+ */
+export declare enum DataMode {
+    /** Overwrite local data with remote server snapshot. */
+    Remote = 0,
+    /** Preserve local data and upload/reconcile with remote. */
+    Local = 1,
+    /** Merge local and remote changes using Last-Write-Wins. */
+    Merge = 2,
+    /** Wipe local data tables and reset sync sequence. */
+    Clear = 3
+}
+/**
+ * Authentication lifecycle states of the client.
+ */
+export declare enum AuthStatus {
+    /** No active session. */
+    SignedOut = 0,
+    /** Authenticating or restoring remembered session. */
+    SigningIn = 1,
+    /** Authenticated and ready for synchronized operations. */
+    SignedIn = 2,
+    /** Authentication failed (e.g. invalid credentials or expired session). */
+    Error = 3
+}
+/**
+ * Options for registering a new user account.
+ */
+export interface RegisterOptions {
+    /** Unique username (required). */
+    username: string;
+    /** Account password (required). */
+    password: string;
+    /** Persist session in IndexedDB for automatic login across sessions (default: false). */
+    remember?: boolean;
+    /** Local data handling mode (defaults to DataMode.Local when signed out, or DataMode.Clear when already signed in). */
+    dataMode?: DataMode;
+}
+/**
+ * Options for logging into an existing user account.
+ */
+export interface LoginOptions {
+    /** Unique username (optional if already remembered). */
+    username?: string;
+    /** Account password (optional if already remembered). */
+    password?: string;
+    /** Persist session for automatic login across sessions (default: false). */
+    remember?: boolean;
+    /** Data reconciliation mode (default: DataMode.Remote). */
+    dataMode?: DataMode;
+}
+/**
+ * Options for logging out of the current user session.
+ */
+export interface LogoutOptions {
+    /** Data preservation mode (default: DataMode.Clear to wipe local data). */
+    dataMode?: DataMode;
+}
+/**
+ * Result returned upon successful user registration or login.
+ */
+export interface AuthResult {
+    /** Unique user identifier (UUID). */
+    userId: string;
+    /** User's unique username. */
+    username: string;
+    /** Signed session authentication token for sync and API calls. */
+    token: string;
+}
+/**
+ * Internal persisted session representation in IndexedDB metadata.
+ */
+export interface StoredAuthSession {
+    token: string;
+    userId: string;
+    username: string;
+}
+/**
+ * Internal dependencies provided to Auth by TetherClient.
+ */
+export interface AuthDependencies {
+    baseUrl: string;
+    storage: Storage;
+    fetchFn?: typeof fetch;
+}
+/**
+ * Authentication coordinator managing user sessions, HTTP requests,
+ * metadata persistence, and reconciliation state transitions.
+ */
+export declare class Auth {
+    /** Base URL for remote authentication REST API endpoints. */
+    readonly baseUrl: string;
+    /** Reactive event registry triggered whenever the authentication status changes. */
+    readonly onStatusChange: EventRegistry<AuthStatus>;
+    private storage;
+    private fetchFn;
+    private currentAuthStatus;
+    private currentUsername?;
+    private currentUserId?;
+    private currentToken?;
+    private autoRestorePromise;
+    constructor(dependencies: AuthDependencies);
+    /**
+     * Current authentication lifecycle status.
+     */
+    get status(): AuthStatus;
+    /**
+     * The authenticated user's username, or `undefined` if signed out.
+     */
+    get username(): string | undefined;
+    /**
+     * The authenticated user's ID, or `undefined` if signed out.
+     */
+    get userId(): string | undefined;
+    /**
+     * The active authentication session token, or `undefined` if signed out.
+     */
+    get token(): string | undefined;
+    /**
+     * Restores any remembered session from IndexedDB metadata on startup.
+     */
+    restoreSession(): Promise<void>;
+    /**
+     * Registers a new user account, applies local data mode, and notifies listeners.
+     */
+    register(options: RegisterOptions): Promise<boolean>;
+    /**
+     * Logs into an account (or reconnects with remembered credentials), applies data mode, and notifies listeners.
+     */
+    login(options?: LoginOptions): Promise<boolean>;
+    /**
+     * Logs out of the current session, removes stored credentials, and applies data mode.
+     */
+    logout(options?: LogoutOptions): Promise<boolean>;
+    /**
+     * Updates the in-memory and persisted session token when refreshed by the server.
+     *
+     * @param token - The new refreshed session token.
+     */
+    handleTokenRefresh(token: string): Promise<void>;
+    /**
+     * Cleans up local session and transitions to SignedOut when authentication fails or expires.
+     *
+     * @param _message - Optional error message from the server.
+     */
+    handleAuthError(_message?: string): Promise<void>;
+    private sendAuthRequest;
+    private applyDataMode;
+    private updateStoredAuth;
+    private setStatus;
+}
+//# sourceMappingURL=auth.d.ts.map

package/dist/client/auth.d.ts.map

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

package/dist/client/client.d.cts

@@ -0,0 +1,122 @@
+import { AuthStatus, type LoginOptions, type LogoutOptions, type RegisterOptions } from './auth.cjs';
+import type { TetherClientError } from './errors.cjs';
+import { EventRegistry } from './shared/event.cjs';
+import { type SyncStatus, type WebSocketConstructor } from './sync.cjs';
+import type { Table } from './table.cjs';
+export { AuthStatus, DataMode, type LoginOptions, type LogoutOptions, type RegisterOptions, } from './auth.cjs';
+export { TetherClientError, TetherClientErrorCode } from './errors.cjs';
+/**
+ * Options for configuring a TetherClient database instance.
+ */
+export interface TetherClientOptions {
+    /** Application namespace identifier (defaults to database name). */
+    appId?: string;
+    /**
+     * Unified connection URL for the remote server (e.g. `'http://localhost:8080'`, `'https://api.example.com/db'`,
+     * `'ws://localhost:8080/sync'`, or `'wss://api.example.com/db/sync'`). When provided, host, port, secure protocol,
+     * and base path are extracted automatically and can be overridden by explicit options below.
+     */
+    url?: string;
+    /** Remote server host or hostname (e.g. 'localhost' or 'api.example.com'). Defaults to current browser hostname. */
+    host?: string;
+    /** Remote server port number (e.g. 8080). Defaults to current browser port. */
+    port?: number;
+    /** Whether to use secure HTTPS and WSS protocols (defaults to `true` in secure browser contexts, `false` otherwise). */
+    secure?: boolean;
+    /** Base path for HTTP REST endpoints (defaults to ''). */
+    basePath?: string;
+    /** Path for WebSocket upgrade requests (defaults to `${basePath}/sync`). */
+    webSocketPath?: string;
+    /** Optional custom fetch implementation for authentication requests. */
+    fetch?: typeof fetch;
+    /** Custom WebSocket constructor for streaming requests. */
+    webSocketClass?: WebSocketConstructor;
+    /** Debounce delay in milliseconds before pushing queued local outbox changes (defaults to 10). */
+    pushDebounceMs?: number;
+    /** Initial reconnection backoff delay in milliseconds (defaults to 1000). */
+    reconnectIntervalMs?: number;
+    /** Maximum reconnection backoff delay in milliseconds (defaults to 30000). */
+    maxReconnectIntervalMs?: number;
+    /** Periodic keepalive ping interval in milliseconds (defaults to 30000). Set to 0 to disable. */
+    pingIntervalMs?: number;
+}
+/**
+ * Main client-side database entry point providing reactive IndexedDB tables,
+ * local-first storage, automatic auth lifecycle, and background synchronization.
+ */
+export declare class TetherClient {
+    /** Reactive event registry triggered whenever the authentication status changes. */
+    readonly onAuthStatusChange: EventRegistry<AuthStatus>;
+    /** Reactive event registry triggered whenever the synchronization status changes. */
+    readonly onSyncStatusChange: EventRegistry<SyncStatus>;
+    /** Reactive event registry triggered whenever background sync or network errors occur. */
+    readonly onError: EventRegistry<TetherClientError>;
+    private readonly storage;
+    private readonly auth;
+    private readonly sync;
+    /**
+     * Initializes a new TetherClient instance and wires reactive auth & sync coordination.
+     *
+     * @param name - Name of the local IndexedDB database.
+     * @param options - Configuration options for the server connection and sync behavior.
+     */
+    constructor(name: string, options?: TetherClientOptions);
+    /**
+     * Obtains a typed table reference for reading, mutating, and subscribing to records.
+     * Tables are created dynamically on-demand if not already declared.
+     *
+     * @typeParam T - Data payload model type for records in this table.
+     * @param name - The table name.
+     * @returns A typed `Table<T>` instance.
+     */
+    table<T = unknown>(name: string): Table<T>;
+    /**
+     * Clears all local application tables, outbox entries, and sync metadata.
+     */
+    clear(): Promise<void>;
+    /**
+     * Closes active synchronization connections and closes the IndexedDB database handle.
+     */
+    close(): Promise<void>;
+    /**
+     * Current authentication lifecycle status.
+     */
+    get authStatus(): AuthStatus;
+    /**
+     * The authenticated user's username, or `undefined` if signed out.
+     */
+    get username(): string | undefined;
+    /**
+     * Registers a new user account, applies local data mode, and connects synchronization.
+     *
+     * @param options - Registration credentials and data reconciliation settings.
+     * @returns `true` if registration succeeded; `false` otherwise.
+     */
+    register(options: RegisterOptions): Promise<boolean>;
+    /**
+     * Logs into an account (or reconnects using remembered credentials), applies data mode, and connects synchronization.
+     *
+     * @param options - Optional login credentials and data reconciliation mode.
+     * @returns `true` if authentication succeeded; `false` otherwise.
+     */
+    login(options?: LoginOptions): Promise<boolean>;
+    /**
+     * Logs out of the current session, disconnects sync, and optionally clears local tables.
+     *
+     * @param options - Options controlling whether local data should be wiped.
+     * @returns `true` on successful logout.
+     */
+    logout(options?: LogoutOptions): Promise<boolean>;
+    /**
+     * Retrieves the current synchronization status (e.g. Connected, Connecting, Disconnected, Error).
+     */
+    get syncStatus(): SyncStatus;
+    private createStorage;
+    private createAuth;
+    private createSync;
+    private parseUrl;
+    private resolveHostHeader;
+    private resolveBaseUrl;
+    private resolveWebSocketUrl;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client/client.d.ts

@@ -0,0 +1,122 @@
+import { AuthStatus, type LoginOptions, type LogoutOptions, type RegisterOptions } from './auth.js';
+import type { TetherClientError } from './errors.js';
+import { EventRegistry } from './shared/event.js';
+import { type SyncStatus, type WebSocketConstructor } from './sync.js';
+import type { Table } from './table.js';
+export { AuthStatus, DataMode, type LoginOptions, type LogoutOptions, type RegisterOptions, } from './auth.js';
+export { TetherClientError, TetherClientErrorCode } from './errors.js';
+/**
+ * Options for configuring a TetherClient database instance.
+ */
+export interface TetherClientOptions {
+    /** Application namespace identifier (defaults to database name). */
+    appId?: string;
+    /**
+     * Unified connection URL for the remote server (e.g. `'http://localhost:8080'`, `'https://api.example.com/db'`,
+     * `'ws://localhost:8080/sync'`, or `'wss://api.example.com/db/sync'`). When provided, host, port, secure protocol,
+     * and base path are extracted automatically and can be overridden by explicit options below.
+     */
+    url?: string;
+    /** Remote server host or hostname (e.g. 'localhost' or 'api.example.com'). Defaults to current browser hostname. */
+    host?: string;
+    /** Remote server port number (e.g. 8080). Defaults to current browser port. */
+    port?: number;
+    /** Whether to use secure HTTPS and WSS protocols (defaults to `true` in secure browser contexts, `false` otherwise). */
+    secure?: boolean;
+    /** Base path for HTTP REST endpoints (defaults to ''). */
+    basePath?: string;
+    /** Path for WebSocket upgrade requests (defaults to `${basePath}/sync`). */
+    webSocketPath?: string;
+    /** Optional custom fetch implementation for authentication requests. */
+    fetch?: typeof fetch;
+    /** Custom WebSocket constructor for streaming requests. */
+    webSocketClass?: WebSocketConstructor;
+    /** Debounce delay in milliseconds before pushing queued local outbox changes (defaults to 10). */
+    pushDebounceMs?: number;
+    /** Initial reconnection backoff delay in milliseconds (defaults to 1000). */
+    reconnectIntervalMs?: number;
+    /** Maximum reconnection backoff delay in milliseconds (defaults to 30000). */
+    maxReconnectIntervalMs?: number;
+    /** Periodic keepalive ping interval in milliseconds (defaults to 30000). Set to 0 to disable. */
+    pingIntervalMs?: number;
+}
+/**
+ * Main client-side database entry point providing reactive IndexedDB tables,
+ * local-first storage, automatic auth lifecycle, and background synchronization.
+ */
+export declare class TetherClient {
+    /** Reactive event registry triggered whenever the authentication status changes. */
+    readonly onAuthStatusChange: EventRegistry<AuthStatus>;
+    /** Reactive event registry triggered whenever the synchronization status changes. */
+    readonly onSyncStatusChange: EventRegistry<SyncStatus>;
+    /** Reactive event registry triggered whenever background sync or network errors occur. */
+    readonly onError: EventRegistry<TetherClientError>;
+    private readonly storage;
+    private readonly auth;
+    private readonly sync;
+    /**
+     * Initializes a new TetherClient instance and wires reactive auth & sync coordination.
+     *
+     * @param name - Name of the local IndexedDB database.
+     * @param options - Configuration options for the server connection and sync behavior.
+     */
+    constructor(name: string, options?: TetherClientOptions);
+    /**
+     * Obtains a typed table reference for reading, mutating, and subscribing to records.
+     * Tables are created dynamically on-demand if not already declared.
+     *
+     * @typeParam T - Data payload model type for records in this table.
+     * @param name - The table name.
+     * @returns A typed `Table<T>` instance.
+     */
+    table<T = unknown>(name: string): Table<T>;
+    /**
+     * Clears all local application tables, outbox entries, and sync metadata.
+     */
+    clear(): Promise<void>;
+    /**
+     * Closes active synchronization connections and closes the IndexedDB database handle.
+     */
+    close(): Promise<void>;
+    /**
+     * Current authentication lifecycle status.
+     */
+    get authStatus(): AuthStatus;
+    /**
+     * The authenticated user's username, or `undefined` if signed out.
+     */
+    get username(): string | undefined;
+    /**
+     * Registers a new user account, applies local data mode, and connects synchronization.
+     *
+     * @param options - Registration credentials and data reconciliation settings.
+     * @returns `true` if registration succeeded; `false` otherwise.
+     */
+    register(options: RegisterOptions): Promise<boolean>;
+    /**
+     * Logs into an account (or reconnects using remembered credentials), applies data mode, and connects synchronization.
+     *
+     * @param options - Optional login credentials and data reconciliation mode.
+     * @returns `true` if authentication succeeded; `false` otherwise.
+     */
+    login(options?: LoginOptions): Promise<boolean>;
+    /**
+     * Logs out of the current session, disconnects sync, and optionally clears local tables.
+     *
+     * @param options - Options controlling whether local data should be wiped.
+     * @returns `true` on successful logout.
+     */
+    logout(options?: LogoutOptions): Promise<boolean>;
+    /**
+     * Retrieves the current synchronization status (e.g. Connected, Connecting, Disconnected, Error).
+     */
+    get syncStatus(): SyncStatus;
+    private createStorage;
+    private createAuth;
+    private createSync;
+    private parseUrl;
+    private resolveHostHeader;
+    private resolveBaseUrl;
+    private resolveWebSocketUrl;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client/client.d.ts.map

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

package/dist/client/errors.d.cts

@@ -0,0 +1,39 @@
+/**
+ * Error codes identifying broader client-side error categories.
+ */
+export declare enum TetherClientErrorCode {
+    /** A required configuration option or parameter is missing. */
+    MissingConfiguration = 0,
+    /** An invalid parameter or argument was provided to a client method. */
+    InvalidInput = 1,
+    /** No suitable fetch implementation is available in the runtime environment. */
+    FetchUnavailable = 2,
+    /** Network or connection failure when communicating with the server. */
+    NetworkError = 3,
+    /** No valid credentials or session available for authentication. */
+    MissingCredentials = 4,
+    /** User registration failed. */
+    RegistrationFailed = 5,
+    /** User authentication / login failed. */
+    AuthenticationFailed = 6,
+    /** Local storage operation failed. */
+    StorageError = 7,
+    /** Real-time synchronization encountered an error. */
+    SyncError = 8
+}
+/**
+ * Dedicated error class for TetherDB client errors.
+ * Error messages are user-safe and contain no internal technical details.
+ */
+export declare class TetherClientError extends Error {
+    /** Error category code identifying the broad error type. */
+    readonly code: TetherClientErrorCode;
+    /**
+     * Initializes a new `TetherClientError`.
+     *
+     * @param code - The error category code.
+     * @param message - User-safe error description message.
+     */
+    constructor(code: TetherClientErrorCode, message?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/client/errors.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Error codes identifying broader client-side error categories.
+ */
+export declare enum TetherClientErrorCode {
+    /** A required configuration option or parameter is missing. */
+    MissingConfiguration = 0,
+    /** An invalid parameter or argument was provided to a client method. */
+    InvalidInput = 1,
+    /** No suitable fetch implementation is available in the runtime environment. */
+    FetchUnavailable = 2,
+    /** Network or connection failure when communicating with the server. */
+    NetworkError = 3,
+    /** No valid credentials or session available for authentication. */
+    MissingCredentials = 4,
+    /** User registration failed. */
+    RegistrationFailed = 5,
+    /** User authentication / login failed. */
+    AuthenticationFailed = 6,
+    /** Local storage operation failed. */
+    StorageError = 7,
+    /** Real-time synchronization encountered an error. */
+    SyncError = 8
+}
+/**
+ * Dedicated error class for TetherDB client errors.
+ * Error messages are user-safe and contain no internal technical details.
+ */
+export declare class TetherClientError extends Error {
+    /** Error category code identifying the broad error type. */
+    readonly code: TetherClientErrorCode;
+    /**
+     * Initializes a new `TetherClientError`.
+     *
+     * @param code - The error category code.
+     * @param message - User-safe error description message.
+     */
+    constructor(code: TetherClientErrorCode, message?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/client/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/client/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,oBAAY,qBAAqB;IAC/B,+DAA+D;IAC/D,oBAAoB,IAAA;IACpB,wEAAwE;IACxE,YAAY,IAAA;IACZ,gFAAgF;IAChF,gBAAgB,IAAA;IAChB,wEAAwE;IACxE,YAAY,IAAA;IACZ,oEAAoE;IACpE,kBAAkB,IAAA;IAClB,gCAAgC;IAChC,kBAAkB,IAAA;IAClB,0CAA0C;IAC1C,oBAAoB,IAAA;IACpB,sCAAsC;IACtC,YAAY,IAAA;IACZ,sDAAsD;IACtD,SAAS,IAAA;CACV;AAED;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IAErC;;;;;OAKG;IACH,YAAY,IAAI,EAAE,qBAAqB,EAAE,OAAO,CAAC,EAAE,MAAM,EAKxD;CACF"}