@nmvuong92/fluxe 0.1.1 → 0.3.0

package/lib/core/client.d.ts

@@ -16,6 +16,15 @@ export interface RpcMeta {
 }
 export declare const lastRpcMeta: () => RpcMeta;
 export declare function rpc<T = any>(cell: string, action: string, input: unknown): Promise<T>;
+export declare function upload(field: string, files: File | File[]): Promise<{
+    key: string;
+    url: string;
+    size: number;
+} | Array<{
+    key: string;
+    url: string;
+    size: number;
+}>>;
 export declare function mutate<T>(opts: {
     optimistic?: () => void;
     run: () => Promise<T>;

package/lib/core/client.js

@@ -70,6 +70,20 @@ export async function rpc(cell, action, input) {
         throw parseRpcError(res.status, await res.text());
     return res.json();
 }
+/* Upload file qua POST /__upload/<field> (multipart). Trả { key, url, size } (hoặc mảng nếu nhiều). */
+export async function upload(field, files) {
+    const fd = new FormData();
+    for (const f of Array.isArray(files) ? files : [files])
+        fd.append(field, f);
+    const res = await fetch(`/__upload/${field}`, {
+        method: "POST",
+        headers: { "x-csrf-token": cookie("csrf") }, // KHÔNG set content-type — browser tự thêm boundary
+        body: fd,
+    });
+    if (!res.ok)
+        throw parseRpcError(res.status, await res.text());
+    return res.json();
+}
 // Optimistic update: chạy optimistic() ngay, run() ngầm; lỗi → rollback() + ném lại.
 export async function mutate(opts) {
     opts.optimistic?.();

package/lib/core/engine.d.ts

@@ -2,10 +2,13 @@ import type { ComponentType } from "react";
 import type { Backend } from "../backends/types";
 import type { HeadMeta } from "./seo";
 import type { Session } from "./auth";
+import type { TFn } from "./i18n";
 export interface Ctx<I> {
     input: I;
     backend: Backend;
     session?: Session | null;
+    locale?: string;
+    t?: TFn;
 }
 export type Loader<I, O> = (ctx: Ctx<I>) => Promise<O>;
 export type Action<I, O> = (ctx: Ctx<I>) => Promise<O>;

package/lib/core/i18n.d.ts

@@ -0,0 +1,17 @@
+export type Messages = Record<string, string>;
+export type TFn = (key: string, vars?: Record<string, string | number>) => string;
+export interface I18n {
+    locales: string[];
+    defaultLocale: string;
+    catalogs: Record<string, Messages>;
+}
+export declare function createI18n(opts: {
+    defaultLocale: string;
+    catalogs: Record<string, Messages>;
+}): I18n;
+export declare function translate(i18n: I18n, locale: string, key: string, vars?: Record<string, string | number>): string;
+export declare function makeT(i18n: I18n, locale: string): TFn;
+export declare function resolveLocale(i18n: I18n, opts: {
+    cookie?: string;
+    acceptLanguage?: string;
+}): string;

package/lib/core/i18n.js

@@ -0,0 +1,40 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
+/* i18n — THUẦN, testable. Catalog message theo locale + t(key, vars) interpolate {var}.
+ * resolveLocale: chọn locale từ cookie / Accept-Language, giới hạn trong locale có thật. */
+export function createI18n(opts) {
+    const locales = Object.keys(opts.catalogs);
+    if (!locales.includes(opts.defaultLocale)) {
+        throw new Error(`i18n: defaultLocale '${opts.defaultLocale}' không có trong catalogs`);
+    }
+    return { locales, defaultLocale: opts.defaultLocale, catalogs: opts.catalogs };
+}
+/* Tra key trong catalog locale → fallback defaultLocale → fallback chính key. Interpolate {var}. */
+export function translate(i18n, locale, key, vars) {
+    const msg = i18n.catalogs[locale]?.[key] ?? i18n.catalogs[i18n.defaultLocale]?.[key] ?? key;
+    if (!vars)
+        return msg;
+    return msg.replace(/\{(\w+)\}/g, (_, k) => (k in vars ? String(vars[k]) : `{${k}}`));
+}
+/* t() đã bind locale — dùng trong loader/view. */
+export function makeT(i18n, locale) {
+    return (key, vars) => translate(i18n, locale, key, vars);
+}
+/* Chọn locale: cookie hợp lệ > Accept-Language (khớp tag hoặc base) > defaultLocale. */
+export function resolveLocale(i18n, opts) {
+    if (opts.cookie && i18n.locales.includes(opts.cookie))
+        return opts.cookie;
+    if (opts.acceptLanguage) {
+        for (const part of opts.acceptLanguage.split(",")) {
+            const tag = part.split(";")[0].trim(); // "en-US"
+            if (!tag)
+                continue;
+            if (i18n.locales.includes(tag))
+                return tag;
+            const base = tag.split("-")[0]; // "en"
+            if (i18n.locales.includes(base))
+                return base;
+        }
+    }
+    return i18n.defaultLocale;
+}

package/lib/core/multipart.d.ts

@@ -0,0 +1,8 @@
+export interface Part {
+    name: string;
+    filename?: string;
+    contentType?: string;
+    data: Buffer;
+}
+export declare function boundaryFromContentType(contentType: string | undefined): string | null;
+export declare function parseMultipart(body: Buffer, boundary: string): Part[];

package/lib/core/multipart.js

@@ -0,0 +1,49 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
+/* Parser multipart/form-data — THUẦN, chỉ Buffer (không lib). Tách body theo boundary thành
+ * các part { name, filename?, contentType?, data }. Dùng cho upload. */
+const CRLFCRLF = Buffer.from("\r\n\r\n");
+/* boundary lấy từ header Content-Type: multipart/form-data; boundary=XXXX */
+export function boundaryFromContentType(contentType) {
+    if (!contentType)
+        return null;
+    const m = /boundary=(?:"([^"]+)"|([^;]+))/i.exec(contentType);
+    return m ? (m[1] ?? m[2]).trim() : null;
+}
+export function parseMultipart(body, boundary) {
+    const parts = [];
+    const delim = Buffer.from(`--${boundary}`);
+    const positions = [];
+    let idx = body.indexOf(delim, 0);
+    while (idx !== -1) {
+        positions.push(idx);
+        idx = body.indexOf(delim, idx + delim.length);
+    }
+    for (let i = 0; i < positions.length - 1; i++) {
+        let start = positions[i] + delim.length;
+        if (body[start] === 0x2d && body[start + 1] === 0x2d)
+            continue; // "--" → delim đóng, bỏ
+        if (body[start] === 0x0d && body[start + 1] === 0x0a)
+            start += 2; // bỏ \r\n sau delim
+        let end = positions[i + 1];
+        if (body[end - 2] === 0x0d && body[end - 1] === 0x0a)
+            end -= 2; // bỏ \r\n trước delim kế
+        const seg = body.subarray(start, end);
+        const sep = seg.indexOf(CRLFCRLF);
+        if (sep === -1)
+            continue;
+        const headerStr = seg.subarray(0, sep).toString("utf8");
+        const data = seg.subarray(sep + CRLFCRLF.length);
+        const cd = /content-disposition:[^\r\n]*?name="([^"]*)"(?:[^\r\n]*?filename="([^"]*)")?/i.exec(headerStr);
+        if (!cd)
+            continue;
+        const ct = /content-type:\s*([^\r\n]+)/i.exec(headerStr);
+        parts.push({
+            name: cd[1],
+            filename: cd[2] || undefined,
+            contentType: ct?.[1]?.trim(),
+            data,
+        });
+    }
+    return parts;
+}

package/lib/index.d.ts

@@ -5,6 +5,7 @@ export * from "./core/resolver.ts";
 export * from "./core/wiring.ts";
 export * from "./core/auth.ts";
 export * from "./core/env.ts";
+export * from "./core/i18n.ts";
 export * from "./core/seo.ts";
 export * from "./core/broker.ts";
 export * from "./core/presence.ts";
@@ -14,6 +15,10 @@ 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 { createHttpBackend } from "./backends/http.ts";
 export { createPostgresBackend } from "./backends/postgres.ts";

package/lib/index.js

@@ -9,6 +9,7 @@ export * from "./core/resolver.js"; // resolve, ResolutionProfile/Manifest, Cell
 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/i18n.js"; // createI18n, resolveLocale, translate, makeT, t(key, vars)
 export * from "./core/seo.js"; // renderHead, renderSitemap, renderRobots, HeadMeta
 export * from "./core/broker.js"; // pub/sub
 export * from "./core/presence.js"; // ai online theo topic
@@ -18,6 +19,10 @@ 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 { createHttpBackend } from "./backends/http.js";
 export { createPostgresBackend } from "./backends/postgres.js";

package/lib/react/LocaleSwitch.d.ts

@@ -0,0 +1,6 @@
+export declare function LocaleSwitch({ locales, current, labels, className, }: {
+    locales: string[];
+    current?: string;
+    labels?: Record<string, string>;
+    className?: string;
+}): import("react").JSX.Element;

package/lib/react/LocaleSwitch.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
+/* <LocaleSwitch> — đổi ngôn ngữ qua link ?locale=xx (server set cookie + redirect).
+ * Render HTML thuần → chạy cả trên cell static (0 JS). Active theo `current` (ctx.locale). */
+export function LocaleSwitch({ locales, current, labels, className, }) {
+    return (_jsx("span", { className: className ?? "locale-switch", children: locales.map((l) => (_jsx("a", { href: `?locale=${l}`, className: l === current ? "locale active" : "locale", "aria-current": l === current ? "true" : undefined, children: labels?.[l] ?? l.toUpperCase() }, l))) }));
+}

package/lib/react/index.d.ts

@@ -4,6 +4,7 @@ export { Link } from "./Link";
 export { Nav, type NavItem } from "./Nav";
 export { useTheme, type Theme } from "./theme";
 export { ThemeToggle } from "./ThemeToggle";
+export { LocaleSwitch } from "./LocaleSwitch";
 export { shellScript } from "./shell";
 export { DebugBar } from "./DebugBar";
 export { debug, DebugStore } from "./store";

package/lib/react/index.js

@@ -8,6 +8,7 @@ export { Link } from "./Link";
 export { Nav } from "./Nav";
 export { useTheme } from "./theme";
 export { ThemeToggle } from "./ThemeToggle";
+export { LocaleSwitch } from "./LocaleSwitch";
 export { shellScript } from "./shell";
 export { DebugBar } from "./DebugBar";
 export { debug, DebugStore } from "./store";

package/lib/react/shell.d.ts

@@ -1 +1 @@
-export declare const shellScript = "(function(){\nvar d=document.documentElement;\ntry{var t=localStorage.getItem('theme');if(t==='dark'||t==='light')d.dataset.theme=t;}catch(e){}\nfunction active(){var p=location.pathname;document.querySelectorAll('.nav-link').forEach(function(a){try{a.classList.toggle('active',new URL(a.href).pathname===p);}catch(e){}});}\nfunction wire(){var b=document.querySelector('[data-fluxe-theme-toggle]');if(b&&!b._w){b._w=1;b.addEventListener('click',function(){var n=d.dataset.theme==='dark'?'light':'dark';d.dataset.theme=n;try{localStorage.setItem('theme',n);}catch(e){}});}active();}\nif(document.readyState!=='loading')wire();else document.addEventListener('DOMContentLoaded',wire);\naddEventListener('fluxe:nav',active);addEventListener('popstate',active);\n})();";
+export declare const shellScript = "(function(){\nvar d=document.documentElement;\ntry{var t=localStorage.getItem('theme');if(t==='dark'||t==='light')d.dataset.theme=t;}catch(e){}\nfunction active(){var p=location.pathname;document.querySelectorAll('.nav-link').forEach(function(a){try{a.classList.toggle('active',new URL(a.href).pathname===p);}catch(e){}});}\nfunction wire(){var b=document.querySelector('[data-fluxe-theme-toggle]');if(b&&!b._w){b._w=1;b.addEventListener('click',function(){var n=d.dataset.theme==='dark'?'light':'dark';d.dataset.theme=n;try{localStorage.setItem('theme',n);}catch(e){}document.cookie='theme='+n+';Path=/;Max-Age=31536000;SameSite=Lax';});}active();}\nif(document.readyState!=='loading')wire();else document.addEventListener('DOMContentLoaded',wire);\naddEventListener('fluxe:nav',active);addEventListener('popstate',active);\n})();";

package/lib/react/shell.js

@@ -9,7 +9,7 @@ export const shellScript = `(function(){
 var d=document.documentElement;
 try{var t=localStorage.getItem('theme');if(t==='dark'||t==='light')d.dataset.theme=t;}catch(e){}
 function active(){var p=location.pathname;document.querySelectorAll('.nav-link').forEach(function(a){try{a.classList.toggle('active',new URL(a.href).pathname===p);}catch(e){}});}
-function wire(){var b=document.querySelector('[data-fluxe-theme-toggle]');if(b&&!b._w){b._w=1;b.addEventListener('click',function(){var n=d.dataset.theme==='dark'?'light':'dark';d.dataset.theme=n;try{localStorage.setItem('theme',n);}catch(e){}});}active();}
+function wire(){var b=document.querySelector('[data-fluxe-theme-toggle]');if(b&&!b._w){b._w=1;b.addEventListener('click',function(){var n=d.dataset.theme==='dark'?'light':'dark';d.dataset.theme=n;try{localStorage.setItem('theme',n);}catch(e){}document.cookie='theme='+n+';Path=/;Max-Age=31536000;SameSite=Lax';});}active();}
 if(document.readyState!=='loading')wire();else document.addEventListener('DOMContentLoaded',wire);
 addEventListener('fluxe:nav',active);addEventListener('popstate',active);
 })();`;

package/lib/server_factory.d.ts

@@ -8,5 +8,11 @@ type LayoutEntry = LayoutMeta & {
     }) => any;
 };
 type LayoutMap = Record<string, LayoutEntry>;
-export declare function makeServer(manifest: ResolutionManifest, cells: CellDef<any, any>[], layouts?: LayoutMap): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
+import { type I18n } from "./core/i18n.ts";
+import { type Storage } from "./storage/types.ts";
+export declare function makeServer(manifest: ResolutionManifest, cells: CellDef<any, any>[], layouts?: LayoutMap, opts?: {
+    i18n?: I18n;
+    storage?: Storage;
+    maxUpload?: number;
+}): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
 export {};

package/lib/server_factory.js

@@ -20,6 +20,9 @@ import { createPresence } from "./core/presence.js";
 import { etagOf, etagMatches } from "./core/etag.js";
 import { createRenderCache } from "./core/rendercache.js";
 import { parseChaos } from "./core/chaos.js";
+import { resolveLocale, makeT } from "./core/i18n.js";
+import { parseMultipart, boundaryFromContentType } from "./core/multipart.js";
+import { makeKey } from "./storage/types.js";
 import { createMemoryBackend } from "./backends/memory.js";
 import { createHttpBackend } from "./backends/http.js";
 // Build backend theo ngôn ngữ (cho live swap trong devtools).
@@ -36,7 +39,7 @@ function devBackend(lang) {
     const url = process.env[`${lang.toUpperCase()}_URL`] ?? DEV_BACKENDS[lang];
     return url ? createHttpBackend(lang, url) : createMemoryBackend();
 }
-import { randomUUID } from "node:crypto";
+import { randomUUID, randomBytes } from "node:crypto";
 const DEV = process.env.NODE_ENV !== "production";
 const SECRET = process.env.FLUXE_SECRET ?? "dev-secret-change-me";
 // Demo user store (password hash scrypt tạo lúc boot). App thật: lấy từ DB.
@@ -59,9 +62,10 @@ function sendError(res, wantsJson, err) {
     }
 }
 // Phần head (trước body) và tail (sau body) — body được STREAM ở giữa.
-function shellHead(cell, data) {
+function shellHead(cell, data, lang = "vi", theme = "") {
     const headHtml = renderHead(cell.head ? cell.head(data) : {});
-    return `<!doctype html><html lang="vi"><head><meta charset="utf-8">${headHtml}</head><body><div id="root">`;
+    const themeAttr = theme ? ` data-theme="${theme}"` : ""; // theme-SSR: no-flash ngay lần đầu
+    return `<!doctype html><html lang="${lang}"${themeAttr}><head><meta charset="utf-8">${headHtml}</head><body><div id="root">`;
 }
 function shellTail(cell, data, shipClientJs) {
     const island = shipClientJs
@@ -85,7 +89,25 @@ function renderBodyToString(node) {
         });
     });
 }
-export function makeServer(manifest, cells, layouts = {}) {
+export function makeServer(manifest, cells, layouts = {}, opts = {}) {
+    const i18n = opts.i18n;
+    const storage = opts.storage;
+    const MAX_UPLOAD = opts.maxUpload ?? 10 * 1024 * 1024; // 10MB mặc định
+    const readBodyBuffer = (req) => new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on("data", (c) => {
+            size += c.length;
+            if (size > MAX_UPLOAD) {
+                req.destroy();
+                reject(new FluxeError("upload", "File quá lớn", 413));
+            }
+            else
+                chunks.push(c);
+        });
+        req.on("end", () => resolve(Buffer.concat(chunks)));
+        req.on("error", reject);
+    });
     // Cells được TIÊM từ app (DI) — engine không import ngược vào app/. Thêm trang = sửa app/app.ts.
     const matchRoute = makeRouter(cells);
     const byId = new Map(cells.map((c) => [c.id, c]));
@@ -108,7 +130,20 @@ export function makeServer(manifest, cells, layouts = {}) {
         // CSRF double-submit: đảm bảo có cookie csrf (đặt nếu chưa) — client gửi lại qua header.
         let csrf = cookies.csrf;
         const csrfCookie = csrf ? "" : (csrf = newCsrfToken(), `csrf=${csrf}; Path=/; SameSite=Lax`);
+        // Resolved Shell: locale (i18n) + theme — giải từ cookie/header, đưa vào loader + <html>.
+        const locale = i18n ? resolveLocale(i18n, { cookie: cookies.locale, acceptLanguage: req.headers["accept-language"] }) : "vi";
+        const t = i18n ? makeT(i18n, locale) : (k) => k;
+        const theme = cookies.theme === "dark" || cookies.theme === "light" ? cookies.theme : "";
         try {
+            // Đổi ngôn ngữ qua ?locale=xx → set cookie + redirect (chạy cả trên cell static, 0 JS).
+            {
+                const ql = url.searchParams.get("locale");
+                if (i18n && ql && i18n.locales.includes(ql)) {
+                    url.searchParams.delete("locale");
+                    res.writeHead(303, { "set-cookie": `locale=${ql}; Path=/; SameSite=Lax`, location: url.pathname + (url.search || "") });
+                    return res.end();
+                }
+            }
             if (url.pathname === "/client.js") {
                 if (clientJs === undefined && existsSync("./dist/client.js"))
                     clientJs = readFileSync("./dist/client.js");
@@ -166,6 +201,43 @@ export function makeServer(manifest, cells, layouts = {}) {
                 });
                 return res.end(`<p>Đã đăng xuất. <a href="/">trang chủ</a></p>`);
             }
+            // File upload: POST /__upload/<field> → parse multipart → storage.put. CSRF + giới hạn size.
+            if (url.pathname.startsWith("/__upload/") && req.method === "POST") {
+                if (!storage) {
+                    res.writeHead(501);
+                    return res.end(JSON.stringify({ error: { code: "no_storage", message: "Chưa cấu hình storage", status: 501 } }));
+                }
+                if (!cookies.csrf || req.headers["x-csrf-token"] !== cookies.csrf)
+                    throw new FluxeError("csrf", "CSRF không hợp lệ", 403);
+                const boundary = boundaryFromContentType(req.headers["content-type"]);
+                if (!boundary)
+                    throw new FluxeError("upload", "Cần multipart/form-data", 400);
+                const files = parseMultipart(await readBodyBuffer(req), boundary).filter((p) => p.filename);
+                if (!files.length)
+                    throw new FluxeError("upload", "Không có file", 400);
+                const out = [];
+                for (const f of files) {
+                    const key = makeKey(f.filename, randomBytes(8).toString("hex"));
+                    out.push(await storage.put(key, f.data, { contentType: f.contentType }));
+                }
+                res.writeHead(200, { "content-type": "application/json" });
+                return res.end(JSON.stringify(out.length === 1 ? out[0] : out));
+            }
+            // Serve file: GET /__file/<key> → storage.get → stream về.
+            if (url.pathname.startsWith("/__file/") && req.method === "GET") {
+                if (!storage) {
+                    res.writeHead(404);
+                    return res.end();
+                }
+                const key = decodeURIComponent(url.pathname.slice("/__file/".length));
+                const file = await storage.get(key);
+                if (!file) {
+                    res.writeHead(404);
+                    return res.end();
+                }
+                res.writeHead(200, { "content-type": file.contentType ?? "application/octet-stream", "content-length": String(file.size) });
+                return res.end(file.data);
+            }
             if (url.pathname.startsWith("/__sse/")) {
                 // Realtime channel (SSE): giữ kết nối, đẩy event khi publish trên topic. ?id= → presence.
                 const topic = decodeURIComponent(url.pathname.slice("/__sse/".length));
@@ -243,7 +315,7 @@ export function makeServer(manifest, cells, layouts = {}) {
             if (cell.requireRole && !hasRole(session, cell.requireRole)) {
                 throw new FluxeError("forbidden", `Cần quyền '${cell.requireRole}'`, 403);
             }
-            const data = await cell.loader({ input: match.params, backend: backendFor(cell.id), session });
+            const data = await cell.loader({ input: match.params, backend: backendFor(cell.id), session, locale, t });
             if (wantsJson) {
                 const body = JSON.stringify({ cell: cell.id, data, layout: cell.layout });
                 const etag = etagOf(body); // render cache: 304 nếu props không đổi
@@ -255,8 +327,9 @@ export function makeServer(manifest, cells, layouts = {}) {
                 return res.end(body);
             }
             let node = h(cell.view, { data });
+            const shellCtx = { locale, t, theme, path: url.pathname }; // Resolved Shell ctx cho layout
             for (const id of layoutChain(cell.layout, layouts)) { // inner→outer: bọc dần
-                node = h(layouts[id].component, { children: node });
+                node = h(layouts[id].component, { children: node, ctx: shellCtx });
             }
             const shipClientJs = manifest.cells[cell.id]?.render.shipClientJs ?? false;
             const pageHeaders = { "content-type": "text/html; charset=utf-8" };
@@ -265,10 +338,10 @@ export function makeServer(manifest, cells, layouts = {}) {
             // Ý B — render cache cell static: render 1 lần → giữ Buffer → ghi lại (zero-copy).
             // Gate etag(data): data đổi ⇒ miss ⇒ render lại (không trả HTML cũ). Chỉ cell static & public.
             if (manifest.cells[cell.id]?.render.mode === "static" && cell.cache !== false && !cell.requireAuth && !cell.requireRole) {
-                const etag = etagOf(JSON.stringify(data));
+                const etag = etagOf(JSON.stringify(data) + "|" + locale + "|" + theme); // lang/theme đổi → bust cache
                 let hit = renderCache.get(url.pathname);
                 if (!hit || hit.etag !== etag) {
-                    const full = shellHead(cell, data) + await renderBodyToString(node) + shellTail(cell, data, shipClientJs);
+                    const full = shellHead(cell, data, locale, theme) + await renderBodyToString(node) + shellTail(cell, data, shipClientJs);
                     hit = { etag, buf: Buffer.from(full, "utf8") };
                     renderCache.set(url.pathname, hit);
                 }
@@ -277,7 +350,7 @@ export function makeServer(manifest, cells, layouts = {}) {
             }
             // Streaming SSR: gửi head ngay → stream body (Suspense chảy dần) → tail khi xong.
             res.writeHead(200, pageHeaders);
-            res.write(shellHead(cell, data));
+            res.write(shellHead(cell, data, locale, theme));
             const through = new PassThrough();
             through.on("data", (c) => res.write(c));
             through.on("end", () => { res.write(shellTail(cell, data, shipClientJs)); res.end(); });

package/lib/storage/local.d.ts

@@ -0,0 +1,5 @@
+import type { Storage } from "./types.ts";
+export declare function createLocalStorage(opts: {
+    dir: string;
+    baseUrl?: string;
+}): Storage;

package/lib/storage/local.js

@@ -0,0 +1,37 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
+import { mkdir, writeFile, readFile, unlink } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { safeKey } from "./types.js";
+/* Driver đĩa local — ghi dưới `dir`, serve qua baseUrl (/__file/<key>). Key được làm sạch
+ * (safeKey) nên không thoát thư mục (path traversal). */
+export function createLocalStorage(opts) {
+    const baseUrl = opts.baseUrl ?? "/__file";
+    const pathOf = (key) => join(opts.dir, safeKey(key)); // chặn ../
+    const u = (key) => `${baseUrl}/${encodeURIComponent(safeKey(key))}`;
+    return {
+        name: "local",
+        async put(key, data, _opts) {
+            const p = pathOf(key);
+            await mkdir(dirname(p), { recursive: true });
+            await writeFile(p, data);
+            return { key: safeKey(key), url: u(key), size: data.length };
+        },
+        async get(key) {
+            try {
+                const data = await readFile(pathOf(key));
+                return { data, size: data.length };
+            }
+            catch {
+                return null;
+            }
+        },
+        async delete(key) {
+            try {
+                await unlink(pathOf(key));
+            }
+            catch { /* không có thì thôi */ }
+        },
+        url: u,
+    };
+}

package/lib/storage/memory.d.ts

@@ -0,0 +1,2 @@
+import type { Storage } from "./types.ts";
+export declare function createMemoryStorage(baseUrl?: string): Storage;

package/lib/storage/memory.js

@@ -0,0 +1,19 @@
+/* Driver in-RAM (dev/test). 0 đĩa, mất khi restart. */
+export function createMemoryStorage(baseUrl = "/__file") {
+    const m = new Map();
+    const u = (key) => `${baseUrl}/${encodeURIComponent(key)}`;
+    return {
+        name: "memory",
+        async put(key, data, opts) {
+            m.set(key, { data, contentType: opts?.contentType, size: data.length });
+            return { key, url: u(key), size: data.length };
+        },
+        async get(key) {
+            return m.get(key) ?? null;
+        },
+        async delete(key) {
+            m.delete(key);
+        },
+        url: u,
+    };
+}

package/lib/storage/s3.d.ts

@@ -0,0 +1,6 @@
+import type { Storage } from "./types.ts";
+export declare function createS3Storage(opts: {
+    bucket: string;
+    region: string;
+    publicBaseUrl?: string;
+}): Storage;

package/lib/storage/s3.js

@@ -0,0 +1,28 @@
+import { safeKey } from "./types.js";
+export function createS3Storage(opts) {
+    const base = opts.publicBaseUrl ?? `https://${opts.bucket}.s3.${opts.region}.amazonaws.com`;
+    const u = (key) => `${base}/${safeKey(key)}`;
+    // Khi đã `npm i @aws-sdk/client-s3`, thay phần ném lỗi bằng lệnh thật (mẫu trong comment).
+    const notReady = () => {
+        throw new Error("createS3Storage: cài '@aws-sdk/client-s3' rồi bỏ comment phần triển khai trong src/storage/s3.ts");
+    };
+    return {
+        name: "s3",
+        async put(key, _data, _o) {
+            notReady();
+            // await client.send(new PutObjectCommand({ Bucket: opts.bucket, Key: safeKey(key), Body: _data, ContentType: _o?.contentType }));
+            return { key: safeKey(key), url: u(key), size: _data.length };
+        },
+        async get(_key) {
+            notReady();
+            // const r = await client.send(new GetObjectCommand({ Bucket: opts.bucket, Key: safeKey(_key) }));
+            // return { data: Buffer.from(await r.Body!.transformToByteArray()), contentType: r.ContentType, size: r.ContentLength ?? 0 };
+            return null;
+        },
+        async delete(_key) {
+            notReady();
+            // await client.send(new DeleteObjectCommand({ Bucket: opts.bucket, Key: safeKey(_key) }));
+        },
+        url: u,
+    };
+}

package/lib/storage/types.d.ts

@@ -0,0 +1,21 @@
+export interface PutResult {
+    key: string;
+    url: string;
+    size: number;
+}
+export interface GetResult {
+    data: Buffer;
+    contentType?: string;
+    size: number;
+}
+export interface Storage {
+    name: string;
+    put(key: string, data: Buffer, opts?: {
+        contentType?: string;
+    }): Promise<PutResult>;
+    get(key: string): Promise<GetResult | null>;
+    delete(key: string): Promise<void>;
+    url(key: string): string;
+}
+export declare function safeKey(name: string): string;
+export declare function makeKey(filename: string, randomHex: string): string;

package/lib/storage/types.js

@@ -0,0 +1,14 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
+/* Storage Adapter — interface chuẩn để SWITCH driver lưu file (như Backend).
+ * Cell/endpoint chỉ biết interface này; đổi local ↔ S3 ↔ … = thay implementation. */
+/* Làm sạch tên file → key an toàn (không slash, không '..', chỉ [A-Za-z0-9._-]). */
+export function safeKey(name) {
+    const base = name.split(/[\\/]/).pop() ?? name; // bỏ path
+    const clean = base.replace(/[^A-Za-z0-9._-]/g, "_").replace(/\.{2,}/g, "_");
+    return clean.slice(0, 120) || "file";
+}
+/* Sinh key duy nhất: <randomHex>-<safeName>. randomHex truyền vào để thuần (test dễ). */
+export function makeKey(filename, randomHex) {
+    return `${randomHex}-${safeKey(filename)}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nmvuong92/fluxe",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "fluxe — khung fullstack tối giản polyglot (RCA: Resolved Cell Architecture).",
   "license": "Apache-2.0",
   "author": "nmvuong92",