@prabhask5/stellar-engine 1.1.18 → 1.2.0

package/dist/crdt/config.js

@@ -0,0 +1,123 @@
+/**
+ * @fileoverview CRDT Configuration Singleton
+ *
+ * Manages the resolved CRDT configuration singleton. The raw {@link CRDTConfig}
+ * (with optional fields) is provided by the consumer via `initEngine({ crdt: ... })`.
+ * This module applies sensible defaults and stores the result as a
+ * {@link ResolvedCRDTConfig} singleton, accessible to all other CRDT modules
+ * via {@link getCRDTConfig}.
+ *
+ * Initialization flow:
+ *   1. Consumer calls `initEngine({ crdt: { ... } })`
+ *   2. `config.ts#initEngine` calls `_initCRDT(rawConfig, prefix)`
+ *   3. This module merges defaults → stores singleton
+ *   4. Other CRDT modules call `getCRDTConfig()` to read the resolved config
+ *
+ * If `initEngine()` is called without a `crdt` field, the singleton remains
+ * `null` and `getCRDTConfig()` throws with a descriptive error message.
+ *
+ * @see {@link ../config.ts} for the `initEngine()` entry point
+ * @see {@link ./types.ts} for the config interfaces
+ */
+// =============================================================================
+//  Default Values
+// =============================================================================
+/**
+ * Default values for all optional CRDT configuration fields.
+ *
+ * These defaults are tuned for a typical collaborative document editor:
+ * - 30s persist interval balances durability vs. Supabase write costs
+ * - 100ms broadcast debounce merges rapid keystrokes without noticeable lag
+ * - 5s local save debounce provides crash recovery with minimal IndexedDB churn
+ * - 50ms cursor debounce keeps presence smooth without flooding the channel
+ * - 250KB chunk threshold stays well below Supabase's ~1MB Broadcast limit
+ */
+const DEFAULTS = {
+    supabaseTable: 'crdt_documents',
+    columns: 'id,page_id,state,state_vector,state_size,device_id,updated_at,created_at',
+    persistIntervalMs: 30000,
+    broadcastDebounceMs: 100,
+    localSaveDebounceMs: 5000,
+    cursorDebounceMs: 50,
+    maxOfflineDocuments: 50,
+    maxBroadcastPayloadBytes: 250000,
+    syncPeerTimeoutMs: 3000,
+    maxReconnectAttempts: 5,
+    reconnectBaseDelayMs: 1000
+};
+// =============================================================================
+//  Module State
+// =============================================================================
+/** The resolved config singleton (set by {@link _initCRDT}). */
+let resolvedConfig = null;
+/** The application prefix (e.g., 'myapp'), used for channel naming. */
+let crdtPrefix = '';
+// =============================================================================
+//  Initialization
+// =============================================================================
+/**
+ * Initialize the CRDT configuration singleton.
+ *
+ * Called internally by {@link ../config.ts#initEngine} when `config.crdt` is
+ * provided. Merges user-provided values with defaults and stores the result.
+ *
+ * @param rawConfig - The user-provided CRDT config (with optional fields).
+ * @param prefix - The application prefix from `SyncEngineConfig.prefix`.
+ * @internal
+ */
+export function _initCRDT(rawConfig, prefix) {
+    crdtPrefix = prefix;
+    resolvedConfig = {
+        supabaseTable: rawConfig.supabaseTable ?? DEFAULTS.supabaseTable,
+        columns: rawConfig.columns ?? DEFAULTS.columns,
+        persistIntervalMs: rawConfig.persistIntervalMs ?? DEFAULTS.persistIntervalMs,
+        broadcastDebounceMs: rawConfig.broadcastDebounceMs ?? DEFAULTS.broadcastDebounceMs,
+        localSaveDebounceMs: rawConfig.localSaveDebounceMs ?? DEFAULTS.localSaveDebounceMs,
+        cursorDebounceMs: rawConfig.cursorDebounceMs ?? DEFAULTS.cursorDebounceMs,
+        maxOfflineDocuments: rawConfig.maxOfflineDocuments ?? DEFAULTS.maxOfflineDocuments,
+        maxBroadcastPayloadBytes: rawConfig.maxBroadcastPayloadBytes ?? DEFAULTS.maxBroadcastPayloadBytes,
+        syncPeerTimeoutMs: rawConfig.syncPeerTimeoutMs ?? DEFAULTS.syncPeerTimeoutMs,
+        maxReconnectAttempts: rawConfig.maxReconnectAttempts ?? DEFAULTS.maxReconnectAttempts,
+        reconnectBaseDelayMs: rawConfig.reconnectBaseDelayMs ?? DEFAULTS.reconnectBaseDelayMs
+    };
+}
+// =============================================================================
+//  Accessors
+// =============================================================================
+/**
+ * Get the resolved CRDT configuration.
+ *
+ * @throws {Error} If CRDT was not configured in `initEngine()`.
+ * @returns The fully resolved {@link ResolvedCRDTConfig} with all defaults applied.
+ */
+export function getCRDTConfig() {
+    if (!resolvedConfig) {
+        throw new Error('CRDT not configured. Add crdt to your initEngine() config.');
+    }
+    return resolvedConfig;
+}
+/**
+ * Get the application prefix for use in channel naming and storage keys.
+ *
+ * @throws {Error} If CRDT was not configured in `initEngine()`.
+ * @returns The prefix string (e.g., `'myapp'`).
+ */
+export function getCRDTPrefix() {
+    if (!resolvedConfig) {
+        throw new Error('CRDT not configured. Add crdt to your initEngine() config.');
+    }
+    return crdtPrefix;
+}
+/**
+ * Check whether the CRDT subsystem has been initialized.
+ *
+ * Unlike {@link getCRDTConfig}, this does not throw — it returns a boolean.
+ * Used by conditional code paths that need to check CRDT availability
+ * without triggering an error (e.g., sign-out cleanup).
+ *
+ * @returns `true` if `_initCRDT()` has been called.
+ */
+export function isCRDTEnabled() {
+    return resolvedConfig !== null;
+}
+//# sourceMappingURL=config.js.map

package/dist/crdt/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/crdt/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,gFAAgF;AAChF,kBAAkB;AAClB,gFAAgF;AAEhF;;;;;;;;;GASG;AACH,MAAM,QAAQ,GAAuB;IACnC,aAAa,EAAE,gBAAgB;IAC/B,OAAO,EAAE,0EAA0E;IACnF,iBAAiB,EAAE,KAAM;IACzB,mBAAmB,EAAE,GAAG;IACxB,mBAAmB,EAAE,IAAK;IAC1B,gBAAgB,EAAE,EAAE;IACpB,mBAAmB,EAAE,EAAE;IACvB,wBAAwB,EAAE,MAAO;IACjC,iBAAiB,EAAE,IAAK;IACxB,oBAAoB,EAAE,CAAC;IACvB,oBAAoB,EAAE,IAAK;CAC5B,CAAC;AAEF,gFAAgF;AAChF,gBAAgB;AAChB,gFAAgF;AAEhF,gEAAgE;AAChE,IAAI,cAAc,GAA8B,IAAI,CAAC;AAErD,uEAAuE;AACvE,IAAI,UAAU,GAAG,EAAE,CAAC;AAEpB,gFAAgF;AAChF,kBAAkB;AAClB,gFAAgF;AAEhF;;;;;;;;;GASG;AACH,MAAM,UAAU,SAAS,CAAC,SAAqB,EAAE,MAAc;IAC7D,UAAU,GAAG,MAAM,CAAC;IACpB,cAAc,GAAG;QACf,aAAa,EAAE,SAAS,CAAC,aAAa,IAAI,QAAQ,CAAC,aAAa;QAChE,OAAO,EAAE,SAAS,CAAC,OAAO,IAAI,QAAQ,CAAC,OAAO;QAC9C,iBAAiB,EAAE,SAAS,CAAC,iBAAiB,IAAI,QAAQ,CAAC,iBAAiB;QAC5E,mBAAmB,EAAE,SAAS,CAAC,mBAAmB,IAAI,QAAQ,CAAC,mBAAmB;QAClF,mBAAmB,EAAE,SAAS,CAAC,mBAAmB,IAAI,QAAQ,CAAC,mBAAmB;QAClF,gBAAgB,EAAE,SAAS,CAAC,gBAAgB,IAAI,QAAQ,CAAC,gBAAgB;QACzE,mBAAmB,EAAE,SAAS,CAAC,mBAAmB,IAAI,QAAQ,CAAC,mBAAmB;QAClF,wBAAwB,EACtB,SAAS,CAAC,wBAAwB,IAAI,QAAQ,CAAC,wBAAwB;QACzE,iBAAiB,EAAE,SAAS,CAAC,iBAAiB,IAAI,QAAQ,CAAC,iBAAiB;QAC5E,oBAAoB,EAAE,SAAS,CAAC,oBAAoB,IAAI,QAAQ,CAAC,oBAAoB;QACrF,oBAAoB,EAAE,SAAS,CAAC,oBAAoB,IAAI,QAAQ,CAAC,oBAAoB;KACtF,CAAC;AACJ,CAAC;AAED,gFAAgF;AAChF,aAAa;AACb,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,UAAU,aAAa;IAC3B,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;IAChF,CAAC;IACD,OAAO,cAAc,CAAC;AACxB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa;IAC3B,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;IAChF,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,cAAc,KAAK,IAAI,CAAC;AACjC,CAAC"}

package/dist/crdt/helpers.d.ts

@@ -0,0 +1,104 @@
+/**
+ * @fileoverview CRDT Document Type Factories and Yjs Re-exports
+ *
+ * Provides convenience factory functions for creating shared data types within
+ * a Yjs document. Consumers use these instead of importing `yjs` directly,
+ * which keeps `yjs` as an internal dependency of the engine.
+ *
+ * Each factory function takes a `Y.Doc` and a type name, and returns the
+ * corresponding shared type instance. If the type already exists in the doc
+ * (e.g., from a previous session or a remote peer), the existing instance is
+ * returned — Yjs shared types are singletons keyed by name within a doc.
+ *
+ * The "block document" factory ({@link createBlockDocument}) sets up a standard
+ * structure for Notion-style block editors: an `XmlFragment` for the content
+ * tree and a `Map` for per-block metadata.
+ *
+ * @see {@link ./provider.ts} for the orchestrator that creates Y.Doc instances
+ * @see {@link ./types.ts} for the TypeScript types
+ *
+ * @example
+ * import { openDocument, createSharedText } from '@prabhask5/stellar-engine/crdt';
+ *
+ * const provider = await openDocument('doc-1', 'page-1');
+ * const title = createSharedText(provider.doc, 'title');
+ * title.insert(0, 'Hello, World!');
+ */
+import * as Y from 'yjs';
+/**
+ * Get or create a shared `Y.Text` within a Yjs document.
+ *
+ * `Y.Text` supports rich text with formatting attributes (bold, italic, etc.)
+ * and is the standard type for collaborative text editors.
+ *
+ * @param doc - The Yjs document instance.
+ * @param name - The shared type name (unique within the document). Default: `'text'`.
+ * @returns The `Y.Text` instance, either existing or newly created.
+ *
+ * @example
+ * const text = createSharedText(doc, 'title');
+ * text.insert(0, 'My Page Title');
+ */
+export declare function createSharedText(doc: Y.Doc, name?: string): Y.Text;
+/**
+ * Get or create a shared `Y.XmlFragment` within a Yjs document.
+ *
+ * `Y.XmlFragment` is the standard container for block-based editors
+ * (Prosemirror, Tiptap, BlockNote). It represents a tree of XML elements
+ * that maps to the editor's document model.
+ *
+ * @param doc - The Yjs document instance.
+ * @param name - The shared type name. Default: `'content'`.
+ * @returns The `Y.XmlFragment` instance.
+ *
+ * @example
+ * const content = createSharedXmlFragment(doc, 'content');
+ * // Use with Tiptap: new Editor({ extensions: [Collaboration.configure({ fragment: content })] })
+ */
+export declare function createSharedXmlFragment(doc: Y.Doc, name?: string): Y.XmlFragment;
+/**
+ * Get or create a shared `Y.Array` within a Yjs document.
+ *
+ * `Y.Array` is a CRDT list type suitable for ordered collections
+ * (e.g., a list of block IDs, kanban columns, or comment threads).
+ *
+ * @param doc - The Yjs document instance.
+ * @param name - The shared type name. Default: `'array'`.
+ * @returns The `Y.Array` instance.
+ */
+export declare function createSharedArray<T>(doc: Y.Doc, name?: string): Y.Array<T>;
+/**
+ * Get or create a shared `Y.Map` within a Yjs document.
+ *
+ * `Y.Map` is a CRDT key-value map suitable for document metadata,
+ * settings, or per-block properties.
+ *
+ * @param doc - The Yjs document instance.
+ * @param name - The shared type name. Default: `'map'`.
+ * @returns The `Y.Map` instance.
+ */
+export declare function createSharedMap<T>(doc: Y.Doc, name?: string): Y.Map<T>;
+/**
+ * Set up a standard "block document" structure within a Yjs document.
+ *
+ * Creates two shared types commonly used by Notion-style block editors:
+ *   - `content` (`Y.XmlFragment`) — The block tree (paragraphs, headings, lists, etc.)
+ *   - `meta` (`Y.Map`) — Per-document metadata (title, icon, cover, properties, etc.)
+ *
+ * This is a convenience function — consumers can also create these types
+ * individually using the other factory functions.
+ *
+ * @param doc - The Yjs document instance.
+ * @returns An object with `content` and `meta` shared types.
+ *
+ * @example
+ * const provider = await openDocument('doc-1', 'page-1');
+ * const { content, meta } = createBlockDocument(provider.doc);
+ * meta.set('title', 'My Page');
+ * // Pass `content` to your block editor's collaboration extension
+ */
+export declare function createBlockDocument(doc: Y.Doc): {
+    content: Y.XmlFragment;
+    meta: Y.Map<unknown>;
+};
+//# sourceMappingURL=helpers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/crdt/helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAMzB;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,IAAI,SAAS,GAAG,CAAC,CAAC,IAAI,CAElE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,IAAI,SAAY,GAAG,CAAC,CAAC,WAAW,CAEnF;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,IAAI,SAAU,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAE3E;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,IAAI,SAAQ,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAErE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,GAAG;IAC/C,OAAO,EAAE,CAAC,CAAC,WAAW,CAAC;IACvB,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;CACtB,CAKA"}

package/dist/crdt/helpers.js

@@ -0,0 +1,116 @@
+/**
+ * @fileoverview CRDT Document Type Factories and Yjs Re-exports
+ *
+ * Provides convenience factory functions for creating shared data types within
+ * a Yjs document. Consumers use these instead of importing `yjs` directly,
+ * which keeps `yjs` as an internal dependency of the engine.
+ *
+ * Each factory function takes a `Y.Doc` and a type name, and returns the
+ * corresponding shared type instance. If the type already exists in the doc
+ * (e.g., from a previous session or a remote peer), the existing instance is
+ * returned — Yjs shared types are singletons keyed by name within a doc.
+ *
+ * The "block document" factory ({@link createBlockDocument}) sets up a standard
+ * structure for Notion-style block editors: an `XmlFragment` for the content
+ * tree and a `Map` for per-block metadata.
+ *
+ * @see {@link ./provider.ts} for the orchestrator that creates Y.Doc instances
+ * @see {@link ./types.ts} for the TypeScript types
+ *
+ * @example
+ * import { openDocument, createSharedText } from '@prabhask5/stellar-engine/crdt';
+ *
+ * const provider = await openDocument('doc-1', 'page-1');
+ * const title = createSharedText(provider.doc, 'title');
+ * title.insert(0, 'Hello, World!');
+ */
+// =============================================================================
+//  Shared Type Factories
+// =============================================================================
+/**
+ * Get or create a shared `Y.Text` within a Yjs document.
+ *
+ * `Y.Text` supports rich text with formatting attributes (bold, italic, etc.)
+ * and is the standard type for collaborative text editors.
+ *
+ * @param doc - The Yjs document instance.
+ * @param name - The shared type name (unique within the document). Default: `'text'`.
+ * @returns The `Y.Text` instance, either existing or newly created.
+ *
+ * @example
+ * const text = createSharedText(doc, 'title');
+ * text.insert(0, 'My Page Title');
+ */
+export function createSharedText(doc, name = 'text') {
+    return doc.getText(name);
+}
+/**
+ * Get or create a shared `Y.XmlFragment` within a Yjs document.
+ *
+ * `Y.XmlFragment` is the standard container for block-based editors
+ * (Prosemirror, Tiptap, BlockNote). It represents a tree of XML elements
+ * that maps to the editor's document model.
+ *
+ * @param doc - The Yjs document instance.
+ * @param name - The shared type name. Default: `'content'`.
+ * @returns The `Y.XmlFragment` instance.
+ *
+ * @example
+ * const content = createSharedXmlFragment(doc, 'content');
+ * // Use with Tiptap: new Editor({ extensions: [Collaboration.configure({ fragment: content })] })
+ */
+export function createSharedXmlFragment(doc, name = 'content') {
+    return doc.getXmlFragment(name);
+}
+/**
+ * Get or create a shared `Y.Array` within a Yjs document.
+ *
+ * `Y.Array` is a CRDT list type suitable for ordered collections
+ * (e.g., a list of block IDs, kanban columns, or comment threads).
+ *
+ * @param doc - The Yjs document instance.
+ * @param name - The shared type name. Default: `'array'`.
+ * @returns The `Y.Array` instance.
+ */
+export function createSharedArray(doc, name = 'array') {
+    return doc.getArray(name);
+}
+/**
+ * Get or create a shared `Y.Map` within a Yjs document.
+ *
+ * `Y.Map` is a CRDT key-value map suitable for document metadata,
+ * settings, or per-block properties.
+ *
+ * @param doc - The Yjs document instance.
+ * @param name - The shared type name. Default: `'map'`.
+ * @returns The `Y.Map` instance.
+ */
+export function createSharedMap(doc, name = 'map') {
+    return doc.getMap(name);
+}
+/**
+ * Set up a standard "block document" structure within a Yjs document.
+ *
+ * Creates two shared types commonly used by Notion-style block editors:
+ *   - `content` (`Y.XmlFragment`) — The block tree (paragraphs, headings, lists, etc.)
+ *   - `meta` (`Y.Map`) — Per-document metadata (title, icon, cover, properties, etc.)
+ *
+ * This is a convenience function — consumers can also create these types
+ * individually using the other factory functions.
+ *
+ * @param doc - The Yjs document instance.
+ * @returns An object with `content` and `meta` shared types.
+ *
+ * @example
+ * const provider = await openDocument('doc-1', 'page-1');
+ * const { content, meta } = createBlockDocument(provider.doc);
+ * meta.set('title', 'My Page');
+ * // Pass `content` to your block editor's collaboration extension
+ */
+export function createBlockDocument(doc) {
+    return {
+        content: doc.getXmlFragment('content'),
+        meta: doc.getMap('meta')
+    };
+}
+//# sourceMappingURL=helpers.js.map

package/dist/crdt/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/crdt/helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,gFAAgF;AAChF,yBAAyB;AACzB,gFAAgF;AAEhF;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAU,EAAE,IAAI,GAAG,MAAM;IACxD,OAAO,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAAU,EAAE,IAAI,GAAG,SAAS;IAClE,OAAO,GAAG,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;AAClC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAI,GAAU,EAAE,IAAI,GAAG,OAAO;IAC7D,OAAO,GAAG,CAAC,QAAQ,CAAI,IAAI,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAI,GAAU,EAAE,IAAI,GAAG,KAAK;IACzD,OAAO,GAAG,CAAC,MAAM,CAAI,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAU;IAI5C,OAAO;QACL,OAAO,EAAE,GAAG,CAAC,cAAc,CAAC,SAAS,CAAC;QACtC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC;KACzB,CAAC;AACJ,CAAC"}

package/dist/crdt/offline.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @fileoverview CRDT Offline Document Management
+ *
+ * Controls which CRDT documents are available for offline access. Offline-enabled
+ * documents have their full Yjs state persisted to IndexedDB, allowing editing
+ * even without network connectivity.
+ *
+ * Key behaviors:
+ *   - {@link enableOffline} — Mark a document for offline access (stores state locally)
+ *   - {@link disableOffline} — Remove a document from offline storage
+ *   - Enforces `maxOfflineDocuments` limit (default: 50)
+ *   - If the document is currently open, saves its current state immediately
+ *   - If not open but online, fetches from Supabase and saves locally
+ *   - If not open and offline, returns an error (can't fetch remote state)
+ *
+ * Non-offline documents opened while offline return `null` from the provider,
+ * signaling to the consumer app that the document is unavailable offline.
+ * Non-offline documents opened while online exist only in memory (no IndexedDB).
+ *
+ * @see {@link ./store.ts} for IndexedDB CRUD and offline queries
+ * @see {@link ./provider.ts} for document lifecycle
+ * @see {@link ./config.ts} for `maxOfflineDocuments` configuration
+ */
+/**
+ * Enable offline access for a CRDT document.
+ *
+ * Persists the document's current Yjs state to IndexedDB so it can be loaded
+ * and edited without network connectivity. If the document is currently open
+ * in a provider, its live state is saved. If not open but online, the state
+ * is fetched from Supabase.
+ *
+ * @param pageId - The page/entity this document belongs to.
+ * @param documentId - The unique document identifier.
+ *
+ * @throws {Error} If the offline document limit has been reached.
+ * @throws {Error} If the document is not open and the device is offline.
+ *
+ * @example
+ * await enableOffline('page-1', 'doc-1');
+ * // Document is now available offline
+ */
+export declare function enableOffline(pageId: string, documentId: string): Promise<void>;
+/**
+ * Disable offline access for a CRDT document.
+ *
+ * Removes the document and all its pending updates from IndexedDB.
+ * If the document is currently open in a provider, it continues to work
+ * in memory but will no longer persist to IndexedDB.
+ *
+ * @param pageId - The page/entity this document belongs to (unused, kept for API consistency).
+ * @param documentId - The document to remove from offline storage.
+ *
+ * @example
+ * await disableOffline('page-1', 'doc-1');
+ * // Document is no longer available offline
+ */
+export declare function disableOffline(_pageId: string, documentId: string): Promise<void>;
+//# 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;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAmBH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA2ErF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGvF"}

package/dist/crdt/offline.js

@@ -0,0 +1,130 @@
+/**
+ * @fileoverview CRDT Offline Document Management
+ *
+ * Controls which CRDT documents are available for offline access. Offline-enabled
+ * documents have their full Yjs state persisted to IndexedDB, allowing editing
+ * even without network connectivity.
+ *
+ * Key behaviors:
+ *   - {@link enableOffline} — Mark a document for offline access (stores state locally)
+ *   - {@link disableOffline} — Remove a document from offline storage
+ *   - Enforces `maxOfflineDocuments` limit (default: 50)
+ *   - If the document is currently open, saves its current state immediately
+ *   - If not open but online, fetches from Supabase and saves locally
+ *   - If not open and offline, returns an error (can't fetch remote state)
+ *
+ * Non-offline documents opened while offline return `null` from the provider,
+ * signaling to the consumer app that the document is unavailable offline.
+ * Non-offline documents opened while online exist only in memory (no IndexedDB).
+ *
+ * @see {@link ./store.ts} for IndexedDB CRUD and offline queries
+ * @see {@link ./provider.ts} for document lifecycle
+ * @see {@link ./config.ts} for `maxOfflineDocuments` configuration
+ */
+import * as Y from 'yjs';
+import { debugLog, debugWarn } from '../debug';
+import { getCRDTConfig } from './config';
+import { getActiveProvider } from './provider';
+import { fetchRemoteState } from './persistence';
+import { saveDocumentState, deleteDocumentState, getOfflineDocumentCount, loadDocumentState } from './store';
+// =============================================================================
+//  Public API
+// =============================================================================
+/**
+ * Enable offline access for a CRDT document.
+ *
+ * Persists the document's current Yjs state to IndexedDB so it can be loaded
+ * and edited without network connectivity. If the document is currently open
+ * in a provider, its live state is saved. If not open but online, the state
+ * is fetched from Supabase.
+ *
+ * @param pageId - The page/entity this document belongs to.
+ * @param documentId - The unique document identifier.
+ *
+ * @throws {Error} If the offline document limit has been reached.
+ * @throws {Error} If the document is not open and the device is offline.
+ *
+ * @example
+ * await enableOffline('page-1', 'doc-1');
+ * // Document is now available offline
+ */
+export async function enableOffline(pageId, documentId) {
+    const config = getCRDTConfig();
+    /* Check if already enabled. */
+    const existing = await loadDocumentState(documentId);
+    if (existing?.offlineEnabled === 1) {
+        debugLog(`[CRDT] Document ${documentId} is already offline-enabled`);
+        return;
+    }
+    /* Enforce max offline documents limit. */
+    const currentCount = await getOfflineDocumentCount();
+    if (currentCount >= config.maxOfflineDocuments) {
+        const msg = `Offline limit reached (${config.maxOfflineDocuments}), cannot enable for ${documentId}`;
+        debugWarn(`[CRDT] ${msg}`);
+        throw new Error(msg);
+    }
+    /* If provider is active, save its current state. */
+    const provider = getActiveProvider(documentId);
+    if (provider) {
+        const state = Y.encodeStateAsUpdate(provider.doc);
+        const stateVector = Y.encodeStateVector(provider.doc);
+        const record = {
+            documentId,
+            pageId,
+            state,
+            stateVector,
+            offlineEnabled: 1,
+            localUpdatedAt: new Date().toISOString(),
+            lastPersistedAt: existing?.lastPersistedAt ?? null,
+            stateSize: state.byteLength
+        };
+        await saveDocumentState(record);
+        debugLog(`[CRDT] Offline enabled for document ${documentId} (${currentCount + 1}/${config.maxOfflineDocuments} offline docs)`);
+        return;
+    }
+    /* Not open — try to fetch from Supabase if online. */
+    if (typeof navigator !== 'undefined' && navigator.onLine) {
+        const remoteState = await fetchRemoteState(pageId);
+        if (remoteState) {
+            /* Create a temporary doc to extract the state vector. */
+            const tempDoc = new Y.Doc();
+            Y.applyUpdate(tempDoc, remoteState);
+            const stateVector = Y.encodeStateVector(tempDoc);
+            tempDoc.destroy();
+            const record = {
+                documentId,
+                pageId,
+                state: remoteState,
+                stateVector,
+                offlineEnabled: 1,
+                localUpdatedAt: new Date().toISOString(),
+                lastPersistedAt: new Date().toISOString(),
+                stateSize: remoteState.byteLength
+            };
+            await saveDocumentState(record);
+            debugLog(`[CRDT] Offline enabled for document ${documentId} (${currentCount + 1}/${config.maxOfflineDocuments} offline docs)`);
+            return;
+        }
+    }
+    /* Offline and not open — can't enable. */
+    throw new Error(`Cannot enable offline for document ${documentId}: not currently open and device is offline.`);
+}
+/**
+ * Disable offline access for a CRDT document.
+ *
+ * Removes the document and all its pending updates from IndexedDB.
+ * If the document is currently open in a provider, it continues to work
+ * in memory but will no longer persist to IndexedDB.
+ *
+ * @param pageId - The page/entity this document belongs to (unused, kept for API consistency).
+ * @param documentId - The document to remove from offline storage.
+ *
+ * @example
+ * await disableOffline('page-1', 'doc-1');
+ * // Document is no longer available offline
+ */
+export async function disableOffline(_pageId, documentId) {
+    await deleteDocumentState(documentId);
+    debugLog(`[CRDT] Offline disabled for document ${documentId}`);
+}
+//# sourceMappingURL=offline.js.map

package/dist/crdt/offline.js.map

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

package/dist/crdt/persistence.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @fileoverview CRDT Supabase Persistence
+ *
+ * Handles durable persistence of Yjs document state to the Supabase
+ * `crdt_documents` table. This is the long-term storage layer — the
+ * "source of truth" that survives device loss, browser data clearing,
+ * and cross-device sync.
+ *
+ * Key behaviors:
+ *   - {@link persistDocument} — Upserts full Yjs state to Supabase
+ *   - {@link persistAllDirty} — Persists all active dirty documents
+ *   - {@link fetchRemoteState} — Fetches latest state for initial load / sync
+ *   - Binary state is base64-encoded for Supabase REST transport
+ *   - Skips unchanged documents (compares state vectors)
+ *   - Updates `lastPersistedAt` in IndexedDB on success
+ *   - Clears pending updates after successful persist
+ *
+ * Timing:
+ *   - Periodic persist: every `persistIntervalMs` (default 30s)
+ *   - On document close (if dirty and online)
+ *   - On offline → online reconnection (immediate)
+ *
+ * @see {@link ./provider.ts} for the timer that triggers periodic persists
+ * @see {@link ./store.ts} for IndexedDB operations
+ * @see {@link ./config.ts} for timing configuration
+ */
+import * as Y from 'yjs';
+/**
+ * Persist a Yjs document's full state to Supabase.
+ *
+ * Performs an upsert: if a row for this `page_id` already exists, it is
+ * updated; otherwise a new row is created. The upsert key is `page_id`
+ * (unique per user via RLS).
+ *
+ * On success:
+ *   - Clears `crdtPendingUpdates` for this document in IndexedDB
+ *   - Updates `lastPersistedAt` in the local `crdtDocuments` record
+ *
+ * @param documentId - The document identifier (for logging and IndexedDB updates).
+ * @param doc - The Yjs document to persist.
+ *
+ * @throws {Error} If the Supabase upsert fails.
+ */
+export declare function persistDocument(documentId: string, doc: Y.Doc): Promise<void>;
+/**
+ * Persist all active dirty documents to Supabase.
+ *
+ * Iterates all active providers, checks if they are dirty, and persists
+ * each one. Errors are caught per-document to avoid one failure blocking others.
+ *
+ * Useful as a manual "save all" action or for pre-close cleanup.
+ */
+export declare function persistAllDirty(): Promise<void>;
+/**
+ * Fetch the latest CRDT document state from Supabase by page ID.
+ *
+ * Used during `openDocument` when no local state exists and the device is
+ * online. Returns the raw Yjs binary state ready to be applied via
+ * `Y.applyUpdate(doc, state)`.
+ *
+ * @param pageId - The page/entity ID to fetch the document for.
+ * @returns The Yjs state as a `Uint8Array`, or `null` if no document exists.
+ */
+export declare function fetchRemoteState(pageId: string): Promise<Uint8Array | null>;
+//# sourceMappingURL=persistence.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../src/crdt/persistence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAuCzB;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CA2CnF;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAqBrD;AAMD;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAqBjF"}