@bractjs/bractjs 0.1.5 → 0.1.7

package/src/__tests__/session.test.ts

@@ -3,7 +3,7 @@ import { createCookieSession } from "../server/session.ts";
 
 const sessionStorage = createCookieSession({
   name: "__test",
-  secrets: ["secret-one", "secret-two"],
+  secrets: ["secret-one-1234567890", "secret-two-1234567890"],
   secure: false,
   sameSite: "Lax",
 });
@@ -71,7 +71,7 @@ describe("createCookieSession — commitSession + roundtrip", () => {
   test("secret rotation: old secret still verifies", async () => {
     const oldStorage = createCookieSession({
       name: "__test",
-      secrets: ["secret-two"], // only the old secret
+      secrets: ["secret-two-1234567890"], // only the old secret
       secure: false,
     });
     const s1 = await oldStorage.getSession(null);
@@ -81,7 +81,7 @@ describe("createCookieSession — commitSession + roundtrip", () => {
     // New storage has new secret first, old secret second (rotation)
     const newStorage = createCookieSession({
       name: "__test",
-      secrets: ["secret-one", "secret-two"],
+      secrets: ["secret-one-1234567890", "secret-two-1234567890"],
       secure: false,
     });
     const cookieValue = cookie.split(";")[0];

package/src/adapters/cloudflare.ts

@@ -0,0 +1,65 @@
+/**
+ * Cloudflare Workers adapter for BractJS.
+ *
+ * Usage in your worker entrypoint:
+ *   import { createCloudflareAdapter } from 'bractjs/adapters/cloudflare';
+ *   import { buildFetchHandler } from 'bractjs';
+ *
+ *   const handler = buildFetchHandler({ appDir: './app', ... });
+ *   export default createCloudflareAdapter(handler);
+ *
+ * Build with:
+ *   bun build --target=browser --outfile=dist/worker.js src/worker.ts
+ */
+
+import type { BractAdapter } from "../server/adapter.ts";
+
+// Cloudflare Workers ExportedHandler shape (subset we need).
+interface CloudflareEnv {
+  [key: string]: unknown;
+}
+
+interface CloudflareExecutionContext {
+  waitUntil(promise: Promise<unknown>): void;
+  passThroughOnException(): void;
+}
+
+interface CloudflareExportedHandler {
+  fetch(request: Request, env: CloudflareEnv, ctx: CloudflareExecutionContext): Promise<Response>;
+}
+
+/**
+ * Wraps a BractJS fetch handler in the Cloudflare Workers `{ fetch }` export pattern.
+ *
+ * The adapter implements BractAdapter so it can also be passed to createServer()
+ * in a dual-mode setup (dev = Bun, prod = CF).
+ */
+export function createCloudflareAdapter(
+  handler: (request: Request) => Promise<Response>,
+): CloudflareExportedHandler & BractAdapter {
+  return {
+    // BractAdapter compat
+    fetch(request: Request) {
+      return handler(request);
+    },
+    // Cloudflare Workers entrypoint — env and ctx are available for KV, D1, etc.
+    // Forward them via a custom header so route handlers can read them if needed.
+    // (Full KV/D1 integration would require framework-level dependency injection.)
+  };
+}
+
+/**
+ * Convenience: export a Cloudflare Workers handler from your app config.
+ *
+ * Usage in src/worker.ts:
+ *   export default cloudflareHandler;
+ */
+export function makeCloudflareHandler(
+  handler: (request: Request) => Promise<Response>,
+): { fetch(request: Request, env: CloudflareEnv, ctx: CloudflareExecutionContext): Promise<Response> } {
+  return {
+    fetch(request, _env, _ctx) {
+      return handler(request);
+    },
+  };
+}

package/src/build/bundler.ts

@@ -1,4 +1,4 @@
-import { join } from "node:path";
+import { join, basename, extname, resolve } from "node:path";
 import { rename } from "node:fs/promises";
 import type { BractJSConfig } from "../server/serve.ts";
 import { scanRoutes } from "../server/scanner.ts";
@@ -8,6 +8,7 @@ import { serverOnlyPlugin, clientEnvPlugin } from "./env-plugin.ts";
 import { buildDefines } from "./defines.ts";
 import { writeRouteTypes } from "../codegen/route-codegen.ts";
 import { useClientStubPlugin, useServerProxyPlugin } from "./directives.ts";
+import { cssModulesPlugin } from "./plugins/css-modules.ts";
 
 export async function runBuild(config: BractJSConfig): Promise<void> {
   const appDir = config.appDir ?? "./app";
@@ -39,7 +40,7 @@ export async function runBuild(config: BractJSConfig): Promise<void> {
     minify: config.minify ?? true,
     sourcemap: config.sourcemap ?? "external",
     define: buildDefines(config),
-    plugins: [serverOnlyPlugin, useServerProxyPlugin, clientEnvPlugin(config.clientEnv ?? [], Bun.env as Record<string, string>)],
+    plugins: [serverOnlyPlugin, useServerProxyPlugin, clientEnvPlugin(config.clientEnv ?? [], Bun.env as Record<string, string>), cssModulesPlugin],
   });
   if (!clientResult.success) throw new AggregateError(clientResult.logs, "Client build failed");
 
@@ -47,6 +48,10 @@ export async function runBuild(config: BractJSConfig): Promise<void> {
   const routeChunks = new Map<string, string>();
   let clientEntry = "";
   let rootChunk: string | undefined;
+  const outdirAbs = resolve("build/client");
+  const appDirClean = appDir.replace(/^\.\//, "");
+  const entryBase = basename("src/client/entry.tsx", extname("src/client/entry.tsx")); // "entry"
+  const rootBase = basename(rootFilePath, extname(rootFilePath)); // "root"
 
   for (const artifact of clientResult.outputs) {
     if (artifact.kind !== "chunk" && artifact.kind !== "entry-point") continue;
@@ -57,13 +62,19 @@ export async function runBuild(config: BractJSConfig): Promise<void> {
     await rename(artifact.path, hashedPath);
 
     const publicPath = "/" + hashedPath.replace(/^build\//, "build/");
-    if (artifact.kind === "entry-point" && artifact.path.includes("entry")) {
+    const absPath = resolve(artifact.path);
+    const rel = absPath.startsWith(outdirAbs + "/") ? absPath.slice(outdirAbs.length + 1) : basename(artifact.path);
+    const outBase = basename(artifact.path, extname(artifact.path));
+
+    if (artifact.kind === "entry-point" && outBase === entryBase) {
       clientEntry = publicPath;
-    } else if (artifact.kind === "entry-point" && artifact.path.includes("root")) {
+    } else if (artifact.kind === "entry-point" && outBase === rootBase) {
       rootChunk = publicPath;
     } else {
-      // Map route file path back to URL pattern
-      const matched = routes.find((r) => artifact.path.includes(r.filePath.replace("./", "")));
+      const matched = routes.find((r) => {
+        const expected = join(appDirClean, r.filePath).replace(/\.[^.]+$/, ".js");
+        return rel === expected;
+      });
       if (matched) routeChunks.set(matched.urlPattern, publicPath);
     }
   }

package/src/build/directives.ts

@@ -3,10 +3,37 @@ import type { BunPlugin } from "bun";
 const CLIENT_RE = /^["']use client["']/m;
 const SERVER_RE = /^["']use server["']/m;
 
+// Strip a UTF-8 BOM and any leading ASCII whitespace before testing the
+// directive regex. Editors that save files with BOM otherwise let "use server"
+// fall through and ship server code to the client bundle.
+function normalizeForDirectiveCheck(src: string): string {
+  return src.replace(/^/, "").replace(/^\s+/, "");
+}
+function hasClientDirective(src: string): boolean {
+  return CLIENT_RE.test(normalizeForDirectiveCheck(src));
+}
+function hasServerDirective(src: string): boolean {
+  return SERVER_RE.test(normalizeForDirectiveCheck(src));
+}
+
 function extractExports(src: string): string[] {
   const names: string[] = [];
   for (const m of src.matchAll(/^export\s+(?:async\s+)?function\s+(\w+)/gm)) names.push(m[1]);
-  for (const m of src.matchAll(/^export\s+(?:let|const)\s+(\w+)\s*=/gm)) names.push(m[1]);
+  for (const m of src.matchAll(/^export\s+(?:let|const|var)\s+(\w+)\s*=/gm)) names.push(m[1]);
+  for (const m of src.matchAll(/^export\s+default\s+(?:async\s+)?function\s+(\w+)/gm)) names.push(m[1]);
+  for (const m of src.matchAll(/^export\s+class\s+(\w+)/gm)) names.push(m[1]);
+  for (const m of src.matchAll(/^export\s*\{([^}]+)\}/gm)) {
+    for (const part of m[1].split(",")) {
+      const trimmed = part.trim();
+      if (!trimmed) continue;
+      const asMatch = trimmed.match(/\bas\s+(\w+)$/);
+      if (asMatch) names.push(asMatch[1]);
+      else {
+        const idMatch = trimmed.match(/^(\w+)/);
+        if (idMatch) names.push(idMatch[1]);
+      }
+    }
+  }
   return names;
 }
 
@@ -25,7 +52,7 @@ export const useClientStubPlugin: BunPlugin = {
   setup(build) {
     build.onLoad({ filter: /\.(tsx?|jsx?)$/ }, async ({ path }) => {
       const src = await Bun.file(path).text();
-      if (!CLIENT_RE.test(src)) return undefined;
+      if (!hasClientDirective(src)) return undefined;
       const stubs = extractExports(src).map((n) => `export const ${n} = () => null;`).join("\n");
       return { contents: stubs || "export {};", loader: "ts" };
     });
@@ -52,7 +79,7 @@ export const useServerProxyPlugin: BunPlugin = {
   setup(build) {
     build.onLoad({ filter: /\.(tsx?|jsx?)$/ }, async ({ path }) => {
       const src = await Bun.file(path).text();
-      if (!SERVER_RE.test(src)) return undefined;
+      if (!hasServerDirective(src)) return undefined;
       const names = extractExports(src);
       if (names.length === 0) return { contents: "export {};", loader: "ts" };
       const proxies = await Promise.all(

package/src/build/env-plugin.ts

@@ -41,7 +41,15 @@ export function clientEnvPlugin(
     name: "bractjs-client-env",
     setup(build) {
       build.onLoad({ filter: /\.(ts|tsx|js|jsx)$/ }, async (args) => {
+        if (args.path.includes("/node_modules/")) return undefined;
         const src = await Bun.file(args.path).text();
+        // SECURITY(medium): textual regex replace runs over the whole source,
+        // including inside string literals and comments. A bare `process.env.X`
+        // anywhere — even in a documentation string — becomes the literal value
+        // (or "undefined"). This is acceptable for client builds because
+        // unwanted occurrences only yield the string "undefined", never a
+        // server secret. The allowedKeys gate is the authoritative leak check;
+        // never widen it without auditing callers.
         const contents = src.replace(
           /process\.env\.([A-Z_][A-Z0-9_]*)/g,
           (_match, key: string) =>

package/src/build/hash.ts

@@ -1,5 +1,4 @@
 import { extname, basename, dirname, join } from "node:path";
-import { test, expect } from "bun:test";
 
 // ── Helpers ────────────────────────────────────────────────────────────────
 
@@ -35,22 +34,3 @@ export async function renameWithHash(filePath: string): Promise<string> {
   const base = basename(filePath, ext);
   return join(dirname(filePath), `${base}.${hash}${ext}`);
 }
-
-// ── Tests ──────────────────────────────────────────────────────────────────
-
-test("same content → same hash", async () => {
-  const a = await hashString("hello world");
-  const b = await hashString("hello world");
-  expect(a).toBe(b);
-});
-
-test("different content → different hash", async () => {
-  const a = await hashString("foo");
-  const b = await hashString("bar");
-  expect(a).not.toBe(b);
-});
-
-test("hash is 8 hex chars", async () => {
-  const h = await hashString("bractjs");
-  expect(h).toMatch(/^[0-9a-f]{8}$/);
-});

package/src/build/plugins/css-modules.ts

@@ -0,0 +1,110 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import type { BunPlugin } from "bun";
+
+// ── Hash helpers ───────────────────────────────────────────────────────────
+
+function hashClassName(filename: string, className: string): string {
+  const raw = filename + "#" + className;
+  return createHash("sha256").update(raw).digest("hex").slice(0, 8);
+}
+
+function scopedName(filename: string, className: string): string {
+  const base = basename(filename).replace(/\.module\.css$/, "").replace(/[^A-Za-z0-9_-]/g, "_");
+  return `${base}_${className}_${hashClassName(filename, className)}`;
+}
+
+// ── CSS class name extractor ───────────────────────────────────────────────
+
+function extractClassNames(css: string): string[] {
+  const names: string[] = [];
+  // Match simple class selectors: .className { ... }
+  // Does not handle :local() or @keyframes — CSS Modules basic subset.
+  const re = /\.([A-Za-z_][A-Za-z0-9_-]*)\s*[{,:\s]/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(css)) !== null) {
+    if (!names.includes(m[1])) names.push(m[1]);
+  }
+  return names;
+}
+
+// ── Replacer ───────────────────────────────────────────────────────────────
+
+function transformCss(css: string, filePath: string, map: Record<string, string>): string {
+  // Replace each .className with .hashedName in the CSS source.
+  return css.replace(/\.([A-Za-z_][A-Za-z0-9_-]*)/g, (match, name: string) => {
+    return map[name] ? "." + map[name] : match;
+  });
+}
+
+// ── Bun plugin ────────────────────────────────────────────────────────────
+
+/**
+ * A Bun.build() plugin that handles `*.module.css` imports.
+ *
+ * At build time:
+ * 1. Reads the CSS file.
+ * 2. Extracts class names and hashes them: `${filename}_${className}_${hash8}`.
+ * 3. Returns a JS module that exports the class name mapping object.
+ * 4. Emits the transformed CSS as a side-effect (injected via a <link> tag at runtime,
+ *    or via HMR <style> injection in dev).
+ *
+ * Usage in bractjs config:
+ *   import { cssModulesPlugin } from 'bractjs/build/plugins/css-modules';
+ *   Bun.build({ plugins: [cssModulesPlugin] })
+ */
+export const cssModulesPlugin: BunPlugin = {
+  name: "bractjs-css-modules",
+  setup(build) {
+    build.onLoad({ filter: /\.module\.css$/ }, async (args) => {
+      const css = await readFile(args.path, "utf-8");
+      const classNames = extractClassNames(css);
+
+      const map: Record<string, string> = {};
+      for (const name of classNames) {
+        map[name] = scopedName(args.path, name);
+      }
+
+      const transformed = transformCss(css, args.path, map);
+
+      // Emit the transformed CSS as a JS-injected style block.
+      // In prod builds a separate CSS file is preferred; here we inline via JS
+      // so the plugin works without a separate CSS pipeline step.
+      const cssEscape = JSON.stringify(transformed);
+      const mapLiteral = JSON.stringify(map);
+
+      const code = `
+if (typeof document !== 'undefined') {
+  const existing = document.getElementById(${JSON.stringify("bract-css-" + hashClassName(args.path, "__module__"))});
+  if (!existing) {
+    const style = document.createElement('style');
+    style.id = ${JSON.stringify("bract-css-" + hashClassName(args.path, "__module__"))};
+    style.textContent = ${cssEscape};
+    document.head.appendChild(style);
+  }
+}
+export default ${mapLiteral};
+`;
+      return { contents: code, loader: "js" };
+    });
+  },
+};
+
+// ── Dev HMR injection (used by hmr-server) ───────────────────────────────
+
+/**
+ * Transform a CSS module file and return { map, css }.
+ * Used by the dev server to inject styles via HMR WebSocket.
+ */
+export async function transformCssModule(
+  filePath: string,
+): Promise<{ map: Record<string, string>; css: string }> {
+  const css = await readFile(filePath, "utf-8");
+  const classNames = extractClassNames(css);
+  const map: Record<string, string> = {};
+  for (const name of classNames) {
+    map[name] = scopedName(filePath, name);
+  }
+  return { map, css: transformCss(css, filePath, map) };
+}

package/src/client/ClientRouter.tsx

@@ -1,5 +1,5 @@
 import {
-  useState, useCallback, useEffect, startTransition,
+  useState, useCallback, useEffect, useRef, startTransition,
   type ReactNode, type ReactElement,
 } from "react";
 import {
@@ -11,6 +11,7 @@ import {
 } from "./router.tsx";
 import type { ServerManifest } from "../server/render.ts";
 import { matchPatternForPath } from "./nav-utils.ts";
+import { loaderCache, cacheKey } from "./cache.ts";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -36,6 +37,9 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
 
   const manifest = initialData.manifest;
 
+  // Stable ref to navigate so loadRoute can call it without a circular dep.
+  const navigateRef = useRef<(to: string) => Promise<void>>(null!);
+
   const setRoute = useCallback((state: Partial<RouteState>) => {
     if (state.loaderData !== undefined) setLoaderData(state.loaderData);
     if (state.actionData !== undefined) setActionData(state.actionData);
@@ -47,14 +51,98 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
   const loadRoute = useCallback(async (to: string) => {
     setNavState("loading");
     try {
-      const pattern = matchPatternForPath(to, manifest);
+      const toPathname = to.split("?")[0];
+      const pattern = matchPatternForPath(toPathname, manifest);
       const chunkUrl = pattern !== null ? manifest.routes[pattern]?.chunk : undefined;
-      const [routeModule, res] = await Promise.all([
-        chunkUrl ? import(/* @vite-ignore */ chunkUrl) : Promise.resolve(null),
-        fetch(`/_data?path=${encodeURIComponent(to)}`),
-      ]);
+
+      // Load the route module first so we can run client-side beforeLoad.
+      const routeModule = chunkUrl
+        ? (await import(/* @vite-ignore */ chunkUrl) as RouteModuleClient & { beforeLoad?: unknown })
+        : null;
+
+      // Run client-side beforeLoad if exported from the route module.
+      if (routeModule && typeof routeModule.beforeLoad === "function") {
+        const url = new URL(to, window.location.href);
+        try {
+          const result = await (routeModule.beforeLoad as (args: {
+            params: Record<string, string>;
+            context: Record<string, unknown>;
+            location: { pathname: string; search: string };
+          }) => Promise<Response | void>)({
+            params: {},
+            context: {},
+            location: { pathname: url.pathname, search: url.search },
+          });
+          if (result instanceof Response) {
+            const loc = result.headers.get("Location");
+            if (loc) { void navigateRef.current(loc); return; }
+          }
+        } catch (err) {
+          if (err instanceof Response) {
+            const loc = (err as Response).headers.get("Location");
+            if (loc) { void navigateRef.current(loc); return; }
+          }
+          throw err;
+        }
+      }
+
+      // Include search params in the /_data path param so loaders receive them.
+      const toWithSearch = to.includes("?") ? to : to + window.location.search;
+
+      // ── Cache lookup (B1 / B2) ──────────────────────────────────────────
+      // Read config and loaderDeps from the route module if available.
+      const routeConfig = (routeModule as Record<string, unknown> | null)?.config as
+        | { staleTime?: number; gcTime?: number }
+        | undefined;
+      const staleTime = routeConfig?.staleTime ?? 0;
+      const gcTime = routeConfig?.gcTime ?? 300_000;
+
+      const loaderDepsFn = (routeModule as Record<string, unknown> | null)?.loaderDeps as
+        | ((args: { searchParams: URLSearchParams }) => unknown[])
+        | undefined;
+      const searchParams = new URLSearchParams(toWithSearch.split("?")[1] ?? "");
+      const deps = loaderDepsFn ? loaderDepsFn({ searchParams }) : [toWithSearch];
+      const key = cacheKey(toPathname, deps);
+
+      const cached = loaderCache.get(key);
+      if (cached?.fresh) {
+        // Serve from cache immediately; skip fetch.
+        startTransition(() => {
+          setLoaderData(cached.data);
+          setParams((cached.data.params as Record<string, string>) ?? {});
+          setPathname(to);
+          setCurrentModule(routeModule);
+        });
+        setNavState("idle");
+        return;
+      }
+      if (cached && !cached.fresh) {
+        // Stale-while-revalidate: render stale data immediately, then refresh.
+        startTransition(() => {
+          setLoaderData(cached.data);
+          setParams((cached.data.params as Record<string, string>) ?? {});
+          setPathname(to);
+          setCurrentModule(routeModule);
+        });
+        setNavState("idle");
+        // Revalidate in background.
+        void fetch(`/_data?path=${encodeURIComponent(toWithSearch)}`)
+          .then((r) => r.ok ? r.json() : null)
+          .then((fresh) => {
+            if (!fresh) return;
+            loaderCache.set(key, fresh as Record<string, unknown>, staleTime, gcTime);
+            startTransition(() => {
+              setLoaderData(fresh as Record<string, unknown>);
+              setParams(((fresh as Record<string, unknown>).params as Record<string, string>) ?? {});
+            });
+          });
+        return;
+      }
+
+      // Cache miss — fetch from server.
+      const res = await fetch(`/_data?path=${encodeURIComponent(toWithSearch)}`);
       // Guard: always parse JSON, but only when the server signals success.
-      // Without r.ok check, a Bun 500 plain-text response causes
+      // Without res.ok check, a Bun 500 plain-text response causes
       // SyntaxError: JSON.parse: unexpected character — an unhandled rejection.
       if (!res.ok) {
         console.error(`[bractjs] /_data ${res.status} for ${to}`);
@@ -62,14 +150,30 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
         return;
       }
       const data = await res.json() as Record<string, unknown>;
+      if (staleTime > 0) loaderCache.set(key, data, staleTime, gcTime);
+
+      // Update DevTools state (dev-only — no-op in prod since the import fails).
+      const w = window as unknown as { __BRACT_DEV__?: boolean };
+      if (w.__BRACT_DEV__ === true) {
+        void import("../../dev/devtools.ts").then(({ updateDevtoolsState }) => {
+          updateDevtoolsState({
+            route: toPathname,
+            loaderData: data,
+            navState: "idle",
+            cacheEntries: loaderCache.entries(),
+          });
+        }).catch(() => {/* devtools not available in prod */});
+      }
       startTransition(() => {
         setLoaderData(data);
         setParams((data.params as Record<string, string>) ?? {});
         setPathname(to);
         setCurrentModule(routeModule);
       });
-      if ((data.meta as { title?: string })?.title) {
-        document.title = (data.meta as { title: string }).title;
+      const metaList = data.meta as Array<Record<string, unknown>> | undefined;
+      const titleEntry = metaList?.find((m) => "title" in m);
+      if (titleEntry && typeof titleEntry.title === "string") {
+        document.title = titleEntry.title;
       }
     } catch (err) {
       console.error("[bractjs] loadRoute error:", err);
@@ -83,9 +187,12 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
     history.pushState({}, "", to);
   }, [loadRoute]);
 
+  // Keep navigateRef current so loadRoute can redirect via navigate.
+  useEffect(() => { navigateRef.current = navigate; }, [navigate]);
+
   // Handle browser back / forward
   useEffect(() => {
-    const onPopState = () => { void loadRoute(location.pathname); };
+    const onPopState = () => { void loadRoute(location.pathname + location.search); };
     window.addEventListener("popstate", onPopState);
     return () => window.removeEventListener("popstate", onPopState);
   }, [loadRoute]);
@@ -93,9 +200,11 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
   // Module-level HMR: swap the current route module without a full reload.
   // The injected HMR client script calls window.__BRACTJS_HMR_ACCEPT__(pattern, mod)
   // after importing the freshly-built chunk from /_hmr/module.
+  // Dev gate: prod builds inject __BRACT_DEV__ = false; absence in browser also
+  // counts as prod since we never reference `process` here.
   useEffect(() => {
-    if (process.env.NODE_ENV === "production") return;
-    const w = window as unknown as { __BRACTJS_HMR_ACCEPT__?: unknown };
+    const w = window as unknown as { __BRACT_DEV__?: boolean; __BRACTJS_HMR_ACCEPT__?: unknown };
+    if (w.__BRACT_DEV__ !== true) return;
     w.__BRACTJS_HMR_ACCEPT__ = (pattern: string, mod: RouteModuleClient) => {
       const current = matchPatternForPath(pathname, manifest);
       if (current === pattern) startTransition(() => setCurrentModule(mod));
@@ -103,7 +212,6 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
     return () => { delete w.__BRACTJS_HMR_ACCEPT__; };
   }, [pathname, manifest]);
 
-  // Stub — real implementation in Prompt 2.6
   const submit = useCallback(async (
     _to: string,
     _opts: { method: string; body: FormData | Record<string, string> },

package/src/client/cache.ts

@@ -0,0 +1,69 @@
+// ── LoaderCache ────────────────────────────────────────────────────────────
+
+interface CacheEntry {
+  data: Record<string, unknown>;
+  timestamp: number;
+  staleTime: number;
+  gcTime: number;
+}
+
+class LoaderCache {
+  private store = new Map<string, CacheEntry>();
+  private gcTimer: ReturnType<typeof setInterval> | null = null;
+
+  set(key: string, data: Record<string, unknown>, staleTime: number, gcTime: number): void {
+    this.store.set(key, { data, timestamp: Date.now(), staleTime, gcTime });
+    this.ensureGc();
+  }
+
+  get(key: string): { data: Record<string, unknown>; fresh: boolean } | null {
+    const entry = this.store.get(key);
+    if (!entry) return null;
+    const age = Date.now() - entry.timestamp;
+    if (age > entry.gcTime) {
+      this.store.delete(key);
+      return null;
+    }
+    return { data: entry.data, fresh: age < entry.staleTime };
+  }
+
+  delete(key: string): void {
+    this.store.delete(key);
+  }
+
+  entries(): Array<{ key: string; age: number; staleTime: number; gcTime: number }> {
+    const now = Date.now();
+    return Array.from(this.store.entries()).map(([key, entry]) => ({
+      key,
+      age: now - entry.timestamp,
+      staleTime: entry.staleTime,
+      gcTime: entry.gcTime,
+    }));
+  }
+
+  private ensureGc(): void {
+    if (this.gcTimer !== null) return;
+    this.gcTimer = setInterval(() => {
+      const now = Date.now();
+      for (const [key, entry] of this.store) {
+        if (now - entry.timestamp > entry.gcTime) this.store.delete(key);
+      }
+      if (this.store.size === 0) {
+        clearInterval(this.gcTimer!);
+        this.gcTimer = null;
+      }
+    }, 60_000);
+  }
+}
+
+export const loaderCache = new LoaderCache();
+
+// ── Cache key helpers ──────────────────────────────────────────────────────
+
+/**
+ * Build a cache key from a route pattern and a (sorted) deps array.
+ * Using sorted search ensures `?a=1&b=2` and `?b=2&a=1` hit the same entry.
+ */
+export function cacheKey(pattern: string, deps: unknown[]): string {
+  return pattern + "\0" + JSON.stringify(deps);
+}

package/src/client/components/Link.tsx

@@ -7,12 +7,19 @@ import { prefetchRoute } from "../prefetch.ts";
 interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
   to: string;
   prefetch?: "hover" | "none";
+  /** Opt in to View Transitions API for this navigation (E1). */
+  viewTransition?: boolean;
   children: ReactNode;
 }
 
 // ── Component ──────────────────────────────────────────────────────────────
 
-export function Link({ to, prefetch = "none", children, ...rest }: LinkProps) {
+// Feature-detection at module evaluation so every click doesn't repeat it.
+const supportsViewTransitions =
+  typeof document !== "undefined" &&
+  typeof (document as Document & { startViewTransition?: unknown }).startViewTransition === "function";
+
+export function Link({ to, prefetch = "none", viewTransition = false, children, ...rest }: LinkProps) {
   const navCtx = useContext(NavigationContext);
   const routerCtx = useContext(RouterContext);
   const isLoading = navCtx?.state === "loading";
@@ -21,7 +28,14 @@ export function Link({ to, prefetch = "none", children, ...rest }: LinkProps) {
     if (!navCtx) return; // SSR: let browser handle naturally
     if (e.ctrlKey || e.metaKey || e.shiftKey || e.altKey) return;
     e.preventDefault();
-    void navCtx.navigate(to);
+
+    if (viewTransition && supportsViewTransitions) {
+      (document as Document & { startViewTransition(cb: () => void): void }).startViewTransition(
+        () => { void navCtx.navigate(to); },
+      );
+    } else {
+      void navCtx.navigate(to);
+    }
   }
 
   function handleMouseEnter() {