@abraca/dabra 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -299,10 +299,16 @@ interface AbracadabraProviderConfiguration extends Omit<HocuspocusProviderConfig
  *     own AbracadabraProvider instances sharing the same WebSocket connection.
  *
  *  2. Offline-first – persists CRDT updates to IndexedDB so they survive
- *     page reloads and network outages.  On reconnect, pending updates are
- *     flushed before resuming normal sync.
+ *     page reloads and network outages.  On startup, the last saved document
+ *     snapshot is applied immediately so the UI is usable without a server
+ *     connection.  On reconnect, pending updates are flushed and a fresh
+ *     snapshot is saved.
  *
- *  3. Permission snapshotting – stores the resolved role locally so the UI
+ *  3. Server-scoped storage – the IndexedDB database is keyed by server
+ *     hostname + docId, preventing cross-server data contamination when the
+ *     same docId is used on multiple servers.
+ *
+ *  4. Permission snapshotting – stores the resolved role locally so the UI
  *     can gate write operations without a network round-trip.  Role is
  *     refreshed from the server on every reconnect.
  */
@@ -315,7 +321,30 @@ declare class AbracadabraProvider extends HocuspocusProvider {
   private subdocLoading;
   private abracadabraConfig;
   private readonly boundHandleYSubdocsChange;
+  /**
+   * Resolves once the document has been pre-populated from the local
+   * IndexedDB snapshot (if one exists).  Await this before rendering UI
+   * that depends on the document content — it resolves immediately when
+   * the offline store is disabled or when no snapshot has been saved yet.
+   */
+  readonly ready: Promise<void>;
   constructor(configuration: AbracadabraProviderConfiguration);
+  /**
+   * Extract the server hostname from the provider configuration.
+   * Used to namespace the IndexedDB key so docs from different servers
+   * never share the same database.
+   */
+  private static deriveServerOrigin;
+  /**
+   * Load the stored document snapshot (and any pending local edits) from
+   * IndexedDB and apply them to the Y.Doc so the UI can render without a
+   * server connection.
+   *
+   * Uses `this.offlineStore` as the Y.js update origin so that
+   * `documentUpdateHandler` ignores these replayed updates and does not
+   * attempt to re-persist or re-send them.
+   */
+  private _initFromOfflineStore;
   authenticatedHandler(scope: string): void;
   /**
    * Override sendToken to send a pubkey-only identity declaration instead of a
@@ -361,11 +390,21 @@ declare class AbracadabraProvider extends HocuspocusProvider {
   /**
    * Override to persist every local update to IndexedDB before sending it
    * over the wire, ensuring no work is lost during connection outages.
+   *
+   * Updates applied by the server (origin === this) and updates replayed
+   * from the offline store (origin === this.offlineStore) are both skipped
+   * to avoid loops.
    */
   documentUpdateHandler(update: Uint8Array, origin: unknown): void;
   /**
-   * After reconnect + sync, flush any updates that were generated while
-   * offline, then flush any queued subdoc registrations.
+   * After reconnect + sync:
+   *  1. Flush any updates that were generated while offline.
+   *  2. Flush any queued subdoc registrations.
+   *  3. Save a fresh full document snapshot for the next offline session.
+   *
+   * Uses a local `store` reference captured at the start so that a concurrent
+   * `destroy()` call setting `offlineStore = null` does not cause null-ref
+   * errors across async await boundaries.
    */
   private flushPendingUpdates;
   get isConnected(): boolean;
@@ -864,8 +903,12 @@ declare class HocuspocusProvider extends EventEmitter {
  *  - Store the last-known state vector for fast reconnect diffs.
  *  - Store a permission snapshot so the UI can gate writes without a network round-trip.
  *  - Queue subdoc registration events created while offline.
+ *  - Store a full document snapshot so the app can load content without a server connection.
  *
  * Falls back to a silent no-op when IndexedDB is unavailable (e.g. SSR / Node.js).
+ *
+ * Database key is scoped by server origin to prevent cross-server data contamination
+ * when the same docId is used on multiple servers.
  */
 interface PendingSubdoc {
   childId: string;
@@ -873,13 +916,28 @@ interface PendingSubdoc {
   createdAt: number;
 }
 declare class OfflineStore {
-  private docId;
+  private storeKey;
   private db;
-  constructor(docId: string);
+  /**
+   * @param docId       The document UUID.
+   * @param serverOrigin  Hostname of the server (e.g. "abra.cou.sh").
+   *                    When provided the IndexedDB database is namespaced
+   *                    per-server, preventing cross-server data contamination.
+   */
+  constructor(docId: string, serverOrigin?: string);
   private getDb;
   persistUpdate(update: Uint8Array): Promise<void>;
   getPendingUpdates(): Promise<Uint8Array[]>;
   clearPendingUpdates(): Promise<void>;
+  /**
+   * Persist a full Y.js state snapshot (Y.encodeStateAsUpdate output).
+   * Replaces any previously stored snapshot.
+   */
+  saveDocSnapshot(snapshot: Uint8Array): Promise<void>;
+  /**
+   * Retrieve the stored full document snapshot, or null if none exists.
+   */
+  getDocSnapshot(): Promise<Uint8Array | null>;
   getStateVector(): Promise<Uint8Array | null>;
   saveStateVector(sv: Uint8Array): Promise<void>;
   getPermissionSnapshot(): Promise<string | null>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abraca/dabra",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "abracadabra provider",
   "keywords": [
     "abracadabra",

package/src/AbracadabraProvider.ts

@@ -74,10 +74,16 @@ function isValidDocId(id: string): boolean {
  *     own AbracadabraProvider instances sharing the same WebSocket connection.
  *
  *  2. Offline-first – persists CRDT updates to IndexedDB so they survive
- *     page reloads and network outages.  On reconnect, pending updates are
- *     flushed before resuming normal sync.
+ *     page reloads and network outages.  On startup, the last saved document
+ *     snapshot is applied immediately so the UI is usable without a server
+ *     connection.  On reconnect, pending updates are flushed and a fresh
+ *     snapshot is saved.
  *
- *  3. Permission snapshotting – stores the resolved role locally so the UI
+ *  3. Server-scoped storage – the IndexedDB database is keyed by server
+ *     hostname + docId, preventing cross-server data contamination when the
+ *     same docId is used on multiple servers.
+ *
+ *  4. Permission snapshotting – stores the resolved role locally so the UI
  *     can gate write operations without a network round-trip.  Role is
  *     refreshed from the server on every reconnect.
  */
@@ -94,6 +100,14 @@ export class AbracadabraProvider extends HocuspocusProvider {
 
 	private readonly boundHandleYSubdocsChange = this.handleYSubdocsChange.bind(this);
 
+	/**
+	 * Resolves once the document has been pre-populated from the local
+	 * IndexedDB snapshot (if one exists).  Await this before rendering UI
+	 * that depends on the document content — it resolves immediately when
+	 * the offline store is disabled or when no snapshot has been saved yet.
+	 */
+	public readonly ready: Promise<void>;
+
 	constructor(configuration: AbracadabraProviderConfiguration) {
 		// Derive URL and token from client when not explicitly set.
 		const resolved = { ...configuration } as HocuspocusProviderConfiguration;
@@ -113,9 +127,10 @@ export class AbracadabraProvider extends HocuspocusProvider {
 		this.abracadabraConfig = configuration;
 		this.subdocLoading = configuration.subdocLoading ?? "lazy";
 
+		const serverOrigin = AbracadabraProvider.deriveServerOrigin(configuration, client);
 		this.offlineStore = configuration.disableOfflineStore
 			? null
-			: new OfflineStore(configuration.name);
+			: new OfflineStore(configuration.name, serverOrigin);
 
 		this.on(
 			"subdocRegistered",
@@ -131,6 +146,57 @@ export class AbracadabraProvider extends HocuspocusProvider {
 
 		// Restore permission snapshot while offline.
 		this.restorePermissionSnapshot();
+
+		// Pre-populate the Y.Doc from the local snapshot so the UI works offline.
+		this.ready = this._initFromOfflineStore();
+	}
+
+	// ── Server origin derivation ──────────────────────────────────────────────
+
+	/**
+	 * Extract the server hostname from the provider configuration.
+	 * Used to namespace the IndexedDB key so docs from different servers
+	 * never share the same database.
+	 */
+	private static deriveServerOrigin(
+		config: AbracadabraProviderConfiguration,
+		client: AbracadabraClient | null,
+	): string | undefined {
+		try {
+			const url =
+				config.url ??
+				(config.websocketProvider as HocuspocusProviderWebsocket | undefined)?.url ??
+				client?.wsUrl;
+			if (url) return new URL(url).hostname;
+		} catch {
+			// Malformed URL — fall back to no scoping
+		}
+		return undefined;
+	}
+
+	// ── Offline-first initialisation ──────────────────────────────────────────
+
+	/**
+	 * Load the stored document snapshot (and any pending local edits) from
+	 * IndexedDB and apply them to the Y.Doc so the UI can render without a
+	 * server connection.
+	 *
+	 * Uses `this.offlineStore` as the Y.js update origin so that
+	 * `documentUpdateHandler` ignores these replayed updates and does not
+	 * attempt to re-persist or re-send them.
+	 */
+	private async _initFromOfflineStore(): Promise<void> {
+		if (!this.offlineStore) return;
+
+		const snapshot = await this.offlineStore.getDocSnapshot().catch(() => null);
+		if (snapshot) {
+			Y.applyUpdate(this.document, snapshot, this.offlineStore);
+		}
+
+		const pending = await this.offlineStore.getPendingUpdates().catch(() => []);
+		for (const update of pending) {
+			Y.applyUpdate(this.document, update, this.offlineStore);
+		}
 	}
 
 	// ── Auth / permission snapshot ────────────────────────────────────────────
@@ -351,23 +417,29 @@ export class AbracadabraProvider extends HocuspocusProvider {
 	private async _doLoadChild(childId: string): Promise<AbracadabraProvider> {
 		const childDoc = new Y.Doc({ guid: childId });
 
-		// Notify the server that this child belongs to the parent document and
-		// wait for server confirmation before opening the child WebSocket.
-		// Without waiting, the child's SyncStep1 may race against subdoc
-		// creation and get a NotFound error on first sync.
-		await new Promise<void>((resolve) => {
-			const onRegistered = ({ childId: cid }: onSubdocRegisteredParameters) => {
-				if (cid === childId) {
-					this.off("subdocRegistered", onRegistered);
-					resolve();
-				}
-			};
-			this.on("subdocRegistered", onRegistered);
+		if (this.isConnected) {
+			// Online: notify the server that this child belongs to the parent and
+			// wait for server confirmation before opening the child WebSocket.
+			// Without waiting, the child's SyncStep1 may race against subdoc
+			// creation and get a NotFound error on first sync.
+			await new Promise<void>((resolve) => {
+				const onRegistered = ({ childId: cid }: onSubdocRegisteredParameters) => {
+					if (cid === childId) {
+						this.off("subdocRegistered", onRegistered);
+						resolve();
+					}
+				};
+				this.on("subdocRegistered", onRegistered);
+				this.registerSubdoc(childDoc);
+				// Fallback: don't block forever if the server is slow or the
+				// doc was already registered in a previous session.
+				setTimeout(resolve, 3000);
+			});
+		} else {
+			// Offline: queue the registration for replay on reconnect and proceed
+			// immediately so the child provider can populate from its local store.
 			this.registerSubdoc(childDoc);
-			// Fallback: don't block forever if the server is slow or the
-			// doc was already registered in a previous session.
-			setTimeout(resolve, 3000);
-		});
+		}
 
 		// Each child gets its own WebSocket connection.  Omitting
 		// websocketProvider lets HocuspocusProvider create one automatically
@@ -409,9 +481,18 @@ export class AbracadabraProvider extends HocuspocusProvider {
 	/**
 	 * Override to persist every local update to IndexedDB before sending it
 	 * over the wire, ensuring no work is lost during connection outages.
+	 *
+	 * Updates applied by the server (origin === this) and updates replayed
+	 * from the offline store (origin === this.offlineStore) are both skipped
+	 * to avoid loops.
 	 */
 	override documentUpdateHandler(update: Uint8Array, origin: unknown) {
 		if (origin === this) return;
+		// Only skip when the store exists AND origin matches it.
+		// Without the null-guard, a null offlineStore would match any update
+		// with origin=null (the default for user transactions), silently
+		// dropping all local writes when disableOfflineStore is true.
+		if (this.offlineStore !== null && origin === this.offlineStore) return;
 
 		// Persist locally first (fire-and-forget; errors are non-fatal).
 		this.offlineStore?.persistUpdate(update).catch(() => null);
@@ -420,13 +501,20 @@ export class AbracadabraProvider extends HocuspocusProvider {
 	}
 
 	/**
-	 * After reconnect + sync, flush any updates that were generated while
-	 * offline, then flush any queued subdoc registrations.
+	 * After reconnect + sync:
+	 *  1. Flush any updates that were generated while offline.
+	 *  2. Flush any queued subdoc registrations.
+	 *  3. Save a fresh full document snapshot for the next offline session.
+	 *
+	 * Uses a local `store` reference captured at the start so that a concurrent
+	 * `destroy()` call setting `offlineStore = null` does not cause null-ref
+	 * errors across async await boundaries.
 	 */
 	private async flushPendingUpdates() {
-		if (!this.offlineStore) return;
+		const store = this.offlineStore;
+		if (!store) return;
 
-		const updates = await this.offlineStore.getPendingUpdates();
+		const updates = await store.getPendingUpdates();
 		if (updates.length > 0) {
 			for (const update of updates) {
 				this.send(UpdateMessage, {
@@ -434,16 +522,20 @@ export class AbracadabraProvider extends HocuspocusProvider {
 					documentName: this.configuration.name,
 				});
 			}
-			await this.offlineStore.clearPendingUpdates();
+			await store.clearPendingUpdates();
 		}
 
-		const pendingSubdocs = await this.offlineStore.getPendingSubdocs();
+		const pendingSubdocs = await store.getPendingSubdocs();
 		for (const { childId } of pendingSubdocs) {
 			this.send(SubdocMessage, {
 				documentName: this.configuration.name,
 				childDocumentName: childId,
 			} as any);
 		}
+
+		// Snapshot the current merged state so the next offline load sees it.
+		const snapshot = Y.encodeStateAsUpdate(this.document);
+		await store.saveDocSnapshot(snapshot).catch(() => null);
 	}
 
 	get isConnected(): boolean {

package/src/OfflineStore.ts

@@ -6,8 +6,12 @@
  *  - Store the last-known state vector for fast reconnect diffs.
  *  - Store a permission snapshot so the UI can gate writes without a network round-trip.
  *  - Queue subdoc registration events created while offline.
+ *  - Store a full document snapshot so the app can load content without a server connection.
  *
  * Falls back to a silent no-op when IndexedDB is unavailable (e.g. SSR / Node.js).
+ *
+ * Database key is scoped by server origin to prevent cross-server data contamination
+ * when the same docId is used on multiple servers.
  */
 
 export interface PendingSubdoc {
@@ -16,15 +20,15 @@ export interface PendingSubdoc {
 	createdAt: number;
 }
 
-const DB_VERSION = 1;
+const DB_VERSION = 2;
 
 function idbAvailable(): boolean {
 	return typeof globalThis !== "undefined" && "indexedDB" in globalThis;
 }
 
-function openDb(docId: string): Promise<IDBDatabase> {
+function openDb(storeKey: string): Promise<IDBDatabase> {
 	return new Promise((resolve, reject) => {
-		const req = globalThis.indexedDB.open(`abracadabra:${docId}`, DB_VERSION);
+		const req = globalThis.indexedDB.open(`abracadabra:${storeKey}`, DB_VERSION);
 
 		req.onupgradeneeded = (event) => {
 			const db = (event.target as IDBOpenDBRequest).result;
@@ -38,6 +42,10 @@ function openDb(docId: string): Promise<IDBDatabase> {
 			if (!db.objectStoreNames.contains("subdoc_queue")) {
 				db.createObjectStore("subdoc_queue", { keyPath: "childId" });
 			}
+			// v2: full document snapshot store
+			if (!db.objectStoreNames.contains("doc_state")) {
+				db.createObjectStore("doc_state");
+			}
 		};
 
 		req.onsuccess = () => resolve(req.result);
@@ -56,22 +64,28 @@ function txPromise<T>(
 }
 
 export class OfflineStore {
-	private docId: string;
+	private storeKey: string;
 	private db: IDBDatabase | null = null;
 
-	constructor(docId: string) {
-		this.docId = docId;
+	/**
+	 * @param docId       The document UUID.
+	 * @param serverOrigin  Hostname of the server (e.g. "abra.cou.sh").
+	 *                    When provided the IndexedDB database is namespaced
+	 *                    per-server, preventing cross-server data contamination.
+	 */
+	constructor(docId: string, serverOrigin?: string) {
+		this.storeKey = serverOrigin ? `${serverOrigin}/${docId}` : docId;
 	}
 
 	private async getDb(): Promise<IDBDatabase | null> {
 		if (!idbAvailable()) return null;
 		if (!this.db) {
-			this.db = await openDb(this.docId).catch(() => null);
+			this.db = await openDb(this.storeKey).catch(() => null);
 		}
 		return this.db;
 	}
 
-	// ── Updates ─────────────────────────────────────────────────────────────
+	// ── Pending (unsynced) updates ────────────────────────────────────────────
 
 	async persistUpdate(update: Uint8Array): Promise<void> {
 		const db = await this.getDb();
@@ -100,6 +114,36 @@ export class OfflineStore {
 		await txPromise(tx.objectStore("updates"), tx.objectStore("updates").clear());
 	}
 
+	// ── Full document snapshot ────────────────────────────────────────────────
+
+	/**
+	 * Persist a full Y.js state snapshot (Y.encodeStateAsUpdate output).
+	 * Replaces any previously stored snapshot.
+	 */
+	async saveDocSnapshot(snapshot: Uint8Array): Promise<void> {
+		const db = await this.getDb();
+		if (!db) return;
+		const tx = db.transaction("doc_state", "readwrite");
+		await txPromise(
+			tx.objectStore("doc_state"),
+			tx.objectStore("doc_state").put(snapshot, "snapshot"),
+		);
+	}
+
+	/**
+	 * Retrieve the stored full document snapshot, or null if none exists.
+	 */
+	async getDocSnapshot(): Promise<Uint8Array | null> {
+		const db = await this.getDb();
+		if (!db) return null;
+		const tx = db.transaction("doc_state", "readonly");
+		const result = await txPromise<Uint8Array | undefined>(
+			tx.objectStore("doc_state"),
+			tx.objectStore("doc_state").get("snapshot"),
+		);
+		return result ?? null;
+	}
+
 	// ── State vector ─────────────────────────────────────────────────────────
 
 	async getStateVector(): Promise<Uint8Array | null> {