@affectively/dash 5.0.1 → 5.1.0

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;
+}

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

@@ -0,0 +1,223 @@
+/**
+ * Offline Adapter for Dash
+ *
+ * Wraps Aeon's OfflineOperationQueue to provide offline-first
+ * operation queuing for Yjs documents.
+ */
+import { OfflineOperationQueue, } from '@affectively/aeon';
+import * as Y from 'yjs';
+const STORAGE_KEY_PREFIX = 'dash-offline-queue-';
+/**
+ * Adapter that queues Yjs updates when offline
+ */
+export class DashOfflineAdapter {
+    queue;
+    doc;
+    roomId;
+    storageKey;
+    isOnline = true;
+    processingQueue = false;
+    constructor(doc, roomId, maxQueueSize = 1000, maxRetries = 3) {
+        this.queue = new OfflineOperationQueue(maxQueueSize, maxRetries);
+        this.doc = doc;
+        this.roomId = roomId;
+        this.storageKey = `${STORAGE_KEY_PREFIX}${roomId}`;
+        // Load persisted queue on startup
+        this.loadPersistedQueue();
+        // Setup network status listeners
+        this.setupNetworkListeners();
+        // Setup queue event handlers
+        this.setupQueueEvents();
+    }
+    /**
+     * Setup network status listeners
+     */
+    setupNetworkListeners() {
+        if (typeof window !== 'undefined') {
+            this.isOnline = navigator.onLine;
+            window.addEventListener('online', () => {
+                this.isOnline = true;
+                this.processQueue();
+            });
+            window.addEventListener('offline', () => {
+                this.isOnline = false;
+            });
+        }
+    }
+    /**
+     * Setup queue event handlers
+     */
+    setupQueueEvents() {
+        this.queue.on('operation-synced', (operation) => {
+            this.persistQueue();
+        });
+        this.queue.on('operation-failed', (operation, error) => {
+            console.warn(`[DashOfflineAdapter] Operation ${operation.id} failed: ${error.message}`);
+            this.persistQueue();
+        });
+        this.queue.on('queue-empty', () => {
+            this.clearPersistedQueue();
+        });
+    }
+    /**
+     * Queue a Yjs update for later sync
+     */
+    queueUpdate(update, priority = 'normal') {
+        const operation = this.queue.enqueue('update', { update: Array.from(update) }, this.roomId, priority);
+        this.persistQueue();
+        return operation;
+    }
+    /**
+     * Check if we should queue (offline) or send directly
+     */
+    shouldQueue() {
+        return !this.isOnline;
+    }
+    /**
+     * Process queued operations
+     * @param sendFn Function to send updates (typically HybridProvider.send)
+     */
+    async processQueue(sendFn) {
+        if (!this.isOnline || this.processingQueue) {
+            return { synced: 0, failed: 0 };
+        }
+        this.processingQueue = true;
+        let synced = 0;
+        let failed = 0;
+        try {
+            while (true) {
+                const batch = this.queue.getNextBatch(10);
+                if (batch.length === 0)
+                    break;
+                const ids = batch.map((op) => op.id);
+                this.queue.markSyncing(ids);
+                for (const operation of batch) {
+                    try {
+                        const update = new Uint8Array(operation.data.update);
+                        if (sendFn) {
+                            // Send via provided function
+                            await sendFn(update);
+                        }
+                        else {
+                            // Apply locally if no send function
+                            Y.applyUpdate(this.doc, update);
+                        }
+                        this.queue.markSynced(operation.id);
+                        synced++;
+                    }
+                    catch (error) {
+                        this.queue.markFailed(operation.id, error);
+                        failed++;
+                    }
+                }
+            }
+        }
+        finally {
+            this.processingQueue = false;
+            this.persistQueue();
+        }
+        return { synced, failed };
+    }
+    /**
+     * Get queue statistics
+     */
+    getStats() {
+        return this.queue.getStats();
+    }
+    /**
+     * Get pending operation count
+     */
+    getPendingCount() {
+        return this.queue.getPendingCount();
+    }
+    /**
+     * Check if online
+     */
+    getOnlineStatus() {
+        return this.isOnline;
+    }
+    /**
+     * Retry failed operations
+     */
+    retryFailed() {
+        this.queue.retryFailed();
+        this.persistQueue();
+    }
+    /**
+     * Clear failed operations
+     */
+    clearFailed() {
+        this.queue.clearFailed();
+        this.persistQueue();
+    }
+    /**
+     * Clear all queued operations
+     */
+    clear() {
+        this.queue.clear();
+        this.clearPersistedQueue();
+    }
+    /**
+     * Subscribe to queue events
+     */
+    on(event, handler) {
+        this.queue.on(event, handler);
+    }
+    /**
+     * Unsubscribe from queue events
+     */
+    off(event, handler) {
+        this.queue.off(event, handler);
+    }
+    // ============================================
+    // Persistence
+    // ============================================
+    /**
+     * Persist queue to localStorage
+     */
+    persistQueue() {
+        if (typeof localStorage !== 'undefined') {
+            try {
+                const operations = this.queue.export();
+                localStorage.setItem(this.storageKey, JSON.stringify(operations));
+            }
+            catch (error) {
+                console.warn('[DashOfflineAdapter] Failed to persist queue:', error);
+            }
+        }
+    }
+    /**
+     * Load queue from localStorage
+     */
+    loadPersistedQueue() {
+        if (typeof localStorage !== 'undefined') {
+            try {
+                const stored = localStorage.getItem(this.storageKey);
+                if (stored) {
+                    const operations = JSON.parse(stored);
+                    this.queue.import(operations);
+                }
+            }
+            catch (error) {
+                console.warn('[DashOfflineAdapter] Failed to load persisted queue:', error);
+            }
+        }
+    }
+    /**
+     * Clear persisted queue
+     */
+    clearPersistedQueue() {
+        if (typeof localStorage !== 'undefined') {
+            localStorage.removeItem(this.storageKey);
+        }
+    }
+    /**
+     * Cleanup
+     */
+    destroy() {
+        this.queue.clear();
+        if (typeof window !== 'undefined') {
+            // Note: Can't easily remove anonymous listeners, but they'll be GC'd
+        }
+    }
+}

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

@@ -0,0 +1,114 @@
+/**
+ * Presence Adapter for Dash
+ *
+ * Bridges Yjs awareness protocol with Aeon's AgentPresenceManager.
+ * Provides rich presence features: cursor tracking, active sections, roles.
+ */
+import { type AgentPresence } from '@affectively/aeon';
+import type { Awareness } from 'y-protocols/awareness';
+/**
+ * Adapter that syncs Yjs awareness with Aeon presence
+ */
+export declare class DashPresenceAdapter {
+    private aeonPresence;
+    private yjsAwareness;
+    private localAgentId;
+    private roomId;
+    constructor(roomId: string, awareness: Awareness);
+    /**
+     * Sync Yjs awareness updates to Aeon presence
+     */
+    private setupYjsToAeonSync;
+    /**
+     * Sync Aeon presence updates back to Yjs awareness
+     */
+    private setupAeonToYjsSync;
+    /**
+     * Update local cursor position
+     */
+    updateCursor(x: number, y: number, path: string): void;
+    /**
+     * Update local active section
+     */
+    updateActiveSection(section: string): void;
+    /**
+     * Update local user info
+     */
+    updateUserInfo(name: string, role?: AgentPresence['role']): void;
+    /**
+     * Get all online agents
+     */
+    getOnlineAgents(): AgentPresence[];
+    /**
+     * Get all agents (including offline)
+     */
+    getAllAgents(): AgentPresence[];
+    /**
+     * Get presence for specific agent
+     */
+    getPresence(agentId: string): AgentPresence | undefined;
+    /**
+     * Get agents in a specific section
+     */
+    getAgentsInSection(section: string): AgentPresence[];
+    /**
+     * Get presence statistics
+     */
+    getStats(): {
+        total: number;
+        online: number;
+        away: number;
+        offline: number;
+        reconnecting: number;
+        byRole: Record<string, number>;
+    };
+    /**
+     * Get local agent ID
+     */
+    getLocalAgentId(): string;
+    /**
+     * Subscribe to presence events
+     */
+    on<E extends keyof PresenceEvents>(event: E, handler: PresenceEvents[E]): void;
+    /**
+     * Unsubscribe from presence events
+     */
+    off<E extends keyof PresenceEvents>(event: E, handler: PresenceEvents[E]): void;
+    /**
+     * Cleanup
+     */
+    destroy(): void;
+}
+/**
+ * Presence event types
+ */
+export interface PresenceEvents {
+    presence_updated: (data: {
+        agentId: string;
+        presence: AgentPresence;
+    }) => void;
+    agent_joined: (data: {
+        agentId: string;
+        presence: AgentPresence;
+    }) => void;
+    agent_left: (data: {
+        agentId: string;
+        presence: AgentPresence;
+    }) => void;
+    cursor_updated: (data: {
+        agentId: string;
+        cursorPosition: {
+            x: number;
+            y: number;
+            path: string;
+        };
+    }) => void;
+    section_updated: (data: {
+        agentId: string;
+        activeSection: string;
+    }) => void;
+    status_updated: (data: {
+        agentId: string;
+        status: AgentPresence['status'];
+    }) => void;
+}