zero-query 0.7.5 → 0.8.7

package/dist/zquery.js

@@ -1,5 +1,5 @@
 /**
- * zQuery (zeroQuery) v0.7.5
+ * zQuery (zeroQuery) v0.8.7
  * Lightweight Frontend Library
  * https://github.com/tonywied17/zero-query
  * (c) 2026 Anthony Wiedman - MIT License
@@ -205,6 +205,8 @@ function reactive(target, onChange, _path = '') {
       const old = obj[key];
       if (old === value) return true;
       obj[key] = value;
+      // Invalidate proxy cache for the old value (it may have been replaced)
+      if (old && typeof old === 'object') proxyCache.delete(old);
       try {
         onChange(key, value, old);
       } catch (err) {
@@ -216,6 +218,7 @@ function reactive(target, onChange, _path = '') {
     deleteProperty(obj, key) {
       const old = obj[key];
       delete obj[key];
+      if (old && typeof old === 'object') proxyCache.delete(old);
       try {
         onChange(key, undefined, old);
       } catch (err) {
@@ -242,6 +245,10 @@ class Signal {
     // Track dependency if there's an active effect
     if (Signal._activeEffect) {
       this._subscribers.add(Signal._activeEffect);
+      // Record this signal in the effect's dependency set for proper cleanup
+      if (Signal._activeEffect._deps) {
+        Signal._activeEffect._deps.add(this);
+      }
     }
     return this._value;
   }
@@ -255,12 +262,15 @@ class Signal {
   peek() { return this._value; }
 
   _notify() {
-    this._subscribers.forEach(fn => {
-      try { fn(); }
+    // Snapshot subscribers before iterating — a subscriber might modify
+    // the set (e.g., an effect re-running, adding itself back)
+    const subs = [...this._subscribers];
+    for (let i = 0; i < subs.length; i++) {
+      try { subs[i](); }
       catch (err) {
         reportError(ErrorCode.SIGNAL_CALLBACK, 'Signal subscriber threw', { signal: this }, err);
       }
-    });
+    }
   }
 
   subscribe(fn) {
@@ -295,12 +305,24 @@ function computed(fn) {
 }
 
 /**
- * Create a side-effect that auto-tracks signal dependencies
+ * Create a side-effect that auto-tracks signal dependencies.
+ * Returns a dispose function that removes the effect from all
+ * signals it subscribed to — prevents memory leaks.
+ *
  * @param {Function} fn — effect function
  * @returns {Function} — dispose function
  */
 function effect(fn) {
   const execute = () => {
+    // Clean up old subscriptions before re-running so stale
+    // dependencies from a previous run are properly removed
+    if (execute._deps) {
+      for (const sig of execute._deps) {
+        sig._subscribers.delete(execute);
+      }
+      execute._deps.clear();
+    }
+
     Signal._activeEffect = execute;
     try { fn(); }
     catch (err) {
@@ -308,9 +330,19 @@ function effect(fn) {
     }
     finally { Signal._activeEffect = null; }
   };
+
+  // Track which signals this effect reads from
+  execute._deps = new Set();
+
   execute();
   return () => {
-    // Remove this effect from all signals that track it
+    // Dispose: remove this effect from every signal it subscribed to
+    if (execute._deps) {
+      for (const sig of execute._deps) {
+        sig._subscribers.delete(execute);
+      }
+      execute._deps.clear();
+    }
     Signal._activeEffect = null;
   };
 }
@@ -323,6 +355,7 @@ function effect(fn) {
  * into a full jQuery-like chainable wrapper with modern APIs.
  */
 
+
 // ---------------------------------------------------------------------------
 // ZQueryCollection — wraps an array of elements with chainable methods
 // ---------------------------------------------------------------------------
@@ -541,21 +574,46 @@ class ZQueryCollection {
   // --- Classes -------------------------------------------------------------
 
   addClass(...names) {
+    // Fast path: single class, no spaces — avoids flatMap + regex split allocation
+    if (names.length === 1 && names[0].indexOf(' ') === -1) {
+      const c = names[0];
+      for (let i = 0; i < this.elements.length; i++) this.elements[i].classList.add(c);
+      return this;
+    }
     const classes = names.flatMap(n => n.split(/\s+/));
-    return this.each((_, el) => el.classList.add(...classes));
+    for (let i = 0; i < this.elements.length; i++) this.elements[i].classList.add(...classes);
+    return this;
   }
 
   removeClass(...names) {
+    if (names.length === 1 && names[0].indexOf(' ') === -1) {
+      const c = names[0];
+      for (let i = 0; i < this.elements.length; i++) this.elements[i].classList.remove(c);
+      return this;
+    }
     const classes = names.flatMap(n => n.split(/\s+/));
-    return this.each((_, el) => el.classList.remove(...classes));
+    for (let i = 0; i < this.elements.length; i++) this.elements[i].classList.remove(...classes);
+    return this;
   }
 
   toggleClass(...args) {
     const force = typeof args[args.length - 1] === 'boolean' ? args.pop() : undefined;
+    // Fast path: single class, no spaces
+    if (args.length === 1 && args[0].indexOf(' ') === -1) {
+      const c = args[0];
+      for (let i = 0; i < this.elements.length; i++) {
+        force !== undefined ? this.elements[i].classList.toggle(c, force) : this.elements[i].classList.toggle(c);
+      }
+      return this;
+    }
     const classes = args.flatMap(n => n.split(/\s+/));
-    return this.each((_, el) => {
-      classes.forEach(c => force !== undefined ? el.classList.toggle(c, force) : el.classList.toggle(c));
-    });
+    for (let i = 0; i < this.elements.length; i++) {
+      const el = this.elements[i];
+      for (let j = 0; j < classes.length; j++) {
+        force !== undefined ? el.classList.toggle(classes[j], force) : el.classList.toggle(classes[j]);
+      }
+    }
+    return this;
   }
 
   hasClass(name) {
@@ -591,7 +649,8 @@ class ZQueryCollection {
 
   css(props) {
     if (typeof props === 'string') {
-      return getComputedStyle(this.first())[props];
+      const el = this.first();
+      return el ? getComputedStyle(el)[props] : undefined;
     }
     return this.each((_, el) => Object.assign(el.style, props));
   }
@@ -667,7 +726,21 @@ class ZQueryCollection {
 
   html(content) {
     if (content === undefined) return this.first()?.innerHTML;
-    return this.each((_, el) => { el.innerHTML = content; });
+    // Auto-morph: if the element already has children, use the diff engine
+    // to patch the DOM (preserves focus, scroll, state, keyed reorder via LIS).
+    // Empty elements get raw innerHTML for fast first-paint — same strategy
+    // the component system uses (first render = innerHTML, updates = morph).
+    return this.each((_, el) => {
+      if (el.childNodes.length > 0) {
+        _morph(el, content);
+      } else {
+        el.innerHTML = content;
+      }
+    });
+  }
+
+  morph(content) {
+    return this.each((_, el) => { _morph(el, content); });
   }
 
   text(content) {
@@ -724,7 +797,8 @@ class ZQueryCollection {
   }
 
   empty() {
-    return this.each((_, el) => { el.innerHTML = ''; });
+    // textContent = '' clears all children without invoking the HTML parser
+    return this.each((_, el) => { el.textContent = ''; });
   }
 
   clone(deep = true) {
@@ -734,8 +808,9 @@ class ZQueryCollection {
   replaceWith(content) {
     return this.each((_, el) => {
       if (typeof content === 'string') {
-        el.insertAdjacentHTML('afterend', content);
-        el.remove();
+        // Auto-morph: diff attributes + children when the tag name matches
+        // instead of destroying and re-creating the element.
+        _morphElement(el, content);
       } else if (content instanceof Node) {
         el.parentNode.replaceChild(content, el);
       }
@@ -821,7 +896,9 @@ class ZQueryCollection {
 
   toggle(display = '') {
     return this.each((_, el) => {
-      el.style.display = (el.style.display === 'none' || getComputedStyle(el).display === 'none') ? display : 'none';
+      // Check inline style first (cheap) before forcing layout via getComputedStyle
+      const hidden = el.style.display === 'none' || (el.style.display !== '' ? false : getComputedStyle(el).display === 'none');
+      el.style.display = hidden ? display : 'none';
     });
   }
 
@@ -1932,13 +2009,43 @@ function _evalBinary(node, scope) {
  *   Typical: [loopVars, state, { props, refs, $ }]
  * @returns {*} — evaluation result, or undefined on error
  */
+
+// AST cache — avoids re-tokenizing and re-parsing the same expression string.
+// Bounded to prevent unbounded memory growth in long-lived apps.
+const _astCache = new Map();
+const _AST_CACHE_MAX = 512;
+
 function safeEval(expr, scope) {
   try {
     const trimmed = expr.trim();
     if (!trimmed) return undefined;
-    const tokens = tokenize(trimmed);
-    const parser = new Parser(tokens, scope);
-    const ast = parser.parse();
+
+    // Fast path for simple identifiers: "count", "name", "visible"
+    // Avoids full tokenize→parse→evaluate overhead for the most common case.
+    if (/^[a-zA-Z_$][\w$]*$/.test(trimmed)) {
+      for (const layer of scope) {
+        if (layer && typeof layer === 'object' && trimmed in layer) {
+          return layer[trimmed];
+        }
+      }
+      // Fall through to full parser for built-in globals (Math, JSON, etc.)
+    }
+
+    // Check AST cache
+    let ast = _astCache.get(trimmed);
+    if (!ast) {
+      const tokens = tokenize(trimmed);
+      const parser = new Parser(tokens, scope);
+      ast = parser.parse();
+
+      // Evict oldest entries when cache is full
+      if (_astCache.size >= _AST_CACHE_MAX) {
+        const first = _astCache.keys().next().value;
+        _astCache.delete(first);
+      }
+      _astCache.set(trimmed, ast);
+    }
+
     return evaluate(ast, scope);
   } catch (err) {
     if (typeof console !== 'undefined' && console.debug) {
@@ -1958,8 +2065,27 @@ function safeEval(expr, scope) {
  *
  * Approach: walk old and new trees in parallel, reconcile node by node.
  * Keyed elements (via `z-key`) get matched across position changes.
+ *
+ * Performance advantages over virtual DOM (React/Angular):
+ *   - No virtual tree allocation or diffing — works directly on real DOM
+ *   - Skips unchanged subtrees via fast isEqualNode() check
+ *   - z-skip attribute to opt out of diffing entire subtrees
+ *   - Reuses a single template element for HTML parsing (zero GC pressure)
+ *   - Keyed reconciliation uses LIS (Longest Increasing Subsequence) to
+ *     minimize DOM moves — same algorithm as Vue 3 / ivi
+ *   - Minimal attribute diffing with early bail-out
  */
 
+// ---------------------------------------------------------------------------
+// Reusable template element — avoids per-call allocation
+// ---------------------------------------------------------------------------
+let _tpl = null;
+
+function _getTemplate() {
+  if (!_tpl) _tpl = document.createElement('template');
+  return _tpl;
+}
+
 // ---------------------------------------------------------------------------
 // morph(existingRoot, newHTML) — patch existing DOM to match newHTML
 // ---------------------------------------------------------------------------
@@ -1972,15 +2098,53 @@ function safeEval(expr, scope) {
  * @param {string} newHTML — The desired HTML string
  */
 function morph(rootEl, newHTML) {
-  const template = document.createElement('template');
-  template.innerHTML = newHTML;
-  const newRoot = template.content;
+  const start = typeof window !== 'undefined' && window.__zqMorphHook ? performance.now() : 0;
+  const tpl = _getTemplate();
+  tpl.innerHTML = newHTML;
+  const newRoot = tpl.content;
 
-  // Convert to element for consistent handling — wrap in a div if needed
+  // Move children into a wrapper for consistent handling.
+  // We move (not clone) from the template — cheaper than cloning.
   const tempDiv = document.createElement('div');
   while (newRoot.firstChild) tempDiv.appendChild(newRoot.firstChild);
 
   _morphChildren(rootEl, tempDiv);
+
+  if (start) window.__zqMorphHook(rootEl, performance.now() - start);
+}
+
+/**
+ * Morph a single element in place — diffs attributes and children
+ * without replacing the node reference. Useful for replaceWith-style
+ * updates where you want to keep the element identity when the tag
+ * name matches.
+ *
+ * If the new HTML produces a different tag, falls back to native replace.
+ *
+ * @param {Element} oldEl — The live DOM element to patch
+ * @param {string} newHTML — HTML string for the replacement element
+ * @returns {Element} — The resulting element (same ref if morphed, new if replaced)
+ */
+function morphElement(oldEl, newHTML) {
+  const start = typeof window !== 'undefined' && window.__zqMorphHook ? performance.now() : 0;
+  const tpl = _getTemplate();
+  tpl.innerHTML = newHTML;
+  const newEl = tpl.content.firstElementChild;
+  if (!newEl) return oldEl;
+
+  // Same tag — morph in place (preserves identity, event listeners, refs)
+  if (oldEl.nodeName === newEl.nodeName) {
+    _morphAttributes(oldEl, newEl);
+    _morphChildren(oldEl, newEl);
+    if (start) window.__zqMorphHook(oldEl, performance.now() - start);
+    return oldEl;
+  }
+
+  // Different tag — must replace (can't morph <div> into <span>)
+  const clone = newEl.cloneNode(true);
+  oldEl.parentNode.replaceChild(clone, oldEl);
+  if (start) window.__zqMorphHook(clone, performance.now() - start);
+  return clone;
 }
 
 /**
@@ -1990,25 +2154,42 @@ function morph(rootEl, newHTML) {
  * @param {Element} newParent — desired state parent
  */
 function _morphChildren(oldParent, newParent) {
-  const oldChildren = [...oldParent.childNodes];
-  const newChildren = [...newParent.childNodes];
+  // Snapshot live NodeLists into arrays — childNodes is live and
+  // mutates during insertBefore/removeChild. Using a for loop to push
+  // avoids spread operator overhead for large child lists.
+  const oldCN = oldParent.childNodes;
+  const newCN = newParent.childNodes;
+  const oldLen = oldCN.length;
+  const newLen = newCN.length;
+  const oldChildren = new Array(oldLen);
+  const newChildren = new Array(newLen);
+  for (let i = 0; i < oldLen; i++) oldChildren[i] = oldCN[i];
+  for (let i = 0; i < newLen; i++) newChildren[i] = newCN[i];
 
-  // Build key maps for keyed element matching
-  const oldKeyMap = new Map();
-  const newKeyMap = new Map();
+  // Scan for keyed elements — only build maps if keys exist
+  let hasKeys = false;
+  let oldKeyMap, newKeyMap;
 
-  for (let i = 0; i < oldChildren.length; i++) {
-    const key = _getKey(oldChildren[i]);
-    if (key != null) oldKeyMap.set(key, i);
+  for (let i = 0; i < oldLen; i++) {
+    if (_getKey(oldChildren[i]) != null) { hasKeys = true; break; }
   }
-  for (let i = 0; i < newChildren.length; i++) {
-    const key = _getKey(newChildren[i]);
-    if (key != null) newKeyMap.set(key, i);
+  if (!hasKeys) {
+    for (let i = 0; i < newLen; i++) {
+      if (_getKey(newChildren[i]) != null) { hasKeys = true; break; }
+    }
   }
 
-  const hasKeys = oldKeyMap.size > 0 || newKeyMap.size > 0;
-
   if (hasKeys) {
+    oldKeyMap = new Map();
+    newKeyMap = new Map();
+    for (let i = 0; i < oldLen; i++) {
+      const key = _getKey(oldChildren[i]);
+      if (key != null) oldKeyMap.set(key, i);
+    }
+    for (let i = 0; i < newLen; i++) {
+      const key = _getKey(newChildren[i]);
+      if (key != null) newKeyMap.set(key, i);
+    }
     _morphChildrenKeyed(oldParent, oldChildren, newChildren, oldKeyMap, newKeyMap);
   } else {
     _morphChildrenUnkeyed(oldParent, oldChildren, newChildren);
@@ -2019,35 +2200,42 @@ function _morphChildren(oldParent, newParent) {
  * Unkeyed reconciliation — positional matching.
  */
 function _morphChildrenUnkeyed(oldParent, oldChildren, newChildren) {
-  const maxLen = Math.max(oldChildren.length, newChildren.length);
+  const oldLen = oldChildren.length;
+  const newLen = newChildren.length;
+  const minLen = oldLen < newLen ? oldLen : newLen;
 
-  for (let i = 0; i < maxLen; i++) {
-    const oldNode = oldChildren[i];
-    const newNode = newChildren[i];
+  // Morph overlapping range
+  for (let i = 0; i < minLen; i++) {
+    _morphNode(oldParent, oldChildren[i], newChildren[i]);
+  }
 
-    if (!oldNode && newNode) {
-      // New node — append
-      oldParent.appendChild(newNode.cloneNode(true));
-    } else if (oldNode && !newNode) {
-      // Extra old node — remove
-      oldParent.removeChild(oldNode);
-    } else if (oldNode && newNode) {
-      _morphNode(oldParent, oldNode, newNode);
+  // Append new nodes
+  if (newLen > oldLen) {
+    for (let i = oldLen; i < newLen; i++) {
+      oldParent.appendChild(newChildren[i].cloneNode(true));
+    }
+  }
+
+  // Remove excess old nodes (iterate backwards to avoid index shifting)
+  if (oldLen > newLen) {
+    for (let i = oldLen - 1; i >= newLen; i--) {
+      oldParent.removeChild(oldChildren[i]);
     }
   }
 }
 
 /**
- * Keyed reconciliation — match by z-key, reorder minimal moves.
+ * Keyed reconciliation — match by z-key, reorder with minimal moves
+ * using Longest Increasing Subsequence (LIS) to find the maximum set
+ * of nodes that are already in the correct relative order, then only
+ * move the remaining nodes.
  */
 function _morphChildrenKeyed(oldParent, oldChildren, newChildren, oldKeyMap, newKeyMap) {
-  // Track which old nodes are consumed
   const consumed = new Set();
-
-  // Step 1: Build ordered list of matched old nodes for new children
   const newLen = newChildren.length;
-  const matched = new Array(newLen); // matched[newIdx] = oldNode | null
+  const matched = new Array(newLen);
 
+  // Step 1: Match new children to old children by key
   for (let i = 0; i < newLen; i++) {
     const key = _getKey(newChildren[i]);
     if (key != null && oldKeyMap.has(key)) {
@@ -2059,21 +2247,40 @@ function _morphChildrenKeyed(oldParent, oldChildren, newChildren, oldKeyMap, new
     }
   }
 
-  // Step 2: Remove old nodes that are not in the new tree
+  // Step 2: Remove old keyed nodes not in the new tree
   for (let i = oldChildren.length - 1; i >= 0; i--) {
     if (!consumed.has(i)) {
       const key = _getKey(oldChildren[i]);
       if (key != null && !newKeyMap.has(key)) {
         oldParent.removeChild(oldChildren[i]);
-      } else if (key == null) {
-        // Unkeyed old node — will be handled positionally below
       }
     }
   }
 
-  // Step 3: Insert/reorder/morph
+  // Step 3: Build index array for LIS of matched old indices.
+  // This finds the largest set of keyed nodes already in order,
+  // so we only need to move the rest — O(n log n) instead of O(n²).
+  const oldIndices = [];      // Maps new-position → old-position (or -1)
+  for (let i = 0; i < newLen; i++) {
+    if (matched[i]) {
+      const key = _getKey(newChildren[i]);
+      oldIndices.push(oldKeyMap.get(key));
+    } else {
+      oldIndices.push(-1);
+    }
+  }
+
+  const lisSet = _lis(oldIndices);
+
+  // Step 4: Insert / reorder / morph — walk new children forward,
+  // using LIS to decide which nodes stay in place.
   let cursor = oldParent.firstChild;
-  const unkeyedOld = oldChildren.filter((n, i) => !consumed.has(i) && _getKey(n) == null);
+  const unkeyedOld = [];
+  for (let i = 0; i < oldChildren.length; i++) {
+    if (!consumed.has(i) && _getKey(oldChildren[i]) == null) {
+      unkeyedOld.push(oldChildren[i]);
+    }
+  }
   let unkeyedIdx = 0;
 
   for (let i = 0; i < newLen; i++) {
@@ -2082,16 +2289,14 @@ function _morphChildrenKeyed(oldParent, oldChildren, newChildren, oldKeyMap, new
     let oldNode = matched[i];
 
     if (!oldNode && newKey == null) {
-      // Try to match an unkeyed old node positionally
       oldNode = unkeyedOld[unkeyedIdx++] || null;
     }
 
     if (oldNode) {
-      // Move into position if needed
-      if (oldNode !== cursor) {
+      // If this node is NOT part of the LIS, it needs to be moved
+      if (!lisSet.has(i)) {
         oldParent.insertBefore(oldNode, cursor);
       }
-      // Morph in place
       _morphNode(oldParent, oldNode, newNode);
       cursor = oldNode.nextSibling;
     } else {
@@ -2102,11 +2307,10 @@ function _morphChildrenKeyed(oldParent, oldChildren, newChildren, oldKeyMap, new
       } else {
         oldParent.appendChild(clone);
       }
-      // cursor stays the same — new node is before it
     }
   }
 
-  // Remove any remaining unkeyed old nodes at the end
+  // Remove remaining unkeyed old nodes
   while (unkeyedIdx < unkeyedOld.length) {
     const leftover = unkeyedOld[unkeyedIdx++];
     if (leftover.parentNode === oldParent) {
@@ -2125,6 +2329,54 @@ function _morphChildrenKeyed(oldParent, oldChildren, newChildren, oldKeyMap, new
   }
 }
 
+/**
+ * Compute the Longest Increasing Subsequence of an index array.
+ * Returns a Set of positions (in the input) that form the LIS.
+ * Entries with value -1 (unmatched) are excluded.
+ *
+ * O(n log n) — same algorithm used by Vue 3 and ivi.
+ *
+ * @param {number[]} arr — array of old-tree indices (-1 = unmatched)
+ * @returns {Set<number>} — positions in arr belonging to the LIS
+ */
+function _lis(arr) {
+  const len = arr.length;
+  const result = new Set();
+  if (len === 0) return result;
+
+  // tails[i] = index in arr of the smallest tail element for LIS of length i+1
+  const tails = [];
+  // prev[i] = predecessor index in arr for the LIS ending at arr[i]
+  const prev = new Array(len).fill(-1);
+  const tailIndices = []; // parallel to tails: actual positions
+
+  for (let i = 0; i < len; i++) {
+    if (arr[i] === -1) continue;
+    const val = arr[i];
+
+    // Binary search for insertion point in tails
+    let lo = 0, hi = tails.length;
+    while (lo < hi) {
+      const mid = (lo + hi) >> 1;
+      if (tails[mid] < val) lo = mid + 1;
+      else hi = mid;
+    }
+
+    tails[lo] = val;
+    tailIndices[lo] = i;
+    prev[i] = lo > 0 ? tailIndices[lo - 1] : -1;
+  }
+
+  // Reconstruct: walk backwards from the last element of LIS
+  let k = tailIndices[tails.length - 1];
+  for (let i = tails.length - 1; i >= 0; i--) {
+    result.add(k);
+    k = prev[k];
+  }
+
+  return result;
+}
+
 /**
  * Morph a single node in place.
  */
@@ -2151,10 +2403,18 @@ function _morphNode(parent, oldNode, newNode) {
 
   // Both are elements — diff attributes then recurse children
   if (oldNode.nodeType === 1) {
+    // z-skip: developer opt-out — skip diffing this subtree entirely.
+    // Useful for third-party widgets, canvas, video, or large static content.
+    if (oldNode.hasAttribute('z-skip')) return;
+
+    // Fast bail-out: if the elements are identical, skip everything.
+    // isEqualNode() is a native C++ comparison — much faster than walking
+    // attributes + children in JS when trees haven't changed.
+    if (oldNode.isEqualNode(newNode)) return;
+
     _morphAttributes(oldNode, newNode);
 
     // Special elements: don't recurse into their children
-    // (textarea value, input value, select, etc.)
     const tag = oldNode.nodeName;
     if (tag === 'INPUT') {
       _syncInputValue(oldNode, newNode);
@@ -2167,7 +2427,6 @@ function _morphNode(parent, oldNode, newNode) {
       return;
     }
     if (tag === 'SELECT') {
-      // Recurse children (options) then sync value
       _morphChildren(oldNode, newNode);
       if (oldNode.value !== newNode.value) {
         oldNode.value = newNode.value;
@@ -2182,23 +2441,45 @@ function _morphNode(parent, oldNode, newNode) {
 
 /**
  * Sync attributes from newEl onto oldEl.
+ * Uses a single pass: build a set of new attribute names, iterate
+ * old attrs for removals, then apply new attrs.
  */
 function _morphAttributes(oldEl, newEl) {
-  // Add/update attributes
   const newAttrs = newEl.attributes;
-  for (let i = 0; i < newAttrs.length; i++) {
+  const oldAttrs = oldEl.attributes;
+  const newLen = newAttrs.length;
+  const oldLen = oldAttrs.length;
+
+  // Fast path: if both have same number of attributes, check if they're identical
+  if (newLen === oldLen) {
+    let same = true;
+    for (let i = 0; i < newLen; i++) {
+      const na = newAttrs[i];
+      if (oldEl.getAttribute(na.name) !== na.value) { same = false; break; }
+    }
+    if (same) {
+      // Also verify no extra old attrs (names mismatch)
+      for (let i = 0; i < oldLen; i++) {
+        if (!newEl.hasAttribute(oldAttrs[i].name)) { same = false; break; }
+      }
+    }
+    if (same) return;
+  }
+
+  // Build set of new attr names for O(1) lookup during removal pass
+  const newNames = new Set();
+  for (let i = 0; i < newLen; i++) {
     const attr = newAttrs[i];
+    newNames.add(attr.name);
     if (oldEl.getAttribute(attr.name) !== attr.value) {
       oldEl.setAttribute(attr.name, attr.value);
     }
   }
 
   // Remove stale attributes
-  const oldAttrs = oldEl.attributes;
-  for (let i = oldAttrs.length - 1; i >= 0; i--) {
-    const attr = oldAttrs[i];
-    if (!newEl.hasAttribute(attr.name)) {
-      oldEl.removeAttribute(attr.name);
+  for (let i = oldLen - 1; i >= 0; i--) {
+    if (!newNames.has(oldAttrs[i].name)) {
+      oldEl.removeAttribute(oldAttrs[i].name);
     }
   }
 }
@@ -2222,12 +2503,36 @@ function _syncInputValue(oldEl, newEl) {
 }
 
 /**
- * Get the reconciliation key from a node (z-key attribute).
+ * Get the reconciliation key from a node.
+ *
+ * Priority: z-key attribute → id attribute → data-id / data-key.
+ * Auto-detected keys use a `\0` prefix to avoid collisions with
+ * explicit z-key values.
+ *
+ * This means the LIS-optimised keyed path activates automatically
+ * whenever elements carry `id` or `data-id` / `data-key` attributes
+ * — no extra markup required.
+ *
  * @returns {string|null}
  */
 function _getKey(node) {
   if (node.nodeType !== 1) return null;
-  return node.getAttribute('z-key') || null;
+
+  // Explicit z-key — highest priority
+  const zk = node.getAttribute('z-key');
+  if (zk) return zk;
+
+  // Auto-key: id attribute (unique by spec)
+  if (node.id) return '\0id:' + node.id;
+
+  // Auto-key: data-id or data-key attributes
+  const ds = node.dataset;
+  if (ds) {
+    if (ds.id)  return '\0data-id:'  + ds.id;
+    if (ds.key) return '\0data-key:' + ds.key;
+  }
+
+  return null;
 }
 
 // --- src/component.js --------------------------------------------
@@ -2248,7 +2553,7 @@ function _getKey(node) {
  *   - Scoped styles (inline or via styleUrl)
  *   - External templates via templateUrl (with {{expression}} interpolation)
  *   - External styles via styleUrl (fetched & scoped automatically)
- *   - Relative path resolution — templateUrl, styleUrl, and pages.dir
+ *   - Relative path resolution — templateUrl and styleUrl
  *     resolve relative to the component file automatically
  */
 
@@ -2318,16 +2623,6 @@ function _fetchResource(url) {
   return promise;
 }
 
-/**
- * Convert a kebab-case id to Title Case.
- * 'getting-started' → 'Getting Started'
- * @param {string} id
- * @returns {string}
- */
-function _titleCase(id) {
-  return id.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
-}
-
 /**
  * Resolve a relative URL against a base.
  *
@@ -2546,47 +2841,10 @@ class Component {
   //   - string              → single stylesheet
   //   - string[]            → array of URLs → all fetched & concatenated
   //
-  // pages config (shorthand for multi-template + route-param page switching):
-  //   pages: {
-  //     dir:     'pages',             // relative to component file (or base)
-  //     param:   'section',           // route param name → this.activePage
-  //     default: 'getting-started',   // fallback when param is absent
-  //     ext:     '.html',             // file extension (default '.html')
-  //     items:   ['page-a', { id: 'page-b', label: 'Page B' }, ...]
-  //   }
-  //   Exposes this.pages (array of {id,label}), this.activePage (current id)
-  //   Pages are lazy-loaded: only the active page is fetched on first render,
-  //   remaining pages are prefetched in the background for instant navigation.
-  //
   async _loadExternals() {
     const def = this._def;
     const base = def._base; // auto-detected or explicit
 
-    // -- Pages config ---------------------------------------------
-    if (def.pages && !def._pagesNormalized) {
-      const p = def.pages;
-      const ext = p.ext || '.html';
-      const dir = _resolveUrl((p.dir || '').replace(/\/+$/, ''), base);
-
-      // Normalize items → [{id, label}, …]
-      def._pages = (p.items || []).map(item => {
-        if (typeof item === 'string') return { id: item, label: _titleCase(item) };
-        return { id: item.id, label: item.label || _titleCase(item.id) };
-      });
-
-      // Build URL map for lazy per-page loading.
-      // Pages are fetched on demand (active page first, rest prefetched in
-      // the background) so the component renders as soon as the visible
-      // page is ready instead of waiting for every page to download.
-      def._pageUrls = {};
-      for (const { id } of def._pages) {
-        def._pageUrls[id] = `${dir}/${id}${ext}`;
-      }
-      if (!def._externalTemplates) def._externalTemplates = {};
-
-      def._pagesNormalized = true;
-    }
-
     // -- External templates --------------------------------------
     if (def.templateUrl && !def._templateLoaded) {
       const tu = def.templateUrl;
@@ -2599,9 +2857,8 @@ class Component {
         results.forEach((html, i) => { def._externalTemplates[i] = html; });
       } else if (typeof tu === 'object') {
         const entries = Object.entries(tu);
-        // Pages config already resolved; plain objects still need resolving
         const results = await Promise.all(
-          entries.map(([, url]) => _fetchResource(def._pagesNormalized ? url : _resolveUrl(url, base)))
+          entries.map(([, url]) => _fetchResource(_resolveUrl(url, base)))
         );
         def._externalTemplates = {};
         entries.forEach(([key], i) => { def._externalTemplates[key] = results[i]; });
@@ -2630,8 +2887,7 @@ class Component {
   _render() {
     // If externals haven't loaded yet, trigger async load then re-render
     if ((this._def.templateUrl && !this._def._templateLoaded) ||
-        (this._def.styleUrl && !this._def._styleLoaded) ||
-        (this._def.pages && !this._def._pagesNormalized)) {
+        (this._def.styleUrl && !this._def._styleLoaded)) {
       this._loadExternals().then(() => {
         if (!this._destroyed) this._render();
       });
@@ -2643,43 +2899,6 @@ class Component {
       this.templates = this._def._externalTemplates;
     }
 
-    // Expose pages metadata and active page (derived from route param)
-    if (this._def._pages) {
-      this.pages = this._def._pages;
-      const pc = this._def.pages;
-      let active = (pc.param && this.props.$params?.[pc.param]) || pc.default || this._def._pages[0]?.id || '';
-
-      // Fall back to default if the param doesn't match any known page
-      if (this._def._pageUrls && !(active in this._def._pageUrls)) {
-        active = pc.default || this._def._pages[0]?.id || '';
-      }
-      this.activePage = active;
-
-      // Lazy-load: fetch only the active page's template on demand
-      if (this._def._pageUrls && !(active in this._def._externalTemplates)) {
-        const url = this._def._pageUrls[active];
-        if (url) {
-          _fetchResource(url).then(html => {
-            this._def._externalTemplates[active] = html;
-            if (!this._destroyed) this._render();
-          });
-          return; // Wait for active page before rendering
-        }
-      }
-
-      // Prefetch remaining pages in background (once, after active page is ready)
-      if (this._def._pageUrls && !this._def._pagesPrefetched) {
-        this._def._pagesPrefetched = true;
-        for (const [id, url] of Object.entries(this._def._pageUrls)) {
-          if (!(id in this._def._externalTemplates)) {
-            _fetchResource(url).then(html => {
-              this._def._externalTemplates[id] = html;
-            });
-          }
-        }
-      }
-    }
-
     // Determine HTML content
     let html;
     if (this._def.render) {
@@ -2704,6 +2923,11 @@ class Component {
       html = '';
     }
 
+    // Pre-expand z-html and z-text at string level so the morph engine
+    // can diff their content properly (instead of clearing + re-injecting
+    // on every re-render). Same pattern as z-for: parse → evaluate → serialize.
+    html = this._expandContentDirectives(html);
+
     // -- Slot distribution ----------------------------------------
     // Replace <slot> elements with captured slot content from parent.
     // <slot> → default slot content
@@ -2793,8 +3017,10 @@ class Component {
 
     // Update DOM via morphing (diffing) — preserves unchanged nodes
     // First render uses innerHTML for speed; subsequent renders morph.
+    const _renderStart = typeof window !== 'undefined' && (window.__zqMorphHook || window.__zqRenderHook) ? performance.now() : 0;
     if (!this._mounted) {
       this._el.innerHTML = html;
+      if (_renderStart && window.__zqRenderHook) window.__zqRenderHook(this._el, performance.now() - _renderStart, 'mount', this._def._name);
     } else {
       morph(this._el, html);
     }
@@ -2837,31 +3063,31 @@ class Component {
     }
   }
 
-  // Bind @event="method" and z-on:event="method" handlers via delegation
+  // Bind @event="method" and z-on:event="method" handlers via delegation.
+  //
+  // Optimization: on the FIRST render, we scan for event attributes, build
+  // a delegated handler map, and attach one listener per event type to the
+  // component root. On subsequent renders (re-bind), we only rebuild the
+  // internal binding map — existing DOM listeners are reused since they
+  // delegate to event.target.closest(selector) at fire time.
   _bindEvents() {
-    // Clean up old delegated listeners
-    this._listeners.forEach(({ event, handler }) => {
-      this._el.removeEventListener(event, handler);
-    });
-    this._listeners = [];
+    // Always rebuild the binding map from current DOM
+    const eventMap = new Map(); // event → [{ selector, methodExpr, modifiers, el }]
 
-    // Find all elements with @event or z-on:event attributes
     const allEls = this._el.querySelectorAll('*');
-    const eventMap = new Map(); // event → [{ selector, method, modifiers }]
-
     allEls.forEach(child => {
-      // Skip elements inside z-pre subtrees
       if (child.closest('[z-pre]')) return;
 
-      [...child.attributes].forEach(attr => {
-        // Support both @event and z-on:event syntax
+      const attrs = child.attributes;
+      for (let a = 0; a < attrs.length; a++) {
+        const attr = attrs[a];
         let raw;
-        if (attr.name.startsWith('@')) {
-          raw = attr.name.slice(1); // @click.prevent → click.prevent
+        if (attr.name.charCodeAt(0) === 64) { // '@'
+          raw = attr.name.slice(1);
         } else if (attr.name.startsWith('z-on:')) {
-          raw = attr.name.slice(5); // z-on:click.prevent → click.prevent
+          raw = attr.name.slice(5);
         } else {
-          return;
+          continue;
         }
 
         const parts = raw.split('.');
@@ -2877,12 +3103,45 @@ class Component {
 
         if (!eventMap.has(event)) eventMap.set(event, []);
         eventMap.get(event).push({ selector, methodExpr, modifiers, el: child });
-      });
+      }
     });
 
+    // Store binding map for the delegated handlers to reference
+    this._eventBindings = eventMap;
+
+    // Only attach DOM listeners once — reuse on subsequent renders.
+    // The handlers close over `this` and read `this._eventBindings`
+    // at fire time, so they always use the latest binding map.
+    if (this._delegatedEvents) {
+      // Already attached — just make sure new event types are covered
+      for (const event of eventMap.keys()) {
+        if (!this._delegatedEvents.has(event)) {
+          this._attachDelegatedEvent(event, eventMap.get(event));
+        }
+      }
+      // Remove listeners for event types no longer in the template
+      for (const event of this._delegatedEvents.keys()) {
+        if (!eventMap.has(event)) {
+          const { handler, opts } = this._delegatedEvents.get(event);
+          this._el.removeEventListener(event, handler, opts);
+          this._delegatedEvents.delete(event);
+          // Also remove from _listeners array
+          this._listeners = this._listeners.filter(l => l.event !== event);
+        }
+      }
+      return;
+    }
+
+    this._delegatedEvents = new Map();
+
     // Register delegated listeners on the component root
     for (const [event, bindings] of eventMap) {
-      // Determine listener options from modifiers
+      this._attachDelegatedEvent(event, bindings);
+    }
+  }
+
+  // Attach a single delegated listener for an event type
+  _attachDelegatedEvent(event, bindings) {
       const needsCapture = bindings.some(b => b.modifiers.includes('capture'));
       const needsPassive = bindings.some(b => b.modifiers.includes('passive'));
       const listenerOpts = (needsCapture || needsPassive)
@@ -2890,7 +3149,9 @@ class Component {
         : false;
 
       const handler = (e) => {
-        for (const { selector, methodExpr, modifiers, el } of bindings) {
+        // Read bindings from live map — always up to date after re-renders
+        const currentBindings = this._eventBindings?.get(event) || [];
+        for (const { selector, methodExpr, modifiers, el } of currentBindings) {
           if (!e.target.closest(selector)) continue;
 
           // .self — only fire if target is the element itself
@@ -2960,7 +3221,7 @@ class Component {
       };
       this._el.addEventListener(event, handler, listenerOpts);
       this._listeners.push({ event, handler });
-    }
+      this._delegatedEvents.set(event, { handler, opts: listenerOpts });
   }
 
   // Bind z-ref="name" → this.refs.name
@@ -2999,7 +3260,7 @@ class Component {
       // Read current state value (supports dot-path keys)
       const currentVal = _getPath(this.state, key);
 
-      // -- Set initial DOM value from state ------------------------
+      // -- Set initial DOM value from state (always sync) ----------
       if (tag === 'input' && type === 'checkbox') {
         el.checked = !!currentVal;
       } else if (tag === 'input' && type === 'radio') {
@@ -3021,6 +3282,11 @@ 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;
+
       const handler = () => {
         let val;
         if (type === 'checkbox')           val = el.checked;
@@ -3140,6 +3406,41 @@ class Component {
     return temp.innerHTML;
   }
 
+  // ---------------------------------------------------------------------------
+  // _expandContentDirectives — Pre-morph z-html & z-text expansion
+  //
+  // Evaluates z-html and z-text directives at the string level so the morph
+  // engine receives HTML with the actual content inline. This lets the diff
+  // algorithm properly compare old vs new content (text nodes, child elements)
+  // instead of clearing + re-injecting on every re-render.
+  //
+  // Same parse → evaluate → serialize pattern as _expandZFor.
+  // ---------------------------------------------------------------------------
+  _expandContentDirectives(html) {
+    if (!html.includes('z-html') && !html.includes('z-text')) return html;
+
+    const temp = document.createElement('div');
+    temp.innerHTML = html;
+
+    // z-html: evaluate expression → inject as innerHTML
+    temp.querySelectorAll('[z-html]').forEach(el => {
+      if (el.closest('[z-pre]')) return;
+      const val = this._evalExpr(el.getAttribute('z-html'));
+      el.innerHTML = val != null ? String(val) : '';
+      el.removeAttribute('z-html');
+    });
+
+    // z-text: evaluate expression → inject as textContent (HTML-safe)
+    temp.querySelectorAll('[z-text]').forEach(el => {
+      if (el.closest('[z-pre]')) return;
+      const val = this._evalExpr(el.getAttribute('z-text'));
+      el.textContent = val != null ? String(val) : '';
+      el.removeAttribute('z-text');
+    });
+
+    return temp.innerHTML;
+  }
+
   // ---------------------------------------------------------------------------
   // _processDirectives — Post-innerHTML DOM-level directive processing
   // ---------------------------------------------------------------------------
@@ -3192,25 +3493,36 @@ class Component {
     });
 
     // -- z-bind:attr / :attr (dynamic attribute binding) -----------
-    this._el.querySelectorAll('*').forEach(el => {
-      if (el.closest('[z-pre]')) return;
-      [...el.attributes].forEach(attr => {
+    // 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).
+    const walker = document.createTreeWalker(this._el, NodeFilter.SHOW_ELEMENT, {
+      acceptNode(n) {
+        return n.hasAttribute('z-pre') ? NodeFilter.FILTER_REJECT : NodeFilter.FILTER_ACCEPT;
+      }
+    });
+    let node;
+    while ((node = walker.nextNode())) {
+      const attrs = node.attributes;
+      for (let i = attrs.length - 1; i >= 0; i--) {
+        const attr = attrs[i];
         let attrName;
         if (attr.name.startsWith('z-bind:')) attrName = attr.name.slice(7);
-        else if (attr.name.startsWith(':') && !attr.name.startsWith('::')) attrName = attr.name.slice(1);
-        else return;
+        else if (attr.name.charCodeAt(0) === 58 && attr.name.charCodeAt(1) !== 58) attrName = attr.name.slice(1); // ':' but not '::'
+        else continue;
 
         const val = this._evalExpr(attr.value);
-        el.removeAttribute(attr.name);
+        node.removeAttribute(attr.name);
         if (val === false || val === null || val === undefined) {
-          el.removeAttribute(attrName);
+          node.removeAttribute(attrName);
         } else if (val === true) {
-          el.setAttribute(attrName, '');
+          node.setAttribute(attrName, '');
         } else {
-          el.setAttribute(attrName, String(val));
+          node.setAttribute(attrName, String(val));
         }
-      });
-    });
+      }
+    }
 
     // -- z-class (dynamic class binding) ---------------------------
     this._el.querySelectorAll('[z-class]').forEach(el => {
@@ -3242,21 +3554,9 @@ class Component {
       el.removeAttribute('z-style');
     });
 
-    // -- z-html (innerHTML injection) ------------------------------
-    this._el.querySelectorAll('[z-html]').forEach(el => {
-      if (el.closest('[z-pre]')) return;
-      const val = this._evalExpr(el.getAttribute('z-html'));
-      el.innerHTML = val != null ? String(val) : '';
-      el.removeAttribute('z-html');
-    });
-
-    // -- z-text (safe textContent binding) -------------------------
-    this._el.querySelectorAll('[z-text]').forEach(el => {
-      if (el.closest('[z-pre]')) return;
-      const val = this._evalExpr(el.getAttribute('z-text'));
-      el.textContent = val != null ? String(val) : '';
-      el.removeAttribute('z-text');
-    });
+    // 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 => {
@@ -3289,6 +3589,8 @@ class Component {
     }
     this._listeners.forEach(({ event, handler }) => this._el.removeEventListener(event, handler));
     this._listeners = [];
+    this._delegatedEvents = null;
+    this._eventBindings = null;
     if (this._styleEl) this._styleEl.remove();
     _instances.delete(this._el);
     this._el.innerHTML = '';
@@ -3299,7 +3601,7 @@ class Component {
 // Reserved definition keys (not user methods)
 const _reservedKeys = new Set([
   'state', 'render', 'styles', 'init', 'mounted', 'updated', 'destroyed', 'props',
-  'templateUrl', 'styleUrl', 'templates', 'pages', 'activePage', 'base',
+  'templateUrl', 'styleUrl', 'templates', 'base',
   'computed', 'watch'
 ]);
 
@@ -3322,8 +3624,8 @@ function component(name, definition) {
   }
   definition._name = name;
 
-  // Auto-detect the calling module's URL so that relative templateUrl,
-  // styleUrl, and pages.dir paths resolve relative to the component file.
+  // Auto-detect the calling module's URL so that relative templateUrl
+  // and styleUrl paths resolve relative to the component file.
   // An explicit `base` string on the definition overrides auto-detection.
   if (definition.base !== undefined) {
     definition._base = definition.base;   // explicit override
@@ -3439,6 +3741,24 @@ function getRegistry() {
   return Object.fromEntries(_registry);
 }
 
+/**
+ * Pre-load a component's external templates and styles so the next mount
+ * renders synchronously (no blank flash while fetching).
+ * Safe to call multiple times — skips if already loaded.
+ * @param {string} name — registered component name
+ * @returns {Promise<void>}
+ */
+async function prefetch(name) {
+  const def = _registry.get(name);
+  if (!def) return;
+
+  // Load templateUrl and styleUrl if not already loaded.
+  if ((def.templateUrl && !def._templateLoaded) ||
+      (def.styleUrl && !def._styleLoaded)) {
+    await Component.prototype._loadExternals.call({ _def: def });
+  }
+}
+
 
 // ---------------------------------------------------------------------------
 // Global stylesheet loader
@@ -3546,6 +3866,7 @@ function style(urls, opts = {}) {
  * 
  * Supports hash mode (#/path) and history mode (/path).
  * Route params, query strings, navigation guards, and lazy loading.
+ * Sub-route history substates for in-page UI changes (modals, tabs, etc.).
  * 
  * Usage:
  *   $.router({
@@ -3562,6 +3883,9 @@ function style(urls, opts = {}) {
 
 
 
+// Unique marker on history.state to identify zQuery-managed entries
+const _ZQ_STATE_KEY = '__zq';
+
 class Router {
   constructor(config = {}) {
     this._el = null;
@@ -3595,6 +3919,10 @@ class Router {
     this._instance = null;                        // current mounted component
     this._resolving = false;                      // re-entrancy guard
 
+    // Sub-route history substates
+    this._substateListeners = [];                 // [(key, data) => bool|void]
+    this._inSubstate = false;                       // true while substate entries are in the history stack
+
     // Set outlet element
     if (config.el) {
       this._el = typeof config.el === 'string' ? document.querySelector(config.el) : config.el;
@@ -3609,7 +3937,21 @@ class Router {
     if (this._mode === 'hash') {
       window.addEventListener('hashchange', () => this._resolve());
     } else {
-      window.addEventListener('popstate', () => this._resolve());
+      window.addEventListener('popstate', (e) => {
+        // Check for substate pop first — if a listener handles it, don't route
+        const st = e.state;
+        if (st && st[_ZQ_STATE_KEY] === 'substate') {
+          const handled = this._fireSubstate(st.key, st.data, 'pop');
+          if (handled) return;
+          // Unhandled substate — fall through to route resolve
+          // _inSubstate stays true so the next non-substate pop triggers reset
+        } else if (this._inSubstate) {
+          // Popped past all substates — notify listeners to reset to defaults
+          this._inSubstate = false;
+          this._fireSubstate(null, null, 'reset');
+        }
+        this._resolve();
+      });
     }
 
     // Intercept link clicks for SPA navigation
@@ -3658,7 +4000,7 @@ class Router {
 
     // Per-route fallback: register an alias path for the same component.
     // e.g. { path: '/docs/:section', fallback: '/docs', component: 'docs-page' }
-    // When matched via fallback, missing params are undefined → pages `default` kicks in.
+    // When matched via fallback, missing params are undefined.
     if (route.fallback) {
       const fbKeys = [];
       const fbPattern = route.fallback
@@ -3692,6 +4034,19 @@ class Router {
     });
   }
 
+  /**
+   * Get the full current URL (path + hash) for same-URL detection.
+   * @returns {string}
+   */
+  _currentURL() {
+    if (this._mode === 'hash') {
+      return window.location.hash.slice(1) || '/';
+    }
+    const pathname = window.location.pathname || '/';
+    const hash = window.location.hash || '';
+    return pathname + hash;
+  }
+
   navigate(path, options = {}) {
     // Interpolate :param placeholders if options.params is provided
     if (options.params) path = this._interpolateParams(path, options.params);
@@ -3703,9 +4058,48 @@ class Router {
       // Hash mode uses the URL hash for routing, so a #fragment can't live
       // in the URL. Store it as a scroll target for the destination component.
       if (fragment) window.__zqScrollTarget = fragment;
-      window.location.hash = '#' + normalized;
+      const targetHash = '#' + normalized;
+      // Skip if already at this exact hash (prevents duplicate entries)
+      if (window.location.hash === targetHash && !options.force) return this;
+      window.location.hash = targetHash;
     } else {
-      window.history.pushState(options.state || {}, '', this._base + normalized + hash);
+      const targetURL = this._base + normalized + hash;
+      const currentURL = (window.location.pathname || '/') + (window.location.hash || '');
+
+      if (targetURL === currentURL && !options.force) {
+        // Same full URL (path + hash) — don't push duplicate entry.
+        // If only the hash changed to a fragment target, scroll to it.
+        if (fragment) {
+          const el = document.getElementById(fragment);
+          if (el) el.scrollIntoView({ behavior: 'smooth', block: 'start' });
+        }
+        return this;
+      }
+
+      // Same route path but different hash fragment — use replaceState
+      // so back goes to the previous *route*, not the previous scroll position.
+      const targetPathOnly = this._base + normalized;
+      const currentPathOnly = window.location.pathname || '/';
+      if (targetPathOnly === currentPathOnly && hash && !options.force) {
+        window.history.replaceState(
+          { ...options.state, [_ZQ_STATE_KEY]: 'route' },
+          '',
+          targetURL
+        );
+        // Scroll to the fragment target
+        if (fragment) {
+          const el = document.getElementById(fragment);
+          if (el) el.scrollIntoView({ behavior: 'smooth', block: 'start' });
+        }
+        // Don't re-resolve — same route, just a hash change
+        return this;
+      }
+
+      window.history.pushState(
+        { ...options.state, [_ZQ_STATE_KEY]: 'route' },
+        '',
+        targetURL
+      );
       this._resolve();
     }
     return this;
@@ -3721,7 +4115,11 @@ class Router {
       if (fragment) window.__zqScrollTarget = fragment;
       window.location.replace('#' + normalized);
     } else {
-      window.history.replaceState(options.state || {}, '', this._base + normalized + hash);
+      window.history.replaceState(
+        { ...options.state, [_ZQ_STATE_KEY]: 'route' },
+        '',
+        this._base + normalized + hash
+      );
       this._resolve();
     }
     return this;
@@ -3776,6 +4174,80 @@ class Router {
     return () => this._listeners.delete(fn);
   }
 
+  // --- Sub-route history substates -----------------------------------------
+
+  /**
+   * Push a lightweight history entry for in-component UI state.
+   * The URL path does NOT change — only a history entry is added so the
+   * back button can undo the UI change (close modal, revert tab, etc.)
+   * before navigating away.
+   *
+   * @param {string} key   — identifier (e.g. 'modal', 'tab', 'panel')
+   * @param {*}      data  — arbitrary state (serializable)
+   * @returns {Router}
+   *
+   * @example
+   * // Open a modal and push a substate
+   * router.pushSubstate('modal', { id: 'confirm-delete' });
+   * // User hits back → onSubstate fires → close the modal
+   */
+  pushSubstate(key, data) {
+    this._inSubstate = true;
+    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 },
+        '',
+        window.location.href
+      );
+    } else {
+      window.history.pushState(
+        { [_ZQ_STATE_KEY]: 'substate', key, data },
+        '',
+        window.location.href      // keep same URL
+      );
+    }
+    return this;
+  }
+
+  /**
+   * Register a listener for substate pops (back button on a substate entry).
+   * The callback receives `(key, data)` and should return `true` if it
+   * handled the pop (prevents route resolution). If no listener returns
+   * `true`, normal route resolution proceeds.
+   *
+   * @param {(key: string, data: any, action: string) => boolean|void} fn
+   * @returns {() => void} unsubscribe function
+   *
+   * @example
+   * const unsub = router.onSubstate((key, data) => {
+   *   if (key === 'modal') { closeModal(); return true; }
+   * });
+   */
+  onSubstate(fn) {
+    this._substateListeners.push(fn);
+    return () => {
+      this._substateListeners = this._substateListeners.filter(f => f !== fn);
+    };
+  }
+
+  /**
+   * Fire substate listeners. Returns true if any listener handled it.
+   * @private
+   */
+  _fireSubstate(key, data, action) {
+    for (const fn of this._substateListeners) {
+      try {
+        if (fn(key, data, action) === true) return true;
+      } catch (err) {
+        reportError(ErrorCode.ROUTER_GUARD, 'onSubstate listener threw', { key, data }, err);
+      }
+    }
+    return false;
+  }
+
   // --- Current state -------------------------------------------------------
 
   get current() { return this._current; }
@@ -3836,6 +4308,16 @@ class Router {
   }
 
   async __resolve() {
+    // Check if we're landing on a substate entry (e.g. page refresh on a
+    // substate bookmark, or hash-mode popstate). Fire listeners and bail
+    // if handled — the URL hasn't changed so there's no route to resolve.
+    const histState = window.history.state;
+    if (histState && histState[_ZQ_STATE_KEY] === 'substate') {
+      const handled = this._fireSubstate(histState.key, histState.data, 'resolve');
+      if (handled) return;
+      // No listener handled it — fall through to normal routing
+    }
+
     const fullPath = this.path;
     const [pathPart, queryString] = fullPath.split('?');
     const path = pathPart || '/';
@@ -3863,6 +4345,18 @@ class Router {
     const to = { route: matched, params, query, path };
     const from = this._current;
 
+    // Same-route optimization: if the resolved route is the same component
+    // with the same params, skip the full destroy/mount cycle and just
+    // update props. This prevents flashing and unnecessary DOM churn.
+    if (from && this._instance && matched.component === from.route.component) {
+      const sameParams = JSON.stringify(params) === JSON.stringify(from.params);
+      const sameQuery = JSON.stringify(query) === JSON.stringify(from.query);
+      if (sameParams && sameQuery) {
+        // Identical navigation — nothing to do
+        return;
+      }
+    }
+
     // Run before guards
     for (const guard of this._guards.before) {
       try {
@@ -3881,7 +4375,11 @@ class Router {
             if (rFrag) window.__zqScrollTarget = rFrag;
             window.location.replace('#' + rNorm);
           } else {
-            window.history.replaceState({}, '', this._base + rNorm + rHash);
+            window.history.replaceState(
+              { [_ZQ_STATE_KEY]: 'route' },
+              '',
+              this._base + rNorm + rHash
+            );
           }
           return this.__resolve();
         }
@@ -3904,6 +4402,12 @@ class Router {
 
     // Mount component into outlet
     if (this._el && matched.component) {
+      // Pre-load external templates/styles so the mount renders synchronously
+      // (keeps old content visible during the fetch instead of showing blank)
+      if (typeof matched.component === 'string') {
+        await prefetch(matched.component);
+      }
+
       // Destroy previous
       if (this._instance) {
         this._instance.destroy();
@@ -3911,6 +4415,7 @@ class Router {
       }
 
       // Create container
+      const _routeStart = typeof window !== 'undefined' && window.__zqRenderHook ? performance.now() : 0;
       this._el.innerHTML = '';
 
       // Pass route params and query as props
@@ -3921,10 +4426,12 @@ class Router {
         const container = document.createElement(matched.component);
         this._el.appendChild(container);
         this._instance = mount(container, matched.component, props);
+        if (_routeStart) window.__zqRenderHook(this._el, performance.now() - _routeStart, 'route', matched.component);
       }
       // If component is a render function
       else if (typeof matched.component === 'function') {
         this._el.innerHTML = matched.component(to);
+        if (_routeStart) window.__zqRenderHook(this._el, performance.now() - _routeStart, 'route', to);
       }
     }
 
@@ -3942,6 +4449,8 @@ class Router {
   destroy() {
     if (this._instance) this._instance.destroy();
     this._listeners.clear();
+    this._substateListeners = [];
+    this._inSubstate = false;
     this._routes = [];
     this._guards = { before: [], after: [] };
   }
@@ -4704,8 +5213,10 @@ $.mountAll    = mountAll;
 $.getInstance = getInstance;
 $.destroy     = destroy;
 $.components  = getRegistry;
+$.prefetch    = prefetch;
 $.style       = style;
-$.morph       = morph;
+$.morph        = morph;
+$.morphElement = morphElement;
 $.safeEval    = safeEval;
 
 // --- Router ----------------------------------------------------------------
@@ -4746,12 +5257,15 @@ $.session    = session;
 $.bus        = bus;
 
 // --- Error handling --------------------------------------------------------
-$.onError     = onError;
-$.ZQueryError = ZQueryError;
-$.ErrorCode   = ErrorCode;
+$.onError        = onError;
+$.ZQueryError    = ZQueryError;
+$.ErrorCode      = ErrorCode;
+$.guardCallback  = guardCallback;
+$.validate       = validate;
 
 // --- Meta ------------------------------------------------------------------
-$.version = '0.7.5';
+$.version = '0.8.7';
+$.libSize = '~89 KB';
 $.meta    = {};                // populated at build time by CLI bundler
 
 $.noConflict = () => {