webspresso 0.0.65 → 0.0.67

package/plugins/orm-cache-admin/admin-component.js

@@ -0,0 +1,146 @@
+/**
+ * Admin SPA page for ORM cache (Mithril string component)
+ * @module plugins/orm-cache-admin/admin-component
+ */
+
+function generateOrmCacheAdminComponent() {
+  return `
+(function() {
+
+function ormCacheApi(method, path, body) {
+  var opts = { method: method, credentials: 'same-origin' };
+  if (body !== undefined) {
+    opts.headers = { 'Content-Type': 'application/json' };
+    opts.body = JSON.stringify(body);
+  }
+  return fetch('/_admin/api/orm-cache' + path, opts).then(function(r) {
+    return r.json().then(function(j) {
+      if (!r.ok) throw new Error(j.error || r.statusText);
+      return j;
+    });
+  });
+}
+
+var OrmCachePage = {
+  oninit: function(vnode) {
+    vnode.state.loading = true;
+    vnode.state.error = null;
+    vnode.state.stats = null;
+    vnode.state.modelName = '';
+    this.refresh(vnode);
+  },
+  refresh: function(vnode) {
+    vnode.state.loading = true;
+    vnode.state.error = null;
+    ormCacheApi('get', '/stats').then(function(s) {
+      vnode.state.stats = s;
+      vnode.state.loading = false;
+      m.redraw();
+    }).catch(function(e) {
+      vnode.state.error = e.message || String(e);
+      vnode.state.loading = false;
+      m.redraw();
+    });
+  },
+  purge: function(vnode) {
+    if (!confirm('Purge entire ORM cache?')) return;
+    ormCacheApi('post', '/purge').then(function() {
+      return this.refresh(vnode);
+    }.bind(this)).catch(function(e) {
+      vnode.state.error = e.message;
+      m.redraw();
+    }.bind(this));
+  },
+  invalidateModel: function(vnode) {
+    var name = (vnode.state.modelName || '').trim();
+    if (!name) return;
+    ormCacheApi('post', '/invalidate', { model: name }).then(function() {
+      vnode.state.modelName = '';
+      return this.refresh(vnode);
+    }.bind(this)).catch(function(e) {
+      vnode.state.error = e.message;
+      m.redraw();
+    }.bind(this));
+  },
+  resetMetrics: function(vnode) {
+    ormCacheApi('post', '/metrics/reset').then(function() {
+      return this.refresh(vnode);
+    }.bind(this)).catch(function(e) {
+      vnode.state.error = e.message;
+      m.redraw();
+    }.bind(this));
+  },
+  view: function(vnode) {
+    var s = vnode.state;
+    var self = this;
+    return m(Layout, [
+      m(Breadcrumb, { items: [{ label: 'ORM Cache', href: '/orm-cache' }] }),
+      m('div.mb-6', [
+        m('h1.text-2xl.font-bold.text-gray-900', 'ORM query cache'),
+        m('p.text-gray-500.text-sm.mt-1', 'Hit/miss metrics and manual invalidation (memory provider)'),
+      ]),
+      s.loading
+        ? m('div.flex.justify-center.py-16', m(Spinner))
+        : s.error
+          ? m('div.bg-red-50.text-red-700.p-4.rounded-lg', s.error)
+          : m('div.space-y-6', [
+              m('div.grid.grid-cols-2.md:grid-cols-4.gap-4', [
+                statBox('Hits', s.stats && s.stats.hits),
+                statBox('Misses', s.stats && s.stats.misses),
+                statBox('Hit rate', formatRate(s.stats && s.stats.hitRate)),
+                statBox('Bypassed', s.stats && s.stats.bypassed),
+              ]),
+              m('div.grid.grid-cols-2.md:grid-cols-4.gap-4', [
+                statBox('Sets', s.stats && s.stats.sets),
+                statBox('Invalidations', s.stats && s.stats.invalidations),
+                statBox('Approx keys', s.stats && s.stats.approxKeys),
+                statBox('Approx tags', s.stats && s.stats.approxTags),
+              ]),
+              m('div.flex.flex-wrap.gap-2', [
+                m('button.px-4.py-2.bg-red-600.text-white.rounded-md.text-sm', {
+                  onclick: function() { self.purge(vnode); },
+                }, 'Purge all'),
+                m('button.px-4.py-2.bg-gray-200.text-gray-800.rounded-md.text-sm', {
+                  onclick: function() { self.resetMetrics(vnode); },
+                }, 'Reset metrics'),
+                m('button.px-4.py-2.bg-blue-600.text-white.rounded-md.text-sm', {
+                  onclick: function() { self.refresh(vnode); },
+                }, 'Refresh'),
+              ]),
+              m('div.bg-white.rounded-lg.shadow.p-4', [
+                m('h3.text-sm.font-semibold.mb-2', 'Invalidate by model'),
+                m('div.flex.gap-2', [
+                  m('input.flex-1.border.rounded.px-3.py-2.text-sm', {
+                    placeholder: 'Model name (e.g. User)',
+                    value: s.modelName,
+                    oninput: function(e) { s.modelName = e.target.value; },
+                  }),
+                  m('button.px-4.py-2.bg-amber-600.text-white.rounded-md.text-sm', {
+                    onclick: function() { self.invalidateModel(vnode); },
+                  }, 'Invalidate'),
+                ]),
+              ]),
+            ]),
+    ]);
+  },
+};
+
+function statBox(label, value) {
+  return m('div.bg-white.rounded-lg.shadow.p-4', [
+    m('p.text-xs.text-gray-500.uppercase', label),
+    m('p.text-xl.font-semibold.text-gray-900', value === undefined || value === null ? '—' : String(value)),
+  ]);
+}
+
+function formatRate(r) {
+  if (r === null || r === undefined || isNaN(r)) return '—';
+  return (r * 100).toFixed(1) + '%';
+}
+
+window.__customPages = window.__customPages || {};
+window.__customPages['orm-cache'] = OrmCachePage;
+})();
+`;
+}
+
+module.exports = { generateOrmCacheAdminComponent };

package/plugins/orm-cache-admin/api-handlers.js

@@ -0,0 +1,78 @@
+/**
+ * Admin API for ORM cache metrics and purge
+ * @module plugins/orm-cache-admin/api-handlers
+ */
+
+/**
+ * @param {object} options
+ * @param {import('../../core/orm/types').DatabaseInstance} options.db
+ */
+function createOrmCacheAdminHandlers({ db }) {
+  function requireCache(res) {
+    if (!db.cache) {
+      res.status(503).json({ error: 'ORM cache is not enabled on this database' });
+      return null;
+    }
+    return db.cache;
+  }
+
+  async function getStats(req, res) {
+    try {
+      const cache = requireCache(res);
+      if (!cache) return;
+      res.json(cache.getMetrics());
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  }
+
+  async function postPurge(req, res) {
+    try {
+      const cache = requireCache(res);
+      if (!cache) return;
+      cache.purge();
+      res.json({ ok: true });
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  }
+
+  async function postInvalidate(req, res) {
+    try {
+      const cache = requireCache(res);
+      if (!cache) return;
+      const body = req.body && typeof req.body === 'object' ? req.body : {};
+      if (Array.isArray(body.tags) && body.tags.length > 0) {
+        cache.invalidateTags(body.tags.map(String));
+        return res.json({ ok: true, mode: 'tags' });
+      }
+      if (typeof body.model === 'string' && body.model.trim()) {
+        cache.invalidateModel(body.model.trim());
+        return res.json({ ok: true, mode: 'model' });
+      }
+      res.status(400).json({ error: 'Provide { model: string } or { tags: string[] }' });
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  }
+
+  async function postResetMetrics(req, res) {
+    try {
+      const cache = requireCache(res);
+      if (!cache) return;
+      cache.resetMetrics();
+      res.json({ ok: true });
+    } catch (e) {
+      res.status(500).json({ error: e.message });
+    }
+  }
+
+  return {
+    getStats,
+    postPurge,
+    postInvalidate,
+    postResetMetrics,
+  };
+}
+
+module.exports = { createOrmCacheAdminHandlers };

package/plugins/orm-cache-admin/index.js

@@ -0,0 +1,72 @@
+/**
+ * ORM Cache Admin — metrics, purge, invalidate (requires admin-panel + db.cache)
+ * @module plugins/orm-cache-admin
+ */
+
+const { createOrmCacheAdminHandlers } = require('./api-handlers');
+const { generateOrmCacheAdminComponent } = require('./admin-component');
+
+/**
+ * @param {object} options
+ * @param {import('../../core/orm/types').DatabaseInstance} options.db - From createDatabase({ cache: true })
+ */
+function ormCacheAdminPlugin(options = {}) {
+  const { db } = options;
+
+  if (!db) {
+    throw new Error('orm-cache-admin plugin requires `db` (database instance from createDatabase)');
+  }
+
+  return {
+    name: 'orm-cache-admin',
+    version: '1.0.0',
+    description: 'Admin UI for ORM query cache metrics and purge',
+    dependencies: { 'admin-panel': '*' },
+
+    register() {},
+
+    onRoutesReady(ctx) {
+      const adminApi = ctx.usePlugin('admin-panel');
+      if (!adminApi) {
+        console.warn('[orm-cache-admin] admin-panel not found, skipping registration');
+        return;
+      }
+
+      if (!db.cache) {
+        console.warn('[orm-cache-admin] db.cache is disabled; enable createDatabase({ cache: true })');
+        return;
+      }
+
+      const handlers = createOrmCacheAdminHandlers({ db });
+
+      adminApi.registerModule({
+        id: 'orm-cache',
+        pages: [{
+          id: 'orm-cache',
+          title: 'ORM Cache',
+          path: '/orm-cache',
+          icon: 'database',
+          component: generateOrmCacheAdminComponent(),
+        }],
+        menu: [{
+          id: 'orm-cache',
+          label: 'ORM Cache',
+          path: '/orm-cache',
+          icon: 'database',
+          order: 15,
+        }],
+        api: {
+          prefix: '/orm-cache',
+          routes: [
+            { method: 'get', path: '/stats', handler: handlers.getStats },
+            { method: 'post', path: '/purge', handler: handlers.postPurge },
+            { method: 'post', path: '/invalidate', handler: handlers.postInvalidate },
+            { method: 'post', path: '/metrics/reset', handler: handlers.postResetMetrics },
+          ],
+        },
+      });
+    },
+  };
+}
+
+module.exports = ormCacheAdminPlugin;

package/src/client-runtime/bootstrap-alpine-swup.js

@@ -0,0 +1,34 @@
+/* global Swup, SwupHeadPlugin, SwupScriptsPlugin, Alpine */
+(function () {
+  if (typeof Swup === 'undefined' || typeof SwupHeadPlugin === 'undefined' || typeof SwupScriptsPlugin === 'undefined' || typeof Alpine === 'undefined') {
+    return;
+  }
+
+  function ignoreVisit(url, ctx) {
+    var el = ctx && ctx.el;
+    if (el && el.closest && el.closest('[data-no-swup]')) return true;
+    try {
+      var u = new URL(url, window.location.origin);
+      var p = u.pathname;
+      if (p.indexOf('/_admin') === 0 || p.indexOf('/_webspresso') === 0) return true;
+    } catch (e) {
+      /* ignore */
+    }
+    return false;
+  }
+
+  var swup = new Swup({
+    containers: ['#swup'],
+    plugins: [new SwupHeadPlugin(), new SwupScriptsPlugin()],
+    ignoreVisit: ignoreVisit,
+  });
+
+  swup.hooks.on('content:replace', function () {
+    var root = document.querySelector('#swup');
+    if (root && typeof Alpine.initTree === 'function') {
+      Alpine.initTree(root);
+    }
+  });
+
+  window.__webspressoSwup = swup;
+})();

package/src/client-runtime/bootstrap-swup.js

@@ -0,0 +1,26 @@
+/* global Swup, SwupHeadPlugin, SwupScriptsPlugin */
+(function () {
+  if (typeof Swup === 'undefined' || typeof SwupHeadPlugin === 'undefined' || typeof SwupScriptsPlugin === 'undefined') {
+    return;
+  }
+
+  function ignoreVisit(url, ctx) {
+    var el = ctx && ctx.el;
+    if (el && el.closest && el.closest('[data-no-swup]')) return true;
+    try {
+      var u = new URL(url, window.location.origin);
+      var p = u.pathname;
+      if (p.indexOf('/_admin') === 0 || p.indexOf('/_webspresso') === 0) return true;
+    } catch (e) {
+      /* ignore */
+    }
+    return false;
+  }
+
+  var swup = new Swup({
+    containers: ['#swup'],
+    plugins: [new SwupHeadPlugin(), new SwupScriptsPlugin()],
+    ignoreVisit: ignoreVisit,
+  });
+  window.__webspressoSwup = swup;
+})();

package/src/client-runtime/mount.js

@@ -0,0 +1,65 @@
+/**
+ * Mount Express routes that serve vendored Alpine / Swup UMD builds from node_modules
+ * and framework bootstrap scripts from src/client-runtime/.
+ */
+
+const path = require('path');
+const express = require('express');
+
+const CLIENT_RUNTIME_BASE = '/__webspresso/client-runtime';
+
+/** Resolve a file next to the package's resolved main entry (works with package "exports"). */
+function pkgFileFromMain(pkg, ...segments) {
+  const entry = require.resolve(pkg);
+  return path.join(path.dirname(entry), ...segments);
+}
+
+/**
+ * @param {import('express').Express} app
+ * @param {{ alpine: boolean, swup: boolean }} flags
+ */
+function mountClientRuntime(app, flags) {
+  if (!flags || (!flags.alpine && !flags.swup)) return;
+
+  const router = express.Router();
+
+  function send(res, filePath) {
+    res.type('application/javascript');
+    res.sendFile(filePath);
+  }
+
+  if (flags.alpine) {
+    router.get('/alpine.min.js', (req, res) => {
+      send(res, pkgFileFromMain('alpinejs', 'cdn.min.js'));
+    });
+  }
+
+  if (flags.swup) {
+    router.get('/swup.umd.js', (req, res) => {
+      send(res, pkgFileFromMain('swup', 'Swup.umd.js'));
+    });
+    router.get('/swup-head-plugin.umd.js', (req, res) => {
+      send(res, pkgFileFromMain('@swup/head-plugin', 'index.umd.js'));
+    });
+    router.get('/swup-scripts-plugin.umd.js', (req, res) => {
+      send(res, pkgFileFromMain('@swup/scripts-plugin', 'index.umd.js'));
+    });
+    const runtimeDir = __dirname;
+    if (flags.alpine) {
+      router.get('/bootstrap-alpine-swup.js', (req, res) => {
+        send(res, path.join(runtimeDir, 'bootstrap-alpine-swup.js'));
+      });
+    } else {
+      router.get('/bootstrap-swup.js', (req, res) => {
+        send(res, path.join(runtimeDir, 'bootstrap-swup.js'));
+      });
+    }
+  }
+
+  app.use(CLIENT_RUNTIME_BASE, router);
+}
+
+module.exports = {
+  mountClientRuntime,
+  CLIENT_RUNTIME_BASE,
+};

package/src/client-runtime/resolve.js

@@ -0,0 +1,40 @@
+/**
+ * Resolve clientRuntime flags from createApp({ clientRuntime }) and optional env overrides.
+ * Env: WEBSPRESSO_ALPINE=1|true, WEBSPRESSO_SWUP=1|true (override explicit false from options when set).
+ */
+
+function envTruthy(name) {
+  const v = process.env[name];
+  if (v == null || v === '') return undefined;
+  return v === '1' || /^true$/i.test(String(v));
+}
+
+function optionEnabled(v) {
+  if (v === true) return true;
+  if (v && typeof v === 'object') return true;
+  return false;
+}
+
+/**
+ * @param {object} [options]
+ * @param {object} [options.clientRuntime]
+ * @param {boolean|object} [options.clientRuntime.alpine]
+ * @param {boolean|object} [options.clientRuntime.swup]
+ * @returns {{ alpine: boolean, swup: boolean }}
+ */
+function resolveClientRuntime(options = {}) {
+  const cr = options.clientRuntime;
+  let alpine = false;
+  let swup = false;
+  if (cr && typeof cr === 'object') {
+    alpine = optionEnabled(cr.alpine);
+    swup = optionEnabled(cr.swup);
+  }
+  const envA = envTruthy('WEBSPRESSO_ALPINE');
+  const envS = envTruthy('WEBSPRESSO_SWUP');
+  if (envA !== undefined) alpine = envA;
+  if (envS !== undefined) swup = envS;
+  return { alpine, swup };
+}
+
+module.exports = { resolveClientRuntime };

package/src/file-router.js

@@ -276,9 +276,58 @@ function detectLocale(req) {
 }
 
 /**
- * Resolve middleware from config - supports both functions and named strings
- * @param {Array} middlewareConfig - Array of middleware functions or names
- * @param {Object} middlewareRegistry - Named middleware registry
+ * True when the registry entry is (options) => (req, res, next) => …
+ * Express handlers typically have length >= 2 (req, res) or 3 (req, res, next).
+ */
+function isMiddlewareFactory(fn) {
+  return typeof fn === 'function' && fn.length <= 1;
+}
+
+/**
+ * Resolve a named middleware from createApp({ middlewares }).
+ * @param {string} name
+ * @param {Function} entry
+ * @param {boolean} fromTuple - true when route used ['name', options]
+ * @param {unknown} tupleOptions - second element of the tuple (only when fromTuple)
+ * @param {Object} middlewareRegistry - for error messages
+ * @returns {Function} Express middleware
+ */
+function resolveNamedMiddleware(name, entry, fromTuple, tupleOptions, middlewareRegistry) {
+  if (!entry) {
+    throw new Error(`Middleware "${name}" not found in registry. Available: ${Object.keys(middlewareRegistry).join(', ') || 'none'}`);
+  }
+  if (typeof entry !== 'function') {
+    throw new Error(`Middleware "${name}" must be a function`);
+  }
+
+  if (fromTuple) {
+    if (!isMiddlewareFactory(entry)) {
+      throw new Error(
+        `Middleware "${name}" must be a factory (options) => (req, res, next) => … when using ["${name}", options] tuple form`
+      );
+    }
+    const produced = entry(tupleOptions);
+    if (typeof produced !== 'function') {
+      throw new Error(`Middleware factory "${name}" must return an Express middleware function`);
+    }
+    return produced;
+  }
+
+  if (isMiddlewareFactory(entry)) {
+    const produced = entry({});
+    if (typeof produced !== 'function') {
+      throw new Error(`Middleware factory "${name}" must return an Express middleware function`);
+    }
+    return produced;
+  }
+
+  return entry;
+}
+
+/**
+ * Resolve middleware from config — functions, string names, or [name, options] tuples
+ * @param {Array} middlewareConfig - middleware functions, names, or ['name', options] tuples
+ * @param {Object} middlewareRegistry - Named middleware registry (plain handlers or option factories)
  * @returns {Array} Array of resolved middleware functions
  */
 function resolveMiddlewares(middlewareConfig, middlewareRegistry = {}) {
@@ -292,17 +341,17 @@ function resolveMiddlewares(middlewareConfig, middlewareRegistry = {}) {
     }
     
     if (typeof mw === 'string') {
-      const resolved = middlewareRegistry[mw];
-      if (!resolved) {
-        throw new Error(`Middleware "${mw}" not found in registry. Available: ${Object.keys(middlewareRegistry).join(', ') || 'none'}`);
-      }
-      if (typeof resolved !== 'function') {
-        throw new Error(`Middleware "${mw}" must be a function`);
-      }
-      return resolved;
+      return resolveNamedMiddleware(mw, middlewareRegistry[mw], false, undefined, middlewareRegistry);
+    }
+
+    if (Array.isArray(mw) && mw.length === 2 && typeof mw[0] === 'string') {
+      const name = mw[0];
+      return resolveNamedMiddleware(name, middlewareRegistry[name], true, mw[1], middlewareRegistry);
     }
     
-    throw new Error(`Invalid middleware at index ${index}: must be a function or string name`);
+    throw new Error(
+      `Invalid middleware at index ${index}: must be a function, string name, or [name, options] tuple`
+    );
   });
 }
 
@@ -316,10 +365,22 @@ function resolveMiddlewares(middlewareConfig, middlewareRegistry = {}) {
  * @param {Object} options.pluginManager - Plugin manager instance
  * @param {boolean} options.silent - Suppress console output
  * @param {Object} options.db - Database instance (exposed as ctx.db in load/meta)
+ * @param {{ alpine?: boolean, swup?: boolean }} [options.clientRuntime] - Passed to Nunjucks as `clientRuntime` (default both false)
  * @returns {Array} Route metadata for plugins
  */
 function mountPages(app, options) {
-  const { pagesDir, nunjucks, middlewares = {}, pluginManager = null, silent = false, db = null } = options;
+  const {
+    pagesDir,
+    nunjucks,
+    middlewares = {},
+    pluginManager = null,
+    silent = false,
+    db = null,
+    clientRuntime: clientRuntimeOpt = null,
+  } = options;
+  const clientRuntime = clientRuntimeOpt && typeof clientRuntimeOpt === 'object'
+    ? { alpine: !!clientRuntimeOpt.alpine, swup: !!clientRuntimeOpt.swup }
+    : { alpine: false, swup: false };
   const isDev = process.env.NODE_ENV !== 'production';
   const log = silent ? () => {} : console.log.bind(console);
   
@@ -499,7 +560,8 @@ function mountPages(app, options) {
             indexable: true,
             canonical: null
           },
-          fsy: { ...baseHelpers, ...pluginHelpers }
+          fsy: { ...baseHelpers, ...pluginHelpers },
+          clientRuntime,
         };
         
         // Execute hooks: onRequest
@@ -563,6 +625,7 @@ function mountPages(app, options) {
           locale: ctx.locale,
           t: ctx.t,
           fsy: ctx.fsy,
+          clientRuntime: ctx.clientRuntime,
           req: {
             path: req.path,
             query: req.query,

package/src/server.js

@@ -9,6 +9,8 @@ const nunjucks = require('nunjucks');
 const timeout = require('connect-timeout');
 
 const { setAppContext } = require('./app-context');
+const { mountClientRuntime } = require('./client-runtime/mount');
+const { resolveClientRuntime } = require('./client-runtime/resolve');
 const { mountPages } = require('./file-router');
 const { configureAssets, createHelpers, getScriptInjector } = require('./helpers');
 const { createPluginManager } = require('./plugin-manager');
@@ -258,6 +260,7 @@ function haltOnTimedout(req, res, next) {
  * @param {string|boolean} options.timeout - Request timeout (default: '30s', false to disable)
  * @param {Object} options.auth - Authentication manager instance (from createAuth)
  * @param {Object} options.db - Database instance (exposed as ctx.db to plugins)
+ * @param {Object} [options.clientRuntime] - Optional client assets: `{ alpine?: boolean|object, swup?: boolean|object }`. Overridable by env `WEBSPRESSO_ALPINE` / `WEBSPRESSO_SWUP` (=1 or true). Serves `/__webspresso/client-runtime/*` when either flag is on.
  * @param {function(import('express').Express, Object): void} [options.setupRoutes] - Called after file routes and plugins, before 404 handler
  * @returns {Object} { app, nunjucksEnv, pluginManager, authMiddleware }
  */
@@ -294,6 +297,8 @@ function createApp(options = {}) {
     throw new Error('pagesDir is required');
   }
 
+  const clientRuntime = resolveClientRuntime(options);
+
   setAppContext({ db: options.db ?? null });
   
   const app = express();
@@ -378,7 +383,9 @@ function createApp(options = {}) {
       etag: true
     }));
   }
-  
+
+  mountClientRuntime(app, clientRuntime);
+
   // Configure Nunjucks
   const templateDirs = viewsDir ? [pagesDir, viewsDir] : [pagesDir];
   
@@ -439,7 +446,8 @@ function createApp(options = {}) {
     middlewares,
     pluginManager,
     silent: isTest,
-    db: options.db ?? null
+    db: options.db ?? null,
+    clientRuntime,
   });
   
   // Set route metadata in plugin manager
@@ -480,6 +488,7 @@ function createApp(options = {}) {
       authMiddleware,
       pluginManager,
       options,
+      clientRuntime,
     });
   }
   

package/templates/skills/webspresso-usage/SKILL.md

@@ -66,8 +66,9 @@ project/
 | `timeout` | e.g. `'30s'` or `false` |
 | `helmet` | `true` / `false` / object |
 | `assets` | `{ version, manifestPath, prefix }` for `fsy.asset` / `fsy.css` / `fsy.js` |
+| `clientRuntime` | Opt-in `{ alpine?, swup? }` — serves `/__webspresso/client-runtime/*`, template `clientRuntime`, partial `views/partials/webspresso-client-runtime.njk`, `<main id="swup">` when swup on. Env: `WEBSPRESSO_ALPINE`, `WEBSPRESSO_SWUP`. |
 | `auth` | Auth manager from `createAuth` (session routes) |
-| `setupRoutes(app, ctx)` | **Register custom Express routes here** — runs **after** file routes and plugins’ `onRoutesReady`, **before** 404. Do not rely on `app.get` *after* `createApp` returns unless routes are appended before the 404 middleware (see [`src/server.js`](../../../src/server.js)). |
+| `setupRoutes(app, ctx)` | **Register custom Express routes here** — runs **after** file routes and plugins’ `onRoutesReady`, **before** 404. `ctx.clientRuntime` included. Do not rely on `app.get` *after* `createApp` returns unless routes are appended before the 404 middleware (see [`src/server.js`](../../../src/server.js)). |
 
 **Returns:** `{ app, nunjucksEnv, pluginManager, authMiddleware? }` (and related).
 
@@ -164,6 +165,8 @@ Analytics plugin adds `fsy.analyticsHead`, `fsy.verificationTags`, etc., when co
 
 **Transactions:** `db.transaction(async (trx) => { trx.getRepository('User') })`.
 
+**Query cache (optional):** `createDatabase({ ..., cache: true })` or `cache: { defaultStrategy: 'auto'|'smart', memory: { maxEntries, defaultTtlMs }, provider?: custom }`. Opt-in per model: `defineModel({ ..., cache: 'auto'|'smart'|true })`. API: `db.cache` → `getMetrics()`, `purge()`, `invalidateModel(name)`, `invalidateTags(tags[])`, `resetMetrics()`. Reads bypass cache when using a transaction knex. Admin UI: `ormCacheAdminPlugin({ db })` (needs `admin-panel` and `cache` enabled).
+
 Pass **`db`** into **`createApp({ db })`** so **`ctx.db`** works in pages and plugins. **`pages/api/`** handlers receive **`req.db`** (and route **`middleware`** runs after it). Outside requests, use **`getDb()`** / **`hasDb()`**; for **`setupRoutes`**-only routes, use **`attachDbMiddleware`**.
 
 ---
@@ -180,6 +183,7 @@ Pass **`db`** into **`createApp({ db })`** so **`ctx.db`** works in pages and pl
 | `auditLogPlugin` | Admin mutation audit trail |
 | `recaptchaPlugin` | v2/v3 + middleware |
 | `seoCheckerPlugin` | Dev SEO panel |
+| `ormCacheAdminPlugin` | Admin page for ORM cache metrics / purge / invalidate (`db.cache` required) |
 
 **Custom plugin:** `name`, `version`, `register(ctx)`, `onRoutesReady(ctx)` — use `ctx.app`, `ctx.db`, `ctx.addHelper`, `ctx.addRoute`, `ctx.usePlugin('other')`. Plugin failures **warn**; app keeps running.