zero-query 0.4.9 → 0.6.3

package/dist/zquery.min.js

@@ -1,17 +1,20 @@
 /**
- * zQuery (zeroQuery) v0.4.9
+ * zQuery (zeroQuery) v0.6.3
  * Lightweight Frontend Library
  * https://github.com/tonywied17/zero-query
  * (c) 2026 Anthony Wiedman — MIT License
  */
 (function(global) {
 'use strict';
-function reactive(target, onChange, _path = '') { if (typeof target !== 'object' || target === null) return target; const proxyCache = new WeakMap(); const handler = { get(obj, key) { if (key === '__isReactive') return true; if (key === '__raw') return obj; const value = obj[key]; if (typeof value === 'object' && value !== null) { if (proxyCache.has(value)) return proxyCache.get(value); const childProxy = new Proxy(value, handler); proxyCache.set(value, childProxy); return childProxy; } return value; }, set(obj, key, value) { const old = obj[key]; if (old === value) return true; obj[key] = value; onChange(key, value, old); return true; }, deleteProperty(obj, key) { const old = obj[key]; delete obj[key]; onChange(key, undefined, old); return true; } }; return new Proxy(target, handler);
-class ZQueryCollection { constructor(elements) { this.elements = Array.isArray(elements) ? elements : [elements]; this.length = this.elements.length; this.elements.forEach((el, i) => { this[i] = el; }); } each(fn) { this.elements.forEach((el, i) => fn.call(el, i, el)); return this; } map(fn) { return this.elements.map((el, i) => fn.call(el, i, el)); } 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]] : []); } toArray(){ return [...this.elements]; } [Symbol.iterator]() { return this.elements[Symbol.iterator](); } find(selector) { const found = []; this.elements.forEach(el => found.push(...el.querySelectorAll(selector))); return new ZQueryCollection(found); } parent() { const parents = [...new Set(this.elements.map(el => el.parentElement).filter(Boolean))]; return new ZQueryCollection(parents); } closest(selector) { return new ZQueryCollection( this.elements.map(el => el.closest(selector)).filter(Boolean) ); } children(selector) { const kids = []; this.elements.forEach(el => { kids.push(...(selector ? el.querySelectorAll(`:scope > ${selector}`) : el.children)); }); return new ZQueryCollection([...kids]); } siblings() { const sibs = []; this.elements.forEach(el => { sibs.push(...[...el.parentElement.children].filter(c => c !== el)); }); 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)); } filter(selector) { if (typeof selector === 'function') { return new ZQueryCollection(this.elements.filter(selector)); } return new ZQueryCollection(this.elements.filter(el => el.matches(selector))); } not(selector) { if (typeof selector === 'function') { return new ZQueryCollection(this.elements.filter((el, i) => !selector.call(el, i, el))); } return new ZQueryCollection(this.elements.filter(el => !el.matches(selector))); } has(selector) { return new ZQueryCollection(this.elements.filter(el => el.querySelector(selector))); } addClass(...names) { const classes = names.flatMap(n => n.split(/\s+/)); return this.each((_, el) => el.classList.add(...classes)); } removeClass(...names) { const classes = names.flatMap(n => n.split(/\s+/)); return this.each((_, el) => el.classList.remove(...classes)); } toggleClass(name, force) { return this.each((_, el) => el.classList.toggle(name, force)); } hasClass(name) { return this.first()?.classList.contains(name) || false; } attr(name, value) { if (value === undefined) return this.first()?.getAttribute(name); return this.each((_, el) => el.setAttribute(name, value)); } removeAttr(name) { return this.each((_, el) => el.removeAttribute(name)); } prop(name, value) { if (value === undefined) return this.first()?.[name]; return this.each((_, el) => { el[name] = value; }); } data(key, value) { if (value === undefined) { if (key === undefined) return this.first()?.dataset; const raw = this.first()?.dataset[key]; try { return JSON.parse(raw); } catch { return raw; } } return this.each((_, el) => { el.dataset[key] = typeof value === 'object' ? JSON.stringify(value) : value; }); } css(props) { if (typeof props === 'string') { return getComputedStyle(this.first())[props]; } return this.each((_, el) => Object.assign(el.style, props)); } width() { return this.first()?.getBoundingClientRect().width; } height() { return this.first()?.getBoundingClientRect().height; } offset() { const r = this.first()?.getBoundingClientRect(); return r ? { top: r.top + window.scrollY, left: r.left + window.scrollX, width: r.width, height: r.height } : null; } position() { const el = this.first(); return el ? { top: el.offsetTop, left: el.offsetLeft } : null; } html(content) { if (content === undefined) return this.first()?.innerHTML; return this.each((_, el) => { el.innerHTML = content; }); } text(content) { if (content === undefined) return this.first()?.textContent; return this.each((_, el) => { el.textContent = content; }); } val(value) { if (value === undefined) return this.first()?.value; return this.each((_, el) => { el.value = value; }); } append(content) { return this.each((_, el) => { if (typeof content === 'string') el.insertAdjacentHTML('beforeend', content); else if (content instanceof ZQueryCollection) content.each((__, c) => el.appendChild(c)); else if (content instanceof Node) el.appendChild(content); }); } prepend(content) { return this.each((_, el) => { if (typeof content === 'string') el.insertAdjacentHTML('afterbegin', content); else if (content instanceof Node) el.insertBefore(content, el.firstChild); }); } after(content) { return this.each((_, el) => { if (typeof content === 'string') el.insertAdjacentHTML('afterend', content); else if (content instanceof Node) el.parentNode.insertBefore(content, el.nextSibling); }); } before(content) { return this.each((_, el) => { if (typeof content === 'string') el.insertAdjacentHTML('beforebegin', content); else if (content instanceof Node) el.parentNode.insertBefore(content, el); }); } wrap(wrapper) { return this.each((_, el) => { const w = typeof wrapper === 'string' ? createFragment(wrapper).firstElementChild : wrapper.cloneNode(true); el.parentNode.insertBefore(w, el); w.appendChild(el); }); } remove() { return this.each((_, el) => el.remove()); } empty() { return this.each((_, el) => { el.innerHTML = ''; }); } clone(deep = true) { return new ZQueryCollection(this.elements.map(el => el.cloneNode(deep))); } replaceWith(content) { return this.each((_, el) => { if (typeof content === 'string') { el.insertAdjacentHTML('afterend', content); el.remove(); } else if (content instanceof Node) { el.parentNode.replaceChild(content, el); } }); } show(display = '') { return this.each((_, el) => { el.style.display = display; }); } hide() { return this.each((_, el) => { el.style.display = 'none'; }); } toggle(display = '') { return this.each((_, el) => { el.style.display = (el.style.display === 'none' || getComputedStyle(el).display === 'none') ? display : 'none'; }); } on(event, selectorOrHandler, handler) { const events = event.split(/\s+/); return this.each((_, el) => { events.forEach(evt => { if (typeof selectorOrHandler === 'function') { el.addEventListener(evt, selectorOrHandler); } else { el.addEventListener(evt, (e) => { const target = e.target.closest(selectorOrHandler); if (target && el.contains(target)) handler.call(target, e); }); } }); }); } off(event, handler) { const events = event.split(/\s+/); return this.each((_, el) => { events.forEach(evt => el.removeEventListener(evt, handler)); }); } one(event, handler) { return this.each((_, el) => { el.addEventListener(event, handler, { once: true }); }); } trigger(event, detail) { return this.each((_, el) => { el.dispatchEvent(new CustomEvent(event, { detail, bubbles: true, cancelable: true })); }); } click(fn) { return fn ? this.on('click', fn) : this.trigger('click'); } submit(fn) { return fn ? this.on('submit', fn) : this.trigger('submit'); } focus() { this.first()?.focus(); return this; } blur() { this.first()?.blur(); return this; } animate(props, duration = 300, easing = 'ease') { return new Promise(resolve => { const count = { done: 0 }; this.each((_, el) => { el.style.transition = `all ${duration}ms ${easing}`; requestAnimationFrame(() => { Object.assign(el.style, props); const onEnd = () => { el.removeEventListener('transitionend', onEnd); el.style.transition = ''; if (++count.done >= this.length) resolve(this); }; el.addEventListener('transitionend', onEnd); }); }); setTimeout(() => resolve(this), duration + 50); }); } fadeIn(duration = 300) { return this.css({ opacity: '0', display: '' }).animate({ opacity: '1' }, duration); } fadeOut(duration = 300) { return this.animate({ opacity: '0' }, duration).then(col => col.hide()); } slideToggle(duration = 300) { return this.each((_, el) => { if (el.style.display === 'none' || getComputedStyle(el).display === 'none') { 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); } else { 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); } }); } serialize() { const form = this.first(); if (!form || form.tagName !== 'FORM') return ''; return new URLSearchParams(new FormData(form)).toString(); } serializeObject() { const form = this.first(); if (!form || form.tagName !== 'FORM') return {}; const obj = {}; new FormData(form).forEach((v, k) => { if (obj[k] !== undefined) { if (!Array.isArray(obj[k])) obj[k] = [obj[k]]; obj[k].push(v); } else { obj[k] = v; } }); return obj; }
-const _registry = new Map(); const _instances = new Map(); const _resourceCache = new Map(); let _uid = 0;
-class Router { constructor(config = {}) { this._el = null; const isFile = typeof location !== 'undefined' && location.protocol === 'file:'; this._mode = isFile ? 'hash' : (config.mode || 'history'); let rawBase = config.base; if (rawBase == null) { rawBase = (typeof window !== 'undefined' && window.__ZQ_BASE) || ''; if (!rawBase && typeof document !== 'undefined') { const baseEl = document.querySelector('base'); if (baseEl) { try { rawBase = new URL(baseEl.href).pathname; } catch { rawBase = baseEl.getAttribute('href') || ''; } if (rawBase === '/') rawBase = ''; } } } this._base = String(rawBase).replace(/\/+$/, ''); if (this._base && !this._base.startsWith('/')) this._base = '/' + this._base; this._routes = []; this._fallback = config.fallback || null; this._current = null; this._guards = { before: [], after: [] }; this._listeners = new Set(); this._instance = null; this._resolving = false; if (config.el) { this._el = typeof config.el === 'string' ? document.querySelector(config.el) : config.el; } if (config.routes) { config.routes.forEach(r => this.add(r)); } if (this._mode === 'hash') { window.addEventListener('hashchange', () => this._resolve()); } else { window.addEventListener('popstate', () => this._resolve()); } document.addEventListener('click', (e) => { if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return; const link = e.target.closest('[z-link]'); if (!link) return; if (link.getAttribute('target') === '_blank') return; e.preventDefault(); this.navigate(link.getAttribute('z-link')); }); if (this._el) { queueMicrotask(() => this._resolve()); } } add(route) { const keys = []; const pattern = route.path .replace(/:(\w+)/g, (_, key) => { keys.push(key); return '([^/]+)'; }) .replace(/\*/g, '(.*)'); const regex = new RegExp(`^${pattern}$`); this._routes.push({ ...route, _regex: regex, _keys: keys }); if (route.fallback) { const fbKeys = []; const fbPattern = route.fallback .replace(/:(\w+)/g, (_, key) => { fbKeys.push(key); return '([^/]+)'; }) .replace(/\*/g, '(.*)'); const fbRegex = new RegExp(`^${fbPattern}$`); this._routes.push({ ...route, path: route.fallback, _regex: fbRegex, _keys: fbKeys }); } return this; } remove(path) { this._routes = this._routes.filter(r => r.path !== path); return this; } navigate(path, options = {}) { const [cleanPath, fragment] = (path || '').split('#'); let normalized = this._normalizePath(cleanPath); const hash = fragment ? '#' + fragment : ''; if (this._mode === 'hash') { if (fragment) window.__zqScrollTarget = fragment; window.location.hash = '#' + normalized; } else { window.history.pushState(options.state || {}, '', this._base + normalized + hash); this._resolve(); } return this; } replace(path, options = {}) { const [cleanPath, fragment] = (path || '').split('#'); let normalized = this._normalizePath(cleanPath); const hash = fragment ? '#' + fragment : ''; if (this._mode === 'hash') { if (fragment) window.__zqScrollTarget = fragment; window.location.replace('#' + normalized); } else { window.history.replaceState(options.state || {}, '', this._base + normalized + hash); this._resolve(); } return this; } _normalizePath(path) { let p = path && path.startsWith('/') ? path : (path ? `/${path}` : '/'); if (this._base) { if (p === this._base) return '/'; if (p.startsWith(this._base + '/')) p = p.slice(this._base.length) || '/'; } return p; } resolve(path) { const normalized = path && path.startsWith('/') ? path : (path ? `/${path}` : '/'); return this._base + normalized; } back() { window.history.back(); return this; } forward() { window.history.forward(); return this; } go(n) { window.history.go(n); return this; } beforeEach(fn) { this._guards.before.push(fn); return this; } afterEach(fn) { this._guards.after.push(fn); return this; } onChange(fn) { this._listeners.add(fn); return () => this._listeners.delete(fn); } get current() { return this._current; } get base() { return this._base; } get path() { if (this._mode === 'hash') { const raw = window.location.hash.slice(1) || '/'; if (raw && !raw.startsWith('/')) { window.__zqScrollTarget = raw; const fallbackPath = (this._current && this._current.path) || '/'; window.location.replace('#' + fallbackPath); return fallbackPath; } return raw; } let pathname = window.location.pathname || '/'; if (pathname.length > 1 && pathname.endsWith('/')) { pathname = pathname.slice(0, -1); } if (this._base) { if (pathname === this._base) return '/'; if (pathname.startsWith(this._base + '/')) { return pathname.slice(this._base.length) || '/'; } } return pathname; } get query() { const search = this._mode === 'hash' ? (window.location.hash.split('?')[1] || '') : window.location.search.slice(1); return Object.fromEntries(new URLSearchParams(search)); } async _resolve() { if (this._resolving) return; this._resolving = true; try { await this.__resolve(); } finally { this._resolving = false; } } async __resolve() { const fullPath = this.path; const [pathPart, queryString] = fullPath.split('?'); const path = pathPart || '/'; const query = Object.fromEntries(new URLSearchParams(queryString || '')); let matched = null; let params = {}; for (const route of this._routes) { const m = path.match(route._regex); if (m) { matched = route; route._keys.forEach((key, i) => { params[key] = m[i + 1]; }); break; } } if (!matched && this._fallback) { matched = { component: this._fallback, path: '*', _keys: [], _regex: /.*/ }; } if (!matched) return; const to = { route: matched, params, query, path }; const from = this._current; for (const guard of this._guards.before) { const result = await guard(to, from); if (result === false) return; if (typeof result === 'string') { return this.navigate(result); } } if (matched.load) { try { await matched.load(); } catch (err) { console.error(`zQuery Router: Failed to load module for "${matched.path}"`, err); return; } } this._current = to; if (this._el && matched.component) { if (this._instance) { this._instance.destroy(); this._instance = null; } this._el.innerHTML = ''; const props = { ...params, $route: to, $query: query, $params: params }; if (typeof matched.component === 'string') { const container = document.createElement(matched.component); this._el.appendChild(container); this._instance = mount(container, matched.component, props); } else if (typeof matched.component === 'function') { this._el.innerHTML = matched.component(to); } } for (const guard of this._guards.after) { await guard(to, from); } this._listeners.forEach(fn => fn(to, from)); } destroy() { if (this._instance) this._instance.destroy(); this._listeners.clear(); this._routes = []; this._guards = { before: [], after: [] }; }
-class Store { constructor(config = {}) { this._subscribers = new Map(); this._wildcards = new Set(); this._actions = config.actions || {}; this._getters = config.getters || {}; this._middleware = []; this._history = []; this._debug = config.debug || false; const initial = typeof config.state === 'function' ? config.state() : { ...(config.state || {}) }; this.state = reactive(initial, (key, value, old) => { const subs = this._subscribers.get(key); if (subs) subs.forEach(fn => fn(value, old, key)); this._wildcards.forEach(fn => fn(key, value, old)); }); this.getters = {}; for (const [name, fn] of Object.entries(this._getters)) { Object.defineProperty(this.getters, name, { get: () => fn(this.state.__raw || this.state), enumerable: true }); } } dispatch(name, ...args) { const action = this._actions[name]; if (!action) { console.warn(`zQuery Store: Unknown action "${name}"`); return; } for (const mw of this._middleware) { const result = mw(name, args, this.state); if (result === false) 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; } subscribe(keyOrFn, fn) { if (typeof keyOrFn === 'function') { this._wildcards.add(keyOrFn); return () => this._wildcards.delete(keyOrFn); } if (!this._subscribers.has(keyOrFn)) { this._subscribers.set(keyOrFn, new Set()); } this._subscribers.get(keyOrFn).add(fn); return () => this._subscribers.get(keyOrFn)?.delete(fn); } snapshot() { return JSON.parse(JSON.stringify(this.state.__raw || this.state)); } replaceState(newState) { const raw = this.state.__raw || this.state; for (const key of Object.keys(raw)) { delete this.state[key]; } Object.assign(this.state, newState); } use(fn) { this._middleware.push(fn); return this; } get history() { return [...this._history]; } reset(initialState) { this.replaceState(initialState); this._history = []; }
-const _config = { baseURL: '', headers: { 'Content-Type': 'application/json' }, timeout: 30000,
+const ErrorCode = Object.freeze({ REACTIVE_CALLBACK: 'ZQ_REACTIVE_CALLBACK', SIGNAL_CALLBACK: 'ZQ_SIGNAL_CALLBACK', EFFECT_EXEC: 'ZQ_EFFECT_EXEC', EXPR_PARSE: 'ZQ_EXPR_PARSE', EXPR_EVAL: 'ZQ_EXPR_EVAL', EXPR_UNSAFE_ACCESS: 'ZQ_EXPR_UNSAFE_ACCESS', 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_LOAD: 'ZQ_ROUTER_LOAD', ROUTER_GUARD: 'ZQ_ROUTER_GUARD', ROUTER_RESOLVE: 'ZQ_ROUTER_RESOLVE', STORE_ACTION: 'ZQ_STORE_ACTION', STORE_MIDDLEWARE: 'ZQ_STORE_MIDDLEWARE', STORE_SUBSCRIBE: 'ZQ_STORE_SUBSCRIBE', HTTP_REQUEST: 'ZQ_HTTP_REQUEST', HTTP_TIMEOUT: 'ZQ_HTTP_TIMEOUT', HTTP_INTERCEPTOR: 'ZQ_HTTP_INTERCEPTOR', HTTP_PARSE: 'ZQ_HTTP_PARSE', INVALID_ARGUMENT: 'ZQ_INVALID_ARGUMENT',
+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(); const handler = { get(obj, key) { if (key === '__isReactive') return true; if (key === '__raw') return obj; const value = obj[key]; if (typeof value === 'object' && value !== null) { if (proxyCache.has(value)) return proxyCache.get(value); const childProxy = new Proxy(value, handler); proxyCache.set(value, childProxy); return childProxy; } return value; }, set(obj, key, value) { const old = obj[key]; if (old === value) return true; obj[key] = value; 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]; try { onChange(key, undefined, old); } catch (err) { reportError(ErrorCode.REACTIVE_CALLBACK, `Reactive onChange threw for key "${String(key)}"`, { key, old }, err); } return true; } }; return new Proxy(target, handler);
+class ZQueryCollection { constructor(elements) { this.elements = Array.isArray(elements) ? elements : [elements]; this.length = this.elements.length; this.elements.forEach((el, i) => { this[i] = el; }); } each(fn) { this.elements.forEach((el, i) => fn.call(el, i, el)); return this; } map(fn) { 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]] : []); } toArray(){ return [...this.elements]; } [Symbol.iterator]() { return this.elements[Symbol.iterator](); } find(selector) { const found = []; this.elements.forEach(el => found.push(...el.querySelectorAll(selector))); return new ZQueryCollection(found); } parent() { const parents = [...new Set(this.elements.map(el => el.parentElement).filter(Boolean))]; return new ZQueryCollection(parents); } closest(selector) { return new ZQueryCollection( this.elements.map(el => el.closest(selector)).filter(Boolean) ); } children(selector) { const kids = []; this.elements.forEach(el => { kids.push(...(selector ? el.querySelectorAll(`:scope > ${selector}`) : el.children)); }); return new ZQueryCollection([...kids]); } siblings() { const sibs = []; this.elements.forEach(el => { sibs.push(...[...el.parentElement.children].filter(c => c !== el)); }); 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)); } filter(selector) { if (typeof selector === 'function') { return new ZQueryCollection(this.elements.filter(selector)); } return new ZQueryCollection(this.elements.filter(el => el.matches(selector))); } not(selector) { if (typeof selector === 'function') { return new ZQueryCollection(this.elements.filter((el, i) => !selector.call(el, i, el))); } return new ZQueryCollection(this.elements.filter(el => !el.matches(selector))); } has(selector) { return new ZQueryCollection(this.elements.filter(el => el.querySelector(selector))); } addClass(...names) { const classes = names.flatMap(n => n.split(/\s+/)); return this.each((_, el) => el.classList.add(...classes)); } removeClass(...names) { const classes = names.flatMap(n => n.split(/\s+/)); return this.each((_, el) => el.classList.remove(...classes)); } toggleClass(name, force) { return this.each((_, el) => el.classList.toggle(name, force)); } hasClass(name) { return this.first()?.classList.contains(name) || false; } attr(name, value) { if (value === undefined) return this.first()?.getAttribute(name); return this.each((_, el) => el.setAttribute(name, value)); } removeAttr(name) { return this.each((_, el) => el.removeAttribute(name)); } prop(name, value) { if (value === undefined) return this.first()?.[name]; return this.each((_, el) => { el[name] = value; }); } data(key, value) { if (value === undefined) { if (key === undefined) return this.first()?.dataset; const raw = this.first()?.dataset[key]; try { return JSON.parse(raw); } catch { return raw; } } return this.each((_, el) => { el.dataset[key] = typeof value === 'object' ? JSON.stringify(value) : value; }); } css(props) { if (typeof props === 'string') { return getComputedStyle(this.first())[props]; } return this.each((_, el) => Object.assign(el.style, props)); } width() { return this.first()?.getBoundingClientRect().width; } height() { return this.first()?.getBoundingClientRect().height; } offset() { const r = this.first()?.getBoundingClientRect(); return r ? { top: r.top + window.scrollY, left: r.left + window.scrollX, width: r.width, height: r.height } : null; } position() { const el = this.first(); return el ? { top: el.offsetTop, left: el.offsetLeft } : null; } html(content) { if (content === undefined) return this.first()?.innerHTML; return this.each((_, el) => { el.innerHTML = content; }); } text(content) { if (content === undefined) return this.first()?.textContent; return this.each((_, el) => { el.textContent = content; }); } val(value) { if (value === undefined) return this.first()?.value; return this.each((_, el) => { el.value = value; }); } append(content) { return this.each((_, el) => { if (typeof content === 'string') el.insertAdjacentHTML('beforeend', content); else if (content instanceof ZQueryCollection) content.each((__, c) => el.appendChild(c)); else if (content instanceof Node) el.appendChild(content); }); } prepend(content) { return this.each((_, el) => { if (typeof content === 'string') el.insertAdjacentHTML('afterbegin', content); else if (content instanceof Node) el.insertBefore(content, el.firstChild); }); } after(content) { return this.each((_, el) => { if (typeof content === 'string') el.insertAdjacentHTML('afterend', content); else if (content instanceof Node) el.parentNode.insertBefore(content, el.nextSibling); }); } before(content) { return this.each((_, el) => { if (typeof content === 'string') el.insertAdjacentHTML('beforebegin', content); else if (content instanceof Node) el.parentNode.insertBefore(content, el); }); } wrap(wrapper) { return this.each((_, el) => { const w = typeof wrapper === 'string' ? createFragment(wrapper).firstElementChild : wrapper.cloneNode(true); el.parentNode.insertBefore(w, el); w.appendChild(el); }); } remove() { return this.each((_, el) => el.remove()); } empty() { return this.each((_, el) => { el.innerHTML = ''; }); } clone(deep = true) { return new ZQueryCollection(this.elements.map(el => el.cloneNode(deep))); } replaceWith(content) { return this.each((_, el) => { if (typeof content === 'string') { el.insertAdjacentHTML('afterend', content); el.remove(); } else if (content instanceof Node) { el.parentNode.replaceChild(content, el); } }); } show(display = '') { return this.each((_, el) => { el.style.display = display; }); } hide() { return this.each((_, el) => { el.style.display = 'none'; }); } toggle(display = '') { return this.each((_, el) => { el.style.display = (el.style.display === 'none' || getComputedStyle(el).display === 'none') ? display : 'none'; }); } on(event, selectorOrHandler, handler) { const events = event.split(/\s+/); return this.each((_, el) => { events.forEach(evt => { if (typeof selectorOrHandler === 'function') { el.addEventListener(evt, selectorOrHandler); } else { el.addEventListener(evt, (e) => { const target = e.target.closest(selectorOrHandler); if (target && el.contains(target)) handler.call(target, e); }); } }); }); } off(event, handler) { const events = event.split(/\s+/); return this.each((_, el) => { events.forEach(evt => el.removeEventListener(evt, handler)); }); } one(event, handler) { return this.each((_, el) => { el.addEventListener(event, handler, { once: true }); }); } trigger(event, detail) { return this.each((_, el) => { el.dispatchEvent(new CustomEvent(event, { detail, bubbles: true, cancelable: true })); }); } click(fn) { return fn ? this.on('click', fn) : this.trigger('click'); } submit(fn) { return fn ? this.on('submit', fn) : this.trigger('submit'); } focus() { this.first()?.focus(); return this; } blur() { this.first()?.blur(); return this; } animate(props, duration = 300, easing = 'ease') { return new Promise(resolve => { const count = { done: 0 }; this.each((_, el) => { el.style.transition = `all ${duration}ms ${easing}`; requestAnimationFrame(() => { Object.assign(el.style, props); const onEnd = () => { el.removeEventListener('transitionend', onEnd); el.style.transition = ''; if (++count.done >= this.length) resolve(this); }; el.addEventListener('transitionend', onEnd); }); }); setTimeout(() => resolve(this), duration + 50); }); } fadeIn(duration = 300) { return this.css({ opacity: '0', display: '' }).animate({ opacity: '1' }, duration); } fadeOut(duration = 300) { return this.animate({ opacity: '0' }, duration).then(col => col.hide()); } slideToggle(duration = 300) { return this.each((_, el) => { if (el.style.display === 'none' || getComputedStyle(el).display === 'none') { 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); } else { 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); } }); } serialize() { const form = this.first(); if (!form || form.tagName !== 'FORM') return ''; return new URLSearchParams(new FormData(form)).toString(); } serializeObject() { const form = this.first(); if (!form || form.tagName !== 'FORM') return {}; const obj = {}; new FormData(form).forEach((v, k) => { if (obj[k] !== undefined) { if (!Array.isArray(obj[k])) obj[k] = [obj[k]]; obj[k].push(v); } else { obj[k] = v; } }); return obj; }
+const T = { NUM: 1, STR: 2, IDENT: 3, OP: 4, PUNC: 5, TMPL: 6, EOF: 7
+function morph(rootEl, newHTML) { const template = document.createElement('template'); template.innerHTML = newHTML; const newRoot = template.content; const tempDiv = document.createElement('div'); while (newRoot.firstChild) tempDiv.appendChild(newRoot.firstChild); _morphChildren(rootEl, tempDiv);
+const _registry = new Map(); const _instances = new Map(); const _resourceCache = new Map(); let _uid = 0;
+class Router { constructor(config = {}) { this._el = null; const isFile = typeof location !== 'undefined' && location.protocol === 'file:'; this._mode = isFile ? 'hash' : (config.mode || 'history'); let rawBase = config.base; if (rawBase == null) { rawBase = (typeof window !== 'undefined' && window.__ZQ_BASE) || ''; if (!rawBase && typeof document !== 'undefined') { const baseEl = document.querySelector('base'); if (baseEl) { try { rawBase = new URL(baseEl.href).pathname; } catch { rawBase = baseEl.getAttribute('href') || ''; } if (rawBase === '/') rawBase = ''; } } } this._base = String(rawBase).replace(/\/+$/, ''); if (this._base && !this._base.startsWith('/')) this._base = '/' + this._base; this._routes = []; this._fallback = config.fallback || null; this._current = null; this._guards = { before: [], after: [] }; this._listeners = new Set(); this._instance = null; this._resolving = false; if (config.el) { this._el = typeof config.el === 'string' ? document.querySelector(config.el) : config.el; } if (config.routes) { config.routes.forEach(r => this.add(r)); } if (this._mode === 'hash') { window.addEventListener('hashchange', () => this._resolve()); } else { window.addEventListener('popstate', () => this._resolve()); } document.addEventListener('click', (e) => { if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return; const link = e.target.closest('[z-link]'); if (!link) return; if (link.getAttribute('target') === '_blank') return; e.preventDefault(); this.navigate(link.getAttribute('z-link')); }); if (this._el) { queueMicrotask(() => this._resolve()); } } add(route) { const keys = []; const pattern = route.path .replace(/:(\w+)/g, (_, key) => { keys.push(key); return '([^/]+)'; }) .replace(/\*/g, '(.*)'); const regex = new RegExp(`^${pattern}$`); this._routes.push({ ...route, _regex: regex, _keys: keys }); if (route.fallback) { const fbKeys = []; const fbPattern = route.fallback .replace(/:(\w+)/g, (_, key) => { fbKeys.push(key); return '([^/]+)'; }) .replace(/\*/g, '(.*)'); const fbRegex = new RegExp(`^${fbPattern}$`); this._routes.push({ ...route, path: route.fallback, _regex: fbRegex, _keys: fbKeys }); } return this; } remove(path) { this._routes = this._routes.filter(r => r.path !== path); return this; } navigate(path, options = {}) { const [cleanPath, fragment] = (path || '').split('#'); let normalized = this._normalizePath(cleanPath); const hash = fragment ? '#' + fragment : ''; if (this._mode === 'hash') { if (fragment) window.__zqScrollTarget = fragment; window.location.hash = '#' + normalized; } else { window.history.pushState(options.state || {}, '', this._base + normalized + hash); this._resolve(); } return this; } replace(path, options = {}) { const [cleanPath, fragment] = (path || '').split('#'); let normalized = this._normalizePath(cleanPath); const hash = fragment ? '#' + fragment : ''; if (this._mode === 'hash') { if (fragment) window.__zqScrollTarget = fragment; window.location.replace('#' + normalized); } else { window.history.replaceState(options.state || {}, '', this._base + normalized + hash); this._resolve(); } return this; } _normalizePath(path) { let p = path && path.startsWith('/') ? path : (path ? `/${path}` : '/'); if (this._base) { if (p === this._base) return '/'; if (p.startsWith(this._base + '/')) p = p.slice(this._base.length) || '/'; } return p; } resolve(path) { const normalized = path && path.startsWith('/') ? path : (path ? `/${path}` : '/'); return this._base + normalized; } back() { window.history.back(); return this; } forward() { window.history.forward(); return this; } go(n) { window.history.go(n); return this; } beforeEach(fn) { this._guards.before.push(fn); return this; } afterEach(fn) { this._guards.after.push(fn); return this; } onChange(fn) { this._listeners.add(fn); return () => this._listeners.delete(fn); } get current() { return this._current; } get base() { return this._base; } get path() { if (this._mode === 'hash') { const raw = window.location.hash.slice(1) || '/'; if (raw && !raw.startsWith('/')) { window.__zqScrollTarget = raw; const fallbackPath = (this._current && this._current.path) || '/'; window.location.replace('#' + fallbackPath); return fallbackPath; } return raw; } let pathname = window.location.pathname || '/'; if (pathname.length > 1 && pathname.endsWith('/')) { pathname = pathname.slice(0, -1); } if (this._base) { if (pathname === this._base) return '/'; if (pathname.startsWith(this._base + '/')) { return pathname.slice(this._base.length) || '/'; } } return pathname; } get query() { const search = this._mode === 'hash' ? (window.location.hash.split('?')[1] || '') : window.location.search.slice(1); return Object.fromEntries(new URLSearchParams(search)); } async _resolve() { if (this._resolving) return; this._resolving = true; try { await this.__resolve(); } finally { this._resolving = false; } } async __resolve() { const fullPath = this.path; const [pathPart, queryString] = fullPath.split('?'); const path = pathPart || '/'; const query = Object.fromEntries(new URLSearchParams(queryString || '')); let matched = null; let params = {}; for (const route of this._routes) { const m = path.match(route._regex); if (m) { matched = route; route._keys.forEach((key, i) => { params[key] = m[i + 1]; }); break; } } if (!matched && this._fallback) { matched = { component: this._fallback, path: '*', _keys: [], _regex: /.*/ }; } if (!matched) return; const to = { route: matched, params, query, path }; const from = this._current; for (const guard of this._guards.before) { try { const result = await guard(to, from); if (result === false) return; if (typeof result === 'string') { return this.navigate(result); } } catch (err) { reportError(ErrorCode.ROUTER_GUARD, 'Before-guard threw', { to, from }, err); return; } } if (matched.load) { try { await matched.load(); } catch (err) { reportError(ErrorCode.ROUTER_LOAD, `Failed to load module for route "${matched.path}"`, { path: matched.path }, err); return; } } this._current = to; if (this._el && matched.component) { if (this._instance) { this._instance.destroy(); this._instance = null; } this._el.innerHTML = ''; const props = { ...params, $route: to, $query: query, $params: params }; if (typeof matched.component === 'string') { const container = document.createElement(matched.component); this._el.appendChild(container); this._instance = mount(container, matched.component, props); } else if (typeof matched.component === 'function') { this._el.innerHTML = matched.component(to); } } for (const guard of this._guards.after) { await guard(to, from); } this._listeners.forEach(fn => fn(to, from)); } destroy() { if (this._instance) this._instance.destroy(); this._listeners.clear(); this._routes = []; this._guards = { before: [], after: [] }; }
+class Store { constructor(config = {}) { this._subscribers = new Map(); this._wildcards = new Set(); this._actions = config.actions || {}; this._getters = config.getters || {}; this._middleware = []; this._history = []; this._debug = config.debug || false; const initial = typeof config.state === 'function' ? config.state() : { ...(config.state || {}) }; this.state = reactive(initial, (key, value, old) => { const subs = this._subscribers.get(key); if (subs) subs.forEach(fn => { try { fn(value, old, key); } catch (err) { reportError(ErrorCode.STORE_SUBSCRIBE, `Subscriber for "${key}" threw`, { key }, err); } }); this._wildcards.forEach(fn => { try { fn(key, value, old); } catch (err) { reportError(ErrorCode.STORE_SUBSCRIBE, 'Wildcard subscriber threw', { key }, err); } }); }); this.getters = {}; for (const [name, fn] of Object.entries(this._getters)) { Object.defineProperty(this.getters, name, { get: () => fn(this.state.__raw || this.state), enumerable: true }); } } dispatch(name, ...args) { const action = this._actions[name]; if (!action) { reportError(ErrorCode.STORE_ACTION, `Unknown action "${name}"`, { action: name, args }); return; } for (const mw of this._middleware) { try { const result = mw(name, args, this.state); if (result === false) return; } 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); } 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); } } subscribe(keyOrFn, fn) { if (typeof keyOrFn === 'function') { this._wildcards.add(keyOrFn); return () => this._wildcards.delete(keyOrFn); } if (!this._subscribers.has(keyOrFn)) { this._subscribers.set(keyOrFn, new Set()); } this._subscribers.get(keyOrFn).add(fn); return () => this._subscribers.get(keyOrFn)?.delete(fn); } snapshot() { return JSON.parse(JSON.stringify(this.state.__raw || this.state)); } replaceState(newState) { const raw = this.state.__raw || this.state; for (const key of Object.keys(raw)) { delete this.state[key]; } Object.assign(this.state, newState); } use(fn) { this._middleware.push(fn); return this; } get history() { return [...this._history]; } reset(initialState) { this.replaceState(initialState); this._history = []; }
+const _config = { baseURL: '', headers: { 'Content-Type': 'application/json' }, timeout: 30000,
 function debounce(fn, ms = 250) { let timer; const debounced = (...args) => { clearTimeout(timer); timer = setTimeout(() => fn(...args), ms); }; debounced.cancel = () => clearTimeout(timer); return debounced;
-function $(selector, context) { if (typeof selector === 'function') { query.ready(selector); return; } return query(selector, context);
+function $(selector, context) { if (typeof selector === 'function') { query.ready(selector); return; } return query(selector, context);
 })(typeof window !== 'undefined' ? window : globalThis);

package/index.d.ts

@@ -4,7 +4,7 @@
  * Lightweight modern frontend library — jQuery-like selectors, reactive
  * components, SPA router, state management, HTTP client & utilities.
  *
- * @version 0.4.9
+ * @version 0.6.3
  * @license MIT
  * @see https://z-query.com/docs
  */
@@ -38,6 +38,11 @@ export class ZQueryCollection {
    */
   map<T>(fn: (this: Element, index: number, element: Element) => T): T[];
 
+  /**
+   * Iterate elements with Array-style `forEach`. Returns `this` for chaining.
+   */
+  forEach(fn: (element: Element, index: number, elements: Element[]) => void): this;
+
   /** First raw element, or `null`. */
   first(): Element | null;
 
@@ -384,6 +389,20 @@ interface ComponentDefinition {
   /** Called when the component is destroyed. Clean up subscriptions here. */
   destroyed?(this: ComponentInstance): void;
 
+  /**
+   * Computed properties — lazy getters derived from state.
+   * Each function receives the raw state as its argument.
+   * Access via `this.computed.name` in methods and templates.
+   */
+  computed?: Record<string, (state: Record<string, any>) => any>;
+
+  /**
+   * Watch state keys for changes.
+   * Keys support dot-path notation (e.g. `'user.name'`).
+   * Handler receives `(newValue, oldValue)`.
+   */
+  watch?: Record<string, ((this: ComponentInstance, newVal: any, oldVal: any) => void) | { handler: (this: ComponentInstance, newVal: any, oldVal: any) => void }>;
+
   /** Additional keys become instance methods (bound to the instance). */
   [method: string]: any;
 }
@@ -414,6 +433,12 @@ interface ComponentInstance {
   /** Active page id derived from route param (when using `pages` config). */
   activePage: string;
 
+  /**
+   * Computed properties — lazy getters derived from state.
+   * Defined via `computed` in the component definition.
+   */
+  readonly computed: Record<string, any>;
+
   /** Merge partial state (triggers re-render). */
   setState(partial: Record<string, any>): void;
 
@@ -491,6 +516,85 @@ interface StyleOptions {
 export function style(urls: string | string[], opts?: StyleOptions): StyleHandle;
 
 
+// ---------------------------------------------------------------------------
+// DOM Diffing (Morphing)
+// ---------------------------------------------------------------------------
+
+/**
+ * Morph an existing DOM element's children to match new HTML.
+ * Only touches nodes that actually differ — preserves focus, scroll
+ * positions, video playback, and other live DOM state.
+ *
+ * Use `z-key="uniqueId"` attributes on list items for keyed reconciliation.
+ *
+ * @param rootEl The live DOM container to patch.
+ * @param newHTML The desired HTML string.
+ */
+export function morph(rootEl: Element, newHTML: string): void;
+
+
+// ---------------------------------------------------------------------------
+// Safe Expression Evaluator
+// ---------------------------------------------------------------------------
+
+/**
+ * CSP-safe expression evaluator. Parses and evaluates JS expressions
+ * without `eval()` or `new Function()`. Used internally by directives.
+ *
+ * @param expr Expression string.
+ * @param scope Array of scope objects checked in order for identifier resolution.
+ * @returns Evaluation result, or `undefined` on error.
+ */
+export function safeEval(expr: string, scope: object[]): any;
+
+
+// ---------------------------------------------------------------------------
+// SSR (Server-Side Rendering)
+// ---------------------------------------------------------------------------
+
+/** SSR application instance for server-side component rendering. */
+interface SSRApp {
+  /** Register a component for SSR. */
+  component(name: string, definition: ComponentDefinition): SSRApp;
+
+  /**
+   * Render a component to an HTML string.
+   * @param componentName Registered component name.
+   * @param props Props to pass to the component.
+   * @param options Rendering options.
+   */
+  renderToString(
+    componentName: string,
+    props?: Record<string, any>,
+    options?: { hydrate?: boolean },
+  ): Promise<string>;
+
+  /**
+   * Render a full HTML page with a component mounted in a shell.
+   */
+  renderPage(options: {
+    component?: string;
+    props?: Record<string, any>;
+    title?: string;
+    styles?: string[];
+    scripts?: string[];
+    lang?: string;
+    meta?: string;
+    bodyAttrs?: string;
+  }): Promise<string>;
+}
+
+/** Create an SSR application instance. */
+export function createSSRApp(): SSRApp;
+
+/**
+ * Quick one-shot render of a component definition to an HTML string.
+ * @param definition Component definition object.
+ * @param props Props to pass.
+ */
+export function renderToString(definition: ComponentDefinition, props?: Record<string, any>): string;
+
+
 // ---------------------------------------------------------------------------
 // Directive System
 // ---------------------------------------------------------------------------
@@ -512,6 +616,11 @@ export function style(urls: string | string[], opts?: StyleOptions): StyleHandle
 //     n in 5                     Number range → [1, 2, 3, 4, 5].
 //     (val, key) in object       Object iteration → {key, value} entries.
 //
+//   z-key="uniqueId"           Keyed reconciliation for list items.
+//                              Preserves DOM nodes across reorders. Use inside
+//                              z-for to give each item a stable identity.
+//                              Example: <li z-for="item in items" z-key="{{item.id}}">
+//
 //   z-show="expression"        Toggle `display: none` (element stays in DOM).
 //
 // ─── Attribute Directives ───────────────────────────────────────────────
@@ -571,6 +680,20 @@ export function style(urls: string | string[], opts?: StyleOptions): StyleHandle
 //   z-pre                      Skip all directive processing for this element
 //                              and its descendants.
 //
+// ─── Slot System ────────────────────────────────────────────────────────
+//
+//   <slot>                     Default slot — replaced with child content
+//                              passed by the parent component.
+//   <slot name="header">       Named slot — replaced with child content that
+//                              has a matching slot="header" attribute.
+//   <slot>fallback</slot>      Fallback content shown when no slot content provided.
+//
+//   Parent usage:
+//     <my-component>
+//       <h1 slot="header">Title</h1>   (→ named slot "header")
+//       <p>Body text</p>               (→ default slot)
+//     </my-component>
+//
 // ─── Processing Order ───────────────────────────────────────────────────
 //
 //   1. z-for        (pre-innerHTML expansion)
@@ -1046,22 +1169,125 @@ interface EventBus {
 export const bus: EventBus;
 
 
+// ---------------------------------------------------------------------------
+// Error Handling
+// ---------------------------------------------------------------------------
+
+/** All structured error codes used by zQuery. */
+export const ErrorCode: {
+  // Reactive
+  readonly REACTIVE_CALLBACK: 'ZQ_REACTIVE_CALLBACK';
+  readonly SIGNAL_CALLBACK: 'ZQ_SIGNAL_CALLBACK';
+  readonly EFFECT_EXEC: 'ZQ_EFFECT_EXEC';
+
+  // Expression parser
+  readonly EXPR_PARSE: 'ZQ_EXPR_PARSE';
+  readonly EXPR_EVAL: 'ZQ_EXPR_EVAL';
+  readonly EXPR_UNSAFE_ACCESS: 'ZQ_EXPR_UNSAFE_ACCESS';
+
+  // Component
+  readonly COMP_INVALID_NAME: 'ZQ_COMP_INVALID_NAME';
+  readonly COMP_NOT_FOUND: 'ZQ_COMP_NOT_FOUND';
+  readonly COMP_MOUNT_TARGET: 'ZQ_COMP_MOUNT_TARGET';
+  readonly COMP_RENDER: 'ZQ_COMP_RENDER';
+  readonly COMP_LIFECYCLE: 'ZQ_COMP_LIFECYCLE';
+  readonly COMP_RESOURCE: 'ZQ_COMP_RESOURCE';
+  readonly COMP_DIRECTIVE: 'ZQ_COMP_DIRECTIVE';
+
+  // Router
+  readonly ROUTER_LOAD: 'ZQ_ROUTER_LOAD';
+  readonly ROUTER_GUARD: 'ZQ_ROUTER_GUARD';
+  readonly ROUTER_RESOLVE: 'ZQ_ROUTER_RESOLVE';
+
+  // Store
+  readonly STORE_ACTION: 'ZQ_STORE_ACTION';
+  readonly STORE_MIDDLEWARE: 'ZQ_STORE_MIDDLEWARE';
+  readonly STORE_SUBSCRIBE: 'ZQ_STORE_SUBSCRIBE';
+
+  // HTTP
+  readonly HTTP_REQUEST: 'ZQ_HTTP_REQUEST';
+  readonly HTTP_TIMEOUT: 'ZQ_HTTP_TIMEOUT';
+  readonly HTTP_INTERCEPTOR: 'ZQ_HTTP_INTERCEPTOR';
+  readonly HTTP_PARSE: 'ZQ_HTTP_PARSE';
+
+  // General
+  readonly INVALID_ARGUMENT: 'ZQ_INVALID_ARGUMENT';
+};
+
+/** Union of all error code string values. */
+export type ErrorCodeValue = typeof ErrorCode[keyof typeof ErrorCode];
+
+/** Structured error class used throughout zQuery. */
+export class ZQueryError extends Error {
+  readonly name: 'ZQueryError';
+  /** Machine-readable error code (e.g. `'ZQ_COMP_RENDER'`). */
+  readonly code: ErrorCodeValue;
+  /** Extra contextual data (component name, expression string, etc.). */
+  readonly context: Record<string, any>;
+  /** Original error that caused this one, if any. */
+  readonly cause?: Error;
+
+  constructor(
+    code: ErrorCodeValue,
+    message: string,
+    context?: Record<string, any>,
+    cause?: Error,
+  );
+}
+
+/** Error handler callback type. */
+export type ZQueryErrorHandler = (error: ZQueryError) => void;
+
+/**
+ * Register a global error handler. Called whenever zQuery catches an
+ * error internally. Pass `null` to remove.
+ */
+export function onError(handler: ZQueryErrorHandler | null): void;
+
+/**
+ * Report an error through the global handler and console.
+ * Non-throwing — used for recoverable errors in callbacks, lifecycle hooks, etc.
+ */
+export function reportError(
+  code: ErrorCodeValue,
+  message: string,
+  context?: Record<string, any>,
+  cause?: Error,
+): void;
+
+/**
+ * Wrap a callback so that thrown errors are caught, reported via `reportError`,
+ * and don't crash the current execution context.
+ */
+export function guardCallback<T extends (...args: any[]) => any>(
+  fn: T,
+  code: ErrorCodeValue,
+  context?: Record<string, any>,
+): (...args: Parameters<T>) => ReturnType<T> | undefined;
+
+/**
+ * Validate a required value is defined and of the expected type.
+ * Throws `ZQueryError` with `INVALID_ARGUMENT` on failure.
+ */
+export function validate(value: any, name: string, expectedType?: string): void;
+
+
 // ---------------------------------------------------------------------------
 // $ — Main function & namespace
 // ---------------------------------------------------------------------------
 
 /**
- * Main selector / DOM-ready function.
+ * Main selector / DOM-ready function — always returns a `ZQueryCollection` (like jQuery).
  *
- * - `$('selector')` → single Element via `querySelector`
- * - `$('<div>…</div>')` → create element from HTML
- * - `$(element)` → return as-is
+ * - `$('selector')` → ZQueryCollection via `querySelectorAll`
+ * - `$('<div>…</div>')` → ZQueryCollection from created elements
+ * - `$(element)` → ZQueryCollection wrapping the element
  * - `$(fn)` → DOMContentLoaded shorthand
  */
 interface ZQueryStatic {
-  (selector: string, context?: string | Element): Element | null;
-  (element: Element): Element;
-  (nodeList: NodeList | HTMLCollection | Element[]): Element | null;
+  (selector: string, context?: string | Element): ZQueryCollection;
+  (element: Element): ZQueryCollection;
+  (nodeList: NodeList | HTMLCollection | Element[]): ZQueryCollection;
   (fn: () => void): void;
 
   // -- Collection selector -------------------------------------------------
@@ -1082,12 +1308,14 @@ interface ZQueryStatic {
   id(id: string): Element | null;
   /** `document.querySelector('.name')` */
   class(name: string): Element | null;
-  /** `document.getElementsByClassName(name)` as array. */
-  classes(name: string): Element[];
-  /** `document.getElementsByTagName(name)` as array. */
-  tag(name: string): Element[];
-  /** Children of `#parentId` as array. */
-  children(parentId: string): Element[];
+  /** `document.getElementsByClassName(name)` as `ZQueryCollection`. */
+  classes(name: string): ZQueryCollection;
+  /** `document.getElementsByTagName(name)` as `ZQueryCollection`. */
+  tag(name: string): ZQueryCollection;
+  /** `document.getElementsByName(name)` as `ZQueryCollection`. */
+  name(name: string): ZQueryCollection;
+  /** Children of `#parentId` as `ZQueryCollection`. */
+  children(parentId: string): ZQueryCollection;
 
   // -- Static helpers ------------------------------------------------------
   /**
@@ -1117,6 +1345,7 @@ interface ZQueryStatic {
 
   // -- Reactive ------------------------------------------------------------
   reactive: typeof reactive;
+  Signal: typeof Signal;
   signal: typeof signal;
   computed: typeof computed;
   effect: typeof effect;
@@ -1130,6 +1359,8 @@ interface ZQueryStatic {
   /** Returns all registered component definitions. */
   components: typeof getRegistry;
   style: typeof style;
+  morph: typeof morph;
+  safeEval: typeof safeEval;
 
   // -- Router --------------------------------------------------------------
   router: typeof createRouter;
@@ -1147,6 +1378,14 @@ interface ZQueryStatic {
   patch: HttpClient['patch'];
   delete: HttpClient['delete'];
 
+  // -- Error Handling ------------------------------------------------------
+  /** Register a global error handler (or pass `null` to remove). */
+  onError: typeof onError;
+  /** Structured error class. */
+  ZQueryError: typeof ZQueryError;
+  /** Frozen map of all error code constants. */
+  ErrorCode: typeof ErrorCode;
+
   // -- Utilities -----------------------------------------------------------
   debounce: typeof debounce;
   throttle: typeof throttle;

package/index.js

@@ -10,17 +10,20 @@
  */
 
 import { query, queryAll, ZQueryCollection } from './src/core.js';
-import { reactive, signal, computed, effect } from './src/reactive.js';
+import { reactive, Signal, signal, computed, effect } from './src/reactive.js';
 import { component, mount, mountAll, getInstance, destroy, getRegistry, style } from './src/component.js';
 import { createRouter, getRouter } from './src/router.js';
 import { createStore, getStore } from './src/store.js';
 import { http } from './src/http.js';
+import { morph } from './src/diff.js';
+import { safeEval } from './src/expression.js';
 import {
   debounce, throttle, pipe, once, sleep,
   escapeHtml, html, trust, uuid, camelCase, kebabCase,
   deepClone, deepMerge, isEqual, param, parseQuery,
   storage, session, bus,
 } from './src/utils.js';
+import { ZQueryError, ErrorCode, onError, reportError } from './src/errors.js';
 
 
 // ---------------------------------------------------------------------------
@@ -28,16 +31,16 @@ import {
 // ---------------------------------------------------------------------------
 
 /**
- * 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
@@ -49,11 +52,14 @@ function $(selector, context) {
 }
 
 
-// --- Quick refs ------------------------------------------------------------
+// --- Quick refs (DOM selectors) --------------------------------------------
 $.id       = query.id;
 $.class    = query.class;
 $.classes  = query.classes;
 $.tag      = query.tag;
+Object.defineProperty($, 'name', {
+  value: query.name, writable: true, configurable: true
+});
 $.children = query.children;
 
 // --- Collection selector ---------------------------------------------------
@@ -82,6 +88,7 @@ $.fn       = query.fn;
 
 // --- Reactive primitives ---------------------------------------------------
 $.reactive = reactive;
+$.Signal   = Signal;
 $.signal   = signal;
 $.computed = computed;
 $.effect   = effect;
@@ -94,6 +101,8 @@ $.getInstance = getInstance;
 $.destroy     = destroy;
 $.components  = getRegistry;
 $.style       = style;
+$.morph       = morph;
+$.safeEval    = safeEval;
 
 // --- Router ----------------------------------------------------------------
 $.router    = createRouter;
@@ -132,6 +141,11 @@ $.storage    = storage;
 $.session    = session;
 $.bus        = bus;
 
+// --- Error handling --------------------------------------------------------
+$.onError     = onError;
+$.ZQueryError = ZQueryError;
+$.ErrorCode   = ErrorCode;
+
 // --- Meta ------------------------------------------------------------------
 $.version = '__VERSION__';
 $.meta    = {};                // populated at build time by CLI bundler
@@ -161,11 +175,14 @@ export {
   $ as zQuery,
   ZQueryCollection,
   queryAll,
-  reactive, signal, computed, effect,
+  reactive, Signal, signal, computed, effect,
   component, mount, mountAll, getInstance, destroy, getRegistry, style,
+  morph,
+  safeEval,
   createRouter, getRouter,
   createStore, getStore,
   http,
+  ZQueryError, ErrorCode, onError, reportError,
   debounce, throttle, pipe, once, sleep,
   escapeHtml, html, trust, uuid, camelCase, kebabCase,
   deepClone, deepMerge, isEqual, param, parseQuery,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zero-query",
-  "version": "0.4.9",
+  "version": "0.6.3",
   "description": "Lightweight modern frontend library — jQuery-like selectors, reactive components, SPA router, and state management with zero dependencies.",
   "main": "index.js",
   "types": "index.d.ts",
@@ -21,7 +21,9 @@
     "dev": "node cli/index.js dev zquery-website",
     "dev-lib": "node cli/index.js build --watch",
     "bundle": "node cli/index.js bundle",
-    "bundle:app": "node cli/index.js bundle zquery-website"
+    "bundle:app": "node cli/index.js bundle zquery-website --minimal",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "keywords": [
     "dom",
@@ -52,5 +54,9 @@
   },
   "dependencies": {
     "zero-http": "^0.2.3"
+  },
+  "devDependencies": {
+    "jsdom": "^28.1.0",
+    "vitest": "^4.0.18"
   }
 }