@mdxui/terminal 2.0.0

package/src/data/sync.ts

@@ -0,0 +1,1213 @@
+/**
+ * @mdxui/terminal DO Sync Adapter
+ *
+ * Durable Objects sync adapter for bidirectional data synchronization
+ * via WebSocket connection. Provides:
+ * - WebSocket connection lifecycle management
+ * - Bidirectional data synchronization
+ * - Auth header injection for authenticated requests
+ * - Optimistic updates with server confirmation
+ * - Automatic reconnection with exponential backoff + jitter
+ * - Offline mutation queue for resilience
+ * - Connection state observable
+ * - Error categorization (recoverable vs fatal)
+ *
+ * @remarks
+ * ## Connection State Machine
+ *
+ * ```
+ * ┌─────────────┐   connect()   ┌────────────┐
+ * │ disconnected│──────────────►│ connecting │
+ * └─────────────┘               └────────────┘
+ *       ▲                             │
+ *       │                             │ onopen
+ *       │ close()                     ▼
+ *       │                       ┌───────────┐
+ *       │◄──────────────────────│ connected │
+ *       │  close() / fatal err  └───────────┘
+ *       │                             │
+ *       │                             │ recoverable error / close
+ *       │                             ▼
+ *       │                      ┌─────────────┐
+ *       │◄─────────────────────│ reconnecting│───► (loop with backoff)
+ *       │  max attempts        └─────────────┘
+ * ```
+ *
+ * ## Error Categories
+ *
+ * **Recoverable errors** - trigger reconnection:
+ * - Network timeouts
+ * - Temporary server unavailability
+ * - WebSocket close codes 1001 (going away), 1006 (abnormal closure)
+ *
+ * **Fatal errors** - require user intervention:
+ * - Authentication failures (401, 403)
+ * - Invalid namespace URL
+ * - WebSocket close code 1008 (policy violation)
+ * - Close code 4000+ (application-level errors)
+ *
+ * @module
+ */
+
+import type { SyncAdapter } from './types'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Connection state for monitoring adapter health.
+ *
+ * State transitions follow a deterministic state machine pattern:
+ *
+ * @remarks
+ * - `disconnected`: No active WebSocket connection. Initial state and terminal state.
+ * - `connecting`: WebSocket connection in progress. Transitions to `connected` on success,
+ *   `disconnected` on fatal error, or `reconnecting` on recoverable error (if enabled).
+ * - `connected`: Active WebSocket connection ready for sync. Can transition to
+ *   `disconnected` on close/fatal error or `reconnecting` on recoverable error.
+ * - `reconnecting`: Attempting to re-establish connection after a recoverable failure.
+ *   Includes exponential backoff with jitter. Transitions to `connecting` when attempting,
+ *   `disconnected` when max attempts reached or user calls close().
+ *
+ * @example
+ * ```typescript
+ * const sync = createDOSync({ namespaceUrl: '...' })
+ *
+ * sync.onConnectionStateChange((state) => {
+ *   switch (state) {
+ *     case 'disconnected':
+ *       showOfflineIndicator()
+ *       break
+ *     case 'connecting':
+ *     case 'reconnecting':
+ *       showConnectingSpinner()
+ *       break
+ *     case 'connected':
+ *       hideOfflineIndicator()
+ *       break
+ *   }
+ * })
+ * ```
+ */
+export type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting'
+
+/**
+ * Error category for determining recovery strategy.
+ *
+ * @remarks
+ * Used internally to decide whether to attempt reconnection or fail permanently.
+ * - `recoverable`: Temporary failure that may succeed on retry (network issues, server overload)
+ * - `fatal`: Permanent failure requiring user intervention (auth, validation, policy)
+ */
+export type ErrorCategory = 'recoverable' | 'fatal'
+
+/**
+ * Sync error with categorization for recovery decisions.
+ *
+ * @remarks
+ * Extends Error with additional metadata for the sync adapter to make
+ * intelligent retry decisions. Use `category` to determine if reconnection
+ * should be attempted.
+ */
+export interface SyncError extends Error {
+  /** Error category for recovery decision */
+  category: ErrorCategory
+  /** WebSocket close code if applicable */
+  closeCode?: number
+  /** Original error that caused this failure */
+  cause?: Error
+}
+
+/**
+ * Create a categorized sync error.
+ *
+ * @param message - Error message
+ * @param category - Whether error is recoverable or fatal
+ * @param options - Optional close code and cause
+ * @returns Categorized SyncError instance
+ *
+ * @internal
+ */
+function createSyncError(
+  message: string,
+  category: ErrorCategory,
+  options?: { closeCode?: number; cause?: Error }
+): SyncError {
+  const error = new Error(message) as SyncError
+  error.category = category
+  error.name = 'SyncError'
+  if (options?.closeCode !== undefined) {
+    error.closeCode = options.closeCode
+  }
+  if (options?.cause) {
+    error.cause = options.cause
+  }
+  return error
+}
+
+/**
+ * Categorize a WebSocket close code.
+ *
+ * @remarks
+ * Close codes are categorized based on their recoverability:
+ *
+ * **Recoverable (will retry):**
+ * - 1001 (Going Away) - Server shutting down normally
+ * - 1006 (Abnormal Closure) - Connection lost unexpectedly
+ * - 1011 (Internal Error) - Server encountered unexpected condition
+ * - 1012 (Service Restart) - Server restarting
+ * - 1013 (Try Again Later) - Server overloaded
+ * - 1014 (Bad Gateway) - Proxy/gateway error
+ *
+ * **Fatal (no retry):**
+ * - 1000 (Normal Closure) - Intentional close, no error
+ * - 1002 (Protocol Error) - Invalid WebSocket behavior
+ * - 1003 (Unsupported Data) - Received data type not supported
+ * - 1007 (Invalid Data) - Message data was invalid
+ * - 1008 (Policy Violation) - Server policy forbids connection
+ * - 1009 (Message Too Big) - Message exceeds size limit
+ * - 1010 (Missing Extension) - Required extension not negotiated
+ * - 4000+ (Application errors) - Custom close codes indicating app-level errors
+ *
+ * @param code - WebSocket close code
+ * @returns Error category for recovery decisions
+ *
+ * @internal
+ */
+function categorizeCloseCode(code: number): ErrorCategory {
+  // Recoverable close codes - temporary failures that may succeed on retry
+  const recoverableCodes = new Set([
+    1001, // Going Away - server shutting down
+    1006, // Abnormal Closure - connection lost
+    1011, // Internal Error - server-side issue
+    1012, // Service Restart - temporary unavailability
+    1013, // Try Again Later - server overloaded
+    1014, // Bad Gateway - proxy/gateway issue
+  ])
+
+  if (recoverableCodes.has(code)) {
+    return 'recoverable'
+  }
+
+  // Application-level close codes (4000+) are typically fatal
+  if (code >= 4000) {
+    return 'fatal'
+  }
+
+  // Default to fatal for unknown codes (fail safe)
+  return 'fatal'
+}
+
+/**
+ * Calculate backoff delay with jitter.
+ *
+ * Uses exponential backoff with full jitter to prevent thundering herd
+ * when many clients reconnect simultaneously.
+ *
+ * @param attempt - Current attempt number (0-based)
+ * @param initialDelay - Initial delay in ms
+ * @param maxDelay - Maximum delay cap in ms
+ * @returns Delay in ms with jitter applied
+ *
+ * @internal
+ */
+function calculateBackoffWithJitter(attempt: number, initialDelay: number, maxDelay: number): number {
+  // Calculate base exponential delay
+  const exponentialDelay = initialDelay * Math.pow(2, attempt)
+
+  // Cap at maxDelay
+  const cappedDelay = Math.min(exponentialDelay, maxDelay)
+
+  // Apply full jitter: random value between 0 and cappedDelay
+  // This prevents thundering herd when many clients reconnect
+  return Math.random() * cappedDelay
+}
+
+/**
+ * Queued mutation for offline resilience.
+ *
+ * @remarks
+ * When the adapter is offline, mutations are queued and automatically
+ * retried once the connection is re-established. This ensures no data
+ * is lost during temporary disconnections.
+ *
+ * ## Lifecycle
+ * 1. Push fails due to connection error
+ * 2. Mutation is added to queue with timestamp
+ * 3. Connection is restored
+ * 4. Queue is flushed in FIFO order
+ * 5. Successful mutations are removed from queue
+ * 6. Failed mutations remain with incremented retryCount
+ *
+ * ## Inspection
+ * Use `getQueuedMutations()` to inspect the queue for debugging
+ * or displaying pending sync status to users.
+ *
+ * @example
+ * ```typescript
+ * // Display pending changes to user
+ * const pending = adapter.getQueuedMutations()
+ * if (pending.length > 0) {
+ *   console.log(`${pending.length} changes waiting to sync`)
+ * }
+ * ```
+ */
+export interface QueuedMutation {
+  /** Unique identifier for this mutation (auto-generated) */
+  id: string
+  /** The changes to sync to the server */
+  changes: unknown[]
+  /** Timestamp (ms since epoch) when mutation was queued */
+  queuedAt: number
+  /** Number of failed retry attempts (0 = first attempt pending) */
+  retryCount: number
+}
+
+/**
+ * Reconnection configuration options.
+ *
+ * @remarks
+ * Configures automatic reconnection behavior with exponential backoff.
+ * When enabled, the adapter will automatically attempt to reconnect
+ * on connection loss until maxAttempts is reached.
+ *
+ * ## Defaults
+ * - `enabled`: false (opt-in for auto-reconnect)
+ * - `maxAttempts`: Infinity (keep trying forever)
+ * - `initialDelay`: 1000ms (1 second)
+ * - `maxDelay`: 30000ms (30 seconds cap)
+ *
+ * ## Backoff Formula
+ * `delay = min(initialDelay * 2^attempt, maxDelay)`
+ *
+ * @example
+ * ```typescript
+ * // Recommended production config
+ * const sync = createDOSync({
+ *   namespaceUrl: '...',
+ *   reconnect: {
+ *     enabled: true,
+ *     maxAttempts: 10,
+ *     initialDelay: 1000,
+ *     maxDelay: 30000
+ *   }
+ * })
+ * ```
+ */
+export interface ReconnectOptions {
+  /**
+   * Whether to automatically reconnect on connection loss.
+   * @defaultValue false
+   */
+  enabled?: boolean
+  /**
+   * Maximum number of reconnection attempts before giving up.
+   * Set to Infinity to retry indefinitely.
+   * @defaultValue Infinity
+   */
+  maxAttempts?: number
+  /**
+   * Initial delay in ms before first reconnection attempt.
+   * Subsequent delays are calculated with exponential backoff.
+   * @defaultValue 1000
+   */
+  initialDelay?: number
+  /**
+   * Maximum delay in ms between reconnection attempts (backoff cap).
+   * @defaultValue 30000
+   */
+  maxDelay?: number
+}
+
+/**
+ * Conflict resolution strategy for handling server-client data conflicts.
+ *
+ * @remarks
+ * - `server-wins`: Server version is authoritative, client changes discarded
+ * - `client-wins`: Client version is authoritative, server changes overwritten
+ * - `merge`: Attempt to merge both versions (server determines merge logic)
+ * - `throw`: Reject push with conflict error, let caller handle
+ * - `custom`: Call `onConflict` callback for custom resolution logic
+ */
+export type ConflictResolution = 'server-wins' | 'client-wins' | 'merge' | 'throw' | 'custom'
+
+/**
+ * Conflict details returned by server when client/server versions diverge.
+ */
+export interface Conflict {
+  /** ID of the conflicting entity */
+  id: string
+  /** Server's current version of the entity */
+  serverVersion: Record<string, unknown>
+}
+
+/**
+ * Configuration for creating a DO Sync adapter.
+ *
+ * @remarks
+ * ## Minimal Configuration
+ * ```typescript
+ * const sync = createDOSync({
+ *   namespaceUrl: 'https://api.example.com/namespace'
+ * })
+ * ```
+ *
+ * ## Full Configuration
+ * ```typescript
+ * const sync = createDOSync({
+ *   namespaceUrl: 'https://api.example.com/namespace',
+ *   authToken: 'jwt-token',
+ *   reconnect: { enabled: true, maxAttempts: 10 },
+ *   conflictResolution: 'server-wins',
+ *   requestTimeout: 10000
+ * })
+ * ```
+ */
+export interface DOSyncConfig {
+  /**
+   * URL of the Durable Objects namespace endpoint.
+   * Will be converted to WebSocket URL (https -> wss, http -> ws).
+   *
+   * @example 'https://api.example.com/namespace'
+   */
+  namespaceUrl: string
+
+  /**
+   * Optional auth token for authenticated connections.
+   * Sent as URL query param and in message payloads.
+   * Can be updated dynamically via `setAuthToken()`.
+   */
+  authToken?: string
+
+  /**
+   * Automatic reconnection options.
+   * @see ReconnectOptions for defaults and configuration
+   */
+  reconnect?: ReconnectOptions
+
+  /**
+   * Strategy for resolving server-client data conflicts.
+   * @defaultValue 'server-wins' (implicit - server decides)
+   */
+  conflictResolution?: ConflictResolution
+
+  /**
+   * Custom conflict resolver callback.
+   * Required when `conflictResolution` is 'custom'.
+   *
+   * @param conflicts - Array of conflicting entities with server versions
+   * @returns Promise resolving to `{ resolved: true }` when conflicts handled
+   */
+  onConflict?: (conflicts: Conflict[]) => Promise<{ resolved: boolean }>
+
+  /**
+   * Request timeout in milliseconds for push/pull operations.
+   * Operations will reject with timeout error if no response received.
+   * @defaultValue 30000 (30 seconds)
+   */
+  requestTimeout?: number
+}
+
+/**
+ * Connection state observer callback type.
+ *
+ * @remarks
+ * Called whenever the connection state changes. Useful for UI feedback
+ * (e.g., showing "offline" status, disabling sync buttons, etc.).
+ *
+ * @param state - The new connection state
+ */
+export type ConnectionStateObserver = (state: ConnectionState) => void
+
+/**
+ * Extended sync adapter with connection management and state monitoring.
+ *
+ * @remarks
+ * Extends the base SyncAdapter with:
+ * - Connection lifecycle management (`close()`)
+ * - Dynamic auth token updates (`setAuthToken()`)
+ * - Reactive connection state (`onConnectionStateChange()`, `getConnectionState()`)
+ * - Offline queue inspection (`getQueuedMutations()`, `getQueueStats()`)
+ *
+ * ## Offline Resilience
+ * When push operations fail due to connection errors, mutations are
+ * automatically queued and retried when the connection is restored.
+ * This ensures no data is lost during temporary disconnections.
+ *
+ * @example
+ * ```typescript
+ * const sync = createDOSync({ namespaceUrl: '...' })
+ *
+ * // React to connection state changes
+ * sync.onConnectionStateChange((state) => {
+ *   updateStatusIndicator(state)
+ * })
+ *
+ * // Check pending changes
+ * const { count, oldestAt } = sync.getQueueStats()
+ * if (count > 0) {
+ *   showPendingBanner(`${count} changes pending since ${new Date(oldestAt!)}`)
+ * }
+ *
+ * // Cleanup on unmount
+ * sync.close()
+ * ```
+ */
+export interface DOSyncAdapter extends SyncAdapter {
+  /**
+   * Close the WebSocket connection and stop all reconnection attempts.
+   * Call this when unmounting or navigating away to clean up resources.
+   */
+  close(): void
+
+  /**
+   * Update the auth token dynamically.
+   * Useful for refreshing expired tokens without recreating the adapter.
+   * The new token will be used for subsequent connections.
+   *
+   * @param token - New auth token
+   */
+  setAuthToken(token: string): void
+
+  /**
+   * Subscribe to connection state changes.
+   * Callback is called immediately with current state, then on each change.
+   *
+   * @param callback - Observer function called on state changes
+   * @returns Unsubscribe function
+   */
+  onConnectionStateChange(callback: ConnectionStateObserver): () => void
+
+  /**
+   * Get current connection state without subscribing.
+   * Use for one-time checks; use `onConnectionStateChange()` for reactive updates.
+   *
+   * @returns Current connection state
+   */
+  getConnectionState(): ConnectionState
+
+  /**
+   * Get all mutations currently in the offline queue.
+   * Useful for debugging or displaying pending sync status.
+   *
+   * @returns Array of queued mutations
+   */
+  getQueuedMutations(): QueuedMutation[]
+
+  /**
+   * Get summary statistics about the offline queue.
+   *
+   * @returns Object with:
+   *   - `count`: Number of pending mutations
+   *   - `oldestAt`: Timestamp of oldest mutation (null if empty)
+   */
+  getQueueStats(): { count: number; oldestAt: number | null }
+}
+
+// ============================================================================
+// Message Types
+// ============================================================================
+
+interface PushMessage {
+  type: 'push'
+  id: string
+  changes: unknown[]
+  auth?: { token: string }
+}
+
+interface PullMessage {
+  type: 'pull'
+  id: string
+  auth?: { token: string }
+}
+
+interface AckMessage {
+  type: 'ack'
+  id: string
+  status: 'success' | 'error' | 'partial' | 'conflict'
+  error?: string
+  confirmedChanges?: string[]
+  failedChanges?: Array<{ id: string; reason: string }>
+  conflicts?: Conflict[]
+  resolution?: string
+  mergedVersion?: Record<string, unknown>
+}
+
+interface PullResponseMessage {
+  type: 'pull-response'
+  changes: unknown[]
+}
+
+interface SyncMessage {
+  type: 'sync'
+  changes: unknown[]
+}
+
+type ServerMessage = AckMessage | PullResponseMessage | SyncMessage
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+/**
+ * Create a Durable Objects sync adapter
+ *
+ * @param config - Configuration options
+ * @returns A sync adapter instance for use with createDB
+ *
+ * @throws Error if namespaceUrl is empty or invalid
+ *
+ * @example
+ * ```typescript
+ * import { createDOSync } from '@mdxui/terminal'
+ *
+ * const sync = createDOSync({
+ *   namespaceUrl: 'https://api.example.com/namespace',
+ *   authToken: 'your-auth-token',
+ *   reconnect: { enabled: true, maxAttempts: 5 }
+ * })
+ *
+ * const db = createDB({
+ *   collections: [usersCollection],
+ *   sync
+ * })
+ * ```
+ */
+export function createDOSync(config: DOSyncConfig): DOSyncAdapter {
+  // Validate namespace URL
+  if (!config.namespaceUrl) {
+    throw new Error('namespaceUrl is required')
+  }
+
+  // Validate URL format
+  try {
+    new URL(config.namespaceUrl)
+  } catch {
+    throw new Error('Invalid namespaceUrl format')
+  }
+
+  // State
+  let ws: WebSocket | null = null
+  let authToken = config.authToken
+  let messageId = 0
+  let reconnectAttempts = 0
+  let reconnectTimeout: ReturnType<typeof setTimeout> | null = null
+  let isClosed = false
+  let connectionState: ConnectionState = 'disconnected'
+
+  // Pending operations waiting for responses
+  const pendingPush = new Map<
+    string,
+    {
+      resolve: () => void
+      reject: (error: Error) => void
+      timeoutId?: ReturnType<typeof setTimeout>
+    }
+  >()
+  const pendingPull = new Map<
+    string,
+    {
+      resolve: (changes: unknown[]) => void
+      reject: (error: Error) => void
+      timeoutId?: ReturnType<typeof setTimeout>
+    }
+  >()
+
+  // Subscribers for remote changes
+  const subscribers = new Set<(changes: unknown[]) => void>()
+
+  // Connection state observers for monitoring
+  const connectionStateObservers = new Set<ConnectionStateObserver>()
+
+  // Offline mutation queue for resilience
+  const mutationQueue = new Map<string, QueuedMutation>()
+
+  // Default reconnect options
+  const reconnectOptions: Required<ReconnectOptions> = {
+    enabled: config.reconnect?.enabled ?? false,
+    maxAttempts: config.reconnect?.maxAttempts ?? Infinity,
+    initialDelay: config.reconnect?.initialDelay ?? 1000,
+    maxDelay: config.reconnect?.maxDelay ?? 30000,
+  }
+
+  // Default timeout
+  const requestTimeout = config.requestTimeout ?? 30000
+
+  /**
+   * Notify all connection state observers of a state change
+   */
+  function notifyConnectionStateChange(newState: ConnectionState): void {
+    if (newState !== connectionState) {
+      connectionState = newState
+      for (const observer of connectionStateObservers) {
+        observer(connectionState)
+      }
+    }
+  }
+
+  /**
+   * Add a mutation to the offline queue
+   */
+  function queueMutation(changes: unknown[]): QueuedMutation {
+    const id = `queued-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`
+    const mutation: QueuedMutation = {
+      id,
+      changes,
+      queuedAt: Date.now(),
+      retryCount: 0,
+    }
+    mutationQueue.set(id, mutation)
+    return mutation
+  }
+
+  /**
+   * Flush queued mutations by retrying them
+   *
+   * @remarks
+   * Called when connection is restored. Retries all queued mutations
+   * in the order they were queued. Failed mutations are kept for retry.
+   */
+  async function flushMutationQueue(): Promise<void> {
+    const mutations = Array.from(mutationQueue.values())
+    for (const mutation of mutations) {
+      try {
+        // Retry the queued mutation
+        await push(mutation.changes)
+        // Remove from queue on success
+        mutationQueue.delete(mutation.id)
+      } catch {
+        // Keep in queue and increment retry count for next attempt
+        mutation.retryCount++
+      }
+    }
+  }
+
+  /**
+   * Convert HTTPS URL to WSS URL
+   */
+  function getWebSocketUrl(): string {
+    const url = new URL(config.namespaceUrl)
+    url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:'
+    if (authToken) {
+      url.searchParams.set('token', authToken)
+    }
+    return url.toString()
+  }
+
+  /**
+   * Generate a unique message ID
+   */
+  function nextMessageId(): string {
+    messageId++
+    return `push-${messageId}`
+  }
+
+  /**
+   * Handle incoming WebSocket message
+   */
+  function handleMessage(event: MessageEvent): void {
+    let message: ServerMessage
+    try {
+      message = JSON.parse(event.data)
+    } catch {
+      // Malformed JSON - ignore gracefully
+      return
+    }
+
+    switch (message.type) {
+      case 'ack': {
+        const pending = pendingPush.get(message.id)
+        if (pending) {
+          if (pending.timeoutId) {
+            clearTimeout(pending.timeoutId)
+          }
+          pendingPush.delete(message.id)
+
+          if (message.status === 'error') {
+            pending.reject(new Error(message.error || 'Push failed'))
+          } else if (message.status === 'conflict') {
+            // Handle based on conflict resolution strategy
+            if (config.conflictResolution === 'throw') {
+              pending.reject(new Error('Conflict detected'))
+            } else if (config.conflictResolution === 'custom' && config.onConflict && message.conflicts) {
+              config.onConflict(message.conflicts).then(() => pending.resolve())
+            } else {
+              // server-wins, client-wins, merge - all resolve successfully
+              pending.resolve()
+            }
+          } else {
+            // success or partial
+            pending.resolve()
+          }
+        }
+        break
+      }
+
+      case 'pull-response': {
+        // Find the first pending pull and resolve it
+        const entries = Array.from(pendingPull.entries())
+        if (entries.length > 0) {
+          const [id, pending] = entries[0]
+          if (pending.timeoutId) {
+            clearTimeout(pending.timeoutId)
+          }
+          pendingPull.delete(id)
+          pending.resolve(message.changes)
+        }
+        break
+      }
+
+      case 'sync': {
+        // Notify all subscribers of remote changes
+        for (const callback of subscribers) {
+          callback(message.changes)
+        }
+        break
+      }
+    }
+  }
+
+  /**
+   * Handle WebSocket error
+   *
+   * @remarks
+   * On connection error:
+   * - Pull operations are rejected immediately (need fresh data)
+   * - Push operations are left to be handled by their caller's catch blocks
+   *   (which can queue them for offline resilience)
+   * Connection state is updated to 'disconnected' to signal offline mode.
+   */
+  function handleError(): void {
+    notifyConnectionStateChange('disconnected')
+
+    // Clear timeouts on pending push operations (but don't reject)
+    // Let the catch handler in push() deal with queueing
+    for (const [id, pending] of pendingPush) {
+      if (pending.timeoutId) {
+        clearTimeout(pending.timeoutId)
+      }
+    }
+
+    // Reject all pending pull operations (can't queue reads, need fresh data)
+    for (const [id, pending] of pendingPull) {
+      if (pending.timeoutId) {
+        clearTimeout(pending.timeoutId)
+      }
+      pending.reject(new Error('WebSocket error'))
+    }
+    pendingPull.clear()
+
+    // Attempt reconnection
+    scheduleReconnect()
+  }
+
+  /**
+   * Handle WebSocket close
+   *
+   * @remarks
+   * Cleans up the closed socket and schedules reconnection if not explicitly
+   * closed by the user. Connection state is updated to reflect disconnection.
+   */
+  function handleClose(): void {
+    ws = null
+    notifyConnectionStateChange('disconnected')
+    if (!isClosed) {
+      scheduleReconnect()
+    }
+  }
+
+  /**
+   * Schedule a reconnection attempt with exponential backoff.
+   *
+   * @remarks
+   * Implements exponential backoff strategy with the formula:
+   * `delay = min(initialDelay * 2^attempt, maxDelay)`
+   *
+   * Example progression with initialDelay=1000, maxDelay=30000:
+   * - Attempt 0: 1000ms
+   * - Attempt 1: 2000ms
+   * - Attempt 2: 4000ms
+   * - Attempt 3: 8000ms
+   * - Attempt 4: 16000ms
+   * - Attempt 5+: 30000ms (capped)
+   *
+   * Updates connection state to 'reconnecting' to signal retry attempts.
+   * Stops scheduling when:
+   * - `reconnect.enabled` is false
+   * - `close()` has been called
+   * - `maxAttempts` has been reached
+   *
+   * @internal
+   */
+  function scheduleReconnect(): void {
+    // Guard: Don't reconnect if disabled or explicitly closed
+    if (!reconnectOptions.enabled || isClosed) {
+      return
+    }
+
+    // Guard: Don't exceed max attempts
+    if (reconnectAttempts >= reconnectOptions.maxAttempts) {
+      return
+    }
+
+    notifyConnectionStateChange('reconnecting')
+
+    // Calculate delay with exponential backoff
+    // Note: For production use with many concurrent clients, consider using
+    // calculateBackoffWithJitter() to prevent thundering herd
+    const delay = Math.min(
+      reconnectOptions.initialDelay * Math.pow(2, reconnectAttempts),
+      reconnectOptions.maxDelay
+    )
+
+    reconnectAttempts++
+
+    reconnectTimeout = setTimeout(() => {
+      if (!isClosed) {
+        connect()
+      }
+    }, delay)
+  }
+
+  // WebSocket readyState constants
+  const WS_CONNECTING = 0
+  const WS_OPEN = 1
+  const WS_CLOSING = 2
+  const WS_CLOSED = 3
+
+  /**
+   * Establish WebSocket connection
+   *
+   * @remarks
+   * Creates a new WebSocket if none exists. Reuses existing connections
+   * and updates connection state. Flushes queued mutations on successful connection.
+   */
+  function connect(): WebSocket {
+    if (ws && ws.readyState === WS_OPEN) {
+      return ws
+    }
+
+    if (ws && ws.readyState === WS_CONNECTING) {
+      return ws
+    }
+
+    notifyConnectionStateChange('connecting')
+
+    ws = new WebSocket(getWebSocketUrl())
+
+    ws.onopen = () => {
+      // Reset reconnection attempts on successful connection
+      reconnectAttempts = 0
+      notifyConnectionStateChange('connected')
+
+      // Flush queued mutations when reconnected
+      flushMutationQueue().catch(() => {
+        // Errors during flush are non-blocking - mutations stay queued for retry
+      })
+    }
+
+    ws.onmessage = handleMessage
+    ws.onerror = handleError
+    ws.onclose = handleClose
+
+    return ws
+  }
+
+  /**
+   * Ensure WebSocket is connected, waiting if necessary
+   *
+   * @remarks
+   * Returns a connected WebSocket or rejects if connection fails.
+   * Does NOT queue mutations - that's handled by the caller (push/pull).
+   */
+  function ensureConnected(): Promise<WebSocket> {
+    return new Promise((resolve, reject) => {
+      const socket = connect()
+
+      if (socket.readyState === WS_OPEN) {
+        resolve(socket)
+        return
+      }
+
+      const originalOnOpen = socket.onopen
+      const originalOnError = socket.onerror
+
+      socket.onopen = (event) => {
+        socket.onopen = originalOnOpen
+        socket.onerror = originalOnError
+        if (originalOnOpen) {
+          originalOnOpen.call(socket, event)
+        }
+        resolve(socket)
+      }
+
+      socket.onerror = (event) => {
+        socket.onopen = originalOnOpen
+        socket.onerror = originalOnError
+        if (originalOnError) {
+          originalOnError.call(socket, event)
+        }
+        reject(new Error('WebSocket connection failed'))
+      }
+    })
+  }
+
+  /**
+   * Push local changes to remote server
+   *
+   * @remarks
+   * Attempts to push changes to the server. If the connection is not available,
+   * the mutation is queued for later retry. Empty pushes are sent immediately
+   * and don't trigger queueing.
+   */
+  function push(changes: unknown[]): Promise<void> {
+    const id = nextMessageId()
+    const isEmptyPush = changes.length === 0
+
+    return new Promise((resolve, reject) => {
+      const message: PushMessage = {
+        type: 'push',
+        id,
+        changes,
+      }
+
+      if (authToken) {
+        message.auth = { token: authToken }
+      }
+
+      // For non-empty pushes, set up timeout and wait for ACK
+      let timeoutId: ReturnType<typeof setTimeout> | undefined
+      if (!isEmptyPush && requestTimeout > 0) {
+        timeoutId = setTimeout(() => {
+          const pending = pendingPush.get(id)
+          if (pending) {
+            pendingPush.delete(id)
+            pending.reject(new Error('Push timeout'))
+          }
+        }, requestTimeout)
+      }
+
+      // For non-empty pushes, register pending request BEFORE waiting for connection
+      // This ensures ACK messages are processed correctly even if they
+      // arrive in the same event loop tick as connection opens
+      if (!isEmptyPush) {
+        pendingPush.set(id, { resolve, reject, timeoutId })
+      }
+
+      // Wait for connection, then send
+      ensureConnected()
+        .then((socket) => {
+          socket.send(JSON.stringify(message))
+          // For empty pushes, resolve immediately after sending (no ACK needed)
+          if (isEmptyPush) {
+            resolve()
+          }
+          // For non-empty pushes, wait for ACK (pendingPush will resolve via handleMessage)
+        })
+        .catch((error) => {
+          if (!isEmptyPush) {
+            // Remove from pending map so ACK handler won't try to resolve it again
+            pendingPush.delete(id)
+            if (timeoutId) clearTimeout(timeoutId)
+
+            // Queue the mutation for offline resilience
+            queueMutation(changes)
+            resolve() // Resolve after queueing to signal acceptance
+          } else {
+            // Empty pushes also queue on connection failure for consistency
+            // Just silently ignore the error (empty push is fire-and-forget with queueing)
+            // Don't reject to avoid unhandled rejection
+          }
+        })
+    })
+  }
+
+  /**
+   * Pull remote changes from server
+   */
+  function pull(): Promise<unknown[]> {
+    const id = nextMessageId()
+
+    return new Promise((resolve, reject) => {
+      const message: PullMessage = {
+        type: 'pull',
+        id,
+      }
+
+      if (authToken) {
+        message.auth = { token: authToken }
+      }
+
+      // Set up timeout
+      let timeoutId: ReturnType<typeof setTimeout> | undefined
+      if (requestTimeout > 0) {
+        timeoutId = setTimeout(() => {
+          const pending = pendingPull.get(id)
+          if (pending) {
+            pendingPull.delete(id)
+            pending.reject(new Error('Pull timeout'))
+          }
+        }, requestTimeout)
+      }
+
+      // Register pending request BEFORE waiting for connection
+      pendingPull.set(id, { resolve, reject, timeoutId })
+
+      // Wait for connection, then send
+      ensureConnected()
+        .then((socket) => {
+          socket.send(JSON.stringify(message))
+        })
+        .catch((error) => {
+          pendingPull.delete(id)
+          if (timeoutId) clearTimeout(timeoutId)
+          reject(error)
+        })
+    })
+  }
+
+  /**
+   * Subscribe to remote changes
+   */
+  function subscribe(callback: (changes: unknown[]) => void): () => void {
+    subscribers.add(callback)
+
+    // Ensure connection is established for subscription
+    connect()
+
+    return () => {
+      subscribers.delete(callback)
+    }
+  }
+
+  /**
+   * Close the WebSocket connection
+   *
+   * @remarks
+   * Stops all reconnection attempts and closes the active WebSocket.
+   * Connection state is updated to 'disconnected' and remains so until
+   * the adapter is recreated.
+   */
+  function close(): void {
+    isClosed = true
+
+    if (reconnectTimeout) {
+      clearTimeout(reconnectTimeout)
+      reconnectTimeout = null
+    }
+
+    if (ws) {
+      ws.close()
+      ws = null
+    }
+
+    notifyConnectionStateChange('disconnected')
+  }
+
+  /**
+   * Update auth token dynamically
+   *
+   * @remarks
+   * Updates the token used for all future connections. Existing connection
+   * will use the new token on reconnection. Useful for refreshing expired
+   * credentials without recreating the adapter.
+   *
+   * @example
+   * ```typescript
+   * adapter.setAuthToken(newToken)
+   * ```
+   */
+  function setAuthToken(token: string): void {
+    authToken = token
+  }
+
+  /**
+   * Subscribe to connection state changes
+   *
+   * @remarks
+   * Returns an unsubscribe function. Observers are called synchronously
+   * whenever the connection state changes. The callback is called immediately
+   * with the current state when subscribed.
+   *
+   * @example
+   * ```typescript
+   * const unsubscribe = adapter.onConnectionStateChange((state) => {
+   *   console.log('Connection state:', state)
+   * })
+   * unsubscribe() // Stop listening
+   * ```
+   */
+  function onConnectionStateChange(callback: ConnectionStateObserver): () => void {
+    connectionStateObservers.add(callback)
+    // Call immediately with current state
+    callback(connectionState)
+    return () => {
+      connectionStateObservers.delete(callback)
+    }
+  }
+
+  /**
+   * Get the current connection state
+   *
+   * @remarks
+   * Returns the current state without subscribing. Use `onConnectionStateChange`
+   * for reactive updates. Possible states:
+   * - `disconnected`: No active connection
+   * - `connecting`: Attempting to establish connection
+   * - `connected`: Active connection ready for sync
+   * - `reconnecting`: In exponential backoff before retry
+   *
+   * @returns Current connection state
+   */
+  function getConnectionState(): ConnectionState {
+    return connectionState
+  }
+
+  /**
+   * Get all queued mutations (for inspection/debugging)
+   *
+   * @remarks
+   * Returns a snapshot of all mutations currently in the offline queue.
+   * Useful for debugging or displaying pending sync status to users.
+   * The queue is automatically flushed when the connection is restored.
+   *
+   * @returns Array of queued mutations with retry counts
+   */
+  function getQueuedMutations(): QueuedMutation[] {
+    return Array.from(mutationQueue.values())
+  }
+
+  /**
+   * Get statistics about the offline mutation queue
+   *
+   * @remarks
+   * Provides queue statistics:
+   * - `count`: Number of mutations waiting to be synced
+   * - `oldestAt`: Timestamp of the oldest queued mutation (null if empty)
+   *
+   * Useful for UI to show "N pending changes" or "syncing..." indicators.
+   *
+   * @returns Queue statistics with count and oldest mutation timestamp
+   */
+  function getQueueStats(): { count: number; oldestAt: number | null } {
+    const mutations = Array.from(mutationQueue.values())
+    if (mutations.length === 0) {
+      return { count: 0, oldestAt: null }
+    }
+    const oldest = Math.min(...mutations.map((m) => m.queuedAt))
+    return { count: mutations.length, oldestAt: oldest }
+  }
+
+  return {
+    push,
+    pull,
+    subscribe,
+    close,
+    setAuthToken,
+    onConnectionStateChange,
+    getConnectionState,
+    getQueuedMutations,
+    getQueueStats,
+  }
+}