zero-query 0.9.8 → 1.0.0

package/README.md

@@ -15,21 +15,23 @@
 
 </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 ~100 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 |
 | --- | --- |
-| **Components** | Reactive state, template literals, `@event` delegation (22 modifiers — key filters, system keys, `.outside`, timing, and more), `z-model` two-way binding (with `z-trim`, `z-number`, `z-lazy`, `z-debounce`, `z-uppercase`, `z-lowercase`), 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, action history, snapshots |
+| **Components** | Reactive state, template literals, `@event` delegation (22 modifiers - key filters, system keys, `.outside`, timing, and more), `z-model` two-way binding (with `z-trim`, `z-number`, `z-lazy`, `z-debounce`, `z-uppercase`, `z-lowercase`), 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 with `z-link-params`, `z-to-top` scroll modifier (`instant`/`smooth`), `z-active-route` active-link class directive, `<z-outlet>` declarative mount point, sub-route history substates (`pushSubstate`/`onSubstate`) |
+| **Directives** | `z-if`, `z-else-if`, `z-else`, `z-for`, `z-model`, `z-show`, `z-bind`/`:attr`, `z-class`, `z-style`, `z-text`, `z-html`, `z-ref`, `z-cloak`, `z-pre`, `z-key`, `z-skip`, `@event`/`z-on` &mdash; 17 built-in template directives |
+| **Reactive** | Deep proxy reactivity, Signals (`.value`, `.peek()`), computed values, effects (auto-tracked with dispose), `batch()` for deferred notifications, `untracked()` for dependency-free reads |
+| **Store** | Reactive global state, named actions, computed getters, middleware, subscriptions, `batch()` grouped mutations, `checkpoint()`/`undo()`/`redo()` with configurable stack, action history, snapshots |
 | **Selectors & DOM** | jQuery-like chainable selectors, traversal, DOM manipulation, events, animation |
 | **HTTP** | Fetch wrapper with auto-JSON, interceptors (with unsubscribe & clear), HEAD requests, parallel requests (`http.all`), config inspection (`getConfig`), timeout/abort, base URL |
-| **Utils** | debounce, throttle, pipe, once, sleep, memoize, escapeHtml, stripHtml, uuid, capitalize, truncate, range, chunk, groupBy, unique, pick, omit, getPath/setPath, isEmpty, clamp, retry, timeout, deepClone, deepMerge, storage/session wrappers, event bus |
+| **Utils** | debounce, throttle, pipe, once, sleep, memoize (LRU), escapeHtml, stripHtml, uuid, capitalize, truncate, range, chunk, groupBy, unique, pick, omit, getPath/setPath, isEmpty, clamp, retry, timeout, deepClone (enhanced fallback), deepMerge (prototype-pollution safe), storage/session wrappers, event bus |
+| **Security** | XSS-safe template expressions (`{{}}` auto-escaping), sandboxed expression evaluator (blocks `window`, `Function`, `eval`, `RegExp`, `Error`, prototype chains), prototype pollution prevention in `deepMerge`/`setPath`, `z-link` protocol validation, SSR error sanitization |
 | **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 |
+| **SSR** | Server-side rendering to HTML strings in Node.js - `createSSRApp()`, `renderToString()`, `renderPage()` with SEO/Open Graph support, `renderBatch()` for parallel rendering, fragment mode, hydration markers, graceful error handling, `escapeHtml()` utility |
 
 ---
 
@@ -37,7 +39,7 @@
 
 ### Recommended: CLI Dev Server
 
-The fastest way to develop with zQuery is via the built-in **CLI dev server** with **live-reload**. It serves your ES modules as-is and automatically resolves the library — no manual downloads required.
+The fastest way to develop with zQuery is via the built-in **CLI dev server** with **live-reload**. It serves your ES modules as-is and automatically resolves the library - no manual downloads required.
 
 ```bash
 # Install (per-project or globally)
@@ -53,29 +55,29 @@ npx zquery dev my-app
 
 > **Tip:** Stay in the project root (where `node_modules` lives) instead of `cd`-ing into `my-app`. This keeps `index.d.ts` accessible to your IDE for full type/intellisense support.
 
-The `create` command generates a ready-to-run project with a sidebar layout, router, multiple components (including folder components with external templates and styles), and responsive styles. Use `--minimal` (or `-m`) to scaffold a lightweight 3-page starter instead. The dev server watches for file changes, hot-swaps CSS in-place, full-reloads on other changes, and handles SPA fallback routing.
+The `create` command generates a ready-to-run project with a sidebar layout, router, multiple components (including folder components with external templates and styles), and responsive styles. Use `--minimal` (or `-m`) to scaffold a lightweight 3-page starter instead. Use `--ssr` (or `-s`) to scaffold a project with a Node.js server-side rendering example. The dev server watches for file changes, hot-swaps CSS in-place, full-reloads on other changes, and handles SPA fallback routing.
 
 #### Error Overlay
 
-The dev server includes a **full-screen error overlay** that surfaces errors directly in the browser — similar to Vite or Angular:
+The dev server includes a **full-screen error overlay** that surfaces errors directly in the browser - similar to Vite or Angular:
 
-- **Syntax errors** — JS files are validated on every save *before* the reload is triggered. If a syntax error is found the page stays intact and a dark overlay appears with the error message, file path, line:column, and a code frame pointing to the exact location.
-- **Runtime errors** — uncaught exceptions and unhandled promise rejections are captured and displayed in the same overlay with a cleaned-up stack trace.
+- **Syntax errors** - JS files are validated on every save *before* the reload is triggered. If a syntax error is found the page stays intact and a dark overlay appears with the error message, file path, line:column, and a code frame pointing to the exact location.
+- **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 expandable toolbar appears in the bottom-right corner. In its **collapsed** state it shows live render and request counters. Click the chevron to **expand** and reveal the route indicator (color-coded by the last navigation event — navigate, pop, replace, hashchange, substate), registered component count, and DOM element count. Click any stat to open a **dark-themed DevTools inspector** as a popup — or visit `http://localhost:<port>/_devtools` for a standalone split-view panel with five tabs: **Router** (live route state, guards, history timeline), **Components** (live state cards), **Performance** (render timeline with timing metrics), **Network** (fetch log with JSON viewer), and **Elements** (live DOM tree with component badges, source viewer, expand/collapse).
+A compact expandable toolbar appears in the bottom-right corner. In its **collapsed** state it shows live render and request counters. Click the chevron to **expand** and reveal the route indicator (color-coded by the last navigation event - navigate, pop, replace, hashchange, substate), registered component count, and DOM element count. Click any stat to open a **dark-themed DevTools inspector** as a popup - or visit `http://localhost:<port>/_devtools` for a standalone split-view panel with five tabs: **Router** (live route state, guards, history timeline), **Components** (live state cards), **Performance** (render timeline with timing metrics), **Network** (fetch log with JSON viewer), and **Elements** (live DOM tree with component badges, source viewer, expand/collapse).
 
 ### Alternative: Manual Setup (No npm)
 
-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.
+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  (~100 KB)
+# → dist/zquery.min.js  (~91 KB)
 ```
 
 ### Include in HTML
@@ -109,7 +111,7 @@ import './components/about.js';
 import './components/contacts/contacts.js';
 import { routes } from './routes.js';
 
-$.router({ el: '#app', routes, fallback: 'not-found' });
+$.router({ routes, fallback: 'not-found' });
 ```
 
 ### Define a Component
@@ -129,7 +131,7 @@ $.component('home-page', {
 });
 ```
 
-That's it — a fully working SPA with the dev server's live-reload.
+That's it - a fully working SPA with the dev server's live-reload.
 
 ---
 
@@ -186,10 +188,30 @@ my-app/                          ← minimal scaffold (npx zquery create my-app
   assets/
 ```
 
+Use `--ssr` for a project with server-side rendering:
+
+```
+my-app/                          ← SSR scaffold (npx zquery create my-app --ssr)
+  index.html                     ← client HTML shell
+  global.css
+  app/
+    app.js                       ← client entry - registers shared components
+    routes.js                    ← shared route definitions
+    components/
+      home.js                    ← shared component (SSR + client)
+      about.js
+      not-found.js
+  server/
+    index.js                     ← SSR HTTP server
+  assets/
+```
+
+Components in `app/components/` export plain definition objects - the client registers them with `$.component()`, the server with `app.component()`. The `--ssr` flag handles everything automatically - installs dependencies, starts the server at `http://localhost:3000`, and opens the browser.
+
 - 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.
+- `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.
 
@@ -197,7 +219,7 @@ my-app/                          ← minimal scaffold (npx zquery create my-app
 
 ## CLI Bundler
 
-The CLI compiles your entire app — ES modules, the library, external templates, and assets — into a **single production-ready bundle**. It outputs two builds in one step: a `server/` build for deploying to any web server, and a `local/` build that works straight from disk. No config, no flags — just point it at your app.
+The CLI compiles your entire app - ES modules, the library, external templates, and assets - into a **single production-ready bundle**. It outputs two builds in one step: a `server/` build for deploying to any web server, and a `local/` build that works straight from disk. No config, no flags - just point it at your app.
 
 ```bash
 # Auto-detect entry from any .html with a module script
@@ -219,7 +241,7 @@ dist/
     z-app.<hash>.min.js
     global.<hash>.min.css
     assets/
-  local/                ← open from disk (file://) — no server needed
+  local/                ← open from disk (file://) - no server needed
     index.html
     z-app.<hash>.min.js
     ...
@@ -236,11 +258,11 @@ dist/
 
 ### What the Bundler Does
 
-1. **Entry detection** — a strict precedence order ensures the correct file is chosen:
-   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** — `app/app.js`, `scripts/app.js`, `src/app.js`, `js/app.js`, `app.js`, `main.js`.
+1. **Entry detection** - a strict precedence order ensures the correct file is chosen:
+   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** - `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` files
@@ -268,7 +290,7 @@ location / {
 }
 ```
 
-**Sub-path deployment** (e.g. `/my-app/`): set `<base href="/my-app/">` in your HTML — the router auto-detects it.
+**Sub-path deployment** (e.g. `/my-app/`): set `<base href="/my-app/">` in your HTML - the router auto-detects it.
 
 ---
 
@@ -277,13 +299,13 @@ location / {
 | Namespace | Methods |
 | --- | --- |
 | `$()` | Chainable selector → `ZQueryCollection` (CSS selectors, elements, NodeLists, HTML strings) |
-| `$.all()` | Alias for `$()` — identical behavior |
+| `$.all()` | Alias for `$()` - identical behavior |
 | `$.id` `$.class` `$.classes` `$.tag` `$.name` `$.children` `$.qs` `$.qsa` | 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` `$.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 |
+| `$.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 |
@@ -298,14 +320,16 @@ location / {
 | `$.retry` `$.timeout` | Async utils |
 | `$.param` `$.parseQuery` | URL utils |
 | `$.storage` `$.session` | Storage wrappers |
-| `$.EventBus` `$.bus` | Event bus || `$.onError` `$.ZQueryError` `$.ErrorCode` `$.guardCallback` `$.validate` | Error handling || `$.version` | Library version |\n| `$.libSize` | Minified bundle size string (e.g. `\"~100 KB\"`) |
+| `$.EventBus` `$.bus` | Event bus |
+| `$.onError` `$.ZQueryError` `$.ErrorCode` `$.guardCallback` `$.guardAsync` `$.formatError` `$.validate` | Error handling |
+| `$.version` | Library version |\n| `$.libSize` | Minified bundle size string (e.g. `\"~91 KB\"`) |
 | `$.unitTests` | Build-time test results `{ passed, failed, total, suites, duration, ok }` |
 | `$.meta` | Build metadata (populated by CLI bundler) |
 | `$.noConflict` | Release `$` global |
 
 | CLI Command | Description |
 | --- | --- |
-| `zquery create [dir]` | Scaffold a new project. Default: full-featured app. `--minimal` / `-m`: lightweight 3-page starter with 404 fallback. |
+| `zquery create [dir]` | Scaffold a new project. Default: full-featured app. `--minimal` / `-m`: lightweight 3-page starter. `--ssr` / `-s`: SSR project with shared components and HTTP server. |
 | `zquery dev [root]` | Dev server with live-reload, CSS hot-swap, error overlay, expandable floating toolbar &amp; five-tab 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`) |
@@ -323,4 +347,4 @@ The official **[zQuery for VS Code](https://marketplace.visualstudio.com/items?i
 
 ## License
 
-MIT — [Anthony Wiedman / Molex](https://github.com/tonywied17)
+MIT - [Anthony Wiedman / Molex](https://github.com/tonywied17)

package/cli/args.js

@@ -1,5 +1,5 @@
 /**
- * cli/args.js — CLI argument parsing helpers
+ * cli/args.js - CLI argument parsing helpers
  *
  * Provides the raw args array and two helper functions for reading
  * named flags (--verbose, -v) and valued options (--port 8080, -p 8080).

package/cli/commands/build.js

@@ -1,5 +1,5 @@
 /**
- * cli/commands/build.js — library build command
+ * cli/commands/build.js - library build command
  *
  * Concatenates the zQuery source modules into dist/zquery.js and
  * dist/zquery.min.js.
@@ -208,7 +208,7 @@ function buildLibrary() {
   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`);
+  console.log(`  ✓ dist/zquery.dist.zip (${sizeKB(zipBuf)} KB) - ${entries.length} files`);
 
   return { DIST, OUT_FILE, MIN_FILE };
 }

package/cli/commands/bundle.js

@@ -1,5 +1,5 @@
 /**
- * cli/commands/bundle.js — app bundler command
+ * cli/commands/bundle.js - app bundler command
  *
  * Walks the ES module import graph starting from an entry file,
  * strips import/export syntax, concatenates everything into a single
@@ -59,7 +59,7 @@ function extractImports(code) {
   return specifiers;
 }
 
-/** Walk the import graph — topological sort (leaves first). */
+/** Walk the import graph - topological sort (leaves first). */
 function walkImportGraph(entry) {
   const visited = new Set();
   const order   = [];
@@ -119,7 +119,7 @@ function rewriteResourceUrls(code, filePath, projectRoot) {
     (match, prefix, quote, url) => {
       if (url.startsWith('/') || url.includes('://')) return match;
       const abs = path.resolve(fileDir, url);
-      // Only rewrite if the file actually exists — avoids mangling code examples
+      // Only rewrite if the file actually exists - avoids mangling code examples
       if (!fs.existsSync(abs)) return match;
       const rel = path.relative(projectRoot, abs).replace(/\\/g, '/');
       return `${prefix}${quote}${rel}${quote}`;
@@ -128,7 +128,7 @@ function rewriteResourceUrls(code, filePath, projectRoot) {
 }
 
 /**
- * Minify HTML for inlining — strips indentation and collapses whitespace
+ * 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.
  */
@@ -164,7 +164,7 @@ function minifyHTML(html) {
 }
 
 /**
- * Minify CSS for inlining — strips comments, collapses whitespace,
+ * Minify CSS for inlining - strips comments, collapses whitespace,
  * removes unnecessary spaces around punctuation.
  */
 function minifyCSS(css) {
@@ -396,7 +396,7 @@ function collectInlineResources(files, projectRoot) {
         inlineMap[relKey] = fs.readFileSync(tmplPath, 'utf-8');
       }
     } else if (/templateUrl\s*:/.test(code)) {
-      // Dynamic templateUrl (e.g. Object.fromEntries, computed map) —
+      // Dynamic templateUrl (e.g. Object.fromEntries, computed map) -
       // inline all .html files in the component's directory tree so
       // the runtime __zqInline lookup can resolve them by suffix.
       (function scanHtml(dir) {
@@ -412,7 +412,7 @@ function collectInlineResources(files, projectRoot) {
               scanHtml(full);
             }
           }
-        } catch { /* permission error — skip */ }
+        } catch { /* permission error - skip */ }
       })(fileDir);
     }
   }
@@ -429,7 +429,7 @@ function collectInlineResources(files, projectRoot) {
 /**
  * Auto-detect the app entry point.
  *
- * Strategy — ordered by precedence (first match wins):
+ * Strategy - ordered by precedence (first match wins):
  *   1. HTML discovery: index.html first, then other .html files
  *      (root level + one directory deep).
  *   2. Within each HTML file, prefer a module <script> whose src
@@ -456,7 +456,7 @@ function detectEntry(projectRoot) {
             htmlFiles.push(path.join(sub, child.name));
           }
         }
-      } catch { /* permission error — skip */ }
+      } catch { /* permission error - skip */ }
     }
   }
 
@@ -490,8 +490,8 @@ function detectEntry(projectRoot) {
   }
 
   // 2. Search JS files for entry-point patterns.
-  //    Pass 1 — $.router (the canonical entry point).
-  //    Pass 2 — $.mount, $.store, mountAll (component-level, lower confidence).
+  //    Pass 1 - $.router (the canonical entry point).
+  //    Pass 2 - $.mount, $.store, mountAll (component-level, lower confidence).
   const routerRe  = /\$\.router\s*\(/;
   const otherRe   = /\$\.(mount|store)\s*\(|mountAll\s*\(/;
 
@@ -541,8 +541,8 @@ function detectEntry(projectRoot) {
 /**
  * Rewrite an HTML file to replace the module <script> with the bundle.
  * Produces two variants:
- *   server/index.html — <base href="/"> for SPA deep routes
- *   local/index.html  — relative paths for file:// access
+ *   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, globalCssOrigHref, globalCssHash) {
   const htmlPath = path.resolve(projectRoot, htmlRelPath);
@@ -737,7 +737,7 @@ function bundleApp() {
   const minimal = flag('minimal', 'm');
   const globalCssOverride = option('global-css', null, null);
 
-  // Entry point — positional arg (directory or file) or auto-detection
+  // Entry point - positional arg (directory or file) or auto-detection
   let entry = null;
   let targetDir = null;
   for (let i = 1; i < args.length; i++) {
@@ -984,7 +984,7 @@ function bundleApp() {
   console.log(`\n  ✓ ${minBase} (${sizeKB(fs.readFileSync(minFile))} KB)`);
 
   // ------------------------------------------------------------------
-  // Global CSS bundling — extract from index.html <link> or --global-css
+  // Global CSS bundling - extract from index.html <link> or --global-css
   // ------------------------------------------------------------------
   let globalCssHash = null;
   let globalCssOrigHref = null;

package/cli/commands/create.js

@@ -1,4 +1,4 @@
-// cli/commands/create.js — scaffold a new zQuery project
+// cli/commands/create.js - scaffold a new zQuery project
 //
 // Templates live in cli/scaffold/<variant>/ (default or minimal).
 // Reads template files, replaces {{NAME}} with the project name,
@@ -6,6 +6,7 @@
 
 const fs   = require('fs');
 const path = require('path');
+const { execSync, spawn } = require('child_process');
 const { flag } = require('../args');
 
 /**
@@ -30,11 +31,15 @@ function createProject(args) {
   const target = dirArg ? path.resolve(dirArg) : process.cwd();
   const name   = path.basename(target);
 
-  // Determine scaffold variant: --minimal / -m  or  default
-  const variant = flag('minimal', 'm') ? 'minimal' : 'default';
+  // Determine scaffold variant: --minimal / -m  or  --ssr / -s  or  default
+  const variant = flag('minimal', 'm') ? 'minimal'
+                : flag('ssr', 's')     ? 'ssr'
+                :                        'default';
 
   // Guard: refuse to overwrite existing files
-  const conflicts = ['index.html', 'global.css', 'app', 'assets'].filter(f =>
+  const checkFiles = ['index.html', 'global.css', 'app', 'assets'];
+  if (variant === 'ssr') checkFiles.push('server');
+  const conflicts = checkFiles.filter(f =>
     fs.existsSync(path.join(target, f))
   );
   if (conflicts.length) {
@@ -43,7 +48,7 @@ function createProject(args) {
     process.exit(1);
   }
 
-  console.log(`\n  zQuery — Create Project (${variant})\n`);
+  console.log(`\n  zQuery - Create Project (${variant})\n`);
   console.log(`  Scaffolding into ${target}\n`);
 
   // Resolve the scaffold template directory for the chosen variant
@@ -70,11 +75,40 @@ function createProject(args) {
     console.log(`  ✓ ${rel}`);
   }
 
-  console.log(`
+  const devCmd = `npx zquery dev${target !== process.cwd() ? ` ${dirArg}` : ''}`;
+
+  if (variant === 'ssr') {
+    console.log(`\n  Installing dependencies...\n`);
+    // Install zero-query from the same package that provides this CLI
+    // (works both in local dev and when installed from npm)
+    const zqRoot = path.resolve(__dirname, '..', '..');
+    try {
+      execSync(`npm install "${zqRoot}"`, { cwd: target, stdio: 'inherit' });
+    } catch {
+      console.error(`\n  ✗ npm install failed. Run it manually:\n\n    cd ${dirArg || '.'}\n    npm install\n    node server/index.js\n`);
+      process.exit(1);
+    }
+
+    console.log(`\n  Starting SSR server...\n`);
+    const child = spawn('node', ['server/index.js'], { cwd: target, stdio: 'inherit' });
+
+    setTimeout(() => {
+      const open = process.platform === 'win32' ? 'start'
+                 : process.platform === 'darwin' ? 'open' : 'xdg-open';
+      try { execSync(`${open} http://localhost:3000`, { stdio: 'ignore' }); } catch {}
+    }, 500);
+
+    process.on('SIGINT',  () => { child.kill(); process.exit(); });
+    process.on('SIGTERM', () => { child.kill(); process.exit(); });
+    child.on('exit', (code) => process.exit(code || 0));
+    return; // keep process alive for the server
+  } else {
+    console.log(`
   Done! Next steps:
 
-    npx zquery dev${target !== process.cwd() ? ` ${dirArg}` : ''}
+    ${devCmd}
 `);
+  }
 }
 
 module.exports = createProject;

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

@@ -1,5 +1,5 @@
 /**
- * cli/commands/dev/devtools/index.js — DevTools HTML assembler
+ * 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.

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

@@ -39,7 +39,7 @@ function formatTime(ts) {
 }
 
 // ===================================================================
-// Connection — find target window (opener popup → iframe fallback)
+// Connection - find target window (opener popup → iframe fallback)
 // ===================================================================
 function isConnected() {
   try { return targetWin && (targetWin === window.opener ? !targetWin.closed : true) && targetWin.document; }
@@ -48,11 +48,11 @@ function isConnected() {
 
 function detectMode() {
   if (window.opener) {
-    // Opened as popup — hide iframe, use opener
+    // Opened as popup - hide iframe, use opener
     mode = 'popup';
     targetWin = window.opener;
   } else {
-    // Standalone tab — embed app in iframe
+    // Standalone tab - embed app in iframe
     mode = 'split-h';
     targetWin = null; // will set from iframe.contentWindow
   }
@@ -110,11 +110,11 @@ var tbDragging = false;
 
     var isH = mode === 'split-h';
     if (isH) {
-      // Vertical column divider — drag toolbar up/down
+      // Vertical column divider - drag toolbar up/down
       startPos = e.clientY;
       startOffset = parseInt(toolbar.style.top, 10) || toolbar.offsetTop;
     } else {
-      // Horizontal row divider — drag toolbar left/right
+      // Horizontal row divider - drag toolbar left/right
       startPos = e.clientX;
       startOffset = parseInt(toolbar.style.left, 10) || toolbar.offsetLeft;
     }
@@ -180,7 +180,7 @@ divider.addEventListener('mousedown', function(e) {
 });
 
 // ===================================================================
-// Refresh button — reload the embedded iframe
+// Refresh button - reload the embedded iframe
 // ===================================================================
 document.getElementById('btn-refresh').addEventListener('click', function(e) {
   e.stopPropagation();
@@ -192,7 +192,7 @@ document.getElementById('btn-refresh').addEventListener('click', function(e) {
 });
 
 // ===================================================================
-// Viewport preset buttons — resize browser pane to mobile/tablet/desktop
+// Viewport preset buttons - resize browser pane to mobile/tablet/desktop
 // ===================================================================
 var viewportBtns = document.querySelectorAll('.viewport-btn');
 
@@ -219,10 +219,10 @@ viewportBtns.forEach(function(btn) {
     var total = rootEl.offsetWidth;
 
     if (targetWidth === 0) {
-      // Desktop — reset to default CSS proportions
+      // Desktop - reset to default CSS proportions
       rootEl.style.gridTemplateColumns = '';
     } else {
-      // Mobile/Tablet — set iframe column to exact pixel width
+      // Mobile/Tablet - set iframe column to exact pixel width
       var pct = Math.min(85, Math.max(15, (targetWidth / total) * 100));
       rootEl.style.gridTemplateColumns = pct.toFixed(1) + '% 4px 1fr';
     }
@@ -233,7 +233,7 @@ viewportBtns.forEach(function(btn) {
 });
 
 // ===================================================================
-// Route indicator — toggle label showing current path + hash
+// Route indicator - toggle label showing current path + hash
 // ===================================================================
 var routeBtn = document.getElementById('btn-route');
 var routeLabel = document.getElementById('route-label');
@@ -266,7 +266,7 @@ setInterval(function() {
 }, 500);
 
 // ===================================================================
-// init — connect to target window (popup or iframe)
+// init - connect to target window (popup or iframe)
 // ===================================================================
 function init() {
   // If popup mode, targetWin is already set
@@ -310,7 +310,7 @@ function init() {
 }
 
 // ===================================================================
-// connectToTarget — read existing data, start listeners, periodic sync
+// connectToTarget - read existing data, start listeners, periodic sync
 // ===================================================================
 function connectToTarget() {
 
@@ -372,7 +372,7 @@ function connectToTarget() {
   // Periodic refresh for components + perf (fast when tab is visible)
   setInterval(function() {
     if (!isConnected()) {
-      // Retry connection — opener may be mid-mutation, not truly gone
+      // Retry connection - opener may be mid-mutation, not truly gone
       try {
         if (mode === 'popup' && window.opener && !window.opener.closed) {
           targetWin = window.opener;
@@ -389,7 +389,7 @@ function connectToTarget() {
         return;
       }
     }
-    // Keep targetDoc fresh — the opener may have reloaded (live-reload)
+    // Keep targetDoc fresh - the opener may have reloaded (live-reload)
     try {
       var freshDoc = targetWin.document;
       if (freshDoc !== targetDoc) {

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

@@ -72,7 +72,7 @@ function buildNode(node, depth) {
   var nodePath = getNodePath(node);
   var hasChildren = false;
   var childNodes = node.childNodes;
-  // style/script content is shown inline via the peek button — treat as leaf
+  // style/script content is shown inline via the peek button - treat as leaf
   if (tag !== 'style' && tag !== 'script') {
     for (var i = 0; i < childNodes.length; i++) {
       var cn = childNodes[i];
@@ -238,7 +238,7 @@ function buildNode(node, depth) {
     toggleNested(childContainer, 0);
   });
 
-  // Row click — select element (not toggle)
+  // Row click - select element (not toggle)
   row.addEventListener('click', function(e) {
     // Don't select when clicking toggle arrow, badge, action buttons, or peek
     if (e.target.closest('.tree-toggle') || e.target.closest('.tree-badge') || e.target.closest('.tree-action') || e.target.closest('.tree-peek')) return;
@@ -351,7 +351,7 @@ function showDetail(node) {
 }
 
 // ===================================================================
-// MutationObserver — watch target document for live DOM changes
+// MutationObserver - watch target document for live DOM changes
 // ===================================================================
 function startObserver() {
   if (!targetDoc || observer) return;
@@ -394,7 +394,7 @@ function startObserver() {
         }
     }
 
-    if (!dominated) return; // All mutations were from devtools highlight — skip rebuild
+    if (!dominated) return; // All mutations were from devtools highlight - skip rebuild
 
     // Debounce tree rebuild
     clearTimeout(startObserver._timer);

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

@@ -9,7 +9,7 @@ function updateStats() {
   document.getElementById('morph-count').textContent = morphCount + ' renders';
   document.getElementById('req-count').textContent = requests.length + ' requests';
 
-  // Route stat — show current path
+  // Route stat - show current path
   try {
     var router = targetWin && targetWin.$ && targetWin.$.getRouter();
     var routeStat = document.getElementById('route-stat');

package/cli/commands/dev/devtools/styles.css

@@ -20,7 +20,7 @@ button{font:inherit;cursor:pointer;border:none;background:none;color:inherit}
 .divider:hover{background:var(--accent)}
 
 /* Divider toolbar */
-/* split-h: divider is a tall 4px column — toolbar sits to its LEFT, overlaying the browser */
+/* split-h: divider is a tall 4px column - toolbar sits to its LEFT, overlaying the browser */
 .divider-toolbar{position:absolute;display:flex;flex-direction:column;align-items:center;gap:2px;
 padding:4px 2px;background:var(--bg2);border:1px solid var(--border);border-radius:6px;
 z-index:11;top:12px;right:100%;margin-right:2px;cursor:grab}
@@ -36,7 +36,7 @@ border:1px solid var(--border);border-radius:4px;font-size:11px;color:var(--acce
 max-width:0;overflow:hidden;opacity:0;transition:max-width .25s ease,opacity .2s ease,padding .2s ease;
 padding:0;pointer-events:none;line-height:22px;text-overflow:ellipsis}
 .route-label.open{max-width:50vw;opacity:1;padding:2px 8px;pointer-events:auto}
-/* split-v: divider is a wide 4px row — toolbar sits ABOVE it as a horizontal bar */
+/* split-v: divider is a wide 4px row - toolbar sits ABOVE it as a horizontal bar */
 #root.split-v .divider-toolbar{flex-direction:row;gap:4px;padding:2px 4px;
 top:auto;right:auto;bottom:100%;left:12px;margin-right:0;margin-bottom:2px}
 #root.split-v .divider-sep{width:1px;height:14px;margin:0 1px}

package/cli/commands/dev/index.js

@@ -1,5 +1,5 @@
 /**
- * cli/commands/dev/index.js — Dev server orchestrator
+ * 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,
@@ -44,7 +44,7 @@ function resolveRoot(htmlEntry) {
 }
 
 // ---------------------------------------------------------------------------
-// devServer — main entry point (called from cli/index.js)
+// devServer - main entry point (called from cli/index.js)
 // ---------------------------------------------------------------------------
 
 async function devServer() {