zero-query 0.6.3 → 0.8.6

package/dist/zquery.js

@@ -1,13 +1,13 @@
 /**
- * zQuery (zeroQuery) v0.6.3
+ * zQuery (zeroQuery) v0.8.6
  * Lightweight Frontend Library
  * https://github.com/tonywied17/zero-query
- * (c) 2026 Anthony Wiedman — MIT License
+ * (c) 2026 Anthony Wiedman - MIT License
  */
 (function(global) {
   'use strict';
 
-// --- src/errors.js ———————————————————————————————————————————————
+// --- src/errors.js -----------------------------------------------
 /**
  * zQuery Errors — Structured error handling system
  *
@@ -164,7 +164,7 @@ function validate(value, name, expectedType) {
   }
 }
 
-// --- src/reactive.js —————————————————————————————————————————————
+// --- src/reactive.js ---------------------------------------------
 /**
  * zQuery Reactive — Proxy-based deep reactivity system
  * 
@@ -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,14 +330,24 @@ 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;
   };
 }
 
-// --- src/core.js —————————————————————————————————————————————————
+// --- src/core.js -------------------------------------------------
 /**
  * zQuery Core — Selector engine & chainable DOM collection
  * 
@@ -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
 // ---------------------------------------------------------------------------
@@ -393,8 +426,96 @@ class ZQueryCollection {
     return new ZQueryCollection(sibs);
   }
 
-  next()  { return new ZQueryCollection(this.elements.map(el => el.nextElementSibling).filter(Boolean)); }
-  prev()  { return new ZQueryCollection(this.elements.map(el => el.previousElementSibling).filter(Boolean)); }
+  next(selector)  {
+    const els = this.elements.map(el => el.nextElementSibling).filter(Boolean);
+    return new ZQueryCollection(selector ? els.filter(el => el.matches(selector)) : els);
+  }
+
+  prev(selector)  {
+    const els = this.elements.map(el => el.previousElementSibling).filter(Boolean);
+    return new ZQueryCollection(selector ? els.filter(el => el.matches(selector)) : els);
+  }
+
+  nextAll(selector) {
+    const result = [];
+    this.elements.forEach(el => {
+      let sib = el.nextElementSibling;
+      while (sib) {
+        if (!selector || sib.matches(selector)) result.push(sib);
+        sib = sib.nextElementSibling;
+      }
+    });
+    return new ZQueryCollection(result);
+  }
+
+  nextUntil(selector, filter) {
+    const result = [];
+    this.elements.forEach(el => {
+      let sib = el.nextElementSibling;
+      while (sib) {
+        if (selector && sib.matches(selector)) break;
+        if (!filter || sib.matches(filter)) result.push(sib);
+        sib = sib.nextElementSibling;
+      }
+    });
+    return new ZQueryCollection(result);
+  }
+
+  prevAll(selector) {
+    const result = [];
+    this.elements.forEach(el => {
+      let sib = el.previousElementSibling;
+      while (sib) {
+        if (!selector || sib.matches(selector)) result.push(sib);
+        sib = sib.previousElementSibling;
+      }
+    });
+    return new ZQueryCollection(result);
+  }
+
+  prevUntil(selector, filter) {
+    const result = [];
+    this.elements.forEach(el => {
+      let sib = el.previousElementSibling;
+      while (sib) {
+        if (selector && sib.matches(selector)) break;
+        if (!filter || sib.matches(filter)) result.push(sib);
+        sib = sib.previousElementSibling;
+      }
+    });
+    return new ZQueryCollection(result);
+  }
+
+  parents(selector) {
+    const result = [];
+    this.elements.forEach(el => {
+      let parent = el.parentElement;
+      while (parent) {
+        if (!selector || parent.matches(selector)) result.push(parent);
+        parent = parent.parentElement;
+      }
+    });
+    return new ZQueryCollection([...new Set(result)]);
+  }
+
+  parentsUntil(selector, filter) {
+    const result = [];
+    this.elements.forEach(el => {
+      let parent = el.parentElement;
+      while (parent) {
+        if (selector && parent.matches(selector)) break;
+        if (!filter || parent.matches(filter)) result.push(parent);
+        parent = parent.parentElement;
+      }
+    });
+    return new ZQueryCollection([...new Set(result)]);
+  }
+
+  contents() {
+    const result = [];
+    this.elements.forEach(el => result.push(...el.childNodes));
+    return new ZQueryCollection(result);
+  }
 
   filter(selector) {
     if (typeof selector === 'function') {
@@ -414,20 +535,85 @@ class ZQueryCollection {
     return new ZQueryCollection(this.elements.filter(el => el.querySelector(selector)));
   }
 
+  is(selector) {
+    if (typeof selector === 'function') {
+      return this.elements.some((el, i) => selector.call(el, i, el));
+    }
+    return this.elements.some(el => el.matches(selector));
+  }
+
+  slice(start, end) {
+    return new ZQueryCollection(this.elements.slice(start, end));
+  }
+
+  add(selector, context) {
+    const toAdd = (selector instanceof ZQueryCollection)
+      ? selector.elements
+      : (selector instanceof Node)
+        ? [selector]
+        : Array.from((context || document).querySelectorAll(selector));
+    return new ZQueryCollection([...this.elements, ...toAdd]);
+  }
+
+  get(index) {
+    if (index === undefined) return [...this.elements];
+    return index < 0 ? this.elements[this.length + index] : this.elements[index];
+  }
+
+  index(selector) {
+    if (selector === undefined) {
+      const el = this.first();
+      return el ? Array.from(el.parentElement.children).indexOf(el) : -1;
+    }
+    const target = (typeof selector === 'string')
+      ? document.querySelector(selector)
+      : selector;
+    return this.elements.indexOf(target);
+  }
+
   // --- 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(name, force) {
-    return this.each((_, el) => el.classList.toggle(name, force));
+  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+/));
+    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) {
@@ -463,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));
   }
@@ -481,11 +668,79 @@ class ZQueryCollection {
     return el ? { top: el.offsetTop, left: el.offsetLeft } : null;
   }
 
+  scrollTop(value) {
+    if (value === undefined) {
+      const el = this.first();
+      return el === window ? window.scrollY : el?.scrollTop;
+    }
+    return this.each((_, el) => {
+      if (el === window) window.scrollTo(window.scrollX, value);
+      else el.scrollTop = value;
+    });
+  }
+
+  scrollLeft(value) {
+    if (value === undefined) {
+      const el = this.first();
+      return el === window ? window.scrollX : el?.scrollLeft;
+    }
+    return this.each((_, el) => {
+      if (el === window) window.scrollTo(value, window.scrollY);
+      else el.scrollLeft = value;
+    });
+  }
+
+  innerWidth() {
+    const el = this.first();
+    return el?.clientWidth;
+  }
+
+  innerHeight() {
+    const el = this.first();
+    return el?.clientHeight;
+  }
+
+  outerWidth(includeMargin = false) {
+    const el = this.first();
+    if (!el) return undefined;
+    let w = el.offsetWidth;
+    if (includeMargin) {
+      const style = getComputedStyle(el);
+      w += parseFloat(style.marginLeft) + parseFloat(style.marginRight);
+    }
+    return w;
+  }
+
+  outerHeight(includeMargin = false) {
+    const el = this.first();
+    if (!el) return undefined;
+    let h = el.offsetHeight;
+    if (includeMargin) {
+      const style = getComputedStyle(el);
+      h += parseFloat(style.marginTop) + parseFloat(style.marginBottom);
+    }
+    return h;
+  }
+
   // --- Content -------------------------------------------------------------
 
   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) {
@@ -542,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) {
@@ -552,14 +808,82 @@ 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);
       }
     });
   }
 
+  appendTo(target) {
+    const dest = typeof target === 'string' ? document.querySelector(target) : target instanceof ZQueryCollection ? target.first() : target;
+    if (dest) this.each((_, el) => dest.appendChild(el));
+    return this;
+  }
+
+  prependTo(target) {
+    const dest = typeof target === 'string' ? document.querySelector(target) : target instanceof ZQueryCollection ? target.first() : target;
+    if (dest) this.each((_, el) => dest.insertBefore(el, dest.firstChild));
+    return this;
+  }
+
+  insertAfter(target) {
+    const ref = typeof target === 'string' ? document.querySelector(target) : target instanceof ZQueryCollection ? target.first() : target;
+    if (ref && ref.parentNode) this.each((_, el) => ref.parentNode.insertBefore(el, ref.nextSibling));
+    return this;
+  }
+
+  insertBefore(target) {
+    const ref = typeof target === 'string' ? document.querySelector(target) : target instanceof ZQueryCollection ? target.first() : target;
+    if (ref && ref.parentNode) this.each((_, el) => ref.parentNode.insertBefore(el, ref));
+    return this;
+  }
+
+  replaceAll(target) {
+    const targets = typeof target === 'string'
+      ? Array.from(document.querySelectorAll(target))
+      : target instanceof ZQueryCollection ? target.elements : [target];
+    targets.forEach((t, i) => {
+      const nodes = i === 0 ? this.elements : this.elements.map(el => el.cloneNode(true));
+      nodes.forEach(el => t.parentNode.insertBefore(el, t));
+      t.remove();
+    });
+    return this;
+  }
+
+  unwrap(selector) {
+    this.elements.forEach(el => {
+      const parent = el.parentElement;
+      if (!parent || parent === document.body) return;
+      if (selector && !parent.matches(selector)) return;
+      parent.replaceWith(...parent.childNodes);
+    });
+    return this;
+  }
+
+  wrapAll(wrapper) {
+    const w = typeof wrapper === 'string' ? createFragment(wrapper).firstElementChild : wrapper.cloneNode(true);
+    const first = this.first();
+    if (!first) return this;
+    first.parentNode.insertBefore(w, first);
+    this.each((_, el) => w.appendChild(el));
+    return this;
+  }
+
+  wrapInner(wrapper) {
+    return this.each((_, el) => {
+      const w = typeof wrapper === 'string' ? createFragment(wrapper).firstElementChild : wrapper.cloneNode(true);
+      while (el.firstChild) w.appendChild(el.firstChild);
+      el.appendChild(w);
+    });
+  }
+
+  detach() {
+    return this.each((_, el) => el.remove());
+  }
+
   // --- Visibility ----------------------------------------------------------
 
   show(display = '') {
@@ -572,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';
     });
   }
 
@@ -585,9 +911,10 @@ class ZQueryCollection {
       events.forEach(evt => {
         if (typeof selectorOrHandler === 'function') {
           el.addEventListener(evt, selectorOrHandler);
-        } else {
-          // Delegated event
+        } else if (typeof selectorOrHandler === 'string') {
+          // Delegated event — only works on elements that support closest()
           el.addEventListener(evt, (e) => {
+            if (!e.target || typeof e.target.closest !== 'function') return;
             const target = e.target.closest(selectorOrHandler);
             if (target && el.contains(target)) handler.call(target, e);
           });
@@ -620,6 +947,10 @@ class ZQueryCollection {
   submit(fn)  { return fn ? this.on('submit', fn) : this.trigger('submit'); }
   focus()     { this.first()?.focus(); return this; }
   blur()      { this.first()?.blur(); return this; }
+  hover(enterFn, leaveFn) {
+    this.on('mouseenter', enterFn);
+    return this.on('mouseleave', leaveFn || enterFn);
+  }
 
   // --- Animation -----------------------------------------------------------
 
@@ -651,6 +982,40 @@ class ZQueryCollection {
     return this.animate({ opacity: '0' }, duration).then(col => col.hide());
   }
 
+  fadeToggle(duration = 300) {
+    return Promise.all(this.elements.map(el => {
+      const visible = getComputedStyle(el).opacity !== '0' && getComputedStyle(el).display !== 'none';
+      const col = new ZQueryCollection([el]);
+      return visible ? col.fadeOut(duration) : col.fadeIn(duration);
+    })).then(() => this);
+  }
+
+  fadeTo(duration, opacity) {
+    return this.animate({ opacity: String(opacity) }, duration);
+  }
+
+  slideDown(duration = 300) {
+    return this.each((_, el) => {
+      el.style.display = '';
+      el.style.overflow = 'hidden';
+      const h = el.scrollHeight + 'px';
+      el.style.maxHeight = '0';
+      el.style.transition = `max-height ${duration}ms ease`;
+      requestAnimationFrame(() => { el.style.maxHeight = h; });
+      setTimeout(() => { el.style.maxHeight = ''; el.style.overflow = ''; el.style.transition = ''; }, duration);
+    });
+  }
+
+  slideUp(duration = 300) {
+    return this.each((_, el) => {
+      el.style.overflow = 'hidden';
+      el.style.maxHeight = el.scrollHeight + 'px';
+      el.style.transition = `max-height ${duration}ms ease`;
+      requestAnimationFrame(() => { el.style.maxHeight = '0'; });
+      setTimeout(() => { el.style.display = 'none'; el.style.maxHeight = ''; el.style.overflow = ''; el.style.transition = ''; }, duration);
+    });
+  }
+
   slideToggle(duration = 300) {
     return this.each((_, el) => {
       if (el.style.display === 'none' || getComputedStyle(el).display === 'none') {
@@ -798,7 +1163,7 @@ query.children = (parentId) => {
   return new ZQueryCollection(p ? Array.from(p.children) : []);
 };
 
-// Create element shorthand
+// Create element shorthand — returns ZQueryCollection for chaining
 query.create = (tag, attrs = {}, ...children) => {
   const el = document.createElement(tag);
   for (const [k, v] of Object.entries(attrs)) {
@@ -812,7 +1177,7 @@ query.create = (tag, attrs = {}, ...children) => {
     if (typeof child === 'string') el.appendChild(document.createTextNode(child));
     else if (child instanceof Node) el.appendChild(child);
   });
-  return el;
+  return new ZQueryCollection(el);
 };
 
 // DOM ready
@@ -821,17 +1186,24 @@ query.ready = (fn) => {
   else document.addEventListener('DOMContentLoaded', fn);
 };
 
-// Global event listeners — supports direct and delegated forms
+// Global event listeners — supports direct, delegated, and target-bound forms
 //   $.on('keydown', handler)           → direct listener on document
 //   $.on('click', '.btn', handler)     → delegated via closest()
+//   $.on('scroll', window, handler)    → direct listener on target
 query.on = (event, selectorOrHandler, handler) => {
   if (typeof selectorOrHandler === 'function') {
     // 2-arg: direct document listener (keydown, resize, etc.)
     document.addEventListener(event, selectorOrHandler);
     return;
   }
-  // 3-arg: delegated
+  // EventTarget (window, element, etc.) — direct listener on target
+  if (typeof selectorOrHandler === 'object' && typeof selectorOrHandler.addEventListener === 'function') {
+    selectorOrHandler.addEventListener(event, handler);
+    return;
+  }
+  // 3-arg string: delegated
   document.addEventListener(event, (e) => {
+    if (!e.target || typeof e.target.closest !== 'function') return;
     const target = e.target.closest(selectorOrHandler);
     if (target) handler.call(target, e);
   });
@@ -845,7 +1217,7 @@ query.off = (event, handler) => {
 // Extend collection prototype (like $.fn in jQuery)
 query.fn = ZQueryCollection.prototype;
 
-// --- src/expression.js ———————————————————————————————————————————
+// --- src/expression.js -------------------------------------------
 /**
  * zQuery Expression Parser — CSP-safe expression evaluator
  *
@@ -1637,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) {
@@ -1653,7 +2055,7 @@ function safeEval(expr, scope) {
   }
 }
 
-// --- src/diff.js —————————————————————————————————————————————————
+// --- src/diff.js -------------------------------------------------
 /**
  * zQuery Diff — Lightweight DOM morphing engine
  *
@@ -1663,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
 // ---------------------------------------------------------------------------
@@ -1677,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;
 }
 
 /**
@@ -1695,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];
-
-  // Build key maps for keyed element matching
-  const oldKeyMap = new Map();
-  const newKeyMap = new Map();
-
-  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 < newChildren.length; i++) {
-    const key = _getKey(newChildren[i]);
-    if (key != null) newKeyMap.set(key, i);
+  // 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];
+
+  // Scan for keyed elements — only build maps if keys exist
+  let hasKeys = false;
+  let oldKeyMap, newKeyMap;
+
+  for (let i = 0; i < oldLen; i++) {
+    if (_getKey(oldChildren[i]) != null) { hasKeys = true; break; }
+  }
+  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);
@@ -1724,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)) {
@@ -1764,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++) {
@@ -1787,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 {
@@ -1807,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) {
@@ -1830,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.
  */
@@ -1856,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);
@@ -1872,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;
@@ -1887,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);
     }
   }
 }
@@ -1927,15 +2503,39 @@ 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 ————————————————————————————————————————————
+// --- src/component.js --------------------------------------------
 /**
  * zQuery Component — Lightweight reactive component system
  * 
@@ -2276,7 +2876,7 @@ class Component {
       // 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) };
+        return { ...item, label: item.label || _titleCase(item.id) };
       });
 
       // Build URL map for lazy per-page loading.
@@ -2318,11 +2918,14 @@ class Component {
     if (def.styleUrl && !def._styleLoaded) {
       const su = def.styleUrl;
       if (typeof su === 'string') {
-        def._externalStyles = await _fetchResource(_resolveUrl(su, base));
+        const resolved = _resolveUrl(su, base);
+        def._externalStyles = await _fetchResource(resolved);
+        def._resolvedStyleUrls = [resolved];
       } else if (Array.isArray(su)) {
         const urls = su.map(u => _resolveUrl(u, base));
         const results = await Promise.all(urls.map(u => _fetchResource(u)));
         def._externalStyles = results.join('\n');
+        def._resolvedStyleUrls = urls;
       }
       def._styleLoaded = true;
     }
@@ -2406,6 +3009,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
@@ -2449,6 +3057,13 @@ class Component {
       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);
       this._styleEl = styleEl;
     }
@@ -2488,8 +3103,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);
     }
@@ -2532,31 +3149,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('.');
@@ -2572,12 +3189,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)
@@ -2585,7 +3235,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
@@ -2655,7 +3307,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
@@ -2694,7 +3346,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') {
@@ -2716,6 +3368,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;
@@ -2835,6 +3492,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
   // ---------------------------------------------------------------------------
@@ -2887,25 +3579,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 => {
@@ -2937,21 +3640,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 => {
@@ -2984,6 +3675,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 = '';
@@ -3134,6 +3827,36 @@ 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, styleUrl, and normalize pages config
+  if ((def.templateUrl && !def._templateLoaded) ||
+      (def.styleUrl && !def._styleLoaded) ||
+      (def.pages && !def._pagesNormalized)) {
+    await Component.prototype._loadExternals.call({ _def: def });
+  }
+
+  // For pages-based components, prefetch ALL page templates so any
+  // active page renders instantly on mount.
+  if (def._pageUrls && def._externalTemplates) {
+    const missing = Object.entries(def._pageUrls)
+      .filter(([id]) => !(id in def._externalTemplates));
+    if (missing.length) {
+      const results = await Promise.all(missing.map(([, url]) => _fetchResource(url)));
+      missing.forEach(([id], i) => { def._externalTemplates[id] = results[i]; });
+    }
+  }
+}
+
 
 // ---------------------------------------------------------------------------
 // Global stylesheet loader
@@ -3235,12 +3958,13 @@ function style(urls, opts = {}) {
   };
 }
 
-// --- src/router.js ———————————————————————————————————————————————
+// --- src/router.js -----------------------------------------------
 /**
  * zQuery Router — Client-side SPA router
  * 
  * 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({
@@ -3257,6 +3981,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;
@@ -3290,6 +4017,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;
@@ -3304,7 +4035,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
@@ -3315,7 +4060,21 @@ class Router {
       if (!link) return;
       if (link.getAttribute('target') === '_blank') return;
       e.preventDefault();
-      this.navigate(link.getAttribute('z-link'));
+      let href = link.getAttribute('z-link');
+      // Support z-link-params for dynamic :param interpolation
+      const paramsAttr = link.getAttribute('z-link-params');
+      if (paramsAttr) {
+        try {
+          const params = JSON.parse(paramsAttr);
+          href = this._interpolateParams(href, params);
+        } catch { /* ignore malformed JSON */ }
+      }
+      this.navigate(href);
+      // z-to-top modifier: scroll to top after navigation
+      if (link.hasAttribute('z-to-top')) {
+        const scrollBehavior = link.getAttribute('z-to-top') || 'instant';
+        window.scrollTo({ top: 0, behavior: scrollBehavior });
+      }
     });
 
     // Initial resolve
@@ -3359,7 +4118,36 @@ class Router {
 
   // --- Navigation ----------------------------------------------------------
 
+  /**
+   * Interpolate :param placeholders in a path with the given values.
+   * @param {string} path — e.g. '/user/:id/posts/:pid'
+   * @param {Object} params — e.g. { id: 42, pid: 7 }
+   * @returns {string}
+   */
+  _interpolateParams(path, params) {
+    if (!params || typeof params !== 'object') return path;
+    return path.replace(/:([\w]+)/g, (_, key) => {
+      const val = params[key];
+      return val != null ? encodeURIComponent(String(val)) : ':' + key;
+    });
+  }
+
+  /**
+   * 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);
     // Separate hash fragment (e.g. /docs/getting-started#cli-bundler)
     const [cleanPath, fragment] = (path || '').split('#');
     let normalized = this._normalizePath(cleanPath);
@@ -3368,15 +4156,56 @@ 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;
   }
 
   replace(path, options = {}) {
+    // Interpolate :param placeholders if options.params is provided
+    if (options.params) path = this._interpolateParams(path, options.params);
     const [cleanPath, fragment] = (path || '').split('#');
     let normalized = this._normalizePath(cleanPath);
     const hash = fragment ? '#' + fragment : '';
@@ -3384,7 +4213,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;
@@ -3439,6 +4272,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; }
@@ -3490,6 +4397,7 @@ class Router {
     // Prevent re-entrant calls (e.g. listener triggering navigation)
     if (this._resolving) return;
     this._resolving = true;
+    this._redirectCount = 0;
     try {
       await this.__resolve();
     } finally {
@@ -3498,6 +4406,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 || '/';
@@ -3525,13 +4443,43 @@ 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 {
         const result = await guard(to, from);
         if (result === false) return;                    // Cancel
         if (typeof result === 'string') {                // Redirect
-          return this.navigate(result);
+          if (++this._redirectCount > 10) {
+            reportError(ErrorCode.ROUTER_GUARD, 'Too many guard redirects (possible loop)', { to }, null);
+            return;
+          }
+          // Update URL directly and re-resolve (avoids re-entrancy block)
+          const [rPath, rFrag] = result.split('#');
+          const rNorm = this._normalizePath(rPath || '/');
+          const rHash = rFrag ? '#' + rFrag : '';
+          if (this._mode === 'hash') {
+            if (rFrag) window.__zqScrollTarget = rFrag;
+            window.location.replace('#' + rNorm);
+          } else {
+            window.history.replaceState(
+              { [_ZQ_STATE_KEY]: 'route' },
+              '',
+              this._base + rNorm + rHash
+            );
+          }
+          return this.__resolve();
         }
       } catch (err) {
         reportError(ErrorCode.ROUTER_GUARD, 'Before-guard threw', { to, from }, err);
@@ -3552,6 +4500,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();
@@ -3559,6 +4513,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
@@ -3569,10 +4524,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);
       }
     }
 
@@ -3590,6 +4547,8 @@ class Router {
   destroy() {
     if (this._instance) this._instance.destroy();
     this._listeners.clear();
+    this._substateListeners = [];
+    this._inSubstate = false;
     this._routes = [];
     this._guards = { before: [], after: [] };
   }
@@ -3610,7 +4569,7 @@ function getRouter() {
   return _activeRouter;
 }
 
-// --- src/store.js ————————————————————————————————————————————————
+// --- src/store.js ------------------------------------------------
 /**
  * zQuery Store — Global reactive state management
  * 
@@ -3796,7 +4755,7 @@ function getStore(name = 'default') {
   return _stores.get(name) || null;
 }
 
-// --- src/http.js —————————————————————————————————————————————————
+// --- src/http.js -------------------------------------------------
 /**
  * zQuery HTTP — Lightweight fetch wrapper
  * 
@@ -3983,7 +4942,7 @@ const http = {
   raw: (url, opts) => fetch(url, opts),
 };
 
-// --- src/utils.js ————————————————————————————————————————————————
+// --- src/utils.js ------------------------------------------------
 /**
  * zQuery Utils — Common utility functions
  * 
@@ -4256,7 +5215,7 @@ class EventBus {
 
 const bus = new EventBus();
 
-// --- index.js (assembly) ——————————————————————————————————————————
+// --- index.js (assembly) ------------------------------------------
 /**
  * ┌---------------------------------------------------------┐
  * │  zQuery (zeroQuery) — Lightweight Frontend Library     │
@@ -4352,8 +5311,10 @@ $.mountAll    = mountAll;
 $.getInstance = getInstance;
 $.destroy     = destroy;
 $.components  = getRegistry;
+$.prefetch    = prefetch;
 $.style       = style;
-$.morph       = morph;
+$.morph        = morph;
+$.morphElement = morphElement;
 $.safeEval    = safeEval;
 
 // --- Router ----------------------------------------------------------------
@@ -4394,12 +5355,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.6.3';
+$.version = '0.8.6';
+$.libSize = '~91 KB';
 $.meta    = {};                // populated at build time by CLI bundler
 
 $.noConflict = () => {