webspresso 0.0.89 → 0.0.90

package/plugins/content/client/inline-edit.js

@@ -243,35 +243,59 @@
       });
   }
 
-  function sanitizeClientHtml(htmlStr) {
-    if (!htmlStr) return '';
+  function setSanitizedHtmlContent(el, htmlStr) {
+    if (!htmlStr) {
+      el.textContent = '';
+      return;
+    }
     try {
       var parser = new DOMParser();
       var doc = parser.parseFromString(htmlStr, 'text/html');
-      var forbiddenTags = ['script', 'iframe', 'object', 'embed', 'applet', 'base'];
-      forbiddenTags.forEach(function (tag) {
-        var nodes = doc.querySelectorAll(tag);
-        for (var i = 0; i < nodes.length; i++) {
-          nodes[i].parentNode.removeChild(nodes[i]);
-        }
-      });
-      var allNodes = doc.querySelectorAll('*');
-      for (var i = 0; i < allNodes.length; i++) {
+      var allowedTags = {
+        p: 1, br: 1, b: 1, i: 1, strong: 1, em: 1, u: 1, s: 1, strike: 1,
+        h1: 1, h2: 1, h3: 1, h4: 1, h5: 1, h6: 1, ul: 1, ol: 1, li: 1,
+        blockquote: 1, pre: 1, code: 1, a: 1, span: 1, div: 1, hr: 1,
+        table: 1, thead: 1, tbody: 1, tr: 1, th: 1, td: 1, img: 1
+      };
+      var allowedAttrs = {
+        href: 1, title: 1, target: 1, rel: 1, class: 1, id: 1, src: 1, alt: 1, width: 1, height: 1
+      };
+      var allNodes = doc.body.querySelectorAll('*');
+      for (var i = allNodes.length - 1; i >= 0; i--) {
         var node = allNodes[i];
+        var tag = node.tagName.toLowerCase();
+        if (!allowedTags[tag]) {
+          if (node.parentNode) {
+            node.parentNode.removeChild(node);
+          } else {
+            node.remove();
+          }
+          continue;
+        }
         var attrs = Array.prototype.slice.call(node.attributes);
         for (var j = 0; j < attrs.length; j++) {
           var attrName = attrs[j].name.toLowerCase();
-          var attrVal = attrs[j].value.toLowerCase().trim();
-          if (attrName.indexOf('on') === 0) {
+          var attrVal = attrs[j].value.toLowerCase().replace(/[\x00-\x20\s]+/g, '').trim();
+          if (attrName.indexOf('on') === 0 || !allowedAttrs[attrName]) {
             node.removeAttribute(attrs[j].name);
-          } else if ((attrName === 'href' || attrName === 'src') && attrVal.indexOf('javascript:') === 0) {
+          } else if ((attrName === 'href' || attrName === 'src' || attrName === 'action' || attrName === 'formaction' || attrName === 'xlink:href') &&
+                     /^(?:javascript|data|vbscript):/i.test(attrVal)) {
             node.removeAttribute(attrs[j].name);
+          } else if (tag === 'a' && node.getAttribute('target') === '_blank') {
+            node.setAttribute('rel', 'noopener noreferrer');
           }
         }
       }
-      return doc.body.innerHTML;
+
+      // Transfer DOM nodes directly to target element
+      while (el.firstChild) {
+        el.removeChild(el.firstChild);
+      }
+      while (doc.body.firstChild) {
+        el.appendChild(doc.body.firstChild);
+      }
     } catch (e) {
-      return '';
+      el.textContent = htmlStr;
     }
   }
 
@@ -282,7 +306,7 @@
       var val = data[field];
       var isHtml = el.getAttribute('data-ws-content-html') === 'true';
       if (isHtml) {
-        el.innerHTML = sanitizeClientHtml(val);
+        setSanitizedHtmlContent(el, val);
       } else {
         el.textContent = val != null ? val : '';
       }

package/plugins/cors.js

@@ -47,9 +47,12 @@ function createCorsMiddleware(options = {}) {
 
   function isOriginAllowed(reqOrigin, callback) {
     if (!config.origin || config.origin === '*') {
-      return callback(null, config.origin);
+      if (config.credentials) {
+        return callback(null, false);
+      }
+      return callback(null, '*');
     }
-    if (!reqOrigin) {
+    if (!reqOrigin || reqOrigin === 'null') {
       return callback(null, false);
     }
     if (typeof config.origin === 'string') {
@@ -72,6 +75,9 @@ function createCorsMiddleware(options = {}) {
     if (typeof config.origin === 'function') {
       return config.origin(reqOrigin, callback);
     }
+    if (config.origin === true) {
+      return callback(null, reqOrigin);
+    }
     return callback(null, false);
   }
 
@@ -96,15 +102,13 @@ function createCorsMiddleware(options = {}) {
       }
 
       if (allowedOrigin) {
-        if (allowedOrigin === '*' && config.credentials) {
-          res.setHeader('Access-Control-Allow-Origin', reqOrigin || '*');
-        } else {
-          res.setHeader('Access-Control-Allow-Origin', allowedOrigin);
+        res.setHeader('Access-Control-Allow-Origin', allowedOrigin);
+        if (allowedOrigin !== '*') {
+          res.setHeader('Vary', 'Origin');
         }
-        res.setHeader('Vary', 'Origin');
       }
 
-      if (config.credentials) {
+      if (config.credentials && allowedOrigin && allowedOrigin !== '*') {
         res.setHeader('Access-Control-Allow-Credentials', 'true');
       }
 

package/plugins/csrf/index.js

@@ -158,11 +158,11 @@ function csrfPlugin(options = {}) {
       }
 
       // 1. Retrieve or generate secret token
-      let secret;
+      let csrfTokenValue;
       if (useCookie) {
-        secret = cookieOptions.signed ? req.signedCookies[cookieKey] : req.cookies[cookieKey];
-        if (!secret) {
-          secret = crypto.randomBytes(32).toString('hex');
+        csrfTokenValue = cookieOptions.signed ? req.signedCookies[cookieKey] : req.cookies[cookieKey];
+        if (!csrfTokenValue) {
+          csrfTokenValue = crypto.randomBytes(32).toString('hex');
           const isHttps = req.secure || req.headers?.['x-forwarded-proto'] === 'https' || process.env.NODE_ENV === 'production' || process.env.COOKIE_SECURE === 'true';
           const effectiveCookieOptions = {
             httpOnly: true,
@@ -170,18 +170,18 @@ function csrfPlugin(options = {}) {
             ...cookieOptions,
             secure: cookieOpts.secure !== undefined ? cookieOpts.secure : isHttps,
           };
-          res.cookie(cookieKey, secret, effectiveCookieOptions);
+          res.cookie(cookieKey, csrfTokenValue, effectiveCookieOptions);
         }
       } else {
         // Session based
         if (!req.session[sessionKey]) {
           req.session[sessionKey] = crypto.randomBytes(32).toString('hex');
         }
-        secret = req.session[sessionKey];
+        csrfTokenValue = req.session[sessionKey];
       }
 
       // Define standard req.csrfToken()
-      req.csrfToken = () => secret;
+      req.csrfToken = () => csrfTokenValue;
 
       // 2. Perform CSRF verification for mutating HTTP methods
       const method = req.method ? req.method.toUpperCase() : 'GET';
@@ -196,7 +196,7 @@ function csrfPlugin(options = {}) {
           req.headers['x-xsrf-token']
         );
 
-        if (!submitted || !safeCompare(submitted, secret)) {
+        if (!submitted || !safeCompare(submitted, csrfTokenValue)) {
           res.status(errorStatus);
           if (req.accepts('html') && !req.path.startsWith('/api')) {
             return res.send(`<h1>${errorStatus} Forbidden</h1><p>${errorMessage}</p>`);

package/src/file-router.js

@@ -432,16 +432,14 @@ function loadI18n(pagesDir, routeDir, locale) {
   return data;
 }
 
-/**
- * Create a translation function
- * @param {Object} translations - Translation object
- * @returns {Function} Translation function t(key)
- */
-function createTranslator(translations) {
-  return function t(key, params = EMPTY_OBJECT) {
-    let value = translations[key];
+function createTranslator(translations = {}) {
+  return function t(key, params = EMPTY_OBJECT, defaultVal = null) {
+    const defaultValue = typeof params === 'string' ? params : defaultVal;
+    const interpolationParams = typeof params === 'object' && params !== null ? params : EMPTY_OBJECT;
+
+    let value = translations ? translations[key] : undefined;
     
-    if (value === undefined) {
+    if (value === undefined && translations) {
       // Try nested key lookup (e.g., "meta.title")
       const parts = key.split('.');
       value = translations;
@@ -456,12 +454,12 @@ function createTranslator(translations) {
     }
     
     if (value === undefined) {
-      return key; // Return key if translation not found
+      return defaultValue !== null && defaultValue !== undefined ? defaultValue : key;
     }
     
     // Replace params like {{name}} in the translation
-    if (typeof value === 'string' && params && params !== EMPTY_OBJECT && Object.keys(params).length > 0) {
-      for (const [paramKey, paramValue] of Object.entries(params)) {
+    if (typeof value === 'string' && interpolationParams && interpolationParams !== EMPTY_OBJECT && Object.keys(interpolationParams).length > 0) {
+      for (const [paramKey, paramValue] of Object.entries(interpolationParams)) {
         let regex = paramRegexCache.get(paramKey);
         if (regex === undefined) {
           const escaped = escapeRegExp(paramKey);
@@ -814,6 +812,18 @@ function mountPages(app, options) {
   sortRoutes(apiRoutes);
   sortRoutes(ssrRoutes);
 
+  // Check for duplicate route bindings
+  const registeredRouteMap = new Map();
+  for (const r of [...apiRoutes, ...ssrRoutes]) {
+    const key = `${(r.method || 'GET').toUpperCase()} ${r.routePath}`;
+    if (registeredRouteMap.has(key)) {
+      const existing = registeredRouteMap.get(key);
+      console.warn(`[webspresso] WARNING: Duplicate route detected: ${key} in "${r.file}" conflicts with existing route in "${existing.file}".`);
+    } else {
+      registeredRouteMap.set(key, r);
+    }
+  }
+
   const apiStatic = apiRoutes.filter((r) => routeRegistrationMeta(r.routePath).tier === 0);
   const apiDynamic = apiRoutes.filter((r) => routeRegistrationMeta(r.routePath).tier !== 0);
   const ssrStatic = ssrRoutes.filter((r) => routeRegistrationMeta(r.routePath).tier === 0);
@@ -1002,7 +1012,9 @@ function mountPages(app, options) {
         // Run load function
         if (config?.load && typeof config.load === 'function') {
           const loadData = await config.load(req, ctx);
-          ctx.data = { ...ctx.data, ...loadData };
+          if (loadData && typeof loadData === 'object' && !Array.isArray(loadData)) {
+            ctx.data = { ...ctx.data, ...loadData };
+          }
         }
         
         // Execute hooks: afterLoad
@@ -1012,7 +1024,9 @@ function mountPages(app, options) {
         // Run meta function
         if (config?.meta && typeof config.meta === 'function') {
           const metaData = await config.meta(req, ctx);
-          ctx.meta = { ...ctx.meta, ...metaData };
+          if (metaData && typeof metaData === 'object' && !Array.isArray(metaData)) {
+            ctx.meta = { ...ctx.meta, ...metaData };
+          }
         }
         
         // Execute hooks: beforeRender
@@ -1058,6 +1072,9 @@ function mountPages(app, options) {
         await executeHook(globalHooks, 'afterRender', ctx);
         await executeHook(routeHooks, 'afterRender', ctx);
         
+        if (route.routePath === '/404' || route.file === '404.njk') {
+          res.status(404);
+        }
         res.send(ctx.html);
       } catch (err) {
         console.error(`SSR error ${route.routePath}:`, err);

package/src/helpers.js

@@ -236,7 +236,7 @@ function createHelpers(ctx) {
      * @returns {*}
      */
     q(name, def = null) {
-      return req.query[name] !== undefined ? req.query[name] : def;
+      return req && req.query && req.query[name] !== undefined ? req.query[name] : def;
     },
 
     /**
@@ -246,7 +246,7 @@ function createHelpers(ctx) {
      * @returns {*}
      */
     param(name, def = null) {
-      return req.params[name] !== undefined ? req.params[name] : def;
+      return req && req.params && req.params[name] !== undefined ? req.params[name] : def;
     },
 
     /**
@@ -256,7 +256,8 @@ function createHelpers(ctx) {
      * @returns {*}
      */
     hdr(name, def = null) {
-      return req.get(name) || def;
+      if (!req) return def;
+      return (typeof req.get === 'function' ? req.get(name) : (req.headers && req.headers[name.toLowerCase()])) || def;
     },
 
     /**

package/src/plugin-manager.js

@@ -202,7 +202,10 @@ class PluginManager {
         continue;
       }
       pluginMap.set(plugin.name, plugin);
-      graph.set(plugin.name, new Set(Object.keys(plugin.dependencies || {})));
+      const depNames = Array.isArray(plugin.dependencies)
+        ? plugin.dependencies
+        : Object.keys(plugin.dependencies || {});
+      graph.set(plugin.name, new Set(depNames));
     }
 
     // Topological sort (Kahn's algorithm)
@@ -339,7 +342,11 @@ class PluginManager {
   _validateDependencies(plugin) {
     if (!plugin.dependencies) return;
 
-    for (const [depName, versionRange] of Object.entries(plugin.dependencies)) {
+    const depEntries = Array.isArray(plugin.dependencies)
+      ? plugin.dependencies.map(d => [d, '*'])
+      : Object.entries(plugin.dependencies);
+
+    for (const [depName, versionRange] of depEntries) {
       const dep = this.plugins.get(depName);
 
       if (!dep) {
@@ -350,7 +357,7 @@ class PluginManager {
         continue;
       }
 
-      if (dep.version && !semver.satisfies(dep.version, versionRange)) {
+      if (dep.version && versionRange !== '*' && !semver.satisfies(dep.version, versionRange)) {
         console.warn(
           `[plugin-manager] Plugin "${plugin.name}" requires "${depName}@${versionRange}" ` +
           `but found v${dep.version}. Plugin may not work correctly.`

package/src/server.js

@@ -3,6 +3,9 @@
  * Express + Nunjucks SSR server with file-based routing
  */
 
+const fs = require('fs');
+const path = require('path');
+const { AsyncLocalStorage } = require('async_hooks');
 const express = require('express');
 const helmet = require('helmet');
 const nunjucks = require('nunjucks');
@@ -11,10 +14,103 @@ const timeout = require('connect-timeout');
 const { setAppContext } = require('./app-context');
 const { mountClientRuntime } = require('./client-runtime/mount');
 const { resolveClientRuntime } = require('./client-runtime/resolve');
-const { mountPages, detectLocale } = require('./file-router');
+const { mountPages, detectLocale, loadI18n, createTranslator } = require('./file-router');
 const { configureAssets, createHelpers, getScriptInjector } = require('./helpers');
 const { createPluginManager } = require('./plugin-manager');
 
+// Async storage for tracking template render call stacks (circular extends guard)
+const renderStackStorage = new AsyncLocalStorage();
+
+/**
+ * Configure Nunjucks environment with circular extends guard and loader protection
+ * @param {string|string[]} templateDirs - Template directory paths
+ * @param {Object} options - Nunjucks options
+ * @returns {nunjucks.Environment}
+ */
+function configureSafeNunjucks(templateDirs, options = {}) {
+  const env = nunjucks.configure(templateDirs, options);
+  const origGetTemplate = env.getTemplate.bind(env);
+  const origRender = env.render.bind(env);
+  const origRenderString = env.renderString.bind(env);
+
+  function wrapTemplateRoot(tmpl, name, store) {
+    if (!tmpl || tmpl._safeWrapped) return;
+    tmpl._safeWrapped = true;
+    const origRoot = tmpl.rootRenderFunc;
+    if (typeof origRoot !== 'function') return;
+
+    tmpl.rootRenderFunc = function(e, context, frame, runtime, renderCb) {
+      const normalizedName = String(name || tmpl.path || 'anonymous');
+      store.stack.push(normalizedName);
+      let finished = false;
+      const done = (err, out) => {
+        if (!finished) {
+          finished = true;
+          const idx = store.stack.lastIndexOf(normalizedName);
+          if (idx !== -1) store.stack.splice(idx, 1);
+        }
+        renderCb(err, out);
+      };
+      try {
+        return origRoot.call(this, e, context, frame, runtime, done);
+      } catch (ex) {
+        const idx = store.stack.lastIndexOf(normalizedName);
+        if (idx !== -1) store.stack.splice(idx, 1);
+        throw ex;
+      }
+    };
+  }
+
+  env.getTemplate = function(name, eagerCompile, parentName, ignoreMissing, cb) {
+    if (typeof parentName === 'function') {
+      cb = parentName;
+      parentName = null;
+    }
+    if (typeof eagerCompile === 'function') {
+      cb = eagerCompile;
+      eagerCompile = false;
+    }
+
+    const store = renderStackStorage.getStore();
+    if (store && name) {
+      const normalizedName = String(name);
+      if (store.stack.includes(normalizedName)) {
+        const cycle = [...store.stack, normalizedName].join(' -> ');
+        const err = new Error(`Circular template extension detected: ${cycle}`);
+        if (typeof cb === 'function') return cb(err);
+        throw err;
+      }
+    }
+
+    const wrappedCb = typeof cb === 'function' ? function(err, tmpl) {
+      if (tmpl && store) {
+        wrapTemplateRoot(tmpl, name, store);
+      }
+      cb(err, tmpl);
+    } : undefined;
+
+    const res = origGetTemplate(name, eagerCompile, parentName, ignoreMissing, wrappedCb);
+    if (res && store) {
+      wrapTemplateRoot(res, name, store);
+    }
+    return res;
+  };
+
+  env.render = function(name, ctx, cb) {
+    return renderStackStorage.run({ stack: [] }, () => {
+      return origRender(name, ctx, cb);
+    });
+  };
+
+  env.renderString = function(src, ctx, opts, cb) {
+    return renderStackStorage.run({ stack: [] }, () => {
+      return origRenderString(src, ctx, opts, cb);
+    });
+  };
+
+  return env;
+}
+
 /**
  * Get default Helmet configuration
  * @param {boolean} isDev - Whether in development mode
@@ -58,13 +154,27 @@ function getDefaultHelmetConfig(isDev) {
 }
 
 /**
- * Use JSON error responses for `pages/api/*` routes and clients that do not prefer HTML.
+ * Use JSON error responses for `pages/api/*` routes, XHR requests, and clients that prefer JSON.
  * @param {import('express').Request} req
  * @returns {boolean}
  */
 function preferJsonErrorResponse(req) {
+  if (!req) return false;
   if (req.path && req.path.startsWith('/api')) return true;
-  return !req.accepts('html');
+  if (req.xhr) return true;
+  
+  if (typeof req.accepts === 'function') {
+    const preferred = req.accepts(['html', 'json']);
+    if (preferred === 'json') return true;
+    if (preferred === 'html') return false;
+    return !req.accepts('html');
+  }
+
+  const accept = req.headers && req.headers.accept;
+  if (accept && accept.includes('application/json') && !accept.includes('text/html')) {
+    return true;
+  }
+  return false;
 }
 
 /**
@@ -405,10 +515,10 @@ function createApp(options = {}) {
 
   mountClientRuntime(app, clientRuntime);
 
-  // Configure Nunjucks
-  const templateDirs = viewsDir ? [pagesDir, viewsDir] : [pagesDir];
+  // Configure Nunjucks with viewsDir priority and circular extension guard
+  const templateDirs = viewsDir ? [viewsDir, pagesDir] : [pagesDir];
   
-  const nunjucksEnv = nunjucks.configure(templateDirs, {
+  const nunjucksEnv = configureSafeNunjucks(templateDirs, {
     autoescape: true,
     express: app,
     watch: isDev && !isTest,
@@ -528,10 +638,15 @@ function createApp(options = {}) {
     // Merge plugin helpers
     const pluginHelpers = pluginManager.getHelpers();
     Object.assign(fsy, pluginHelpers);
+
+    // Provide safe i18n translator helper
+    const translations = loadI18n(pagesDir, '', locale);
+    const t = createTranslator(translations);
     
     return {
       fsy,
       locale,
+      t,
       isDev,
       url: req.url,
       method: req.method,
@@ -539,20 +654,63 @@ function createApp(options = {}) {
     };
   }
   
+  // Pre-resolve error templates and loaders once at startup to avoid runtime synchronous fs operations
+  const resolved404Template = typeof errorPages.notFound === 'string'
+    ? errorPages.notFound
+    : ((viewsDir && fs.existsSync(path.join(viewsDir, '404.njk'))) || fs.existsSync(path.join(pagesDir, '404.njk')))
+      ? '404.njk'
+      : null;
+
+  const config404Path = path.join(pagesDir, '404.js');
+  const has404DataLoader = fs.existsSync(config404Path);
+
+  const resolved500Template = typeof errorPages.serverError === 'string'
+    ? errorPages.serverError
+    : ((viewsDir && fs.existsSync(path.join(viewsDir, '500.njk'))) || fs.existsSync(path.join(pagesDir, '500.njk')))
+      ? '500.njk'
+      : null;
+
+  const resolved503Template = typeof errorPages.timeout === 'string'
+    ? errorPages.timeout
+    : ((viewsDir && fs.existsSync(path.join(viewsDir, '503.njk'))) || fs.existsSync(path.join(pagesDir, '503.njk')))
+      ? '503.njk'
+      : null;
+
   // 404 handler
-  app.use((req, res) => {
+  app.use(async (req, res) => {
     res.status(404);
     const ctx = createErrorContext(req);
     
-    // Custom handler function
+    // 1. Custom handler function
     if (typeof errorPages.notFound === 'function') {
       return errorPages.notFound(req, res, ctx);
     }
     
-    // Custom template
-    if (typeof errorPages.notFound === 'string') {
+    // 2. Custom or auto-discovered 404 template (pre-resolved at startup)
+    const notFoundTemplate = resolved404Template;
+    
+    if (notFoundTemplate && !preferJsonErrorResponse(req)) {
       try {
-        const html = nunjucksEnv.render(errorPages.notFound, ctx);
+        // If pages/404.js exists, execute load() data loader
+        if (has404DataLoader) {
+          try {
+            if (isDev && require.cache[require.resolve(config404Path)]) {
+              delete require.cache[require.resolve(config404Path)];
+            }
+            const config404 = require(config404Path);
+            const loadFn = typeof config404 === 'function' ? config404 : config404.load;
+            if (typeof loadFn === 'function') {
+              const loadData = await loadFn({ req, res, db: ctx.db || null, ctx });
+              if (loadData && typeof loadData === 'object') {
+                Object.assign(ctx, loadData);
+              }
+            }
+          } catch (loadErr) {
+            console.error('Error executing 404.js load():', loadErr);
+          }
+        }
+
+        const html = nunjucksEnv.render(notFoundTemplate, ctx);
         return res.send(html);
       } catch (e) {
         console.error('Error rendering 404 template:', e);
@@ -560,7 +718,7 @@ function createApp(options = {}) {
     }
     
     // Default response
-    if (req.accepts('html')) {
+    if (!preferJsonErrorResponse(req)) {
       res.send(default404Html());
     } else {
       res.json({ error: 'Not Found', status: 404 });
@@ -569,6 +727,10 @@ function createApp(options = {}) {
   
   // Error handler
   app.use((err, req, res, next) => {
+    if (res.headersSent) {
+      return next(err);
+    }
+    
     // Handle timeout errors
     if (req.timedout) {
       console.error('Request timed out:', req.method, req.url);
@@ -580,10 +742,12 @@ function createApp(options = {}) {
         return errorPages.timeout(req, res, ctx);
       }
       
-      // Custom timeout template
-      if (typeof errorPages.timeout === 'string' && !preferJsonErrorResponse(req)) {
+      // Custom or auto-discovered timeout template (pre-resolved at startup)
+      const timeoutTemplate = resolved503Template;
+
+      if (timeoutTemplate && !preferJsonErrorResponse(req)) {
         try {
-          const html = nunjucksEnv.render(errorPages.timeout, ctx);
+          const html = nunjucksEnv.render(timeoutTemplate, ctx);
           return res.send(html);
         } catch (e) {
           console.error('Error rendering timeout template:', e);
@@ -610,10 +774,12 @@ function createApp(options = {}) {
       return errorPages.serverError(err, req, res, ctx);
     }
     
-    // Custom template (skipped for /api and JSON-preferring clients so they never get HTML)
-    if (typeof errorPages.serverError === 'string' && !preferJsonErrorResponse(req)) {
+    // Custom or auto-discovered 500 template (pre-resolved at startup)
+    const serverErrorTemplate = resolved500Template;
+
+    if (serverErrorTemplate && !preferJsonErrorResponse(req)) {
       try {
-        const html = nunjucksEnv.render(errorPages.serverError, ctx);
+        const html = nunjucksEnv.render(serverErrorTemplate, ctx);
         return res.send(html);
       } catch (e) {
         console.error('Error rendering 500 template:', e);

package/templates/skills/webspresso-usage/REFERENCE-framework.md

@@ -53,7 +53,7 @@ project/
 | `db` | DB instance from `createDatabase()` → **`ctx.db`** in `load`, `meta`, plugins |
 | `middlewares` | Named map; reference by string in route/API config (`middleware: ['auth']`) |
 | `plugins` | Array of plugin factories/objects |
-| `errorPages` | `{ notFound, serverError, timeout }` — function or template path. File-based SSR/API errors are passed to this Express error middleware via `next(err)`. **`serverError` / `timeout` as a template path** is not used for paths under **`/api`** (those get default JSON). |
+| `errorPages` | `{ notFound?: string \| Function, serverError?: string \| Function, timeout?: string \| Function }` — Nunjucks template path (e.g. `notFound: '404.njk'`, relative to `viewsDir`) or Express handler fn `(req, res, ctx) => ...`. Template context receives `{ fsy, locale, isDev, url, method }` (and `{ error, status }` for 500). File-based SSR/API errors are passed to this Express error middleware via `next(err)`. **`serverError` / `timeout` as a template path** is not used for paths under **`/api`** (those get default JSON). |
 | `timeout` | e.g. `'30s'` or `false` |
 | `helmet` | `true` / `false` / object |
 | `assets` | `{ version, manifestPath, prefix }` for `fsy.asset` / `fsy.css` / `fsy.js` |
@@ -160,7 +160,7 @@ Available in all Nunjucks templates:
 - **Request:** `fsy.q`, `fsy.param`, `fsy.hdr`
 - **Utils:** `fsy.slugify`, `fsy.truncate`, `fsy.prettyBytes`, `fsy.prettyMs`
 - **Dates:** `fsy.date`, `fsy.dateFormat`, `fsy.dateFromNow`, `fsy.dateDiff`, …
-- **Assets:** `fsy.asset`, `fsy.css`, `fsy.js`, `fsy.img` (with `assets` config)
+- **Assets & Versioning:** `fsy.asset(path)` (returns versioned `?v=...` or Vite/Webpack manifest resolved URL), `fsy.css(href, attrs)` (generates `<link>` tag), `fsy.js(src, attrs)` (generates `<script>` tag with boolean attributes), `fsy.img(src, alt, attrs)` (generates `<img>` tag). Configured via `createApp({ assets: { version, manifestPath, prefix } })`.
 - **Dev:** `fsy.isDev()`
 - **SEO:** `fsy.jsonld`