webspresso 0.0.101 → 0.0.103

package/.agents/AGENTS.md

@@ -38,7 +38,7 @@ Every coding agent working on Webspresso **MUST** follow this 4-step execution d
 This `.agents/` customization root is organized into modular topic guides:
 
 1. **[File-Based Routing & API Routes](.agents/ROUTING.md)** — File-based page routes (`pages/`), method-suffixed API routes (`pages/api/*.get.js`, `*.post.js`), parameter brackets (`[id]`), Zod request schemas, and the strict prohibition of manual `routes/` directories or `app.get()`.
-2. **[Architecture & Structure](.agents/ARCHITECTURE.md)** — File-based routing (`pages/`), Asset Management & Versioning (`AssetManager`, `fsy.asset`), ORM models & `zdb` schemas (`core/orm`), Mithril.js Admin Panel SPA (`plugins/admin-panel`), and Plugin Ecosystem.
+2. **[Architecture & Structure](.agents/ARCHITECTURE.md)** — File-based routing (`pages/`), Cold Start & AOT Optimizations (`discoverAppRoutes`, `lazyRoutes: true`, `routes.manifest.json`, `templates.compiled.js`, `lazyPlugin`), Asset Management & Versioning (`AssetManager`, `fsy.asset`), ORM models & `zdb` schemas (`core/orm`), Mithril.js Admin Panel SPA (`plugins/admin-panel`), and Plugin Ecosystem.
 3. **[Services Layer](.agents/SERVICES.md)** — File-based auto-discovery (`services/`), Zod validation, declarative `auth` & RBAC guards, automatic ACID transaction propagation (`transaction: true`), timeouts, and memoization.
 4. **[Exceptions & Error Handling](.agents/ERRORS.md)** — Django-inspired framework exception hierarchy (`WebspressoError`, `HttpError`, `ValidationError`, `SecurityError`, `RequestAbortedError`), central error boundary, `app.setErrorHandler()`, and production error masking.
 5. **[Graceful Shutdown & Lifecycle](.agents/SHUTDOWN.md)** — `ShutdownManager`, `NodeHttpAdapter`, connection draining, force close mode, and reverse-order plugin disposer cleanup.

package/.agents/ARCHITECTURE.md

@@ -23,6 +23,12 @@
   - Discovered routes are compiled and sorted in deterministic priority order: Static $\to$ Deep Dynamic $\to$ Shallow Dynamic $\to$ Catch-All (`*`).
   - Detects `METHOD + PATH` collision conflicts at startup and throws descriptive errors.
   - Inspectable via `app.routes.list()` for CLI tools, documentation generation, and debugging.
+- **High-Performance Architecture & Cold-Start Optimization**:
+  - **Single-Pass Unified Route Discovery (`discoverAppRoutes`)**: Discovers Page routes, API routes, and Route Groups in a single filesystem traversal pass, avoiding redundant tree walks during startup.
+  - **Dev-Mode On-Demand (JIT) Route Evaluation (`lazyRoutes: true`)**: In development (`NODE_ENV !== 'production'`), route handler modules (`pages/**/*.js`) are loaded on first incoming HTTP request instead of eager-evaluating all routes at boot, reducing dev boot time to ~15ms on large projects.
+  - **AOT Route Manifest (`webspresso build` & `routesManifest`)**: Production builds generate `.webspresso/routes.manifest.json`. When present (or configured via `createApp({ routesManifest: true })`), zero directory scanning or route sorting occurs at runtime.
+  - **AOT Nunjucks Template Precompilation (`precompileTemplates` & `precompiledTemplates`)**: `webspresso build` compiles all `.njk` templates in `pages/` and `views/` into `.webspresso/templates.compiled.js`. In production, templates execute without runtime parser/AST generation or disk reads.
+  - **On-Demand Lazy Plugins (`lazyPlugin`, `defineLazyPlugin`)**: Heavy plugins (e.g. `adminPanelPlugin({ lazy: true })`, `fileManagerPlugin({ lazy: true })`) mount Express proxy routers and hydrate in memory only when a matching HTTP request or service call arrives.
 - **Templating & Helpers**: Nunjucks (`.njk`) templates rendered with layouts (e.g. `views/layout.njk`). Access helpers via `fsy` object in templates.
 - **Asset Management & Cache-Busting (`assets`, `AssetManager`, `fsy`)**:
   - Configured via `createApp({ assets: { version, manifestPath, prefix, publicDir } })` or `configureAssets()`.
@@ -115,6 +121,11 @@ Plugins expose `name`, `version`, `dependencies`, and lifecycle hooks (`register
 | `restResourcePlugin` | ORM / REST API | Auto RESTful CRUD endpoints from models with eager loading & sanitization |
 | `xlsxPlugin` | Excel / Export | Excel spreadsheet generation, parsing, ORM streaming export (`res.xlsx`), and services |
 | `csvPlugin` | CSV / Export | RFC 4180 CSV generator, parser, Excel UTF-8 BOM, streaming writer (`res.csv`), and services |
+| `lazyPlugin` | Core / Performance | On-demand plugin hydration wrapper deferring plugin setup until first request/call |
+
+- **On-Demand Lazy Plugins (`lazyPlugin`, `defineLazyPlugin`)**:
+  - Wrap any plugin via `lazyPlugin(() => heavyPlugin(), { prefix: '/path', services: ['service.name'] })`.
+  - Built-in shorthand support on resource-heavy plugins: `adminPanelPlugin({ db, lazy: true })` and `fileManagerPlugin({ lazy: true })`.
 
 ---
 

package/.agents/CONVENTIONS.md

@@ -44,3 +44,7 @@
    - **ALWAYS** use published `package.json` export paths: `require('webspresso/core/auth')`, `require('webspresso/core/orm')`, `require('webspresso/plugins/polar/src/webhooks')`.
    - **NEVER** rely on deep relative paths from `node_modules/webspresso/...` or append `/index.js` unless documenting a pre-0.0.95 workaround.
    - Smoke test: `tests/unit/package-exports.test.js`.
+14. **Tailwind CSS v4 Standard (NO v3 PostCSS Boilerplate)**:
+   - **ALWAYS** prefer Tailwind CSS v4 using `npx webspresso add tailwind --v4` (powered by Oxide and `@tailwindcss/cli`).
+   - **ALWAYS** use CSS-first `@import "tailwindcss";` in `src/input.css` and compile to `public/css/style.css`.
+   - **NEVER** create redundant `tailwind.config.js` or `postcss.config.js` files unless custom legacy PostCSS plugins are specifically required.

package/.agents/ORM.md

@@ -51,7 +51,9 @@ import { defineModel, zdb } from 'webspresso';
 export default defineModel({
   name: 'Product',
   table: 'products',
-  schema: zdb.schema({
+  timestamps: true, // auto-injects createdAt & updatedAt into schema & scopes
+  softDelete: true, // auto-injects deletedAt & manages soft-delete scope
+  schema: {
     id: zdb.id(),
     name: zdb.string().min(2),
     slug: zdb.string().unique(),
@@ -61,9 +63,7 @@ export default defineModel({
     metadata: zdb.json({ optional: true }),
     category_id: zdb.integer(),
     active: zdb.boolean({ default: true }),
-    created_at: zdb.timestamp({ auto: 'create' }),
-    updated_at: zdb.timestamp({ auto: 'update' }),
-  }),
+  },
   relations: {
     category: { type: 'belongsTo', model: 'Category', foreignKey: 'category_id' },
     reviews: { type: 'hasMany', model: 'Review', foreignKey: 'product_id' },
@@ -81,6 +81,13 @@ export default defineModel({
 });
 ```
 
+### Automatic Timestamps & Soft Deletes (`timestamps`, `softDelete`)
+Instead of manually defining boilerplate timestamp and soft delete columns in `schema`, configure them declaratively:
+- **Top-level / Options:** `timestamps: true` (or `options: { timestamps: true }`) automatically injects `createdAt` and `updatedAt` into the Zod schema, validation rules, column map, and Knex migrations.
+- **Soft Deletes:** `softDelete: true` (or `softDeletes: true`) automatically injects `deletedAt` (nullable/optional) into the schema and activates the repository `whereNull('deletedAt')` soft-delete scope.
+- **Custom column names & snake_case:** `timestamps: { snakeCase: true }` or `timestamps: { createdAt: 'created_at', updatedAt: 'updated_at' }`, `softDelete: { deletedAt: 'deleted_at' }`.
+- **Explicit Schema Spread:** `...zdb.timestamps()` and `...zdb.softDeletes()` are also supported for explicit schema definitions.
+
 ### Supported `zdb` Data Types
 - `zdb.id()` — Primary key (BigInt / Auto-increment)
 - `zdb.string({ max, unique, optional, sortable })` — String / VarChar
@@ -90,6 +97,8 @@ export default defineModel({
 - `zdb.file()` — File asset URL / upload path (non-sortable by default)
 - `zdb.json()` — Serialized JSON column (non-sortable by default)
 - `zdb.timestamp({ auto, sortable })` — Timestamp (`auto: 'create'` / `auto: 'update'`)
+- `zdb.timestamps({ snakeCase })` — Timestamp pair (`createdAt`, `updatedAt`)
+- `zdb.softDelete()`, `zdb.softDeletes({ snakeCase })` — Soft delete timestamp (`deletedAt`)
 
 *Note: All `zdb` types support chainable `.config({ sortable: boolean })` or options object `{ sortable: boolean }`.*
 

package/.agents/PLUGINS.md

@@ -151,8 +151,9 @@ Outgoing Webhook Dispatcher and Management Plugin with zero external dependencie
 
 ### 2.4 `adminPanelPlugin` (`plugins/admin-panel`)
 Mithril.js SPA Admin Panel mounted at `/_admin`.
-- **Options**: `{ path: '/_admin', db, title: 'Webspresso Admin' }`
+- **Options**: `{ path: '/_admin', db, title: 'Webspresso Admin', lazy: false }`
 - **Features**: Auto CRUD screens for ORM models, user staff auth, custom page registration, widgets, field renderers.
+- **On-Demand Hydration (`lazy: true`)**: When set to `true`, the admin panel plugin wraps itself with `lazyPlugin()`, deferring route mounting and internal setup until the first HTTP request hits `/_admin`.
 
 ### 2.3 `contentPlugin` (`plugins/content`)
 Schema-driven headless CMS & inline content editing.
@@ -168,11 +169,12 @@ Multipart file upload manager with local / cloud storage providers.
 
 ### 2.5 `fileManagerPlugin` (`plugins/file-manager`)
 Filesystem-first media library, directory explorer, and modal asset picker for Admin Panel.
-- **Options**: `{ baseDir: './public/uploads', publicBasePath: '/uploads', apiPrefix: '/files', pageTitle: 'File Manager', maxUploadBytes: 10485760, allowedExtensions, allowedMimeTypes, includePage: true }`
+- **Options**: `{ baseDir: './public/uploads', publicBasePath: '/uploads', apiPrefix: '/files', pageTitle: 'File Manager', maxUploadBytes: 10485760, allowedExtensions, allowedMimeTypes, includePage: true, lazy: false }`
 - **Features**:
   - Directory tree navigation (breadcrumbs), safe subfolder creation (`mkdir`), item rename, delete, and move.
   - Path traversal attack protection (`resolveSafePath`).
   - Grid (thumbnail gallery) & List (table) view modes.
+  - On-demand hydration via `lazy: true`.
   - Search by filename and type filter (Images, Documents, Videos, Audio, Archives, Code).
   - Media preview modal with copy URL and direct playback/preview.
   - "Choose from Media Library" modal picker integrated with `FileUploadField` and `zdb.file()` form fields.
@@ -662,7 +664,31 @@ Zero-dependency OAuth 2.0 & Social Login plugin supporting Google, GitHub, and c
   - `fsy.oauthUrl('google')` ➔ `"/auth/google"`
   - `fsy.oauthUrl('github', { returnTo: '/dashboard' })` ➔ `"/auth/github?returnTo=%2Fdashboard"`
 
-
-
-
-
+### 2.20 `lazyPlugin` / `defineLazyPlugin` (`plugins/lazy`)
+Zero-dependency on-demand plugin hydration wrapper that defers heavy plugin initialization, route mounting, and service registration until the first matching HTTP request or service invocation.
+- **Why**: Drastically slashes application cold start time and peak memory footprint when mounting heavy modules (such as admin panels, media libraries, documentation portals, or internal diagnostic tools) that are not needed on every server startup.
+- **Usage**:
+  ```javascript
+  const { lazyPlugin, adminPanelPlugin, fileManagerPlugin } = require('webspresso/plugins');
+
+  // Option 1: Using built-in lazy option
+  adminPanelPlugin({ db, lazy: true });
+  fileManagerPlugin({ lazy: true });
+
+  // Option 2: Wrapping custom or 3rd-party plugins
+  const heavyPlugin = lazyPlugin(
+    () => require('./my-heavy-plugin')({ config: 123 }),
+    {
+      name: 'my-heavy-plugin',
+      prefix: '/heavy',            // Hydrates when request path starts with /heavy
+      services: ['heavy.process'],  // Hydrates when ctx.service('heavy.process') is called
+      helpers: ['heavyHelper'],     // Hydrates when fsy.heavyHelper() is evaluated
+      events: ['heavy.*'],          // Hydrates when matching event is dispatched
+      onHydrate: (plugin) => console.log('Plugin hydrated!'),
+    }
+  );
+  ```
+- **How It Works**:
+  - Mounts a lightweight Express router proxy at `prefix`.
+  - Stubs placeholder services into `ServiceRegistry` and proxy helpers into Nunjucks context.
+  - Intercepts incoming requests/calls, executes the plugin factory function, runs `register(ctx)` and `onRoutesReady(ctx)`, replaces proxies seamlessly with the real router/services, and forwards the initial call with zero dropped requests.

package/.agents/ROUTING.md

@@ -119,6 +119,73 @@ module.exports = {
 > [!IMPORTANT]
 > **NEVER use raw Knex queries** like `req.db('notes')` in route handlers. **ALWAYS use repositories**: `req.db.getRepository('Note')`. This guarantees schema validation, lifecycle hooks, soft deletes, and query caching are respected.
 
+### 2.1 Smart API Validation i18n & Error Translation
+
+Webspresso features built-in **Smart Dual-Layer Auto-Translation** for Zod schema validation errors with **zero runtime overhead on valid requests**.
+
+#### How It Works:
+1. **Explicit Custom Keys**: Define dictionary translation keys directly inside Zod schemas (e.g. `z.string({ message: 'auth.email_required' })` or `z.string().min(5, 'auth.password_min')`).
+2. **Dynamic Fallbacks**: If no explicit key is matched, the engine falls back to convention-based candidate keys:
+   - `validation.fields.<field>.<code/type>` (e.g., `validation.fields.email.invalid_string`)
+   - `validation.<code/type>` (e.g., `validation.too_small`, `validation.required`, `validation.invalid_string.email`)
+   - `zod.<code/type>`
+3. **Parameter Interpolation**: Dynamic schema parameters (e.g. `{{ min }}`, `{{ max }}`, `{{ expected }}`, `{{ received }}`) are automatically interpolated into translated messages or inline custom template strings.
+4. **Context Injection**: `apiCtx` provides `{ locale, t, service, db, sse }` to route handlers for immediate localized responses.
+
+#### Example Usage:
+
+```json
+// pages/locales/tr.json
+{
+  "auth": {
+    "email_required": "Lütfen geçerli bir e-posta adresi giriniz"
+  },
+  "validation": {
+    "required": "Bu alan zorunludur",
+    "too_small": "En az {{ min }} karakter olmalıdır"
+  }
+}
+```
+
+```javascript
+// pages/api/auth/register.post.js
+'use strict';
+const { defineApi } = require('webspresso');
+
+module.exports = defineApi({
+  schema: ({ z }) => ({
+    body: z.object({
+      // Explicit dictionary translation key
+      email: z.string({ message: 'auth.email_required' }).email(),
+      // Automatic fallback to validation.too_small with {{ min }} interpolation
+      password: z.string().min(8),
+    }),
+  }),
+  handler: async (req, res, { t, locale }) => {
+    // req.locale and t() are injected into handler context
+    return res.status(201).json({
+      success: true,
+      message: t('auth.registered_success', { email: req.input.body.email }),
+    });
+  },
+});
+```
+
+Client requests sending `Accept-Language: tr` or query param `?lang=tr` will automatically receive fully localized validation errors in the 400 Bad Request response:
+```json
+{
+  "error": "Validation failed",
+  "issues": [
+    {
+      "field": "password",
+      "code": "too_small",
+      "key": "validation.too_small",
+      "message": "En az 8 karakter olmalıdır"
+    }
+  ]
+}
+```
+
 ---
 
 ## 3. Dynamic Route Parameters (`[param]`)
@@ -326,7 +393,37 @@ const routeList = app.routes.list();
 // ]
 ```
 
-### 6.5 Server-Sent Events (SSE) Streaming (`res.sse`)
+### 6.5 Cold Start & High-Performance Routing Architecture
+
+Webspresso incorporates multi-tier optimizations to ensure sub-millisecond cold starts in production and instant dev-server boot times:
+
+#### 1. Single-Pass Unified Route Discovery (`discoverAppRoutes`)
+Instead of performing multiple independent directory traversals, `discoverAppRoutes(rootDir, options)` discovers Page routes, API routes, and Route Groups in a single traversal pass:
+```javascript
+const { discoverAppRoutes } = require('webspresso');
+
+const { routeTable, pageRoutes, apiRoutes } = discoverAppRoutes(__dirname);
+```
+Passing `discoveredRoutes` to `createApp({ discoveredRoutes })` skips internal discovery completely.
+
+#### 2. Dev-Mode On-Demand (JIT) Route Evaluation (`lazyRoutes: true`)
+In development (`NODE_ENV !== 'production'`), `lazyRoutes: true` is enabled by default:
+- Route paths and HTTP methods are registered immediately with lightweight proxy handlers.
+- Route handler modules (`pages/**/*.js` / `pages/api/**/*.js`) are required and evaluated **on-demand on the first incoming HTTP request**.
+- Result: Dev server boots in ~15ms even in applications with hundreds of routes.
+- Can be explicitly controlled via `createApp({ lazyRoutes: false })` to force eager evaluation.
+
+#### 3. Production Ahead-of-Time (AOT) Route Manifest (`routes.manifest.json`)
+For maximum production performance, compile your route table during the build step:
+```bash
+npx webspresso build
+```
+This generates `.webspresso/routes.manifest.json`. When `createApp({ routesManifest: true })` is used (or when `.webspresso/routes.manifest.json` exists in `NODE_ENV === 'production'`), Webspresso:
+- Bypasses filesystem directory scanning (`pages/`) entirely.
+- Bypasses regex path compilation and route sorting at boot.
+- Instantly binds pre-sorted routes from the manifest.
+
+### 6.6 Server-Sent Events (SSE) Streaming (`res.sse`)
 For real-time event streaming and LLM token outputs, use the native `res.sse()` helper (or `{ sse }` from `ctx`):
 
 ```javascript
@@ -352,7 +449,7 @@ module.exports = defineApi({
 });
 ```
 
-### 6.6 Cascading Middleware (`_middleware.js`) & Nested Layouts (`_layout.njk`)
+### 6.7 Cascading Middleware (`_middleware.js`) & Nested Layouts (`_layout.njk`)
 
 Webspresso supports folder-level cascading middleware inheritance and nested layouts across directory trees:
 

package/.agents/skills/webspresso-framework/SKILL.md

@@ -42,11 +42,43 @@ webspresso start            # Start production server
 webspresso doctor           # Run system sanity checks
 webspresso db:migrate       # Run pending Knex migrations
 webspresso db:seed          # Run database seeders
+webspresso add:tailwind     # Add Tailwind CSS v4 (Oxide engine, zero-config)
 webspresso agents:init      # Scaffold AI Agent rules and skills
 ```
 
 ---
 
+## 🎨 Tailwind CSS v4 Integration
+
+Webspresso natively supports **Tailwind CSS v4** (Oxide engine, LightningCSS, zero-config CSS-first architecture).
+
+### Setup & Commands
+```bash
+# Add Tailwind CSS v4 (recommended, zero-config CSS-first)
+npx webspresso add tailwind --v4
+
+# Or upgrade an existing Tailwind v3 project to v4
+npx webspresso add tailwind --upgrade
+```
+
+### Architecture & Conventions
+- **CSS-First Directives**: `src/input.css` uses modern v4 `@import`:
+  ```css
+  @import "tailwindcss";
+  ```
+- **Zero Configuration**: No `tailwind.config.js`, `postcss.config.js`, or `autoprefixer` required.
+- **Compiled Output**: Compiles into `public/css/style.css` via `@tailwindcss/cli`.
+- **Scripts in `package.json`**:
+  - `"build:css"`: `@tailwindcss/cli -i ./src/input.css -o ./public/css/style.css --minify`
+  - `"watch:css"`: `@tailwindcss/cli -i ./src/input.css -o ./public/css/style.css --watch`
+  - `"dev"`: Automatically runs CSS watcher alongside the server: `npm run watch:css & node --watch server.js`
+- **Template Integration**: Link stylesheet in Nunjucks layouts (`views/layout.njk`):
+  ```nunjucks
+  <link rel="stylesheet" href="{{ fsy.asset('/css/style.css') }}">
+  ```
+
+---
+
 ## 🏗️ Core Architecture Overview
 
 - **`pages/` & `pages/api/`**: File-based SSR templates (`.njk`), companion data loaders (`.js`), and method-suffixed API endpoints (`.get.js`, `.post.js`).

package/.agents/skills/webspresso-orm-and-database/SKILL.md

@@ -21,8 +21,10 @@ module.exports = defineModel({
   name: 'Product',
   table: 'products',
   primaryKey: 'id',
+  timestamps: true, // auto-injects createdAt & updatedAt into schema & scopes
+  softDelete: true, // auto-injects deletedAt & enables soft-delete scope
   
-  schema: zdb.object({
+  schema: {
     id: zdb.id(),
     name: zdb.string().min(1).max(255),
     slug: zdb.string().unique(),
@@ -30,10 +32,7 @@ module.exports = defineModel({
     in_stock: zdb.boolean().default(true),
     metadata: zdb.json().optional(),
     user_id: zdb.foreignKey('users.id'),
-    created_at: zdb.timestamp().autoCreate(),
-    updated_at: zdb.timestamp().autoUpdate(),
-    deleted_at: zdb.timestamp().nullable(),
-  }),
+  },
 
   relations: {
     user: {

package/.agents/skills/webspresso-routing-and-api/SKILL.md

@@ -85,10 +85,10 @@ module.exports = definePage({
 {% extends "layout.njk" %}
 
 {% block content %}
-<div class="product-page">
-  <h1>{{ product.name }}</h1>
-  <p class="price">{{ fsy.formatCurrency(product.price) }}</p>
-  <p>{{ product.description }}</p>
+<div class="max-w-4xl mx-auto p-6 bg-white dark:bg-gray-900 rounded-xl shadow-sm">
+  <h1 class="text-2xl font-bold text-gray-900 dark:text-white">{{ product.name }}</h1>
+  <p class="text-lg font-semibold text-emerald-600 mt-2">{{ fsy.formatCurrency(product.price) }}</p>
+  <p class="text-gray-600 dark:text-gray-300 mt-4 leading-relaxed">{{ product.description }}</p>
 </div>
 {% endblock %}
 ```

package/AGENTS.md

@@ -58,6 +58,12 @@ Every coding agent working on Webspresso **MUST** follow this 4-step execution d
 - **Graceful Shutdown & Lifecycle Management**: Configured via `createApp({ server: { shutdown: { enabled: true, mode: 'graceful'|'force', timeout: 10000 } } })`. Socket connection tracking, request draining with `Connection: close`, and reverse-order plugin disposer cleanup.
 - **HTTP Response Compression**: Zero-dependency streaming zlib compression configured via `createApp({ server: { compression: true } })` with Brotli (`br`), Gzip (`gzip`), Deflate (`deflate`), threshold buffering (1 KB), and route-level opt-out (`res.compress(false)`).
 - **Custom Error & 404 Pages**: Configured via `createApp({ errorPages: { notFound, serverError, timeout } })`. Supports template paths (e.g. `notFound: '404.njk'`) or custom handler functions, passing `{ fsy, locale, isDev, url, method }` to templates.
+- **Cold Start & High-Performance Optimizations**:
+  - Unified single-pass route scanner (`discoverAppRoutes`).
+  - Dev-mode on-demand (JIT) route evaluation (`lazyRoutes: true`, dev boot ~15ms).
+  - Ahead-of-time (AOT) route table manifest (`webspresso build` -> `.webspresso/routes.manifest.json`).
+  - Ahead-of-time (AOT) Nunjucks template precompilation (`webspresso build` -> `.webspresso/templates.compiled.js`).
+  - On-demand lazy plugin hydration (`lazyPlugin`, `adminPanelPlugin({ lazy: true })`, `fileManagerPlugin({ lazy: true })`).
 - **Middleware & Hooks**: Route lifecycle hooks can be declared per-page or globally via `pages/_hooks.js`.
 - **API Endpoints & Routing Architecture**:
   - ⚠️ **CRITICAL ANTI-PATTERN: NEVER create a `routes/` or `src/routes/` directory. NEVER use `express.Router()`, `app.get()`, or `app.post()` for application endpoints.**

package/README.md

@@ -31,11 +31,12 @@ Open **`http://localhost:3000`** in your browser.
 | Layer | Capabilities |
 | :--- | :--- |
 | **Routing & SSR** | 100% file-based routing (`pages/`), method suffixes (`.get.js`, `.post.js`), nested layouts (`_layout.njk`), directory-level error boundaries (`_error.njk`), loading skeletons (`_loading.njk`), and out-of-order chunked response streaming (`res.renderStream`). |
+| **Performance & Cold Start** | Single-pass unified route discovery, dev mode JIT on-demand route evaluation, production AOT route manifest (`webspresso build`), AOT Nunjucks template precompilation (zero AST parsing at runtime), and on-demand lazy plugin mounting. |
 | **Database & ORM** | Built-in Knex ORM with `defineModel`, `zdb` schema builder, Repository pattern (`db.getRepository('Model')`), relations (`belongsTo`, `hasMany`), cascade soft-delete & restore, and ambient transactions via `AsyncLocalStorage`. |
 | **Dual Auth & Sessions** | Stateful cookies for SSR + stateless HS256 JWT rotation for APIs, magic links, active device management & remote session revocation, CSRF protection, and zero external auth dependencies. |
 | **Services & Queues** | File-based auto-discovery in `services/` with declarative Zod validation, role-based access guards, and ACID transaction propagation. Background worker queues in `jobs/`. |
-| **Admin Panel SPA** | Integrated Mithril.js single-page admin panel mounted at `/_admin` with auto-layout wrapping, CRUD views, custom dashboard widgets, and custom field renderers. |
-| **Plugin Ecosystem** | 20+ official plugins: Polar.sh billing, Webhooks dispatcher with HMAC signatures, Realtime (WebSocket/SSE), Site Analytics, API Keys, File Manager, CSV/Excel generation, and more. |
+| **Admin Panel SPA** | Integrated Mithril.js single-page admin panel mounted at `/_admin` with auto-layout wrapping, CRUD views, custom dashboard widgets, and custom field renderers. Supports on-demand lazy mounting (`adminPanelPlugin({ lazy: true })`). |
+| **Plugin Ecosystem** | 20+ official plugins: Polar.sh billing, Webhooks dispatcher with HMAC signatures, Realtime (WebSocket/SSE), Site Analytics, API Keys, File Manager, CSV/Excel generation, On-demand Lazy Plugins (`lazyPlugin`), and more. |
 | **DevOps & Production** | Built-in streaming zlib compression (`brotli`/`gzip`), socket connection draining & graceful shutdown, `webspresso deploy:check` production readiness auditor, and Docker scaffolding. |
 
 ---
@@ -114,13 +115,13 @@ const { defineModel, zdb } = require('webspresso');
 module.exports = defineModel({
   name: 'Note',
   table: 'notes',
+  timestamps: true, // auto-injects createdAt & updatedAt into schema & scopes
+  softDelete: true, // auto-injects deletedAt & enables soft-delete scope
   schema: {
     id: zdb.id(),
     title: zdb.string(200),
     content: zdb.text(),
     userId: zdb.integer(),
-    ...zdb.timestamps(),
-    ...zdb.softDeletes(),
   },
   relations: {
     user: { type: 'belongsTo', model: 'User', foreignKey: 'userId' },
@@ -154,13 +155,25 @@ app.listen(PORT, () => {
 
 ---
 
+## ⚡ High-Performance Architecture (Cold Start & AOT)
+
+Webspresso is designed for blazing-fast cold starts and minimal resource consumption in both development and production:
+
+1. **Unified Single-Pass Route Discovery (`discoverAppRoutes`)**: Traverses the filesystem only once at startup, building the `RouteTable` and companion loaders in a single pass (saving 30-40% mount time).
+2. **Dev-Mode On-Demand (JIT) Route Evaluation**: In development, API routes and SSR companion `.js` configs are resolved on-demand when first requested. The dev server boots in **<100ms** regardless of project size.
+3. **Production AOT Route Manifest (`webspresso build`)**: The build step generates `.webspresso/routes.manifest.json`. In production, the server mounts pre-indexed routes with **zero filesystem directory scans**.
+4. **Nunjucks Template Precompilation (AOT / Zero-AST Parse)**: `webspresso build` precompiles `.njk` templates into JavaScript render functions (`.webspresso/templates.compiled.js`). Eliminates runtime disk I/O and template parsing overhead for ultra-low TTFB.
+5. **On-Demand Lazy Plugins (`lazyPlugin`)**: Heavy plugins (e.g. `adminPanelPlugin({ lazy: true })`, `fileManagerPlugin({ lazy: true })`) defer initialization, session setup, and route mounting until first access to their URL prefix or service invocation.
+
+---
+
 ## 🧰 Essential CLI Commands
 
 ```bash
 # Development & Builds
-npx webspresso dev                 # Start dev server with watch & live reload
-npx webspresso build               # Compile production assets
-npx webspresso start               # Run production server
+npx webspresso dev                 # Start dev server with watch & JIT live reload
+npx webspresso build               # Compile production assets, AOT route manifest & precompiled templates
+npx webspresso start               # Run production server with zero-FS discovery
 
 # Database & Migrations
 npx webspresso db:migrate          # Run pending database migrations

package/bin/commands/add-tailwind.js

@@ -171,6 +171,16 @@ module.exports = {
       // Create placeholder CSS
       fs.writeFileSync('public/css/style.css', '/* Run npm run build:css */\n');
       console.log('✅ Created public/css/style.css');
+
+      // Ensure public/css/style.css is in .gitignore
+      if (fs.existsSync('.gitignore')) {
+        let gitignore = fs.readFileSync('.gitignore', 'utf-8');
+        if (!gitignore.includes('public/css/style.css')) {
+          gitignore = gitignore.trimEnd() + '\npublic/css/style.css\n';
+          fs.writeFileSync('.gitignore', gitignore);
+          console.log('✅ Added public/css/style.css to .gitignore');
+        }
+      }
       
       // Try to build CSS if tailwindcss / @tailwindcss/cli is already installed
       const tailwindBin = path.join(process.cwd(), 'node_modules', '.bin', 'tailwindcss');

package/bin/commands/build.js

@@ -15,6 +15,8 @@ function registerCommand(program) {
     .description('Build production assets (Tailwind CSS and esbuild JS with manifest.json)')
     .option('--no-css', 'Skip CSS build')
     .option('--no-js', 'Skip JS bundle build')
+    .option('--no-routes', 'Skip generating AOT route manifest')
+    .option('--no-templates', 'Skip precompiling Nunjucks templates')
     .option('--no-hash', 'Disable content hashing in asset filenames')
     .action(async (options = {}) => {
       const cwd = process.cwd();
@@ -33,6 +35,8 @@ function registerCommand(program) {
 
       let cssBuilt = false;
       let jsBuilt = false;
+      let routesBuilt = false;
+      let routeCount = 0;
 
       // 1. Build CSS (Tailwind)
       if (options.css !== false) {
@@ -90,9 +94,39 @@ function registerCommand(program) {
         }
       }
 
+      // 3. Build AOT Route Manifest (.webspresso/routes.manifest.json)
+      if (options.routes !== false) {
+        try {
+          const { generateRouteManifest } = require('../../src/discovery/route-manifest');
+          const result = generateRouteManifest({ rootDir: cwd });
+          routesBuilt = true;
+          routeCount = result.routeCount;
+          console.log(`🗺️  AOT route manifest generated (${result.routeCount} routes) at: ${path.relative(cwd, result.manifestPath)}`);
+        } catch (err) {
+          console.error('❌ Route manifest generation failed:', err.message);
+        }
+      }
+
+      // 4. Precompile Nunjucks Templates (.webspresso/templates.compiled.js)
+      let templatesBuilt = false;
+      let templateCount = 0;
+      if (options.templates !== false) {
+        try {
+          const { precompileTemplates } = require('../../src/template/precompile');
+          const result = precompileTemplates({ rootDir: cwd });
+          templatesBuilt = true;
+          templateCount = result.templateCount;
+          console.log(`📑 Precompiled Nunjucks templates (${result.templateCount} templates) at: ${path.relative(cwd, result.manifestPath)}`);
+        } catch (err) {
+          console.error('❌ Template precompilation failed:', err.message);
+        }
+      }
+
       console.log('\n✨ Asset build complete!\n');
       if (cssBuilt) console.log('  ✓ CSS: public/css/style.css');
       if (jsBuilt) console.log('  ✓ JS: public/dist/ & manifest.json');
+      if (routesBuilt) console.log(`  ✓ Routes: .webspresso/routes.manifest.json (${routeCount} routes)`);
+      if (templatesBuilt) console.log(`  ✓ Templates: .webspresso/templates.compiled.js (${templateCount} templates)`);
     });
 }
 

package/bin/commands/routes.js

@@ -19,10 +19,18 @@ function registerCommand(program) {
     .option('-a, --api', 'Filter to only API endpoints')
     .option('-p, --pages', 'Filter to only SSR page routes')
     .option('-j, --json', 'Output routes as JSON')
+    .option('-m, --manifest', 'Generate or update .webspresso/routes.manifest.json')
     .option('--root <dir>', 'Root directory of the project', process.cwd())
     .action((options) => {
       const rootDir = path.resolve(options.root || process.cwd());
 
+      if (options.manifest) {
+        const { generateRouteManifest } = require('../../src/discovery/route-manifest');
+        const result = generateRouteManifest({ rootDir });
+        console.log(`✅ AOT route manifest written to: ${path.relative(rootDir, result.manifestPath)} (${result.routeCount} routes)`);
+        return;
+      }
+
       const descriptors = scanRoutes({
         rootDir,
         pages: fs.existsSync(path.join(rootDir, 'pages')) ? { dir: 'pages' } : true,

package/core/applySchema.js

@@ -49,8 +49,25 @@ function applySchema(req, compiledSchema) {
   }
 }
 
+let _translateValidationIssues = null;
+function getTranslateValidationIssues() {
+  if (!_translateValidationIssues) {
+    try {
+      _translateValidationIssues = require('../src/api/validation-i18n').translateValidationIssues;
+    } catch {
+      _translateValidationIssues = (issues) => issues;
+    }
+  }
+  return _translateValidationIssues;
+}
+
+function translateValidationIssues(issues, options) {
+  return getTranslateValidationIssues()(issues, options);
+}
+
 module.exports = {
-  applySchema
+  applySchema,
+  translateValidationIssues,
 };
 
 

package/core/auth/jwt.js

@@ -6,18 +6,17 @@
 
 const crypto = require('crypto');
 
+const HS256_HEADER_BASE64URL = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9';
+
 /**
  * Base64URL encode string or Buffer
  * @param {string|Buffer} input
  * @returns {string}
  */
 function base64UrlEncode(input) {
-  const buf = Buffer.isBuffer(input) ? input : Buffer.from(input, 'utf8');
-  return buf
-    .toString('base64')
-    .replace(/=/g, '')
-    .replace(/\+/g, '-')
-    .replace(/\//g, '_');
+  return Buffer.isBuffer(input)
+    ? input.toString('base64url')
+    : Buffer.from(String(input), 'utf8').toString('base64url');
 }
 
 /**
@@ -26,11 +25,7 @@ function base64UrlEncode(input) {
  * @returns {string}
  */
 function base64UrlDecode(input) {
-  let base64 = input.replace(/-/g, '+').replace(/_/g, '/');
-  while (base64.length % 4 !== 0) {
-    base64 += '=';
-  }
-  return Buffer.from(base64, 'base64').toString('utf8');
+  return Buffer.from(String(input), 'base64url').toString('utf8');
 }
 
 /**
@@ -110,16 +105,14 @@ function signJwt(payload, secret, options = {}) {
     ...payload,
   };
 
-  const encodedHeader = base64UrlEncode(JSON.stringify(header));
+  const encodedHeader = algorithm === 'HS256' ? HS256_HEADER_BASE64URL : base64UrlEncode(JSON.stringify(header));
   const encodedPayload = base64UrlEncode(JSON.stringify(fullPayload));
 
   const signingInput = `${encodedHeader}.${encodedPayload}`;
-  const signature = crypto
+  const encodedSignature = crypto
     .createHmac('sha256', secret)
     .update(signingInput)
-    .digest();
-
-  const encodedSignature = base64UrlEncode(signature);
+    .digest('base64url');
 
   return `${signingInput}.${encodedSignature}`;
 }
@@ -177,7 +170,7 @@ function verifyJwt(token, secret, options = {}) {
     .update(signingInput)
     .digest();
 
-  const actualSignatureBuf = Buffer.from(encodedSignature.replace(/-/g, '+').replace(/_/g, '/'), 'base64');
+  const actualSignatureBuf = Buffer.from(encodedSignature, 'base64url');
 
   if (
     expectedSignatureBuf.length !== actualSignatureBuf.length ||