dolphin-client 1.0.4 → 1.0.6

package/dist/index.cjs

@@ -47,7 +47,21 @@ var APIHandler = class {
     target.requestDirect = (method, path, body, options) => {
       return this.requestDirect(method, path, body, options);
     };
-    const methods = ["get", "post", "put", "patch", "del", "request", "requestDirect"];
+    target._findCSRFToken = () => this._findCSRFToken();
+    target._resolveBaseUrl = (path) => this._resolveBaseUrl(path);
+    target._normalizeValidationErrors = (errData) => this._normalizeValidationErrors(errData);
+    const methods = [
+      "get",
+      "post",
+      "put",
+      "patch",
+      "del",
+      "request",
+      "requestDirect",
+      "_findCSRFToken",
+      "_resolveBaseUrl",
+      "_normalizeValidationErrors"
+    ];
     return new Proxy(target, {
       get: (t, prop) => {
         if (typeof prop === "string" && !methods.includes(prop)) {
@@ -57,6 +71,108 @@ var APIHandler = class {
       }
     });
   }
+  /**
+   * Attempts to find a CSRF token in the document (meta tags, forms, or cookies).
+   * Works for Laravel, CakePHP, WordPress, Express, NestJS, etc.
+   * @private
+   */
+  _findCSRFToken() {
+    if (typeof document === "undefined") return null;
+    const metaNames = ["csrf-token", "_csrf", "xsrf-token", "csrf_token"];
+    for (const name of metaNames) {
+      const metaEl = document.querySelector(`meta[name="${name}"], meta[content][name$="${name}"]`);
+      if (metaEl) {
+        const token = metaEl.getAttribute("content");
+        if (token) return token;
+      }
+    }
+    const inputNames = ["_csrfToken", "_token", "_csrf", "csrf_token"];
+    for (const name of inputNames) {
+      const inputEl = document.querySelector(`input[type="hidden"][name="${name}"]`);
+      if (inputEl && inputEl.value) return inputEl.value;
+    }
+    const cookies = ["csrfToken", "XSRF-TOKEN", "_csrf", "csrf_token"];
+    for (const name of cookies) {
+      const match = document.cookie.match(new RegExp("(^|;\\s*)" + name + "=([^;]*)"));
+      if (match) return decodeURIComponent(match[2]);
+    }
+    const wpNonce = typeof window !== "undefined" && window.wpApiSettings?.nonce;
+    if (wpNonce) return wpNonce;
+    return null;
+  }
+  /**
+   * Dynamically resolves the Base Path/URL from `<base href="...">` or subfolders.
+   * @private
+   */
+  _resolveBaseUrl(path) {
+    if (path.startsWith("http://") || path.startsWith("https://")) {
+      return path;
+    }
+    let baseUrl = this.client.httpUrl;
+    if (typeof document !== "undefined") {
+      const baseEl = document.querySelector("base[href]");
+      if (baseEl) {
+        const href = baseEl.getAttribute("href") || "";
+        if (href && href !== "/") {
+          const cleanHref = href.endsWith("/") ? href.slice(0, -1) : href;
+          baseUrl = `${this.client.httpUrl}${cleanHref.startsWith("/") ? cleanHref : "/" + cleanHref}`;
+        }
+      } else {
+        const metaBase = document.querySelector('meta[name="base-path"]');
+        if (metaBase) {
+          const content = metaBase.getAttribute("content") || "";
+          if (content && content !== "/") {
+            const cleanContent = content.endsWith("/") ? content.slice(0, -1) : content;
+            baseUrl = `${this.client.httpUrl}${cleanContent.startsWith("/") ? cleanContent : "/" + cleanContent}`;
+          }
+        }
+      }
+    }
+    const cleanPath = path.startsWith("/") ? path : "/" + path;
+    return `${baseUrl}${cleanPath}`;
+  }
+  /**
+   * Normalizes backend validation errors from major PHP and Node.js frameworks
+   * into a unified { [field]: message } object.
+   * @private
+   */
+  _normalizeValidationErrors(errData) {
+    const normalized = {};
+    if (!errData || typeof errData !== "object") return normalized;
+    const errors = errData.errors || errData.validationErrors || errData;
+    if (Array.isArray(errors)) {
+      for (const err of errors) {
+        if (err && typeof err === "object") {
+          const field = err.path || err.param || err.field || err.property;
+          const msg = err.msg || err.message || err.error;
+          if (field && msg) {
+            normalized[field] = Array.isArray(msg) ? msg[0] : msg;
+          }
+        }
+      }
+      return normalized;
+    }
+    if (typeof errors === "object" && errors !== null) {
+      for (const key in errors) {
+        const val = errors[key];
+        if (!val) continue;
+        if (Array.isArray(val)) {
+          if (val.length > 0) {
+            normalized[key] = String(val[0]);
+          }
+        } else if (typeof val === "object") {
+          const innerKeys = Object.keys(val);
+          if (innerKeys.length > 0) {
+            const firstInnerKey = innerKeys[0];
+            normalized[key] = String(val[firstInnerKey]);
+          }
+        } else {
+          normalized[key] = String(val);
+        }
+      }
+    }
+    return normalized;
+  }
   /**
    * Intercept request for offline-first caching and queuing.
    */
@@ -107,30 +223,68 @@ var APIHandler = class {
    */
   async requestDirect(method, path, body = null, options = {}) {
     const _isRetry = options._isRetry === true;
-    const url = path.startsWith("http://") || path.startsWith("https://") ? path : `${this.client.httpUrl}${path.startsWith("/") ? path : "/" + path}`;
+    let finalMethod = method.toUpperCase();
+    let finalBody = body;
+    const headers = {
+      "Content-Type": "application/json",
+      ...options.headers || {}
+    };
+    if (["PUT", "PATCH", "DELETE"].includes(finalMethod)) {
+      if (this.client.options.methodSpoofing || options.methodSpoofing) {
+        headers["X-HTTP-Method-Override"] = finalMethod;
+        if (finalBody instanceof FormData) {
+          finalBody.append("_method", finalMethod);
+        } else if (finalBody && typeof finalBody === "object") {
+          finalBody = {
+            ...finalBody,
+            _method: finalMethod
+          };
+        } else if (!finalBody) {
+          finalBody = { _method: finalMethod };
+        }
+        finalMethod = "POST";
+      }
+    }
+    const url = this._resolveBaseUrl(path);
     if (this.client.options.debug) {
-      console.log(`%c\u{1F680} [Dolphin API Request]:`, "color: #3b82f6; font-weight: bold;", method.toUpperCase(), path, body || "");
+      console.log(`%c\u{1F680} [Dolphin API Request]:`, "color: #3b82f6; font-weight: bold;", method.toUpperCase(), path, finalBody || "");
     }
     const controller = new AbortController();
     const timeoutId = setTimeout(
       () => controller.abort(),
       this.client.options.timeout
     );
-    const headers = {
-      "Content-Type": "application/json",
-      ...options.headers || {}
-    };
     if (this.client.accessToken) {
       headers["Authorization"] = `Bearer ${this.client.accessToken}`;
     }
+    if (["POST", "PUT", "PATCH", "DELETE"].includes(method.toUpperCase())) {
+      const csrfToken = this._findCSRFToken();
+      if (csrfToken) {
+        headers["X-CSRF-Token"] = csrfToken;
+        headers["X-XSRF-TOKEN"] = csrfToken;
+        headers["X-CSRFToken"] = csrfToken;
+        headers["X-WP-Nonce"] = csrfToken;
+        if (finalBody && typeof finalBody === "object") {
+          if (!finalBody._csrfToken && !finalBody._token && !finalBody._csrf) {
+            finalBody = {
+              ...finalBody,
+              _csrfToken: csrfToken,
+              _token: csrfToken,
+              _csrf: csrfToken
+            };
+          }
+        }
+      }
+    }
     const fetchOptions = { ...options };
     delete fetchOptions._isRetry;
+    delete fetchOptions.methodSpoofing;
     try {
       const response = await fetch(url, {
-        method,
+        method: finalMethod,
         headers,
         signal: controller.signal,
-        ...body ? { body: JSON.stringify(body) } : {},
+        ...finalBody ? { body: JSON.stringify(finalBody) } : {},
         ...fetchOptions
       });
       clearTimeout(timeoutId);
@@ -162,6 +316,14 @@ var APIHandler = class {
       if (this.client.options.debug) {
         console.error(`%c\u274C [Dolphin API Error]:`, "color: #ef4444; font-weight: bold;", method.toUpperCase(), path, err);
       }
+      if (err && typeof err === "object" && err.data) {
+        const normErrors = this._normalizeValidationErrors(err.data);
+        if (Object.keys(normErrors).length > 0) {
+          for (const field in normErrors) {
+            this.client.publish(`errors/${field}`, normErrors[field]);
+          }
+        }
+      }
       if (err.name === "AbortError") {
         throw { status: 408, data: { error: "Request timed out" } };
       }
@@ -295,12 +457,15 @@ var DolphinStore = class {
   data;
   listeners;
   subscribed;
+  /** @fix: Store unsubscribe functions so destroy() can clean up WS subscriptions (was: subscriptions never removed) */
+  _unsubscribers;
   /** @param {DolphinClient} client */
   constructor(client) {
     this.client = client;
     this.data = /* @__PURE__ */ new Map();
     this.listeners = /* @__PURE__ */ new Set();
     this.subscribed = /* @__PURE__ */ new Set();
+    this._unsubscribers = /* @__PURE__ */ new Map();
     return new Proxy(this, {
       get: (target, prop) => {
         if (prop in target) return target[prop];
@@ -352,9 +517,12 @@ var DolphinStore = class {
       state.error = null;
       this._applyTransform(state);
       if (!this.subscribed.has(name)) {
-        this.client.subscribe(`db:sync/${name.toLowerCase()}`, (update) => {
+        const unsubscribe = () => this.client.unsubscribe(`db:sync/${name.toLowerCase()}`, updateHandler);
+        const updateHandler = (update) => {
           this._handleRemoteUpdate(name, update);
-        });
+        };
+        this.client.subscribe(`db:sync/${name.toLowerCase()}`, updateHandler);
+        this._unsubscribers.set(name, unsubscribe);
         this.subscribed.add(name);
       }
     } catch (e) {
@@ -411,6 +579,22 @@ var DolphinStore = class {
   _notify() {
     this.listeners.forEach((l) => l());
   }
+  /**
+   * Clean up all WebSocket subscriptions and listeners.
+   * Call this when the store is no longer needed to prevent resource leaks.
+   */
+  destroy() {
+    this._unsubscribers.forEach((unsub) => {
+      try {
+        unsub();
+      } catch {
+      }
+    });
+    this._unsubscribers.clear();
+    this.subscribed.clear();
+    this.listeners.clear();
+    this.data.clear();
+  }
 };
 
 // src/core.ts
@@ -430,6 +614,8 @@ var DolphinClient = class {
   fileHandlers;
   _offlineQueue;
   reconnectAttempts;
+  /** @fix: Store timer ID so disconnect() can cancel pending reconnects (was: memory/logic leak) */
+  _reconnectTimer;
   _attachedListeners;
   constructor(url = "", deviceId = "", options = {}) {
     if (!url && typeof window !== "undefined") url = window.location.host;
@@ -439,7 +625,7 @@ var DolphinClient = class {
     else if (typeof window !== "undefined") protocol = window.location.protocol;
     this.host = (url || "localhost").replace(/\/$/, "").replace(/^https?:\/\//, "");
     this.httpUrl = `${protocol}//${this.host}`;
-    this.deviceId = deviceId || "web_" + Math.random().toString(36).substr(2, 8);
+    this.deviceId = deviceId || (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function" ? "web_" + crypto.randomUUID().replace(/-/g, "").slice(0, 8) : "web_" + Math.random().toString(36).slice(2, 10));
     this.options = {
       timeout: 15e3,
       chunkSize: 65536,
@@ -447,6 +633,9 @@ var DolphinClient = class {
       maxReconnect: 5,
       autoRefreshToken: true,
       debug: false,
+      methodSpoofing: false,
+      routerViewport: "main, #viewport, body",
+      routerTransitions: true,
       ...options
     };
     this.socket = null;
@@ -466,6 +655,7 @@ var DolphinClient = class {
     this.fileHandlers = /* @__PURE__ */ new Set();
     this._offlineQueue = [];
     this.reconnectAttempts = 0;
+    this._reconnectTimer = null;
     this._attachedListeners = [];
     if (typeof window !== "undefined" && typeof this._initDOMBinding === "function") {
       this._initDOMBinding();
@@ -494,6 +684,9 @@ var DolphinClient = class {
   // ── WebSocket ─────────────────────────────────────────────────────────────
   /** Connect to the Dolphin realtime server */
   async connect() {
+    if (this.socket && (this.socket.readyState === WebSocket.OPEN || this.socket.readyState === WebSocket.CONNECTING)) {
+      return Promise.resolve();
+    }
     return new Promise((resolve, reject) => {
       const protocol = this.httpUrl.startsWith("https") ? "wss:" : "ws:";
       const wsUrl = `${protocol}//${this.host}/realtime?deviceId=${this.deviceId}`;
@@ -518,11 +711,18 @@ var DolphinClient = class {
   }
   /** Disconnect cleanly */
   disconnect() {
+    if (this._reconnectTimer !== null) {
+      clearTimeout(this._reconnectTimer);
+      this._reconnectTimer = null;
+    }
     if (this.socket) {
       this.socket.onclose = null;
       this.socket.close();
       this.socket = null;
     }
+    if (typeof this._collabCleanup === "function") {
+      this._collabCleanup();
+    }
     this.cleanupDomListeners();
   }
   /** @private */
@@ -610,8 +810,11 @@ var DolphinClient = class {
       this.reconnectAttempts++;
       const delay = Math.pow(2, this.reconnectAttempts) * 1e3;
       console.log(`[Dolphin] Reconnecting in ${delay / 1e3}s (attempt ${this.reconnectAttempts})...`);
-      setTimeout(() => this.connect().catch(() => {
-      }), delay);
+      this._reconnectTimer = setTimeout(() => {
+        this._reconnectTimer = null;
+        this.connect().catch(() => {
+        });
+      }, delay);
     } else {
       console.error("[Dolphin] Max reconnect attempts reached.");
     }
@@ -789,6 +992,7 @@ var DolphinClient = class {
 
 // src/dom.ts
 function attachDOMBinding(clientProto) {
+  const componentPromiseCache = /* @__PURE__ */ new Map();
   function escapeRegExp(str) {
     return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   }
@@ -1035,7 +1239,9 @@ function attachDOMBinding(clientProto) {
       const scheduleFn = typeof requestAnimationFrame !== "undefined" ? requestAnimationFrame : (cb) => setTimeout(cb, 0);
       scheduleFn(() => {
         pendingUpdates.forEach((html, el) => {
-          patchDOM(el, html);
+          if (el.isConnected !== false) {
+            patchDOM(el, html);
+          }
         });
         pendingUpdates.clear();
         rafScheduled = false;
@@ -1174,7 +1380,7 @@ function attachDOMBinding(clientProto) {
     if (this._domInitialized) return;
     this._domInitialized = true;
     const PUSH_EVENTS = ["input", "change", "keyup", "paste", "blur"];
-    const debounceTimers = /* @__PURE__ */ new Map();
+    const debounceTimers = /* @__PURE__ */ new WeakMap();
     PUSH_EVENTS.forEach((evtName) => {
       this.addDomListener(document, evtName, (e) => {
         if (!e.target || !e.target.getAttribute) return;
@@ -1227,6 +1433,14 @@ function attachDOMBinding(clientProto) {
       const rtTopic = e.target.getAttribute("data-rt-submit");
       const apiTarget = e.target.getAttribute("data-api-submit");
       if (rtTopic || apiTarget) {
+        const formInputs = e.target.querySelectorAll("[name]");
+        formInputs.forEach((inputEl) => {
+          const name = inputEl.name;
+          if (name) {
+            this.publish(`errors/${name}`, "");
+            inputEl.classList.remove("invalid");
+          }
+        });
         const validatedInputs = e.target.querySelectorAll("[data-rt-validate]");
         let formIsValid = true;
         if (validatedInputs.length > 0 && typeof this.validateField === "function") {
@@ -1240,9 +1454,6 @@ function attachDOMBinding(clientProto) {
                 formIsValid = false;
                 inputEl.classList.add("invalid");
                 this.publish(`errors/${name}`, errorMsg);
-              } else {
-                inputEl.classList.remove("invalid");
-                this.publish(`errors/${name}`, "");
               }
             }
           });
@@ -1270,8 +1481,11 @@ function attachDOMBinding(clientProto) {
             resolvedTarget = resolvedTarget.replace(new RegExp(`\\{\\{${escapedK}\\}\\}`, "g"), parentCtx[k] !== void 0 && parentCtx[k] !== null ? parentCtx[k] : "");
           }
           const parts = resolvedTarget.trim().split(" ");
-          const method = parts.length > 1 ? parts[0].toUpperCase() : "POST";
+          let method = parts.length > 1 ? parts[0].toUpperCase() : "POST";
           const path = parts.length > 1 ? parts[1] : parts[0];
+          if (data._method) {
+            method = String(data._method).toUpperCase();
+          }
           try {
             const result = await this.api.request(method, path, data);
             const resultBind = e.target.getAttribute("data-api-result");
@@ -1358,6 +1572,8 @@ function attachDOMBinding(clientProto) {
     });
     this._scanAndFetchAPIBinds();
     this._scanStoreBinds();
+    this._resolveImports();
+    this._initSPARouter();
   };
   clientProto._scanAndFetchAPIBinds = async function() {
     if (typeof document === "undefined") return;
@@ -1365,6 +1581,10 @@ function attachDOMBinding(clientProto) {
     for (const el of Array.from(elements)) {
       const path = el.getAttribute("data-api-get");
       if (!path) continue;
+      if (typeof el.hasAttribute === "function" && el.hasAttribute("data-api-initialized")) continue;
+      if (typeof el.setAttribute === "function") {
+        el.setAttribute("data-api-initialized", "true");
+      }
       try {
         const result = await this.api.get(path);
         const apiStore = el.getAttribute("data-api-store");
@@ -1380,20 +1600,22 @@ function attachDOMBinding(clientProto) {
         } else if (!apiStore) {
           const template = resolveTemplate(el);
           if (template && typeof result === "object" && result !== null) {
-            if (Array.isArray(result)) {
+            const processedResult = this._applyDeclarativeDirectives(el, result);
+            if (Array.isArray(processedResult)) {
               let combinedHTML = "";
-              for (const item of result) {
+              for (const item of processedResult) {
                 combinedHTML += renderTemplate(template, item);
               }
               scheduleDOMUpdate(el, combinedHTML);
             } else {
-              scheduleDOMUpdate(el, renderTemplate(template, result));
+              scheduleDOMUpdate(el, renderTemplate(template, processedResult));
             }
           } else {
             if (el.tagName === "INPUT" || el.tagName === "TEXTAREA") {
               el.value = typeof result === "object" ? result.value !== void 0 ? result.value : "" : result;
             } else {
-              el.innerHTML = typeof result === "object" ? result.html || result.text || JSON.stringify(result) : result;
+              const rawHTML = typeof result === "object" ? result.html || result.text || JSON.stringify(result) : String(result);
+              el.innerHTML = sanitizeHTML(rawHTML);
             }
           }
         }
@@ -1402,21 +1624,139 @@ function attachDOMBinding(clientProto) {
       }
     }
   };
+  clientProto._applyDeclarativeDirectives = function(el, payload) {
+    let processedPayload = payload;
+    if (typeof payload === "object" && payload !== null) {
+      const applyFilterSearchSort = (arr) => {
+        let result = [...arr];
+        const filterAttr = el.getAttribute("data-rt-filter");
+        if (filterAttr) {
+          const parts = filterAttr.split("==");
+          if (parts.length === 2) {
+            const itemProp = parts[0].trim();
+            const storeExpr = parts[1].trim();
+            let filterVal = void 0;
+            const storeParts = storeExpr.split(".");
+            if (storeParts.length === 2) {
+              filterVal = this.getStoreState(storeParts[0], storeParts[1]);
+            } else {
+              filterVal = payload[storeExpr] !== void 0 ? payload[storeExpr] : this.getStoreState("app", storeExpr);
+            }
+            if (filterVal !== void 0 && filterVal !== null && filterVal !== "") {
+              result = result.filter((item) => item[itemProp] === filterVal);
+            }
+          }
+        }
+        const searchAttr = el.getAttribute("data-rt-search");
+        if (searchAttr) {
+          const parts = searchAttr.split("==");
+          if (parts.length === 2) {
+            const itemProp = parts[0].trim();
+            const storeExpr = parts[1].trim();
+            let searchVal = void 0;
+            const storeParts = storeExpr.split(".");
+            if (storeParts.length === 2) {
+              searchVal = this.getStoreState(storeParts[0], storeParts[1]);
+            } else {
+              searchVal = payload[storeExpr] !== void 0 ? payload[storeExpr] : this.getStoreState("app", storeExpr);
+            }
+            if (searchVal !== void 0 && searchVal !== null && searchVal !== "") {
+              const query = String(searchVal).toLowerCase();
+              result = result.filter((item) => {
+                const val = item[itemProp];
+                return val !== void 0 && val !== null && String(val).toLowerCase().includes(query);
+              });
+            }
+          }
+        }
+        const sortAttr = el.getAttribute("data-rt-sort");
+        if (sortAttr) {
+          let sortByVal = void 0;
+          const storeParts = sortAttr.split(".");
+          if (storeParts.length === 2) {
+            sortByVal = this.getStoreState(storeParts[0], storeParts[1]);
+          } else {
+            sortByVal = payload[sortAttr] !== void 0 ? payload[sortAttr] : this.getStoreState("app", sortAttr);
+          }
+          if (sortByVal && sortByVal !== "") {
+            if (sortByVal === "popular") {
+              result.sort((a, b) => {
+                const rateA = a.rating?.rate || a.rate || 0;
+                const rateB = b.rating?.rate || b.rate || 0;
+                return rateB - rateA;
+              });
+            } else {
+              let field = "";
+              let direction = "asc";
+              if (sortByVal.endsWith("-low") || sortByVal.endsWith("-asc")) {
+                field = sortByVal.replace("-low", "").replace("-asc", "");
+                direction = "asc";
+              } else if (sortByVal.endsWith("-high") || sortByVal.endsWith("-desc")) {
+                field = sortByVal.replace("-high", "").replace("-desc", "");
+                direction = "desc";
+              }
+              if (field) {
+                result.sort((a, b) => {
+                  const resolveVal = (obj, path) => {
+                    return path.split(".").reduce((acc, part) => acc && acc[part], obj);
+                  };
+                  let valA = resolveVal(a, field);
+                  let valB = resolveVal(b, field);
+                  if (valA === void 0) valA = a[field];
+                  if (valB === void 0) valB = b[field];
+                  if (typeof valA === "string" && typeof valB === "string") {
+                    return direction === "asc" ? valA.localeCompare(valB) : valB.localeCompare(valA);
+                  }
+                  const numA = Number(valA);
+                  const numB = Number(valB);
+                  if (!isNaN(numA) && !isNaN(numB)) {
+                    return direction === "asc" ? numA - numB : numB - numA;
+                  }
+                  return 0;
+                });
+              }
+            }
+          }
+        }
+        return result;
+      };
+      if (Array.isArray(payload)) {
+        processedPayload = applyFilterSearchSort(payload);
+      } else {
+        let foundArrayKey = "";
+        for (const key in payload) {
+          if (Array.isArray(payload[key])) {
+            foundArrayKey = key;
+            break;
+          }
+        }
+        if (foundArrayKey) {
+          const processedArray = applyFilterSearchSort(payload[foundArrayKey]);
+          processedPayload = {
+            ...payload,
+            [foundArrayKey]: processedArray
+          };
+        }
+      }
+    }
+    return processedPayload;
+  };
   clientProto._updateDOM = function(topic, payload) {
     if (typeof document === "undefined") return;
     const elements = document.querySelectorAll(`[data-rt-bind="${topic}"]`);
     elements.forEach((el) => {
-      if (el.getAttribute("data-rt-type") === "context" && typeof payload === "object" && payload !== null) {
-        el._rtContext = payload;
+      const processedPayload = this._applyDeclarativeDirectives(el, payload);
+      if (el.getAttribute("data-rt-type") === "context" && typeof processedPayload === "object" && processedPayload !== null) {
+        el._rtContext = processedPayload;
         const processNode = (node) => {
           if (node.hasAttribute("data-rt-text")) {
             const key = node.getAttribute("data-rt-text");
-            if (key && payload[key] !== void 0 && payload[key] !== null) node.textContent = payload[key];
+            if (key && processedPayload[key] !== void 0 && processedPayload[key] !== null) node.textContent = processedPayload[key];
           }
           if (node.hasAttribute("data-rt-html")) {
             const key = node.getAttribute("data-rt-html");
-            if (key && payload[key] !== void 0 && payload[key] !== null) {
-              node.innerHTML = sanitizeHTML(payload[key]);
+            if (key && processedPayload[key] !== void 0 && processedPayload[key] !== null) {
+              node.innerHTML = sanitizeHTML(processedPayload[key]);
             }
           }
           if (node.hasAttribute("data-rt-attr")) {
@@ -1427,8 +1767,8 @@ function attachDOMBinding(clientProto) {
                 if (parts.length === 2) {
                   const attrName = parts[0].trim();
                   const key = parts[1].trim();
-                  if (attrName && key && payload[key] !== void 0 && payload[key] !== null) {
-                    node.setAttribute(attrName, payload[key]);
+                  if (attrName && key && processedPayload[key] !== void 0 && processedPayload[key] !== null) {
+                    node.setAttribute(attrName, processedPayload[key]);
                   }
                 }
               });
@@ -1443,7 +1783,7 @@ function attachDOMBinding(clientProto) {
                   const className = parts[0].trim();
                   const key = parts[1].trim();
                   const classNames = className.split(/\s+/).filter(Boolean);
-                  if (payload[key]) {
+                  if (processedPayload[key]) {
                     classNames.forEach((c) => node.classList.add(c));
                   } else {
                     classNames.forEach((c) => node.classList.remove(c));
@@ -1455,7 +1795,7 @@ function attachDOMBinding(clientProto) {
           if (node.hasAttribute("data-rt-if")) {
             const key = node.getAttribute("data-rt-if");
             if (key) {
-              if (payload[key]) {
+              if (processedPayload[key]) {
                 node.style.display = "";
               } else {
                 node.style.display = "none";
@@ -1465,7 +1805,7 @@ function attachDOMBinding(clientProto) {
           if (node.hasAttribute("data-rt-hide")) {
             const key = node.getAttribute("data-rt-hide");
             if (key) {
-              if (payload[key]) {
+              if (processedPayload[key]) {
                 node.style.display = "none";
               } else {
                 node.style.display = "";
@@ -1478,25 +1818,172 @@ function attachDOMBinding(clientProto) {
         return;
       }
       const template = resolveTemplate(el);
-      if (template && typeof payload === "object" && payload !== null) {
-        if (Array.isArray(payload)) {
+      if (template && typeof processedPayload === "object" && processedPayload !== null) {
+        if (Array.isArray(processedPayload)) {
           let combinedHTML = "";
-          for (const item of payload) {
+          for (const item of processedPayload) {
             combinedHTML += renderTemplate(template, item);
           }
           scheduleDOMUpdate(el, combinedHTML);
         } else {
-          scheduleDOMUpdate(el, renderTemplate(template, payload));
+          scheduleDOMUpdate(el, renderTemplate(template, processedPayload));
         }
         return;
       }
       if (el.tagName === "INPUT" || el.tagName === "TEXTAREA") {
-        el.value = typeof payload === "object" ? payload.value !== void 0 ? payload.value : "" : payload;
+        el.value = typeof processedPayload === "object" ? processedPayload.value !== void 0 ? processedPayload.value : "" : processedPayload;
+      } else if (template) {
+        el.innerHTML = typeof processedPayload === "object" ? processedPayload.html || processedPayload.text || JSON.stringify(processedPayload) : String(processedPayload);
       } else {
-        el.innerHTML = typeof payload === "object" ? payload.html || payload.text || JSON.stringify(payload) : payload;
+        const rawHTML = typeof processedPayload === "object" ? processedPayload.html || processedPayload.text || JSON.stringify(processedPayload) : String(processedPayload);
+        el.innerHTML = sanitizeHTML(rawHTML);
       }
     });
   };
+  clientProto._resolveImports = async function(container) {
+    if (typeof document === "undefined") return;
+    const root = container || document.body || document;
+    if (!root || typeof root.querySelectorAll !== "function") return;
+    const elements = root.querySelectorAll("[data-import]");
+    if (elements.length === 0) return;
+    const resolveNode = async (el, resolvingSet) => {
+      const src = el.getAttribute("data-import");
+      if (!src) return;
+      if (resolvingSet.has(src)) {
+        console.warn(`[Dolphin Component Warning]: Circular import detected for "${src}". Skipping resolving.`);
+        el.innerHTML = `<span style="color:red;font-weight:bold;">Circular import: ${src}</span>`;
+        return;
+      }
+      resolvingSet.add(src);
+      let promise = componentPromiseCache.get(src);
+      if (!promise) {
+        promise = fetch(src).then((res) => {
+          if (!res.ok) throw new Error(`HTTP ${res.status}`);
+          return res.text();
+        });
+        promise.catch(() => componentPromiseCache.delete(src));
+        componentPromiseCache.set(src, promise);
+      }
+      let content = "";
+      try {
+        content = await promise;
+      } catch (err) {
+        console.error(`[Dolphin Component Error]: Failed to fetch component "${src}":`, err);
+        content = `<span style="color:red;font-weight:bold;">Failed to import ${src}</span>`;
+      }
+      el.innerHTML = sanitizeHTML(content);
+      el.removeAttribute("data-import");
+      const nestedElements = el.querySelectorAll("[data-import]");
+      if (nestedElements.length > 0) {
+        const subPromises = Array.from(nestedElements).map((child) => resolveNode(child, new Set(resolvingSet)));
+        await Promise.all(subPromises);
+      }
+      this._scanStoreBinds();
+      this._scanAndFetchAPIBinds();
+    };
+    const promises = Array.from(elements).map((el) => resolveNode(el, /* @__PURE__ */ new Set()));
+    await Promise.all(promises);
+  };
+  clientProto._initSPARouter = function() {
+    if (typeof window === "undefined" || typeof document === "undefined") return;
+    if (this._routerInitialized) return;
+    this._routerInitialized = true;
+    let _spaAbortController = null;
+    const findViewport = () => {
+      const selector = this.options.routerViewport || "main, #viewport, body";
+      const selectors = selector.split(",").map((s) => s.trim());
+      for (const sel of selectors) {
+        const el = document.querySelector(sel);
+        if (el) return el;
+      }
+      return document.body;
+    };
+    const loadPage = async (url, pushState = true) => {
+      try {
+        if (this.options.debug) {
+          console.log(`%c\u{1F6E3}\uFE0F [Dolphin Router]: Navigating to ${url}...`, "color: #3b82f6; font-weight: bold;");
+        }
+        if (_spaAbortController) {
+          _spaAbortController.abort();
+        }
+        _spaAbortController = new AbortController();
+        const signal = _spaAbortController.signal;
+        const viewport = findViewport();
+        if (this.options.routerTransitions && viewport) {
+          viewport.classList.add("dolphin-fade-out");
+          await new Promise((r) => setTimeout(r, 150));
+        }
+        const response = await fetch(url, { signal });
+        if (!response.ok) throw new Error(`HTTP ${response.status}`);
+        const html = await response.text();
+        _spaAbortController = null;
+        const parser = new DOMParser();
+        const doc = parser.parseFromString(html, "text/html");
+        if (doc.title) {
+          document.title = doc.title;
+        }
+        const newViewport = doc.querySelector(this.options.routerViewport || "main, #viewport, body");
+        const currentViewport = findViewport();
+        if (newViewport && currentViewport) {
+          currentViewport.innerHTML = newViewport.innerHTML;
+          Array.from(newViewport.attributes).forEach((attr) => {
+            currentViewport.setAttribute(attr.name, attr.value);
+          });
+        } else if (currentViewport) {
+          currentViewport.innerHTML = doc.body.innerHTML;
+        }
+        if (pushState) {
+          window.history.pushState({ dolphinSpa: true, url }, "", url);
+        }
+        if (this.options.routerTransitions && currentViewport) {
+          currentViewport.classList.remove("dolphin-fade-out");
+          currentViewport.classList.add("dolphin-fade-in");
+          setTimeout(() => currentViewport.classList.remove("dolphin-fade-in"), 300);
+        }
+        await this._resolveImports(currentViewport);
+        this._scanStoreBinds();
+        this._scanAndFetchAPIBinds();
+      } catch (err) {
+        if (err && err.name === "AbortError") return;
+        console.error("[Dolphin Router Error]: Failed to route page:", err);
+        window.location.href = url;
+      }
+    };
+    this.addDomListener(document, "click", (e) => {
+      const anchor = e.target.closest("a");
+      if (!anchor) return;
+      if (!anchor.hasAttribute("data-spa") && anchor.getAttribute("data-spa") !== "true") return;
+      const href = anchor.getAttribute("href");
+      if (!href || href.startsWith("#") || href.startsWith("javascript:") || href.startsWith("mailto:") || href.startsWith("tel:")) return;
+      const url = new URL(href, window.location.href);
+      if (url.origin !== window.location.origin) return;
+      e.preventDefault();
+      loadPage(href);
+    });
+    this.addDomListener(window, "popstate", (e) => {
+      if (e.state && e.state.dolphinSpa) {
+        loadPage(e.state.url, false);
+      } else if (e.state === null) {
+        loadPage(window.location.pathname, false);
+      }
+    });
+    if (this.options.routerTransitions) {
+      const style = document.createElement("style");
+      style.innerHTML = `
+                .dolphin-fade-out {
+                    opacity: 0;
+                    transition: opacity 0.15s ease-in-out;
+                }
+                .dolphin-fade-in {
+                    opacity: 0;
+                }
+                main, #viewport, body {
+                    transition: opacity 0.15s ease-in-out;
+                }
+            `;
+      document.head.appendChild(style);
+    }
+  };
 }
 
 // src/offline.ts
@@ -1574,6 +2061,10 @@ var DolphinOffline = class {
         const store = transaction.objectStore("cache");
         store.put({ data, timestamp: Date.now() }, key);
         transaction.oncomplete = () => resolve();
+        transaction.onerror = () => {
+          console.warn("[Dolphin Offline] setCache write failed for key:", key);
+          resolve();
+        };
       } catch {
         resolve();
       }
@@ -1596,6 +2087,11 @@ var DolphinOffline = class {
         const store = transaction.objectStore("mutations");
         store.add(mutation);
         transaction.oncomplete = () => resolve();
+        transaction.onerror = () => {
+          console.warn("[Dolphin Offline] queueMutation write failed:", method, path);
+          this.memoryMutations.push(mutation);
+          resolve();
+        };
       } catch {
         resolve();
       }
@@ -1628,6 +2124,10 @@ var DolphinOffline = class {
         const store = transaction.objectStore("mutations");
         store.delete(id);
         transaction.oncomplete = () => resolve();
+        transaction.onerror = () => {
+          console.warn("[Dolphin Offline] removeMutation failed for id:", id);
+          resolve();
+        };
       } catch {
         resolve();
       }
@@ -1973,6 +2473,9 @@ function attachDragDrop(clientProto) {
 function attachCollab(clientProto) {
   clientProto._initCollab = function() {
     if (typeof document === "undefined") return;
+    const remoteCursors = /* @__PURE__ */ new Map();
+    const cursorStaleTimers = /* @__PURE__ */ new Map();
+    const CURSOR_STALE_MS = 5e3;
     this.addDomListener(document, "mousemove", (e) => {
       const shareContainers = document.querySelectorAll("[data-rt-cursor-share]");
       shareContainers.forEach((container) => {
@@ -2009,6 +2512,7 @@ function attachCollab(clientProto) {
       if (e.target._typingTimer) clearTimeout(e.target._typingTimer);
       e.target._typingTimer = setTimeout(() => {
         e.target._isTyping = false;
+        e.target._typingTimer = null;
         publishTyping(false);
       }, 2e3);
     });
@@ -2032,21 +2536,32 @@ function attachCollab(clientProto) {
       if (remoteDeviceId === this.deviceId) return;
       const container = document.querySelector(`[data-rt-cursor-share="${room}"]`);
       if (!container) return;
-      let cursorEl = container.querySelector(`.rt-cursor-${remoteDeviceId}`);
-      if (!cursorEl) {
+      const cursorKey = `${room}::${remoteDeviceId}`;
+      let cursorEl = remoteCursors.get(cursorKey);
+      if (!cursorEl || !document.contains(cursorEl)) {
         cursorEl = document.createElement("div");
         cursorEl.className = `rt-cursor rt-cursor-${remoteDeviceId}`;
         cursorEl.style.position = "absolute";
         cursorEl.style.width = "10px";
         cursorEl.style.height = "10px";
         cursorEl.style.borderRadius = "50%";
-        cursorEl.style.backgroundColor = "#" + Math.floor(Math.random() * 16777215).toString(16);
+        cursorEl.style.backgroundColor = "#" + Math.floor(Math.random() * 16777215).toString(16).padStart(6, "0");
         cursorEl.style.pointerEvents = "none";
         container.appendChild(cursorEl);
+        remoteCursors.set(cursorKey, cursorEl);
       }
       const box = container.getBoundingClientRect();
       cursorEl.style.left = payload.x * box.width + "px";
       cursorEl.style.top = payload.y * box.height + "px";
+      if (cursorStaleTimers.has(cursorKey)) {
+        clearTimeout(cursorStaleTimers.get(cursorKey));
+      }
+      cursorStaleTimers.set(cursorKey, setTimeout(() => {
+        const el = remoteCursors.get(cursorKey);
+        if (el && el.parentNode) el.parentNode.removeChild(el);
+        remoteCursors.delete(cursorKey);
+        cursorStaleTimers.delete(cursorKey);
+      }, CURSOR_STALE_MS));
     });
     this.subscribe("collab/+/crdt", (payload, topic) => {
       if (payload.deviceId === this.deviceId) return;
@@ -2064,6 +2579,14 @@ function attachCollab(clientProto) {
         }
       });
     });
+    this._collabCleanup = () => {
+      cursorStaleTimers.forEach((t) => clearTimeout(t));
+      cursorStaleTimers.clear();
+      remoteCursors.forEach((el) => {
+        if (el && el.parentNode) el.parentNode.removeChild(el);
+      });
+      remoteCursors.clear();
+    };
   };
 }