@seip/bluebird-js 0.0.0-stage → 0.0.1

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 (73) hide show
  1. package/.env_example +54 -0
  2. package/AGENTS.md +403 -0
  3. package/LICENSE +21 -0
  4. package/README.md +284 -2
  5. package/app/routes/api.js +50 -0
  6. package/app/routes/web.js +53 -0
  7. package/app/views/about.html +161 -0
  8. package/app/views/dashboard.html +140 -0
  9. package/app/views/index.html +150 -0
  10. package/app/views/login.html +144 -0
  11. package/core/app.d.ts +18 -0
  12. package/core/app.js +644 -0
  13. package/core/auth.d.ts +13 -0
  14. package/core/auth.js +326 -0
  15. package/core/cache.d.ts +17 -0
  16. package/core/cache.js +475 -0
  17. package/core/cli/doctor.js +287 -0
  18. package/core/cli/ecosystem.js +162 -0
  19. package/core/cli/init.js +779 -0
  20. package/core/cli/migrate.js +541 -0
  21. package/core/cli/model.js +66 -0
  22. package/core/cli/nginx.js +199 -0
  23. package/core/cli/route.js +121 -0
  24. package/core/cli/swagger.js +45 -0
  25. package/core/cli/view.js +77 -0
  26. package/core/config.d.ts +3 -0
  27. package/core/config.js +111 -0
  28. package/core/csrf.d.ts +3 -0
  29. package/core/csrf.js +114 -0
  30. package/core/database.d.ts +15 -0
  31. package/core/database.js +636 -0
  32. package/core/debug.d.ts +3 -0
  33. package/core/debug.js +250 -0
  34. package/core/hash.d.ts +3 -0
  35. package/core/hash.js +194 -0
  36. package/core/index.d.ts +1071 -0
  37. package/core/logger.d.ts +3 -0
  38. package/core/logger.js +124 -0
  39. package/core/middleware.d.ts +3 -0
  40. package/core/middleware.js +28 -0
  41. package/core/model.d.ts +19 -0
  42. package/core/model.js +600 -0
  43. package/core/queue.d.ts +13 -0
  44. package/core/queue.js +172 -0
  45. package/core/ratelimit.d.ts +3 -0
  46. package/core/ratelimit.js +145 -0
  47. package/core/redis.d.ts +21 -0
  48. package/core/redis.js +230 -0
  49. package/core/render.d.ts +3 -0
  50. package/core/render.js +676 -0
  51. package/core/router.d.ts +3 -0
  52. package/core/router.js +171 -0
  53. package/core/seo.d.ts +3 -0
  54. package/core/seo.js +106 -0
  55. package/core/swagger.d.ts +3 -0
  56. package/core/swagger.js +60 -0
  57. package/core/upload.d.ts +13 -0
  58. package/core/upload.js +102 -0
  59. package/core/util/colors.js +82 -0
  60. package/core/validate.d.ts +15 -0
  61. package/core/validate.js +364 -0
  62. package/core/vite.d.ts +3 -0
  63. package/core/vite.js +145 -0
  64. package/core/ws.d.ts +13 -0
  65. package/core/ws.js +245 -0
  66. package/index.js +18 -0
  67. package/jsconfig.json +15 -0
  68. package/package.json +84 -3
  69. package/production.md +273 -0
  70. package/public/css/bluebird.min.css +2 -0
  71. package/public/images/favicon.ico +0 -0
  72. package/public/js/bluebird-client.js +1663 -0
  73. package/public/js/bluebird.min.js +1073 -0
package/.env_example ADDED
@@ -0,0 +1,54 @@
1
+ # Server and Application Configuration
2
+ DEBUG=true
3
+ PORT=3000
4
+ HOST="localhost"
5
+ APP_URL="http://localhost:3000"
6
+ VERSION="1.0.0"
7
+
8
+ # Application Metadata
9
+ TITLE="Bluebird Application"
10
+ DESCRIPTION="Bluebird.js Web and API Project"
11
+
12
+ # Security Configuration
13
+ JWT_SECRET="CHANGE_ME_TO_A_LONG_RANDOM_STRING_AT_LEAST_32_CHARS"
14
+
15
+ # Cache Configuration
16
+ # Options: "memory" (fast in-process LRU, default), "file" (filesystem cache fallback), "redis" (distributed cache), "none" (disabled)
17
+ CACHE_MODE="memory"
18
+ CACHE_MAX_KEYS=1000
19
+
20
+ # Redis Configuration (Used when CACHE_MODE="redis" or passing { driver: "redis" })
21
+ REDIS_HOST="localhost"
22
+ REDIS_PORT=6379
23
+ REDIS_PASSWORD=""
24
+
25
+ # PM2 Clustering Configuration
26
+ PM2_APP_NAME="bluebird-app"
27
+ PM2_INSTANCES=1
28
+ PM2_MAX_MEMORY="512M"
29
+
30
+ # Render Cache Configuration
31
+ RENDER_CACHE_TTL=300
32
+ RENDER_CACHE_MAX=500
33
+
34
+ # Database Configuration
35
+ # SQLite (Default - native node:sqlite with WAL mode)
36
+ DB_TYPE="sqlite"
37
+ DB_FILE="database/blue_bird.db"
38
+ DATABASE_URL="sqlite:database/blue_bird.db"
39
+
40
+ # MySQL (Uncomment to use MySQL)
41
+ # DB_TYPE="mysql"
42
+ # DB_NAME="blue_bird"
43
+ # DB_USER="root"
44
+ # DB_PASSWORD="root"
45
+ # DB_PORT=3306
46
+ # DATABASE_URL="mysql://root:root@localhost:3306/blue_bird"
47
+
48
+ # PostgreSQL (Uncomment to use PostgreSQL)
49
+ # DB_TYPE="postgres"
50
+ # DB_NAME="blue_bird"
51
+ # DB_USER="postgres"
52
+ # DB_PASSWORD="root"
53
+ # DB_PORT=5432
54
+ # DATABASE_URL="postgresql://postgres:root@localhost:5432/blue_bird?schema=public"
package/AGENTS.md ADDED
@@ -0,0 +1,403 @@
1
+ # Bluebird.js Framework - AI Agent Guide
2
+
3
+ This document serves as the primary manual for any AI Agent interacting with the codebase. It details the architecture of Bluebird.js (`@seip/bluebird-js`), its internal modules, and how features should be written or modified.
4
+
5
+ ## 1. Core Architecture
6
+
7
+ Bluebird.js is a performance-first web and API framework built on **Express** (Node.js 22.18+). It provides pure modern JavaScript ESM execution, JWT auth, HTML rendering with multi-level caching, BaseModel, schema validation, database access, and queue processing out of the box.
8
+
9
+ - **Entrypoint (`index.js`)**: Located at the project root. Initializes the server using `App` from `core/app.js` and registers the routes.
10
+ - **Application (`app/`)**: Application code — `app/routes/` (API + web), `app/models/` (BaseModels), `app/views/` (HTML templates), `app/jobs/` (background workers).
11
+ - **Public assets (`public/`)**: Static files only (CSS, JS, images, fonts). Served directly by Nginx or Express fallback.
12
+ - **Core (`core/`)**: The framework core. Contains `Router`, `Render`, `Validator`, `Auth`, `Cache`, `Redis`, `Database`, `Model`, `Csrf`, `Hash`, etc. **DO NOT MODIFY** the core unless explicitly requested.
13
+
14
+ ## 2. Modern JavaScript Standard (ESM)
15
+
16
+ Bluebird.js standardizes on pure modern JavaScript (Node.js 22.18+ ESM) with zero build steps or transpilation pipelines required:
17
+
18
+ - **Root Entrypoint (`index.js`)**: Run in development with `node --watch --env-file=.env index.js`.
19
+ - **Production Entrypoint (`index.js`)**: Run with `node --env-file=.env index.js` or via PM2 cluster.
20
+ - **Initialization**: `npx bluebird-js` scaffolds a new project directly with `index.js` at the root.
21
+ - **IDE Intellisense**: Powered by `core/index.d.ts` and `jsconfig.json`.
22
+
23
+ ```javascript
24
+ import App from "@seip/bluebird-js/core/app.js";
25
+ import routerApi from "./app/routes/api.js";
26
+ import routerWeb from "./app/routes/web.js";
27
+
28
+ const app = new App({
29
+ routes: [routerWeb, routerApi],
30
+ port: process.env.PORT || 3000,
31
+ });
32
+
33
+ app.run();
34
+ ```
35
+
36
+ ## 3. Routing (Router)
37
+
38
+ Do not use Express' native router directly. Always use Bluebird's `Router` wrapper.
39
+
40
+ ```javascript
41
+ import Router from "@seip/bluebird-js/core/router.js";
42
+
43
+ const routerApi = new Router("/api");
44
+
45
+ routerApi.get("/users", (req, res) => {
46
+ res.json({ users: [] });
47
+ });
48
+
49
+ export default routerApi;
50
+ ```
51
+
52
+ When created with `{ seo: true }`, all GET routes registered on that router are tracked for search engine indexing.
53
+
54
+ ## 4. Request Validation (Validator)
55
+
56
+ Incoming request data is validated using `core/validate.js`, which automatically returns HTTP 400 JSON responses on error. The validator inspects request payloads without destructively mutating raw data.
57
+
58
+ ```javascript
59
+ import Validator from "@seip/bluebird-js/core/validate.js";
60
+
61
+ const userSchema = {
62
+ email: { required: true, email: true },
63
+ password: { required: true, min: 8 },
64
+ bio: { required: false },
65
+ };
66
+
67
+ const validateUser = new Validator(userSchema, "en");
68
+
69
+ routerApi.post("/users", validateUser.middleware(), (req, res) => {
70
+ res.json({ success: true });
71
+ });
72
+ ```
73
+
74
+ ## 5. Lightweight BaseModel (Model)
75
+
76
+ > **Important Architecture Note:**
77
+ > Bluebird's `BaseModel` (`core/model.js`) is designed as a lightweight, zero-dependency static facade for high performance, simple queries, soft deletes, and migrations.
78
+ > **For complex multi-tier enterprise ORM mapping, Prisma is recommended.**
79
+
80
+ ### Defining a Model
81
+
82
+ Create models inside `app/models/`:
83
+
84
+ ```javascript
85
+ import Model from "@seip/bluebird-js/core/model.js";
86
+
87
+ export default class User extends Model {
88
+ static table = "users";
89
+ static primaryKey = "id";
90
+ static timestamps = true;
91
+ static softDelete = true;
92
+
93
+ static schema = {
94
+ id: { type: "int", primary: true, auto: true },
95
+ name: { type: "string", length: 150, required: true },
96
+ email: { type: "string", length: 150, unique: true, required: true, email: true },
97
+ password: { type: "string", length: 255, required: true, min: 8, hidden: true, hash: true },
98
+ role: { type: "string", length: 20, default: "user", in: ["user", "admin"] },
99
+ };
100
+ }
101
+ ```
102
+
103
+ ### CRUD Shortcuts & Query Facades
104
+
105
+ Every Model exposes direct shortcuts to database queries, transactions, and mutations:
106
+
107
+ ```javascript
108
+ const total = await User.query("SELECT COUNT(*) as count FROM users", [], "return_row");
109
+ await User.transaction(async (tx) => {
110
+ await tx.query("UPDATE users SET role = ? WHERE id = ?", ["admin", 1]);
111
+ });
112
+
113
+ const userId = await User.create({ name: "Alice", email: "alice@example.com", password: "secretPassword" });
114
+
115
+ const user = await User.find(1, { cache: 60 });
116
+ const userWithPosts = await User.find(1, { oneMany: Post });
117
+ const postWithAuthor = await Post.find(10, { belongsTo: User });
118
+
119
+ const page = await User.paginate({ where: { role: "user" }, page: 1, limit: 10 });
120
+ await User.update(userId, { name: "Alice Smith" });
121
+
122
+ await User.delete(userId);
123
+ await User.delete(userId, { force: true });
124
+ await User.delete(userId, { cascade: [Post] });
125
+ await User.restore(userId);
126
+ ```
127
+
128
+ ## 6. CSRF Protection (Csrf)
129
+
130
+ Bluebird provides native, zero-dependency HMAC-signed CSRF protection (`core/csrf.js`):
131
+
132
+ ```javascript
133
+ import Csrf from "@seip/bluebird-js/core/csrf.js";
134
+
135
+ routerWeb.use(Csrf.middleware());
136
+ ```
137
+
138
+ ## 7. Authentication & Password Hashing (Auth & Hash)
139
+
140
+ ### Password Hashing (Hash)
141
+
142
+ Native password hashing using `node:crypto.scrypt` with random salt and timing-safe comparison (zero external npm dependencies required).
143
+
144
+ ```javascript
145
+ import Hash from "@seip/bluebird-js/core/hash.js";
146
+
147
+ const hash = await Hash.make("mySecretPassword");
148
+ const isValid = await Hash.verify("mySecretPassword", hash);
149
+ ```
150
+
151
+ ### JWT Handling (Auth)
152
+
153
+ Native JWT handling with AES-256-GCM encryption and HMAC-SHA256 signature verification using `node:crypto`.
154
+
155
+ ```javascript
156
+ import Auth from "@seip/bluebird-js/core/auth.js";
157
+
158
+ router.get("/profile", Auth.protect(), (req, res) => {
159
+ res.json({ user: req.user });
160
+ });
161
+
162
+ router.post("/login", async (req, res) => {
163
+ const user = { id: 1, name: "John" };
164
+ await Auth.login(res, user);
165
+ res.ok(user, "Logged in");
166
+ });
167
+
168
+ router.post("/logout", async (req, res) => {
169
+ await Auth.logout(res);
170
+ res.ok(null, "Logged out");
171
+ });
172
+ ```
173
+
174
+ ## 8. HTTP Response Helpers & Health Check
175
+
176
+ Bluebird decorates the Express `res` object with standardized helper methods:
177
+
178
+ ```javascript
179
+ res.ok(data, "Success message");
180
+ res.created(data, "Created successfully");
181
+ res.paginate(items, pagination, "Fetched");
182
+
183
+ res.badRequest("Invalid input", errors);
184
+ res.unauthorized("Authentication required");
185
+ res.forbidden("Access denied");
186
+ res.notFound("Resource not found");
187
+ res.serverError("Internal failure", err);
188
+ ```
189
+
190
+ Every Bluebird application provides a native `/api/health` endpoint returning uptime, timestamp, environment, and memory consumption.
191
+
192
+ ## 9. Performance Caching (Cache & Redis)
193
+
194
+ Caching defaults to fast in-memory LRU storage, ideal for desktop applications and single or dual PM2 instances. Filesystem caching (`driver: "file"`) is available as persistent local fallback, and Redis (`driver: "redis"`) is isolated in `core/redis.js` on-demand for high-traffic environments.
195
+
196
+ ```javascript
197
+ import Cache from "@seip/bluebird-js/core/cache.js";
198
+
199
+ router.get("/stats", Cache.middleware(60), (req, res) => {
200
+ res.ok({ usersCount: 150 });
201
+ });
202
+
203
+ await Cache.set("custom_key", { data: "value" }, 120, { driver: "memory" });
204
+ const cachedData = await Cache.get("custom_key", { driver: "memory" });
205
+
206
+ const stats = await Cache.deduplicate("stats-key", async () => {
207
+ return await calculateHeavyStats();
208
+ });
209
+
210
+ await Cache.delete("custom_key");
211
+ await Cache.clear();
212
+ ```
213
+
214
+ ## 10. Database Module (database.js)
215
+
216
+ Bluebird provides a unified wrapper class (`core/database.js`) supporting **SQLite (native `node:sqlite` in Node 22.18+ with `better-sqlite3` fallback)**, **MySQL (`mysql2/promise`)**, and **PostgreSQL (`pg`)**:
217
+
218
+ - **Native SQLite by Default:** No native C++ compilation or build tools required.
219
+ - **SQLite Concurrency & WAL:** Automatically configures WAL mode, busy timeout, and memory-mapped I/O.
220
+ - **Prepared Statement Caching:** SQLite caches prepared statement ASTs automatically.
221
+ - **Query Caching:** Supports `{ cache: 60 }` across memory, file, and redis backends.
222
+
223
+ ```javascript
224
+ import { Database, DB_TYPE } from "@seip/bluebird-js/core/database.js";
225
+
226
+ const connection = new Database(20);
227
+
228
+ const user = await connection.query("SELECT * FROM users WHERE id = ?", [1], "return_row");
229
+ const stats = await connection.query("SELECT COUNT(*) as cnt FROM logs", [], { cache: 60 });
230
+
231
+ await connection.transaction(async (tx) => {
232
+ const id = await tx.query("INSERT INTO users (name) VALUES (?)", ["Alice"]);
233
+ await tx.query("INSERT INTO profiles (user_id) VALUES (?)", [id]);
234
+ });
235
+ ```
236
+
237
+ ## 11. On-Demand Modules & CLI Add
238
+
239
+ To keep dependencies lightweight and minimal, optional modules load dynamically on-demand:
240
+
241
+ ```bash
242
+ npx bluebird-js add upload # Installs multer for file uploads
243
+ npx bluebird-js add ws # Installs ws for WebSockets
244
+ npx bluebird-js add redis # Installs redis for distributed caching
245
+ npx bluebird-js add sqlite # Installs better-sqlite3 (fallback for older environments)
246
+ npx bluebird-js add mysql # Installs mysql2
247
+ npx bluebird-js add postgres # Installs pg
248
+ npx bluebird-js add bcrypt # Installs bcrypt
249
+ npx bluebird-js add swagger # Installs swagger-ui-express & swagger-jsdoc
250
+ npx bluebird-js add helmet # Installs helmet
251
+ npx bluebird-js add ejs # Installs ejs
252
+ npx bluebird-js add react-islands # Installs react, react-dom, vite & scaffolds island runtime
253
+ ```
254
+
255
+ ## 12. Security, Rate Limiting & SEO (Security Headers, Helmet, RateLimit, Seo)
256
+
257
+ Bluebird includes native zero-dependency security headers enabled by default (`X-Content-Type-Options: nosniff`, `X-XSS-Protection: 0`, `X-Frame-Options: SAMEORIGIN`, `Referrer-Policy: strict-origin-when-cross-origin`, `Permissions-Policy`).
258
+
259
+ ### Native Rate Limiting (`core/ratelimit.js`)
260
+
261
+ Configure rate limiting globally via `new App({ rateLimit })` or per-route via `App.rateLimit()` (supports `"memory"` and `"redis"` drivers):
262
+
263
+ ```javascript
264
+ import App from "@seip/bluebird-js/core/app.js";
265
+
266
+ const app = new App({
267
+ routes: [routerWeb, routerApi],
268
+ rateLimit: { max: 120, windowMs: 60000 },
269
+ });
270
+
271
+ routerApi.post("/login", App.rateLimit({ max: 5, windowMs: 60000 }), async (req, res) => {
272
+ res.ok({ authenticated: true });
273
+ });
274
+ ```
275
+
276
+ ### Automatic SEO Sitemap & Robots (`core/seo.js`)
277
+
278
+ When a `Router` is created with `{ seo: true }`, all static `GET` routes are automatically registered and exposed at `/sitemap.xml` and `/robots.txt` by `App`.
279
+
280
+ ### Helmet Integration
281
+
282
+ Helmet can be applied per router when installed (`npx bluebird-js add helmet`):
283
+
284
+ ```javascript
285
+ import App from "@seip/bluebird-js/core/app.js";
286
+
287
+ const apiRouter = new Router("/api");
288
+ apiRouter.use(App.helmet());
289
+ ```
290
+
291
+ ## 13. Production Deployment & Electron Desktop Mode
292
+
293
+ ### PM2 & Nginx Reverse Proxy
294
+
295
+ Production deployments run directly via `npm start` or PM2 cluster mode:
296
+
297
+ ```bash
298
+ npx bluebird-js make:ecosystem # Generates ecosystem.config.cjs
299
+ npx bluebird-js make:ecosystem --start # Generates and starts immediately in PM2
300
+ npx bluebird-js nginx:conf [domain] [port] [root] # Generates Nginx config with upstream keepalive & static try_files
301
+ ```
302
+
303
+ For complete deployment details including Nginx reverse proxy configuration and optional standalone Docker snippet, consult [production.md](production.md).
304
+
305
+ ### Electron & Desktop Mode (`desktop: true`)
306
+
307
+ Bluebird supports running embedded inside Electron or Tauri desktop applications where the application bundle (`.asar`) is read-only:
308
+
309
+ - Automatically routes SQLite database files, `logs/`, and `app/cache/` to a writable OS user data directory (`Config.userDataDir()`), copying initial bundled SQLite databases on first run.
310
+ - Binds strictly to `127.0.0.1` with dynamic port allocation (`port: 0`) via `await app.runDesktop()`.
311
+
312
+ ```javascript
313
+ const app = new App({
314
+ desktop: true,
315
+ userDataPath: electronApp.getPath("userData"),
316
+ routes: [routerWeb, routerApi],
317
+ });
318
+
319
+ const { url, port } = await app.runDesktop();
320
+ mainWindow.loadURL(url);
321
+ ```
322
+
323
+ ## 14. Developer Tooling CLI
324
+
325
+ ```bash
326
+ npx bluebird-js doctor # Project diagnostics and HTTP smoke tests
327
+ npx bluebird-js make:model <Name> # BaseModel scaffolding
328
+ npx bluebird-js make:route <name> # REST route scaffolding
329
+ npx bluebird-js make:route <name> --auth # Authenticated REST route scaffolding
330
+ npx bluebird-js make:view <name> # HTML or EJS template scaffolding
331
+ npx bluebird-js make:migration <name> # Blank SQL migration
332
+ npx bluebird-js make:migration --model <Model> # Auto DDL migration from Model schema
333
+ npx bluebird-js make:migration --all # Batch generate migrations for all models
334
+ npx bluebird-js migrate # Applies pending migrations
335
+ npx bluebird-js migrate:status # Displays applied batches
336
+ npx bluebird-js migrate:rollback # Reverts latest batch
337
+ npx bluebird-js make:seed <name> # Database seed file creation
338
+ npx bluebird-js seed # Executes database seeds
339
+ npx bluebird-js nginx:conf [domain] [port] [root] # Generates Host Nginx reverse proxy
340
+ npx bluebird-js make:ecosystem [--start] # Generates PM2 cluster configuration
341
+ ```
342
+
343
+ ## 15. Background Jobs & Queue (Queue)
344
+
345
+ Lightweight background worker (`core/queue.js`) backed by Redis with automatic in-memory fallback.
346
+
347
+ ```javascript
348
+ import Queue from "@seip/bluebird-js/core/queue.js";
349
+
350
+ Queue.process("sendWelcomeEmail", async (payload) => {
351
+ console.log(`Sending email to ${payload.email}...`);
352
+ });
353
+
354
+ await Queue.dispatch("sendWelcomeEmail", { email: "user@example.com" });
355
+ await Queue.work();
356
+ ```
357
+
358
+ ## 16. HTML Views, Layouts, Partials/Components, React Islands & Client Router
359
+
360
+ Bluebird provides a hybrid architecture uniting database-driven server-rendered HTML with server-side components/partials, shared layouts, selective React client interactivity, and instant View Transitions SPA navigation:
361
+
362
+ - **L0 In-Memory Template Cache**: In production (`DEBUG=false`), raw template files from `app/views/` are cached in memory on first read, eliminating disk I/O even on uncached dynamic dashboard routes.
363
+ - **HTML Templates**: Located in `app/views/` and delivered with `Render.send()`, `Render.partial()`, `Render.stream()`, or `Render.view()`. Variables are interpolated using `{{ key }}` (HTML-escaped) or `{{{ key }}}` (raw HTML / JSON-LD).
364
+ - **Shared Layouts**: Declare `{{!< main }}` at the top of any view (or pass `{ _layout: "main" }`) to wrap the rendered view inside `app/views/layouts/main.html` at `{{{ body }}}`. When requested with `X-Bluebird-Partial: 1`, layouts are automatically bypassed for fast partial swaps.
365
+ - **Server Partials / Components with Props**: Include reusable components from `app/views/partials/` or `app/views/components/` directly inside `.html` templates with custom props:
366
+ `{{> stat_card title="Revenue" value=stats.revenue active=true }}`
367
+ Or render components programmatically via `Render.component("stat_card", { title: "Revenue", value: "$9,500" })` and `Render.partial(res, "stat_card", data)`.
368
+ - **Loops & Conditionals**:
369
+ - `{{#each items as item}} <li>{{ item_index }}: {{ item.name }}</li> {{/each}}`
370
+ - `{{#if user.isAdmin}} <button>Manage</button> {{else}} <span>Guest</span> {{/if}}`
371
+ - **React Islands**: Located in `src/islands/`. Hydrated selectively on DOM elements matching `[data-island]`.
372
+ - **Dynamic Head Assets (`{{{ bluebirdHead }}}`)**: Powered by `core/vite.js`. In development (`DEBUG=true`), injects React Fast Refresh preamble and Vite HMR client. In production (`DEBUG=false`), resolves hashed CSS/JS from `public/dist/.vite/manifest.json`.
373
+ - **Client Router (`public/js/bluebird-client.js`)**:
374
+ - Native `document.startViewTransition()` page navigation.
375
+ - Partial DOM fragment swaps via `data-partial-target="#selector"` on links or `await Bluebird.renderPartial(url, "#selector")` with automatic redirect handling.
376
+ - Bounded TTL link prefetching on hover (`max 50 entries`, `60s TTL`).
377
+ - Automatic unmounting of non-persistent React roots on page transitions.
378
+ - Persistent components via `data-persist="true"` (live media streams, audio players, persistent cart state are never interrupted during navigation).
379
+ - Cross-island event bus and reactive store (`window.Bluebird.store`, `window.Bluebird.emit()`, `window.Bluebird.on()`).
380
+ - **Scaffolding**: Run `npx bluebird-js add react-islands` to install dependencies and scaffold Vite configs and demo components.
381
+
382
+ ```html
383
+ {{!< main }}
384
+ <section class="dashboard-grid">
385
+ {{> stat_card title="Active Users" value=stats.users active=true }}
386
+
387
+ <ul>
388
+ {{#each servers as srv}}
389
+ <li>{{ srv.name }} — {{#if srv.online}}Online{{else}}Offline{{/if}}</li>
390
+ {{/each}}
391
+ </ul>
392
+
393
+ <div data-island="RadioPlayer" data-props='{"stream":"https://live.mp3"}' data-persist="true"></div>
394
+ <div data-island="LiveCounter" data-props='{"initial": 0}'></div>
395
+ </section>
396
+ ```
397
+
398
+ ## 17. AI Development Guidelines
399
+
400
+ 1. **Assets & Views**: Static assets in `public/`. HTML views, layouts (`app/views/layouts/`), and partials (`app/views/partials/`) in `app/views/` served via `Render.view()`, `Render.send()`, or `Render.partial()`.
401
+ 2. **JSON Responses**: Use decorated `res.ok()`, `res.created()`, `res.badRequest()`, etc.
402
+ 3. **No inline comments**: Preserve code cleanliness. Use **ONLY JSDoc comments** (`/** ... */`).
403
+ 4. **All documentation in English**.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Andres Paiva
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.