zero-query 0.5.2 → 0.6.3

package/README.md

@@ -15,14 +15,14 @@
 
 </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 ~84 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) |
+| **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 |
@@ -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  (~84 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 |

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');

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)
+// ---------------------------------------------------------------------------
+
+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 });
+
+  // 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 };

package/cli/commands/dev/overlay.js

@@ -0,0 +1,317 @@
+/**
+ * cli/commands/dev/overlay.js — Client-side error overlay + SSE live-reload
+ *
+ * Returns an HTML <script> snippet that is injected before </body> in
+ * every HTML response served by the dev server.  Responsibilities:
+ *
+ *   1. Error Overlay — full-screen dark overlay with code frames, stack
+ *      traces, and ZQueryError metadata.  Dismissable via Esc or ×.
+ *   2. Runtime error hooks — window.onerror, unhandledrejection, AND
+ *      the zQuery $.onError() hook so framework-level errors are
+ *      surfaced in the overlay automatically.
+ *   3. SSE connection — listens for reload / css / error:syntax /
+ *      error:clear events from the dev server watcher.
+ */
+
+'use strict';
+
+// The snippet is a self-contained IIFE — no external dependencies.
+// It must work in all browsers that support EventSource (IE11 excluded).
+
+const OVERLAY_SCRIPT = `<script>
+(function(){
+  // =====================================================================
+  // Error overlay
+  // =====================================================================
+  var overlayEl = null;
+
+  var OVERLAY_CSS =
+    'position:fixed;top:0;left:0;width:100%;height:100%;' +
+    'background:rgba(0,0,0,0.92);color:#fff;z-index:2147483647;' +
+    'font-family:ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,monospace;' +
+    'font-size:13px;overflow-y:auto;padding:0;margin:0;box-sizing:border-box;';
+
+  var HEADER_CSS =
+    'padding:20px 24px 12px;border-bottom:1px solid rgba(255,255,255,0.1);' +
+    'display:flex;align-items:flex-start;justify-content:space-between;';
+
+  var BADGE_CSS =
+    'display:inline-block;padding:3px 8px;border-radius:4px;font-size:11px;' +
+    'font-weight:700;text-transform:uppercase;letter-spacing:0.5px;margin-bottom:8px;';
+
+  // Map ZQueryError code prefixes to colours so devs can see at a glance
+  // which subsystem produced the error.
+  var CODE_COLORS = {
+    'ZQ_REACTIVE':  '#9b59b6',
+    'ZQ_SIGNAL':    '#9b59b6',
+    'ZQ_EFFECT':    '#9b59b6',
+    'ZQ_EXPR':      '#2980b9',
+    'ZQ_COMP':      '#16a085',
+    'ZQ_ROUTER':    '#d35400',
+    'ZQ_STORE':     '#8e44ad',
+    'ZQ_HTTP':      '#2c3e50',
+    'ZQ_DEV':       '#e74c3c',
+    'ZQ_INVALID':   '#7f8c8d',
+  };
+
+  function badgeColor(data) {
+    if (data.code) {
+      var keys = Object.keys(CODE_COLORS);
+      for (var i = 0; i < keys.length; i++) {
+        if (data.code.indexOf(keys[i]) === 0) return CODE_COLORS[keys[i]];
+      }
+    }
+    if (data.type && /syntax|parse/i.test(data.type)) return '#e74c3c';
+    return '#e67e22';
+  }
+
+  function esc(s) {
+    var d = document.createElement('div');
+    d.appendChild(document.createTextNode(s));
+    return d.innerHTML;
+  }
+
+  function createOverlay(data) {
+    removeOverlay();
+    var wrap = document.createElement('div');
+    wrap.id = '__zq_error_overlay';
+    wrap.setAttribute('style', OVERLAY_CSS);
+    wrap.setAttribute('tabindex', '-1');
+
+    var color = badgeColor(data);
+    var html = '';
+
+    // ----- header row -----
+    html += '<div style="' + HEADER_CSS + '">';
+    html += '<div>';
+
+    // Error code badge (if present)
+    if (data.code) {
+      html += '<span style="' + BADGE_CSS + 'background:' + color + ';margin-right:6px;">' + esc(data.code) + '</span>';
+    }
+    // Type badge
+    html += '<span style="' + BADGE_CSS + 'background:' + (data.code ? 'rgba(255,255,255,0.1)' : color) + ';">' + esc(data.type || 'Error') + '</span>';
+
+    // Message
+    html += '<div style="font-size:18px;font-weight:600;line-height:1.4;color:#ff6b6b;margin-top:4px;">';
+    html += esc(data.message || 'Unknown error');
+    html += '</div></div>';
+
+    // Close button
+    html += '<button id="__zq_close" style="' +
+      'background:none;border:1px solid rgba(255,255,255,0.2);color:#999;' +
+      'font-size:20px;cursor:pointer;border-radius:6px;width:32px;height:32px;' +
+      'display:flex;align-items:center;justify-content:center;flex-shrink:0;' +
+      'margin-left:16px;transition:all 0.15s;"' +
+      ' onmouseover="this.style.color=\\'#fff\\';this.style.borderColor=\\'rgba(255,255,255,0.5)\\'"' +
+      ' onmouseout="this.style.color=\\'#999\\';this.style.borderColor=\\'rgba(255,255,255,0.2)\\'"' +
+      '>&times;</button>';
+    html += '</div>';
+
+    // ----- file location -----
+    if (data.file) {
+      html += '<div style="padding:10px 24px;color:#8be9fd;font-size:13px;">';
+      html += '<span style="color:#888;">File: </span>' + esc(data.file);
+      if (data.line) html += '<span style="color:#888;">:</span>' + data.line;
+      if (data.column) html += '<span style="color:#888;">:</span>' + data.column;
+      html += '</div>';
+    }
+
+    // ----- ZQueryError context (key/value pairs) -----
+    if (data.context && typeof data.context === 'object' && Object.keys(data.context).length) {
+      html += '<div style="padding:8px 24px;display:flex;flex-wrap:wrap;gap:8px;">';
+      var ctxKeys = Object.keys(data.context);
+      for (var ci = 0; ci < ctxKeys.length; ci++) {
+        var k = ctxKeys[ci], v = data.context[k];
+        html += '<span style="background:rgba(255,255,255,0.06);border:1px solid rgba(255,255,255,0.08);' +
+          'padding:3px 10px;border-radius:4px;font-size:12px;">' +
+          '<span style="color:#888;">' + esc(k) + ': </span>' +
+          '<span style="color:#f1fa8c;">' + esc(typeof v === 'object' ? JSON.stringify(v) : String(v)) + '</span>' +
+          '</span>';
+      }
+      html += '</div>';
+    }
+
+    // ----- code frame -----
+    if (data.frame) {
+      html += '<pre style="' +
+        'margin:0;padding:16px 24px;background:rgba(255,255,255,0.04);' +
+        'border-top:1px solid rgba(255,255,255,0.06);' +
+        'border-bottom:1px solid rgba(255,255,255,0.06);' +
+        'overflow-x:auto;line-height:1.6;font-size:13px;">';
+      var lines = data.frame.split('\\n');
+      for (var fi = 0; fi < lines.length; fi++) {
+        var fl = lines[fi];
+        if (fl.charAt(0) === '>') {
+          html += '<span style="color:#ff6b6b;font-weight:600;">' + esc(fl) + '</span>\\n';
+        } else if (fl.indexOf('^') !== -1 && fl.trim().replace(/[\\s|^]/g, '') === '') {
+          html += '<span style="color:#e74c3c;font-weight:700;">' + esc(fl) + '</span>\\n';
+        } else {
+          html += '<span style="color:#999;">' + esc(fl) + '</span>\\n';
+        }
+      }
+      html += '</pre>';
+    }
+
+    // ----- stack trace -----
+    if (data.stack) {
+      html += '<div style="padding:16px 24px;">';
+      html += '<div style="color:#888;font-size:11px;text-transform:uppercase;letter-spacing:0.5px;margin-bottom:8px;">Stack Trace</div>';
+      html += '<pre style="margin:0;color:#bbb;font-size:12px;line-height:1.7;white-space:pre-wrap;word-break:break-word;">';
+      html += esc(data.stack);
+      html += '</pre></div>';
+    }
+
+    // ----- tip -----
+    html += '<div style="padding:16px 24px;color:#555;font-size:11px;border-top:1px solid rgba(255,255,255,0.06);">';
+    html += 'Fix the error and save \\u2014 the overlay will clear automatically. Press <kbd style="' +
+      'background:rgba(255,255,255,0.1);padding:1px 6px;border-radius:3px;font-size:11px;' +
+      '">Esc</kbd> to dismiss.';
+    html += '</div>';
+
+    wrap.innerHTML = html;
+    document.body.appendChild(wrap);
+    overlayEl = wrap;
+
+    var closeBtn = document.getElementById('__zq_close');
+    if (closeBtn) closeBtn.addEventListener('click', removeOverlay);
+    wrap.addEventListener('keydown', function(e) { if (e.key === 'Escape') removeOverlay(); });
+    wrap.focus();
+  }
+
+  function removeOverlay() {
+    if (overlayEl && overlayEl.parentNode) overlayEl.parentNode.removeChild(overlayEl);
+    overlayEl = null;
+  }
+
+  // =====================================================================
+  // Console helper
+  // =====================================================================
+  function logToConsole(data) {
+    var label = data.code ? data.code + ' ' : '';
+    var msg = '\\n%c zQuery DevError %c ' + label + data.type + ': ' + data.message;
+    if (data.file) msg += '\\n  at ' + data.file + (data.line ? ':' + data.line : '') + (data.column ? ':' + data.column : '');
+    console.error(msg, 'background:#e74c3c;color:#fff;padding:2px 6px;border-radius:3px;font-weight:700;', 'color:inherit;');
+    if (data.frame) console.error(data.frame);
+  }
+
+  function cleanStack(stack) {
+    return stack.split('\\n')
+      .filter(function(l) { return l.indexOf('__zq_') === -1 && l.indexOf('EventSource') === -1; })
+      .map(function(l) { return l.replace(location.origin, ''); })
+      .join('\\n');
+  }
+
+  // =====================================================================
+  // Runtime error hooks
+  // =====================================================================
+  window.addEventListener('error', function(e) {
+    if (!e.filename) return;
+    var err = e.error || {};
+    var data = {
+      code:    err.code || '',
+      type:    (err.constructor && err.constructor.name) || 'Error',
+      message: e.message || String(err),
+      file:    e.filename.replace(location.origin, ''),
+      line:    e.lineno || 0,
+      column:  e.colno || 0,
+      context: err.context || null,
+      stack:   err.stack ? cleanStack(err.stack) : ''
+    };
+    createOverlay(data);
+    logToConsole(data);
+  });
+
+  window.addEventListener('unhandledrejection', function(e) {
+    var err = e.reason || {};
+    var data = {
+      code:    err.code || '',
+      type:    err.name === 'ZQueryError' ? 'ZQueryError' : 'Unhandled Promise Rejection',
+      message: err.message || String(err),
+      context: err.context || null,
+      stack:   err.stack ? cleanStack(err.stack) : ''
+    };
+    createOverlay(data);
+    logToConsole(data);
+  });
+
+  // =====================================================================
+  // Hook into zQuery's $.onError() when the library is loaded
+  // =====================================================================
+  function hookZQueryErrors() {
+    // $.onError is set by the framework — wait for it
+    if (typeof $ !== 'undefined' && typeof $.onError === 'function') {
+      $.onError(function(zqErr) {
+        var data = {
+          code:    zqErr.code || '',
+          type:    'ZQueryError',
+          message: zqErr.message,
+          context: zqErr.context || null,
+          stack:   zqErr.stack ? cleanStack(zqErr.stack) : ''
+        };
+        createOverlay(data);
+        logToConsole(data);
+      });
+      return;
+    }
+    // Retry until the library has loaded (max ~5s)
+    if (hookZQueryErrors._tries < 50) {
+      hookZQueryErrors._tries++;
+      setTimeout(hookZQueryErrors, 100);
+    }
+  }
+  hookZQueryErrors._tries = 0;
+  // Defer so the page's own scripts load first
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', hookZQueryErrors);
+  } else {
+    setTimeout(hookZQueryErrors, 0);
+  }
+
+  // =====================================================================
+  // SSE connection (live-reload + server-pushed errors)
+  // =====================================================================
+  var es, reconnectTimer;
+
+  function connect() {
+    es = new EventSource('/__zq_reload');
+
+    es.addEventListener('reload', function() {
+      removeOverlay();
+      location.reload();
+    });
+
+    es.addEventListener('css', function() {
+      var sheets = document.querySelectorAll('link[rel="stylesheet"]');
+      sheets.forEach(function(l) {
+        var href = l.getAttribute('href');
+        if (!href) return;
+        var sep = href.indexOf('?') >= 0 ? '&' : '?';
+        l.setAttribute('href', href.replace(/[?&]_zqr=\\\\d+/, '') + sep + '_zqr=' + Date.now());
+      });
+    });
+
+    es.addEventListener('error:syntax', function(e) {
+      try { var data = JSON.parse(e.data); createOverlay(data); logToConsole(data); } catch(_){}
+    });
+
+    es.addEventListener('error:runtime', function(e) {
+      try { var data = JSON.parse(e.data); createOverlay(data); logToConsole(data); } catch(_){}
+    });
+
+    es.addEventListener('error:clear', function() {
+      removeOverlay();
+    });
+
+    es.onerror = function() {
+      es.close();
+      clearTimeout(reconnectTimer);
+      reconnectTimer = setTimeout(connect, 2000);
+    };
+  }
+
+  connect();
+})();
+</script>`;
+
+module.exports = OVERLAY_SCRIPT;

package/cli/commands/dev/server.js

@@ -0,0 +1,129 @@
+/**
+ * cli/commands/dev/server.js — HTTP server & SSE broadcasting
+ *
+ * Creates the zero-http app, serves static files, injects the
+ * error-overlay snippet into HTML responses, and manages the
+ * SSE connection pool for live-reload events.
+ */
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const OVERLAY_SCRIPT = require('./overlay');
+
+// ---------------------------------------------------------------------------
+// SSE client pool
+// ---------------------------------------------------------------------------
+
+class SSEPool {
+  constructor() {
+    this._clients = new Set();
+  }
+
+  add(sse) {
+    this._clients.add(sse);
+    sse.on('close', () => this._clients.delete(sse));
+  }
+
+  broadcast(eventType, data) {
+    for (const sse of this._clients) {
+      try { sse.event(eventType, data || ''); } catch { this._clients.delete(sse); }
+    }
+  }
+
+  closeAll() {
+    for (const sse of this._clients) {
+      try { sse.close(); } catch { /* ignore */ }
+    }
+    this._clients.clear();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Server factory
+// ---------------------------------------------------------------------------
+
+/**
+ * @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 }}
+ */
+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 { createApp, static: serveStatic } = zeroHttp;
+
+  const app  = createApp();
+  const pool = new SSEPool();
+
+  // ---- SSE endpoint ----
+  app.get('/__zq_reload', (req, res) => {
+    const sse = res.sse({ keepAlive: 30000, keepAliveComment: 'ping' });
+    pool.add(sse);
+  });
+
+  // ---- Auto-resolve zquery.min.js ----
+  const pkgRoot = path.resolve(__dirname, '..', '..', '..');
+
+  app.use((req, res, next) => {
+    if (noIntercept) return next();
+    const basename = path.basename(req.url.split('?')[0]).toLowerCase();
+    if (basename !== 'zquery.min.js') return next();
+
+    const candidates = [
+      path.join(pkgRoot, 'dist', 'zquery.min.js'),
+      path.join(root, 'node_modules', 'zero-query', 'dist', 'zquery.min.js'),
+    ];
+    for (const p of candidates) {
+      if (fs.existsSync(p)) {
+        res.set('Content-Type', 'application/javascript; charset=utf-8');
+        res.set('Cache-Control', 'no-cache');
+        res.send(fs.readFileSync(p, 'utf-8'));
+        return;
+      }
+    }
+    next();
+  });
+
+  // ---- Static files ----
+  app.use(serveStatic(root, { index: false, dotfiles: 'ignore' }));
+
+  // ---- SPA fallback — inject overlay/SSE snippet ----
+  app.get('*', (req, res) => {
+    if (path.extname(req.url) && path.extname(req.url) !== '.html') {
+      res.status(404).send('Not Found');
+      return;
+    }
+    const indexPath = path.join(root, htmlEntry);
+    if (!fs.existsSync(indexPath)) {
+      res.status(404).send(`${htmlEntry} not found`);
+      return;
+    }
+    let html = fs.readFileSync(indexPath, 'utf-8');
+    if (html.includes('</body>')) {
+      html = html.replace('</body>', OVERLAY_SCRIPT + '\n</body>');
+    } else {
+      html += OVERLAY_SCRIPT;
+    }
+    res.html(html);
+  });
+
+  function listen(cb) {
+    app.listen(port, cb);
+  }
+
+  return { app, pool, listen };
+}
+
+module.exports = { createServer, SSEPool };