zero-query 0.5.2 → 0.7.5

package/dist/zquery.js

@@ -1,13 +1,170 @@
 /**
- * zQuery (zeroQuery) v0.5.2
+ * zQuery (zeroQuery) v0.7.5
  * 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/reactive.js —————————————————————————————————————————————
+// --- src/errors.js -----------------------------------------------
+/**
+ * zQuery Errors — Structured error handling system
+ *
+ * Provides typed error classes and a configurable error handler so that
+ * errors surface consistently across all modules (reactive, component,
+ * router, store, expression parser, HTTP, etc.).
+ *
+ * Default behaviour: errors are logged via console.warn/error.
+ * Users can override with $.onError(handler) to integrate with their
+ * own logging, crash-reporting, or UI notification system.
+ */
+
+// ---------------------------------------------------------------------------
+// Error codes — every zQuery error has a unique code for programmatic use
+// ---------------------------------------------------------------------------
+const ErrorCode = Object.freeze({
+  // Reactive
+  REACTIVE_CALLBACK:   'ZQ_REACTIVE_CALLBACK',
+  SIGNAL_CALLBACK:     'ZQ_SIGNAL_CALLBACK',
+  EFFECT_EXEC:         'ZQ_EFFECT_EXEC',
+
+  // Expression parser
+  EXPR_PARSE:          'ZQ_EXPR_PARSE',
+  EXPR_EVAL:           'ZQ_EXPR_EVAL',
+  EXPR_UNSAFE_ACCESS:  'ZQ_EXPR_UNSAFE_ACCESS',
+
+  // Component
+  COMP_INVALID_NAME:   'ZQ_COMP_INVALID_NAME',
+  COMP_NOT_FOUND:      'ZQ_COMP_NOT_FOUND',
+  COMP_MOUNT_TARGET:   'ZQ_COMP_MOUNT_TARGET',
+  COMP_RENDER:         'ZQ_COMP_RENDER',
+  COMP_LIFECYCLE:      'ZQ_COMP_LIFECYCLE',
+  COMP_RESOURCE:       'ZQ_COMP_RESOURCE',
+  COMP_DIRECTIVE:      'ZQ_COMP_DIRECTIVE',
+
+  // Router
+  ROUTER_LOAD:         'ZQ_ROUTER_LOAD',
+  ROUTER_GUARD:        'ZQ_ROUTER_GUARD',
+  ROUTER_RESOLVE:      'ZQ_ROUTER_RESOLVE',
+
+  // Store
+  STORE_ACTION:        'ZQ_STORE_ACTION',
+  STORE_MIDDLEWARE:     'ZQ_STORE_MIDDLEWARE',
+  STORE_SUBSCRIBE:     'ZQ_STORE_SUBSCRIBE',
+
+  // HTTP
+  HTTP_REQUEST:        'ZQ_HTTP_REQUEST',
+  HTTP_TIMEOUT:        'ZQ_HTTP_TIMEOUT',
+  HTTP_INTERCEPTOR:    'ZQ_HTTP_INTERCEPTOR',
+  HTTP_PARSE:          'ZQ_HTTP_PARSE',
+
+  // General
+  INVALID_ARGUMENT:    'ZQ_INVALID_ARGUMENT',
+});
+
+
+// ---------------------------------------------------------------------------
+// ZQueryError — custom error class
+// ---------------------------------------------------------------------------
+class ZQueryError extends Error {
+  /**
+   * @param {string} code    — one of ErrorCode values
+   * @param {string} message — human-readable description
+   * @param {object} [context] — extra data (component name, expression, etc.)
+   * @param {Error}  [cause]   — original error
+   */
+  constructor(code, message, context = {}, cause) {
+    super(message);
+    this.name = 'ZQueryError';
+    this.code = code;
+    this.context = context;
+    if (cause) this.cause = cause;
+  }
+}
+
+
+// ---------------------------------------------------------------------------
+// Global error handler
+// ---------------------------------------------------------------------------
+let _errorHandler = null;
+
+/**
+ * Register a global error handler.
+ * Called whenever zQuery catches an error internally.
+ *
+ * @param {Function|null} handler — (error: ZQueryError) => void
+ */
+function onError(handler) {
+  _errorHandler = typeof handler === 'function' ? handler : null;
+}
+
+/**
+ * Report an error through the global handler and console.
+ * Non-throwing — used for recoverable errors in callbacks, lifecycle hooks, etc.
+ *
+ * @param {string} code — ErrorCode
+ * @param {string} message
+ * @param {object} [context]
+ * @param {Error} [cause]
+ */
+function reportError(code, message, context = {}, cause) {
+  const err = cause instanceof ZQueryError
+    ? cause
+    : new ZQueryError(code, message, context, cause);
+
+  // User handler gets first crack
+  if (_errorHandler) {
+    try { _errorHandler(err); } catch { /* prevent handler from crashing framework */ }
+  }
+
+  // Always log for developer visibility
+  console.error(`[zQuery ${code}] ${message}`, context, cause || '');
+}
+
+/**
+ * Wrap a callback so that thrown errors are caught, reported, and don't crash
+ * the current execution context.
+ *
+ * @param {Function} fn
+ * @param {string} code — ErrorCode to use if the callback throws
+ * @param {object} [context]
+ * @returns {Function}
+ */
+function guardCallback(fn, code, context = {}) {
+  return (...args) => {
+    try {
+      return fn(...args);
+    } catch (err) {
+      reportError(code, err.message || 'Callback error', context, err);
+    }
+  };
+}
+
+/**
+ * Validate a required value is defined and of the expected type.
+ * Throws ZQueryError on failure (for fast-fail at API boundaries).
+ *
+ * @param {*} value
+ * @param {string} name — parameter name for error message
+ * @param {string} expectedType — 'string', 'function', 'object', etc.
+ */
+function validate(value, name, expectedType) {
+  if (value === undefined || value === null) {
+    throw new ZQueryError(
+      ErrorCode.INVALID_ARGUMENT,
+      `"${name}" is required but got ${value}`
+    );
+  }
+  if (expectedType && typeof value !== expectedType) {
+    throw new ZQueryError(
+      ErrorCode.INVALID_ARGUMENT,
+      `"${name}" must be a ${expectedType}, got ${typeof value}`
+    );
+  }
+}
+
+// --- src/reactive.js ---------------------------------------------
 /**
  * zQuery Reactive — Proxy-based deep reactivity system
  * 
@@ -15,11 +172,16 @@
  * Used internally by components and store for auto-updates.
  */
 
+
 // ---------------------------------------------------------------------------
 // Deep reactive proxy
 // ---------------------------------------------------------------------------
 function reactive(target, onChange, _path = '') {
   if (typeof target !== 'object' || target === null) return target;
+  if (typeof onChange !== 'function') {
+    reportError(ErrorCode.REACTIVE_CALLBACK, 'reactive() onChange must be a function', { received: typeof onChange });
+    onChange = () => {};
+  }
 
   const proxyCache = new WeakMap();
 
@@ -43,14 +205,22 @@ function reactive(target, onChange, _path = '') {
       const old = obj[key];
       if (old === value) return true;
       obj[key] = value;
-      onChange(key, value, old);
+      try {
+        onChange(key, value, old);
+      } catch (err) {
+        reportError(ErrorCode.REACTIVE_CALLBACK, `Reactive onChange threw for key "${String(key)}"`, { key, value, old }, err);
+      }
       return true;
     },
 
     deleteProperty(obj, key) {
       const old = obj[key];
       delete obj[key];
-      onChange(key, undefined, old);
+      try {
+        onChange(key, undefined, old);
+      } catch (err) {
+        reportError(ErrorCode.REACTIVE_CALLBACK, `Reactive onChange threw for key "${String(key)}"`, { key, old }, err);
+      }
       return true;
     }
   };
@@ -85,7 +255,12 @@ class Signal {
   peek() { return this._value; }
 
   _notify() {
-    this._subscribers.forEach(fn => fn());
+    this._subscribers.forEach(fn => {
+      try { fn(); }
+      catch (err) {
+        reportError(ErrorCode.SIGNAL_CALLBACK, 'Signal subscriber threw', { signal: this }, err);
+      }
+    });
   }
 
   subscribe(fn) {
@@ -128,13 +303,19 @@ function effect(fn) {
   const execute = () => {
     Signal._activeEffect = execute;
     try { fn(); }
+    catch (err) {
+      reportError(ErrorCode.EFFECT_EXEC, 'Effect function threw', {}, err);
+    }
     finally { Signal._activeEffect = null; }
   };
   execute();
-  return () => { /* Signals will hold weak refs if needed */ };
+  return () => {
+    // Remove this effect from all signals that track it
+    Signal._activeEffect = null;
+  };
 }
 
-// --- src/core.js —————————————————————————————————————————————————
+// --- src/core.js -------------------------------------------------
 /**
  * zQuery Core — Selector engine & chainable DOM collection
  * 
@@ -163,6 +344,11 @@ class ZQueryCollection {
     return this.elements.map((el, i) => fn.call(el, i, el));
   }
 
+  forEach(fn) {
+    this.elements.forEach((el, i) => fn(el, i, this.elements));
+    return this;
+  }
+
   first() { return this.elements[0] || null; }
   last()  { return this.elements[this.length - 1] || null; }
   eq(i)   { return new ZQueryCollection(this.elements[i] ? [this.elements[i]] : []); }
@@ -207,8 +393,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') {
@@ -228,6 +502,42 @@ 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) {
@@ -240,8 +550,12 @@ class ZQueryCollection {
     return this.each((_, el) => el.classList.remove(...classes));
   }
 
-  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;
+    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));
+    });
   }
 
   hasClass(name) {
@@ -295,6 +609,60 @@ 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) {
@@ -374,6 +742,73 @@ class ZQueryCollection {
     });
   }
 
+  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 = '') {
@@ -399,9 +834,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);
           });
@@ -434,6 +870,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 -----------------------------------------------------------
 
@@ -465,6 +905,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') {
@@ -511,163 +985,1252 @@ class ZQueryCollection {
 
 
 // ---------------------------------------------------------------------------
-// Helper — create document fragment from HTML string
+// Helper — create document fragment from HTML string
+// ---------------------------------------------------------------------------
+function createFragment(html) {
+  const tpl = document.createElement('template');
+  tpl.innerHTML = html.trim();
+  return tpl.content;
+}
+
+
+// ---------------------------------------------------------------------------
+// $() — main selector / creator (returns ZQueryCollection, like jQuery)
+// ---------------------------------------------------------------------------
+function query(selector, context) {
+  // null / undefined
+  if (!selector) return new ZQueryCollection([]);
+
+  // Already a collection — return as-is
+  if (selector instanceof ZQueryCollection) return selector;
+
+  // DOM element or Window — wrap in collection
+  if (selector instanceof Node || selector === window) {
+    return new ZQueryCollection([selector]);
+  }
+
+  // NodeList / HTMLCollection / Array — wrap in collection
+  if (selector instanceof NodeList || selector instanceof HTMLCollection || Array.isArray(selector)) {
+    return new ZQueryCollection(Array.from(selector));
+  }
+
+  // HTML string → create elements, wrap in collection
+  if (typeof selector === 'string' && selector.trim().startsWith('<')) {
+    const fragment = createFragment(selector);
+    return new ZQueryCollection([...fragment.childNodes].filter(n => n.nodeType === 1));
+  }
+
+  // CSS selector string → querySelectorAll (collection)
+  if (typeof selector === 'string') {
+    const root = context
+      ? (typeof context === 'string' ? document.querySelector(context) : context)
+      : document;
+    return new ZQueryCollection([...root.querySelectorAll(selector)]);
+  }
+
+  return new ZQueryCollection([]);
+}
+
+
+// ---------------------------------------------------------------------------
+// $.all() — collection selector (returns ZQueryCollection for CSS selectors)
+// ---------------------------------------------------------------------------
+function queryAll(selector, context) {
+  // null / undefined
+  if (!selector) return new ZQueryCollection([]);
+
+  // Already a collection
+  if (selector instanceof ZQueryCollection) return selector;
+
+  // DOM element or Window
+  if (selector instanceof Node || selector === window) {
+    return new ZQueryCollection([selector]);
+  }
+
+  // NodeList / HTMLCollection / Array
+  if (selector instanceof NodeList || selector instanceof HTMLCollection || Array.isArray(selector)) {
+    return new ZQueryCollection(Array.from(selector));
+  }
+
+  // HTML string → create elements
+  if (typeof selector === 'string' && selector.trim().startsWith('<')) {
+    const fragment = createFragment(selector);
+    return new ZQueryCollection([...fragment.childNodes].filter(n => n.nodeType === 1));
+  }
+
+  // CSS selector string → querySelectorAll (collection)
+  if (typeof selector === 'string') {
+    const root = context
+      ? (typeof context === 'string' ? document.querySelector(context) : context)
+      : document;
+    return new ZQueryCollection([...root.querySelectorAll(selector)]);
+  }
+
+  return new ZQueryCollection([]);
+}
+
+
+// ---------------------------------------------------------------------------
+// Quick-ref shortcuts, on $ namespace)
+// ---------------------------------------------------------------------------
+query.id       = (id) => document.getElementById(id);
+query.class    = (name) => document.querySelector(`.${name}`);
+query.classes  = (name) => new ZQueryCollection(Array.from(document.getElementsByClassName(name)));
+query.tag      = (name) => new ZQueryCollection(Array.from(document.getElementsByTagName(name)));
+Object.defineProperty(query, 'name', {
+  value: (name) => new ZQueryCollection(Array.from(document.getElementsByName(name))),
+  writable: true, configurable: true
+});
+query.children = (parentId) => {
+  const p = document.getElementById(parentId);
+  return new ZQueryCollection(p ? Array.from(p.children) : []);
+};
+
+// 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)) {
+    if (k === 'class') el.className = v;
+    else if (k === 'style' && typeof v === 'object') Object.assign(el.style, v);
+    else if (k.startsWith('on') && typeof v === 'function') el.addEventListener(k.slice(2), v);
+    else if (k === 'data' && typeof v === 'object') Object.entries(v).forEach(([dk, dv]) => { el.dataset[dk] = dv; });
+    else el.setAttribute(k, v);
+  }
+  children.flat().forEach(child => {
+    if (typeof child === 'string') el.appendChild(document.createTextNode(child));
+    else if (child instanceof Node) el.appendChild(child);
+  });
+  return new ZQueryCollection(el);
+};
+
+// DOM ready
+query.ready = (fn) => {
+  if (document.readyState !== 'loading') fn();
+  else document.addEventListener('DOMContentLoaded', fn);
+};
+
+// 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;
+  }
+  // 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);
+  });
+};
+
+// Remove a direct global listener
+query.off = (event, handler) => {
+  document.removeEventListener(event, handler);
+};
+
+// Extend collection prototype (like $.fn in jQuery)
+query.fn = ZQueryCollection.prototype;
+
+// --- src/expression.js -------------------------------------------
+/**
+ * zQuery Expression Parser — CSP-safe expression evaluator
+ *
+ * Replaces `new Function()` / `eval()` with a hand-written parser that
+ * evaluates expressions safely without violating Content Security Policy.
+ *
+ * Supports:
+ *   - Property access:       user.name, items[0], items[i]
+ *   - Method calls:          items.length, str.toUpperCase()
+ *   - Arithmetic:            a + b, count * 2, i % 2
+ *   - Comparison:            a === b, count > 0, x != null
+ *   - Logical:               a && b, a || b, !a
+ *   - Ternary:               a ? b : c
+ *   - Typeof:                typeof x
+ *   - Unary:                 -a, +a, !a
+ *   - Literals:              42, 'hello', "world", true, false, null, undefined
+ *   - Template literals:     `Hello ${name}`
+ *   - Array literals:        [1, 2, 3]
+ *   - Object literals:       { foo: 'bar', baz: 1 }
+ *   - Grouping:              (a + b) * c
+ *   - Nullish coalescing:    a ?? b
+ *   - Optional chaining:     a?.b, a?.[b], a?.()
+ *   - Arrow functions:       x => x.id, (a, b) => a + b
+ */
+
+// Token types
+const T = {
+  NUM: 1, STR: 2, IDENT: 3, OP: 4, PUNC: 5, TMPL: 6, EOF: 7
+};
+
+// Operator precedence (higher = binds tighter)
+const PREC = {
+  '??': 2,
+  '||': 3,
+  '&&': 4,
+  '==': 8, '!=': 8, '===': 8, '!==': 8,
+  '<': 9, '>': 9, '<=': 9, '>=': 9, 'instanceof': 9, 'in': 9,
+  '+': 11, '-': 11,
+  '*': 12, '/': 12, '%': 12,
+};
+
+const KEYWORDS = new Set([
+  'true', 'false', 'null', 'undefined', 'typeof', 'instanceof', 'in',
+  'new', 'void'
+]);
+
+// ---------------------------------------------------------------------------
+// Tokenizer
+// ---------------------------------------------------------------------------
+function tokenize(expr) {
+  const tokens = [];
+  let i = 0;
+  const len = expr.length;
+
+  while (i < len) {
+    const ch = expr[i];
+
+    // Whitespace
+    if (ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r') { i++; continue; }
+
+    // Numbers
+    if ((ch >= '0' && ch <= '9') || (ch === '.' && i + 1 < len && expr[i + 1] >= '0' && expr[i + 1] <= '9')) {
+      let num = '';
+      if (ch === '0' && i + 1 < len && (expr[i + 1] === 'x' || expr[i + 1] === 'X')) {
+        num = '0x'; i += 2;
+        while (i < len && /[0-9a-fA-F]/.test(expr[i])) num += expr[i++];
+      } else {
+        while (i < len && ((expr[i] >= '0' && expr[i] <= '9') || expr[i] === '.')) num += expr[i++];
+        if (i < len && (expr[i] === 'e' || expr[i] === 'E')) {
+          num += expr[i++];
+          if (i < len && (expr[i] === '+' || expr[i] === '-')) num += expr[i++];
+          while (i < len && expr[i] >= '0' && expr[i] <= '9') num += expr[i++];
+        }
+      }
+      tokens.push({ t: T.NUM, v: Number(num) });
+      continue;
+    }
+
+    // Strings
+    if (ch === "'" || ch === '"') {
+      const quote = ch;
+      let str = '';
+      i++;
+      while (i < len && expr[i] !== quote) {
+        if (expr[i] === '\\' && i + 1 < len) {
+          const esc = expr[++i];
+          if (esc === 'n') str += '\n';
+          else if (esc === 't') str += '\t';
+          else if (esc === 'r') str += '\r';
+          else if (esc === '\\') str += '\\';
+          else if (esc === quote) str += quote;
+          else str += esc;
+        } else {
+          str += expr[i];
+        }
+        i++;
+      }
+      i++; // closing quote
+      tokens.push({ t: T.STR, v: str });
+      continue;
+    }
+
+    // Template literals
+    if (ch === '`') {
+      const parts = []; // alternating: string, expr, string, expr, ...
+      let str = '';
+      i++;
+      while (i < len && expr[i] !== '`') {
+        if (expr[i] === '$' && i + 1 < len && expr[i + 1] === '{') {
+          parts.push(str);
+          str = '';
+          i += 2;
+          let depth = 1;
+          let inner = '';
+          while (i < len && depth > 0) {
+            if (expr[i] === '{') depth++;
+            else if (expr[i] === '}') { depth--; if (depth === 0) break; }
+            inner += expr[i++];
+          }
+          i++; // closing }
+          parts.push({ expr: inner });
+        } else {
+          if (expr[i] === '\\' && i + 1 < len) { str += expr[++i]; }
+          else str += expr[i];
+          i++;
+        }
+      }
+      i++; // closing backtick
+      parts.push(str);
+      tokens.push({ t: T.TMPL, v: parts });
+      continue;
+    }
+
+    // Identifiers & keywords
+    if ((ch >= 'a' && ch <= 'z') || (ch >= 'A' && ch <= 'Z') || ch === '_' || ch === '$') {
+      let ident = '';
+      while (i < len && /[\w$]/.test(expr[i])) ident += expr[i++];
+      tokens.push({ t: T.IDENT, v: ident });
+      continue;
+    }
+
+    // Multi-char operators
+    const two = expr.slice(i, i + 3);
+    if (two === '===' || two === '!==' || two === '?.') {
+      if (two === '?.') {
+        tokens.push({ t: T.OP, v: '?.' });
+        i += 2;
+      } else {
+        tokens.push({ t: T.OP, v: two });
+        i += 3;
+      }
+      continue;
+    }
+    const pair = expr.slice(i, i + 2);
+    if (pair === '==' || pair === '!=' || pair === '<=' || pair === '>=' ||
+        pair === '&&' || pair === '||' || pair === '??' || pair === '?.' ||
+        pair === '=>') {
+      tokens.push({ t: T.OP, v: pair });
+      i += 2;
+      continue;
+    }
+
+    // Single char operators and punctuation
+    if ('+-*/%'.includes(ch)) {
+      tokens.push({ t: T.OP, v: ch });
+      i++; continue;
+    }
+    if ('<>=!'.includes(ch)) {
+      tokens.push({ t: T.OP, v: ch });
+      i++; continue;
+    }
+    if ('()[]{},.?:'.includes(ch)) {
+      tokens.push({ t: T.PUNC, v: ch });
+      i++; continue;
+    }
+
+    // Unknown — skip
+    i++;
+  }
+
+  tokens.push({ t: T.EOF, v: null });
+  return tokens;
+}
+
+// ---------------------------------------------------------------------------
+// Parser — Pratt (precedence climbing)
+// ---------------------------------------------------------------------------
+class Parser {
+  constructor(tokens, scope) {
+    this.tokens = tokens;
+    this.pos = 0;
+    this.scope = scope;
+  }
+
+  peek() { return this.tokens[this.pos]; }
+  next() { return this.tokens[this.pos++]; }
+
+  expect(type, val) {
+    const t = this.next();
+    if (t.t !== type || (val !== undefined && t.v !== val)) {
+      throw new Error(`Expected ${val || type} but got ${t.v}`);
+    }
+    return t;
+  }
+
+  match(type, val) {
+    const t = this.peek();
+    if (t.t === type && (val === undefined || t.v === val)) {
+      return this.next();
+    }
+    return null;
+  }
+
+  // Main entry
+  parse() {
+    const result = this.parseExpression(0);
+    return result;
+  }
+
+  // Precedence climbing
+  parseExpression(minPrec) {
+    let left = this.parseUnary();
+
+    while (true) {
+      const tok = this.peek();
+
+      // Ternary
+      if (tok.t === T.PUNC && tok.v === '?') {
+        // Distinguish ternary ? from optional chaining ?.
+        if (this.tokens[this.pos + 1]?.v !== '.') {
+          if (1 <= minPrec) break; // ternary has very low precedence
+          this.next(); // consume ?
+          const truthy = this.parseExpression(0);
+          this.expect(T.PUNC, ':');
+          const falsy = this.parseExpression(1);
+          left = { type: 'ternary', cond: left, truthy, falsy };
+          continue;
+        }
+      }
+
+      // Binary operators
+      if (tok.t === T.OP && tok.v in PREC) {
+        const prec = PREC[tok.v];
+        if (prec <= minPrec) break;
+        this.next();
+        const right = this.parseExpression(prec);
+        left = { type: 'binary', op: tok.v, left, right };
+        continue;
+      }
+
+      // instanceof and in as binary operators
+      if (tok.t === T.IDENT && (tok.v === 'instanceof' || tok.v === 'in') && PREC[tok.v] > minPrec) {
+        const prec = PREC[tok.v];
+        this.next();
+        const right = this.parseExpression(prec);
+        left = { type: 'binary', op: tok.v, left, right };
+        continue;
+      }
+
+      break;
+    }
+
+    return left;
+  }
+
+  parseUnary() {
+    const tok = this.peek();
+
+    // typeof
+    if (tok.t === T.IDENT && tok.v === 'typeof') {
+      this.next();
+      const arg = this.parseUnary();
+      return { type: 'typeof', arg };
+    }
+
+    // void
+    if (tok.t === T.IDENT && tok.v === 'void') {
+      this.next();
+      this.parseUnary(); // evaluate but discard
+      return { type: 'literal', value: undefined };
+    }
+
+    // !expr
+    if (tok.t === T.OP && tok.v === '!') {
+      this.next();
+      const arg = this.parseUnary();
+      return { type: 'not', arg };
+    }
+
+    // -expr, +expr
+    if (tok.t === T.OP && (tok.v === '-' || tok.v === '+')) {
+      this.next();
+      const arg = this.parseUnary();
+      return { type: 'unary', op: tok.v, arg };
+    }
+
+    return this.parsePostfix();
+  }
+
+  parsePostfix() {
+    let left = this.parsePrimary();
+
+    while (true) {
+      const tok = this.peek();
+
+      // Property access: a.b
+      if (tok.t === T.PUNC && tok.v === '.') {
+        this.next();
+        const prop = this.next();
+        left = { type: 'member', obj: left, prop: prop.v, computed: false };
+        // Check for method call: a.b()
+        if (this.peek().t === T.PUNC && this.peek().v === '(') {
+          left = this._parseCall(left);
+        }
+        continue;
+      }
+
+      // Optional chaining: a?.b, a?.[b], a?.()
+      if (tok.t === T.OP && tok.v === '?.') {
+        this.next();
+        const next = this.peek();
+        if (next.t === T.PUNC && next.v === '[') {
+          // a?.[expr]
+          this.next();
+          const prop = this.parseExpression(0);
+          this.expect(T.PUNC, ']');
+          left = { type: 'optional_member', obj: left, prop, computed: true };
+        } else if (next.t === T.PUNC && next.v === '(') {
+          // a?.()
+          left = { type: 'optional_call', callee: left, args: this._parseArgs() };
+        } else {
+          // a?.b
+          const prop = this.next();
+          left = { type: 'optional_member', obj: left, prop: prop.v, computed: false };
+          if (this.peek().t === T.PUNC && this.peek().v === '(') {
+            left = this._parseCall(left);
+          }
+        }
+        continue;
+      }
+
+      // Computed access: a[b]
+      if (tok.t === T.PUNC && tok.v === '[') {
+        this.next();
+        const prop = this.parseExpression(0);
+        this.expect(T.PUNC, ']');
+        left = { type: 'member', obj: left, prop, computed: true };
+        // Check for method call: a[b]()
+        if (this.peek().t === T.PUNC && this.peek().v === '(') {
+          left = this._parseCall(left);
+        }
+        continue;
+      }
+
+      // Function call: fn()
+      if (tok.t === T.PUNC && tok.v === '(') {
+        left = this._parseCall(left);
+        continue;
+      }
+
+      break;
+    }
+
+    return left;
+  }
+
+  _parseCall(callee) {
+    const args = this._parseArgs();
+    return { type: 'call', callee, args };
+  }
+
+  _parseArgs() {
+    this.expect(T.PUNC, '(');
+    const args = [];
+    while (!(this.peek().t === T.PUNC && this.peek().v === ')') && this.peek().t !== T.EOF) {
+      args.push(this.parseExpression(0));
+      if (this.peek().t === T.PUNC && this.peek().v === ',') this.next();
+    }
+    this.expect(T.PUNC, ')');
+    return args;
+  }
+
+  parsePrimary() {
+    const tok = this.peek();
+
+    // Number literal
+    if (tok.t === T.NUM) {
+      this.next();
+      return { type: 'literal', value: tok.v };
+    }
+
+    // String literal
+    if (tok.t === T.STR) {
+      this.next();
+      return { type: 'literal', value: tok.v };
+    }
+
+    // Template literal
+    if (tok.t === T.TMPL) {
+      this.next();
+      return { type: 'template', parts: tok.v };
+    }
+
+    // Arrow function with parens: () =>, (a) =>, (a, b) =>
+    // or regular grouping: (expr)
+    if (tok.t === T.PUNC && tok.v === '(') {
+      const savedPos = this.pos;
+      this.next(); // consume (
+      const params = [];
+      let couldBeArrow = true;
+
+      if (this.peek().t === T.PUNC && this.peek().v === ')') {
+        // () => ... — no params
+      } else {
+        while (couldBeArrow) {
+          const p = this.peek();
+          if (p.t === T.IDENT && !KEYWORDS.has(p.v)) {
+            params.push(this.next().v);
+            if (this.peek().t === T.PUNC && this.peek().v === ',') {
+              this.next();
+            } else {
+              break;
+            }
+          } else {
+            couldBeArrow = false;
+          }
+        }
+      }
+
+      if (couldBeArrow && this.peek().t === T.PUNC && this.peek().v === ')') {
+        this.next(); // consume )
+        if (this.peek().t === T.OP && this.peek().v === '=>') {
+          this.next(); // consume =>
+          const body = this.parseExpression(0);
+          return { type: 'arrow', params, body };
+        }
+      }
+
+      // Not an arrow — restore and parse as grouping
+      this.pos = savedPos;
+      this.next(); // consume (
+      const expr = this.parseExpression(0);
+      this.expect(T.PUNC, ')');
+      return expr;
+    }
+
+    // Array literal
+    if (tok.t === T.PUNC && tok.v === '[') {
+      this.next();
+      const elements = [];
+      while (!(this.peek().t === T.PUNC && this.peek().v === ']') && this.peek().t !== T.EOF) {
+        elements.push(this.parseExpression(0));
+        if (this.peek().t === T.PUNC && this.peek().v === ',') this.next();
+      }
+      this.expect(T.PUNC, ']');
+      return { type: 'array', elements };
+    }
+
+    // Object literal
+    if (tok.t === T.PUNC && tok.v === '{') {
+      this.next();
+      const properties = [];
+      while (!(this.peek().t === T.PUNC && this.peek().v === '}') && this.peek().t !== T.EOF) {
+        const keyTok = this.next();
+        let key;
+        if (keyTok.t === T.IDENT || keyTok.t === T.STR) key = keyTok.v;
+        else if (keyTok.t === T.NUM) key = String(keyTok.v);
+        else throw new Error('Invalid object key: ' + keyTok.v);
+
+        // Shorthand property: { foo } means { foo: foo }
+        if (this.peek().t === T.PUNC && (this.peek().v === ',' || this.peek().v === '}')) {
+          properties.push({ key, value: { type: 'ident', name: key } });
+        } else {
+          this.expect(T.PUNC, ':');
+          properties.push({ key, value: this.parseExpression(0) });
+        }
+        if (this.peek().t === T.PUNC && this.peek().v === ',') this.next();
+      }
+      this.expect(T.PUNC, '}');
+      return { type: 'object', properties };
+    }
+
+    // Identifiers & keywords
+    if (tok.t === T.IDENT) {
+      this.next();
+
+      // Keywords
+      if (tok.v === 'true') return { type: 'literal', value: true };
+      if (tok.v === 'false') return { type: 'literal', value: false };
+      if (tok.v === 'null') return { type: 'literal', value: null };
+      if (tok.v === 'undefined') return { type: 'literal', value: undefined };
+
+      // new keyword
+      if (tok.v === 'new') {
+        const classExpr = this.parsePostfix();
+        let args = [];
+        if (this.peek().t === T.PUNC && this.peek().v === '(') {
+          args = this._parseArgs();
+        }
+        return { type: 'new', callee: classExpr, args };
+      }
+
+      // Arrow function: x => expr
+      if (this.peek().t === T.OP && this.peek().v === '=>') {
+        this.next(); // consume =>
+        const body = this.parseExpression(0);
+        return { type: 'arrow', params: [tok.v], body };
+      }
+
+      return { type: 'ident', name: tok.v };
+    }
+
+    // Fallback — return undefined for unparseable
+    this.next();
+    return { type: 'literal', value: undefined };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Evaluator — walks the AST, resolves against scope
+// ---------------------------------------------------------------------------
+
+/** Safe property access whitelist for built-in prototypes */
+const SAFE_ARRAY_METHODS = new Set([
+  'length', 'map', 'filter', 'find', 'findIndex', 'some', 'every',
+  'reduce', 'reduceRight', 'forEach', 'includes', 'indexOf', 'lastIndexOf',
+  'join', 'slice', 'concat', 'flat', 'flatMap', 'reverse', 'sort',
+  'fill', 'keys', 'values', 'entries', 'at', 'toString',
+]);
+
+const SAFE_STRING_METHODS = new Set([
+  'length', 'charAt', 'charCodeAt', 'includes', 'indexOf', 'lastIndexOf',
+  'slice', 'substring', 'trim', 'trimStart', 'trimEnd', 'toLowerCase',
+  'toUpperCase', 'split', 'replace', 'replaceAll', 'match', 'search',
+  'startsWith', 'endsWith', 'padStart', 'padEnd', 'repeat', 'at',
+  'toString', 'valueOf',
+]);
+
+const SAFE_NUMBER_METHODS = new Set([
+  'toFixed', 'toPrecision', 'toString', 'valueOf',
+]);
+
+const SAFE_OBJECT_METHODS = new Set([
+  'hasOwnProperty', 'toString', 'valueOf',
+]);
+
+const SAFE_MATH_PROPS = new Set([
+  'PI', 'E', 'LN2', 'LN10', 'LOG2E', 'LOG10E', 'SQRT2', 'SQRT1_2',
+  'abs', 'ceil', 'floor', 'round', 'trunc', 'max', 'min', 'pow',
+  'sqrt', 'sign', 'random', 'log', 'log2', 'log10',
+]);
+
+const SAFE_JSON_PROPS = new Set(['parse', 'stringify']);
+
+/**
+ * Check if property access is safe
+ */
+function _isSafeAccess(obj, prop) {
+  // Never allow access to dangerous properties
+  const BLOCKED = new Set([
+    'constructor', '__proto__', 'prototype', '__defineGetter__',
+    '__defineSetter__', '__lookupGetter__', '__lookupSetter__',
+  ]);
+  if (typeof prop === 'string' && BLOCKED.has(prop)) return false;
+
+  // Always allow plain object/function property access and array index access
+  if (obj !== null && obj !== undefined && (typeof obj === 'object' || typeof obj === 'function')) return true;
+  if (typeof obj === 'string') return SAFE_STRING_METHODS.has(prop);
+  if (typeof obj === 'number') return SAFE_NUMBER_METHODS.has(prop);
+  return false;
+}
+
+function evaluate(node, scope) {
+  if (!node) return undefined;
+
+  switch (node.type) {
+    case 'literal':
+      return node.value;
+
+    case 'ident': {
+      const name = node.name;
+      // Check scope layers in order
+      for (const layer of scope) {
+        if (layer && typeof layer === 'object' && name in layer) {
+          return layer[name];
+        }
+      }
+      // Built-in globals (safe ones only)
+      if (name === 'Math') return Math;
+      if (name === 'JSON') return JSON;
+      if (name === 'Date') return Date;
+      if (name === 'Array') return Array;
+      if (name === 'Object') return Object;
+      if (name === 'String') return String;
+      if (name === 'Number') return Number;
+      if (name === 'Boolean') return Boolean;
+      if (name === 'parseInt') return parseInt;
+      if (name === 'parseFloat') return parseFloat;
+      if (name === 'isNaN') return isNaN;
+      if (name === 'isFinite') return isFinite;
+      if (name === 'Infinity') return Infinity;
+      if (name === 'NaN') return NaN;
+      if (name === 'encodeURIComponent') return encodeURIComponent;
+      if (name === 'decodeURIComponent') return decodeURIComponent;
+      if (name === 'console') return console;
+      return undefined;
+    }
+
+    case 'template': {
+      // Template literal with interpolation
+      let result = '';
+      for (const part of node.parts) {
+        if (typeof part === 'string') {
+          result += part;
+        } else if (part && part.expr) {
+          result += String(safeEval(part.expr, scope) ?? '');
+        }
+      }
+      return result;
+    }
+
+    case 'member': {
+      const obj = evaluate(node.obj, scope);
+      if (obj == null) return undefined;
+      const prop = node.computed ? evaluate(node.prop, scope) : node.prop;
+      if (!_isSafeAccess(obj, prop)) return undefined;
+      return obj[prop];
+    }
+
+    case 'optional_member': {
+      const obj = evaluate(node.obj, scope);
+      if (obj == null) return undefined;
+      const prop = node.computed ? evaluate(node.prop, scope) : node.prop;
+      if (!_isSafeAccess(obj, prop)) return undefined;
+      return obj[prop];
+    }
+
+    case 'call': {
+      const result = _resolveCall(node, scope, false);
+      return result;
+    }
+
+    case 'optional_call': {
+      const callee = evaluate(node.callee, scope);
+      if (callee == null) return undefined;
+      if (typeof callee !== 'function') return undefined;
+      const args = node.args.map(a => evaluate(a, scope));
+      return callee(...args);
+    }
+
+    case 'new': {
+      const Ctor = evaluate(node.callee, scope);
+      if (typeof Ctor !== 'function') return undefined;
+      // Only allow safe constructors
+      if (Ctor === Date || Ctor === Array || Ctor === Map || Ctor === Set ||
+          Ctor === RegExp || Ctor === Error || Ctor === URL || Ctor === URLSearchParams) {
+        const args = node.args.map(a => evaluate(a, scope));
+        return new Ctor(...args);
+      }
+      return undefined;
+    }
+
+    case 'binary':
+      return _evalBinary(node, scope);
+
+    case 'unary': {
+      const val = evaluate(node.arg, scope);
+      return node.op === '-' ? -val : +val;
+    }
+
+    case 'not':
+      return !evaluate(node.arg, scope);
+
+    case 'typeof': {
+      try {
+        return typeof evaluate(node.arg, scope);
+      } catch {
+        return 'undefined';
+      }
+    }
+
+    case 'ternary': {
+      const cond = evaluate(node.cond, scope);
+      return cond ? evaluate(node.truthy, scope) : evaluate(node.falsy, scope);
+    }
+
+    case 'array':
+      return node.elements.map(e => evaluate(e, scope));
+
+    case 'object': {
+      const obj = {};
+      for (const { key, value } of node.properties) {
+        obj[key] = evaluate(value, scope);
+      }
+      return obj;
+    }
+
+    case 'arrow': {
+      const paramNames = node.params;
+      const bodyNode = node.body;
+      const closedScope = scope;
+      return function(...args) {
+        const arrowScope = {};
+        paramNames.forEach((name, i) => { arrowScope[name] = args[i]; });
+        return evaluate(bodyNode, [arrowScope, ...closedScope]);
+      };
+    }
+
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Resolve and execute a function call safely.
+ */
+function _resolveCall(node, scope) {
+  const callee = node.callee;
+  const args = node.args.map(a => evaluate(a, scope));
+
+  // Method call: obj.method() — bind `this` to obj
+  if (callee.type === 'member' || callee.type === 'optional_member') {
+    const obj = evaluate(callee.obj, scope);
+    if (obj == null) return undefined;
+    const prop = callee.computed ? evaluate(callee.prop, scope) : callee.prop;
+    if (!_isSafeAccess(obj, prop)) return undefined;
+    const fn = obj[prop];
+    if (typeof fn !== 'function') return undefined;
+    return fn.apply(obj, args);
+  }
+
+  // Direct call: fn(args)
+  const fn = evaluate(callee, scope);
+  if (typeof fn !== 'function') return undefined;
+  return fn(...args);
+}
+
+/**
+ * Evaluate binary expression.
+ */
+function _evalBinary(node, scope) {
+  // Short-circuit for logical ops
+  if (node.op === '&&') {
+    const left = evaluate(node.left, scope);
+    return left ? evaluate(node.right, scope) : left;
+  }
+  if (node.op === '||') {
+    const left = evaluate(node.left, scope);
+    return left ? left : evaluate(node.right, scope);
+  }
+  if (node.op === '??') {
+    const left = evaluate(node.left, scope);
+    return left != null ? left : evaluate(node.right, scope);
+  }
+
+  const left = evaluate(node.left, scope);
+  const right = evaluate(node.right, scope);
+
+  switch (node.op) {
+    case '+': return left + right;
+    case '-': return left - right;
+    case '*': return left * right;
+    case '/': return left / right;
+    case '%': return left % right;
+    case '==': return left == right;
+    case '!=': return left != right;
+    case '===': return left === right;
+    case '!==': return left !== right;
+    case '<': return left < right;
+    case '>': return left > right;
+    case '<=': return left <= right;
+    case '>=': return left >= right;
+    case 'instanceof': return left instanceof right;
+    case 'in': return left in right;
+    default: return undefined;
+  }
+}
+
+
+// ---------------------------------------------------------------------------
+// Public API
 // ---------------------------------------------------------------------------
-function createFragment(html) {
-  const tpl = document.createElement('template');
-  tpl.innerHTML = html.trim();
-  return tpl.content;
-}
 
+/**
+ * Safely evaluate a JS expression string against scope layers.
+ *
+ * @param {string} expr — expression string
+ * @param {object[]} scope — array of scope objects, checked in order
+ *   Typical: [loopVars, state, { props, refs, $ }]
+ * @returns {*} — evaluation result, or undefined on error
+ */
+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();
+    return evaluate(ast, scope);
+  } catch (err) {
+    if (typeof console !== 'undefined' && console.debug) {
+      console.debug(`[zQuery EXPR_EVAL] Failed to evaluate: "${expr}"`, err.message);
+    }
+    return undefined;
+  }
+}
+
+// --- src/diff.js -------------------------------------------------
+/**
+ * zQuery Diff — Lightweight DOM morphing engine
+ *
+ * Patches an existing DOM tree to match new HTML without destroying nodes
+ * that haven't changed. Preserves focus, scroll positions, third-party
+ * widget state, video playback, and other live DOM state.
+ *
+ * Approach: walk old and new trees in parallel, reconcile node by node.
+ * Keyed elements (via `z-key`) get matched across position changes.
+ */
 
 // ---------------------------------------------------------------------------
-// $() — main selector / creator function (returns single element for CSS selectors)
+// morph(existingRoot, newHTML) — patch existing DOM to match newHTML
 // ---------------------------------------------------------------------------
-function query(selector, context) {
-  // null / undefined
-  if (!selector) return null;
 
-  // Already a collection — return first element
-  if (selector instanceof ZQueryCollection) return selector.first();
+/**
+ * Morph an existing DOM element's children to match new HTML.
+ * Only touches nodes that actually differ.
+ *
+ * @param {Element} rootEl — The live DOM container to patch
+ * @param {string} newHTML — The desired HTML string
+ */
+function morph(rootEl, newHTML) {
+  const template = document.createElement('template');
+  template.innerHTML = newHTML;
+  const newRoot = template.content;
+
+  // Convert to element for consistent handling — wrap in a div if needed
+  const tempDiv = document.createElement('div');
+  while (newRoot.firstChild) tempDiv.appendChild(newRoot.firstChild);
 
-  // DOM element or Window — return as-is
-  if (selector instanceof Node || selector === window) {
-    return selector;
+  _morphChildren(rootEl, tempDiv);
+}
+
+/**
+ * Reconcile children of `oldParent` to match `newParent`.
+ *
+ * @param {Element} oldParent — live DOM parent
+ * @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);
   }
 
-  // NodeList / HTMLCollection / Array — return first element
-  if (selector instanceof NodeList || selector instanceof HTMLCollection || Array.isArray(selector)) {
-    const arr = Array.from(selector);
-    return arr[0] || null;
+  const hasKeys = oldKeyMap.size > 0 || newKeyMap.size > 0;
+
+  if (hasKeys) {
+    _morphChildrenKeyed(oldParent, oldChildren, newChildren, oldKeyMap, newKeyMap);
+  } else {
+    _morphChildrenUnkeyed(oldParent, oldChildren, newChildren);
   }
+}
 
-  // HTML string → create elements, return first
-  if (typeof selector === 'string' && selector.trim().startsWith('<')) {
-    const fragment = createFragment(selector);
-    const els = [...fragment.childNodes].filter(n => n.nodeType === 1);
-    return els[0] || null;
+/**
+ * Unkeyed reconciliation — positional matching.
+ */
+function _morphChildrenUnkeyed(oldParent, oldChildren, newChildren) {
+  const maxLen = Math.max(oldChildren.length, newChildren.length);
+
+  for (let i = 0; i < maxLen; i++) {
+    const oldNode = oldChildren[i];
+    const newNode = 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);
+    }
   }
+}
 
-  // CSS selector string → querySelector (single element)
-  if (typeof selector === 'string') {
-    const root = context
-      ? (typeof context === 'string' ? document.querySelector(context) : context)
-      : document;
-    return root.querySelector(selector);
+/**
+ * Keyed reconciliation — match by z-key, reorder minimal moves.
+ */
+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
+
+  for (let i = 0; i < newLen; i++) {
+    const key = _getKey(newChildren[i]);
+    if (key != null && oldKeyMap.has(key)) {
+      const oldIdx = oldKeyMap.get(key);
+      matched[i] = oldChildren[oldIdx];
+      consumed.add(oldIdx);
+    } else {
+      matched[i] = null;
+    }
   }
 
-  return null;
-}
+  // Step 2: Remove old nodes that are 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
+  let cursor = oldParent.firstChild;
+  const unkeyedOld = oldChildren.filter((n, i) => !consumed.has(i) && _getKey(n) == null);
+  let unkeyedIdx = 0;
 
-// ---------------------------------------------------------------------------
-// $.all() — collection selector (returns ZQueryCollection for CSS selectors)
-// ---------------------------------------------------------------------------
-function queryAll(selector, context) {
-  // null / undefined
-  if (!selector) return new ZQueryCollection([]);
+  for (let i = 0; i < newLen; i++) {
+    const newNode = newChildren[i];
+    const newKey = _getKey(newNode);
+    let oldNode = matched[i];
 
-  // Already a collection
-  if (selector instanceof ZQueryCollection) return selector;
+    if (!oldNode && newKey == null) {
+      // Try to match an unkeyed old node positionally
+      oldNode = unkeyedOld[unkeyedIdx++] || null;
+    }
 
-  // DOM element or Window
-  if (selector instanceof Node || selector === window) {
-    return new ZQueryCollection([selector]);
+    if (oldNode) {
+      // Move into position if needed
+      if (oldNode !== cursor) {
+        oldParent.insertBefore(oldNode, cursor);
+      }
+      // Morph in place
+      _morphNode(oldParent, oldNode, newNode);
+      cursor = oldNode.nextSibling;
+    } else {
+      // Insert new node
+      const clone = newNode.cloneNode(true);
+      if (cursor) {
+        oldParent.insertBefore(clone, cursor);
+      } else {
+        oldParent.appendChild(clone);
+      }
+      // cursor stays the same — new node is before it
+    }
   }
 
-  // NodeList / HTMLCollection / Array
-  if (selector instanceof NodeList || selector instanceof HTMLCollection || Array.isArray(selector)) {
-    return new ZQueryCollection(Array.from(selector));
+  // Remove any remaining unkeyed old nodes at the end
+  while (unkeyedIdx < unkeyedOld.length) {
+    const leftover = unkeyedOld[unkeyedIdx++];
+    if (leftover.parentNode === oldParent) {
+      oldParent.removeChild(leftover);
+    }
   }
 
-  // HTML string → create elements
-  if (typeof selector === 'string' && selector.trim().startsWith('<')) {
-    const fragment = createFragment(selector);
-    return new ZQueryCollection([...fragment.childNodes].filter(n => n.nodeType === 1));
+  // Remove any remaining keyed old nodes that weren't consumed
+  for (let i = 0; i < oldChildren.length; i++) {
+    if (!consumed.has(i)) {
+      const node = oldChildren[i];
+      if (node.parentNode === oldParent && _getKey(node) != null && !newKeyMap.has(_getKey(node))) {
+        oldParent.removeChild(node);
+      }
+    }
   }
+}
 
-  // CSS selector string → querySelectorAll (collection)
-  if (typeof selector === 'string') {
-    const root = context
-      ? (typeof context === 'string' ? document.querySelector(context) : context)
-      : document;
-    return new ZQueryCollection([...root.querySelectorAll(selector)]);
+/**
+ * Morph a single node in place.
+ */
+function _morphNode(parent, oldNode, newNode) {
+  // Text / comment nodes — just update content
+  if (oldNode.nodeType === 3 || oldNode.nodeType === 8) {
+    if (newNode.nodeType === oldNode.nodeType) {
+      if (oldNode.nodeValue !== newNode.nodeValue) {
+        oldNode.nodeValue = newNode.nodeValue;
+      }
+      return;
+    }
+    // Different node types — replace
+    parent.replaceChild(newNode.cloneNode(true), oldNode);
+    return;
   }
 
-  return new ZQueryCollection([]);
-}
+  // Different node types or tag names — replace entirely
+  if (oldNode.nodeType !== newNode.nodeType ||
+      oldNode.nodeName !== newNode.nodeName) {
+    parent.replaceChild(newNode.cloneNode(true), oldNode);
+    return;
+  }
 
+  // Both are elements — diff attributes then recurse children
+  if (oldNode.nodeType === 1) {
+    _morphAttributes(oldNode, newNode);
 
-// ---------------------------------------------------------------------------
-// Quick-ref shortcuts, on $ namespace)
-// ---------------------------------------------------------------------------
-query.id       = (id) => document.getElementById(id);
-query.class    = (name) => document.querySelector(`.${name}`);
-query.classes  = (name) => Array.from(document.getElementsByClassName(name));
-query.tag      = (name) => Array.from(document.getElementsByTagName(name));
-Object.defineProperty(query, 'name', {
-  value: (name) => Array.from(document.getElementsByName(name)),
-  writable: true, configurable: true
-});
-query.attr     = (attr, value) => Array.from(
-  document.querySelectorAll(value !== undefined ? `[${attr}="${value}"]` : `[${attr}]`)
-);
-query.data     = (key, value) => Array.from(
-  document.querySelectorAll(value !== undefined ? `[data-${key}="${value}"]` : `[data-${key}]`)
-);
-query.children = (parentId) => {
-  const p = document.getElementById(parentId);
-  return p ? Array.from(p.children) : [];
-};
+    // Special elements: don't recurse into their children
+    // (textarea value, input value, select, etc.)
+    const tag = oldNode.nodeName;
+    if (tag === 'INPUT') {
+      _syncInputValue(oldNode, newNode);
+      return;
+    }
+    if (tag === 'TEXTAREA') {
+      if (oldNode.value !== newNode.textContent) {
+        oldNode.value = newNode.textContent || '';
+      }
+      return;
+    }
+    if (tag === 'SELECT') {
+      // Recurse children (options) then sync value
+      _morphChildren(oldNode, newNode);
+      if (oldNode.value !== newNode.value) {
+        oldNode.value = newNode.value;
+      }
+      return;
+    }
 
-// Create element shorthand
-query.create = (tag, attrs = {}, ...children) => {
-  const el = document.createElement(tag);
-  for (const [k, v] of Object.entries(attrs)) {
-    if (k === 'class') el.className = v;
-    else if (k === 'style' && typeof v === 'object') Object.assign(el.style, v);
-    else if (k.startsWith('on') && typeof v === 'function') el.addEventListener(k.slice(2), v);
-    else if (k === 'data' && typeof v === 'object') Object.entries(v).forEach(([dk, dv]) => { el.dataset[dk] = dv; });
-    else el.setAttribute(k, v);
+    // Generic element — recurse children
+    _morphChildren(oldNode, newNode);
   }
-  children.flat().forEach(child => {
-    if (typeof child === 'string') el.appendChild(document.createTextNode(child));
-    else if (child instanceof Node) el.appendChild(child);
-  });
-  return el;
-};
+}
 
-// DOM ready
-query.ready = (fn) => {
-  if (document.readyState !== 'loading') fn();
-  else document.addEventListener('DOMContentLoaded', fn);
-};
+/**
+ * Sync attributes from newEl onto oldEl.
+ */
+function _morphAttributes(oldEl, newEl) {
+  // Add/update attributes
+  const newAttrs = newEl.attributes;
+  for (let i = 0; i < newAttrs.length; i++) {
+    const attr = newAttrs[i];
+    if (oldEl.getAttribute(attr.name) !== attr.value) {
+      oldEl.setAttribute(attr.name, attr.value);
+    }
+  }
 
-// Global event listeners — supports direct and delegated forms
-//   $.on('keydown', handler)           → direct listener on document
-//   $.on('click', '.btn', handler)     → delegated via closest()
-query.on = (event, selectorOrHandler, handler) => {
-  if (typeof selectorOrHandler === 'function') {
-    // 2-arg: direct document listener (keydown, resize, etc.)
-    document.addEventListener(event, selectorOrHandler);
-    return;
+  // 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);
+    }
   }
-  // 3-arg: delegated
-  document.addEventListener(event, (e) => {
-    const target = e.target.closest(selectorOrHandler);
-    if (target) handler.call(target, e);
-  });
-};
+}
 
-// Remove a direct global listener
-query.off = (event, handler) => {
-  document.removeEventListener(event, handler);
-};
+/**
+ * Sync input element value, checked, disabled states.
+ */
+function _syncInputValue(oldEl, newEl) {
+  const type = (oldEl.type || '').toLowerCase();
 
-// Extend collection prototype (like $.fn in jQuery)
-query.fn = ZQueryCollection.prototype;
+  if (type === 'checkbox' || type === 'radio') {
+    if (oldEl.checked !== newEl.checked) oldEl.checked = newEl.checked;
+  } else {
+    if (oldEl.value !== (newEl.getAttribute('value') || '')) {
+      oldEl.value = newEl.getAttribute('value') || '';
+    }
+  }
+
+  // Sync disabled
+  if (oldEl.disabled !== newEl.disabled) oldEl.disabled = newEl.disabled;
+}
+
+/**
+ * Get the reconciliation key from a node (z-key attribute).
+ * @returns {string|null}
+ */
+function _getKey(node) {
+  if (node.nodeType !== 1) return null;
+  return node.getAttribute('z-key') || null;
+}
 
-// --- src/component.js ————————————————————————————————————————————
+// --- src/component.js --------------------------------------------
 /**
  * zQuery Component — Lightweight reactive component system
  * 
@@ -690,6 +2253,9 @@ query.fn = ZQueryCollection.prototype;
  */
 
 
+
+
+
 // ---------------------------------------------------------------------------
 // Component registry & external resource cache
 // ---------------------------------------------------------------------------
@@ -864,10 +2430,27 @@ class Component {
     this._destroyed = false;
     this._updateQueued = false;
     this._listeners = [];
+    this._watchCleanups = [];
 
     // Refs map
     this.refs = {};
 
+    // Capture slot content before first render replaces it
+    this._slotContent = {};
+    const defaultSlotNodes = [];
+    [...el.childNodes].forEach(node => {
+      if (node.nodeType === 1 && node.hasAttribute('slot')) {
+        const slotName = node.getAttribute('slot');
+        if (!this._slotContent[slotName]) this._slotContent[slotName] = '';
+        this._slotContent[slotName] += node.outerHTML;
+      } else if (node.nodeType === 1 || (node.nodeType === 3 && node.textContent.trim())) {
+        defaultSlotNodes.push(node.nodeType === 1 ? node.outerHTML : node.textContent);
+      }
+    });
+    if (defaultSlotNodes.length) {
+      this._slotContent['default'] = defaultSlotNodes.join('');
+    }
+
     // Props (read-only from parent)
     this.props = Object.freeze({ ...props });
 
@@ -876,10 +2459,25 @@ class Component {
       ? definition.state()
       : { ...(definition.state || {}) };
 
-    this.state = reactive(initialState, () => {
-      if (!this._destroyed) this._scheduleUpdate();
+    this.state = reactive(initialState, (key, value, old) => {
+      if (!this._destroyed) {
+        // Run watchers for the changed key
+        this._runWatchers(key, value, old);
+        this._scheduleUpdate();
+      }
     });
 
+    // Computed properties — lazy getters derived from state
+    this.computed = {};
+    if (definition.computed) {
+      for (const [name, fn] of Object.entries(definition.computed)) {
+        Object.defineProperty(this.computed, name, {
+          get: () => fn.call(this, this.state.__raw || this.state),
+          enumerable: true
+        });
+      }
+    }
+
     // Bind all user methods to this instance
     for (const [key, val] of Object.entries(definition)) {
       if (typeof val === 'function' && !_reservedKeys.has(key)) {
@@ -888,7 +2486,36 @@ class Component {
     }
 
     // Init lifecycle
-    if (definition.init) definition.init.call(this);
+    if (definition.init) {
+      try { definition.init.call(this); }
+      catch (err) { reportError(ErrorCode.COMP_LIFECYCLE, `Component "${definition._name}" init() threw`, { component: definition._name }, err); }
+    }
+
+    // Set up watchers after init so initial state is ready
+    if (definition.watch) {
+      this._prevWatchValues = {};
+      for (const key of Object.keys(definition.watch)) {
+        this._prevWatchValues[key] = _getPath(this.state.__raw || this.state, key);
+      }
+    }
+  }
+
+  // Run registered watchers for a changed key
+  _runWatchers(changedKey, value, old) {
+    const watchers = this._def.watch;
+    if (!watchers) return;
+    for (const [key, handler] of Object.entries(watchers)) {
+      // Match exact key or parent key (e.g. watcher on 'user' fires when 'user.name' changes)
+      if (changedKey === key || key.startsWith(changedKey + '.') || changedKey.startsWith(key + '.') || changedKey === key) {
+        const currentVal = _getPath(this.state.__raw || this.state, key);
+        const prevVal = this._prevWatchValues?.[key];
+        if (currentVal !== prevVal) {
+          const fn = typeof handler === 'function' ? handler : handler.handler;
+          if (typeof fn === 'function') fn.call(this, currentVal, prevVal);
+          if (this._prevWatchValues) this._prevWatchValues[key] = currentVal;
+        }
+      }
+    }
   }
 
   // Schedule a batched DOM update (microtask)
@@ -986,11 +2613,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;
     }
@@ -1063,17 +2693,29 @@ class Component {
       // Then do global {{expression}} interpolation on the remaining content
       html = html.replace(/\{\{(.+?)\}\}/g, (_, expr) => {
         try {
-          return new Function('state', 'props', '$', `with(state){return ${expr.trim()}}`)(
+          const result = safeEval(expr.trim(), [
             this.state.__raw || this.state,
-            this.props,
-            typeof window !== 'undefined' ? window.$ : undefined
-          );
+            { props: this.props, computed: this.computed, $: typeof window !== 'undefined' ? window.$ : undefined }
+          ]);
+          return result != null ? result : '';
         } catch { return ''; }
       });
     } else {
       html = '';
     }
 
+    // -- Slot distribution ----------------------------------------
+    // Replace <slot> elements with captured slot content from parent.
+    // <slot> → default slot content
+    // <slot name="header"> → named slot content
+    // Fallback content between <slot>...</slot> used when no content provided.
+    if (html.includes('<slot')) {
+      html = html.replace(/<slot(?:\s+name="([^"]*)")?\s*(?:\/>|>([\s\S]*?)<\/slot>)/g, (_, name, fallback) => {
+        const slotName = name || 'default';
+        return this._slotContent[slotName] || fallback || '';
+      });
+    }
+
     // Combine inline styles + external styles
     const combinedStyles = [
       this._def.styles || '',
@@ -1084,33 +2726,52 @@ class Component {
     if (!this._mounted && combinedStyles) {
       const scopeAttr = `z-s${this._uid}`;
       this._el.setAttribute(scopeAttr, '');
-      const scoped = combinedStyles.replace(/([^{}]+)\{/g, (match, selector) => {
+      let inAtBlock = 0;
+      const scoped = combinedStyles.replace(/([^{}]+)\{|\}/g, (match, selector) => {
+        if (match === '}') {
+          if (inAtBlock > 0) inAtBlock--;
+          return match;
+        }
+        const trimmed = selector.trim();
+        // Don't scope @-rules (@media, @keyframes, @supports, @container, @layer, @font-face, etc.)
+        if (trimmed.startsWith('@')) {
+          inAtBlock++;
+          return match;
+        }
+        // Don't scope keyframe stops (from, to, 0%, 50%, etc.)
+        if (inAtBlock > 0 && /^[\d%\s,fromto]+$/.test(trimmed.replace(/\s/g, ''))) {
+          return match;
+        }
         return selector.split(',').map(s => `[${scopeAttr}] ${s.trim()}`).join(', ') + ' {';
       });
       const styleEl = document.createElement('style');
       styleEl.textContent = scoped;
       styleEl.setAttribute('data-zq-component', this._def._name || '');
+      styleEl.setAttribute('data-zq-scope', scopeAttr);
+      if (this._def._resolvedStyleUrls) {
+        styleEl.setAttribute('data-zq-style-urls', this._def._resolvedStyleUrls.join(' '));
+        if (this._def.styles) {
+          styleEl.setAttribute('data-zq-inline', this._def.styles);
+        }
+      }
       document.head.appendChild(styleEl);
       this._styleEl = styleEl;
     }
 
     // -- Focus preservation ----------------------------------------
-    // Before replacing innerHTML, save focus state so we can restore
-    // cursor position after the DOM is rebuilt.  Works for any focused
-    // input/textarea/select inside the component, not only z-model.
+    // DOM morphing preserves unchanged nodes naturally, but we still
+    // track focus for cases where the focused element's subtree changes.
     let _focusInfo = null;
     const _active = document.activeElement;
     if (_active && this._el.contains(_active)) {
       const modelKey = _active.getAttribute?.('z-model');
       const refKey = _active.getAttribute?.('z-ref');
-      // Build a selector that can locate the same element after re-render
       let selector = null;
       if (modelKey) {
         selector = `[z-model="${modelKey}"]`;
       } else if (refKey) {
         selector = `[z-ref="${refKey}"]`;
       } else {
-        // Fallback: match by tag + type + name + placeholder combination
         const tag = _active.tagName.toLowerCase();
         if (tag === 'input' || tag === 'textarea' || tag === 'select') {
           let s = tag;
@@ -1130,8 +2791,13 @@ class Component {
       }
     }
 
-    // Update DOM
-    this._el.innerHTML = html;
+    // Update DOM via morphing (diffing) — preserves unchanged nodes
+    // First render uses innerHTML for speed; subsequent renders morph.
+    if (!this._mounted) {
+      this._el.innerHTML = html;
+    } else {
+      morph(this._el, html);
+    }
 
     // Process structural & attribute directives
     this._processDirectives();
@@ -1141,10 +2807,10 @@ class Component {
     this._bindRefs();
     this._bindModels();
 
-    // Restore focus after re-render
+    // Restore focus if the morph replaced the focused element
     if (_focusInfo) {
       const el = this._el.querySelector(_focusInfo.selector);
-      if (el) {
+      if (el && el !== document.activeElement) {
         el.focus();
         try {
           if (_focusInfo.start !== null && _focusInfo.start !== undefined) {
@@ -1159,9 +2825,15 @@ class Component {
 
     if (!this._mounted) {
       this._mounted = true;
-      if (this._def.mounted) this._def.mounted.call(this);
+      if (this._def.mounted) {
+        try { this._def.mounted.call(this); }
+        catch (err) { reportError(ErrorCode.COMP_LIFECYCLE, `Component "${this._def._name}" mounted() threw`, { component: this._def._name }, err); }
+      }
     } else {
-      if (this._def.updated) this._def.updated.call(this);
+      if (this._def.updated) {
+        try { this._def.updated.call(this); }
+        catch (err) { reportError(ErrorCode.COMP_LIFECYCLE, `Component "${this._def._name}" updated() threw`, { component: this._def._name }, err); }
+      }
     }
   }
 
@@ -1370,18 +3042,13 @@ class Component {
   }
 
   // ---------------------------------------------------------------------------
-  // Expression evaluator — runs expr in component context (state, props, refs)
+  // Expression evaluator — CSP-safe parser (no eval / new Function)
   // ---------------------------------------------------------------------------
   _evalExpr(expr) {
-    try {
-      return new Function('state', 'props', 'refs', '$',
-        `with(state){return (${expr})}`)(
-        this.state.__raw || this.state,
-        this.props,
-        this.refs,
-        typeof window !== 'undefined' ? window.$ : undefined
-      );
-    } catch { return undefined; }
+    return safeEval(expr, [
+      this.state.__raw || this.state,
+      { props: this.props, refs: this.refs, computed: this.computed, $: typeof window !== 'undefined' ? window.$ : undefined }
+    ]);
   }
 
   // ---------------------------------------------------------------------------
@@ -1443,13 +3110,15 @@ class Component {
         const evalReplace = (str, item, index) =>
           str.replace(/\{\{(.+?)\}\}/g, (_, inner) => {
             try {
-              return new Function(itemVar, indexVar, 'state', 'props', '$',
-                `with(state){return (${inner.trim()})}`)(
-                item, index,
+              const loopScope = {};
+              loopScope[itemVar] = item;
+              loopScope[indexVar] = index;
+              const result = safeEval(inner.trim(), [
+                loopScope,
                 this.state.__raw || this.state,
-                this.props,
-                typeof window !== 'undefined' ? window.$ : undefined
-              );
+                { props: this.props, computed: this.computed, $: typeof window !== 'undefined' ? window.$ : undefined }
+              ]);
+              return result != null ? result : '';
             } catch { return ''; }
           });
 
@@ -1614,7 +3283,10 @@ class Component {
   destroy() {
     if (this._destroyed) return;
     this._destroyed = true;
-    if (this._def.destroyed) this._def.destroyed.call(this);
+    if (this._def.destroyed) {
+      try { this._def.destroyed.call(this); }
+      catch (err) { reportError(ErrorCode.COMP_LIFECYCLE, `Component "${this._def._name}" destroyed() threw`, { component: this._def._name }, err); }
+    }
     this._listeners.forEach(({ event, handler }) => this._el.removeEventListener(event, handler));
     this._listeners = [];
     if (this._styleEl) this._styleEl.remove();
@@ -1627,7 +3299,8 @@ 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', 'pages', 'activePage', 'base',
+  'computed', 'watch'
 ]);
 
 
@@ -1641,8 +3314,11 @@ const _reservedKeys = new Set([
  * @param {object} definition — component definition
  */
 function component(name, definition) {
+  if (!name || typeof name !== 'string') {
+    throw new ZQueryError(ErrorCode.COMP_INVALID_NAME, 'Component name must be a non-empty string');
+  }
   if (!name.includes('-')) {
-    throw new Error(`zQuery: Component name "${name}" must contain a hyphen (Web Component convention)`);
+    throw new ZQueryError(ErrorCode.COMP_INVALID_NAME, `Component name "${name}" must contain a hyphen (Web Component convention)`);
   }
   definition._name = name;
 
@@ -1667,10 +3343,10 @@ function component(name, definition) {
  */
 function mount(target, componentName, props = {}) {
   const el = typeof target === 'string' ? document.querySelector(target) : target;
-  if (!el) throw new Error(`zQuery: Mount target "${target}" not found`);
+  if (!el) throw new ZQueryError(ErrorCode.COMP_MOUNT_TARGET, `Mount target "${target}" not found`, { target });
 
   const def = _registry.get(componentName);
-  if (!def) throw new Error(`zQuery: Component "${componentName}" not registered`);
+  if (!def) throw new ZQueryError(ErrorCode.COMP_NOT_FOUND, `Component "${componentName}" not registered`, { component: componentName });
 
   // Destroy existing instance
   if (_instances.has(el)) _instances.get(el).destroy();
@@ -1693,12 +3369,40 @@ function mountAll(root = document.body) {
 
       // Extract props from attributes
       const props = {};
+
+      // Find parent component instance for evaluating dynamic prop expressions
+      let parentInstance = null;
+      let ancestor = tag.parentElement;
+      while (ancestor) {
+        if (_instances.has(ancestor)) {
+          parentInstance = _instances.get(ancestor);
+          break;
+        }
+        ancestor = ancestor.parentElement;
+      }
+
       [...tag.attributes].forEach(attr => {
-        if (!attr.name.startsWith('@') && !attr.name.startsWith('z-')) {
-          // Try JSON parse for objects/arrays
-          try { props[attr.name] = JSON.parse(attr.value); }
-          catch { props[attr.name] = attr.value; }
+        if (attr.name.startsWith('@') || attr.name.startsWith('z-')) return;
+
+        // Dynamic prop: :propName="expression" — evaluate in parent context
+        if (attr.name.startsWith(':')) {
+          const propName = attr.name.slice(1);
+          if (parentInstance) {
+            props[propName] = safeEval(attr.value, [
+              parentInstance.state.__raw || parentInstance.state,
+              { props: parentInstance.props, refs: parentInstance.refs, computed: parentInstance.computed, $: typeof window !== 'undefined' ? window.$ : undefined }
+            ]);
+          } else {
+            // No parent — try JSON parse
+            try { props[propName] = JSON.parse(attr.value); }
+            catch { props[propName] = attr.value; }
+          }
+          return;
         }
+
+        // Static prop
+        try { props[attr.name] = JSON.parse(attr.value); }
+        catch { props[attr.name] = attr.value; }
       });
 
       const instance = new Component(tag, def, props);
@@ -1836,7 +3540,7 @@ function style(urls, opts = {}) {
   };
 }
 
-// --- src/router.js ———————————————————————————————————————————————
+// --- src/router.js -----------------------------------------------
 /**
  * zQuery Router — Client-side SPA router
  * 
@@ -1857,6 +3561,7 @@ function style(urls, opts = {}) {
  */
 
 
+
 class Router {
   constructor(config = {}) {
     this._el = null;
@@ -1915,7 +3620,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
@@ -1959,7 +3678,23 @@ 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;
+    });
+  }
+
   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);
@@ -1977,6 +3712,8 @@ class Router {
   }
 
   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 : '';
@@ -2090,6 +3827,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 {
@@ -2127,10 +3865,29 @@ class Router {
 
     // Run before guards
     for (const guard of this._guards.before) {
-      const result = await guard(to, from);
-      if (result === false) return;                    // Cancel
-      if (typeof result === 'string') {                // Redirect
-        return this.navigate(result);
+      try {
+        const result = await guard(to, from);
+        if (result === false) return;                    // Cancel
+        if (typeof result === 'string') {                // Redirect
+          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({}, '', this._base + rNorm + rHash);
+          }
+          return this.__resolve();
+        }
+      } catch (err) {
+        reportError(ErrorCode.ROUTER_GUARD, 'Before-guard threw', { to, from }, err);
+        return;
       }
     }
 
@@ -2138,7 +3895,7 @@ class Router {
     if (matched.load) {
       try { await matched.load(); }
       catch (err) {
-        console.error(`zQuery Router: Failed to load module for "${matched.path}"`, err);
+        reportError(ErrorCode.ROUTER_LOAD, `Failed to load module for route "${matched.path}"`, { path: matched.path }, err);
         return;
       }
     }
@@ -2205,7 +3962,7 @@ function getRouter() {
   return _activeRouter;
 }
 
-// --- src/store.js ————————————————————————————————————————————————
+// --- src/store.js ------------------------------------------------
 /**
  * zQuery Store — Global reactive state management
  * 
@@ -2234,6 +3991,7 @@ function getRouter() {
  */
 
 
+
 class Store {
   constructor(config = {}) {
     this._subscribers = new Map();   // key → Set<fn>
@@ -2250,9 +4008,15 @@ class Store {
     this.state = reactive(initial, (key, value, old) => {
       // Notify key-specific subscribers
       const subs = this._subscribers.get(key);
-      if (subs) subs.forEach(fn => fn(value, old, key));
+      if (subs) subs.forEach(fn => {
+        try { fn(value, old, key); }
+        catch (err) { reportError(ErrorCode.STORE_SUBSCRIBE, `Subscriber for "${key}" threw`, { key }, err); }
+      });
       // Notify wildcard subscribers
-      this._wildcards.forEach(fn => fn(key, value, old));
+      this._wildcards.forEach(fn => {
+        try { fn(key, value, old); }
+        catch (err) { reportError(ErrorCode.STORE_SUBSCRIBE, 'Wildcard subscriber threw', { key }, err); }
+      });
     });
 
     // Build getters as computed properties
@@ -2273,23 +4037,32 @@ class Store {
   dispatch(name, ...args) {
     const action = this._actions[name];
     if (!action) {
-      console.warn(`zQuery Store: Unknown action "${name}"`);
+      reportError(ErrorCode.STORE_ACTION, `Unknown action "${name}"`, { action: name, args });
       return;
     }
 
     // Run middleware
     for (const mw of this._middleware) {
-      const result = mw(name, args, this.state);
-      if (result === false) return; // blocked by middleware
+      try {
+        const result = mw(name, args, this.state);
+        if (result === false) return; // blocked by middleware
+      } catch (err) {
+        reportError(ErrorCode.STORE_MIDDLEWARE, `Middleware threw during "${name}"`, { action: name }, err);
+        return;
+      }
     }
 
     if (this._debug) {
       console.log(`%c[Store] ${name}`, 'color: #4CAF50; font-weight: bold;', ...args);
     }
 
-    const result = action(this.state, ...args);
-    this._history.push({ action: name, args, timestamp: Date.now() });
-    return result;
+    try {
+      const result = action(this.state, ...args);
+      this._history.push({ action: name, args, timestamp: Date.now() });
+      return result;
+    } catch (err) {
+      reportError(ErrorCode.STORE_ACTION, `Action "${name}" threw`, { action: name, args }, err);
+    }
   }
 
   /**
@@ -2375,7 +4148,7 @@ function getStore(name = 'default') {
   return _stores.get(name) || null;
 }
 
-// --- src/http.js —————————————————————————————————————————————————
+// --- src/http.js -------------------------------------------------
 /**
  * zQuery HTTP — Lightweight fetch wrapper
  * 
@@ -2408,6 +4181,9 @@ const _interceptors = {
  * Core request function
  */
 async function request(method, url, data, options = {}) {
+  if (!url || typeof url !== 'string') {
+    throw new Error(`HTTP request requires a URL string, got ${typeof url}`);
+  }
   let fullURL = url.startsWith('http') ? url : _config.baseURL + url;
   let headers = { ..._config.headers, ...options.headers };
   let body = undefined;
@@ -2463,16 +4239,21 @@ async function request(method, url, data, options = {}) {
     const contentType = response.headers.get('Content-Type') || '';
     let responseData;
 
-    if (contentType.includes('application/json')) {
-      responseData = await response.json();
-    } else if (contentType.includes('text/')) {
-      responseData = await response.text();
-    } else if (contentType.includes('application/octet-stream') || contentType.includes('image/')) {
-      responseData = await response.blob();
-    } else {
-      // Try JSON first, fall back to text
-      const text = await response.text();
-      try { responseData = JSON.parse(text); } catch { responseData = text; }
+    try {
+      if (contentType.includes('application/json')) {
+        responseData = await response.json();
+      } else if (contentType.includes('text/')) {
+        responseData = await response.text();
+      } else if (contentType.includes('application/octet-stream') || contentType.includes('image/')) {
+        responseData = await response.blob();
+      } else {
+        // Try JSON first, fall back to text
+        const text = await response.text();
+        try { responseData = JSON.parse(text); } catch { responseData = text; }
+      }
+    } catch (parseErr) {
+      responseData = null;
+      console.warn(`[zQuery HTTP] Failed to parse response body from ${method} ${fullURL}:`, parseErr.message);
     }
 
     const result = {
@@ -2554,7 +4335,7 @@ const http = {
   raw: (url, opts) => fetch(url, opts),
 };
 
-// --- src/utils.js ————————————————————————————————————————————————
+// --- src/utils.js ------------------------------------------------
 /**
  * zQuery Utils — Common utility functions
  * 
@@ -2827,7 +4608,7 @@ class EventBus {
 
 const bus = new EventBus();
 
-// --- index.js (assembly) ——————————————————————————————————————————
+// --- index.js (assembly) ------------------------------------------
 /**
  * ┌---------------------------------------------------------┐
  * │  zQuery (zeroQuery) — Lightweight Frontend Library     │
@@ -2846,21 +4627,24 @@ const bus = new EventBus();
 
 
 
+
+
+
 // ---------------------------------------------------------------------------
 // $ — The main function & namespace
 // ---------------------------------------------------------------------------
 
 /**
- * Main selector function
+ * Main selector function — always returns a ZQueryCollection (like jQuery).
  * 
- *   $('selector')         → single Element (querySelector)
- *   $('<div>hello</div>') → create element (first created node)
- *   $(element)            → return element as-is
+ *   $('selector')         → ZQueryCollection (querySelectorAll)
+ *   $('<div>hello</div>') → ZQueryCollection from created elements
+ *   $(element)            → ZQueryCollection wrapping the element
  *   $(fn)                 → DOMContentLoaded shorthand
  * 
  * @param {string|Element|NodeList|Function} selector
  * @param {string|Element} [context]
- * @returns {Element|null}
+ * @returns {ZQueryCollection}
  */
 function $(selector, context) {
   // $(fn) → DOM ready shorthand
@@ -2880,8 +4664,6 @@ $.tag      = query.tag;
 Object.defineProperty($, 'name', {
   value: query.name, writable: true, configurable: true
 });
-$.attr     = query.attr;
-$.data     = query.data;
 $.children = query.children;
 
 // --- Collection selector ---------------------------------------------------
@@ -2923,6 +4705,8 @@ $.getInstance = getInstance;
 $.destroy     = destroy;
 $.components  = getRegistry;
 $.style       = style;
+$.morph       = morph;
+$.safeEval    = safeEval;
 
 // --- Router ----------------------------------------------------------------
 $.router    = createRouter;
@@ -2961,8 +4745,13 @@ $.storage    = storage;
 $.session    = session;
 $.bus        = bus;
 
+// --- Error handling --------------------------------------------------------
+$.onError     = onError;
+$.ZQueryError = ZQueryError;
+$.ErrorCode   = ErrorCode;
+
 // --- Meta ------------------------------------------------------------------
-$.version = '0.5.2';
+$.version = '0.7.5';
 $.meta    = {};                // populated at build time by CLI bundler
 
 $.noConflict = () => {