@prabhask5/stellar-engine 1.0.19 → 1.1.1

package/dist/crdt/awareness.d.ts

@@ -0,0 +1,35 @@
+/**
+ * CRDT Awareness (Presence) Management
+ *
+ * Manages Yjs Awareness protocol for user presence indicators
+ * (cursor positions, active users, etc.) via Supabase broadcast.
+ */
+import { Awareness } from 'y-protocols/awareness';
+import type { AwarenessUser } from './types';
+/**
+ * Initialize awareness (presence) for a CRDT document.
+ *
+ * Creates an Awareness instance and sets up a dedicated broadcast channel
+ * for syncing presence state between clients.
+ *
+ * @param docId - Document/note ID
+ * @param userInfo - Current user's display info
+ * @returns The Awareness instance
+ */
+export declare function initAwareness(docId: string, userInfo: AwarenessUser): Awareness;
+/**
+ * Get the awareness instance for a document.
+ *
+ * @param docId - Document/note ID
+ * @returns The Awareness instance if initialized, undefined otherwise
+ */
+export declare function getAwareness(docId: string): Awareness | undefined;
+/**
+ * Destroy awareness for a document.
+ *
+ * Removes awareness state, closes the broadcast channel, and cleans up listeners.
+ *
+ * @param docId - Document/note ID
+ */
+export declare function destroyAwareness(docId: string): Promise<void>;
+//# sourceMappingURL=awareness.d.ts.map

package/dist/crdt/awareness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"awareness.d.ts","sourceRoot":"","sources":["../../src/crdt/awareness.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAOlD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AA2B7C;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,GAAG,SAAS,CAkG/E;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAEjE;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BnE"}

package/dist/crdt/awareness.js

@@ -0,0 +1,173 @@
+/**
+ * CRDT Awareness (Presence) Management
+ *
+ * Manages Yjs Awareness protocol for user presence indicators
+ * (cursor positions, active users, etc.) via Supabase broadcast.
+ */
+import { Awareness } from 'y-protocols/awareness';
+import * as awarenessProtocol from 'y-protocols/awareness';
+import { debugLog, debugWarn, debugError } from '../debug';
+import { getDeviceId } from '../deviceId';
+import { getEngineConfig } from '../config';
+import { supabase } from '../supabase/client';
+import { getCrdtDoc } from './doc';
+/** Active awareness instances: docId → { awareness, channel, cleanup } */
+const activeAwareness = new Map();
+function uint8ArrayToBase64(bytes) {
+    let binary = '';
+    for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+}
+function base64ToUint8Array(base64) {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+/**
+ * Initialize awareness (presence) for a CRDT document.
+ *
+ * Creates an Awareness instance and sets up a dedicated broadcast channel
+ * for syncing presence state between clients.
+ *
+ * @param docId - Document/note ID
+ * @param userInfo - Current user's display info
+ * @returns The Awareness instance
+ */
+export function initAwareness(docId, userInfo) {
+    const existing = activeAwareness.get(docId);
+    if (existing) {
+        // Update user info on existing awareness
+        existing.awareness.setLocalStateField('user', userInfo);
+        debugLog('[CRDT Awareness] Updated user info for:', docId);
+        return existing.awareness;
+    }
+    const doc = getCrdtDoc(docId);
+    if (!doc) {
+        throw new Error(`Cannot init awareness - doc not initialized: ${docId}`);
+    }
+    debugLog('[CRDT Awareness] Initializing for:', docId);
+    const awareness = new Awareness(doc);
+    const deviceId = getDeviceId();
+    const prefix = getEngineConfig().prefix;
+    const channelName = `awareness_${prefix}_${docId}`;
+    const cleanup = [];
+    // Set local state
+    awareness.setLocalStateField('user', userInfo);
+    // Create a broadcast channel for awareness
+    const channel = supabase.channel(channelName, {
+        config: {
+            broadcast: { self: false }
+        }
+    });
+    // Listen for remote awareness updates
+    channel.on('broadcast', { event: 'awareness' }, (payload) => {
+        if (payload.payload.deviceId === deviceId)
+            return;
+        try {
+            const update = base64ToUint8Array(payload.payload.data);
+            awarenessProtocol.applyAwarenessUpdate(awareness, update, 'remote');
+        }
+        catch (e) {
+            debugError('[CRDT Awareness] Error applying remote update:', e);
+        }
+    });
+    // Broadcast local awareness changes
+    const onUpdate = ({ added, updated, removed }, origin) => {
+        if (origin === 'remote')
+            return;
+        const changedClients = added.concat(updated).concat(removed);
+        try {
+            const update = awarenessProtocol.encodeAwarenessUpdate(awareness, changedClients);
+            channel.send({
+                type: 'broadcast',
+                event: 'awareness',
+                payload: {
+                    data: uint8ArrayToBase64(update),
+                    deviceId
+                }
+            });
+        }
+        catch (e) {
+            debugError('[CRDT Awareness] Error broadcasting update:', e);
+        }
+    };
+    awareness.on('update', onUpdate);
+    cleanup.push(() => awareness.off('update', onUpdate));
+    // Subscribe to channel
+    channel.subscribe((status) => {
+        if (status === 'SUBSCRIBED') {
+            debugLog('[CRDT Awareness] Channel connected for:', docId);
+            // Send initial awareness state
+            const update = awarenessProtocol.encodeAwarenessUpdate(awareness, [doc.clientID]);
+            channel.send({
+                type: 'broadcast',
+                event: 'awareness',
+                payload: {
+                    data: uint8ArrayToBase64(update),
+                    deviceId
+                }
+            });
+        }
+    });
+    // Clean up awareness on window unload
+    const beforeUnload = () => {
+        awarenessProtocol.removeAwarenessStates(awareness, [doc.clientID], 'window-unload');
+    };
+    if (typeof window !== 'undefined') {
+        window.addEventListener('beforeunload', beforeUnload);
+        cleanup.push(() => window.removeEventListener('beforeunload', beforeUnload));
+    }
+    activeAwareness.set(docId, { awareness, channel, cleanup });
+    return awareness;
+}
+/**
+ * Get the awareness instance for a document.
+ *
+ * @param docId - Document/note ID
+ * @returns The Awareness instance if initialized, undefined otherwise
+ */
+export function getAwareness(docId) {
+    return activeAwareness.get(docId)?.awareness;
+}
+/**
+ * Destroy awareness for a document.
+ *
+ * Removes awareness state, closes the broadcast channel, and cleans up listeners.
+ *
+ * @param docId - Document/note ID
+ */
+export async function destroyAwareness(docId) {
+    const entry = activeAwareness.get(docId);
+    if (!entry)
+        return;
+    debugLog('[CRDT Awareness] Destroying for:', docId);
+    // Run cleanup callbacks
+    for (const fn of entry.cleanup) {
+        try {
+            fn();
+        }
+        catch (e) {
+            debugWarn('[CRDT Awareness] Cleanup error:', e);
+        }
+    }
+    // Remove awareness states
+    const doc = getCrdtDoc(docId);
+    if (doc) {
+        awarenessProtocol.removeAwarenessStates(entry.awareness, [doc.clientID], 'destroy');
+    }
+    // Close channel
+    try {
+        await supabase.removeChannel(entry.channel);
+    }
+    catch (e) {
+        debugWarn('[CRDT Awareness] Error removing channel:', e);
+    }
+    entry.awareness.destroy();
+    activeAwareness.delete(docId);
+}
+//# sourceMappingURL=awareness.js.map

package/dist/crdt/awareness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"awareness.js","sourceRoot":"","sources":["../../src/crdt/awareness.ts"],"names":[],"mappings":"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"}

package/dist/crdt/doc.d.ts

@@ -0,0 +1,56 @@
+/**
+ * CRDT Document Lifecycle Management
+ *
+ * Creates, manages, and destroys Yjs Y.Doc instances with y-indexeddb persistence.
+ * The engine fully owns all Yjs and y-indexeddb -- apps never import these directly.
+ */
+import * as Y from 'yjs';
+import { IndexeddbPersistence } from 'y-indexeddb';
+import type { CrdtDocConfig, CrdtDocState } from './types';
+/**
+ * Initialize a CRDT document with local IndexedDB persistence.
+ *
+ * Creates a Y.Doc and attaches IndexeddbPersistence for local durability.
+ * If the document already exists, returns the existing instance.
+ *
+ * @param docId - Unique identifier for the document (typically note ID)
+ * @param config - Optional configuration
+ * @returns The Y.Doc instance
+ */
+export declare function initCrdtDoc(docId: string, config?: CrdtDocConfig): Y.Doc;
+/**
+ * Get an active CRDT document by ID.
+ *
+ * @param docId - Document identifier
+ * @returns The Y.Doc if it exists, undefined otherwise
+ */
+export declare function getCrdtDoc(docId: string): Y.Doc | undefined;
+/**
+ * Wait for a document's IndexedDB persistence to finish syncing.
+ * Resolves immediately if already synced.
+ *
+ * @param docId - Document identifier
+ */
+export declare function waitForCrdtSync(docId: string): Promise<void>;
+/**
+ * Destroy a CRDT document and clean up all resources.
+ *
+ * Closes IndexedDB persistence, runs cleanup callbacks, and removes from active map.
+ *
+ * @param docId - Document identifier
+ */
+export declare function destroyCrdtDoc(docId: string): Promise<void>;
+/**
+ * Get the internal state for a document (used by other CRDT modules).
+ * @internal
+ */
+export declare function _getDocEntry(docId: string): {
+    doc: Y.Doc;
+    persistence: IndexeddbPersistence;
+    state: CrdtDocState;
+} | undefined;
+/**
+ * Get all active document IDs.
+ */
+export declare function getActiveCrdtDocIds(): string[];
+//# sourceMappingURL=doc.d.ts.map

package/dist/crdt/doc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc.d.ts","sourceRoot":"","sources":["../../src/crdt/doc.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAGnD,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAU3D;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,CAAC,CAAC,GAAG,CA6BxE;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,GAAG,SAAS,CAE3D;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBlE;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BjE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM;SA7HL,CAAC,CAAC,GAAG;iBAAe,oBAAoB;WAAS,YAAY;cA+HjG;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,EAAE,CAE9C"}

package/dist/crdt/doc.js

@@ -0,0 +1,130 @@
+/**
+ * CRDT Document Lifecycle Management
+ *
+ * Creates, manages, and destroys Yjs Y.Doc instances with y-indexeddb persistence.
+ * The engine fully owns all Yjs and y-indexeddb -- apps never import these directly.
+ */
+import * as Y from 'yjs';
+import { IndexeddbPersistence } from 'y-indexeddb';
+import { debugLog, debugWarn } from '../debug';
+import { getEngineConfig } from '../config';
+/** Active documents map: docId → { doc, persistence, state } */
+const activeDocs = new Map();
+function getDbName(docId, config) {
+    const prefix = config?.dbPrefix || getEngineConfig().prefix;
+    return `${prefix}_crdt_${docId}`;
+}
+/**
+ * Initialize a CRDT document with local IndexedDB persistence.
+ *
+ * Creates a Y.Doc and attaches IndexeddbPersistence for local durability.
+ * If the document already exists, returns the existing instance.
+ *
+ * @param docId - Unique identifier for the document (typically note ID)
+ * @param config - Optional configuration
+ * @returns The Y.Doc instance
+ */
+export function initCrdtDoc(docId, config) {
+    const existing = activeDocs.get(docId);
+    if (existing) {
+        debugLog('[CRDT] Doc already initialized:', docId);
+        return existing.doc;
+    }
+    debugLog('[CRDT] Initializing doc:', docId);
+    const doc = new Y.Doc();
+    const dbName = getDbName(docId, config);
+    const persistence = new IndexeddbPersistence(dbName, doc);
+    const cleanup = [];
+    const state = {
+        docId,
+        cleanup
+    };
+    // Log when persistence is synced from IndexedDB
+    const onSynced = () => {
+        debugLog('[CRDT] IndexedDB synced for doc:', docId);
+    };
+    persistence.on('synced', onSynced);
+    cleanup.push(() => persistence.off('synced', onSynced));
+    activeDocs.set(docId, { doc, persistence, state });
+    return doc;
+}
+/**
+ * Get an active CRDT document by ID.
+ *
+ * @param docId - Document identifier
+ * @returns The Y.Doc if it exists, undefined otherwise
+ */
+export function getCrdtDoc(docId) {
+    return activeDocs.get(docId)?.doc;
+}
+/**
+ * Wait for a document's IndexedDB persistence to finish syncing.
+ * Resolves immediately if already synced.
+ *
+ * @param docId - Document identifier
+ */
+export async function waitForCrdtSync(docId) {
+    const entry = activeDocs.get(docId);
+    if (!entry) {
+        debugWarn('[CRDT] Cannot wait for sync - doc not initialized:', docId);
+        return;
+    }
+    if (entry.persistence.synced)
+        return;
+    return new Promise((resolve) => {
+        const handler = () => {
+            entry.persistence.off('synced', handler);
+            resolve();
+        };
+        entry.persistence.on('synced', handler);
+    });
+}
+/**
+ * Destroy a CRDT document and clean up all resources.
+ *
+ * Closes IndexedDB persistence, runs cleanup callbacks, and removes from active map.
+ *
+ * @param docId - Document identifier
+ */
+export async function destroyCrdtDoc(docId) {
+    const entry = activeDocs.get(docId);
+    if (!entry) {
+        debugLog('[CRDT] Doc not found for destroy:', docId);
+        return;
+    }
+    debugLog('[CRDT] Destroying doc:', docId);
+    // Run cleanup callbacks (removes event listeners)
+    for (const fn of entry.state.cleanup) {
+        try {
+            fn();
+        }
+        catch (e) {
+            debugWarn('[CRDT] Cleanup error for doc:', docId, e);
+        }
+    }
+    // Close IndexedDB persistence
+    try {
+        await entry.persistence.destroy();
+    }
+    catch (e) {
+        debugWarn('[CRDT] Error closing persistence for doc:', docId, e);
+    }
+    // Destroy the Y.Doc
+    entry.doc.destroy();
+    activeDocs.delete(docId);
+    debugLog('[CRDT] Doc destroyed:', docId);
+}
+/**
+ * Get the internal state for a document (used by other CRDT modules).
+ * @internal
+ */
+export function _getDocEntry(docId) {
+    return activeDocs.get(docId);
+}
+/**
+ * Get all active document IDs.
+ */
+export function getActiveCrdtDocIds() {
+    return Array.from(activeDocs.keys());
+}
+//# sourceMappingURL=doc.js.map

package/dist/crdt/doc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc.js","sourceRoot":"","sources":["../../src/crdt/doc.ts"],"names":[],"mappings":"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"}

package/dist/crdt/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * CRDT Module Barrel Export
+ *
+ * Provides complete Yjs/CRDT management for collaborative editing.
+ * Apps should import everything from this module and never import
+ * yjs or y-indexeddb directly.
+ */
+export { Doc as YDoc, Array as YArray, Map as YMap, Text as YText } from 'yjs';
+export * as Y from 'yjs';
+export { initCrdtDoc, getCrdtDoc, destroyCrdtDoc, waitForCrdtSync, getActiveCrdtDocIds } from './doc';
+export { connectCrdtRealtime, disconnectCrdtRealtime, saveCrdtCheckpoint, loadCrdtFromRemote, getCrdtSyncState, isCrdtRealtimeConnected } from './sync';
+export { initAwareness, getAwareness, destroyAwareness } from './awareness';
+export { Awareness } from 'y-protocols/awareness';
+export { cacheCrdtForOffline, removeCrdtOfflineCache, isCrdtCachedOffline, loadCrdtFromOfflineCache } from './offline';
+//# sourceMappingURL=index.d.ts.map

package/dist/crdt/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/crdt/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,GAAG,IAAI,IAAI,EAAE,KAAK,IAAI,MAAM,EAAE,GAAG,IAAI,IAAI,EAAE,IAAI,IAAI,KAAK,EAAE,MAAM,KAAK,CAAC;AAC/E,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAGzB,OAAO,EACL,WAAW,EACX,UAAU,EACV,cAAc,EACd,eAAe,EACf,mBAAmB,EACpB,MAAM,OAAO,CAAC;AAGf,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,uBAAuB,EACxB,MAAM,QAAQ,CAAC;AAGhB,OAAO,EACL,aAAa,EACb,YAAY,EACZ,gBAAgB,EACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGlD,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACnB,wBAAwB,EACzB,MAAM,WAAW,CAAC"}

package/dist/crdt/index.js

@@ -0,0 +1,20 @@
+/**
+ * CRDT Module Barrel Export
+ *
+ * Provides complete Yjs/CRDT management for collaborative editing.
+ * Apps should import everything from this module and never import
+ * yjs or y-indexeddb directly.
+ */
+// Re-export Y for type access (apps need Y.Array, Y.Map, Y.Text, etc.)
+export { Doc as YDoc, Array as YArray, Map as YMap, Text as YText } from 'yjs';
+export * as Y from 'yjs';
+// Document lifecycle
+export { initCrdtDoc, getCrdtDoc, destroyCrdtDoc, waitForCrdtSync, getActiveCrdtDocIds } from './doc';
+// Realtime sync
+export { connectCrdtRealtime, disconnectCrdtRealtime, saveCrdtCheckpoint, loadCrdtFromRemote, getCrdtSyncState, isCrdtRealtimeConnected } from './sync';
+// Awareness (presence)
+export { initAwareness, getAwareness, destroyAwareness } from './awareness';
+export { Awareness } from 'y-protocols/awareness';
+// Offline cache
+export { cacheCrdtForOffline, removeCrdtOfflineCache, isCrdtCachedOffline, loadCrdtFromOfflineCache } from './offline';
+//# sourceMappingURL=index.js.map

package/dist/crdt/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/crdt/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,uEAAuE;AACvE,OAAO,EAAE,GAAG,IAAI,IAAI,EAAE,KAAK,IAAI,MAAM,EAAE,GAAG,IAAI,IAAI,EAAE,IAAI,IAAI,KAAK,EAAE,MAAM,KAAK,CAAC;AAC/E,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB,qBAAqB;AACrB,OAAO,EACL,WAAW,EACX,UAAU,EACV,cAAc,EACd,eAAe,EACf,mBAAmB,EACpB,MAAM,OAAO,CAAC;AAEf,gBAAgB;AAChB,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,uBAAuB,EACxB,MAAM,QAAQ,CAAC;AAEhB,uBAAuB;AACvB,OAAO,EACL,aAAa,EACb,YAAY,EACZ,gBAAgB,EACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD,gBAAgB;AAChB,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACnB,wBAAwB,EACzB,MAAM,WAAW,CAAC"}

package/dist/crdt/offline.d.ts

@@ -0,0 +1,45 @@
+/**
+ * CRDT Offline Cache Management
+ *
+ * Manages selective offline caching of Yjs document state.
+ * Uses a dedicated IndexedDB store separate from y-indexeddb persistence.
+ *
+ * The active y-indexeddb persistence (from doc.ts) handles documents that are
+ * currently open. This module handles explicit offline download/caching for
+ * documents the user wants available offline even when not actively editing.
+ */
+import * as Y from 'yjs';
+/**
+ * Cache a CRDT document for offline access.
+ *
+ * Serializes the current Yjs state and stores it in IndexedDB.
+ * If the document is currently active, uses its live state.
+ * Otherwise, fetches the state from Supabase.
+ *
+ * @param docId - Document/note ID
+ */
+export declare function cacheCrdtForOffline(docId: string): Promise<void>;
+/**
+ * Remove a document from the offline cache.
+ *
+ * @param docId - Document/note ID
+ */
+export declare function removeCrdtOfflineCache(docId: string): Promise<void>;
+/**
+ * Check if a document is cached for offline access.
+ *
+ * @param docId - Document/note ID
+ * @returns true if the document is cached
+ */
+export declare function isCrdtCachedOffline(docId: string): Promise<boolean>;
+/**
+ * Load a cached CRDT document state from offline storage.
+ *
+ * Creates a new Y.Doc and applies the cached state to it.
+ * The caller is responsible for destroying the returned doc.
+ *
+ * @param docId - Document/note ID
+ * @returns A Y.Doc with the cached state, or null if not cached
+ */
+export declare function loadCrdtFromOfflineCache(docId: string): Promise<Y.Doc | null>;
+//# sourceMappingURL=offline.d.ts.map

package/dist/crdt/offline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"offline.d.ts","sourceRoot":"","sources":["../../src/crdt/offline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAkCzB;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA6DtE;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAmBzE;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAkBzE;AAED;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,CA6BnF"}