@jqhtml/core 2.3.70 → 2.3.71

package/dist/index.js

@@ -1505,309 +1505,6 @@ function serialize_for_cache_key(value) {
     }
 }
 
-/**
- * Load Coordinator - Request deduplication for component on_load() calls
- *
- * Coordinates parallel component loading to prevent duplicate requests.
- * When multiple components with identical names and args load simultaneously,
- * only the first (leader) executes on_load(). Others (followers) wait for
- * the leader's result.
- *
- * Key Concepts:
- * - **INVOCATION_KEY**: Unique identifier for component name + args combination
- * - **Leader**: First component to reach on_load() for a given INVOCATION_KEY
- * - **Follower**: Subsequent components that wait for leader's result
- *
- * Lifecycle:
- * 1. Leader reaches on_load() → create coordination entry
- * 2. Followers reach on_load() → join waiting queue
- * 3. Leader completes → distribute data to all followers
- * 4. Clear coordination entry (no caching)
- *
- * @internal This class is not exposed in the public API
- */
-class Load_Coordinator {
-    /**
-     * Generate INVOCATION_KEY from component name and args
-     * Uses deterministic JSON serialization (sorted keys)
-     * Excludes internal properties (those starting with _)
-     *
-     * For functions/objects:
-     * - Checks for ._jqhtml_cache_id property (assigned by RSpade)
-     * - Falls back to .jqhtml_cache_id() method if property doesn't exist
-     * - If neither exists, marks property as uncacheable
-     *
-     * Returns object with:
-     * - key: Cache key string, or null if uncacheable
-     * - uncacheable_property: Name of first property that prevented caching (for debugging)
-     */
-    static generate_invocation_key(component_name, args, options = {}) {
-        let uncacheable_property;
-        let uncacheable_reason;
-        // Filter out internal properties (starting with _) and serialize args
-        const serializable_args = {};
-        for (const key of Object.keys(args).sort()) {
-            if (key.startsWith('_')) {
-                continue; // Skip internal properties
-            }
-            // Skip framework properties that shouldn't affect cache identity
-            // Note: _load_only and _load_render_only are already filtered by the _ prefix check above
-            if (key === 'use_cached_data') {
-                continue;
-            }
-            const value = args[key];
-            const value_type = typeof value;
-            // Handle primitives (string, number, boolean, null, undefined)
-            if (value === null || value === undefined ||
-                value_type === 'string' || value_type === 'number' ||
-                value_type === 'boolean') {
-                serializable_args[key] = value;
-                continue;
-            }
-            // Handle functions and objects
-            if (value_type === 'function' || value_type === 'object') {
-                // Check for ._jqhtml_cache_id property (fastest, what RSpade assigns)
-                if (value._jqhtml_cache_id !== undefined) {
-                    serializable_args[key] = `__JQHTML_CACHE_ID__:${String(value._jqhtml_cache_id)}`;
-                    continue;
-                }
-                // Check for .jqhtml_cache_id() method (more flexible, for custom objects)
-                if (typeof value.jqhtml_cache_id === 'function') {
-                    try {
-                        const cache_id = value.jqhtml_cache_id();
-                        serializable_args[key] = `__JQHTML_CACHE_ID__:${String(cache_id)}`;
-                        continue;
-                    }
-                    catch (error) {
-                        // Method threw error - treat as uncacheable
-                        if (!uncacheable_property) {
-                            uncacheable_property = key;
-                            uncacheable_reason = 'cache-id-threw';
-                        }
-                        return { key: null, uncacheable_property, uncacheable_reason };
-                    }
-                }
-                // No author-supplied id. The cache may fall back to keying by
-                // deterministic content; deduplication deliberately may not.
-                if (options.allow_content_serialization) {
-                    const serialized = serialize_for_cache_key(value);
-                    if (serialized.ok) {
-                        serializable_args[key] = `__JQHTML_CONTENT__:${serialized.text}`;
-                        continue;
-                    }
-                    if (!uncacheable_property) {
-                        uncacheable_property = key;
-                        // This package compiles with strictNullChecks off, and without it
-                        // TypeScript will not narrow a discriminated union by its boolean
-                        // discriminant - so `serialized` is still the full Serialize_Result
-                        // here even though `ok` has been ruled out above. The cast states
-                        // what the control flow already guarantees.
-                        uncacheable_reason = serialized.reason;
-                    }
-                    return { key: null, uncacheable_property, uncacheable_reason };
-                }
-                if (!uncacheable_property) {
-                    uncacheable_property = key;
-                    uncacheable_reason = value_type === 'function' ? 'function' : 'object';
-                }
-                return { key: null, uncacheable_property, uncacheable_reason };
-            }
-            // Unknown type (symbol, bigint, etc.) - uncacheable
-            if (!uncacheable_property) {
-                uncacheable_property = key;
-                uncacheable_reason = value_type;
-            }
-            return { key: null, uncacheable_property, uncacheable_reason };
-        }
-        // Try to serialize - if it fails (shouldn't happen now, but safety net), return null
-        try {
-            const sorted_args = JSON.stringify(serializable_args);
-            return { key: `${component_name}::${sorted_args}` };
-        }
-        catch (error) {
-            // Serialization failed unexpectedly
-            return { key: null, uncacheable_property };
-        }
-    }
-    /**
-     * Check if a component should execute on_load() or wait for existing request
-     * Returns true if component should execute (is leader), false if should wait (is follower)
-     *
-     * @param key - The dedup key the caller captured for this load. Every coordinator
-     *              method takes it, because args may legally change during on_load()
-     *              and a recomputed key would address a different (or no) entry.
-     */
-    static should_execute_on_load(component, key) {
-        const entry = this._registry.get(key);
-        if (!entry) {
-            // No existing request - this component becomes the leader
-            return true;
-        }
-        if (entry.status === 'loading') {
-            // Request in progress - this component becomes a follower
-            entry.waiting.push(component);
-            return false;
-        }
-        // Entry exists but completed/failed - should have been cleaned up
-        // Treat as new leader
-        return true;
-    }
-    /**
-     * Register a leader component that will execute on_load()
-     * Creates coordination entry and returns a function to call when data is ready
-     *
-     * @param key - The dedup key captured by the caller (see should_execute_on_load)
-     * @returns A function that accepts the final data and completes coordination
-     */
-    static register_leader(component, key) {
-        // Create a promise that we control - it settles when coordination completes or fails
-        let resolve_promise;
-        let reject_promise;
-        const coordination_promise = new Promise((resolve, reject) => {
-            resolve_promise = resolve;
-            reject_promise = reject;
-        });
-        // A leader with no followers still has to be able to reject this promise on
-        // error; without a handler that rejection surfaces as an unhandled rejection.
-        coordination_promise.catch(() => { });
-        const entry = {
-            status: 'loading',
-            promise: coordination_promise, // Followers await THIS promise, not on_load's
-            resolve_promise,
-            reject_promise,
-            leader_component: component,
-            leader_data: null,
-            waiting: []
-        };
-        this._registry.set(key, entry);
-        // Return cleanup function that accepts the final data
-        return (final_data) => this._complete_coordination(key, component, final_data);
-    }
-    /**
-     * Get the coordination promise for a follower component
-     * Returns a promise that resolves when the leader completes, or rejects if it failed
-     */
-    static get_coordination_promise(key) {
-        const entry = this._registry.get(key);
-        if (!entry || entry.status !== 'loading') {
-            return null;
-        }
-        return entry.promise;
-    }
-    /**
-     * Complete coordination after leader's on_load() finishes
-     * Stores leader's data, marks entry as completed, and resolves the promise.
-     * Followers retrieve the data themselves via get_leader_data().
-     *
-     * @param key - The coordination key captured at registration
-     * @param leader - The leader component
-     * @param final_data - The final data after on_load and normalization
-     * @private
-     */
-    static _complete_coordination(key, leader, final_data) {
-        const entry = this._registry.get(key);
-        if (!entry) {
-            return;
-        }
-        // Stored as TEXT so each follower parses its own object graph - sharing one
-        // decoded object would let one component's mutation reach every other.
-        try {
-            entry.leader_data = JSON.stringify(final_data);
-        }
-        catch (error) {
-            // Unserializable data cannot be shared; followers load independently.
-            entry.leader_data = null;
-        }
-        entry.status = 'completed';
-        if (window.jqhtml?.debug?.verbose) {
-            console.log(`[Load Coordinator] Leader ${leader._cid} completed, data available for ${entry.waiting.length} followers`, { key, data: entry.leader_data });
-        }
-        // Resolve the promise - followers waiting on it will now wake up
-        entry.resolve_promise();
-        // Nobody is waiting, so nothing will ever come back to collect the data.
-        // Without this the registry grows once per distinct name+args, forever.
-        if (entry.waiting.length === 0) {
-            this._registry.delete(key);
-        }
-    }
-    /**
-     * Get leader's data for a follower component
-     * Called by follower after coordination promise resolves
-     * Returns a freshly parsed copy and cleans up if this is the last follower
-     *
-     * @param key - The dedup key captured by the follower before it began waiting
-     */
-    static get_leader_data(component, key) {
-        const entry = this._registry.get(key);
-        if (!entry || entry.status !== 'completed' || entry.leader_data === null) {
-            return null;
-        }
-        // Remove this follower from the waiting list
-        const follower_index = entry.waiting.indexOf(component);
-        if (follower_index !== -1) {
-            entry.waiting.splice(follower_index, 1);
-        }
-        // One parse per follower: each gets its OWN object, never a shared reference.
-        const data = JSON.parse(entry.leader_data);
-        if (window.jqhtml?.debug?.verbose) {
-            console.log(`[Load Coordinator] Follower ${component._cid} retrieving data from leader ${entry.leader_component._cid}`, { key, remaining_followers: entry.waiting.length });
-        }
-        // If this was the last follower, clean up the entry
-        if (entry.waiting.length === 0) {
-            this._registry.delete(key);
-            if (window.jqhtml?.debug?.verbose) {
-                console.log(`[Load Coordinator] Coordination complete for key: ${key}`, { registry_size: this._registry.size });
-            }
-        }
-        return data;
-    }
-    /**
-     * Handle leader on_load() error
-     * Rejects every waiting follower and clears the entry so the next component retries
-     *
-     * @param key - The dedup key captured at registration
-     */
-    static handle_leader_error(key, error) {
-        const entry = this._registry.get(key);
-        if (!entry) {
-            return;
-        }
-        entry.status = 'failed';
-        console.error(`[Load Coordinator] Leader ${entry.leader_component._cid} on_load() failed for key: ${key}`, error);
-        // Reject FIRST: followers are parked on this promise and their catch in _load()
-        // propagates the failure exactly as if their own on_load() had thrown. Deleting
-        // without rejecting left them awaiting a promise nobody could ever settle.
-        entry.reject_promise(error);
-        // Clear coordination entry so future requests can retry
-        this._registry.delete(key);
-        if (window.jqhtml?.debug?.verbose) {
-            console.log(`[Load Coordinator] Cleared failed coordination for key: ${key}`, { followers_count: entry.waiting.length });
-        }
-    }
-    /**
-     * Get current registry state (for debugging)
-     */
-    static get_registry_state() {
-        const state = {};
-        for (const [key, entry] of this._registry.entries()) {
-            state[key] = {
-                status: entry.status,
-                leader_cid: entry.leader_component._cid,
-                waiting_count: entry.waiting.length,
-                waiting_cids: entry.waiting.map(c => c._cid)
-            };
-        }
-        return state;
-    }
-    /**
-     * Clear all coordination entries (for testing/debugging)
-     */
-    static clear_all() {
-        this._registry.clear();
-    }
-}
-Load_Coordinator._registry = new Map();
-
 /**
  * Jqhtml_Local_Storage - Scoped local storage for JQHTML component caching
  *
@@ -1826,7 +1523,19 @@ Load_Coordinator._registry = new Map();
  * 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.
+ * and arrays are handled recursively. A class whose wire form is not its own
+ * properties (one that defines toJSON(), or keeps state in private fields)
+ * registers a {to_plain, from_plain} pair and is rebuilt through it. Date, Map and
+ * Set are pre-registered the same way - there is no second mechanism.
+ *
+ * ONE SERIALIZER. Every copy of on_load() data the framework makes goes through
+ * this file: the localStorage cache (set()/get()), the normalization of every
+ * on_load() result into this.data (normalize_for_cache()), and the copy a
+ * deduplicated follower takes of its leader's data (serialize()/deserialize(),
+ * used by load-coordinator.ts). Anything that survives one of those survives all
+ * of them, and anything dropped is dropped identically on all of them. A plain
+ * JSON.stringify anywhere on those paths would consult toJSON() and hand out a
+ * wire form nothing knows how to restore.
  *
  * Scoping Strategy:
  * Storage is scoped by a user-provided cache key (typically a session identifier,
@@ -1902,14 +1611,11 @@ Load_Coordinator._registry = new Map();
  *       silently. Neither ever throws.
  * ---------------------------------------------------------------------------
  */
-// ============================================================================
-// Class Registry for Serialization
-// ============================================================================
-// Registry mapping class names to constructors
+// Registry mapping class names to constructors and their restore hooks
 const class_registry = Object.create(null);
 // Markers for serialized class instances (unique to avoid collisions with user data)
 // Replaced at build time by rollup (see rollup.config.js).
-const CORE_VERSION = '2.3.70';
+const CORE_VERSION = '2.3.71';
 const CLASS_MARKER = '__jqhtml_class__';
 const PROPS_MARKER = '__jqhtml_props__';
 /**
@@ -1917,13 +1623,56 @@ const PROPS_MARKER = '__jqhtml_props__';
  * 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
+ * @param options - How to convert instances to and from their plain form; see
+ *                  Cache_Class_Options. Omit for a class whose state is its own
+ *                  enumerable properties.
+ * @throws Error if klass is not a named function/class, or if to_plain is given
+ *         without the from_plain that undoes it
  */
-function register_cache_class(klass) {
+function register_cache_class(klass, options = {}) {
     if (typeof klass !== 'function' || !klass.name) {
         throw new Error('[JQHTML Cache] register_cache_class requires a named class constructor');
     }
-    class_registry[klass.name] = klass;
+    const to_plain = typeof options.to_plain === 'function' ? options.to_plain : null;
+    const from_plain = typeof options.from_plain === 'function' ? options.from_plain : null;
+    if (to_plain && !from_plain) {
+        throw new Error(`[JQHTML Cache] register_cache_class(${klass.name}): to_plain needs a from_plain. ` +
+            `The serializer cannot rebuild an instance from a custom wire form on its own.`);
+    }
+    class_registry[klass.name] = { klass, to_plain, from_plain };
+}
+// Built-ins travel through the same hook as user classes. Their wire forms are
+// the ones the cache has always stored (ISO string, entry pairs, item list), so
+// entries written before this existed still restore.
+register_cache_class(Date, {
+    to_plain: (date) => date.toISOString(),
+    from_plain: (iso) => new Date(iso)
+});
+register_cache_class(Map, {
+    to_plain: (map) => Array.from(map.entries()),
+    from_plain: (entries) => new Map(entries)
+});
+register_cache_class(Set, {
+    to_plain: (set) => Array.from(set),
+    from_plain: (items) => new Set(items)
+});
+/**
+ * Find the registry entry for a live value: by constructor name first, then by
+ * instanceof for the built-ins so a subclass of Date/Map/Set (whose name is not
+ * registered) still serializes as the built-in it is.
+ */
+function lookup_registered(value) {
+    const ctor = value.constructor;
+    if (ctor && ctor.name && class_registry[ctor.name]) {
+        return { name: ctor.name, entry: class_registry[ctor.name] };
+    }
+    if (value instanceof Date)
+        return { name: 'Date', entry: class_registry['Date'] };
+    if (value instanceof Map)
+        return { name: 'Map', entry: class_registry['Map'] };
+    if (value instanceof Set)
+        return { name: 'Set', entry: class_registry['Set'] };
+    return null;
 }
 /**
  * Serialize a value to JSON string, handling ES6 class instances recursively.
@@ -2050,48 +1799,20 @@ function process_for_serialization(value, verbose, seen, path = '', collector) {
             }
             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 entry_path = collector ? `${path}.get(${String(k)})` : '';
-                const processedKey = process_for_serialization(k, verbose, seen, entry_path, collector);
-                const processedValue = process_for_serialization(v, verbose, seen, entry_path, collector);
-                entries.push([processedKey, processedValue]);
-            }
-            return {
-                [CLASS_MARKER]: 'Map',
-                [PROPS_MARKER]: entries
-            };
-        }
-        // Handle Set objects
-        if (value instanceof Set) {
-            const items = [];
-            let index = 0;
-            for (const item of value) {
-                items.push(process_for_serialization(item, verbose, seen, collector ? `${path}[Set ${index++}]` : '', collector));
+        // Registered classes - Date, Map and Set included - go out as
+        // {__jqhtml_class__, __jqhtml_props__} through their restore hook.
+        const registered = lookup_registered(value);
+        if (registered) {
+            const plain = registered_plain_form(registered, value, verbose, seen, path, collector);
+            if (plain === undefined) {
+                return undefined; // to_plain threw; the value is dropped, and reported
             }
             return {
-                [CLASS_MARKER]: 'Set',
-                [PROPS_MARKER]: items
+                [CLASS_MARKER]: registered.name,
+                [PROPS_MARKER]: plain
             };
         }
-        // Get the constructor
         const ctor = value.constructor;
-        // Handle registered class instances
-        if (ctor && ctor.name && class_registry[ctor.name]) {
-            return {
-                [CLASS_MARKER]: ctor.name,
-                [PROPS_MARKER]: process_own_properties(value, verbose, seen, path, collector)
-            };
-        }
         // Handle plain objects (constructor is Object or no constructor)
         if (ctor === Object || ctor === undefined || ctor === null) {
             return process_own_properties(value, verbose, seen, path, collector);
@@ -2105,12 +1826,54 @@ function process_for_serialization(value, verbose, seen, path = '', collector) {
             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.`);
         }
-        return process_own_properties(value, verbose, seen, path, collector);
+        return process_own_properties(value, verbose, seen, path, collector);
+    }
+    finally {
+        // Pop this object off the ancestor path now that its subtree is done.
+        seen.delete(value);
+    }
+}
+/**
+ * The plain value stored for a registered instance.
+ *
+ * No from_plain: own enumerable properties (toJSON() is deliberately bypassed,
+ * because Object.assign is the only way back and it needs the properties).
+ * With from_plain: to_plain(instance), or toJSON() when the class defines one,
+ * or own properties as the last resort. Whatever comes back is walked by the
+ * serializer like any other value.
+ *
+ * Returns undefined when to_plain threw - the caller drops the value.
+ */
+function registered_plain_form(registered, value, verbose, seen, path, collector) {
+    const { name, entry } = registered;
+    if (!entry.from_plain) {
+        return process_own_properties(value, verbose, seen, path, collector);
+    }
+    let plain;
+    try {
+        if (entry.to_plain) {
+            plain = entry.to_plain(value);
+        }
+        else if (typeof value.toJSON === 'function') {
+            plain = value.toJSON();
+        }
+        else {
+            return process_own_properties(value, verbose, seen, path, collector);
+        }
+    }
+    catch (e) {
+        collector?.(path, 'to-plain-threw', name);
+        if (verbose) {
+            console.warn(`[JQHTML Cache] to_plain for class "${name}" threw - value will be omitted:`, e);
+        }
+        return undefined;
     }
-    finally {
-        // Pop this object off the ancestor path now that its subtree is done.
-        seen.delete(value);
+    // A toJSON() that returns `this` has no separate wire form; own properties it is.
+    if (plain === value) {
+        return process_own_properties(value, verbose, seen, path, collector);
     }
+    const processed = process_for_serialization(plain, verbose, seen, path, collector);
+    return processed === undefined ? null : processed;
 }
 /**
  * Walk an object's own enumerable properties (bypassing any toJSON) into a plain
@@ -2167,7 +1930,11 @@ function strip_advice(kind, detail) {
         case 'unregistered-class':
             return `it is an instance of the unregistered class "${detail}", so it was degraded to a plain ` +
                 `object and its methods are gone. Call jqhtml.register_cache_class(${detail}) at startup ` +
-                `to get real instances back.`;
+                `to get real instances back - with { from_plain } if the class defines toJSON() or keeps ` +
+                `state outside its own properties.`;
+        case 'to-plain-threw':
+            return `the to_plain hook registered for class "${detail}" threw, so the value was dropped. ` +
+                `Make to_plain total over every instance the class can produce.`;
     }
 }
 /**
@@ -2239,27 +2006,9 @@ function process_for_deserialization(value, verbose) {
     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) {
+        // Look up registered class (Date, Map and Set are registered like any other)
+        const entry = class_registry[class_name];
+        if (!entry) {
             if (verbose) {
                 console.warn(`[JQHTML Cache] Cannot restore class "${class_name}" - not registered. ` +
                     `Data will be returned as plain object. ` +
@@ -2268,10 +2017,14 @@ function process_for_deserialization(value, verbose) {
             // Return as plain object rather than failing completely
             return process_for_deserialization(props, verbose);
         }
-        // Create instance without calling constructor and assign properties
+        // Restore through from_plain when the class has one; otherwise create an
+        // instance without calling the constructor and assign the properties back.
         try {
-            const instance = Object.create(klass.prototype);
             const processed_props = process_for_deserialization(props, verbose);
+            if (entry.from_plain) {
+                return entry.from_plain(processed_props);
+            }
+            const instance = Object.create(entry.klass.prototype);
             Object.assign(instance, processed_props);
             return instance;
         }
@@ -2344,290 +2097,624 @@ class Jqhtml_Local_Storage {
      * @returns {boolean}
      * @private
      */
-    static _is_storage_available() {
+    static _is_storage_available() {
+        try {
+            const storage = window.localStorage;
+            const test = '__jqhtml_storage_test__';
+            storage.setItem(test, test);
+            storage.removeItem(test);
+            return true;
+        }
+        catch (e) {
+            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
+     * @private
+     */
+    static _validate_scope() {
+        if (!this._storage_available) {
+            return;
+        }
+        try {
+            const stored_key = localStorage.getItem('_jqhtml_cache_key');
+            // If the scope marker (core version + developer key) changed, clear only JQHTML keys
+            if (stored_key !== null && stored_key !== this._scope_marker) {
+                console.log('[JQHTML Local Storage] Cache scope changed, clearing JQHTML keys:', {
+                    old_key: stored_key,
+                    new_key: this._scope_marker,
+                });
+                this._clear_jqhtml_keys();
+                localStorage.setItem('_jqhtml_cache_key', this._scope_marker);
+            }
+            else if (stored_key === null) {
+                // First time JQHTML is using this storage - just set the key, don't clear
+                console.log('[JQHTML Local Storage] Initializing cache scope (first use):', {
+                    new_key: this._scope_marker,
+                });
+                localStorage.setItem('_jqhtml_cache_key', this._scope_marker);
+            }
+        }
+        catch (e) {
+            console.error('[JQHTML Local Storage] Failed to validate scope:', e);
+        }
+    }
+    /**
+     * Clear only JQHTML keys from storage (keys starting with 'jqhtml::')
+     * Preserves keys from other libraries
+     * @private
+     */
+    static _clear_jqhtml_keys() {
+        if (!this._storage_available) {
+            return;
+        }
+        const keys_to_remove = [];
+        // Collect all JQHTML keys
+        for (let i = 0; i < localStorage.length; i++) {
+            const key = localStorage.key(i);
+            if (key && key.startsWith('jqhtml::')) {
+                keys_to_remove.push(key);
+            }
+        }
+        // Remove collected keys
+        keys_to_remove.forEach(key => {
+            try {
+                localStorage.removeItem(key);
+            }
+            catch (e) {
+                console.error('[JQHTML Local Storage] Failed to remove key:', key, e);
+            }
+        });
+        console.log(`[JQHTML Local Storage] Cleared ${keys_to_remove.length} JQHTML keys`);
+    }
+    /**
+     * Build scoped key with JQHTML namespace prefix
+     * @param {string} key - Developer-provided key
+     * @returns {string}
+     * @private
+     */
+    static _build_key(key) {
+        return `jqhtml::${key}::${this._cache_key}`;
+    }
+    /**
+     * Check if storage is ready for use
+     * @returns {boolean}
+     * @private
+     */
+    static _is_ready() {
+        return this._storage_available === true && this._cache_key !== null && this._initialized;
+    }
+    /**
+     * 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 (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 size_bytes = new Blob([serialized]).size;
+        const size_mb = size_bytes / (1024 * 1024);
+        if (size_mb > 1) {
+            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, serialized);
+    }
+    /**
+     * 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} Deserialized value with class instances restored, or null if not found/failed
+     */
+    static get(key) {
+        if (!this._is_ready()) {
+            return null;
+        }
+        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
+     * @param {string} key - Storage key
+     */
+    static remove(key) {
+        if (!this._is_ready()) {
+            return;
+        }
+        this._remove_item(key);
+    }
+    /**
+     * Serialize a value to its class-aware TEXT form - the same text set() stores.
+     *
+     * This is the copy-by-value primitive the rest of the framework uses whenever
+     * data has to cross from one component to another (load-coordinator.ts hands a
+     * leader's data to its followers through it). Plain JSON.stringify is not a
+     * substitute: it consults toJSON() and produces a wire form that deserialize()
+     * cannot recognise, so a registered class would come back as a plain object.
+     *
+     * @returns The text, or null when the value as a whole cannot be expressed.
+     */
+    static serialize(value) {
+        return serialize_value(value, this._is_verbose());
+    }
+    /**
+     * Rebuild a value from text produced by serialize(), restoring Date, Map, Set
+     * and every register_cache_class() class. Returns null when the text is not
+     * restorable (a registered from_plain threw at the root) - the same signal
+     * get() gives for a corrupt entry.
+     */
+    static deserialize(text) {
+        return deserialize_value(text, this._is_verbose());
+    }
+    /**
+     * Perform a serialize/deserialize round-trip on a value.
+     *
+     * The result is ALWAYS jqhtml's own copy: nothing of the caller's object graph
+     * is aliased through, and a value the serializer cannot express is dropped
+     * rather than smuggled out. That is what makes `this.data` identical whether it
+     * came from on_load() or from a cache hit - the old "on failure return the
+     * original" branch broke exactly that promise, and only on the hard cases.
+     *
+     * @param {any} value - The value to normalize
+     * @param {string} [component_name] - Names the component in development warnings.
+     *        Omit to convert silently (the unit tests and non-component callers).
+     * @returns {any} The round-tripped value. Never the original object.
+     */
+    static normalize_for_cache(value, component_name) {
+        const verbose = this._is_verbose();
+        const collector = make_strip_collector(component_name);
+        // Serialize to JSON string
+        const serialized = serialize_value(value, verbose, 'this.data', collector);
+        if (serialized === null) {
+            // The value as a WHOLE could not be expressed (it was itself a function,
+            // a promise, a DOM node...). The round trip of such a value is nothing;
+            // returning the original would put an uncacheable object into this.data.
+            return {};
+        }
+        // Deserialize back to object
+        const deserialized = deserialize_value(serialized, verbose);
+        // `null` from deserialize_value() is ambiguous: it means "failed", but a value
+        // that legitimately serialized to the text `null` also comes back as null. The
+        // serialized text disambiguates.
+        if (deserialized === null && serialized !== 'null') {
+            // Only reachable when a registered class constructor blew up on restore.
+            return {};
+        }
+        return deserialized;
+    }
+    /**
+     * Internal set implementation with scope validation and quota handling
+     * @param {string} key
+     * @param {string} serialized - Pre-serialized JSON string
+     * @private
+     */
+    static _set_item(key, serialized) {
+        // Validate scope before every write
+        this._validate_scope();
+        const scoped_key = this._build_key(key);
         try {
-            const storage = window.localStorage;
-            const test = '__jqhtml_storage_test__';
-            storage.setItem(test, test);
-            storage.removeItem(test);
-            return true;
+            localStorage.setItem(scoped_key, serialized);
         }
         catch (e) {
-            return false;
+            // Check if quota exceeded
+            if (e.name === 'QuotaExceededError' || e.code === 22) {
+                console.warn('[JQHTML Local Storage] Quota exceeded, clearing JQHTML keys and retrying');
+                // Clear only JQHTML keys and retry once
+                this._clear_jqhtml_keys();
+                // Re-stamp the SCOPE MARKER, not the raw developer key: _validate_scope()
+                // compares against `${CORE_VERSION}::${key}`, so writing the bare key here
+                // made the very next write look like a scope change and wipe the cache again.
+                localStorage.setItem('_jqhtml_cache_key', this._scope_marker);
+                try {
+                    localStorage.setItem(scoped_key, serialized);
+                }
+                catch (retry_error) {
+                    console.error('[JQHTML Local Storage] Failed to set item after clearing JQHTML keys:', retry_error);
+                }
+            }
+            else {
+                console.error('[JQHTML Local Storage] Failed to set item:', e);
+            }
         }
     }
     /**
-     * Check if verbose mode is enabled
+     * Internal remove implementation
+     * @param {string} key
      * @private
      */
-    static _is_verbose() {
-        return window.jqhtml?.debug?.verbose === true;
+    static _remove_item(key) {
+        const scoped_key = this._build_key(key);
+        try {
+            localStorage.removeItem(scoped_key);
+        }
+        catch (e) {
+            console.error('[JQHTML Local Storage] Failed to remove item:', e);
+        }
     }
+}
+Jqhtml_Local_Storage._cache_key = null;
+/** Versioned scope identity - compared in _validate_scope() to clear on a core upgrade. */
+Jqhtml_Local_Storage._scope_marker = null;
+Jqhtml_Local_Storage._cache_mode = 'data';
+Jqhtml_Local_Storage._storage_available = null;
+Jqhtml_Local_Storage._initialized = false;
+
+/**
+ * Load Coordinator - Request deduplication for component on_load() calls
+ *
+ * Coordinates parallel component loading to prevent duplicate requests.
+ * When multiple components with identical names and args load simultaneously,
+ * only the first (leader) executes on_load(). Others (followers) wait for
+ * the leader's result.
+ *
+ * Key Concepts:
+ * - **INVOCATION_KEY**: Unique identifier for component name + args combination
+ * - **Leader**: First component to reach on_load() for a given INVOCATION_KEY
+ * - **Follower**: Subsequent components that wait for leader's result
+ *
+ * Lifecycle:
+ * 1. Leader reaches on_load() → create coordination entry
+ * 2. Followers reach on_load() → join waiting queue
+ * 3. Leader completes → distribute data to all followers
+ * 4. Clear coordination entry (no caching)
+ *
+ * The hand-off is a copy, and it is made by the cache serializer
+ * (Jqhtml_Local_Storage.serialize()/deserialize()), never by JSON.stringify.
+ * A follower never runs on_load() and never revalidates, so whatever it is
+ * handed is final: the copy has to rebuild Date, Map, Set and every
+ * register_cache_class() instance exactly as the leader's this.data holds them.
+ * JSON.stringify would consult toJSON() and hand out a wire form that
+ * normalize_for_cache() cannot recognise - the follower would then render
+ * against plain objects while the leader renders against instances.
+ *
+ * @internal This class is not exposed in the public API
+ */
+class Load_Coordinator {
     /**
-     * Validate storage scope and clear JQHTML keys if cache key changed
-     * Only clears keys prefixed with 'jqhtml::' to preserve other libraries' data
-     * @private
+     * Generate INVOCATION_KEY from component name and args
+     * Uses deterministic JSON serialization (sorted keys)
+     * Excludes internal properties (those starting with _)
+     *
+     * For functions/objects:
+     * - Checks for ._jqhtml_cache_id property (assigned by RSpade)
+     * - Falls back to .jqhtml_cache_id() method if property doesn't exist
+     * - If neither exists, marks property as uncacheable
+     *
+     * Returns object with:
+     * - key: Cache key string, or null if uncacheable
+     * - uncacheable_property: Name of first property that prevented caching (for debugging)
      */
-    static _validate_scope() {
-        if (!this._storage_available) {
-            return;
-        }
-        try {
-            const stored_key = localStorage.getItem('_jqhtml_cache_key');
-            // If the scope marker (core version + developer key) changed, clear only JQHTML keys
-            if (stored_key !== null && stored_key !== this._scope_marker) {
-                console.log('[JQHTML Local Storage] Cache scope changed, clearing JQHTML keys:', {
-                    old_key: stored_key,
-                    new_key: this._scope_marker,
-                });
-                this._clear_jqhtml_keys();
-                localStorage.setItem('_jqhtml_cache_key', this._scope_marker);
+    static generate_invocation_key(component_name, args, options = {}) {
+        let uncacheable_property;
+        let uncacheable_reason;
+        // Filter out internal properties (starting with _) and serialize args
+        const serializable_args = {};
+        for (const key of Object.keys(args).sort()) {
+            if (key.startsWith('_')) {
+                continue; // Skip internal properties
             }
-            else if (stored_key === null) {
-                // First time JQHTML is using this storage - just set the key, don't clear
-                console.log('[JQHTML Local Storage] Initializing cache scope (first use):', {
-                    new_key: this._scope_marker,
-                });
-                localStorage.setItem('_jqhtml_cache_key', this._scope_marker);
+            // Skip framework properties that shouldn't affect cache identity
+            // Note: _load_only and _load_render_only are already filtered by the _ prefix check above
+            if (key === 'use_cached_data') {
+                continue;
+            }
+            const value = args[key];
+            const value_type = typeof value;
+            // Handle primitives (string, number, boolean, null, undefined)
+            if (value === null || value === undefined ||
+                value_type === 'string' || value_type === 'number' ||
+                value_type === 'boolean') {
+                serializable_args[key] = value;
+                continue;
+            }
+            // Handle functions and objects
+            if (value_type === 'function' || value_type === 'object') {
+                // Check for ._jqhtml_cache_id property (fastest, what RSpade assigns)
+                if (value._jqhtml_cache_id !== undefined) {
+                    serializable_args[key] = `__JQHTML_CACHE_ID__:${String(value._jqhtml_cache_id)}`;
+                    continue;
+                }
+                // Check for .jqhtml_cache_id() method (more flexible, for custom objects)
+                if (typeof value.jqhtml_cache_id === 'function') {
+                    try {
+                        const cache_id = value.jqhtml_cache_id();
+                        serializable_args[key] = `__JQHTML_CACHE_ID__:${String(cache_id)}`;
+                        continue;
+                    }
+                    catch (error) {
+                        // Method threw error - treat as uncacheable
+                        if (!uncacheable_property) {
+                            uncacheable_property = key;
+                            uncacheable_reason = 'cache-id-threw';
+                        }
+                        return { key: null, uncacheable_property, uncacheable_reason };
+                    }
+                }
+                // No author-supplied id. The cache may fall back to keying by
+                // deterministic content; deduplication deliberately may not.
+                if (options.allow_content_serialization) {
+                    const serialized = serialize_for_cache_key(value);
+                    if (serialized.ok) {
+                        serializable_args[key] = `__JQHTML_CONTENT__:${serialized.text}`;
+                        continue;
+                    }
+                    if (!uncacheable_property) {
+                        uncacheable_property = key;
+                        // This package compiles with strictNullChecks off, and without it
+                        // TypeScript will not narrow a discriminated union by its boolean
+                        // discriminant - so `serialized` is still the full Serialize_Result
+                        // here even though `ok` has been ruled out above. The cast states
+                        // what the control flow already guarantees.
+                        uncacheable_reason = serialized.reason;
+                    }
+                    return { key: null, uncacheable_property, uncacheable_reason };
+                }
+                if (!uncacheable_property) {
+                    uncacheable_property = key;
+                    uncacheable_reason = value_type === 'function' ? 'function' : 'object';
+                }
+                return { key: null, uncacheable_property, uncacheable_reason };
+            }
+            // Unknown type (symbol, bigint, etc.) - uncacheable
+            if (!uncacheable_property) {
+                uncacheable_property = key;
+                uncacheable_reason = value_type;
             }
+            return { key: null, uncacheable_property, uncacheable_reason };
         }
-        catch (e) {
-            console.error('[JQHTML Local Storage] Failed to validate scope:', e);
+        // Try to serialize - if it fails (shouldn't happen now, but safety net), return null
+        try {
+            const sorted_args = JSON.stringify(serializable_args);
+            return { key: `${component_name}::${sorted_args}` };
+        }
+        catch (error) {
+            // Serialization failed unexpectedly
+            return { key: null, uncacheable_property };
         }
     }
     /**
-     * Clear only JQHTML keys from storage (keys starting with 'jqhtml::')
-     * Preserves keys from other libraries
-     * @private
+     * Check if a component should execute on_load() or wait for existing request
+     * Returns true if component should execute (is leader), false if should wait (is follower)
+     *
+     * @param key - The dedup key the caller captured for this load. Every coordinator
+     *              method takes it, because args may legally change during on_load()
+     *              and a recomputed key would address a different (or no) entry.
      */
-    static _clear_jqhtml_keys() {
-        if (!this._storage_available) {
-            return;
+    static should_execute_on_load(component, key) {
+        const entry = this._registry.get(key);
+        if (!entry) {
+            // No existing request - this component becomes the leader
+            return true;
         }
-        const keys_to_remove = [];
-        // Collect all JQHTML keys
-        for (let i = 0; i < localStorage.length; i++) {
-            const key = localStorage.key(i);
-            if (key && key.startsWith('jqhtml::')) {
-                keys_to_remove.push(key);
-            }
+        if (entry.status === 'loading') {
+            // Request in progress - this component becomes a follower
+            entry.waiting.push(component);
+            return false;
         }
-        // Remove collected keys
-        keys_to_remove.forEach(key => {
-            try {
-                localStorage.removeItem(key);
-            }
-            catch (e) {
-                console.error('[JQHTML Local Storage] Failed to remove key:', key, e);
-            }
-        });
-        console.log(`[JQHTML Local Storage] Cleared ${keys_to_remove.length} JQHTML keys`);
+        // Entry exists but completed/failed - should have been cleaned up
+        // Treat as new leader
+        return true;
     }
     /**
-     * Build scoped key with JQHTML namespace prefix
-     * @param {string} key - Developer-provided key
-     * @returns {string}
-     * @private
+     * Register a leader component that will execute on_load()
+     * Creates coordination entry and returns a function to call when data is ready
+     *
+     * @param key - The dedup key captured by the caller (see should_execute_on_load)
+     * @returns A function that accepts the final data and completes coordination
      */
-    static _build_key(key) {
-        return `jqhtml::${key}::${this._cache_key}`;
+    static register_leader(component, key) {
+        // Create a promise that we control - it settles when coordination completes or fails
+        let resolve_promise;
+        let reject_promise;
+        const coordination_promise = new Promise((resolve, reject) => {
+            resolve_promise = resolve;
+            reject_promise = reject;
+        });
+        // A leader with no followers still has to be able to reject this promise on
+        // error; without a handler that rejection surfaces as an unhandled rejection.
+        coordination_promise.catch(() => { });
+        const entry = {
+            status: 'loading',
+            promise: coordination_promise, // Followers await THIS promise, not on_load's
+            resolve_promise,
+            reject_promise,
+            leader_component: component,
+            leader_data: null,
+            waiting: []
+        };
+        this._registry.set(key, entry);
+        // Return cleanup function that accepts the final data
+        return (final_data) => this._complete_coordination(key, component, final_data);
     }
     /**
-     * Check if storage is ready for use
-     * @returns {boolean}
-     * @private
+     * Get the coordination promise for a follower component
+     * Returns a promise that resolves when the leader completes, or rejects if it failed
      */
-    static _is_ready() {
-        return this._storage_available === true && this._cache_key !== null && this._initialized;
+    static get_coordination_promise(key) {
+        const entry = this._registry.get(key);
+        if (!entry || entry.status !== 'loading') {
+            return null;
+        }
+        return entry.promise;
     }
     /**
-     * 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.
+     * Complete coordination after leader's on_load() finishes
+     * Stores leader's data, marks entry as completed, and resolves the promise.
+     * Followers retrieve the data themselves via get_leader_data().
      *
-     * @param {string} key - Storage key
-     * @param {*} value - Value to store (primitives, objects, arrays, or registered class instances)
+     * @param key - The coordination key captured at registration
+     * @param leader - The leader component
+     * @param final_data - The final data after on_load and normalization
+     * @private
      */
-    static set(key, value) {
-        if (!this._is_ready()) {
+    static _complete_coordination(key, leader, final_data) {
+        const entry = this._registry.get(key);
+        if (!entry) {
             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;
+        // Stored as TEXT so each follower rebuilds its own object graph - sharing one
+        // decoded object would let one component's mutation reach every other.
+        // The cache serializer, not JSON.stringify: this.data holds live Date/Map/Set
+        // and register_cache_class() instances, and only the serializer that made
+        // them knows how to carry them across. null means the data as a whole could
+        // not be expressed; followers then load independently.
+        entry.leader_data = Jqhtml_Local_Storage.serialize(final_data);
+        entry.status = 'completed';
+        if (window.jqhtml?.debug?.verbose) {
+            console.log(`[Load Coordinator] Leader ${leader._cid} completed, data available for ${entry.waiting.length} followers`, { key, data: entry.leader_data });
         }
-        // Check size before attempting to store (1MB limit)
-        const size_bytes = new Blob([serialized]).size;
-        const size_mb = size_bytes / (1024 * 1024);
-        if (size_mb > 1) {
-            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;
+        // Resolve the promise - followers waiting on it will now wake up
+        entry.resolve_promise();
+        // Nobody is waiting, so nothing will ever come back to collect the data.
+        // Without this the registry grows once per distinct name+args, forever.
+        if (entry.waiting.length === 0) {
+            this._registry.delete(key);
         }
-        this._set_item(key, serialized);
     }
     /**
-     * Get item from localStorage with class-aware deserialization.
-     *
-     * If deserialization fails, returns null (as if no cache exists).
+     * Get leader's data for a follower component
+     * Called by follower after coordination promise resolves
+     * Returns a freshly parsed copy and cleans up if this is the last follower
      *
-     * @param {string} key - Storage key
-     * @returns {*|null} Deserialized value with class instances restored, or null if not found/failed
+     * @param key - The dedup key captured by the follower before it began waiting
      */
-    static get(key) {
-        if (!this._is_ready()) {
+    static get_leader_data(component, key) {
+        const entry = this._registry.get(key);
+        if (!entry || entry.status !== 'completed' || entry.leader_data === null) {
             return null;
         }
-        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;
+        // Remove this follower from the waiting list
+        const follower_index = entry.waiting.indexOf(component);
+        if (follower_index !== -1) {
+            entry.waiting.splice(follower_index, 1);
         }
-        catch (e) {
-            if (verbose) {
-                console.warn('[JQHTML Cache] Failed to get item:', e);
-            }
-            return null;
+        // One deserialize per follower: each gets its OWN object graph, never a
+        // shared reference, with the same instances the leader's this.data holds.
+        const data = Jqhtml_Local_Storage.deserialize(entry.leader_data);
+        if (window.jqhtml?.debug?.verbose) {
+            console.log(`[Load Coordinator] Follower ${component._cid} retrieving data from leader ${entry.leader_component._cid}`, { key, remaining_followers: entry.waiting.length });
         }
-    }
-    /**
-     * Remove item from localStorage
-     * @param {string} key - Storage key
-     */
-    static remove(key) {
-        if (!this._is_ready()) {
-            return;
+        // If this was the last follower, clean up the entry
+        if (entry.waiting.length === 0) {
+            this._registry.delete(key);
+            if (window.jqhtml?.debug?.verbose) {
+                console.log(`[Load Coordinator] Coordination complete for key: ${key}`, { registry_size: this._registry.size });
+            }
         }
-        this._remove_item(key);
+        return data;
     }
     /**
-     * Perform a serialize/deserialize round-trip on a value.
-     *
-     * The result is ALWAYS jqhtml's own copy: nothing of the caller's object graph
-     * is aliased through, and a value the serializer cannot express is dropped
-     * rather than smuggled out. That is what makes `this.data` identical whether it
-     * came from on_load() or from a cache hit - the old "on failure return the
-     * original" branch broke exactly that promise, and only on the hard cases.
+     * Handle leader on_load() error
+     * Rejects every waiting follower and clears the entry so the next component retries
      *
-     * @param {any} value - The value to normalize
-     * @param {string} [component_name] - Names the component in development warnings.
-     *        Omit to convert silently (the unit tests and non-component callers).
-     * @returns {any} The round-tripped value. Never the original object.
+     * @param key - The dedup key captured at registration
      */
-    static normalize_for_cache(value, component_name) {
-        const verbose = this._is_verbose();
-        const collector = make_strip_collector(component_name);
-        // Serialize to JSON string
-        const serialized = serialize_value(value, verbose, 'this.data', collector);
-        if (serialized === null) {
-            // The value as a WHOLE could not be expressed (it was itself a function,
-            // a promise, a DOM node...). The round trip of such a value is nothing;
-            // returning the original would put an uncacheable object into this.data.
-            return {};
+    static handle_leader_error(key, error) {
+        const entry = this._registry.get(key);
+        if (!entry) {
+            return;
         }
-        // Deserialize back to object
-        const deserialized = deserialize_value(serialized, verbose);
-        // `null` from deserialize_value() is ambiguous: it means "failed", but a value
-        // that legitimately serialized to the text `null` also comes back as null. The
-        // serialized text disambiguates.
-        if (deserialized === null && serialized !== 'null') {
-            // Only reachable when a registered class constructor blew up on restore.
-            return {};
+        entry.status = 'failed';
+        console.error(`[Load Coordinator] Leader ${entry.leader_component._cid} on_load() failed for key: ${key}`, error);
+        // Reject FIRST: followers are parked on this promise and their catch in _load()
+        // propagates the failure exactly as if their own on_load() had thrown. Deleting
+        // without rejecting left them awaiting a promise nobody could ever settle.
+        entry.reject_promise(error);
+        // Clear coordination entry so future requests can retry
+        this._registry.delete(key);
+        if (window.jqhtml?.debug?.verbose) {
+            console.log(`[Load Coordinator] Cleared failed coordination for key: ${key}`, { followers_count: entry.waiting.length });
         }
-        return deserialized;
     }
     /**
-     * Internal set implementation with scope validation and quota handling
-     * @param {string} key
-     * @param {string} serialized - Pre-serialized JSON string
-     * @private
+     * Get current registry state (for debugging)
      */
-    static _set_item(key, serialized) {
-        // Validate scope before every write
-        this._validate_scope();
-        const scoped_key = this._build_key(key);
-        try {
-            localStorage.setItem(scoped_key, serialized);
-        }
-        catch (e) {
-            // Check if quota exceeded
-            if (e.name === 'QuotaExceededError' || e.code === 22) {
-                console.warn('[JQHTML Local Storage] Quota exceeded, clearing JQHTML keys and retrying');
-                // Clear only JQHTML keys and retry once
-                this._clear_jqhtml_keys();
-                // Re-stamp the SCOPE MARKER, not the raw developer key: _validate_scope()
-                // compares against `${CORE_VERSION}::${key}`, so writing the bare key here
-                // made the very next write look like a scope change and wipe the cache again.
-                localStorage.setItem('_jqhtml_cache_key', this._scope_marker);
-                try {
-                    localStorage.setItem(scoped_key, serialized);
-                }
-                catch (retry_error) {
-                    console.error('[JQHTML Local Storage] Failed to set item after clearing JQHTML keys:', retry_error);
-                }
-            }
-            else {
-                console.error('[JQHTML Local Storage] Failed to set item:', e);
-            }
+    static get_registry_state() {
+        const state = {};
+        for (const [key, entry] of this._registry.entries()) {
+            state[key] = {
+                status: entry.status,
+                leader_cid: entry.leader_component._cid,
+                waiting_count: entry.waiting.length,
+                waiting_cids: entry.waiting.map(c => c._cid)
+            };
         }
+        return state;
     }
     /**
-     * Internal remove implementation
-     * @param {string} key
-     * @private
+     * Clear all coordination entries (for testing/debugging)
      */
-    static _remove_item(key) {
-        const scoped_key = this._build_key(key);
-        try {
-            localStorage.removeItem(scoped_key);
-        }
-        catch (e) {
-            console.error('[JQHTML Local Storage] Failed to remove item:', e);
-        }
+    static clear_all() {
+        this._registry.clear();
     }
 }
-Jqhtml_Local_Storage._cache_key = null;
-/** Versioned scope identity - compared in _validate_scope() to clear on a core upgrade. */
-Jqhtml_Local_Storage._scope_marker = null;
-Jqhtml_Local_Storage._cache_mode = 'data';
-Jqhtml_Local_Storage._storage_available = null;
-Jqhtml_Local_Storage._initialized = false;
+Load_Coordinator._registry = new Map();
 
 /**
  * JQHTML Component Event System
@@ -7243,7 +7330,7 @@ function init(jQuery, config) {
     }
 }
 // Version - will be replaced during build with actual version from package.json
-const version = '2.3.70';
+const version = '2.3.71';
 // Default export with all functionality
 const jqhtml = {
     // Core