@nmvuong92/fluxe 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 nmvuong92
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,5 @@
+fluxe (@nmvuong92/fluxe)
+Copyright 2026 nmvuong92
+
+This product includes software developed by nmvuong92.
+Licensed under the Apache License, Version 2.0.

package/README.md

@@ -1,5 +1,9 @@
 # fluxe
 
+[![CI](https://github.com/nmvuong92/fluxe/actions/workflows/ci.yml/badge.svg)](https://github.com/nmvuong92/fluxe/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@nmvuong92/fluxe.svg)](https://www.npmjs.com/package/@nmvuong92/fluxe)
+[![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+
 Khung fullstack **polyglot** dựa 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 (ngôn ngữ, render, transport,
 backend, scale) là **kết quả được GIẢI** bởi engine, không viết tay.*
@@ -86,3 +90,9 @@ mỗi tầng đúng ngôn ngữ tối ưu, đúng §6d của [idea.md](idea.md).
 
 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)**.
 Spec + plan: `docs/superpowers/`.
+
+## License
+
+**Apache-2.0** © 2026 nmvuong92. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
+Copyright is held solely by the author, who reserves the right to offer the software under
+separate commercial terms.

package/lib/backends/sqlite.js

@@ -1,3 +1,5 @@
+// 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. */

package/lib/backends/types.js

@@ -1,3 +1,5 @@
+// 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

package/lib/core/auth.js

@@ -1,3 +1,5 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
 import { createHmac, timingSafeEqual, scryptSync, randomBytes } from "node:crypto";
 export function hasRole(session, role) {
     return !!session?.roles?.includes(role);

package/lib/core/broker.js

@@ -1,3 +1,5 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
 /* Broker pub/sub in-memory — nền của realtime channel (Trục 4g), bản 1-node.
  * Bản distributed: thay bằng NATS/Redis fan-out (cùng interface). Bản stateful:
  * actor-Go (app/native/actor-go). Đây là lõi đơn giản nhất, dependency-free. */

package/lib/core/cli.js

@@ -1,3 +1,5 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
 /* fx CLI — registry lệnh thuần (testable). bin/fx.ts dispatch + spawn. */
 const SYNC = "tsx scripts/sync.ts"; // auto-discovery: quét app/cells/* → app/app.ts
 const ESBUILD = "esbuild src/client.tsx --bundle --format=esm --outfile=dist/client.js --jsx=automatic --loader:.tsx=tsx";

package/lib/core/client.js

@@ -1,3 +1,5 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
 /* ============================================================
  * Client runtime — Inertia-style + mutations DX.
  * - rpc(): gọi action, ném RpcError CÓ CẤU TRÚC (code/message/details) khi lỗi.

package/lib/core/codegen.js

@@ -1,3 +1,5 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
 /* Codegen contract polyglot — MỘT schema → types TS + Go + Rust (chữ ký RCA:
  * type-safe xuyên ngôn ngữ). Thuần (string-in/string-out), dễ test. */
 const pascal = (s) => s.charAt(0).toUpperCase() + s.slice(1);

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/errors.js

@@ -1,3 +1,5 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
 /* Error handling (tenet T5 / Trục 4q):
  * - FluxeError = domain error (giá trị có kiểu) → map status/code/message an toàn.
  * - Lỗi khác = unexpected → 500 generic + errorId; detail chỉ ở dev (không leak prod). */

package/lib/core/etag.js

@@ -1,3 +1,5 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
 import { createHash } from "node:crypto";
 /* Render cache — ETag/304: hash body, client gửi If-None-Match → 304 nếu không đổi
  * (không gửi lại body). Dùng cho JSON props (SPA nav refetch nhiều). */

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/jobs.js

@@ -1,3 +1,5 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
 import { DatabaseSync } from "node:sqlite";
 /* Worker: xử lý cạn job pending (retry → dead-letter bao bọc nên luôn kết thúc). */
 export async function drain(queue, handlers, opts) {

package/lib/core/layouts.js

@@ -1,3 +1,5 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
 /* Nested layouts — phần thuần: giải chuỗi layout từ cell lên root.
  * Trả về thứ tự INNER→OUTER để render bọc dần (outermost cuối cùng bọc ngoài). */
 export function layoutChain(layoutId, layouts) {

package/lib/core/nav.js

@@ -1,3 +1,5 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
 /* Resolved Navigation — phần THUẦN (testable, không DOM/fetch).
  * shouldIntercept: có nên chặn click để SPA-nav không. createPrefetchCache: cache props
  * theo URL + dedup in-flight (prefetch on hover → nav cảm giác tức thì). */

package/lib/core/observe.js

@@ -1,3 +1,5 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
 /* Observability — request log Ring Buffer CIRCULAR (#17).
  * Trước: push + shift (shift O(n) mỗi record khi đầy). Giờ: mảng vòng + con trỏ ghi →
  * record O(1) (không dời mảng). recent O(n) chỉ trên số phần tử yêu cầu. */

package/lib/core/presence.js

@@ -1,3 +1,5 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
 /* Presence — ai đang online per topic (Trục 4g). Refcount theo id để chịu multi-tab/
  * nhiều kết nối cùng user. Bản 1-node; distributed: chia sẻ qua NATS/Redis (gắn 4d). */
 export function createPresence() {

package/lib/core/ratelimit.js

@@ -1,3 +1,5 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
 /* Rate limiting (6b.F) — token bucket per key (vd IP/user/route). Thuần, clock injected.
  * Bucket bound bằng LRU (maxKeys) → CHỐNG RÒ RAM khi nhiều IP (kẻ tấn công nhiều nguồn).
  * Bản 1-node; distributed: chia sẻ bucket qua Redis (gắn 4d), cùng interface. */

package/lib/core/rendercache.js

@@ -1,3 +1,5 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
 /* ============================================================
  * Render cache — memoize HTML đã render của cell static, key theo route.
  *

package/lib/core/seo.js

@@ -1,3 +1,5 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
 /* SEO / head management — builder thuần (testable). Cell khai báo head(data) →
  * framework bơm vào <head>; sitemap/robots tự sinh từ route table. */
 function esc(s) {

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";

package/lib/index.js

@@ -1,3 +1,5 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
 /* @nmvuong92/fluxe — entry ENGINE (server-side, không kéo node:sqlite).
  * Subpath: /react (DX React), /client (rpc runtime), /jobs, /sqlite (cần node:sqlite). */
 export * from "./core/engine.js"; // defineCell, Ctx, CellDef, Loader, Action, Hydration
@@ -7,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

package/lib/react/DebugBar.js

@@ -1,3 +1,5 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
 import { createElement as h, useState, useSyncExternalStore } from "react";
 import { debug } from "./store";
 import { setChaos, getChaos, setDevBackend, getDevBackend } from "../core/client";

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/Nav.js

@@ -1,4 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
 /* <Nav/> — render menu khai báo (app/nav.ts) bằng <Link>. Active set bởi shellScript (vanilla)
  * theo path → chạy cả trên trang static. <Link> cho SPA nav trên trang island. */
 import { Link } from "./Link";

package/lib/react/ThemeToggle.js

@@ -1,4 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
 /* <ThemeToggle/> — nút đổi light/dark. Render HTML thuần + marker; logic do shellScript (vanilla)
  * xử lý → chạy cả trên trang static (0 React JS). Không cần hydrate. */
 export function ThemeToggle() {

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

@@ -1,3 +1,5 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
 /* @fluxe/react — devtools lite: data fetching + tracing + debug bar.
  * Dùng: useQuery / useMutation trong cell; mount <DebugBar/> 1 lần. */
 export { useQuery } from "./query";
@@ -6,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/mutation.js

@@ -1,3 +1,5 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
 import { useState } from "react";
 import { debug } from "./store";
 import { lastRpcMeta } from "../core/client";

package/lib/react/nav-client.js

@@ -1,3 +1,5 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
 /* Client nav controller — wire phần thuần (nav.ts) với DOM/history/fetch.
  * KHÔNG import cells/router (giữ client bundle sạch server code) → "internal?" = cùng origin +
  * server trả về cell hợp lệ. window/history/location chỉ đụng trong hàm (an toàn SSR import). */

package/lib/react/query.js

@@ -1,3 +1,5 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
 import { useState, useEffect, useRef } from "react";
 import { debug } from "./store";
 import { lastRpcMeta } from "../core/client";

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

@@ -1,3 +1,5 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
 /* shellScript — JS vanilla TÍ HON chạy trên MỌI trang (kể cả static 0-React-JS) để:
  *  - no-flash theme: đọc localStorage.theme → set data-theme ngay khi parse (trước content).
  *  - nút .theme-toggle: đổi light/dark + lưu localStorage (không cần React hydrate).
@@ -7,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/react/store.js

@@ -1,3 +1,5 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
 /* @fluxe/react — debug store + tracing (lite). Mọi query/mutation/error ghi vào đây;
  * DebugBar subscribe để hiển thị "full flow". Immutable update → useSyncExternalStore re-render. */
 const MAX = 50;

package/lib/react/theme.js

@@ -1,3 +1,5 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
 /* Theme — light/dark/auto qua data-theme trên <html> + localStorage. SSR-safe (window chỉ
  * đụng trong effect/handler). "auto" = theo OS (prefers-color-scheme) → static cell 0 JS vẫn
  * dark được nhờ CSS @media, không cần script. */

package/lib/server_factory.d.ts

@@ -8,5 +8,8 @@ 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";
+export declare function makeServer(manifest: ResolutionManifest, cells: CellDef<any, any>[], layouts?: LayoutMap, opts?: {
+    i18n?: I18n;
+}): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
 export {};

package/lib/server_factory.js

@@ -1,3 +1,5 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
 import http from "node:http";
 import { readFileSync, existsSync } from "node:fs";
 import { PassThrough } from "node:stream";
@@ -18,6 +20,7 @@ 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 { createMemoryBackend } from "./backends/memory.js";
 import { createHttpBackend } from "./backends/http.js";
 // Build backend theo ngôn ngữ (cho live swap trong devtools).
@@ -57,9 +60,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
@@ -83,7 +87,8 @@ function renderBodyToString(node) {
         });
     });
 }
-export function makeServer(manifest, cells, layouts = {}) {
+export function makeServer(manifest, cells, layouts = {}, opts = {}) {
+    const i18n = opts.i18n;
     // 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]));
@@ -106,7 +111,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");
@@ -241,7 +259,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
@@ -253,8 +271,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" };
@@ -263,10 +282,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);
                 }
@@ -275,7 +294,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/package.json

@@ -1,17 +1,49 @@
 {
   "name": "@nmvuong92/fluxe",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "fluxe — khung fullstack tối giản polyglot (RCA: Resolved Cell Architecture).",
+  "license": "Apache-2.0",
+  "author": "nmvuong92",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nmvuong92/fluxe.git"
+  },
+  "homepage": "https://github.com/nmvuong92/fluxe#readme",
+  "bugs": {
+    "url": "https://github.com/nmvuong92/fluxe/issues"
+  },
   "exports": {
-    ".": { "types": "./lib/index.d.ts", "default": "./lib/index.js" },
-    "./react": { "types": "./lib/react/index.d.ts", "default": "./lib/react/index.js" },
-    "./client": { "types": "./lib/core/client.d.ts", "default": "./lib/core/client.js" },
-    "./jobs": { "types": "./lib/core/jobs.d.ts", "default": "./lib/core/jobs.js" },
-    "./sqlite": { "types": "./lib/backends/sqlite.d.ts", "default": "./lib/backends/sqlite.js" }
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./react": {
+      "types": "./lib/react/index.d.ts",
+      "default": "./lib/react/index.js"
+    },
+    "./client": {
+      "types": "./lib/core/client.d.ts",
+      "default": "./lib/core/client.js"
+    },
+    "./jobs": {
+      "types": "./lib/core/jobs.d.ts",
+      "default": "./lib/core/jobs.js"
+    },
+    "./sqlite": {
+      "types": "./lib/backends/sqlite.d.ts",
+      "default": "./lib/backends/sqlite.js"
+    }
+  },
+  "files": [
+    "lib",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public"
   },
-  "files": ["lib", "README.md"],
-  "publishConfig": { "access": "public" },
   "scripts": {
     "typecheck": "tsc --noEmit",
     "sync": "tsx scripts/sync.ts",
@@ -25,9 +57,26 @@
     "resolve": "npm run sync && tsx scripts/resolve.ts",
     "fx": "tsx bin/fx.ts",
     "build": "rm -rf lib && tsc -p tsconfig.build.json",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "release": "npm run test:all && npm version patch -m 'release: v%s' && git push --follow-tags",
+    "release:minor": "npm run test:all && npm version minor -m 'release: v%s' && git push --follow-tags",
+    "release:major": "npm run test:all && npm version major -m 'release: v%s' && git push --follow-tags"
+  },
+  "dependencies": {
+    "zod": "^3"
+  },
+  "peerDependencies": {
+    "react": "^18 || ^19",
+    "react-dom": "^18 || ^19"
   },
-  "dependencies": { "zod": "^3" },
-  "peerDependencies": { "react": "^18 || ^19", "react-dom": "^18 || ^19" },
-  "devDependencies": { "typescript": "^5", "tsx": "^4", "esbuild": "^0.23", "react": "^18", "react-dom": "^18", "@types/node": "^20", "@types/react": "^18", "@types/react-dom": "^18" }
+  "devDependencies": {
+    "typescript": "^5",
+    "tsx": "^4",
+    "esbuild": "^0.23",
+    "react": "^18",
+    "react-dom": "^18",
+    "@types/node": "^20",
+    "@types/react": "^18",
+    "@types/react-dom": "^18"
+  }
 }