@v-tilt/browser 1.4.3 → 1.4.4

package/lib/storage.js

@@ -1,194 +1,369 @@
 "use strict";
 /**
- * Unified Storage Manager - Following PostHog's PostHogPersistence pattern
+ * Unified Storage Manager
  *
- * Single class handles all storage operations for both sessions and users.
- * Reduces code duplication and ensures consistent cookie handling.
+ * Handles all storage operations for sessions and users with consistent
+ * cookie handling across different persistence methods.
  *
  * Storage methods:
- * - cookie: Browser cookies (cross-subdomain support)
- * - localStorage: Persistent local storage
- * - sessionStorage: Tab-specific storage (cleared on tab close)
- * - localStorage+cookie: Both for redundancy
- * - memory: In-memory only (no persistence)
+ * - `cookie`: Browser cookies with cross-subdomain support
+ * - `localStorage`: Persistent local storage
+ * - `sessionStorage`: Tab-specific storage (cleared on tab close)
+ * - `localStorage+cookie`: Hybrid mode (default) - full data in localStorage,
+ *   critical identity properties also in cookies for SSR support
+ * - `memory`: In-memory only (no persistence)
+ *
+ * The `localStorage+cookie` mode is designed for traditional server-side
+ * rendered websites where each page navigation reloads JavaScript:
+ * - Critical properties (anonymous_id, device_id, etc.) are stored in cookies
+ * - Cookies ensure identity persists across full page reloads
+ * - localStorage provides fast access for SPA-style navigation
+ * - Falls back to cookie-only if localStorage is unavailable
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.StorageManager = exports.USER_COOKIE_MAX_AGE = exports.SESSION_COOKIE_MAX_AGE = void 0;
+exports.StorageManager = exports.USER_COOKIE_MAX_AGE = exports.SESSION_COOKIE_MAX_AGE = exports.COOKIE_PERSISTED_PROPERTIES = void 0;
 exports.shouldUseCrossSubdomainCookie = shouldUseCrossSubdomainCookie;
 exports.createStorageManager = createStorageManager;
 const constants_1 = require("./constants");
 const globals_1 = require("./utils/globals");
-// Default cookie TTLs
-exports.SESSION_COOKIE_MAX_AGE = 1800; // 30 minutes
-exports.USER_COOKIE_MAX_AGE = 31536000; // 1 year
-// Platforms excluded from cross-subdomain cookies (following PostHog)
+/**
+ * Critical properties persisted to cookies in `localStorage+cookie` mode.
+ * These ensure identity survives full page reloads in traditional SSR websites.
+ */
+exports.COOKIE_PERSISTED_PROPERTIES = [
+    constants_1.ANONYMOUS_ID_KEY,
+    constants_1.DEVICE_ID_KEY,
+    constants_1.DISTINCT_ID_KEY,
+    constants_1.USER_STATE_KEY,
+];
+/** Session cookie TTL: 30 minutes */
+exports.SESSION_COOKIE_MAX_AGE = 1800;
+/** User cookie TTL: 1 year */
+exports.USER_COOKIE_MAX_AGE = 31536000;
+/** Platforms where cross-subdomain cookies are disabled */
 const EXCLUDED_FROM_CROSS_SUBDOMAIN = [
     "herokuapp.com",
     "vercel.app",
     "netlify.app",
 ];
 /**
- * Auto-detect if cross-subdomain cookies should be enabled
- * Returns false for platforms like herokuapp.com, vercel.app, netlify.app
+ * Check if cross-subdomain cookies should be enabled.
+ * Returns false for shared hosting platforms to prevent cookie conflicts.
  */
 function shouldUseCrossSubdomainCookie() {
     var _a;
-    if (typeof document === "undefined") {
+    if (typeof document === "undefined")
         return false;
-    }
     const hostname = (_a = document.location) === null || _a === void 0 ? void 0 : _a.hostname;
-    if (!hostname) {
+    if (!hostname)
         return false;
-    }
     const lastTwoParts = hostname.split(".").slice(-2).join(".");
-    for (const excluded of EXCLUDED_FROM_CROSS_SUBDOMAIN) {
-        if (lastTwoParts === excluded) {
-            return false;
-        }
-    }
-    return true;
+    return !EXCLUDED_FROM_CROSS_SUBDOMAIN.includes(lastTwoParts);
 }
 /**
- * Get the cookie domain for cross-subdomain cookies
- * Returns domain like ".example.com" or empty string for same-origin
+ * Get cookie domain for cross-subdomain cookies.
+ * @returns Domain like ".example.com" or empty string for same-origin
  */
 function getCookieDomain(cross_subdomain) {
     var _a;
-    if (!cross_subdomain) {
+    if (!cross_subdomain || typeof document === "undefined")
         return "";
-    }
-    if (typeof document === "undefined") {
-        return "";
-    }
     const hostname = (_a = document.location) === null || _a === void 0 ? void 0 : _a.hostname;
-    if (!hostname) {
+    if (!hostname)
         return "";
-    }
-    // Match domain pattern like "example.com" from "sub.example.com"
     const matches = hostname.match(/[a-z0-9][a-z0-9-]+\.[a-z]{2,}$/i);
     return matches ? `.${matches[0]}` : "";
 }
 /**
  * Unified Storage Manager
+ *
  * Provides consistent storage operations across all persistence methods
+ * with automatic fallbacks and SSR support.
  */
 class StorageManager {
     constructor(options) {
-        var _a, _b;
+        var _a, _b, _c;
         this.memoryStorage = new Map();
+        this._localStorageSupported = null;
         this.method = options.method;
         this.cross_subdomain =
             (_a = options.cross_subdomain) !== null && _a !== void 0 ? _a : shouldUseCrossSubdomainCookie();
-        this.sameSite = options.sameSite || "Lax";
-        // Auto-detect secure flag from protocol
+        this.sameSite = (_b = options.sameSite) !== null && _b !== void 0 ? _b : "Lax";
         this.secure =
-            (_b = options.secure) !== null && _b !== void 0 ? _b : (typeof location !== "undefined" && location.protocol === "https:");
+            (_c = options.secure) !== null && _c !== void 0 ? _c : (typeof location !== "undefined" && location.protocol === "https:");
     }
-    // ============================================================================
-    // Public API - Simple key-value operations
-    // ============================================================================
+    // ---------------------------------------------------------------------------
+    // Storage availability checks
+    // ---------------------------------------------------------------------------
+    /** Check if localStorage is available (result is cached) */
+    isLocalStorageSupported() {
+        if (this._localStorageSupported !== null) {
+            return this._localStorageSupported;
+        }
+        if (typeof globals_1.window === "undefined" || !globals_1.window.localStorage) {
+            this._localStorageSupported = false;
+            return false;
+        }
+        try {
+            const testKey = "__vt_ls_test__";
+            globals_1.window.localStorage.setItem(testKey, "1");
+            const ok = globals_1.window.localStorage.getItem(testKey) === "1";
+            globals_1.window.localStorage.removeItem(testKey);
+            this._localStorageSupported = ok;
+            if (!ok) {
+                console.warn("[vTilt] localStorage unavailable, using cookies");
+            }
+            return ok;
+        }
+        catch (_a) {
+            this._localStorageSupported = false;
+            console.warn("[vTilt] localStorage unavailable, using cookies");
+            return false;
+        }
+    }
+    /** Check if a key should be persisted to cookies */
+    isCriticalProperty(key) {
+        return exports.COOKIE_PERSISTED_PROPERTIES.includes(key);
+    }
+    // ---------------------------------------------------------------------------
+    // Public API
+    // ---------------------------------------------------------------------------
     /**
-     * Get a value from storage
+     * Get a value from storage.
+     *
+     * For `localStorage+cookie` mode:
+     * - Critical properties: read cookie first (for SSR), fall back to localStorage
+     * - Non-critical properties: read from localStorage only
      */
     get(key) {
         var _a;
         try {
-            if (this.method === constants_1.PERSISTENCE_METHODS.memory) {
-                return (_a = this.memoryStorage.get(key)) !== null && _a !== void 0 ? _a : null;
-            }
-            if (this.usesLocalStorage()) {
-                const value = localStorage.getItem(key);
-                if (value !== null) {
-                    return value;
-                }
-                // Fall back to cookie for localStorage+cookie mode
-                if (this.method === constants_1.PERSISTENCE_METHODS.localStoragePlusCookie) {
+            switch (this.method) {
+                case constants_1.PERSISTENCE_METHODS.memory:
+                    return (_a = this.memoryStorage.get(key)) !== null && _a !== void 0 ? _a : null;
+                case constants_1.PERSISTENCE_METHODS.localStoragePlusCookie:
+                    return this.getLocalStoragePlusCookie(key);
+                case constants_1.PERSISTENCE_METHODS.localStorage:
+                    return this.getLocalStorage(key);
+                case constants_1.PERSISTENCE_METHODS.sessionStorage:
+                    return this.readFromSessionStorage(key);
+                case constants_1.PERSISTENCE_METHODS.cookie:
+                default:
                     return this.getCookie(key);
-                }
-                return null;
-            }
-            if (this.usesSessionStorage()) {
-                return sessionStorage.getItem(key);
             }
-            // Cookie-only mode
-            return this.getCookie(key);
         }
-        catch (error) {
-            console.warn(`[StorageManager] Failed to get "${key}":`, error);
+        catch (err) {
+            console.warn(`[vTilt] Storage get error for "${key}":`, err);
             return null;
         }
     }
     /**
-     * Set a value in storage
-     * @param maxAge - Cookie max age in seconds (ignored for localStorage/sessionStorage)
+     * Set a value in storage.
+     * @param maxAge Cookie max age in seconds (only for cookie-based storage)
+     *
+     * For `localStorage+cookie` mode:
+     * - All values stored in localStorage (if available)
+     * - Critical properties ALWAYS stored in cookies for SSR support
      */
     set(key, value, maxAge) {
         try {
-            if (this.method === constants_1.PERSISTENCE_METHODS.memory) {
-                this.memoryStorage.set(key, value);
-                return;
-            }
-            if (this.usesLocalStorage()) {
-                localStorage.setItem(key, value);
-                // Also set cookie for localStorage+cookie mode
-                if (this.method === constants_1.PERSISTENCE_METHODS.localStoragePlusCookie) {
-                    this.setCookie(key, value, maxAge || exports.USER_COOKIE_MAX_AGE);
-                }
-                return;
+            switch (this.method) {
+                case constants_1.PERSISTENCE_METHODS.memory:
+                    this.memoryStorage.set(key, value);
+                    break;
+                case constants_1.PERSISTENCE_METHODS.localStoragePlusCookie:
+                    this.setLocalStoragePlusCookie(key, value, maxAge);
+                    break;
+                case constants_1.PERSISTENCE_METHODS.localStorage:
+                    this.setLocalStorage(key, value);
+                    break;
+                case constants_1.PERSISTENCE_METHODS.sessionStorage:
+                    this.writeToSessionStorage(key, value);
+                    break;
+                case constants_1.PERSISTENCE_METHODS.cookie:
+                default:
+                    this.setCookie(key, value, maxAge !== null && maxAge !== void 0 ? maxAge : exports.USER_COOKIE_MAX_AGE);
             }
-            if (this.usesSessionStorage()) {
-                sessionStorage.setItem(key, value);
-                return;
-            }
-            // Cookie-only mode
-            this.setCookie(key, value, maxAge || exports.USER_COOKIE_MAX_AGE);
         }
-        catch (error) {
-            console.warn(`[StorageManager] Failed to set "${key}":`, error);
+        catch (err) {
+            console.warn(`[vTilt] Storage set error for "${key}":`, err);
         }
     }
-    /**
-     * Remove a value from storage
-     */
+    /** Remove a value from storage */
     remove(key) {
         try {
-            if (this.method === constants_1.PERSISTENCE_METHODS.memory) {
-                this.memoryStorage.delete(key);
-                return;
-            }
-            if (this.usesLocalStorage()) {
-                localStorage.removeItem(key);
-                if (this.method === constants_1.PERSISTENCE_METHODS.localStoragePlusCookie) {
+            switch (this.method) {
+                case constants_1.PERSISTENCE_METHODS.memory:
+                    this.memoryStorage.delete(key);
+                    break;
+                case constants_1.PERSISTENCE_METHODS.localStoragePlusCookie:
+                    this.removeLocalStoragePlusCookie(key);
+                    break;
+                case constants_1.PERSISTENCE_METHODS.localStorage:
+                    this.removeLocalStorage(key);
+                    break;
+                case constants_1.PERSISTENCE_METHODS.sessionStorage:
+                    this.removeFromSessionStorage(key);
+                    break;
+                case constants_1.PERSISTENCE_METHODS.cookie:
+                default:
                     this.removeCookie(key);
-                }
-                return;
             }
-            if (this.usesSessionStorage()) {
-                sessionStorage.removeItem(key);
-                return;
+        }
+        catch (err) {
+            console.warn(`[vTilt] Storage remove error for "${key}":`, err);
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // localStorage+cookie mode (hybrid)
+    // ---------------------------------------------------------------------------
+    getLocalStoragePlusCookie(key) {
+        if (this.isCriticalProperty(key)) {
+            // Critical: cookie takes precedence (for SSR support)
+            const cookieValue = this.getCookie(key);
+            const lsValue = this.getLocalStorage(key);
+            if (cookieValue !== null) {
+                // Sync to localStorage for faster future reads
+                if (lsValue !== cookieValue && this.isLocalStorageSupported()) {
+                    try {
+                        globals_1.window === null || globals_1.window === void 0 ? void 0 : globals_1.window.localStorage.setItem(key, cookieValue);
+                    }
+                    catch (_a) {
+                        /* ignore */
+                    }
+                }
+                return cookieValue;
             }
-            // Cookie-only mode
+            return lsValue;
+        }
+        // Non-critical: localStorage only
+        return this.getLocalStorage(key);
+    }
+    setLocalStoragePlusCookie(key, value, maxAge) {
+        // Always try localStorage first
+        this.setLocalStorage(key, value);
+        // Critical properties MUST go to cookies (SSR support)
+        if (this.isCriticalProperty(key)) {
+            this.setCookie(key, value, maxAge !== null && maxAge !== void 0 ? maxAge : exports.USER_COOKIE_MAX_AGE);
+        }
+    }
+    removeLocalStoragePlusCookie(key) {
+        this.removeLocalStorage(key);
+        if (this.isCriticalProperty(key)) {
             this.removeCookie(key);
         }
-        catch (error) {
-            console.warn(`[StorageManager] Failed to remove "${key}":`, error);
+    }
+    // ---------------------------------------------------------------------------
+    // localStorage operations
+    // ---------------------------------------------------------------------------
+    getLocalStorage(key) {
+        var _a;
+        if (!this.isLocalStorageSupported())
+            return null;
+        try {
+            return (_a = globals_1.window === null || globals_1.window === void 0 ? void 0 : globals_1.window.localStorage.getItem(key)) !== null && _a !== void 0 ? _a : null;
+        }
+        catch (_b) {
+            return null;
         }
     }
-    // ============================================================================
-    // JSON operations with optional expiry (for session data)
-    // ============================================================================
-    /**
-     * Get JSON value with expiry check
-     * Returns null if expired or not found
-     */
+    setLocalStorage(key, value) {
+        if (!this.isLocalStorageSupported())
+            return;
+        try {
+            globals_1.window === null || globals_1.window === void 0 ? void 0 : globals_1.window.localStorage.setItem(key, value);
+        }
+        catch (err) {
+            console.warn("[vTilt] localStorage write error:", err);
+        }
+    }
+    removeLocalStorage(key) {
+        if (!this.isLocalStorageSupported())
+            return;
+        try {
+            globals_1.window === null || globals_1.window === void 0 ? void 0 : globals_1.window.localStorage.removeItem(key);
+        }
+        catch (_a) {
+            /* ignore */
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // sessionStorage operations (internal)
+    // ---------------------------------------------------------------------------
+    readFromSessionStorage(key) {
+        var _a;
+        try {
+            return (_a = globals_1.window === null || globals_1.window === void 0 ? void 0 : globals_1.window.sessionStorage.getItem(key)) !== null && _a !== void 0 ? _a : null;
+        }
+        catch (_b) {
+            return null;
+        }
+    }
+    writeToSessionStorage(key, value) {
+        try {
+            globals_1.window === null || globals_1.window === void 0 ? void 0 : globals_1.window.sessionStorage.setItem(key, value);
+        }
+        catch (err) {
+            console.warn("[vTilt] sessionStorage write error:", err);
+        }
+    }
+    removeFromSessionStorage(key) {
+        try {
+            globals_1.window === null || globals_1.window === void 0 ? void 0 : globals_1.window.sessionStorage.removeItem(key);
+        }
+        catch (_a) {
+            /* ignore */
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Cookie operations
+    // ---------------------------------------------------------------------------
+    getCookie(name) {
+        if (typeof document === "undefined")
+            return null;
+        const nameEq = name + "=";
+        for (const part of document.cookie.split(";")) {
+            const trimmed = part.trim();
+            if (trimmed.startsWith(nameEq)) {
+                try {
+                    return decodeURIComponent(trimmed.slice(nameEq.length));
+                }
+                catch (_a) {
+                    return trimmed.slice(nameEq.length);
+                }
+            }
+        }
+        return null;
+    }
+    setCookie(name, value, maxAge) {
+        if (typeof document === "undefined")
+            return;
+        const domain = getCookieDomain(this.cross_subdomain);
+        let cookie = `${name}=${encodeURIComponent(value)}; Max-Age=${maxAge}; path=/; SameSite=${this.sameSite}`;
+        if (this.secure)
+            cookie += "; Secure";
+        if (domain)
+            cookie += `; domain=${domain}`;
+        document.cookie = cookie;
+    }
+    removeCookie(name) {
+        if (typeof document === "undefined")
+            return;
+        const domain = getCookieDomain(this.cross_subdomain);
+        document.cookie = `${name}=; Max-Age=0; path=/${domain ? `; domain=${domain}` : ""}`;
+        // Also try without domain
+        document.cookie = `${name}=; Max-Age=0; path=/`;
+    }
+    // ---------------------------------------------------------------------------
+    // JSON helpers
+    // ---------------------------------------------------------------------------
+    /** Get JSON value with expiry check */
     getWithExpiry(key) {
         const raw = this.get(key);
-        if (!raw) {
+        if (!raw)
             return null;
-        }
         try {
             const item = JSON.parse(raw);
-            // Check expiry if set
             if (item.expiry && Date.now() > item.expiry) {
                 this.remove(key);
                 return null;
@@ -196,14 +371,10 @@ class StorageManager {
             return item.value;
         }
         catch (_a) {
-            // Not JSON or invalid format - return raw value if compatible
             return null;
         }
     }
-    /**
-     * Set JSON value with optional expiry
-     * @param ttlMs - Time to live in milliseconds
-     */
+    /** Set JSON value with optional TTL */
     setWithExpiry(key, value, ttlMs) {
         const item = {
             value,
@@ -211,14 +382,11 @@ class StorageManager {
         };
         this.set(key, JSON.stringify(item));
     }
-    /**
-     * Get JSON value (no expiry check)
-     */
+    /** Get parsed JSON value */
     getJSON(key) {
         const raw = this.get(key);
-        if (!raw) {
+        if (!raw)
             return null;
-        }
         try {
             return JSON.parse(raw);
         }
@@ -226,126 +394,45 @@ class StorageManager {
             return null;
         }
     }
-    /**
-     * Set JSON value
-     */
+    /** Set JSON value */
     setJSON(key, value, maxAge) {
         this.set(key, JSON.stringify(value), maxAge);
     }
-    // ============================================================================
-    // Cookie operations (internal)
-    // ============================================================================
-    getCookie(name) {
-        if (typeof document === "undefined") {
-            return null;
-        }
-        const cookies = document.cookie.split(";");
-        for (const cookie of cookies) {
-            const [key, ...valueParts] = cookie.trim().split("=");
-            if (key === name) {
-                const value = valueParts.join("="); // Handle values with = in them
-                try {
-                    return decodeURIComponent(value);
-                }
-                catch (_a) {
-                    return value;
-                }
-            }
-        }
-        return null;
-    }
-    setCookie(name, value, maxAge) {
-        if (typeof document === "undefined") {
-            return;
-        }
-        let cookieString = `${name}=${encodeURIComponent(value)}`;
-        cookieString += `; Max-Age=${maxAge}`;
-        cookieString += `; path=/`;
-        cookieString += `; SameSite=${this.sameSite}`;
-        if (this.secure) {
-            cookieString += `; Secure`;
-        }
-        // Auto-detect domain for cross-subdomain cookies
-        const domain = getCookieDomain(this.cross_subdomain);
-        if (domain) {
-            cookieString += `; domain=${domain}`;
-        }
-        document.cookie = cookieString;
-    }
-    removeCookie(name) {
-        if (typeof document === "undefined") {
-            return;
-        }
-        // Auto-detect domain for cross-subdomain cookies
-        const domain = getCookieDomain(this.cross_subdomain);
-        // Set cookie with expired date
-        let cookieString = `${name}=; Max-Age=0; path=/`;
-        if (domain) {
-            cookieString += `; domain=${domain}`;
-        }
-        document.cookie = cookieString;
-        // Also try without domain (in case it was set without)
-        document.cookie = `${name}=; Max-Age=0; path=/`;
-    }
-    // ============================================================================
-    // Helper methods
-    // ============================================================================
-    usesLocalStorage() {
-        return (this.method === constants_1.PERSISTENCE_METHODS.localStorage ||
-            this.method === constants_1.PERSISTENCE_METHODS.localStoragePlusCookie);
-    }
-    usesSessionStorage() {
-        return this.method === constants_1.PERSISTENCE_METHODS.sessionStorage;
-    }
-    /**
-     * Check if sessionStorage is available
-     */
+    // ---------------------------------------------------------------------------
+    // Utility methods
+    // ---------------------------------------------------------------------------
+    /** Check if sessionStorage is available */
     canUseSessionStorage() {
-        if (typeof globals_1.window === "undefined" || !(globals_1.window === null || globals_1.window === void 0 ? void 0 : globals_1.window.sessionStorage)) {
+        if (typeof globals_1.window === "undefined" || !(globals_1.window === null || globals_1.window === void 0 ? void 0 : globals_1.window.sessionStorage))
             return false;
-        }
         try {
-            const testKey = "__vt_storage_test__";
-            globals_1.window.sessionStorage.setItem(testKey, "test");
-            globals_1.window.sessionStorage.removeItem(testKey);
+            const k = "__vt_ss_test__";
+            globals_1.window.sessionStorage.setItem(k, "1");
+            globals_1.window.sessionStorage.removeItem(k);
             return true;
         }
         catch (_a) {
             return false;
         }
     }
-    /**
-     * Get direct access to sessionStorage (for window_id which always uses sessionStorage)
-     */
+    /** Get sessionStorage instance (for window_id which always uses sessionStorage) */
     getSessionStorage() {
         var _a;
-        if (!this.canUseSessionStorage()) {
-            return null;
-        }
-        return (_a = globals_1.window === null || globals_1.window === void 0 ? void 0 : globals_1.window.sessionStorage) !== null && _a !== void 0 ? _a : null;
+        return this.canUseSessionStorage()
+            ? ((_a = globals_1.window === null || globals_1.window === void 0 ? void 0 : globals_1.window.sessionStorage) !== null && _a !== void 0 ? _a : null)
+            : null;
     }
-    /**
-     * Update storage method at runtime
-     */
+    /** Update storage method at runtime */
     setMethod(method) {
         this.method = method;
     }
-    /**
-     * Get current storage method
-     */
+    /** Get current storage method */
     getMethod() {
         return this.method;
     }
 }
 exports.StorageManager = StorageManager;
-/**
- * Create a shared storage instance
- * Use this for creating storage managers with consistent settings
- */
+/** Factory function to create a StorageManager with default settings */
 function createStorageManager(method, cross_subdomain) {
-    return new StorageManager({
-        method,
-        cross_subdomain,
-        sameSite: "Lax",
-    });
+    return new StorageManager({ method, cross_subdomain, sameSite: "Lax" });
 }

package/lib/user-manager.d.ts

@@ -94,7 +94,21 @@ export declare class UserManager {
      */
     update_referrer_info(): void;
     /**
-     * Load user identity from storage
+     * Load user identity from storage.
+     *
+     * For traditional SSR websites where each page navigation reloads JavaScript,
+     * identity MUST be persisted immediately when generated to ensure the same
+     * anonymous_id is used across all page loads.
+     *
+     * Flow:
+     * 1. Load from storage (reads cookies first for critical properties in SSR mode)
+     * 2. Generate new IDs if not found
+     * 3. Immediately persist to storage (saved to both localStorage and cookies)
+     *
+     * With `localStorage+cookie` persistence (default):
+     * - Critical properties are stored in cookies for SSR compatibility
+     * - Full data is stored in localStorage for fast SPA-style access
+     * - Cookies ensure identity persists across full page reloads
      */
     private loadUserIdentity;
     /**