@nmvuong92/fluxe 0.7.0 → 0.9.1

package/README.md

@@ -8,8 +8,8 @@ Khung fullstack tối giản — **một runtime TypeScript** (chạy trên `nod
 trên triết lý **RCA — Resolved Cell Architecture**: *logic chỉ phụ thuộc HỢP ĐỒNG; mọi quyết định
 vận hành (render, backend data) là **kết quả được GIẢI** bởi engine, không viết tay.*
 
-> Đổi backend data `memory ↔ sqlite ↔ postgres`, đổi render `static ↔ island`, gộp nhiều backend
-> trong một app per-cell — tất cả chỉ sửa `app/profiles.ts`, **cell & frontend không đổi một dòng**.
+> Đổi backend data `memory ↔ sqlite ↔ postgres` chỉ một dòng trong `app/backend.ts`, đổi render
+> `static ↔ island` qua profile — **cell & frontend không đổi một dòng**.
 
 ## Cài & dùng (npm)
 
@@ -18,17 +18,17 @@ npm i @nmvuong92/fluxe react react-dom zod
 ```
 
 ```ts
-import { defineCell, withInput, makeServer, createMemoryBackend } from "@nmvuong92/fluxe";
+import { defineCell, withInput, makeServer } from "@nmvuong92/fluxe";
 import { useQuery, useMutation, Link, Nav, ThemeToggle } from "@nmvuong92/fluxe/react";
 import { rpc } from "@nmvuong92/fluxe/client";
 ```
 
 | Import | Nội dung |
 |--------|----------|
-| `@nmvuong92/fluxe` | engine: defineCell, makeServer, resolver, auth, validate, backends, seo, broker, ratelimit, codegen… |
+| `@nmvuong92/fluxe` | engine: defineCell, makeServer, resolver, auth, validate, seo, broker, ratelimit, codegen… (KHÔNG có driver data — backend là của bạn ở `app/backend.ts`) |
 | `@nmvuong92/fluxe/react` | useQuery, useMutation, Link, Nav, ThemeToggle, useTheme, DebugBar |
 | `@nmvuong92/fluxe/client` | rpc, RpcError, mutate, revalidate, subscribe |
-| `@nmvuong92/fluxe/jobs` · `/sqlite` | queue/dead-letter · SQLite backend (cần `--experimental-sqlite`) |
+| `@nmvuong92/fluxe/jobs` | queue/dead-letter (cần `--experimental-sqlite`) |
 
 ## Chạy nhanh
 
@@ -36,7 +36,7 @@ import { rpc } from "@nmvuong92/fluxe/client";
 npm install
 npm run fx -- build        # resolve + prerender + bundle (1 schema → types TS qua fx gen)
 npm run fx -- dev          # http://localhost:5180
-npm run test:all           # typecheck + 107 unit + 28 integration — TẤT CẢ XANH
+npm run test:all           # typecheck + 144 unit + integration (selftest2) — TẤT CẢ XANH
 ```
 
 `fx`: `gen · resolve · prerender · build · dev · test · jobs`.
@@ -47,9 +47,12 @@ npm run test:all           # typecheck + 107 unit + 28 integration — TẤT C
 app/        ← DEV sở hữu (sửa thoải mái) — Contract Plane
   cells/        trang/feature (route + loader + view + action/head/layout/guard)
   layouts/      layout dùng chung (nested)
-  profiles.ts   CHỌN backend data per môi trường + per-cell (memory/sqlite/postgres)
+  server.ts     server entry — Express/Hono/Nest mount fluxe (mặc định Express)
+  backend.ts    TẦNG DATA của bạn: interface domain + chọn driver (memory/sqlite/postgres)
+  profiles.ts   profile resolve render mode (static/island) per môi trường
   contract.ts   schema → codegen types TS
   env.ts        env có kiểu, validate fail-fast lúc boot
+  app.ts        registry cell — sinh tự động (fx sync), đừng sửa
 
 src/        ← ENGINE (không đụng) — Resolution Plane
   core/         resolver · router · errors · auth · validate · codegen · layouts ·
@@ -57,15 +60,16 @@ src/        ← ENGINE (không đụng) — Resolution Plane
   server_factory.ts   runtime ráp cell + giải manifest
 ```
 
-**Quy tắc:** "backend nào đang chạy" do `app/profiles.ts` (config) quyết, **không** do vị trí
-folder. Engine không bao giờ import ngược vào `app/`.
+**Quy tắc:** backend là **tầng data của bạn** ở `app/backend.ts` (interface domain + chọn driver),
+inject qua `makeServer(…, { backend })`. Engine không bao giờ import ngược vào `app/`.
 
 ## Tính năng (tất cả TDD + chạy thật)
 
+- **Server** — chạy zero-config (`makeServer`, node:http) HOẶC nhúng vào **Express/Hono/Nest** qua adapter (`@nmvuong92/fluxe/express|hono|nest`)
 - **Render** — static (0 JS) · island hydrate · SPA nav (Inertia) · static-prerender · API mode `?json=1`
 - **Routing** — động `[param]` → `ctx.input` · **nested layouts** · SEO (head/canonical/OG/JSON-LD per cell, `/sitemap.xml`, `/robots.txt`)
 - **Bảo mật (đầy đủ)** — input validation (Zod) · auth password **scrypt** · **RBAC** · **CSRF** double-submit · **rate-limit** token-bucket · error handling không-leak + structured
-- **Data** — backend TS per-cell (`memory`/`sqlite`/`postgres`) · DB **SQLite thật** (`node:sqlite`) + **Postgres** (inject client `pg`) · **codegen contract** 1 schema → types TS
+- **Data** — backend **user-owned** ở `app/backend.ts` (bạn tự định nghĩa interface + implement bằng `node:sqlite`/`pg`/ORM trực tiếp), inject qua `makeServer(…, { backend })` · engine 0 driver · **codegen contract** 1 schema → types TS
 - **Mutations DX** — `RpcError` có cấu trúc · `mutate()` optimistic + rollback · lỗi validation field-level
 - **Realtime (Trục 4g)** — **SSE channel** + pub/sub broker · live-update on action · **presence** (multi-tab)
 - **Async** — **job queue bền** (SQLite, retry → dead-letter)
@@ -73,24 +77,54 @@ folder. Engine không bao giờ import ngược vào `app/`.
 - **Config** — env có kiểu, fail-fast lúc boot
 - **DX** — `fx` CLI · mock `Backend` test cực dễ · typecheck gate
 
-## Backend data (driver TS in-process)
+## Backend data (user-owned, TS in-process)
 
-Backend chỉ là **driver data TypeScript in-process** — chọn qua `app/profiles.ts`, cell không đổi:
+Backend là **tầng data của bạn** — định nghĩa interface domain ở `app/backend.ts` + chọn driver
+**TS in-process** dưới đây, inject qua `makeServer(…, { backend })`. Cell chỉ thấy interface:
 
-| Driver | Ghi chú |
-|--------|---------|
-| `memory` | in-process, mặc định dev |
-| `sqlite` | `node:sqlite` built-in, 0 dep, persist ra file (engine tự dựng) |
-| `postgres` | production — **bạn tự inject client `pg`** (`npm i pg` + `DATABASE_URL`) |
+| Driver | Bạn tự implement bằng |
+|--------|------------------------|
+| `memory` | object in-RAM — mặc định dev |
+| `sqlite` | `node:sqlite` built-in (`DatabaseSync`), 0 dep, persist ra file (cần `--experimental-sqlite`) |
+| `postgres` | `npm i pg`, dùng `Pool`/`Client` trực tiếp (`DATABASE_URL`) |
 
 ```ts
-export const profiles = {
-  dev:    { name: "dev",    backend: "memory" },
-  sqlite: { name: "sqlite", backend: "sqlite" },
-  mixed:  { name: "mixed",  backend: "memory", cellBackends: { todos: "sqlite" } },
-};
+// app/backend.ts — engine không biết gì
+import { DatabaseSync } from "node:sqlite";
+
+export interface Todo { id: string; title: string; done: boolean }
+export interface Backend {
+  name: string;
+  listTodos(): Promise<Todo[]>;
+  addTodo(title: string): Promise<Todo>;
+  toggleTodo(id: string): Promise<Todo[]>;
+}
+
+export function memoryBackend(): Backend {
+  let items: Todo[] = [];
+  let seq = 0;
+  return {
+    name: "memory",
+    async listTodos() { return items; },
+    async addTodo(title) { const t = { id: String(++seq), title, done: false }; items.push(t); return t; },
+    async toggleTodo(id) { items = items.map((t) => t.id === id ? { ...t, done: !t.done } : t); return items; },
+  };
+}
+
+export function sqliteBackend(path = ":memory:"): Backend {
+  const db = new DatabaseSync(path);
+  db.exec(`CREATE TABLE IF NOT EXISTS todos (id INTEGER PRIMARY KEY AUTOINCREMENT, title TEXT, done INTEGER DEFAULT 0)`);
+  // … CRUD bằng db.prepare(...)
+  return { name: "sqlite" } as any;
+}
+
+export const backend: Backend = process.env.FLUXE_SQLITE_PATH
+  ? sqliteBackend(process.env.FLUXE_SQLITE_PATH)   // đổi 1 dòng = đổi nơi lưu
+  : memoryBackend();
 ```
 
+Nguồn khác (REST/ORM/Redis)? Tự implement `Backend` là xong — engine không quan tâm bên dưới.
+
 ## Triết lý
 
 Toàn bộ định hướng, các trục chiến lược, tenets và nguyên lý RCA: xem **[idea.md](idea.md)**.

package/lib/adapters/express.d.ts

@@ -0,0 +1,3 @@
+import type { RequestHandler } from "express";
+import { createHandler } from "../server_factory.ts";
+export declare function fluxe(...args: Parameters<typeof createHandler>): RequestHandler;

package/lib/adapters/express.js

@@ -0,0 +1,7 @@
+import { createHandler } from "../server_factory.js";
+/* Mount fluxe như middleware (đặt SAU các route riêng của bạn — fluxe là catch-all):
+ *   app.use(fluxe(manifest, cells, layouts, { backend }));  */
+export function fluxe(...args) {
+    const handler = createHandler(...args);
+    return (req, res, next) => { handler(req, res).catch(next); };
+}

package/lib/adapters/hono.d.ts

@@ -0,0 +1,3 @@
+import type { MiddlewareHandler } from "hono";
+import { createHandler } from "../server_factory.ts";
+export declare function fluxe(...args: Parameters<typeof createHandler>): MiddlewareHandler;

package/lib/adapters/hono.js

@@ -0,0 +1,48 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
+/* Adapter Hono (chạy trên Node qua @hono/node-server). `hono` + `@hono/node-server` là peerDependency.
+ * Hono yêu cầu handler trả về Web `Response`; còn createHandler ghi vào node res. Ta dùng một
+ * "capture shim": chạy handler vào res đệm (buffer) rồi dựng Response chuẩn → Hono ghi sạch,
+ * không đụng nội bộ node-server. (Đánh đổi: buffer toàn response thay vì stream — chấp nhận được
+ * cho lớp adapter; muốn stream thì dùng makeServer/Express.) */
+import { Writable } from "node:stream";
+import { createHandler } from "../server_factory.js";
+class CaptureRes extends Writable {
+    statusCode = 200;
+    headersSent = false;
+    headers = {};
+    chunks = [];
+    writeHead(status, headers) {
+        this.statusCode = status;
+        if (headers)
+            for (const k of Object.keys(headers))
+                this.headers[k.toLowerCase()] = headers[k];
+        this.headersSent = true;
+        return this;
+    }
+    setHeader(k, v) { this.headers[k.toLowerCase()] = v; return this; }
+    getHeader(k) { return this.headers[k.toLowerCase()]; }
+    _write(chunk, _enc, cb) { this.chunks.push(Buffer.from(chunk)); cb(); }
+}
+/* Mount fluxe như catch-all (đặt SAU route Hono riêng của bạn):
+ *   app.use("*", fluxe(manifest, cells, layouts, { backend }));
+ *   serve({ fetch: app.fetch, port: 5180 });   // từ @hono/node-server  */
+export function fluxe(...args) {
+    const handler = createHandler(...args);
+    return async (c) => {
+        const { incoming } = c.env;
+        const res = new CaptureRes();
+        const finished = new Promise((resolve) => res.on("finish", resolve));
+        await handler(incoming, res);
+        await finished;
+        const headers = new Headers();
+        for (const [k, v] of Object.entries(res.headers)) {
+            if (Array.isArray(v))
+                v.forEach((x) => headers.append(k, String(x)));
+            else
+                headers.set(k, String(v));
+        }
+        const body = Buffer.concat(res.chunks);
+        return new Response(body.length ? body : null, { status: res.statusCode, headers });
+    };
+}

package/lib/adapters/nest.d.ts

@@ -0,0 +1,3 @@
+import type { NestMiddleware } from "@nestjs/common";
+import { createHandler } from "../server_factory.ts";
+export declare function fluxeMiddleware(...args: Parameters<typeof createHandler>): NestMiddleware["use"];

package/lib/adapters/nest.js

@@ -0,0 +1,9 @@
+import { createHandler } from "../server_factory.js";
+/* Functional middleware — mount global (khuyên dùng, catch-all đặt sau route Nest):
+ *   const app = await NestFactory.create(AppModule);
+ *   app.use(fluxeMiddleware(manifest, cells, layouts, { backend }));
+ * (hoặc consumer.apply(...).forRoutes("{*splat}") trong module — Nest 11 dùng wildcard mới). */
+export function fluxeMiddleware(...args) {
+    const handler = createHandler(...args);
+    return (req, res, next) => { handler(req, res).catch(next); };
+}

package/lib/core/cli.js

@@ -47,7 +47,7 @@ export const COMMANDS = {
     },
     dev: {
         desc: "Sync + resolve + build client + chạy server",
-        shell: (a) => `${SYNC} && tsx scripts/resolve.ts ${p(a)} && ${ESBUILD} && tsx src/server.tsx`,
+        shell: (a) => `${SYNC} && tsx scripts/resolve.ts ${p(a)} && ${ESBUILD} && tsx app/server.ts`,
     },
     test: {
         desc: "Sync + typecheck + unit + integration",

package/lib/core/config.d.ts

@@ -3,7 +3,6 @@ declare const Schema: z.ZodObject<{
     env: z.ZodEnum<["development", "production", "test"]>;
     secret: z.ZodString;
     port: z.ZodNumber;
-    defaultBackend: z.ZodEnum<["memory", "sqlite", "postgres"]>;
     rateLimit: z.ZodObject<{
         capacity: z.ZodNumber;
         refillPerSec: z.ZodNumber;
@@ -42,7 +41,6 @@ declare const Schema: z.ZodObject<{
     env: "development" | "production" | "test";
     secret: string;
     port: number;
-    defaultBackend: "memory" | "sqlite" | "postgres";
     rateLimit: {
         capacity: number;
         refillPerSec: number;
@@ -61,7 +59,6 @@ declare const Schema: z.ZodObject<{
     env: "development" | "production" | "test";
     secret: string;
     port: number;
-    defaultBackend: "memory" | "sqlite" | "postgres";
     rateLimit: {
         capacity: number;
         refillPerSec: number;
@@ -83,7 +80,6 @@ export declare const ENV_KEYS: {
     readonly NODE_ENV: "env";
     readonly FLUXE_SECRET: "secret";
     readonly "PORT (ho\u1EB7c FLUXE_PORT)": "port";
-    readonly FLUXE_BACKEND: "defaultBackend";
     readonly FLUXE_RATELIMIT_CAPACITY: "rateLimit.capacity";
     readonly FLUXE_RATELIMIT_REFILL: "rateLimit.refillPerSec";
     readonly FLUXE_RATELIMIT_MAX_KEYS: "rateLimit.maxKeys";

package/lib/core/config.js

@@ -9,7 +9,6 @@ const Schema = z.object({
     env: z.enum(["development", "production", "test"]),
     secret: z.string().min(8),
     port: z.coerce.number().int().positive(),
-    defaultBackend: z.enum(["memory", "sqlite", "postgres"]),
     rateLimit: z.object({
         capacity: z.coerce.number().int().positive(),
         refillPerSec: z.coerce.number().positive(),
@@ -24,7 +23,6 @@ export const ENV_KEYS = {
     "NODE_ENV": "env",
     "FLUXE_SECRET": "secret",
     "PORT (hoặc FLUXE_PORT)": "port",
-    "FLUXE_BACKEND": "defaultBackend",
     "FLUXE_RATELIMIT_CAPACITY": "rateLimit.capacity",
     "FLUXE_RATELIMIT_REFILL": "rateLimit.refillPerSec",
     "FLUXE_RATELIMIT_MAX_KEYS": "rateLimit.maxKeys",
@@ -52,7 +50,6 @@ export function loadConfig(source = process.env, overrides = {}) {
         env: source.NODE_ENV || "development",
         secret: source.FLUXE_SECRET || "dev-secret-change-me",
         port: num(source, "PORT", num(source, "FLUXE_PORT", 5180)),
-        defaultBackend: source.FLUXE_BACKEND || "memory",
         rateLimit: {
             capacity: num(source, "FLUXE_RATELIMIT_CAPACITY", 30),
             refillPerSec: num(source, "FLUXE_RATELIMIT_REFILL", 10),

package/lib/core/panel.js

@@ -8,7 +8,6 @@ export function renderResolutionPanel(m, requests = []) {
         <td><code>${c.route}</code></td>
         <td>${c.render.mode}</td>
         <td>${c.render.shipClientJs ? "✓ JS" : "0 JS"}</td>
-        <td><span class="badge ${c.backend.language}">${c.backend.language}</span></td>
       </tr>`).join("");
     return `<!doctype html><html lang="vi"><head><meta charset="utf-8"><title>fluxe — RCA Resolution</title>
 <style>
@@ -19,14 +18,12 @@ export function renderResolutionPanel(m, requests = []) {
   th,td{text-align:left;padding:.5rem .75rem;border-bottom:1px solid #2a2a40}
   th{color:#8a8aa0;font-weight:600;font-size:.78rem;text-transform:uppercase;letter-spacing:.04em}
   code{background:#1a1a2e;padding:.1rem .35rem;border-radius:4px;color:#a0a0ff}
-  .badge{display:inline-block;padding:.1rem .55rem;border-radius:99px;font-size:.78rem}
-  .memory{background:#7c7cff33;color:#a0a0ff}.sqlite{background:#00add833;color:#5fd3f0}.postgres{background:#dea58433;color:#e8b48f}
 </style></head>
 <body>
   <h1>RCA Resolution</h1>
-  <div class="sub">profile <b>${m.profile}</b> · default backend <b>${m.backend.language}</b> (in-process)</div>
+  <div class="sub">profile <b>${m.profile}</b> · data = backend user-owned (app/backend.ts)</div>
   <table>
-    <thead><tr><th>cell</th><th>route</th><th>render</th><th>JS</th><th>backend</th></tr></thead>
+    <thead><tr><th>cell</th><th>route</th><th>render</th><th>JS</th></tr></thead>
     <tbody>${rows}
     </tbody>
   </table>

package/lib/core/resolver.d.ts

@@ -1,5 +1,4 @@
 export type RenderMode = "static" | "island";
-export type BackendKind = "memory" | "sqlite" | "postgres";
 export interface CellDecl {
     id: string;
     route: string;
@@ -7,11 +6,6 @@ export interface CellDecl {
 }
 export interface ResolutionProfile {
     name: string;
-    backend: BackendKind;
-    cellBackends?: Record<string, BackendKind>;
-}
-export interface BackendResolution {
-    language: BackendKind;
 }
 export interface CellResolution {
     id: string;
@@ -20,12 +14,10 @@ export interface CellResolution {
         mode: RenderMode;
         shipClientJs: boolean;
     };
-    backend: BackendResolution;
 }
 export interface ResolutionManifest {
     version: 1;
     profile: string;
-    backend: BackendResolution;
     cells: Record<string, CellResolution>;
 }
 export declare function resolve(cells: CellDecl[], profile: ResolutionProfile): ResolutionManifest;

package/lib/core/resolver.js

@@ -1,20 +1,4 @@
-const ALLOWED = ["memory", "sqlite", "postgres"];
-// Giải một BackendKind → BackendResolution. Mọi driver TS đều in-process (0 roundtrip).
-// Dùng chung cho default app-level lẫn override per-cell.
-function resolveBackend(kind, profile) {
-    if (!ALLOWED.includes(kind)) {
-        throw new Error(`profile "${profile.name}": backend không hợp lệ: ${kind}`);
-    }
-    return { language: kind };
-}
 export function resolve(cells, profile) {
-    const ids = new Set(cells.map((c) => c.id));
-    for (const id of Object.keys(profile.cellBackends ?? {})) {
-        if (!ids.has(id)) {
-            throw new Error(`profile "${profile.name}": cellBackends trỏ cell không tồn tại: ${id}`);
-        }
-    }
-    const backend = resolveBackend(profile.backend, profile); // default app-level
     const out = {};
     const seenRoutes = new Set();
     for (const c of cells) {
@@ -23,14 +7,12 @@ export function resolve(cells, profile) {
         if (seenRoutes.has(c.route))
             throw new Error(`route trùng: ${c.route}`);
         seenRoutes.add(c.route);
-        const kind = profile.cellBackends?.[c.id] ?? profile.backend;
         const mode = c.hydration ?? "island"; // default island
         out[c.id] = {
             id: c.id,
             route: c.route,
             render: { mode, shipClientJs: mode === "island" },
-            backend: resolveBackend(kind, profile),
         };
     }
-    return { version: 1, profile: profile.name, backend, cells: out };
+    return { version: 1, profile: profile.name, cells: out };
 }

package/lib/index.d.ts

@@ -2,7 +2,6 @@ export * from "./core/engine.ts";
 export * from "./core/validate.ts";
 export * from "./core/errors.ts";
 export * from "./core/resolver.ts";
-export * from "./core/wiring.ts";
 export * from "./core/auth.ts";
 export * from "./core/env.ts";
 export * from "./core/config.ts";
@@ -15,13 +14,8 @@ export * from "./core/ratelimit.ts";
 export * from "./core/codegen.ts";
 export * from "./core/layouts.ts";
 export * from "./core/router.ts";
-export * from "./core/testing.ts";
-export * from "./backends/types.ts";
 export * from "./storage/types.ts";
 export { createMemoryStorage } from "./storage/memory.ts";
 export { createLocalStorage } from "./storage/local.ts";
 export { createS3Storage } from "./storage/s3.ts";
-export { createMemoryBackend } from "./backends/memory.ts";
-export { createSqliteBackend } from "./backends/sqlite.ts";
-export { createPostgresBackend } from "./backends/postgres.ts";
-export { makeServer } from "./server_factory.ts";
+export { makeServer, createHandler, type NodeHandler, type MakeServerOpts } from "./server_factory.ts";

package/lib/index.js

@@ -6,7 +6,6 @@ export * from "./core/engine.js"; // defineCell, Ctx, CellDef, Loader, Action, H
 export * from "./core/validate.js"; // validateInput, withInput
 export * from "./core/errors.js"; // FluxeError, ErrorPayload, toErrorPayload, renderErrorPage
 export * from "./core/resolver.js"; // resolve, ResolutionProfile/Manifest, CellDecl, RenderMode…
-export * from "./core/wiring.js"; // backendFromManifest, backendsFromManifest
 export * from "./core/auth.js"; // session HMAC, scrypt password, CSRF, RBAC
 export * from "./core/env.js"; // loadEnv
 export * from "./core/config.js"; // FluxeConfig, loadConfig (default ← ENV FLUXE_* ← override)
@@ -19,13 +18,9 @@ export * from "./core/ratelimit.js"; // token-bucket + LRU
 export * from "./core/codegen.js"; // genTS
 export * from "./core/layouts.js"; // layoutChain, LayoutMeta
 export * from "./core/router.js"; // makeRouter
-export * from "./core/testing.js"; // createTestBackend
-export * from "./backends/types.js"; // Backend, Todo
 export * from "./storage/types.js"; // Storage, PutResult, GetResult, safeKey, makeKey
 export { createMemoryStorage } from "./storage/memory.js";
 export { createLocalStorage } from "./storage/local.js";
 export { createS3Storage } from "./storage/s3.js"; // adapter tham chiếu (cần @aws-sdk/client-s3)
-export { createMemoryBackend } from "./backends/memory.js";
-export { createSqliteBackend } from "./backends/sqlite.js";
-export { createPostgresBackend } from "./backends/postgres.js"; // user tự inject client `pg`
-export { makeServer } from "./server_factory.js";
+export { makeServer, createHandler } from "./server_factory.js";
+// Backend = USER-OWNED (app/backend.ts) — engine KHÔNG ship driver/domain data nào.

package/lib/server_factory.d.ts

@@ -11,10 +11,13 @@ type LayoutMap = Record<string, LayoutEntry>;
 import { type I18n } from "./core/i18n.ts";
 import { type Storage } from "./storage/types.ts";
 import { type FluxeConfig } from "./core/config.ts";
-export declare function makeServer(manifest: ResolutionManifest, cells: CellDef<any, any>[], layouts?: LayoutMap, opts?: {
+export interface MakeServerOpts {
     i18n?: I18n;
     storage?: Storage;
     config?: FluxeConfig;
     backend?: unknown;
-}): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
+}
+export type NodeHandler = (req: http.IncomingMessage, res: http.ServerResponse) => Promise<unknown>;
+export declare function createHandler(manifest: ResolutionManifest, cells: CellDef<any, any>[], layouts?: LayoutMap, opts?: MakeServerOpts): NodeHandler;
+export declare function makeServer(manifest: ResolutionManifest, cells: CellDef<any, any>[], layouts?: LayoutMap, opts?: MakeServerOpts): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
 export {};

package/lib/server_factory.js

@@ -5,7 +5,6 @@ import { readFileSync, existsSync } from "node:fs";
 import { PassThrough } from "node:stream";
 import { createElement as h } from "react";
 import { renderToPipeableStream } from "react-dom/server";
-import { backendsFromManifest } from "./core/wiring.js";
 import { renderResolutionPanel } from "./core/panel.js";
 import { makeRouter } from "./core/router.js";
 import { layoutChain } from "./core/layouts.js";
@@ -75,7 +74,9 @@ function renderBodyToString(node) {
         });
     });
 }
-export function makeServer(manifest, cells, layouts = {}, opts = {}) {
+/* createHandler — lõi request framework-agnostic: trả về handler Node (req,res).
+ * Dùng trực tiếp cho adapter Express/Hono/Nest; makeServer chỉ bọc bằng http.createServer. */
+export function createHandler(manifest, cells, layouts = {}, opts = {}) {
     const i18n = opts.i18n;
     const storage = opts.storage;
     const config = opts.config ?? loadConfig(); // default ← ENV (FLUXE_*) ← override
@@ -99,10 +100,8 @@ export function makeServer(manifest, cells, layouts = {}, opts = {}) {
     const matchRoute = makeRouter(cells);
     const byId = new Map(cells.map((c) => [c.id, c]));
     // Backend USER-OWNED (app/backend.ts) inject qua opts.backend → dùng cho mọi cell.
-    // Nếu app không truyền → fallback driver built-in giải từ manifest (memory/sqlite) cho quick-start.
-    const userBackend = opts.backend;
-    const backends = userBackend === undefined ? backendsFromManifest(manifest) : null;
-    const backendFor = (id) => userBackend ?? backends.byCell.get(id) ?? backends.default;
+    // Engine KHÔNG ship/giải backend; cell nào dùng backend mà app quên truyền → undefined (lỗi rõ ràng).
+    const backendFor = (_id) => opts.backend;
     // Resolved Container: service realtime đăng ký LƯỜI — chỉ tạo khi thật sự dùng (SSE/action).
     // App không realtime → broker/presence KHÔNG bao giờ bootstrap. resolved() ở /_fluxe/stats.
     const container = createContainer();
@@ -112,7 +111,7 @@ export function makeServer(manifest, cells, layouts = {}, opts = {}) {
     const recorder = createRecorder(); // request log — chạy mỗi request → eager (luôn dùng)
     const renderCache = createRenderCache({ maxKeys: config.renderCache.maxKeys }); // FLUXE_RENDERCACHE_MAX_KEYS
     let clientJs; // ý A: đọc dist/client.js 1 lần (zero-copy: tái dùng buffer)
-    return http.createServer(async (req, res) => {
+    return async (req, res) => {
         const url = new URL(req.url, "http://localhost");
         const start = Date.now();
         res.on("finish", () => recorder.record({ method: req.method ?? "?", path: url.pathname, status: res.statusCode, ms: Date.now() - start, ts: start }));
@@ -272,10 +271,10 @@ export function makeServer(manifest, cells, layouts = {}, opts = {}) {
                     return res.end("no action");
                 }
                 const t0 = Date.now();
-                // DevTools (DEV): #3 resolution (backend TS in-process do manifest giải).
+                // DevTools (DEV): #3 resolution (render mode của cell; data = backend user-owned).
                 const backend = backendFor(cellId);
-                const r = manifest.cells[cellId]?.backend;
-                const resolution = r ? `${r.language}/in-process` : "memory/in-process";
+                const render = manifest.cells[cellId]?.render;
+                const resolution = render ? `${render.mode}/${backend?.name ?? "no-backend"}` : "island";
                 // #1 Chaos (DEV): inject delay + lỗi giả lập để test UX.
                 if (DEV && req.headers["x-fluxe-chaos"]) {
                     const c = parseChaos(String(req.headers["x-fluxe-chaos"]));
@@ -354,5 +353,9 @@ export function makeServer(manifest, cells, layouts = {}, opts = {}) {
             // Action (rpc) luôn nhận lỗi dạng JSON.
             sendError(res, wantsJson || url.pathname.startsWith("/__action/"), err);
         }
-    });
+    };
+}
+/* makeServer — đường zero-config: bọc createHandler bằng http.createServer (giữ API cũ). */
+export function makeServer(manifest, cells, layouts = {}, opts = {}) {
+    return http.createServer(createHandler(manifest, cells, layouts, opts));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nmvuong92/fluxe",
-  "version": "0.7.0",
+  "version": "0.9.1",
   "description": "fluxe — khung fullstack tối giản, một runtime TS (RCA: Resolved Cell Architecture).",
   "license": "Apache-2.0",
   "author": "nmvuong92",
@@ -30,9 +30,17 @@
       "types": "./lib/core/jobs.d.ts",
       "default": "./lib/core/jobs.js"
     },
-    "./sqlite": {
-      "types": "./lib/backends/sqlite.d.ts",
-      "default": "./lib/backends/sqlite.js"
+    "./express": {
+      "types": "./lib/adapters/express.d.ts",
+      "default": "./lib/adapters/express.js"
+    },
+    "./hono": {
+      "types": "./lib/adapters/hono.d.ts",
+      "default": "./lib/adapters/hono.js"
+    },
+    "./nest": {
+      "types": "./lib/adapters/nest.d.ts",
+      "default": "./lib/adapters/nest.js"
     }
   },
   "files": [
@@ -48,8 +56,8 @@
     "typecheck": "tsc --noEmit",
     "sync": "tsx scripts/sync.ts",
     "build:client": "npm run sync && esbuild src/client.tsx --bundle --format=esm --outfile=dist/client.js --jsx=automatic --loader:.tsx=tsx",
-    "dev": "npm run build:client && tsx src/server.tsx",
-    "dev:remote": "npm run build:client && FLUXE_BACKEND=remote tsx src/server.tsx",
+    "dev": "npm run build:client && tsx app/server.ts",
+    "dev:node": "npm run build:client && tsx src/server.tsx",
     "test": "tsx src/selftest2.ts",
     "test:unit": "node --experimental-sqlite --import tsx --test '{src,app}/**/*.test.ts'",
     "test:cells": "node --experimental-sqlite --import tsx --test 'app/cells/**/*.test.ts'",
@@ -67,16 +75,47 @@
   },
   "peerDependencies": {
     "react": "^18 || ^19",
-    "react-dom": "^18 || ^19"
+    "react-dom": "^18 || ^19",
+    "express": "^4 || ^5",
+    "hono": "^4",
+    "@hono/node-server": "^1 || ^2",
+    "@nestjs/common": "^10 || ^11",
+    "@nestjs/core": "^10 || ^11"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    },
+    "hono": {
+      "optional": true
+    },
+    "@hono/node-server": {
+      "optional": true
+    },
+    "@nestjs/common": {
+      "optional": true
+    },
+    "@nestjs/core": {
+      "optional": true
+    }
   },
   "devDependencies": {
-    "typescript": "^5",
-    "tsx": "^4",
+    "@hono/node-server": "^2.0.6",
+    "@nestjs/common": "^11.1.27",
+    "@nestjs/core": "^11.1.27",
+    "@nestjs/platform-express": "^11.1.27",
+    "@types/express": "^5.0.6",
+    "@types/node": "^20",
+    "@types/react": "^18",
+    "@types/react-dom": "^18",
     "esbuild": "^0.23",
+    "express": "^5.2.1",
+    "hono": "^4.12.27",
     "react": "^18",
     "react-dom": "^18",
-    "@types/node": "^20",
-    "@types/react": "^18",
-    "@types/react-dom": "^18"
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.2",
+    "tsx": "^4",
+    "typescript": "^5"
   }
 }

package/lib/backends/memory.d.ts

@@ -1,2 +0,0 @@
-import type { Backend } from "./types";
-export declare function createMemoryBackend(): Backend;

package/lib/backends/memory.js

@@ -1,21 +0,0 @@
-/* Backend #1: in-memory. Đại diện cho "TS thuần". */
-export function createMemoryBackend() {
-    let todos = [
-        { id: "1", title: "Học kiến trúc fullstack", done: true },
-        { id: "2", title: "Dựng PoC switch backend", done: false },
-    ];
-    let seq = 3;
-    return {
-        name: "memory",
-        async listTodos() { return todos; },
-        async addTodo(title) {
-            const t = { id: String(seq++), title, done: false };
-            todos = [...todos, t];
-            return t;
-        },
-        async toggleTodo(id) {
-            todos = todos.map((t) => (t.id === id ? { ...t, done: !t.done } : t));
-            return todos;
-        },
-    };
-}

package/lib/backends/postgres.d.ts

@@ -1,7 +0,0 @@
-import type { Backend } from "./types";
-export interface PgClientLike {
-    query(sql: string, params?: unknown[]): Promise<{
-        rows: any[];
-    }>;
-}
-export declare function createPostgresBackend(client: PgClientLike): Backend;

package/lib/backends/postgres.js

@@ -1,28 +0,0 @@
-// Nhận sẵn client (đã connect) để testable + không buộc import pg ở repo này.
-export function createPostgresBackend(client) {
-    const toTodo = (r) => ({ id: String(r.id), title: r.title, done: !!r.done });
-    return {
-        name: "postgres",
-        async listTodos() {
-            const { rows } = await client.query("SELECT * FROM todos ORDER BY id");
-            return rows.map(toTodo);
-        },
-        async addTodo(title) {
-            const { rows } = await client.query("INSERT INTO todos (title, done) VALUES ($1, false) RETURNING *", [title]);
-            return toTodo(rows[0]);
-        },
-        async toggleTodo(id) {
-            await client.query("UPDATE todos SET done = NOT done WHERE id = $1", [id]);
-            const { rows } = await client.query("SELECT * FROM todos ORDER BY id");
-            return rows.map(toTodo);
-        },
-    };
-}
-/* Cách dùng thật (khi có pg + server):
- *   import { Client } from "pg";
- *   const client = new Client(process.env.DATABASE_URL);
- *   await client.connect();
- *   await client.query(`CREATE TABLE IF NOT EXISTS todos (
- *     id SERIAL PRIMARY KEY, title TEXT NOT NULL, done BOOLEAN NOT NULL DEFAULT false)`);
- *   const backend = createPostgresBackend(client);
- */

package/lib/backends/sqlite.d.ts

@@ -1,2 +0,0 @@
-import type { Backend } from "./types";
-export declare function createSqliteBackend(path?: string): Backend;

package/lib/backends/sqlite.js

@@ -1,29 +0,0 @@
-// Copyright (c) 2026 nmvuong92
-// SPDX-License-Identifier: Apache-2.0
-import { DatabaseSync } from "node:sqlite";
-/* Backend DB THẬT — SQLite qua node:sqlite (built-in, 0 dep, persist ra file).
- * Chạy cần cờ: node --experimental-sqlite … Cùng interface Backend → switch như mọi backend. */
-export function createSqliteBackend(path = ":memory:") {
-    const db = new DatabaseSync(path);
-    db.exec(`CREATE TABLE IF NOT EXISTS todos (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    title TEXT NOT NULL,
-    done INTEGER NOT NULL DEFAULT 0
-  )`);
-    const toTodo = (r) => ({ id: String(r.id), title: r.title, done: !!r.done });
-    const all = () => db.prepare("SELECT * FROM todos ORDER BY id").all().map(toTodo);
-    return {
-        name: "sqlite",
-        async listTodos() {
-            return all();
-        },
-        async addTodo(title) {
-            const info = db.prepare("INSERT INTO todos (title) VALUES (?)").run(title);
-            return toTodo(db.prepare("SELECT * FROM todos WHERE id = ?").get(info.lastInsertRowid));
-        },
-        async toggleTodo(id) {
-            db.prepare("UPDATE todos SET done = 1 - done WHERE id = ?").run(Number(id));
-            return all();
-        },
-    };
-}

package/lib/backends/types.d.ts

@@ -1,11 +0,0 @@
-export interface Todo {
-    id: string;
-    title: string;
-    done: boolean;
-}
-export interface Backend {
-    name: string;
-    listTodos(): Promise<Todo[]>;
-    addTodo(title: string): Promise<Todo>;
-    toggleTodo(id: string): Promise<Todo[]>;
-}

package/lib/backends/types.js

@@ -1,9 +0,0 @@
-// Copyright (c) 2026 nmvuong92
-// SPDX-License-Identifier: Apache-2.0
-/* ============================================================
- * Backend Adapter — interface chuẩn để SWITCH backend.
- * loader/action chỉ biết tới interface này, không biết
- * dữ liệu đến từ memory, Postgres, hay một service Go từ xa.
- * Đổi backend = thay một implementation, frontend & cell không đổi.
- * ============================================================ */
-export {};

package/lib/core/testing.d.ts

@@ -1,9 +0,0 @@
-import type { Backend, Todo } from "../backends/types";
-export interface TestBackend extends Backend {
-    calls: {
-        method: string;
-        args: unknown[];
-    }[];
-    failNext(method: "listTodos" | "addTodo" | "toggleTodo", error?: Error): void;
-}
-export declare function createTestBackend(initial?: Todo[]): TestBackend;

package/lib/core/testing.js

@@ -1,38 +0,0 @@
-export function createTestBackend(initial = []) {
-    let todos = initial.map((t) => ({ ...t }));
-    let seq = initial.length + 1;
-    const calls = [];
-    const failures = {};
-    const guard = (method) => {
-        const e = failures[method];
-        if (e) {
-            failures[method] = undefined;
-            throw e;
-        }
-    };
-    return {
-        name: "test",
-        calls,
-        failNext(method, error = new Error(`test fail: ${method}`)) {
-            failures[method] = error;
-        },
-        async listTodos() {
-            calls.push({ method: "listTodos", args: [] });
-            guard("listTodos");
-            return todos.map((t) => ({ ...t }));
-        },
-        async addTodo(title) {
-            calls.push({ method: "addTodo", args: [title] });
-            guard("addTodo");
-            const t = { id: String(seq++), title, done: false };
-            todos = [...todos, t];
-            return { ...t };
-        },
-        async toggleTodo(id) {
-            calls.push({ method: "toggleTodo", args: [id] });
-            guard("toggleTodo");
-            todos = todos.map((t) => (t.id === id ? { ...t, done: !t.done } : t));
-            return todos.map((t) => ({ ...t }));
-        },
-    };
-}

package/lib/core/wiring.d.ts

@@ -1,8 +0,0 @@
-import type { Backend } from "../backends/types";
-import type { ResolutionManifest } from "./resolver.ts";
-export declare function backendFromManifest(m: ResolutionManifest): Backend;
-export interface ManifestBackends {
-    byCell: Map<string, Backend>;
-    default: Backend;
-}
-export declare function backendsFromManifest(m: ResolutionManifest): ManifestBackends;

package/lib/core/wiring.js

@@ -1,35 +0,0 @@
-import { createMemoryBackend } from "../backends/memory.js";
-import { createSqliteBackend } from "../backends/sqlite.js";
-// Driver TS in-process, engine dựng được zero-dep. (postgres cần client `pg` → user tự inject,
-// không phải kind auto-resolve.)
-function buildBackend(b) {
-    if (b.language === "memory")
-        return createMemoryBackend();
-    if (b.language === "sqlite")
-        return createSqliteBackend(process.env.FLUXE_SQLITE_PATH ?? ":memory:");
-    throw new Error(`manifest backend "${b.language}" không dựng được tự động (chỉ memory | sqlite)`);
-}
-// Backend app-level (default) — giữ cho code cũ/đơn giản.
-export function backendFromManifest(m) {
-    return buildBackend(m.backend);
-}
-// Dựng backend per-cell, DEDUP theo `language` → cells cùng resolution
-// chia sẻ MỘT instance (vd memory dùng chung một store).
-export function backendsFromManifest(m) {
-    const cache = new Map();
-    const make = (b) => {
-        const key = b.language;
-        let inst = cache.get(key);
-        if (!inst) {
-            inst = buildBackend(b);
-            cache.set(key, inst);
-        }
-        return inst;
-    };
-    const def = make(m.backend);
-    const byCell = new Map();
-    for (const id of Object.keys(m.cells)) {
-        byCell.set(id, make(m.cells[id].backend));
-    }
-    return { byCell, default: def };
-}