zero-query 0.6.3 → 0.7.5

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src=".github/images/logo.svg" alt="zQuery logo" width="300" height="300">
+  <img src=".github/images/logo-animated.svg" alt="zQuery logo" width="300" height="300">
 </p>
 
 <h1 align="center">zQuery</h1>
@@ -15,18 +15,18 @@
 
 </p>
 
-> **Lightweight, zero-dependency frontend library that combines jQuery-style DOM manipulation with a modern reactive component system, SPA router, global state management, HTTP client, and utility toolkit — all in a single ~84 KB minified browser bundle. Works out of the box with ES modules. An optional CLI bundler is available for single-file production builds.**
+> **Lightweight, zero-dependency frontend library that combines jQuery-style DOM manipulation with a modern reactive component system, SPA router, global state management, HTTP client, and utility toolkit — all in a single ~80 KB minified browser bundle. Works out of the box with ES modules. An optional CLI bundler is available for single-file production builds.**
 
 ## Features
 
 | Module | Highlights |
 | --- | --- |
-| **Core `$()`** | jQuery-like chainable selectors, traversal, DOM manipulation, events, animation |
+| **Router** | History & hash mode, route params (`:id`), guards, lazy loading, `z-link` navigation, `z-to-top` scroll modifier (`instant`/`smooth`) |
 | **Components** | Reactive state, template literals, `@event` delegation (8 modifiers), `z-model` two-way binding, computed properties, watch callbacks, slot-based content projection, directives (`z-if`/`z-else-if`/`z-else`, `z-for`, `z-show`, `z-bind`/`:attr`, `z-class`, `z-style`, `z-text`, `z-html`, `z-ref`, `z-cloak`, `z-pre`, `z-key`), DOM morphing engine (no innerHTML rebuild), CSP-safe expression evaluation, scoped styles, external templates (`templateUrl` / `styleUrl`), lifecycle hooks, auto-injected base styles |
-| **Router** | History & hash mode, route params (`:id`), guards, lazy loading, `z-link` navigation |
 | **Store** | Reactive global state, named actions, computed getters, middleware, subscriptions |
 | **HTTP** | Fetch wrapper with auto-JSON, interceptors, timeout/abort, base URL |
 | **Reactive** | Deep proxy reactivity, Signals, computed values, effects |
+| **Selectors & DOM** | jQuery-like chainable selectors, traversal, DOM manipulation, events, animation |
 | **Utils** | debounce, throttle, pipe, once, sleep, escapeHtml, uuid, deepClone, deepMerge, storage/session wrappers, event bus |
 
 ---
@@ -69,7 +69,7 @@ If you prefer **zero tooling**, download `dist/zQuery.min.js` from the [GitHub r
 git clone https://github.com/tonywied17/zero-query.git
 cd zero-query
 npx zquery build
-# → dist/zQuery.min.js  (~84 KB)
+# → dist/zQuery.min.js  (~80 KB)
 ```
 
 ### Include in HTML
@@ -278,7 +278,7 @@ For full method signatures, options, and examples, see **[API.md](API.md)**.
 
 ## Editor Support
 
-The official **[zQuery for VS Code](https://marketplace.visualstudio.com/items?itemName=zQuery.zquery-vs-code)** extension provides autocomplete, hover docs, HTML directive support, and 140+ code snippets for every API method and directive. Install it from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=zQuery.zquery-vs-code) or search **"zQuery for VS Code"** in Extensions.
+The official **[zQuery for VS Code](https://marketplace.visualstudio.com/items?itemName=zQuery.zquery-vs-code)** extension provides autocomplete, hover docs, HTML directive support, and 185+ code snippets for every API method and directive. Install it from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=zQuery.zquery-vs-code) or search **"zQuery for VS Code"** in Extensions.
 
 ---
 

package/cli/commands/build.js

@@ -34,7 +34,7 @@ function buildLibrary() {
     code = code.replace(/^import\s+[\s\S]*?from\s+['"].*?['"];?\s*$/gm, '');
     code = code.replace(/^export\s+(default\s+)?/gm, '');
     code = code.replace(/^export\s*\{[\s\S]*?\};\s*$/gm, '');
-    return `// --- ${file} ${'—'.repeat(60 - file.length)}\n${code.trim()}`;
+    return `// --- ${file} ${'-'.repeat(60 - file.length)}\n${code.trim()}`;
   });
 
   let indexCode = fs.readFileSync(path.join(process.cwd(), 'index.js'), 'utf-8');
@@ -42,9 +42,9 @@ function buildLibrary() {
   indexCode = indexCode.replace(/^export\s*\{[\s\S]*?\};\s*$/gm, '');
   indexCode = indexCode.replace(/^export\s+(default\s+)?/gm, '');
 
-  const banner = `/**\n * zQuery (zeroQuery) v${VERSION}\n * Lightweight Frontend Library\n * https://github.com/tonywied17/zero-query\n * (c) ${new Date().getFullYear()} Anthony Wiedman — MIT License\n */`;
+  const banner = `/**\n * zQuery (zeroQuery) v${VERSION}\n * Lightweight Frontend Library\n * https://github.com/tonywied17/zero-query\n * (c) ${new Date().getFullYear()} Anthony Wiedman - MIT License\n */`;
 
-  const bundle = `${banner}\n(function(global) {\n  'use strict';\n\n${parts.join('\n\n')}\n\n// --- index.js (assembly) ${'—'.repeat(42)}\n${indexCode.trim().replace("'__VERSION__'", `'${VERSION}'`)}\n\n})(typeof window !== 'undefined' ? window : globalThis);\n`;
+  const bundle = `${banner}\n(function(global) {\n  'use strict';\n\n${parts.join('\n\n')}\n\n// --- index.js (assembly) ${'-'.repeat(42)}\n${indexCode.trim().replace("'__VERSION__'", `'${VERSION}'`)}\n\n})(typeof window !== 'undefined' ? window : globalThis);\n`;
 
   fs.writeFileSync(OUT_FILE, bundle, 'utf-8');
   fs.writeFileSync(MIN_FILE, minify(bundle, banner), 'utf-8');

package/cli/commands/bundle.js

@@ -24,6 +24,8 @@ const buildLibrary             = require('./build');
 /** Resolve an import specifier relative to the importing file. */
 function resolveImport(specifier, fromFile) {
   if (!specifier.startsWith('.') && !specifier.startsWith('/')) return null;
+  // Skip non-JS assets (CSS, images, etc.) referenced in code examples
+  if (/\.(?:css|json|svg|png|jpg|gif|woff2?|ttf|eot)$/i.test(specifier)) return null;
   let resolved = path.resolve(path.dirname(fromFile), specifier);
   if (!path.extname(resolved) && fs.existsSync(resolved + '.js')) {
     resolved += '.js';
@@ -112,6 +114,243 @@ function rewriteResourceUrls(code, filePath, projectRoot) {
   );
 }
 
+/**
+ * Minify HTML for inlining — strips indentation and collapses whitespace
+ * between tags.  Preserves content inside <pre>, <code>, and <textarea>
+ * blocks verbatim so syntax-highlighted code samples survive.
+ */
+function minifyHTML(html) {
+  const preserved = [];
+  // Protect <pre>…</pre> and <textarea>…</textarea> (multiline code blocks)
+  html = html.replace(/<(pre|textarea)(\b[^>]*)>[\s\S]*?<\/\1>/gi, m => {
+    preserved.push(m);
+    return `\x00P${preserved.length - 1}\x00`;
+  });
+  // Strip HTML comments
+  html = html.replace(/<!--[\s\S]*?-->/g, '');
+  // Collapse runs of whitespace (newlines + indentation) to a single space
+  html = html.replace(/\s{2,}/g, ' ');
+  // Remove space between tags: "> <" → "><"
+  // but preserve a space when an inline element is involved (a, span, strong, em, b, i, code, small, sub, sup, abbr, label)
+  html = html.replace(/>\s+</g, (m, offset) => {
+    const before = html.slice(Math.max(0, offset - 80), offset + 1);
+    const after  = html.slice(offset + m.length - 1, offset + m.length + 40);
+    const inlineTags = /\b(a|span|strong|em|b|i|code|small|sub|sup|abbr|label)\b/i;
+    const closingInline = /<\/\s*(a|span|strong|em|b|i|code|small|sub|sup|abbr|label)\s*>$/i.test(before);
+    const openingInline = /^<(a|span|strong|em|b|i|code|small|sub|sup|abbr|label)[\s>]/i.test(after);
+    return (closingInline || openingInline) ? '> <' : '><';
+  });
+  // Remove spaces inside opening tags:  <tag  attr = "val" > → <tag attr="val">
+  html = html.replace(/ *\/ *>/g, '/>');
+  html = html.replace(/ *= */g, '=');
+  // Trim
+  html = html.trim();
+  // Restore preserved blocks
+  html = html.replace(/\x00P(\d+)\x00/g, (_, i) => preserved[+i]);
+  return html;
+}
+
+/**
+ * Minify CSS for inlining — strips comments, collapses whitespace,
+ * removes unnecessary spaces around punctuation.
+ */
+function minifyCSS(css) {
+  // Strip block comments
+  css = css.replace(/\/\*[\s\S]*?\*\//g, '');
+  // Collapse whitespace
+  css = css.replace(/\s{2,}/g, ' ');
+  // Remove spaces around { } : ; ,
+  css = css.replace(/\s*([{};:,])\s*/g, '$1');
+  // Remove trailing semicolons before }
+  css = css.replace(/;}/g, '}');
+  return css.trim();
+}
+
+/**
+ * Walk JS source and minify the HTML/CSS inside template literals.
+ * Handles ${…} interpolations (with nesting) and preserves <pre> blocks.
+ * Only trims whitespace sequences that appear between/around HTML tags.
+ */
+function minifyTemplateLiterals(code) {
+  let out = '';
+  let i = 0;
+  while (i < code.length) {
+    const ch = code[i];
+
+    // Regular string: copy verbatim
+    if (ch === '"' || ch === "'") {
+      const q = ch; out += ch; i++;
+      while (i < code.length) {
+        if (code[i] === '\\') { out += code[i] + (code[i + 1] || ''); i += 2; continue; }
+        out += code[i];
+        if (code[i] === q) { i++; break; }
+        i++;
+      }
+      continue;
+    }
+
+    // Line comment: copy verbatim
+    if (ch === '/' && code[i + 1] === '/') {
+      while (i < code.length && code[i] !== '\n') out += code[i++];
+      continue;
+    }
+    // Block comment: copy verbatim
+    if (ch === '/' && code[i + 1] === '*') {
+      out += '/*'; i += 2;
+      while (i < code.length && !(code[i] === '*' && code[i + 1] === '/')) out += code[i++];
+      out += '*/'; i += 2;
+      continue;
+    }
+
+    // Template literal: extract, minify HTML, and emit
+    if (ch === '`') {
+      out += _minifyTemplate(code, i);
+      // Advance past the template
+      i = _skipTemplateLiteral(code, i);
+      continue;
+    }
+
+    out += ch; i++;
+  }
+  return out;
+}
+
+/** Extract a full template literal (handling nested ${…}) and return it minified. */
+function _minifyTemplate(code, start) {
+  const end = _skipTemplateLiteral(code, start);
+  const raw = code.substring(start, end);
+  // Only minify templates that contain HTML tags or CSS rules
+  if (/<\w/.test(raw)) return _collapseTemplateWS(raw);
+  if (/[{};]\s/.test(raw) && /[.#\w-]+\s*\{/.test(raw)) return _collapseTemplateCSS(raw);
+  return raw;
+}
+
+/** Return index past the closing backtick of a template starting at `start`. */
+function _skipTemplateLiteral(code, start) {
+  let i = start + 1; // skip opening backtick
+  let depth = 0;
+  while (i < code.length) {
+    if (code[i] === '\\') { i += 2; continue; }
+    if (code[i] === '$' && code[i + 1] === '{') { depth++; i += 2; continue; }
+    if (depth > 0) {
+      if (code[i] === '{') { depth++; i++; continue; }
+      if (code[i] === '}') { depth--; i++; continue; }
+      if (code[i] === '`') { i = _skipTemplateLiteral(code, i); continue; }
+      if (code[i] === '"' || code[i] === "'") {
+        const q = code[i]; i++;
+        while (i < code.length) {
+          if (code[i] === '\\') { i += 2; continue; }
+          if (code[i] === q) { i++; break; }
+          i++;
+        }
+        continue;
+      }
+      i++; continue;
+    }
+    if (code[i] === '`') { i++; return i; } // closing backtick
+    i++;
+  }
+  return i;
+}
+
+/**
+ * Collapse whitespace in the text portions of an HTML template literal,
+ * preserving ${…} expressions, <pre> blocks, and inline text spacing.
+ */
+function _collapseTemplateWS(tpl) {
+  // Build array of segments: text portions vs ${…} expressions
+  const segments = [];
+  let i = 1; // skip opening backtick
+  let text = '';
+  while (i < tpl.length - 1) { // stop before closing backtick
+    if (tpl[i] === '\\') { text += tpl[i] + (tpl[i + 1] || ''); i += 2; continue; }
+    if (tpl[i] === '$' && tpl[i + 1] === '{') {
+      if (text) { segments.push({ type: 'text', val: text }); text = ''; }
+      // Collect the full expression
+      let depth = 1; let expr = '${'; i += 2;
+      while (i < tpl.length - 1 && depth > 0) {
+        if (tpl[i] === '\\') { expr += tpl[i] + (tpl[i + 1] || ''); i += 2; continue; }
+        if (tpl[i] === '{') depth++;
+        if (tpl[i] === '}') depth--;
+        if (depth > 0) { expr += tpl[i]; i++; } else { expr += '}'; i++; }
+      }
+      segments.push({ type: 'expr', val: expr });
+      continue;
+    }
+    text += tpl[i]; i++;
+  }
+  if (text) segments.push({ type: 'text', val: text });
+
+  // Minify text segments (collapse whitespace between/around tags)
+  for (let s = 0; s < segments.length; s++) {
+    if (segments[s].type !== 'text') continue;
+    let t = segments[s].val;
+    // Protect <pre>…</pre> regions
+    const preserved = [];
+    t = t.replace(/<pre(\b[^>]*)>[\s\S]*?<\/pre>/gi, m => {
+      preserved.push(m);
+      return `\x00P${preserved.length - 1}\x00`;
+    });
+    // Collapse whitespace runs that touch a < or > but preserve a space
+    // when an inline element boundary is involved
+    t = t.replace(/>\s{2,}/g, (m, offset) => {
+      const before = t.slice(Math.max(0, offset - 80), offset + 1);
+      if (/<\/\s*(a|span|strong|em|b|i|code|small|sub|sup|abbr|label)\s*>$/i.test(before)) return '> ';
+      return '>';
+    });
+    t = t.replace(/\s{2,}</g, (m, offset) => {
+      const after = t.slice(offset + m.length - 1, offset + m.length + 40);
+      if (/^<(a|span|strong|em|b|i|code|small|sub|sup|abbr|label)[\s>]/i.test(after)) return ' <';
+      return '<';
+    });
+    // Collapse other multi-whitespace runs to a single space
+    t = t.replace(/\s{2,}/g, ' ');
+    // Restore <pre> blocks
+    t = t.replace(/\x00P(\d+)\x00/g, (_, idx) => preserved[+idx]);
+    segments[s].val = t;
+  }
+
+  return '`' + segments.map(s => s.val).join('') + '`';
+}
+
+/**
+ * Collapse CSS whitespace inside a template literal (styles: `…`).
+ * Uses the same segment-splitting approach as _collapseTemplateWS so
+ * ${…} expressions are preserved untouched.
+ */
+function _collapseTemplateCSS(tpl) {
+  const segments = [];
+  let i = 1; let text = '';
+  while (i < tpl.length - 1) {
+    if (tpl[i] === '\\') { text += tpl[i] + (tpl[i + 1] || ''); i += 2; continue; }
+    if (tpl[i] === '$' && tpl[i + 1] === '{') {
+      if (text) { segments.push({ type: 'text', val: text }); text = ''; }
+      let depth = 1; let expr = '${'; i += 2;
+      while (i < tpl.length - 1 && depth > 0) {
+        if (tpl[i] === '\\') { expr += tpl[i] + (tpl[i + 1] || ''); i += 2; continue; }
+        if (tpl[i] === '{') depth++;
+        if (tpl[i] === '}') depth--;
+        if (depth > 0) { expr += tpl[i]; i++; } else { expr += '}'; i++; }
+      }
+      segments.push({ type: 'expr', val: expr });
+      continue;
+    }
+    text += tpl[i]; i++;
+  }
+  if (text) segments.push({ type: 'text', val: text });
+
+  for (let s = 0; s < segments.length; s++) {
+    if (segments[s].type !== 'text') continue;
+    let t = segments[s].val;
+    t = t.replace(/\/\*[\s\S]*?\*\//g, '');
+    t = t.replace(/\s{2,}/g, ' ');
+    t = t.replace(/\s*([{};:,])\s*/g, '$1');
+    t = t.replace(/;}/g, '}');
+    segments[s].val = t;
+  }
+  return '`' + segments.map(s => s.val).join('') + '`';
+}
+
 /**
  * Scan bundled source files for external resource references
  * (pages config, templateUrl, styleUrl) and return a map of
@@ -152,7 +391,8 @@ function collectInlineResources(files, projectRoot) {
     }
 
     // styleUrl:
-    const styleMatch = code.match(/styleUrl\s*:\s*['"]([^'"]+)['"]/);
+    const styleUrlRe = /styleUrl\s*:\s*['"]([^'"]+)['"]/g;
+    const styleMatch = styleUrlRe.exec(code);
     if (styleMatch) {
       const stylePath = path.join(fileDir, styleMatch[1]);
       if (fs.existsSync(stylePath)) {
@@ -172,6 +412,12 @@ function collectInlineResources(files, projectRoot) {
     }
   }
 
+  // Minify inlined resources by type
+  for (const key of Object.keys(inlineMap)) {
+    if (key.endsWith('.html')) inlineMap[key] = minifyHTML(inlineMap[key]);
+    else if (key.endsWith('.css')) inlineMap[key] = minifyCSS(inlineMap[key]);
+  }
+
   return inlineMap;
 }
 
@@ -316,6 +562,37 @@ function rewriteHtml(projectRoot, htmlRelPath, bundleFile, includeLib, bundledFi
     assets.add(ref);
   }
 
+  // Also scan the bundled JS for src/href references to local assets
+  const bundleContent = fs.existsSync(bundleFile) ? fs.readFileSync(bundleFile, 'utf-8') : '';
+  const jsAssetRe = /\b(?:src|href)\s*=\s*["\\]*["']([^"']+\.(?:svg|png|jpg|jpeg|gif|webp|ico|woff2?|ttf|eot|mp4|webm))["']/gi;
+  while ((m = jsAssetRe.exec(bundleContent)) !== null) {
+    const ref = m[1];
+    if (ref.startsWith('http') || ref.startsWith('//') || ref.startsWith('data:')) continue;
+    if (!assets.has(ref)) {
+      const refAbs = path.resolve(htmlDir, ref);
+      if (fs.existsSync(refAbs)) assets.add(ref);
+    }
+  }
+
+  // For any referenced asset directories, copy all sibling files too
+  const assetDirs = new Set();
+  for (const asset of assets) {
+    const dir = path.dirname(asset);
+    if (dir && dir !== '.') assetDirs.add(dir);
+  }
+  for (const dir of assetDirs) {
+    const absDirPath = path.resolve(htmlDir, dir);
+    if (fs.existsSync(absDirPath) && fs.statSync(absDirPath).isDirectory()) {
+      for (const child of fs.readdirSync(absDirPath)) {
+        const childRel = path.join(dir, child).replace(/\\/g, '/');
+        const childAbs = path.join(absDirPath, child);
+        if (fs.statSync(childAbs).isFile() && !assets.has(childRel)) {
+          assets.add(childRel);
+        }
+      }
+    }
+  }
+
   // Copy assets into both dist dirs
   let copiedCount = 0;
   for (const asset of assets) {
@@ -574,8 +851,9 @@ function bundleApp() {
     code = stripModuleSyntax(code);
     code = replaceImportMeta(code, file, projectRoot);
     code = rewriteResourceUrls(code, file, projectRoot);
+    code = minifyTemplateLiterals(code);
     const rel = path.relative(projectRoot, file);
-    return `// --- ${rel} ${'—'.repeat(Math.max(1, 60 - rel.length))}\n${code.trim()}`;
+    return `// --- ${rel} ${'-'.repeat(Math.max(1, 60 - rel.length))}\n${code.trim()}`;
   });
 
   // Embed zquery.min.js
@@ -612,8 +890,8 @@ function bundleApp() {
 
     if (libPath) {
       const libBytes = fs.statSync(libPath).size;
-      libSection = `// --- zquery.min.js (library) ${'—'.repeat(34)}\n${fs.readFileSync(libPath, 'utf-8').trim()}\n\n`
-                 + `// --- Build-time metadata ————————————————————————————\nif(typeof $!=="undefined"){$.meta=Object.assign($.meta||{},{libSize:${libBytes}});}\n\n`;
+      libSection = `// --- zquery.min.js (library) ${'-'.repeat(34)}\n${fs.readFileSync(libPath, 'utf-8').trim()}\n\n`
+                 + `// --- Build-time metadata ${'-'.repeat(50)}\nif(typeof $!=="undefined"){$.meta=Object.assign($.meta||{},{libSize:${libBytes}});}\n\n`;
       console.log(`  Embedded library from ${path.relative(projectRoot, libPath)} (${(libBytes / 1024).toFixed(1)} KB)`);
     } else {
       console.warn(`\n  ⚠  Could not find zquery.min.js anywhere`);
@@ -621,7 +899,7 @@ function bundleApp() {
     }
   }
 
-  const banner = `/**\n * App bundle — built by zQuery CLI\n * Entry: ${entryRel}\n * ${new Date().toISOString()}\n */`;
+  const banner = `/**\n * App bundle - built by zQuery CLI\n * Entry: ${entryRel}\n * ${new Date().toISOString()}\n */`;
 
   // Inline resources
   const inlineMap = collectInlineResources(files, projectRoot);
@@ -635,7 +913,7 @@ function bundleApp() {
         .replace(/\r/g, '');
       return `  '${key}': '${escaped}'`;
     });
-    inlineSection = `// --- Inlined resources (file:// support) ${'—'.repeat(20)}\nwindow.__zqInline = {\n${entries.join(',\n')}\n};\n\n`;
+    inlineSection = `// --- Inlined resources (file:// support) ${'-'.repeat(20)}\nwindow.__zqInline = {\n${entries.join(',\n')}\n};\n\n`;
     console.log(`\n  Inlined ${Object.keys(inlineMap).length} external resource(s)`);
   }
 
@@ -668,10 +946,10 @@ function bundleApp() {
   console.log(`\n  ✓ ${bundleBase} (${sizeKB(fs.readFileSync(bundleFile))} KB)`);
   console.log(`  ✓ ${minBase} (${sizeKB(fs.readFileSync(minFile))} KB)`);
 
-  // Rewrite HTML (use full bundle — minified version mangles template literal whitespace)
+  // Rewrite HTML to reference the minified bundle
   const bundledFileSet = new Set(files);
   if (htmlFile) {
-    rewriteHtml(projectRoot, htmlFile, bundleFile, true, bundledFileSet, serverDir, localDir);
+    rewriteHtml(projectRoot, htmlFile, minFile, true, bundledFileSet, serverDir, localDir);
   }
 
   // Copy static asset directories (icons/, images/, fonts/, etc.)

package/cli/commands/dev/index.js

@@ -46,14 +46,14 @@ function resolveRoot(htmlEntry) {
 // devServer — main entry point (called from cli/index.js)
 // ---------------------------------------------------------------------------
 
-function devServer() {
+async function devServer() {
   const htmlEntry   = option('index', 'i', 'index.html');
   const port        = parseInt(option('port', 'p', '3100'), 10);
   const noIntercept = flag('no-intercept');
   const root        = resolveRoot(htmlEntry);
 
   // Start HTTP server + SSE pool
-  const { app, pool, listen } = createServer({ root, htmlEntry, port, noIntercept });
+  const { app, pool, listen } = await createServer({ root, htmlEntry, port, noIntercept });
 
   // Start file watcher
   const watcher = startWatcher({ root, pool });

package/cli/commands/dev/overlay.js

@@ -281,14 +281,63 @@ const OVERLAY_SCRIPT = `<script>
       location.reload();
     });
 
-    es.addEventListener('css', function() {
+    es.addEventListener('css', function(e) {
+      var changedPath = (e.data || '').replace(/^\\/+/, '');
+      var matched = false;
+
+      // 1) Try cache-busting matching <link rel="stylesheet"> tags
       var sheets = document.querySelectorAll('link[rel="stylesheet"]');
       sheets.forEach(function(l) {
         var href = l.getAttribute('href');
         if (!href) return;
+        var clean = href.replace(/[?&]_zqr=\\d+/, '').replace(/^\\/+/, '');
+        if (changedPath && clean.indexOf(changedPath) === -1) return;
+        matched = true;
         var sep = href.indexOf('?') >= 0 ? '&' : '?';
-        l.setAttribute('href', href.replace(/[?&]_zqr=\\\\d+/, '') + sep + '_zqr=' + Date.now());
+        l.setAttribute('href', href.replace(/[?&]_zqr=\\d+/, '') + sep + '_zqr=' + Date.now());
       });
+
+      // 2) Try hot-swapping scoped <style data-zq-style-urls> elements
+      //    These come from component styleUrl — the CSS was fetched, scoped,
+      //    and injected as an inline <style>. We re-fetch and re-scope it.
+      if (!matched) {
+        var scopedEls = document.querySelectorAll('style[data-zq-style-urls]');
+        scopedEls.forEach(function(el) {
+          var urls = el.getAttribute('data-zq-style-urls') || '';
+          var hit = urls.split(' ').some(function(u) {
+            return u && u.replace(/^\\/+/, '').indexOf(changedPath) !== -1;
+          });
+          if (!hit) return;
+          matched = true;
+
+          var scopeAttr = el.getAttribute('data-zq-scope') || '';
+          var inlineStyles = el.getAttribute('data-zq-inline') || '';
+
+          // Re-fetch all style URLs (cache-busted)
+          var urlList = urls.split(' ').filter(Boolean);
+          Promise.all(urlList.map(function(u) {
+            return fetch(u + (u.indexOf('?') >= 0 ? '&' : '?') + '_zqr=' + Date.now())
+              .then(function(r) { return r.text(); });
+          })).then(function(results) {
+            var raw = (inlineStyles ? inlineStyles + '\\n' : '') + results.join('\\n');
+            // Re-scope CSS with the same scope attribute
+            if (scopeAttr) {
+              var inAt = 0;
+              raw = raw.replace(/([^{}]+)\\{|\\}/g, function(m, sel) {
+                if (m === '}') { if (inAt > 0) inAt--; return m; }
+                var t = sel.trim();
+                if (t.charAt(0) === '@') { inAt++; return m; }
+                if (inAt > 0 && /^[\\d%\\s,fromto]+$/.test(t.replace(/\\s/g, ''))) return m;
+                return sel.split(',').map(function(s) { return '[' + scopeAttr + '] ' + s.trim(); }).join(', ') + ' {';
+              });
+            }
+            el.textContent = raw;
+          });
+        });
+      }
+
+      // 3) Nothing matched — fall back to full reload
+      if (!matched) { location.reload(); }
     });
 
     es.addEventListener('error:syntax', function(e) {

package/cli/commands/dev/server.js

@@ -44,22 +44,51 @@ class SSEPool {
 // Server factory
 // ---------------------------------------------------------------------------
 
+/**
+ * Prompt the user to auto-install zero-http when it isn't found.
+ * Resolves `true` if the user accepts, `false` otherwise.
+ */
+function promptInstall() {
+  const rl = require('readline').createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  return new Promise((resolve) => {
+    rl.question(
+      '\n  The local dev server requires zero-http, which is not installed.\n' +
+      '  This package is only used during development and is not needed\n' +
+      '  for building, bundling, or production.\n' +
+      '  Install it now? (y/n): ',
+      (answer) => {
+        rl.close();
+        resolve(answer.trim().toLowerCase() === 'y');
+      }
+    );
+  });
+}
+
 /**
  * @param {object} opts
  * @param {string} opts.root        — absolute path to project root
  * @param {string} opts.htmlEntry   — e.g. 'index.html'
  * @param {number} opts.port
  * @param {boolean} opts.noIntercept — skip zquery.min.js auto-resolve
- * @returns {{ app, pool: SSEPool, listen: Function }}
+ * @returns {Promise<{ app, pool: SSEPool, listen: Function }>}
  */
-function createServer({ root, htmlEntry, port, noIntercept }) {
+async function createServer({ root, htmlEntry, port, noIntercept }) {
   let zeroHttp;
   try {
     zeroHttp = require('zero-http');
   } catch {
-    console.error(`\n  \u2717 zero-http is required for the dev server.`);
-    console.error(`    Install it: npm install zero-http --save-dev\n`);
-    process.exit(1);
+    const ok = await promptInstall();
+    if (!ok) {
+      console.error('\n  ✖ Cannot start dev server without zero-http.\n');
+      process.exit(1);
+    }
+    const { execSync } = require('child_process');
+    console.log('\n  Installing zero-http...\n');
+    execSync('npm install zero-http --save-dev', { stdio: 'inherit' });
+    zeroHttp = require('zero-http');
   }
 
   const { createApp, static: serveStatic } = zeroHttp;

package/cli/commands/dev/watcher.js

@@ -28,6 +28,14 @@ function isIgnored(filepath) {
   return filepath.split(path.sep).some(p => IGNORE_DIRS.has(p));
 }
 
+/**
+ * Return the file's mtime as a millisecond timestamp, or 0 if unreadable.
+ * Used to ignore spurious fs.watch events (Windows fires on reads too).
+ */
+function mtime(filepath) {
+  try { return fs.statSync(filepath).mtimeMs; } catch { return 0; }
+}
+
 /** Recursively collect every directory under `dir` (excluding ignored). */
 function collectWatchDirs(dir) {
   const dirs = [dir];
@@ -59,6 +67,24 @@ function startWatcher({ root, pool }) {
   let debounceTimer;
   let currentError = null;   // track which file has an active error
 
+  // Track file mtimes so we only react to genuine writes.
+  // On Windows, fs.watch fires on reads/access too, which causes
+  // spurious reloads the first time the server serves a file.
+  // We seed the cache with current mtimes so the first real save
+  // (which changes the mtime) is always detected.
+  const mtimeCache = new Map();
+  for (const d of watchDirs) {
+    try {
+      for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+        if (entry.isFile()) {
+          const fp = path.join(d, entry.name);
+          const mt = mtime(fp);
+          if (mt) mtimeCache.set(fp, mt);
+        }
+      }
+    } catch { /* skip */ }
+  }
+
   for (const dir of watchDirs) {
     try {
       const watcher = fs.watch(dir, (_, filename) => {
@@ -68,6 +94,13 @@ function startWatcher({ root, pool }) {
 
         clearTimeout(debounceTimer);
         debounceTimer = setTimeout(() => {
+          // Skip if the file hasn't actually been modified
+          const mt = mtime(fullPath);
+          if (mt === 0) return;                 // deleted or unreadable
+          const prev = mtimeCache.get(fullPath);
+          mtimeCache.set(fullPath, mt);
+          if (prev !== undefined && mt === prev) return; // unchanged
+
           const rel = path.relative(root, fullPath).replace(/\\/g, '/');
           const ext = path.extname(filename).toLowerCase();
 

package/cli/scaffold/index.html

@@ -6,6 +6,7 @@
   <title>{{NAME}}</title>
   <base href="/">
   <link rel="stylesheet" href="styles/styles.css">
+  <link rel="icon" type="image/png" href="favicon.ico">
   <script src="scripts/vendor/zquery.min.js"></script>
   <script type="module" src="scripts/app.js"></script>
 </head>