@seip/bluebird-js 0.1.6 → 0.2.0

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 (152) hide show
  1. package/.vscode/extensions.json +7 -7
  2. package/.vscode/settings.json +10 -10
  3. package/AGENTS.md +266 -116
  4. package/README.md +258 -245
  5. package/app/models/user.js +19 -0
  6. package/app/resources/html/home.html +137 -0
  7. package/app/resources/html/layouts/main.html +54 -0
  8. package/app/resources/html/notFound.html +14 -0
  9. package/app/resources/html/terms.html +46 -0
  10. package/app/resources/index.html +27 -0
  11. package/app/resources/layouts/AppLayout.jsx +89 -0
  12. package/app/resources/main.jsx +18 -0
  13. package/app/resources/pages/Dashboard.jsx +98 -0
  14. package/app/resources/pages/Home.jsx +140 -0
  15. package/app/resources/pages/Login.jsx +35 -0
  16. package/app/resources/pages/NotFound.jsx +16 -0
  17. package/app/resources/pages/Register.jsx +55 -0
  18. package/app/resources/routes.jsx +54 -0
  19. package/app/resources/spa.js +67 -0
  20. package/app/resources/styles.css +9 -0
  21. package/app/routes/api.js +85 -50
  22. package/app/routes/auth.js +209 -0
  23. package/app/routes/web.js +49 -37
  24. package/core/ai.d.ts +151 -151
  25. package/core/ai.js +1071 -1051
  26. package/core/app.d.ts +2 -18
  27. package/core/app.js +978 -792
  28. package/core/auth.d.ts +2 -13
  29. package/core/auth.js +444 -326
  30. package/core/cli/backup.js +167 -167
  31. package/core/cli/build.js +37 -0
  32. package/core/cli/dev.js +155 -0
  33. package/core/cli/doctor.js +37 -2
  34. package/core/cli/export.js +191 -0
  35. package/core/cli/init.js +101 -332
  36. package/core/cli/nginx.js +1 -1
  37. package/core/cli/templates.js +139 -0
  38. package/core/cli/view.js +73 -136
  39. package/core/config.js +44 -2
  40. package/core/csrf.js +156 -24
  41. package/core/database.js +737 -684
  42. package/core/debug.js +1 -1
  43. package/core/html.js +8 -1
  44. package/core/index.d.ts +1286 -1431
  45. package/core/paths.js +55 -0
  46. package/core/ratelimit.js +10 -1
  47. package/core/react/client/api.js +237 -0
  48. package/core/react/client/auth.js +236 -0
  49. package/core/react/client/components.js +1321 -0
  50. package/core/react/client/i18n.js +338 -0
  51. package/core/react/client/index.d.ts +249 -0
  52. package/core/react/client/index.js +49 -0
  53. package/core/react/client/router.js +26 -0
  54. package/core/react/client/theme.css +512 -0
  55. package/core/render-cache.js +250 -212
  56. package/core/render.d.ts +25 -21
  57. package/core/render.js +613 -603
  58. package/core/router.d.ts +2 -3
  59. package/core/router.js +171 -171
  60. package/core/seo.js +10 -0
  61. package/core/spa.js +599 -0
  62. package/core/view-loader.js +81 -455
  63. package/core/vite-plugin.d.ts +18 -0
  64. package/core/vite-plugin.js +162 -0
  65. package/core/vite.js +250 -145
  66. package/index.js +22 -18
  67. package/jsconfig.json +5 -3
  68. package/package.json +114 -92
  69. package/production.md +8 -3
  70. package/public/js/bluebird.js +1160 -0
  71. package/templates/_auth/app/database.js +19 -0
  72. package/templates/_auth/app/models/user.js +22 -0
  73. package/templates/_auth/app/routes/auth-router.js +304 -0
  74. package/templates/_base/app/resources/html/layouts/main.html +55 -0
  75. package/templates/_base/app/resources/html/notFound.html +14 -0
  76. package/templates/_base/app/resources/index.html +27 -0
  77. package/templates/_base/app/resources/styles.css +9 -0
  78. package/templates/api/app/models/note.js +18 -0
  79. package/templates/api/app/routes/api.js +82 -0
  80. package/templates/api/app/routes/auth.js +11 -0
  81. package/templates/api/index.js +19 -0
  82. package/templates/api/template.json +13 -0
  83. package/templates/auth/app/mail.js +11 -0
  84. package/templates/auth/app/models/password_reset.js +18 -0
  85. package/templates/auth/app/resources/html/home.html +21 -0
  86. package/templates/auth/app/resources/html/partials/nav.html +2 -0
  87. package/templates/auth/app/resources/layouts/AppLayout.jsx +60 -0
  88. package/templates/auth/app/resources/main.jsx +18 -0
  89. package/templates/auth/app/resources/pages/Dashboard.jsx +51 -0
  90. package/templates/auth/app/resources/pages/ForgotPassword.jsx +34 -0
  91. package/templates/auth/app/resources/pages/Login.jsx +36 -0
  92. package/templates/auth/app/resources/pages/NotFound.jsx +16 -0
  93. package/templates/auth/app/resources/pages/Profile.jsx +99 -0
  94. package/templates/auth/app/resources/pages/Register.jsx +50 -0
  95. package/templates/auth/app/resources/pages/ResetPassword.jsx +50 -0
  96. package/templates/auth/app/resources/routes.jsx +54 -0
  97. package/templates/auth/app/resources/spa.js +29 -0
  98. package/templates/auth/app/routes/api.js +17 -0
  99. package/templates/auth/app/routes/auth.js +13 -0
  100. package/templates/auth/app/routes/web.js +21 -0
  101. package/templates/auth/index.js +19 -0
  102. package/templates/auth/template.json +15 -0
  103. package/templates/blank/app/models/.gitkeep +0 -0
  104. package/templates/blank/app/resources/html/home.html +27 -0
  105. package/templates/blank/app/resources/html/partials/nav.html +1 -0
  106. package/templates/blank/app/resources/main.jsx +16 -0
  107. package/templates/blank/app/resources/pages/Home.jsx +42 -0
  108. package/templates/blank/app/resources/pages/NotFound.jsx +27 -0
  109. package/templates/blank/app/resources/routes.jsx +15 -0
  110. package/templates/blank/app/resources/spa.js +24 -0
  111. package/templates/blank/app/routes/api.js +11 -0
  112. package/templates/blank/app/routes/web.js +21 -0
  113. package/templates/blank/index.js +13 -0
  114. package/templates/blank/template.json +12 -0
  115. package/templates/blog/app/lib/blog.js +149 -0
  116. package/templates/blog/app/models/post.js +22 -0
  117. package/templates/blog/app/resources/html/home.html +28 -0
  118. package/templates/blog/app/resources/html/not-found.html +5 -0
  119. package/templates/blog/app/resources/html/partials/nav.html +2 -0
  120. package/templates/blog/app/resources/html/partials/post-card.html +9 -0
  121. package/templates/blog/app/resources/html/post.html +8 -0
  122. package/templates/blog/app/resources/layouts/AdminLayout.jsx +54 -0
  123. package/templates/blog/app/resources/main.jsx +18 -0
  124. package/templates/blog/app/resources/pages/Login.jsx +31 -0
  125. package/templates/blog/app/resources/pages/NotFound.jsx +16 -0
  126. package/templates/blog/app/resources/pages/PostEditor.jsx +51 -0
  127. package/templates/blog/app/resources/pages/Posts.jsx +83 -0
  128. package/templates/blog/app/resources/pages/Register.jsx +43 -0
  129. package/templates/blog/app/resources/routes.jsx +51 -0
  130. package/templates/blog/app/resources/spa.js +25 -0
  131. package/templates/blog/app/resources/styles.css +40 -0
  132. package/templates/blog/app/routes/api.js +77 -0
  133. package/templates/blog/app/routes/auth.js +10 -0
  134. package/templates/blog/app/routes/web.js +114 -0
  135. package/templates/blog/index.js +21 -0
  136. package/templates/blog/template.json +14 -0
  137. package/vite.config.js +11 -0
  138. package/app/views/about.jsx +0 -98
  139. package/app/views/components/Header.jsx +0 -42
  140. package/app/views/components/LiveCounter.jsx +0 -66
  141. package/app/views/dashboard.jsx +0 -300
  142. package/app/views/index.jsx +0 -123
  143. package/app/views/layouts/main/view.jsx +0 -201
  144. package/app/views/legal/terms.html +0 -29
  145. package/app/views/login.jsx +0 -141
  146. package/core/actions.d.ts +0 -4
  147. package/core/actions.js +0 -329
  148. package/core/jsx.d.ts +0 -38
  149. package/core/jsx.js +0 -1432
  150. package/core/vite.d.ts +0 -3
  151. package/public/js/bluebird-client.js +0 -3161
  152. package/public/js/tailwind.js +0 -8
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Bluebird.js Framework
2
2
 
3
- **Performance-first Node.js API and web framework with native JavaScript ESM, built-in Tailwind CSS, Inter fonts, declarative UI components, JWT auth, BaseModel, smart migrations, and multi-level caching.**
3
+ **Performance-first Node.js framework: Express + HTML `{{ }}` SSR templates + React Router SPA with Vite, Tailwind CSS v4, JWT auth with roles, BaseModel, smart migrations, and multi-level caching.**
4
4
 
5
5
  [![npm version](https://img.shields.io/npm/v/@seip/bluebird-js.svg)](https://www.npmjs.com/package/@seip/bluebird-js)
6
6
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
@@ -10,24 +10,23 @@
10
10
 
11
11
  ## Introduction
12
12
 
13
- Bluebird.js (`@seip/bluebird-js`) is a high-performance web and API framework built on Express (Node.js 22.18+). It provides native modern JavaScript ESM execution, built-in Tailwind CSS v4 runtime and Google Fonts (`Inter`), zero-build SSR with React/Next.js-style component tags, multi-driver caching (in-memory LRU by default with filesystem and Redis support), AES-256-GCM encrypted JWT authentication, BaseModel schema definitions with smart migrations, CSRF protection, background queues, and PM2 production clustering into a cohesive developer experience.
13
+ Bluebird.js (`@seip/bluebird-js`) is a high-performance web and API framework built on Express (Node.js 22.18+). Public landings and SEO pages render cleanly on the server with **HTML `{{ }}` templates** (`app/resources/html/`), while interactive dashboards and web applications run as **client-rendered React 19 + React Router SPAs** mounted via `router.spa()`, bundled with Vite and styled with Tailwind CSS v4 (dark and light themes). It ships with JWT authentication (with optional role checks and `/api/auth/*` routes), vanilla HTML UI helpers (`public/js/bluebird.js`), Tailwind React components, multi-driver caching (in-memory LRU, filesystem, and Redis), BaseModel with smart migrations, CSRF protection, background queues, and PM2 production clustering.
14
14
 
15
15
  ### Key Highlights
16
16
 
17
- - **Native Zero-Build React JSX & TSX SSR (`app/views/*.jsx`, `*.tsx`):** Compiles `.jsx` and TypeScript `.tsx` modules in memory via Node 22.18+ `module.registerHooks()` with zero temporary disk files, automatic TypeScript type stripping, and zero build steps.
18
- - **`<ErrorBoundary>` & Dynamic `<Head>` Hoisting:** Native JSX error boundary (`<ErrorBoundary fallback={...}>`) protects against subtree SSR errors, while `<Head>`, `<Title>`, and `<Meta>` automatically hoist metadata into the page head.
19
- - **Streaming SSR with `<Suspense>` & Instant Caching:** Chunked progressive rendering (`Render.stream()`) with fallback skeletons and seamless deferred template swapping, automatically caching assembled output for instant cache HITs.
20
- - **Client Components with `useAction` & `useActionState`:** Micro-reactive client runtime with standard hooks (`useState`, `useEffect`, `useAction`, `useActionState`, `html` tagged templates), plus anti-CLS layout locking (`minHeight`, `minWidth`) and automatic button/form pending states.
21
- - **Declarative Auto-Routes from Views:** Export `const route`, `const cache`, `const middlewares`, `const layout`, and `const seo` directly from `app/views/*.jsx` or `*.tsx` to mount cached, protected web routes automatically (`noAutoDiscoverRoutes: true` in `new App()` to disable).
22
- - **Built-In Tailwind CSS & Inter Font:** Includes the official standalone Tailwind CSS runtime (`/js/tailwind.js`) and Google Fonts `Inter` by default with zero configuration or compilers.
17
+ - **HTML `{{ }}` SSR Engine:** Fast `.html` views, layouts (`{{{ body }}}`), partials (`{{> name }}`), `{{if}}`/`{{else}}`, `{{each}}`, raw `{{{ html }}}`, and `{{ vite "app/resources/styles.css" }}`, and `\{{ literal }}` escapes.
18
+ - **React Router SPA (`router.spa()`):** Serves the React shell `app/resources/index.html` with per-URL SEO metadata (`title`, `description`, `keywords`, `canonical`, Open Graph, `robots`, `jsonld`), custom scripts/styles, and a full-width anti-CLS skeleton inside `<div id="root">`.
19
+ - **One React Codebase, Web + Desktop + Mobile:** Zero server-injected props in the SPA — React talks directly to `/api/*` via `api()`. `npx bluebird-js export` turns the same code into a 100% static HTML/JS/CSS build for Electron (`loadFile`), Capacitor, or any static host, with bearer-token auth against your Bluebird API.
20
+ - **Vite & Tailwind CSS v4:** Vite middleware HMR on the same port as Express in development; client bundle + manifest in `public/build/` via `npx bluebird-js build`. Built-in dark and light theme synchronization.
21
+ - **AuthProvider & Role Guards:** Client `AuthProvider`, `useAuth()`, `RequireAuth` (with optional `roles`), `GuestOnly`, plus default `/api/auth/login`, `/logout`, `/me`, and optional `/register`.
22
+ - **UI Kits for Both Worlds:** React UI components (`Link`, `Button`, `Form`, `Input`, `Select`, `Textarea`, `Card`, `Badge`, `Carousel`, `Modal`, `Drawer`, `Skeleton`, `ThemeToggle`, `Toaster` / `toast`) and dependency-free vanilla `public/js/bluebird.js` (`data-carousel`, `data-toast`, `data-modal`, `data-dropdown`, `data-tabs`, `data-theme-toggle`, `data-form`).
23
23
  - **Smart Automatic Migrations:** CLI detects schema changes across `app/models/`, resolves foreign key dependencies topologically, generates consolidated `CREATE TABLE` / `ALTER TABLE ADD COLUMN` SQL files, and executes them with interactive terminal prompts.
24
24
  - **Lightweight BaseModel:** Static facade providing readable schemas, CRUD shortcuts, query operators (`IN`, `$gt`, `$like`), `count()`, `exists()`, `firstOrCreate()`, `updateOrCreate()`, smart relations without N+1 queries, soft deletes, and automatic query cache invalidation.
25
- - **Native SQLite & Desktop Mode (Electron/Tauri):** Uses Node's built-in `node:sqlite` driver with zero compilation overhead, plus first-class `desktop: true` mode (`app.runDesktop()`) for read-only `.asar` bundles.
26
- - **Comprehensive Client UI Kit:** Built-in `bluebird-client.js` with toasts, snackbars, drawers, command palette (`Ctrl+K`), responsive data tables, tabs, carousels, declarative forms (`data-bb-form`), and View Transitions SPA routing.
25
+ - **Native SQLite & Desktop Mode (Electron/Tauri):** Uses Node's built-in `node:sqlite` driver (no native compilation), plus first-class `desktop: true` mode (`app.runDesktop()`) for read-only `.asar` bundles.
27
26
  - **Decoupled Caching:** High-speed in-memory LRU cache by default, persistent filesystem fallback, and modular Redis support via `core/redis.js`.
28
- - **Unified AI Client (`core/ai.js`):** Native zero-dependency client with DeepSeek default (`deepseek-flash`), Gemini 3.5/3.8, and OpenAI, featuring reversible PII data masking, 0ms prompt caching, sliding window rate limits ("Anti-Quiebra"), and JSON schema validation.
29
- - **Atomic Database Backups & Verification:** WAL-safe, non-blocking online SQLite snapshots using `VACUUM INTO` and gzip compression, with automated retention rotation (`--keep 10`) and integrity-verified restore.
30
- - **CSRF, Rate Limiting & Security:** Native HMAC-SHA256 signed CSRF protection, built-in Rate Limiter (`rateLimit` in `App` or `App.rateLimit()`), automatic `/sitemap.xml` & `/robots.txt` generation, and secure HTTP headers.
27
+ - **Unified AI Client (`core/ai.js`):** Built-in client (no provider SDKs) with DeepSeek default (`deepseek-flash`), Gemini 3.5/3.8, and OpenAI, featuring reversible PII data masking, 0ms prompt caching, sliding window rate limits ("Anti-Quiebra"), and JSON schema validation.
28
+ - **Atomic Database Backups & Verification:** WAL-safe, non-blocking online SQLite snapshots using `VACUUM INTO` and gzip compression, with automated retention rotation (`--keep 10`, ordered by filename timestamp so same-millisecond backups never drop the newest one) and integrity-verified restore.
29
+ - **CSRF, Rate Limiting & Security:** Native HMAC-SHA256 signed CSRF protection (timing-safe, rotated on login/logout, never leaked through cached pages), built-in Rate Limiter (`rateLimit` in `App`, `App.rateLimit()`), secure-by-default CORS, CSP nonces (`'nonce-{nonce}'`) applied to every inline script/style, automatic `/sitemap.xml` & `/robots.txt` generation, and secure HTTP headers.
31
30
  - **Production Ready:** Built-in PM2 clustering CLI (`npx bluebird-js make:ecosystem`), optimized Nginx generator (`npx bluebird-js nginx:conf`), and native runner (`npm start`).
32
31
 
33
32
  ---
@@ -48,9 +47,39 @@ npx bluebird-js
48
47
 
49
48
  The interactive CLI configures:
50
49
  - Project title and port settings
51
- - Database engine: `sqlite` (default, native zero-configuration), `mysql`, `postgres`, or `none`
50
+ - Project template (see below), `blank` by default
51
+ - Database engine: `sqlite` (default, built into Node.js), `mysql`, `postgres`, or `none`
52
52
  - Connection credentials and database paths
53
- - Automatic generation of `index.js`, `.env`, `jsconfig.json`, `app/`, and `public/`
53
+ - Automatic generation of `index.js`, `vite.config.js`, `.env`, `jsconfig.json`, `app/`, and `public/`
54
+
55
+ #### Project Templates
56
+
57
+ Pick a starting point with a flag (or answer the prompt). Every template starts clean, so there is nothing to delete before building your own app:
58
+
59
+ ```bash
60
+ npx bluebird-js # asks for the template (default: blank)
61
+ npx bluebird-js --blank # HTML {{ }} page on / + one-page React SPA on /app/*
62
+ npx bluebird-js --auth # + login, register, forgot/reset password, dashboard, profile
63
+ npx bluebird-js --blog # SEO blog (HTML list, posts, RSS, sitemap) + React admin on /app
64
+ npx bluebird-js --api # headless REST API: JWT auth (cookie or bearer) + CRUD example
65
+ npx bluebird-js --demo # full showcase used to develop the framework
66
+ npx bluebird-js --auth --yes --title "My App" # non-interactive
67
+ ```
68
+
69
+ | Template | Server | React (`/app`) | Database |
70
+ |---|---|---|---|
71
+ | `blank` | `/` HTML page, `/api/hello` | `Home.jsx` only | optional |
72
+ | `auth` | `/` landing, `/api/auth/*` (me, login, logout, register, forgot/reset password, profile, password), `/api/dashboard` | Login, Register, ForgotPassword, ResetPassword, Dashboard, Profile | required (tables created on first run) |
73
+ | `blog` | `/`, `/blog/:slug` (cached, JSON-LD), `/feed.xml`, posts in `/sitemap.xml`, `/api/posts` (admin) | Login, one-time admin Register, Posts, PostEditor | required |
74
+ | `api` | `/api/auth/*`, `/api/notes` (paginated, owner-scoped CRUD), no Vite | none | required |
75
+
76
+ - In `auth` and `api`, every new account gets the `user` role; promote admins yourself, e.g. in a seed: `await User.update(id, { role: "admin" })`. In `blog`, only the first account can register: it becomes the `admin` and registration closes.
77
+ - Sessions are checked against the database on every protected request (`Auth.configure({ resolveUser })`): changing or resetting the password signs out every other device (the current one gets a fresh token), `POST /api/auth/logout-all` signs out everywhere, deleted accounts lose access, and role changes apply immediately. Changing the sign-in email requires `current_password`.
78
+ - Password reset links are printed in the server console by `app/mail.js` until you plug in a mail provider there.
79
+ - Tables are created with `CREATE TABLE IF NOT EXISTS` at startup (`app/database.js`); use `make:migration` / `migrate` for later schema changes.
80
+ - Existing files are never overwritten, so the command is safe to run inside an existing folder.
81
+
82
+ Dependencies: `express`, `react`, `react-dom`, `react-router`, `vite`, `@vitejs/plugin-react`, `tailwindcss` and `@tailwindcss/vite` are installed with the framework; database drivers, Redis, uploads, WebSockets, Swagger and Helmet are optional (`npx bluebird-js add <module>`).
54
83
 
55
84
  ### 3. Development Server
56
85
 
@@ -58,7 +87,20 @@ The interactive CLI configures:
58
87
  npm run dev
59
88
  ```
60
89
 
61
- The server starts with Node's native file watcher (`--watch`) and loads `.env` automatically via `--env-file=.env`.
90
+ `npm run dev` runs `bluebird-js dev`: Express and Vite share one port, with React Fast Refresh and Tailwind CSS HMR for `app/resources/` (HTML `{{ }}` pages included). The server restarts when any server file under `app/` changes (routes, models, jobs, `app/lib/`...), or `index.js`, `.env`, `app/resources/spa.js`; client files in `app/resources/` hot-reload through Vite instead, and writes to `logs/`, `node_modules/`, or build output never restart it. Watch extra folders with `bluebird-js dev index.js --watch app/services`.
91
+
92
+ ### 4. Production Build
93
+
94
+ ```bash
95
+ npx bluebird-js build # Builds client SPA & Tailwind CSS bundle into public/build/
96
+ npm start
97
+ ```
98
+
99
+ ### 5. Static Export (Electron, Capacitor, static hosting)
100
+
101
+ ```bash
102
+ npx bluebird-js export --api https://api.example.com # dist/client/index.html + assets/
103
+ ```
62
104
 
63
105
  ---
64
106
 
@@ -67,30 +109,29 @@ The server starts with Node's native file watcher (`--watch`) and loads `.env` a
67
109
  ```
68
110
  project/
69
111
  ├── index.js # Main application entrypoint
112
+ ├── vite.config.js # Optional Vite config (React, Tailwind, Bluebird plugins)
70
113
  ├── app/
71
- │ ├── models/ # BaseModel definitions
72
- │ │ ├── user.js # User model schema & methods
73
- │ │ └── post.js # Post model schema & relations
74
- │ ├── routes/ # Application routes
75
- │ │ ├── api.js # REST API routes
76
- │ │ └── web.js # HTML page routes
77
- │ ├── views/ # React JSX (.jsx) & JavaScript (.js) SSR views
78
- │ │ ├── components/ # Reusable JSX components (e.g. Header.jsx)
79
- │ │ ├── layouts/ # Shared page layouts (e.g. main/view.jsx)
80
- │ │ ├── index.jsx # Public home view (Auto-Route: /)
81
- │ │ ├── about.jsx # About page view (Auto-Route: /about)
82
- │ │ ├── login.jsx # Sign-in page view (Auto-Route: /login)
83
- │ │ └── dashboard.jsx # Protected dashboard view (Auto-Route: /dashboard)
114
+ │ ├── resources/ # Everything client-side
115
+ │ │ ├── index.html # React SPA shell (router.spa() + npx bluebird-js export)
116
+ │ │ ├── spa.js # SPA config: mount, title, description, per-URL meta tree
117
+ │ │ ├── styles.css # Tailwind CSS v4 entry (shared by HTML SSR + React SPA)
118
+ │ │ ├── main.jsx # createRoot + AuthProvider + RouterProvider
119
+ │ │ ├── routes.jsx # createRouter + lazy routes
120
+ │ │ ├── layouts/AppLayout.jsx
121
+ │ │ ├── pages/ # Home.jsx, Login.jsx, Register.jsx, Dashboard.jsx, NotFound.jsx
122
+ │ │ └── html/ # HTML {{ }} SSR templates
123
+ │ │ ├── layouts/main.html
124
+ │ │ ├── partials/
125
+ │ │ ├── home.html
126
+ │ │ ├── terms.html
127
+ │ │ └── notFound.html (404 page for unknown routes)
128
+ │ ├── models/ # BaseModel definitions (user.js)
129
+ │ ├── routes/ # Express routes (web.js, auth.js, api.js)
84
130
  │ └── jobs/ # Background worker job handlers
85
- ├── public/ # Public static assets (CSS, JS, images, fonts)
86
- │ ├── js/
87
- │ │ ├── tailwind.js # Built-in Tailwind CSS runtime
88
- │ │ └── bluebird-client.js # Client UI kit, View Transitions & SPA router
89
- │ └── images/
131
+ ├── public/ # Static assets (js/bluebird.js, images/, build/)
90
132
  ├── core/ # Bluebird.js framework core
91
133
  ├── database/ # SQLite storage and SQL migrations
92
- │ └── migrations/ # Version-controlled SQL migrations
93
- ├── .env # Environment variables
134
+ ├── .env
94
135
  └── package.json
95
136
  ```
96
137
 
@@ -218,264 +259,215 @@ npx bluebird-js migrate --yes
218
259
 
219
260
  ---
220
261
 
221
- ### 3. React JSX SSR, Declarative Auto-Routes & `<Client>` Skeletons
262
+ ### 3. HTML `{{ }}` SSR Rendering & React Router SPA (`router.spa()`)
222
263
 
223
- #### Default Tailwind CSS & Inter Typography
264
+ Bluebird separates **server-rendered HTML pages** (landings, storefronts, marketing, legal pages) from **client-rendered React Router SPAs** (dashboards, admin panels, interactive apps).
224
265
 
225
- The default layout (`app/views/layouts/main/view.jsx`) comes pre-wired with Google Fonts `Inter` and the standalone Tailwind CSS v4 runtime (`/js/tailwind.js`). You can write pure Tailwind utility classes immediately without running Vite, PostCSS, or Tailwind CLI.
266
+ #### 404 Pages
226
267
 
227
- #### Native `.jsx` Views & Declarative Auto-Routes
268
+ Unknown routes return JSON under `/api` (and for JSON clients), and for browsers render `app/resources/html/notFound.html` (with `{{ path }}`) inside the `main` layout, or a built-in page when that view does not exist. Inside a `router.spa()` mount the React `NotFound` page (`{ path: "*" }` in `routes.jsx`) handles them. Disable it with `new App({ notFound: false })`.
228
269
 
229
- Bluebird compiles `.jsx` files in memory using Node's native module hooks (`core/jsx.js`)—no external bundler or disk temp files required. Even better, any view inside `app/views/` (excluding `layouts/`, `components/`, `partials/`, `islands/`, and `/api`) can export its own route configuration (`route`, `cache`, `middlewares`, `layout`, `seo`) and `App` mounts it automatically on startup (pass `noAutoDiscoverRoutes: true` to `new App()` if you prefer manual registration only):
270
+ #### HTML `{{ }}` Templates (`app/resources/html/`)
230
271
 
231
- ```jsx
232
- // app/views/components/Header.jsx
233
- export default function Header({ title, user, count = 0 }) {
234
- return (
235
- <header className="flex items-center justify-between p-6 border-b border-slate-800">
236
- <div>
237
- <h1 className="text-2xl font-bold text-slate-100">{title}</h1>
238
- <p className="text-sm text-slate-400">Welcome back, {user?.name || "Guest"}</p>
239
- </div>
240
- <span className="px-3 py-1 rounded-full text-xs font-semibold bg-sky-500/10 text-sky-400 border border-sky-500/20">
241
- Notifications: {count}
242
- </span>
243
- </header>
272
+ ```javascript
273
+ // app/routes/web.js
274
+ import Router from "@seip/bluebird-js/core/router.js";
275
+ import Render from "@seip/bluebird-js/core/render.js";
276
+
277
+ const routerWeb = new Router("/", { seo: true });
278
+
279
+ routerWeb.get("/", (req, res) => {
280
+ const clientsHtml = clients.map((c) => `<span>${c.name}</span>`).join("");
281
+ return Render.html(
282
+ res,
283
+ "home",
284
+ { title: "Welcome", clientsHtml, slides },
285
+ { layout: "main", cache: 300 }
244
286
  );
245
- }
287
+ });
246
288
  ```
247
289
 
248
- ```jsx
249
- // app/views/dashboard.jsx
250
- import Auth from "@seip/bluebird-js/core/auth.js";
251
- import Actions from "@seip/bluebird-js/core/actions.js";
252
- import { Client } from "@seip/bluebird-js/core/jsx.js";
253
- import Header from "./components/Header.jsx";
254
- import LiveCounter from "./components/LiveCounter.js";
255
-
256
- export const route = "/dashboard";
257
- export const layout = "main";
258
- export const middlewares = [Auth.protect({ redirect: "/login" })];
259
- export const seo = false;
260
- export const head = (data) => ({ title: `Dashboard — ${data.user?.name || "Member"}` });
261
-
262
- // Server Actions: automatic CSRF, 16KB maxBytes guard, prototype pollution filter & Validator schema
263
- export const actions = {
264
- syncCount: Actions.define(
265
- {
266
- maxBytes: "16kb",
267
- schema: { count: { required: true, number: true } },
268
- },
269
- async ({ body, user }) => {
270
- return { syncedCount: Number(body.count), updatedBy: user?.email };
271
- }
272
- ),
273
- };
274
-
275
- export default async function DashboardView({ user, syncedCount = 7 }) {
276
- return (
277
- <>
278
- <Header title="Protected Dashboard" user={user} count={syncedCount} />
279
-
280
- <div className="space-y-6 mt-6">
281
- {/* Reusable imported Client component with persistent state & anti-CLS skeleton */}
282
- <Client
283
- component={LiveCounter}
284
- props={{ initial: syncedCount }}
285
- persistent={true}
286
- minHeight={56}
287
- skeleton={
288
- <div className="h-14 rounded-xl bg-slate-900 animate-pulse flex items-center px-4 text-xs text-slate-400">
289
- Loading interactive widget...
290
- </div>
291
- }
292
- />
290
+ ```html
291
+ <!-- app/resources/html/home.html -->
292
+ <section>
293
+ <h1>{{ title }}</h1>
294
+ <div>{{{ clientsHtml }}}</div>
295
+ {{#if slides}}
296
+ <div data-carousel data-autoplay="5000">
297
+ <div data-carousel-track>
298
+ {{#each slides}}<div data-carousel-slide>{{ title }}</div>{{/each}}
293
299
  </div>
294
- </>
295
- );
296
- }
300
+ <div data-carousel-dots></div>
301
+ </div>
302
+ {{/if}}
303
+ </section>
297
304
  ```
298
305
 
299
- #### Reactive Client Components & `useAction` (`LiveCounter.jsx`)
306
+ #### React Router SPA (`router.spa()`)
300
307
 
301
- Client components run in the browser using Bluebird's micro-reactive runtime with hooks (`useState`, `useEffect`, `useAction`, `useActionState`, `useRef`, `html` tagged templates). You can invoke Server Actions or standard API endpoints and handle native DOM events with standard `event.preventDefault()`:
308
+ The SPA config lives in `app/resources/spa.js`, so the web server and the static export share the same title, description, and meta tree. `router.spa()` renders the React shell `app/resources/index.html` with per-URL SEO tags, JSON-LD, canonical links, custom scripts/styles, and a full-width inline skeleton inside `<div id="root">`:
302
309
 
303
- ```jsx
304
- // app/views/components/LiveCounter.jsx
305
- import { useState, useEffect, useAction } from "@seip/bluebird-js/core/jsx.js";
306
- import { html } from "@seip/bluebird-js/core/html.js";
307
-
308
- export default function LiveCounter({ initial = 7, label = "Client Counter" }) {
309
- const [count, setCount] = useState(Number(initial) || 0);
310
- const [sync, isPending] = useAction("syncCount", {
311
- onSuccess(res) {
312
- window.toast?.({ title: "Synced", description: res.data.message });
313
- },
314
- });
310
+ ```javascript
311
+ // app/resources/spa.js
312
+ export default {
313
+ mount: "/app",
314
+ lang: "en",
315
+ titleTemplate: "%s — My App",
316
+ skeleton: "app",
317
+ meta: {
318
+ "*": { title: "Workspace", robots: "noindex, nofollow", skeleton: "app" },
319
+ "/": { title: "Explore", description: "Interactive workspace", robots: "index, follow", skeleton: "page" },
320
+ "login": { title: "Sign In", keywords: "login, auth", skeleton: "auth", jsonld: { "@type": "WebPage" } },
321
+ "/app/register": { title: "Register", skeleton: "auth" },
322
+ },
323
+ };
324
+ ```
315
325
 
316
- const actualizarDashboard = (event) => {
317
- event.preventDefault(); // Native DOM event support
318
- sync({ count }); // Dispatches Server Action with pending states
319
- };
326
+ ```javascript
327
+ // app/routes/web.js
328
+ import spa from "../resources/spa.js";
320
329
 
321
- return html`
322
- <div class="h-14 rounded-xl border border-slate-800 bg-slate-950/90 px-4 flex items-center justify-between">
323
- <span class="text-xs text-slate-300">${label}: <strong class="text-sky-400 font-mono">${count}</strong></span>
324
- <div class="flex items-center gap-2">
325
- <button type="button" onClick=${() => setCount(count + 1)} class="px-2.5 py-1 bg-sky-500 rounded text-xs font-bold text-slate-950">+1</button>
326
- <button type="button" onClick=${actualizarDashboard} disabled=${isPending} class="px-2.5 py-1 bg-emerald-500/15 border border-emerald-500/30 rounded text-xs text-emerald-300">
327
- ${isPending ? "Syncing..." : "Sync Server Action"}
328
- </button>
329
- </div>
330
- </div>
331
- `;
332
- }
330
+ routerWeb.spa(spa.mount, spa);
333
331
  ```
334
332
 
335
- #### `<ErrorBoundary>` & Dynamic `<Head>` Hoisting
333
+ Keys inside `meta` accept both relative (`"login"`) and absolute (`"/app/login"`) formats, dynamic functions `(req, params) => ({ ... })`, and `"*"` wildcard defaults. The React entry defaults to `app/resources/main.jsx` and the shell to `app/resources/index.html` (`template: false` uses the built-in shell).
334
+
335
+ The React shell (`app/resources/index.html`) and the HTML SSR layout (`app/resources/html/layouts/main.html`) are separate files on purpose: the first one is also the entry of the static export.
336
+
337
+ #### Design System & Theming
336
338
 
337
- Catch rendering errors during SSR in subtrees and hoist metadata directly into the document `<head>`:
339
+ Bluebird ships a neutral, shadcn-style design system shared by React components and HTML `{{ }}` views. The Vite plugin injects it right after `@import "tailwindcss"` in your stylesheet, so there is nothing to import:
340
+
341
+ - **Tokens** (light and dark): `background`, `foreground`, `card`, `popover`, `primary`, `secondary`, `muted`, `accent`, `destructive`, `border`, `input`, `ring`, `brand`, `success`, `warning`, `info`, used as Tailwind utilities (`bg-primary`, `text-muted-foreground`, `border-border`...).
342
+ - **Component classes** for plain HTML: `btn` + `btn-primary | btn-secondary | btn-outline | btn-ghost | btn-danger | btn-link` + `btn-sm | btn-lg | btn-icon`, `card` / `card-title` / `card-description`, `field` / `field-label` / `field-hint` / `field-error`, `badge` / `badge-dot`, `nav-link` (active with `aria-current="page"`), `glass`, `bg-app`, and `brand`.
343
+ - **Color is used sparingly**: `primary` (near-black in light, near-white in dark) for the main action, `secondary`/`outline`/`ghost` for the rest, `danger` for destructive actions, and `brand` only for the logo. Badges and toasts stay neutral with a small colored dot for the tone.
344
+
345
+ ```html
346
+ <a href="/app" class="btn btn-primary">Open app</a>
347
+ <button class="btn btn-outline btn-sm">Cancel</button>
348
+ <span class="badge"><span class="badge-dot bg-success"></span>Live</span>
349
+ ```
338
350
 
339
351
  ```jsx
340
- import { ErrorBoundary, Head, Title, Meta } from "@seip/bluebird-js/core/jsx.js";
341
-
342
- export default function ProfilePage({ user }) {
343
- return (
344
- <>
345
- <Head>
346
- <Title>Profile — {user.name}</Title>
347
- <Meta name="robots" content="noindex,nofollow" />
348
- </Head>
349
-
350
- <ErrorBoundary fallback={(err) => <div className="p-4 bg-red-950 text-red-400 rounded-xl">Error: {err.message}</div>}>
351
- <UserProfileWidget userId={user.id} />
352
- </ErrorBoundary>
353
- </>
354
- );
355
- }
352
+ import { Button, Link, buttonVariants } from "@seip/bluebird-js/react";
353
+
354
+ <Button variant="danger" size="sm">Delete</Button>
355
+ <Link to="/new" className={buttonVariants({ variant: "outline" })}>New post</Link>
356
+ ```
357
+
358
+ Customize it by overriding the variables in `app/resources/styles.css` (your values win over the defaults), or turn the injection off with `bluebird({ theme: false })` in `vite.config.js`:
359
+
360
+ ```css
361
+ :root { --primary: oklch(0.55 0.2 264); --primary-foreground: oklch(0.98 0 0); --brand: oklch(0.65 0.2 30); }
362
+ .dark { --primary: oklch(0.7 0.16 264); --primary-foreground: oklch(0.15 0 0); }
356
363
  ```
357
364
 
358
- #### Streaming SSR with `<Suspense>` & Instant Cache HIT
365
+ #### Component Languages (i18n)
359
366
 
360
- Stream progressive chunked HTML responses with immediate skeletons. If route cache is enabled (`cache: 60`), cache misses stream progressively while caching the assembled final HTML, and subsequent requests are served as **instant Cache HITs** without streaming overhead:
367
+ Built-in UI strings (toast badges, close buttons, carousel controls, loading and error fallbacks, theme toggle labels) follow the page language from `<html lang>`: `{{ lang }}` in HTML views and `lang` in `app/resources/spa.js` for the React SPA. English, Spanish, Portuguese, French, German, and Italian are included; regional tags fall back to their base language (`es-AR` uses `es`) and unknown languages fall back to English. In Spanish, `toast.success()` shows **Correcto**, `toast.warning()` **Cuidado**, and `toast.error()` **Error**.
361
368
 
362
369
  ```jsx
363
- import { Suspense } from "@seip/bluebird-js/core/jsx.js";
370
+ import { addMessages, setLocale, useLocale } from "@seip/bluebird-js/react";
364
371
 
365
- export const cache = 60; // Subsequent hits served instantly from RAM LRU
372
+ addMessages("es", { "toast.warning": "Atención" });
373
+ addMessages("ja", { "toast.success": "成功", "toast.warning": "注意", "toast.error": "エラー" });
374
+ setLocale("es");
366
375
 
367
- export default function FeedPage() {
368
- return (
369
- <div>
370
- <h1>Live Activity</h1>
371
- <Suspense fallback={<div className="h-40 animate-pulse bg-slate-900 rounded-xl">Loading feed...</div>}>
372
- <AsyncFeedList />
373
- </Suspense>
374
- </div>
375
- );
376
- }
376
+ const { locale, t } = useLocale();
377
+ t("carousel.status", { n: 2, total: 5 });
377
378
  ```
378
379
 
379
- #### Zero-Build TypeScript & TSX Support (`.tsx`, `.ts`)
380
+ HTML views get the same strings from `public/js/bluebird.js` through `Bluebird.i18n.t()`, `Bluebird.i18n.addMessages()`, and `Bluebird.i18n.setLocale()`. A custom `badge` on a toast always wins over the translated label.
380
381
 
381
- Write views and components directly in TypeScript. Bluebird strips type annotations natively in memory using Node's native module customization hooks with zero build steps and zero disk temp files:
382
+ #### Client React API (`@seip/bluebird-js/react`) & Auth
382
383
 
383
- ```tsx
384
- // app/views/components/UserCard.tsx
385
- interface UserProps {
386
- id: number;
387
- name: string;
388
- role: "admin" | "member";
389
- }
390
-
391
- export default function UserCard({ id, name, role }: UserProps): any {
392
- return (
393
- <div className="user-card" data-id={id}>
394
- <strong>{name}</strong> <span>({role})</span>
395
- </div>
396
- );
397
- }
384
+ ```jsx
385
+ // app/resources/main.jsx
386
+ import { createRoot } from "react-dom/client";
387
+ import { RouterProvider } from "react-router/dom";
388
+ import { AuthProvider, Toaster } from "@seip/bluebird-js/react";
389
+ import "./styles.css";
390
+ import { router } from "./routes.jsx";
391
+
392
+ createRoot(document.getElementById("root")).render(
393
+ <AuthProvider>
394
+ <RouterProvider router={router} />
395
+ <Toaster />
396
+ </AuthProvider>
397
+ );
398
398
  ```
399
399
 
400
- ---
400
+ ```jsx
401
+ // app/resources/routes.jsx
402
+ import { createRouter } from "@seip/bluebird-js/react";
401
403
 
402
- ### 4. Built-in Client UI Kit (`public/js/bluebird-client.js`)
404
+ export const router = createRouter(routes, { basename: "/app" });
405
+ ```
403
406
 
404
- Bluebird includes a lightweight, dependency-free client UI toolkit with Tailwind CSS styles built right into `public/js/bluebird-client.js`:
407
+ - **Router**: `createRouter()` uses `createBrowserRouter` (with `basename`) on the server and `createHashRouter` in static exports or under `file://`.
408
+ - **Auth hooks & route guards**: `useAuth()` (`user`, `loading`, `authenticated`, `registerEnabled`, `login`, `register`, `logout`, `refresh`, `hasRole`), `<RequireAuth roles={["admin"]} />` (optional `roles` — without `roles`, any signed-in user passes), and `<GuestOnly />`.
409
+ - **REST helper**: `api.get/post/put/patch/delete(url, body)` sends `X-CSRF-Token` (cookie sessions) or `Authorization: Bearer` (token mode), parses JSON, and normalizes `Validator` errors into `ApiError.errors`. Configure with `configureApi({ baseUrl, auth: "cookie" | "token" })`.
410
+ - **UI Components (Light + Dark Tailwind)**: `Link`, `Button`, `Form`, `SubmitButton`, `Input`, `Textarea`, `Select`, `Card`, `Badge`, `Carousel`, `Modal`, `Drawer`, `Skeleton`, `PageSkeleton`, `ProgressBar`, `Spinner`, `ThemeToggle`, `useTheme`, `Toaster` / `toast`, `cn()`.
411
+ - **Vanilla Browser Helpers (`public/js/bluebird.js`)**: `data-carousel`, `data-toast`, `data-modal` / `data-modal-open`, `data-dropdown`, `data-tabs`, `data-theme-toggle`, `data-copy`, `data-confirm`, `data-password-toggle`, and `form[data-form]`.
405
412
 
406
- #### Toasts & Snackbars
413
+ #### Role-Protected Backend & Optional Register (`app/routes/auth.js`)
407
414
 
408
415
  ```javascript
409
- toast({
410
- title: "Profile Updated",
411
- description: "Your settings have been saved successfully.",
412
- type: "success",
413
- position: "top-right",
414
- duration: 4000,
415
- });
416
+ import Auth from "@seip/bluebird-js/core/auth.js";
417
+ import { createAuthRouter } from "./app/routes/auth.js";
416
418
 
417
- snackbar({ message: "Network connection restored", type: "info" });
418
- ```
419
+ const routerAuth = createAuthRouter({ register: true });
419
420
 
420
- Or trigger them declaratively via HTML attributes:
421
- ```html
422
- <button data-toast="Settings saved successfully!" data-toast-type="success">Save</button>
423
- <button data-snackbar="Item deleted" data-snackbar-type="error">Delete</button>
421
+ routerApi.get("/profile", Auth.protect(), (req, res) => res.ok({ user: req.user }));
422
+ routerApi.get("/admin/stats", Auth.protect({ roles: "admin" }), (req, res) => res.ok({ ok: true }));
424
423
  ```
425
424
 
426
- #### Drawers & Mobile Navigation
425
+ The auth and API routers apply `Csrf.middleware()`. Browser sessions use an HttpOnly cookie; clients sending `X-Auth-Mode: token` (static exports) receive `{ user, token }` and authenticate with `Authorization: Bearer`, which is CSRF-exempt because it is never sent automatically by the browser.
427
426
 
428
- ```html
429
- <button data-drawer-target="cartDrawer">Open Cart</button>
427
+ #### Static Export: Electron, Capacitor & Static Hosting (`npx bluebird-js export`)
430
428
 
431
- <div id="cartDrawer" class="hidden fixed top-0 right-0 h-full w-80 bg-slate-900 p-6 z-50">
432
- <button data-drawer-close="cartDrawer" class="text-slate-400">&times;</button>
433
- <h3>Shopping Cart</h3>
434
- </div>
435
- ```
429
+ Builds the same React code, `index.html` shell, and `spa.js` metadata into a 100% static HTML/JS/CSS folder:
436
430
 
437
- #### Responsive Data Table (`ResponsiveDataTable`)
431
+ ```bash
432
+ npx bluebird-js export --api https://api.example.com # dist/client (hash router, ./ assets)
433
+ npx bluebird-js export --out mobile/www --api https://api.example.com
434
+ npx bluebird-js export --router browser --base / --out dist/web # static host with history fallback
435
+ ```
438
436
 
439
- Transforms tables dynamically into touch-friendly cards on mobile devices:
437
+ | Option | Default | Purpose |
438
+ |---|---|---|
439
+ | `--out <dir>` | `dist/client` | Output folder (refuses `app/`, `core/`, `public/`, or the project root) |
440
+ | `--api <url>` | `EXPORT_API_URL` or `APP_URL` | Base URL prepended by `api()` to `/api/*` |
441
+ | `--router <mode>` | `hash` | `hash` (works with `file://`), `browser`, or `memory` |
442
+ | `--base <path>` | `./` (`/` for browser) | Asset base URL |
443
+ | `--auth <mode>` | `token` | `token` (Bearer in `localStorage`) or `cookie` |
444
+ | `--config <file>` | `app/resources/spa.js` | SPA config module |
445
+ | `--no-public` | | Skip copying `public/` |
440
446
 
441
447
  ```javascript
442
- new ResponsiveDataTable("usersTableContainer", {
443
- columns: [
444
- { key: "id", label: "ID", sortable: true },
445
- { key: "name", label: "Name", sortable: true },
446
- { key: "email", label: "Email" },
447
- { key: "role", label: "Role" },
448
- ],
449
- data: usersList,
450
- searchable: true,
451
- pagination: true,
452
- pageSize: 10,
453
- onEdit: (row) => editUser(row.id),
454
- onDelete: (row) => deleteUser(row.id),
455
- });
448
+ // Electron main process (static client, no embedded server)
449
+ mainWindow.loadFile(path.join(__dirname, "dist/client/index.html"));
456
450
  ```
457
451
 
458
- #### Declarative SPA Forms (`data-bb-form`)
459
-
460
- ```html
461
- <form action="/api/profile" method="POST" data-bb-form="true">
462
- <input type="text" name="name" required />
463
- <button type="submit">Update</button>
464
- </form>
452
+ ```json
453
+ // capacitor.config.json
454
+ { "appId": "com.example.app", "appName": "Example", "webDir": "dist/client" }
465
455
  ```
466
- Submissions are automatically handled via `fetch`, CSRF tokens are injected, and toasts/redirects are handled seamlessly via View Transitions.
467
456
 
468
- #### Declarative DOM Helpers
457
+ Use `isExported()` to hide web-only UI (for example links to HTML pages) inside the exported build. The embedded-server Electron mode (`desktop: true`) keeps working as before.
469
458
 
470
- - `data-copy="Text to copy"`: Copies text to clipboard on click.
471
- - `data-confirm="Are you sure?"`: Confirms before link navigation or button click.
472
- - `data-toggle="theme"`: Switches between dark and light modes and updates the `dark` class on `<html>`.
473
- - `data-password-toggle="passwordFieldId"`: Toggles password visibility.
474
- - `data-filter-target="tableId"`: Live filters rows or cards matching input value.
459
+ #### Development & Production
460
+
461
+ ```bash
462
+ npm run dev # bluebird-js dev: Express + Vite on one port (HMR + Tailwind v4), restarts on server file changes
463
+ npx bluebird-js build # Builds client SPA & Tailwind CSS bundle into public/build/
464
+ npm start # Production: serves public/build/.vite/manifest.json
465
+ npx bluebird-js export # Static React build for Electron, Capacitor, or static hosting
466
+ ```
475
467
 
476
468
  ---
477
469
 
478
- ### 5. Multi-Driver Caching (`core/cache.js`)
470
+ ### 4. Multi-Driver Caching (`core/cache.js`)
479
471
 
480
472
  ```javascript
481
473
  import Cache from "@seip/bluebird-js/core/cache.js";
@@ -486,9 +478,23 @@ const metrics = await Cache.get("metrics", { driver: "memory" });
486
478
  await Cache.set("report", htmlContent, 300, { driver: "file" });
487
479
  ```
488
480
 
481
+ HTML render caches (`Render.html(..., { cache: 300 })`, `Render.cache(300)`, `router.spa(..., { cache: 300 })`) are keyed by path. Query strings bypass the cache unless allowlisted (`cacheQuery: ["page"]` or `Render.cache(300, { query: ["page"] })`), preventing cache flooding. Cached pages restore each visitor's own CSRF token and CSP nonce.
482
+
483
+ #### Security Defaults (CORS & CSP)
484
+
485
+ ```javascript
486
+ const app = new App({
487
+ routes: [routerWeb, routerApi],
488
+ // "*" never reflects origins nor sends credentials. Credentialed CORS requires an allowlist:
489
+ cors: { origin: ["https://app.example.com"], credentials: true },
490
+ // {nonce} becomes a per-request nonce added to every inline <script>/<style> Bluebird renders:
491
+ security: { csp: "default-src 'self'; script-src 'self' 'nonce-{nonce}'" },
492
+ });
493
+ ```
494
+
489
495
  ---
490
496
 
491
- ### 6. Desktop Applications (Electron & Desktop Mode)
497
+ ### 5. Desktop Applications (Electron & Desktop Mode)
492
498
 
493
499
  Bluebird.js runs natively embedded inside **Electron** applications with ultra-fast boot (<200ms) and minimal RAM consumption (~25–40 MB vs ~300 MB with Nextron):
494
500
 
@@ -500,15 +506,19 @@ Bluebird.js runs natively embedded inside **Electron** applications with ultra-f
500
506
  npx bluebird-js add electron
501
507
  ```
502
508
 
509
+ The generated desktop scripts run `npx bluebird-js build` before `electron-builder`, so pages are served from the production build inside the `.asar` bundle.
510
+
511
+ Prefer a client-only desktop or mobile app that talks to a remote API? Use `npx bluebird-js export` (section 3) and load `dist/client/index.html` with `mainWindow.loadFile()` or Capacitor.
512
+
503
513
  ---
504
514
 
505
- ### 7. Unified AI Client (`core/ai.js`)
515
+ ### 6. Unified AI Client (`core/ai.js`)
506
516
 
507
- Native zero-dependency AI client supporting **DeepSeek (default)**, **Google Gemini**, and **OpenAI** with reversible PII data masking, 0ms prompt caching, sliding window rate limits, and JSON schema validation:
517
+ Built-in AI client (no provider SDKs required) supporting **DeepSeek (default)**, **Google Gemini**, and **OpenAI** with reversible PII data masking, 0ms prompt caching, sliding window rate limits, and JSON schema validation:
508
518
 
509
519
  - **DeepSeek by Default (`deepseek-flash`):** Default endpoint `https://api.deepseek.com`, served by DeepSeek-V4.1-Flash-1017 (legacy names `deepseek-v4-flash`, `deepseek-chat` supported). Optional thinking mode (`thinking: { type: "enabled" }`, `reasoningEffort: "high"`).
510
520
  - **Google Gemini & OpenAI:** Built-in REST connectors for `gemini-3.5-flash`, `gemini-3.8-flash`, `gemini-2.5-flash`, `gpt-4o-mini`, and custom endpoints via `baseURL`.
511
- - **Accurate Real IP Detection (`getClientIp`):** Resolves real visitor IPs across Cloudflare (`cf-connecting-ip`, `true-client-ip`), Nginx (`x-real-ip`), proxy chains (`x-forwarded-for`), and cleans IPv6 mappings.
521
+ - **Accurate Real IP Detection (`getClientIp`):** Resolves real visitor IPs across Cloudflare (`cf-connecting-ip`, `true-client-ip`), Nginx (`x-real-ip`), proxy chains (`x-forwarded-for`), and cleans IPv6 mappings. Proxy headers are only trusted from local/private reverse proxies (`trustProxy` defaults to `"loopback, linklocal, uniquelocal"`; set it to your CDN hop count when needed), so clients cannot spoof them to bypass rate limits.
512
522
  - **Reversible PII Masking:** Replaces sensitive user keys (`name`, `email`, `dni`, etc.) with anonymous tokens (`[name_01]`, `[email_01]`) before transmission, restoring original values in responses.
513
523
  - **0ms Prompt Cache Hit:** Computes cache hashes on *anonymized* prompts so multiple users querying identical prompt templates trigger an immediate $0 / 0ms Cache Hit.
514
524
  - **Rate Limit Protection ("Anti-Quiebra"):** Configurable per-minute/per-day sliding windows (e.g. `{ minute: 6, day: 30 }`), returning clean HTTP 429 errors via `ai.protect()` middleware before depleting API budget.
@@ -553,7 +563,7 @@ for await (const chunk of supportAi.askStream("Explain quantum computing in simp
553
563
 
554
564
  ---
555
565
 
556
- ### 8. Atomic Database Backups & Verification (`core/database.js`)
566
+ ### 7. Atomic Database Backups & Verification (`core/database.js`)
557
567
 
558
568
  WAL-safe, non-blocking snapshots for SQLite using `VACUUM INTO` and gzip compression, with automated retention rotation and integrity-verified restore:
559
569
 
@@ -575,10 +585,13 @@ await Database.restore("database/backups/backup-sqlite-2026-11-03_170000_123.db.
575
585
  ## Developer Tooling CLI
576
586
 
577
587
  ```bash
588
+ npx bluebird-js [--blank|--auth|--blog|--api|--demo] # Scaffolds a project from a template (default: blank)
578
589
  npx bluebird-js doctor # Diagnostic audit and HTTP smoke tests
579
590
  npx bluebird-js make:model <Name> # Generates BaseModel class
580
591
  npx bluebird-js make:route <name> [--auth] # Scaffolds REST route
581
- npx bluebird-js make:view <name> [--ejs] # Scaffolds HTML/EJS template
592
+ npx bluebird-js make:view <name> [--partial|--layout] # Scaffolds an HTML {{ }} template view
593
+ npx bluebird-js build # Builds client SPA and Tailwind CSS bundle (public/build/)
594
+ npx bluebird-js export [--api url] [--out dir] # Static React export (Electron, Capacitor, static hosts)
582
595
  npx bluebird-js make:migration [name] # Smart auto-migration from app/models/
583
596
  npx bluebird-js make:migration --model <Model> # Generates migration for specific Model
584
597
  npx bluebird-js migrate [--yes] # Executes pending migrations
@@ -587,11 +600,11 @@ npx bluebird-js migrate:rollback # Reverts latest migration
587
600
  npx bluebird-js make:seed <name> # Creates database seed file
588
601
  npx bluebird-js seed # Executes database seeds
589
602
  npx bluebird-js db:backup [--keep 10] [--out dir] # Compressed WAL-safe database backup with retention rotation
603
+ npx bluebird-js dev [entry] [--watch dir] # Dev server (Vite HMR) restarting only on server file changes
590
604
  npx bluebird-js db:restore <file> [--yes] # Safe database restore with pre-backup & integrity check
591
605
  npx bluebird-js nginx:conf [domain] [port] [root] # Generates Nginx reverse proxy configuration
592
606
  npx bluebird-js make:ecosystem [--start] # Generates PM2 clustering config
593
607
  npx bluebird-js add electron # Scaffolds Electron desktop app & desktop.js
594
- npx bluebird-js add react-islands # Scaffolds React Islands, Vite & Client Router
595
608
  npx bluebird-js add <module> # Installs optional on-demand package
596
609
  ```
597
610