npm - @nmvuong92/fluxe - Versions diffs - 0.1.0 - Mend

@nmvuong92/fluxe 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (90) hide show

package/README.md +88 -0
package/lib/backends/http.d.ts +2 -0
package/lib/backends/http.js +32 -0
package/lib/backends/memory.d.ts +2 -0
package/lib/backends/memory.js +21 -0
package/lib/backends/postgres.d.ts +7 -0
package/lib/backends/postgres.js +28 -0
package/lib/backends/sqlite.d.ts +2 -0
package/lib/backends/sqlite.js +27 -0
package/lib/backends/types.d.ts +11 -0
package/lib/backends/types.js +7 -0
package/lib/core/auth.d.ts +12 -0
package/lib/core/auth.js +54 -0
package/lib/core/broker.d.ts +7 -0
package/lib/core/broker.js +27 -0
package/lib/core/chaos.d.ts +5 -0
package/lib/core/chaos.js +11 -0
package/lib/core/cli.d.ts +6 -0
package/lib/core/cli.js +54 -0
package/lib/core/client.d.ts +33 -0
package/lib/core/client.js +108 -0
package/lib/core/codegen.d.ts +7 -0
package/lib/core/codegen.js +28 -0
package/lib/core/engine.d.ts +28 -0
package/lib/core/engine.js +1 -0
package/lib/core/env.d.ts +2 -0
package/lib/core/env.js +10 -0
package/lib/core/errors.d.ts +19 -0
package/lib/core/errors.js +39 -0
package/lib/core/etag.d.ts +2 -0
package/lib/core/etag.js +11 -0
package/lib/core/jobs.d.ts +27 -0
package/lib/core/jobs.js +54 -0
package/lib/core/layouts.d.ts +5 -0
package/lib/core/layouts.js +17 -0
package/lib/core/nav.d.ts +29 -0
package/lib/core/nav.js +53 -0
package/lib/core/observe.d.ts +12 -0
package/lib/core/observe.js +24 -0
package/lib/core/panel.d.ts +3 -0
package/lib/core/panel.js +46 -0
package/lib/core/presence.d.ts +6 -0
package/lib/core/presence.js +33 -0
package/lib/core/ratelimit.d.ts +13 -0
package/lib/core/ratelimit.js +32 -0
package/lib/core/rendercache.d.ts +15 -0
package/lib/core/rendercache.js +39 -0
package/lib/core/resolver.d.ts +37 -0
package/lib/core/resolver.js +42 -0
package/lib/core/router.d.ts +6 -0
package/lib/core/router.js +41 -0
package/lib/core/seo.d.ts +10 -0
package/lib/core/seo.js +27 -0
package/lib/core/testing.d.ts +9 -0
package/lib/core/testing.js +38 -0
package/lib/core/validate.d.ts +4 -0
package/lib/core/validate.js +17 -0
package/lib/core/wiring.d.ts +8 -0
package/lib/core/wiring.js +33 -0
package/lib/hot/search.d.ts +9 -0
package/lib/hot/search.js +16 -0
package/lib/index.d.ts +20 -0
package/lib/index.js +22 -0
package/lib/react/DebugBar.d.ts +3 -0
package/lib/react/DebugBar.js +57 -0
package/lib/react/Link.d.ts +12 -0
package/lib/react/Link.js +11 -0
package/lib/react/Nav.d.ts +8 -0
package/lib/react/Nav.js +7 -0
package/lib/react/ThemeToggle.d.ts +1 -0
package/lib/react/ThemeToggle.js +6 -0
package/lib/react/index.d.ts +10 -0
package/lib/react/index.js +11 -0
package/lib/react/mutation.d.ts +5 -0
package/lib/react/mutation.js +30 -0
package/lib/react/nav-client.d.ts +10 -0
package/lib/react/nav-client.js +76 -0
package/lib/react/query.d.ts +9 -0
package/lib/react/query.js +62 -0
package/lib/react/repro.d.ts +4 -0
package/lib/react/repro.js +19 -0
package/lib/react/shell.d.ts +1 -0
package/lib/react/shell.js +13 -0
package/lib/react/store.d.ts +28 -0
package/lib/react/store.js +31 -0
package/lib/react/theme.d.ts +6 -0
package/lib/react/theme.js +29 -0
package/lib/server_factory.d.ts +12 -0
package/lib/server_factory.js +293 -0
package/package.json +33 -0

package/lib/core/seo.js ADDED Viewed

@@ -0,0 +1,27 @@
+/* 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) {
+    return String(s)
+        .replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+export function renderHead(meta) {
+    const tags = [`<title>${esc(meta.title ?? "fluxe")}</title>`];
+    if (meta.description)
+        tags.push(`<meta name="description" content="${esc(meta.description)}">`);
+    if (meta.canonical)
+        tags.push(`<link rel="canonical" href="${esc(meta.canonical)}">`);
+    for (const [k, v] of Object.entries(meta.og ?? {})) {
+        tags.push(`<meta property="og:${esc(k)}" content="${esc(v)}">`);
+    }
+    if (meta.jsonLd)
+        tags.push(`<script type="application/ld+json">${JSON.stringify(meta.jsonLd)}</script>`);
+    return tags.join("");
+}
+// Chỉ route tĩnh (bỏ [param] và route nội bộ) — caller lọc trước hoặc truyền sẵn.
+export function renderSitemap(routes, baseUrl) {
+    const urls = routes.map((r) => `  <url><loc>${esc(baseUrl + r)}</loc></url>`).join("\n");
+    return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls}\n</urlset>\n`;
+}
+export function renderRobots(baseUrl) {
+    return `User-agent: *\nAllow: /\nSitemap: ${baseUrl}/sitemap.xml\n`;
+}

package/lib/core/testing.d.ts ADDED Viewed

@@ -0,0 +1,9 @@
+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 ADDED Viewed

@@ -0,0 +1,38 @@
+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/validate.d.ts ADDED Viewed

@@ -0,0 +1,4 @@
+import type { ZodType } from "zod";
+import type { Action } from "./engine";
+export declare function validateInput<T>(schema: ZodType<T>, raw: unknown): T;
+export declare function withInput<I, O>(schema: ZodType<I>, handler: Action<I, O>): Action<I, O>;

package/lib/core/validate.js ADDED Viewed

@@ -0,0 +1,17 @@
+import { FluxeError } from "./errors.js";
+/* Input validation từ schema (Zod). Sai → FluxeError 400 code=validation + details
+ * field-level (gắn error handling T5). Dùng cho action input (body không tin được). */
+export function validateInput(schema, raw) {
+    const r = schema.safeParse(raw);
+    if (!r.success) {
+        const details = r.error.issues.map((i) => ({ path: i.path.join(".") || "(root)", message: i.message }));
+        throw new FluxeError("validation", "Dữ liệu không hợp lệ", 400, details);
+    }
+    return r.data;
+}
+/* Bọc một action với schema input → runtime tự validate trước khi gọi handler. */
+export function withInput(schema, handler) {
+    const fn = ((ctx) => handler(ctx));
+    fn.inputSchema = schema;
+    return fn;
+}

package/lib/core/wiring.d.ts ADDED Viewed

@@ -0,0 +1,8 @@
+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 ADDED Viewed

@@ -0,0 +1,33 @@
+import { createMemoryBackend } from "../backends/memory.js";
+import { createHttpBackend } from "../backends/http.js";
+function buildBackend(b) {
+    if (b.language === "memory")
+        return createMemoryBackend();
+    if (!b.endpoint)
+        throw new Error(`manifest backend "${b.language}" thiếu endpoint`);
+    return createHttpBackend(b.language, b.endpoint);
+}
+// 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 key `language:endpoint` → 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}:${b.endpoint ?? ""}`;
+        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 };
+}

package/lib/hot/search.d.ts ADDED Viewed

@@ -0,0 +1,9 @@
+export interface SearchHit {
+    item: string;
+    score: number;
+}
+export interface SearchService {
+    name: string;
+    search(items: string[], query: string): Promise<SearchHit[]>;
+}
+export declare function createRustSearch(baseUrl: string): SearchService;

package/lib/hot/search.js ADDED Viewed

@@ -0,0 +1,16 @@
+export function createRustSearch(baseUrl) {
+    const base = baseUrl.replace(/\/$/, "");
+    return {
+        name: "rust-hot",
+        async search(items, query) {
+            const r = await fetch(`${base}/search?q=${encodeURIComponent(query)}`, {
+                method: "POST",
+                headers: { "content-type": "text/plain" },
+                body: items.join("\n"),
+            });
+            if (!r.ok)
+                throw new Error(`hot search → HTTP ${r.status}`);
+            return (await r.json());
+        },
+    };
+}

package/lib/index.d.ts ADDED Viewed

@@ -0,0 +1,20 @@
+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/seo.ts";
+export * from "./core/broker.ts";
+export * from "./core/presence.ts";
+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 { createMemoryBackend } from "./backends/memory.ts";
+export { createHttpBackend } from "./backends/http.ts";
+export { createPostgresBackend } from "./backends/postgres.ts";
+export { makeServer } from "./server_factory.ts";

package/lib/index.js ADDED Viewed

@@ -0,0 +1,22 @@
+/* @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
+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/seo.js"; // renderHead, renderSitemap, renderRobots, HeadMeta
+export * from "./core/broker.js"; // pub/sub
+export * from "./core/presence.js"; // ai online theo topic
+export * from "./core/ratelimit.js"; // token-bucket + LRU
+export * from "./core/codegen.js"; // genTS/genGo/genRust
+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 { createMemoryBackend } from "./backends/memory.js";
+export { createHttpBackend } from "./backends/http.js";
+export { createPostgresBackend } from "./backends/postgres.js";
+export { makeServer } from "./server_factory.js";

package/lib/react/DebugBar.d.ts ADDED Viewed

@@ -0,0 +1,3 @@
+export declare function DebugBar(): import("react").DetailedReactHTMLElement<{
+    style: any;
+}, HTMLElement>;

package/lib/react/DebugBar.js ADDED Viewed

@@ -0,0 +1,57 @@
+import { createElement as h, useState, useSyncExternalStore } from "react";
+import { debug } from "./store";
+import { setChaos, getChaos, setDevBackend, getDevBackend } from "../core/client";
+import { reproTest } from "./repro";
+const EMPTY = [];
+const DOT = { pending: "#e3b341", ok: "#3fb950", error: "#f85149" };
+const CHAOS = "delay=600;fail=0.4";
+function useEvents() {
+    return useSyncExternalStore(debug.subscribe, debug.getSnapshot, () => EMPTY);
+}
+const ctrlBtn = (active) => ({
+    background: active ? "#1f6feb" : "#21262d", color: "#e6edf3", border: "1px solid #30363d",
+    borderRadius: 6, padding: "2px 8px", cursor: "pointer", fontSize: 11,
+});
+export function DebugBar() {
+    const events = useEvents();
+    const [open, setOpen] = useState(false);
+    const [sel, setSel] = useState(null);
+    const [, force] = useState(0); // re-render khi đổi chaos/backend
+    const [copied, setCopied] = useState(false);
+    const errs = events.filter((e) => e.status === "error").length;
+    const wrap = { position: "fixed", right: 12, bottom: 12, zIndex: 99999, font: "12px ui-monospace,monospace" };
+    if (!open) {
+        return h("div", { style: wrap }, h("button", {
+            onClick: () => setOpen(true),
+            style: { background: errs ? "#3d1417" : "#161b22", color: "#e6edf3", border: "1px solid #30363d", borderRadius: 999, padding: "6px 12px", cursor: "pointer", boxShadow: "0 4px 16px #0008" },
+        }, `⚡ fluxe · ${events.length}${errs ? ` · ${errs}✗` : ""}`));
+    }
+    const chaosOn = getChaos() !== "";
+    const be = getDevBackend();
+    // #1 Chaos toggle + #5 backend swap
+    const controls = h("div", { style: { display: "flex", gap: 6, alignItems: "center", padding: "6px 10px", background: "#0d1117", borderBottom: "1px solid #21262d", flexWrap: "wrap" } }, h("button", { onClick: () => { setChaos(chaosOn ? "" : CHAOS); force((x) => x + 1); }, style: ctrlBtn(chaosOn), title: CHAOS }, chaosOn ? "🔥 Chaos ON" : "Chaos"), h("span", { style: { color: "#7d8590" } }, "backend:"), ...["", "memory", "go", "rust"].map((v) => h("button", { key: v || "auto", onClick: () => { setDevBackend(v); force((x) => x + 1); }, style: ctrlBtn(be === v) }, v || "auto")));
+    const rows = events.length === 0
+        ? [h("div", { key: "e", style: { color: "#7d8590", padding: 8 } }, "Tương tác đi — query/mutation sẽ hiện ở đây.")]
+        : events.map((e) => h("div", { key: e.id, onClick: () => { setSel(sel === e.id ? null : e.id); setCopied(false); },
+            style: { display: "flex", gap: 8, alignItems: "center", padding: "4px 8px", cursor: "pointer", borderBottom: "1px solid #21262d", background: sel === e.id ? "#161b22" : "transparent" } }, h("span", { style: { width: 8, height: 8, borderRadius: 8, background: DOT[e.status], flexShrink: 0 } }), h("span", { style: { color: "#7d8590", textTransform: "uppercase", fontSize: 10, width: 50 } }, e.kind), h("span", { style: { color: "#e6edf3", flex: 1 } }, e.label), e.resolution ? h("span", { style: { color: "#5fd3f0", fontSize: 10 } }, e.resolution) : null, // #3 RCA
+        h("span", { style: { color: "#7d8590", width: 44, textAlign: "right" } }, e.ms != null ? `${e.ms}ms` : "…")));
+    // #4 trace (timing bars) + repro→test (#2)
+    let detail = null;
+    if (sel != null) {
+        const e = events.find((x) => x.id === sel);
+        if (e) {
+            const scale = Math.max(1, e.ms ?? 1);
+            const bar = (label, ms, color) => ms == null ? null :
+                h("div", { style: { display: "flex", gap: 6, alignItems: "center", margin: "2px 0" } }, h("span", { style: { color: "#7d8590", width: 60 } }, label), h("div", { style: { height: 8, width: `${Math.max(4, (ms / scale) * 200)}px`, background: color, borderRadius: 3 } }), h("span", { style: { color: "#7d8590" } }, `${ms}ms`));
+            detail = h("div", { style: { padding: 8, borderTop: "1px solid #30363d" } }, e.resolution ? h("div", { style: { color: "#5fd3f0", marginBottom: 4 } }, `resolution: ${e.resolution}`) : null, bar("server", e.serverMs, "#3fb950"), bar("client", e.ms, "#1f6feb"), h("pre", { style: { margin: "6px 0 0", maxHeight: 120, overflow: "auto", color: "#a5d6ff", whiteSpace: "pre-wrap" } }, e.error ? "ERROR: " + e.error : JSON.stringify(e.data, null, 2)), e.kind === "mutation" ? h("button", {
+                onClick: () => { try {
+                    navigator.clipboard?.writeText(reproTest(e));
+                    setCopied(true);
+                }
+                catch { } },
+                style: { ...ctrlBtn(false), marginTop: 6 },
+            }, copied ? "✓ đã copy test" : "📋 Copy as test") : null);
+        }
+    }
+    return h("div", { style: wrap }, h("div", { style: { width: 380, background: "#0d1117", border: "1px solid #30363d", borderRadius: 10, overflow: "hidden", boxShadow: "0 8px 32px #000a" } }, h("div", { style: { display: "flex", justifyContent: "space-between", alignItems: "center", padding: "8px 10px", background: "#161b22", color: "#e6edf3" } }, h("b", null, "⚡ fluxe devtools"), h("button", { onClick: () => setOpen(false), style: { background: "none", border: "none", color: "#7d8590", cursor: "pointer", fontSize: 14 } }, "✕")), controls, h("div", { style: { maxHeight: 220, overflow: "auto" } }, ...rows), detail));
+}

package/lib/react/Link.d.ts ADDED Viewed

@@ -0,0 +1,12 @@
+import type { ReactNode } from "react";
+interface LinkProps {
+    href: string;
+    children?: ReactNode;
+    prefetch?: boolean;
+    preserveScroll?: boolean;
+    className?: string;
+    target?: string;
+    download?: boolean;
+}
+export declare function Link({ href, children, prefetch: pf, preserveScroll, ...rest }: LinkProps): import("react").JSX.Element;
+export {};

package/lib/react/Link.js ADDED Viewed

@@ -0,0 +1,11 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { go, prefetch, shouldIntercept } from "./nav-client";
+export function Link({ href, children, prefetch: pf = true, preserveScroll, ...rest }) {
+    return (_jsx("a", { href: href, onMouseEnter: pf ? () => prefetch(href) : undefined, onClick: (e) => {
+            const origin = typeof location !== "undefined" ? location.origin : "";
+            if (shouldIntercept(e.nativeEvent, { href, origin, target: rest.target, download: rest.download })) {
+                e.preventDefault();
+                void go(href, true, { preserveScroll });
+            }
+        }, ...rest, children: children }));
+}

package/lib/react/Nav.d.ts ADDED Viewed

@@ -0,0 +1,8 @@
+export interface NavItem {
+    label: string;
+    href: string;
+}
+export declare function Nav({ items, className }: {
+    items: NavItem[];
+    className?: string;
+}): import("react").JSX.Element;

package/lib/react/Nav.js ADDED Viewed

@@ -0,0 +1,7 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/* <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";
+export function Nav({ items, className }) {
+    return (_jsx("nav", { className: className ?? "nav", children: items.map((it) => (_jsx(Link, { href: it.href, className: "nav-link", children: it.label }, it.href))) }));
+}

package/lib/react/ThemeToggle.d.ts ADDED Viewed

	@@ -0,0 +1 @@
1	+ export declare function ThemeToggle(): import("react").JSX.Element;

package/lib/react/ThemeToggle.js ADDED Viewed

@@ -0,0 +1,6 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/* <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() {
+    return (_jsx("button", { "data-fluxe-theme-toggle": true, className: "theme-toggle", "aria-label": "\u0110\u1ED5i giao di\u1EC7n s\u00E1ng/t\u1ED1i", title: "S\u00E1ng/T\u1ED1i", children: "\u25D0" }));
+}

package/lib/react/index.d.ts ADDED Viewed

@@ -0,0 +1,10 @@
+export { useQuery } from "./query";
+export { useMutation } from "./mutation";
+export { Link } from "./Link";
+export { Nav, type NavItem } from "./Nav";
+export { useTheme, type Theme } from "./theme";
+export { ThemeToggle } from "./ThemeToggle";
+export { shellScript } from "./shell";
+export { DebugBar } from "./DebugBar";
+export { debug, DebugStore } from "./store";
+export type { DebugEvent } from "./store";

package/lib/react/index.js ADDED Viewed

@@ -0,0 +1,11 @@
+/* @fluxe/react — devtools lite: data fetching + tracing + debug bar.
+ * Dùng: useQuery / useMutation trong cell; mount <DebugBar/> 1 lần. */
+export { useQuery } from "./query";
+export { useMutation } from "./mutation";
+export { Link } from "./Link";
+export { Nav } from "./Nav";
+export { useTheme } from "./theme";
+export { ThemeToggle } from "./ThemeToggle";
+export { shellScript } from "./shell";
+export { DebugBar } from "./DebugBar";
+export { debug, DebugStore } from "./store";

package/lib/react/mutation.d.ts ADDED Viewed

@@ -0,0 +1,5 @@
+export declare function useMutation<I, O>(label: string, fn: (input: I) => Promise<O>): {
+    mutate: (input: I) => Promise<O | undefined>;
+    loading: boolean;
+    error: string;
+};

package/lib/react/mutation.js ADDED Viewed

@@ -0,0 +1,30 @@
+import { useState } from "react";
+import { debug } from "./store";
+import { lastRpcMeta } from "../core/client";
+/* useMutation — gọi action server, log tracing (resolution/timing) + lỗi có cấu trúc. */
+export function useMutation(label, fn) {
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState("");
+    async function mutate(input) {
+        setLoading(true);
+        setError("");
+        const id = debug.start("mutation", "rpc:" + label);
+        try {
+            const out = await fn(input);
+            const m = lastRpcMeta();
+            debug.finish(id, { status: "ok", data: out, input, resolution: m.resolution, serverMs: m.serverMs, ms: m.clientMs });
+            return out;
+        }
+        catch (e) {
+            const m = lastRpcMeta();
+            const msg = e?.details?.[0]?.message ?? e?.message ?? String(e);
+            setError(msg);
+            debug.finish(id, { status: "error", error: msg, input, resolution: m.resolution, serverMs: m.serverMs });
+            throw e;
+        }
+        finally {
+            setLoading(false);
+        }
+    }
+    return { mutate, loading, error };
+}

package/lib/react/nav-client.d.ts ADDED Viewed

@@ -0,0 +1,10 @@
+import { shouldIntercept } from "../core/nav";
+type Swap = (cell: string, data: unknown, layout?: string) => void;
+export declare function initNav(swap: Swap): void;
+export declare function prefetch(href: string): void;
+export interface NavOptions {
+    preserveScroll?: boolean;
+}
+export declare function go(href: string, push?: boolean, opts?: NavOptions): Promise<void>;
+export declare function navigate(href: string, opts?: NavOptions): Promise<void>;
+export { shouldIntercept };

package/lib/react/nav-client.js ADDED Viewed

@@ -0,0 +1,76 @@
+/* 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). */
+import { fetchPageProps } from "../core/client";
+import { createPrefetchCache, shouldIntercept } from "../core/nav";
+let onSwap = null;
+const cache = createPrefetchCache();
+const pathOf = (href) => {
+    try {
+        const u = new URL(href, location.origin);
+        return u.pathname + u.search;
+    }
+    catch {
+        return href;
+    }
+};
+const sameOrigin = (href) => {
+    try {
+        return new URL(href, location.origin).origin === location.origin;
+    }
+    catch {
+        return false;
+    }
+};
+export function initNav(swap) {
+    onSwap = swap;
+    if ("scrollRestoration" in history)
+        history.scrollRestoration = "manual";
+    window.addEventListener("popstate", () => { void go(location.pathname + location.search, false); });
+    window.fluxe = { navigate, prefetch }; // API điều hướng programmatic
+}
+function saveScroll() {
+    history.replaceState({ ...(history.state ?? {}), scrollY: window.scrollY }, "");
+}
+function restoreScroll(y) {
+    requestAnimationFrame(() => requestAnimationFrame(() => window.scrollTo(0, y)));
+}
+/* Prefetch (hover): nạp trước props link cùng origin vào cache → click sau cảm giác tức thì. */
+export function prefetch(href) {
+    if (!sameOrigin(href))
+        return;
+    void cache.load(pathOf(href), fetchPageProps).catch(() => { });
+}
+/* Điều hướng: cùng origin → thử SPA swap; server trả non-cell / lỗi → để browser (hard nav). */
+export async function go(href, push = true, opts = {}) {
+    if (!sameOrigin(href)) {
+        location.href = href;
+        return;
+    }
+    const path = pathOf(href);
+    let props;
+    try {
+        props = await cache.load(path, fetchPageProps);
+    }
+    catch {
+        location.href = href;
+        return;
+    }
+    if (!props || !props.cell) {
+        location.href = href;
+        return;
+    } // không phải cell (file tĩnh…) → hard nav
+    if (push) {
+        saveScroll();
+        history.pushState({ fluxe: 1, scrollY: opts.preserveScroll ? window.scrollY : 0 }, "", href);
+    }
+    onSwap?.(props.cell, props.data, props.layout);
+    window.dispatchEvent(new Event("fluxe:nav")); // cho <Nav/> cập nhật active
+    if (opts.preserveScroll)
+        return;
+    restoreScroll(push ? 0 : (history.state?.scrollY ?? 0));
+}
+export function navigate(href, opts = {}) {
+    return go(href, true, opts);
+}
+export { shouldIntercept };

package/lib/react/query.d.ts ADDED Viewed

@@ -0,0 +1,9 @@
+export declare function useQuery<T>(key: string, fetcher: () => Promise<T>, opts?: {
+    initial?: T;
+    enabled?: boolean;
+}): {
+    data: T | undefined;
+    error: string;
+    loading: boolean;
+    refetch: () => Promise<void>;
+};

package/lib/react/query.js ADDED Viewed

@@ -0,0 +1,62 @@
+import { useState, useEffect, useRef } from "react";
+import { debug } from "./store";
+import { lastRpcMeta } from "../core/client";
+/* useQuery — react-query-lite: cache theo key, dedup in-flight (chống refetch storm),
+ * loading/error/data, refetch, log tracing (resolution/timing). */
+const cache = new Map();
+const inflight = new Map();
+export function useQuery(key, fetcher, opts = {}) {
+    const [data, setData] = useState(opts.initial !== undefined ? opts.initial : cache.get(key));
+    const [error, setError] = useState("");
+    const [loading, setLoading] = useState(false);
+    const fetcherRef = useRef(fetcher);
+    fetcherRef.current = fetcher;
+    async function run() {
+        // Dedup: nếu đã có fetch đang bay cho key → dùng chung, không bắn request mới.
+        let p = inflight.get(key);
+        const fresh = !p;
+        if (!p) {
+            const id = debug.start("query", "query:" + key);
+            p = (async () => {
+                try {
+                    const d = await fetcherRef.current();
+                    const m = lastRpcMeta();
+                    cache.set(key, d);
+                    debug.finish(id, { status: "ok", data: d, resolution: m.resolution, serverMs: m.serverMs, ms: m.clientMs });
+                    return d;
+                }
+                catch (e) {
+                    const m = lastRpcMeta();
+                    debug.finish(id, { status: "error", error: e?.message ?? String(e), resolution: m.resolution });
+                    throw e;
+                }
+                finally {
+                    inflight.delete(key);
+                }
+            })();
+            inflight.set(key, p);
+        }
+        if (fresh) {
+            setLoading(true);
+            setError("");
+        }
+        try {
+            setData(await p);
+        }
+        catch (e) {
+            setError(e?.message ?? String(e));
+        }
+        finally {
+            setLoading(false);
+        }
+    }
+    useEffect(() => {
+        if (opts.enabled === false)
+            return;
+        if (opts.initial !== undefined && cache.get(key) === undefined)
+            cache.set(key, opts.initial);
+        run();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [key]);
+    return { data, error, loading, refetch: run };
+}

package/lib/react/repro.d.ts ADDED Viewed

@@ -0,0 +1,4 @@
+import type { DebugEvent } from "./store";
+export declare function reproTest(ev: DebugEvent & {
+    input?: unknown;
+}): string;

package/lib/react/repro.js ADDED Viewed

@@ -0,0 +1,19 @@
+/* Repro → Test: từ một event (label "rpc:cell.action", input, data) sinh sẵn một test
+ * dùng createTestBackend — biến bug thành test deterministic, dán vào là chạy. Thuần. */
+export function reproTest(ev) {
+    const m = ev.label.match(/^rpc:([^.]+)\.(.+)$/);
+    const cell = m?.[1] ?? "cell";
+    const action = m?.[2] ?? "action";
+    const input = JSON.stringify(ev.input ?? {});
+    const expected = JSON.stringify(ev.data ?? null);
+    return `import { test } from "node:test";
+import assert from "node:assert/strict";
+import ${cell} from "../app/cells/${cell}/index";
+import { createTestBackend } from "../src/core/testing";
+test("repro: ${cell}.${action}", async () => {
+  const backend = createTestBackend();
+  const out = await ${cell}.actions!.${action}({ input: ${input}, backend });
+  assert.deepEqual(out, ${expected});
+});`;
+}

package/lib/react/shell.d.ts ADDED Viewed

@@ -0,0 +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})();";

package/lib/react/shell.js ADDED Viewed

@@ -0,0 +1,13 @@
+/* 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).
+ *  - .nav-link active theo path; cập nhật khi SPA nav ("fluxe:nav") + back/forward.
+ * Layout nhúng <script>{shellScript}</script>. ~0.5KB, độc lập React → static cell vẫn tương tác. */
+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();}
+if(document.readyState!=='loading')wire();else document.addEventListener('DOMContentLoaded',wire);
+addEventListener('fluxe:nav',active);addEventListener('popstate',active);
+})();`;

package/lib/react/store.d.ts ADDED Viewed

@@ -0,0 +1,28 @@
+export type EventKind = "query" | "mutation" | "error";
+export type EventStatus = "pending" | "ok" | "error";
+export interface DebugEvent {
+    id: number;
+    kind: EventKind;
+    label: string;
+    status: EventStatus;
+    startedAt: number;
+    ms?: number;
+    data?: unknown;
+    error?: string;
+    input?: unknown;
+    resolution?: string;
+    serverMs?: number;
+}
+type Listener = () => void;
+export declare class DebugStore {
+    events: DebugEvent[];
+    private listeners;
+    private seq;
+    start(kind: EventKind, label: string): number;
+    finish(id: number, patch: Partial<DebugEvent>): void;
+    subscribe: (fn: Listener) => (() => void);
+    getSnapshot: () => DebugEvent[];
+    private emit;
+}
+export declare const debug: DebugStore;
+export {};