hyperbook 0.84.3 → 0.84.5

package/dist/assets/cloud.js

@@ -1,8 +1,20 @@
+/// <reference path="./hyperbook.types.js" />
 window.hyperbook = window.hyperbook || {};
-window.hyperbook.cloud = (function () {
+
+/**
+ * Cloud sync integration for hyperbook store data.
+ * Handles authentication, event-based sync, and snapshot sync.
+ * @type {HyperbookCloud}
+ * @memberof hyperbook
+ * @see hyperbook.store
+ * @see hyperbook.i18n
+ */
+hyperbook.cloud = (function () {
   // ===== Cloud Integration =====
   const AUTH_TOKEN_KEY = "hyperbook_auth_token";
   const AUTH_USER_KEY = "hyperbook_auth_user";
+  const LAST_EVENT_ID_KEY = "hyperbook_last_event_id";
+  const EVENT_BATCH_MAX_SIZE = 512 * 1024; // 512KB
   let isLoadingFromCloud = false;
   let syncManager = null;
 
@@ -41,7 +53,6 @@ window.hyperbook.cloud = (function () {
       this.maxWaitTime = options.maxWaitTime || 10000;
       this.minSaveInterval = options.minSaveInterval || 1000;
 
-      this.isDirty = false;
       this.lastSaveTime = 0;
       this.lastChangeTime = 0;
       this.debounceTimer = null;
@@ -50,110 +61,25 @@ window.hyperbook.cloud = (function () {
       this.saveMutex = new Mutex();
       this.retryCount = 0;
 
-      this.dirtyStores = new Set();
+      this.pendingEvents = [];
+      this.lastEventId = parseInt(
+        localStorage.getItem(LAST_EVENT_ID_KEY) || "0",
+        10,
+      );
 
       this.offlineQueue = [];
       this.isOnline = navigator.onLine;
 
-      // Snapshots for external DB polling
-      this.externalDBs = options.externalDBs || [];
-      this.externalSnapshots = {};
-      this.pollInterval = options.pollInterval || 5000;
-      this.pollTimer = null;
-
       this.setupEventListeners();
     }
 
-    /**
-     * Get a fingerprint of an external DB by hashing all row data.
-     */
-    _snapshotExternalDB(dbName) {
-      return new Promise((resolve) => {
-        const request = indexedDB.open(dbName);
-        request.onerror = () => resolve(null);
-        request.onsuccess = (event) => {
-          const db = event.target.result;
-          const storeNames = Array.from(db.objectStoreNames);
-          if (storeNames.length === 0) {
-            db.close();
-            resolve(null);
-            return;
-          }
-
-          const parts = [];
-          const tx = db.transaction(storeNames, "readonly");
-          let pending = storeNames.length;
-          storeNames.forEach((name) => {
-            const rows = [];
-            const cursorReq = tx.objectStore(name).openCursor();
-            cursorReq.onsuccess = (e) => {
-              const cursor = e.target.result;
-              if (cursor) {
-                rows.push(JSON.stringify(cursor.value));
-                cursor.continue();
-              } else {
-                parts.push(name + ":" + rows.join(","));
-                pending--;
-                if (pending === 0) {
-                  db.close();
-                  resolve(parts.join("|"));
-                }
-              }
-            };
-            cursorReq.onerror = () => {
-              pending--;
-              if (pending === 0) {
-                db.close();
-                resolve(parts.join("|"));
-              }
-            };
-          });
-        };
-      });
-    }
-
-    /**
-     * Take initial snapshots and start polling external DBs for changes.
-     */
-    async startPolling() {
-      for (const dbName of this.externalDBs) {
-        this.externalSnapshots[dbName] = await this._snapshotExternalDB(dbName);
-      }
-      this.pollTimer = setInterval(
-        () => this._pollExternalDBs(),
-        this.pollInterval,
-      );
-    }
-
-    /**
-     * Stop polling external DBs.
-     */
-    stopPolling() {
-      if (this.pollTimer) {
-        clearInterval(this.pollTimer);
-        this.pollTimer = null;
-      }
-    }
-
-    async _pollExternalDBs() {
-      if (isLoadingFromCloud || this.saveInProgress) return;
-      for (const dbName of this.externalDBs) {
-        const current = await this._snapshotExternalDB(dbName);
-        const prev = this.externalSnapshots[dbName];
-
-        if (current !== prev) {
-          this.externalSnapshots[dbName] = current;
-          this.markDirty(dbName);
-        }
-      }
+    get isDirty() {
+      return this.pendingEvents.length > 0;
     }
 
-    markDirty(storeName = null) {
+    addEvent(event) {
       if (isLoadingFromCloud || isReadOnlyMode()) return;
-      if (storeName) {
-        this.dirtyStores.add(storeName);
-      }
-      this.isDirty = true;
+      this.pendingEvents.push(event);
       this.lastChangeTime = Date.now();
       this.updateUI("unsaved");
       this.scheduleSave();
@@ -196,24 +122,46 @@ window.hyperbook.cloud = (function () {
         this.updateUI("saving");
 
         try {
-          const dataToSave = await this.exportStores();
+          // Take a snapshot of pending events
+          const eventsToSend = this.pendingEvents.slice();
+          const serialized = JSON.stringify(eventsToSend);
 
           if (!this.isOnline) {
             this.offlineQueue.push({
-              data: dataToSave,
+              events: eventsToSend,
+              afterEventId: this.lastEventId,
               timestamp: Date.now(),
             });
+            this.pendingEvents = [];
             this.updateUI("offline-queued");
             return;
           }
 
-          await apiRequest(`/api/store/${HYPERBOOK_CLOUD.id}`, {
-            method: "POST",
-            body: JSON.stringify({ data: dataToSave }),
-          });
+          let result;
+
+          if (serialized.length > EVENT_BATCH_MAX_SIZE) {
+            // Large batch — fall back to full snapshot
+            result = await this.sendSnapshot();
+          } else {
+            // Normal path — send events
+            result = await this.sendEvents(eventsToSend);
+          }
 
-          this.isDirty = false;
-          this.dirtyStores.clear();
+          if (result.conflict) {
+            // 409 — stale state, re-fetch
+            console.log("⚠ Stale state detected, re-fetching from cloud...");
+            await loadFromCloud();
+            this.pendingEvents = [];
+            window.location.reload();
+            return;
+          }
+
+          this.pendingEvents = [];
+          this.lastEventId = result.lastEventId;
+          localStorage.setItem(
+            LAST_EVENT_ID_KEY,
+            String(this.lastEventId),
+          );
           this.lastSaveTime = Date.now();
           this.retryCount = 0;
           this.updateUI("saved");
@@ -228,19 +176,46 @@ window.hyperbook.cloud = (function () {
       });
     }
 
-    async exportStores() {
-      const hyperbookExport = await store.export({ prettyJson: false });
-      const sqlIdeExport = await exportExternalDB("SQL-IDE");
-      const learnJExport = await exportExternalDB("LearnJ");
-      return {
-        version: 1,
-        origin: window.location.origin,
-        data: {
-          hyperbook: JSON.parse(await hyperbookExport.text()),
-          sqlIde: sqlIdeExport || {},
-          learnJ: learnJExport || {},
+    async sendEvents(events, afterEventId) {
+      var effectiveAfterId = afterEventId !== undefined ? afterEventId : this.lastEventId;
+      try {
+        const data = await apiRequest(
+          `/api/store/${HYPERBOOK_CLOUD.id}/events`,
+          {
+            method: "POST",
+            body: JSON.stringify({
+              events: events,
+              afterEventId: effectiveAfterId,
+            }),
+          },
+        );
+        return { lastEventId: data.lastEventId, conflict: false };
+      } catch (error) {
+        if (error.status === 409) {
+          return { conflict: true };
+        }
+        throw error;
+      }
+    }
+
+    async sendSnapshot() {
+      const storeExport = await hyperbook.store.db.export({ prettyJson: false });
+      const exportData = JSON.parse(await storeExport.text());
+
+      const data = await apiRequest(
+        `/api/store/${HYPERBOOK_CLOUD.id}/snapshot`,
+        {
+          method: "POST",
+          body: JSON.stringify({
+            data: {
+              version: 1,
+              origin: window.location.origin,
+              data: { hyperbook: exportData },
+            },
+          }),
         },
-      };
+      );
+      return { lastEventId: data.lastEventId, conflict: false };
     }
 
     scheduleRetry() {
@@ -272,7 +247,6 @@ window.hyperbook.cloud = (function () {
 
       window.addEventListener("beforeunload", (e) => {
         if (this.isDirty) {
-          this.performSave("unload");
           e.preventDefault();
           e.returnValue = "";
         }
@@ -289,21 +263,38 @@ window.hyperbook.cloud = (function () {
       if (this.offlineQueue.length === 0) return;
 
       console.log(`Processing ${this.offlineQueue.length} queued saves...`);
-      this.offlineQueue.sort((a, b) => a.timestamp - b.timestamp);
 
-      // Only send the latest queued save
-      const latest = this.offlineQueue[this.offlineQueue.length - 1];
-      try {
-        await apiRequest(`/api/store/${HYPERBOOK_CLOUD.id}`, {
-          method: "POST",
-          body: JSON.stringify({ data: latest.data }),
-        });
-        this.offlineQueue = [];
-        this.lastSaveTime = Date.now();
-        console.log("✓ Offline queue processed");
-      } catch (error) {
-        console.error("Failed to process offline queue:", error);
+      // Send queued events in order
+      for (let i = 0; i < this.offlineQueue.length; i++) {
+        const queued = this.offlineQueue[i];
+        try {
+          const result = await this.sendEvents(queued.events, queued.afterEventId);
+
+          if (result.conflict) {
+            // Conflict — discard remaining queue, re-fetch
+            console.log("⚠ Offline queue conflict, re-fetching...");
+            this.offlineQueue = [];
+            await loadFromCloud();
+            window.location.reload();
+            return;
+          }
+
+          this.lastEventId = result.lastEventId;
+          localStorage.setItem(
+            LAST_EVENT_ID_KEY,
+            String(this.lastEventId),
+          );
+        } catch (error) {
+          console.error("Failed to process offline queue:", error);
+          // Keep remaining items in queue
+          this.offlineQueue = this.offlineQueue.slice(i);
+          return;
+        }
       }
+
+      this.offlineQueue = [];
+      this.lastSaveTime = Date.now();
+      console.log("✓ Offline queue processed");
     }
 
     clearTimers() {
@@ -327,16 +318,31 @@ window.hyperbook.cloud = (function () {
     }
 
     async manualSave() {
-      this.isDirty = true;
+      if (this.pendingEvents.length === 0) {
+        // No pending events — send full snapshot
+        this.clearTimers();
+        try {
+          this.updateUI("saving");
+          const result = await this.sendSnapshot();
+          this.lastEventId = result.lastEventId;
+          localStorage.setItem(
+            LAST_EVENT_ID_KEY,
+            String(this.lastEventId),
+          );
+          this.updateUI("saved");
+        } catch (error) {
+          console.error("Manual save failed:", error);
+          this.updateUI("error");
+        }
+        return;
+      }
       this.clearTimers();
       await this.performSave("manual");
     }
 
     reset() {
-      this.isDirty = false;
-      this.dirtyStores.clear();
+      this.pendingEvents = [];
       this.clearTimers();
-      this.stopPolling();
       this.offlineQueue = [];
       this.retryCount = 0;
     }
@@ -400,6 +406,7 @@ window.hyperbook.cloud = (function () {
   function clearAuthToken() {
     localStorage.removeItem(AUTH_TOKEN_KEY);
     localStorage.removeItem(AUTH_USER_KEY);
+    localStorage.removeItem(LAST_EVENT_ID_KEY);
   }
 
   /**
@@ -467,12 +474,16 @@ window.hyperbook.cloud = (function () {
       const data = await response.json();
 
       if (!response.ok) {
-        throw new Error(data.error || "Request failed");
+        const err = new Error(data.error || "Request failed");
+        err.status = response.status;
+        throw err;
       }
 
       return data;
     } catch (error) {
-      console.error("Cloud API error:", error);
+      if (!error.status) {
+        console.error("Cloud API error:", error);
+      }
       throw error;
     }
   }
@@ -524,24 +535,26 @@ window.hyperbook.cloud = (function () {
     try {
       const data = await apiRequest(`/api/store/${HYPERBOOK_CLOUD.id}`);
 
-      if (data && data.data) {
-        // Import data into local stores
-        const storeData = data.data.data || data.data;
-        const { hyperbook, sqlIde, learnJ } = storeData;
+      if (data && data.snapshot) {
+        const storeData = data.snapshot.data || data.snapshot;
+        const { hyperbook } = storeData;
 
         if (hyperbook) {
           const blob = new Blob([JSON.stringify(hyperbook)], {
             type: "application/json",
           });
-          await store.import(blob, { clearTablesBeforeImport: true });
+          await hyperbook.store.db.import(blob, { clearTablesBeforeImport: true });
         }
 
-        if (sqlIde) {
-          await importExternalDB("SQL-IDE", sqlIde);
-        }
-
-        if (learnJ) {
-          await importExternalDB("LearnJ", learnJ);
+        // Track the server's lastEventId
+        if (data.lastEventId !== undefined) {
+          localStorage.setItem(
+            LAST_EVENT_ID_KEY,
+            String(data.lastEventId),
+          );
+          if (syncManager) {
+            syncManager.lastEventId = data.lastEventId;
+          }
         }
 
         console.log("✓ Store loaded from cloud");
@@ -584,20 +597,39 @@ window.hyperbook.cloud = (function () {
         debounceDelay: 2000,
         maxWaitTime: 10000,
         minSaveInterval: 1000,
-        externalDBs: ["SQL-IDE", "LearnJ"],
-        pollInterval: 5000,
       });
 
-      // Hook Dexie tables to track changes (skip currentState — ephemeral UI data)
-      store.tables.forEach((table) => {
+      // Hook Dexie tables to capture granular events (skip currentState — ephemeral UI data)
+      hyperbook.store.tables.forEach((table) => {
         if (table.name === "currentState") return;
-        table.hook("creating", () => syncManager.markDirty(table.name));
-        table.hook("updating", () => syncManager.markDirty(table.name));
-        table.hook("deleting", () => syncManager.markDirty(table.name));
-      });
 
-      // Start polling external DBs for changes
-      syncManager.startPolling();
+        table.hook("creating", function (primKey, obj) {
+          syncManager.addEvent({
+            table: table.name,
+            op: "create",
+            primKey: primKey,
+            data: obj,
+          });
+        });
+
+        table.hook("updating", function (modifications, primKey) {
+          syncManager.addEvent({
+            table: table.name,
+            op: "update",
+            primKey: primKey,
+            data: modifications,
+          });
+        });
+
+        table.hook("deleting", function (primKey) {
+          syncManager.addEvent({
+            table: table.name,
+            op: "delete",
+            primKey: primKey,
+            data: null,
+          });
+        });
+      });
     }
   }
 
@@ -635,29 +667,29 @@ window.hyperbook.cloud = (function () {
     statusEl.className = status;
 
     if (status === "unsaved") {
-      statusEl.textContent = i18n.get("user-unsaved", {}, "Unsaved changes");
+      statusEl.textContent = hyperbook.i18n.get("user-unsaved", {}, "Unsaved changes");
       updateUserIconState("logged-in");
     } else if (status === "saving") {
-      statusEl.textContent = i18n.get("user-saving", {}, "Saving...");
+      statusEl.textContent = hyperbook.i18n.get("user-saving", {}, "Saving...");
       updateUserIconState("syncing");
     } else if (status === "saved") {
-      statusEl.textContent = i18n.get("user-saved", {}, "Saved");
+      statusEl.textContent = hyperbook.i18n.get("user-saved", {}, "Saved");
       updateUserIconState("synced");
     } else if (status === "error") {
-      statusEl.textContent = i18n.get("user-save-error", {}, "Save Error");
+      statusEl.textContent = hyperbook.i18n.get("user-save-error", {}, "Save Error");
       updateUserIconState("unsynced");
     } else if (status === "offline") {
-      statusEl.textContent = i18n.get("user-offline", {}, "Offline");
+      statusEl.textContent = hyperbook.i18n.get("user-offline", {}, "Offline");
       updateUserIconState("unsynced");
     } else if (status === "offline-queued") {
-      statusEl.textContent = i18n.get(
+      statusEl.textContent = hyperbook.i18n.get(
         "user-offline-queued",
         {},
         "Saved locally",
       );
       updateUserIconState("logged-in");
     } else if (status === "readonly") {
-      statusEl.textContent = i18n.get("user-readonly", {}, "Read-Only Mode");
+      statusEl.textContent = hyperbook.i18n.get("user-readonly", {}, "Read-Only Mode");
       statusEl.className = "readonly";
       updateUserIconState("synced");
     }
@@ -686,7 +718,7 @@ window.hyperbook.cloud = (function () {
     const errorEl = document.getElementById("user-login-error");
 
     if (!username || !password) {
-      errorEl.textContent = i18n.get(
+      errorEl.textContent = hyperbook.i18n.get(
         "user-login-required",
         {},
         "Username and password required",
@@ -700,14 +732,14 @@ window.hyperbook.cloud = (function () {
       errorEl.textContent = "";
     } catch (error) {
       errorEl.textContent =
-        error.message || i18n.get("user-login-failed", {}, "Login failed");
+        error.message || hyperbook.i18n.get("user-login-failed", {}, "Login failed");
     }
   };
 
   const logout = () => {
     if (
       confirm(
-        i18n.get("user-logout-confirm", {}, "Are you sure you want to logout?"),
+        hyperbook.i18n.get("user-logout-confirm", {}, "Are you sure you want to logout?"),
       )
     ) {
       hyperbookLogout();
@@ -727,13 +759,21 @@ window.hyperbook.cloud = (function () {
       updateUserUI(user);
     }
 
+    // Hide local export/import/reset when logged into cloud
+    if (HYPERBOOK_CLOUD && getAuthToken()) {
+      document.querySelectorAll(".export-icon, .import-icon, .reset-icon").forEach((el) => {
+        const link = el.closest("a");
+        if (link) link.style.display = "none";
+      });
+    }
+
     // Show impersonation banner if in readonly mode
     if (isReadOnlyMode()) {
       const banner = document.createElement("div");
       banner.id = "impersonation-banner";
       banner.innerHTML = `
-        <span>${i18n.get("user-impersonating", {}, "Impersonating")}: <strong>${user ? user.username : ""}</strong> — ${i18n.get("user-readonly", {}, "Read-Only Mode")}</span>
-        <a href="#" id="exit-impersonation">${i18n.get("user-exit-impersonation", {}, "Exit Impersonation")}</a>
+        <span>${hyperbook.i18n.get("user-impersonating", {}, "Impersonating")}: <strong>${user ? user.username : ""}</strong> — ${hyperbook.i18n.get("user-readonly", {}, "Read-Only Mode")}</span>
+        <a href="#" id="exit-impersonation">${hyperbook.i18n.get("user-exit-impersonation", {}, "Exit Impersonation")}</a>
       `;
       document.body.prepend(banner);
 
@@ -752,6 +792,14 @@ window.hyperbook.cloud = (function () {
 
   return {
     save: () => syncManager?.manualSave(),
+    sendSnapshot: async () => {
+      if (!syncManager || !HYPERBOOK_CLOUD || !getAuthToken() || isReadOnlyMode()) return;
+      syncManager.pendingEvents = [];
+      syncManager.clearTimers();
+      const result = await syncManager.sendSnapshot();
+      syncManager.lastEventId = result.lastEventId;
+      localStorage.setItem(LAST_EVENT_ID_KEY, String(result.lastEventId));
+    },
     userToggle,
     login,
     logout,

package/dist/assets/directive-abc-music/client.js

@@ -1,3 +1,11 @@
+/// <reference path="../hyperbook.types.js" />
+
+/**
+ * ABC music notation rendering and editing.
+ * @type {HyperbookAbc}
+ * @memberof hyperbook
+ * @see hyperbook.store
+ */
 hyperbook.abc = (function () {
   window.codeInput?.registerTemplate(
     "abc-highlighted",
@@ -33,7 +41,7 @@ hyperbook.abc = (function () {
       });
 
       resetEl?.addEventListener("click", () => {
-        store.abcMusic.delete(id);
+        hyperbook.store.abcMusic.delete(id);
         window.location.reload();
       });
 
@@ -46,7 +54,7 @@ hyperbook.abc = (function () {
       });
 
       editorEl.addEventListener("code-input_load", async () => {
-        const storeResult = await store.abcMusic
+        const storeResult = await hyperbook.store.abcMusic
           .where("id")
           .equals(editorEl.id)
           .first();
@@ -70,7 +78,7 @@ hyperbook.abc = (function () {
         });
 
         editorEl.addEventListener("change", () => {
-          store.abcMusic.put({
+          hyperbook.store.abcMusic.put({
             id: editorEl.id,
             tune: editorEl.value,
           });

package/dist/assets/directive-archive/client.js

@@ -1,4 +1,12 @@
-hyperbook.download = (function () {
+/// <reference path="../hyperbook.types.js" />
+
+/**
+ * Archive download management.
+ * @type {HyperbookArchive}
+ * @memberof hyperbook
+ * @see hyperbook.i18n
+ */
+hyperbook.archive = (function () {
   function initElement(el) {
     const labelEl = el.getElementsByClassName("label")[0];
     const src = el.href;
@@ -7,10 +15,10 @@ hyperbook.download = (function () {
       const isOnline = r.ok;
       if (isOnline) {
         labelEl.classList.remove("offline");
-        labelEl.innerHTML = labelEl.innerHTML.replace(`(${i18n.get("archive-offline")})`, "");
+        labelEl.innerHTML = labelEl.innerHTML.replace(`(${hyperbook.i18n.get("archive-offline")})`, "");
       } else {
         labelEl.classList.add("offline");
-        labelEl.innerHTML += ` (${i18n.get("archive-offline")})`;
+        labelEl.innerHTML += ` (${hyperbook.i18n.get("archive-offline")})`;
       }
     });
   }
@@ -36,5 +44,10 @@ hyperbook.download = (function () {
 
   observer.observe(document.body, { childList: true, subtree: true });
 
-  init();
+  // Initialize existing elements on document load
+  document.addEventListener("DOMContentLoaded", () => {
+    init();
+  });
+
+  return { init };
 })();