zero-query 0.6.3 → 0.8.6

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;
 }
 
@@ -275,7 +521,7 @@ function detectEntry(projectRoot) {
   }
 
   // 3. Convention fallbacks
-  const fallbacks = ['scripts/app.js', 'src/app.js', 'js/app.js', 'app.js', 'main.js'];
+  const fallbacks = ['app/app.js', 'scripts/app.js', 'src/app.js', 'js/app.js', 'app.js', 'main.js'];
   for (const f of fallbacks) {
     const fp = path.join(projectRoot, f);
     if (fs.existsSync(fp)) return fp;
@@ -293,7 +539,7 @@ function detectEntry(projectRoot) {
  *   server/index.html — <base href="/"> for SPA deep routes
  *   local/index.html  — relative paths for file:// access
  */
-function rewriteHtml(projectRoot, htmlRelPath, bundleFile, includeLib, bundledFiles, serverDir, localDir) {
+function rewriteHtml(projectRoot, htmlRelPath, bundleFile, includeLib, bundledFiles, serverDir, localDir, globalCssOrigHref, globalCssHash) {
   const htmlPath = path.resolve(projectRoot, htmlRelPath);
   if (!fs.existsSync(htmlPath)) {
     console.warn(`  ⚠  HTML file not found: ${htmlRelPath}`);
@@ -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) {
@@ -370,6 +647,15 @@ function rewriteHtml(projectRoot, htmlRelPath, bundleFile, includeLib, bundledFi
     );
   }
 
+  // Rewrite global CSS link to hashed version
+  if (globalCssOrigHref && globalCssHash) {
+    const escapedHref = globalCssOrigHref.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const cssLinkRe = new RegExp(
+      `(<link[^>]+href\\s*=\\s*["'])${escapedHref}(["'][^>]*>)`, 'i'
+    );
+    html = html.replace(cssLinkRe, `$1${globalCssHash}$2`);
+  }
+
   const serverHtml = html;
   const localHtml  = html.replace(/<base\s+href\s*=\s*["']\/["'][^>]*>\s*\n?\s*/i, '');
 
@@ -387,19 +673,26 @@ function rewriteHtml(projectRoot, htmlRelPath, bundleFile, includeLib, bundledFi
 
 /**
  * Copy the entire app directory into both dist/server and dist/local,
- * skipping only build outputs and tooling dirs.  This ensures all static
- * assets (icons/, images/, fonts/, styles/, scripts/, manifests, etc.)
- * are available in the built output without maintaining a fragile whitelist.
+ * skipping only build outputs, tooling dirs, and the app/ source dir.
+ * This ensures all static assets (assets/, icons/, images/, fonts/,
+ * manifests, etc.) are available in the built output without maintaining
+ * a fragile whitelist.
  */
 function copyStaticAssets(appRoot, serverDir, localDir, bundledFiles) {
-  const SKIP_DIRS = new Set(['dist', 'node_modules', '.git', '.vscode', 'scripts']);
+  const SKIP_DIRS = new Set(['dist', 'node_modules', '.git', '.vscode']);
+
+  // Case-insensitive match for App/ directory (contains bundled source)
+  function isAppDir(name) {
+    return name.toLowerCase() === 'app';
+  }
 
   let copiedCount = 0;
 
   function copyEntry(srcPath, relPath) {
     const stat = fs.statSync(srcPath);
     if (stat.isDirectory()) {
-      if (SKIP_DIRS.has(path.basename(srcPath))) return;
+      const dirName = path.basename(srcPath);
+      if (SKIP_DIRS.has(dirName) || isAppDir(dirName)) return;
       for (const child of fs.readdirSync(srcPath)) {
         copyEntry(path.join(srcPath, child), path.join(relPath, child));
       }
@@ -418,7 +711,7 @@ function copyStaticAssets(appRoot, serverDir, localDir, bundledFiles) {
 
   for (const entry of fs.readdirSync(appRoot, { withFileTypes: true })) {
     if (entry.isDirectory()) {
-      if (SKIP_DIRS.has(entry.name)) continue;
+      if (SKIP_DIRS.has(entry.name) || isAppDir(entry.name)) continue;
       copyEntry(path.join(appRoot, entry.name), entry.name);
     } else {
       copyEntry(path.join(appRoot, entry.name), entry.name);
@@ -437,6 +730,7 @@ function copyStaticAssets(appRoot, serverDir, localDir, bundledFiles) {
 function bundleApp() {
   const projectRoot = process.cwd();
   const minimal = flag('minimal', 'm');
+  const globalCssOverride = option('global-css', null, null);
 
   // Entry point — positional arg (directory or file) or auto-detection
   let entry = null;
@@ -556,14 +850,18 @@ function bundleApp() {
   console.log(`  Output:  ${path.relative(projectRoot, baseDistDir)}/server/ & local/`);
   console.log(`  Library: embedded`);
   console.log(`  HTML:    ${htmlFile || 'not found (no HTML detected)'}`);
-  if (minimal) console.log(`  Mode:    minimal (HTML + bundle only)`);
+  if (minimal) console.log(`  Mode:    minimal (HTML + JS + global CSS only)`);
   console.log('');
 
   // ------ doBuild (inlined) ------
   const start = Date.now();
 
-  if (!fs.existsSync(serverDir)) fs.mkdirSync(serverDir, { recursive: true });
-  if (!fs.existsSync(localDir))  fs.mkdirSync(localDir, { recursive: true });
+  // Clean previous dist outputs for a fresh build
+  for (const dir of [serverDir, localDir]) {
+    if (fs.existsSync(dir)) fs.rmSync(dir, { recursive: true });
+  }
+  fs.mkdirSync(serverDir, { recursive: true });
+  fs.mkdirSync(localDir, { recursive: true });
 
   const files = walkImportGraph(entry);
   console.log(`  Resolved ${files.length} module(s):`);
@@ -574,8 +872,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
@@ -598,8 +897,24 @@ function bundleApp() {
     }
 
     const htmlDir = htmlAbs ? path.dirname(htmlAbs) : null;
+
+    // Case-insensitive search for Assets/ directory
+    function findAssetsDir(root) {
+      try {
+        for (const e of fs.readdirSync(root, { withFileTypes: true })) {
+          if (e.isDirectory() && e.name.toLowerCase() === 'assets') return path.join(root, e.name);
+        }
+      } catch { /* skip */ }
+      return null;
+    }
+
+    const assetsDir    = findAssetsDir(htmlDir || projectRoot);
+    const altAssetsDir = htmlDir ? findAssetsDir(projectRoot) : null;
+
     const libCandidates = [
       path.join(pkgRoot, 'dist/zquery.min.js'),
+      assetsDir    && path.join(assetsDir, 'scripts/zquery.min.js'),
+      altAssetsDir && path.join(altAssetsDir, 'scripts/zquery.min.js'),
       htmlDir && path.join(htmlDir, 'scripts/vendor/zquery.min.js'),
       htmlDir && path.join(htmlDir, 'vendor/zquery.min.js'),
       path.join(projectRoot, 'scripts/vendor/zquery.min.js'),
@@ -612,16 +927,16 @@ 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`);
-      console.warn(`     Place zquery.min.js in scripts/vendor/, vendor/, lib/, or dist/`);
+      console.warn(`     Place zquery.min.js in assets/scripts/, vendor/, lib/, or dist/`);
     }
   }
 
-  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 +950,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)`);
   }
 
@@ -643,8 +958,7 @@ function bundleApp() {
 
   // Content-hashed filenames
   const contentHash = crypto.createHash('sha256').update(bundle).digest('hex').slice(0, 8);
-  const bundleBase  = `z-${entryName}.${contentHash}.js`;
-  const minBase     = `z-${entryName}.${contentHash}.min.js`;
+  const minBase = `z-${entryName}.${contentHash}.min.js`;
 
   // Clean previous builds
   const escName = entryName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -657,21 +971,70 @@ function bundleApp() {
     }
   }
 
-  // Write bundles
-  const bundleFile = path.join(serverDir, bundleBase);
-  const minFile    = path.join(serverDir, minBase);
-  fs.writeFileSync(bundleFile, bundle, 'utf-8');
+  // Write minified bundle
+  const minFile = path.join(serverDir, minBase);
   fs.writeFileSync(minFile, minify(bundle, banner), 'utf-8');
-  fs.copyFileSync(bundleFile, path.join(localDir, bundleBase));
   fs.copyFileSync(minFile, path.join(localDir, minBase));
 
-  console.log(`\n  ✓ ${bundleBase} (${sizeKB(fs.readFileSync(bundleFile))} KB)`);
-  console.log(`  ✓ ${minBase} (${sizeKB(fs.readFileSync(minFile))} KB)`);
+  console.log(`\n  ✓ ${minBase} (${sizeKB(fs.readFileSync(minFile))} KB)`);
+
+  // ------------------------------------------------------------------
+  // Global CSS bundling — extract from index.html <link> or --global-css
+  // ------------------------------------------------------------------
+  let globalCssHash = null;
+  let globalCssOrigHref = null;
+  let globalCssPath = null;
+  if (htmlAbs) {
+    const htmlContent = fs.readFileSync(htmlAbs, 'utf-8');
+    const htmlDir = path.dirname(htmlAbs);
+
+    // Determine global CSS path: --global-css flag overrides, else first <link rel="stylesheet"> in HTML
+    globalCssPath = null;
+    if (globalCssOverride) {
+      globalCssPath = path.resolve(projectRoot, globalCssOverride);
+      // Reconstruct relative href for HTML rewriting
+      globalCssOrigHref = path.relative(htmlDir, globalCssPath).replace(/\\/g, '/');
+    } else {
+      const linkRe = /<link[^>]+rel\s*=\s*["']stylesheet["'][^>]+href\s*=\s*["']([^"']+)["']/gi;
+      const altRe  = /<link[^>]+href\s*=\s*["']([^"']+)["'][^>]+rel\s*=\s*["']stylesheet["']/gi;
+      let linkMatch = linkRe.exec(htmlContent) || altRe.exec(htmlContent);
+      if (linkMatch) {
+        globalCssOrigHref = linkMatch[1];
+        // Strip query string / fragment so the path resolves to the actual file
+        const cleanHref = linkMatch[1].split('?')[0].split('#')[0];
+        globalCssPath = path.resolve(htmlDir, cleanHref);
+      }
+    }
+
+    if (globalCssPath && fs.existsSync(globalCssPath)) {
+      let cssContent = fs.readFileSync(globalCssPath, 'utf-8');
+      const cssMin = minifyCSS(cssContent);
+      const cssHash = crypto.createHash('sha256').update(cssMin).digest('hex').slice(0, 8);
+      const cssOutName = `global.${cssHash}.min.css`;
+
+      // Clean previous global CSS builds
+      const cssCleanRe = /^global\.[a-f0-9]{8}\.min\.css$/;
+      for (const dir of [serverDir, localDir]) {
+        if (fs.existsSync(dir)) {
+          for (const f of fs.readdirSync(dir)) {
+            if (cssCleanRe.test(f)) fs.unlinkSync(path.join(dir, f));
+          }
+        }
+      }
+
+      fs.writeFileSync(path.join(serverDir, cssOutName), cssMin, 'utf-8');
+      fs.writeFileSync(path.join(localDir, cssOutName), cssMin, 'utf-8');
+      globalCssHash = cssOutName;
+      console.log(`  ✓ ${cssOutName} (${sizeKB(Buffer.from(cssMin))} KB)`);
+    }
+  }
 
-  // Rewrite HTML (use full bundle — minified version mangles template literal whitespace)
+  // Rewrite HTML to reference the minified bundle
   const bundledFileSet = new Set(files);
+  // Skip the original unminified global CSS from static asset copying
+  if (globalCssPath) bundledFileSet.add(path.resolve(globalCssPath));
   if (htmlFile) {
-    rewriteHtml(projectRoot, htmlFile, bundleFile, true, bundledFileSet, serverDir, localDir);
+    rewriteHtml(projectRoot, htmlFile, minFile, true, bundledFileSet, serverDir, localDir, globalCssOrigHref, globalCssHash);
   }
 
   // Copy static asset directories (icons/, images/, fonts/, etc.)

package/cli/commands/create.js

@@ -26,7 +26,7 @@ function createProject(args) {
   const name   = path.basename(target);
 
   // Guard: refuse to overwrite existing files
-  const conflicts = ['index.html', 'scripts'].filter(f =>
+  const conflicts = ['index.html', 'global.css', 'app', 'assets'].filter(f =>
     fs.existsSync(path.join(target, f))
   );
   if (conflicts.length) {

package/cli/commands/dev/devtools/index.js

@@ -0,0 +1,56 @@
+/**
+ * cli/commands/dev/devtools/index.js — DevTools HTML assembler
+ *
+ * Reads CSS, HTML, and JS partials from this folder and concatenates them
+ * into a single self-contained HTML page served at /_devtools.
+ *
+ * Communication:
+ *   - window.opener: direct DOM access (same-origin popup)
+ *   - BroadcastChannel('__zq_devtools'): cross-tab fallback
+ */
+
+'use strict';
+
+const { readFileSync } = require('fs');
+const { join } = require('path');
+
+const dir = __dirname;
+const read = (f) => readFileSync(join(dir, f), 'utf8');
+
+const css = read('styles.css');
+const html = read('panel.html');
+
+const jsFiles = [
+  'js/core.js',
+  'js/tabs.js',
+  'js/source.js',
+  'js/elements.js',
+  'js/network.js',
+  'js/components.js',
+  'js/performance.js',
+  'js/router.js',
+  'js/stats.js'
+];
+
+const js = jsFiles.map(read).join('\n\n');
+
+module.exports = `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>zQuery DevTools</title>
+<style>
+${css}
+</style>
+</head>
+<body>
+${html}
+<script>
+(function() {
+'use strict';
+${js}
+})();
+</script>
+</body>
+</html>`;