zero-query 1.0.0 → 1.0.2

package/README.md

@@ -21,7 +21,7 @@
 
 | 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 |
+| **Components** | Reactive state, template literals, `@event` delegation (key filters for any key via `KeyboardEvent.key`, system keys, `.outside`, timing, behavior modifiers, 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 |
@@ -97,7 +97,7 @@ npx zquery build
     <a z-link="/">Home</a>
     <a z-link="/about">About</a>
   </nav>
-  <div id="app"></div>
+  <z-outlet></z-outlet>
 </body>
 </html>
 ```
@@ -108,7 +108,7 @@ npx zquery build
 // app/app.js
 import './components/home.js';
 import './components/about.js';
-import './components/contacts/contacts.js';
+import './components/not-found.js';
 import { routes } from './routes.js';
 
 $.router({ routes, fallback: 'not-found' });
@@ -116,6 +116,8 @@ $.router({ routes, fallback: 'not-found' });
 
 ### Define a Component
 
+One component per file — each self-registers via `$.component()` when imported:
+
 ```js
 // app/components/home.js
 $.component('home-page', {
@@ -131,6 +133,24 @@ $.component('home-page', {
 });
 ```
 
+The router's `fallback` component handles unmatched routes — same pattern. Use `$.getRouter().current?.path` to show the requested URL:
+
+```js
+// app/components/not-found.js
+$.component('not-found', {
+  render() {
+    const router = $.getRouter();
+    return `
+      <div class="card">
+        <h2>404</h2>
+        <p>The page <code>${$.escapeHtml(router.current?.path || '')}</code> was not found.</p>
+        <a z-link="/">Go Home</a>
+      </div>
+    `;
+  }
+});
+```
+
 That's it - a fully working SPA with the dev server's live-reload.
 
 ---
@@ -192,8 +212,9 @@ Use `--ssr` for a project with server-side rendering:
 
 ```
 my-app/                          ← SSR scaffold (npx zquery create my-app --ssr)
-  index.html                     ← client HTML shell
+  index.html                     ← client HTML shell (meta tags, z-link nav)
   global.css
+  package.json
   app/
     app.js                       ← client entry - registers shared components
     routes.js                    ← shared route definitions
@@ -201,12 +222,17 @@ my-app/                          ← SSR scaffold (npx zquery create my-app --ss
       home.js                    ← shared component (SSR + client)
       about.js
       not-found.js
+      blog/                      ← folder component - param routing
+        index.js                 ← blog list (/blog)
+        post.js                  ← blog detail (/blog/:slug)
   server/
-    index.js                     ← SSR HTTP server
+    index.js                     ← SSR HTTP server with JSON API
+    data/
+      posts.js                   ← sample blog data
   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.
+Components in `app/components/` export plain definition objects - the client registers them with `$.component()`, the server with `app.component()`. The scaffold includes a blog with param-based routing (`/blog/:slug`), per-route SEO metadata, JSON API endpoints (`/api/posts`), and `window.__SSR_DATA__` hydration. 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.
@@ -290,7 +316,22 @@ 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/`): add `<base href="/my-app/">` to your `<head>` — the router auto-detects it:
+
+```html
+<head>
+  <base href="/my-app/">
+  <meta charset="UTF-8">
+  <title>My App</title>
+  ...
+</head>
+```
+
+Or pass `base` directly in JavaScript:
+
+```js
+$.router({ base: '/my-app', routes });
+```
 
 ---
 

package/cli/commands/bundle.js

@@ -172,8 +172,10 @@ function minifyCSS(css) {
   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 spaces around { } ; ,  (but NOT : — pseudo-selectors like :not() need the preceding space)
+  css = css.replace(/\s*([{};,])\s*/g, '$1');
+  // Remove space after : (safe in both selectors and declarations)
+  css = css.replace(/:\s+/g, ':');
   // Remove trailing semicolons before }
   css = css.replace(/;}/g, '}');
   return css.trim();
@@ -357,7 +359,8 @@ function _collapseTemplateCSS(tpl) {
     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(/\s*([{};,])\s*/g, '$1');
+    t = t.replace(/:\s+/g, ':');
     t = t.replace(/;}/g, '}');
     segments[s].val = t;
   }

package/cli/commands/create.js

@@ -89,6 +89,13 @@ function createProject(args) {
       process.exit(1);
     }
 
+    // Copy zquery.min.js into the project root so the SSR server can serve it
+    const zqMin = path.join(target, 'node_modules', 'zero-query', 'dist', 'zquery.min.js');
+    if (fs.existsSync(zqMin)) {
+      fs.copyFileSync(zqMin, path.join(target, 'zquery.min.js'));
+      console.log(`  ✓ zquery.min.js`);
+    }
+
     console.log(`\n  Starting SSR server...\n`);
     const child = spawn('node', ['server/index.js'], { cwd: target, stdio: 'inherit' });
 

package/cli/help.js

@@ -12,7 +12,8 @@ function showHelp() {
       --minimal, -m            Use the minimal template (home, counter, about)
                                instead of the full-featured default scaffold
       --ssr, -s                Use the SSR template - includes server/index.js
-                               SSR HTTP server with shared component definitions
+                               SSR HTTP server with shared component definitions,
+                               blog with param routing, JSON API, and SEO metadata
 
     dev [root]                 Start a dev server with live-reload
       --port, -p <number>     Port number (default: 3100)

package/cli/index.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 /**
  * zQuery CLI - entry point

package/cli/scaffold/default/app/app.js

@@ -42,9 +42,6 @@ router.afterEach((to) => {
 
 // Highlight the active nav link on every route change
 router.onChange((to) => {
-  $.all('.nav-link').removeClass('active');
-  $(`.nav-link[z-link="${to.path}"]`).addClass('active');
-
   // Close mobile menu on navigate
   closeMobileMenu();
 });
@@ -161,9 +158,9 @@ $.ready(() => {
     if (current === 'system') applyTheme('system');
   });
 
-  // Set active link on initial load
-  const current = window.location.pathname;
-  $.all(`.nav-link[z-link="${current}"]`).addClass('active');
+  // Highlight the active link on initial load is handled by z-active-route
+
+  console.log('⚡ {{NAME}} - powered by zQuery v' + $.version);
 
   // Stats panel: restore open/closed from $.storage (defaults to open)
   const statsOpen = $.storage.get('statsOpen');

package/cli/scaffold/default/global.css

@@ -24,6 +24,8 @@
   --radius:      8px;
   --radius-lg:   12px;
   --sidebar-w:   240px;
+  --sidebar-bg:  var(--bg-surface);
+  --sidebar-border: var(--border);
   --topbar-h:    56px;
   --font:        'Inter', system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
   --ease-out:    cubic-bezier(0.22, 1, 0.36, 1);
@@ -41,6 +43,8 @@
   --accent-hover:#0550ae;
   --accent-soft: rgba(9,105,218,0.08);
   --accent-glow: rgba(9,105,218,0.04);
+  --sidebar-bg:  #eef2f9;
+  --sidebar-border: rgba(9, 105, 218, 0.12);
   --success:     #1a7f37;
   --danger:      #cf222e;
   --info:        #0969da;
@@ -73,8 +77,8 @@ code { background: var(--bg-hover); padding: 2px 6px; border-radius: 4px; font-s
   position: fixed;
   top: 0; left: 0; bottom: 0;
   width: var(--sidebar-w);
-  background: var(--bg-surface);
-  border-right: 1px solid var(--border);
+  background: var(--sidebar-bg);
+  border-right: 1px solid var(--sidebar-border);
   display: flex;
   flex-direction: column;
   z-index: 100;
@@ -134,6 +138,11 @@ code { background: var(--bg-hover); padding: 2px 6px; border-radius: 4px; font-s
   font-size: 0.8rem;
 }
 
+[data-theme="light"] .sidebar {
+  background: var(--sidebar-bg);
+  border-right-color: var(--sidebar-border);
+}
+
 /* -- Sidebar Contacts (live status) -- */
 .sidebar-contacts {
   border-top: 1px solid var(--border);
@@ -350,7 +359,7 @@ code { background: var(--bg-hover); padding: 2px 6px; border-radius: 4px; font-s
   margin-left: auto;
   margin-right: auto;
   padding: 2.5rem 3rem 2.5rem calc(var(--sidebar-w) + 3rem);
-  max-width: calc(1010px + var(--sidebar-w));
+  max-width: calc(1200px + var(--sidebar-w));
   min-height: 100vh;
 }
 
@@ -504,7 +513,7 @@ code { background: var(--bg-hover); padding: 2px 6px; border-radius: 4px; font-s
 @keyframes toast-out { from { opacity: 1; transform: translateY(0) scale(1); } to { opacity: 0; transform: translateY(-10px) scale(0.95); } }
 
 /* -- Route Transition -- */
-z-outlet { animation: fade-in 0.25s var(--ease-out); }
+z-outlet { display: block; animation: fade-in 0.25s var(--ease-out); }
 @keyframes fade-in { from { opacity: 0; transform: translateY(6px); } to { opacity: 1; transform: translateY(0); } }
 
 /* -- Responsive: Mobile -- */

package/cli/scaffold/default/index.html

@@ -18,28 +18,28 @@
       <span class="brand"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="var(--accent)" style="width:18px;height:18px;vertical-align:-3px;margin-right:0.2rem;"><path fill-rule="evenodd" d="M14.615 1.595a.75.75 0 0 1 .359.852L12.982 9.75h7.268a.75.75 0 0 1 .548 1.262l-10.5 11.25a.75.75 0 0 1-1.272-.71l1.992-7.302H3.75a.75.75 0 0 1-.548-1.262l10.5-11.25a.75.75 0 0 1 .913-.143Z" clip-rule="evenodd"/></svg> {{NAME}}</span>
     </div>
     <nav class="sidebar-nav">
-      <a z-link="/" class="nav-link">
+      <a z-link="/" class="nav-link" z-active-route="/" z-active-exact>
         <span class="nav-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" d="m2.25 12 8.954-8.955a1.126 1.126 0 0 1 1.591 0L21.75 12M4.5 9.75v10.125c0 .621.504 1.125 1.125 1.125H9.75v-4.875c0-.621.504-1.125 1.125-1.125h2.25c.621 0 1.125.504 1.125 1.125V21h4.125c.621 0 1.125-.504 1.125-1.125V9.75M8.25 21h8.25"/></svg></span> Home
       </a>
-      <a z-link="/counter" class="nav-link">
+      <a z-link="/counter" class="nav-link" z-active-route="/counter">
         <span class="nav-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" d="M5.25 8.25h15m-16.5 7.5h15m-1.8-13.5-3.9 19.5m-2.1-19.5-3.9 19.5"/></svg></span> Counter
       </a>
-      <a z-link="/todos" class="nav-link">
+      <a z-link="/todos" class="nav-link" z-active-route="/todos">
         <span class="nav-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" d="M9 12.75 11.25 15 15 9.75M21 12a9 9 0 1 1-18 0 9 9 0 0 1 18 0Z"/></svg></span> Todos
       </a>
-      <a z-link="/contacts" class="nav-link">
+      <a z-link="/contacts" class="nav-link" z-active-route="/contacts">
         <span class="nav-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" d="M15 9h3.75M15 12h3.75M15 15h3.75M4.5 19.5h15a2.25 2.25 0 0 0 2.25-2.25V6.75A2.25 2.25 0 0 0 19.5 4.5h-15a2.25 2.25 0 0 0-2.25 2.25v10.5A2.25 2.25 0 0 0 4.5 19.5Zm6-10.125a1.875 1.875 0 1 1-3.75 0 1.875 1.875 0 0 1 3.75 0Zm1.294 6.336a6.721 6.721 0 0 1-3.17.789 6.721 6.721 0 0 1-3.168-.789 3.376 3.376 0 0 1 6.338 0Z"/></svg></span> Contacts
       </a>
-      <a z-link="/api" class="nav-link">
+      <a z-link="/api" class="nav-link" z-active-route="/api">
         <span class="nav-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" d="M12 21a9.004 9.004 0 0 0 8.716-6.747M12 21a9.004 9.004 0 0 1-8.716-6.747M12 21c2.485 0 4.5-4.03 4.5-9S14.485 3 12 3m0 18c-2.485 0-4.5-4.03-4.5-9S9.515 3 12 3m0 0a8.997 8.997 0 0 1 7.843 4.582M12 3a8.997 8.997 0 0 0-7.843 4.582m15.686 0A11.953 11.953 0 0 1 12 10.5c-2.998 0-5.74-1.1-7.843-2.918m15.686 0A8.959 8.959 0 0 1 21 12c0 .778-.099 1.533-.284 2.253m0 0A17.919 17.919 0 0 1 12 16.5c-3.162 0-6.133-.815-8.716-2.247m0 0A9.015 9.015 0 0 1 3 12c0-1.605.42-3.113 1.157-4.418"/></svg></span> API Demo
       </a>
-      <a z-link="/playground" class="nav-link">
+      <a z-link="/playground" class="nav-link" z-active-route="/playground">
         <span class="nav-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" d="m21 7.5-9-5.25L3 7.5m18 0-9 5.25m9-5.25v9l-9 5.25M3 7.5l9 5.25M3 7.5v9l9 5.25m0-9v9"/></svg></span> Playground
       </a>
-      <a z-link="/toolkit" class="nav-link">
+      <a z-link="/toolkit" class="nav-link" z-active-route="/toolkit">
         <span class="nav-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" d="M21.75 6.75a4.5 4.5 0 0 1-4.884 4.484c-1.076-.091-2.264.071-2.95.904l-7.152 8.684a2.548 2.548 0 1 1-3.586-3.586l8.684-7.152c.833-.686.995-1.874.904-2.95a4.5 4.5 0 0 1 6.336-4.486l-3.276 3.276a3.004 3.004 0 0 0 2.25 2.25l3.276-3.276c.256.565.398 1.192.398 1.852Z"/></svg></span> Toolkit
       </a>
-      <a z-link="/about" class="nav-link">
+      <a z-link="/about" class="nav-link" z-active-route="/about">
         <span class="nav-icon"><svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" d="M12 18v-5.25m0 0a6.01 6.01 0 0 0 1.5-.189m-1.5.189a6.01 6.01 0 0 1-1.5-.189m3.75 7.478a12.06 12.06 0 0 1-4.5 0m3.75 2.383a14.406 14.406 0 0 1-3 0M14.25 18v-.192c0-.983.658-1.823 1.508-2.316a7.5 7.5 0 1 0-7.517 0c.85.493 1.509 1.333 1.509 2.316V18"/></svg></span> About
       </a>
     </nav>

package/cli/scaffold/minimal/app/app.js

@@ -25,12 +25,8 @@ const router = $.router({
   mode: 'history'
 });
 
-// Highlight the active nav link on every route change
-router.onChange((to) => {
-  $.all('.nav-link').removeClass('active');
-  $(`.nav-link[z-link="${to.path}"]`).addClass('active');
-
-  // Close mobile menu on navigate
+// Close mobile menu on route change
+router.onChange(() => {
   closeMobileMenu();
 });
 
@@ -70,9 +66,7 @@ $.ready(() => {
     if (current === 'system') applyTheme('system');
   });
 
-  // Highlight the active link on initial load
-  const current = window.location.pathname;
-  $.all(`.nav-link[z-link="${current}"]`).addClass('active');
+  // Active nav highlighting is handled by z-active-route in the HTML
 
   console.log('⚡ {{NAME}} - powered by zQuery v' + $.version);
 });

package/cli/scaffold/minimal/global.css

@@ -22,6 +22,8 @@
   --radius:      8px;
   --radius-lg:   12px;
   --sidebar-w:   220px;
+  --sidebar-bg:  var(--bg-surface);
+  --sidebar-border: var(--border);
   --topbar-h:    56px;
   --font:        'Inter', system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
   --ease-out:    cubic-bezier(0.22, 1, 0.36, 1);
@@ -39,6 +41,8 @@
   --accent-hover:#0550ae;
   --accent-soft: rgba(9,105,218,0.08);
   --accent-glow: rgba(9,105,218,0.04);
+  --sidebar-bg:  #eef2f9;
+  --sidebar-border: rgba(9, 105, 218, 0.12);
   --success:     #1a7f37;
   --danger:      #cf222e;
 }
@@ -64,8 +68,8 @@ code { background: var(--bg-hover); padding: 2px 6px; border-radius: 4px; font-s
   position: fixed;
   top: 0; left: 0; bottom: 0;
   width: var(--sidebar-w);
-  background: var(--bg-surface);
-  border-right: 1px solid var(--border);
+  background: var(--sidebar-bg);
+  border-right: 1px solid var(--sidebar-border);
   display: flex;
   flex-direction: column;
   z-index: 100;
@@ -118,6 +122,11 @@ code { background: var(--bg-hover); padding: 2px 6px; border-radius: 4px; font-s
   font-size: 0.8rem;
 }
 
+[data-theme="light"] .sidebar {
+  background: var(--sidebar-bg);
+  border-right-color: var(--sidebar-border);
+}
+
 /* -- Mobile Top Bar -- */
 .topbar {
   display: none;
@@ -181,7 +190,7 @@ code { background: var(--bg-hover); padding: 2px 6px; border-radius: 4px; font-s
   margin-left: auto;
   margin-right: auto;
   padding: 2.5rem 3rem 2.5rem calc(var(--sidebar-w) + 3rem);
-  max-width: calc(1010px + var(--sidebar-w));
+  max-width: calc(1200px + var(--sidebar-w));
   min-height: 100vh;
 }
 
@@ -259,7 +268,7 @@ code { background: var(--bg-hover); padding: 2px 6px; border-radius: 4px; font-s
 .muted { color: var(--text-muted); }
 
 /* -- Route Transition -- */
-z-outlet { animation: fade-in 0.25s var(--ease-out); }
+z-outlet { display: block; animation: fade-in 0.25s var(--ease-out); }
 @keyframes fade-in { from { opacity: 0; transform: translateY(6px); } to { opacity: 1; transform: translateY(0); } }
 
 /* -- Responsive: Mobile -- */

package/cli/scaffold/minimal/index.html

@@ -17,9 +17,9 @@
       <span class="brand">⚡ {{NAME}}</span>
     </div>
     <nav class="sidebar-nav">
-      <a z-link="/" class="nav-link">Home</a>
-      <a z-link="/counter" class="nav-link">Counter</a>
-      <a z-link="/about" class="nav-link">About</a>
+      <a z-link="/" class="nav-link" z-active-route="/" z-active-exact>Home</a>
+      <a z-link="/counter" class="nav-link" z-active-route="/counter">Counter</a>
+      <a z-link="/about" class="nav-link" z-active-route="/about">About</a>
     </nav>
     <div class="sidebar-footer">
       <small>zQuery <span id="nav-version"></span></small>

package/cli/scaffold/ssr/app/app.js

@@ -2,17 +2,31 @@
 //
 // Imports shared component definitions and registers them with zQuery.
 // The SSR server imports the same definitions via createSSRApp().
+// Server-fetched data is embedded in window.__SSR_DATA__ for hydration.
 
 import { homePage }  from './components/home.js';
 import { aboutPage } from './components/about.js';
+import { blogList }  from './components/blog/index.js';
+import { blogPost }  from './components/blog/post.js';
 import { notFound }  from './components/not-found.js';
 import { routes }    from './routes.js';
 
 // Register shared component definitions on the client
 $.component('home-page',  homePage);
 $.component('about-page', aboutPage);
+$.component('blog-list',  blogList);
+$.component('blog-post',  blogPost);
 $.component('not-found',  notFound);
 
+// Route → page title mapping (mirrors server getMetaForRoute)
+const routeTitles = {
+  'home-page':  '{{NAME}} — Home',
+  'blog-list':  'Blog — {{NAME}}',
+  'blog-post':  null, // dynamic — set by component
+  'about-page': 'About — {{NAME}}',
+  'not-found':  'Page Not Found — {{NAME}}',
+};
+
 // Client-side router
 const router = $.router({
   routes,
@@ -20,10 +34,8 @@ const router = $.router({
   mode: 'history'
 });
 
-// Active nav highlighting
-router.onChange((to) => {
-  $.qsa('.nav-link').forEach(link => {
-    const href = link.getAttribute('z-link') || link.getAttribute('href');
-    link.classList.toggle('active', href === to.path);
-  });
+// Update document.title on client-side navigations
+router.onChange(({ component }) => {
+  const title = routeTitles[component];
+  if (title) document.title = title;
 });

package/cli/scaffold/ssr/app/components/about.js

@@ -1,27 +1,54 @@
 // about.js - About page component
 
 export const aboutPage = {
-  state: () => ({
-    features: [
-      'createSSRApp() - isolated component registry for Node.js',
-      'renderToString() - render a component to an HTML string',
-      'renderPage() - full HTML document with meta tags',
-      'renderBatch() - render multiple components in one call',
-      'Hydration markers (data-zq-ssr) for client takeover',
-      'SEO: description, canonical URL, Open Graph tags',
-    ]
-  }),
-
   render() {
-    const list = this.state.features.map(f => `<li>${f}</li>`).join('');
     return `
       <div class="page-header">
         <h1>About</h1>
-        <p class="subtitle">SSR capabilities in this scaffold.</p>
+        <p class="subtitle">This app is powered by zQuery — a zero-dependency frontend micro-library.</p>
+      </div>
+
+      <div class="card">
+        <h3>What is zQuery?</h3>
+        <p style="line-height:1.7;">
+          zQuery is a lightweight, zero-dependency JavaScript library for building
+          reactive web applications. It provides components, routing, state management,
+          server-side rendering, and more — all in a single, tiny package with no
+          build step required.
+        </p>
       </div>
+
+      <div class="card">
+        <h3>Core Features</h3>
+        <ul style="padding-left:1.2rem; line-height:2;">
+          <li><strong>Reactive state</strong> — fine-grained reactivity with <code>$.reactive()</code></li>
+          <li><strong>Components</strong> — <code>$.component()</code> with state, lifecycle hooks, and computed properties</li>
+          <li><strong>Routing</strong> — <code>$.router()</code> with history mode, params, guards, and <code>z-link</code> navigation</li>
+          <li><strong>Store</strong> — centralized state via <code>$.store()</code></li>
+          <li><strong>SSR</strong> — <code>createSSRApp()</code>, <code>renderToString()</code>, hydration markers</li>
+          <li><strong>HTTP</strong> — <code>$.http</code> with interceptors, timeout, and parallel requests</li>
+          <li><strong>Zero dependencies</strong> — nothing to install, audit, or keep up-to-date</li>
+        </ul>
+      </div>
+
+      <div class="card">
+        <h3>This Scaffold</h3>
+        <p style="line-height:1.7;">
+          You're running the <strong>SSR scaffold</strong> — a production-ready starter
+          with server-side rendering, client hydration, param-based routing, JSON API
+          endpoints, and per-route SEO metadata. Edit the components in <code>app/</code>
+          and the server in <code>server/</code> to make it your own.
+        </p>
+      </div>
+
       <div class="card">
-        <h3>SSR API</h3>
-        <ul style="padding-left:1.2rem; line-height:2;">${list}</ul>
+        <h3>Links</h3>
+        <ul style="padding-left:1.2rem; line-height:2.2; list-style:none;">
+          <li>📄 <a href="https://z-query.com" target="_blank" rel="noopener">zQuery Website</a></li>
+          <li>📦 <a href="https://www.npmjs.com/package/zero-query" target="_blank" rel="noopener">npm — zero-query</a></li>
+          <li>🛠️ <a href="https://github.com/tonywied17/zero-query" target="_blank" rel="noopener">GitHub Repository</a></li>
+          <li>📖 <a href="https://z-query.com/docs" target="_blank" rel="noopener">Documentation</a></li>
+        </ul>
       </div>
     `;
   }

package/cli/scaffold/ssr/app/components/blog/index.js

@@ -0,0 +1,65 @@
+// blog/index.js - Blog listing component
+//
+// Renders a grid of blog post cards. Data flow:
+//   SSR:    Server passes { posts } as props → render() reads this.props.posts
+//   Client: init() checks window.__SSR_DATA__ first (hydration), then fetches
+//           from /api/posts for subsequent navigations.
+//
+// Demonstrates:
+//   - Shared component that works on both server and client
+//   - Server data injection via props (SSR) and fetch (client)
+//   - z-link with dynamic URLs for client-side navigation
+//   - Clean SSR-friendly templates (no DOM API in render)
+
+export const blogList = {
+  state: () => ({
+    posts: [],
+    loaded: false,
+  }),
+
+  async init() {
+    // On the server, props.posts is injected by app.renderToString()
+    if (this.props.posts) {
+      this.state.posts = this.props.posts;
+      this.state.loaded = true;
+      return;
+    }
+
+    // On the client, check for SSR-embedded data first (initial page load)
+    const ssrData = typeof window !== 'undefined' && window.__SSR_DATA__;
+    if (ssrData && ssrData.component === 'blog-list') {
+      this.state.posts = ssrData.props.posts;
+      this.state.loaded = true;
+      window.__SSR_DATA__ = null;
+      return;
+    }
+
+    // Client navigation — fetch from server API
+    const res = await fetch('/api/posts');
+    this.state.posts = await res.json();
+    this.state.loaded = true;
+  },
+
+  render() {
+    const posts = this.state.posts;
+
+    const cards = posts.map(post => `
+      <a z-link="/blog/${post.slug}" class="blog-card">
+        <div class="blog-card-header">
+          <span class="badge badge-ssr">${post.tag}</span>
+          <time class="blog-date">${post.date}</time>
+        </div>
+        <h3 class="blog-title">${post.title}</h3>
+        <p class="blog-summary">${post.summary}</p>
+      </a>
+    `).join('');
+
+    return `
+      <div class="page-header">
+        <h1>Blog</h1>
+        <p class="subtitle">Server-rendered articles — fast first paint, fully crawlable.</p>
+      </div>
+      <div class="blog-grid">${cards}</div>
+    `;
+  }
+};

package/cli/scaffold/ssr/app/components/blog/post.js

@@ -0,0 +1,78 @@
+// blog/post.js - Single blog post detail component
+//
+// Renders the full content of a blog post. Data flow:
+//   SSR:    Server passes { post } as props → init() reads this.props.post
+//   Client: init() checks window.__SSR_DATA__ first, then fetches from
+//           /api/posts/:slug for client-side navigations.
+//
+// Route:  /blog/:slug
+//
+// Demonstrates:
+//   - Param routing with this.props.$params.slug (or this.props.slug)
+//   - Server data injection via props (SSR) and fetch (client)
+//   - z-link for back-navigation without full page reload
+//   - Graceful handling of missing data (404-style fallback)
+
+export const blogPost = {
+  state: () => ({
+    post: null,
+    loaded: false,
+  }),
+
+  async init() {
+    const slug = this.props.slug || (this.props.$params && this.props.$params.slug);
+
+    // On the server, props.post is injected by app.renderToString()
+    if (this.props.post) {
+      this.state.post = this.props.post;
+      this.state.loaded = true;
+      return;
+    }
+
+    // On the client, check for SSR-embedded data first (initial page load)
+    const ssrData = typeof window !== 'undefined' && window.__SSR_DATA__;
+    if (ssrData && ssrData.component === 'blog-post' && ssrData.params.slug === slug) {
+      this.state.post = ssrData.props.post;
+      this.state.loaded = true;
+      window.__SSR_DATA__ = null;
+      return;
+    }
+
+    // Client navigation — fetch from server API
+    const res = await fetch(`/api/posts/${slug}`);
+    if (res.ok) {
+      this.state.post = await res.json();
+    }
+    this.state.loaded = true;
+  },
+
+  render() {
+    const post = this.state.post;
+
+    if (!post) {
+      return `
+        <div class="page-header center">
+          <h1>Post Not Found</h1>
+          <p class="subtitle">The article you're looking for doesn't exist.</p>
+          <p style="margin-top:1rem;">
+            <a z-link="/blog" class="back-link">← Back to Blog</a>
+          </p>
+        </div>
+      `;
+    }
+
+    return `
+      <article class="blog-post">
+        <header class="page-header">
+          <a z-link="/blog" class="back-link">← Back to Blog</a>
+          <h1>${post.title}</h1>
+          <div class="blog-post-meta">
+            <span class="badge badge-ssr">${post.tag}</span>
+            <time class="blog-date">${post.date}</time>
+          </div>
+        </header>
+        <div class="blog-post-body">${post.body}</div>
+      </article>
+    `;
+  }
+};