npm - webspresso - Versions diffs - 0.0.27 → 0.0.28 - Mend

webspresso 0.0.27 → 0.0.28

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.md CHANGED Viewed

@@ -318,7 +318,10 @@ const { app } = createApp({
     },
     // Option 2: Template path (rendered with Nunjucks)
-    serverError: 'errors/500.njk'
+    serverError: 'errors/500.njk',
+    // Timeout error page (503)
+    timeout: 'errors/503.njk'
   }
 });
 ```
@@ -326,6 +329,20 @@ const { app } = createApp({
 Error templates receive these variables:
 - `404.njk`: `{ url, method }`
 - `500.njk`: `{ error, status, isDev }`
+- `503.njk`: `{ url, method, isDev }`
+**Request Timeout:**
+Configure request timeout with `connect-timeout`:
+```javascript
+const { app } = createApp({
+  pagesDir: './pages',
+  timeout: '30s',  // Default: 30 seconds
+  // timeout: '1m',  // 1 minute
+  // timeout: false, // Disable timeout
+});
+```
 **Asset Management:**
@@ -455,9 +472,37 @@ Options:
 **Sitemap Plugin:**
 - Generates `/sitemap.xml` from routes automatically
+- **Dynamic Database Content**: Generate URLs from database records
 - Excludes dynamic routes and API endpoints
 - Supports i18n with hreflang tags
 - Generates `/robots.txt`
+- Configurable caching for performance
+```javascript
+sitemapPlugin({
+  hostname: 'https://example.com',
+  db, // Database instance
+  dynamicSources: [
+    {
+      model: 'Post',                    // Model name
+      urlPattern: '/blog/:slug',        // URL pattern
+      lastmodField: 'updated_at',       // Field for lastmod
+      filter: (r) => r.published,       // Filter records
+      priority: 0.9,
+    },
+    {
+      // Custom query function
+      query: async (db) => {
+        return db.getRepository('Product')
+          .query()
+          .where('active', true)
+          .list();
+      },
+      urlPattern: '/products/:slug',
+    },
+  ],
+})
+```
 **Analytics Plugin:**
 - Google Analytics (GA4) and Google Ads
@@ -544,6 +589,84 @@ function myPluginFactory(options = {}) {
 }
 ```
+### Script Injection
+Plugins can inject content into templates dynamically:
+```javascript
+const myPlugin = {
+  name: 'my-plugin',
+  version: '1.0.0',
+  register(ctx) {
+    // Inject into <head> section
+    ctx.injectHead('<meta name="my-plugin" content="enabled">', { priority: 10 });
+    // Inject at end of <body>
+    ctx.injectBody('<script src="/my-plugin.js"></script>');
+    // Inject CSS styles
+    ctx.injectStyle(`
+      .my-plugin-widget { display: block; }
+    `);
+    // Register link for dev toolbar
+    ctx.registerDevLink({
+      name: 'My Plugin',
+      path: '/my-plugin',
+      icon: '🔌',
+      description: 'My plugin dashboard'
+    });
+  }
+};
+```
+**Template Usage:**
+```njk
+<head>
+  {# Injected head content from plugins #}
+  {{ fsy.injectHead() | safe }}
+</head>
+<body>
+  ...
+  {# Injected body content from plugins #}
+  {{ fsy.injectBody() | safe }}
+  {# Dev toolbar (only in development) #}
+  {{ fsy.devToolbar() | safe }}
+</body>
+```
+### Dev Toolbar
+A development toolbar appears at the bottom of pages in development mode:
+- **Quick Links**: Dashboard, Admin Panel, Schema Explorer
+- **Plugin Links**: Plugins can register custom links
+- **Hover to Expand**: Minimized by default, expands on hover
+- **Auto-hidden**: Not shown in production mode
+```javascript
+// Register custom link from plugin
+ctx.registerDevLink({
+  name: 'API Docs',
+  path: '/docs/api',
+  icon: '📚',
+  description: 'API Documentation'
+});
+```
+**Custom Links in Templates:**
+```njk
+{{ fsy.devToolbar({
+  customLinks: [
+    { name: 'Logs', path: '/logs', icon: '📋' }
+  ]
+}) | safe }}
+```
 ## File-Based Routing
 ### SSR Pages

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "webspresso",
-  "version": "0.0.27",
+  "version": "0.0.28",
   "description": "Minimal, production-ready SSR framework for Node.js with file-based routing, Nunjucks templating, built-in i18n, and CLI tooling",
   "main": "index.js",
   "bin": {

package/plugins/sitemap.js CHANGED Viewed

@@ -1,6 +1,6 @@
 /**
  * Webspresso Sitemap Plugin
- * Generates XML sitemap from registered routes
+ * Generates XML sitemap from registered routes with dynamic database support
  */
 const { matchPattern } = require('../src/plugin-manager');
@@ -18,6 +18,40 @@ function escapeXml(str) {
     .replace(/'/g, '&apos;');
 }
+/**
+ * Format date to ISO string for sitemap
+ */
+function formatLastmod(date) {
+  if (!date) return null;
+  const d = date instanceof Date ? date : new Date(date);
+  if (isNaN(d.getTime())) return null;
+  return d.toISOString().split('T')[0]; // YYYY-MM-DD format
+}
+/**
+ * Replace URL pattern placeholders with values
+ * @param {string} pattern - URL pattern (e.g., '/blog/:slug' or '/posts/[id]')
+ * @param {Object} record - Record with values
+ * @param {Object} fieldMapping - Mapping of param names to field names
+ */
+function buildUrlFromPattern(pattern, record, fieldMapping = {}) {
+  let url = pattern;
+  // Handle :param style
+  url = url.replace(/:(\w+)/g, (match, param) => {
+    const field = fieldMapping[param] || param;
+    return record[field] !== undefined ? encodeURIComponent(record[field]) : match;
+  });
+  // Handle [param] style
+  url = url.replace(/\[(\w+)\]/g, (match, param) => {
+    const field = fieldMapping[param] || param;
+    return record[field] !== undefined ? encodeURIComponent(record[field]) : match;
+  });
+  return url;
+}
 /**
  * Generate sitemap XML content
  */
@@ -76,6 +110,20 @@ function generateRobotsTxt(hostname, options = {}) {
   return txt;
 }
+/**
+ * @typedef {Object} DynamicSource
+ * @property {string} [model] - Model name to query from database
+ * @property {Function} [query] - Custom query function: (db) => Promise<Array>
+ * @property {string} urlPattern - URL pattern with placeholders (e.g., '/blog/:slug' or '/posts/[id]')
+ * @property {Object} [fields] - Field mapping { urlParam: recordField }
+ * @property {string} [lastmodField] - Field name for lastmod date
+ * @property {string} [changefreq] - Change frequency for these URLs
+ * @property {number} [priority] - Priority for these URLs (0.0 - 1.0)
+ * @property {boolean} [i18n] - Enable i18n for these URLs (default: true)
+ * @property {Function} [filter] - Filter function: (record) => boolean
+ * @property {Function} [transform] - Transform function: (record) => record
+ */
 /**
  * Create the sitemap plugin
  * @param {Object} options - Plugin options
@@ -87,6 +135,8 @@ function generateRobotsTxt(hostname, options = {}) {
  * @param {Array<string>} options.locales - Supported locales (defaults to env SUPPORTED_LOCALES)
  * @param {boolean} options.robots - Generate robots.txt endpoint
  * @param {Array<string>} options.robotsDisallow - Paths to disallow in robots.txt
+ * @param {Array<DynamicSource>} options.dynamicSources - Dynamic URL sources from database
+ * @param {Object} options.db - Database instance for dynamic queries
  */
 function sitemapPlugin(options = {}) {
   const {
@@ -97,16 +147,172 @@ function sitemapPlugin(options = {}) {
     i18n = false,
     locales = (process.env.SUPPORTED_LOCALES || 'en').split(','),
     robots = true,
-    robotsDisallow = []
+    robotsDisallow = [],
+    dynamicSources = [],
+    db = null
   } = options;
   // Storage for dynamic URLs and exclusions
   const dynamicUrls = [];
   const dynamicExclusions = [...exclude];
+  const registeredSources = [...dynamicSources];
+  // Cached URLs (for dynamic sources)
+  let cachedUrls = null;
+  let cacheTime = null;
+  const cacheMaxAge = options.cacheMaxAge || 5 * 60 * 1000; // 5 minutes default
+  /**
+   * Fetch URLs from dynamic sources
+   */
+  async function fetchDynamicSourceUrls(dbInstance) {
+    const urls = [];
+    for (const source of registeredSources) {
+      try {
+        let records = [];
+        // Get records from model or custom query
+        if (source.query && typeof source.query === 'function') {
+          records = await source.query(dbInstance);
+        } else if (source.model && dbInstance) {
+          const repo = dbInstance.getRepository(source.model);
+          if (repo) {
+            records = await repo.findAll();
+          }
+        }
+        // Apply filter if provided
+        if (source.filter && typeof source.filter === 'function') {
+          records = records.filter(source.filter);
+        }
+        // Transform records to URLs
+        for (let record of records) {
+          // Apply transform if provided
+          if (source.transform && typeof source.transform === 'function') {
+            record = source.transform(record);
+          }
+          const path = buildUrlFromPattern(
+            source.urlPattern,
+            record,
+            source.fields || {}
+          );
+          // Get lastmod from record if field specified
+          let lastmod = null;
+          if (source.lastmodField && record[source.lastmodField]) {
+            lastmod = formatLastmod(record[source.lastmodField]);
+          }
+          urls.push({
+            path,
+            changefreq: source.changefreq || changefreq,
+            priority: source.priority || priority,
+            lastmod,
+            i18n: source.i18n !== false,
+            _source: source.model || 'custom'
+          });
+        }
+      } catch (err) {
+        console.error(`Sitemap: Error fetching from source ${source.model || 'custom'}:`, err.message);
+      }
+    }
+    return urls;
+  }
+  /**
+   * Build all sitemap URLs
+   */
+  async function buildAllUrls(routes, dbInstance) {
+    const urls = [];
+    const hostnameNormalized = hostname.replace(/\/$/, '');
+    // Filter static routes for sitemap
+    const sitemapRoutes = routes
+      .filter(r => r.type === 'ssr')
+      .filter(r => !r.isDynamic) // Exclude dynamic routes (they come from dynamicSources)
+      .filter(r => {
+        // Check exclusion patterns
+        for (const pattern of dynamicExclusions) {
+          if (matchPattern(r.pattern, pattern)) {
+            return false;
+          }
+        }
+        return true;
+      });
+    // Add static route URLs
+    for (const route of sitemapRoutes) {
+      const baseUrl = `${hostnameNormalized}${route.pattern}`;
+      const urlEntry = {
+        loc: baseUrl,
+        changefreq,
+        priority
+      };
+      // Add i18n alternates
+      if (i18n && locales.length > 1) {
+        urlEntry.alternates = locales.map(lang => ({
+          lang,
+          href: `${baseUrl}${baseUrl.includes('?') ? '&' : '?'}lang=${lang}`
+        }));
+      }
+      urls.push(urlEntry);
+    }
+    // Add manually added dynamic URLs
+    for (const dynUrl of dynamicUrls) {
+      const urlEntry = {
+        loc: `${hostnameNormalized}${dynUrl.path}`,
+        changefreq: dynUrl.changefreq || changefreq,
+        priority: dynUrl.priority || priority,
+        lastmod: dynUrl.lastmod
+      };
+      if (i18n && locales.length > 1 && dynUrl.i18n !== false) {
+        urlEntry.alternates = locales.map(lang => ({
+          lang,
+          href: `${urlEntry.loc}${urlEntry.loc.includes('?') ? '&' : '?'}lang=${lang}`
+        }));
+      }
+      urls.push(urlEntry);
+    }
+    // Fetch URLs from dynamic sources (database or custom queries)
+    if (registeredSources.length > 0) {
+      const sourceUrls = await fetchDynamicSourceUrls(dbInstance);
+      for (const dynUrl of sourceUrls) {
+        const urlEntry = {
+          loc: `${hostnameNormalized}${dynUrl.path}`,
+          changefreq: dynUrl.changefreq,
+          priority: dynUrl.priority,
+          lastmod: dynUrl.lastmod
+        };
+        if (i18n && locales.length > 1 && dynUrl.i18n !== false) {
+          urlEntry.alternates = locales.map(lang => ({
+            lang,
+            href: `${urlEntry.loc}${urlEntry.loc.includes('?') ? '&' : '?'}lang=${lang}`
+          }));
+        }
+        urls.push(urlEntry);
+      }
+    }
+    return urls;
+  }
   return {
     name: 'sitemap',
-    version: '1.0.0',
+    version: '2.0.0',
     _options: options,
     /**
@@ -120,6 +326,7 @@ function sitemapPlugin(options = {}) {
        */
       addUrl(path, opts = {}) {
         dynamicUrls.push({ path, ...opts });
+        cachedUrls = null; // Invalidate cache
       },
       /**
@@ -128,13 +335,41 @@ function sitemapPlugin(options = {}) {
        */
       exclude(pattern) {
         dynamicExclusions.push(pattern);
+        cachedUrls = null; // Invalidate cache
       },
       /**
-       * Get all sitemap URLs
+       * Add a dynamic source for URLs from database
+       * @param {DynamicSource} source - Dynamic source configuration
+       */
+      addDynamicSource(source) {
+        if (!source.urlPattern) {
+          throw new Error('urlPattern is required for dynamic source');
+        }
+        registeredSources.push(source);
+        cachedUrls = null; // Invalidate cache
+      },
+      /**
+       * Get all manually added URLs
        */
       getUrls() {
         return [...dynamicUrls];
+      },
+      /**
+       * Get all registered dynamic sources
+       */
+      getDynamicSources() {
+        return [...registeredSources];
+      },
+      /**
+       * Invalidate URL cache (useful after database changes)
+       */
+      invalidateCache() {
+        cachedUrls = null;
+        cacheTime = null;
       }
     },
@@ -142,66 +377,39 @@ function sitemapPlugin(options = {}) {
      * Called after routes are mounted
      */
     onRoutesReady(ctx) {
-      // Filter routes for sitemap
-      const sitemapRoutes = ctx.routes
-        .filter(r => r.type === 'ssr')
-        .filter(r => !r.isDynamic) // Exclude dynamic routes
-        .filter(r => {
-          // Check exclusion patterns
-          for (const pattern of dynamicExclusions) {
-            if (matchPattern(r.pattern, pattern)) {
-              return false;
-            }
-          }
-          return true;
-        });
-      // Build URLs
-      const urls = [];
+      const dbInstance = db || ctx.options?.db;
-      for (const route of sitemapRoutes) {
-        const baseUrl = `${hostname.replace(/\/$/, '')}${route.pattern}`;
-        const urlEntry = {
-          loc: baseUrl,
-          changefreq,
-          priority
-        };
-        // Add i18n alternates
-        if (i18n && locales.length > 1) {
-          urlEntry.alternates = locales.map(lang => ({
-            lang,
-            href: `${baseUrl}${baseUrl.includes('?') ? '&' : '?'}lang=${lang}`
-          }));
-        }
-        urls.push(urlEntry);
-      }
-      // Add dynamic URLs
-      for (const dynUrl of dynamicUrls) {
-        const urlEntry = {
-          loc: `${hostname.replace(/\/$/, '')}${dynUrl.path}`,
-          changefreq: dynUrl.changefreq || changefreq,
-          priority: dynUrl.priority || priority,
-          lastmod: dynUrl.lastmod
-        };
-        if (i18n && locales.length > 1 && dynUrl.i18n !== false) {
-          urlEntry.alternates = locales.map(lang => ({
-            lang,
-            href: `${urlEntry.loc}${urlEntry.loc.includes('?') ? '&' : '?'}lang=${lang}`
+      // Register sitemap route (async handler for dynamic sources)
+      ctx.addRoute('get', '/sitemap.xml', async (req, res) => {
+        try {
+          // Check cache
+          const now = Date.now();
+          if (cachedUrls && cacheTime && (now - cacheTime) < cacheMaxAge) {
+            res.type('application/xml');
+            return res.send(generateSitemapXml(cachedUrls, {
+              hostname,
+              defaultChangefreq: changefreq,
+              defaultPriority: priority
+            }));
+          }
+          // Build URLs
+          const urls = await buildAllUrls(ctx.routes, dbInstance);
+          // Cache results
+          cachedUrls = urls;
+          cacheTime = now;
+          res.type('application/xml');
+          res.send(generateSitemapXml(urls, {
+            hostname,
+            defaultChangefreq: changefreq,
+            defaultPriority: priority
           }));
+        } catch (err) {
+          console.error('Sitemap generation error:', err);
+          res.status(500).send('Error generating sitemap');
         }
-        urls.push(urlEntry);
-      }
-      // Register sitemap route
-      ctx.addRoute('get', '/sitemap.xml', (req, res) => {
-        res.type('application/xml');
-        res.send(generateSitemapXml(urls, { hostname, defaultChangefreq: changefreq, defaultPriority: priority }));
       });
       // Register robots.txt route
@@ -215,6 +423,13 @@ function sitemapPlugin(options = {}) {
   };
 }
+// Export helpers for testing
+sitemapPlugin.escapeXml = escapeXml;
+sitemapPlugin.formatLastmod = formatLastmod;
+sitemapPlugin.buildUrlFromPattern = buildUrlFromPattern;
+sitemapPlugin.generateSitemapXml = generateSitemapXml;
+sitemapPlugin.generateRobotsTxt = generateRobotsTxt;
 module.exports = sitemapPlugin;

package/src/helpers.js CHANGED Viewed

@@ -581,10 +581,379 @@ function createHelpers(ctx) {
     dateEndOf(date, unit = 'day') {
       if (!date) return dayjs();
       return dayjs(date).endOf(unit);
+    },
+    // ============================================
+    // Script Injection Helpers
+    // ============================================
+    /**
+     * Get injected head content
+     * @returns {string} HTML content for head section
+     */
+    injectHead() {
+      const injector = getScriptInjector();
+      let content = '';
+      // Add styles
+      const styles = injector.getStylesContent();
+      if (styles) {
+        content += `<style id="webspresso-injected-styles">\n${styles}\n</style>\n`;
+      }
+      // Add head scripts
+      content += injector.getHeadContent();
+      return content;
+    },
+    /**
+     * Get injected body content (for end of body)
+     * @returns {string} HTML content for body end
+     */
+    injectBody() {
+      return getScriptInjector().getBodyContent();
+    },
+    /**
+     * Get dev toolbar HTML (only in development mode)
+     * @param {Object} options - { plugins: Array, customLinks: Array }
+     * @returns {string} Dev toolbar HTML
+     */
+    devToolbar(options = {}) {
+      const injector = getScriptInjector();
+      const registeredPlugins = injector.getPlugins();
+      return generateDevToolbar({
+        ...options,
+        plugins: [...registeredPlugins, ...(options.plugins || [])]
+      });
+    },
+    /**
+     * Get the script injector instance for advanced usage
+     * @returns {ScriptInjector}
+     */
+    getInjector() {
+      return getScriptInjector();
     }
   };
 }
+/**
+ * Script Injector - manages script/style injection for templates
+ */
+class ScriptInjector {
+  constructor() {
+    this.headScripts = [];
+    this.bodyScripts = [];
+    this.styles = [];
+    this.plugins = [];
+  }
+  /**
+   * Add content to head section
+   * @param {string} content - HTML/script content
+   * @param {Object} options - { priority: number, id: string }
+   */
+  addHead(content, options = {}) {
+    this.headScripts.push({
+      content,
+      priority: options.priority || 0,
+      id: options.id || null
+    });
+  }
+  /**
+   * Add content to body end section
+   * @param {string} content - HTML/script content
+   * @param {Object} options - { priority: number, id: string }
+   */
+  addBody(content, options = {}) {
+    this.bodyScripts.push({
+      content,
+      priority: options.priority || 0,
+      id: options.id || null
+    });
+  }
+  /**
+   * Add CSS styles
+   * @param {string} css - CSS content
+   * @param {Object} options - { id: string }
+   */
+  addStyle(css, options = {}) {
+    this.styles.push({
+      content: css,
+      id: options.id || null
+    });
+  }
+  /**
+   * Register a plugin for dev toolbar
+   * @param {Object} plugin - { name, path, icon, description }
+   */
+  registerPlugin(plugin) {
+    this.plugins.push(plugin);
+  }
+  /**
+   * Get head content sorted by priority
+   */
+  getHeadContent() {
+    const sorted = [...this.headScripts].sort((a, b) => b.priority - a.priority);
+    return sorted.map(s => s.content).join('\n');
+  }
+  /**
+   * Get body content sorted by priority
+   */
+  getBodyContent() {
+    const sorted = [...this.bodyScripts].sort((a, b) => b.priority - a.priority);
+    return sorted.map(s => s.content).join('\n');
+  }
+  /**
+   * Get styles content
+   */
+  getStylesContent() {
+    return this.styles.map(s => s.content).join('\n');
+  }
+  /**
+   * Get registered plugins
+   */
+  getPlugins() {
+    return [...this.plugins];
+  }
+  /**
+   * Clear all injections
+   */
+  clear() {
+    this.headScripts = [];
+    this.bodyScripts = [];
+    this.styles = [];
+  }
+}
+// Global script injector instance
+let globalInjector = new ScriptInjector();
+/**
+ * Get or create the global script injector
+ */
+function getScriptInjector() {
+  return globalInjector;
+}
+/**
+ * Reset the global script injector (useful for testing)
+ */
+function resetScriptInjector() {
+  globalInjector = new ScriptInjector();
+  return globalInjector;
+}
+/**
+ * Generate dev toolbar HTML
+ * @param {Object} options - { plugins: Array, routes: Array }
+ */
+function generateDevToolbar(options = {}) {
+  const { plugins = [], customLinks = [] } = options;
+  const isDev = process.env.NODE_ENV !== 'production';
+  if (!isDev) return '';
+  // Default plugin links
+  const defaultPlugins = [
+    { name: 'Dashboard', path: '/_webspresso', icon: '📊', description: 'Development Dashboard' },
+    { name: 'Admin', path: '/_admin', icon: '⚙️', description: 'Admin Panel' },
+    { name: 'Schema', path: '/_schema', icon: '🗂️', description: 'Schema Explorer' },
+  ];
+  const allPlugins = [...defaultPlugins, ...plugins, ...customLinks];
+  const toolbarStyles = `
+    <style id="webspresso-dev-toolbar-styles">
+      #webspresso-dev-toolbar {
+        position: fixed;
+        bottom: 0;
+        left: 0;
+        right: 0;
+        background: linear-gradient(135deg, #1a1a2e 0%, #16213e 100%);
+        border-top: 1px solid #0f3460;
+        padding: 0;
+        z-index: 99999;
+        font-family: 'SF Mono', 'Monaco', 'Inconsolata', monospace;
+        font-size: 12px;
+        transform: translateY(calc(100% - 32px));
+        transition: transform 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+      }
+      #webspresso-dev-toolbar:hover,
+      #webspresso-dev-toolbar.expanded {
+        transform: translateY(0);
+      }
+      #webspresso-dev-toolbar-toggle {
+        position: absolute;
+        top: -24px;
+        left: 50%;
+        transform: translateX(-50%);
+        background: linear-gradient(135deg, #1a1a2e 0%, #16213e 100%);
+        border: 1px solid #0f3460;
+        border-bottom: none;
+        border-radius: 8px 8px 0 0;
+        padding: 4px 16px;
+        cursor: pointer;
+        color: #e94560;
+        font-weight: 600;
+        font-size: 10px;
+        letter-spacing: 1px;
+        text-transform: uppercase;
+      }
+      #webspresso-dev-toolbar-header {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        padding: 8px 16px;
+        border-bottom: 1px solid #0f3460;
+        background: rgba(0,0,0,0.2);
+      }
+      #webspresso-dev-toolbar-brand {
+        display: flex;
+        align-items: center;
+        gap: 8px;
+        color: #e94560;
+        font-weight: 700;
+        font-size: 11px;
+        letter-spacing: 0.5px;
+      }
+      #webspresso-dev-toolbar-brand svg {
+        width: 16px;
+        height: 16px;
+      }
+      #webspresso-dev-toolbar-info {
+        color: #a1a1aa;
+        font-size: 10px;
+      }
+      #webspresso-dev-toolbar-content {
+        display: flex;
+        align-items: stretch;
+        gap: 0;
+        padding: 0;
+        overflow-x: auto;
+      }
+      .webspresso-dev-toolbar-section {
+        display: flex;
+        align-items: center;
+        gap: 4px;
+        padding: 12px 16px;
+        border-right: 1px solid #0f3460;
+      }
+      .webspresso-dev-toolbar-section:last-child {
+        border-right: none;
+      }
+      .webspresso-dev-toolbar-section-title {
+        color: #a1a1aa;
+        font-size: 9px;
+        text-transform: uppercase;
+        letter-spacing: 1px;
+        margin-right: 8px;
+      }
+      .webspresso-dev-toolbar-link {
+        display: flex;
+        align-items: center;
+        gap: 6px;
+        padding: 6px 12px;
+        background: rgba(233, 69, 96, 0.1);
+        border: 1px solid rgba(233, 69, 96, 0.2);
+        border-radius: 6px;
+        color: #f1f1f1;
+        text-decoration: none;
+        transition: all 0.2s ease;
+        white-space: nowrap;
+      }
+      .webspresso-dev-toolbar-link:hover {
+        background: rgba(233, 69, 96, 0.2);
+        border-color: #e94560;
+        color: #fff;
+        transform: translateY(-1px);
+      }
+      .webspresso-dev-toolbar-link-icon {
+        font-size: 14px;
+      }
+      .webspresso-dev-toolbar-link-text {
+        font-weight: 500;
+      }
+      .webspresso-dev-toolbar-close {
+        background: none;
+        border: none;
+        color: #a1a1aa;
+        cursor: pointer;
+        padding: 4px 8px;
+        font-size: 16px;
+        transition: color 0.2s;
+      }
+      .webspresso-dev-toolbar-close:hover {
+        color: #e94560;
+      }
+      @media (max-width: 768px) {
+        #webspresso-dev-toolbar {
+          font-size: 11px;
+        }
+        .webspresso-dev-toolbar-link {
+          padding: 4px 8px;
+        }
+      }
+    </style>
+  `;
+  const pluginLinks = allPlugins.map(p => `
+    <a href="${p.path}" class="webspresso-dev-toolbar-link" title="${p.description || p.name}">
+      <span class="webspresso-dev-toolbar-link-icon">${p.icon || '🔗'}</span>
+      <span class="webspresso-dev-toolbar-link-text">${p.name}</span>
+    </a>
+  `).join('');
+  const toolbarHtml = `
+    ${toolbarStyles}
+    <div id="webspresso-dev-toolbar">
+      <div id="webspresso-dev-toolbar-toggle">⚡ DEV</div>
+      <div id="webspresso-dev-toolbar-header">
+        <div id="webspresso-dev-toolbar-brand">
+          <svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+            <path d="M12 2L2 7L12 12L22 7L12 2Z" fill="currentColor" opacity="0.3"/>
+            <path d="M2 17L12 22L22 17" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+            <path d="M2 12L12 17L22 12" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+          </svg>
+          WEBSPRESSO DEV
+        </div>
+        <div id="webspresso-dev-toolbar-info">
+          Node ${process.version} | ${new Date().toLocaleTimeString()}
+        </div>
+      </div>
+      <div id="webspresso-dev-toolbar-content">
+        <div class="webspresso-dev-toolbar-section">
+          <span class="webspresso-dev-toolbar-section-title">Quick Links</span>
+          ${pluginLinks}
+        </div>
+      </div>
+    </div>
+    <script>
+      (function() {
+        const toolbar = document.getElementById('webspresso-dev-toolbar');
+        const toggle = document.getElementById('webspresso-dev-toolbar-toggle');
+        if (toolbar && toggle) {
+          toggle.addEventListener('click', function() {
+            toolbar.classList.toggle('expanded');
+          });
+        }
+      })();
+    </script>
+  `;
+  return toolbarHtml;
+}
 /**
  * Pure utility functions (can be used without request context)
  */
@@ -637,6 +1006,10 @@ module.exports = {
   utils,
   AssetManager,
   configureAssets,
-  getAssetManager
+  getAssetManager,
+  ScriptInjector,
+  getScriptInjector,
+  resetScriptInjector,
+  generateDevToolbar
 };

package/src/plugin-manager.js CHANGED Viewed

@@ -333,6 +333,8 @@ class PluginManager {
    */
   _createPluginContext(plugin, context) {
     const self = this;
+    // Import script injector
+    const { getScriptInjector } = require('./helpers');
     return {
       app: context.app,
@@ -372,6 +374,52 @@ class PluginManager {
        */
       get routes() {
         return self.routes;
+      },
+      // ============================================
+      // Script Injection API
+      // ============================================
+      /**
+       * Inject content into head section
+       * @param {string} content - HTML/script content
+       * @param {Object} options - { priority: number, id: string }
+       */
+      injectHead(content, options = {}) {
+        getScriptInjector().addHead(content, options);
+      },
+      /**
+       * Inject content into body end section
+       * @param {string} content - HTML/script content
+       * @param {Object} options - { priority: number, id: string }
+       */
+      injectBody(content, options = {}) {
+        getScriptInjector().addBody(content, options);
+      },
+      /**
+       * Inject CSS styles
+       * @param {string} css - CSS content
+       * @param {Object} options - { id: string }
+       */
+      injectStyle(css, options = {}) {
+        getScriptInjector().addStyle(css, options);
+      },
+      /**
+       * Register a link for the dev toolbar
+       * @param {Object} link - { name, path, icon, description }
+       */
+      registerDevLink(link) {
+        getScriptInjector().registerPlugin(link);
+      },
+      /**
+       * Get the script injector instance for advanced usage
+       */
+      getScriptInjector() {
+        return getScriptInjector();
       }
     };
   }