zero-query 0.6.3 → 0.8.6

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) {
@@ -311,6 +360,383 @@ const OVERLAY_SCRIPT = `<script>
   }
 
   connect();
+
+  // =====================================================================
+  // Fetch / $.http Interceptor — pretty console logging
+  // =====================================================================
+  var __zqChannel;
+  try { __zqChannel = new BroadcastChannel('__zq_devtools'); } catch(e) {}
+
+  var __zqRequests = [];
+  var __zqMorphEvents = [];
+  var __zqMorphCount = 0;
+  var __zqRenderCount = 0;
+  var __zqReqId = 0;
+  var _origFetch = window.fetch;
+
+  window.fetch = function(input, init) {
+    var url = typeof input === 'string' ? input : (input && input.url ? input.url : String(input));
+    var method = ((init && init.method) || (input && input.method) || 'GET').toUpperCase();
+    var id = ++__zqReqId;
+    var start = performance.now();
+
+    // Skip internal dev-server requests
+    if (url.indexOf('__zq_') !== -1 || url.indexOf('/_devtools') !== -1) {
+      return _origFetch.apply(this, arguments);
+    }
+
+    return _origFetch.apply(this, arguments).then(function(response) {
+      var elapsed = Math.round(performance.now() - start);
+      var status = response.status;
+      var cloned = response.clone();
+
+      cloned.text().then(function(bodyText) {
+        var entry = {
+          id: id, method: method, url: url, status: status,
+          elapsed: elapsed, bodyPreview: bodyText.slice(0, 5000),
+          timestamp: Date.now()
+        };
+        __zqRequests.push(entry);
+        if (__zqRequests.length > 500) __zqRequests.shift();
+        updateDevBar();
+
+        // Pretty console log
+        var isOk = status >= 200 && status < 300;
+        var color = isOk ? '#2ecc71' : status < 400 ? '#f39c12' : '#e74c3c';
+
+        console.groupCollapsed(
+          '%c ' + method + ' %c' + status + '%c ' + url + '  %c' + elapsed + 'ms',
+          'background:' + color + ';color:#fff;padding:2px 6px;border-radius:3px;font-weight:700;font-size:11px',
+          'color:' + color + ';font-weight:700;margin-left:8px',
+          'color:inherit;margin-left:4px',
+          'color:#888;margin-left:8px;font-size:11px'
+        );
+
+        // Response body
+        try {
+          var parsed = JSON.parse(bodyText);
+          console.log('%c Response  ', 'background:#1e1e2e;color:#8be9fd;padding:2px 6px;border-radius:2px;font-weight:600', parsed);
+        } catch(pe) {
+          if (bodyText.length > 0) {
+            console.log('%c Response  ', 'background:#1e1e2e;color:#8be9fd;padding:2px 6px;border-radius:2px;font-weight:600',
+              bodyText.length > 500 ? bodyText.slice(0, 500) + '... (' + bodyText.length + ' chars)' : bodyText);
+          }
+        }
+
+        // Headers
+        try {
+          console.log('%c Headers   ', 'background:#1e1e2e;color:#bd93f9;padding:2px 6px;border-radius:2px;font-weight:600',
+            Object.fromEntries(response.headers.entries()));
+        } catch(he) {}
+
+        // Request body (if sent)
+        if (init && init.body) {
+          try {
+            console.log('%c Request   ', 'background:#1e1e2e;color:#f1fa8c;padding:2px 6px;border-radius:2px;font-weight:600',
+              JSON.parse(init.body));
+          } catch(re) {
+            console.log('%c Request   ', 'background:#1e1e2e;color:#f1fa8c;padding:2px 6px;border-radius:2px;font-weight:600',
+              String(init.body).slice(0, 500));
+          }
+        }
+
+        console.groupEnd();
+
+        // Broadcast to devtools
+        if (__zqChannel) {
+          try { __zqChannel.postMessage({ type: 'http', data: entry }); } catch(ce) {}
+        }
+      }).catch(function() {});
+
+      return response;
+    }, function(err) {
+      var elapsed = Math.round(performance.now() - start);
+      console.groupCollapsed(
+        '%c ' + method + ' %cERR%c ' + url + '  %c' + elapsed + 'ms',
+        'background:#e74c3c;color:#fff;padding:2px 6px;border-radius:3px;font-weight:700;font-size:11px',
+        'color:#e74c3c;font-weight:700;margin-left:8px',
+        'color:inherit;margin-left:4px',
+        'color:#888;margin-left:8px;font-size:11px'
+      );
+      console.error(err);
+      console.groupEnd();
+
+      var entry = { id: id, method: method, url: url, status: 0, elapsed: elapsed, bodyPreview: err.message, timestamp: Date.now() };
+      __zqRequests.push(entry);
+      updateDevBar();
+      if (__zqChannel) {
+        try { __zqChannel.postMessage({ type: 'http', data: entry }); } catch(ce) {}
+      }
+
+      throw err;
+    });
+  };
+
+  // =====================================================================
+  // Morph instrumentation — hook via window.__zqMorphHook (set by diff.js)
+  // =====================================================================
+  window.__zqMorphHook = function(el, elapsed) {
+    __zqMorphCount++;
+    updateDevBar();
+
+    var evt = { target: el.id || el.tagName.toLowerCase(), elapsed: elapsed, kind: 'morph', timestamp: Date.now() };
+    __zqMorphEvents.push(evt);
+    if (__zqMorphEvents.length > 200) __zqMorphEvents.shift();
+
+    // Console timing for slow morphs (> 4ms)
+    if (elapsed > 4) {
+      console.log(
+        '%c morph %c' + elapsed.toFixed(2) + 'ms%c ' + (el.id || el.tagName.toLowerCase()),
+        'background:#9b59b6;color:#fff;padding:2px 6px;border-radius:3px;font-weight:700;font-size:11px',
+        'color:' + (elapsed > 16 ? '#e74c3c' : '#f39c12') + ';font-weight:700;margin-left:8px',
+        'color:#888;margin-left:4px'
+      );
+    }
+
+    // Broadcast to devtools
+    if (__zqChannel) {
+      try {
+        __zqChannel.postMessage({
+          type: 'morph-detail',
+          data: evt
+        });
+      } catch(ce) {}
+    }
+  };
+
+  // =====================================================================
+  // Render instrumentation — hook for first-renders & route swaps
+  // =====================================================================
+  window.__zqRenderHook = function(el, elapsed, kind, name) {
+    __zqRenderCount++;
+    __zqMorphCount++; // count renders in the morph total for the toolbar
+    updateDevBar();
+
+    var evt = { target: name || el.id || el.tagName.toLowerCase(), elapsed: elapsed, kind: kind, timestamp: Date.now() };
+    __zqMorphEvents.push(evt);
+    if (__zqMorphEvents.length > 200) __zqMorphEvents.shift();
+
+    // Console log for route/mount renders
+    var label = kind === 'route' ? ' route ' : ' mount ';
+    var bg = kind === 'route' ? '#d29922' : '#3fb950';
+    console.log(
+      '%c' + label + '%c' + elapsed.toFixed(2) + 'ms%c ' + (name || el.id || el.tagName.toLowerCase()),
+      'background:' + bg + ';color:#fff;padding:2px 6px;border-radius:3px;font-weight:700;font-size:11px',
+      'color:' + (elapsed > 16 ? '#e74c3c' : '#888') + ';font-weight:700;margin-left:8px',
+      'color:#888;margin-left:4px'
+    );
+
+    // Broadcast to devtools
+    if (__zqChannel) {
+      try {
+        __zqChannel.postMessage({
+          type: 'render-detail',
+          data: evt
+        });
+      } catch(ce) {}
+    }
+  };
+
+  // =====================================================================
+  // Router instrumentation — history state tracking for devtools
+  // =====================================================================
+  var __zqRouterEvents = [];
+
+  var _origPushState = history.pushState;
+  history.pushState = function(state, title, url) {
+    _origPushState.apply(this, arguments);
+    var isSubstate = state && state.__zq === 'substate';
+    var evt = {
+      action: isSubstate ? 'substate' : 'navigate',
+      url: String(url || location.href).replace(location.origin, ''),
+      key: isSubstate ? state.key : null,
+      data: isSubstate ? state.data : null,
+      timestamp: Date.now()
+    };
+    __zqRouterEvents.push(evt);
+    if (__zqRouterEvents.length > 200) __zqRouterEvents.shift();
+    if (__zqChannel) {
+      try { __zqChannel.postMessage({ type: 'router', data: evt }); } catch(e) {}
+    }
+  };
+
+  var _origReplaceState = history.replaceState;
+  history.replaceState = function(state, title, url) {
+    _origReplaceState.apply(this, arguments);
+    var isSubstate = state && state.__zq === 'substate';
+    var evt = {
+      action: 'replace',
+      url: String(url || location.href).replace(location.origin, ''),
+      key: isSubstate ? state.key : null,
+      data: isSubstate ? state.data : null,
+      timestamp: Date.now()
+    };
+    __zqRouterEvents.push(evt);
+    if (__zqRouterEvents.length > 200) __zqRouterEvents.shift();
+    if (__zqChannel) {
+      try { __zqChannel.postMessage({ type: 'router', data: evt }); } catch(e) {}
+    }
+  };
+
+  window.addEventListener('popstate', function(e) {
+    var state = e.state;
+    var isSubstate = state && state.__zq === 'substate';
+    var evt = {
+      action: isSubstate ? 'pop-substate' : 'pop',
+      url: location.pathname + location.hash,
+      key: isSubstate ? state.key : null,
+      data: isSubstate ? state.data : null,
+      timestamp: Date.now()
+    };
+    __zqRouterEvents.push(evt);
+    if (__zqRouterEvents.length > 200) __zqRouterEvents.shift();
+    if (__zqChannel) {
+      try { __zqChannel.postMessage({ type: 'router', data: evt }); } catch(e) {}
+    }
+  });
+
+  window.addEventListener('hashchange', function() {
+    var evt = {
+      action: 'hashchange',
+      url: location.hash,
+      timestamp: Date.now()
+    };
+    __zqRouterEvents.push(evt);
+    if (__zqRouterEvents.length > 200) __zqRouterEvents.shift();
+    if (__zqChannel) {
+      try { __zqChannel.postMessage({ type: 'router', data: evt }); } catch(e) {}
+    }
+  });
+
+  // =====================================================================
+  // Dev Toolbar — floating bar with DOM viewer button & request counter
+  // =====================================================================
+  var devBar;
+
+  function createDevBar() {
+    devBar = document.createElement('div');
+    devBar.id = '__zq_devbar';
+    devBar.setAttribute('style',
+      'position:fixed;bottom:12px;right:12px;z-index:2147483646;' +
+      'display:flex;align-items:center;gap:6px;' +
+      'background:rgba(22,27,34,0.92);border:1px solid rgba(48,54,61,0.8);' +
+      'border-radius:8px;padding:4px 6px;backdrop-filter:blur(8px);' +
+      'font-family:ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,monospace;' +
+      'font-size:11px;color:#8b949e;user-select:none;cursor:default;' +
+      'box-shadow:0 4px 12px rgba(0,0,0,0.4);'
+    );
+    devBar.innerHTML =
+      '<span style="color:#58a6ff;font-weight:700;padding:0 4px;font-size:10px;letter-spacing:.5px">zQ</span>' +
+      '<span id="__zq_bar_reqs" title="Network requests" style="padding:2px 6px;border-radius:4px;' +
+        'background:rgba(88,166,255,0.1);color:#58a6ff;cursor:pointer;font-size:10px;font-weight:600;">0 req</span>' +
+      '<span id="__zq_bar_morphs" title="Render operations" style="padding:2px 6px;border-radius:4px;' +
+        'background:rgba(188,140,255,0.1);color:#bc8cff;cursor:pointer;font-size:10px;font-weight:600;">0 render</span>' +
+      '<button id="__zq_bar_dom" title="Open DevTools (/_devtools)" style="' +
+        'padding:3px 8px;border-radius:4px;font-size:10px;font-weight:700;' +
+        'background:rgba(63,185,80,0.15);color:#3fb950;border:1px solid rgba(63,185,80,0.3);' +
+        'cursor:pointer;font-family:inherit;transition:all .15s;' +
+      '">DOM</button>' +
+      '<button id="__zq_bar_close" title="Close toolbar" style="' +
+        'padding:0 4px;color:#484f58;cursor:pointer;font-size:14px;border:none;' +
+        'background:none;font-family:inherit;line-height:1;' +
+      '">&times;</button>';
+
+    document.body.appendChild(devBar);
+    updateDevBar();
+
+    // Check if we're inside a devtools split-view iframe
+    function isInSplitFrame() {
+      try { return window.parent !== window && window.parent.document.getElementById('app-frame'); }
+      catch(e) { return false; }
+    }
+
+    // Switch tab in devtools (works for both split iframe and popup)
+    function switchDevTab(tab) {
+      if (__zqChannel) {
+        __zqChannel.postMessage({ type: 'switch-tab', tab: tab });
+      }
+    }
+
+    // Req counter → Network tab
+    document.getElementById('__zq_bar_reqs').addEventListener('click', function() {
+      if (isInSplitFrame()) {
+        switchDevTab('network');
+      } else {
+        openDevToolsPopup('network');
+      }
+    });
+
+    // Render counter → Performance tab
+    document.getElementById('__zq_bar_morphs').addEventListener('click', function() {
+      if (isInSplitFrame()) {
+        switchDevTab('perf');
+      } else {
+        openDevToolsPopup('perf');
+      }
+    });
+
+    // DOM button → Elements tab (in split) or open popup
+    var __zqPopup = null;
+    function openDevToolsPopup(tab) {
+      // If popup is already open, just switch the tab via BroadcastChannel
+      if (__zqPopup && !__zqPopup.closed) {
+        switchDevTab(tab);
+        __zqPopup.focus();
+        return;
+      }
+      var w = 1080, h = 800;
+      var left = window.screenX + window.outerWidth - w - 20;
+      var top = window.screenY + 60;
+      var url = '/_devtools' + (tab ? '#' + tab : '');
+      __zqPopup = window.open(url, '__zq_devtools',
+        'width=' + w + ',height=' + h + ',left=' + left + ',top=' + top +
+        ',resizable=yes,scrollbars=yes');
+    }
+
+    document.getElementById('__zq_bar_dom').addEventListener('click', function() {
+      if (isInSplitFrame()) {
+        switchDevTab('dom');
+      } else {
+        openDevToolsPopup('dom');
+      }
+    });
+
+    // Close button
+    document.getElementById('__zq_bar_close').addEventListener('click', function() {
+      devBar.style.display = 'none';
+    });
+
+    // Hover effects
+    document.getElementById('__zq_bar_dom').addEventListener('mouseover', function() {
+      this.style.background = 'rgba(63,185,80,0.3)';
+    });
+    document.getElementById('__zq_bar_dom').addEventListener('mouseout', function() {
+      this.style.background = 'rgba(63,185,80,0.15)';
+    });
+  }
+
+  function updateDevBar() {
+    if (!devBar) return;
+    var reqEl = document.getElementById('__zq_bar_reqs');
+    var morphEl = document.getElementById('__zq_bar_morphs');
+    if (reqEl) reqEl.textContent = __zqRequests.length + ' req';
+    if (morphEl) morphEl.textContent = __zqMorphCount + ' render';
+  }
+
+  // Expose for devtools popup
+  window.__zqDevTools = {
+    get requests() { return __zqRequests; },
+    get morphEvents() { return __zqMorphEvents; },
+    get morphCount() { return __zqMorphCount; },
+    get renderCount() { return __zqRenderCount; },
+    get routerEvents() { return __zqRouterEvents; }
+  };
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', createDevBar);
+  } else {
+    createDevBar();
+  }
 })();
 </script>`;
 

package/cli/commands/dev/server.js

@@ -11,6 +11,7 @@
 const fs   = require('fs');
 const path = require('path');
 const OVERLAY_SCRIPT = require('./overlay');
+const DEVTOOLS_HTML  = require('./devtools');
 
 // ---------------------------------------------------------------------------
 // SSE client pool
@@ -44,22 +45,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;
@@ -73,6 +103,13 @@ function createServer({ root, htmlEntry, port, noIntercept }) {
     pool.add(sse);
   });
 
+  // ---- DevTools panel ----
+  app.get('/_devtools', (req, res) => {
+    res.set('Content-Type', 'text/html; charset=utf-8');
+    res.set('Cache-Control', 'no-cache');
+    res.send(DEVTOOLS_HTML);
+  });
+
   // ---- Auto-resolve zquery.min.js ----
   const pkgRoot = path.resolve(__dirname, '..', '..', '..');
 

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];
@@ -52,12 +60,31 @@ function collectWatchDirs(dir) {
  * @param {SSEPool} opts.pool  — SSE broadcast pool
  * @returns {{ dirs: string[], destroy: Function }}
  */
-function startWatcher({ root, pool }) {
+function startWatcher({ root, pool, bundleMode, serveRoot }) {
   const watchDirs = collectWatchDirs(root);
   const watchers  = [];
 
   let debounceTimer;
   let currentError = null;   // track which file has an active error
+  let bundleTimer = null;    // debounce for bundle rebuilds
+
+  // 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 {
@@ -68,6 +95,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();
 
@@ -95,6 +129,30 @@ function startWatcher({ root, pool }) {
           }
 
           // ---- Full reload ----
+          if (bundleMode) {
+            // Debounce bundle rebuilds (500ms) so rapid saves don't spam
+            clearTimeout(bundleTimer);
+            bundleTimer = setTimeout(() => {
+              try {
+                const bundleFn = require('../bundle');
+                const { args: cliArgs } = require('../../args');
+                const savedArgs = cliArgs.slice();
+                cliArgs.length = 0;
+                cliArgs.push('bundle');
+                const prevCwd = process.cwd();
+                process.chdir(root);
+                bundleFn();
+                process.chdir(prevCwd);
+                cliArgs.length = 0;
+                savedArgs.forEach(a => cliArgs.push(a));
+                logReload(rel + ' (rebuilt)');
+                pool.broadcast('reload', rel);
+              } catch (err) {
+                console.error('  Bundle rebuild failed:', err.message);
+              }
+            }, 500);
+            return;
+          }
           logReload(rel);
           pool.broadcast('reload', rel);
         }, 100);

package/cli/help.js

@@ -7,7 +7,7 @@ function showHelp() {
   COMMANDS
 
     create [dir]               Scaffold a new zQuery project
-                               Creates index.html, scripts/, styles/ in the target directory
+                               Creates index.html, global.css, app/, assets/ in the target directory
                                (defaults to the current directory)
 
     dev [root]                 Start a dev server with live-reload
@@ -15,6 +15,8 @@ function showHelp() {
       --index, -i <file>        Index HTML file (default: index.html)
       --no-intercept           Disable auto-resolution of zquery.min.js
                                (serve the on-disk vendor copy instead)
+      --bundle, -b             Serve the bundled build (runs bundler first,
+                               serves from dist/server/, auto-rebuilds on save)
 
                                Includes error overlay: syntax errors are
                                caught on save and shown as a full-screen
@@ -24,7 +26,8 @@ function showHelp() {
     bundle [dir|file]          Bundle app ES modules into a single file
       --out, -o <path>         Output directory (default: dist/ next to HTML file)
       --index, -i <file>        Index HTML file (default: auto-detected)
-      --minimal, -m            Only output HTML + bundled JS (skip static assets)
+      --minimal, -m            Only output HTML, bundled JS, and global CSS (skip static assets)
+      --global-css <path>      Override global CSS input (default: first <link> in HTML)
 
     build                      Build the zQuery library \u2192 dist/      --watch, -w              Watch src/ and rebuild on changes                               (must be run from the project root where src/ lives)
 
@@ -35,7 +38,7 @@ function showHelp() {
         1. index.html first, then other .html files
         2. Within HTML: module script pointing to app.js, else first module script
         3. JS scan: $.router( first (entry point), then $.mount( / $.store(
-        4. Convention fallbacks (scripts/app.js, app.js, etc.)
+        4. Convention fallbacks (app/app.js, scripts/app.js, app.js, etc.)
       • Passing a directory auto-detects the entry; passing a file uses it directly
       • zquery.min.js is always embedded (auto-built from source if not found)
       • HTML file is auto-detected (any .html, not just index.html)
@@ -83,12 +86,12 @@ function showHelp() {
     zquery bundle my-app/
 
     # Pass a direct entry file (skip auto-detection)
-    zquery bundle my-app/scripts/main.js
+    zquery bundle my-app/app/main.js
 
     # Custom output directory
     zquery bundle my-app/ -o build/
 
-    # Minimal build (only HTML + bundled JS, no static assets)
+    # Minimal build (HTML + JS + global CSS, no static asset copying)
     zquery bundle my-app/ --minimal
 
     # Dev server with a custom index page