@jqhtml/core 2.3.35 → 2.3.50

package/dist/index.js

@@ -34,11 +34,9 @@ class LifecycleManager {
      * Boot a component - run its full lifecycle
      * Called when component is created
      *
-     * Supports lifecycle skip flags:
-     * - skip_render_and_ready: Skip first render/on_render and skip on_ready entirely.
-     *   Component reports ready after on_load completes.
-     * - skip_ready: Skip on_ready only.
-     *   Component reports ready after on_render completes (after potential re-render from on_load).
+     * Supports lifecycle truncation flags:
+     * - _load_only: on_create + on_load only. No render, no children, no on_render, no on_loaded, no on_ready.
+     * - _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);
@@ -50,20 +48,25 @@ class LifecycleManager {
                 return;
             // Trigger create event
             component.trigger('create');
-            // Check for skip_render_and_ready flag
-            const skip_render_and_ready = component._skip_render_and_ready;
-            const skip_ready = component._skip_ready;
+            // Check for lifecycle truncation flags
+            const load_only = component._load_only;
+            const load_render_only = component._load_render_only;
+            const is_detached = component._is_detached;
             let render_id;
-            if (skip_render_and_ready) {
-                // Skip the first render/on_render before on_load
-                // Still need to set render_id to 0 for tracking
+            if (load_only || is_detached) {
+                // _load_only or detached: skip initial render entirely
                 render_id = 0;
                 component._render_count = 0;
             }
+            else if (load_render_only) {
+                // _load_render_only: render to create children, but skip on_render()
+                render_id = component._render(null, { skip_on_render: true });
+                // Check if stopped during render
+                if (component._stopped)
+                    return;
+            }
             else {
-                // Render phase - SYNCHRONOUS, creates DOM and child components
-                // Note: _render() now calls on_render() internally after DOM update
-                // Capture render ID to detect if another render happens before ready
+                // Normal: render with on_render()
                 render_id = component._render();
                 // Check if stopped during render
                 if (component._stopped)
@@ -72,30 +75,39 @@ class LifecycleManager {
             // Load phase - ASYNC, but only if on_load() is overridden
             // Skip entirely if component uses default stub to avoid unnecessary yield
             if (component._has_on_load()) {
+                // Load gates: await any promises registered via gate_load() during
+                // on_create() before the FIRST on_load(). Gates delay ONLY this load
+                // phase — create/render/on_render/cached-paint already happened above.
+                // Released early by reload()/refresh()/stop() while gated (see component).
+                // Returns null (no await) for the common no-gate case to keep timing
+                // identical for ungated components.
+                const gate_wait = component._await_load_gates();
+                if (gate_wait) {
+                    await gate_wait;
+                    // Check if stopped while awaiting gates
+                    if (component._stopped)
+                        return;
+                }
                 await component._load();
                 // Yield to microtask queue after on_load completes
                 // This ensures async queue tasks always run before the on_load process completes,
                 // even if on_load() itself completes instantly (deterministic behavior)
                 await Promise.resolve();
             }
-            // Trigger 'loaded' event - fires after on_load completes (or would have completed)
-            // This happens before the render/on_render second step
-            component.trigger('loaded');
             // Check if stopped during load
             if (component._stopped)
                 return;
-            // If skip_render_and_ready, mark component as ready now and return
-            if (skip_render_and_ready) {
-                // Set ready state and trigger event
+            // If _load_only, mark component as ready now and return
+            if (load_only) {
                 component._ready_state = 4;
                 component._update_debug_attrs();
-                component._log_lifecycle('ready', 'complete (skip_render_and_ready)');
+                component._log_lifecycle('ready', 'complete (_load_only)');
                 component.trigger('ready');
                 return;
             }
-            // If data changed during load, re-render
-            // Note: _render() now calls on_render() internally after DOM update
-            if (component._should_rerender()) {
+            // Detached elements always render here (initial render was skipped)
+            // Normal elements re-render only if data changed during on_load
+            if (is_detached || component._should_rerender()) {
                 // Disable animations during re-render to prevent visual artifacts
                 // from CSS transitions/animations firing on newly rendered elements
                 const $el = component.$;
@@ -112,11 +124,25 @@ class LifecycleManager {
                         }, 5);
                     });
                 }
-                render_id = component._render();
+                // _load_render_only: re-render with skip_on_render to suppress DOM hooks
+                if (load_render_only) {
+                    render_id = component._render(null, { skip_on_render: true });
+                }
+                else {
+                    render_id = component._render();
+                }
                 // Check if stopped during re-render
                 if (component._stopped)
                     return;
             }
+            // _load_render_only: skip waiting for children, on_ready — mark ready and return
+            if (load_render_only) {
+                component._ready_state = 4;
+                component._update_debug_attrs();
+                component._log_lifecycle('ready', 'complete (_load_render_only)');
+                component.trigger('ready');
+                return;
+            }
             // Fire 'rendered' event - component has completed its synchronous render chain
             // This happens once, after the final on_render (whether from first render or re-render after on_load)
             if (!component._has_rendered) {
@@ -140,15 +166,6 @@ class LifecycleManager {
             if (component._render_count !== render_id) {
                 return; // Stale render, don't call ready
             }
-            // If skip_ready, mark component as ready now without calling _ready()
-            if (skip_ready) {
-                // Set ready state and trigger event
-                component._ready_state = 4;
-                component._update_debug_attrs();
-                component._log_lifecycle('ready', 'complete (skip_ready)');
-                component.trigger('ready');
-                return;
-            }
             // Ready phase - waits for children, then calls on_ready()
             await component._ready();
             // Check if stopped during ready
@@ -654,20 +671,26 @@ function process_component_to_html(instruction, html, components, context) {
     // pass this behavior to all child components rendered in its template
     let props = originalProps;
     const parentArgs = context.args;
-    // Check if we need to propagate any flags
-    const propagate_use_cached_data = parentArgs?.use_cached_data === true && props.use_cached_data === undefined;
-    const propagate_skip_render_and_ready = parentArgs?.skip_render_and_ready === true && props.skip_render_and_ready === undefined;
-    const propagate_skip_ready = parentArgs?.skip_ready === true && props.skip_ready === undefined;
-    if (propagate_use_cached_data || propagate_skip_render_and_ready || propagate_skip_ready) {
+    // Check if we need to propagate any flags.
+    // Template-authored flags arrive with the '$' still on the key ($_load_only=false
+    // compiles to props['$_load_only']) - honor both spellings so a child template can
+    // opt out of a cascading parent flag with an explicit false.
+    const own_use_cached_data = props.use_cached_data !== undefined ? props.use_cached_data : props['$use_cached_data'];
+    const own_load_only = props._load_only !== undefined ? props._load_only : props['$_load_only'];
+    const own_load_render_only = props._load_render_only !== undefined ? props._load_render_only : props['$_load_render_only'];
+    const propagate_use_cached_data = parentArgs?.use_cached_data === true && own_use_cached_data === undefined;
+    const propagate_load_only = parentArgs?._load_only === true && own_load_only === undefined;
+    const propagate_load_render_only = parentArgs?._load_render_only === true && own_load_render_only === undefined;
+    if (propagate_use_cached_data || propagate_load_only || propagate_load_render_only) {
         props = { ...originalProps };
         if (propagate_use_cached_data) {
             props.use_cached_data = true;
         }
-        if (propagate_skip_render_and_ready) {
-            props.skip_render_and_ready = true;
+        if (propagate_load_only) {
+            props._load_only = true;
         }
-        if (propagate_skip_ready) {
-            props.skip_ready = true;
+        if (propagate_load_render_only) {
+            props._load_render_only = true;
         }
     }
     // Determine if third parameter is a function (default content) or object (named slots)
@@ -983,6 +1006,14 @@ async function initialize_component(element, compData) {
     if (ComponentClass.name !== name) {
         options._component_name = name;
     }
+    // Pass lifecycle truncation flags via options (not DOM attributes, since _ prefix is filtered).
+    // Accept both the plain key (cascaded/programmatic) and the '$'-prefixed key (template-authored).
+    if (props._load_only === true || props['$_load_only'] === true) {
+        options._load_only = true;
+    }
+    if (props._load_render_only === true || props['$_load_render_only'] === true) {
+        options._load_render_only = true;
+    }
     // Create component instance - element first, then options
     const instance = new ComponentClass(element, options);
     // Set the instantiator (the component that rendered this one in their template)
@@ -1240,7 +1271,8 @@ class Load_Coordinator {
                 continue; // Skip internal properties
             }
             // Skip framework properties that shouldn't affect cache identity
-            if (key === 'use_cached_data' || key === 'skip_render_and_ready' || key === 'skip_ready') {
+            // 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];
@@ -1618,7 +1650,13 @@ function process_for_serialization(value, verbose, seen) {
         // Return undefined to omit this value (not fail entire serialization)
         return undefined;
     }
-    // Handle circular references
+    // 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)) {
         if (verbose) {
             console.warn('[JQHTML Cache] Circular reference detected - cannot serialize');
@@ -1626,69 +1664,89 @@ function process_for_serialization(value, verbose, seen) {
         return undefined; // Fail entire serialization
     }
     seen.add(value);
-    // Handle arrays
-    if (Array.isArray(value)) {
-        const result = [];
-        for (let i = 0; i < value.length; i++) {
-            const item = value[i];
-            const processed = process_for_serialization(item, verbose, seen);
-            // For arrays, we keep undefined as null to preserve indices
-            result.push(processed === undefined ? null : processed);
+    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);
+                // For arrays, we keep undefined as null to preserve indices
+                result.push(processed === undefined ? null : processed);
+            }
+            return result;
         }
-        return result;
-    }
-    // Handle Date objects specially
-    if (value instanceof Date) {
-        return {
-            [CLASS_MARKER]: 'Date',
-            [PROPS_MARKER]: value.toISOString()
-        };
-    }
-    // Handle Map objects
-    if (value instanceof Map) {
-        const entries = [];
-        for (const [k, v] of value) {
-            const processedKey = process_for_serialization(k, verbose, seen);
-            const processedValue = process_for_serialization(v, verbose, seen);
-            entries.push([processedKey, processedValue]);
-        }
-        return {
-            [CLASS_MARKER]: 'Map',
-            [PROPS_MARKER]: entries
-        };
-    }
-    // Handle Set objects
-    if (value instanceof Set) {
-        const items = [];
-        for (const item of value) {
-            items.push(process_for_serialization(item, verbose, seen));
+        // Handle Date objects specially
+        if (value instanceof Date) {
+            return {
+                [CLASS_MARKER]: 'Date',
+                [PROPS_MARKER]: value.toISOString()
+            };
         }
-        return {
-            [CLASS_MARKER]: 'Set',
-            [PROPS_MARKER]: items
-        };
-    }
-    // Get the constructor
-    const ctor = value.constructor;
-    // Handle registered class instances
-    if (ctor && ctor.name && class_registry[ctor.name]) {
-        const props = {};
-        // Extract own enumerable properties (bypass any toJSON method)
-        for (const key of Object.keys(value)) {
-            const propValue = value[key];
-            const processed = process_for_serialization(propValue, verbose, seen);
-            // Only include if not undefined (failed serialization)
-            if (processed !== undefined || propValue === undefined) {
-                props[key] = processed;
+        // Handle Map objects
+        if (value instanceof Map) {
+            const entries = [];
+            for (const [k, v] of value) {
+                const processedKey = process_for_serialization(k, verbose, seen);
+                const processedValue = process_for_serialization(v, verbose, seen);
+                entries.push([processedKey, processedValue]);
+            }
+            return {
+                [CLASS_MARKER]: 'Map',
+                [PROPS_MARKER]: entries
+            };
+        }
+        // Handle Set objects
+        if (value instanceof Set) {
+            const items = [];
+            for (const item of value) {
+                items.push(process_for_serialization(item, verbose, seen));
             }
+            return {
+                [CLASS_MARKER]: 'Set',
+                [PROPS_MARKER]: items
+            };
         }
-        return {
-            [CLASS_MARKER]: ctor.name,
-            [PROPS_MARKER]: props
-        };
-    }
-    // Handle plain objects (constructor is Object or no constructor)
-    if (ctor === Object || ctor === undefined || ctor === null) {
+        // Get the constructor
+        const ctor = value.constructor;
+        // Handle registered class instances
+        if (ctor && ctor.name && class_registry[ctor.name]) {
+            const props = {};
+            // Extract own enumerable properties (bypass any toJSON method)
+            for (const key of Object.keys(value)) {
+                const propValue = value[key];
+                const processed = process_for_serialization(propValue, verbose, seen);
+                // Only include if not undefined (failed serialization)
+                if (processed !== undefined || propValue === undefined) {
+                    props[key] = processed;
+                }
+            }
+            return {
+                [CLASS_MARKER]: ctor.name,
+                [PROPS_MARKER]: props
+            };
+        }
+        // Handle plain objects (constructor is Object or no constructor)
+        if (ctor === Object || ctor === undefined || ctor === null) {
+            const result = {};
+            for (const key of Object.keys(value)) {
+                const propValue = value[key];
+                const processed = process_for_serialization(propValue, verbose, seen);
+                // Only include if not undefined (unless original was undefined)
+                if (processed !== undefined || propValue === undefined) {
+                    result[key] = processed;
+                }
+            }
+            return result;
+        }
+        // Unregistered class instance - convert to plain object for hot/cold parity
+        // This ensures developers catch missing class registrations during development
+        // (methods will be lost, only properties preserved)
+        if (verbose) {
+            console.warn(`[JQHTML Cache] Converting unregistered class "${ctor.name}" to plain object. ` +
+                `Methods will be lost. Call jqhtml.register_cache_class(${ctor.name}) to preserve the class.`);
+        }
+        // Convert to plain object - properties are preserved, prototype methods are lost
         const result = {};
         for (const key of Object.keys(value)) {
             const propValue = value[key];
@@ -1700,24 +1758,10 @@ function process_for_serialization(value, verbose, seen) {
         }
         return result;
     }
-    // Unregistered class instance - convert to plain object for hot/cold parity
-    // This ensures developers catch missing class registrations during development
-    // (methods will be lost, only properties preserved)
-    if (verbose) {
-        console.warn(`[JQHTML Cache] Converting unregistered class "${ctor.name}" to plain object. ` +
-            `Methods will be lost. Call jqhtml.register_cache_class(${ctor.name}) to preserve the class.`);
-    }
-    // Convert to plain object - properties are preserved, prototype methods are lost
-    const result = {};
-    for (const key of Object.keys(value)) {
-        const propValue = value[key];
-        const processed = process_for_serialization(propValue, verbose, seen);
-        // Only include if not undefined (unless original was undefined)
-        if (processed !== undefined || propValue === undefined) {
-            result[key] = processed;
-        }
+    finally {
+        // Pop this object off the ancestor path now that its subtree is done.
+        seen.delete(value);
     }
-    return result;
 }
 // ============================================================================
 // Deserialization (String → Object)
@@ -2136,10 +2180,825 @@ class Jqhtml_Local_Storage {
         }
     }
 }
-Jqhtml_Local_Storage._cache_key = null;
-Jqhtml_Local_Storage._cache_mode = 'data';
-Jqhtml_Local_Storage._storage_available = null;
-Jqhtml_Local_Storage._initialized = false;
+Jqhtml_Local_Storage._cache_key = null;
+Jqhtml_Local_Storage._cache_mode = 'data';
+Jqhtml_Local_Storage._storage_available = null;
+Jqhtml_Local_Storage._initialized = false;
+
+/**
+ * JQHTML Component Event System
+ *
+ * Extracted from component.ts - handles lifecycle event registration,
+ * triggering, and state tracking.
+ *
+ * Events have "sticky" semantics for lifecycle events: if an event has already
+ * occurred, new .on() handlers fire immediately with the stored data.
+ */
+/**
+ * Register a callback for an event.
+ *
+ * Lifecycle events (create, render, load, loaded, ready) are "sticky":
+ * If a lifecycle event has already occurred, the callback fires immediately
+ * AND registers for future occurrences.
+ *
+ * Custom events only fire when explicitly triggered via trigger().
+ *
+ * @param component - The component instance
+ * @param event_name - Name of the event
+ * @param callback - Callback: (component, data?) => void
+ */
+function event_on(component, event_name, callback) {
+    // Initialize callback array for this event if needed
+    if (!component._lifecycle_callbacks.has(event_name)) {
+        component._lifecycle_callbacks.set(event_name, []);
+    }
+    // Add callback to queue
+    component._lifecycle_callbacks.get(event_name).push(callback);
+    // If this lifecycle event has already occurred, fire the callback immediately
+    // with the stored data from when trigger() was called
+    if (component._lifecycle_states.has(event_name)) {
+        try {
+            const stored_data = component._lifecycle_states.get(event_name);
+            callback(component, stored_data);
+        }
+        catch (error) {
+            console.error(`[JQHTML] Error in ${event_name} callback:`, error);
+        }
+    }
+    return component;
+}
+/**
+ * Register a callback that fires exactly once.
+ *
+ * - If the event already occurred (sticky), fires immediately and does NOT register.
+ * - If the event has not occurred, registers and auto-deregisters after first fire.
+ *
+ * @param component - The component instance
+ * @param event_name - Name of the event
+ * @param callback - Callback: (component, data?) => void
+ */
+function event_once(component, event_name, callback) {
+    // If event already occurred, fire immediately and we're done
+    if (component._lifecycle_states.has(event_name)) {
+        try {
+            const stored_data = component._lifecycle_states.get(event_name);
+            callback(component, stored_data);
+        }
+        catch (error) {
+            console.error(`[JQHTML] Error in ${event_name} once callback:`, error);
+        }
+        return component;
+    }
+    // Wrap callback to auto-deregister after first fire
+    const wrapper = (comp, data) => {
+        // Remove ourselves from the callback list
+        const callbacks = component._lifecycle_callbacks.get(event_name);
+        if (callbacks) {
+            const idx = callbacks.indexOf(wrapper);
+            if (idx !== -1)
+                callbacks.splice(idx, 1);
+        }
+        callback(comp, data);
+    };
+    // Initialize callback array for this event if needed
+    if (!component._lifecycle_callbacks.has(event_name)) {
+        component._lifecycle_callbacks.set(event_name, []);
+    }
+    component._lifecycle_callbacks.get(event_name).push(wrapper);
+    return component;
+}
+/**
+ * Trigger an event - fires all registered callbacks.
+ * Marks event as occurred so future .on() calls fire immediately.
+ *
+ * @param component - The component instance
+ * @param event_name - Name of the event to trigger
+ * @param data - Optional data to pass to callbacks as second parameter
+ */
+function event_trigger(component, event_name, data) {
+    // Mark this event as occurred and store the data for late subscribers
+    component._lifecycle_states.set(event_name, data);
+    // Fire all registered callbacks for this event
+    const callbacks = component._lifecycle_callbacks.get(event_name);
+    if (callbacks) {
+        for (const callback of callbacks) {
+            try {
+                callback.bind(component)(component, data);
+            }
+            catch (error) {
+                console.error(`[JQHTML] Error in ${event_name} callback:`, error);
+            }
+        }
+    }
+}
+/**
+ * Check if any callbacks are registered for a given event.
+ *
+ * @param component - The component instance
+ * @param event_name - Name of the event to check
+ */
+function event_on_registered(component, event_name) {
+    const callbacks = component._lifecycle_callbacks.get(event_name);
+    return !!(callbacks && callbacks.length > 0);
+}
+/**
+ * Invalidate a lifecycle event - removes the "already occurred" marker.
+ *
+ * After invalidate() is called:
+ * - New .on() handlers will NOT fire immediately
+ * - The ready() promise will NOT resolve immediately
+ * - Handlers wait for the next trigger() call
+ *
+ * Existing registered callbacks are NOT removed - they'll fire on next trigger().
+ *
+ * Use case: Call invalidate('ready') at the start of reload() or render()
+ * so that any new .on('ready') handlers wait for the reload/render to complete.
+ *
+ * @param component - The component instance
+ * @param event_name - Name of the event to invalidate
+ */
+function event_invalidate(component, event_name) {
+    component._lifecycle_states.delete(event_name);
+}
+
+/**
+ * JQHTML Data Proxy System
+ *
+ * Extracted from component.ts - handles:
+ * - Data freeze/unfreeze enforcement via Proxy
+ * - Detached on_load() execution with restricted access
+ */
+/**
+ * Set up the `this.data` property on a component using Object.defineProperty
+ * with a Proxy that enforces freeze/unfreeze semantics.
+ *
+ * After setup:
+ * - `this.data` reads/writes go through a Proxy
+ * - When `component.__data_frozen === true`, writes throw errors
+ * - When frozen is false, writes pass through normally
+ *
+ * @param component - The component instance to set up data on
+ */
+function setup_data_property(component) {
+    let _data = {};
+    // Helper to create frozen proxy for data object
+    const create_proxy = (obj) => {
+        return new Proxy(obj, {
+            set: (target, prop, value) => {
+                if (component.__data_frozen) {
+                    console.error(`[JQHTML] ERROR: Component "${component.component_name()}" attempted to modify this.data.${String(prop)} outside of on_create() or on_load().\n\n` +
+                        `RESTRICTION: this.data can ONLY be modified in:\n` +
+                        `  - on_create() (set initial defaults, synchronous only)\n` +
+                        `  - on_load() (fetch data from APIs, can be async)\n\n` +
+                        `WHY: this.data represents loaded state. Modifying it outside these methods bypasses the framework's render cycle.\n\n` +
+                        `FIX: Modify this.data in on_create() (for defaults) or on_load() (for fetched data):\n` +
+                        `  ❌ In on_ready(): this.data.${String(prop)} = ${JSON.stringify(value)};\n` +
+                        `  ✅ In on_create(): this.data.${String(prop)} = ${JSON.stringify(value)}; // Set default\n` +
+                        `  ✅ In on_load(): this.data.${String(prop)} = ${JSON.stringify(value)}; // Fetch from API\n` +
+                        `  ✅ For component state: this.args.${String(prop)} = ${JSON.stringify(value)}; (accessible in on_load)`);
+                    throw new Error(`[JQHTML] Cannot modify this.data.${String(prop)} outside of on_create() or on_load(). ` +
+                        `this.data is frozen after on_create() and unfrozen only during on_load().`);
+                }
+                target[prop] = value;
+                return true;
+            },
+            deleteProperty: (target, prop) => {
+                if (component.__data_frozen) {
+                    console.error(`[JQHTML] ERROR: Component "${component.component_name()}" attempted to delete this.data.${String(prop)} outside of on_create() or on_load().\n\n` +
+                        `RESTRICTION: this.data can ONLY be modified in:\n` +
+                        `  - on_create() (set initial defaults, synchronous only)\n` +
+                        `  - on_load() (fetch data from APIs, can be async)\n\n` +
+                        `WHY: this.data represents loaded state. Modifying it outside these methods bypasses the framework's render cycle.`);
+                    throw new Error(`[JQHTML] Cannot delete this.data.${String(prop)} outside of on_create() or on_load(). ` +
+                        `this.data is frozen after on_create() and unfrozen only during on_load().`);
+                }
+                delete target[prop];
+                return true;
+            }
+        });
+    };
+    // Create initial proxied data object
+    _data = create_proxy({});
+    Object.defineProperty(component, 'data', {
+        get: () => _data,
+        set: (value) => {
+            if (component.__data_frozen) {
+                console.error(`[JQHTML] ERROR: Component "${component.component_name()}" attempted to reassign this.data outside of on_create() or on_load().\n\n` +
+                    `RESTRICTION: this.data can ONLY be modified in:\n` +
+                    `  - on_create() (set initial defaults, synchronous only)\n` +
+                    `  - on_load() (fetch data from APIs, can be async)\n\n` +
+                    `WHY: this.data represents loaded state. Modifying it outside these methods bypasses the framework's render cycle.\n\n` +
+                    `FIX: Modify this.data in on_create() (for defaults) or on_load() (for fetched data):\n` +
+                    `  ❌ In on_ready(): this.data = {...};\n` +
+                    `  ✅ In on_create(): this.data.count = 0; // Set default\n` +
+                    `  ✅ In on_load(): this.data = await fetch(...); // Fetch from API\n` +
+                    `  ✅ For component state: this.args.count = 5; (accessible in on_load)`);
+                throw new Error(`[JQHTML] Cannot reassign this.data outside of on_create() or on_load(). ` +
+                    `this.data is frozen after on_create() and unfrozen only during on_load().`);
+            }
+            // When setting, wrap the new value in a proxy too
+            _data = create_proxy(value);
+        },
+        enumerable: true,
+        configurable: false
+    });
+}
+/**
+ * Execute on_load() in a detached context with restricted access.
+ *
+ * Creates a sandboxed environment where on_load() can only access:
+ * - this.args (read-only)
+ * - this.data (read/write, cloned from __initial_data_snapshot)
+ *
+ * All other property access (this.$, this.$sid, etc.) throws errors.
+ *
+ * @param component - The component instance
+ * @param use_load_coordinator - Whether to use Load_Coordinator for deduplication
+ * @returns The resulting data and optional coordination completion function
+ */
+async function execute_on_load_detached(component, use_load_coordinator = false) {
+    // Clone this.data from the snapshot captured after on_create()
+    const data_clone = component.__initial_data_snapshot
+        ? JSON.parse(JSON.stringify(component.__initial_data_snapshot))
+        : {};
+    // Create a read-only proxy for args that blocks all modifications
+    // Can't use JSON clone because args may contain functions (_slots, callbacks)
+    const component_name = component.component_name();
+    const create_readonly_proxy = (obj, path = 'this.args') => {
+        if (obj === null || typeof obj !== 'object')
+            return obj;
+        return new Proxy(obj, {
+            get(target, prop) {
+                const value = target[prop];
+                // Recursively wrap nested objects (but not functions)
+                if (value !== null && typeof value === 'object' && typeof value !== 'function') {
+                    return create_readonly_proxy(value, `${path}.${String(prop)}`);
+                }
+                return value;
+            },
+            set(_target, prop, value) {
+                console.error(`[JQHTML] ERROR: Component "${component_name}" attempted to modify ${path}.${String(prop)} during on_load().\n\n` +
+                    `RESTRICTION: this.args is READ-ONLY during on_load().\n\n` +
+                    `WHY: this.args configures what data to fetch. Modifying it during on_load() creates circular dependencies.\n\n` +
+                    `FIX: Modify this.args BEFORE on_load() runs (in on_create() or before calling reload()):\n` +
+                    `  ❌ Inside on_load(): ${path}.${String(prop)} = ${JSON.stringify(value)};\n` +
+                    `  ✅ In on_create(): this.args.${String(prop)} = defaultValue;`);
+                throw new Error(`[JQHTML] Cannot modify ${path}.${String(prop)} during on_load(). ` +
+                    `this.args is read-only in on_load().`);
+            },
+            deleteProperty(_target, prop) {
+                console.error(`[JQHTML] ERROR: Component "${component_name}" attempted to delete ${path}.${String(prop)} during on_load().\n\n` +
+                    `RESTRICTION: this.args is READ-ONLY during on_load().`);
+                throw new Error(`[JQHTML] Cannot delete ${path}.${String(prop)} during on_load(). ` +
+                    `this.args is read-only in on_load().`);
+            }
+        });
+    };
+    // Create a detached context object that on_load will operate on
+    const detached_context = {
+        args: create_readonly_proxy(component.args), // Read-only proxy wrapping real args
+        data: data_clone // Cloned data - modifications stay isolated
+    };
+    // Create restricted proxy that operates on the detached context
+    const restricted_this = new Proxy(detached_context, {
+        get(target, prop) {
+            // Only allow access to args and data
+            if (prop === 'args') {
+                return target.args;
+            }
+            if (prop === 'data') {
+                return target.data;
+            }
+            // Block everything else
+            console.error(`[JQHTML] ERROR: Component "${component_name}" attempted to access this.${String(prop)} during on_load().\n\n` +
+                `RESTRICTION: on_load() may ONLY access:\n` +
+                `  - this.args (read-only)\n` +
+                `  - this.data (read/write)\n\n` +
+                `WHY: on_load() is for data fetching only. All other component functionality should happen in other lifecycle methods.\n\n` +
+                `FIX:\n` +
+                `  - DOM manipulation → use on_render() or on_ready()\n` +
+                `  - Component methods → call them before/after on_load(), not inside it\n` +
+                `  - Other properties → restructure code to only use this.args and this.data in on_load()`);
+            throw new Error(`[JQHTML] Cannot access this.${String(prop)} during on_load(). ` +
+                `on_load() may only access this.args and this.data.`);
+        },
+        set(target, prop, value) {
+            // Only allow setting data
+            if (prop === 'data') {
+                target.data = value;
+                return true;
+            }
+            // Block setting args
+            if (prop === 'args') {
+                console.error(`[JQHTML] ERROR: Component "${component_name}" attempted to modify this.args during on_load().\n\n` +
+                    `RESTRICTION: on_load() may ONLY modify:\n` +
+                    `  - this.data (read/write)\n\n` +
+                    `WHY: this.args is component state that on_load() depends on. Modifying it inside on_load() creates circular dependencies.\n\n` +
+                    `FIX: Modify this.args BEFORE calling on_load() (in on_create() or other lifecycle methods), not inside on_load():\n` +
+                    `  ❌ Inside on_load(): this.args.filter = 'new_value';\n` +
+                    `  ✅ In on_create(): this.args.filter = this.args.initial_filter || 'default';`);
+                throw new Error(`[JQHTML] Cannot modify this.args during on_load(). ` +
+                    `Modify this.args in other lifecycle methods, not inside on_load().`);
+            }
+            // Block setting any other properties
+            console.error(`[JQHTML] ERROR: Component "${component_name}" attempted to modify this.${String(prop)} during on_load().\n\n` +
+                `RESTRICTION: on_load() may ONLY modify:\n` +
+                `  - this.data (read/write)\n\n` +
+                `WHY: on_load() is for data fetching only. Setting properties on the component instance should happen in other lifecycle methods.\n\n` +
+                `FIX: Store your data in this.data instead:\n` +
+                `  ❌ this.${String(prop)} = value;\n` +
+                `  ✅ this.data.${String(prop)} = value;`);
+            throw new Error(`[JQHTML] Cannot modify this.${String(prop)} during on_load(). ` +
+                `Only this.data can be modified in on_load().`);
+        }
+    });
+    // Create promise for this on_load() call
+    const on_load_promise = (async () => {
+        try {
+            await component._call_lifecycle('on_load', restricted_this);
+        }
+        catch (error) {
+            if (use_load_coordinator) {
+                // Handle error and notify coordinator
+                Load_Coordinator.handle_leader_error(component, error);
+            }
+            throw error;
+        }
+    })();
+    // If using Load_Coordinator, register as leader
+    // Note: We store the completion function but DON'T call it here
+    // It will be called by _load() after _apply_load_result() updates this.data
+    let complete_coordination = null;
+    if (use_load_coordinator) {
+        complete_coordination = Load_Coordinator.register_leader(component, on_load_promise);
+    }
+    await on_load_promise;
+    // Note: We don't validate args changes here because external code (like parent
+    // components calling reload()) is allowed to modify component.args during on_load().
+    // The read-only proxy only prevents code INSIDE on_load() from modifying args.
+    // Return the data from the detached context AND the completion function
+    return {
+        data: detached_context.data,
+        complete_coordination
+    };
+}
+
+/**
+ * JQHTML Component Cache Integration
+ *
+ * Extracted from component.ts - handles cache key generation,
+ * cache reads during create(), cache checks during reload(),
+ * and HTML cache snapshots during ready().
+ *
+ * Uses Jqhtml_Local_Storage as the underlying storage layer.
+ */
+/**
+ * Generate a cache key for a component using its name + args.
+ * Supports custom cache_id() override.
+ *
+ * @param component - The component instance
+ * @returns Cache key string or null if caching is disabled
+ */
+function generate_cache_key(component) {
+    if (typeof component.cache_id === 'function') {
+        try {
+            const custom_cache_id = component.cache_id();
+            return { cache_key: `${component.component_name()}::${String(custom_cache_id)}` };
+        }
+        catch (error) {
+            return { cache_key: null, uncacheable_property: 'cache_id()' };
+        }
+    }
+    // Use standard args-based cache key generation
+    const result = Load_Coordinator.generate_invocation_key(component.component_name(), component.args);
+    return { cache_key: result.key, uncacheable_property: result.uncacheable_property };
+}
+/**
+ * Read cache during create() phase.
+ * Sets component._cache_key, _cached_html, _use_cached_data_hit as side effects.
+ *
+ * @param component - The component instance
+ */
+function read_cache_in_create(component) {
+    const { cache_key, uncacheable_property } = generate_cache_key(component);
+    // If cache_key is null, caching disabled
+    if (cache_key === null) {
+        // Set data-nocache attribute for debugging
+        if (uncacheable_property) {
+            component.$.attr('data-nocache', uncacheable_property);
+        }
+        if (window.jqhtml?.debug?.verbose) {
+            console.log(`[Cache] Component ${component._cid} (${component.component_name()}) has non-serializable args - caching disabled`, { uncacheable_property });
+        }
+        return;
+    }
+    // Store cache key for later use
+    component._cache_key = cache_key;
+    // Get cache mode
+    const cache_mode = Jqhtml_Local_Storage.get_cache_mode();
+    if (window.jqhtml?.debug?.verbose) {
+        console.log(`[Cache ${cache_mode}] Component ${component._cid} (${component.component_name()}) checking cache in create()`, { cache_key, cache_mode, has_cache_key_set: Jqhtml_Local_Storage.has_cache_key() });
+    }
+    if (cache_mode === 'html') {
+        // HTML cache mode - check for cached HTML to inject on first render
+        const html_cache_key = `${cache_key}::html`;
+        const cached_html = Jqhtml_Local_Storage.get(html_cache_key);
+        if (cached_html !== null && typeof cached_html === 'string') {
+            component._cached_html = cached_html;
+            if (window.jqhtml?.debug?.verbose) {
+                console.log(`[Cache html] Component ${component._cid} (${component.component_name()}) found cached HTML`, { cache_key: html_cache_key, html_length: cached_html.length });
+            }
+        }
+        else {
+            if (window.jqhtml?.debug?.verbose) {
+                console.log(`[Cache html] Component ${component._cid} (${component.component_name()}) cache miss`, { cache_key: html_cache_key });
+            }
+        }
+        // Warn if use_cached_data is set in html cache mode
+        if (component.args.use_cached_data === true) {
+            console.warn(`[JQHTML] Component "${component.component_name()}" has use_cached_data=true but cache mode is 'html'.\n` +
+                `use_cached_data only applies to 'data' cache mode. In 'html' mode, the entire rendered HTML is cached.\n` +
+                `The use_cached_data flag will be ignored.`);
+        }
+    }
+    else {
+        // Data cache mode (default) - check for cached data to hydrate this.data
+        const cached_data = Jqhtml_Local_Storage.get(cache_key);
+        if (cached_data !== null && typeof cached_data === 'object') {
+            // Hydrate this.data with cached data
+            component.data = cached_data;
+            if (component.args.use_cached_data === true) {
+                component._use_cached_data_hit = true;
+                if (window.jqhtml?.debug?.verbose) {
+                    console.log(`[Cache data] Component ${component._cid} (${component.component_name()}) using cached data (use_cached_data=true, skipping on_load)`, { cache_key, data: cached_data });
+                }
+            }
+            else {
+                if (window.jqhtml?.debug?.verbose) {
+                    console.log(`[Cache data] Component ${component._cid} (${component.component_name()}) hydrated from cache`, { cache_key, data: cached_data });
+                }
+            }
+        }
+        else {
+            if (window.jqhtml?.debug?.verbose) {
+                console.log(`[Cache data] Component ${component._cid} (${component.component_name()}) cache miss`, { cache_key });
+            }
+        }
+    }
+}
+/**
+ * Check cache during reload() when args have changed.
+ * If cache hit, hydrates data/html and triggers an immediate render.
+ *
+ * @param component - The component instance
+ * @returns true if rendered from cache, false otherwise
+ */
+function check_cache_on_reload(component) {
+    const { cache_key } = generate_cache_key(component);
+    if (cache_key === null) {
+        return false;
+    }
+    const cache_mode = Jqhtml_Local_Storage.get_cache_mode();
+    component._cache_key = cache_key;
+    if (cache_mode === 'html') {
+        // HTML cache mode - check for cached HTML
+        const html_cache_key = `${cache_key}::html`;
+        const cached_html = Jqhtml_Local_Storage.get(html_cache_key);
+        if (cached_html !== null && typeof cached_html === 'string') {
+            if (window.jqhtml?.debug?.verbose) {
+                console.log(`[Cache html] reload() - Component ${component._cid} (${component.component_name()}) found cached HTML (args changed)`, { cache_key: html_cache_key, html_length: cached_html.length });
+            }
+            component._cached_html = cached_html;
+            // Call _render() directly (not render()) since _reload() manages the full lifecycle
+            // Using render() would trigger a separate queue entry and interfere with _reload()'s flow
+            component._render();
+            return true;
+        }
+    }
+    else {
+        // Data cache mode (default) - check for cached data
+        const cached_data = Jqhtml_Local_Storage.get(cache_key);
+        if (cached_data !== null && typeof cached_data === 'object' && JSON.stringify(cached_data) !== '{}') {
+            if (window.jqhtml?.debug?.verbose) {
+                console.log(`[Cache data] reload() - Component ${component._cid} (${component.component_name()}) hydrated from cache (args changed)`, { cache_key, data: cached_data });
+            }
+            // Hydrate this.data with cached data
+            component.__data_frozen = false;
+            component.data = cached_data;
+            component.__data_frozen = true;
+            // Call _render() directly (not render()) since _reload() manages the full lifecycle
+            component._render();
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Write HTML cache snapshot during ready() phase.
+ * Only caches if the component is dynamic (data changed during on_load).
+ *
+ * @param component - The component instance
+ */
+function write_html_cache_snapshot(component) {
+    if (!component._should_cache_html_after_ready || !component._cache_key) {
+        return;
+    }
+    if (component._is_dynamic) {
+        component._should_cache_html_after_ready = false;
+        const html = component.$.html();
+        const html_cache_key = `${component._cache_key}::html`;
+        Jqhtml_Local_Storage.set(html_cache_key, html);
+        if (window.jqhtml?.debug?.verbose) {
+            console.log(`[Cache html] Component ${component._cid} (${component.component_name()}) cached HTML after children on_render complete`, { cache_key: html_cache_key, html_length: html.length });
+        }
+    }
+    else {
+        component._should_cache_html_after_ready = false;
+        if (window.jqhtml?.debug?.verbose) {
+            console.log(`[Cache html] Component ${component._cid} (${component.component_name()}) is static (no data change) - skipping HTML cache`);
+        }
+    }
+}
+/**
+ * Write data/HTML to cache after on_load() completes.
+ * Called from _apply_load_result().
+ *
+ * @param component - The component instance
+ * @param data_changed - Whether this.data changed during on_load
+ */
+function write_cache_on_loaded(component, data_changed) {
+    if (!data_changed || !component._cache_key) {
+        return;
+    }
+    const cache_mode = Jqhtml_Local_Storage.get_cache_mode();
+    if (cache_mode === 'html') {
+        // HTML cache mode - flag to cache HTML after children ready in _ready()
+        component._should_cache_html_after_ready = true;
+        if (window.jqhtml?.debug?.verbose) {
+            console.log(`[Cache html] Component ${component._cid} (${component.component_name()}) will cache HTML after ready`, { cache_key: component._cache_key });
+        }
+    }
+    else {
+        // Data cache mode (default) - write this.data to cache
+        Jqhtml_Local_Storage.set(component._cache_key, component.data);
+        if (window.jqhtml?.debug?.verbose) {
+            console.log(`[Cache data] Component ${component._cid} (${component.component_name()}) cached data after on_load()`, { cache_key: component._cache_key, data: component.data });
+        }
+    }
+}
+
+/**
+ * JQHTML Component Lifecycle Queue
+ *
+ * Serializes lifecycle operations (render, reload, refresh) per component.
+ * Replaces _create_debounced_function with a proper queue that:
+ *
+ * - At most one operation runs at a time per component
+ * - At most one operation is pending (waiting for the current to finish)
+ * - Same-type pending operations collapse (fan-in: all callers share one execution)
+ * - Different-type pending operations: new replaces old (old callers get the new result)
+ *
+ * Boot bypasses this queue entirely - it runs the lifecycle directly.
+ */
+class Component_Queue {
+    constructor() {
+        /** Currently executing operation */
+        this._current = null;
+        /** Next operation waiting to execute after current completes */
+        this._pending = null;
+    }
+    /**
+     * Enqueue a lifecycle operation.
+     *
+     * Behavior:
+     * - Nothing running → execute immediately
+     * - Something running, no pending → create pending entry
+     * - Something running, same type pending → collapse (share pending promise)
+     * - Something running, different type pending → replace pending (all callers get new result)
+     *
+     * @param type - Operation type ('render', 'reload', 'refresh', 'load')
+     * @param executor - The async function to execute
+     * @returns Promise that resolves when the operation completes
+     */
+    enqueue(type, executor) {
+        // If nothing running, execute immediately
+        if (!this._current) {
+            return this._execute(type, executor);
+        }
+        // Something is running — add to pending
+        if (this._pending) {
+            if (this._pending.type === type) {
+                // Same type pending → collapse (fan-in)
+                // All callers share the same future execution
+                return new Promise((resolve, reject) => {
+                    this._pending.resolvers.push(resolve);
+                    this._pending.rejecters.push(reject);
+                });
+            }
+            else {
+                // Different type pending → replace
+                // Old pending callers join the new operation
+                // (their operation was superseded by a different type)
+                const old_resolvers = this._pending.resolvers;
+                const old_rejecters = this._pending.rejecters;
+                return new Promise((resolve, reject) => {
+                    this._pending = {
+                        type,
+                        executor,
+                        resolvers: [...old_resolvers, resolve],
+                        rejecters: [...old_rejecters, reject]
+                    };
+                });
+            }
+        }
+        // No pending entry yet — create one
+        return new Promise((resolve, reject) => {
+            this._pending = {
+                type,
+                executor,
+                resolvers: [resolve],
+                rejecters: [reject]
+            };
+        });
+    }
+    /**
+     * Execute an operation and handle pending queue after completion.
+     * @private
+     */
+    _execute(type, executor) {
+        const promise = (async () => {
+            try {
+                await executor();
+            }
+            finally {
+                this._current = null;
+                // Run pending if exists
+                if (this._pending) {
+                    const pending = this._pending;
+                    this._pending = null;
+                    try {
+                        await this._execute(pending.type, pending.executor);
+                        for (const resolve of pending.resolvers)
+                            resolve();
+                    }
+                    catch (err) {
+                        for (const reject of pending.rejecters)
+                            reject(err);
+                    }
+                }
+            }
+        })();
+        this._current = { type, promise };
+        return promise;
+    }
+    /**
+     * Check if any operation is currently running.
+     */
+    get is_busy() {
+        return this._current !== null;
+    }
+    /**
+     * Check if there's a pending operation waiting.
+     */
+    get has_pending() {
+        return this._pending !== null;
+    }
+}
+
+/**
+ * JQHTML SSR Preload Data System
+ *
+ * Captures component data during SSR rendering and replays it on the client
+ * to skip redundant on_load() calls during hydration.
+ *
+ * Server-side: start_data_capture() → render → get_captured_data()
+ * Client-side: set_preload_data(entries) → components boot with preloaded data → clear_preload_data()
+ */
+// --- Capture (Server Side) ---
+let _capture_enabled = false;
+let _capture_buffer = [];
+// Track captured keys to avoid duplicates from Load Coordinator followers
+let _captured_keys = new Set();
+/**
+ * Enable data capture mode. After this call, every component that completes
+ * on_load() has its final this.data recorded.
+ *
+ * Idempotent — calling twice is fine.
+ */
+function start_data_capture() {
+    _capture_enabled = true;
+    _capture_buffer = [];
+    _captured_keys.clear();
+}
+/**
+ * Record a component's data after on_load() completes.
+ * Called internally from _apply_load_result().
+ *
+ * @param component_name - Component name
+ * @param args - Component args at time of on_load()
+ * @param data - this.data after on_load() completed
+ * @param cache_key - The cache key for deduplication (null = always capture)
+ */
+function capture_component_data(component_name, args, data, cache_key) {
+    if (!_capture_enabled)
+        return;
+    // Deduplicate: if Load Coordinator already captured this key, skip
+    if (cache_key !== null) {
+        if (_captured_keys.has(cache_key))
+            return;
+        _captured_keys.add(cache_key);
+    }
+    // Deep clone args and data to plain objects (no proxies, no class instances)
+    try {
+        const cloned_args = JSON.parse(JSON.stringify(args));
+        const cloned_data = JSON.parse(JSON.stringify(data));
+        _capture_buffer.push({
+            component: component_name,
+            args: cloned_args,
+            data: cloned_data,
+        });
+    }
+    catch (error) {
+        // Non-serializable data — skip capture for this component
+        if (typeof console !== 'undefined') {
+            console.warn(`[JQHTML SSR Capture] Failed to serialize data for ${component_name}:`, error);
+        }
+    }
+}
+/**
+ * Returns all captured component data and resets the capture buffer.
+ * One-shot: calling clears the buffer.
+ */
+function get_captured_data() {
+    const result = _capture_buffer;
+    _capture_buffer = [];
+    _captured_keys.clear();
+    return result;
+}
+/**
+ * Check if data capture is currently enabled.
+ */
+function is_capture_enabled() {
+    return _capture_enabled;
+}
+/**
+ * Stop data capture and clear all state.
+ */
+function stop_data_capture() {
+    _capture_enabled = false;
+    _capture_buffer = [];
+    _captured_keys.clear();
+}
+// --- Preload (Client Side) ---
+let _preload_cache = new Map();
+/**
+ * Seed the preload cache with SSR-captured data.
+ * Must be called before any component _load() runs.
+ *
+ * @param entries - Array of { component, args, data } entries from get_captured_data()
+ */
+function set_preload_data(entries) {
+    if (!entries || entries.length === 0)
+        return;
+    _preload_cache.clear();
+    for (const entry of entries) {
+        // Generate key using the same algorithm as Load Coordinator
+        const result = Load_Coordinator.generate_invocation_key(entry.component, entry.args);
+        if (result.key !== null) {
+            _preload_cache.set(result.key, entry.data);
+        }
+    }
+}
+/**
+ * Check if preloaded data exists for a given cache key.
+ * If found, returns the data and removes the entry (one-shot).
+ *
+ * @param cache_key - The cache key (same format as Load Coordinator)
+ * @returns The preloaded data, or null if no match
+ */
+function consume_preload_data(cache_key) {
+    if (_preload_cache.size === 0)
+        return null;
+    const data = _preload_cache.get(cache_key);
+    if (data !== undefined) {
+        _preload_cache.delete(cache_key);
+        return data;
+    }
+    return null;
+}
+/**
+ * Clear any remaining unconsumed preload entries.
+ * Call after initial page hydration is complete.
+ */
+function clear_preload_data() {
+    _preload_cache.clear();
+}
+/**
+ * Check if any preload data is available (for fast early exit in _load).
+ */
+function has_preload_data() {
+    return _preload_cache.size > 0;
+}
 
 /**
  * JQHTML v2 Component Base Class
@@ -2171,6 +3030,7 @@ class Jqhtml_Component {
         this._data_on_last_render = null; // Data snapshot from last render (for refresh() comparison)
         this.__initial_data_snapshot = null; // Snapshot of this.data after on_create() for restoration before on_load()
         this.__data_frozen = false; // Track if this.data is currently frozen
+        this._queue = new Component_Queue(); // Lifecycle operation queue (render/reload/refresh)
         this.next_reload_force_refresh = null; // State machine for reload()/refresh() debounce precedence
         this.__lifecycle_authorized = false; // Flag for lifecycle method protection
         // Cache mode properties
@@ -2184,12 +3044,17 @@ class Jqhtml_Component {
         this._on_render_complete = false; // True after on_render() has been called post-on_load
         // use_cached_data feature - skip on_load() when cache hit occurs
         this._use_cached_data_hit = false; // True if use_cached_data=true AND cache was used
-        // skip_render_and_ready feature - skip first render/on_render and on_ready entirely
-        // Component reports ready after on_load completes
-        this._skip_render_and_ready = false;
-        // skip_ready feature - skip on_ready only
-        // Component reports ready after on_render completes
-        this._skip_ready = false;
+        // _load_only: create + load only. No render, no children, no on_render, no on_loaded, no on_ready.
+        this._load_only = false;
+        // _load_render_only: create + render + load + re-render. No on_render, no on_loaded, no on_ready.
+        this._load_render_only = false;
+        // Detached optimization: true when element is not in the DOM at boot time.
+        // Skips initial render and cache read — just on_load then render.
+        // Override with _force_initial_render to keep normal double-render behavior.
+        this._is_detached = false;
+        // _force_initial_render: override detached optimization — render even when not in DOM.
+        // Use when you need the loading spinner visible immediately after appending.
+        this._force_initial_render = false;
         // rendered event - fires once after the synchronous render chain completes
         // (after on_load's re-render if applicable, or after first render if no on_load)
         this._has_rendered = false;
@@ -2200,6 +3065,11 @@ class Jqhtml_Component {
         // Set in constructor (prototype chain is established before constructor runs)
         // Used to skip expensive cache/load operations for static components
         this.__has_custom_on_load = false;
+        // gate_load() — "load gates" registered during on_create() that must settle
+        // before the component's FIRST on_load() runs. See gate_load() / _await_load_gates().
+        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)
         // 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
@@ -2241,12 +3111,15 @@ class Jqhtml_Component {
         // Merge in order: defineArgs (defaults from Define tag) < dataAttrs < args (invocation overrides)
         const defineArgs = template_for_args?.defineArgs || {};
         this.args = { ...defineArgs, ...dataAttrs, ...args };
-        // Set lifecycle skip flags from args
-        if (this.args.skip_render_and_ready === true) {
-            this._skip_render_and_ready = true;
+        // Set lifecycle truncation flags from args
+        if (this.args._load_only === true) {
+            this._load_only = true;
+        }
+        if (this.args._load_render_only === true) {
+            this._load_render_only = true;
         }
-        if (this.args.skip_ready === true) {
-            this._skip_ready = true;
+        if (this.args._force_initial_render === true) {
+            this._force_initial_render = true;
         }
         // Attach component to element
         this.$.data('_component', this);
@@ -2257,68 +3130,8 @@ class Jqhtml_Component {
         // Find DOM parent component (for lifecycle coordination)
         this._find_dom_parent();
         // Setup data property with freeze enforcement using Proxy
-        let _data = {};
-        // Helper to create frozen proxy for data object
-        const createDataProxy = (obj) => {
-            return new Proxy(obj, {
-                set: (target, prop, value) => {
-                    if (this.__data_frozen) {
-                        console.error(`[JQHTML] ERROR: Component "${this.component_name()}" attempted to modify this.data.${String(prop)} outside of on_create() or on_load().\n\n` +
-                            `RESTRICTION: this.data can ONLY be modified in:\n` +
-                            `  - on_create() (set initial defaults, synchronous only)\n` +
-                            `  - on_load() (fetch data from APIs, can be async)\n\n` +
-                            `WHY: this.data represents loaded state. Modifying it outside these methods bypasses the framework's render cycle.\n\n` +
-                            `FIX: Modify this.data in on_create() (for defaults) or on_load() (for fetched data):\n` +
-                            `  ❌ In on_ready(): this.data.${String(prop)} = ${JSON.stringify(value)};\n` +
-                            `  ✅ In on_create(): this.data.${String(prop)} = ${JSON.stringify(value)}; // Set default\n` +
-                            `  ✅ In on_load(): this.data.${String(prop)} = ${JSON.stringify(value)}; // Fetch from API\n` +
-                            `  ✅ For component state: this.args.${String(prop)} = ${JSON.stringify(value)}; (accessible in on_load)`);
-                        throw new Error(`[JQHTML] Cannot modify this.data.${String(prop)} outside of on_create() or on_load(). ` +
-                            `this.data is frozen after on_create() and unfrozen only during on_load().`);
-                    }
-                    target[prop] = value;
-                    return true;
-                },
-                deleteProperty: (target, prop) => {
-                    if (this.__data_frozen) {
-                        console.error(`[JQHTML] ERROR: Component "${this.component_name()}" attempted to delete this.data.${String(prop)} outside of on_create() or on_load().\n\n` +
-                            `RESTRICTION: this.data can ONLY be modified in:\n` +
-                            `  - on_create() (set initial defaults, synchronous only)\n` +
-                            `  - on_load() (fetch data from APIs, can be async)\n\n` +
-                            `WHY: this.data represents loaded state. Modifying it outside these methods bypasses the framework's render cycle.`);
-                        throw new Error(`[JQHTML] Cannot delete this.data.${String(prop)} outside of on_create() or on_load(). ` +
-                            `this.data is frozen after on_create() and unfrozen only during on_load().`);
-                    }
-                    delete target[prop];
-                    return true;
-                }
-            });
-        };
-        // Create initial proxied data object
-        _data = createDataProxy({});
-        Object.defineProperty(this, 'data', {
-            get: () => _data,
-            set: (value) => {
-                if (this.__data_frozen) {
-                    console.error(`[JQHTML] ERROR: Component "${this.component_name()}" attempted to reassign this.data outside of on_create() or on_load().\n\n` +
-                        `RESTRICTION: this.data can ONLY be modified in:\n` +
-                        `  - on_create() (set initial defaults, synchronous only)\n` +
-                        `  - on_load() (fetch data from APIs, can be async)\n\n` +
-                        `WHY: this.data represents loaded state. Modifying it outside these methods bypasses the framework's render cycle.\n\n` +
-                        `FIX: Modify this.data in on_create() (for defaults) or on_load() (for fetched data):\n` +
-                        `  ❌ In on_ready(): this.data = {...};\n` +
-                        `  ✅ In on_create(): this.data.count = 0; // Set default\n` +
-                        `  ✅ In on_load(): this.data = await fetch(...); // Fetch from API\n` +
-                        `  ✅ For component state: this.args.count = 5; (accessible in on_load)`);
-                    throw new Error(`[JQHTML] Cannot reassign this.data outside of on_create() or on_load(). ` +
-                        `this.data is frozen after on_create() and unfrozen only during on_load().`);
-                }
-                // When setting, wrap the new value in a proxy too
-                _data = createDataProxy(value);
-            },
-            enumerable: true,
-            configurable: false
-        });
+        // @see data-proxy.ts for full implementation
+        setup_data_property(this);
         // 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 = {};
@@ -2420,7 +3233,7 @@ class Jqhtml_Component {
      * @returns The current _render_count after incrementing (used to detect stale renders)
      * @private
      */
-    _render(id = null) {
+    _render(id = null, options = {}) {
         // Increment render count to track this specific render
         this._render_count++;
         const current_render_id = this._render_count;
@@ -2441,7 +3254,7 @@ class Jqhtml_Component {
                     `Element with $sid="${id}" exists but is not initialized as a component.\n` +
                     `Add $redrawable attribute or make it a proper component.`);
             }
-            return child._render();
+            return child._render(null, options);
         }
         this._log_lifecycle('render', 'start');
         // HTML CACHE MODE - If we have cached HTML, inject it directly and skip template rendering
@@ -2458,13 +3271,13 @@ class Jqhtml_Component {
             // Mark first render complete
             this._did_first_render = true;
             this._log_lifecycle('render', 'complete (cached HTML)');
-            // NEW ARCHITECTURE: Call on_render() even after cache inject
-            // This ensures consistent behavior - on_render() always runs after DOM update
-            // Note: this.data has defaults from on_create(), not fresh data yet
-            const cacheRenderResult = this._call_lifecycle_sync('on_render');
-            if (cacheRenderResult && typeof cacheRenderResult.then === 'function') {
-                console.warn(`[JQHTML] Component "${this.component_name()}" returned a Promise from on_render(). ` +
-                    `on_render() must be synchronous code. Remove 'async' from the function declaration.`);
+            // Call on_render() after cache inject (unless suppressed by _load_render_only)
+            if (!options.skip_on_render) {
+                const cacheRenderResult = this._call_lifecycle_sync('on_render');
+                if (cacheRenderResult && typeof cacheRenderResult.then === 'function') {
+                    console.warn(`[JQHTML] Component "${this.component_name()}" returned a Promise from on_render(). ` +
+                        `on_render() must be synchronous code. Remove 'async' from the function declaration.`);
+                }
             }
             // Emit lifecycle event
             this.trigger('render');
@@ -2649,18 +3462,13 @@ class Jqhtml_Component {
         // Don't update ready state here - let phases complete in order
         this._update_debug_attrs();
         this._log_lifecycle('render', 'complete');
-        // Call on_render() with authorization (sync) immediately after render completes
-        // This ensures event handlers are always re-attached after DOM updates
-        //
-        // NEW ARCHITECTURE: on_render() can now access this.data normally
-        // The HTML cache mode now properly synchronizes - on_render() runs after both:
-        // 1. Cache inject (with on_create() defaults)
-        // 2. Second render (with fresh data from on_load())
-        // Since on_render() always runs with appropriate data, no proxy restriction needed
-        const renderResult = this._call_lifecycle_sync('on_render');
-        if (renderResult && typeof renderResult.then === 'function') {
-            console.warn(`[JQHTML] Component "${this.component_name()}" returned a Promise from on_render(). ` +
-                `on_render() must be synchronous code. Remove 'async' from the function declaration.`);
+        // Call on_render() after render completes (unless suppressed by _load_render_only)
+        if (!options.skip_on_render) {
+            const renderResult = this._call_lifecycle_sync('on_render');
+            if (renderResult && typeof renderResult.then === 'function') {
+                console.warn(`[JQHTML] Component "${this.component_name()}" returned a Promise from on_render(). ` +
+                    `on_render() must be synchronous code. Remove 'async' from the function declaration.`);
+            }
         }
         // Emit lifecycle event
         this.trigger('render');
@@ -2690,18 +3498,18 @@ class Jqhtml_Component {
      * Public render method - re-renders component and completes lifecycle
      * This is what users should call when they want to update a component.
      *
-     * Lifecycle sequence:
+     * Lifecycle sequence (serialized via component queue):
      * 1. _render() - Updates DOM synchronously, calls on_render(), fires 'render' event
-     * 2. Async continuation (fire and forget):
-     *    - _wait_for_children_ready() - Waits for all children to reach ready state
-     *    - on_ready() - Calls user's ready hook
-     *    - trigger('ready') - Fires ready event
+     * 2. _wait_for_children_ready() - Waits for all children to reach ready state
+     * 3. on_ready() - Calls user's ready hook
+     * 4. trigger('ready') - Fires ready event
      *
-     * Returns immediately after _render() completes - does NOT wait for children
+     * Goes through the component queue to prevent concurrent lifecycle operations.
+     * Returns a Promise that resolves when the full render lifecycle completes.
      */
     render(id = null) {
         if (this._stopped)
-            return;
+            return Promise.resolve();
         // Invalidate ready event so new handlers wait for this render cycle to complete
         // This prevents .on('ready') handlers from firing immediately based on previous lifecycle
         this.invalidate('ready');
@@ -2720,10 +3528,12 @@ class Jqhtml_Component {
             }
             return child.render();
         }
-        // Execute render phase synchronously and capture render ID
-        const render_id = this._render();
-        // Fire off async lifecycle completion in background (don't await)
-        (async () => {
+        // Enqueue the full render lifecycle through the component queue
+        // Return the queue promise so `await this.render()` resolves when the
+        // full render lifecycle (DOM update, children ready, on_ready) completes
+        return this._queue.enqueue('render', async () => {
+            // Execute render phase synchronously and capture render ID
+            const render_id = this._render();
             // Wait for all child components to be ready
             await this._wait_for_children_ready();
             // Check if this render is still current before calling on_ready
@@ -2734,8 +3544,8 @@ class Jqhtml_Component {
             // Call on_ready hook with authorization
             await this._call_lifecycle('on_ready');
             // Trigger ready event
-            await this.trigger('ready');
-        })();
+            this.trigger('ready');
+        });
     }
     /**
      * Alias for render() - re-renders component with current data
@@ -2744,6 +3554,70 @@ class Jqhtml_Component {
     redraw(id = null) {
         return this.render(id);
     }
+    /**
+     * Re-fetch data by executing on_load() without triggering re-render or lifecycle.
+     *
+     * Runs on_load() on a detached proxy (same restrictions as during boot):
+     *   - this.data is restored to on_create() snapshot, then unfrozen for writing
+     *   - this.args is read-only
+     *   - All other properties (this.$, this.$sid, etc.) are blocked
+     *
+     * After on_load() completes, this.data is atomically updated and re-frozen.
+     * The developer decides what to do next (e.g., call this.render()).
+     *
+     * Pattern: load() invokes on_load(), just as render() invokes on_render().
+     *
+     * @returns true if this.data changed, false if unchanged
+     */
+    async load() {
+        if (this._stopped)
+            return false;
+        // Capture result through queue closure
+        let data_changed = false;
+        await this._queue.enqueue('load', async () => {
+            // Snapshot current data for change detection
+            const data_before = JSON.stringify(this.data);
+            // Execute on_load() on detached proxy (restores data to on_create snapshot)
+            const { data: result_data } = await this._execute_on_load_detached(false);
+            // Atomically update this.data: unfreeze → assign → normalize → refreeze
+            this.__data_frozen = false;
+            this.data = result_data;
+            const cache_mode = Jqhtml_Local_Storage.get_cache_mode();
+            if (cache_mode === 'data') {
+                const normalized = Jqhtml_Local_Storage.normalize_for_cache(this.data);
+                this.data = normalized;
+            }
+            this.__data_frozen = true;
+            // Detect if data changed
+            const data_after = JSON.stringify(this.data);
+            data_changed = data_before !== data_after;
+            // Update cache with fresh data if changed
+            if (data_changed) {
+                // Regenerate cache key (args may have changed since boot)
+                let cache_key = null;
+                if (typeof this.cache_id === 'function') {
+                    try {
+                        cache_key = `${this.component_name()}::${String(this.cache_id())}`;
+                    }
+                    catch { /* cache_id() threw - skip caching */ }
+                }
+                else {
+                    const result = Load_Coordinator.generate_invocation_key(this.component_name(), this.args);
+                    cache_key = result.key;
+                }
+                if (cache_key && cache_mode !== 'html') {
+                    Jqhtml_Local_Storage.set(cache_key, this.data);
+                }
+            }
+            // Call on_loaded() on the real component (this.data frozen, full access to this.$, this.state)
+            // Suppressed by _load_only and _load_render_only flags (preloading mode)
+            if (!this._load_only && !this._load_render_only) {
+                await this._call_lifecycle('on_loaded');
+                this.trigger('loaded');
+            }
+        });
+        return data_changed;
+    }
     /**
      * Create phase - Quick setup, prepare UI
      * SYNCHRONOUS - no awaits, no yields
@@ -2759,97 +3633,17 @@ class Jqhtml_Component {
                 `on_create() must be synchronous code. Remove 'async' from the function declaration.`);
             // Don't await - on_create MUST be sync. The warning is enough.
         }
+        // Detect detached elements — skip cache and initial render for elements not in DOM
+        // _force_initial_render overrides this optimization
+        this._is_detached = !this.$[0].isConnected && !this._force_initial_render;
         // OPTIMIZATION: Skip cache operations and snapshot if no custom on_load()
         // Components without on_load() don't fetch data, so nothing to cache or restore
         if (this.__has_custom_on_load) {
             // CACHE CHECK - Read from cache based on cache mode ('data' or 'html')
-            // This happens after on_create() but before render, allowing instant first render
-            // Check if component implements cache_id() for custom cache key
-            let cache_key = null;
-            let uncacheable_property;
-            if (typeof this.cache_id === 'function') {
-                try {
-                    const custom_cache_id = this.cache_id();
-                    cache_key = `${this.component_name()}::${String(custom_cache_id)}`;
-                }
-                catch (error) {
-                    // cache_id() threw error - disable caching
-                    uncacheable_property = 'cache_id()';
-                }
-            }
-            else {
-                // Use standard args-based cache key generation
-                const result = Load_Coordinator.generate_invocation_key(this.component_name(), this.args);
-                cache_key = result.key;
-                uncacheable_property = result.uncacheable_property;
-            }
-            // If cache_key is null, caching disabled
-            if (cache_key === null) {
-                // Set data-nocache attribute for debugging (shows which property prevented caching)
-                if (uncacheable_property) {
-                    this.$.attr('data-nocache', uncacheable_property);
-                }
-                if (window.jqhtml?.debug?.verbose) {
-                    console.log(`[Cache] Component ${this._cid} (${this.component_name()}) has non-serializable args - caching disabled`, { uncacheable_property });
-                }
-                // Don't return - continue to snapshot this.data for on_load restoration
-            }
-            else {
-                // Store cache key for later use
-                this._cache_key = cache_key;
-                // Get cache mode
-                const cache_mode = Jqhtml_Local_Storage.get_cache_mode();
-                if (window.jqhtml?.debug?.verbose) {
-                    console.log(`[Cache ${cache_mode}] Component ${this._cid} (${this.component_name()}) checking cache in create()`, { cache_key, cache_mode, has_cache_key_set: Jqhtml_Local_Storage.has_cache_key() });
-                }
-                if (cache_mode === 'html') {
-                    // HTML cache mode - check for cached HTML to inject on first render
-                    const html_cache_key = `${cache_key}::html`;
-                    const cached_html = Jqhtml_Local_Storage.get(html_cache_key);
-                    if (cached_html !== null && typeof cached_html === 'string') {
-                        // Store cached HTML for injection in _render()
-                        this._cached_html = cached_html;
-                        if (window.jqhtml?.debug?.verbose) {
-                            console.log(`[Cache html] Component ${this._cid} (${this.component_name()}) found cached HTML`, { cache_key: html_cache_key, html_length: cached_html.length });
-                        }
-                    }
-                    else {
-                        if (window.jqhtml?.debug?.verbose) {
-                            console.log(`[Cache html] Component ${this._cid} (${this.component_name()}) cache miss`, { cache_key: html_cache_key });
-                        }
-                    }
-                    // Warn if use_cached_data is set in html cache mode - it has no effect
-                    if (this.args.use_cached_data === true) {
-                        console.warn(`[JQHTML] Component "${this.component_name()}" has use_cached_data=true but cache mode is 'html'.\n` +
-                            `use_cached_data only applies to 'data' cache mode. In 'html' mode, the entire rendered HTML is cached.\n` +
-                            `The use_cached_data flag will be ignored.`);
-                    }
-                }
-                else {
-                    // Data cache mode (default) - check for cached data to hydrate this.data
-                    const cached_data = Jqhtml_Local_Storage.get(cache_key);
-                    if (cached_data !== null && typeof cached_data === 'object') {
-                        // Hydrate this.data with cached data
-                        this.data = cached_data;
-                        // If use_cached_data=true, skip on_load() entirely - use cached data as final data
-                        if (this.args.use_cached_data === true) {
-                            this._use_cached_data_hit = true;
-                            if (window.jqhtml?.debug?.verbose) {
-                                console.log(`[Cache data] Component ${this._cid} (${this.component_name()}) using cached data (use_cached_data=true, skipping on_load)`, { cache_key, data: cached_data });
-                            }
-                        }
-                        else {
-                            if (window.jqhtml?.debug?.verbose) {
-                                console.log(`[Cache data] Component ${this._cid} (${this.component_name()}) hydrated from cache`, { cache_key, data: cached_data });
-                            }
-                        }
-                    }
-                    else {
-                        if (window.jqhtml?.debug?.verbose) {
-                            console.log(`[Cache data] Component ${this._cid} (${this.component_name()}) cache miss`, { cache_key });
-                        }
-                    }
-                }
+            // Skip cache for detached elements — no point hydrating from cache when not in DOM
+            // @see component-cache.ts for full implementation
+            if (!this._is_detached) {
+                read_cache_in_create(this);
             }
             // Snapshot this.data after on_create() completes
             // This will be restored before each on_load() execution to reset state
@@ -2863,6 +3657,90 @@ class Jqhtml_Component {
         // Emit lifecycle event
         this.trigger('create');
     }
+    /**
+     * Register a "load gate" — a promise that must settle before this component's
+     * FIRST on_load() runs.
+     *
+     * Register gates during on_create(). Multiple calls accumulate; all gates are
+     * awaited together (via Promise.allSettled) at the seam between create and the
+     * first load. A REJECTED gate does NOT block or abort the load — it is an
+     * ordering hint, not a data dependency, so loading proceeds after settlement
+     * (rejections are logged through the debug channel).
+     *
+     * Gates are ONE-SHOT: they delay the first on_load() only. Once that load
+     * begins the gate list is cleared, and reload()/refresh() never re-await gates.
+     * Calling reload()/refresh() while a gate is still holding the first load
+     * releases the wait immediately and resumes the lifecycle (a later gate
+     * settlement then does nothing).
+     *
+     * Gates delay ONLY the on_load phase — never create(), the initial render,
+     * on_render(), or the cached-content first paint (stale-while-revalidate is
+     * preserved). Components with no custom on_load() ignore gates entirely.
+     *
+     * No-op during SSR (the server cannot await arbitrary client promises).
+     *
+     * jqhtml has no knowledge of WHAT is being awaited — the caller supplies the
+     * promise, and policy such as timeouts is the caller's responsibility (bake it
+     * into the promise you pass).
+     *
+     * @param promise The promise to await before the first on_load().
+     * @throws If called after the component's first load has already started.
+     */
+    gate_load(promise) {
+        if (this.__first_load_started) {
+            throw new Error(`[JQHTML] gate_load() may only be called before the component's first load - ` +
+                `register gates in on_create(). ` +
+                `Component: ${this.component_name()} (_cid: ${this._cid})`);
+        }
+        this.__load_gates.push(promise);
+    }
+    /**
+     * Await all registered load gates before the first on_load().
+     *
+     * Called exactly once, at the boot seam immediately before the load phase
+     * (only for components with a custom on_load()). Latches "first load started"
+     * so any later gate_load() throws and reload()/refresh() never re-await.
+     *
+     * Returns a promise to await when there are gates to wait on, or `null` when
+     * there is nothing to wait for (no gates, or SSR). Returning `null` keeps the
+     * common no-gate path free of an extra microtask hop, so it does not shift the
+     * timing of ungated components.
+     *
+     * The returned promise resolves as soon as any of the following happens
+     * (whichever is first — the rest become no-ops):
+     *   - all gates settle (Promise.allSettled),
+     *   - reload()/refresh() is called while gated (they resolve __gate_resume),
+     *   - the component is stopped (stop() resolves __gate_resume).
+     *
+     * @private
+     */
+    _await_load_gates() {
+        // Latch (synchronous): from here on, gate_load() throws and this runs at
+        // most once — set even when there are no gates so point 2 always holds.
+        this.__first_load_started = true;
+        const gates = this.__load_gates;
+        this.__load_gates = [];
+        // Nothing to gate, or SSR (cannot await arbitrary client promises) — proceed now.
+        if (gates.length === 0 || is_capture_enabled())
+            return null;
+        // Promise.allSettled never rejects; rejected gates are logged (debug channel)
+        // whenever they settle, independent of whether the wait was resumed early.
+        const settled = Promise.allSettled(gates);
+        settled.then((results) => {
+            for (const result of results) {
+                if (result.status === 'rejected' && window.jqhtml?.debug?.verbose) {
+                    console.log(`[JQHTML gate_load] Component ${this._cid} (${this.component_name()}) gate rejected (ignored, load proceeds)`, result.reason);
+                }
+            }
+        });
+        // Race gate settlement against an early-resume signal (reload/refresh/stop while gated).
+        return new Promise((resolve) => {
+            this.__gate_resume = resolve;
+            settled.then(() => resolve());
+        }).then(() => {
+            this.__gate_resume = null;
+        });
+    }
     /**
      * Load phase - Fetch asynchronous data
      * Called bottom-up, fully parallel
@@ -2885,9 +3763,13 @@ class Jqhtml_Component {
             this._update_debug_attrs();
             this._log_lifecycle('load', 'complete (use_cached_data - skipped on_load)');
             this.trigger('load');
+            if (!this._load_only && !this._load_render_only) {
+                await this._call_lifecycle('on_loaded');
+                this.trigger('loaded');
+            }
             return;
         }
-        // Check if component implements cache_id() for custom cache key
+        // Generate cache key (needed for both preload check and load deduplication)
         let cache_key = null;
         let uncacheable_property;
         if (typeof this.cache_id === 'function') {
@@ -2906,6 +3788,19 @@ class Jqhtml_Component {
             cache_key = result.key;
             uncacheable_property = result.uncacheable_property;
         }
+        // SSR preload check: if preloaded data exists for this component+args, use it
+        if (cache_key !== null && has_preload_data()) {
+            const preloaded_data = consume_preload_data(cache_key);
+            if (preloaded_data !== null) {
+                this._cache_key = cache_key;
+                if (window.jqhtml?.debug?.verbose) {
+                    console.log(`[SSR Preload] Component ${this._cid} (${this.component_name()}) using preloaded data`, { cache_key });
+                }
+                const data_before_load = JSON.stringify(this.data);
+                await this._apply_load_result(preloaded_data, data_before_load);
+                return;
+            }
+        }
         // Store cache key for later use
         this._cache_key = cache_key;
         // If cache_key is null, args are not serializable - skip load deduplication and caching
@@ -2961,6 +3856,10 @@ class Jqhtml_Component {
             this._update_debug_attrs();
             this._log_lifecycle('load', 'complete (follower)');
             this.trigger('load');
+            if (!this._load_only && !this._load_render_only) {
+                await this._call_lifecycle('on_loaded');
+                this.trigger('loaded');
+            }
             return;
         }
         // This component is a leader - execute on_load() on detached proxy
@@ -2979,143 +3878,11 @@ class Jqhtml_Component {
     }
     /**
      * Execute on_load() on a fully detached proxy.
-     *
-     * The proxy has:
-     * - A CLONE of this.data (from __initial_data_snapshot)
-     * - Read-only access to this.args
-     * - No access to anything else (this.$, this.sid, etc.)
-     *
-     * This ensures on_load runs completely isolated from the component instance.
-     *
-     * @param use_load_coordinator - If true, register with Load_Coordinator for deduplication
-     * @returns The resulting data from the proxy after on_load completes
+     * @see data-proxy.ts for full implementation
      * @private
      */
     async _execute_on_load_detached(use_load_coordinator = false) {
-        // Clone this.data from the snapshot captured after on_create()
-        const data_clone = this.__initial_data_snapshot
-            ? JSON.parse(JSON.stringify(this.__initial_data_snapshot))
-            : {};
-        // Create a read-only proxy for args that blocks all modifications
-        // Can't use JSON clone because args may contain functions (_slots, callbacks)
-        const create_readonly_proxy = (obj, path = 'this.args') => {
-            if (obj === null || typeof obj !== 'object')
-                return obj;
-            return new Proxy(obj, {
-                get(target, prop) {
-                    const value = target[prop];
-                    // Recursively wrap nested objects (but not functions)
-                    if (value !== null && typeof value === 'object' && typeof value !== 'function') {
-                        return create_readonly_proxy(value, `${path}.${String(prop)}`);
-                    }
-                    return value;
-                },
-                set(target, prop, value) {
-                    console.error(`[JQHTML] ERROR: Component "${component_name}" attempted to modify ${path}.${String(prop)} during on_load().\n\n` +
-                        `RESTRICTION: this.args is READ-ONLY during on_load().\n\n` +
-                        `WHY: this.args configures what data to fetch. Modifying it during on_load() creates circular dependencies.\n\n` +
-                        `FIX: Modify this.args BEFORE on_load() runs (in on_create() or before calling reload()):\n` +
-                        `  ❌ Inside on_load(): ${path}.${String(prop)} = ${JSON.stringify(value)};\n` +
-                        `  ✅ In on_create(): this.args.${String(prop)} = defaultValue;`);
-                    throw new Error(`[JQHTML] Cannot modify ${path}.${String(prop)} during on_load(). ` +
-                        `this.args is read-only in on_load().`);
-                },
-                deleteProperty(target, prop) {
-                    console.error(`[JQHTML] ERROR: Component "${component_name}" attempted to delete ${path}.${String(prop)} during on_load().\n\n` +
-                        `RESTRICTION: this.args is READ-ONLY during on_load().`);
-                    throw new Error(`[JQHTML] Cannot delete ${path}.${String(prop)} during on_load(). ` +
-                        `this.args is read-only in on_load().`);
-                }
-            });
-        };
-        // Create a detached context object that on_load will operate on
-        const detached_context = {
-            args: create_readonly_proxy(this.args), // Read-only proxy wrapping real args
-            data: data_clone // Cloned data - modifications stay isolated
-        };
-        // Create restricted proxy that operates on the detached context
-        const component_name = this.component_name();
-        const restricted_this = new Proxy(detached_context, {
-            get(target, prop) {
-                // Only allow access to args and data
-                if (prop === 'args') {
-                    return target.args;
-                }
-                if (prop === 'data') {
-                    return target.data;
-                }
-                // Block everything else
-                console.error(`[JQHTML] ERROR: Component "${component_name}" attempted to access this.${String(prop)} during on_load().\n\n` +
-                    `RESTRICTION: on_load() may ONLY access:\n` +
-                    `  - this.args (read-only)\n` +
-                    `  - this.data (read/write)\n\n` +
-                    `WHY: on_load() is for data fetching only. All other component functionality should happen in other lifecycle methods.\n\n` +
-                    `FIX:\n` +
-                    `  - DOM manipulation → use on_render() or on_ready()\n` +
-                    `  - Component methods → call them before/after on_load(), not inside it\n` +
-                    `  - Other properties → restructure code to only use this.args and this.data in on_load()`);
-                throw new Error(`[JQHTML] Cannot access this.${String(prop)} during on_load(). ` +
-                    `on_load() may only access this.args and this.data.`);
-            },
-            set(target, prop, value) {
-                // Only allow setting data
-                if (prop === 'data') {
-                    target.data = value;
-                    return true;
-                }
-                // Block setting args
-                if (prop === 'args') {
-                    console.error(`[JQHTML] ERROR: Component "${component_name}" attempted to modify this.args during on_load().\n\n` +
-                        `RESTRICTION: on_load() may ONLY modify:\n` +
-                        `  - this.data (read/write)\n\n` +
-                        `WHY: this.args is component state that on_load() depends on. Modifying it inside on_load() creates circular dependencies.\n\n` +
-                        `FIX: Modify this.args BEFORE calling on_load() (in on_create() or other lifecycle methods), not inside on_load():\n` +
-                        `  ❌ Inside on_load(): this.args.filter = 'new_value';\n` +
-                        `  ✅ In on_create(): this.args.filter = this.args.initial_filter || 'default';`);
-                    throw new Error(`[JQHTML] Cannot modify this.args during on_load(). ` +
-                        `Modify this.args in other lifecycle methods, not inside on_load().`);
-                }
-                // Block setting any other properties
-                console.error(`[JQHTML] ERROR: Component "${component_name}" attempted to modify this.${String(prop)} during on_load().\n\n` +
-                    `RESTRICTION: on_load() may ONLY modify:\n` +
-                    `  - this.data (read/write)\n\n` +
-                    `WHY: on_load() is for data fetching only. Setting properties on the component instance should happen in other lifecycle methods.\n\n` +
-                    `FIX: Store your data in this.data instead:\n` +
-                    `  ❌ this.${String(prop)} = value;\n` +
-                    `  ✅ this.data.${String(prop)} = value;`);
-                throw new Error(`[JQHTML] Cannot modify this.${String(prop)} during on_load(). ` +
-                    `Only this.data can be modified in on_load().`);
-            }
-        });
-        // Create promise for this on_load() call
-        const on_load_promise = (async () => {
-            try {
-                await this._call_lifecycle('on_load', restricted_this);
-            }
-            catch (error) {
-                if (use_load_coordinator) {
-                    // Handle error and notify coordinator
-                    Load_Coordinator.handle_leader_error(this, error);
-                }
-                throw error;
-            }
-        })();
-        // If using Load_Coordinator, register as leader
-        // Note: We store the completion function but DON'T call it here
-        // It will be called by _load() after _apply_load_result() updates this.data
-        let complete_coordination = null;
-        if (use_load_coordinator) {
-            complete_coordination = Load_Coordinator.register_leader(this, on_load_promise);
-        }
-        await on_load_promise;
-        // Note: We don't validate args changes here because external code (like parent
-        // components calling reload()) is allowed to modify component.args during on_load().
-        // The read-only proxy only prevents code INSIDE on_load() from modifying args.
-        // Return the data from the detached context AND the completion function
-        return {
-            data: detached_context.data,
-            complete_coordination
-        };
+        return execute_on_load_detached(this, use_load_coordinator);
     }
     /**
      * Apply the result of on_load() to this.data via the sequential queue.
@@ -3153,34 +3920,30 @@ class Jqhtml_Component {
             }
             // Freeze this.data
             this.__data_frozen = true;
+            // SSR data capture: record this component's data for preloading
+            if (is_capture_enabled() && this._has_on_load()) {
+                capture_component_data(this.component_name(), this.args, this.data, this._cache_key);
+            }
             // Calculate if data changed
             const data_after_load = JSON.stringify(this.data);
             const data_changed = data_before_load !== null && data_after_load !== data_before_load;
             // Track if component is "dynamic" (this.data changed during on_load)
             // Used by HTML cache mode for synchronization - static parents don't block children
             this._is_dynamic = data_changed && data_after_load !== '{}';
-            // CACHE WRITE - If data changed during on_load(), write to cache based on mode
-            if (this._is_dynamic && this._cache_key) {
-                if (cache_mode === 'html') {
-                    // HTML cache mode - flag to cache HTML after children ready in _ready()
-                    this._should_cache_html_after_ready = true;
-                    if (window.jqhtml?.debug?.verbose) {
-                        console.log(`[Cache html] Component ${this._cid} (${this.component_name()}) will cache HTML after ready`, { cache_key: this._cache_key });
-                    }
-                }
-                else {
-                    // Data cache mode (default) - write this.data to cache
-                    Jqhtml_Local_Storage.set(this._cache_key, this.data);
-                    if (window.jqhtml?.debug?.verbose) {
-                        console.log(`[Cache data] Component ${this._cid} (${this.component_name()}) cached data after on_load()`, { cache_key: this._cache_key, data: this.data });
-                    }
-                }
-            }
+            // CACHE WRITE - @see component-cache.ts
+            write_cache_on_loaded(this, this._is_dynamic);
             this._ready_state = 2;
             this._update_debug_attrs();
             this._log_lifecycle('load', 'complete');
             // Emit lifecycle event
             this.trigger('load');
+            // Call on_loaded() - runs on the REAL component (not detached proxy)
+            // this.data is frozen (read-only), but this.$, this.state, this.args are accessible
+            // Suppressed by _load_only and _load_render_only flags (preloading mode)
+            if (!this._load_only && !this._load_render_only) {
+                await this._call_lifecycle('on_loaded');
+                this.trigger('loaded');
+            }
         }
         finally {
             // Signal next in queue
@@ -3196,32 +3959,11 @@ class Jqhtml_Component {
         if (this._stopped || this._ready_state >= 4)
             return;
         this._log_lifecycle('ready', 'start');
-        // HTML CACHE MODE - New synchronization architecture:
-        // 1. Wait for all children to complete on_render (post-on_load)
-        // 2. Take HTML snapshot BEFORE waiting for children ready
-        // 3. This ensures we capture the DOM after on_render but before on_ready manipulations
+        // HTML CACHE MODE - Wait for children on_render, then snapshot
+        // @see component-cache.ts for write_html_cache_snapshot implementation
         if (this._should_cache_html_after_ready && this._cache_key) {
-            // Wait for all children to complete their on_render
             await this._wait_for_children_on_render();
-            // Only cache if this component is dynamic (data changed during on_load)
-            // Static parents don't cache - they just let children proceed
-            if (this._is_dynamic) {
-                this._should_cache_html_after_ready = false;
-                // Cache the rendered HTML
-                const html = this.$.html();
-                const html_cache_key = `${this._cache_key}::html`;
-                Jqhtml_Local_Storage.set(html_cache_key, html);
-                if (window.jqhtml?.debug?.verbose) {
-                    console.log(`[Cache html] Component ${this._cid} (${this.component_name()}) cached HTML after children on_render complete`, { cache_key: html_cache_key, html_length: html.length });
-                }
-            }
-            else {
-                // Static component - just clear the flag, don't cache
-                this._should_cache_html_after_ready = false;
-                if (window.jqhtml?.debug?.verbose) {
-                    console.log(`[Cache html] Component ${this._cid} (${this.component_name()}) is static (no data change) - skipping HTML cache`);
-                }
-            }
+            write_html_cache_snapshot(this);
         }
         // Wait for all children to reach ready state (bottom-up execution)
         await this._wait_for_children_ready();
@@ -3382,6 +4124,17 @@ class Jqhtml_Component {
      *                        If false, only re-render if data actually changed.
      */
     async reload(always_render) {
+        // Load-gate short-circuit: if a gate is currently holding the first on_load,
+        // reload()/refresh() resumes the paused boot lifecycle instead of running its
+        // normal debounced re-fetch. The boot lifecycle then proceeds to run on_load
+        // (the fresh fetch) exactly as reload() would want. Any later gate settlement
+        // becomes a no-op. Return a promise that resolves when the component is ready.
+        if (this.__gate_resume) {
+            const resume = this.__gate_resume;
+            this.__gate_resume = null;
+            resume();
+            return this.ready();
+        }
         // Default to true if undefined
         const force_refresh = always_render !== undefined ? always_render : true;
         // State machine: reload(true) takes precedence over reload(false)
@@ -3394,11 +4147,9 @@ class Jqhtml_Component {
                 this.next_reload_force_refresh = false;
             }
         }
-        // Lazy-create debounced _reload function on first use
-        if (!this._reload_debounced) {
-            this._reload_debounced = this._create_debounced_function(this._reload.bind(this), 0);
-        }
-        return this._reload_debounced();
+        // Enqueue through component queue (replaces _create_debounced_function)
+        // Same-type pending operations collapse (multiple reload() calls share one execution)
+        return this._queue.enqueue('reload', () => this._reload());
     }
     /**
      * Refresh component - re-fetch data and re-render only if data changed (debounced)
@@ -3480,57 +4231,8 @@ class Jqhtml_Component {
             }
         }
         if (args_changed) {
-            // Check if component implements cache_id() for custom cache key
-            let cache_key = null;
-            if (typeof this.cache_id === 'function') {
-                try {
-                    const custom_cache_id = this.cache_id();
-                    cache_key = `${this.component_name()}::${String(custom_cache_id)}`;
-                }
-                catch (error) {
-                    // cache_id() threw error - disable caching
-                    cache_key = null;
-                }
-            }
-            else {
-                // Use standard args-based cache key generation
-                const result = Load_Coordinator.generate_invocation_key(this.component_name(), this.args);
-                cache_key = result.key;
-            }
-            // Check for cached data/html when args changed
-            if (cache_key !== null) {
-                const cache_mode = Jqhtml_Local_Storage.get_cache_mode();
-                this._cache_key = cache_key;
-                if (cache_mode === 'html') {
-                    // HTML cache mode - check for cached HTML
-                    const html_cache_key = `${cache_key}::html`;
-                    const cached_html = Jqhtml_Local_Storage.get(html_cache_key);
-                    if (cached_html !== null && typeof cached_html === 'string') {
-                        if (window.jqhtml?.debug?.verbose) {
-                            console.log(`[Cache html] reload() - Component ${this._cid} (${this.component_name()}) found cached HTML (args changed)`, { cache_key: html_cache_key, html_length: cached_html.length });
-                        }
-                        // Store cached HTML for injection in _render()
-                        this._cached_html = cached_html;
-                        this.render();
-                        rendered_from_cache = true;
-                    }
-                }
-                else {
-                    // Data cache mode (default) - check for cached data
-                    const cached_data = Jqhtml_Local_Storage.get(cache_key);
-                    if (cached_data !== null && typeof cached_data === 'object' && JSON.stringify(cached_data) !== '{}') {
-                        if (window.jqhtml?.debug?.verbose) {
-                            console.log(`[Cache data] reload() - Component ${this._cid} (${this.component_name()}) hydrated from cache (args changed)`, { cache_key, data: cached_data });
-                        }
-                        // Hydrate this.data with cached data
-                        this.__data_frozen = false;
-                        this.data = cached_data;
-                        this.__data_frozen = true;
-                        this.render();
-                        rendered_from_cache = true;
-                    }
-                }
-            }
+            // @see component-cache.ts for full implementation
+            rendered_from_cache = check_cache_on_reload(this);
         }
         // Capture data state before on_load for comparison
         data_before_load = JSON.stringify(this.data);
@@ -3604,11 +4306,18 @@ class Jqhtml_Component {
         if (this._stopped)
             return;
         this._stopped = true;
+        // If a load gate is holding the first on_load, release the wait so the boot
+        // lifecycle unwinds cleanly (it will see _stopped and abandon the load).
+        if (this.__gate_resume) {
+            const resume = this.__gate_resume;
+            this.__gate_resume = null;
+            resume();
+        }
         // Early bailout: skip expensive cleanup if no handlers registered
         // Only matters for aborting boot() lifecycle - minimal cleanup sufficient
         const has_custom_stop = this.on_stop !== Jqhtml_Component.prototype.on_stop;
-        const has_destroy_callbacks = this._on_registered('destroy');
-        if (!has_custom_stop && !has_destroy_callbacks) {
+        const has_stop_callbacks = this._on_registered('stop');
+        if (!has_custom_stop && !has_stop_callbacks) {
             // Fast path: no cleanup logic defined, just mark as stopped
             this._lifecycle_manager.unregister_component(this);
             this._ready_state = 99;
@@ -3656,6 +4365,7 @@ class Jqhtml_Component {
     on_render() { }
     on_create() { }
     on_load() { } // Override to fetch data asynchronously
+    on_loaded() { } // Override to process loaded data (e.g., clone this.data to this.state)
     async on_ready() { }
     on_stop() { }
     /**
@@ -3701,85 +4411,39 @@ class Jqhtml_Component {
         return this.constructor.name;
     }
     /**
-     * Register event callback
-     * Supports lifecycle events ('render', 'create', 'load', 'ready', 'stop') and custom events
-     * Lifecycle event callbacks fire after the lifecycle method completes
-     * If a lifecycle event has already occurred, the callback fires immediately AND registers for future occurrences
-     * Custom events only fire when explicitly triggered via .trigger()
-     *
-     * Callback signature: (component, data?) => void
-     *   - component: The component instance that triggered the event
-     *   - data: Optional data passed as second parameter to trigger()
+     * Register event callback - delegates to component-events.ts
+     * @see component-events.ts for full documentation
      */
     on(event_name, callback) {
-        // Initialize callback array for this event if needed
-        if (!this._lifecycle_callbacks.has(event_name)) {
-            this._lifecycle_callbacks.set(event_name, []);
-        }
-        // Add callback to queue
-        this._lifecycle_callbacks.get(event_name).push(callback);
-        // If this lifecycle event has already occurred, fire the callback immediately
-        // with the stored data from when trigger() was called
-        if (this._lifecycle_states.has(event_name)) {
-            try {
-                const stored_data = this._lifecycle_states.get(event_name);
-                callback(this, stored_data);
-            }
-            catch (error) {
-                console.error(`[JQHTML] Error in ${event_name} callback:`, error);
-            }
-        }
-        return this;
+        return event_on(this, event_name, callback);
     }
     /**
-     * Trigger a lifecycle event - fires all registered callbacks
-     * Marks event as occurred so future .on() calls fire immediately
-     *
-     * @param event_name - Name of the event to trigger
-     * @param data - Optional data to pass to callbacks as second parameter
+     * Register a callback that fires exactly once - delegates to component-events.ts
+     * If the event already occurred, fires immediately and does not register.
+     * @see component-events.ts for full documentation
+     */
+    once(event_name, callback) {
+        return event_once(this, event_name, callback);
+    }
+    /**
+     * Trigger a lifecycle event - delegates to component-events.ts
+     * @see component-events.ts for full documentation
      */
     trigger(event_name, data) {
-        // Mark this event as occurred and store the data for late subscribers
-        this._lifecycle_states.set(event_name, data);
-        // Fire all registered callbacks for this event
-        const callbacks = this._lifecycle_callbacks.get(event_name);
-        if (callbacks) {
-            for (const callback of callbacks) {
-                try {
-                    callback.bind(this)(this, data);
-                }
-                catch (error) {
-                    console.error(`[JQHTML] Error in ${event_name} callback:`, error);
-                }
-            }
-        }
+        event_trigger(this, event_name, data);
     }
     /**
      * Check if any callbacks are registered for a given event
-     * Used to determine if cleanup logic needs to run
      */
     _on_registered(event_name) {
-        const callbacks = this._lifecycle_callbacks.get(event_name);
-        return !!(callbacks && callbacks.length > 0);
+        return event_on_registered(this, event_name);
     }
     /**
-     * Invalidate a lifecycle event - removes the "already occurred" marker
-     *
-     * This is the opposite of trigger(). After invalidate() is called:
-     * - New .on() handlers will NOT fire immediately
-     * - The ready() promise will NOT resolve immediately
-     * - Handlers wait for the next trigger() call
-     *
-     * Existing registered callbacks are NOT removed - they'll fire on next trigger().
-     *
-     * Use case: Call invalidate('ready') at the start of reload() or render()
-     * so that any new .on('ready') handlers wait for the reload/render to complete
-     * rather than firing immediately based on the previous lifecycle's state.
-     *
-     * @param event_name - Name of the event to invalidate
+     * Invalidate a lifecycle event - delegates to component-events.ts
+     * @see component-events.ts for full documentation
      */
     invalidate(event_name) {
-        this._lifecycle_states.delete(event_name);
+        event_invalidate(this, event_name);
     }
     /**
      * Find element by scoped ID
@@ -4151,84 +4815,6 @@ class Jqhtml_Component {
             window.JQHTML_DEBUG.log(this.component_name(), 'debug', `${action}: ${args.map(a => JSON.stringify(a)).join(', ')}`);
         }
     }
-    /**
-     * Creates a debounced function with exclusivity and promise fan-in
-     *
-     * When invoked, immediately runs the callback exclusively.
-     * For subsequent invocations, applies a delay before running the callback exclusively again.
-     * The delay starts after the current asynchronous operation resolves.
-     *
-     * If delay is 0, the function only prevents enqueueing multiple executions,
-     * but will still run them immediately in an exclusive sequential manner.
-     *
-     * The most recent invocation's parameters are used when the function executes.
-     * Returns a promise that resolves when the next exclusive execution completes.
-     *
-     * @private
-     */
-    _create_debounced_function(callback, delay) {
-        let running = false;
-        let queued = false;
-        let last_end_time = 0; // timestamp of last completed run
-        let timer = null;
-        let next_args = [];
-        let resolve_queue = [];
-        let reject_queue = [];
-        const run_function = async () => {
-            const these_resolves = resolve_queue;
-            const these_rejects = reject_queue;
-            const args = next_args;
-            resolve_queue = [];
-            reject_queue = [];
-            next_args = [];
-            queued = false;
-            running = true;
-            try {
-                const result = await callback(...args);
-                for (const resolve of these_resolves)
-                    resolve(result);
-            }
-            catch (err) {
-                for (const reject of these_rejects)
-                    reject(err);
-            }
-            finally {
-                running = false;
-                last_end_time = Date.now();
-                if (queued) {
-                    clearTimeout(timer);
-                    timer = setTimeout(run_function, Math.max(delay, 0));
-                }
-                else {
-                    timer = null;
-                }
-            }
-        };
-        return function (...args) {
-            next_args = args;
-            return new Promise((resolve, reject) => {
-                resolve_queue.push(resolve);
-                reject_queue.push(reject);
-                // Nothing running and nothing scheduled
-                if (!running && !timer) {
-                    const first_call = last_end_time === 0;
-                    const since = first_call ? Infinity : Date.now() - last_end_time;
-                    if (since >= delay) {
-                        run_function();
-                    }
-                    else {
-                        const wait = Math.max(delay - since, 0);
-                        clearTimeout(timer);
-                        timer = setTimeout(run_function, wait);
-                    }
-                    return;
-                }
-                // If already running or timer exists, just mark queued
-                // The finally{} of run_function handles scheduling after full delay
-                queued = true;
-            });
-        };
-    }
 }
 // Static properties
 Jqhtml_Component.__jqhtml_component = true; // Marker for unified register() detection
@@ -4884,6 +5470,61 @@ function init_jquery_plugin(jQuery) {
     const originalEmpty = jQuery.fn.empty;
     const originalHtml = jQuery.fn.html;
     const originalText = jQuery.fn.text;
+    // ---------------------------------------------------------------------------
+    // Guard against hand-creating elements with data-sid via jQuery.
+    //
+    // $sid / data-sid is provisioned ONLY by the jqhtml template renderer, which
+    // ALWAYS emits data-sid paired with a scoped id ("<sid>:<component_cid>").
+    // That scoped id is what binds the element to its component; data-sid on its
+    // own does nothing. So an element whose data-sid is NOT paired with such an id
+    // was hand-written (e.g. .html('<div data-sid="x">')) and the framework never
+    // provisioned it - this.$sid('x') can never find it. We detect exactly that.
+    //
+    // The framework's own rendering injects data-sid via native innerHTML, never
+    // through these jQuery methods, and the one internal jQuery .html() copy
+    // (the .component() tag-mismatch path) carries the provisioned id - so neither
+    // trips this guard.
+    // ---------------------------------------------------------------------------
+    // Return the offending data-sid value if `html` contains a hand-written
+    // data-sid element (data-sid without the scoped "<sid>:<cid>" id), else null.
+    const find_manual_sid = (html) => {
+        if (typeof html !== 'string' || html.indexOf('data-sid') === -1)
+            return null;
+        if (typeof document === 'undefined')
+            return null; // no DOM to parse (SSR)
+        const tpl = document.createElement('template');
+        tpl.innerHTML = html; // native parse - does not route back through jQuery
+        const candidates = tpl.content.querySelectorAll('[data-sid]');
+        for (let i = 0; i < candidates.length; i++) {
+            const el = candidates[i];
+            const sid = el.getAttribute('data-sid') || '';
+            const id = el.getAttribute('id') || '';
+            // Provisioned elements have id="<sid>:<cid>". Anything else is hand-written.
+            if (id.indexOf(sid + ':') !== 0)
+                return sid;
+        }
+        return null;
+    };
+    const assert_no_manual_sid = (value, where) => {
+        const sid = find_manual_sid(value);
+        if (sid === null)
+            return;
+        throw new Error(`[JQHTML] Manually creating an element with data-sid="${sid}" via jQuery (${where}) is not allowed.\n\n` +
+            `data-sid is NOT a normal attribute you can hand-write. It is provisioned by the jqhtml template\n` +
+            `renderer, which scopes the element to its component by pairing data-sid with a unique id\n` +
+            `("${sid}:<component_cid>"). An element you create yourself has no such scoped id, so\n` +
+            `this.$sid('${sid}') / this.sid('${sid}') can never find it - scoping to a component is the entire\n` +
+            `point of data-sid.\n\n` +
+            `CORRECT USAGE:\n` +
+            `  • Put the element in your component template with $sid:\n` +
+            `      <div $sid="${sid}"></div>\n` +
+            `    then access it from the component: this.$sid('${sid}')\n` +
+            `  • Need it created dynamically? Use a child component or a $redrawable element in the template\n` +
+            `    and render() it, instead of injecting raw HTML.\n\n` +
+            `If you only need to select or mark a plain element, use a normal attribute or class instead:\n` +
+            `  • <div data-role="${sid}"> → .find('[data-role="${sid}"]')\n` +
+            `  • <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
@@ -4910,6 +5551,8 @@ function init_jquery_plugin(jQuery) {
         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();
@@ -5012,6 +5655,33 @@ function init_jquery_plugin(jQuery) {
         // Pass through to original .find()
         return originalFind.call(this, selector);
     };
+    // Guard the content-insertion methods that build elements from HTML strings,
+    // plus $() construction. Wrapped once so repeated init() calls don't re-wrap.
+    if (!jQuery.fn.__jqhtml_sid_guarded) {
+        jQuery.fn.__jqhtml_sid_guarded = true;
+        // .append('<div data-sid>'), .prepend, .before, .after, .replaceWith
+        for (const name of ['append', 'prepend', 'before', 'after', 'replaceWith']) {
+            const original = jQuery.fn[name];
+            if (typeof original !== 'function')
+                continue;
+            jQuery.fn[name] = function (...args) {
+                for (const arg of args)
+                    assert_no_manual_sid(arg, '.' + name + '()');
+                return original.apply(this, args);
+            };
+        }
+        // $('<div data-sid="x">') - catch the element at construction time. A
+        // selector like $('[data-sid="x"]') parses to no data-sid element, so it is
+        // not flagged here (selector misuse is handled by .find()/.on()).
+        const originalInit = jQuery.fn.init;
+        const PatchedInit = function (selector, context, root) {
+            if (typeof selector === 'string')
+                assert_no_manual_sid(selector, '$()');
+            return new originalInit(selector, context, root);
+        };
+        PatchedInit.prototype = jQuery.fn;
+        jQuery.fn.init = PatchedInit;
+    }
 }
 // Try to auto-initialize if global jQuery exists
 if (typeof window !== 'undefined' && window.jQuery) {
@@ -5039,7 +5709,7 @@ function init(jQuery) {
     }
 }
 // Version - will be replaced during build with actual version from package.json
-const version = '2.3.35';
+const version = '2.3.50';
 // Default export with all functionality
 const jqhtml = {
     // Core
@@ -5136,7 +5806,13 @@ const jqhtml = {
     // Required for ES6 class instances to be stored and restored from localStorage
     register_cache_class,
     // Boot - hydrate server-rendered component placeholders
-    boot
+    boot,
+    // SSR Preload - capture data during SSR, replay on client to skip on_load()
+    start_data_capture,
+    get_captured_data,
+    stop_data_capture,
+    set_preload_data,
+    clear_preload_data
 };
 // Auto-register on window for browser environments
 // This is REQUIRED for compiled templates which use window.jqhtml.register_template()
@@ -5166,5 +5842,5 @@ if (typeof window !== 'undefined' && !window.jqhtml) {
     }
 }
 
-export { Jqhtml_Component, LifecycleManager as Jqhtml_LifecycleManager, Jqhtml_Local_Storage, LifecycleManager, Load_Coordinator, applyDebugDelay, boot, create_component, jqhtml as default, devWarn, escape_html, escape_html_nl2br, extract_slots, get_component_class, get_component_names, get_registered_templates, get_template, get_template_by_class, handleComponentError, has_component, init, init_jquery_plugin, isSequentialProcessing, list_components, logDataChange, logDispatch, logInstruction, logLifecycle, process_instructions, register, register_cache_class, register_component, register_template, render_template, version };
+export { Jqhtml_Component, LifecycleManager as Jqhtml_LifecycleManager, Jqhtml_Local_Storage, LifecycleManager, Load_Coordinator, applyDebugDelay, boot, clear_preload_data, create_component, jqhtml as default, devWarn, escape_html, escape_html_nl2br, extract_slots, get_captured_data, get_component_class, get_component_names, get_registered_templates, get_template, get_template_by_class, handleComponentError, has_component, init, init_jquery_plugin, isSequentialProcessing, list_components, logDataChange, logDispatch, logInstruction, logLifecycle, process_instructions, register, register_cache_class, register_component, register_template, render_template, set_preload_data, start_data_capture, stop_data_capture, version };
 //# sourceMappingURL=index.js.map