@jqhtml/core 2.3.70 → 2.3.72

package/dist/jqhtml-core.esm.js

@@ -1,5 +1,5 @@
 /**
- * JQHTML Core v2.3.70
+ * JQHTML Core v2.3.72
  * (c) 2025 JQHTML Team
  * Released under the MIT License
  */
@@ -219,12 +219,17 @@ class LifecycleManager {
         return LifecycleManager.instance;
     }
     constructor() {
-        this.active_components = new Set();
-        // No automatic cleanup on DOM removal - components stop explicitly via:
-        // 1. Parent component re-render (calls .empty() which stops children)
-        // 2. Manual .empty(), .html(), .text() calls (overridden to stop children)
+        // Components stop explicitly via:
+        // 1. Parent component re-render (stops descendants before clearing innerHTML)
+        // 2. Any jQuery removal that reaches jQuery.cleanData (.remove(), .empty(),
+        //    .html(x), .text(x), .replaceWith(), .replaceAll()) - hooked in jquery-plugin.ts
         // 3. Explicit .stop() call
-        // This allows components to be moved in DOM without lifecycle interruption
+        // Native DOM removal is NOT observed for stop; 'detach' (dom-attachment.ts) is the
+        // signal for that. Moving a component within the document never stops it.
+        //
+        // There is deliberately no registry of live components here. The DOM (via
+        // element.data('_component')) is the only owner; a registry would pin every
+        // component that left the document without being stopped.
     }
     /**
      * Boot a component - run its full lifecycle
@@ -235,7 +240,6 @@ class LifecycleManager {
      * - _load_render_only: on_create + render + on_load + re-render. No on_render, no on_loaded, no on_ready.
      */
     async boot_component(component) {
-        this.active_components.add(component);
         try {
             // Create phase - SYNCHRONOUS, runs BEFORE first render
             component.create();
@@ -396,12 +400,6 @@ class LifecycleManager {
             }
         }
     }
-    /**
-     * Unregister a component (called on destroy)
-     */
-    unregister_component(component) {
-        this.active_components.delete(component);
-    }
 }
 
 /**
@@ -1511,760 +1509,509 @@ function serialize_for_cache_key(value) {
 }
 
 /**
- * Load Coordinator - Request deduplication for component on_load() calls
+ * Jqhtml_Local_Storage - Scoped local storage for JQHTML component caching
  *
- * 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.
+ * Provides safe, scoped access to localStorage with automatic handling of
+ * unavailable storage, quota exceeded errors, and scope invalidation.
  *
- * 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
+ * Key Features:
+ * - **Manual scoping**: Cache key must be set via set_cache_key() before use
+ * - **Graceful degradation**: Returns null when storage unavailable or cache key not set
+ * - **Quota management**: Auto-clears storage when full and retries operation
+ * - **Scope validation**: Clears storage when cache key changes
+ * - **Developer-friendly keys**: Scoped suffix allows easy inspection in dev tools
+ * - **Class-aware serialization**: ES6 class instances serialize and restore properly
  *
- * 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)
+ * Class-Aware Serialization:
+ * ES6 class instances can be serialized and deserialized if registered via
+ * register_cache_class(). Classes are wrapped as {__jqhtml_class__: "Name", __jqhtml_props__: {...}}
+ * and restored to proper instances on retrieval. Nested class instances in objects
+ * and arrays are handled recursively. 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,
+ * user ID, or combination of relevant scope factors). This scope is stored in
+ * `_jqhtml_cache_key`. If the cache key changes between page loads, all JQHTML
+ * storage is cleared to prevent stale data from different sessions/users.
+ *
+ * Key Format:
+ * Keys are stored as: `jqhtml::developer_key::cache_key`
+ * Example: `jqhtml::User_Profile_data::user_123`
+ *
+ * The `jqhtml::` prefix identifies JQHTML keys, allowing safe clearing of only our keys
+ * without affecting other JavaScript libraries. This enables transparent coexistence
+ * with third-party libraries that also use browser storage.
+ *
+ * Quota Exceeded Handling:
+ * When storage quota is exceeded during a set operation, only JQHTML keys (prefixed with
+ * `jqhtml::`) are cleared, preserving other libraries' data. The operation is then retried
+ * once. This ensures the application continues functioning even when storage is full.
+ *
+ * Usage:
+ *   // Register classes that need to be cached (call once at startup)
+ *   jqhtml.register_cache_class(Contact_Model);
+ *   jqhtml.register_cache_class(User_Profile);
+ *
+ *   // Must set cache key first (typically done once on page load)
+ *   Jqhtml_Local_Storage.set_cache_key('user_123');
+ *
+ *   // Then use storage normally - ES6 classes serialize automatically
+ *   Jqhtml_Local_Storage.set('cached_component', {
+ *     contact: new Contact_Model(),
+ *     timestamp: Date.now()
+ *   });
+ *   const cached = Jqhtml_Local_Storage.get('cached_component');
+ *   // cached.contact instanceof Contact_Model === true
+ *
+ * IMPORTANT - Volatile Storage:
+ * Storage can be cleared at any time due to:
+ * - User clearing browser data
+ * - Private browsing mode restrictions
+ * - Quota exceeded errors
+ * - Cache key changes
+ * - Browser storage unavailable
+ *
+ * Therefore, NEVER store critical data. Only use for:
+ * - Cached component HTML (performance optimization)
+ * - Transient UI state (convenience, not required)
  *
  * @internal This class is not exposed in the public API
+ *
+ * ---------------------------------------------------------------------------
+ * REPORTING WHAT WAS DROPPED
+ *
+ * `this.data` is always the serialized copy this file produces - in EVERY cache
+ * mode, including 'none' (see component.ts `_apply_load_result`). Whatever the
+ * serializer cannot express is therefore not merely missing from the cache, it
+ * is missing from `this.data`, and an author needs to be told once rather than
+ * discover it on the next cache hit.
+ *
+ * Two small optional parameters carry that:
+ *
+ *   process_for_serialization(value, verbose, seen, path, collector?)
+ *       `collector(path, kind)` is invoked for every value that is dropped or
+ *       degraded. `path` is a dotted/bracketed path from the root the caller
+ *       named; `kind` is one of Strip_Kind. Paths are only BUILT when a
+ *       collector is present, so the no-collector path costs nothing.
+ *
+ *   Jqhtml_Local_Storage.normalize_for_cache(value, component_name?)
+ *       With a component name, and only in development mode, each dropped path
+ *       prints exactly ONE console.warn for the life of the page (keyed
+ *       `${component_name}:${path}`, the same once-only shape as
+ *       warn_uncacheable_args in component-cache.ts). Production converts
+ *       silently. Neither ever throws.
+ * ---------------------------------------------------------------------------
  */
-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}` };
+// 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.72';
+const CLASS_MARKER = '__jqhtml_class__';
+const PROPS_MARKER = '__jqhtml_props__';
+/**
+ * Register a class for cache serialization/deserialization.
+ * Must be called before attempting to cache instances of this class.
+ *
+ * @param klass - The class constructor to register
+ * @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, options = {}) {
+    if (typeof klass !== 'function' || !klass.name) {
+        throw new Error('[JQHTML Cache] register_cache_class requires a named class constructor');
+    }
+    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.
+ * Returns null if serialization fails for any reason.
+ *
+ * @param value - The value to serialize
+ * @param verbose - Whether to log warnings
+ * @param path - Root path used when reporting drops (only used with a collector)
+ * @param collector - Optional reporter, see the file header
+ * @returns Serialized JSON string, or null if serialization failed
+ */
+function serialize_value(value, verbose, path = '', collector) {
+    try {
+        const seen = new WeakSet();
+        const processed = process_for_serialization(value, verbose, seen, path, collector);
+        if (processed === undefined) {
+            // Serialization failed - undefined signals failure
+            return null;
         }
-        catch (error) {
-            // Serialization failed unexpectedly
-            return { key: null, uncacheable_property };
+        return JSON.stringify(processed);
+    }
+    catch (e) {
+        if (verbose) {
+            console.warn('[JQHTML Cache] Serialization failed:', e);
         }
+        return null;
     }
-    /**
-     * 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);
+}
+/**
+ * Recursively process a value for serialization.
+ *
+ * Values the serializer cannot express are DROPPED, never passed through: the
+ * result of this function is what becomes `this.data`, so letting a function or
+ * a DOM node survive here would make `this.data` differ from what the cache can
+ * ever return. A dropped property is omitted from an object and becomes `null`
+ * in an array - JSON's own semantics for the same situation.
+ *
+ * Returns undefined for a value that has to be dropped.
+ *
+ * @param value - The value to process
+ * @param verbose - Whether to log warnings
+ * @param seen - WeakSet to detect circular references
+ * @param path - Dotted path of this value (only built when a collector is present)
+ * @param collector - Optional reporter for dropped/degraded values
+ * @returns Processed value ready for JSON.stringify, or undefined if dropped
+ */
+function process_for_serialization(value, verbose, seen, path = '', collector) {
+    // Handle null and undefined
+    if (value === null) {
+        return null;
     }
-    /**
-     * 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;
+    if (value === undefined) {
+        return undefined; // JSON.stringify will omit this property
     }
-    /**
-     * 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;
+    // Handle primitives
+    if (typeof value !== 'object') {
+        // string, number, boolean are fine
+        if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+            return value;
         }
-        // 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);
+        // bigint, symbol, function cannot be serialized
+        if (typeof value === 'function') {
+            collector?.(path, 'function');
         }
-        catch (error) {
-            // Unserializable data cannot be shared; followers load independently.
-            entry.leader_data = null;
+        else if (typeof value === 'symbol') {
+            collector?.(path, 'symbol');
         }
-        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 });
+        else if (typeof value === 'bigint') {
+            collector?.(path, 'bigint');
         }
-        // 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);
+        if (verbose) {
+            console.warn(`[JQHTML Cache] Cannot serialize ${typeof value} - value will be omitted`);
         }
+        // Return undefined to omit this value (not fail entire serialization)
+        return undefined;
     }
-    /**
-     * 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 });
+    // Live objects that only LOOK like data. Each is checked before anything
+    // treats it as a bag of properties, because walking one produces a
+    // meaningless husk (a jQuery object becomes {0: ..., length: 1}) instead of
+    // the drop the author needs to hear about.
+    if (typeof value.nodeType === 'number') {
+        collector?.(path, 'dom-node');
+        return undefined;
+    }
+    if (value.jquery) {
+        collector?.(path, 'jquery');
+        return undefined;
+    }
+    // Duck-typed on purpose: importing Jqhtml_Component here would be a cycle
+    // (component.ts imports this file). _cid + component_name() is the pair no
+    // plain data object carries.
+    if (value._cid !== undefined && typeof value.component_name === 'function') {
+        collector?.(path, 'component');
+        return undefined;
+    }
+    if (typeof value.then === 'function') {
+        collector?.(path, 'promise');
+        return undefined;
+    }
+    // Handle circular references.
+    // `seen` tracks only the current ancestor path (the DFS stack): an object is
+    // added on the way down and removed on the way back up (see finally below).
+    // This flags a genuine cycle (a back-edge to an ancestor) while allowing a
+    // shared reference in a DAG to be serialized independently on each visit.
+    // JSON round-trip semantics do not preserve identity anyway, so emitting a
+    // copy per reference is correct; silently omitting the property is not.
+    if (seen.has(value)) {
+        collector?.(path, 'circular');
+        if (verbose) {
+            console.warn('[JQHTML Cache] Circular reference detected - cutting the cycle');
         }
-        // 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 undefined; // Cut the cycle here; the rest of the tree still serializes
+    }
+    seen.add(value);
+    try {
+        // Handle arrays
+        if (Array.isArray(value)) {
+            const result = [];
+            for (let i = 0; i < value.length; i++) {
+                const item = value[i];
+                const processed = process_for_serialization(item, verbose, seen, collector ? `${path}[${i}]` : '', collector);
+                // For arrays, we keep undefined as null to preserve indices
+                result.push(processed === undefined ? null : processed);
             }
+            return result;
         }
-        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;
+        // 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]: registered.name,
+                [PROPS_MARKER]: plain
+            };
         }
-        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 });
+        const ctor = value.constructor;
+        // 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);
         }
-    }
-    /**
-     * 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)
-            };
+        // Unregistered class instance - convert to plain object for hot/cold parity.
+        // Properties are preserved, prototype methods are lost, exactly as a cache
+        // hit would produce, so the loss shows up on the first load rather than on
+        // the next page view.
+        collector?.(path, 'unregistered-class', ctor.name);
+        if (verbose) {
+            console.warn(`[JQHTML Cache] Converting unregistered class "${ctor.name}" to plain object. ` +
+                `Methods will be lost. Call jqhtml.register_cache_class(${ctor.name}) to preserve the class.`);
         }
-        return state;
+        return process_own_properties(value, verbose, seen, path, collector);
     }
-    /**
-     * Clear all coordination entries (for testing/debugging)
-     */
-    static clear_all() {
-        this._registry.clear();
+    finally {
+        // Pop this object off the ancestor path now that its subtree is done.
+        seen.delete(value);
     }
 }
-Load_Coordinator._registry = new Map();
-
 /**
- * Jqhtml_Local_Storage - Scoped local storage for JQHTML component caching
+ * The plain value stored for a registered instance.
  *
- * Provides safe, scoped access to localStorage with automatic handling of
- * unavailable storage, quota exceeded errors, and scope invalidation.
- *
- * Key Features:
- * - **Manual scoping**: Cache key must be set via set_cache_key() before use
- * - **Graceful degradation**: Returns null when storage unavailable or cache key not set
- * - **Quota management**: Auto-clears storage when full and retries operation
- * - **Scope validation**: Clears storage when cache key changes
- * - **Developer-friendly keys**: Scoped suffix allows easy inspection in dev tools
- * - **Class-aware serialization**: ES6 class instances serialize and restore properly
- *
- * Class-Aware Serialization:
- * ES6 class instances can be serialized and deserialized if registered via
- * register_cache_class(). Classes are wrapped as {__jqhtml_class__: "Name", __jqhtml_props__: {...}}
- * and restored to proper instances on retrieval. Nested class instances in objects
- * and arrays are handled recursively.
- *
- * Scoping Strategy:
- * Storage is scoped by a user-provided cache key (typically a session identifier,
- * user ID, or combination of relevant scope factors). This scope is stored in
- * `_jqhtml_cache_key`. If the cache key changes between page loads, all JQHTML
- * storage is cleared to prevent stale data from different sessions/users.
- *
- * Key Format:
- * Keys are stored as: `jqhtml::developer_key::cache_key`
- * Example: `jqhtml::User_Profile_data::user_123`
- *
- * The `jqhtml::` prefix identifies JQHTML keys, allowing safe clearing of only our keys
- * without affecting other JavaScript libraries. This enables transparent coexistence
- * with third-party libraries that also use browser storage.
- *
- * Quota Exceeded Handling:
- * When storage quota is exceeded during a set operation, only JQHTML keys (prefixed with
- * `jqhtml::`) are cleared, preserving other libraries' data. The operation is then retried
- * once. This ensures the application continues functioning even when storage is full.
- *
- * Usage:
- *   // Register classes that need to be cached (call once at startup)
- *   jqhtml.register_cache_class(Contact_Model);
- *   jqhtml.register_cache_class(User_Profile);
- *
- *   // Must set cache key first (typically done once on page load)
- *   Jqhtml_Local_Storage.set_cache_key('user_123');
- *
- *   // Then use storage normally - ES6 classes serialize automatically
- *   Jqhtml_Local_Storage.set('cached_component', {
- *     contact: new Contact_Model(),
- *     timestamp: Date.now()
- *   });
- *   const cached = Jqhtml_Local_Storage.get('cached_component');
- *   // cached.contact instanceof Contact_Model === true
- *
- * IMPORTANT - Volatile Storage:
- * Storage can be cleared at any time due to:
- * - User clearing browser data
- * - Private browsing mode restrictions
- * - Quota exceeded errors
- * - Cache key changes
- * - Browser storage unavailable
- *
- * Therefore, NEVER store critical data. Only use for:
- * - Cached component HTML (performance optimization)
- * - Transient UI state (convenience, not required)
- *
- * @internal This class is not exposed in the public API
- *
- * ---------------------------------------------------------------------------
- * REPORTING WHAT WAS DROPPED
- *
- * `this.data` is always the serialized copy this file produces - in EVERY cache
- * mode, including 'none' (see component.ts `_apply_load_result`). Whatever the
- * serializer cannot express is therefore not merely missing from the cache, it
- * is missing from `this.data`, and an author needs to be told once rather than
- * discover it on the next cache hit.
- *
- * Two small optional parameters carry that:
- *
- *   process_for_serialization(value, verbose, seen, path, collector?)
- *       `collector(path, kind)` is invoked for every value that is dropped or
- *       degraded. `path` is a dotted/bracketed path from the root the caller
- *       named; `kind` is one of Strip_Kind. Paths are only BUILT when a
- *       collector is present, so the no-collector path costs nothing.
+ * 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.
  *
- *   Jqhtml_Local_Storage.normalize_for_cache(value, component_name?)
- *       With a component name, and only in development mode, each dropped path
- *       prints exactly ONE console.warn for the life of the page (keyed
- *       `${component_name}:${path}`, the same once-only shape as
- *       warn_uncacheable_args in component-cache.ts). Production converts
- *       silently. Neither ever throws.
- * ---------------------------------------------------------------------------
+ * 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
+ * unregistered instances - all three keep exactly the same property semantics.
  */
+function process_own_properties(value, verbose, seen, path, collector) {
+    const result = {};
+    for (const key of Object.keys(value)) {
+        const propValue = value[key];
+        const processed = process_for_serialization(propValue, verbose, seen, collector ? `${path}.${key}` : '', collector);
+        // Only include if not undefined (unless original was undefined)
+        if (processed !== undefined || propValue === undefined) {
+            result[key] = processed;
+        }
+    }
+    return result;
+}
 // ============================================================================
-// Class Registry for Serialization
+// Development warnings for dropped values
 // ============================================================================
-// Registry mapping class names to constructors
-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 CLASS_MARKER = '__jqhtml_class__';
-const PROPS_MARKER = '__jqhtml_props__';
+// One warning per component + path, for the life of the page. A list of 50 rows
+// each carrying an $on_select callback must print ONE warning, not 50, and must
+// not print it again on the next reload() or on the next instance of the same
+// component. Same shape as _warned_uncacheable in component-cache.ts.
+const _warned_stripped = new Set();
 /**
- * Register a class for cache serialization/deserialization.
- * Must be called before attempting to cache instances of this class.
- *
- * @param klass - The class constructor to register
- * @throws Error if klass is not a named function/class
+ * What was lost, and where the value actually belongs. Every message names a
+ * destination, because "it was dropped" without "put it here instead" is not
+ * actionable.
  */
-function register_cache_class(klass) {
-    if (typeof klass !== 'function' || !klass.name) {
-        throw new Error('[JQHTML Cache] register_cache_class requires a named class constructor');
+function strip_advice(kind, detail) {
+    switch (kind) {
+        case 'function':
+            return 'a function cannot be serialized. Callbacks are configuration, not loaded data - ' +
+                'pass it in this.args (from the parent template) and keep only ids in this.data.';
+        case 'promise':
+            return 'a promise cannot be serialized. Await it inside on_load() and store the RESULT, ' +
+                'or hold the pending promise in this.state.';
+        case 'dom-node':
+            return 'a DOM node cannot be serialized. Elements, timers, files and sockets belong in this.state.';
+        case 'jquery':
+            return 'a jQuery object cannot be serialized. Elements, timers, files and sockets belong in this.state.';
+        case 'component':
+            return 'a Jqhtml_Component cannot be serialized. Keep component references in this.state ' +
+                'and address children with this.sid().';
+        case 'symbol':
+            return 'a symbol cannot be serialized. Use a string, or keep it in this.state.';
+        case 'bigint':
+            return 'a bigint cannot be serialized. Convert it to a string in on_load(), or keep it in this.state.';
+        case 'circular':
+            return 'it points back to one of its own ancestors, and the cycle was cut. Store the graph ' +
+                'flat (ids instead of back-references) in this.data, or keep the linked form in this.state.';
+        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 - 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.`;
     }
-    class_registry[klass.name] = klass;
 }
 /**
- * Serialize a value to JSON string, handling ES6 class instances recursively.
- * Returns null if serialization fails for any reason.
+ * Build the collector normalize_for_cache() hands to the serializer, or
+ * `undefined` when nobody is listening - production, or a caller that named no
+ * component. Returning undefined (rather than a no-op function) is what keeps
+ * the serializer from building path strings at all on the hot path.
+ */
+function make_strip_collector(component_name) {
+    if (!component_name)
+        return undefined;
+    if (get_config().mode !== 'development')
+        return undefined;
+    return (path, kind, detail) => {
+        try {
+            const dedupe_key = `${component_name}:${path}`;
+            if (_warned_stripped.has(dedupe_key))
+                return;
+            _warned_stripped.add(dedupe_key);
+            console.warn(`[JQHTML] <${component_name}> dropped ${path} from this.data: ${strip_advice(kind, detail)}\n` +
+                `  this.data is always the serialized copy jqhtml stores in and restores from cache, ` +
+                `so only serializable values survive on_load() - in every cache mode.`, { component: component_name, path, kind });
+        }
+        catch {
+            // A warning must never be able to break a load.
+        }
+    };
+}
+// ============================================================================
+// Deserialization (String → Object)
+// ============================================================================
+/**
+ * Deserialize a JSON string, restoring ES6 class instances.
+ * Returns null if deserialization fails.
  *
- * @param value - The value to serialize
+ * @param str - The JSON string to deserialize
  * @param verbose - Whether to log warnings
- * @param path - Root path used when reporting drops (only used with a collector)
- * @param collector - Optional reporter, see the file header
- * @returns Serialized JSON string, or null if serialization failed
+ * @returns Deserialized value with class instances restored, or null if failed
  */
-function serialize_value(value, verbose, path = '', collector) {
+function deserialize_value(str, verbose) {
     try {
-        const seen = new WeakSet();
-        const processed = process_for_serialization(value, verbose, seen, path, collector);
-        if (processed === undefined) {
-            // Serialization failed - undefined signals failure
-            return null;
-        }
-        return JSON.stringify(processed);
+        const parsed = JSON.parse(str);
+        return process_for_deserialization(parsed, verbose);
     }
     catch (e) {
         if (verbose) {
-            console.warn('[JQHTML Cache] Serialization failed:', e);
+            console.warn('[JQHTML Cache] Deserialization failed:', e);
         }
         return null;
     }
 }
 /**
- * Recursively process a value for serialization.
- *
- * Values the serializer cannot express are DROPPED, never passed through: the
- * result of this function is what becomes `this.data`, so letting a function or
- * a DOM node survive here would make `this.data` differ from what the cache can
- * ever return. A dropped property is omitted from an object and becomes `null`
- * in an array - JSON's own semantics for the same situation.
- *
- * Returns undefined for a value that has to be dropped.
+ * Recursively process a parsed value, restoring class instances.
  *
- * @param value - The value to process
+ * @param value - The parsed value to process
  * @param verbose - Whether to log warnings
- * @param seen - WeakSet to detect circular references
- * @param path - Dotted path of this value (only built when a collector is present)
- * @param collector - Optional reporter for dropped/degraded values
- * @returns Processed value ready for JSON.stringify, or undefined if dropped
+ * @returns Processed value with class instances restored
  */
-function process_for_serialization(value, verbose, seen, path = '', collector) {
-    // Handle null and undefined
-    if (value === null) {
-        return null;
+function process_for_deserialization(value, verbose) {
+    // Handle primitives and null
+    if (value === null || value === undefined || typeof value !== 'object') {
+        return value;
     }
-    if (value === undefined) {
-        return undefined; // JSON.stringify will omit this property
-    }
-    // Handle primitives
-    if (typeof value !== 'object') {
-        // string, number, boolean are fine
-        if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
-            return value;
-        }
-        // bigint, symbol, function cannot be serialized
-        if (typeof value === 'function') {
-            collector?.(path, 'function');
-        }
-        else if (typeof value === 'symbol') {
-            collector?.(path, 'symbol');
-        }
-        else if (typeof value === 'bigint') {
-            collector?.(path, 'bigint');
-        }
-        if (verbose) {
-            console.warn(`[JQHTML Cache] Cannot serialize ${typeof value} - value will be omitted`);
-        }
-        // Return undefined to omit this value (not fail entire serialization)
-        return undefined;
-    }
-    // Live objects that only LOOK like data. Each is checked before anything
-    // treats it as a bag of properties, because walking one produces a
-    // meaningless husk (a jQuery object becomes {0: ..., length: 1}) instead of
-    // the drop the author needs to hear about.
-    if (typeof value.nodeType === 'number') {
-        collector?.(path, 'dom-node');
-        return undefined;
-    }
-    if (value.jquery) {
-        collector?.(path, 'jquery');
-        return undefined;
-    }
-    // Duck-typed on purpose: importing Jqhtml_Component here would be a cycle
-    // (component.ts imports this file). _cid + component_name() is the pair no
-    // plain data object carries.
-    if (value._cid !== undefined && typeof value.component_name === 'function') {
-        collector?.(path, 'component');
-        return undefined;
-    }
-    if (typeof value.then === 'function') {
-        collector?.(path, 'promise');
-        return undefined;
-    }
-    // Handle circular references.
-    // `seen` tracks only the current ancestor path (the DFS stack): an object is
-    // added on the way down and removed on the way back up (see finally below).
-    // This flags a genuine cycle (a back-edge to an ancestor) while allowing a
-    // shared reference in a DAG to be serialized independently on each visit.
-    // JSON round-trip semantics do not preserve identity anyway, so emitting a
-    // copy per reference is correct; silently omitting the property is not.
-    if (seen.has(value)) {
-        collector?.(path, 'circular');
-        if (verbose) {
-            console.warn('[JQHTML Cache] Circular reference detected - cutting the cycle');
-        }
-        return undefined; // Cut the cycle here; the rest of the tree still serializes
-    }
-    seen.add(value);
-    try {
-        // Handle arrays
-        if (Array.isArray(value)) {
-            const result = [];
-            for (let i = 0; i < value.length; i++) {
-                const item = value[i];
-                const processed = process_for_serialization(item, verbose, seen, collector ? `${path}[${i}]` : '', collector);
-                // For arrays, we keep undefined as null to preserve indices
-                result.push(processed === undefined ? null : processed);
-            }
-            return result;
-        }
-        // Handle Date objects specially
-        if (value instanceof Date) {
-            return {
-                [CLASS_MARKER]: 'Date',
-                [PROPS_MARKER]: value.toISOString()
-            };
-        }
-        // Handle Map objects
-        if (value instanceof Map) {
-            const entries = [];
-            for (const [k, v] of value) {
-                const 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));
-            }
-            return {
-                [CLASS_MARKER]: 'Set',
-                [PROPS_MARKER]: items
-            };
-        }
-        // Get the constructor
-        const ctor = value.constructor;
-        // Handle registered class instances
-        if (ctor && ctor.name && class_registry[ctor.name]) {
-            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);
-        }
-        // Unregistered class instance - convert to plain object for hot/cold parity.
-        // Properties are preserved, prototype methods are lost, exactly as a cache
-        // hit would produce, so the loss shows up on the first load rather than on
-        // the next page view.
-        collector?.(path, 'unregistered-class', ctor.name);
-        if (verbose) {
-            console.warn(`[JQHTML Cache] Converting unregistered class "${ctor.name}" to plain object. ` +
-                `Methods will be lost. Call jqhtml.register_cache_class(${ctor.name}) to preserve the class.`);
-        }
-        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);
-    }
-}
-/**
- * Walk an object's own enumerable properties (bypassing any toJSON) into a plain
- * object. Shared by plain objects, registered class instances and degraded
- * unregistered instances - all three keep exactly the same property semantics.
- */
-function process_own_properties(value, verbose, seen, path, collector) {
-    const result = {};
-    for (const key of Object.keys(value)) {
-        const propValue = value[key];
-        const processed = process_for_serialization(propValue, verbose, seen, collector ? `${path}.${key}` : '', collector);
-        // Only include if not undefined (unless original was undefined)
-        if (processed !== undefined || propValue === undefined) {
-            result[key] = processed;
-        }
-    }
-    return result;
-}
-// ============================================================================
-// Development warnings for dropped values
-// ============================================================================
-// One warning per component + path, for the life of the page. A list of 50 rows
-// each carrying an $on_select callback must print ONE warning, not 50, and must
-// not print it again on the next reload() or on the next instance of the same
-// component. Same shape as _warned_uncacheable in component-cache.ts.
-const _warned_stripped = new Set();
-/**
- * What was lost, and where the value actually belongs. Every message names a
- * destination, because "it was dropped" without "put it here instead" is not
- * actionable.
- */
-function strip_advice(kind, detail) {
-    switch (kind) {
-        case 'function':
-            return 'a function cannot be serialized. Callbacks are configuration, not loaded data - ' +
-                'pass it in this.args (from the parent template) and keep only ids in this.data.';
-        case 'promise':
-            return 'a promise cannot be serialized. Await it inside on_load() and store the RESULT, ' +
-                'or hold the pending promise in this.state.';
-        case 'dom-node':
-            return 'a DOM node cannot be serialized. Elements, timers, files and sockets belong in this.state.';
-        case 'jquery':
-            return 'a jQuery object cannot be serialized. Elements, timers, files and sockets belong in this.state.';
-        case 'component':
-            return 'a Jqhtml_Component cannot be serialized. Keep component references in this.state ' +
-                'and address children with this.sid().';
-        case 'symbol':
-            return 'a symbol cannot be serialized. Use a string, or keep it in this.state.';
-        case 'bigint':
-            return 'a bigint cannot be serialized. Convert it to a string in on_load(), or keep it in this.state.';
-        case 'circular':
-            return 'it points back to one of its own ancestors, and the cycle was cut. Store the graph ' +
-                'flat (ids instead of back-references) in this.data, or keep the linked form in this.state.';
-        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.`;
-    }
-}
-/**
- * Build the collector normalize_for_cache() hands to the serializer, or
- * `undefined` when nobody is listening - production, or a caller that named no
- * component. Returning undefined (rather than a no-op function) is what keeps
- * the serializer from building path strings at all on the hot path.
- */
-function make_strip_collector(component_name) {
-    if (!component_name)
-        return undefined;
-    if (get_config().mode !== 'development')
-        return undefined;
-    return (path, kind, detail) => {
-        try {
-            const dedupe_key = `${component_name}:${path}`;
-            if (_warned_stripped.has(dedupe_key))
-                return;
-            _warned_stripped.add(dedupe_key);
-            console.warn(`[JQHTML] <${component_name}> dropped ${path} from this.data: ${strip_advice(kind, detail)}\n` +
-                `  this.data is always the serialized copy jqhtml stores in and restores from cache, ` +
-                `so only serializable values survive on_load() - in every cache mode.`, { component: component_name, path, kind });
-        }
-        catch {
-            // A warning must never be able to break a load.
-        }
-    };
-}
-// ============================================================================
-// Deserialization (String → Object)
-// ============================================================================
-/**
- * Deserialize a JSON string, restoring ES6 class instances.
- * Returns null if deserialization fails.
- *
- * @param str - The JSON string to deserialize
- * @param verbose - Whether to log warnings
- * @returns Deserialized value with class instances restored, or null if failed
- */
-function deserialize_value(str, verbose) {
-    try {
-        const parsed = JSON.parse(str);
-        return process_for_deserialization(parsed, verbose);
-    }
-    catch (e) {
-        if (verbose) {
-            console.warn('[JQHTML Cache] Deserialization failed:', e);
-        }
-        return null;
-    }
-}
-/**
- * Recursively process a parsed value, restoring class instances.
- *
- * @param value - The parsed value to process
- * @param verbose - Whether to log warnings
- * @returns Processed value with class instances restored
- */
-function process_for_deserialization(value, verbose) {
-    // Handle primitives and null
-    if (value === null || value === undefined || typeof value !== 'object') {
-        return value;
-    }
-    // Handle arrays
-    if (Array.isArray(value)) {
-        return value.map(item => process_for_deserialization(item, verbose));
+    // Handle arrays
+    if (Array.isArray(value)) {
+        return value.map(item => process_for_deserialization(item, verbose));
     }
     // Check for class marker
     if (value[CLASS_MARKER] !== undefined && value[PROPS_MARKER] !== undefined) {
         const class_name = value[CLASS_MARKER];
         const props = value[PROPS_MARKER];
-        // Handle built-in types
-        if (class_name === 'Date') {
-            return new Date(props);
-        }
-        if (class_name === 'Map') {
-            const map = new Map();
-            for (const [k, v] of props) {
-                map.set(process_for_deserialization(k, verbose), process_for_deserialization(v, verbose));
-            }
-            return map;
-        }
-        if (class_name === 'Set') {
-            const set = new Set();
-            for (const item of props) {
-                set.add(process_for_deserialization(item, verbose));
-            }
-            return set;
-        }
-        // Look up registered class
-        const klass = class_registry[class_name];
-        if (!klass) {
+        // 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 +2020,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;
         }
@@ -2284,355 +2035,689 @@ function process_for_deserialization(value, verbose) {
             if (verbose) {
                 console.warn(`[JQHTML Cache] Failed to restore class "${class_name}":`, e);
             }
-            // Return null to signal cache should be treated as miss
-            return null;
+            // Return null to signal cache should be treated as miss
+            return null;
+        }
+    }
+    // Plain object - process recursively
+    const result = {};
+    for (const key of Object.keys(value)) {
+        result[key] = process_for_deserialization(value[key], verbose);
+    }
+    return result;
+}
+class Jqhtml_Local_Storage {
+    /**
+     * Set the cache key and initialize storage
+     * Must be called before any get/set operations
+     * @param {string} cache_key - Unique identifier for this cache scope
+     * @param {CacheMode} cache_mode - Cache strategy: 'data' (default, recommended) or 'html'
+     */
+    static set_cache_key(cache_key, cache_mode = 'data') {
+        this._cache_key = cache_key;
+        // Key SHAPE is a function of the library (see cache-key-serializer.ts), so an
+        // upgrade that changes it must invalidate everything persisted under the old shape.
+        // Version the SCOPE MARKER rather than the key itself: _validate_scope() already
+        // clears every jqhtml key when this value changes, and leaving the per-entry key
+        // format alone keeps stored keys readable and avoids repeating the version in each.
+        this._scope_marker = `${CORE_VERSION}::${cache_key}`;
+        this._cache_mode = cache_mode;
+        this._init();
+    }
+    /**
+     * Check if cache key has been set
+     * @returns {boolean} True if cache key is configured
+     */
+    static has_cache_key() {
+        return this._cache_key !== null;
+    }
+    /**
+     * Get the current cache mode
+     * @returns {CacheMode} Current cache mode ('data' or 'html')
+     */
+    static get_cache_mode() {
+        return this._cache_mode;
+    }
+    /**
+     * Initialize storage system and validate scope
+     * Called automatically after cache key is set
+     * @private
+     */
+    static _init() {
+        // Check storage availability
+        if (this._storage_available === null) {
+            this._storage_available = this._is_storage_available();
+        }
+        if (!this._storage_available || !this._cache_key) {
+            return;
+        }
+        // Validate scope
+        this._validate_scope();
+        this._initialized = true;
+    }
+    /**
+     * Check if localStorage is available
+     * @returns {boolean}
+     * @private
+     */
+    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 {
+            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);
+            }
+        }
+    }
+    /**
+     * Internal remove implementation
+     * @param {string} key
+     * @private
+     */
+    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 {
+    /**
+     * 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 };
         }
-    }
-    // Plain object - process recursively
-    const result = {};
-    for (const key of Object.keys(value)) {
-        result[key] = process_for_deserialization(value[key], verbose);
-    }
-    return result;
-}
-class Jqhtml_Local_Storage {
-    /**
-     * Set the cache key and initialize storage
-     * Must be called before any get/set operations
-     * @param {string} cache_key - Unique identifier for this cache scope
-     * @param {CacheMode} cache_mode - Cache strategy: 'data' (default, recommended) or 'html'
-     */
-    static set_cache_key(cache_key, cache_mode = 'data') {
-        this._cache_key = cache_key;
-        // Key SHAPE is a function of the library (see cache-key-serializer.ts), so an
-        // upgrade that changes it must invalidate everything persisted under the old shape.
-        // Version the SCOPE MARKER rather than the key itself: _validate_scope() already
-        // clears every jqhtml key when this value changes, and leaving the per-entry key
-        // format alone keeps stored keys readable and avoids repeating the version in each.
-        this._scope_marker = `${CORE_VERSION}::${cache_key}`;
-        this._cache_mode = cache_mode;
-        this._init();
-    }
-    /**
-     * Check if cache key has been set
-     * @returns {boolean} True if cache key is configured
-     */
-    static has_cache_key() {
-        return this._cache_key !== null;
-    }
-    /**
-     * Get the current cache mode
-     * @returns {CacheMode} Current cache mode ('data' or 'html')
-     */
-    static get_cache_mode() {
-        return this._cache_mode;
-    }
-    /**
-     * Initialize storage system and validate scope
-     * Called automatically after cache key is set
-     * @private
-     */
-    static _init() {
-        // Check storage availability
-        if (this._storage_available === null) {
-            this._storage_available = this._is_storage_available();
+        // 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}` };
         }
-        if (!this._storage_available || !this._cache_key) {
-            return;
+        catch (error) {
+            // Serialization failed unexpectedly
+            return { key: null, uncacheable_property };
         }
-        // Validate scope
-        this._validate_scope();
-        this._initialized = true;
     }
     /**
-     * Check if localStorage is available
-     * @returns {boolean}
-     * @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 _is_storage_available() {
-        try {
-            const storage = window.localStorage;
-            const test = '__jqhtml_storage_test__';
-            storage.setItem(test, test);
-            storage.removeItem(test);
+    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;
         }
-        catch (e) {
+        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;
     }
     /**
-     * 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
+     * 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 _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);
-            }
+    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;
         });
-        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}`;
+        // 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()) {
-            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
-            }
+    static _complete_coordination(key, leader, final_data) {
+        const entry = this._registry.get(key);
+        if (!entry) {
             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;
+        // 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);
         }
-        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
@@ -3094,6 +3179,85 @@ async function execute_on_load_detached(component, dedup_key = null) {
     };
 }
 
+/**
+ * JQHTML DOM Attachment Tracking
+ *
+ * Backs the component 'attach' / 'detach' lifecycle events.
+ *
+ * One document-level MutationObserver (childList + subtree) is installed the first
+ * time any component expresses interest in attachment, and disconnected when the
+ * last interested component is stopped or collected. The observer never inspects
+ * mutation records: it is only a "the tree changed" tick. On each batch it walks
+ * the tracked components and asks each to compare its root's isConnected against
+ * its own recorded attachment state (Jqhtml_Component._attachment_check()). Cost is
+ * O(tracked components) per mutation batch, independent of how much of the page
+ * changed, and zero when nothing has opted in.
+ *
+ * Because MutationObserver delivers per microtask, a node moved synchronously
+ * (remove + insert in one task, e.g. appendTo) never shows a transition. Only a
+ * component whose root is actually off-document when the batch flushes is detached.
+ *
+ * Tracked components are held by WeakRef. A component that is removed from the
+ * document natively (never stopped) and then dropped by everything else is therefore
+ * collectable: the tracker pins nothing. Dead refs are pruned on the next batch.
+ */
+const tracked = new Set();
+const ref_of = new WeakMap();
+let observer = null;
+function on_mutation() {
+    for (const ref of tracked) {
+        const component = ref.deref();
+        if (!component || component._stopped) {
+            tracked.delete(ref);
+            continue;
+        }
+        component._attachment_check();
+    }
+    if (tracked.size === 0)
+        disconnect();
+}
+function connect() {
+    if (observer !== null)
+        return;
+    if (typeof MutationObserver === 'undefined' || typeof document === 'undefined')
+        return;
+    observer = new MutationObserver(on_mutation);
+    observer.observe(document.documentElement, { childList: true, subtree: true });
+}
+function disconnect() {
+    if (observer === null)
+        return;
+    observer.disconnect();
+    observer = null;
+}
+/** Start watching a component's root for attach/detach transitions. Idempotent. */
+function track_attachment(component) {
+    if (ref_of.has(component))
+        return;
+    const ref = new WeakRef(component);
+    ref_of.set(component, ref);
+    tracked.add(ref);
+    connect();
+}
+/** Stop watching a component (called from _stop()). Idempotent. */
+function untrack_attachment(component) {
+    const ref = ref_of.get(component);
+    if (!ref)
+        return;
+    ref_of.delete(component);
+    tracked.delete(ref);
+    if (tracked.size === 0)
+        disconnect();
+}
+/** Number of components currently tracked (diagnostics / tests). */
+function tracked_attachment_count() {
+    return tracked.size;
+}
+/** Whether the document observer is currently installed (diagnostics / tests). */
+function attachment_observer_active() {
+    return observer !== null;
+}
+
 /**
  * JQHTML Component Cache Integration
  *
@@ -4002,6 +4166,12 @@ class Jqhtml_Component {
         this.__load_gates = []; // Pending gates (cleared once the first load begins)
         this.__first_load_started = false; // Latch: true once the first load phase begins (enforces one-shot + throw-after)
         this.__gate_resume = null; // Resolver to release an in-progress gate wait early (reload/refresh/stop)
+        // DOM attachment state machine - see _attachment_check() / dom-attachment.ts.
+        // _attached is the component's OWN belief about whether it is in the document;
+        // it flips at most once per direction, and 'attach' / 'detach' fire only on a flip.
+        this._attached = false;
+        this._attachment_checked = false; // First check has run (after the first 'ready' dispatch)
+        this._attachment_tracking = false; // Something is interested: on_attach/on_detach overridden, or .on('attach'|'detach')
         // Detect custom on_load() override immediately
         // Prototype chain is set up before constructor runs, so this.on_load
         // correctly resolves to child class override if one exists
@@ -4075,6 +4245,12 @@ class Jqhtml_Component {
         // Initialize this.state as an empty object (convention for arbitrary component state)
         // No special meaning to framework - mutable anywhere, not cached, not frozen
         this.state = {};
+        // Overriding on_attach()/on_detach() is interest in attachment tracking. Tracking
+        // itself only starts after the first 'ready' dispatch (see _attachment_check()).
+        if (this.on_attach !== Jqhtml_Component.prototype.on_attach ||
+            this.on_detach !== Jqhtml_Component.prototype.on_detach) {
+            this._attachment_tracking = true;
+        }
         this._log_lifecycle('construct', 'complete');
     }
     /**
@@ -4088,7 +4264,9 @@ class Jqhtml_Component {
             on_render: 'Use render() to trigger a re-render.',
             on_load: 'Use reload() to refresh data.',
             on_ready: 'Called automatically when ready.',
-            on_stop: 'Use stop() to stop the component.'
+            on_stop: 'Use stop() to stop the component.',
+            on_attach: 'Called automatically when the component enters the document.',
+            on_detach: 'Called automatically when the component leaves the document.'
         };
         const impls = {};
         const self = this;
@@ -5442,8 +5620,13 @@ class Jqhtml_Component {
         // stopped children into the parent's registry.
         this._log_lifecycle('destroy', 'start');
         this.$.addClass('_Component_Stopped');
-        // Unregister from lifecycle manager
-        this._lifecycle_manager.unregister_component(this);
+        // A component that believes it is attached is detached first, so 'detach' always
+        // precedes 'stop' and subscribers can rely on strict attach/detach alternation.
+        // A component that never fired 'attach' (stopped before ready, or born and kept
+        // off-document) fires no 'detach' either. Either way it leaves the tracker.
+        if (this._attached)
+            this._transition_attachment(false);
+        untrack_attachment(this);
         // Call user's on_stop() hook with authorization (sync) - only when actually
         // overridden, since _call_lifecycle_sync() on the base no-op costs per child
         // on every re-render.
@@ -5488,6 +5671,89 @@ class Jqhtml_Component {
     on_loaded() { } // Override to process loaded data (e.g., clone this.data to this.state)
     async on_ready() { }
     on_stop() { }
+    on_attach() { } // Sync. Root entered the document (first checked after 'ready')
+    on_detach() { } // Sync. Root left the document, or the component is being stopped while attached
+    // -------------------------------------------------------------------------
+    // DOM attachment state machine
+    // -------------------------------------------------------------------------
+    /**
+     * Whether this component currently considers itself attached to the document.
+     *
+     * This is the component's recorded state, not a live isConnected read: it is
+     * false until the first check after 'ready', and from then on flips only when a
+     * transition is observed (or on stop()). It is exactly the state 'attach' and
+     * 'detach' have reported.
+     */
+    is_attached() {
+        return this._attached;
+    }
+    /**
+     * Flip the recorded state and fire the matching hook + event. The opposite
+     * sticky event is invalidated first, so a late subscriber only ever sees the
+     * current state. Hook errors are isolated; the event still fires.
+     * @private
+     */
+    _transition_attachment(attached) {
+        this._attached = attached;
+        const event_name = attached ? 'attach' : 'detach';
+        const hook_name = attached ? 'on_attach' : 'on_detach';
+        this.invalidate(attached ? 'detach' : 'attach');
+        if (this[hook_name] !== Jqhtml_Component.prototype[hook_name]) {
+            try {
+                const result = this._call_lifecycle_sync(hook_name);
+                if (result && typeof result.then === 'function') {
+                    console.warn(`[JQHTML] Component "${this.component_name()}" returned a Promise from ${hook_name}(). ` +
+                        `${hook_name}() must be synchronous code. Remove 'async' from the function declaration.`);
+                }
+            }
+            catch (error) {
+                console.error(`[JQHTML] Error in ${hook_name}() for ${this.component_name()}:`, error);
+            }
+        }
+        this.trigger(event_name);
+    }
+    /**
+     * Compare the root's live connectivity with the recorded state and transition
+     * on a difference. Idempotent. Called by the document observer on every
+     * mutation batch for tracked components, and directly by the framework after
+     * 'ready' and when interest is registered late.
+     * @private
+     */
+    _attachment_check() {
+        if (this._stopped)
+            return;
+        const connected = !!this.$[0].isConnected;
+        if (connected !== this._attached)
+            this._transition_attachment(connected);
+    }
+    /**
+     * The first check, run once the 'ready' handlers have completed. Fires 'attach'
+     * if the component was born attached, even with no listener, so a later
+     * .on('attach') gets the sticky fire. Deferred interest starts tracking here.
+     * @private
+     */
+    _attachment_first_check() {
+        const first = !this._attachment_checked;
+        this._attachment_checked = true;
+        this._attachment_check();
+        if (first && this._attachment_tracking)
+            track_attachment(this);
+    }
+    /**
+     * Register interest in attach/detach. Before the first ready check this only
+     * records the interest; after it, tracking starts immediately and a check runs
+     * at once, so a late subscriber on a natively-removed component sees 'detach'.
+     * @private
+     */
+    _watch_attachment() {
+        if (this._attachment_tracking)
+            return;
+        this._attachment_tracking = true;
+        if (this._attachment_checked && !this._stopped) {
+            track_attachment(this);
+            this._attachment_check();
+        }
+    }
     /**
      * Called with the viewport width in CSS pixels:
      *   - after every on_render()
@@ -5552,6 +5818,8 @@ class Jqhtml_Component {
      * @see component-events.ts for full documentation
      */
     on(event_name, callback) {
+        if (event_name === 'attach' || event_name === 'detach')
+            this._watch_attachment();
         return event_on(this, event_name, callback);
     }
     /**
@@ -5560,14 +5828,24 @@ class Jqhtml_Component {
      * @see component-events.ts for full documentation
      */
     once(event_name, callback) {
+        if (event_name === 'attach' || event_name === 'detach')
+            this._watch_attachment();
         return event_once(this, event_name, callback);
     }
     /**
      * Trigger a lifecycle event - delegates to component-events.ts
      * @see component-events.ts for full documentation
+     *
+     * 'ready' is special: once its handlers have run, the component runs its first
+     * attachment check (and every later one, idempotently). Doing it here rather than
+     * at each of the call sites that trigger 'ready' guarantees the order
+     * on_ready() -> 'ready' handlers -> 'attach', so everything on_ready() set up is
+     * complete before anyone learns the component is in the document.
      */
     trigger(event_name, data) {
         event_trigger(this, event_name, data);
+        if (event_name === 'ready' && !this._stopped)
+            this._attachment_first_check();
     }
     /**
      * Check if any callbacks are registered for a given event
@@ -7001,9 +7279,42 @@ function init_jquery_plugin(jQuery) {
         return jQuery(results);
     };
     // Store original jQuery methods
-    const originalEmpty = jQuery.fn.empty;
     const originalHtml = jQuery.fn.html;
-    const originalText = jQuery.fn.text;
+    // ---------------------------------------------------------------------------
+    // Stop components on every jQuery-driven removal by hooking jQuery.cleanData.
+    //
+    // jQuery routes .remove(), .empty(), .html(x), .text(x), .replaceWith() and
+    // .replaceAll() through jQuery.cleanData(elems) to drop the data store and
+    // handlers of every element about to leave the tree - and `elems` is already the
+    // flattened subtree, in document order (parent before child). Stopping here is
+    // therefore one classList check per removed element, no extra traversal, and
+    // covers every jQuery removal path at once. It is the same hook jQuery UI's
+    // widget factory uses for the same reason.
+    //
+    // It MUST be installed on the original jQuery object: jQuery's own code calls
+    // cleanData through its closure-local reference, not through our wrapper. The
+    // wrapper's copied static is updated below so both names agree.
+    //
+    // .detach() does NOT call cleanData, by jQuery's own design (it keeps data for
+    // reinsertion), and native DOM removal (el.remove(), innerHTML = '') bypasses
+    // jQuery entirely. Neither stops a component; the 'detach' lifecycle event is
+    // the signal for those. Moving a component (.appendTo) is not a removal.
+    // ---------------------------------------------------------------------------
+    const originalCleanData = _jqhtml_original_jquery.cleanData;
+    const cleanDataWithComponentStop = function (elems) {
+        for (let i = 0; i < elems.length; i++) {
+            const el = elems[i];
+            if (el.nodeType !== 1 || !el.classList.contains('Component'))
+                continue;
+            const component = _jqhtml_original_jquery.data(el, '_component');
+            if (component && !component._stopped) {
+                component._stop(); // Not recursive: every descendant is in elems too
+            }
+        }
+        return originalCleanData(elems);
+    };
+    _jqhtml_original_jquery.cleanData = cleanDataWithComponentStop;
+    jQuery.cleanData = cleanDataWithComponentStop;
     // ---------------------------------------------------------------------------
     // Guard against hand-creating elements with data-sid via jQuery.
     //
@@ -7060,53 +7371,15 @@ function init_jquery_plugin(jQuery) {
             `  • <div class="MyComponent__${sid}"> → .find('.MyComponent__${sid}')`);
     };
     /**
-     * Override jQuery.fn.empty() to stop child components before clearing DOM
-     * This ensures component cleanup hooks fire when DOM is cleared
-     */
-    jQuery.fn.empty = function () {
-        return this.each(function () {
-            // Stop all child components before clearing DOM
-            jQuery(this).find('.Component').each(function () {
-                const component = jQuery(this).data('_component');
-                if (component && !component._stopped) {
-                    component._stop(); // Stop just the component, DOM will be cleared anyway
-                }
-            });
-            // Call original empty
-            originalEmpty.call(jQuery(this));
-        });
-    };
-    /**
-     * Override jQuery.fn.html() to stop child components when setting new content
-     * When used as setter, calls .empty() first to properly cleanup components
+     * Override jQuery.fn.html() setter to reject hand-written data-sid before the
+     * DOM is mutated. Component stopping is handled by the cleanData hook above.
      */
     jQuery.fn.html = function (value) {
-        // Getter - just pass through
         if (arguments.length === 0) {
             return originalHtml.call(this);
         }
-        // Reject hand-written data-sid before mutating the DOM
         assert_no_manual_sid(value, '.html()');
-        // Setter - empty first (which stops components), then set content
-        return this.each(function () {
-            jQuery(this).empty();
-            originalHtml.call(jQuery(this), value);
-        });
-    };
-    /**
-     * Override jQuery.fn.text() to stop child components when setting new content
-     * When used as setter, calls .empty() first to properly cleanup components
-     */
-    jQuery.fn.text = function (value) {
-        // Getter - just pass through
-        if (arguments.length === 0) {
-            return originalText.call(this);
-        }
-        // Setter - empty first (which stops components), then set content
-        return this.each(function () {
-            jQuery(this).empty();
-            originalText.call(jQuery(this), value);
-        });
+        return originalHtml.call(this, value);
     };
     // Store original jQuery.fn.on
     const originalOn = jQuery.fn.on;
@@ -7248,7 +7521,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.72';
 // Default export with all functionality
 const jqhtml = {
     // Core
@@ -7363,7 +7636,11 @@ const jqhtml = {
     get_captured_data,
     stop_data_capture,
     set_preload_data,
-    clear_preload_data
+    clear_preload_data,
+    // Attachment tracking diagnostics - how many components are watched for
+    // attach/detach and whether the document observer is currently installed
+    tracked_attachment_count,
+    attachment_observer_active
 };
 // Auto-register on window for browser environments
 // This is REQUIRED for compiled templates which use window.jqhtml.register_template()
@@ -7393,5 +7670,5 @@ if (typeof window !== 'undefined' && !window.jqhtml) {
     }
 }
 
-export { COMPONENT_NAME_PATTERN, COMPONENT_NAME_RULE, Jqhtml_Component, LifecycleManager as Jqhtml_LifecycleManager, Jqhtml_Local_Storage, LifecycleManager, Load_Coordinator, add_object_printer, applyDebugDelay, boot, clear_preload_data, configure, create_component, debug_overlay, jqhtml as default, devWarn, dynamic_component_name, escape_html, escape_html_nl2br, extract_slots, get_captured_data, get_component_class, get_component_names, get_config, get_object_printers, get_registered_templates, get_template, get_template_by_class, handleComponentError, has_component, init, init_jquery_plugin, isSequentialProcessing, is_component_name, list_components, logDataChange, logDispatch, logInstruction, logLifecycle, print_object, process_instructions, register, register_cache_class, register_component, register_template, set_preload_data, start_data_capture, stop_data_capture, version };
+export { COMPONENT_NAME_PATTERN, COMPONENT_NAME_RULE, Jqhtml_Component, LifecycleManager as Jqhtml_LifecycleManager, Jqhtml_Local_Storage, LifecycleManager, Load_Coordinator, add_object_printer, applyDebugDelay, attachment_observer_active, boot, clear_preload_data, configure, create_component, debug_overlay, jqhtml as default, devWarn, dynamic_component_name, escape_html, escape_html_nl2br, extract_slots, get_captured_data, get_component_class, get_component_names, get_config, get_object_printers, get_registered_templates, get_template, get_template_by_class, handleComponentError, has_component, init, init_jquery_plugin, isSequentialProcessing, is_component_name, list_components, logDataChange, logDispatch, logInstruction, logLifecycle, print_object, process_instructions, register, register_cache_class, register_component, register_template, set_preload_data, start_data_capture, stop_data_capture, tracked_attachment_count, version };
 //# sourceMappingURL=jqhtml-core.esm.js.map