@jqhtml/core 2.3.68 → 2.3.71

package/dist/jqhtml-core.esm.js

@@ -1,5 +1,5 @@
 /**
- * JQHTML Core v2.3.68
+ * JQHTML Core v2.3.71
  * (c) 2025 JQHTML Team
  * Released under the MIT License
  */
@@ -1510,309 +1510,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
  *
@@ -1831,7 +1528,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,
@@ -1907,14 +1616,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.68';
+const CORE_VERSION = '2.3.71';
 const CLASS_MARKER = '__jqhtml_class__';
 const PROPS_MARKER = '__jqhtml_props__';
 /**
@@ -1922,13 +1628,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.
@@ -2055,48 +1804,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);
@@ -2117,6 +1838,48 @@ function process_for_serialization(value, verbose, seen, path = '', collector) {
         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;
+    }
+    // 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
  * object. Shared by plain objects, registered class instances and degraded
@@ -2172,7 +1935,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.`;
     }
 }
 /**
@@ -2244,27 +2011,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. ` +
@@ -2273,10 +2022,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;
         }
@@ -2434,205 +2187,539 @@ class Jqhtml_Local_Storage {
      * @returns {string}
      * @private
      */
-    static _build_key(key) {
-        return `jqhtml::${key}::${this._cache_key}`;
+    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 {
+            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);
+            }
+        }
     }
     /**
-     * Check if storage is ready for use
-     * @returns {boolean}
+     * Internal remove implementation
+     * @param {string} key
      * @private
      */
-    static _is_ready() {
-        return this._storage_available === true && this._cache_key !== null && this._initialized;
+    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 {
     /**
-     * Set item in localStorage with class-aware serialization.
+     * Generate INVOCATION_KEY from component name and args
+     * Uses deterministic JSON serialization (sorted keys)
+     * Excludes internal properties (those starting with _)
      *
-     * If serialization fails (e.g., unregistered class instances, circular refs),
-     * the existing cache entry is removed and nothing is stored.
+     * 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
      *
-     * @param {string} key - Storage key
-     * @param {*} value - Value to store (primitives, objects, arrays, or registered class instances)
+     * Returns object with:
+     * - key: Cache key string, or null if uncacheable
+     * - uncacheable_property: Name of first property that prevented caching (for debugging)
      */
-    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);
+    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
             }
-            catch (e) {
-                // Ignore removal errors
+            // 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;
             }
-            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 });
+            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;
             }
-            // Remove existing cache entry since we can't update it
-            try {
-                localStorage.removeItem(scoped_key);
+            // 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 };
             }
-            catch (e) {
-                // Ignore removal errors
+            // Unknown type (symbol, bigint, etc.) - uncacheable
+            if (!uncacheable_property) {
+                uncacheable_property = key;
+                uncacheable_reason = value_type;
             }
-            return;
+            return { key: null, uncacheable_property, uncacheable_reason };
         }
-        this._set_item(key, serialized);
+        // 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 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
+     * Get the coordination promise for a follower component
+     * Returns a promise that resolves when the leader completes, or rejects if it 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);
-            }
+    static get_coordination_promise(key) {
+        const entry = this._registry.get(key);
+        if (!entry || entry.status !== 'loading') {
             return null;
         }
+        return entry.promise;
     }
     /**
-     * Remove item from localStorage
-     * @param {string} key - Storage key
+     * 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 remove(key) {
-        if (!this._is_ready()) {
+    static _complete_coordination(key, leader, final_data) {
+        const entry = this._registry.get(key);
+        if (!entry) {
             return;
         }
-        this._remove_item(key);
+        // 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 });
+        }
+        // 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);
+        }
     }
     /**
-     * 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.
+     * 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 {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 by the follower before it began waiting
      */
-    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 get_leader_data(component, key) {
+        const entry = this._registry.get(key);
+        if (!entry || entry.status !== 'completed' || entry.leader_data === null) {
+            return null;
         }
-        // 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 {};
+        // Remove this follower from the waiting list
+        const follower_index = entry.waiting.indexOf(component);
+        if (follower_index !== -1) {
+            entry.waiting.splice(follower_index, 1);
         }
-        return deserialized;
+        // 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 });
+        }
+        // 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;
     }
     /**
-     * Internal set implementation with scope validation and quota handling
-     * @param {string} key
-     * @param {string} serialized - Pre-serialized JSON string
-     * @private
+     * 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 _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);
+    static handle_leader_error(key, error) {
+        const entry = this._registry.get(key);
+        if (!entry) {
+            return;
         }
-        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);
-            }
+        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 });
         }
     }
     /**
-     * Internal remove implementation
-     * @param {string} key
-     * @private
+     * Get current registry state (for 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 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();
     }
 }
-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
@@ -3943,6 +4030,7 @@ function resolve_parent_template(template_def, ctor) {
 class Jqhtml_Component {
     constructor(element, args = {}) {
         this._ready_state = 0; // 0=created, 1=init, 2=loaded, 3=rendered, 4=ready
+        this._debug_no_data = false; // Set by _reload_without_data(); cleared by any real load
         this._instantiator = null; // Component that instantiated this one
         this._dom_parent = null; // Closest component in DOM tree (for lifecycle)
         this._dom_children = new Set(); // Components in DOM subtree (for lifecycle)
@@ -4555,6 +4643,8 @@ class Jqhtml_Component {
             // The queued executor can start long after load() was called - re-check.
             if (this._stopped)
                 return false;
+            // Any real load returns the component to normal, whatever the debug tool did.
+            this._debug_no_data = false;
             // Snapshot current data for change detection
             const data_before = JSON.stringify(this.data);
             // Execute on_load() on detached proxy (restores data to on_create snapshot)
@@ -4744,6 +4834,8 @@ class Jqhtml_Component {
     async _load() {
         if (this._stopped || this._ready_state >= 2)
             return;
+        // Any real load returns the component to normal, whatever the debug tool did.
+        this._debug_no_data = false;
         this._log_lifecycle('load', 'start');
         // use_cached_data feature: If cache hit occurred and use_cached_data=true, skip on_load() entirely
         // The cached data is already in this.data from create() phase
@@ -5176,6 +5268,51 @@ class Jqhtml_Component {
     async refresh() {
         return this.reload(false);
     }
+    /**
+     * Re-render this component from its on_create() state with its cache dropped and
+     * WITHOUT running on_load()/on_loaded()/on_ready().
+     *
+     * @internal debug tool. Used by the debug overlay's lifecycle footer to see what a
+     * component looks like with no loaded data at all. Not public API, not documented,
+     * and no downstream code should call it: reload() or refresh() afterwards returns
+     * the component to normal (the snapshot is intact and the cache is gone, so the
+     * next load is a genuine fresh fetch).
+     */
+    _reload_without_data() {
+        if (this._stopped)
+            return Promise.resolve();
+        // Same marker invalidation reload()/render() do: later ready() waiters must wait
+        // for THIS cycle rather than resolve off the previous one.
+        this.invalidate('ready');
+        // Serialised with reload()/refresh() so it can never interleave with a real load.
+        return this._queue.enqueue('reload', async () => {
+            if (this._stopped)
+                return;
+            // Drop this component's own cache entries (data and html snapshot), so a later
+            // reload() genuinely re-fetches instead of hydrating from what is on screen now.
+            const { cache_key } = generate_cache_key(this);
+            if (cache_key !== null) {
+                Jqhtml_Local_Storage.remove(cache_key);
+                Jqhtml_Local_Storage.remove(`${cache_key}::html`);
+            }
+            // Back to the on_create() state. Components with no custom on_load() take no
+            // snapshot (nothing can have changed this.data), so they simply re-render.
+            if (this.__initial_data_snapshot !== null) {
+                this.__data_frozen = false;
+                this.data = JSON.parse(JSON.stringify(this.__initial_data_snapshot));
+                this.__data_frozen = true;
+            }
+            // Read by the debug overlay's lifecycle row; cleared by _reload()/load()/_load().
+            this._debug_no_data = true;
+            this._render();
+            await this._wait_for_children_ready();
+            if (this._stopped)
+                return;
+            this._ready_state = 4;
+            this._update_debug_attrs();
+            this.trigger('ready');
+        });
+    }
     /**
      * Internal reload implementation - re-fetch data and re-render
      *
@@ -5213,6 +5350,8 @@ class Jqhtml_Component {
     async _reload() {
         if (this._stopped)
             return;
+        // Any real load returns the component to normal, whatever the debug tool did.
+        this._debug_no_data = false;
         // Invalidate ready event so new handlers wait for this reload to complete
         // This prevents .on('ready') handlers from firing immediately based on previous lifecycle
         this.invalidate('ready');
@@ -5951,9 +6090,9 @@ Jqhtml_Component.__jqhtml_component = true; // Marker for unified register() det
 // A bare component name, as accepted by closest() in place of a class selector
 Jqhtml_Component.COMPONENT_NAME_PATTERN = COMPONENT_NAME_PATTERN;
 
-var light_css = "html[data-jqhtml-debug] .jqhtml-debug-hit {\n  outline: 2px solid #e5322d;\n  outline-offset: -2px;\n}\n\nhtml[data-jqhtml-debug] .jqhtml-debug-hit.jqhtml-debug-depth-0 {\n  outline-color: #e5322d;\n}\n\nhtml[data-jqhtml-debug] .jqhtml-debug-hit.jqhtml-debug-depth-1 {\n  outline-color: #2f6fe4;\n}\n\nhtml[data-jqhtml-debug] .jqhtml-debug-hit.jqhtml-debug-depth-2 {\n  outline-color: #1f9d55;\n}\n\nhtml[data-jqhtml-debug] .jqhtml-debug-hit.jqhtml-debug-depth-3 {\n  outline-color: #d97706;\n}\n\nhtml[data-jqhtml-debug] .jqhtml-debug-hit.jqhtml-debug-depth-4 {\n  outline-color: #7c3aed;\n}\n\nhtml[data-jqhtml-debug] .jqhtml-debug-hit.jqhtml-debug-depth-5 {\n  outline-color: #0e7490;\n}";
+var light_css = "html[data-jqhtml-debug] .jqhtml-debug-selected {\n  outline: 2px solid #b45309;\n  outline-offset: -2px;\n}\n\nhtml[data-jqhtml-debug] .jqhtml-debug-hit {\n  outline: 2px solid #e5322d;\n  outline-offset: -2px;\n}\n\nhtml[data-jqhtml-debug] .jqhtml-debug-hit.jqhtml-debug-depth-0 {\n  outline-color: #e5322d;\n}\n\nhtml[data-jqhtml-debug] .jqhtml-debug-hit.jqhtml-debug-depth-1 {\n  outline-color: #2f6fe4;\n}\n\nhtml[data-jqhtml-debug] .jqhtml-debug-hit.jqhtml-debug-depth-2 {\n  outline-color: #1f9d55;\n}\n\nhtml[data-jqhtml-debug] .jqhtml-debug-hit.jqhtml-debug-depth-3 {\n  outline-color: #d97706;\n}\n\nhtml[data-jqhtml-debug] .jqhtml-debug-hit.jqhtml-debug-depth-4 {\n  outline-color: #7c3aed;\n}\n\nhtml[data-jqhtml-debug] .jqhtml-debug-hit.jqhtml-debug-depth-5 {\n  outline-color: #0e7490;\n}";
 
-var shadow_css = ":host {\n  all: initial;\n  display: block;\n  position: fixed;\n  box-sizing: border-box;\n  top: 0;\n  left: 0;\n  width: 100vw;\n  height: 100vh;\n  z-index: 2147483647;\n  pointer-events: none;\n  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, \"Liberation Mono\", monospace;\n  font-size: 12px;\n  font-weight: normal;\n  font-style: normal;\n  font-variant: normal;\n  line-height: 1.4;\n  color: #1c1c1c;\n  text-align: left;\n  text-transform: none;\n  text-indent: 0;\n  text-shadow: none;\n  letter-spacing: normal;\n  word-spacing: normal;\n  white-space: normal;\n  word-break: normal;\n  overflow-wrap: anywhere;\n  hyphens: none;\n  tab-size: 4;\n  direction: ltr;\n  visibility: visible;\n  cursor: default;\n  list-style: none;\n  quotes: none;\n}\n\n.jqhtml-debug-layer {\n  position: absolute;\n  top: 0;\n  left: 0;\n  width: 100%;\n  height: 100%;\n  overflow: hidden;\n  pointer-events: none;\n}\n\n.jqhtml-debug-label {\n  position: absolute;\n  box-sizing: border-box;\n  display: block;\n  padding: 1px 5px;\n  min-height: 18px;\n  color: #ffffff;\n  background: #e5322d;\n  border-radius: 0 0 3px 0;\n  font-size: 11px;\n  line-height: 16px;\n  white-space: normal;\n  overflow-wrap: anywhere;\n  overflow: hidden;\n  pointer-events: none;\n}\n\n.jqhtml-debug-label.jqhtml-debug-depth-0 {\n  background: #e5322d;\n}\n\n.jqhtml-debug-label.jqhtml-debug-depth-1 {\n  background: #2f6fe4;\n}\n\n.jqhtml-debug-label.jqhtml-debug-depth-2 {\n  background: #1f9d55;\n}\n\n.jqhtml-debug-label.jqhtml-debug-depth-3 {\n  background: #d97706;\n}\n\n.jqhtml-debug-label.jqhtml-debug-depth-4 {\n  background: #7c3aed;\n}\n\n.jqhtml-debug-label.jqhtml-debug-depth-5 {\n  background: #0e7490;\n}\n\n.jqhtml-debug-label-name {\n  font-weight: bold;\n}\n\n.jqhtml-debug-label-args {\n  opacity: 0.9;\n  margin-left: 6px;\n}\n\n.jqhtml-debug-modal {\n  display: none;\n  position: absolute;\n  box-sizing: border-box;\n  top: 24px;\n  right: 24px;\n  width: 520px;\n  max-width: calc(100% - 48px);\n  max-height: calc(100% - 48px);\n  overflow: auto;\n  padding: 0 0 12px 0;\n  background: #ffffff;\n  color: #1c1c1c;\n  border: 1px solid #d0d0d0;\n  border-radius: 6px;\n  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.25);\n  pointer-events: auto;\n}\n\n.jqhtml-debug-modal.jqhtml-debug-modal-open {\n  display: block;\n}\n\n.jqhtml-debug-title {\n  display: flex;\n  align-items: center;\n  gap: 8px;\n  position: sticky;\n  top: 0;\n  padding: 8px 12px;\n  background: #1c1c1c;\n  color: #ffffff;\n  font-weight: bold;\n}\n\n.jqhtml-debug-title-name {\n  flex: 1 1 auto;\n  font-size: 13px;\n}\n\n.jqhtml-debug-button {\n  all: unset;\n  display: inline-block;\n  box-sizing: border-box;\n  padding: 2px 8px;\n  border: 1px solid rgba(255, 255, 255, 0.6);\n  border-radius: 3px;\n  color: #ffffff;\n  font-size: 11px;\n  line-height: 16px;\n  cursor: pointer;\n  user-select: none;\n}\n\n.jqhtml-debug-button:hover {\n  background: rgba(255, 255, 255, 0.15);\n}\n\n.jqhtml-debug-section {\n  padding: 8px 12px 0 12px;\n}\n\n.jqhtml-debug-h {\n  margin: 4px 0;\n  color: #666666;\n  font-size: 11px;\n  text-transform: uppercase;\n  letter-spacing: 0.06em;\n}\n\n.jqhtml-debug-table {\n  display: grid;\n  grid-template-columns: max-content max-content 1fr;\n  column-gap: 12px;\n  row-gap: 2px;\n  align-items: baseline;\n}\n\n.jqhtml-debug-key {\n  color: #005cc5;\n  white-space: nowrap;\n}\n\n.jqhtml-debug-type {\n  color: #666666;\n  font-size: 11px;\n  white-space: nowrap;\n}\n\n.jqhtml-debug-value {\n  white-space: pre-wrap;\n  overflow-wrap: anywhere;\n}\n\n.jqhtml-debug-empty {\n  color: #666666;\n  font-style: italic;\n}\n\n.jqhtml-debug-list {\n  display: block;\n  margin: 0;\n  padding: 0;\n}\n\n.jqhtml-debug-link {\n  display: block;\n  padding: 2px 4px;\n  margin: 0 -4px;\n  border-radius: 3px;\n  cursor: pointer;\n}\n\n.jqhtml-debug-link:hover {\n  background: #eef3ff;\n}\n\n.jqhtml-debug-link-cid {\n  color: #666666;\n  margin-left: 6px;\n}\n\n.jqhtml-debug-note {\n  margin-top: 4px;\n  color: #92400e;\n  font-size: 11px;\n}";
+var shadow_css = ":host {\n  all: initial;\n  display: block;\n  position: fixed;\n  box-sizing: border-box;\n  top: 0;\n  left: 0;\n  width: 100vw;\n  height: 100vh;\n  z-index: 2147483647;\n  pointer-events: none;\n  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, \"Liberation Mono\", monospace;\n  font-size: 12px;\n  font-weight: normal;\n  font-style: normal;\n  font-variant: normal;\n  line-height: 1.4;\n  color: #1c1c1c;\n  text-align: left;\n  text-transform: none;\n  text-indent: 0;\n  text-shadow: none;\n  letter-spacing: normal;\n  word-spacing: normal;\n  white-space: normal;\n  word-break: normal;\n  overflow-wrap: anywhere;\n  hyphens: none;\n  tab-size: 4;\n  direction: ltr;\n  visibility: visible;\n  cursor: default;\n  list-style: none;\n  quotes: none;\n}\n\n.jqhtml-debug-layer {\n  position: absolute;\n  top: 0;\n  left: 0;\n  width: 100%;\n  height: 100%;\n  overflow: hidden;\n  pointer-events: none;\n}\n\n.jqhtml-debug-label {\n  position: absolute;\n  box-sizing: border-box;\n  display: block;\n  padding: 1px 5px;\n  min-height: 18px;\n  color: #ffffff;\n  background: #e5322d;\n  border-radius: 0 0 3px 0;\n  font-size: 11px;\n  line-height: 16px;\n  white-space: normal;\n  overflow-wrap: anywhere;\n  overflow: hidden;\n  pointer-events: auto;\n  cursor: pointer;\n}\n\n.jqhtml-debug-label.jqhtml-debug-depth-0 {\n  background: #e5322d;\n}\n\n.jqhtml-debug-label.jqhtml-debug-depth-1 {\n  background: #2f6fe4;\n}\n\n.jqhtml-debug-label.jqhtml-debug-depth-2 {\n  background: #1f9d55;\n}\n\n.jqhtml-debug-label.jqhtml-debug-depth-3 {\n  background: #d97706;\n}\n\n.jqhtml-debug-label.jqhtml-debug-depth-4 {\n  background: #7c3aed;\n}\n\n.jqhtml-debug-label.jqhtml-debug-depth-5 {\n  background: #0e7490;\n}\n\n.jqhtml-debug-label-name {\n  font-weight: bold;\n}\n\n.jqhtml-debug-label-args {\n  opacity: 0.9;\n  margin-left: 6px;\n}\n\n.jqhtml-debug-modal {\n  display: none;\n  position: absolute;\n  box-sizing: border-box;\n  top: 24px;\n  right: 24px;\n  width: 520px;\n  max-width: calc(100% - 48px);\n  overflow: hidden;\n  padding: 0;\n  background: #ffffff;\n  color: #1c1c1c;\n  border: 1px solid #d0d0d0;\n  border-radius: 6px;\n  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.25);\n  pointer-events: auto;\n}\n\n.jqhtml-debug-modal.jqhtml-debug-modal-open {\n  display: block;\n}\n\n.jqhtml-debug-modal.jqhtml-debug-modal-left {\n  left: 24px;\n  right: auto;\n}\n\n.jqhtml-debug-title {\n  display: flex;\n  align-items: center;\n  gap: 8px;\n  padding: 8px 12px;\n  background: #1c1c1c;\n  color: #ffffff;\n  font-weight: bold;\n}\n\n.jqhtml-debug-body {\n  display: block;\n  box-sizing: border-box;\n  overflow-y: scroll;\n  min-height: 300px;\n  max-height: min(600px, 100vh - 200px);\n  padding: 0 0 12px 0;\n}\n\n.jqhtml-debug-footer {\n  display: flex;\n  align-items: center;\n  gap: 8px;\n  padding: 8px 12px;\n  background: #ffffff;\n  border-top: 1px solid #d0d0d0;\n}\n\n.jqhtml-debug-footer-label {\n  color: #666666;\n  font-size: 11px;\n  text-transform: uppercase;\n  letter-spacing: 0.06em;\n}\n\n.jqhtml-debug-title-name {\n  flex: 1 1 auto;\n  font-size: 13px;\n}\n\n.jqhtml-debug-button {\n  all: unset;\n  display: inline-block;\n  box-sizing: border-box;\n  padding: 2px 8px;\n  border: 1px solid rgba(255, 255, 255, 0.6);\n  border-radius: 3px;\n  color: #ffffff;\n  font-size: 11px;\n  line-height: 16px;\n  cursor: pointer;\n  user-select: none;\n}\n\n.jqhtml-debug-button:hover {\n  background: rgba(255, 255, 255, 0.15);\n}\n\n.jqhtml-debug-button.jqhtml-debug-footer-button {\n  color: #1c1c1c;\n  border-color: #d0d0d0;\n}\n\n.jqhtml-debug-button.jqhtml-debug-footer-button:hover {\n  background: #eef3ff;\n}\n\n.jqhtml-debug-section {\n  padding: 8px 12px 0 12px;\n}\n\n.jqhtml-debug-h {\n  margin: 4px 0;\n  color: #666666;\n  font-size: 11px;\n  text-transform: uppercase;\n  letter-spacing: 0.06em;\n}\n\n.jqhtml-debug-table {\n  display: grid;\n  grid-template-columns: max-content max-content 1fr;\n  column-gap: 12px;\n  row-gap: 2px;\n  align-items: baseline;\n}\n\n.jqhtml-debug-key {\n  color: #005cc5;\n  white-space: nowrap;\n}\n\n.jqhtml-debug-type {\n  color: #666666;\n  font-size: 11px;\n  white-space: nowrap;\n}\n\n.jqhtml-debug-value {\n  white-space: pre-wrap;\n  overflow-wrap: anywhere;\n}\n\n.jqhtml-debug-empty {\n  color: #666666;\n  font-style: italic;\n}\n\n.jqhtml-debug-list {\n  display: block;\n  margin: 0;\n  padding: 0;\n}\n\n.jqhtml-debug-link {\n  display: block;\n  padding: 2px 4px;\n  margin: 0 -4px;\n  border-radius: 3px;\n  cursor: pointer;\n}\n\n.jqhtml-debug-link:hover {\n  background: #eef3ff;\n}\n\n.jqhtml-debug-link-cid {\n  color: #666666;\n  margin-left: 6px;\n}\n\n.jqhtml-debug-note {\n  margin-top: 4px;\n  color: #92400e;\n  font-size: 11px;\n}";
 
 /**
  * Component debug overlay.
@@ -5965,6 +6104,12 @@ var shadow_css = ":host {\n  all: initial;\n  display: block;\n  position: fixed
  * data, state, ancestry, instantiator) instead of firing the click. Alt+click
  * passes through. `disable()` puts everything back.
  *
+ * The labels are part of the interaction, not just decoration: the pointer can
+ * move from a component onto one of its tabs without the hover set collapsing,
+ * and clicking a tab inspects that tab's component. The modal keeps an amber
+ * outline on whatever it is showing, and its title bar carries Parent / Back so
+ * the DOM chain can be walked without going back to the page.
+ *
  * Non-invasiveness, the design goal (details in ./CLAUDE.md):
  *   - The overlay's own UI lives in a shadow root on a host element appended to
  *     <body>, styled by shadow.scss. Page CSS cannot select into it and :host
@@ -5983,8 +6128,11 @@ const HOST_ATTR = 'data-jqhtml-debug-root'; // the shadow host
 const LIGHT_STYLE_ID = 'jqhtml-debug-light-styles';
 const HIT_CLASS = `${PREFIX}hit`;
 const DEPTH_CLASS = `${PREFIX}depth-`;
+const SELECTED_CLASS = `${PREFIX}selected`; // on the element the modal is showing
 const DEPTH_COLORS = 6; // keep in step with $depth-colors in _tokens.scss
 const LABEL_HEIGHT = 18;
+const LABEL_MIN_WIDTH = 400; // a narrow component still gets a readable tab
+const VIEWPORT_MARGIN = 5; // gap kept between a label's right edge and the viewport
 const READY_STATES = ['created', 'init', 'loaded', 'rendered', 'ready'];
 const state = {
     enabled: false,
@@ -5994,7 +6142,10 @@ const state = {
     modal: null,
     chain: [],
     hit_elements: [],
+    label_hovered: false,
     modal_component: null,
+    nav_stack: [],
+    selected_element: null,
 };
 // ---------------------------------------------------------------------------
 // Public API
@@ -6051,7 +6202,7 @@ const debug_overlay = {
             : chain_for(target && target.jquery ? target[0] : target)[0];
         if (!component)
             return false;
-        open_modal(component);
+        select(component);
         return true;
     },
 };
@@ -6106,9 +6257,18 @@ function is_ours(event) {
 // ---------------------------------------------------------------------------
 // Hover
 // ---------------------------------------------------------------------------
+/**
+ * A hover on the page replaces the hover set - except while the pointer is on
+ * our own UI. An event from inside the shadow host (a label, the modal) never
+ * clears or changes the hover, and neither does a page hover raised while the
+ * pointer is parked on a label: that is what lets a label be reached and clicked
+ * without the outlines it belongs to vanishing on the way.
+ */
 function on_mouseover(event) {
     if (is_ours(event))
         return;
+    if (state.label_hovered)
+        return;
     const chain = chain_for(event.target);
     if (chain[0] === state.chain[0])
         return;
@@ -6118,6 +6278,32 @@ function on_mouseout(event) {
     if (!event.relatedTarget)
         clear_hover(); // pointer left the document
 }
+/**
+ * The pointer left a label. If it landed back inside the component the label
+ * belongs to (the usual case - the label sits on the component's own corner),
+ * the hover set stays; anywhere else it goes. `elementFromPoint` reports our
+ * shadow host for a point covered by another label, so the host is skipped and
+ * the page element underneath is used.
+ */
+function on_label_leave(event) {
+    state.label_hovered = false;
+    const innermost = state.chain[0];
+    if (!innermost)
+        return;
+    const under = element_under(event.clientX, event.clientY);
+    if (!under || !innermost.$[0].contains(under))
+        clear_hover();
+}
+function element_under(x, y) {
+    const all = document.elementsFromPoint;
+    const candidates = all
+        ? all.call(document, x, y)
+        : [document.elementFromPoint(x, y)].filter(Boolean);
+    for (const node of candidates)
+        if (node !== state.host)
+            return node;
+    return null;
+}
 function on_reposition() {
     if (state.chain.length)
         render_labels();
@@ -6140,18 +6326,23 @@ function clear_hover() {
     }
     state.hit_elements = [];
     state.chain = [];
+    state.label_hovered = false;
     if (state.layer)
         state.layer.textContent = '';
 }
 /**
  * One tab per component in the chain, pinned to the component's top-left
- * corner and no wider than the component. Outermost first so the innermost
- * paints on top; tabs that share a corner (a child filling its parent, the
- * usual case) stack downward instead of hiding each other.
+ * corner. Width: the component's, but a narrow component still gets up to
+ * LABEL_MIN_WIDTH so its name and args stay legible; a label that would then
+ * run off the right edge is slid back so its right edge sits at the margin.
+ * Outermost first so the innermost paints on top; tabs that share a corner (a
+ * child filling its parent, the usual case) stack downward instead of hiding
+ * each other.
  */
 function render_labels() {
     const layer = state.layer;
     layer.textContent = '';
+    state.label_hovered = false; // the element the pointer was on is gone
     const taken = new Map();
     for (let depth = state.chain.length - 1; depth >= 0; depth--) {
         const component = state.chain[depth];
@@ -6164,14 +6355,33 @@ function render_labels() {
         const stacked = taken.get(key) || 0;
         taken.set(key, stacked + 1);
         const label = el('div', `label ${PREFIX}depth-${depth % DEPTH_COLORS}`);
-        label.style.left = `${left}px`;
+        // Laid out at the left edge FIRST, then moved. An absolutely positioned box
+        // shrink-to-fits into the room its own `left` leaves, so measuring it at its
+        // final position would report the squeezed width, and moving it would let it
+        // re-expand - the two chase each other. At left 0 it has the whole viewport,
+        // so the measurement below is the width it will actually keep.
+        label.style.left = '0px';
         label.style.top = `${top + stacked * LABEL_HEIGHT}px`;
-        label.style.maxWidth = `${Math.max(24, Math.round(rect.width))}px`;
+        label.style.maxWidth = `${rect.width < LABEL_MIN_WIDTH ? LABEL_MIN_WIDTH : Math.round(rect.width)}px`;
         label.appendChild(el('span', 'label-name', component.component_name()));
         const args = simple_args(component);
         if (args)
             label.appendChild(el('span', 'label-args', args));
+        // Each label knows its own component: it is a hover target that holds the set
+        // in place, and a click target that inspects THAT component, not the innermost.
+        label.addEventListener('mouseenter', () => { state.label_hovered = true; });
+        label.addEventListener('mouseleave', on_label_leave);
+        label.addEventListener('click', (event) => {
+            event.stopPropagation(); // the document handler already skips is_ours events
+            select(component);
+        });
         layer.appendChild(label);
+        // A label on a narrow component may be wider than the component, so a component
+        // near the right edge can push its label off-screen. Slide it back until its
+        // right edge sits on the margin, never past the left edge.
+        const width = label.getBoundingClientRect().width || label.offsetWidth;
+        const limit = window.innerWidth - VIEWPORT_MARGIN;
+        label.style.left = `${left + width > limit ? Math.max(0, Math.round(limit - width)) : left}px`;
     }
 }
 /** `$id=7 $title="Users"` - only strings, numbers and booleans, never internals. */
@@ -6201,7 +6411,7 @@ function on_click(event) {
         close_modal();
         return;
     }
-    open_modal(chain[0]);
+    select(chain[0]);
 }
 function on_keydown(event) {
     if (event.key === 'Escape' && state.modal_component) {
@@ -6215,17 +6425,82 @@ function close_modal() {
     state.modal.classList.remove(`${PREFIX}modal-open`);
     state.modal.textContent = '';
     state.modal_component = null;
+    state.nav_stack = [];
+    set_selected(null);
+}
+// ---------------------------------------------------------------------------
+// Selection and navigation
+//
+// Three ways in, and they differ only in what they do to the navigation stack:
+//   select()   - a FRESH selection (page click, label click, inspect()): the stack
+//                is dropped, so Back disappears.
+//   navigate() - a step along the chain (Parent, an Ancestry entry, the
+//                Instantiator link): the component being left is pushed.
+//   show()     - render only, stack untouched; what Back and the lifecycle
+//                buttons re-open with.
+// ---------------------------------------------------------------------------
+function select(component) {
+    state.nav_stack = [];
+    show(component);
+}
+function navigate(component) {
+    if (state.modal_component && state.modal_component !== component) {
+        state.nav_stack.push(state.modal_component);
+    }
+    show(component);
+}
+/** Pop to the last component still alive; a stopped one is skipped, not shown. */
+function go_back() {
+    while (state.nav_stack.length) {
+        const previous = state.nav_stack.pop();
+        if (previous.$.hasClass('_Component_Stopped'))
+            continue;
+        show(previous);
+        return;
+    }
+    if (state.modal_component)
+        show(state.modal_component); // nothing left: drop Back
+}
+/** Move SELECTED_CLASS to `element`, or take it off the page entirely for null. */
+function set_selected(element) {
+    if (state.selected_element && state.selected_element !== element) {
+        state.selected_element.classList.remove(SELECTED_CLASS);
+    }
+    state.selected_element = element;
+    if (element)
+        element.classList.add(SELECTED_CLASS);
 }
-function open_modal(component) {
+/**
+ * The inspector. Three children: a fixed title bar, a scrolling body holding every
+ * section, and a fixed footer of lifecycle buttons. The modal sits top-right, but
+ * moves to the left when the inspected component is itself in the right half of the
+ * viewport - otherwise the panel covers the thing being inspected.
+ */
+function show(component) {
     const modal = state.modal;
     modal.textContent = '';
     state.modal_component = component;
     const chain = chain_for(component.$[0]);
     const ancestors = chain.slice(1);
     const element = component.$[0];
-    // Title bar
+    set_selected(element);
+    modal.classList.toggle(`${PREFIX}modal-left`, element.getBoundingClientRect().left > window.innerWidth / 2);
+    // Title bar: the name, then [Back] [Parent] [Log to console] [Close]. Back is
+    // there only while something was navigated away from, Parent only while the
+    // component has a DOM parent component - the first Ancestry entry.
     const title = el('div', 'title');
     title.appendChild(el('span', 'title-name', `<${component.component_name()}>`));
+    if (state.nav_stack.length) {
+        const back = el('button', 'button', 'Back');
+        back.addEventListener('click', go_back);
+        title.appendChild(back);
+    }
+    const parent = ancestors[0];
+    if (parent) {
+        const up = el('button', 'button', 'Parent');
+        up.addEventListener('click', () => navigate(parent));
+        title.appendChild(up);
+    }
     const log = el('button', 'button', 'Log to console');
     log.addEventListener('click', () => {
         console.log(`[JQHTML debug] <${component.component_name()}>`, component, element);
@@ -6235,6 +6510,9 @@ function open_modal(component) {
     close.addEventListener('click', close_modal);
     title.appendChild(close);
     modal.appendChild(title);
+    // The only scrolling element: the title bar and the footer stay put.
+    const body = el('div', 'body');
+    modal.appendChild(body);
     // Identity
     const ctor = component.constructor;
     const hierarchy = ctor.get_class_hierarchy ? ctor.get_class_hierarchy() : [ctor.name];
@@ -6243,15 +6521,18 @@ function open_modal(component) {
     row(identity, 'class', '', hierarchy.join(' → '));
     row(identity, 'element', '', describe_element(element));
     row(identity, '_cid', '', String(component._cid));
-    row(identity, 'lifecycle', '', READY_STATES[component._ready_state] || String(component._ready_state));
+    const lifecycle = READY_STATES[component._ready_state] || String(component._ready_state);
+    row(identity, 'lifecycle', '', component._debug_no_data
+        ? `${lifecycle} (no data - reload w/o data)`
+        : lifecycle);
     const nocache = element.getAttribute('data-nocache');
     if (nocache)
         row(identity, 'cache', '', `declined: ${nocache}`);
-    modal.appendChild(section('Identity', identity));
+    body.appendChild(section('Identity', identity));
     // Args / data / state
-    modal.appendChild(section('Args', object_table(component.args)));
-    modal.appendChild(section('Data', object_table(component.data)));
-    modal.appendChild(section('State', object_table(component.state)));
+    body.appendChild(section('Args', object_table(component.args)));
+    body.appendChild(section('Data', object_table(component.data)));
+    body.appendChild(section('State', object_table(component.state)));
     // Ancestry
     const list = el('div', 'list');
     if (!ancestors.length)
@@ -6260,10 +6541,10 @@ function open_modal(component) {
         const link = el('div', 'link');
         link.appendChild(el('span', 'link-name', `<${ancestor.component_name()}>`));
         link.appendChild(el('span', 'link-cid', String(ancestor._cid)));
-        link.addEventListener('click', () => open_modal(ancestor));
+        link.addEventListener('click', () => navigate(ancestor));
         list.appendChild(link);
     }
-    modal.appendChild(section('Ancestry (DOM, nearest first)', list));
+    body.appendChild(section('Ancestry (DOM, nearest first)', list));
     // Instantiator - the component whose template wrote this tag. Differs from
     // the DOM parent for markup written in a slot body or default content.
     const instantiator = component.instantiator ? component.instantiator() : null;
@@ -6272,7 +6553,7 @@ function open_modal(component) {
         const link = el('div', 'link');
         link.appendChild(el('span', 'link-name', `<${instantiator.component_name()}>`));
         link.appendChild(el('span', 'link-cid', String(instantiator._cid)));
-        link.addEventListener('click', () => open_modal(instantiator));
+        link.addEventListener('click', () => navigate(instantiator));
         inst.appendChild(link);
         if (ancestors[0] && instantiator !== ancestors[0]) {
             inst.appendChild(el('div', 'note', 'Written in this component\'s template but rendered inside a different parent (slot or default content): handlers and $sid bind here.'));
@@ -6281,9 +6562,49 @@ function open_modal(component) {
     else {
         inst.appendChild(el('div', 'empty', 'none - created directly'));
     }
-    modal.appendChild(section('Instantiator', inst));
+    body.appendChild(section('Instantiator', inst));
+    // Footer: lifecycle controls. Clicks land inside the shadow host, so the
+    // overlay's own click hijack lets them through (is_ours).
+    const footer = el('div', 'footer');
+    footer.appendChild(el('span', 'footer-label', 'Lifecycle:'));
+    footer.appendChild(lifecycle_button(component, 'Reload', (c) => c.reload()));
+    footer.appendChild(lifecycle_button(component, 'Refresh', (c) => c.refresh()));
+    footer.appendChild(lifecycle_button(component, 'Rerender', (c) => c.render()));
+    footer.appendChild(lifecycle_button(component, 'Reload w/o data', (c) => c._reload_without_data()));
+    modal.appendChild(footer);
     modal.classList.add(`${PREFIX}modal-open`);
 }
+/**
+ * One footer button. Runs its lifecycle call on a live component, logs whatever it
+ * throws or rejects with, and re-opens the modal once the call settles so the panel
+ * (lifecycle row above all) describes the state the button just produced.
+ */
+function lifecycle_button(component, label, run) {
+    const button = el('button', 'button footer-button', label);
+    button.addEventListener('click', () => {
+        if (component.$.hasClass('_Component_Stopped'))
+            return; // dead component: nothing to do
+        let result;
+        try {
+            result = run(component);
+        }
+        catch (error) {
+            console.error(`[JQHTML debug] ${label} threw on <${component.component_name()}>`, error);
+            return;
+        }
+        Promise.resolve(result)
+            .catch((error) => {
+            console.error(`[JQHTML debug] ${label} rejected on <${component.component_name()}>`, error);
+        })
+            .then(() => {
+            // `show`, not `select`: the lifecycle buttons re-render the panel in place
+            // and must not throw away the navigation stack behind it.
+            if (state.enabled && state.modal_component === component)
+                show(component);
+        });
+    });
+    return button;
+}
 // ---------------------------------------------------------------------------
 // DOM helpers (shadow side)
 // ---------------------------------------------------------------------------
@@ -7014,7 +7335,7 @@ function init(jQuery, config) {
     }
 }
 // Version - will be replaced during build with actual version from package.json
-const version = '2.3.68';
+const version = '2.3.71';
 // Default export with all functionality
 const jqhtml = {
     // Core