@affectively/dash 5.3.1 → 5.4.1

package/dist/src/sync/AutomergeProvider.js

@@ -0,0 +1,153 @@
+/**
+ * AutomergeProvider - Automerge sync over WebSocket relay
+ *
+ * Mirrors HybridProvider's transport selection and discovery logic
+ * but uses Automerge's built-in sync protocol instead of Yjs.
+ * The relay server is CRDT-agnostic — it relays opaque binary frames.
+ *
+ * @automerge/automerge is dynamically imported so users who only use
+ * Yjs never pay the bundle cost.
+ */
+export class AutomergeProvider {
+    config;
+    _doc;
+    _onChange;
+    _ws = null;
+    _syncState = null;
+    _automerge = null;
+    _ready;
+    _destroyed = false;
+    _reconnectTimer = null;
+    _reconnectDelayMs = 1000;
+    _maxReconnectDelayMs = 30_000;
+    constructor(doc, config, options) {
+        this._doc = doc;
+        this.config = config;
+        this._onChange = options?.onChange;
+        this._ready = this.initialize();
+    }
+    async initialize() {
+        const am = await import('@automerge/automerge');
+        this._automerge = am;
+        this._syncState = am.initSyncState();
+        this.connectWebSocket();
+    }
+    getRelayUrl() {
+        if (this.config.websocket?.url) {
+            return toWsUrl(this.config.websocket.url);
+        }
+        if (this.config.webtransport?.url) {
+            return toWsUrl(this.config.webtransport.url);
+        }
+        return null;
+    }
+    connectWebSocket() {
+        if (this._destroyed)
+            return;
+        const relayUrl = this.getRelayUrl();
+        if (!relayUrl)
+            return;
+        const separator = relayUrl.includes('?') ? '&' : '?';
+        const params = new URLSearchParams({ room: this.config.roomName });
+        if (this.config.apiKey) {
+            params.set('apiKey', this.config.apiKey);
+        }
+        const url = `${relayUrl}${separator}${params.toString()}`;
+        try {
+            this._ws = new WebSocket(url);
+            this._ws.binaryType = 'arraybuffer';
+        }
+        catch {
+            this.scheduleReconnect();
+            return;
+        }
+        this._ws.addEventListener('open', () => {
+            this._reconnectDelayMs = 1000;
+            this.sendSyncMessage();
+        });
+        this._ws.addEventListener('message', (event) => {
+            this.handleMessage(event.data);
+        });
+        this._ws.addEventListener('close', () => {
+            this._ws = null;
+            this.scheduleReconnect();
+        });
+        this._ws.addEventListener('error', () => {
+            // close event will follow and trigger reconnect
+        });
+    }
+    scheduleReconnect() {
+        if (this._destroyed || this._reconnectTimer)
+            return;
+        this._reconnectTimer = setTimeout(() => {
+            this._reconnectTimer = null;
+            this.connectWebSocket();
+        }, this._reconnectDelayMs);
+        this._reconnectDelayMs = Math.min(this._reconnectDelayMs * 2, this._maxReconnectDelayMs);
+    }
+    sendSyncMessage() {
+        const am = this._automerge;
+        if (!am || !this._ws || this._ws.readyState !== WebSocket.OPEN)
+            return;
+        const [nextSyncState, message] = am.generateSyncMessage(this._doc, this._syncState);
+        this._syncState = nextSyncState;
+        if (message) {
+            this._ws.send(message);
+        }
+    }
+    handleMessage(data) {
+        const am = this._automerge;
+        if (!am)
+            return;
+        const message = new Uint8Array(data);
+        const [nextDoc, nextSyncState] = am.receiveSyncMessage(this._doc, this._syncState, message);
+        this._doc = nextDoc;
+        this._syncState = nextSyncState;
+        this._onChange?.(this._doc);
+        // After receiving, we may need to send our own changes
+        this.sendSyncMessage();
+    }
+    /**
+     * Update the local document. Required because Automerge documents are immutable —
+     * after calling Automerge.change(), pass the new doc here to sync it.
+     */
+    updateDoc(newDoc) {
+        this._doc = newDoc;
+        this.sendSyncMessage();
+    }
+    get doc() {
+        return this._doc;
+    }
+    get ready() {
+        return this._ready;
+    }
+    get roomName() {
+        return this.config.roomName;
+    }
+    get connected() {
+        return this._ws !== null && this._ws.readyState === WebSocket.OPEN;
+    }
+    disconnect() {
+        if (this._reconnectTimer) {
+            clearTimeout(this._reconnectTimer);
+            this._reconnectTimer = null;
+        }
+        if (this._ws) {
+            this._ws.close();
+            this._ws = null;
+        }
+    }
+    async destroy() {
+        this._destroyed = true;
+        this.disconnect();
+    }
+}
+function toWsUrl(url) {
+    if (url.startsWith('wss://') || url.startsWith('ws://'))
+        return url;
+    if (url.startsWith('https://'))
+        return `wss://${url.slice('https://'.length)}`;
+    if (url.startsWith('http://'))
+        return `ws://${url.slice('http://'.length)}`;
+    return url;
+}

package/dist/src/sync/aeon/config.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Aeon Integration Configuration
+ *
+ * Configuration for Aeon sync features in Dash.
+ * All features enabled by default.
+ */
+export interface AeonConfig {
+    /** Enable delta sync optimization (70-80% bandwidth reduction) */
+    enableDeltaSync: boolean;
+    /** Enable rich presence tracking (cursors, sections, activity) */
+    enableRichPresence: boolean;
+    /** Enable offline operation queuing */
+    enableOfflineQueue: boolean;
+    /** Bytes threshold before falling back to full sync instead of delta */
+    deltaThreshold: number;
+    /** Maximum operations to hold in offline queue */
+    maxOfflineQueueSize: number;
+    /** Maximum retries for failed offline operations */
+    maxOfflineRetries: number;
+}
+export declare const defaultAeonConfig: AeonConfig;

package/dist/src/sync/aeon/config.js

@@ -0,0 +1,14 @@
+/**
+ * Aeon Integration Configuration
+ *
+ * Configuration for Aeon sync features in Dash.
+ * All features enabled by default.
+ */
+export const defaultAeonConfig = {
+    enableDeltaSync: true,
+    enableRichPresence: true,
+    enableOfflineQueue: true,
+    deltaThreshold: 1000,
+    maxOfflineQueueSize: 1000,
+    maxOfflineRetries: 3,
+};

package/dist/src/sync/aeon/delta-adapter.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Delta Adapter for Dash
+ *
+ * Wraps Aeon's DeltaSyncOptimizer to provide delta compression
+ * for Yjs document updates. Achieves 70-80% bandwidth reduction.
+ */
+import { type DeltaOperation, type DeltaStats } from '@affectively/aeon';
+/**
+ * Adapter that wraps Yjs updates with delta compression
+ */
+export declare class DashDeltaAdapter {
+    private optimizer;
+    private roomId;
+    private updateCounter;
+    constructor(roomId: string, threshold?: number);
+    /**
+     * Wrap a Yjs update with delta compression
+     * Returns a delta payload ready for transmission
+     */
+    wrapUpdate(update: Uint8Array, origin?: string): DeltaPayload;
+    /**
+     * Unwrap a delta payload back to Yjs update
+     */
+    unwrapDelta(payload: DeltaPayload): Uint8Array;
+    /**
+     * Encode delta payload for wire transmission
+     */
+    encodePayload(payload: DeltaPayload): Uint8Array;
+    /**
+     * Decode delta payload from wire
+     */
+    decodePayload(data: Uint8Array): DeltaPayload;
+    /**
+     * Get compression statistics
+     */
+    getStats(): DeltaStats;
+    /**
+     * Reset statistics
+     */
+    resetStats(): void;
+    /**
+     * Get memory footprint estimate
+     */
+    getMemoryEstimate(): number;
+    /**
+     * Clear operation history
+     */
+    clearHistory(): void;
+}
+/**
+ * Delta payload structure for wire transmission
+ */
+export interface DeltaPayload {
+    type: 'delta';
+    delta: DeltaOperation;
+    originalSize: number;
+    deltaSize: number;
+}
+/**
+ * Check if a payload is a delta payload
+ */
+export declare function isDeltaPayload(data: unknown): data is DeltaPayload;

package/dist/src/sync/aeon/delta-adapter.js

@@ -0,0 +1,98 @@
+/**
+ * Delta Adapter for Dash
+ *
+ * Wraps Aeon's DeltaSyncOptimizer to provide delta compression
+ * for Yjs document updates. Achieves 70-80% bandwidth reduction.
+ */
+import { DeltaSyncOptimizer, } from '@affectively/aeon';
+/**
+ * Adapter that wraps Yjs updates with delta compression
+ */
+export class DashDeltaAdapter {
+    optimizer;
+    roomId;
+    updateCounter = 0;
+    constructor(roomId, threshold = 1000) {
+        this.roomId = roomId;
+        this.optimizer = new DeltaSyncOptimizer(threshold);
+    }
+    /**
+     * Wrap a Yjs update with delta compression
+     * Returns a delta payload ready for transmission
+     */
+    wrapUpdate(update, origin) {
+        const operationId = `${this.roomId}-${this.updateCounter++}`;
+        // Create an Aeon Operation from the Yjs update
+        const operation = {
+            id: operationId,
+            type: 'update',
+            sessionId: this.roomId,
+            data: {
+                update: Array.from(update),
+                origin: origin ?? 'local',
+            },
+            status: 'pending',
+            createdAt: Date.now(),
+        };
+        const delta = this.optimizer.computeDelta(operation);
+        return {
+            type: 'delta',
+            delta,
+            originalSize: update.byteLength,
+            deltaSize: new TextEncoder().encode(JSON.stringify(delta)).byteLength,
+        };
+    }
+    /**
+     * Unwrap a delta payload back to Yjs update
+     */
+    unwrapDelta(payload) {
+        const operation = this.optimizer.decompressDelta(payload.delta);
+        return new Uint8Array(operation.data.update);
+    }
+    /**
+     * Encode delta payload for wire transmission
+     */
+    encodePayload(payload) {
+        return new TextEncoder().encode(JSON.stringify(payload));
+    }
+    /**
+     * Decode delta payload from wire
+     */
+    decodePayload(data) {
+        return JSON.parse(new TextDecoder().decode(data));
+    }
+    /**
+     * Get compression statistics
+     */
+    getStats() {
+        return this.optimizer.getStats();
+    }
+    /**
+     * Reset statistics
+     */
+    resetStats() {
+        this.optimizer.resetStats();
+    }
+    /**
+     * Get memory footprint estimate
+     */
+    getMemoryEstimate() {
+        return this.optimizer.getMemoryEstimate();
+    }
+    /**
+     * Clear operation history
+     */
+    clearHistory() {
+        this.optimizer.resetStats();
+    }
+}
+/**
+ * Check if a payload is a delta payload
+ */
+export function isDeltaPayload(data) {
+    return (typeof data === 'object' &&
+        data !== null &&
+        'type' in data &&
+        data.type === 'delta' &&
+        'delta' in data);
+}

package/dist/src/sync/aeon/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Aeon Integration for Dash
+ *
+ * Provides enhanced sync capabilities through Aeon:
+ * - Delta compression (70-80% bandwidth reduction)
+ * - Rich presence tracking (cursors, sections, activity)
+ * - Offline operation queuing with persistence
+ * - Schema versioning and migrations
+ */
+export { defaultAeonConfig, type AeonConfig } from './config.js';
+export { DashDeltaAdapter, isDeltaPayload, type DeltaPayload, } from './delta-adapter.js';
+export { DashPresenceAdapter, type PresenceEvents, } from './presence-adapter.js';
+export { DashOfflineAdapter, type ProcessQueueResult, type OfflineQueueEvents, } from './offline-adapter.js';
+export { DashSchemaAdapter, createSchemaAdapter, } from './schema-adapter.js';
+export type { DeltaOperation, DeltaStats, DeltaBatch, } from '@affectively/aeon';
+export type { AgentPresence, } from '@affectively/aeon';
+export type { OfflineOperation, OfflineQueueStats, OperationPriority, } from '@affectively/aeon';
+export type { SchemaVersion, Migration, MigrationResult, MigrationRecord, } from '@affectively/aeon';

package/dist/src/sync/aeon/index.js

@@ -0,0 +1,19 @@
+/**
+ * Aeon Integration for Dash
+ *
+ * Provides enhanced sync capabilities through Aeon:
+ * - Delta compression (70-80% bandwidth reduction)
+ * - Rich presence tracking (cursors, sections, activity)
+ * - Offline operation queuing with persistence
+ * - Schema versioning and migrations
+ */
+// Configuration
+export { defaultAeonConfig } from './config.js';
+// Delta compression adapter
+export { DashDeltaAdapter, isDeltaPayload, } from './delta-adapter.js';
+// Presence adapter
+export { DashPresenceAdapter, } from './presence-adapter.js';
+// Offline queue adapter
+export { DashOfflineAdapter, } from './offline-adapter.js';
+// Schema versioning adapter
+export { DashSchemaAdapter, createSchemaAdapter, } from './schema-adapter.js';

package/dist/src/sync/aeon/offline-adapter.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Offline Adapter for Dash
+ *
+ * Wraps Aeon's OfflineOperationQueue to provide offline-first
+ * operation queuing for Yjs documents.
+ */
+import { type OfflineOperation, type OfflineQueueStats, type OperationPriority } from '@affectively/aeon';
+import * as Y from 'yjs';
+/**
+ * Adapter that queues Yjs updates when offline
+ */
+export declare class DashOfflineAdapter {
+    private queue;
+    private doc;
+    private roomId;
+    private storageKey;
+    private isOnline;
+    private processingQueue;
+    constructor(doc: Y.Doc, roomId: string, maxQueueSize?: number, maxRetries?: number);
+    /**
+     * Setup network status listeners
+     */
+    private setupNetworkListeners;
+    /**
+     * Setup queue event handlers
+     */
+    private setupQueueEvents;
+    /**
+     * Queue a Yjs update for later sync
+     */
+    queueUpdate(update: Uint8Array, priority?: OperationPriority): OfflineOperation;
+    /**
+     * Check if we should queue (offline) or send directly
+     */
+    shouldQueue(): boolean;
+    /**
+     * Process queued operations
+     * @param sendFn Function to send updates (typically HybridProvider.send)
+     */
+    processQueue(sendFn?: (update: Uint8Array) => Promise<void>): Promise<ProcessQueueResult>;
+    /**
+     * Get queue statistics
+     */
+    getStats(): OfflineQueueStats;
+    /**
+     * Get pending operation count
+     */
+    getPendingCount(): number;
+    /**
+     * Check if online
+     */
+    getOnlineStatus(): boolean;
+    /**
+     * Retry failed operations
+     */
+    retryFailed(): void;
+    /**
+     * Clear failed operations
+     */
+    clearFailed(): void;
+    /**
+     * Clear all queued operations
+     */
+    clear(): void;
+    /**
+     * Subscribe to queue events
+     */
+    on<E extends keyof OfflineQueueEvents>(event: E, handler: OfflineQueueEvents[E]): void;
+    /**
+     * Unsubscribe from queue events
+     */
+    off<E extends keyof OfflineQueueEvents>(event: E, handler: OfflineQueueEvents[E]): void;
+    /**
+     * Persist queue to localStorage
+     */
+    private persistQueue;
+    /**
+     * Load queue from localStorage
+     */
+    private loadPersistedQueue;
+    /**
+     * Clear persisted queue
+     */
+    private clearPersistedQueue;
+    /**
+     * Cleanup
+     */
+    destroy(): void;
+}
+/**
+ * Result of processing the queue
+ */
+export interface ProcessQueueResult {
+    synced: number;
+    failed: number;
+}
+/**
+ * Offline queue event types
+ */
+export interface OfflineQueueEvents {
+    'operation-added': (operation: OfflineOperation) => void;
+    'operation-synced': (operation: OfflineOperation) => void;
+    'operation-failed': (operation: OfflineOperation, error: Error) => void;
+    'queue-empty': () => void;
+    'sync-started': () => void;
+    'sync-completed': (stats: {
+        synced: number;
+        failed: number;
+    }) => void;
+}