zero-query 0.5.2 → 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 ~54 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 |
-| **Components** | Reactive state, template literals, `@event` delegation (8 modifiers), `z-model` two-way binding, 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`), scoped styles, external templates (`templateUrl` / `styleUrl`), lifecycle hooks, auto-injected base styles (`z-cloak` hiding, mobile tap-highlight suppression) |
-| **Router** | History & hash mode, route params (`:id`), guards, lazy loading, `z-link` navigation |
+| **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 |
 | **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  (~54 KB)
+# → dist/zQuery.min.js  (~80 KB)
 ```
 
 ### Include in HTML
@@ -240,13 +240,15 @@ location / {
 
 | Namespace | Methods |
 | --- | --- |
-| `$()` | Single-element selector → `Element \| null` |
-| `$.all()` | Collection selector → `ZQueryCollection` |
-| `$.id` `$.class` `$.classes` `$.tag` `$.children` | Quick DOM refs |
+| `$()` | Chainable selector → `ZQueryCollection` (CSS selectors, elements, NodeLists, HTML strings) |
+| `$.all()` | Alias for `$()` — identical behavior |
+| `$.id` `$.class` `$.classes` `$.tag` `$.name` `$.children` | Quick DOM refs |
 | `$.create` | Element factory |
 | `$.ready` `$.on` `$.off` | DOM ready, global event delegation & direct listeners |
 | `$.fn` | Collection prototype (extend it) |
 | `$.component` `$.mount` `$.mountAll` `$.getInstance` `$.destroy` `$.components` | Component system |
+| `$.morph` | DOM morphing engine — patch existing DOM to match new HTML without destroying unchanged nodes |
+| `$.safeEval` | CSP-safe expression evaluator (replaces `eval` / `new Function`) |
 | `$.style` | Dynamically load global stylesheet file(s) at runtime |
 | `$.router` `$.getRouter` | SPA router |
 | `$.store` `$.getStore` | State management |
@@ -276,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

@@ -16,8 +16,10 @@ function buildLibrary() {
   const VERSION = pkg.version;
 
   const modules = [
-    'src/reactive.js', 'src/core.js', 'src/component.js',
-    'src/router.js',   'src/store.js', 'src/http.js', 'src/utils.js',
+    'src/errors.js',
+    'src/reactive.js', 'src/core.js', 'src/expression.js', 'src/diff.js',
+    'src/component.js', 'src/router.js', 'src/store.js', 'src/http.js',
+    'src/utils.js',
   ];
 
   const DIST     = path.join(process.cwd(), 'dist');
@@ -32,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');
@@ -40,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

@@ -0,0 +1,82 @@
+/**
+ * cli/commands/dev/index.js — Dev server orchestrator
+ *
+ * Ties together the HTTP server, file watcher, logger, and overlay
+ * to provide a complete development environment with live-reload,
+ * syntax validation, and a full-screen error overlay that surfaces
+ * both build-time and runtime ZQueryErrors.
+ */
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+const { args, flag, option } = require('../../args');
+const { createServer }       = require('./server');
+const { startWatcher }       = require('./watcher');
+const { printBanner }        = require('./logger');
+
+// ---------------------------------------------------------------------------
+// Resolve project root
+// ---------------------------------------------------------------------------
+
+function resolveRoot(htmlEntry) {
+  // Explicit positional argument  →  zquery dev <dir>
+  for (let i = 1; i < args.length; i++) {
+    const prev = args[i - 1];
+    if (!args[i].startsWith('-') && prev !== '-p' && prev !== '--port' && prev !== '--index' && prev !== '-i') {
+      return path.resolve(process.cwd(), args[i]);
+    }
+  }
+
+  // Auto-detect: first candidate that contains the HTML entry file
+  const candidates = [
+    process.cwd(),
+    path.join(process.cwd(), 'public'),
+    path.join(process.cwd(), 'src'),
+  ];
+  for (const c of candidates) {
+    if (fs.existsSync(path.join(c, htmlEntry))) return c;
+  }
+  return process.cwd();
+}
+
+// ---------------------------------------------------------------------------
+// devServer — main entry point (called from cli/index.js)
+// ---------------------------------------------------------------------------
+
+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 } = await createServer({ root, htmlEntry, port, noIntercept });
+
+  // Start file watcher
+  const watcher = startWatcher({ root, pool });
+
+  // Boot
+  listen(() => {
+    printBanner({
+      port,
+      root:          path.relative(process.cwd(), root) || '.',
+      htmlEntry,
+      noIntercept,
+      watchDirCount: watcher.dirs.length,
+    });
+  });
+
+  // Graceful shutdown
+  process.on('SIGINT', () => {
+    console.log('\n  Shutting down...');
+    watcher.destroy();
+    pool.closeAll();
+    app.close(() => process.exit(0));
+    setTimeout(() => process.exit(0), 1000);
+  });
+}
+
+module.exports = devServer;

package/cli/commands/dev/logger.js

@@ -0,0 +1,70 @@
+/**
+ * cli/commands/dev/logger.js — Terminal output helpers
+ *
+ * Provides styled console output for the dev server: startup banner,
+ * timestamped file-change messages, and error formatting.
+ */
+
+'use strict';
+
+// ANSI colour helpers (works on all modern terminals)
+const c = {
+  reset:   '\x1b[0m',
+  bold:    '\x1b[1m',
+  dim:     '\x1b[2m',
+  red:     '\x1b[31m',
+  green:   '\x1b[32m',
+  yellow:  '\x1b[33m',
+  cyan:    '\x1b[36m',
+  magenta: '\x1b[35m',
+};
+
+function timestamp() {
+  return new Date().toLocaleTimeString();
+}
+
+// ---------------------------------------------------------------------------
+// Event-level log helpers
+// ---------------------------------------------------------------------------
+
+function logCSS(relPath) {
+  console.log(`  ${timestamp()}  ${c.magenta} css ${c.reset} ${relPath}`);
+}
+
+function logReload(relPath) {
+  console.log(`  ${timestamp()}  ${c.cyan} reload ${c.reset} ${relPath}`);
+}
+
+function logError(descriptor) {
+  const t = timestamp();
+  console.log(`  ${t}  ${c.red} error ${c.reset} ${descriptor.file}`);
+  console.log(`         ${c.red}${descriptor.type}: ${descriptor.message}${c.reset}`);
+  if (descriptor.line) {
+    console.log(`         ${c.dim}at line ${descriptor.line}${descriptor.column ? ':' + descriptor.column : ''}${c.reset}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Startup banner
+// ---------------------------------------------------------------------------
+
+function printBanner({ port, root, htmlEntry, noIntercept, watchDirCount }) {
+  const rule = c.dim + '-'.repeat(40) + c.reset;
+  console.log(`\n  ${c.bold}zQuery Dev Server${c.reset}`);
+  console.log(`  ${rule}`);
+  console.log(`  Local:       ${c.cyan}http://localhost:${port}/${c.reset}`);
+  console.log(`  Root:        ${root}`);
+  if (htmlEntry !== 'index.html') {
+    console.log(`  HTML:        ${c.cyan}${htmlEntry}${c.reset}`);
+  }
+  console.log(`  Live Reload: ${c.green}enabled${c.reset} (SSE)`);
+  console.log(`  Overlay:     ${c.green}enabled${c.reset} (syntax + runtime + ZQueryError)`);
+  if (noIntercept) {
+    console.log(`  Intercept:   ${c.yellow}disabled${c.reset} (--no-intercept)`);
+  }
+  console.log(`  Watching:    all files in ${watchDirCount} director${watchDirCount === 1 ? 'y' : 'ies'}`);
+  console.log(`  ${rule}`);
+  console.log(`  Press Ctrl+C to stop\n`);
+}
+
+module.exports = { logCSS, logReload, logError, printBanner };