@affectively/dash 5.3.1 → 5.4.1

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

@@ -0,0 +1,227 @@
+/**
+ * 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') {
+            if (typeof navigator !== 'undefined' && typeof navigator.onLine === 'boolean') {
+                this.isOnline = navigator.onLine;
+            }
+            if (typeof window.addEventListener === 'function') {
+                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;
+}

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

@@ -0,0 +1,157 @@
+/**
+ * Presence Adapter for Dash
+ *
+ * Bridges Yjs awareness protocol with Aeon's AgentPresenceManager.
+ * Provides rich presence features: cursor tracking, active sections, roles.
+ */
+import { AgentPresenceManager, } from '@affectively/aeon';
+/**
+ * Adapter that syncs Yjs awareness with Aeon presence
+ */
+export class DashPresenceAdapter {
+    aeonPresence;
+    yjsAwareness;
+    localAgentId;
+    roomId;
+    constructor(roomId, awareness) {
+        this.roomId = roomId;
+        this.yjsAwareness = awareness;
+        this.localAgentId = `agent-${awareness.clientID}`;
+        this.aeonPresence = new AgentPresenceManager(roomId);
+        // Register local agent
+        this.aeonPresence.agentJoined(this.localAgentId, `User ${awareness.clientID}`, 'user');
+        // Bidirectional sync setup
+        this.setupYjsToAeonSync();
+        this.setupAeonToYjsSync();
+    }
+    /**
+     * Sync Yjs awareness updates to Aeon presence
+     */
+    setupYjsToAeonSync() {
+        this.yjsAwareness.on('update', ({ added, updated, removed }) => {
+            const states = this.yjsAwareness.getStates();
+            // Handle added/updated
+            for (const clientId of [...added, ...updated]) {
+                const state = states.get(clientId);
+                if (state) {
+                    const agentId = `agent-${clientId}`;
+                    if (added.includes(clientId)) {
+                        this.aeonPresence.agentJoined(agentId, state.user?.name || `User ${clientId}`, state.user?.role || 'user', state.metadata);
+                    }
+                    // Sync cursor and section if present
+                    if (state.cursor) {
+                        this.aeonPresence.updateCursor(agentId, state.cursor.x ?? 0, state.cursor.y ?? 0, state.cursor.path ?? '');
+                    }
+                    if (state.activeSection) {
+                        this.aeonPresence.updateActiveSection(agentId, state.activeSection);
+                    }
+                    // Heartbeat to keep presence alive
+                    this.aeonPresence.heartbeat(agentId);
+                }
+            }
+            // Handle removed
+            for (const clientId of removed) {
+                this.aeonPresence.agentLeft(`agent-${clientId}`);
+            }
+        });
+    }
+    /**
+     * Sync Aeon presence updates back to Yjs awareness
+     */
+    setupAeonToYjsSync() {
+        // When local presence updates via Aeon API, reflect to Yjs
+        this.aeonPresence.on('cursor_updated', ({ agentId, cursorPosition }) => {
+            if (agentId === this.localAgentId) {
+                this.yjsAwareness.setLocalStateField('cursor', cursorPosition);
+            }
+        });
+        this.aeonPresence.on('section_updated', ({ agentId, activeSection }) => {
+            if (agentId === this.localAgentId) {
+                this.yjsAwareness.setLocalStateField('activeSection', activeSection);
+            }
+        });
+    }
+    // ============================================
+    // Rich Presence API
+    // ============================================
+    /**
+     * Update local cursor position
+     */
+    updateCursor(x, y, path) {
+        this.aeonPresence.updateCursor(this.localAgentId, x, y, path);
+    }
+    /**
+     * Update local active section
+     */
+    updateActiveSection(section) {
+        this.aeonPresence.updateActiveSection(this.localAgentId, section);
+    }
+    /**
+     * Update local user info
+     */
+    updateUserInfo(name, role = 'user') {
+        this.aeonPresence.updatePresence(this.localAgentId, {
+            agentId: this.localAgentId,
+            name,
+            role,
+            status: 'online',
+        });
+        // Also sync to Yjs awareness
+        this.yjsAwareness.setLocalStateField('user', { name, role });
+    }
+    /**
+     * Get all online agents
+     */
+    getOnlineAgents() {
+        return this.aeonPresence.getOnlineAgents();
+    }
+    /**
+     * Get all agents (including offline)
+     */
+    getAllAgents() {
+        return this.aeonPresence.getAllAgents();
+    }
+    /**
+     * Get presence for specific agent
+     */
+    getPresence(agentId) {
+        return this.aeonPresence.getPresence(agentId);
+    }
+    /**
+     * Get agents in a specific section
+     */
+    getAgentsInSection(section) {
+        return this.aeonPresence.getInSection(section);
+    }
+    /**
+     * Get presence statistics
+     */
+    getStats() {
+        return this.aeonPresence.getPresenceStats();
+    }
+    /**
+     * Get local agent ID
+     */
+    getLocalAgentId() {
+        return this.localAgentId;
+    }
+    /**
+     * Subscribe to presence events
+     */
+    on(event, handler) {
+        this.aeonPresence.on(event, handler);
+    }
+    /**
+     * Unsubscribe from presence events
+     */
+    off(event, handler) {
+        this.aeonPresence.off(event, handler);
+    }
+    /**
+     * Cleanup
+     */
+    destroy() {
+        this.aeonPresence.agentLeft(this.localAgentId);
+        this.aeonPresence.destroy();
+    }
+}

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

@@ -0,0 +1,95 @@
+/**
+ * Schema Adapter for Dash
+ *
+ * Bridges Aeon's SchemaVersionManager with Dash's LensEngine.
+ * Provides migration tracking, version compatibility checks, and audit trails.
+ */
+import { type SchemaVersion, type Migration, type MigrationResult } from '@affectively/aeon';
+import { LensEngine, type LensOp } from '../../schema/lens.js';
+/**
+ * Adapter that bridges Aeon versioning with Dash's Lens system
+ */
+export declare class DashSchemaAdapter {
+    private versionManager;
+    private migrationEngine;
+    private migrationTracker;
+    private lensEngine;
+    constructor(lensEngine: LensEngine);
+    /**
+     * Register a schema version with associated Lens operations
+     */
+    registerVersion(version: string, description: string, lensOps?: LensOp[], breaking?: boolean): void;
+    /**
+     * Register a migration for a version upgrade
+     */
+    registerMigration(id: string, fromVersion: string, toVersion: string, migrate: (data: unknown) => unknown, rollback?: (data: unknown) => unknown): void;
+    /**
+     * Execute a migration on data
+     */
+    executeMigration(migrationId: string, data: unknown): Promise<MigrationResult>;
+    /**
+     * Rollback a migration
+     */
+    rollbackMigration(migrationId: string, data: unknown): Promise<MigrationResult>;
+    /**
+     * Migrate data using Lens transformations
+     */
+    migrateWithLens(data: Record<string, unknown>, fromVersion: number, toVersion: number): Record<string, unknown>;
+    /**
+     * Get current version
+     */
+    getCurrentVersion(): SchemaVersion;
+    /**
+     * Get a specific version by string
+     */
+    getVersion(version: string): SchemaVersion | undefined;
+    /**
+     * Get migration by ID
+     */
+    getMigration(id: string): Migration | undefined;
+    /**
+     * Check if migration is needed
+     */
+    needsMigration(fromVersion: string, toVersion: string): boolean;
+    /**
+     * Get migration path between versions
+     */
+    getMigrationPath(fromVersion: string, toVersion: string): SchemaVersion[];
+    /**
+     * Get pending migrations
+     */
+    getPendingMigrations(): Migration[];
+    /**
+     * Get migration statistics
+     */
+    getStatistics(): {
+        engine: {
+            totalExecuted: number;
+            successful: number;
+            failed: number;
+            successRate: number;
+            totalDurationMs: number;
+            averageDurationMs: number;
+            totalAffected: number;
+        };
+        tracker: {
+            total: number;
+            applied: number;
+            failed: number;
+            pending: number;
+            rolledBack: number;
+            successRate: number;
+            totalDurationMs: number;
+            averageDurationMs: number;
+            totalItemsAffected: number;
+        };
+    };
+    /**
+     * Format version for display
+     */
+    formatVersion(version: SchemaVersion): string;
+}
+/**
+ * Create a schema adapter from an existing LensEngine
+ */
+export declare function createSchemaAdapter(lensEngine: LensEngine): DashSchemaAdapter;