@jqhtml/core 2.3.61 → 2.3.67

package/dist/index.js

@@ -199,6 +199,38 @@ class LifecycleManager {
     }
 }
 
+/**
+ * The one rule for "is this name a component?"
+ *
+ * An optional SINGLE leading underscore, then a capital letter, then letters,
+ * digits and underscores. The underscore prefix is a namespace reserved for
+ * framework-provided components (`_Root_Layout`) so they cannot collide with
+ * application components. Two or more leading underscores are not a component
+ * name; a lower-case first letter after the optional underscore is an HTML tag.
+ */
+const COMPONENT_NAME_PATTERN = /^_?[A-Z][A-Za-z0-9_]*$/;
+const COMPONENT_NAME_RULE = 'must start with a capital letter, optionally preceded by a single underscore';
+function is_component_name(name) {
+    return COMPONENT_NAME_PATTERN.test(name);
+}
+/**
+ * The render-time check behind <{expression}>: the expression must evaluate
+ * to a component name string that a literal tag would accept - no more, no
+ * less. A valid name that names nothing renders the ordinary placeholder
+ * component, exactly as an undefined literal tag does.
+ */
+function dynamic_component_name(value) {
+    if (typeof value !== 'string' || value === '') {
+        const shown = value === '' ? 'an empty string' : typeof value === 'string' ? `'${value}'` : `${value === null ? 'null' : typeof value}`;
+        throw new Error(`[JQHTML] Dynamic component tag <{...}> evaluated to ${shown}; expected a non-empty component name string`);
+    }
+    if (!is_component_name(value)) {
+        throw new Error(`[JQHTML] Dynamic component tag <{...}> evaluated to '${value}', which is not a valid component name: ` +
+            `a component name ${COMPONENT_NAME_RULE}, then letters, digits and underscores`);
+    }
+    return value;
+}
+
 /**
  * JQHTML v2 Component Registry
  *
@@ -245,9 +277,9 @@ function register_component(nameOrClass, component_class, template) {
         if (!component_class) {
             throw new Error('Component class is required when registering by name');
         }
-        // Validate component name starts with capital letter
-        if (!/^[A-Z]/.test(name)) {
-            throw new Error(`Component name '${name}' must start with a capital letter. Convention is First_Letter_With_Underscores.`);
+        // Validate component name against the shared rule
+        if (!is_component_name(name)) {
+            throw new Error(`Component name '${name}' ${COMPONENT_NAME_RULE}. Convention is First_Letter_With_Underscores.`);
         }
         component_classes.set(name, component_class);
         // If template provided, register it
@@ -316,9 +348,9 @@ function register_template(template_def) {
     if (!name) {
         throw new Error('Template must have a name property');
     }
-    // Validate template name starts with capital letter
-    if (!/^[A-Z]/.test(name)) {
-        throw new Error(`Template name '${name}' must start with a capital letter. Convention is First_Letter_With_Underscores.`);
+    // Validate template name against the shared rule
+    if (!is_component_name(name)) {
+        throw new Error(`Template name '${name}' ${COMPONENT_NAME_RULE}. Convention is First_Letter_With_Underscores.`);
     }
     // Check for duplicate registration
     if (component_templates.has(name)) {
@@ -1096,13 +1128,10 @@ async function initialize_component(element, compData) {
     if (slots) {
         options._slots = slots;
     }
-    // Always pass _component_name when component name differs from class name
-    // This happens when:
-    // 1. No class registered for component (uses Jqhtml_Component)
-    // 2. Class inherited from parent via extends chain (uses parent class but child template)
-    if (ComponentClass.name !== name) {
-        options._component_name = name;
-    }
+    // Always pass the invocation name: it is what component_name() reports, it
+    // selects the template when the class is inherited via an extends chain or
+    // is the bare Jqhtml_Component, and it is the class the element carries.
+    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) {
@@ -1847,7 +1876,7 @@ Load_Coordinator._registry = new Map();
 const class_registry = Object.create(null);
 // Markers for serialized class instances (unique to avoid collisions with user data)
 // Replaced at build time by rollup (see rollup.config.js).
-const CORE_VERSION = '2.3.61';
+const CORE_VERSION = '2.3.67';
 const CLASS_MARKER = '__jqhtml_class__';
 const PROPS_MARKER = '__jqhtml_props__';
 /**
@@ -3095,511 +3124,910 @@ function write_cache_on_loaded(component, data_changed) {
 }
 
 /**
- * JQHTML Component Lifecycle Queue
+ * JQHTML v2 Template Renderer
  *
- * Serializes lifecycle operations (render, reload, refresh) per component.
- * Replaces _create_debounced_function with a proper queue that:
+ * Connects compiled templates to components
+ * Processes instruction arrays and handles bindings
+ */
+/**
+ * Process slot-only template inheritance
  *
- * - 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)
+ * When a component's template returns {_slots: {...}}, walk the prototype
+ * chain to find a parent template and invoke it with the child's slots as content.
  *
- * Boot bypasses this queue entirely - it runs the lifecycle directly.
+ * @param component The component instance
+ * @param childSlots The slots object from the child template
+ * @returns [instructions, context] tuple or null if no parent found
  */
-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]
-                    };
-                });
-            }
+async function process_slot_inheritance(component, childSlots) {
+    // Walk the prototype chain to find parent class with template
+    let currentClass = Object.getPrototypeOf(component.constructor);
+    console.log(`[JQHTML] Walking prototype chain for ${component.constructor.name}`);
+    while (currentClass && currentClass !== Jqhtml_Component && currentClass.name !== 'Object') {
+        const className = currentClass.name;
+        console.log(`[JQHTML]   Checking parent class: ${className}`);
+        // Skip internal framework classes
+        if (className === '_Jqhtml_Component' || className === '_Base_Jqhtml_Component') {
+            currentClass = Object.getPrototypeOf(currentClass);
+            continue;
         }
-        // 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);
-                    }
+        // Try to find template for this parent class
+        try {
+            const parentTemplate = get_template(className);
+            console.log(`[JQHTML]   Template found for ${className}:`, parentTemplate ? parentTemplate.name : 'null');
+            // Check if we got the default template (means no real template found)
+            if (parentTemplate && parentTemplate.name !== 'Jqhtml_Component') {
+                console.log(`[JQHTML]   Invoking parent template ${className}`);
+                // Found a real parent template - invoke it with child's slots as content
+                const [parentInstructions, parentContext] = parentTemplate.render.call(component, component.data, component.args, childSlots // Pass child slots as content parameter
+                );
+                // Check if parent also returns slots (recursive inheritance)
+                if (parentInstructions && typeof parentInstructions === 'object' && parentInstructions._slots) {
+                    // Parent also has slot-only template - recurse
+                    console.log(`[JQHTML]   Parent also slot-only, recursing`);
+                    return await process_slot_inheritance(component, parentInstructions._slots);
                 }
+                // Parent returned HTML - we're done
+                console.log(`[JQHTML]   Parent returned instructions, inheritance complete`);
+                return [parentInstructions, parentContext];
             }
-        })();
-        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;
+        }
+        catch (error) {
+            console.warn(`[JQHTML] Error looking up parent template for ${className}:`, error);
+        }
+        // Move to next parent
+        currentClass = Object.getPrototypeOf(currentClass);
     }
-}
-
-/**
- * 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();
+    // No parent template found
+    console.warn(`[JQHTML] No parent template found after walking chain`);
+    return null;
 }
 /**
- * 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)
+ * Render a template for a component
+ * Templates are functions that return [instructions, context] tuples
  */
-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);
+async function render_template(component, template_fn) {
+    // Get template from registry if not provided
+    let render_fn = template_fn;
+    if (!render_fn) {
+        const template_def = get_template_by_class(component.constructor);
+        render_fn = template_def.render;
     }
-    // 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,
-        });
+    if (!render_fn) {
+        // No template, component should handle its own rendering
+        return;
     }
-    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);
+    // Clear existing content
+    component.$.empty();
+    // Execute template function
+    // Templates receive: (data, args, content)
+    // Provide a default empty content function if none provided
+    const defaultContent = () => '';
+    let [instructions, context] = render_fn.call(component, component.data, component.args, defaultContent // Default content function that returns empty string
+    );
+    // Check for slot-only template inheritance
+    // If instructions is {_slots: {...}}, this is a slot-only template
+    // We need to find the parent template and invoke it with these slots
+    if (instructions && typeof instructions === 'object' && instructions._slots) {
+        console.log(`[JQHTML] Slot-only template detected for ${component.constructor.name}, invoking inheritance`);
+        const result = await process_slot_inheritance(component, instructions._slots);
+        if (result) {
+            console.log(`[JQHTML] Parent template found, using parent instructions`);
+            instructions = result[0];
+            context = result[1];
+        }
+        else {
+            console.warn(`[JQHTML] No parent template found for ${component.constructor.name}, rendering empty`);
+            // No parent template found - return empty
+            instructions = [];
         }
     }
+    // Process instructions to generate DOM
+    await process_instructions(instructions, component.$, component);
+    // Process bindings after DOM is created
+    await process_bindings(component);
+    // Attach event handlers
+    await attach_event_handlers(component);
 }
 /**
- * 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.
+ * Process data bindings (attributes created by :prop syntax)
  */
-function is_capture_enabled() {
-    return _capture_enabled;
+async function process_bindings(component) {
+    // Find all elements with data-bind-* attributes
+    component.$.find('[data-bind-prop], [data-bind-value], [data-bind-text], [data-bind-html], [data-bind-class], [data-bind-style]').each((_, element) => {
+        const el = $(element);
+        const attrs = element.attributes;
+        for (let i = 0; i < attrs.length; i++) {
+            const attr = attrs[i];
+            if (attr.name.startsWith('data-bind-')) {
+                const binding_type = attr.name.substring(10); // Remove 'data-bind-'
+                const expression = attr.value;
+                try {
+                    // Evaluate expression in component context
+                    const value = evaluate_expression(expression, component);
+                    // Apply binding based on type
+                    switch (binding_type) {
+                        case 'prop':
+                            // Generic property binding
+                            const prop_name = el.attr('data-bind-prop-name') || 'value';
+                            el.prop(prop_name, value);
+                            break;
+                        case 'value':
+                            el.val(value);
+                            break;
+                        case 'text':
+                            el.text(value);
+                            break;
+                        case 'html':
+                            el.html(value);
+                            break;
+                        case 'class':
+                            if (typeof value === 'object') {
+                                // Object syntax: {active: true, disabled: false}
+                                Object.entries(value).forEach(([className, enabled]) => {
+                                    el.toggleClass(className, !!enabled);
+                                });
+                            }
+                            else {
+                                // String syntax
+                                el.addClass(String(value));
+                            }
+                            break;
+                        case 'style':
+                            if (typeof value === 'object') {
+                                el.css(value);
+                            }
+                            else {
+                                el.attr('style', String(value));
+                            }
+                            break;
+                        default:
+                            // Custom binding - set as attribute
+                            el.attr(binding_type, value);
+                    }
+                }
+                catch (error) {
+                    console.error(`Error evaluating binding "${expression}":`, error);
+                }
+            }
+        }
+    });
 }
 /**
- * Stop data capture and clear all state.
+ * Attach event handlers (attributes created by @event syntax)
  */
-function stop_data_capture() {
-    _capture_enabled = false;
-    _capture_buffer = [];
-    _captured_keys.clear();
+async function attach_event_handlers(component) {
+    // Find all elements with data-on-* attributes
+    component.$.find('[data-on-click], [data-on-change], [data-on-submit], [data-on-keyup], [data-on-keydown], [data-on-focus], [data-on-blur]').each((_, element) => {
+        const el = $(element);
+        const attrs = element.attributes;
+        for (let i = 0; i < attrs.length; i++) {
+            const attr = attrs[i];
+            if (attr.name.startsWith('data-on-')) {
+                const event_name = attr.name.substring(8); // Remove 'data-on-'
+                const handler_expr = attr.value;
+                // Remove the attribute to avoid re-processing
+                el.removeAttr(attr.name);
+                // Attach event handler
+                el.on(event_name, function (event) {
+                    try {
+                        // Create handler function in component context
+                        const handler = evaluate_handler(handler_expr, component);
+                        if (typeof handler === 'function') {
+                            // Call with component as 'this' and pass event
+                            handler.call(component, event);
+                        }
+                        else {
+                            // Expression to execute
+                            evaluate_expression(handler_expr, component, { $event: event });
+                        }
+                    }
+                    catch (error) {
+                        console.error(`Error in ${event_name} handler "${handler_expr}":`, error);
+                    }
+                });
+            }
+        }
+    });
 }
-// --- 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()
+ * Evaluate an expression in component context
  */
-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);
-        }
+function evaluate_expression(expression, component, locals = {}) {
+    // Create evaluation context
+    const context = {
+        // Component properties
+        data: component.data,
+        args: component.args,
+        $: component.$,
+        // Component methods
+        $sid: component.$sid.bind(component),
+        // Locals (like $event)
+        ...locals
+    };
+    // Build function that evaluates in context
+    const keys = Object.keys(context);
+    const values = Object.values(context);
+    try {
+        // Use Function constructor for better performance than eval
+        const fn = new Function(...keys, `return (${expression})`);
+        return fn(...values);
+    }
+    catch (error) {
+        console.error(`Invalid expression: ${expression}`, error);
+        return undefined;
     }
 }
 /**
- * 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
+ * Evaluate a handler expression (might be method name or inline code)
  */
-function consume_preload_data(cache_key) {
-    if (_preload_cache.size === 0)
+function evaluate_handler(expression, component) {
+    // Check if it's a method name on the component
+    if (expression in component && typeof component[expression] === 'function') {
+        return component[expression];
+    }
+    // Otherwise treat as inline code
+    try {
+        return new Function('$event', `
+      const { data, args, $, emit, $sid } = this;
+      ${expression}
+    `).bind(component);
+    }
+    catch (error) {
+        console.error(`Invalid handler: ${expression}`, error);
         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.
+ * Helper to escape HTML for safe output
  */
-function clear_preload_data() {
-    _preload_cache.clear();
+function escape_html(str) {
+    const div = document.createElement('div');
+    div.textContent = str;
+    return div.innerHTML;
 }
 /**
- * Check if any preload data is available (for fast early exit in _load).
+ * Helper to escape HTML and convert newlines to <br /> tags
+ * Used by <%br= %> syntax for displaying user-entered text with line breaks
  */
-function has_preload_data() {
-    return _preload_cache.size > 0;
+function escape_html_nl2br(str) {
+    const div = document.createElement('div');
+    div.textContent = str;
+    // Escape HTML first, then replace newlines with <br />
+    return div.innerHTML.replace(/\n/g, '<br />');
 }
 
 /**
- * JQHTML Viewport Resize Dispatch
+ * Value printers: how <%= %> renders an OBJECT.
  *
- * One framework-owned, debounced window 'resize' listener fans out to every live
- * component in the document by calling on_viewport_resize(viewport_width).
+ * Primitives never come here - the generated template code routes only
+ * non-null, non-array objects to print_object(), so a hundred-row list of
+ * strings costs exactly what it did before. An object reaching an
+ * interpolation is walked through the printer chain in registration order;
+ * the first printer to return anything but undefined handles it. A printer
+ * returns a string (escaped or not according to the construct, exactly as a
+ * string literal at that site) or a component descriptor:
  *
- * Components never bind their own window listener, so there is nothing to unbind
- * in on_stop() - a component that is stopped or removed from the document simply
- * stops being found by the dispatcher.
- */
-/** Trailing-edge debounce applied to the window resize listener. */
-const VIEWPORT_RESIZE_DEBOUNCE_MS = 30;
-let debounce_timer = null;
-let listener_installed = false;
-/**
- * Current viewport width in CSS pixels.
+ *   { component: { name: 'Rich_Text_Display', args: { value }, attrs: { class: 'x' } } }
  *
- * window.innerWidth is used (not $(window).width()) because it matches the width
- * CSS media queries resolve against. It includes the scrollbar gutter.
+ * which jqhtml mounts as if the template had written the tag - live in the
+ * browser, server-rendered under SSR - with no environment awareness on the
+ * printer's side. A descriptor carries no content.
  *
- * Returns 0 outside a browser (SSR).
+ * Attribute position (<div title="<%= v %>">) compiles through a different
+ * path and never consults printers.
  */
-function get_viewport_width() {
-    return typeof window !== 'undefined' ? window.innerWidth : 0;
-}
+const printers = [];
 /**
- * Call on_viewport_resize(width) on every component currently in the document.
- *
- * Walks $('.Component') in document order (parents before children). Elements
- * with no component instance and stopped components are skipped. A component
- * that throws is logged and the walk continues - one bad handler must not stop
- * the rest of the page from resizing.
+ * Register a printer at the end of the chain. Printers run in registration
+ * order; return undefined to decline, a string, or a component descriptor.
  */
-function dispatch_viewport_resize(jQuery) {
-    const viewport_width = get_viewport_width();
-    jQuery('.Component').each(function () {
-        const component = jQuery(this).data('_component');
-        if (!component || component._stopped)
-            return;
-        if (typeof component.on_viewport_resize !== 'function')
-            return;
-        try {
-            component.on_viewport_resize(viewport_width);
-        }
-        catch (error) {
-            console.error(`[JQHTML] Error in on_viewport_resize() for ${component.component_name?.() || 'component'}:`, error);
-        }
-    });
+function add_object_printer(printer) {
+    if (typeof printer !== 'function') {
+        throw new Error('[JQHTML] add_object_printer() expects a function (value) => undefined | string | descriptor');
+    }
+    printers.push(printer);
+}
+/** The registered printers, in order. Read-only view for diagnostics. */
+function get_object_printers() {
+    return printers;
 }
 /**
- * Install the single window resize listener. Idempotent - repeated init() calls
- * and non-browser environments are no-ops.
+ * Render an object at an interpolation site. Called by compiled templates for
+ * every non-null, non-array object reaching <%= %>, <%!= %> or <%br= %>.
+ * Throws when nothing handles the value or a printer returns garbage.
  */
-function init_viewport_resize(jQuery) {
-    if (typeof window === 'undefined')
-        return;
-    if (listener_installed)
-        return;
-    listener_installed = true;
-    jQuery(window).on('resize.jqhtml_viewport', function () {
-        if (debounce_timer !== null)
-            clearTimeout(debounce_timer);
-        debounce_timer = setTimeout(function () {
-            debounce_timer = null;
-            dispatch_viewport_resize(jQuery);
-        }, VIEWPORT_RESIZE_DEBOUNCE_MS);
-    });
+function print_object(value, mode) {
+    if (value === null || typeof value !== 'object') {
+        throw new TypeError(`[JQHTML] print_object() is the object branch of interpolation; got ${typeof value}`);
+    }
+    for (let i = 0; i < printers.length; i++) {
+        const result = printers[i](value);
+        if (result === undefined)
+            continue;
+        if (typeof result === 'string')
+            return print_string(result, mode);
+        if (is_descriptor(result))
+            return descriptor_to_instruction(result, i);
+        throw new Error(`[JQHTML] Object printer #${i + 1} of ${printers.length} returned ${describe(result)}; ` +
+            `a printer must return undefined (decline), a string, or a { component: { name, args, attrs } } descriptor`);
+    }
+    throw new Error(`[JQHTML] Cannot interpolate a ${constructor_name(value)} object: ` +
+        (printers.length
+            ? `none of the ${printers.length} registered object printer(s) handled it. `
+            : `no object printers are registered. `) +
+        `Register one with jqhtml.add_object_printer(fn), or interpolate a primitive.`);
+}
+function print_string(text, mode) {
+    if (mode === 'escape')
+        return escape_html(text);
+    if (mode === 'nl2br')
+        return escape_html_nl2br(text);
+    return text;
+}
+function is_descriptor(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value) &&
+        !!value.component && typeof value.component === 'object' && !Array.isArray(value.component);
+}
+function descriptor_to_instruction(descriptor, index) {
+    const { name, args, attrs } = descriptor.component;
+    const where = `Object printer #${index + 1}`;
+    if (typeof name !== 'string' || !is_component_name(name)) {
+        throw new Error(`[JQHTML] ${where} returned a descriptor whose component name ${describe(name)} is invalid: ` +
+            `a component name ${COMPONENT_NAME_RULE}, then letters, digits and underscores`);
+    }
+    const props = {};
+    if (attrs !== undefined) {
+        if (!is_plain_object(attrs))
+            throw new Error(`[JQHTML] ${where}: descriptor attrs must be a plain object`);
+        for (const [key, value] of Object.entries(attrs)) {
+            if (key.startsWith('$'))
+                throw new Error(`[JQHTML] ${where}: descriptor attrs key '${key}' - component arguments go in args, without the $ sigil`);
+            props[key] = value;
+        }
+    }
+    if (args !== undefined) {
+        if (!is_plain_object(args))
+            throw new Error(`[JQHTML] ${where}: descriptor args must be a plain object`);
+        for (const [key, value] of Object.entries(args)) {
+            if (key.startsWith('$'))
+                throw new Error(`[JQHTML] ${where}: descriptor args key '${key}' - the $ sigil is template syntax, not part of the argument name`);
+            props[`$${key}`] = value;
+        }
+    }
+    return { comp: [name, props] };
+}
+function is_plain_object(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function constructor_name(value) {
+    const ctor = value.constructor;
+    return ctor && ctor.name ? ctor.name : 'Object';
+}
+function describe(value) {
+    if (value === null)
+        return 'null';
+    if (typeof value === 'string')
+        return `'${value}'`;
+    if (typeof value === 'object')
+        return Array.isArray(value) ? 'an array' : `a ${constructor_name(value)} object without a valid component property`;
+    return `${typeof value} ${String(value)}`;
 }
 
 /**
- * JQHTML v2 Component Base Class
+ * JQHTML Component Lifecycle Queue
  *
- * Core component implementation following v2 specification:
- * - 5-stage lifecycle coordinated by LifecycleManager
- * - Direct jQuery manipulation (no virtual DOM)
- * - Scoped IDs using _cid pattern
- * - Event emission and CSS class hierarchy
+ * 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.
  */
-// WeakMap storage for protected lifecycle method implementations (Option 2)
-// See docs/internal/lifecycle-method-protection.md for design details
-const lifecycle_impls = new WeakMap();
-class Jqhtml_Component {
-    constructor(element, args = {}) {
-        this._ready_state = 0; // 0=created, 1=init, 2=loaded, 3=rendered, 4=ready
-        this._instantiator = null; // Component that instantiated this one
-        this._dom_parent = null; // Closest component in DOM tree (for lifecycle)
-        this._dom_children = new Set(); // Components in DOM subtree (for lifecycle)
-        this._use_dom_fallback = false; // If true, use find() fallback instead of _dom_children optimization
-        this._stopped = false;
-        this._booted = false; // Guard to prevent double boot() calls
-        this._data_before_render = null; // Store data state before initial render
-        this._lifecycle_callbacks = new Map();
-        this._lifecycle_states = new Map(); // Track which lifecycle events have occurred and their data
-        this._did_first_render = false; // Track if component has rendered at least once
-        this._render_count = 0; // Incremented each time _render() is called, used to detect stale renders
-        this._args_on_last_render = null; // Args snapshot from last render (for reload() comparison)
-        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
-        this._cache_key = null; // Cache key for caching
-        // 'html' mode caching
-        this._cached_html = null; // Cached HTML to inject on first render
-        this._used_cached_html = false; // Flag if cached HTML was used (forces re-render after on_load)
-        this._should_cache_html_after_ready = false; // Flag to cache HTML after on_ready lifecycle
-        this._is_dynamic = false; // True if this.data changed during on_load() (used for HTML cache sync)
-        // on_render synchronization (HTML cache mode)
-        this._on_render_complete = false; // True after on_render() has been called post-on_load
-        // 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
-        // _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;
-        // Sequential queue for setting this.data after on_load completes
-        // Multiple _load calls can run on_load in parallel, but setting this.data is serialized
-        this._load_queue = Promise.resolve();
-        // Cached flag: true if this component has a custom on_load() override
-        // 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
-        this.__has_custom_on_load = this.on_load !== Jqhtml_Component.prototype.on_load;
-        this._cid = this._generate_cid();
-        this._lifecycle_manager = LifecycleManager.get_instance();
-        // Create or wrap element
-        if (element) {
-            this.$ = $(element);
-        }
-        else {
-            // Use native createElement for better performance
-            const div = document.createElement('div');
-            this.$ = $(div);
-        }
-        // Extract $ attributes from element and merge with args
-        // $ attributes are stored via jQuery .data() (not as data-* attributes in DOM)
-        const dataAttrs = {};
-        // Get all jQuery .data() values from the element
-        if (this.$.length > 0) {
-            // Get all data via jQuery .data() without arguments (returns all data as object)
-            const allData = this.$.data() || {};
-            for (const key in allData) {
-                // Skip internal attributes
-                if (key !== 'cid' && key !== 'tid' && key !== 'componentName' && key !== 'readyState' &&
-                    key !== '_lifecycleState' && !key.startsWith('_')) {
-                    dataAttrs[key] = allData[key];
-                }
-            }
-        }
-        // Get template to check for defineArgs
-        let template_for_args;
-        if (args._component_name) {
-            template_for_args = get_template(args._component_name);
-        }
-        else {
-            template_for_args = get_template_by_class(this.constructor);
-        }
-        // 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 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._force_initial_render === true) {
-            this._force_initial_render = true;
-        }
-        // Attach component to element
-        this.$.data('_component', this);
-        // Apply CSS classes and attributes
-        this._apply_css_classes();
-        this._apply_default_attributes(); // Apply defaultAttributes from template
-        this._set_attributes();
-        // Find DOM parent component (for lifecycle coordination)
-        this._find_dom_parent();
-        // Setup data property with freeze enforcement using Proxy
-        // @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 = {};
-        this._log_lifecycle('construct', 'complete');
+class Component_Queue {
+    constructor() {
+        /** Currently executing operation */
+        this._current = null;
+        /** Next operation waiting to execute after current completes */
+        this._pending = null;
     }
     /**
-     * Protect lifecycle methods from manual invocation
-     * Stores original implementations in WeakMap, replaces with guarded wrappers
-     * @private
+     * 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
      */
-    _protect_lifecycle_methods() {
-        const methods = {
-            on_create: 'Called automatically during creation.',
-            on_render: 'Use render() to trigger a re-render.',
-            on_load: 'Use reload() to refresh data.',
-            on_ready: 'Called automatically when ready.',
-            on_stop: 'Use stop() to stop the component.'
-        };
-        const impls = {};
-        const self = this;
-        for (const [name, help] of Object.entries(methods)) {
-            const original = this[name];
-            // Skip if using base class default (empty method)
-            if (original === Jqhtml_Component.prototype[name])
-                continue;
-            impls[name] = original;
-            // Create wrapper with same function name (for stack traces)
-            this[name] = {
-                [name](...args) {
-                    if (!self.__lifecycle_authorized) {
-                        throw new Error(`[JQHTML] ${name}() cannot be called manually. ${help}\n` +
-                            `Component: ${self.component_name()} (_cid: ${self._cid})`);
-                    }
-                    return lifecycle_impls.get(self)[name].apply(self, args);
-                }
-            }[name];
+    enqueue(type, executor) {
+        // If nothing running, execute immediately
+        if (!this._current) {
+            return this._execute(type, executor);
         }
-        lifecycle_impls.set(this, impls);
+        // 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]
+            };
+        });
     }
     /**
-     * Call a lifecycle method with authorization (async)
-     * Framework calls this to invoke lifecycle methods, bypassing the protection wrapper.
-     * The flag is set momentarily for the wrapper check, then reset BEFORE user code runs.
-     * This ensures any nested lifecycle calls from user code will fail the flag check.
+     * Execute an operation and handle pending queue after completion.
      * @private
      */
-    async _call_lifecycle(name, context) {
-        // Get the original implementation (bypasses wrapper entirely)
-        const impl = lifecycle_impls.get(this)?.[name] || this[name];
-        // Call original directly - no flag needed since we bypass the wrapper
-        return await impl.call(context || this);
-    }
+    _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 Viewport Resize Dispatch
+ *
+ * One framework-owned, debounced window 'resize' listener fans out to every live
+ * component in the document by calling on_viewport_resize(viewport_width).
+ *
+ * Components never bind their own window listener, so there is nothing to unbind
+ * in on_stop() - a component that is stopped or removed from the document simply
+ * stops being found by the dispatcher.
+ */
+/** Trailing-edge debounce applied to the window resize listener. */
+const VIEWPORT_RESIZE_DEBOUNCE_MS = 30;
+let debounce_timer = null;
+let listener_installed = false;
+/**
+ * Current viewport width in CSS pixels.
+ *
+ * window.innerWidth is used (not $(window).width()) because it matches the width
+ * CSS media queries resolve against. It includes the scrollbar gutter.
+ *
+ * Returns 0 outside a browser (SSR).
+ */
+function get_viewport_width() {
+    return typeof window !== 'undefined' ? window.innerWidth : 0;
+}
+/**
+ * Call on_viewport_resize(width) on every component currently in the document.
+ *
+ * Walks $('.Component') in document order (parents before children). Elements
+ * with no component instance and stopped components are skipped. A component
+ * that throws is logged and the walk continues - one bad handler must not stop
+ * the rest of the page from resizing.
+ */
+function dispatch_viewport_resize(jQuery) {
+    const viewport_width = get_viewport_width();
+    jQuery('.Component').each(function () {
+        const component = jQuery(this).data('_component');
+        if (!component || component._stopped)
+            return;
+        if (typeof component.on_viewport_resize !== 'function')
+            return;
+        try {
+            component.on_viewport_resize(viewport_width);
+        }
+        catch (error) {
+            console.error(`[JQHTML] Error in on_viewport_resize() for ${component.component_name?.() || 'component'}:`, error);
+        }
+    });
+}
+/**
+ * Install the single window resize listener. Idempotent - repeated init() calls
+ * and non-browser environments are no-ops.
+ */
+function init_viewport_resize(jQuery) {
+    if (typeof window === 'undefined')
+        return;
+    if (listener_installed)
+        return;
+    listener_installed = true;
+    jQuery(window).on('resize.jqhtml_viewport', function () {
+        if (debounce_timer !== null)
+            clearTimeout(debounce_timer);
+        debounce_timer = setTimeout(function () {
+            debounce_timer = null;
+            dispatch_viewport_resize(jQuery);
+        }, VIEWPORT_RESIZE_DEBOUNCE_MS);
+    });
+}
+
+/**
+ * JQHTML v2 Component Base Class
+ *
+ * Core component implementation following v2 specification:
+ * - 5-stage lifecycle coordinated by LifecycleManager
+ * - Direct jQuery manipulation (no virtual DOM)
+ * - Scoped IDs using _cid pattern
+ * - Event emission and CSS class hierarchy
+ */
+// WeakMap storage for protected lifecycle method implementations (Option 2)
+// See docs/internal/lifecycle-method-protection.md for design details
+const lifecycle_impls = new WeakMap();
+class Jqhtml_Component {
+    constructor(element, args = {}) {
+        this._ready_state = 0; // 0=created, 1=init, 2=loaded, 3=rendered, 4=ready
+        this._instantiator = null; // Component that instantiated this one
+        this._dom_parent = null; // Closest component in DOM tree (for lifecycle)
+        this._dom_children = new Set(); // Components in DOM subtree (for lifecycle)
+        this._use_dom_fallback = false; // If true, use find() fallback instead of _dom_children optimization
+        this._stopped = false;
+        this._booted = false; // Guard to prevent double boot() calls
+        this._data_before_render = null; // Store data state before initial render
+        this._lifecycle_callbacks = new Map();
+        this._lifecycle_states = new Map(); // Track which lifecycle events have occurred and their data
+        this._did_first_render = false; // Track if component has rendered at least once
+        this._render_count = 0; // Incremented each time _render() is called, used to detect stale renders
+        this._args_on_last_render = null; // Args snapshot from last render (for reload() comparison)
+        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
+        this._cache_key = null; // Cache key for caching
+        // 'html' mode caching
+        this._cached_html = null; // Cached HTML to inject on first render
+        this._used_cached_html = false; // Flag if cached HTML was used (forces re-render after on_load)
+        this._should_cache_html_after_ready = false; // Flag to cache HTML after on_ready lifecycle
+        this._is_dynamic = false; // True if this.data changed during on_load() (used for HTML cache sync)
+        // on_render synchronization (HTML cache mode)
+        this._on_render_complete = false; // True after on_render() has been called post-on_load
+        // 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
+        // _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;
+        // Sequential queue for setting this.data after on_load completes
+        // Multiple _load calls can run on_load in parallel, but setting this.data is serialized
+        this._load_queue = Promise.resolve();
+        // Cached flag: true if this component has a custom on_load() override
+        // 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
+        this.__has_custom_on_load = this.on_load !== Jqhtml_Component.prototype.on_load;
+        this._cid = this._generate_cid();
+        this._lifecycle_manager = LifecycleManager.get_instance();
+        // Create or wrap element
+        if (element) {
+            this.$ = $(element);
+        }
+        else {
+            // Use native createElement for better performance
+            const div = document.createElement('div');
+            this.$ = $(div);
+        }
+        // Extract $ attributes from element and merge with args
+        // $ attributes are stored via jQuery .data() (not as data-* attributes in DOM)
+        const dataAttrs = {};
+        // Get all jQuery .data() values from the element
+        if (this.$.length > 0) {
+            // Get all data via jQuery .data() without arguments (returns all data as object)
+            const allData = this.$.data() || {};
+            for (const key in allData) {
+                // Skip internal attributes
+                if (key !== 'cid' && key !== 'tid' && key !== 'componentName' && key !== 'readyState' &&
+                    key !== '_lifecycleState' && !key.startsWith('_')) {
+                    dataAttrs[key] = allData[key];
+                }
+            }
+        }
+        // Get template to check for defineArgs
+        let template_for_args;
+        if (args._component_name) {
+            template_for_args = get_template(args._component_name);
+        }
+        else {
+            template_for_args = get_template_by_class(this.constructor);
+        }
+        // Merge in order: defineArgs (defaults from Define tag) < dataAttrs < args (invocation overrides)
+        const defineArgs = template_for_args?.defineArgs || {};
+        this.args = { ...defineArgs, ...dataAttrs, ...args };
+        // The name this instance was invoked as. Every invocation path passes it
+        // in args._component_name (template tag, $(el).component('Name'), boot
+        // placeholder); a class handed directly to $(el).component(Class) has
+        // only its own name to offer.
+        const ctor = this.constructor;
+        this._component_name = (typeof args._component_name === 'string' && args._component_name)
+            || ctor.component_name
+            || ctor.name;
+        // 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._force_initial_render === true) {
+            this._force_initial_render = true;
+        }
+        // Attach component to element
+        this.$.data('_component', this);
+        // Apply CSS classes and attributes
+        this._apply_css_classes();
+        this._apply_default_attributes(); // Apply defaultAttributes from template
+        this._set_attributes();
+        // Find DOM parent component (for lifecycle coordination)
+        this._find_dom_parent();
+        // Setup data property with freeze enforcement using Proxy
+        // @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 = {};
+        this._log_lifecycle('construct', 'complete');
+    }
+    /**
+     * Protect lifecycle methods from manual invocation
+     * Stores original implementations in WeakMap, replaces with guarded wrappers
+     * @private
+     */
+    _protect_lifecycle_methods() {
+        const methods = {
+            on_create: 'Called automatically during creation.',
+            on_render: 'Use render() to trigger a re-render.',
+            on_load: 'Use reload() to refresh data.',
+            on_ready: 'Called automatically when ready.',
+            on_stop: 'Use stop() to stop the component.'
+        };
+        const impls = {};
+        const self = this;
+        for (const [name, help] of Object.entries(methods)) {
+            const original = this[name];
+            // Skip if using base class default (empty method)
+            if (original === Jqhtml_Component.prototype[name])
+                continue;
+            impls[name] = original;
+            // Create wrapper with same function name (for stack traces)
+            this[name] = {
+                [name](...args) {
+                    if (!self.__lifecycle_authorized) {
+                        throw new Error(`[JQHTML] ${name}() cannot be called manually. ${help}\n` +
+                            `Component: ${self.component_name()} (_cid: ${self._cid})`);
+                    }
+                    return lifecycle_impls.get(self)[name].apply(self, args);
+                }
+            }[name];
+        }
+        lifecycle_impls.set(this, impls);
+    }
+    /**
+     * Call a lifecycle method with authorization (async)
+     * Framework calls this to invoke lifecycle methods, bypassing the protection wrapper.
+     * The flag is set momentarily for the wrapper check, then reset BEFORE user code runs.
+     * This ensures any nested lifecycle calls from user code will fail the flag check.
+     * @private
+     */
+    async _call_lifecycle(name, context) {
+        // Get the original implementation (bypasses wrapper entirely)
+        const impl = lifecycle_impls.get(this)?.[name] || this[name];
+        // Call original directly - no flag needed since we bypass the wrapper
+        return await impl.call(context || this);
+    }
     /**
      * Call a lifecycle method with authorization (sync version for sync methods like on_stop)
      * @private
@@ -3779,7 +4207,11 @@ class Jqhtml_Component {
                     div.textContent = String(str);
                     // Escape HTML first, then replace newlines with <br />
                     return div.innerHTML.replace(/\n/g, '<br />');
-                }
+                },
+                // Objects reaching <%= %> / <%!= %> / <%br= %> - see value-printers.ts
+                print_object,
+                // <{expression}> name validation - see component-name.ts
+                dynamic_component_name
             };
             // Execute template function
             // Commented out debug logging
@@ -4781,771 +5213,919 @@ class Jqhtml_Component {
         if (stopResult && typeof stopResult.then === 'function') {
             console.warn(`[JQHTML] Component "${this.component_name()}" returned a Promise from on_stop(). ` +
                 `on_stop() must be synchronous code. Remove 'async' from the function declaration.`);
-        }
-        // Fire registered stop callbacks
-        this.trigger('stop');
-        // Remove from DOM parent's children
-        if (this._dom_parent) {
-            this._dom_parent._dom_children.delete(this);
-        }
-        this._ready_state = 99;
-        this._update_debug_attrs();
-        this._log_lifecycle('destroy', 'complete');
-    }
-    /**
-     * Stop component lifecycle - stops all descendant components then self
-     * Leaves DOM intact, just stops lifecycle engine and fires cleanup hooks
-     */
-    stop() {
-        // Stop all descendant components (flat iteration, no recursion needed)
-        this.$.find('.Component').each(function () {
-            const child = $(this).data('_component');
-            if (child && !child._stopped) {
-                child._stop(); // Not recursive - we already have all descendants
-            }
-        });
-        // Then stop self
-        this._stop();
-    }
-    // -------------------------------------------------------------------------
-    // Overridable Lifecycle Hooks
-    // -------------------------------------------------------------------------
-    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() { }
-    /**
-     * Called with the viewport width in CSS pixels:
-     *   - after every on_render()
-     *   - after every on_ready()
-     *   - on window resize, debounced 30ms, for every component in the document
-     *
-     * MUST be synchronous. Prefer CSS media/container queries for pure styling -
-     * override this only when layout requires imperative measurement.
-     */
-    on_viewport_resize(viewport_width) { }
-    /**
-     * Should component re-render after load?
-     * By default, only re-renders if data has changed
-     * Override to control re-rendering behavior
-     */
-    /**
-     * Internal method to determine if component should re-render after on_load()
-     * @private
-     */
-    _should_rerender() {
-        // HTML CACHE MODE - If we used cached HTML, always re-render to get live components
-        if (this._used_cached_html) {
-            if (window.jqhtml?.debug?.verbose) {
-                console.log(`[Cache html] Component ${this._cid} (${this.component_name()}) forcing re-render after cached HTML`);
-            }
-            // Clear the flag
-            this._used_cached_html = false;
-            return true;
-        }
-        // OPTIMIZATION: If no custom on_load(), data cannot change, skip serialization
-        // Data is frozen after on_create() and only unfrozen during on_load()
-        if (!this.__has_custom_on_load) {
-            return false;
-        }
-        // Compare current data state with data state before initial render
-        const currentDataState = JSON.stringify(this.data);
-        const dataChanged = this._data_before_render !== currentDataState;
-        // Update stored state for next comparison
-        if (dataChanged) {
-            this._data_before_render = currentDataState;
-        }
-        return dataChanged;
-    }
-    // -------------------------------------------------------------------------
-    // Public API
-    // -------------------------------------------------------------------------
-    /**
-     * Get component name for debugging
-     */
-    component_name() {
-        return this.constructor.name;
-    }
-    /**
-     * Register event callback - delegates to component-events.ts
-     * @see component-events.ts for full documentation
-     */
-    on(event_name, callback) {
-        return event_on(this, event_name, callback);
-    }
-    /**
-     * 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) {
-        event_trigger(this, event_name, data);
-    }
-    /**
-     * Check if any callbacks are registered for a given event
-     */
-    _on_registered(event_name) {
-        return event_on_registered(this, event_name);
-    }
-    /**
-     * Invalidate a lifecycle event - delegates to component-events.ts
-     * @see component-events.ts for full documentation
-     */
-    invalidate(event_name) {
-        event_invalidate(this, event_name);
-    }
-    /**
-     * Find element by scoped ID
-     *
-     * Searches for elements with id="local_id:THIS_COMPONENT_CID"
-     *
-     * Example:
-     *   Template: <button $sid="save_btn">Save</button>
-     *   Rendered: <button id="save_btn:abc123" data-sid="save_btn">Save</button>
-     *   Access:   this.$sid('save_btn')  // Returns jQuery element
-     *
-     * Performance: Uses native document.getElementById() when component is in DOM,
-     * falls back to jQuery.find() for components not yet attached to DOM.
-     *
-     * @param local_id The local ID (without _cid suffix)
-     * @returns jQuery element with id="local_id:_cid", or empty jQuery object if not found
-     */
-    $sid(local_id) {
-        const scopedId = `${local_id}:${this._cid}`;
-        // Try getElementById first (fast path - works when component is in DOM)
-        const el = document.getElementById(scopedId);
-        if (el) {
-            return $(el);
-        }
-        // Fallback: component not in DOM yet, search within component subtree
-        // This allows $sid() to work on components before they're appended to body
-        // Must escape the ID because it contains ':' which jQuery treats as a pseudo-selector
-        return this.$.find(`#${$.escapeSelector(scopedId)}`);
-    }
-    /**
-     * Get component instance by scoped ID
-     *
-     * Convenience method that finds element by scoped ID and returns the component instance.
-     *
-     * Example:
-     *   Template: <User_Card $sid="active_user" />
-     *   Access:   const user = this.sid('active_user');  // Returns User_Card instance
-     *             user.data.name  // Access component's data
-     *
-     * To get the scoped ID string itself:
-     *   this.$sid('active_user').attr('id')  // Returns "active_user:abc123xyz"
-     *
-     * @param local_id The local ID (without _cid suffix)
-     * @returns Component instance or null if not found or not a component
-     */
-    sid(local_id) {
-        const element = this.$sid(local_id);
-        const component = element.data('_component');
-        // If no component found but element exists, warn developer
-        if (!component && element.length > 0) {
-            console.warn(`Component ${this.constructor.name} tried to call .sid('${local_id}') - ` +
-                `${local_id} exists, however, it is not a component or $redrawable. ` +
-                `Did you forget to add $redrawable to the tag?`);
-        }
-        return component || null;
-    }
-    /**
-     * Get the component that instantiated this component (rendered it in their template)
-     * Returns null if component was created programmatically via $().component()
-     */
-    instantiator() {
-        return this._instantiator;
+        }
+        // Fire registered stop callbacks
+        this.trigger('stop');
+        // Remove from DOM parent's children
+        if (this._dom_parent) {
+            this._dom_parent._dom_children.delete(this);
+        }
+        this._ready_state = 99;
+        this._update_debug_attrs();
+        this._log_lifecycle('destroy', 'complete');
     }
     /**
-     * Find descendant components by CSS selector
+     * Stop component lifecycle - stops all descendant components then self
+     * Leaves DOM intact, just stops lifecycle engine and fires cleanup hooks
      */
-    find(selector) {
-        const components = [];
-        this.$.find(selector).each((_, el) => {
-            const comp = $(el).data('_component');
-            if (comp instanceof Jqhtml_Component) {
-                components.push(comp);
+    stop() {
+        // Stop all descendant components (flat iteration, no recursion needed)
+        this.$.find('.Component').each(function () {
+            const child = $(this).data('_component');
+            if (child && !child._stopped) {
+                child._stop(); // Not recursive - we already have all descendants
             }
         });
-        return components;
+        // Then stop self
+        this._stop();
     }
+    // -------------------------------------------------------------------------
+    // Overridable Lifecycle Hooks
+    // -------------------------------------------------------------------------
+    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() { }
     /**
-     * Find closest ancestor component matching selector
+     * Called with the viewport width in CSS pixels:
+     *   - after every on_render()
+     *   - after every on_ready()
+     *   - on window resize, debounced 30ms, for every component in the document
      *
-     * A bare component name - a plain identifier starting with a capital letter,
-     * such as 'Parent_Dashboard' - is treated as the component-name class
-     * selector '.Parent_Dashboard'. Components carry a CSS class for every name
-     * in their prototype chain, so a base class name matches its subclasses too.
-     * Every other selector ('.Foo', '#id', '[attr]', 'div > .Component') is
-     * passed to jQuery unchanged.
+     * MUST be synchronous. Prefer CSS media/container queries for pure styling -
+     * override this only when layout requires imperative measurement.
      */
-    closest(selector) {
-        const search = Jqhtml_Component.COMPONENT_NAME_PATTERN.test(selector)
-            ? `.${selector}`
-            : selector;
-        let current = this.$.parent();
-        while (current.length > 0) {
-            if (current.is(search)) {
-                const comp = current.data('_component');
-                if (comp instanceof Jqhtml_Component) {
-                    return comp;
-                }
-            }
-            current = current.parent();
-        }
-        return null;
-    }
-    // -------------------------------------------------------------------------
-    // Static Methods
-    // -------------------------------------------------------------------------
+    on_viewport_resize(viewport_width) { }
     /**
-     * Get CSS class hierarchy for this component type
+     * Should component re-render after load?
+     * By default, only re-renders if data has changed
+     * Override to control re-rendering behavior
      */
-    static get_class_hierarchy() {
-        // v2.2.13 - Fixed to handle undefined values in prototype chain
-        const classes = [];
-        let ctor = this;
-        while (ctor) {
-            // Check if constructor has a valid name property
-            if (!ctor.name || typeof ctor.name !== 'string') {
-                // console.warn('[JQHTML v2.2.13] Invalid constructor name in hierarchy:', ctor);
-                break;
-            }
-            // Only add valid class names (non-empty strings, not 'Object')
-            if (ctor.name !== 'Object' && ctor.name !== '') {
-                // Normalize base class names - handle different import patterns
-                let normalizedName = ctor.name;
-                if (normalizedName === '_Jqhtml_Component' || normalizedName === '_Base_Jqhtml_Component') {
-                    normalizedName = 'Component'; // Use 'Component' instead of 'Jqhtml_Component' for CSS class
-                }
-                else if (normalizedName === 'Jqhtml_Component') {
-                    normalizedName = 'Component'; // Use 'Component' instead of 'Jqhtml_Component' for CSS class
-                }
-                classes.push(normalizedName);
-            }
-            // Get the next prototype
-            const nextProto = Object.getPrototypeOf(ctor);
-            // Stop if we've reached the end of the chain
-            if (!nextProto || nextProto === Object.prototype || nextProto.constructor === Object) {
-                break;
-            }
-            ctor = nextProto;
-        }
-        return classes;
-    }
-    // -------------------------------------------------------------------------
-    // Private Implementation
-    // -------------------------------------------------------------------------
-    _generate_cid() {
-        return uid();
-    }
-    _apply_css_classes() {
-        const hierarchy = this.constructor.get_class_hierarchy();
-        // If component name differs from class name, add component name to hierarchy
-        // This happens when:
-        // 1. Using base Jqhtml_Component with _component_name
-        // 2. Using parent class via extends chain (e.g., Contacts_DataGrid using DataGrid_Abstract class)
-        const classesToAdd = [...hierarchy];
-        if (this.args._component_name && this.args._component_name !== this.constructor.name) {
-            // Add component name at the beginning (most specific)
-            classesToAdd.unshift(this.args._component_name);
-        }
-        // Filter out private classes (starting with _) and invalid class names
-        const publicClasses = classesToAdd.filter(className => {
-            // Guard against undefined, null, or non-string values
-            if (!className || typeof className !== 'string') {
-                console.warn('[JQHTML] Filtered out invalid class name:', className);
-                return false;
-            }
-            return !className.startsWith('_');
-        });
-        if (publicClasses.length > 0) {
-            this.$.addClass(publicClasses.join(' '));
-        }
-    }
-    _apply_default_attributes() {
-        // Get template using same logic as render() method
-        let template;
-        // If we have a component name, try looking up by name first (for unregistered components)
-        if (this.args._component_name) {
-            template = get_template(this.args._component_name);
-        }
-        else {
-            // Otherwise look up by class
-            template = get_template_by_class(this.constructor);
-        }
-        if (!template)
-            return;
-        // Walk the extends chain to collect all defaultAttributes from parent templates
-        // Apply from parent to child so child attributes take precedence
-        const templateChain = [];
-        let currentTemplate = template;
-        // Build chain from child to parent
-        while (currentTemplate) {
-            templateChain.unshift(currentTemplate); // Add to front so parent comes first
-            // Check if this template extends another
-            if (currentTemplate.extends) {
-                try {
-                    currentTemplate = get_template(currentTemplate.extends);
-                }
-                catch (error) {
-                    // Parent template not found, stop chain
-                    break;
-                }
-            }
-            else {
-                break;
-            }
-        }
-        // Apply defaultAttributes from each template in the chain (parent first, child last)
-        for (const tmpl of templateChain) {
-            if (!tmpl.defaultAttributes)
-                continue;
-            // Filter out 'tag' since it determines tag name, not an attribute
-            const defineAttrs = { ...tmpl.defaultAttributes };
-            delete defineAttrs.tag;
-            // Debug logging
-            if (window.jqhtml?.debug?.enabled) {
-                const componentName = tmpl.name || this.args._component_name || this.constructor.name;
-                console.log(`[Component] Applying defaultAttributes for ${componentName}:`, defineAttrs);
-            }
-            // Apply each default attribute
-            for (const [key, value] of Object.entries(defineAttrs)) {
-                if (key === 'class') {
-                    // Special handling for class - merge with existing
-                    const existingClasses = this.$.attr('class');
-                    if (existingClasses) {
-                        const existing = existingClasses.split(/\s+/).filter(c => c);
-                        const newClasses = String(value).split(/\s+/).filter(c => c);
-                        for (const newClass of newClasses) {
-                            if (!existing.includes(newClass)) {
-                                existing.push(newClass);
-                            }
-                        }
-                        this.$.attr('class', existing.join(' '));
-                    }
-                    else {
-                        this.$.attr('class', value);
-                    }
-                }
-                else if (key === 'style') {
-                    // Special handling for style - merge with existing
-                    // Define attributes are applied AFTER invocation attributes
-                    // So we only add Define style properties that don't already exist
-                    // This ensures invocation wins conflicts (invocation overrides Define)
-                    const existingStyle = this.$.attr('style');
-                    if (existingStyle) {
-                        // Parse existing styles (from invocation)
-                        const existingRules = new Map();
-                        existingStyle.split(';').forEach(rule => {
-                            const [prop, val] = rule.split(':').map(s => s.trim());
-                            if (prop && val)
-                                existingRules.set(prop, val);
-                        });
-                        // Parse Define styles and only add if not already present
-                        String(value).split(';').forEach(rule => {
-                            const [prop, val] = rule.split(':').map(s => s.trim());
-                            if (prop && val && !existingRules.has(prop)) {
-                                // Only add if property doesn't exist (invocation wins)
-                                existingRules.set(prop, val);
-                            }
-                        });
-                        // Build merged style string
-                        const merged = Array.from(existingRules.entries())
-                            .map(([prop, val]) => `${prop}: ${val}`)
-                            .join('; ');
-                        this.$.attr('style', merged);
-                    }
-                    else {
-                        this.$.attr('style', value);
-                    }
-                }
-                else if (key.startsWith('$') || key.startsWith('data-')) {
-                    // Data attributes - also update args
-                    const dataKey = key.startsWith('$') ? key.substring(1) :
-                        key.startsWith('data-') ? key.substring(5) : key;
-                    // Only apply if not already set in args
-                    if (!(dataKey in this.args)) {
-                        this.args[dataKey] = value;
-                        this.$.data(dataKey, value);
-                        this.$.attr(key.startsWith('$') ? `data-${dataKey}` : key, String(value));
-                    }
-                }
-                else {
-                    // Regular attributes - apply directly if not already set
-                    if (!this.$.attr(key)) {
-                        this.$.attr(key, value);
-                    }
-                }
+    /**
+     * Internal method to determine if component should re-render after on_load()
+     * @private
+     */
+    _should_rerender() {
+        // HTML CACHE MODE - If we used cached HTML, always re-render to get live components
+        if (this._used_cached_html) {
+            if (window.jqhtml?.debug?.verbose) {
+                console.log(`[Cache html] Component ${this._cid} (${this.component_name()}) forcing re-render after cached HTML`);
             }
+            // Clear the flag
+            this._used_cached_html = false;
+            return true;
         }
-    }
-    _set_attributes() {
-        // data-cid on the rendered element is debug-only: it mirrors this._cid so component
-        // boundaries are legible in DevTools. The runtime never reads it - scoping uses the
-        // _cid property, and the transient data-cid placeholder the instruction processor
-        // matches on is written and removed before this ever runs.
-        if (debug_attributes_enabled()) {
-            this.$.attr('data-cid', this._cid);
+        // OPTIMIZATION: If no custom on_load(), data cannot change, skip serialization
+        // Data is frozen after on_create() and only unfrozen during on_load()
+        if (!this.__has_custom_on_load) {
+            return false;
         }
-        // Only set lifecycle state attribute if verbose mode enabled
-        if (window.jqhtml?.debug?.verbose) {
-            this.$.attr('data-_lifecycle-state', this._ready_state.toString());
+        // Compare current data state with data state before initial render
+        const currentDataState = JSON.stringify(this.data);
+        const dataChanged = this._data_before_render !== currentDataState;
+        // Update stored state for next comparison
+        if (dataChanged) {
+            this._data_before_render = currentDataState;
         }
+        return dataChanged;
     }
-    _update_debug_attrs() {
-        // Only update lifecycle state attribute if verbose mode enabled
-        if (window.jqhtml?.debug?.verbose) {
-            this.$.attr('data-_lifecycle-state', this._ready_state.toString());
-        }
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+    /**
+     * Get component name for debugging
+     */
+    /**
+     * The name this component was invoked as - the tag written in the template
+     * (<User_Card> -> 'User_Card'), the name given to $(el).component('User_Card'),
+     * or the boot placeholder's data-component-init-name. For a template-only
+     * component this is the template name, not 'Jqhtml_Component'. Falls back to
+     * the class's static component_name, then its JS class name.
+     */
+    component_name() {
+        return this._component_name;
     }
-    _find_dom_parent() {
-        let current = this.$.parent();
-        while (current.length > 0) {
-            const parent = current.data('_component');
-            if (parent instanceof Jqhtml_Component) {
-                this._dom_parent = parent;
-                parent._dom_children.add(this);
-                break;
-            }
-            current = current.parent();
-        }
+    /**
+     * Register event callback - delegates to component-events.ts
+     * @see component-events.ts for full documentation
+     */
+    on(event_name, callback) {
+        return event_on(this, event_name, callback);
     }
     /**
-     * Get DOM children (components in DOM subtree)
-     * Uses fast _dom_children registry when possible, falls back to DOM traversal for off-DOM components
-     * @private - Used internally for lifecycle coordination
+     * 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
      */
-    _get_dom_children() {
-        // If component was off-DOM during render, children couldn't register via _find_dom_parent()
-        // Use DOM traversal to find direct children (works off-DOM, slightly slower)
-        if (this._use_dom_fallback) {
-            const directChildren = [];
-            this.$.find('.Component').each((_, el) => {
-                const $el = $(el);
-                const comp = $el.data('_component');
-                if (comp instanceof Jqhtml_Component) {
-                    // Only include if this component is the direct parent (not a grandparent)
-                    // Check: closest parent component is us (or no parent = we're the root)
-                    const closestParent = $el.parent().closest('.Component');
-                    if (closestParent.length === 0 || closestParent.data('_component') === this) {
-                        directChildren.push(comp);
-                    }
-                }
-            });
-            return directChildren;
-        }
-        // Fast path: component was in-DOM during render, children registered normally
-        // Filter out any that have since been removed from DOM (destroyed/replaced)
-        const children = Array.from(this._dom_children);
-        return children.filter(child => {
-            return $.contains(document.documentElement, child.$[0]);
-        });
+    once(event_name, callback) {
+        return event_once(this, event_name, callback);
     }
-    _log_lifecycle(phase, status) {
-        // Use new debug module
-        logLifecycle(this, phase, status);
-        // Keep legacy support for window.JQHTML_DEBUG
-        if (typeof window !== 'undefined' && window.JQHTML_DEBUG) {
-            window.JQHTML_DEBUG.log(this.component_name(), phase, status, {
-                cid: this._cid,
-                ready_state: this._ready_state,
-                args: this.args
-            });
-        }
+    /**
+     * Trigger a lifecycle event - delegates to component-events.ts
+     * @see component-events.ts for full documentation
+     */
+    trigger(event_name, data) {
+        event_trigger(this, event_name, data);
     }
-    _log_debug(action, ...args) {
-        if (typeof window !== 'undefined' && window.JQHTML_DEBUG) {
-            window.JQHTML_DEBUG.log(this.component_name(), 'debug', `${action}: ${args.map(a => JSON.stringify(a)).join(', ')}`);
+    /**
+     * Check if any callbacks are registered for a given event
+     */
+    _on_registered(event_name) {
+        return event_on_registered(this, event_name);
+    }
+    /**
+     * Invalidate a lifecycle event - delegates to component-events.ts
+     * @see component-events.ts for full documentation
+     */
+    invalidate(event_name) {
+        event_invalidate(this, event_name);
+    }
+    /**
+     * Find element by scoped ID
+     *
+     * Searches for elements with id="local_id:THIS_COMPONENT_CID"
+     *
+     * Example:
+     *   Template: <button $sid="save_btn">Save</button>
+     *   Rendered: <button id="save_btn:abc123" data-sid="save_btn">Save</button>
+     *   Access:   this.$sid('save_btn')  // Returns jQuery element
+     *
+     * Performance: Uses native document.getElementById() when component is in DOM,
+     * falls back to jQuery.find() for components not yet attached to DOM.
+     *
+     * @param local_id The local ID (without _cid suffix)
+     * @returns jQuery element with id="local_id:_cid", or empty jQuery object if not found
+     */
+    $sid(local_id) {
+        const scopedId = `${local_id}:${this._cid}`;
+        // Try getElementById first (fast path - works when component is in DOM)
+        const el = document.getElementById(scopedId);
+        if (el) {
+            return $(el);
         }
+        // Fallback: component not in DOM yet, search within component subtree
+        // This allows $sid() to work on components before they're appended to body
+        // Must escape the ID because it contains ':' which jQuery treats as a pseudo-selector
+        return this.$.find(`#${$.escapeSelector(scopedId)}`);
     }
-}
-// Static properties
-Jqhtml_Component.__jqhtml_component = true; // Marker for unified register() detection
-// A bare component name, as accepted by closest() in place of a class selector
-Jqhtml_Component.COMPONENT_NAME_PATTERN = /^[A-Z][A-Za-z0-9_]*$/;
-
-/**
- * JQHTML v2 Template Renderer
- *
- * Connects compiled templates to components
- * Processes instruction arrays and handles bindings
- */
-/**
- * Process slot-only template inheritance
- *
- * When a component's template returns {_slots: {...}}, walk the prototype
- * chain to find a parent template and invoke it with the child's slots as content.
- *
- * @param component The component instance
- * @param childSlots The slots object from the child template
- * @returns [instructions, context] tuple or null if no parent found
- */
-async function process_slot_inheritance(component, childSlots) {
-    // Walk the prototype chain to find parent class with template
-    let currentClass = Object.getPrototypeOf(component.constructor);
-    console.log(`[JQHTML] Walking prototype chain for ${component.constructor.name}`);
-    while (currentClass && currentClass !== Jqhtml_Component && currentClass.name !== 'Object') {
-        const className = currentClass.name;
-        console.log(`[JQHTML]   Checking parent class: ${className}`);
-        // Skip internal framework classes
-        if (className === '_Jqhtml_Component' || className === '_Base_Jqhtml_Component') {
-            currentClass = Object.getPrototypeOf(currentClass);
-            continue;
+    /**
+     * Get component instance by scoped ID
+     *
+     * Convenience method that finds element by scoped ID and returns the component instance.
+     *
+     * Example:
+     *   Template: <User_Card $sid="active_user" />
+     *   Access:   const user = this.sid('active_user');  // Returns User_Card instance
+     *             user.data.name  // Access component's data
+     *
+     * To get the scoped ID string itself:
+     *   this.$sid('active_user').attr('id')  // Returns "active_user:abc123xyz"
+     *
+     * @param local_id The local ID (without _cid suffix)
+     * @returns Component instance or null if not found or not a component
+     */
+    sid(local_id) {
+        const element = this.$sid(local_id);
+        const component = element.data('_component');
+        // If no component found but element exists, warn developer
+        if (!component && element.length > 0) {
+            console.warn(`Component ${this.constructor.name} tried to call .sid('${local_id}') - ` +
+                `${local_id} exists, however, it is not a component or $redrawable. ` +
+                `Did you forget to add $redrawable to the tag?`);
         }
-        // Try to find template for this parent class
-        try {
-            const parentTemplate = get_template(className);
-            console.log(`[JQHTML]   Template found for ${className}:`, parentTemplate ? parentTemplate.name : 'null');
-            // Check if we got the default template (means no real template found)
-            if (parentTemplate && parentTemplate.name !== 'Jqhtml_Component') {
-                console.log(`[JQHTML]   Invoking parent template ${className}`);
-                // Found a real parent template - invoke it with child's slots as content
-                const [parentInstructions, parentContext] = parentTemplate.render.call(component, component.data, component.args, childSlots // Pass child slots as content parameter
-                );
-                // Check if parent also returns slots (recursive inheritance)
-                if (parentInstructions && typeof parentInstructions === 'object' && parentInstructions._slots) {
-                    // Parent also has slot-only template - recurse
-                    console.log(`[JQHTML]   Parent also slot-only, recursing`);
-                    return await process_slot_inheritance(component, parentInstructions._slots);
+        return component || null;
+    }
+    /**
+     * Get the component that instantiated this component (rendered it in their template)
+     * Returns null if component was created programmatically via $().component()
+     */
+    instantiator() {
+        return this._instantiator;
+    }
+    /**
+     * Find descendant components by CSS selector
+     */
+    find(selector) {
+        const components = [];
+        this.$.find(selector).each((_, el) => {
+            const comp = $(el).data('_component');
+            if (comp instanceof Jqhtml_Component) {
+                components.push(comp);
+            }
+        });
+        return components;
+    }
+    /**
+     * Find closest ancestor component matching selector
+     *
+     * A bare component name - a plain identifier starting with a capital letter,
+     * optionally preceded by a single underscore, such as 'Parent_Dashboard' or
+     * '_Root_Layout' - is treated as the component-name class
+     * selector '.Parent_Dashboard'. Components carry a CSS class for every name
+     * in their prototype chain, so a base class name matches its subclasses too.
+     * Every other selector ('.Foo', '#id', '[attr]', 'div > .Component') is
+     * passed to jQuery unchanged.
+     */
+    closest(selector) {
+        const search = Jqhtml_Component.COMPONENT_NAME_PATTERN.test(selector)
+            ? `.${selector}`
+            : selector;
+        let current = this.$.parent();
+        while (current.length > 0) {
+            if (current.is(search)) {
+                const comp = current.data('_component');
+                if (comp instanceof Jqhtml_Component) {
+                    return comp;
                 }
-                // Parent returned HTML - we're done
-                console.log(`[JQHTML]   Parent returned instructions, inheritance complete`);
-                return [parentInstructions, parentContext];
             }
+            current = current.parent();
         }
-        catch (error) {
-            console.warn(`[JQHTML] Error looking up parent template for ${className}:`, error);
+        return null;
+    }
+    // -------------------------------------------------------------------------
+    // Static Methods
+    // -------------------------------------------------------------------------
+    /**
+     * Get CSS class hierarchy for this component type
+     */
+    static get_class_hierarchy() {
+        // v2.2.13 - Fixed to handle undefined values in prototype chain
+        const classes = [];
+        let ctor = this;
+        while (ctor) {
+            // Check if constructor has a valid name property
+            if (!ctor.name || typeof ctor.name !== 'string') {
+                // console.warn('[JQHTML v2.2.13] Invalid constructor name in hierarchy:', ctor);
+                break;
+            }
+            // Only add valid class names (non-empty strings, not 'Object')
+            if (ctor.name !== 'Object' && ctor.name !== '') {
+                // Normalize base class names - handle different import patterns
+                let normalizedName = ctor.name;
+                if (normalizedName === '_Jqhtml_Component' || normalizedName === '_Base_Jqhtml_Component') {
+                    normalizedName = 'Component'; // Use 'Component' instead of 'Jqhtml_Component' for CSS class
+                }
+                else if (normalizedName === 'Jqhtml_Component') {
+                    normalizedName = 'Component'; // Use 'Component' instead of 'Jqhtml_Component' for CSS class
+                }
+                classes.push(normalizedName);
+            }
+            // Get the next prototype
+            const nextProto = Object.getPrototypeOf(ctor);
+            // Stop if we've reached the end of the chain
+            if (!nextProto || nextProto === Object.prototype || nextProto.constructor === Object) {
+                break;
+            }
+            ctor = nextProto;
         }
-        // Move to next parent
-        currentClass = Object.getPrototypeOf(currentClass);
+        return classes;
     }
-    // No parent template found
-    console.warn(`[JQHTML] No parent template found after walking chain`);
-    return null;
-}
-/**
- * Render a template for a component
- * Templates are functions that return [instructions, context] tuples
- */
-async function render_template(component, template_fn) {
-    // Get template from registry if not provided
-    let render_fn = template_fn;
-    if (!render_fn) {
-        const template_def = get_template_by_class(component.constructor);
-        render_fn = template_def.render;
+    // -------------------------------------------------------------------------
+    // Private Implementation
+    // -------------------------------------------------------------------------
+    _generate_cid() {
+        return uid();
     }
-    if (!render_fn) {
-        // No template, component should handle its own rendering
-        return;
+    _apply_css_classes() {
+        const hierarchy = this.constructor.get_class_hierarchy();
+        // If component name differs from class name, add component name to hierarchy
+        // This happens when:
+        // 1. Using base Jqhtml_Component with _component_name
+        // 2. Using parent class via extends chain (e.g., Contacts_DataGrid using DataGrid_Abstract class)
+        const classesToAdd = [...hierarchy];
+        if (this.args._component_name && this.args._component_name !== this.constructor.name) {
+            // Add component name at the beginning (most specific)
+            classesToAdd.unshift(this.args._component_name);
+        }
+        // Filter out private/mangled classes (starting with _) and invalid class names.
+        // A component name with the reserved single-underscore prefix (_Root_Layout)
+        // is public and is kept - see component-name.ts.
+        const publicClasses = classesToAdd.filter(className => {
+            // Guard against undefined, null, or non-string values
+            if (!className || typeof className !== 'string') {
+                console.warn('[JQHTML] Filtered out invalid class name:', className);
+                return false;
+            }
+            return !className.startsWith('_') || is_component_name(className);
+        });
+        if (publicClasses.length > 0) {
+            this.$.addClass(publicClasses.join(' '));
+        }
     }
-    // Clear existing content
-    component.$.empty();
-    // Execute template function
-    // Templates receive: (data, args, content)
-    // Provide a default empty content function if none provided
-    const defaultContent = () => '';
-    let [instructions, context] = render_fn.call(component, component.data, component.args, defaultContent // Default content function that returns empty string
-    );
-    // Check for slot-only template inheritance
-    // If instructions is {_slots: {...}}, this is a slot-only template
-    // We need to find the parent template and invoke it with these slots
-    if (instructions && typeof instructions === 'object' && instructions._slots) {
-        console.log(`[JQHTML] Slot-only template detected for ${component.constructor.name}, invoking inheritance`);
-        const result = await process_slot_inheritance(component, instructions._slots);
-        if (result) {
-            console.log(`[JQHTML] Parent template found, using parent instructions`);
-            instructions = result[0];
-            context = result[1];
+    _apply_default_attributes() {
+        // Get template using same logic as render() method
+        let template;
+        // If we have a component name, try looking up by name first (for unregistered components)
+        if (this.args._component_name) {
+            template = get_template(this.args._component_name);
         }
         else {
-            console.warn(`[JQHTML] No parent template found for ${component.constructor.name}, rendering empty`);
-            // No parent template found - return empty
-            instructions = [];
+            // Otherwise look up by class
+            template = get_template_by_class(this.constructor);
         }
-    }
-    // Process instructions to generate DOM
-    await process_instructions(instructions, component.$, component);
-    // Process bindings after DOM is created
-    await process_bindings(component);
-    // Attach event handlers
-    await attach_event_handlers(component);
-}
-/**
- * Process data bindings (attributes created by :prop syntax)
- */
-async function process_bindings(component) {
-    // Find all elements with data-bind-* attributes
-    component.$.find('[data-bind-prop], [data-bind-value], [data-bind-text], [data-bind-html], [data-bind-class], [data-bind-style]').each((_, element) => {
-        const el = $(element);
-        const attrs = element.attributes;
-        for (let i = 0; i < attrs.length; i++) {
-            const attr = attrs[i];
-            if (attr.name.startsWith('data-bind-')) {
-                const binding_type = attr.name.substring(10); // Remove 'data-bind-'
-                const expression = attr.value;
+        if (!template)
+            return;
+        // Walk the extends chain to collect all defaultAttributes from parent templates
+        // Apply from parent to child so child attributes take precedence
+        const templateChain = [];
+        let currentTemplate = template;
+        // Build chain from child to parent
+        while (currentTemplate) {
+            templateChain.unshift(currentTemplate); // Add to front so parent comes first
+            // Check if this template extends another
+            if (currentTemplate.extends) {
                 try {
-                    // Evaluate expression in component context
-                    const value = evaluate_expression(expression, component);
-                    // Apply binding based on type
-                    switch (binding_type) {
-                        case 'prop':
-                            // Generic property binding
-                            const prop_name = el.attr('data-bind-prop-name') || 'value';
-                            el.prop(prop_name, value);
-                            break;
-                        case 'value':
-                            el.val(value);
-                            break;
-                        case 'text':
-                            el.text(value);
-                            break;
-                        case 'html':
-                            el.html(value);
-                            break;
-                        case 'class':
-                            if (typeof value === 'object') {
-                                // Object syntax: {active: true, disabled: false}
-                                Object.entries(value).forEach(([className, enabled]) => {
-                                    el.toggleClass(className, !!enabled);
-                                });
-                            }
-                            else {
-                                // String syntax
-                                el.addClass(String(value));
-                            }
-                            break;
-                        case 'style':
-                            if (typeof value === 'object') {
-                                el.css(value);
+                    currentTemplate = get_template(currentTemplate.extends);
+                }
+                catch (error) {
+                    // Parent template not found, stop chain
+                    break;
+                }
+            }
+            else {
+                break;
+            }
+        }
+        // Apply defaultAttributes from each template in the chain (parent first, child last)
+        for (const tmpl of templateChain) {
+            if (!tmpl.defaultAttributes)
+                continue;
+            // Filter out 'tag' since it determines tag name, not an attribute
+            const defineAttrs = { ...tmpl.defaultAttributes };
+            delete defineAttrs.tag;
+            // Debug logging
+            if (window.jqhtml?.debug?.enabled) {
+                const componentName = tmpl.name || this.args._component_name || this.constructor.name;
+                console.log(`[Component] Applying defaultAttributes for ${componentName}:`, defineAttrs);
+            }
+            // Apply each default attribute
+            for (const [key, value] of Object.entries(defineAttrs)) {
+                if (key === 'class') {
+                    // Special handling for class - merge with existing
+                    const existingClasses = this.$.attr('class');
+                    if (existingClasses) {
+                        const existing = existingClasses.split(/\s+/).filter(c => c);
+                        const newClasses = String(value).split(/\s+/).filter(c => c);
+                        for (const newClass of newClasses) {
+                            if (!existing.includes(newClass)) {
+                                existing.push(newClass);
                             }
-                            else {
-                                el.attr('style', String(value));
+                        }
+                        this.$.attr('class', existing.join(' '));
+                    }
+                    else {
+                        this.$.attr('class', value);
+                    }
+                }
+                else if (key === 'style') {
+                    // Special handling for style - merge with existing
+                    // Define attributes are applied AFTER invocation attributes
+                    // So we only add Define style properties that don't already exist
+                    // This ensures invocation wins conflicts (invocation overrides Define)
+                    const existingStyle = this.$.attr('style');
+                    if (existingStyle) {
+                        // Parse existing styles (from invocation)
+                        const existingRules = new Map();
+                        existingStyle.split(';').forEach(rule => {
+                            const [prop, val] = rule.split(':').map(s => s.trim());
+                            if (prop && val)
+                                existingRules.set(prop, val);
+                        });
+                        // Parse Define styles and only add if not already present
+                        String(value).split(';').forEach(rule => {
+                            const [prop, val] = rule.split(':').map(s => s.trim());
+                            if (prop && val && !existingRules.has(prop)) {
+                                // Only add if property doesn't exist (invocation wins)
+                                existingRules.set(prop, val);
                             }
-                            break;
-                        default:
-                            // Custom binding - set as attribute
-                            el.attr(binding_type, value);
+                        });
+                        // Build merged style string
+                        const merged = Array.from(existingRules.entries())
+                            .map(([prop, val]) => `${prop}: ${val}`)
+                            .join('; ');
+                        this.$.attr('style', merged);
+                    }
+                    else {
+                        this.$.attr('style', value);
                     }
                 }
-                catch (error) {
-                    console.error(`Error evaluating binding "${expression}":`, error);
+                else if (key.startsWith('$') || key.startsWith('data-')) {
+                    // Data attributes - also update args
+                    const dataKey = key.startsWith('$') ? key.substring(1) :
+                        key.startsWith('data-') ? key.substring(5) : key;
+                    // Only apply if not already set in args
+                    if (!(dataKey in this.args)) {
+                        this.args[dataKey] = value;
+                        this.$.data(dataKey, value);
+                        this.$.attr(key.startsWith('$') ? `data-${dataKey}` : key, String(value));
+                    }
+                }
+                else {
+                    // Regular attributes - apply directly if not already set
+                    if (!this.$.attr(key)) {
+                        this.$.attr(key, value);
+                    }
                 }
             }
         }
-    });
+    }
+    _set_attributes() {
+        // data-cid on the rendered element is debug-only: it mirrors this._cid so component
+        // boundaries are legible in DevTools. The runtime never reads it - scoping uses the
+        // _cid property, and the transient data-cid placeholder the instruction processor
+        // matches on is written and removed before this ever runs.
+        if (debug_attributes_enabled()) {
+            this.$.attr('data-cid', this._cid);
+        }
+        // Only set lifecycle state attribute if verbose mode enabled
+        if (window.jqhtml?.debug?.verbose) {
+            this.$.attr('data-_lifecycle-state', this._ready_state.toString());
+        }
+    }
+    _update_debug_attrs() {
+        // Only update lifecycle state attribute if verbose mode enabled
+        if (window.jqhtml?.debug?.verbose) {
+            this.$.attr('data-_lifecycle-state', this._ready_state.toString());
+        }
+    }
+    _find_dom_parent() {
+        let current = this.$.parent();
+        while (current.length > 0) {
+            const parent = current.data('_component');
+            if (parent instanceof Jqhtml_Component) {
+                this._dom_parent = parent;
+                parent._dom_children.add(this);
+                break;
+            }
+            current = current.parent();
+        }
+    }
+    /**
+     * Get DOM children (components in DOM subtree)
+     * Uses fast _dom_children registry when possible, falls back to DOM traversal for off-DOM components
+     * @private - Used internally for lifecycle coordination
+     */
+    _get_dom_children() {
+        // If component was off-DOM during render, children couldn't register via _find_dom_parent()
+        // Use DOM traversal to find direct children (works off-DOM, slightly slower)
+        if (this._use_dom_fallback) {
+            const directChildren = [];
+            this.$.find('.Component').each((_, el) => {
+                const $el = $(el);
+                const comp = $el.data('_component');
+                if (comp instanceof Jqhtml_Component) {
+                    // Only include if this component is the direct parent (not a grandparent)
+                    // Check: closest parent component is us (or no parent = we're the root)
+                    const closestParent = $el.parent().closest('.Component');
+                    if (closestParent.length === 0 || closestParent.data('_component') === this) {
+                        directChildren.push(comp);
+                    }
+                }
+            });
+            return directChildren;
+        }
+        // Fast path: component was in-DOM during render, children registered normally
+        // Filter out any that have since been removed from DOM (destroyed/replaced)
+        const children = Array.from(this._dom_children);
+        return children.filter(child => {
+            return $.contains(document.documentElement, child.$[0]);
+        });
+    }
+    _log_lifecycle(phase, status) {
+        // Use new debug module
+        logLifecycle(this, phase, status);
+        // Keep legacy support for window.JQHTML_DEBUG
+        if (typeof window !== 'undefined' && window.JQHTML_DEBUG) {
+            window.JQHTML_DEBUG.log(this.component_name(), phase, status, {
+                cid: this._cid,
+                ready_state: this._ready_state,
+                args: this.args
+            });
+        }
+    }
+    _log_debug(action, ...args) {
+        if (typeof window !== 'undefined' && window.JQHTML_DEBUG) {
+            window.JQHTML_DEBUG.log(this.component_name(), 'debug', `${action}: ${args.map(a => JSON.stringify(a)).join(', ')}`);
+        }
+    }
 }
+// Static properties
+Jqhtml_Component.__jqhtml_component = true; // Marker for unified register() detection
+// A bare component name, as accepted by closest() in place of a class selector
+Jqhtml_Component.COMPONENT_NAME_PATTERN = COMPONENT_NAME_PATTERN;
+
+var light_css = "html[data-jqhtml-debug] .jqhtml-debug-hit {\n  outline: 2px solid #e5322d;\n  outline-offset: -2px;\n}\n\nhtml[data-jqhtml-debug] .jqhtml-debug-hit.jqhtml-debug-depth-0 {\n  outline-color: #e5322d;\n}\n\nhtml[data-jqhtml-debug] .jqhtml-debug-hit.jqhtml-debug-depth-1 {\n  outline-color: #2f6fe4;\n}\n\nhtml[data-jqhtml-debug] .jqhtml-debug-hit.jqhtml-debug-depth-2 {\n  outline-color: #1f9d55;\n}\n\nhtml[data-jqhtml-debug] .jqhtml-debug-hit.jqhtml-debug-depth-3 {\n  outline-color: #d97706;\n}\n\nhtml[data-jqhtml-debug] .jqhtml-debug-hit.jqhtml-debug-depth-4 {\n  outline-color: #7c3aed;\n}\n\nhtml[data-jqhtml-debug] .jqhtml-debug-hit.jqhtml-debug-depth-5 {\n  outline-color: #0e7490;\n}";
+
+var shadow_css = ":host {\n  all: initial;\n  display: block;\n  position: fixed;\n  box-sizing: border-box;\n  top: 0;\n  left: 0;\n  width: 100vw;\n  height: 100vh;\n  z-index: 2147483647;\n  pointer-events: none;\n  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, \"Liberation Mono\", monospace;\n  font-size: 12px;\n  font-weight: normal;\n  font-style: normal;\n  font-variant: normal;\n  line-height: 1.4;\n  color: #1c1c1c;\n  text-align: left;\n  text-transform: none;\n  text-indent: 0;\n  text-shadow: none;\n  letter-spacing: normal;\n  word-spacing: normal;\n  white-space: normal;\n  word-break: normal;\n  overflow-wrap: anywhere;\n  hyphens: none;\n  tab-size: 4;\n  direction: ltr;\n  visibility: visible;\n  cursor: default;\n  list-style: none;\n  quotes: none;\n}\n\n.jqhtml-debug-layer {\n  position: absolute;\n  top: 0;\n  left: 0;\n  width: 100%;\n  height: 100%;\n  overflow: hidden;\n  pointer-events: none;\n}\n\n.jqhtml-debug-label {\n  position: absolute;\n  box-sizing: border-box;\n  display: block;\n  padding: 1px 5px;\n  min-height: 18px;\n  color: #ffffff;\n  background: #e5322d;\n  border-radius: 0 0 3px 0;\n  font-size: 11px;\n  line-height: 16px;\n  white-space: normal;\n  overflow-wrap: anywhere;\n  overflow: hidden;\n  pointer-events: none;\n}\n\n.jqhtml-debug-label.jqhtml-debug-depth-0 {\n  background: #e5322d;\n}\n\n.jqhtml-debug-label.jqhtml-debug-depth-1 {\n  background: #2f6fe4;\n}\n\n.jqhtml-debug-label.jqhtml-debug-depth-2 {\n  background: #1f9d55;\n}\n\n.jqhtml-debug-label.jqhtml-debug-depth-3 {\n  background: #d97706;\n}\n\n.jqhtml-debug-label.jqhtml-debug-depth-4 {\n  background: #7c3aed;\n}\n\n.jqhtml-debug-label.jqhtml-debug-depth-5 {\n  background: #0e7490;\n}\n\n.jqhtml-debug-label-name {\n  font-weight: bold;\n}\n\n.jqhtml-debug-label-args {\n  opacity: 0.9;\n  margin-left: 6px;\n}\n\n.jqhtml-debug-modal {\n  display: none;\n  position: absolute;\n  box-sizing: border-box;\n  top: 24px;\n  right: 24px;\n  width: 520px;\n  max-width: calc(100% - 48px);\n  max-height: calc(100% - 48px);\n  overflow: auto;\n  padding: 0 0 12px 0;\n  background: #ffffff;\n  color: #1c1c1c;\n  border: 1px solid #d0d0d0;\n  border-radius: 6px;\n  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.25);\n  pointer-events: auto;\n}\n\n.jqhtml-debug-modal.jqhtml-debug-modal-open {\n  display: block;\n}\n\n.jqhtml-debug-title {\n  display: flex;\n  align-items: center;\n  gap: 8px;\n  position: sticky;\n  top: 0;\n  padding: 8px 12px;\n  background: #1c1c1c;\n  color: #ffffff;\n  font-weight: bold;\n}\n\n.jqhtml-debug-title-name {\n  flex: 1 1 auto;\n  font-size: 13px;\n}\n\n.jqhtml-debug-button {\n  all: unset;\n  display: inline-block;\n  box-sizing: border-box;\n  padding: 2px 8px;\n  border: 1px solid rgba(255, 255, 255, 0.6);\n  border-radius: 3px;\n  color: #ffffff;\n  font-size: 11px;\n  line-height: 16px;\n  cursor: pointer;\n  user-select: none;\n}\n\n.jqhtml-debug-button:hover {\n  background: rgba(255, 255, 255, 0.15);\n}\n\n.jqhtml-debug-section {\n  padding: 8px 12px 0 12px;\n}\n\n.jqhtml-debug-h {\n  margin: 4px 0;\n  color: #666666;\n  font-size: 11px;\n  text-transform: uppercase;\n  letter-spacing: 0.06em;\n}\n\n.jqhtml-debug-table {\n  display: grid;\n  grid-template-columns: max-content max-content 1fr;\n  column-gap: 12px;\n  row-gap: 2px;\n  align-items: baseline;\n}\n\n.jqhtml-debug-key {\n  color: #005cc5;\n  white-space: nowrap;\n}\n\n.jqhtml-debug-type {\n  color: #666666;\n  font-size: 11px;\n  white-space: nowrap;\n}\n\n.jqhtml-debug-value {\n  white-space: pre-wrap;\n  overflow-wrap: anywhere;\n}\n\n.jqhtml-debug-empty {\n  color: #666666;\n  font-style: italic;\n}\n\n.jqhtml-debug-list {\n  display: block;\n  margin: 0;\n  padding: 0;\n}\n\n.jqhtml-debug-link {\n  display: block;\n  padding: 2px 4px;\n  margin: 0 -4px;\n  border-radius: 3px;\n  cursor: pointer;\n}\n\n.jqhtml-debug-link:hover {\n  background: #eef3ff;\n}\n\n.jqhtml-debug-link-cid {\n  color: #666666;\n  margin-left: 6px;\n}\n\n.jqhtml-debug-note {\n  margin-top: 4px;\n  color: #92400e;\n  font-size: 11px;\n}";
+
 /**
- * Attach event handlers (attributes created by @event syntax)
+ * Component debug overlay.
+ *
+ * `jqhtml.debug_overlay.enable()` turns the page into an inspector: hovering
+ * any element outlines the component under the pointer and every component
+ * above it, each with a small tab naming the component and its simple args;
+ * clicking opens a modal describing the innermost component (identity, args,
+ * data, state, ancestry, instantiator) instead of firing the click. Alt+click
+ * passes through. `disable()` puts everything back.
+ *
+ * Non-invasiveness, the design goal (details in ./CLAUDE.md):
+ *   - The overlay's own UI lives in a shadow root on a host element appended to
+ *     <body>, styled by shadow.scss. Page CSS cannot select into it and :host
+ *     cuts inheritance, so its look is fixed whatever the page does.
+ *   - The only thing added to application elements is a pair of classes,
+ *     .jqhtml-debug-hit / .jqhtml-debug-depth-N, which light.scss paints as an
+ *     inset outline (no layout effect) and only while <html data-jqhtml-debug>.
+ *   - Listeners are attached on enable and removed on disable. The stylesheets
+ *     and the (detached) host stay once installed: inert, and cheap to re-enable.
+ *   - Nothing is registered per component, so components created after enable
+ *     are covered automatically.
  */
-async function attach_event_handlers(component) {
-    // Find all elements with data-on-* attributes
-    component.$.find('[data-on-click], [data-on-change], [data-on-submit], [data-on-keyup], [data-on-keydown], [data-on-focus], [data-on-blur]').each((_, element) => {
-        const el = $(element);
-        const attrs = element.attributes;
-        for (let i = 0; i < attrs.length; i++) {
-            const attr = attrs[i];
-            if (attr.name.startsWith('data-on-')) {
-                const event_name = attr.name.substring(8); // Remove 'data-on-'
-                const handler_expr = attr.value;
-                // Remove the attribute to avoid re-processing
-                el.removeAttr(attr.name);
-                // Attach event handler
-                el.on(event_name, function (event) {
-                    try {
-                        // Create handler function in component context
-                        const handler = evaluate_handler(handler_expr, component);
-                        if (typeof handler === 'function') {
-                            // Call with component as 'this' and pass event
-                            handler.call(component, event);
-                        }
-                        else {
-                            // Expression to execute
-                            evaluate_expression(handler_expr, component, { $event: event });
-                        }
-                    }
-                    catch (error) {
-                        console.error(`Error in ${event_name} handler "${handler_expr}":`, error);
-                    }
-                });
-            }
-        }
+const PREFIX = 'jqhtml-debug-';
+const ROOT_ATTR = 'data-jqhtml-debug'; // on <html> while enabled - gates light.scss
+const HOST_ATTR = 'data-jqhtml-debug-root'; // the shadow host
+const LIGHT_STYLE_ID = 'jqhtml-debug-light-styles';
+const HIT_CLASS = `${PREFIX}hit`;
+const DEPTH_CLASS = `${PREFIX}depth-`;
+const DEPTH_COLORS = 6; // keep in step with $depth-colors in _tokens.scss
+const LABEL_HEIGHT = 18;
+const READY_STATES = ['created', 'init', 'loaded', 'rendered', 'ready'];
+const state = {
+    enabled: false,
+    host: null,
+    shadow: null,
+    layer: null,
+    modal: null,
+    chain: [],
+    hit_elements: [],
+    modal_component: null,
+};
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+const debug_overlay = {
+    /** Turn the overlay on. Returns false where there is no DOM (SSR). */
+    enable() {
+        if (typeof document === 'undefined' || !document.documentElement)
+            return false;
+        if (state.enabled)
+            return true;
+        install();
+        if (!state.host.isConnected)
+            (document.body || document.documentElement).appendChild(state.host);
+        document.documentElement.setAttribute(ROOT_ATTR, '');
+        document.addEventListener('mouseover', on_mouseover, true);
+        document.addEventListener('mouseout', on_mouseout, true);
+        document.addEventListener('click', on_click, true);
+        document.addEventListener('keydown', on_keydown, true);
+        document.addEventListener('scroll', on_reposition, true);
+        window.addEventListener('resize', on_reposition);
+        state.enabled = true;
+        return true;
+    },
+    /** Turn the overlay off. Styles stay installed but match nothing. */
+    disable() {
+        if (!state.enabled)
+            return;
+        document.removeEventListener('mouseover', on_mouseover, true);
+        document.removeEventListener('mouseout', on_mouseout, true);
+        document.removeEventListener('click', on_click, true);
+        document.removeEventListener('keydown', on_keydown, true);
+        document.removeEventListener('scroll', on_reposition, true);
+        window.removeEventListener('resize', on_reposition);
+        clear_hover();
+        close_modal();
+        document.documentElement.removeAttribute(ROOT_ATTR);
+        if (state.host && state.host.isConnected)
+            state.host.remove();
+        state.enabled = false;
+    },
+    is_enabled() {
+        return state.enabled;
+    },
+    /**
+     * Open the modal for a component, an element inside one, or a jQuery
+     * object, without needing a click. Handy from the console and from tests.
+     */
+    inspect(target) {
+        if (!state.enabled)
+            return false;
+        const component = target instanceof Jqhtml_Component
+            ? target
+            : chain_for(target && target.jquery ? target[0] : target)[0];
+        if (!component)
+            return false;
+        open_modal(component);
+        return true;
+    },
+};
+// ---------------------------------------------------------------------------
+// Installation (once)
+// ---------------------------------------------------------------------------
+function install() {
+    if (state.host)
+        return;
+    if (!document.getElementById(LIGHT_STYLE_ID)) {
+        const style = document.createElement('style');
+        style.id = LIGHT_STYLE_ID;
+        style.textContent = light_css;
+        document.head.appendChild(style);
+    }
+    const host = document.createElement('div');
+    host.setAttribute(HOST_ATTR, '');
+    const shadow = host.attachShadow({ mode: 'open' });
+    const style = document.createElement('style');
+    style.textContent = shadow_css;
+    shadow.appendChild(style);
+    const layer = el('div', 'layer');
+    shadow.appendChild(layer);
+    const modal = el('div', 'modal');
+    shadow.appendChild(modal);
+    state.host = host;
+    state.shadow = shadow;
+    state.layer = layer;
+    state.modal = modal;
+}
+// ---------------------------------------------------------------------------
+// Component chain
+// ---------------------------------------------------------------------------
+/** Components from the one containing `node` outward to the root. */
+function chain_for(node) {
+    const chain = [];
+    let element = node instanceof Element ? node : (node && node.parentElement) || null;
+    while (element) {
+        const owner = element.closest('.Component');
+        if (!owner)
+            break;
+        const component = $(owner).data('_component');
+        if (component instanceof Jqhtml_Component && !component.$.hasClass('_Component_Stopped'))
+            chain.push(component);
+        element = owner.parentElement;
+    }
+    return chain;
+}
+function is_ours(event) {
+    return !!state.host && event.composedPath().includes(state.host);
+}
+// ---------------------------------------------------------------------------
+// Hover
+// ---------------------------------------------------------------------------
+function on_mouseover(event) {
+    if (is_ours(event))
+        return;
+    const chain = chain_for(event.target);
+    if (chain[0] === state.chain[0])
+        return;
+    set_hover(chain);
+}
+function on_mouseout(event) {
+    if (!event.relatedTarget)
+        clear_hover(); // pointer left the document
+}
+function on_reposition() {
+    if (state.chain.length)
+        render_labels();
+}
+function set_hover(chain) {
+    clear_hover();
+    state.chain = chain;
+    chain.forEach((component, depth) => {
+        const element = component.$[0];
+        element.classList.add(HIT_CLASS, DEPTH_CLASS + (depth % DEPTH_COLORS));
+        state.hit_elements.push(element);
     });
+    render_labels();
+}
+function clear_hover() {
+    for (const element of state.hit_elements) {
+        element.classList.remove(HIT_CLASS);
+        for (let i = 0; i < DEPTH_COLORS; i++)
+            element.classList.remove(DEPTH_CLASS + i);
+    }
+    state.hit_elements = [];
+    state.chain = [];
+    if (state.layer)
+        state.layer.textContent = '';
 }
 /**
- * Evaluate an expression in component context
+ * One tab per component in the chain, pinned to the component's top-left
+ * corner and no wider than the component. Outermost first so the innermost
+ * paints on top; tabs that share a corner (a child filling its parent, the
+ * usual case) stack downward instead of hiding each other.
  */
-function evaluate_expression(expression, component, locals = {}) {
-    // Create evaluation context
-    const context = {
-        // Component properties
-        data: component.data,
-        args: component.args,
-        $: component.$,
-        // Component methods
-        $sid: component.$sid.bind(component),
-        // Locals (like $event)
-        ...locals
-    };
-    // Build function that evaluates in context
-    const keys = Object.keys(context);
-    const values = Object.values(context);
-    try {
-        // Use Function constructor for better performance than eval
-        const fn = new Function(...keys, `return (${expression})`);
-        return fn(...values);
+function render_labels() {
+    const layer = state.layer;
+    layer.textContent = '';
+    const taken = new Map();
+    for (let depth = state.chain.length - 1; depth >= 0; depth--) {
+        const component = state.chain[depth];
+        const rect = component.$[0].getBoundingClientRect();
+        if (rect.width <= 0 || rect.height <= 0)
+            continue;
+        const left = Math.max(0, Math.round(rect.left));
+        const top = Math.max(0, Math.round(rect.top));
+        const key = `${left},${top}`;
+        const stacked = taken.get(key) || 0;
+        taken.set(key, stacked + 1);
+        const label = el('div', `label ${PREFIX}depth-${depth % DEPTH_COLORS}`);
+        label.style.left = `${left}px`;
+        label.style.top = `${top + stacked * LABEL_HEIGHT}px`;
+        label.style.maxWidth = `${Math.max(24, Math.round(rect.width))}px`;
+        label.appendChild(el('span', 'label-name', component.component_name()));
+        const args = simple_args(component);
+        if (args)
+            label.appendChild(el('span', 'label-args', args));
+        layer.appendChild(label);
     }
-    catch (error) {
-        console.error(`Invalid expression: ${expression}`, error);
-        return undefined;
+}
+/** `$id=7 $title="Users"` - only strings, numbers and booleans, never internals. */
+function simple_args(component) {
+    const parts = [];
+    for (const [key, value] of Object.entries(component.args || {})) {
+        if (key.startsWith('_'))
+            continue;
+        if (typeof value === 'string')
+            parts.push(`$${key}=${JSON.stringify(truncate(value, 24))}`);
+        else if (typeof value === 'number' || typeof value === 'boolean')
+            parts.push(`$${key}=${value}`);
     }
+    return parts.join(' ');
 }
-/**
- * Evaluate a handler expression (might be method name or inline code)
- */
-function evaluate_handler(expression, component) {
-    // Check if it's a method name on the component
-    if (expression in component && typeof component[expression] === 'function') {
-        return component[expression];
+// ---------------------------------------------------------------------------
+// Click -> modal
+// ---------------------------------------------------------------------------
+function on_click(event) {
+    if (is_ours(event) || event.altKey)
+        return;
+    event.preventDefault();
+    event.stopPropagation();
+    event.stopImmediatePropagation();
+    const chain = chain_for(event.target);
+    if (!chain.length) {
+        close_modal();
+        return;
     }
-    // Otherwise treat as inline code
+    open_modal(chain[0]);
+}
+function on_keydown(event) {
+    if (event.key === 'Escape' && state.modal_component) {
+        close_modal();
+        event.stopPropagation();
+    }
+}
+function close_modal() {
+    if (!state.modal)
+        return;
+    state.modal.classList.remove(`${PREFIX}modal-open`);
+    state.modal.textContent = '';
+    state.modal_component = null;
+}
+function open_modal(component) {
+    const modal = state.modal;
+    modal.textContent = '';
+    state.modal_component = component;
+    const chain = chain_for(component.$[0]);
+    const ancestors = chain.slice(1);
+    const element = component.$[0];
+    // Title bar
+    const title = el('div', 'title');
+    title.appendChild(el('span', 'title-name', `<${component.component_name()}>`));
+    const log = el('button', 'button', 'Log to console');
+    log.addEventListener('click', () => {
+        console.log(`[JQHTML debug] <${component.component_name()}>`, component, element);
+    });
+    title.appendChild(log);
+    const close = el('button', 'button', 'Close');
+    close.addEventListener('click', close_modal);
+    title.appendChild(close);
+    modal.appendChild(title);
+    // Identity
+    const ctor = component.constructor;
+    const hierarchy = ctor.get_class_hierarchy ? ctor.get_class_hierarchy() : [ctor.name];
+    const identity = table();
+    row(identity, 'name', '', component.component_name());
+    row(identity, 'class', '', hierarchy.join(' → '));
+    row(identity, 'element', '', describe_element(element));
+    row(identity, '_cid', '', String(component._cid));
+    row(identity, 'lifecycle', '', READY_STATES[component._ready_state] || String(component._ready_state));
+    const nocache = element.getAttribute('data-nocache');
+    if (nocache)
+        row(identity, 'cache', '', `declined: ${nocache}`);
+    modal.appendChild(section('Identity', identity));
+    // Args / data / state
+    modal.appendChild(section('Args', object_table(component.args)));
+    modal.appendChild(section('Data', object_table(component.data)));
+    modal.appendChild(section('State', object_table(component.state)));
+    // Ancestry
+    const list = el('div', 'list');
+    if (!ancestors.length)
+        list.appendChild(el('div', 'empty', 'none - this is a root component'));
+    for (const ancestor of ancestors) {
+        const link = el('div', 'link');
+        link.appendChild(el('span', 'link-name', `<${ancestor.component_name()}>`));
+        link.appendChild(el('span', 'link-cid', String(ancestor._cid)));
+        link.addEventListener('click', () => open_modal(ancestor));
+        list.appendChild(link);
+    }
+    modal.appendChild(section('Ancestry (DOM, nearest first)', list));
+    // Instantiator - the component whose template wrote this tag. Differs from
+    // the DOM parent for markup written in a slot body or default content.
+    const instantiator = component.instantiator ? component.instantiator() : null;
+    const inst = el('div', 'list');
+    if (instantiator) {
+        const link = el('div', 'link');
+        link.appendChild(el('span', 'link-name', `<${instantiator.component_name()}>`));
+        link.appendChild(el('span', 'link-cid', String(instantiator._cid)));
+        link.addEventListener('click', () => open_modal(instantiator));
+        inst.appendChild(link);
+        if (ancestors[0] && instantiator !== ancestors[0]) {
+            inst.appendChild(el('div', 'note', 'Written in this component\'s template but rendered inside a different parent (slot or default content): handlers and $sid bind here.'));
+        }
+    }
+    else {
+        inst.appendChild(el('div', 'empty', 'none - created directly'));
+    }
+    modal.appendChild(section('Instantiator', inst));
+    modal.classList.add(`${PREFIX}modal-open`);
+}
+// ---------------------------------------------------------------------------
+// DOM helpers (shadow side)
+// ---------------------------------------------------------------------------
+function el(tag, classes, text) {
+    const node = document.createElement(tag);
+    node.className = classes.split(' ').map((c) => (c.startsWith(PREFIX) ? c : PREFIX + c)).join(' ');
+    if (text !== undefined)
+        node.textContent = text;
+    return node;
+}
+function section(heading, body) {
+    const wrap = el('div', 'section');
+    wrap.appendChild(el('div', 'h', heading));
+    wrap.appendChild(body);
+    return wrap;
+}
+function table() {
+    return el('div', 'table');
+}
+function row(t, key, type, value) {
+    t.appendChild(el('span', 'key', key));
+    t.appendChild(el('span', 'type', type));
+    t.appendChild(el('span', 'value', value));
+}
+function object_table(source) {
+    const entries = source && typeof source === 'object' ? Object.entries(source) : [];
+    if (!entries.length)
+        return el('div', 'empty', 'empty');
+    const t = table();
+    for (const [key, value] of entries)
+        row(t, key, type_of(value), preview(value));
+    return t;
+}
+function type_of(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return `array(${value.length})`;
+    if (value instanceof Jqhtml_Component)
+        return 'component';
+    if (value && value.jquery)
+        return `jQuery(${value.length})`;
+    if (typeof value === 'object' && value instanceof Element)
+        return 'element';
+    return typeof value;
+}
+function preview(value) {
+    if (value === undefined)
+        return 'undefined';
+    if (value === null)
+        return 'null';
+    if (typeof value === 'string')
+        return JSON.stringify(truncate(value, 200));
+    if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint')
+        return String(value);
+    if (typeof value === 'function')
+        return `ƒ ${value.name || 'anonymous'}()`;
+    if (value instanceof Jqhtml_Component)
+        return `<${value.component_name()}> ${value._cid}`;
+    if (value.jquery)
+        return value.length ? describe_element(value[0]) : 'empty';
+    if (value instanceof Element)
+        return describe_element(value);
     try {
-        return new Function('$event', `
-      const { data, args, $, emit, $sid } = this;
-      ${expression}
-    `).bind(component);
+        return truncate(JSON.stringify(value), 200);
     }
-    catch (error) {
-        console.error(`Invalid handler: ${expression}`, error);
-        return null;
+    catch {
+        return `{${Object.keys(value).join(', ')}}`;
     }
 }
-/**
- * Helper to escape HTML for safe output
- */
-function escape_html(str) {
-    const div = document.createElement('div');
-    div.textContent = str;
-    return div.innerHTML;
+function describe_element(element) {
+    const id = element.id ? `#${element.id}` : '';
+    const classes = element.classList.length ? `.${Array.from(element.classList).join('.')}` : '';
+    return `${element.tagName.toLowerCase()}${id}${classes}`;
 }
-/**
- * Helper to escape HTML and convert newlines to <br /> tags
- * Used by <%br= %> syntax for displaying user-entered text with line breaks
- */
-function escape_html_nl2br(str) {
-    const div = document.createElement('div');
-    div.textContent = str;
-    // Escape HTML first, then replace newlines with <br />
-    return div.innerHTML.replace(/\n/g, '<br />');
+function truncate(text, max) {
+    return text.length > max ? `${text.slice(0, max - 1)}…` : text;
 }
 
 /**
@@ -5794,16 +6374,20 @@ function init_jquery_plugin(jQuery) {
             catch (error) {
                 console.warn('[JQHTML] Error stopping existing component during replacement:', error);
             }
-            // Remove component classes (any class starting with capital letter, except BEM classes)
+            // Remove component classes (any class starting with a capital letter, or a
+            // component name with the reserved underscore prefix - except BEM classes)
             const classes = element.attr('class');
             if (classes) {
                 const classList = classes.split(/\s+/);
                 const nonComponentClasses = classList.filter((cls) => {
                     // Keep class if:
                     // 1. It's empty
-                    // 2. It doesn't start with a capital letter
+                    // 2. It is neither capital-first nor a component name (see component-name.ts)
                     // 3. It's a BEM-style class (contains __) - these persist across reinitialization
-                    return !cls || cls[0] !== cls[0].toUpperCase() || cls[0] === cls[0].toLowerCase() || cls.includes('__');
+                    if (!cls || cls.includes('__'))
+                        return true;
+                    const capital_first = cls[0] === cls[0].toUpperCase() && cls[0] !== cls[0].toLowerCase();
+                    return !capital_first && !is_component_name(cls);
                 });
                 element.attr('class', nonComponentClasses.join(' '));
             }
@@ -5832,8 +6416,11 @@ function init_jquery_plugin(jQuery) {
             }
         }
         else {
-            // Direct class reference
+            // Direct class reference. The invocation name is the class's own; it is
+            // recorded for component_name() but does not drive the template tag
+            // check below, which is for named (template-backed) invocations.
             ComponentClass = componentOrName;
+            args = { ...args, _component_name: componentOrName.component_name || componentOrName.name };
         }
         // Check if element tag matches expected tag from template
         let targetElement = element;
@@ -6169,7 +6756,7 @@ function init(jQuery, config) {
     }
 }
 // Version - will be replaced during build with actual version from package.json
-const version = '2.3.61';
+const version = '2.3.67';
 // Default export with all functionality
 const jqhtml = {
     // Core
@@ -6200,6 +6787,14 @@ const jqhtml = {
     // Integration configuration - see config.ts
     configure,
     get_config,
+    // Value printers: how <%= %> renders an object (see value-printers.ts).
+    // print_object and dynamic_component_name are called by compiled templates.
+    add_object_printer,
+    print_object,
+    dynamic_component_name,
+    // Component debug overlay: hover outlines + click-to-inspect modal.
+    // jqhtml.debug_overlay.enable() / .disable() / .is_enabled() / .inspect(x)
+    debug_overlay,
     // Debug settings
     debug: {
         enabled: false,
@@ -6305,5 +6900,5 @@ if (typeof window !== 'undefined' && !window.jqhtml) {
     }
 }
 
-export { Jqhtml_Component, LifecycleManager as Jqhtml_LifecycleManager, Jqhtml_Local_Storage, LifecycleManager, Load_Coordinator, applyDebugDelay, boot, clear_preload_data, configure, create_component, jqhtml as default, devWarn, escape_html, escape_html_nl2br, extract_slots, get_captured_data, get_component_class, get_component_names, get_config, 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 };
+export { COMPONENT_NAME_PATTERN, COMPONENT_NAME_RULE, Jqhtml_Component, LifecycleManager as Jqhtml_LifecycleManager, Jqhtml_Local_Storage, LifecycleManager, Load_Coordinator, add_object_printer, applyDebugDelay, boot, clear_preload_data, configure, create_component, debug_overlay, jqhtml as default, devWarn, dynamic_component_name, escape_html, escape_html_nl2br, extract_slots, get_captured_data, get_component_class, get_component_names, get_config, get_object_printers, get_registered_templates, get_template, get_template_by_class, handleComponentError, has_component, init, init_jquery_plugin, isSequentialProcessing, is_component_name, list_components, logDataChange, logDispatch, logInstruction, logLifecycle, print_object, process_instructions, register, register_cache_class, register_component, register_template, render_template, set_preload_data, start_data_capture, stop_data_capture, version };
 //# sourceMappingURL=index.js.map