@jqhtml/core 2.3.11 → 2.3.13

package/dist/index.js

@@ -1122,6 +1122,15 @@ class Jqhtml_Component {
         this.__data_frozen = false; // Track if this.data is currently frozen
         this.next_reload_force_refresh = null; // State machine for reload()/refresh() debounce precedence
         this.__lifecycle_authorized = false; // Flag for lifecycle method protection
+        // Cache mode properties
+        this._cache_key = null; // Cache key for caching
+        // 'html' mode caching
+        this._cached_html = null; // Cached HTML to inject on first render
+        this._used_cached_html = false; // Flag if cached HTML was used (forces re-render after on_load)
+        this._should_cache_html_after_ready = false; // Flag to cache HTML after on_ready lifecycle
+        this._is_dynamic = false; // True if this.data changed during on_load() (used for HTML cache sync)
+        // on_render synchronization (HTML cache mode)
+        this._on_render_complete = false; // True after on_render() has been called post-on_load
         this._cid = this._generate_cid();
         this._lifecycle_manager = LifecycleManager.get_instance();
         // Create or wrap element
@@ -1352,6 +1361,40 @@ class Jqhtml_Component {
                 `The framework will automatically re-render if this.data changes during on_load().`);
         }
         this._log_lifecycle('render', 'start');
+        // HTML CACHE MODE - If we have cached HTML, inject it directly and skip template rendering
+        if (this._cached_html !== null) {
+            if (window.jqhtml?.debug?.verbose) {
+                console.log(`[Cache html] Component ${this._cid} (${this.component_name()}) injecting cached HTML`, { html_length: this._cached_html.length });
+            }
+            // Inject cached HTML directly
+            this.$[0].innerHTML = this._cached_html;
+            // Mark that we used cached HTML (forces re-render after on_load)
+            this._used_cached_html = true;
+            // Clear cached HTML so next render uses template
+            this._cached_html = null;
+            // Mark first render complete
+            this._did_first_render = true;
+            this._log_lifecycle('render', 'complete (cached HTML)');
+            // NEW ARCHITECTURE: Call on_render() even after cache inject
+            // This ensures consistent behavior - on_render() always runs after DOM update
+            // Note: this.data has defaults from on_create(), not fresh data yet
+            const cacheRenderResult = this._call_lifecycle_sync('on_render');
+            if (cacheRenderResult && typeof cacheRenderResult.then === 'function') {
+                console.warn(`[JQHTML] Component "${this.component_name()}" returned a Promise from on_render(). ` +
+                    `on_render() must be synchronous code. Remove 'async' from the function declaration.`);
+            }
+            // Emit lifecycle event
+            this.trigger('render');
+            // Store args/data snapshots for later comparison
+            try {
+                this._args_on_last_render = JSON.parse(JSON.stringify(this.args));
+            }
+            catch (error) {
+                this._args_on_last_render = null;
+            }
+            this._data_on_last_render = JSON.stringify(this.data);
+            return current_render_id;
+        }
         // Determine child-finding strategy: If component is off-DOM, children can't register
         // via _find_dom_parent() (no parent in DOM to find), so we'll need find() fallback later.
         // If attached to DOM, children register normally and we can use the fast _dom_children path.
@@ -1519,6 +1562,12 @@ class Jqhtml_Component {
         this._log_lifecycle('render', 'complete');
         // Call on_render() with authorization (sync) immediately after render completes
         // This ensures event handlers are always re-attached after DOM updates
+        //
+        // NEW ARCHITECTURE: on_render() can now access this.data normally
+        // The HTML cache mode now properly synchronizes - on_render() runs after both:
+        // 1. Cache inject (with on_create() defaults)
+        // 2. Second render (with fresh data from on_load())
+        // Since on_render() always runs with appropriate data, no proxy restriction needed
         const renderResult = this._call_lifecycle_sync('on_render');
         if (renderResult && typeof renderResult.then === 'function') {
             console.warn(`[JQHTML] Component "${this.component_name()}" returned a Promise from on_render(). ` +
@@ -1539,6 +1588,12 @@ class Jqhtml_Component {
         }
         // Store data snapshot for refresh() comparison
         this._data_on_last_render = JSON.stringify(this.data);
+        // HTML CACHE MODE: Mark on_render complete after second render (post-on_load)
+        // This signals to parent components that this component's DOM is fully rendered
+        // with fresh data and ready for HTML snapshot
+        if (this._ready_state >= 2) {
+            this._on_render_complete = true;
+        }
         // Return the render ID so callers can check if this render is still current
         return current_render_id;
     }
@@ -1612,8 +1667,8 @@ class Jqhtml_Component {
                 `on_create() must be synchronous code. Remove 'async' from the function declaration.`);
             await result; // Still wait for it to avoid breaking existing code
         }
-        // CACHE READ - Hydrate this.data from cache BEFORE first render
-        // This happens after on_create() but before render, allowing instant first render with cached data
+        // CACHE CHECK - Read from cache based on cache mode ('data' or 'html')
+        // This happens after on_create() but before render, allowing instant first render
         const { Load_Coordinator } = await Promise.resolve().then(function () { return loadCoordinator; });
         const { Jqhtml_Local_Storage } = await Promise.resolve().then(function () { return localStorage$1; });
         // Check if component implements cache_id() for custom cache key
@@ -1644,21 +1699,48 @@ class Jqhtml_Component {
             if (window.jqhtml?.debug?.verbose) {
                 console.log(`[Cache] Component ${this._cid} (${this.component_name()}) has non-serializable args - caching disabled`, { uncacheable_property });
             }
-            return; // Skip cache check
-        }
-        if (window.jqhtml?.debug?.verbose) {
-            console.log(`[Cache] Component ${this._cid} (${this.component_name()}) checking cache in create()`, { cache_key, has_cache_key_set: Jqhtml_Local_Storage.has_cache_key() });
-        }
-        const cached_data = Jqhtml_Local_Storage.get(cache_key);
-        if (cached_data !== null) {
-            this.data = cached_data;
-            if (window.jqhtml?.debug?.verbose) {
-                console.log(`[Cache] Component ${this._cid} (${this.component_name()}) hydrated from cache in create()`, { cache_key, data: this.data });
-            }
+            // Don't return - continue to snapshot this.data for on_load restoration
         }
         else {
+            // Store cache key for later use
+            this._cache_key = cache_key;
+            // Get cache mode
+            const cache_mode = Jqhtml_Local_Storage.get_cache_mode();
             if (window.jqhtml?.debug?.verbose) {
-                console.log(`[Cache] Component ${this._cid} (${this.component_name()}) cache miss in create()`, { cache_key });
+                console.log(`[Cache ${cache_mode}] Component ${this._cid} (${this.component_name()}) checking cache in create()`, { cache_key, cache_mode, has_cache_key_set: Jqhtml_Local_Storage.has_cache_key() });
+            }
+            if (cache_mode === 'html') {
+                // HTML cache mode - check for cached HTML to inject on first render
+                const html_cache_key = `${cache_key}::html`;
+                const cached_html = Jqhtml_Local_Storage.get(html_cache_key);
+                if (cached_html !== null && typeof cached_html === 'string') {
+                    // Store cached HTML for injection in _render()
+                    this._cached_html = cached_html;
+                    if (window.jqhtml?.debug?.verbose) {
+                        console.log(`[Cache html] Component ${this._cid} (${this.component_name()}) found cached HTML`, { cache_key: html_cache_key, html_length: cached_html.length });
+                    }
+                }
+                else {
+                    if (window.jqhtml?.debug?.verbose) {
+                        console.log(`[Cache html] Component ${this._cid} (${this.component_name()}) cache miss`, { cache_key: html_cache_key });
+                    }
+                }
+            }
+            else {
+                // Data cache mode (default) - check for cached data to hydrate this.data
+                const cached_data = Jqhtml_Local_Storage.get(cache_key);
+                if (cached_data !== null && typeof cached_data === 'object') {
+                    // Hydrate this.data with cached data
+                    this.data = cached_data;
+                    if (window.jqhtml?.debug?.verbose) {
+                        console.log(`[Cache data] Component ${this._cid} (${this.component_name()}) hydrated from cache`, { cache_key, data: cached_data });
+                    }
+                }
+                else {
+                    if (window.jqhtml?.debug?.verbose) {
+                        console.log(`[Cache data] Component ${this._cid} (${this.component_name()}) cache miss`, { cache_key });
+                    }
+                }
             }
         }
         // Snapshot this.data after on_create() completes
@@ -1848,8 +1930,7 @@ class Jqhtml_Component {
             // Always clear loading flag and complete coordination
             this.__loading = false;
             complete_coordination();
-            // Freeze this.data after on_load() completes
-            this.__data_frozen = true;
+            // Note: this.data stays unfrozen until after normalization below
         }
         // Validate that on_load() only modified this.data
         let argsAfterLoad = null;
@@ -1878,12 +1959,43 @@ class Jqhtml_Component {
                 `  ❌ this.${newProperties[0]} = value;\n` +
                 `  ✅ this.data.${newProperties[0]} = value;`);
         }
-        // Check if data changed during on_load() - if so, update cache (but not if empty)
-        const data_after_load = JSON.stringify(this.data);
-        if (data_after_load !== data_before_load && data_after_load !== '{}') {
-            Jqhtml_Local_Storage.set(cache_key, this.data);
+        // DATA MODE: Normalize this.data through serialize/deserialize round-trip
+        // This ensures "hot" data (fresh from on_load) behaves identically to "cold" data
+        // (restored from cache). Unregistered class instances become plain objects immediately,
+        // so developers catch missing class registrations during development rather than
+        // only after a page reload when data comes from cache.
+        const cache_mode = Jqhtml_Local_Storage.get_cache_mode();
+        if (cache_mode === 'data') {
+            const normalized = Jqhtml_Local_Storage.normalize_for_cache(this.data);
+            this.data = normalized;
             if (window.jqhtml?.debug?.verbose) {
-                console.log(`[Cache] Component ${this._cid} (${this.component_name()}) updated cache after on_load()`, { cache_key, data: this.data });
+                console.log(`[Cache data] Component ${this._cid} (${this.component_name()}) normalized this.data after on_load()`, { data: this.data });
+            }
+        }
+        // Freeze this.data after normalization completes
+        this.__data_frozen = true;
+        // CACHE WRITE - If data changed during on_load(), write to cache based on mode
+        const data_after_load = JSON.stringify(this.data);
+        const data_changed = data_after_load !== data_before_load;
+        // Track if component is "dynamic" (this.data changed during on_load)
+        // Used by HTML cache mode for synchronization - static parents don't block children
+        this._is_dynamic = data_changed && data_after_load !== '{}';
+        if (this._is_dynamic) {
+            if (this._cache_key) {
+                if (cache_mode === 'html') {
+                    // HTML cache mode - flag to cache HTML after children ready in _ready()
+                    this._should_cache_html_after_ready = true;
+                    if (window.jqhtml?.debug?.verbose) {
+                        console.log(`[Cache html] Component ${this._cid} (${this.component_name()}) will cache HTML after ready`, { cache_key: this._cache_key });
+                    }
+                }
+                else {
+                    // Data cache mode (default) - write this.data to cache
+                    Jqhtml_Local_Storage.set(this._cache_key, this.data);
+                    if (window.jqhtml?.debug?.verbose) {
+                        console.log(`[Cache data] Component ${this._cid} (${this.component_name()}) cached data after on_load()`, { cache_key: this._cache_key, data: this.data });
+                    }
+                }
             }
         }
         this._ready_state = 2;
@@ -1901,6 +2013,34 @@ class Jqhtml_Component {
         if (this._stopped || this._ready_state >= 4)
             return;
         this._log_lifecycle('ready', 'start');
+        // HTML CACHE MODE - New synchronization architecture:
+        // 1. Wait for all children to complete on_render (post-on_load)
+        // 2. Take HTML snapshot BEFORE waiting for children ready
+        // 3. This ensures we capture the DOM after on_render but before on_ready manipulations
+        if (this._should_cache_html_after_ready && this._cache_key) {
+            // Wait for all children to complete their on_render
+            await this._wait_for_children_on_render();
+            // Only cache if this component is dynamic (data changed during on_load)
+            // Static parents don't cache - they just let children proceed
+            if (this._is_dynamic) {
+                this._should_cache_html_after_ready = false;
+                // Cache the rendered HTML (async import to avoid circular dependency)
+                const { Jqhtml_Local_Storage } = await Promise.resolve().then(function () { return localStorage$1; });
+                const html = this.$.html();
+                const html_cache_key = `${this._cache_key}::html`;
+                Jqhtml_Local_Storage.set(html_cache_key, html);
+                if (window.jqhtml?.debug?.verbose) {
+                    console.log(`[Cache html] Component ${this._cid} (${this.component_name()}) cached HTML after children on_render complete`, { cache_key: html_cache_key, html_length: html.length });
+                }
+            }
+            else {
+                // Static component - just clear the flag, don't cache
+                this._should_cache_html_after_ready = false;
+                if (window.jqhtml?.debug?.verbose) {
+                    console.log(`[Cache html] Component ${this._cid} (${this.component_name()}) is static (no data change) - skipping HTML cache`);
+                }
+            }
+        }
         // Wait for all children to reach ready state (bottom-up execution)
         await this._wait_for_children_ready();
         await this._call_lifecycle('on_ready');
@@ -1981,6 +2121,47 @@ class Jqhtml_Component {
         // Wait for all children to be ready
         await Promise.all(ready_promises);
     }
+    /**
+     * Wait for all child components to complete on_render (post-on_load)
+     * Used by HTML cache mode to ensure DOM is fully rendered before taking snapshot
+     *
+     * HTML CACHE ARCHITECTURE:
+     * - Parent waits for all children to complete their on_render after on_load
+     * - This ensures the HTML snapshot captures fully rendered DOM
+     * - Static parents (is_dynamic=false) don't block - they immediately let children proceed
+     *
+     * @private
+     */
+    async _wait_for_children_on_render() {
+        const children = this._get_dom_children();
+        if (children.length === 0) {
+            return; // No children, nothing to wait for
+        }
+        // Create promises for each child that hasn't completed on_render yet
+        const render_promises = [];
+        for (const child of children) {
+            // If child already completed on_render post-on_load, skip
+            if (child._on_render_complete) {
+                continue;
+            }
+            // Create promise that resolves when child completes on_render
+            const render_promise = new Promise((resolve) => {
+                // Poll for completion (simple approach - could use events for more efficiency)
+                const check = () => {
+                    if (child._on_render_complete || child._stopped) {
+                        resolve();
+                    }
+                    else {
+                        setTimeout(check, 10);
+                    }
+                };
+                check();
+            });
+            render_promises.push(render_promise);
+        }
+        // Wait for all children to complete on_render
+        await Promise.all(render_promises);
+    }
     /**
      * Reload component - re-fetch data and re-render (debounced)
      *
@@ -2093,19 +2274,38 @@ class Jqhtml_Component {
                 const result = Load_Coordinator.generate_invocation_key(this.component_name(), this.args);
                 cache_key = result.key;
             }
-            // Only use cache if args are serializable
+            // Check for cached data/html when args changed
             if (cache_key !== null) {
-                const cached_data = Jqhtml_Local_Storage.get(cache_key);
-                if (cached_data !== null && JSON.stringify(cached_data) !== '{}') {
-                    if (window.jqhtml?.debug?.verbose) {
-                        console.log(`[Cache] reload() - Component ${this._cid} (${this.component_name()}) hydrated from cache (args changed)`, { cache_key, data: cached_data });
+                const cache_mode = Jqhtml_Local_Storage.get_cache_mode();
+                this._cache_key = cache_key;
+                if (cache_mode === 'html') {
+                    // HTML cache mode - check for cached HTML
+                    const html_cache_key = `${cache_key}::html`;
+                    const cached_html = Jqhtml_Local_Storage.get(html_cache_key);
+                    if (cached_html !== null && typeof cached_html === 'string') {
+                        if (window.jqhtml?.debug?.verbose) {
+                            console.log(`[Cache html] reload() - Component ${this._cid} (${this.component_name()}) found cached HTML (args changed)`, { cache_key: html_cache_key, html_length: cached_html.length });
+                        }
+                        // Store cached HTML for injection in _render()
+                        this._cached_html = cached_html;
+                        this.render();
+                        rendered_from_cache = true;
+                    }
+                }
+                else {
+                    // Data cache mode (default) - check for cached data
+                    const cached_data = Jqhtml_Local_Storage.get(cache_key);
+                    if (cached_data !== null && typeof cached_data === 'object' && JSON.stringify(cached_data) !== '{}') {
+                        if (window.jqhtml?.debug?.verbose) {
+                            console.log(`[Cache data] reload() - Component ${this._cid} (${this.component_name()}) hydrated from cache (args changed)`, { cache_key, data: cached_data });
+                        }
+                        // Hydrate this.data with cached data
+                        this.__data_frozen = false;
+                        this.data = cached_data;
+                        this.__data_frozen = true;
+                        this.render();
+                        rendered_from_cache = true;
                     }
-                    // Unfreeze to set cached data, then re-freeze
-                    this.__data_frozen = false;
-                    this.data = cached_data;
-                    this.__data_frozen = true;
-                    await this.render();
-                    rendered_from_cache = true;
                 }
             }
         }
@@ -2125,12 +2325,25 @@ class Jqhtml_Component {
             // Freeze this.data after on_load() completes
             this.__data_frozen = true;
         }
+        // Import for cache operations
+        const { Load_Coordinator } = await Promise.resolve().then(function () { return loadCoordinator; });
+        const { Jqhtml_Local_Storage } = await Promise.resolve().then(function () { return localStorage$1; });
+        // DATA MODE: Normalize this.data through serialize/deserialize round-trip
+        // (Same as in _load() - ensures hot/cold cache parity)
+        const reload_cache_mode = Jqhtml_Local_Storage.get_cache_mode();
+        if (reload_cache_mode === 'data') {
+            this.__data_frozen = false;
+            const normalized = Jqhtml_Local_Storage.normalize_for_cache(this.data);
+            this.data = normalized;
+            this.__data_frozen = true;
+            if (window.jqhtml?.debug?.verbose) {
+                console.log(`[Cache data] Component ${this._cid} (${this.component_name()}) normalized this.data after on_load() in reload()`, { data: this.data });
+            }
+        }
         // Check if data changed during on_load() - if so, update cache (but not if empty)
         const data_after_load = JSON.stringify(this.data);
         const data_changed = data_after_load !== data_before_load;
         if (data_changed && data_after_load !== '{}') {
-            const { Load_Coordinator } = await Promise.resolve().then(function () { return loadCoordinator; });
-            const { Jqhtml_Local_Storage } = await Promise.resolve().then(function () { return localStorage$1; });
             // Check if component implements cache_id() for custom cache key
             let cache_key = null;
             if (typeof this.cache_id === 'function') {
@@ -2148,11 +2361,22 @@ class Jqhtml_Component {
                 const result = Load_Coordinator.generate_invocation_key(this.component_name(), this.args);
                 cache_key = result.key;
             }
-            // Only update cache if args are serializable
+            // Write to cache based on mode
             if (cache_key !== null) {
-                Jqhtml_Local_Storage.set(cache_key, this.data);
-                if (window.jqhtml?.debug?.verbose) {
-                    console.log(`[Cache] Component ${this._cid} (${this.component_name()}) updated cache after on_load() in reload()`, { cache_key, data: this.data });
+                this._cache_key = cache_key;
+                if (reload_cache_mode === 'html') {
+                    // HTML cache mode - flag to cache HTML after children ready in _ready()
+                    this._should_cache_html_after_ready = true;
+                    if (window.jqhtml?.debug?.verbose) {
+                        console.log(`[Cache html] Component ${this._cid} (${this.component_name()}) will cache HTML after ready in reload()`, { cache_key });
+                    }
+                }
+                else {
+                    // Data cache mode (default) - write this.data to cache
+                    Jqhtml_Local_Storage.set(cache_key, this.data);
+                    if (window.jqhtml?.debug?.verbose) {
+                        console.log(`[Cache data] Component ${this._cid} (${this.component_name()}) cached data after on_load() in reload()`, { cache_key, data: this.data });
+                    }
                 }
             }
         }
@@ -2278,6 +2502,15 @@ class Jqhtml_Component {
      * @private
      */
     _should_rerender() {
+        // HTML CACHE MODE - If we used cached HTML, always re-render to get live components
+        if (this._used_cached_html) {
+            if (window.jqhtml?.debug?.verbose) {
+                console.log(`[Cache html] Component ${this._cid} (${this.component_name()}) forcing re-render after cached HTML`);
+            }
+            // Clear the flag
+            this._used_cached_html = false;
+            return true;
+        }
         // Compare current data state with data state before initial render
         const currentDataState = JSON.stringify(this.data);
         const dataChanged = this._data_before_render !== currentDataState;
@@ -3505,6 +3738,13 @@ if (typeof window !== 'undefined' && window.jQuery) {
  * - **Quota management**: Auto-clears storage when full and retries operation
  * - **Scope validation**: Clears storage when cache key changes
  * - **Developer-friendly keys**: Scoped suffix allows easy inspection in dev tools
+ * - **Class-aware serialization**: ES6 class instances serialize and restore properly
+ *
+ * Class-Aware Serialization:
+ * ES6 class instances can be serialized and deserialized if registered via
+ * register_cache_class(). Classes are wrapped as {__jqhtml_class__: "Name", __jqhtml_props__: {...}}
+ * and restored to proper instances on retrieval. Nested class instances in objects
+ * and arrays are handled recursively.
  *
  * Scoping Strategy:
  * Storage is scoped by a user-provided cache key (typically a session identifier,
@@ -3526,13 +3766,20 @@ if (typeof window !== 'undefined' && window.jQuery) {
  * once. This ensures the application continues functioning even when storage is full.
  *
  * Usage:
+ *   // Register classes that need to be cached (call once at startup)
+ *   jqhtml.register_cache_class(Contact_Model);
+ *   jqhtml.register_cache_class(User_Profile);
+ *
  *   // Must set cache key first (typically done once on page load)
  *   Jqhtml_Local_Storage.set_cache_key('user_123');
  *
- *   // Then use storage normally
- *   Jqhtml_Local_Storage.set('cached_component', {html: '...', timestamp: Date.now()});
+ *   // Then use storage normally - ES6 classes serialize automatically
+ *   Jqhtml_Local_Storage.set('cached_component', {
+ *     contact: new Contact_Model(),
+ *     timestamp: Date.now()
+ *   });
  *   const cached = Jqhtml_Local_Storage.get('cached_component');
- *   Jqhtml_Local_Storage.remove('cached_component');
+ *   // cached.contact instanceof Contact_Model === true
  *
  * IMPORTANT - Volatile Storage:
  * Storage can be cleared at any time due to:
@@ -3548,14 +3795,290 @@ if (typeof window !== 'undefined' && window.jQuery) {
  *
  * @internal This class is not exposed in the public API
  */
+// ============================================================================
+// Class Registry for Serialization
+// ============================================================================
+// Registry mapping class names to constructors
+const class_registry = Object.create(null);
+// Markers for serialized class instances (unique to avoid collisions with user data)
+const CLASS_MARKER = '__jqhtml_class__';
+const PROPS_MARKER = '__jqhtml_props__';
+/**
+ * Register a class for cache serialization/deserialization.
+ * Must be called before attempting to cache instances of this class.
+ *
+ * @param klass - The class constructor to register
+ * @throws Error if klass is not a named function/class
+ */
+function register_cache_class(klass) {
+    if (typeof klass !== 'function' || !klass.name) {
+        throw new Error('[JQHTML Cache] register_cache_class requires a named class constructor');
+    }
+    class_registry[klass.name] = klass;
+}
+// ============================================================================
+// Serialization (Object → String)
+// ============================================================================
+/**
+ * Serialize a value to JSON string, handling ES6 class instances recursively.
+ * Returns null if serialization fails for any reason.
+ *
+ * @param value - The value to serialize
+ * @param verbose - Whether to log warnings
+ * @returns Serialized JSON string, or null if serialization failed
+ */
+function serialize_value(value, verbose) {
+    try {
+        const seen = new WeakSet();
+        const processed = process_for_serialization(value, verbose, seen);
+        if (processed === undefined) {
+            // Serialization failed - undefined signals failure
+            return null;
+        }
+        return JSON.stringify(processed);
+    }
+    catch (e) {
+        if (verbose) {
+            console.warn('[JQHTML Cache] Serialization failed:', e);
+        }
+        return null;
+    }
+}
+/**
+ * Recursively process a value for serialization.
+ * Returns undefined if serialization should fail (unserializable value encountered).
+ *
+ * @param value - The value to process
+ * @param verbose - Whether to log warnings
+ * @param seen - WeakSet to detect circular references
+ * @returns Processed value ready for JSON.stringify, or undefined if failed
+ */
+function process_for_serialization(value, verbose, seen) {
+    // Handle null and undefined
+    if (value === null) {
+        return null;
+    }
+    if (value === undefined) {
+        return undefined; // JSON.stringify will omit this property
+    }
+    // Handle primitives
+    if (typeof value !== 'object') {
+        // string, number, boolean are fine
+        if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+            return value;
+        }
+        // bigint, symbol, function cannot be serialized
+        if (verbose) {
+            console.warn(`[JQHTML Cache] Cannot serialize ${typeof value} - value will be omitted`);
+        }
+        // Return undefined to omit this value (not fail entire serialization)
+        return undefined;
+    }
+    // Handle circular references
+    if (seen.has(value)) {
+        if (verbose) {
+            console.warn('[JQHTML Cache] Circular reference detected - cannot serialize');
+        }
+        return undefined; // Fail entire serialization
+    }
+    seen.add(value);
+    // Handle arrays
+    if (Array.isArray(value)) {
+        const result = [];
+        for (let i = 0; i < value.length; i++) {
+            const item = value[i];
+            const processed = process_for_serialization(item, verbose, seen);
+            // For arrays, we keep undefined as null to preserve indices
+            result.push(processed === undefined ? null : processed);
+        }
+        return result;
+    }
+    // Handle Date objects specially
+    if (value instanceof Date) {
+        return {
+            [CLASS_MARKER]: 'Date',
+            [PROPS_MARKER]: value.toISOString()
+        };
+    }
+    // Handle Map objects
+    if (value instanceof Map) {
+        const entries = [];
+        for (const [k, v] of value) {
+            const processedKey = process_for_serialization(k, verbose, seen);
+            const processedValue = process_for_serialization(v, verbose, seen);
+            entries.push([processedKey, processedValue]);
+        }
+        return {
+            [CLASS_MARKER]: 'Map',
+            [PROPS_MARKER]: entries
+        };
+    }
+    // Handle Set objects
+    if (value instanceof Set) {
+        const items = [];
+        for (const item of value) {
+            items.push(process_for_serialization(item, verbose, seen));
+        }
+        return {
+            [CLASS_MARKER]: 'Set',
+            [PROPS_MARKER]: items
+        };
+    }
+    // Get the constructor
+    const ctor = value.constructor;
+    // Handle registered class instances
+    if (ctor && ctor.name && class_registry[ctor.name]) {
+        const props = {};
+        // Extract own enumerable properties (bypass any toJSON method)
+        for (const key of Object.keys(value)) {
+            const propValue = value[key];
+            const processed = process_for_serialization(propValue, verbose, seen);
+            // Only include if not undefined (failed serialization)
+            if (processed !== undefined || propValue === undefined) {
+                props[key] = processed;
+            }
+        }
+        return {
+            [CLASS_MARKER]: ctor.name,
+            [PROPS_MARKER]: props
+        };
+    }
+    // Handle plain objects (constructor is Object or no constructor)
+    if (ctor === Object || ctor === undefined || ctor === null) {
+        const result = {};
+        for (const key of Object.keys(value)) {
+            const propValue = value[key];
+            const processed = process_for_serialization(propValue, verbose, seen);
+            // Only include if not undefined (unless original was undefined)
+            if (processed !== undefined || propValue === undefined) {
+                result[key] = processed;
+            }
+        }
+        return result;
+    }
+    // Unregistered class instance - convert to plain object for hot/cold parity
+    // This ensures developers catch missing class registrations during development
+    // (methods will be lost, only properties preserved)
+    if (verbose) {
+        console.warn(`[JQHTML Cache] Converting unregistered class "${ctor.name}" to plain object. ` +
+            `Methods will be lost. Call jqhtml.register_cache_class(${ctor.name}) to preserve the class.`);
+    }
+    // Convert to plain object - properties are preserved, prototype methods are lost
+    const result = {};
+    for (const key of Object.keys(value)) {
+        const propValue = value[key];
+        const processed = process_for_serialization(propValue, verbose, seen);
+        // Only include if not undefined (unless original was undefined)
+        if (processed !== undefined || propValue === undefined) {
+            result[key] = processed;
+        }
+    }
+    return result;
+}
+// ============================================================================
+// Deserialization (String → Object)
+// ============================================================================
+/**
+ * Deserialize a JSON string, restoring ES6 class instances.
+ * Returns null if deserialization fails.
+ *
+ * @param str - The JSON string to deserialize
+ * @param verbose - Whether to log warnings
+ * @returns Deserialized value with class instances restored, or null if failed
+ */
+function deserialize_value(str, verbose) {
+    try {
+        const parsed = JSON.parse(str);
+        return process_for_deserialization(parsed, verbose);
+    }
+    catch (e) {
+        if (verbose) {
+            console.warn('[JQHTML Cache] Deserialization failed:', e);
+        }
+        return null;
+    }
+}
+/**
+ * Recursively process a parsed value, restoring class instances.
+ *
+ * @param value - The parsed value to process
+ * @param verbose - Whether to log warnings
+ * @returns Processed value with class instances restored
+ */
+function process_for_deserialization(value, verbose) {
+    // Handle primitives and null
+    if (value === null || value === undefined || typeof value !== 'object') {
+        return value;
+    }
+    // Handle arrays
+    if (Array.isArray(value)) {
+        return value.map(item => process_for_deserialization(item, verbose));
+    }
+    // Check for class marker
+    if (value[CLASS_MARKER] !== undefined && value[PROPS_MARKER] !== undefined) {
+        const class_name = value[CLASS_MARKER];
+        const props = value[PROPS_MARKER];
+        // Handle built-in types
+        if (class_name === 'Date') {
+            return new Date(props);
+        }
+        if (class_name === 'Map') {
+            const map = new Map();
+            for (const [k, v] of props) {
+                map.set(process_for_deserialization(k, verbose), process_for_deserialization(v, verbose));
+            }
+            return map;
+        }
+        if (class_name === 'Set') {
+            const set = new Set();
+            for (const item of props) {
+                set.add(process_for_deserialization(item, verbose));
+            }
+            return set;
+        }
+        // Look up registered class
+        const klass = class_registry[class_name];
+        if (!klass) {
+            if (verbose) {
+                console.warn(`[JQHTML Cache] Cannot restore class "${class_name}" - not registered. ` +
+                    `Data will be returned as plain object. ` +
+                    `Call jqhtml.register_cache_class(${class_name}) to restore class instances.`);
+            }
+            // Return as plain object rather than failing completely
+            return process_for_deserialization(props, verbose);
+        }
+        // Create instance without calling constructor and assign properties
+        try {
+            const instance = Object.create(klass.prototype);
+            const processed_props = process_for_deserialization(props, verbose);
+            Object.assign(instance, processed_props);
+            return instance;
+        }
+        catch (e) {
+            if (verbose) {
+                console.warn(`[JQHTML Cache] Failed to restore class "${class_name}":`, e);
+            }
+            // Return null to signal cache should be treated as miss
+            return null;
+        }
+    }
+    // Plain object - process recursively
+    const result = {};
+    for (const key of Object.keys(value)) {
+        result[key] = process_for_deserialization(value[key], verbose);
+    }
+    return result;
+}
 class Jqhtml_Local_Storage {
     /**
      * Set the cache key and initialize storage
      * Must be called before any get/set operations
      * @param {string} cache_key - Unique identifier for this cache scope
+     * @param {CacheMode} cache_mode - Cache strategy: 'data' (default, recommended) or 'html'
      */
-    static set_cache_key(cache_key) {
+    static set_cache_key(cache_key, cache_mode = 'data') {
         this._cache_key = cache_key;
+        this._cache_mode = cache_mode;
         this._init();
     }
     /**
@@ -3565,6 +4088,13 @@ class Jqhtml_Local_Storage {
     static has_cache_key() {
         return this._cache_key !== null;
     }
+    /**
+     * Get the current cache mode
+     * @returns {CacheMode} Current cache mode ('data' or 'html')
+     */
+    static get_cache_mode() {
+        return this._cache_mode;
+    }
     /**
      * Initialize storage system and validate scope
      * Called automatically after cache key is set
@@ -3599,6 +4129,13 @@ class Jqhtml_Local_Storage {
             return false;
         }
     }
+    /**
+     * Check if verbose mode is enabled
+     * @private
+     */
+    static _is_verbose() {
+        return window.jqhtml?.debug?.verbose === true;
+    }
     /**
      * Validate storage scope and clear JQHTML keys if cache key changed
      * Only clears keys prefixed with 'jqhtml::' to preserve other libraries' data
@@ -3677,34 +4214,90 @@ class Jqhtml_Local_Storage {
         return this._storage_available === true && this._cache_key !== null && this._initialized;
     }
     /**
-     * Set item in localStorage
+     * Set item in localStorage with class-aware serialization.
+     *
+     * If serialization fails (e.g., unregistered class instances, circular refs),
+     * the existing cache entry is removed and nothing is stored.
+     *
      * @param {string} key - Storage key
-     * @param {*} value - Value to store (will be JSON serialized)
+     * @param {*} value - Value to store (primitives, objects, arrays, or registered class instances)
      */
     static set(key, value) {
         if (!this._is_ready()) {
             return;
         }
+        const verbose = this._is_verbose();
+        const scoped_key = this._build_key(key);
+        // Serialize with class-aware processing
+        const serialized = serialize_value(value, verbose);
+        if (serialized === null) {
+            // Serialization failed - remove any existing cache entry
+            if (verbose) {
+                console.warn(`[JQHTML Cache] Failed to serialize value for key "${key}". ` +
+                    `Removing existing cache entry if present.`);
+            }
+            try {
+                localStorage.removeItem(scoped_key);
+            }
+            catch (e) {
+                // Ignore removal errors
+            }
+            return;
+        }
         // Check size before attempting to store (1MB limit)
-        const serialized = JSON.stringify(value);
         const size_bytes = new Blob([serialized]).size;
         const size_mb = size_bytes / (1024 * 1024);
         if (size_mb > 1) {
-            console.warn(`[JQHTML Local Storage] Skipping set - value too large (${size_mb.toFixed(2)}MB > 1MB limit)`, { key, size_bytes, size_mb });
+            if (verbose) {
+                console.warn(`[JQHTML Cache] Skipping set - value too large (${size_mb.toFixed(2)}MB > 1MB limit)`, { key, size_bytes, size_mb });
+            }
+            // Remove existing cache entry since we can't update it
+            try {
+                localStorage.removeItem(scoped_key);
+            }
+            catch (e) {
+                // Ignore removal errors
+            }
             return;
         }
-        this._set_item(key, value, serialized);
+        this._set_item(key, serialized);
     }
     /**
-     * Get item from localStorage
+     * Get item from localStorage with class-aware deserialization.
+     *
+     * If deserialization fails, returns null (as if no cache exists).
+     *
      * @param {string} key - Storage key
-     * @returns {*|null} Parsed value or null if not found/unavailable
+     * @returns {*|null} Deserialized value with class instances restored, or null if not found/failed
      */
     static get(key) {
         if (!this._is_ready()) {
             return null;
         }
-        return this._get_item(key);
+        const verbose = this._is_verbose();
+        const scoped_key = this._build_key(key);
+        try {
+            const serialized = localStorage.getItem(scoped_key);
+            if (serialized === null) {
+                return null;
+            }
+            const result = deserialize_value(serialized, verbose);
+            if (result === null) {
+                // Deserialization failed - treat as cache miss
+                if (verbose) {
+                    console.warn(`[JQHTML Cache] Failed to deserialize value for key "${key}". ` +
+                        `Treating as cache miss.`);
+                }
+                return null;
+            }
+            return result;
+        }
+        catch (e) {
+            if (verbose) {
+                console.warn('[JQHTML Cache] Failed to get item:', e);
+            }
+            return null;
+        }
     }
     /**
      * Remove item from localStorage
@@ -3716,14 +4309,49 @@ class Jqhtml_Local_Storage {
         }
         this._remove_item(key);
     }
+    /**
+     * Perform a serialize/deserialize round-trip on a value.
+     *
+     * This ensures "hot" data (fresh from on_load) behaves identically to "cold" data
+     * (restored from cache). Unregistered class instances will be converted to plain
+     * objects, exactly as they would be if restored from cache.
+     *
+     * Use this to normalize data after on_load() so developers catch missing class
+     * registrations immediately rather than only after a page reload.
+     *
+     * @param {any} value - The value to normalize
+     * @returns {any} The value after serialize/deserialize round-trip, or original if serialization fails
+     */
+    static normalize_for_cache(value) {
+        const verbose = this._is_verbose();
+        // Serialize to JSON string
+        const serialized = serialize_value(value, verbose);
+        if (serialized === null) {
+            // Serialization failed completely - return original
+            // (This happens with circular references or other fatal issues)
+            if (verbose) {
+                console.warn('[JQHTML Cache] normalize_for_cache: Serialization failed, returning original value');
+            }
+            return value;
+        }
+        // Deserialize back to object
+        const deserialized = deserialize_value(serialized, verbose);
+        if (deserialized === null) {
+            // Deserialization failed - return original
+            if (verbose) {
+                console.warn('[JQHTML Cache] normalize_for_cache: Deserialization failed, returning original value');
+            }
+            return value;
+        }
+        return deserialized;
+    }
     /**
      * Internal set implementation with scope validation and quota handling
      * @param {string} key
-     * @param {*} value - Original value (not used, kept for clarity)
      * @param {string} serialized - Pre-serialized JSON string
      * @private
      */
-    static _set_item(key, value, serialized) {
+    static _set_item(key, serialized) {
         // Validate scope before every write
         this._validate_scope();
         const scoped_key = this._build_key(key);
@@ -3749,26 +4377,6 @@ class Jqhtml_Local_Storage {
             }
         }
     }
-    /**
-     * Internal get implementation
-     * @param {string} key
-     * @returns {*|null}
-     * @private
-     */
-    static _get_item(key) {
-        const scoped_key = this._build_key(key);
-        try {
-            const serialized = localStorage.getItem(scoped_key);
-            if (serialized === null) {
-                return null;
-            }
-            return JSON.parse(serialized);
-        }
-        catch (e) {
-            console.error('[JQHTML Local Storage] Failed to get item:', e);
-            return null;
-        }
-    }
     /**
      * Internal remove implementation
      * @param {string} key
@@ -3785,12 +4393,14 @@ class Jqhtml_Local_Storage {
     }
 }
 Jqhtml_Local_Storage._cache_key = null;
+Jqhtml_Local_Storage._cache_mode = 'data';
 Jqhtml_Local_Storage._storage_available = null;
 Jqhtml_Local_Storage._initialized = false;
 
 var localStorage$1 = /*#__PURE__*/Object.freeze({
     __proto__: null,
-    Jqhtml_Local_Storage: Jqhtml_Local_Storage
+    Jqhtml_Local_Storage: Jqhtml_Local_Storage,
+    register_cache_class: register_cache_class
 });
 
 /**
@@ -4053,7 +4663,7 @@ function init(jQuery) {
     }
 }
 // Version - will be replaced during build with actual version from package.json
-const version = '2.3.11';
+const version = '2.3.13';
 // Default export with all functionality
 const jqhtml = {
     // Core
@@ -4137,9 +4747,17 @@ const jqhtml = {
         return version;
     },
     // Cache key setter - enables component caching via local storage
-    set_cache_key(cache_key) {
-        Jqhtml_Local_Storage.set_cache_key(cache_key);
+    // cache_mode: 'data' (default, recommended) or 'html'
+    set_cache_key(cache_key, cache_mode = 'data') {
+        Jqhtml_Local_Storage.set_cache_key(cache_key, cache_mode);
+    },
+    // Get current cache mode
+    get_cache_mode() {
+        return Jqhtml_Local_Storage.get_cache_mode();
     },
+    // Register a class for cache serialization/deserialization
+    // Required for ES6 class instances to be stored and restored from localStorage
+    register_cache_class,
     // Boot - hydrate server-rendered component placeholders
     boot
 };
@@ -4159,5 +4777,5 @@ if (typeof window !== 'undefined' && !window.jqhtml) {
     }
 }
 
-export { Jqhtml_Component, LifecycleManager as Jqhtml_LifecycleManager, Jqhtml_Local_Storage, LifecycleManager, Load_Coordinator, applyDebugDelay, boot, create_component, jqhtml as default, devWarn, escape_html, extract_slots, get_component_class, get_component_names, get_registered_templates, get_template, get_template_by_class, handleComponentError, has_component, init, init_jquery_plugin, isSequentialProcessing, list_components, logDataChange, logDispatch, logInstruction, logLifecycle, process_instructions, register, register_component, register_template, render_template, version };
+export { Jqhtml_Component, LifecycleManager as Jqhtml_LifecycleManager, Jqhtml_Local_Storage, LifecycleManager, Load_Coordinator, applyDebugDelay, boot, create_component, jqhtml as default, devWarn, escape_html, extract_slots, get_component_class, get_component_names, get_registered_templates, get_template, get_template_by_class, handleComponentError, has_component, init, init_jquery_plugin, isSequentialProcessing, list_components, logDataChange, logDispatch, logInstruction, logLifecycle, process_instructions, register, register_cache_class, register_component, register_template, render_template, version };
 //# sourceMappingURL=index.js.map