zero-query 0.7.5 → 0.8.6

package/README.md

@@ -15,19 +15,21 @@
 
 </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 ~80 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 ~91 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 |
 | --- | --- |
-| **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 |
+| **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`, `z-skip`), DOM morphing engine with LIS-based keyed reconciliation (no innerHTML rebuild), CSP-safe expression evaluation with AST caching, scoped styles, external templates (`templateUrl` / `styleUrl`), lifecycle hooks, auto-injected base styles |
+| **Router** | History & hash mode, route params (`:id`), wildcards, guards (`beforeEach`/`afterEach`), lazy loading, `z-link` navigation, `z-to-top` scroll modifier (`instant`/`smooth`), sub-route history substates (`pushSubstate`/`onSubstate`) |
+| **Directives** | `z-if`, `z-for`, `z-model`, `z-show`, `z-bind`, `z-class`, `z-style`, `z-text`, `z-html`, `z-ref`, `z-cloak`, `z-pre`, `z-key`, `z-skip` &mdash; 17 built-in template directives |
+| **Reactive** | Deep proxy reactivity, Signals (`.value`, `.peek()`), computed values, effects (auto-tracked with dispose) |
+| **Store** | Reactive global state, named actions, computed getters, middleware, subscriptions, time-travel (undo/redo/history) |
 | **Selectors & DOM** | jQuery-like chainable selectors, traversal, DOM manipulation, events, animation |
+| **HTTP** | Fetch wrapper with auto-JSON, interceptors, timeout/abort, base URL |
 | **Utils** | debounce, throttle, pipe, once, sleep, escapeHtml, uuid, deepClone, deepMerge, storage/session wrappers, event bus |
+| **Dev Tools** | CLI dev server with live-reload, CSS hot-swap, full-screen error overlay, floating toolbar, dark-themed inspector panel (Router view, DOM tree, network log, component viewer, performance dashboard), fetch interceptor, render instrumentation, CLI bundler for single-file production builds |
 
 ---
 
@@ -61,15 +63,19 @@ The dev server includes a **full-screen error overlay** that surfaces errors dir
 - **Runtime errors** — uncaught exceptions and unhandled promise rejections are captured and displayed in the same overlay with a cleaned-up stack trace.
 - The overlay **auto-clears** when you fix the error and save. Press `Esc` or click `×` to dismiss manually.
 
+#### Floating Toolbar & Inspector
+
+A compact toolbar appears in the bottom-right corner showing live request/render counters and a DOM button. Click any counter to open a **dark-themed DevTools inspector** as a popup — or visit `http://localhost:<port>/_devtools` for a standalone split-view panel with four tabs: **Elements** (live DOM tree with component badges, source viewer, expand/collapse), **Network** (fetch log with JSON viewer), **Components** (live state cards), and **Performance** (render timeline with timing metrics).
+
 ### Alternative: Manual Setup (No npm)
 
-If you prefer **zero tooling**, download `dist/zQuery.min.js` from the [GitHub releases](https://github.com/tonywied17/zero-query/releases/tag/RELEASE) and drop it into `scripts/vendor/`. Then open `index.html` directly in a browser — no Node.js required.
+If you prefer **zero tooling**, download `dist/zquery.min.js` from the [dist/ folder](https://github.com/tonywied17/zero-query/tree/main/dist) and drop it into your project root or `assets/scripts/`. Then open `index.html` directly in a browser — no Node.js required.
 
 ```bash
 git clone https://github.com/tonywied17/zero-query.git
 cd zero-query
 npx zquery build
-# → dist/zQuery.min.js  (~80 KB)
+# → dist/zquery.min.js  (~91 KB)
 ```
 
 ### Include in HTML
@@ -80,9 +86,9 @@ npx zquery build
 <head>
   <meta charset="UTF-8">
   <title>My App</title>
-  <link rel="stylesheet" href="styles/styles.css">
-  <script src="scripts/vendor/zQuery.min.js"></script>
-  <script type="module" src="scripts/app.js"></script>
+  <link rel="stylesheet" href="global.css">
+  <script src="zquery.min.js"></script>
+  <script type="module" src="app/app.js"></script>
 </head>
 <body>
   <nav>
@@ -97,7 +103,7 @@ npx zquery build
 ### Boot Your App
 
 ```js
-// scripts/app.js
+// app/app.js
 import './components/home.js';
 import './components/about.js';
 import './components/contacts/contacts.js';
@@ -109,7 +115,7 @@ $.router({ el: '#app', routes, fallback: 'not-found' });
 ### Define a Component
 
 ```js
-// scripts/components/home.js
+// app/components/home.js
 $.component('home-page', {
   state: () => ({ count: 0 }),
   increment() { this.state.count++; },
@@ -132,9 +138,8 @@ That's it — a fully working SPA with the dev server's live-reload.
 ```
 my-app/
   index.html
-  scripts/
-    vendor/
-      zQuery.min.js       ← only needed for manual setup; dev server auto-resolves
+  global.css
+  app/
     app.js
     routes.js
     store.js
@@ -149,14 +154,17 @@ my-app/
         contacts.js
         contacts.html
         contacts.css
-  styles/
-    styles.css
+  assets/
+    scripts/              ← third-party JS (e.g. zquery.min.js for manual setup)
+    styles/               ← additional stylesheets, fonts, etc.
 ```
 
 - One component per file inside `components/`.
 - Names **must contain a hyphen** (Web Component convention): `home-page`, `app-counter`, etc.
 - Components with external templates or styles can use a subfolder (e.g. `contacts/contacts.js` + `contacts.html` + `contacts.css`).
 - `app.js` is the single entry point — import components, create the store, and boot the router.
+- `global.css` lives next to `index.html` for easy access; the bundler hashes it into `global.<hash>.min.css` for production.
+- `assets/` holds static files that get copied to `dist/` as-is.
 
 ---
 
@@ -172,7 +180,7 @@ npx zquery bundle
 npx zquery bundle my-app/
 
 # Or pass a direct entry file (skips auto-detection)
-npx zquery bundle my-app/scripts/main.js
+npx zquery bundle my-app/app/main.js
 ```
 
 Output goes to `dist/` next to your `index.html`:
@@ -183,7 +191,8 @@ dist/
     index.html
     z-app.<hash>.js
     z-app.<hash>.min.js
-    styles/
+    global.<hash>.min.css
+    assets/
   local/                ← open from disk (file://) — no server needed
     index.html
     z-app.<hash>.js
@@ -196,7 +205,8 @@ dist/
 | --- | --- | --- |
 | `--out <path>` | `-o` | Custom output directory |
 | `--index <file>` | `-i` | 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 file (default: first `<link>` in HTML) |
 
 ### What the Bundler Does
 
@@ -204,7 +214,7 @@ dist/
    1. **HTML files** — `index.html` is checked first, then other `.html` files (root + one level deep).
    2. **Module scripts within HTML** — within each HTML file, a `<script type="module">` whose `src` resolves to `app.js` wins; otherwise the first module script tag is used.
    3. **JS file scan** — if no HTML match, JS files (up to 2 levels deep) are scanned in two passes: first for `$.router(` (the canonical app entry point), then for `$.mount(`, `$.store(`, or `mountAll(`.
-   4. **Convention fallbacks** — `scripts/app.js`, `src/app.js`, `js/app.js`, `app.js`, `main.js`.
+   4. **Convention fallbacks** — `app/app.js`, `scripts/app.js`, `src/app.js`, `js/app.js`, `app.js`, `main.js`.
 2. Resolves all `import` statements and topologically sorts dependencies
 3. Strips `import`/`export` syntax, wraps in an IIFE
 4. Embeds zQuery library and inlines `templateUrl` / `styleUrl` / `pages` files
@@ -246,8 +256,8 @@ location / {
 | `$.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 |
+| `$.component` `$.mount` `$.mountAll` `$.getInstance` `$.destroy` `$.components` `$.prefetch` | Component system |
+| `$.morph` `$.morphElement` | DOM morphing engine — LIS-based keyed reconciliation, `isEqualNode()` bail-outs, `z-skip` opt-out. Patches existing DOM to match new HTML without destroying unchanged nodes. Auto-key detection (`id`, `data-id`, `data-key`) — no `z-key` required. `$().html()` and `$().replaceWith()` auto-morph existing content; `$().morph()` for explicit morph |
 | `$.safeEval` | CSP-safe expression evaluator (replaces `eval` / `new Function`) |
 | `$.style` | Dynamically load global stylesheet file(s) at runtime |
 | `$.router` `$.getRouter` | SPA router |
@@ -260,16 +270,16 @@ location / {
 | `$.param` `$.parseQuery` | URL utils |
 | `$.storage` `$.session` | Storage wrappers |
 | `$.bus` | Event bus |
-| `$.version` | Library version |
+| `$.version` | Library version |\n| `$.libSize` | Minified bundle size string (e.g. `\"~91 KB\"`) |
 | `$.meta` | Build metadata (populated by CLI bundler) |
 | `$.noConflict` | Release `$` global |
 
 | CLI Command | Description |
 | --- | --- |
 | `zquery create [dir]` | Scaffold a new project (index.html, components, store, styles) |
-| `zquery dev [root]` | Dev server with live-reload &amp; error overlay (port 3100). `--index` for custom HTML. |
+| `zquery dev [root]` | Dev server with live-reload, CSS hot-swap, error overlay, floating toolbar &amp; inspector panel (port 3100). Visit `/_devtools` for the standalone panel. `--index` for custom HTML, `--bundle` for bundled mode, `--no-intercept` to skip CDN intercept. |
 | `zquery bundle [dir\|file]` | Bundle app into a single IIFE file. Accepts dir or direct entry file. |
-| `zquery build` | Build the zQuery library (`dist/zQuery.min.js`) |
+| `zquery build` | Build the zQuery library (`dist/zquery.min.js`) |
 | `zquery --help` | Show CLI usage |
 
 For full method signatures, options, and examples, see **[API.md](API.md)**.

package/cli/commands/build.js

@@ -9,6 +9,7 @@
 
 const fs   = require('fs');
 const path = require('path');
+const zlib = require('zlib');
 const { minify, sizeKB } = require('../utils');
 
 function buildLibrary() {
@@ -47,13 +48,121 @@ function buildLibrary() {
   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');
+  const minified = minify(bundle, banner);
+  fs.writeFileSync(MIN_FILE, minified, 'utf-8');
+
+  // Inject actual minified library size into both outputs
+  const libSizeKB = Math.round(Buffer.from(minified).length / 1024);
+  const libSizeStr = `~${libSizeKB} KB`;
+  const outContent = fs.readFileSync(OUT_FILE, 'utf-8').replace("'__LIB_SIZE__'", `'${libSizeStr}'`);
+  const minContent = minified.replace("'__LIB_SIZE__'", `'${libSizeStr}'`);
+  fs.writeFileSync(OUT_FILE, outContent, 'utf-8');
+  fs.writeFileSync(MIN_FILE, minContent, 'utf-8');
 
   const elapsed = Date.now() - start;
   console.log(`  ✓ dist/zquery.js (${sizeKB(fs.readFileSync(OUT_FILE))} KB)`);
   console.log(`  ✓ dist/zquery.min.js (${sizeKB(fs.readFileSync(MIN_FILE))} KB)`);
   console.log(`  Done in ${elapsed}ms\n`);
 
+  // --- Create dist/zquery.dist.zip -----------------------------------------
+  const root = process.cwd();
+  const zipFiles = [
+    { src: OUT_FILE,                        name: 'zquery.js' },
+    { src: MIN_FILE,                        name: 'zquery.min.js' },
+    { src: path.join(root, 'LICENSE'),      name: 'LICENSE' },
+    { src: path.join(root, 'API.md'),       name: 'API.md' },
+    { src: path.join(root, 'README.md'),    name: 'README.md' },
+  ];
+
+  // Minimal ZIP builder (deflate via zlib, no external deps)
+  function buildZip(entries) {
+    const localHeaders = [];
+    const centralHeaders = [];
+    let offset = 0;
+
+    for (const { name, data } of entries) {
+      const nameBytes = Buffer.from(name, 'utf-8');
+      const compressed = zlib.deflateRawSync(data, { level: 9 });
+      const crc = crc32(data);
+      const compLen = compressed.length;
+      const uncompLen = data.length;
+
+      // Local file header
+      const local = Buffer.alloc(30 + nameBytes.length);
+      local.writeUInt32LE(0x04034b50, 0);   // signature
+      local.writeUInt16LE(20, 4);            // version needed
+      local.writeUInt16LE(0, 6);             // flags
+      local.writeUInt16LE(8, 8);             // compression: deflate
+      local.writeUInt16LE(0, 10);            // mod time
+      local.writeUInt16LE(0, 12);            // mod date
+      local.writeUInt32LE(crc, 14);
+      local.writeUInt32LE(compLen, 18);
+      local.writeUInt32LE(uncompLen, 22);
+      local.writeUInt16LE(nameBytes.length, 26);
+      local.writeUInt16LE(0, 28);            // extra field length
+      nameBytes.copy(local, 30);
+
+      localHeaders.push(Buffer.concat([local, compressed]));
+
+      // Central directory header
+      const central = Buffer.alloc(46 + nameBytes.length);
+      central.writeUInt32LE(0x02014b50, 0);
+      central.writeUInt16LE(20, 4);          // version made by
+      central.writeUInt16LE(20, 6);          // version needed
+      central.writeUInt16LE(0, 8);           // flags
+      central.writeUInt16LE(8, 10);          // compression: deflate
+      central.writeUInt16LE(0, 12);          // mod time
+      central.writeUInt16LE(0, 14);          // mod date
+      central.writeUInt32LE(crc, 16);
+      central.writeUInt32LE(compLen, 20);
+      central.writeUInt32LE(uncompLen, 24);
+      central.writeUInt16LE(nameBytes.length, 28);
+      central.writeUInt16LE(0, 30);          // extra field length
+      central.writeUInt16LE(0, 32);          // comment length
+      central.writeUInt16LE(0, 34);          // disk number
+      central.writeUInt16LE(0, 36);          // internal attrs
+      central.writeUInt32LE(0, 38);          // external attrs
+      central.writeUInt32LE(offset, 42);     // local header offset
+      nameBytes.copy(central, 46);
+      centralHeaders.push(central);
+
+      offset += local.length + compressed.length;
+    }
+
+    const centralDir = Buffer.concat(centralHeaders);
+    const eocd = Buffer.alloc(22);
+    eocd.writeUInt32LE(0x06054b50, 0);
+    eocd.writeUInt16LE(0, 4);               // disk number
+    eocd.writeUInt16LE(0, 6);               // central dir disk
+    eocd.writeUInt16LE(entries.length, 8);   // entries on disk
+    eocd.writeUInt16LE(entries.length, 10);  // total entries
+    eocd.writeUInt32LE(centralDir.length, 12);
+    eocd.writeUInt32LE(offset, 16);          // central dir offset
+    eocd.writeUInt16LE(0, 20);              // comment length
+
+    return Buffer.concat([...localHeaders, centralDir, eocd]);
+  }
+
+  function crc32(buf) {
+    let crc = 0xFFFFFFFF;
+    for (let i = 0; i < buf.length; i++) {
+      crc ^= buf[i];
+      for (let j = 0; j < 8; j++) {
+        crc = (crc >>> 1) ^ ((crc & 1) ? 0xEDB88320 : 0);
+      }
+    }
+    return (crc ^ 0xFFFFFFFF) >>> 0;
+  }
+
+  const entries = zipFiles
+    .filter(f => fs.existsSync(f.src))
+    .map(f => ({ name: f.name, data: fs.readFileSync(f.src) }));
+
+  const zipBuf = buildZip(entries);
+  const zipPath = path.join(DIST, 'zquery.dist.zip');
+  fs.writeFileSync(zipPath, zipBuf);
+  console.log(`  ✓ dist/zquery.dist.zip (${sizeKB(zipBuf)} KB) — ${entries.length} files`);
+
   return { DIST, OUT_FILE, MIN_FILE };
 }
 

package/cli/commands/bundle.js

@@ -521,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;
@@ -539,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}`);
@@ -647,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, '');
 
@@ -664,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));
       }
@@ -695,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);
@@ -714,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;
@@ -833,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):`);
@@ -876,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'),
@@ -895,7 +932,7 @@ function bundleApp() {
       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/`);
     }
   }
 
@@ -921,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, '\\$&');
@@ -935,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 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, minFile, 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>`;

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

@@ -0,0 +1,49 @@
+// ===================================================================
+// Components
+// ===================================================================
+function renderComponents() {
+  var list = document.getElementById('comp-list');
+  if (!targetWin || !targetWin.$) {
+    list.innerHTML = '<div class="empty-state">Waiting for zQuery to load...</div>';
+    return;
+  }
+  var $ = targetWin.$;
+  var html = '';
+
+  // Iterate mounted components if components registry exists
+  if ($ && typeof $.components === 'function') {
+    var names = Object.keys($.components());
+    if (!names.length) {
+      list.innerHTML = '<div class="empty-state">No components registered</div>';
+      return;
+    }
+    for (var n = 0; n < names.length; n++) {
+      var name = names[n];
+      // Find mounted instances (exclude scoped <style> tags that carry data-zq-component)
+      var hosts = targetDoc.querySelectorAll(name + ':not(style)');
+      html += '<div class="comp-card">';
+      html += '<div class="comp-name">&lt;' + name + '&gt;</div>';
+      html += '<div class="comp-host">' + hosts.length + ' instance' + (hosts.length !== 1 ? 's' : '') + ' mounted</div>';
+      hosts.forEach(function(host) {
+        try {
+          var inst = $.getInstance(host);
+          if (inst && inst.state) {
+            html += '<div class="comp-state">';
+            var keys = Object.keys(inst.state);
+            for (var k = 0; k < keys.length; k++) {
+              var key = keys[k];
+              var val = inst.state[key];
+              var display = typeof val === 'object' ? JSON.stringify(val) : String(val);
+              if (display.length > 80) display = display.slice(0, 80) + '...';
+              html += '<div class="detail-row"><span class="comp-state-key">' + esc(key) + '</span><span class="comp-state-val">' + esc(display) + '</span></div>';
+            }
+            html += '</div>';
+          }
+        } catch(e) {}
+      });
+      html += '</div>';
+    }
+  }
+  if (!html) html = '<div class="empty-state">No components found</div>';
+  list.innerHTML = html;
+}