@mdxui/terminal 2.0.0

package/src/__tests__/data/sync.test.ts

@@ -0,0 +1,1614 @@
+/**
+ * @mdxui/terminal DO Sync Adapter Tests
+ *
+ * TDD RED Phase: These tests define the contract for the DO Sync Adapter.
+ * All tests should FAIL initially because the implementation doesn't exist yet.
+ *
+ * The DO Sync Adapter provides:
+ * - createDOSync() - Creates a sync adapter for @dotdo/react
+ * - WebSocket connection lifecycle management
+ * - Bidirectional data synchronization
+ * - Auth header injection for authenticated requests
+ * - Optimistic updates with server confirmation
+ * - Automatic reconnection with exponential backoff
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import type { SyncAdapter } from '../../data/types'
+
+// ============================================================================
+// Mock WebSocket Setup
+// ============================================================================
+
+class MockWebSocket {
+  url: string
+  readyState: number = 0 // CONNECTING
+  onopen: ((event: Event) => void) | null = null
+  onclose: ((event: CloseEvent) => void) | null = null
+  onerror: ((event: Event) => void) | null = null
+  onmessage: ((event: MessageEvent) => void) | null = null
+
+  static instances: MockWebSocket[] = []
+  static lastInstance: MockWebSocket | null = null
+
+  constructor(url: string) {
+    this.url = url
+    MockWebSocket.instances.push(this)
+    MockWebSocket.lastInstance = this
+  }
+
+  send(data: string): void {
+    // No-op for mock
+  }
+
+  close(): void {
+    this.readyState = 3 // CLOSED
+    if (this.onclose) {
+      this.onclose(new CloseEvent('close'))
+    }
+  }
+
+  // Simulate connection opened
+  simulateOpen(): void {
+    this.readyState = 1 // OPEN
+    if (this.onopen) {
+      this.onopen(new Event('open'))
+    }
+  }
+
+  // Simulate connection error
+  simulateError(message?: string): void {
+    if (this.onerror) {
+      this.onerror(new Event('error', { detail: message }))
+    }
+  }
+
+  // Simulate receiving message from server
+  simulateMessage(data: any): void {
+    if (this.onmessage) {
+      this.onmessage(new MessageEvent('message', { data: JSON.stringify(data) }))
+    }
+  }
+
+  // Static methods to reset/access instances
+  static reset(): void {
+    MockWebSocket.instances = []
+    MockWebSocket.lastInstance = null
+  }
+
+  static getInstance(index: number = 0): MockWebSocket | undefined {
+    return MockWebSocket.instances[index]
+  }
+
+  static getLastInstance(): MockWebSocket | null {
+    return MockWebSocket.lastInstance
+  }
+}
+
+// Override global WebSocket before importing the module
+const originalWebSocket = globalThis.WebSocket as any
+Object.defineProperty(globalThis, 'WebSocket', {
+  value: MockWebSocket,
+  writable: true,
+  configurable: true,
+})
+
+// ============================================================================
+// createDOSync() Configuration Tests
+// ============================================================================
+
+describe('@mdxui/terminal DO Sync Adapter - createDOSync configuration', () => {
+  beforeEach(() => {
+    MockWebSocket.reset()
+  })
+
+  afterEach(() => {
+    MockWebSocket.reset()
+  })
+
+  it('creates a sync adapter with namespace URL', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+    })
+
+    expect(adapter).toBeDefined()
+    expect(typeof adapter.push).toBe('function')
+    expect(typeof adapter.pull).toBe('function')
+    expect(typeof adapter.subscribe).toBe('function')
+  })
+
+  it('accepts optional auth token in configuration', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+      authToken: 'test-token-12345',
+    })
+
+    expect(adapter).toBeDefined()
+  })
+
+  it('accepts optional reconnection options', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+      reconnect: {
+        enabled: true,
+        maxAttempts: 5,
+        initialDelay: 1000,
+        maxDelay: 30000,
+      },
+    })
+
+    expect(adapter).toBeDefined()
+  })
+
+  it('accepts optional conflict resolution strategy', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+      conflictResolution: 'server-wins',
+    })
+
+    expect(adapter).toBeDefined()
+  })
+
+  it('throws error if namespace URL is missing', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    expect(() => {
+      createDOSync({
+        namespaceUrl: '',
+      })
+    }).toThrow()
+  })
+
+  it('validates namespace URL format', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    expect(() => {
+      createDOSync({
+        namespaceUrl: 'not-a-valid-url',
+      })
+    }).toThrow()
+  })
+})
+
+// ============================================================================
+// WebSocket Connection Lifecycle Tests
+// ============================================================================
+
+describe('@mdxui/terminal DO Sync Adapter - WebSocket lifecycle', () => {
+  beforeEach(() => {
+    MockWebSocket.reset()
+  })
+
+  afterEach(() => {
+    MockWebSocket.reset()
+  })
+
+  it('establishes WebSocket connection on first sync operation', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+    })
+
+    // Trigger a sync operation
+    const promise = adapter.push([])
+
+    // WebSocket should be created
+    const ws = MockWebSocket.getLastInstance()
+    expect(ws).toBeDefined()
+    expect(ws?.url).toContain('api.example.com')
+  })
+
+  it('reuses existing WebSocket connection for subsequent operations', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+    })
+
+    // First operation
+    const promise1 = adapter.push([])
+    const firstWs = MockWebSocket.getLastInstance()
+    const instanceCountAfterFirst = MockWebSocket.instances.length
+
+    // Simulate connection opening
+    firstWs?.simulateOpen()
+
+    // Wait for microtasks to flush
+    await Promise.resolve()
+
+    // Second operation
+    const promise2 = adapter.push([])
+    const instanceCountAfterSecond = MockWebSocket.instances.length
+
+    // Should NOT create a new WebSocket instance
+    expect(instanceCountAfterSecond).toBe(instanceCountAfterFirst)
+  })
+
+  it('handles connection established event', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+    })
+
+    const pushPromise = adapter.push([])
+    const ws = MockWebSocket.getLastInstance()
+
+    expect(ws).toBeDefined()
+    // Should have onopen handler set
+    expect(ws?.onopen).toBeDefined()
+
+    // Simulate successful connection
+    ws?.simulateOpen()
+
+    // Wait for microtasks to flush (ensureConnected's .then() needs to run)
+    await Promise.resolve()
+
+    // Promise should eventually resolve (empty push resolves immediately after connection)
+    await expect(pushPromise).resolves.not.toThrow()
+  })
+
+  it('handles connection closed event', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+    })
+
+    const pushPromise = adapter.push([])
+    const ws = MockWebSocket.getLastInstance()
+
+    ws?.simulateOpen()
+    ws?.close()
+
+    // After close, new connection should be established for next operation
+    const promise2 = adapter.push([])
+    const newWs = MockWebSocket.getInstance(1) // Second WebSocket instance
+
+    expect(newWs).toBeDefined()
+    expect(newWs).not.toBe(ws)
+  })
+
+  it('cleans up resources on disconnect', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+    })
+
+    const pushPromise = adapter.push([])
+    const ws = MockWebSocket.getLastInstance()
+
+    ws?.simulateOpen()
+
+    // Call close if available
+    if ('close' in adapter) {
+      (adapter as any).close?.()
+    }
+
+    // WebSocket should be closed
+    expect(ws?.readyState).toBe(3) // CLOSED
+  })
+})
+
+// ============================================================================
+// Data Synchronization Flow Tests
+// ============================================================================
+
+describe('@mdxui/terminal DO Sync Adapter - data synchronization', () => {
+  beforeEach(() => {
+    MockWebSocket.reset()
+  })
+
+  afterEach(() => {
+    MockWebSocket.reset()
+  })
+
+  it('pushes local changes to remote server', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+    })
+
+    const changes = [
+      {
+        collection: 'users',
+        operation: 'insert',
+        data: { id: '1', name: 'Alice' },
+      },
+    ]
+
+    const pushPromise = adapter.push(changes)
+    const ws = MockWebSocket.getLastInstance()
+
+    ws?.simulateOpen()
+    // Wait for microtasks to flush before sending server response
+    await Promise.resolve()
+    ws?.simulateMessage({ type: 'ack', id: 'push-1', status: 'success' })
+
+    await expect(pushPromise).resolves.not.toThrow()
+  })
+
+  it('sends correct message format on push', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+    })
+
+    const changes = [
+      {
+        collection: 'users',
+        operation: 'insert',
+        data: { id: '1', name: 'Alice' },
+      },
+    ]
+
+    const sendSpy = vi.spyOn(MockWebSocket.prototype, 'send')
+
+    const pushPromise = adapter.push(changes)
+    const ws = MockWebSocket.getLastInstance()
+
+    ws?.simulateOpen()
+    await Promise.resolve()
+    ws?.simulateMessage({ type: 'ack', id: 'push-1', status: 'success' })
+
+    await pushPromise
+
+    expect(sendSpy).toHaveBeenCalled()
+    const sentData = JSON.parse(sendSpy.mock.calls[0][0])
+    expect(sentData.type).toBe('push')
+    expect(sentData.changes).toEqual(changes)
+
+    sendSpy.mockRestore()
+  })
+
+  it('pulls remote changes from server', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+    })
+
+    const pullPromise = adapter.pull()
+    const ws = MockWebSocket.getLastInstance()
+
+    const remoteChanges = [
+      {
+        collection: 'users',
+        operation: 'insert',
+        data: { id: '2', name: 'Bob' },
+      },
+    ]
+
+    ws?.simulateOpen()
+    await Promise.resolve()
+    ws?.simulateMessage({ type: 'pull-response', changes: remoteChanges })
+
+    const result = await pullPromise
+
+    expect(result).toEqual(remoteChanges)
+  })
+
+  it('subscribes to remote changes via WebSocket', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+    })
+
+    const callback = vi.fn()
+    const unsubscribe = adapter.subscribe(callback)
+
+    const ws = MockWebSocket.getLastInstance()
+    ws?.simulateOpen()
+
+    const remoteChanges = [
+      {
+        collection: 'todos',
+        operation: 'update',
+        data: { id: '1', completed: true },
+      },
+    ]
+
+    ws?.simulateMessage({ type: 'sync', changes: remoteChanges })
+
+    expect(callback).toHaveBeenCalledWith(remoteChanges)
+
+    // Unsubscribe should stop receiving messages
+    unsubscribe()
+    ws?.simulateMessage({ type: 'sync', changes: [] })
+
+    // Callback should not be called again
+    expect(callback).toHaveBeenCalledTimes(1)
+  })
+
+  it('handles batch changes in push operation', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+    })
+
+    const changes = [
+      { collection: 'users', operation: 'insert', data: { id: '1', name: 'Alice' } },
+      { collection: 'users', operation: 'insert', data: { id: '2', name: 'Bob' } },
+      { collection: 'todos', operation: 'insert', data: { id: '1', title: 'Task 1' } },
+    ]
+
+    const pushPromise = adapter.push(changes)
+    const ws = MockWebSocket.getLastInstance()
+
+    ws?.simulateOpen()
+    await Promise.resolve()
+    ws?.simulateMessage({ type: 'ack', id: 'push-1', status: 'success' })
+
+    await expect(pushPromise).resolves.not.toThrow()
+  })
+
+  it('handles empty changes array', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+    })
+
+    const pushPromise = adapter.push([])
+    const ws = MockWebSocket.getLastInstance()
+
+    ws?.simulateOpen()
+    await Promise.resolve()
+    // Empty push resolves immediately - no ACK needed
+
+    await expect(pushPromise).resolves.not.toThrow()
+  })
+})
+
+// ============================================================================
+// Error Handling Tests
+// ============================================================================
+
+describe('@mdxui/terminal DO Sync Adapter - error handling', () => {
+  beforeEach(() => {
+    MockWebSocket.reset()
+  })
+
+  afterEach(() => {
+    MockWebSocket.reset()
+  })
+
+  it('queues push and resolves on WebSocket error (offline resilience)', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+    })
+
+    const changes = [{ collection: 'users', operation: 'insert' }]
+    const pushPromise = adapter.push(changes)
+    const ws = MockWebSocket.getLastInstance()
+
+    ws?.simulateError('Connection refused')
+
+    // Should resolve after queueing (offline resilience)
+    await expect(pushPromise).resolves.not.toThrow()
+
+    // Mutation should be queued
+    const queue = adapter.getQueuedMutations()
+    expect(queue.length).toBe(1)
+    expect(queue[0].changes).toEqual(changes)
+  })
+
+  it('rejects push promise on server error response', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+    })
+
+    const pushPromise = adapter.push([{ collection: 'users', operation: 'insert' }])
+    const ws = MockWebSocket.getLastInstance()
+
+    ws?.simulateOpen()
+    await Promise.resolve()
+    ws?.simulateMessage({
+      type: 'ack',
+      id: 'push-1',
+      status: 'error',
+      error: 'Validation failed',
+    })
+
+    await expect(pushPromise).rejects.toThrow('Validation failed')
+  })
+
+  it('rejects pull promise on connection failure', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+    })
+
+    const pullPromise = adapter.pull()
+    const ws = MockWebSocket.getLastInstance()
+
+    ws?.simulateError('Network error')
+
+    await expect(pullPromise).rejects.toThrow()
+  })
+
+  it('handles timeout on push operation', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+      requestTimeout: 100,
+    })
+
+    const pushPromise = adapter.push([{ collection: 'users', operation: 'insert' }])
+    const ws = MockWebSocket.getLastInstance()
+
+    ws?.simulateOpen()
+    // Don't send response - let it timeout
+
+    await expect(pushPromise).rejects.toThrow()
+  })
+
+  it('handles malformed JSON in message', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+    })
+
+    const callback = vi.fn()
+    adapter.subscribe(callback)
+
+    const ws = MockWebSocket.getLastInstance()
+    ws?.simulateOpen()
+
+    // Manually set invalid onmessage to simulate malformed data
+    const originalOnMessage = ws?.onmessage
+    if (ws) {
+      ws.onmessage = (event: MessageEvent) => {
+        // Try to handle malformed JSON
+        try {
+          JSON.parse('{invalid json}')
+        } catch (e) {
+          // Should handle gracefully without crashing
+        }
+      }
+    }
+
+    // Should not throw
+    expect(() => {
+      ws?.onmessage?.(new MessageEvent('message', { data: '{invalid' }))
+    }).not.toThrow()
+
+    if (ws && originalOnMessage) {
+      ws.onmessage = originalOnMessage
+    }
+  })
+})
+
+// ============================================================================
+// Automatic Reconnection Tests
+// ============================================================================
+
+describe('@mdxui/terminal DO Sync Adapter - automatic reconnection', () => {
+  beforeEach(() => {
+    MockWebSocket.reset()
+    vi.useFakeTimers()
+  })
+
+  afterEach(() => {
+    MockWebSocket.reset()
+    vi.useRealTimers()
+  })
+
+  it('automatically reconnects on connection loss', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+      reconnect: { enabled: true, initialDelay: 100, maxDelay: 1000 },
+    })
+
+    const pushPromise = adapter.push([])
+    let ws = MockWebSocket.getLastInstance()
+
+    ws?.simulateOpen()
+    ws?.close() // Simulate connection loss
+
+    // Should attempt reconnection
+    vi.advanceTimersByTime(100)
+
+    ws = MockWebSocket.getInstance(1)
+    expect(ws).toBeDefined()
+  })
+
+  it('implements exponential backoff for reconnection attempts', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+      reconnect: { enabled: true, initialDelay: 100, maxDelay: 5000 },
+    })
+
+    const pushPromise = adapter.push([])
+    let ws = MockWebSocket.getLastInstance()
+
+    ws?.simulateOpen()
+    ws?.close()
+
+    // First retry should be at initialDelay
+    vi.advanceTimersByTime(100)
+    let attemptCount = MockWebSocket.instances.length
+    expect(attemptCount).toBeGreaterThan(1)
+
+    // Close again to trigger second reconnection
+    ws = MockWebSocket.getLastInstance()
+    ws?.close()
+
+    // Second retry should have longer delay
+    vi.advanceTimersByTime(200)
+    let newAttemptCount = MockWebSocket.instances.length
+
+    // Should have more instances
+    expect(newAttemptCount).toBeGreaterThan(attemptCount)
+  })
+
+  it('respects max reconnection attempts', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+      reconnect: { enabled: true, maxAttempts: 3, initialDelay: 50 },
+    })
+
+    // Use non-empty push so it can be properly tracked
+    const changes = [{ operation: 'test' }]
+    const pushPromise = adapter.push(changes)
+    let ws = MockWebSocket.getLastInstance()
+
+    // Simulate first connection failure - this queues the mutation
+    ws?.simulateError('Connection failed')
+
+    // Await the push (should resolve after queueing)
+    await pushPromise
+
+    // Now simulate reconnection failures
+    for (let i = 0; i < 4; i++) {
+      vi.advanceTimersByTime(50)
+      ws = MockWebSocket.getLastInstance()
+      if (ws && ws.readyState !== 3) {
+        ws.simulateError('Connection failed')
+      }
+    }
+
+    // After maxAttempts, should stop trying
+    const instanceCount = MockWebSocket.instances.length
+    vi.advanceTimersByTime(1000)
+
+    // No new instances should be created beyond maxAttempts
+    expect(MockWebSocket.instances.length).toBeLessThanOrEqual(instanceCount + 1)
+  })
+
+  it('stops reconnection attempts after successful connection', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+      reconnect: { enabled: true, initialDelay: 100 },
+    })
+
+    const pushPromise = adapter.push([])
+    const ws = MockWebSocket.getLastInstance()
+
+    ws?.simulateOpen()
+    await Promise.resolve()
+    // Empty push - no ACK needed
+
+    await pushPromise
+
+    // Close connection
+    ws?.close()
+
+    // Wait for close handling
+    await Promise.resolve()
+
+    // Should reconnect on next operation
+    const push2 = adapter.push([])
+    const ws2 = MockWebSocket.getLastInstance()
+
+    expect(ws2).toBeDefined()
+    expect(ws2).not.toBe(ws)
+  })
+})
+
+// ============================================================================
+// Auth Header Injection Tests
+// ============================================================================
+
+describe('@mdxui/terminal DO Sync Adapter - auth header injection', () => {
+  beforeEach(() => {
+    MockWebSocket.reset()
+  })
+
+  afterEach(() => {
+    MockWebSocket.reset()
+  })
+
+  it('injects auth token into WebSocket connection header', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+      authToken: 'bearer-token-xyz',
+    })
+
+    const pushPromise = adapter.push([])
+    const ws = MockWebSocket.getLastInstance()
+
+    expect(ws?.url).toContain('token=bearer-token-xyz')
+  })
+
+  it('sends auth header in push message', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+      authToken: 'secret-token-123',
+    })
+
+    const sendSpy = vi.spyOn(MockWebSocket.prototype, 'send')
+
+    const pushPromise = adapter.push([{ collection: 'users', operation: 'insert' }])
+    const ws = MockWebSocket.getLastInstance()
+
+    ws?.simulateOpen()
+    await Promise.resolve()
+    ws?.simulateMessage({ type: 'ack', id: 'push-1', status: 'success' })
+
+    await pushPromise
+
+    const sentData = JSON.parse(sendSpy.mock.calls[0][0])
+    expect(sentData.auth).toBeDefined()
+    expect(sentData.auth.token).toBe('secret-token-123')
+
+    sendSpy.mockRestore()
+  })
+
+  it('does not include auth token if not provided', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+    })
+
+    const sendSpy = vi.spyOn(MockWebSocket.prototype, 'send')
+
+    const pushPromise = adapter.push([])
+    const ws = MockWebSocket.getLastInstance()
+
+    ws?.simulateOpen()
+    await Promise.resolve()
+    // Empty push - no ACK needed
+
+    await pushPromise
+
+    const sentData = JSON.parse(sendSpy.mock.calls[0][0])
+    expect(sentData.auth).toBeUndefined()
+
+    sendSpy.mockRestore()
+  })
+
+  it('updates auth token dynamically', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+      authToken: 'old-token',
+    })
+
+    // Update token
+    if ('setAuthToken' in adapter) {
+      (adapter as any).setAuthToken('new-token')
+    }
+
+    const sendSpy = vi.spyOn(MockWebSocket.prototype, 'send')
+
+    const pushPromise = adapter.push([])
+    const ws = MockWebSocket.getLastInstance()
+
+    ws?.simulateOpen()
+    await Promise.resolve()
+    // Empty push - no ACK needed
+
+    await pushPromise
+
+    const sentData = JSON.parse(sendSpy.mock.calls[0][0])
+    expect(sentData.auth?.token).toBe('new-token')
+
+    sendSpy.mockRestore()
+  })
+})
+
+// ============================================================================
+// Optimistic Updates with Server Confirmation Tests
+// ============================================================================
+
+describe('@mdxui/terminal DO Sync Adapter - optimistic updates', () => {
+  beforeEach(() => {
+    MockWebSocket.reset()
+  })
+
+  afterEach(() => {
+    MockWebSocket.reset()
+  })
+
+  it('confirms received changes with server acknowledgment', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+    })
+
+    const changes = [
+      {
+        collection: 'users',
+        operation: 'insert',
+        id: 'change-1',
+        data: { id: '1', name: 'Alice' },
+      },
+    ]
+
+    const pushPromise = adapter.push(changes)
+    const ws = MockWebSocket.getLastInstance()
+
+    ws?.simulateOpen()
+    await Promise.resolve()
+    ws?.simulateMessage({
+      type: 'ack',
+      id: 'push-1',
+      status: 'success',
+      confirmedChanges: ['change-1'],
+    })
+
+    await expect(pushPromise).resolves.not.toThrow()
+  })
+
+  it('handles partial server confirmation', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+    })
+
+    const changes = [
+      { collection: 'users', operation: 'insert', id: 'change-1', data: { id: '1' } },
+      { collection: 'users', operation: 'insert', id: 'change-2', data: { id: '2' } },
+    ]
+
+    const pushPromise = adapter.push(changes)
+    const ws = MockWebSocket.getLastInstance()
+
+    ws?.simulateOpen()
+    await Promise.resolve()
+    ws?.simulateMessage({
+      type: 'ack',
+      id: 'push-1',
+      status: 'partial',
+      confirmedChanges: ['change-1'],
+      failedChanges: [{ id: 'change-2', reason: 'Duplicate key' }],
+    })
+
+    // Should resolve but may include error info
+    await expect(pushPromise).resolves.not.toThrow()
+  })
+
+  it('detects server-side conflicts', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+      conflictResolution: 'throw',
+    })
+
+    const changes = [
+      { collection: 'users', operation: 'update', id: 'change-1', data: { id: '1', name: 'Alice' } },
+    ]
+
+    const pushPromise = adapter.push(changes)
+    const ws = MockWebSocket.getLastInstance()
+
+    ws?.simulateOpen()
+    await Promise.resolve()
+    ws?.simulateMessage({
+      type: 'ack',
+      id: 'push-1',
+      status: 'conflict',
+      conflicts: [{ id: 'change-1', serverVersion: { name: 'Bob' } }],
+    })
+
+    // Should reject or handle based on conflict resolution strategy
+    await expect(pushPromise).rejects.toThrow()
+  })
+
+  it('implements server-wins conflict resolution', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+      conflictResolution: 'server-wins',
+    })
+
+    const changes = [
+      { collection: 'users', operation: 'update', id: 'change-1', data: { id: '1', name: 'Alice' } },
+    ]
+
+    const pushPromise = adapter.push(changes)
+    const ws = MockWebSocket.getLastInstance()
+
+    ws?.simulateOpen()
+    await Promise.resolve()
+    ws?.simulateMessage({
+      type: 'ack',
+      id: 'push-1',
+      status: 'conflict',
+      conflicts: [{ id: 'change-1', serverVersion: { name: 'Bob' } }],
+      resolution: 'server-wins',
+    })
+
+    await expect(pushPromise).resolves.not.toThrow()
+  })
+
+  it('implements client-wins conflict resolution', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+      conflictResolution: 'client-wins',
+    })
+
+    const changes = [
+      { collection: 'users', operation: 'update', id: 'change-1', data: { id: '1', name: 'Alice' } },
+    ]
+
+    const pushPromise = adapter.push(changes)
+    const ws = MockWebSocket.getLastInstance()
+
+    ws?.simulateOpen()
+    await Promise.resolve()
+    ws?.simulateMessage({
+      type: 'ack',
+      id: 'push-1',
+      status: 'conflict',
+      conflicts: [{ id: 'change-1', serverVersion: { name: 'Bob' } }],
+      resolution: 'client-wins',
+    })
+
+    await expect(pushPromise).resolves.not.toThrow()
+  })
+
+  it('implements merge conflict resolution', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+      conflictResolution: 'merge',
+    })
+
+    const changes = [
+      {
+        collection: 'users',
+        operation: 'update',
+        id: 'change-1',
+        data: { id: '1', name: 'Alice', age: 30 },
+      },
+    ]
+
+    const pushPromise = adapter.push(changes)
+    const ws = MockWebSocket.getLastInstance()
+
+    ws?.simulateOpen()
+    await Promise.resolve()
+    ws?.simulateMessage({
+      type: 'ack',
+      id: 'push-1',
+      status: 'conflict',
+      conflicts: [{ id: 'change-1', serverVersion: { name: 'Bob', email: 'bob@example.com' } }],
+      resolution: 'merge',
+      mergedVersion: { name: 'Alice', age: 30, email: 'bob@example.com' },
+    })
+
+    await expect(pushPromise).resolves.not.toThrow()
+  })
+
+  it('handles custom conflict resolution callback', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const conflictResolver = vi.fn().mockResolvedValue({ resolved: true })
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+      conflictResolution: 'custom',
+      onConflict: conflictResolver,
+    })
+
+    const changes = [
+      { collection: 'users', operation: 'update', id: 'change-1', data: { id: '1', name: 'Alice' } },
+    ]
+
+    const pushPromise = adapter.push(changes)
+    const ws = MockWebSocket.getLastInstance()
+
+    ws?.simulateOpen()
+    await Promise.resolve()
+    ws?.simulateMessage({
+      type: 'ack',
+      id: 'push-1',
+      status: 'conflict',
+      conflicts: [{ id: 'change-1', serverVersion: { name: 'Bob' } }],
+    })
+
+    await pushPromise
+
+    // Custom resolver should be called
+    expect(conflictResolver).toHaveBeenCalled()
+  })
+})
+
+// ============================================================================
+// Integration Tests
+// ============================================================================
+
+describe('@mdxui/terminal DO Sync Adapter - integration', () => {
+  beforeEach(() => {
+    MockWebSocket.reset()
+  })
+
+  afterEach(() => {
+    MockWebSocket.reset()
+  })
+
+  it('implements full SyncAdapter interface', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+    })
+
+    // Check interface compliance
+    expect(typeof adapter.push).toBe('function')
+    expect(typeof adapter.pull).toBe('function')
+    expect(typeof adapter.subscribe).toBe('function')
+  })
+
+  it('coordinates multiple sync operations', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+    })
+
+    const pushPromise = adapter.push([{ collection: 'users', operation: 'insert' }])
+    const pullPromise = adapter.pull()
+
+    const ws = MockWebSocket.getLastInstance()
+
+    ws?.simulateOpen()
+    await Promise.resolve()
+    ws?.simulateMessage({ type: 'ack', id: 'push-1', status: 'success' })
+    ws?.simulateMessage({
+      type: 'pull-response',
+      changes: [{ collection: 'todos', operation: 'insert' }],
+    })
+
+    await Promise.all([pushPromise, pullPromise])
+
+    expect(true).toBe(true) // Both should succeed
+  })
+
+  it('maintains subscription while performing push/pull', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+    })
+
+    const callback = vi.fn()
+    const unsubscribe = adapter.subscribe(callback)
+
+    const ws = MockWebSocket.getLastInstance()
+    ws?.simulateOpen()
+    await Promise.resolve()
+
+    // Perform push (empty - no ACK needed)
+    const pushPromise = adapter.push([])
+    await Promise.resolve()
+    await pushPromise
+
+    // Subscription should still work
+    ws?.simulateMessage({ type: 'sync', changes: [{ collection: 'users', operation: 'insert' }] })
+
+    expect(callback).toHaveBeenCalled()
+
+    unsubscribe()
+  })
+})
+
+// ============================================================================
+// Connection State Observable Tests
+// ============================================================================
+
+describe('@mdxui/terminal DO Sync Adapter - connection state observable', () => {
+  beforeEach(() => {
+    MockWebSocket.reset()
+  })
+
+  afterEach(() => {
+    MockWebSocket.reset()
+  })
+
+  it('starts in disconnected state', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+    })
+
+    expect(adapter.getConnectionState()).toBe('disconnected')
+  })
+
+  it('transitions to connecting state when initiating connection', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+    })
+
+    const stateChanges: string[] = []
+    adapter.onConnectionStateChange((state) => {
+      stateChanges.push(state)
+    })
+
+    // Initiate connection by subscribing
+    adapter.subscribe(() => {})
+
+    expect(stateChanges).toContain('connecting')
+  })
+
+  it('transitions to connected state on successful connection', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+    })
+
+    const stateChanges: string[] = []
+    adapter.onConnectionStateChange((state) => {
+      stateChanges.push(state)
+    })
+
+    const pushPromise = adapter.push([])
+    const ws = MockWebSocket.getLastInstance()
+    ws?.simulateOpen()
+
+    expect(stateChanges).toContain('connected')
+    expect(adapter.getConnectionState()).toBe('connected')
+  })
+
+  it('transitions to disconnected state on connection error', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+    })
+
+    const stateChanges: string[] = []
+    adapter.onConnectionStateChange((state) => {
+      stateChanges.push(state)
+    })
+
+    const pushPromise = adapter.push([])
+    const ws = MockWebSocket.getLastInstance()
+    ws?.simulateOpen()
+    ws?.simulateError('Connection lost')
+
+    expect(stateChanges).toContain('disconnected')
+  })
+
+  it('transitions to reconnecting state during reconnection attempts', async () => {
+    vi.useFakeTimers()
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+      reconnect: { enabled: true, initialDelay: 100 },
+    })
+
+    const stateChanges: string[] = []
+    adapter.onConnectionStateChange((state) => {
+      stateChanges.push(state)
+    })
+
+    const pushPromise = adapter.push([])
+    let ws = MockWebSocket.getLastInstance()
+    ws?.simulateOpen()
+    ws?.close()
+
+    // Should be in reconnecting after close
+    expect(stateChanges).toContain('reconnecting')
+
+    vi.useRealTimers()
+  })
+
+  it('allows multiple state observers', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+    })
+
+    const observer1 = vi.fn()
+    const observer2 = vi.fn()
+
+    adapter.onConnectionStateChange(observer1)
+    adapter.onConnectionStateChange(observer2)
+
+    adapter.subscribe(() => {})
+    const ws = MockWebSocket.getLastInstance()
+    ws?.simulateOpen()
+
+    expect(observer1).toHaveBeenCalled()
+    expect(observer2).toHaveBeenCalled()
+  })
+
+  it('allows unsubscribing from state changes', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+    })
+
+    const observer = vi.fn()
+    const unsubscribe = adapter.onConnectionStateChange(observer)
+
+    adapter.subscribe(() => {})
+    const ws = MockWebSocket.getLastInstance()
+
+    // First state change
+    ws?.simulateOpen()
+    const callCount = observer.mock.calls.length
+
+    // Unsubscribe
+    unsubscribe()
+
+    // Trigger more state changes
+    ws?.close()
+
+    // Observer should not be called after unsubscribe
+    expect(observer.mock.calls.length).toBe(callCount)
+  })
+})
+
+// ============================================================================
+// Offline Mutation Queue Tests
+// ============================================================================
+
+describe('@mdxui/terminal DO Sync Adapter - offline mutation queue', () => {
+  beforeEach(() => {
+    MockWebSocket.reset()
+  })
+
+  afterEach(() => {
+    MockWebSocket.reset()
+  })
+
+  it('starts with empty queue', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+    })
+
+    expect(adapter.getQueuedMutations()).toHaveLength(0)
+    expect(adapter.getQueueStats()).toEqual({ count: 0, oldestAt: null })
+  })
+
+  it('queues mutations when connection fails', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+    })
+
+    const changes = [{ collection: 'users', operation: 'insert', data: { id: '1' } }]
+
+    // Push will fail because connection immediately fails
+    const pushPromise = adapter.push(changes)
+    const ws = MockWebSocket.getLastInstance()
+    ws?.simulateError('Connection failed')
+
+    // Should resolve after queueing
+    await pushPromise
+
+    // Check queue
+    const queue = adapter.getQueuedMutations()
+    expect(queue.length).toBe(1)
+    expect(queue[0].changes).toEqual(changes)
+  })
+
+  it('includes queue statistics', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+    })
+
+    const changes = [{ collection: 'users', operation: 'insert', data: { id: '1' } }]
+
+    const pushPromise = adapter.push(changes)
+    const ws = MockWebSocket.getLastInstance()
+    ws?.simulateError('Connection failed')
+
+    await pushPromise
+
+    const stats = adapter.getQueueStats()
+    expect(stats.count).toBe(1)
+    expect(stats.oldestAt).toBeTypeOf('number')
+    expect(stats.oldestAt).toBeLessThanOrEqual(Date.now())
+  })
+
+  it('flushes queue on successful reconnection', async () => {
+    vi.useFakeTimers()
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+      reconnect: { enabled: true, initialDelay: 100 },
+    })
+
+    const changes = [{ collection: 'users', operation: 'insert', data: { id: '1' } }]
+
+    // First push fails and gets queued
+    const pushPromise = adapter.push(changes)
+    let ws = MockWebSocket.getLastInstance()
+    ws?.simulateError('Connection failed')
+
+    await pushPromise
+
+    // Verify queued
+    expect(adapter.getQueuedMutations().length).toBe(1)
+
+    // Advance timer to trigger reconnection
+    vi.advanceTimersByTime(100)
+
+    // Get the new WebSocket and simulate successful connection
+    ws = MockWebSocket.getLastInstance()
+    ws?.simulateOpen()
+
+    // Simulate ACK for the flushed mutation
+    ws?.simulateMessage({ type: 'ack', id: 'push-2', status: 'success' })
+
+    // Allow promise to settle
+    await vi.runAllTimersAsync()
+
+    // Queue should be empty after successful flush
+    expect(adapter.getQueuedMutations().length).toBe(0)
+
+    vi.useRealTimers()
+  })
+
+  it('keeps mutations in queue if flush fails', async () => {
+    vi.useFakeTimers()
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+      reconnect: { enabled: true, initialDelay: 100 },
+      requestTimeout: 50,
+    })
+
+    const changes = [{ collection: 'users', operation: 'insert', data: { id: '1' } }]
+
+    // First push fails and gets queued
+    const pushPromise = adapter.push(changes)
+    let ws = MockWebSocket.getLastInstance()
+    ws?.simulateError('Connection failed')
+
+    await pushPromise
+
+    // Verify queued
+    expect(adapter.getQueuedMutations().length).toBe(1)
+
+    // Advance timer to trigger reconnection
+    vi.advanceTimersByTime(100)
+
+    // Get the new WebSocket and simulate successful connection
+    ws = MockWebSocket.getLastInstance()
+    ws?.simulateOpen()
+
+    // Don't send ACK - let it timeout
+    await vi.advanceTimersByTimeAsync(100)
+
+    // Queue should still have the mutation
+    const queue = adapter.getQueuedMutations()
+    expect(queue.length).toBe(1)
+    expect(queue[0].retryCount).toBeGreaterThan(0)
+
+    vi.useRealTimers()
+  })
+
+  it('preserves mutation order in queue', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+    })
+
+    const changes1 = [{ id: 'mutation-1' }]
+    const changes2 = [{ id: 'mutation-2' }]
+    const changes3 = [{ id: 'mutation-3' }]
+
+    // All pushes fail
+    const p1 = adapter.push(changes1)
+    let ws = MockWebSocket.getLastInstance()
+    ws?.simulateError('fail')
+    await p1
+
+    const p2 = adapter.push(changes2)
+    ws = MockWebSocket.getLastInstance()
+    ws?.simulateError('fail')
+    await p2
+
+    const p3 = adapter.push(changes3)
+    ws = MockWebSocket.getLastInstance()
+    ws?.simulateError('fail')
+    await p3
+
+    const queue = adapter.getQueuedMutations()
+    expect(queue.length).toBe(3)
+
+    // Verify order by timestamp
+    const timestamps = queue.map((m) => m.queuedAt)
+    expect(timestamps[0]).toBeLessThanOrEqual(timestamps[1])
+    expect(timestamps[1]).toBeLessThanOrEqual(timestamps[2])
+  })
+})
+
+// ============================================================================
+// Resilience Integration Tests
+// ============================================================================
+
+describe('@mdxui/terminal DO Sync Adapter - resilience integration', () => {
+  beforeEach(() => {
+    MockWebSocket.reset()
+    vi.useFakeTimers()
+  })
+
+  afterEach(() => {
+    MockWebSocket.reset()
+    vi.useRealTimers()
+  })
+
+  it('full offline to online cycle with queued mutations', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+      reconnect: { enabled: true, initialDelay: 100 },
+    })
+
+    const stateChanges: string[] = []
+    adapter.onConnectionStateChange((state) => {
+      stateChanges.push(state)
+    })
+
+    // Start disconnected
+    expect(adapter.getConnectionState()).toBe('disconnected')
+
+    // Initial push fails
+    const changes = [{ collection: 'users', operation: 'insert', data: { id: '1' } }]
+    const pushPromise = adapter.push(changes)
+    let ws = MockWebSocket.getLastInstance()
+    ws?.simulateError('fail')
+    await pushPromise
+
+    // Should be queued
+    expect(adapter.getQueuedMutations().length).toBe(1)
+
+    // Wait for reconnection attempt
+    vi.advanceTimersByTime(100)
+
+    // New connection succeeds
+    ws = MockWebSocket.getLastInstance()
+    ws?.simulateOpen()
+
+    // Flush happens, ACK received
+    ws?.simulateMessage({ type: 'ack', id: 'push-2', status: 'success' })
+
+    await vi.runAllTimersAsync()
+
+    // Queue should be empty
+    expect(adapter.getQueuedMutations().length).toBe(0)
+    expect(adapter.getConnectionState()).toBe('connected')
+
+    // Verify state transitions happened
+    expect(stateChanges).toContain('connecting')
+    expect(stateChanges).toContain('disconnected')
+    expect(stateChanges).toContain('connected')
+  })
+
+  it('handles rapid connection/disconnection cycles', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+      reconnect: { enabled: true, initialDelay: 50, maxDelay: 200 },
+    })
+
+    const stateChanges: string[] = []
+    adapter.onConnectionStateChange((state) => {
+      stateChanges.push(state)
+    })
+
+    // Simulate multiple rapid disconnections
+    for (let i = 0; i < 3; i++) {
+      adapter.push([])
+      const ws = MockWebSocket.getLastInstance()
+      ws?.simulateOpen()
+      ws?.close()
+      vi.advanceTimersByTime(50)
+    }
+
+    // Should have experienced multiple state transitions
+    const reconnectingCount = stateChanges.filter((s) => s === 'reconnecting').length
+    expect(reconnectingCount).toBeGreaterThan(0)
+  })
+
+  it('maintains data integrity across connection drops', async () => {
+    const { createDOSync } = await import('../../data/sync')
+
+    const adapter = createDOSync({
+      namespaceUrl: 'https://api.example.com/namespace',
+      reconnect: { enabled: true, initialDelay: 100 },
+    })
+
+    // Queue a single mutation during offline
+    const changes = [{ id: 'user-1', name: 'Alice' }]
+    const p = adapter.push(changes)
+    const ws1 = MockWebSocket.getLastInstance()
+    ws1?.simulateError('offline')
+    await p
+
+    // Should be queued
+    expect(adapter.getQueuedMutations().length).toBe(1)
+
+    // Reconnect
+    vi.advanceTimersByTime(100)
+    const ws = MockWebSocket.getLastInstance()
+    ws?.simulateOpen()
+
+    // The flush will push with the next messageId (push-2)
+    // Wait a tick for flush to start
+    await vi.advanceTimersByTimeAsync(1)
+
+    // ACK the flushed mutation
+    ws?.simulateMessage({ type: 'ack', id: 'push-2', status: 'success' })
+
+    await vi.runAllTimersAsync()
+
+    // Queue should be empty - data synced
+    expect(adapter.getQueuedMutations().length).toBe(0)
+  })
+})