zero-query 1.2.0 → 1.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zero-query",
-  "version": "1.2.0",
+  "version": "1.2.3",
   "description": "Lightweight modern frontend library - jQuery-like selectors, reactive components, SPA router, and state management with zero dependencies.",
   "main": "index.js",
   "types": "index.d.ts",
@@ -35,7 +35,8 @@
     "lint:fix": "eslint . --fix",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:ssr": "node tests/test-ssr.js"
+    "test:ssr": "node tests/test-ssr.js",
+    "bench": "vitest bench --run"
   },
   "keywords": [
     "dom",

package/src/component.js

@@ -190,6 +190,10 @@ class Component {
     this._updateQueued = false;
     this._listeners = [];
     this._watchCleanups = [];
+    // Elements that have scheduled debounce/throttle timers under this
+    // component instance. Tracked so destroy() can clear them even if the
+    // element is detached from the subtree before teardown.
+    this._timerEls = new Set();
 
     // Refs map
     this.refs = {};
@@ -214,15 +218,21 @@ class Component {
     if (definition.props && typeof definition.props === 'object' && !Array.isArray(definition.props)) {
       // Reactive props with type coercion and defaults
       this.props = this._resolveReactiveProps(definition.props, props);
-      // MutationObserver to re-read props when parent re-renders and changes attributes
+      // MutationObserver to re-read props when parent re-renders and changes attributes.
+      // attributeFilter limits callbacks to the declared prop names (plus their
+      // dynamic `:name` aliases) — unrelated attribute churn no longer fires.
+      const propNames = Object.keys(definition.props);
+      const filter = [];
+      for (const n of propNames) {
+        filter.push(n.toLowerCase());
+        filter.push(':' + n.toLowerCase());
+      }
       this._propObserver = new MutationObserver((mutations) => {
         if (this._destroyed) return;
         let changed = false;
         for (const mut of mutations) {
           if (mut.type === 'attributes') {
             const attrName = mut.attributeName;
-            // Skip internal attributes
-            if (attrName.startsWith('z-') || attrName.startsWith('@') || attrName.startsWith(':') || attrName.startsWith('data-zq')) continue;
             // Check if this is a defined prop (attribute names are lowercase)
             const propName = attrName.startsWith(':') ? attrName.slice(1) : attrName;
             if (propName in definition.props) {
@@ -235,7 +245,7 @@ class Component {
           this._scheduleUpdate();
         }
       });
-      this._propObserver.observe(el, { attributes: true });
+      this._propObserver.observe(el, { attributes: true, attributeFilter: filter });
     } else {
       // Legacy: frozen props from parent
       this.props = Object.freeze({ ...props });
@@ -517,44 +527,60 @@ class Component {
 
     // Apply scoped styles on first render
     if (!this._mounted && combinedStyles) {
-      const scopeAttr = `z-s${this._uid}`;
+      const def = this._def;
+      // Use a stable per-definition scope attr so all instances share one
+      // <style> tag (ref-counted). Anonymous defs fall back to per-instance
+      // scoping for safety.
+      let scopeAttr = def._scopeAttr;
+      if (!scopeAttr) {
+        scopeAttr = def._name ? `z-s-${def._name}` : `z-s${this._uid}`;
+        def._scopeAttr = scopeAttr;
+      }
       this._el.setAttribute(scopeAttr, '');
-      let noScopeDepth = 0;   // brace depth at which a no-scope @-rule started (0 = none active)
-      let braceDepth = 0;     // overall brace depth
-      const scoped = combinedStyles.replace(/([^{}]+)\{|\}/g, (match, selector) => {
-        if (match === '}') {
-          if (noScopeDepth > 0 && braceDepth <= noScopeDepth) noScopeDepth = 0;
-          braceDepth--;
-          return match;
-        }
-        braceDepth++;
-        const trimmed = selector.trim();
-        // Don't scope @-rules themselves
-        if (trimmed.startsWith('@')) {
-          // @keyframes and @font-face contain non-selector content - skip scoping inside them
-          if (/^@(keyframes|font-face)\b/.test(trimmed)) {
-            noScopeDepth = braceDepth;
+      this._scopeAttr = scopeAttr;
+
+      if (def._styleEl && def._styleEl.isConnected) {
+        // Already injected by a previous instance — just bump refcount.
+        def._styleRefCount = (def._styleRefCount || 0) + 1;
+      } else {
+        let noScopeDepth = 0;   // brace depth at which a no-scope @-rule started (0 = none active)
+        let braceDepth = 0;     // overall brace depth
+        const scoped = combinedStyles.replace(/([^{}]+)\{|\}/g, (match, selector) => {
+          if (match === '}') {
+            if (noScopeDepth > 0 && braceDepth <= noScopeDepth) noScopeDepth = 0;
+            braceDepth--;
+            return match;
+          }
+          braceDepth++;
+          const trimmed = selector.trim();
+          // Don't scope @-rules themselves
+          if (trimmed.startsWith('@')) {
+            // @keyframes and @font-face contain non-selector content - skip scoping inside them
+            if (/^@(keyframes|font-face)\b/.test(trimmed)) {
+              noScopeDepth = braceDepth;
+            }
+            return match;
+          }
+          // Inside @keyframes or @font-face - don't scope inner rules
+          if (noScopeDepth > 0 && braceDepth > noScopeDepth) {
+            return match;
+          }
+          return selector.split(',').map(s => `[${scopeAttr}] ${s.trim()}`).join(', ') + ' {';
+        });
+        const styleEl = document.createElement('style');
+        styleEl.textContent = scoped;
+        styleEl.setAttribute('data-zq-component', def._name || '');
+        styleEl.setAttribute('data-zq-scope', scopeAttr);
+        if (def._resolvedStyleUrls) {
+          styleEl.setAttribute('data-zq-style-urls', def._resolvedStyleUrls.join(' '));
+          if (def.styles) {
+            styleEl.setAttribute('data-zq-inline', def.styles);
           }
-          return match;
-        }
-        // Inside @keyframes or @font-face - don't scope inner rules
-        if (noScopeDepth > 0 && braceDepth > noScopeDepth) {
-          return match;
-        }
-        return selector.split(',').map(s => `[${scopeAttr}] ${s.trim()}`).join(', ') + ' {';
-      });
-      const styleEl = document.createElement('style');
-      styleEl.textContent = scoped;
-      styleEl.setAttribute('data-zq-component', this._def._name || '');
-      styleEl.setAttribute('data-zq-scope', scopeAttr);
-      if (this._def._resolvedStyleUrls) {
-        styleEl.setAttribute('data-zq-style-urls', this._def._resolvedStyleUrls.join(' '));
-        if (this._def.styles) {
-          styleEl.setAttribute('data-zq-inline', this._def.styles);
         }
+        document.head.appendChild(styleEl);
+        def._styleEl = styleEl;
+        def._styleRefCount = 1;
       }
-      document.head.appendChild(styleEl);
-      this._styleEl = styleEl;
     }
 
     // -- Focus preservation ----------------------------------------
@@ -763,7 +789,7 @@ class Component {
         });
 
         let stoppedAt = null; // Track elements that called .stop
-        for (const { selector, methodExpr, modifiers, el, matched } of hits) {
+        for (const { methodExpr, modifiers, el, matched } of hits) {
 
           // In delegated events, .stop should prevent ancestor bindings from
           // firing - stopPropagation alone only stops real DOM bubbling.
@@ -857,6 +883,7 @@ class Component {
             clearTimeout(timers[event]);
             timers[event] = setTimeout(() => invoke(e), ms);
             _debounceTimers.set(el, timers);
+            this._timerEls.add(el);
             continue;
           }
 
@@ -869,6 +896,7 @@ class Component {
             invoke(e);
             timers[event] = setTimeout(() => { timers[event] = null; }, ms);
             _throttleTimers.set(el, timers);
+            this._timerEls.add(el);
             continue;
           }
 
@@ -951,10 +979,15 @@ class Component {
         : isEditable ? 'input' : 'input';
 
       // -- Handler: read DOM → write to reactive state -------------
-      // Skip if already bound (morph preserves existing elements,
-      // so re-binding would stack duplicate listeners)
-      if (el._zqModelBound) return;
-      el._zqModelBound = true;
+      // Remove any previously-bound z-model listener on this element so
+      // re-runs (re-render, keyed reconciliation, modifier change) replace
+      // instead of stacking. A boolean "already bound" flag is not enough:
+      // if the bound state key / modifiers ever change, the stale handler
+      // would keep writing to the old key.
+      if (el._zqModelUnbind) {
+        try { el._zqModelUnbind(); } catch { /* ignore */ }
+        el._zqModelUnbind = null;
+      }
 
       const handler = () => {
         let val;
@@ -976,12 +1009,18 @@ class Component {
 
       if (hasDebounce) {
         let timer = null;
-        el.addEventListener(event, () => {
+        const debounced = () => {
           clearTimeout(timer);
           timer = setTimeout(handler, debounceMs);
-        });
+        };
+        el.addEventListener(event, debounced);
+        el._zqModelUnbind = () => {
+          el.removeEventListener(event, debounced);
+          clearTimeout(timer);
+        };
       } else {
         el.addEventListener(event, handler);
+        el._zqModelUnbind = () => el.removeEventListener(event, handler);
       }
     });
   }
@@ -1206,19 +1245,20 @@ class Component {
       }
     });
 
-    // -- z-bind:attr / :attr (dynamic attribute binding) -----------
-    // Use TreeWalker instead of querySelectorAll('*') - avoids
-    // creating a flat array of every single descendant element.
-    // TreeWalker visits nodes lazily; FILTER_REJECT skips z-pre subtrees
-    // at the walker level (faster than per-node closest('[z-pre]') checks).
+    // -- Single TreeWalker pass for z-bind/:attr, z-class, z-style,
+    //    z-stream, z-cloak. One walk amortises the cost across five
+    //    directives that used to issue separate querySelectorAll calls.
+    //    FILTER_REJECT on z-pre subtrees skips per-node closest() checks.
     const walker = document.createTreeWalker(this._el, NodeFilter.SHOW_ELEMENT, {
       acceptNode(n) {
         return n.hasAttribute('z-pre') ? NodeFilter.FILTER_REJECT : NodeFilter.FILTER_ACCEPT;
       }
     });
+    const hasMediaStream = typeof MediaStream !== 'undefined';
     let node;
     while ((node = walker.nextNode())) {
       const attrs = node.attributes;
+      // z-bind:* / :* — iterate attrs once (reverse to allow remove)
       for (let i = attrs.length - 1; i >= 0; i--) {
         const attr = attrs[i];
         let attrName;
@@ -1229,71 +1269,67 @@ class Component {
         const val = this._evalExpr(attr.value);
         node.removeAttribute(attr.name);
         if (val === false || val === null || val === undefined) {
-          node.removeAttribute(attrName);
+          node.toggleAttribute(attrName, false);
         } else if (val === true) {
-          node.setAttribute(attrName, '');
+          node.toggleAttribute(attrName, true);
         } else {
           node.setAttribute(attrName, String(val));
         }
       }
-    }
 
-    // -- z-class (dynamic class binding) ---------------------------
-    this._el.querySelectorAll('[z-class]').forEach(el => {
-      if (el.closest('[z-pre]')) return;
-      const val = this._evalExpr(el.getAttribute('z-class'));
-      if (typeof val === 'string') {
-        val.split(/\s+/).filter(Boolean).forEach(c => el.classList.add(c));
-      } else if (Array.isArray(val)) {
-        val.filter(Boolean).forEach(c => el.classList.add(String(c)));
-      } else if (val && typeof val === 'object') {
-        for (const [cls, active] of Object.entries(val)) {
-          el.classList.toggle(cls, !!active);
+      // z-class
+      if (node.hasAttribute('z-class')) {
+        const val = this._evalExpr(node.getAttribute('z-class'));
+        if (typeof val === 'string') {
+          val.split(/\s+/).filter(Boolean).forEach(c => node.classList.add(c));
+        } else if (Array.isArray(val)) {
+          val.filter(Boolean).forEach(c => node.classList.add(String(c)));
+        } else if (val && typeof val === 'object') {
+          for (const [cls, active] of Object.entries(val)) {
+            node.classList.toggle(cls, !!active);
+          }
         }
+        node.removeAttribute('z-class');
       }
-      el.removeAttribute('z-class');
-    });
 
-    // -- z-style (dynamic inline styles) ---------------------------
-    this._el.querySelectorAll('[z-style]').forEach(el => {
-      if (el.closest('[z-pre]')) return;
-      const val = this._evalExpr(el.getAttribute('z-style'));
-      if (typeof val === 'string') {
-        el.style.cssText += ';' + val;
-      } else if (val && typeof val === 'object') {
-        for (const [prop, v] of Object.entries(val)) {
-          el.style[prop] = v;
+      // z-style
+      if (node.hasAttribute('z-style')) {
+        const val = this._evalExpr(node.getAttribute('z-style'));
+        if (typeof val === 'string') {
+          node.style.cssText += ';' + val;
+        } else if (val && typeof val === 'object') {
+          for (const [prop, v] of Object.entries(val)) {
+            node.style[prop] = v;
+          }
         }
+        node.removeAttribute('z-style');
       }
-      el.removeAttribute('z-style');
-    });
 
-    // -- z-stream (assign MediaStream to <video>/<audio>.srcObject) -
-    this._el.querySelectorAll('[z-stream]').forEach(el => {
-      if (el.closest('[z-pre]')) return;
-      const val = this._evalExpr(el.getAttribute('z-stream'));
-      const hasMediaStream = typeof MediaStream !== 'undefined';
-      if (val == null) {
-        el.srcObject = null;
-      } else if (hasMediaStream && val instanceof MediaStream) {
-        el.srcObject = val;
-      } else if (val && typeof val.getTracks === 'function') {
-        // Accept duck-typed stream objects (test fakes, polyfills).
-        el.srcObject = val;
-      } else {
-        el.srcObject = null;
+      // z-stream → MediaStream → <video>/<audio>.srcObject
+      if (node.hasAttribute('z-stream')) {
+        const val = this._evalExpr(node.getAttribute('z-stream'));
+        if (val == null) {
+          node.srcObject = null;
+        } else if (hasMediaStream && val instanceof MediaStream) {
+          node.srcObject = val;
+        } else if (val && typeof val.getTracks === 'function') {
+          // Accept duck-typed stream objects (test fakes, polyfills).
+          node.srcObject = val;
+        } else {
+          node.srcObject = null;
+        }
+        node.removeAttribute('z-stream');
       }
-      el.removeAttribute('z-stream');
-    });
+
+      // z-cloak (just strip)
+      if (node.hasAttribute('z-cloak')) {
+        node.removeAttribute('z-cloak');
+      }
+    }
 
     // z-html and z-text are now pre-expanded at string level (before
     // morph) via _expandContentDirectives(), so the diff engine can
     // properly diff their content instead of clearing + re-injecting.
-
-    // -- z-cloak (remove after render) -----------------------------
-    this._el.querySelectorAll('[z-cloak]').forEach(el => {
-      el.removeAttribute('z-cloak');
-    });
   }
 
   // ---------------------------------------------------------------------------
@@ -1425,21 +1461,34 @@ class Component {
     this._delegatedEvents = null;
     this._eventBindings = null;
     // Clear any pending debounce/throttle timers to prevent stale closures.
-    // Timers are keyed by individual child elements, so iterate all descendants.
-    const allEls = this._el.querySelectorAll('*');
-    allEls.forEach(child => {
-      const dTimers = _debounceTimers.get(child);
-      if (dTimers) {
-        for (const key in dTimers) clearTimeout(dTimers[key]);
-        _debounceTimers.delete(child);
-      }
-      const tTimers = _throttleTimers.get(child);
-      if (tTimers) {
-        for (const key in tTimers) clearTimeout(tTimers[key]);
-        _throttleTimers.delete(child);
+    // Use the per-instance _timerEls set so detached elements (removed by
+    // z-if / z-for / keyed reconciliation before destroy) are still cleaned.
+    if (this._timerEls) {
+      this._timerEls.forEach(child => {
+        const dTimers = _debounceTimers.get(child);
+        if (dTimers) {
+          for (const key in dTimers) clearTimeout(dTimers[key]);
+          _debounceTimers.delete(child);
+        }
+        const tTimers = _throttleTimers.get(child);
+        if (tTimers) {
+          for (const key in tTimers) clearTimeout(tTimers[key]);
+          _throttleTimers.delete(child);
+        }
+      });
+      this._timerEls.clear();
+    }
+    if (this._scopeAttr) {
+      const def = this._def;
+      if (def && def._styleEl && def._scopeAttr === this._scopeAttr) {
+        def._styleRefCount = (def._styleRefCount || 1) - 1;
+        if (def._styleRefCount <= 0) {
+          def._styleEl.remove();
+          def._styleEl = null;
+          def._styleRefCount = 0;
+        }
       }
-    });
-    if (this._styleEl) this._styleEl.remove();
+    }
     _instances.delete(this._el);
     this._el.innerHTML = '';
   }

package/src/core.js

@@ -283,11 +283,17 @@ export class ZQueryCollection {
       });
     }
     if (value === undefined) return this.first()?.getAttribute(name);
-    return this.each((_, el) => el.setAttribute(name, value));
+    // Fast path: tight loop, no closure allocation, no `each` overhead.
+    // Mirrors the addClass/removeClass single-name fast path.
+    const els = this.elements;
+    for (let i = 0; i < els.length; i++) els[i].setAttribute(name, value);
+    return this;
   }
 
   removeAttr(name) {
-    return this.each((_, el) => el.removeAttribute(name));
+    const els = this.elements;
+    for (let i = 0; i < els.length; i++) els[i].removeAttribute(name);
+    return this;
   }
 
   prop(name, value) {
@@ -852,7 +858,9 @@ export function queryAll(selector, context) {
 // Quick-ref shortcuts, on $ namespace)
 // ---------------------------------------------------------------------------
 query.id       = (id) => document.getElementById(id);
-query.class    = (name) => document.querySelector(`.${name}`);
+// Escape the class name so callers can safely pass identifiers containing
+// dots, colons, leading digits, etc. without breaking the selector.
+query.class    = (name) => document.querySelector(`.${typeof CSS !== 'undefined' && CSS.escape ? CSS.escape(name) : name}`);
 query.classes  = (name) => new ZQueryCollection(Array.from(document.getElementsByClassName(name)));
 query.tag      = (name) => new ZQueryCollection(Array.from(document.getElementsByTagName(name)));
 Object.defineProperty(query, 'name', {

package/src/expression.js

@@ -218,12 +218,28 @@ class Parser {
 
   // Main entry
   parse() {
+    this.depth = 0;
     const result = this.parseExpression(0);
     return result;
   }
 
   // Precedence climbing
   parseExpression(minPrec) {
+    // Cap nesting depth so a deeply parenthesised or recursive expression
+    // can’t stack-overflow the host. Threshold (96) is generous - real
+    // template expressions are flat - but stops pathological inputs cold.
+    if (++this.depth > 96) {
+      this.depth--;
+      throw new Error('Expression nesting depth exceeded (max 96)');
+    }
+    try {
+      return this._parseExpressionImpl(minPrec);
+    } finally {
+      this.depth--;
+    }
+  }
+
+  _parseExpressionImpl(minPrec) {
     let left = this.parseUnary();
 
     while (true) {
@@ -550,13 +566,6 @@ class Parser {
 // ---------------------------------------------------------------------------
 
 /** Safe property access whitelist for built-in prototypes */
-const SAFE_ARRAY_METHODS = new Set([
-  'length', 'map', 'filter', 'find', 'findIndex', 'some', 'every',
-  'reduce', 'reduceRight', 'forEach', 'includes', 'indexOf', 'lastIndexOf',
-  'join', 'slice', 'concat', 'flat', 'flatMap', 'reverse', 'sort',
-  'fill', 'keys', 'values', 'entries', 'at', 'toString',
-]);
-
 const SAFE_STRING_METHODS = new Set([
   'length', 'charAt', 'charCodeAt', 'includes', 'indexOf', 'lastIndexOf',
   'slice', 'substring', 'trim', 'trimStart', 'trimEnd', 'toLowerCase',
@@ -569,18 +578,6 @@ const SAFE_NUMBER_METHODS = new Set([
   'toFixed', 'toPrecision', 'toString', 'valueOf',
 ]);
 
-const SAFE_OBJECT_METHODS = new Set([
-  'hasOwnProperty', 'toString', 'valueOf',
-]);
-
-const SAFE_MATH_PROPS = new Set([
-  'PI', 'E', 'LN2', 'LN10', 'LOG2E', 'LOG10E', 'SQRT2', 'SQRT1_2',
-  'abs', 'ceil', 'floor', 'round', 'trunc', 'max', 'min', 'pow',
-  'sqrt', 'sign', 'random', 'log', 'log2', 'log10',
-]);
-
-const SAFE_JSON_PROPS = new Set(['parse', 'stringify']);
-
 /**
  * Check if property access is safe
  */
@@ -878,8 +875,18 @@ function _evalBinary(node, scope) {
 const _astCache = new Map();
 const _AST_CACHE_MAX = 512;
 
+// Maximum source length accepted by safeEval. Real template expressions
+// are tens of bytes; anything beyond 8 KB is almost certainly an attack
+// payload or accidental dump. Reject up front to avoid feeding the
+// tokenizer and parser unbounded input.
+const _EXPR_MAX_LEN = 8192;
+
 export function safeEval(expr, scope) {
   try {
+    if (typeof expr !== 'string') return undefined;
+    if (expr.length > _EXPR_MAX_LEN) {
+      throw new Error(`Expression exceeds max length (${_EXPR_MAX_LEN} bytes)`);
+    }
     const trimmed = expr.trim();
     if (!trimmed) return undefined;
 

package/src/reactive.js

@@ -7,11 +7,27 @@
 
 import { reportError, ErrorCode } from './errors.js';
 
+// ---------------------------------------------------------------------------
+// Host-object passthrough
+// ---------------------------------------------------------------------------
+// The reactive proxy is meant for plain data: state bags, arrays, nested
+// records. Wrapping host/native objects (MediaStream, RTCPeerConnection,
+// Blob, Map, Date, etc.) breaks them - the proxy receiver is not the real
+// underlying object, so any internal-slot method call throws
+// "Illegal invocation" in the browser. Only proxy values whose prototype is
+// Object.prototype/null (plain objects) or that are Arrays.
+function _isProxyable(value) {
+  if (value === null || typeof value !== 'object') return false;
+  if (Array.isArray(value)) return true;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
 // ---------------------------------------------------------------------------
 // Deep reactive proxy
 // ---------------------------------------------------------------------------
 export function reactive(target, onChange, _path = '') {
-  if (typeof target !== 'object' || target === null) return target;
+  if (!_isProxyable(target)) return target;
   if (typeof onChange !== 'function') {
     reportError(ErrorCode.REACTIVE_CALLBACK, 'reactive() onChange must be a function', { received: typeof onChange });
     onChange = () => {};
@@ -25,7 +41,7 @@ export function reactive(target, onChange, _path = '') {
       if (key === '__raw') return obj;
 
       const value = obj[key];
-      if (typeof value === 'object' && value !== null) {
+      if (_isProxyable(value)) {
         // Return cached proxy or create new one
         if (proxyCache.has(value)) return proxyCache.get(value);
         const childProxy = new Proxy(value, handler);

package/src/router.js

@@ -17,7 +17,7 @@
  *   });
  */
 
-import { mount, destroy, prefetch } from './component.js';
+import { mount, prefetch } from './component.js';
 import { reportError, ErrorCode } from './errors.js';
 
 // Unique marker on history.state to identify zQuery-managed entries
@@ -48,7 +48,12 @@ class Router {
     this._mode = isFile ? 'hash' : (config.mode || 'history');
 
     // Keep-alive cache: component name → { container, instance }
+    // Map iteration order = insertion order, used for LRU eviction.
     this._keepAliveCache = new Map();
+    // Optional cap on cached keep-alive instances. null = unbounded (default).
+    this._keepAliveMax = (typeof config.keepAliveMax === 'number' && config.keepAliveMax > 0)
+      ? config.keepAliveMax
+      : null;
 
     // Base path for sub-path deployments
     // Priority: explicit config.base → window.__ZQ_BASE → <base href> tag
@@ -173,7 +178,13 @@ class Router {
       if (paramsAttr) {
         try {
           const params = JSON.parse(paramsAttr);
-          href = this._interpolateParams(href, params);
+          // Reject arrays, null, primitives - z-link-params must be a plain
+          // key/value object since we use it to interpolate :param placeholders.
+          if (typeof params !== 'object' || params === null || Array.isArray(params)) {
+            reportError(ErrorCode.ROUTER_RESOLVE, 'z-link-params must be a JSON object', { href, paramsAttr });
+          } else {
+            href = this._interpolateParams(href, params);
+          }
         } catch (err) {
           reportError(ErrorCode.ROUTER_RESOLVE, 'Malformed JSON in z-link-params', { href, paramsAttr }, err);
         }
@@ -395,7 +406,6 @@ class Router {
     if (this._mode === 'hash') {
       // Hash mode: stash the substate in a global - hashchange will check.
       // We still push a history entry via a sentinel hash suffix.
-      const current = window.location.hash || '#/';
       window.history.pushState(
         { [_ZQ_STATE_KEY]: 'substate', key, data },
         '',
@@ -636,6 +646,9 @@ class Router {
       // Keep-alive: reuse cached instance
       if (isKeepAlive && componentName && this._keepAliveCache.has(componentName)) {
         const cached = this._keepAliveCache.get(componentName);
+        // Refresh LRU order: move to most-recently-used position
+        this._keepAliveCache.delete(componentName);
+        this._keepAliveCache.set(componentName, cached);
         // Hide all children, show the cached one
         [...this._el.children].forEach(c => { c.style.display = 'none'; });
         cached.container.style.display = '';
@@ -674,6 +687,7 @@ class Router {
 
         if (isKeepAlive) {
           this._keepAliveCache.set(componentName, { container, instance: this._instance });
+          this._evictKeepAliveLRU();
           // Call activated() on first mount
           if (this._instance._def.activated) {
             try { this._instance._def.activated.call(this._instance); }
@@ -741,6 +755,27 @@ class Router {
 
   // --- Destroy -------------------------------------------------------------
 
+  /**
+   * @private Evict least-recently-used keep-alive entries beyond _keepAliveMax.
+   * The current route's component is preserved even if it would otherwise be
+   * the oldest entry, to avoid destroying the active view.
+   */
+  _evictKeepAliveLRU() {
+    if (this._keepAliveMax == null) return;
+    while (this._keepAliveCache.size > this._keepAliveMax) {
+      // Find oldest entry that isn't the currently-active component
+      let evictKey = null;
+      for (const key of this._keepAliveCache.keys()) {
+        if (key !== this._currentComponentName) { evictKey = key; break; }
+      }
+      if (evictKey == null) break;
+      const cached = this._keepAliveCache.get(evictKey);
+      this._keepAliveCache.delete(evictKey);
+      try { cached.instance.destroy(); } catch { /* swallow */ }
+      if (cached.container && cached.container.parentNode) cached.container.remove();
+    }
+  }
+
   destroy() {
     // Remove window/document event listeners to prevent memory leaks
     if (this._onNavEvent) {