@jqhtml/core 2.3.50 → 2.3.54

package/dist/index.cjs

@@ -500,6 +500,70 @@ function register(source) {
         'class name mangling, define static component_name or use register_component().');
 }
 
+/**
+ * JQHTML Runtime Configuration
+ *
+ * Integration-level settings supplied by the host application (RSpade, Laravel,
+ * a bundler entry point) when jqhtml is loaded. Distinct from `jqhtml.debug`,
+ * which is a developer's interactive tracing switch: config here describes the
+ * ENVIRONMENT the app is running in, and jqhtml derives behaviour from it.
+ *
+ *   jqhtml.init($, { mode: 'production' });
+ *   jqhtml.configure({ mode: 'development' });
+ *
+ * Default mode is 'development', so an integration that passes nothing keeps
+ * every diagnostic. Production is always opt-in.
+ */
+/** Flags implied by each mode. Add future conventions here, not at call sites. */
+const MODE_DEFAULTS = {
+    development: {
+        warn_uncacheable_args: true,
+        debug_attributes: true,
+    },
+    production: {
+        warn_uncacheable_args: false,
+        debug_attributes: false,
+    },
+};
+let _mode = 'development';
+let _flags = { ...MODE_DEFAULTS.development };
+/**
+ * Apply integration configuration.
+ *
+ * `mode` resets every flag to that mode's defaults; any explicit flag in the
+ * same call then overrides it. Calling with only flags leaves the mode alone.
+ * Repeated calls merge.
+ */
+function configure(config) {
+    if (!config)
+        return;
+    if (config.mode) {
+        if (!MODE_DEFAULTS[config.mode]) {
+            throw new Error(`[JQHTML] Unknown mode '${config.mode}'. Expected 'development' or 'production'.`);
+        }
+        _mode = config.mode;
+        _flags = { ...MODE_DEFAULTS[config.mode] };
+    }
+    if (config.warn_uncacheable_args !== undefined) {
+        _flags.warn_uncacheable_args = !!config.warn_uncacheable_args;
+    }
+    if (config.debug_attributes !== undefined) {
+        _flags.debug_attributes = !!config.debug_attributes;
+    }
+}
+/** Current mode plus every resolved flag. */
+function get_config() {
+    return { mode: _mode, ..._flags };
+}
+/** True when debug-only DOM attributes (data-sid) should be emitted. */
+function debug_attributes_enabled() {
+    return _flags.debug_attributes;
+}
+/** True when uncacheable-args warnings should be printed. */
+function warn_uncacheable_args_enabled() {
+    return _flags.warn_uncacheable_args;
+}
+
 /**
  * JQHTML v2 Instruction Processor
  *
@@ -637,6 +701,9 @@ function process_tag_to_html(instruction, html, tagElements, components, context
     }
     // Add simple string/numeric attributes directly
     for (const [key, value] of Object.entries(attrs)) {
+        if (key === 'data-sid' && !debug_attributes_enabled()) {
+            continue; // debug-only attribute; the scoped id is what $sid() resolves
+        }
         if (!key.startsWith('$') && !key.startsWith('on') && !key.startsWith('@') &&
             !key.startsWith('data-bind-') && !key.startsWith('data-__-on-') &&
             (typeof value === 'string' || typeof value === 'number')) {
@@ -726,7 +793,10 @@ function process_component_to_html(instruction, html, components, context) {
         const baseId = props['data-sid'];
         // The compiled code ALWAYS sets props['id'] with the correct scoped value
         // Just use it directly - it already has the correct parent _cid baked in
-        html.push(` id="${props['id']}" data-sid="${baseId}"`);
+        // data-sid is debug-only: $sid() resolves via the scoped id, never this.
+        html.push(debug_attributes_enabled()
+            ? ` id="${props['id']}" data-sid="${baseId}"`
+            : ` id="${props['id']}"`);
     }
     // Regular id passes through unchanged
     else if (props['id']) {
@@ -868,6 +938,10 @@ function apply_attributes(element, attrs, context) {
             }
         }
         else if (key.startsWith('data-')) {
+            // data-sid is debug-only - suppressed entirely in production
+            if (key === 'data-sid' && !debug_attributes_enabled()) {
+                continue;
+            }
             // Data attributes - go into DOM
             const attrValue = typeof value === "string" ? value.trim() : value;
             element.attr(key, attrValue);
@@ -1230,6 +1304,146 @@ function handleComponentError(component, phase, error) {
 // 9. Performance Budgets - Warn when components exceed size/time limits
 // 10. Accessibility Auditing - Check for missing ARIA attributes
 
+/**
+ * JQHTML Cache Key Serializer
+ *
+ * Produces a deterministic string for a plain-data argument value, so that two
+ * structurally equal objects built on separate renders yield the SAME cache key.
+ * Templates rebuild `{contact_id: 12}` on every render, so identity-based keying
+ * can never match and permanently opts the receiving component out of caching.
+ *
+ * ---------------------------------------------------------------------------
+ * THIS IS NOT `process_for_serialization()` IN local-storage.ts. DO NOT MERGE THEM.
+ *
+ * That serializer stores cache VALUES and deliberately degrades: a function, a
+ * symbol or a circular reference is dropped and serialization continues, because
+ * losing a method while keeping the data is the right trade for a payload.
+ *
+ * For a cache KEY that policy manufactures false hits. Two argument objects that
+ * differ ONLY by a callback would serialize identically, and a component would
+ * render with another component's cached content - strictly worse than not
+ * caching at all. So this serializer DECLINES on the first value it cannot
+ * express exactly. It never drops anything.
+ * ---------------------------------------------------------------------------
+ *
+ * Allow-list, and nothing else: null, undefined, boolean, number, string, Date,
+ * arrays, and plain objects (prototype Object.prototype or null), in any nesting.
+ * Everything else declines with a reason that reaches `data-nocache`.
+ */
+/**
+ * Values larger than this are declined rather than keyed. The supported case is a
+ * handful of key/value pairs or a list of ids - not a payload. Declining loudly
+ * beats spending the budget on a key nobody benefits from.
+ */
+const MAX_KEY_BYTES = 500;
+class Decline extends Error {
+    constructor(reason) {
+        super(reason);
+        this.reason = reason;
+    }
+}
+function push(state, text) {
+    state.size += text.length;
+    if (state.size > MAX_KEY_BYTES) {
+        throw new Decline('too-large');
+    }
+    return text;
+}
+/**
+ * Length-prefix strings so that no combination of separators can make two
+ * different structures produce the same text.
+ */
+function encode_string(state, prefix, value) {
+    return push(state, `${prefix}${value.length}:${value}`);
+}
+function walk(value, state) {
+    // --- primitives, each tagged so shapes cannot collide ---
+    if (value === null)
+        return push(state, 'n');
+    if (value === undefined)
+        return push(state, 'u');
+    const type = typeof value;
+    if (type === 'boolean')
+        return push(state, value ? 'b1' : 'b0');
+    if (type === 'number')
+        return push(state, `d${String(value)}`);
+    if (type === 'string')
+        return encode_string(state, 's', value);
+    if (type === 'function')
+        throw new Decline('function');
+    if (type === 'symbol')
+        throw new Decline('symbol');
+    if (type === 'bigint')
+        throw new Decline('bigint');
+    if (type !== 'object')
+        throw new Decline(type);
+    // --- objects: reject the impostors before treating anything as data ---
+    if (typeof value.nodeType === 'number')
+        throw new Decline('dom-node');
+    if (value.jquery)
+        throw new Decline('jquery');
+    if (state.seen.has(value))
+        throw new Decline('circular');
+    state.seen.add(value);
+    try {
+        if (value instanceof Date) {
+            const time = value.getTime();
+            if (Number.isNaN(time))
+                throw new Decline('invalid-date');
+            return push(state, `t${value.toISOString()}`);
+        }
+        if (Array.isArray(value)) {
+            // Order is meaningful - never sorted.
+            const parts = [];
+            push(state, 'a[');
+            for (let i = 0; i < value.length; i++) {
+                parts.push(walk(value[i], state));
+            }
+            push(state, ']');
+            return `a[${parts.join(',')}]`;
+        }
+        // Plain object ONLY. A class instance, Map, Set, RegExp, Error, etc. is
+        // declined: two different classes with identical fields would otherwise
+        // serialize the same and collide.
+        const proto = Object.getPrototypeOf(value);
+        if (proto !== Object.prototype && proto !== null) {
+            throw new Decline('non-plain-object');
+        }
+        // Recursive key sort - the existing top-level sort is not enough for nesting.
+        const keys = Object.keys(value).sort();
+        const parts = [];
+        push(state, 'o{');
+        for (const key of keys) {
+            const encoded_key = encode_string(state, 'k', key);
+            parts.push(`${encoded_key}=${walk(value[key], state)}`);
+        }
+        push(state, '}');
+        return `o{${parts.join(',')}}`;
+    }
+    finally {
+        state.seen.delete(value);
+    }
+}
+/**
+ * Serialize a value for use in a cache key.
+ *
+ * @returns `{ok: true, text}` when the value is exactly expressible, or
+ *          `{ok: false, reason}` naming why it is not. Never throws.
+ */
+function serialize_for_cache_key(value) {
+    const state = { seen: new WeakSet(), size: 0 };
+    try {
+        return { ok: true, text: walk(value, state) };
+    }
+    catch (error) {
+        if (error instanceof Decline) {
+            return { ok: false, reason: error.reason };
+        }
+        // A throwing getter or exotic proxy trap - decline rather than guess.
+        return { ok: false, reason: 'unserializable' };
+    }
+}
+
 /**
  * Load Coordinator - Request deduplication for component on_load() calls
  *
@@ -1266,8 +1480,9 @@ class Load_Coordinator {
      * - key: Cache key string, or null if uncacheable
      * - uncacheable_property: Name of first property that prevented caching (for debugging)
      */
-    static generate_invocation_key(component_name, args) {
+    static generate_invocation_key(component_name, args, options = {}) {
         let uncacheable_property;
+        let uncacheable_reason;
         // Filter out internal properties (starting with _) and serialize args
         const serializable_args = {};
         for (const key of Object.keys(args).sort()) {
@@ -1306,21 +1521,37 @@ class Load_Coordinator {
                         // Method threw error - treat as uncacheable
                         if (!uncacheable_property) {
                             uncacheable_property = key;
+                            uncacheable_reason = 'cache-id-threw';
                         }
-                        return { key: null, uncacheable_property };
+                        return { key: null, uncacheable_property, uncacheable_reason };
+                    }
+                }
+                // No author-supplied id. The cache may fall back to keying by
+                // deterministic content; deduplication deliberately may not.
+                if (options.allow_content_serialization) {
+                    const serialized = serialize_for_cache_key(value);
+                    if (serialized.ok) {
+                        serializable_args[key] = `__JQHTML_CONTENT__:${serialized.text}`;
+                        continue;
                     }
+                    if (!uncacheable_property) {
+                        uncacheable_property = key;
+                        uncacheable_reason = serialized.reason;
+                    }
+                    return { key: null, uncacheable_property, uncacheable_reason };
                 }
-                // No cache ID available - this property is uncacheable
                 if (!uncacheable_property) {
                     uncacheable_property = key;
+                    uncacheable_reason = value_type === 'function' ? 'function' : 'object';
                 }
-                return { key: null, uncacheable_property };
+                return { key: null, uncacheable_property, uncacheable_reason };
             }
             // Unknown type (symbol, bigint, etc.) - uncacheable
             if (!uncacheable_property) {
                 uncacheable_property = key;
+                uncacheable_reason = value_type;
             }
-            return { key: null, uncacheable_property };
+            return { key: null, uncacheable_property, uncacheable_reason };
         }
         // Try to serialize - if it fails (shouldn't happen now, but safety net), return null
         try {
@@ -1338,6 +1569,12 @@ class Load_Coordinator {
      */
     static should_execute_on_load(component) {
         const { key } = this.generate_invocation_key(component.component_name(), component.args);
+        // No identity means no coordination. Without this, every un-keyable component
+        // would share the single `null` registry entry and adopt an unrelated
+        // component's data - the worst failure this system can produce.
+        if (key === null) {
+            return true;
+        }
         const entry = this._registry.get(key);
         if (!entry) {
             // No existing request - this component becomes the leader
@@ -1360,6 +1597,10 @@ class Load_Coordinator {
      */
     static register_leader(component, on_load_promise) {
         const { key } = this.generate_invocation_key(component.component_name(), component.args);
+        // Un-keyable component: run alone, register nothing. See should_execute_on_load().
+        if (key === null) {
+            return () => { };
+        }
         // Create a promise that we control - it resolves when complete_coordination is called
         let resolve_promise;
         const coordination_promise = new Promise((resolve) => {
@@ -1581,6 +1822,8 @@ Load_Coordinator._registry = new Map();
 // Registry mapping class names to constructors
 const class_registry = Object.create(null);
 // Markers for serialized class instances (unique to avoid collisions with user data)
+// Replaced at build time by rollup (see rollup.config.js).
+const CORE_VERSION = '2.3.54';
 const CLASS_MARKER = '__jqhtml_class__';
 const PROPS_MARKER = '__jqhtml_props__';
 /**
@@ -1870,6 +2113,12 @@ class Jqhtml_Local_Storage {
      */
     static set_cache_key(cache_key, cache_mode = 'data') {
         this._cache_key = cache_key;
+        // Key SHAPE is a function of the library (see cache-key-serializer.ts), so an
+        // upgrade that changes it must invalidate everything persisted under the old shape.
+        // Version the SCOPE MARKER rather than the key itself: _validate_scope() already
+        // clears every jqhtml key when this value changes, and leaving the per-entry key
+        // format alone keeps stored keys readable and avoids repeating the version in each.
+        this._scope_marker = `${CORE_VERSION}::${cache_key}`;
         this._cache_mode = cache_mode;
         this._init();
     }
@@ -1939,21 +2188,21 @@ class Jqhtml_Local_Storage {
         }
         try {
             const stored_key = localStorage.getItem('_jqhtml_cache_key');
-            // If cache key exists and has changed, clear only JQHTML keys
-            if (stored_key !== null && stored_key !== this._cache_key) {
-                console.log('[JQHTML Local Storage] Cache key changed, clearing JQHTML keys:', {
+            // If the scope marker (core version + developer key) changed, clear only JQHTML keys
+            if (stored_key !== null && stored_key !== this._scope_marker) {
+                console.log('[JQHTML Local Storage] Cache scope changed, clearing JQHTML keys:', {
                     old_key: stored_key,
-                    new_key: this._cache_key,
+                    new_key: this._scope_marker,
                 });
                 this._clear_jqhtml_keys();
-                localStorage.setItem('_jqhtml_cache_key', this._cache_key);
+                localStorage.setItem('_jqhtml_cache_key', this._scope_marker);
             }
             else if (stored_key === null) {
                 // First time JQHTML is using this storage - just set the key, don't clear
-                console.log('[JQHTML Local Storage] Initializing cache key (first use):', {
-                    new_key: this._cache_key,
+                console.log('[JQHTML Local Storage] Initializing cache scope (first use):', {
+                    new_key: this._scope_marker,
                 });
-                localStorage.setItem('_jqhtml_cache_key', this._cache_key);
+                localStorage.setItem('_jqhtml_cache_key', this._scope_marker);
             }
         }
         catch (e) {
@@ -2185,6 +2434,8 @@ class Jqhtml_Local_Storage {
     }
 }
 Jqhtml_Local_Storage._cache_key = null;
+/** Versioned scope identity - compared in _validate_scope() to clear on a core upgrade. */
+Jqhtml_Local_Storage._scope_marker = null;
 Jqhtml_Local_Storage._cache_mode = 'data';
 Jqhtml_Local_Storage._storage_available = null;
 Jqhtml_Local_Storage._initialized = false;
@@ -2282,10 +2533,15 @@ function event_once(component, event_name, callback) {
 function event_trigger(component, event_name, data) {
     // Mark this event as occurred and store the data for late subscribers
     component._lifecycle_states.set(event_name, data);
-    // Fire all registered callbacks for this event
+    // Fire all registered callbacks for this event.
+    // Iterate a SNAPSHOT: handlers registered via once() splice themselves out of the
+    // live array while it is being iterated, which would shift later handlers into
+    // already-visited slots and skip them. The snapshot also means a handler
+    // registered during dispatch does not fire in this dispatch (event_on's sticky
+    // immediate-fire already delivered it).
     const callbacks = component._lifecycle_callbacks.get(event_name);
     if (callbacks) {
-        for (const callback of callbacks) {
+        for (const callback of [...callbacks]) {
             try {
                 callback.bind(component)(component, data);
             }
@@ -2570,12 +2826,73 @@ function generate_cache_key(component) {
             return { cache_key: `${component.component_name()}::${String(custom_cache_id)}` };
         }
         catch (error) {
-            return { cache_key: null, uncacheable_property: 'cache_id()' };
+            return { cache_key: null, uncacheable_property: 'cache_id()', uncacheable_reason: 'cache-id-threw' };
         }
     }
-    // Use standard args-based cache key generation
-    const result = Load_Coordinator.generate_invocation_key(component.component_name(), component.args);
-    return { cache_key: result.key, uncacheable_property: result.uncacheable_property };
+    // Standard args-based key. The CACHE opts into content serialization for plain-data
+    // object args; deduplication does not - see InvocationKeyOptions for why.
+    const result = Load_Coordinator.generate_invocation_key(component.component_name(), component.args, { allow_content_serialization: true });
+    return {
+        cache_key: result.key,
+        uncacheable_property: result.uncacheable_property,
+        uncacheable_reason: result.uncacheable_reason,
+    };
+}
+// One warning per component+property. A list of 50 rows must not print 50 warnings.
+const _warned_uncacheable = new Set();
+/**
+ * Development warning: this component fetches data but cannot be cached, because
+ * its args do not reduce to a stable key and it defines no cache_id() to say what
+ * its identity is. Nothing is broken - the component works - but it silently opts
+ * out of cache reuse and of load deduplication.
+ *
+ * Controlled by the `warn_uncacheable_args` integration flag (see config.ts).
+ */
+function warn_uncacheable_component(component, uncacheable_property, uncacheable_reason) {
+    if (!warn_uncacheable_args_enabled())
+        return;
+    let name = 'unknown';
+    try {
+        name = component.component_name();
+    }
+    catch { /* name unavailable */ }
+    const dedupe_key = `${name}::${uncacheable_property || '?'}::${uncacheable_reason || '?'}`;
+    if (_warned_uncacheable.has(dedupe_key))
+        return;
+    _warned_uncacheable.add(dedupe_key);
+    // cache_id() exists but threw - a different problem with a different fix
+    if (uncacheable_property === 'cache_id()' || uncacheable_reason === 'cache-id-threw') {
+        console.warn(`[JQHTML] <${name}> defines cache_id() but it threw, so this component is not cached ` +
+            `and its loads are not deduplicated. Fix cache_id() so it returns a stable string.`, { component: name, cid: component._cid });
+        return;
+    }
+    const REASONS = {
+        'function': 'it contains a function - a callback is real identity that content cannot express',
+        'symbol': 'it contains a symbol',
+        'bigint': 'it contains a bigint',
+        'dom-node': 'it contains a DOM node',
+        'jquery': 'it contains a jQuery object',
+        'circular': 'it contains a circular reference',
+        'non-plain-object': 'it contains a class instance, Map, Set or similar - only plain objects and arrays can be keyed by content',
+        'too-large': 'it serializes to more than 500 bytes - args are meant to identify data, not carry it',
+        'invalid-date': 'it contains an invalid Date',
+    };
+    const why = REASONS[uncacheable_reason || ''] || 'it cannot be serialized deterministically';
+    console.warn(`[JQHTML] <${name}> cannot be cached: arg $${uncacheable_property} is not keyable because ` +
+        `${why}.\n` +
+        `  The component works, but it will not be restored from cache when reused.\n` +
+        `  Fix: define cache_id() on the component to state its identity explicitly, e.g.\n` +
+        `    cache_id() { return \`${name.toLowerCase()}_\${this.args.some_id}\`; }\n` +
+        `  Or pass plain data (objects/arrays of primitives are keyed automatically) instead of ` +
+        `$${uncacheable_property}.\n` +
+        `  Find it in DevTools with the selector ` +
+        `[data-nocache="${uncacheable_property}:${uncacheable_reason || ''}"].`, {
+        component: name,
+        cid: component._cid,
+        uncacheable_arg: uncacheable_property,
+        reason: uncacheable_reason,
+        all_args: component.args ? Object.keys(component.args) : [],
+    });
 }
 /**
  * Read cache during create() phase.
@@ -2584,13 +2901,15 @@ function generate_cache_key(component) {
  * @param component - The component instance
  */
 function read_cache_in_create(component) {
-    const { cache_key, uncacheable_property } = generate_cache_key(component);
+    const { cache_key, uncacheable_property, uncacheable_reason } = generate_cache_key(component);
     // If cache_key is null, caching disabled
     if (cache_key === null) {
         // Set data-nocache attribute for debugging
         if (uncacheable_property) {
-            component.$.attr('data-nocache', uncacheable_property);
+            // "<arg>:<reason>" - a bare property name left authors reverse-engineering why
+            component.$.attr('data-nocache', uncacheable_reason ? `${uncacheable_property}:${uncacheable_reason}` : uncacheable_property);
         }
+        warn_uncacheable_component(component, uncacheable_property, uncacheable_reason);
         if (window.jqhtml?.debug?.verbose) {
             console.log(`[Cache] Component ${component._cid} (${component.component_name()}) has non-serializable args - caching disabled`, { uncacheable_property });
         }
@@ -3004,6 +3323,75 @@ 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
  *
@@ -3198,6 +3586,21 @@ class Jqhtml_Component {
         // Call original directly - no flag needed since we bypass the wrapper
         return impl.call(this);
     }
+    /**
+     * Fire on_viewport_resize() with the current viewport width.
+     * Called after every on_render() and on_ready(); the debounced window
+     * listener in viewport.ts drives it from then on. Errors are isolated so a
+     * bad handler cannot break the lifecycle.
+     * @private
+     */
+    _fire_viewport_resize() {
+        try {
+            this.on_viewport_resize(get_viewport_width());
+        }
+        catch (error) {
+            console.error(`[JQHTML] Error in on_viewport_resize() for ${this.component_name()}:`, error);
+        }
+    }
     /**
      * Check if on_load() is overridden in a subclass
      * Used to skip the load phase entirely for components that don't fetch data
@@ -3282,6 +3685,7 @@ class Jqhtml_Component {
                     console.warn(`[JQHTML] Component "${this.component_name()}" returned a Promise from on_render(). ` +
                         `on_render() must be synchronous code. Remove 'async' from the function declaration.`);
                 }
+                this._fire_viewport_resize();
             }
             // Emit lifecycle event
             this.trigger('render');
@@ -3473,6 +3877,7 @@ class Jqhtml_Component {
                 console.warn(`[JQHTML] Component "${this.component_name()}" returned a Promise from on_render(). ` +
                     `on_render() must be synchronous code. Remove 'async' from the function declaration.`);
             }
+            this._fire_viewport_resize();
         }
         // Emit lifecycle event
         this.trigger('render');
@@ -3547,6 +3952,7 @@ class Jqhtml_Component {
             }
             // Call on_ready hook with authorization
             await this._call_lifecycle('on_ready');
+            this._fire_viewport_resize();
             // Trigger ready event
             this.trigger('ready');
         });
@@ -3773,9 +4179,18 @@ class Jqhtml_Component {
             }
             return;
         }
-        // Generate cache key (needed for both preload check and load deduplication)
+        // TWO identities, deliberately computed separately.
+        //
+        // cache_key  - may key a plain-data object arg by deterministic CONTENT, and may come
+        //              from the author's cache_id(). A wrong key here is corrected by
+        //              stale-while-revalidate.
+        // dedup_key  - args only, no content serialization, no cache_id(). A deduplicated
+        //              follower never runs on_load() and adopts the leader's data with NO
+        //              revalidation, so a wrong key here is permanently wrong data. Redundant
+        //              concurrent requests are the cheaper failure.
         let cache_key = null;
         let uncacheable_property;
+        let uncacheable_reason;
         if (typeof this.cache_id === 'function') {
             try {
                 const custom_cache_id = this.cache_id();
@@ -3784,14 +4199,16 @@ class Jqhtml_Component {
             catch (error) {
                 // cache_id() threw error - disable caching
                 uncacheable_property = 'cache_id()';
+                uncacheable_reason = 'cache-id-threw';
             }
         }
         else {
-            // Use standard args-based cache key generation
-            const result = Load_Coordinator.generate_invocation_key(this.component_name(), this.args);
+            const result = Load_Coordinator.generate_invocation_key(this.component_name(), this.args, { allow_content_serialization: true });
             cache_key = result.key;
             uncacheable_property = result.uncacheable_property;
+            uncacheable_reason = result.uncacheable_reason;
         }
+        const dedup_key = Load_Coordinator.generate_invocation_key(this.component_name(), this.args).key;
         // SSR preload check: if preloaded data exists for this component+args, use it
         if (cache_key !== null && has_preload_data()) {
             const preloaded_data = consume_preload_data(cache_key);
@@ -3807,23 +4224,24 @@ class Jqhtml_Component {
         }
         // Store cache key for later use
         this._cache_key = cache_key;
-        // If cache_key is null, args are not serializable - skip load deduplication and caching
-        if (cache_key === null) {
-            // Set data-nocache attribute for debugging (shows which property prevented caching)
-            if (uncacheable_property) {
-                this.$.attr('data-nocache', uncacheable_property);
+        // Caching disabled - mark the element with the offending arg AND why
+        if (cache_key === null && uncacheable_property) {
+            this.$.attr('data-nocache', uncacheable_reason ? `${uncacheable_property}:${uncacheable_reason}` : uncacheable_property);
+            if (window.jqhtml?.debug?.verbose) {
+                console.log(`[Cache] Component ${this._cid} (${this.component_name()}) has non-keyable args - caching disabled`, { uncacheable_property, uncacheable_reason });
             }
+        }
+        // Store "before" snapshot for comparison after on_load()
+        const data_before_load = JSON.stringify(this.data);
+        // No dedup identity - run on_load() alone rather than risk sharing a load
+        if (dedup_key === null) {
             if (window.jqhtml?.debug?.verbose) {
-                console.log(`[Cache] Component ${this._cid} (${this.component_name()}) has non-serializable args - load deduplication and caching disabled`, { uncacheable_property });
+                console.log(`[Load Deduplication] Component ${this._cid} (${this.component_name()}) has no dedup key - loading independently`);
             }
-            // Execute on_load on detached proxy without deduplication
             const { data: result_data } = await this._execute_on_load_detached();
-            // Apply result via sequential queue
-            await this._apply_load_result(result_data, null);
+            await this._apply_load_result(result_data, data_before_load);
             return;
         }
-        // Store "before" snapshot for comparison after on_load()
-        const data_before_load = JSON.stringify(this.data);
         // Check if this component should execute on_load() or wait for existing request
         const should_execute = Load_Coordinator.should_execute_on_load(this);
         if (!should_execute) {
@@ -3972,6 +4390,7 @@ class Jqhtml_Component {
         // Wait for all children to reach ready state (bottom-up execution)
         await this._wait_for_children_ready();
         await this._call_lifecycle('on_ready');
+        this._fire_viewport_resize();
         this._ready_state = 4;
         this._update_debug_attrs();
         this._log_lifecycle('ready', 'complete');
@@ -4216,6 +4635,7 @@ class Jqhtml_Component {
             this._render();
             await this._wait_for_children_ready();
             await this._call_lifecycle('on_ready');
+            this._fire_viewport_resize();
             this.trigger('ready');
             this._log_lifecycle('reload', 'complete (no on_load)');
             return;
@@ -4290,6 +4710,7 @@ class Jqhtml_Component {
         if (rendered_from_cache || should_render) {
             await this._wait_for_children_ready();
             await this._call_lifecycle('on_ready');
+            this._fire_viewport_resize();
             // Trigger ready event so parent callbacks fire on subsequent reloads
             this.trigger('ready');
         }
@@ -4372,6 +4793,16 @@ class Jqhtml_Component {
     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
@@ -4746,8 +5177,13 @@ class Jqhtml_Component {
         }
     }
     _set_attributes() {
-        // Always set data-cid
-        this.$.attr('data-cid', this._cid);
+        // 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());
@@ -5686,6 +6122,9 @@ function init_jquery_plugin(jQuery) {
         PatchedInit.prototype = jQuery.fn;
         jQuery.fn.init = PatchedInit;
     }
+    // Install the single debounced window resize listener that drives
+    // on_viewport_resize() on every component. Idempotent.
+    init_viewport_resize(jQuery);
 }
 // Try to auto-initialize if global jQuery exists
 if (typeof window !== 'undefined' && window.jQuery) {
@@ -5699,7 +6138,9 @@ if (typeof window !== 'undefined' && window.jQuery) {
  */
 // Core exports
 // Main initialization function
-function init(jQuery) {
+function init(jQuery, config) {
+    // Integration config first - it governs behaviour during the very first render
+    configure(config);
     // If jQuery is provided, initialize the plugin
     if (jQuery) {
         init_jquery_plugin(jQuery);
@@ -5713,7 +6154,7 @@ function init(jQuery) {
     }
 }
 // Version - will be replaced during build with actual version from package.json
-const version = '2.3.50';
+const version = '2.3.54';
 // Default export with all functionality
 const jqhtml = {
     // Core
@@ -5741,6 +6182,9 @@ const jqhtml = {
     __version: version,
     // state facts
     tombstone: 'pepperoni and cheese',
+    // Integration configuration - see config.ts
+    configure,
+    get_config,
     // Debug settings
     debug: {
         enabled: false,
@@ -5854,6 +6298,7 @@ exports.Load_Coordinator = Load_Coordinator;
 exports.applyDebugDelay = applyDebugDelay;
 exports.boot = boot;
 exports.clear_preload_data = clear_preload_data;
+exports.configure = configure;
 exports.create_component = create_component;
 exports.default = jqhtml;
 exports.devWarn = devWarn;
@@ -5863,6 +6308,7 @@ exports.extract_slots = extract_slots;
 exports.get_captured_data = get_captured_data;
 exports.get_component_class = get_component_class;
 exports.get_component_names = get_component_names;
+exports.get_config = get_config;
 exports.get_registered_templates = get_registered_templates;
 exports.get_template = get_template;
 exports.get_template_by_class = get_template_by_class;