zero-query 1.0.2 → 1.0.5

package/README.md

@@ -29,9 +29,9 @@
 | **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 (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 |
+| **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, `renderShell()` metadata injection hardening (script-tag breakout prevention, ReDoS-safe OG keys, safe `.replace()` patterns) |
 | **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 |
+| **SSR** | Server-side rendering to HTML strings in Node.js - `createSSRApp()`, `renderToString()`, `renderPage()` with SEO/Open Graph support, `renderShell()` for injecting SSR into custom HTML shells, `renderBatch()` for parallel rendering, fragment mode, hydration markers, graceful error handling, `escapeHtml()` utility |
 
 ---
 
@@ -43,7 +43,7 @@ The fastest way to develop with zQuery is via the built-in **CLI dev server** wi
 
 ```bash
 # Install (per-project or globally)
-npm install zero-query --save-dev   # or: npm install zero-query -g
+npm install zero-query   # or: npm install zero-query -g
 ```
 
 Scaffold a new project and start the server:

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

@@ -35,7 +35,7 @@ const router = $.router({
 });
 
 // Update document.title on client-side navigations
-router.onChange(({ component }) => {
-  const title = routeTitles[component];
+router.onChange(({ route }) => {
+  const title = routeTitles[route.component];
   if (title) document.title = title;
 });

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

@@ -34,6 +34,7 @@ export const blogPost = {
     if (ssrData && ssrData.component === 'blog-post' && ssrData.params.slug === slug) {
       this.state.post = ssrData.props.post;
       this.state.loaded = true;
+      if (ssrData.meta && ssrData.meta.title) document.title = ssrData.meta.title;
       window.__SSR_DATA__ = null;
       return;
     }
@@ -44,6 +45,13 @@ export const blogPost = {
       this.state.post = await res.json();
     }
     this.state.loaded = true;
+
+    // Update page title for client-side navigations
+    if (this.state.post) {
+      document.title = `${this.state.post.title} — {{NAME}}`;
+    } else {
+      document.title = 'Post Not Found — {{NAME}}';
+    }
   },
 
   render() {

package/cli/scaffold/ssr/server/index.js

@@ -12,7 +12,7 @@ import { createServer } from 'node:http';
 import { readFile } from 'node:fs/promises';
 import { join, extname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { createSSRApp } from 'zero-query/ssr';
+import { createSSRApp, matchRoute } from 'zero-query/ssr';
 
 // Shared component definitions - same ones the client registers
 import { homePage }  from '../app/components/home.js';
@@ -38,29 +38,6 @@ app.component('blog-list',  blogList);
 app.component('blog-post',  blogPost);
 app.component('not-found',  notFound);
 
-// --- Route matching ---------------------------------------------------------
-
-/**
- * Match a pathname to a route definition. Supports :param segments.
- * Returns { component, params } or the not-found fallback.
- */
-function matchRoute(pathname) {
-  for (const route of routes) {
-    const paramNames = [];
-    const pattern = route.path.replace(/:(\w+)/g, (_, name) => {
-      paramNames.push(name);
-      return '([^/]+)';
-    });
-    const match = new RegExp(`^${pattern}$`).exec(pathname);
-    if (match) {
-      const params = {};
-      paramNames.forEach((name, i) => { params[name] = match[i + 1]; });
-      return { component: route.component, params };
-    }
-  }
-  return { component: 'not-found', params: {} };
-}
-
 // --- Server-side data fetching ----------------------------------------------
 
 /**
@@ -141,7 +118,7 @@ function getMetaForRoute(component, params, props) {
 
 // Read the index.html shell once at startup — it already has z-link nav,
 // client scripts (zquery.min.js + app/app.js), and the <z-outlet> tag.
-// On each request we just inject the SSR body into <z-outlet>.
+// On each request we render the matched component into the shell.
 let shellCache = null;
 async function getShell() {
   if (!shellCache) shellCache = await readFile(join(ROOT, 'index.html'), 'utf-8');
@@ -149,45 +126,22 @@ async function getShell() {
 }
 
 async function render(pathname) {
-  const { component, params } = matchRoute(pathname);
+  const { component, params } = matchRoute(routes, pathname);
   const props = getPropsForRoute(component, params);
   const meta = getMetaForRoute(component, params, props);
 
-  // SSR render — pass server-fetched data as props to the component
-  const body = await app.renderToString(component, props);
-  const shell = await getShell();
-
-  // Inject SSR content into <z-outlet …>
-  let html = shell.replace(/(<z-outlet[^>]*>)(<\/z-outlet>)?/, `$1${body}</z-outlet>`);
-
-  // Inject page-specific <title> and meta tags for SEO / social sharing
-  html = html.replace(/<title>[^<]*<\/title>/, `<title>${meta.title}</title>`);
-  html = html.replace(
-    /<meta name="description" content="[^"]*">/,
-    `<meta name="description" content="${meta.description}">`
-  );
-  html = html.replace(
-    /<meta property="og:title" content="[^"]*">/,
-    `<meta property="og:title" content="${meta.title}">`
-  );
-  html = html.replace(
-    /<meta property="og:description" content="[^"]*">/,
-    `<meta property="og:description" content="${meta.description}">`
-  );
-  html = html.replace(
-    /<meta property="og:type" content="[^"]*">/,
-    `<meta property="og:type" content="${meta.ogType}">`
-  );
-
-  // Embed server data so the client can hydrate without re-fetching.
-  // Also include meta so client can update document.title on navigation.
-  const ssrData = JSON.stringify({ component, params, props, meta });
-  html = html.replace(
-    '</head>',
-    `<script>window.__SSR_DATA__=${ssrData};</script>\n</head>`
-  );
-
-  return html;
+  return app.renderShell(await getShell(), {
+    component,
+    props,
+    title: meta.title,
+    description: meta.description,
+    og: {
+      title: meta.title,
+      description: meta.description,
+      type: meta.ogType,
+    },
+    ssrData: { component, params, props, meta },
+  });
 }
 
 // --- Static files -----------------------------------------------------------

package/dist/zquery.js

@@ -1,5 +1,5 @@
 /**
- * zQuery (zeroQuery) v1.0.2
+ * zQuery (zeroQuery) v1.0.5
  * Lightweight Frontend Library
  * https://github.com/tonywied17/zero-query
  * (c) 2026 Anthony Wiedman - MIT License
@@ -4470,24 +4470,15 @@ class Router {
 
   add(route) {
     // Compile path pattern into regex
-    const keys = [];
-    const pattern = route.path
-      .replace(/:(\w+)/g, (_, key) => { keys.push(key); return '([^/]+)'; })
-      .replace(/\*/g, '(.*)');
-    const regex = new RegExp(`^${pattern}$`);
-
+    const { regex, keys } = compilePath(route.path);
     this._routes.push({ ...route, _regex: regex, _keys: keys });
 
     // Per-route fallback: register an alias path for the same component.
     // e.g. { path: '/docs/:section', fallback: '/docs', component: 'docs-page' }
     // When matched via fallback, missing params are undefined.
     if (route.fallback) {
-      const fbKeys = [];
-      const fbPattern = route.fallback
-        .replace(/:(\w+)/g, (_, key) => { fbKeys.push(key); return '([^/]+)'; })
-        .replace(/\*/g, '(.*)');
-      const fbRegex = new RegExp(`^${fbPattern}$`);
-      this._routes.push({ ...route, path: route.fallback, _regex: fbRegex, _keys: fbKeys });
+      const fb = compilePath(route.fallback);
+      this._routes.push({ ...route, path: route.fallback, _regex: fb.regex, _keys: fb.keys });
     }
 
     return this;
@@ -4984,6 +4975,64 @@ class Router {
 }
 
 
+// ---------------------------------------------------------------------------
+// Path compilation (shared by Router.add and matchRoute)
+// ---------------------------------------------------------------------------
+
+/**
+ * Compile a route path pattern into a RegExp and param key list.
+ * Supports `:param` segments and `*` wildcard.
+ * @param {string} path - e.g. '/user/:id' or '/files/*'
+ * @returns {{ regex: RegExp, keys: string[] }}
+ */
+function compilePath(path) {
+  const keys = [];
+  const pattern = path
+    .replace(/:(\w+)/g, (_, key) => { keys.push(key); return '([^/]+)'; })
+    .replace(/\*/g, '(.*)');
+  return { regex: new RegExp(`^${pattern}$`), keys };
+}
+
+// ---------------------------------------------------------------------------
+// Standalone route matcher (DOM-free — usable on server and client)
+// ---------------------------------------------------------------------------
+
+/**
+ * Match a pathname against an array of route definitions.
+ * Returns `{ component, params }`.  If no route matches, falls back to the
+ * `fallback` component name (default `'not-found'`).
+ *
+ * This is the same matching logic the client-side router uses internally,
+ * extracted so SSR servers can resolve URLs without the DOM.
+ *
+ * @param {Array<{ path: string, component: string, fallback?: string }>} routes
+ * @param {string} pathname - URL path to match, e.g. '/blog/my-post'
+ * @param {string} [fallback='not-found'] - Component name when nothing matches
+ * @returns {{ component: string, params: Record<string, string> }}
+ */
+function matchRoute(routes, pathname, fallback = 'not-found') {
+  for (const route of routes) {
+    const { regex, keys } = compilePath(route.path);
+    const m = pathname.match(regex);
+    if (m) {
+      const params = {};
+      keys.forEach((key, i) => { params[key] = m[i + 1]; });
+      return { component: route.component, params };
+    }
+    // Per-route fallback alias (same as Router.add)
+    if (route.fallback) {
+      const fb = compilePath(route.fallback);
+      const fbm = pathname.match(fb.regex);
+      if (fbm) {
+        const params = {};
+        fb.keys.forEach((key, i) => { params[key] = fbm[i + 1]; });
+        return { component: route.component, params };
+      }
+    }
+  }
+  return { component: fallback, params: {} };
+}
+
 // ---------------------------------------------------------------------------
 // Factory
 // ---------------------------------------------------------------------------
@@ -6139,8 +6188,9 @@ $.morphElement = morphElement;
 $.safeEval    = safeEval;
 
 // --- Router ----------------------------------------------------------------
-$.router    = createRouter;
-$.getRouter = getRouter;
+$.router     = createRouter;
+$.getRouter  = getRouter;
+$.matchRoute = matchRoute;
 
 // --- Store -----------------------------------------------------------------
 $.store    = createStore;
@@ -6204,9 +6254,9 @@ $.validate       = validate;
 $.formatError    = formatError;
 
 // --- Meta ------------------------------------------------------------------
-$.version   = '1.0.2';
+$.version   = '1.0.5';
 $.libSize   = '~107 KB';
-$.unitTests = {"passed":1906,"failed":0,"total":1906,"suites":521,"duration":3744,"ok":true};
+$.unitTests = {"passed":1931,"failed":0,"total":1931,"suites":523,"duration":3815,"ok":true};
 $.meta      = {};              // populated at build time by CLI bundler
 
 $.noConflict = () => {