@bractjs/bractjs 0.1.26 → 0.1.28

package/src/build/bundler.ts

@@ -19,6 +19,8 @@ export interface BuildConfig {
   minify?: boolean;
   clientEnv?: string[];
   plugins?: BunPlugin[];
+  /** SPA mode: when `false`, the build also emits the static document shell. */
+  ssr?: boolean;
 }
 
 export async function runBuild(config: BuildConfig): Promise<void> {
@@ -30,6 +32,16 @@ export async function runBuild(config: BuildConfig): Promise<void> {
   const routeFilePaths = routes.map((r) => join(appDir, r.filePath));
   const rootFilePath = join(appDir, "root.tsx");
 
+  // Static route-module lint: surface empty routes and miscased exports at
+  // build time (no execution — just source analysis).
+  const { lintRouteModuleSource } = await import("./route-lint.ts");
+  for (const r of routes) {
+    const src = await Bun.file(join(appDir, r.filePath)).text().catch(() => "");
+    for (const warning of lintRouteModuleSource(src, r.filePath)) {
+      console.warn(`[bract] ${warning}`);
+    }
+  }
+
   // ── 1. Clean stale artefacts ────────────────────────────────────────────
   const buildDir = config.buildDir ?? "build";
   await Promise.all([
@@ -140,5 +152,26 @@ export async function runBuild(config: BuildConfig): Promise<void> {
   // ── 5. Write manifest ──────────────────────────────────────────────────
   const manifest = generateManifest({ clientEntry, rootChunk, routeChunks, mode: "production" });
   await writeManifest(manifest, "build");
+
+  // ── 6. SPA shell (ssr: false) ───────────────────────────────────────────
+  // Emit the static document shell every document GET will serve in SPA mode.
+  if (config.ssr === false) {
+    const { renderSpaShell } = await import("../server/spa.ts");
+    const { installUseClientServerStub } = await import("../server/use-client-runtime.ts");
+    // root.tsx is imported from source here — "use client" components inside
+    // it must null-render exactly as they do on the running server.
+    installUseClientServerStub(appDir);
+    const serverManifest = {
+      clientEntry,
+      rootChunk,
+      routes: Object.fromEntries(
+        Object.entries(manifest.routes).map(([pat, e]) => [pat, { file: e.chunk, chunk: e.chunk }]),
+      ),
+    };
+    const html = await renderSpaShell(appDir, serverManifest);
+    await Bun.write(join(buildDir, "client", "__spa.html"), html);
+    console.log("[bract] SPA shell → build/client/__spa.html");
+  }
+
   console.log("[bract] build complete →", Object.keys(manifest.routes).length, "routes");
 }

package/src/build/prerender.ts

@@ -0,0 +1,88 @@
+import { join } from "node:path";
+import { buildFetchHandler } from "../server/serve.ts";
+import type { ServerManifest } from "../server/render.ts";
+
+export interface PrerenderOptions {
+  /** Concrete paths to prerender (or a function resolving them, e.g. from a DB). */
+  prerender: string[] | (() => string[] | Promise<string[]>);
+  appDir?: string;
+  publicDir?: string;
+  buildDir?: string;
+  /** Override the manifest instead of loading `<buildDir>/route-manifest.json`. */
+  manifest?: ServerManifest;
+}
+
+export interface PrerenderResult {
+  written: string[];
+}
+
+/**
+ * Where a path's prerendered files live under `<buildDir>/client/_prerender`.
+ * Throws on anything that isn't a clean absolute path — these strings come
+ * from user config but become filesystem writes.
+ */
+export function prerenderPaths(path: string): { html: string; data: string } {
+  if (!path.startsWith("/")) {
+    throw new Error(`[bractjs] prerender: paths must start with "/", got ${JSON.stringify(path)}`);
+  }
+  if (path.includes(":") || path.includes("[") || path.includes("*")) {
+    throw new Error(
+      `[bractjs] prerender: ${JSON.stringify(path)} looks like a route PATTERN — ` +
+        `expand dynamic routes to concrete paths (e.g. "/blog/intro", not "/blog/:slug").`,
+    );
+  }
+  const segments = path.split("/").filter(Boolean);
+  if (segments.some((s) => s === ".." || s === ".")) {
+    throw new Error(`[bractjs] prerender: refusing path with dot segments: ${JSON.stringify(path)}`);
+  }
+  const dir = segments.join("/");
+  return {
+    html: dir === "" ? "index.html" : `${dir}/index.html`,
+    data: dir === "" ? "_data.json" : `${dir}/_data.json`,
+  };
+}
+
+/**
+ * Build-time prerendering (SSG): run the production fetch handler in-process
+ * against each configured path and write the HTML document plus its `/_data`
+ * payload (used by client navigations INTO a prerendered page) under
+ * `<buildDir>/client/_prerender/`. The production server serves these before
+ * falling back to dynamic SSR — query-carrying requests stay dynamic.
+ *
+ * Loaders run for real at build time: anything they need (DB, env) must be
+ * available to the build.
+ */
+export async function runPrerender(options: PrerenderOptions): Promise<PrerenderResult> {
+  const buildDir = options.buildDir ?? "./build";
+  const paths = typeof options.prerender === "function" ? await options.prerender() : options.prerender;
+
+  const handler = buildFetchHandler({
+    appDir: options.appDir ?? "./app",
+    publicDir: options.publicDir,
+    buildDir,
+    manifest: options.manifest,
+  });
+
+  const written: string[] = [];
+  for (const path of paths) {
+    const out = prerenderPaths(path);
+
+    const htmlRes = await handler(new Request("http://prerender.local" + path));
+    if (htmlRes.status !== 200) {
+      throw new Error(`[bractjs] prerender: GET ${path} returned ${htmlRes.status}`);
+    }
+    const htmlFile = join(buildDir, "client", "_prerender", out.html);
+    await Bun.write(htmlFile, await htmlRes.text());
+    written.push(htmlFile);
+
+    const dataRes = await handler(
+      new Request("http://prerender.local/_data?path=" + encodeURIComponent(path)),
+    );
+    if (dataRes.status === 200) {
+      const dataFile = join(buildDir, "client", "_prerender", out.data);
+      await Bun.write(dataFile, await dataRes.text());
+      written.push(dataFile);
+    }
+  }
+  return { written };
+}

package/src/build/route-lint.ts

@@ -0,0 +1,49 @@
+import { extractExports } from "./directives.ts";
+
+// The canonical route-module export names. A route file exporting a near-miss
+// (wrong case) of one of these is almost always a mistake — the framework's
+// projection is case-sensitive, so `Loader` is silently ignored.
+export const ROUTE_EXPORT_NAMES = [
+  "default", "loader", "action", "meta", "beforeLoad", "shouldRevalidate",
+  "searchSchema", "ssr", "Fallback", "handle", "ErrorBoundary", "config",
+  "loaderDeps", "context",
+] as const;
+
+const CANONICAL_LOWER = new Map(ROUTE_EXPORT_NAMES.map((n) => [n.toLowerCase(), n]));
+const CANONICAL_SET = new Set<string>(ROUTE_EXPORT_NAMES);
+
+/** A route is "renderable or does work" if it has any of these. */
+const MEANINGFUL = ["default", "loader", "action", "beforeLoad"];
+
+/**
+ * Static lint of a route module's SOURCE (no execution). Returns human-readable
+ * warning strings. Used by the dev rebuilder and the production build to catch
+ * two common, silent mistakes: a route that renders nothing, and an export
+ * whose casing doesn't match a framework export (so it's ignored).
+ */
+export function lintRouteModuleSource(src: string, filePath: string): string[] {
+  const warnings: string[] = [];
+  const names = extractExports(src);
+  // extractExports misses anonymous `export default () => …` / `export default function() {}`.
+  const hasAnonDefault = /^export\s+default\b/m.test(src) && !names.includes("default");
+  const exportSet = new Set(names);
+  if (hasAnonDefault) exportSet.add("default");
+
+  if (!MEANINGFUL.some((n) => exportSet.has(n))) {
+    warnings.push(
+      `${filePath}: route has no default/loader/action/beforeLoad export — it renders an empty page.`,
+    );
+  }
+
+  for (const name of exportSet) {
+    if (CANONICAL_SET.has(name)) continue;
+    const canonical = CANONICAL_LOWER.get(name.toLowerCase());
+    if (canonical && canonical !== name) {
+      warnings.push(
+        `${filePath}: export "${name}" looks like "${canonical}" — route exports are case-sensitive, so "${name}" is ignored.`,
+      );
+    }
+  }
+
+  return warnings;
+}

package/src/client/ClientRouter.tsx

@@ -7,19 +7,24 @@ import {
   NavigationContext,
   type RouteState,
   type NavigationState,
+  type NavigateOptions,
   type RouteModuleClient,
+  type HydrationPending,
 } from "./router.tsx";
 import type { ServerManifest } from "../server/render.ts";
-import { matchPatternForPath, toSamePath } from "./nav-utils.ts";
+import { matchPatternForPath, toSamePath, parseTo, createLocationKey } from "./nav-utils.ts";
 import { loaderCache, cacheKey } from "./cache.ts";
+import { registerRevalidator, type RevalidationInfo } from "./revalidation.ts";
 import { MetaTags } from "../shared/meta-tags.tsx";
-import type { MetaDescriptor } from "../shared/route-types.ts";
+import type { MetaDescriptor, RouterLocation, ShouldRevalidateFunction } from "../shared/route-types.ts";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
 export interface BractJSInitialData extends RouteState {
   manifest: ServerManifest;
   meta?: MetaDescriptor[];
+  /** Present when the document did not SSR the route component (selective SSR / SPA shell). */
+  ssrMode?: "client-only" | "data-only" | "spa";
 }
 
 interface ClientRouterProps {
@@ -28,31 +33,52 @@ interface ClientRouterProps {
   initialModule?: RouteModuleClient | null;
 }
 
+/** History-entry init carried into loadRoute by navigate/popstate. */
+interface LocationInit {
+  key?: string;
+  state?: unknown;
+}
+
 // ── Component ──────────────────────────────────────────────────────────────
 
 export function ClientRouter({ children, initialData, initialModule = null }: ClientRouterProps): ReactElement {
   const [loaderData, setLoaderData] = useState(initialData.loaderData);
   const [actionData, setActionData] = useState<unknown>(initialData.actionData);
   const [params, setParams] = useState(initialData.params);
-  const [pathname, setPathname] = useState(initialData.pathname);
+  const [location, setLocation] = useState<RouterLocation>(initialData.location);
+  const [search, setSearch] = useState<Record<string, unknown>>(initialData.search ?? {});
   const [navState, setNavState] = useState<NavigationState>("idle");
+  const [revalidationState, setRevalidationState] = useState<"idle" | "loading">("idle");
   const [currentModule, setCurrentModule] = useState<RouteModuleClient | null>(initialModule);
   const [meta, setMeta] = useState<MetaDescriptor[]>(initialData.meta ?? []);
+  const [hydrationPending, setHydrationPending] = useState<HydrationPending>(initialData.ssrMode ?? false);
 
   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!);
 
+  // Refs mirroring state that the stable revalidate/submit callbacks need.
+  const locationRef = useRef(location);
+  useEffect(() => { locationRef.current = location; }, [location]);
+  const currentModuleRef = useRef(currentModule);
+  useEffect(() => { currentModuleRef.current = currentModule; }, [currentModule]);
+
   const setRoute = useCallback((state: Partial<RouteState>) => {
     if (state.loaderData !== undefined) setLoaderData(state.loaderData);
     if (state.actionData !== undefined) setActionData(state.actionData);
     if (state.params !== undefined) setParams(state.params);
-    if (state.pathname !== undefined) setPathname(state.pathname);
+    if (state.search !== undefined) setSearch(state.search);
+    if (state.location !== undefined) setLocation(state.location);
+    else if (state.pathname !== undefined) {
+      // Legacy callers pass a (possibly query-carrying) pathname string.
+      const parsed = parseTo(state.pathname);
+      setLocation((prev) => ({ ...prev, ...parsed }));
+    }
   }, []);
 
   /** Load route data + module without touching history. */
-  const loadRoute = useCallback(async (to: string) => {
+  const loadRoute = useCallback(async (to: string, locInit?: LocationInit) => {
     setNavState("loading");
     // Follow a redirect Location from client-side beforeLoad. Same-origin
     // targets stay in the SPA; an off-origin/protocol-relative Location is NOT
@@ -64,7 +90,18 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
       window.location.href = loc;
     };
     try {
-      const toPathname = to.split("?")[0];
+      const { pathname: toPathname, search: toSearch, hash: toHash } = parseTo(to);
+      // The path handed to /_data: never includes the hash (the fragment is
+      // client-only) and never inherits the previous page's query string —
+      // what you navigate to is exactly what loads.
+      const dataPath = toPathname + toSearch;
+      const nextLocation: RouterLocation = {
+        pathname: toPathname,
+        search: toSearch,
+        hash: toHash,
+        state: locInit?.state ?? null,
+        key: locInit?.key ?? createLocationKey(),
+      };
       const pattern = matchPatternForPath(toPathname, manifest);
       const chunkUrl = pattern !== null ? manifest.routes[pattern]?.chunk : undefined;
 
@@ -99,8 +136,20 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
         }
       }
 
-      // Include search params in the /_data path param so loaders receive them.
-      const toWithSearch = to.includes("?") ? to : to + window.location.search;
+      // Commit a /_data payload + the new location in one transition.
+      const commit = (data: Record<string, unknown>, module: RouteModuleClient | null) => {
+        startTransition(() => {
+          setLoaderData(data);
+          setParams((data.params as Record<string, string>) ?? {});
+          setLocation(nextLocation);
+          setSearch((data.search as Record<string, unknown>) ?? {});
+          setCurrentModule(module);
+          // Re-render the document head from the new route's merged meta.
+          // React 19 hoists the <title>/<meta> elements rendered by <MetaTags>
+          // into <head>, so description/OG tags update on soft navigation.
+          setMeta((data.meta as MetaDescriptor[] | undefined) ?? []);
+        });
+      };
 
       // ── Cache lookup (B1 / B2) ──────────────────────────────────────────
       // Read config and loaderDeps from the route module if available.
@@ -113,33 +162,34 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
       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 searchParams = new URLSearchParams(toSearch);
+      const deps = loaderDepsFn ? loaderDepsFn({ searchParams }) : [dataPath];
       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);
-        });
+        commit(cached.data, 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);
-        });
+        commit(cached.data, routeModule);
         setNavState("idle");
+        // The route can veto the background refetch via shouldRevalidate.
+        const gate = (routeModule as Record<string, unknown> | null)
+          ?.shouldRevalidate as ShouldRevalidateFunction | undefined;
+        const allowRefetch = gate
+          ? gate({
+              currentUrl: new URL(window.location.href),
+              nextUrl: new URL(dataPath, window.location.origin),
+              defaultShouldRevalidate: true,
+            })
+          : true;
+        if (!allowRefetch) return;
         // Revalidate in background.
-        void fetch(`/_data?path=${encodeURIComponent(toWithSearch)}`)
+        void fetch(`/_data?path=${encodeURIComponent(dataPath)}`)
           .then((r) => r.ok ? r.json() : null)
           .then((fresh) => {
             if (!fresh) return;
@@ -147,13 +197,15 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
             startTransition(() => {
               setLoaderData(fresh as Record<string, unknown>);
               setParams(((fresh as Record<string, unknown>).params as Record<string, string>) ?? {});
+              setSearch(((fresh as Record<string, unknown>).search as Record<string, unknown>) ?? {});
+              setMeta(((fresh as Record<string, unknown>).meta as MetaDescriptor[] | undefined) ?? []);
             });
           });
         return;
       }
 
       // Cache miss — fetch from server.
-      const res = await fetch(`/_data?path=${encodeURIComponent(toWithSearch)}`);
+      const res = await fetch(`/_data?path=${encodeURIComponent(dataPath)}`);
       // Guard: always parse JSON, but only when the server signals success.
       // Without res.ok check, a Bun 500 plain-text response causes
       // SyntaxError: JSON.parse: unexpected character — an unhandled rejection.
@@ -183,17 +235,7 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
           });
         }).catch(() => {/* devtools not available in prod */});
       }
-      startTransition(() => {
-        setLoaderData(data);
-        setParams((data.params as Record<string, string>) ?? {});
-        setPathname(to);
-        setCurrentModule(routeModule);
-      });
-      // Re-render the document head from the new route's merged meta. React 19
-      // hoists the <title>/<meta> elements rendered by <MetaTags> into <head>,
-      // so description/OG tags update on soft navigation, not just the title.
-      const nextMeta = (data.meta as MetaDescriptor[] | undefined) ?? [];
-      startTransition(() => setMeta(nextMeta));
+      commit(data, routeModule);
     } catch (err) {
       console.error("[bractjs] loadRoute error:", err);
     } finally {
@@ -201,17 +243,130 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
     }
   }, [manifest]);
 
-  const navigate = useCallback(async (to: string) => {
-    await loadRoute(to);
-    history.pushState({}, "", to);
+  const navigate = useCallback(async (to: string, options?: NavigateOptions) => {
+    const key = createLocationKey();
+    await loadRoute(to, { key, state: options?.state ?? null });
+    const entry = { __bractKey: key, __bractState: options?.state ?? null };
+    if (options?.replace) history.replaceState(entry, "", to);
+    else history.pushState(entry, "", to);
   }, [loadRoute]);
 
   // Keep navigateRef current so loadRoute can redirect via navigate.
   useEffect(() => { navigateRef.current = navigate; }, [navigate]);
 
-  // Handle browser back / forward
+  /**
+   * Re-run the active route's loaders and commit fresh data without touching
+   * history or the location. Gated by the route's shouldRevalidate export;
+   * mutation-triggered runs (info.formMethod set) first drop the whole loader
+   * cache — any cached entry may reflect pre-mutation state.
+   */
+  const revalidate = useCallback(async (info?: RevalidationInfo) => {
+    const loc = locationRef.current;
+    const path = loc.pathname + loc.search;
+    const gate = (currentModuleRef.current as Record<string, unknown> | null)
+      ?.shouldRevalidate as ShouldRevalidateFunction | undefined;
+    const url = new URL(path, window.location.origin);
+    const allow = gate
+      ? gate({
+          currentUrl: url,
+          nextUrl: url,
+          formMethod: info?.formMethod,
+          actionStatus: info?.actionStatus,
+          defaultShouldRevalidate: true,
+        })
+      : true;
+    if (!allow) return;
+    if (info?.formMethod) loaderCache.clear();
+    setRevalidationState("loading");
+    try {
+      const res = await fetch(`/_data?path=${encodeURIComponent(path)}`);
+      if (!res.ok) {
+        console.error(`[bractjs] revalidate /_data ${res.status} for ${path}`);
+        return;
+      }
+      const data = (await res.json()) as Record<string, unknown>;
+      startTransition(() => {
+        setLoaderData(data);
+        setParams((data.params as Record<string, string>) ?? {});
+        setSearch((data.search as Record<string, unknown>) ?? {});
+        setMeta((data.meta as MetaDescriptor[] | undefined) ?? []);
+      });
+    } catch (err) {
+      console.error("[bractjs] revalidate error:", err);
+    } finally {
+      setRevalidationState("idle");
+    }
+  }, []);
+
+  // Let fetchers trigger revalidation without importing this component.
+  useEffect(() => {
+    registerRevalidator(revalidate);
+    return () => registerRevalidator(null);
+  }, [revalidate]);
+
+  // Selective-SSR / SPA hydration completion. The first client render matched
+  // the server (Fallback or empty shell); after mount, put loader data in
+  // place and swap in the real component via a transition.
   useEffect(() => {
-    const onPopState = () => { void loadRoute(location.pathname + location.search); };
+    if (!hydrationPending) return;
+    if (hydrationPending === "data-only") {
+      // Loaders already ran on the server — the data arrived in the bootstrap.
+      startTransition(() => setHydrationPending(false));
+      return;
+    }
+    // "client-only" / "spa": the route loader never ran for this document.
+    void (async () => {
+      const path = window.location.pathname + window.location.search;
+      try {
+        const res = await fetch(`/_data?path=${encodeURIComponent(path)}`);
+        // A redirect here is a beforeLoad gate (SPA shells skip server-side
+        // gating on the document). Do a real navigation — never render a
+        // protected route around redirected data.
+        if (res.redirected) {
+          const safe = toSamePath(res.url);
+          window.location.assign(safe ?? res.url);
+          return;
+        }
+        if (res.ok) {
+          const data = (await res.json()) as Record<string, unknown>;
+          startTransition(() => {
+            setLoaderData(data);
+            setParams((data.params as Record<string, string>) ?? {});
+            setSearch((data.search as Record<string, unknown>) ?? {});
+            setMeta((data.meta as MetaDescriptor[] | undefined) ?? []);
+            setHydrationPending(false);
+          });
+          return;
+        }
+        console.error(`[bractjs] hydration /_data ${res.status} for ${path}`);
+      } catch (err) {
+        console.error("[bractjs] hydration fetch error:", err);
+      }
+      startTransition(() => setHydrationPending(false));
+    })();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // Stamp the initial history entry with our key so back/forward to it can
+  // restore scroll position. Merge into any pre-existing state, don't replace.
+  useEffect(() => {
+    const st = history.state as Record<string, unknown> | null;
+    if (!st || typeof st.__bractKey !== "string") {
+      history.replaceState({ ...(st ?? {}), __bractKey: initialData.location.key }, "", window.location.href);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // Handle browser back / forward. `window.location` must stay explicit here —
+  // the component has a `location` state variable that would shadow the global.
+  useEffect(() => {
+    const onPopState = (e: PopStateEvent) => {
+      const st = e.state as { __bractKey?: string; __bractState?: unknown } | null;
+      void loadRoute(
+        window.location.pathname + window.location.search + window.location.hash,
+        { key: st?.__bractKey ?? "default", state: st?.__bractState ?? null },
+      );
+    };
     window.addEventListener("popstate", onPopState);
     return () => window.removeEventListener("popstate", onPopState);
   }, [loadRoute]);
@@ -225,22 +380,59 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
     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);
+      const current = matchPatternForPath(location.pathname, manifest);
       if (current === pattern) startTransition(() => setCurrentModule(mod));
     };
     return () => { delete w.__BRACTJS_HMR_ACCEPT__; };
-  }, [pathname, manifest]);
+  }, [location.pathname, manifest]);
 
+  /**
+   * Submit a mutation: navState walks "submitting" → "loading" (revalidation)
+   * → "idle", which is what `useNavigation()` renders pending UI from. The
+   * fetch mirrors `<Form>`'s contract: the CSRF header marks it a same-origin
+   * mutation, and a redirected response becomes a real navigation — via
+   * toSamePath so an attacker-controlled Location can never soft-nav the SPA.
+   */
   const submit = useCallback(async (
-    _to: string,
-    _opts: { method: string; body: FormData | Record<string, string> },
+    to: string,
+    opts: { method: string; body: FormData | Record<string, string> },
   ) => {
     setNavState("submitting");
-    setNavState("idle");
-  }, []);
+    try {
+      const body = opts.body instanceof FormData
+        ? opts.body
+        : new URLSearchParams(opts.body);
+      const res = await fetch(to, {
+        method: opts.method.toUpperCase(),
+        body,
+        headers: { "X-BractJS-Action": "1" },
+      });
+      if (res.redirected) {
+        const safe = toSamePath(res.url);
+        if (safe) {
+          // navigate() loads fresh data for the target — no extra revalidation.
+          await navigateRef.current(safe);
+          return;
+        }
+        window.location.assign(res.url);
+        return;
+      }
+      const data = (await res.json()) as unknown;
+      setActionData(data);
+      setNavState("loading");
+      await revalidate({ formMethod: opts.method, actionStatus: res.status });
+    } finally {
+      setNavState("idle");
+    }
+  }, [revalidate]);
 
   return (
-    <RouterContext.Provider value={{ loaderData, actionData, params, pathname, manifest, currentModule, setRoute }}>
+    <RouterContext.Provider
+      value={{
+        loaderData, actionData, params, pathname: location.pathname, location, search,
+        manifest, currentModule, setRoute, revalidate, revalidationState, hydrationPending,
+      }}
+    >
       <NavigationContext.Provider value={{ state: navState, navigate, submit }}>
         <MetaTags meta={meta} />
         {children}

package/src/client/build-path.ts

@@ -0,0 +1,24 @@
+// Substitute `:name` segments in a colon-style route pattern with param values.
+//
+// Mirrors the substitution `bractjs codegen` bakes into the generated `routes`
+// builder (`src/codegen/route-codegen.ts`). The framework's own `<Link>` /
+// `useNavigate` can't import that app-local generated object, so they share this
+// helper instead. Values are URL-encoded; an absent param leaves its `:name`
+// segment intact (surfaced as an obviously-wrong URL rather than silently dropped).
+//
+// Patterns without a `:` (static routes, or already-built hrefs) pass straight
+// through, so this is safe to call unconditionally.
+export function buildPath(
+  pattern: string,
+  params: Record<string, string | number>,
+): string {
+  if (!pattern.includes(":")) return pattern;
+  return pattern
+    .split("/")
+    .map((seg) => {
+      if (!seg.startsWith(":")) return seg;
+      const value = params[seg.slice(1)];
+      return value === undefined ? seg : encodeURIComponent(String(value));
+    })
+    .join("/");
+}

package/src/client/cache.ts

@@ -31,6 +31,14 @@ class LoaderCache {
     this.store.delete(key);
   }
 
+  /**
+   * Drop every entry. Called after a successful mutation — any cached loader
+   * data may now be stale, and serving it would show pre-mutation state.
+   */
+  clear(): void {
+    this.store.clear();
+  }
+
   entries(): Array<{ key: string; age: number; staleTime: number; gcTime: number }> {
     const now = Date.now();
     return Array.from(this.store.entries()).map(([key, entry]) => ({

package/src/client/components/Await.tsx

@@ -1,7 +1,13 @@
 import { Suspense, use, type ReactNode } from "react";
+import { Deferred } from "../../shared/deferred.ts";
 
 interface AwaitProps<T> {
-  resolve: Promise<T>;
+  /**
+   * A promise, or a `Deferred<T>` field from a loader that returned `defer()`.
+   * `useLoaderData<typeof loader>()` preserves deferred fields as `Deferred<T>`,
+   * so they can be passed straight through.
+   */
+  resolve: Promise<T> | Deferred<T>;
   fallback: ReactNode;
   children: (data: T) => ReactNode;
 }
@@ -13,7 +19,8 @@ interface AwaitProps<T> {
  * with the resolved value.
  */
 function Resolved<T>({ resolve, children }: Pick<AwaitProps<T>, "resolve" | "children">) {
-  const data = use(resolve);
+  const promise = resolve instanceof Deferred ? resolve.promise : resolve;
+  const data = use(promise);
   return <>{children(data)}</>;
 }