@bractjs/bractjs 0.1.25 → 0.1.27

package/src/__tests__/typed-routing.test.ts

@@ -0,0 +1,189 @@
+/**
+ * Type-level guardrail for end-to-end typed routing.
+ *
+ * The runtime helpers (`<Link>`, `useNavigate`, `useParams`, `useSearchParams`)
+ * gain their type-safety from a declaration-merging seam: `bractjs codegen`
+ * augments the package's `Register` interface, and the helpers resolve route
+ * types from it. None of that is observable at runtime — only `tsc` proves it.
+ * This test writes a fixture, generates its `route-types.gen.ts`, and runs
+ * `tsc --noEmit` over:
+ *
+ *   - positive usage (typed <Link>/useNavigate/useParams must compile), and
+ *   - negative usage guarded by `@ts-expect-error` (bad params/routes MUST error,
+ *     so a directive that goes unused fails the build), and
+ *   - a SECOND fixture with NO codegen, proving un-registered apps still compile
+ *     with the loose `string` fallback (the backwards-compat contract).
+ *
+ * It guards the subtle failure mode that nearly shipped: a too-clever resolution
+ * type silently falling back to loose `string`, which compiles but enforces
+ * nothing.
+ *
+ * The fixture lives inside the repo (`.tmp-types-*`, gitignored) so its
+ * `@bractjs/bractjs` import self-resolves to the in-repo framework via the root
+ * tsconfig `paths` mapping.
+ */
+import { test, expect, describe, beforeAll, afterAll } from "bun:test";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { resolve, join } from "node:path";
+import { generateRouteTypes } from "../codegen/route-codegen.ts";
+
+const REPO_ROOT = resolve(import.meta.dir, "../..");
+const TMP = resolve(import.meta.dir, `.tmp-types-${Date.now()}`);
+
+// Invoke TypeScript via `bunx tsc` — it works whether tsc is installed locally
+// or fetched on demand. (A direct node_modules/.bin/tsc path is unreliable here:
+// it may be a dangling symlink to an un-installed package.)
+const TSC_CMD = ["bunx", "tsc"] as const;
+
+// A fixture tsconfig that resolves `@bractjs/bractjs` → the in-repo entry, mirrors
+// the example apps' compiler options, and type-checks only this fixture's files.
+function tsconfig(includeGlobDir: string): string {
+  return JSON.stringify(
+    {
+      compilerOptions: {
+        target: "ESNext",
+        module: "ESNext",
+        moduleResolution: "bundler",
+        lib: ["ESNext", "DOM", "DOM.Iterable"],
+        jsx: "react-jsx",
+        jsxImportSource: "react",
+        strict: true,
+        noEmit: true,
+        skipLibCheck: true,
+        allowImportingTsExtensions: true,
+        types: ["react", "react-dom"],
+        // `paths` with absolute targets needs no `baseUrl` (and baseUrl is
+        // deprecated as of TS6, which would fail the compile here).
+        paths: { "@bractjs/bractjs": [join(REPO_ROOT, "src/index.ts")] },
+      },
+      include: [join(includeGlobDir, "**/*.ts"), join(includeGlobDir, "**/*.tsx")],
+    },
+    null,
+    2,
+  );
+}
+
+async function runTsc(projectDir: string): Promise<{ code: number; output: string }> {
+  const proc = Bun.spawn([...TSC_CMD, "--noEmit", "-p", join(projectDir, "tsconfig.json")], {
+    cwd: projectDir,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  return { code, output: stdout + stderr };
+}
+
+let tscAvailable = false;
+
+beforeAll(async () => {
+  await mkdir(TMP, { recursive: true });
+  // Real availability probe: actually run the compiler. Earlier this checked a
+  // symlink's existence and silently skipped when it dangled — making the whole
+  // suite a no-op that still "passed". Run `tsc --version` and trust the exit.
+  try {
+    const probe = Bun.spawn([...TSC_CMD, "--version"], { stdout: "pipe", stderr: "pipe" });
+    const out = await new Response(probe.stdout).text();
+    tscAvailable = (await probe.exited) === 0 && /Version/.test(out);
+  } catch {
+    tscAvailable = false;
+  }
+});
+
+afterAll(async () => {
+  await rm(TMP, { recursive: true, force: true });
+});
+
+describe("typed routing (type-level)", () => {
+  test("tsc is available (else the type-level assertions below are skipped)", () => {
+    // Surfaced as its own test so a skipped type-check is visible in the report
+    // rather than masquerading as a silent pass.
+    if (!tscAvailable) console.warn("[typed-routing] tsc unavailable — type-level checks skipped");
+    expect(typeof tscAvailable).toBe("boolean");
+  });
+
+  test("registered app: typed Link/useNavigate/useParams compile; bad usage errors", async () => {
+    if (!tscAvailable) return; // tsc not available in this environment — skip gracefully
+
+    const app = join(TMP, "registered");
+    await mkdir(join(app, "routes", "blog"), { recursive: true });
+    await writeFile(join(app, "routes", "_index.tsx"), "export default () => null;\n");
+    await writeFile(join(app, "routes", "blog", "[id].tsx"), "export default () => null;\n");
+
+    // Generate the registration file (augments Register on the package).
+    await writeFile(join(app, "route-types.gen.ts"), await generateRouteTypes(app));
+    await writeFile(join(app, "tsconfig.json"), tsconfig("."));
+
+    await writeFile(
+      join(app, "usage.tsx"),
+      `import { Link, useNavigate, useParams, useSearchParams } from "@bractjs/bractjs";\n` +
+        `import "./route-types.gen.ts";\n` +
+        `export function Ok() {\n` +
+        `  const navigate = useNavigate();\n` +
+        `  const p = useParams<"/blog/:id">();\n` +
+        `  const id: string = p.id;\n` +
+        `  useSearchParams<"/blog/:id">();\n` +
+        `  return (<>\n` +
+        `    <Link to="/blog/:id" params={{ id }}>typed</Link>\n` +
+        `    <Link to="/">static literal</Link>\n` +
+        `    <Link to={\`/\${id}\`}>built string (BC)</Link>\n` +
+        `    <button onClick={() => { void navigate("/blog/:id", { params: { id } }); }}>go</button>\n` +
+        `    <button onClick={() => { void navigate("/"); }}>home</button>\n` +
+        `  </>);\n` +
+        `}\n` +
+        `export function Bad() {\n` +
+        `  const navigate = useNavigate();\n` +
+        `  const p = useParams<"/blog/:id">();\n` +
+        `  return (<>\n` +
+        `    {/* @ts-expect-error wrong param key */}\n` +
+        `    <Link to="/blog/:id" params={{ wrong: "1" }}>x</Link>\n` +
+        `    {/* @ts-expect-error missing required param */}\n` +
+        `    <Link to="/blog/:id" params={{}}>x</Link>\n` +
+        `    <button onClick={() => {\n` +
+        `      // @ts-expect-error wrong param key in navigate\n` +
+        `      void navigate("/blog/:id", { params: { wrong: "1" } });\n` +
+        `    }}>go</button>\n` +
+        `    {/* @ts-expect-error /blog/:id has no \`nope\` param */}\n` +
+        `    <span>{p.nope}</span>\n` +
+        `  </>);\n` +
+        `}\n`,
+    );
+
+    const { code, output } = await runTsc(app);
+    // Exit 0 means: positives compiled AND every @ts-expect-error was satisfied
+    // by a real error. A silently-loose type would leave directives unused → TS2578.
+    // (`output` may carry bunx "Resolving dependencies" noise — key on TS errors.)
+    expect(output).not.toContain("TS2578"); // unused @ts-expect-error → typing too loose
+    expect(output).not.toMatch(/error TS/);
+    expect(code).toBe(0);
+  }, 60_000);
+
+  test("un-registered app (no codegen): loose string fallback still compiles", async () => {
+    if (!tscAvailable) return;
+
+    const app = join(TMP, "loose");
+    await mkdir(app, { recursive: true });
+    await writeFile(join(app, "tsconfig.json"), tsconfig("."));
+    // No route-types.gen.ts → Register stays empty → everything falls back to string.
+    await writeFile(
+      join(app, "usage.tsx"),
+      `import { Link, useNavigate, useParams } from "@bractjs/bractjs";\n` +
+        `export function App({ href }: { href: string }) {\n` +
+        `  const navigate = useNavigate();\n` +
+        `  const p = useParams();\n` +
+        `  return (<>\n` +
+        `    <Link to={href}>any string</Link>\n` +
+        `    <Link to="/anything/at/all">arbitrary literal</Link>\n` +
+        `    <button onClick={() => { void navigate("/wherever"); }}>{p.x}</button>\n` +
+        `  </>);\n` +
+        `}\n`,
+    );
+
+    const { code, output } = await runTsc(app);
+    expect(output).not.toMatch(/error TS/);
+    expect(code).toBe(0);
+  }, 60_000);
+});

package/src/build/bundler.ts

@@ -4,11 +4,12 @@ import type { BunPlugin } from "bun";
 import { scanRoutes } from "../server/scanner.ts";
 import { contentHash } from "./hash.ts";
 import { generateManifest, writeManifest } from "./manifest.ts";
-import { serverOnlyPlugin, clientEnvPlugin } from "./env-plugin.ts";
+import { serverModuleStubPlugin, clientEnvPlugin } from "./env-plugin.ts";
 import { buildDefines } from "./defines.ts";
 import { writeRouteTypes } from "../codegen/route-codegen.ts";
 import { useClientStubPlugin, createUseServerProxyPlugin } from "./directives.ts";
 import { cssModulesPlugin } from "./plugins/css-modules.ts";
+import { reactDedupePlugin } from "./react-dedupe.ts";
 
 /** Subset of config fields relevant to the build pipeline. */
 export interface BuildConfig {
@@ -54,18 +55,35 @@ export async function runBuild(config: BuildConfig): Promise<void> {
   if (!serverResult.success) throw new AggregateError(serverResult.logs, "Server build failed");
 
   // ── 3. Client bundle (code-split) ───────────────────────────────────────
-  const clientResult = await Bun.build({
-    entrypoints: [join(pkgRoot, "src/client/entry.tsx"), rootFilePath, ...routeFilePaths],
-    target: "browser",
-    splitting: true,
-    outdir: "build/client",
-    // No publicPath: relative chunk refs work correctly when files are served
-    // at URLs matching their outdir structure (e.g. /build/client/chunk-xxx.js).
-    minify: config.minify ?? true,
-    sourcemap: config.sourcemap ?? "external",
-    define: buildDefines(config),
-    plugins: [serverOnlyPlugin, createUseServerProxyPlugin(appDir), clientEnvPlugin(config.clientEnv ?? [], Bun.env as Record<string, string>), cssModulesPlugin, ...(config.plugins ?? [])],
-  });
+  // The framework's entry.tsx lives OUTSIDE the user's cwd (in pkgRoot). When
+  // Bun sees an entrypoint outside cwd it roots outputs at a common ancestor,
+  // emitting the entry at a nested path (build/client/src/client/entry.js) and
+  // baking ../ traversals into chunk refs — which makes `clientEntry` resolve to
+  // a URL that doesn't exist (e.g. /src/client/entry.<hash>.js). A shim file
+  // inside cwd keeps every entrypoint under one root so the entry output is flat
+  // and chunk refs stay correct. (Same technique as the dev rebuilder.)
+  const SHIM = ".bractjs-entry.tsx";
+  const shimPath = resolve(process.cwd(), SHIM);
+  await Bun.write(shimPath, `import "${join(pkgRoot, "src/client/entry.tsx")}";\nexport {};\n`);
+  const shimBase = basename(SHIM, extname(SHIM)); // ".bractjs-entry"
+
+  let clientResult: Awaited<ReturnType<typeof Bun.build>>;
+  try {
+    clientResult = await Bun.build({
+      entrypoints: [shimPath, rootFilePath, ...routeFilePaths],
+      target: "browser",
+      splitting: true,
+      outdir: "build/client",
+      // No publicPath: relative chunk refs work correctly when files are served
+      // at URLs matching their outdir structure (e.g. /build/client/chunk-xxx.js).
+      minify: config.minify ?? true,
+      sourcemap: config.sourcemap ?? "external",
+      define: buildDefines(config),
+      plugins: [reactDedupePlugin(process.cwd()), serverModuleStubPlugin, createUseServerProxyPlugin(appDir), clientEnvPlugin(config.clientEnv ?? [], Bun.env as Record<string, string>), cssModulesPlugin, ...(config.plugins ?? [])],
+    });
+  } finally {
+    await rm(shimPath, { force: true });
+  }
   if (!clientResult.success) throw new AggregateError(clientResult.logs, "Client build failed");
 
   // ── 4. Hash + rename output files ──────────────────────────────────────
@@ -74,7 +92,6 @@ export async function runBuild(config: BuildConfig): Promise<void> {
   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) {
@@ -83,8 +100,22 @@ export async function runBuild(config: BuildConfig): Promise<void> {
     // would break sibling import refs, which Bun bakes in at bundle time and
     // does NOT rewrite after rename.
     if (artifact.kind !== "entry-point") continue;
+    // Compute the source-relative path BEFORE renaming, to classify the output.
+    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));
     const hash = await contentHash(artifact.path);
     const ext = artifact.path.slice(artifact.path.lastIndexOf("."));
+
+    // The shim is the real client entry — rename it to a flat client.<hash>.js
+    // at the outdir root so its URL is /build/client/client.<hash>.js.
+    if (outBase === shimBase) {
+      const hashedPath = join(outdirAbs, `client.${hash}${ext}`);
+      await rename(artifact.path, hashedPath);
+      clientEntry = "/build/client/" + basename(hashedPath);
+      continue;
+    }
+
     const base = artifact.path.slice(0, artifact.path.lastIndexOf("."));
     const hashedPath = `${base}.${hash}${ext}`;
     await rename(artifact.path, hashedPath);
@@ -94,13 +125,8 @@ export async function runBuild(config: BuildConfig): Promise<void> {
     const publicPath = hashedAbs.startsWith(cwdAbs + "/")
       ? "/" + hashedAbs.slice(cwdAbs.length + 1).replace(/\\/g, "/")
       : "/" + hashedPath.replace(/^build\//, "build/");
-    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 (outBase === entryBase) {
-      clientEntry = publicPath;
-    } else if (outBase === rootBase) {
+    if (outBase === rootBase) {
       rootChunk = publicPath;
     } else {
       const matched = routes.find((r) => {

package/src/build/directives.ts

@@ -10,14 +10,14 @@ const SERVER_RE = /^["']use server["']/m;
 function normalizeForDirectiveCheck(src: string): string {
   return src.replace(/^/, "").replace(/^\s+/, "");
 }
-function hasClientDirective(src: string): boolean {
+export 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[] {
+export 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|var)\s+(\w+)\s*=/gm)) names.push(m[1]);

package/src/build/env-plugin.ts

@@ -1,5 +1,6 @@
 import type { BunPlugin } from "bun";
 import { resolve } from "node:path";
+import { extractExports } from "./directives.ts";
 
 // Lazy: this module is re-exported from the package barrel, so it may be
 // statically pulled into client bundles. `import.meta.dir` is undefined in the
@@ -41,6 +42,68 @@ export const serverOnlyPlugin: BunPlugin = {
   },
 };
 
+// ── Server-only module stub ────────────────────────────────────────────────
+
+const SERVER_FILE_RE = /\.server\.(tsx?|jsx?)$/;
+const DEFAULT_EXPORT_RE = /^export\s+default\b/m;
+
+// Runtime stub injected for every named/default export of a `*.server.ts`
+// module on the client. It is a callable Proxy that throws on call AND on
+// property access, so:
+//   • the route module's loader/action keep referencing the symbols (the
+//     bundle still resolves `import { db } from "./db.server.ts"`), and
+//   • the bodies are inert dead code on the client (the server runs them), but
+//   • any *accidental* use from real client code throws a clear error instead
+//     of silently shipping a broken `undefined`.
+const SERVER_STUB_FACTORY = `const __bractServerStub = (name) => {
+  const fail = () => {
+    throw new Error(
+      "[BractJS] '" + name + "' comes from a *.server.ts module and is not " +
+      "available in the browser. Call it only inside a loader() or action()."
+    );
+  };
+  return new Proxy(fail, { get: (_t, prop) => (prop === "name" ? name : fail()), apply: fail });
+};`;
+
+/**
+ * Client build: replace every export of a `*.server.ts` module with an inert
+ * stub instead of hard-failing the build.
+ *
+ * BractJS ships the *entire* route module — loader and action included — to the
+ * client bundle (the server never strips them). A route that legitimately does
+ * `import { db } from "./db.server.ts"` inside its loader therefore drags the
+ * server module into the client graph. Hard-failing that import (the old
+ * `serverOnlyPlugin` behaviour) made the documented "import a server module in
+ * a loader" pattern impossible. Stubbing instead:
+ *   - keeps named/default imports resolvable, so the route module compiles,
+ *   - guarantees **zero** server source (DB drivers, secrets, `bun:sqlite`,
+ *     etc.) reaches the browser — the original file is never read for content,
+ *   - throws loudly if a stub is ever actually used on the client.
+ *
+ * Loaders/actions are dead code on the client (only the server invokes them),
+ * so the stubs are never called in correct usage.
+ */
+export const serverModuleStubPlugin: BunPlugin = {
+  name: "bractjs-server-module-stub",
+  setup(build) {
+    build.onLoad({ filter: SERVER_FILE_RE }, async ({ path }) => {
+      const src = await Bun.file(path).text();
+      const names = extractExports(src);
+      const lines = [SERVER_STUB_FACTORY];
+      for (const name of names) {
+        lines.push(`export const ${name} = __bractServerStub(${JSON.stringify(name)});`);
+      }
+      if (DEFAULT_EXPORT_RE.test(src)) {
+        lines.push(`export default __bractServerStub("default");`);
+      }
+      // `export {};` guarantees the module is treated as ESM even when the
+      // server file had no statically-detectable exports.
+      lines.push("export {};");
+      return { contents: lines.join("\n"), loader: "ts" };
+    });
+  },
+};
+
 // ── Client env allowlist ───────────────────────────────────────────────────
 
 /**

package/src/build/react-dedupe.ts

@@ -0,0 +1,41 @@
+import type { BunPlugin } from "bun";
+
+/**
+ * Force every `react` / `react-dom` import in the CLIENT bundle to resolve to a
+ * single physical copy (the app's cwd copy).
+ *
+ * The client build mixes entrypoints from two roots: the framework's
+ * `src/client/entry.tsx` (which resolves react from the framework's
+ * node_modules) and the app's route files (which resolve react from the app's
+ * node_modules). When the `file:..`-linked framework carries its own react copy
+ * — even at the same version — those are two distinct module instances. The
+ * result is a dual-React "invalid hook call" (`ReactSharedInternals.H` is null)
+ * the moment a `"use client"` component runs a hook during hydration.
+ *
+ * Pinning all react specifiers to one resolved path eliminates the duplication.
+ */
+const REACT_RE = /^(react|react-dom)(\/.*)?$/;
+
+export function reactDedupePlugin(appCwd: string = process.cwd()): BunPlugin {
+  const cache = new Map<string, string>();
+  const resolveOne = (spec: string): string | null => {
+    if (cache.has(spec)) return cache.get(spec)!;
+    try {
+      const resolved = Bun.resolveSync(spec, appCwd);
+      cache.set(spec, resolved);
+      return resolved;
+    } catch {
+      return null;
+    }
+  };
+
+  return {
+    name: "bractjs:react-dedupe",
+    setup(build) {
+      build.onResolve({ filter: REACT_RE }, (args) => {
+        const resolved = resolveOne(args.path);
+        return resolved ? { path: resolved } : undefined;
+      });
+    },
+  };
+}

package/src/client/ClientRouter.tsx

@@ -10,13 +10,16 @@ import {
   type RouteModuleClient,
 } from "./router.tsx";
 import type { ServerManifest } from "../server/render.ts";
-import { matchPatternForPath } from "./nav-utils.ts";
+import { matchPatternForPath, toSamePath } from "./nav-utils.ts";
 import { loaderCache, cacheKey } from "./cache.ts";
+import { MetaTags } from "../shared/meta-tags.tsx";
+import type { MetaDescriptor } from "../shared/route-types.ts";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
 export interface BractJSInitialData extends RouteState {
   manifest: ServerManifest;
+  meta?: MetaDescriptor[];
 }
 
 interface ClientRouterProps {
@@ -34,6 +37,7 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
   const [pathname, setPathname] = useState(initialData.pathname);
   const [navState, setNavState] = useState<NavigationState>("idle");
   const [currentModule, setCurrentModule] = useState<RouteModuleClient | null>(initialModule);
+  const [meta, setMeta] = useState<MetaDescriptor[]>(initialData.meta ?? []);
 
   const manifest = initialData.manifest;
 
@@ -50,6 +54,15 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
   /** Load route data + module without touching history. */
   const loadRoute = useCallback(async (to: string) => {
     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
+    // fed to the router — we do a full-page navigation so the browser's own
+    // cross-origin handling applies and we never open-redirect via pushState.
+    const followRedirect = (loc: string) => {
+      const safe = toSamePath(loc);
+      if (safe) { void navigateRef.current(safe); return; }
+      window.location.href = loc;
+    };
     try {
       const toPathname = to.split("?")[0];
       const pattern = matchPatternForPath(toPathname, manifest);
@@ -75,12 +88,12 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
           });
           if (result instanceof Response) {
             const loc = result.headers.get("Location");
-            if (loc) { void navigateRef.current(loc); return; }
+            if (loc) { followRedirect(loc); return; }
           }
         } catch (err) {
           if (err instanceof Response) {
             const loc = (err as Response).headers.get("Location");
-            if (loc) { void navigateRef.current(loc); return; }
+            if (loc) { followRedirect(loc); return; }
           }
           throw err;
         }
@@ -176,11 +189,11 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
         setPathname(to);
         setCurrentModule(routeModule);
       });
-      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;
-      }
+      // 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));
     } catch (err) {
       console.error("[bractjs] loadRoute error:", err);
     } finally {
@@ -229,6 +242,7 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
   return (
     <RouterContext.Provider value={{ loaderData, actionData, params, pathname, manifest, currentModule, setRoute }}>
       <NavigationContext.Provider value={{ state: navState, navigate, submit }}>
+        <MetaTags meta={meta} />
         {children}
       </NavigationContext.Provider>
     </RouterContext.Provider>

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/components/Form.tsx

@@ -1,6 +1,7 @@
 import { useContext, type FormEvent, type ReactNode, type FormHTMLAttributes } from "react";
 import { RouterContext, NavigationContext } from "../router.tsx";
 import { reloadLoaders } from "../form-utils.ts";
+import { toSamePath } from "../nav-utils.ts";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -49,8 +50,16 @@ export function Form({ method = "post", action, children, ...rest }: FormProps)
       headers: { "X-BractJS-Action": "1" },
     });
 
+    // The action returned (or threw) a redirect. The browser auto-follows the
+    // 3xx, so `response.url` is the *absolute* final URL — normalize it to a
+    // same-origin path before handing it to the client router, which matches a
+    // route pattern against the pathname (an absolute URL wouldn't match). An
+    // off-origin final URL is NOT handed to the SPA router: fall back to a
+    // full-page navigation so we don't open-redirect through it.
     if (response.redirected) {
-      await navigate(response.url);
+      const to = toSamePath(response.url);
+      if (to) { await navigate(to); return; }
+      window.location.href = response.url;
       return;
     }
 

package/src/client/components/Link.tsx

@@ -1,16 +1,28 @@
 import { useContext, type AnchorHTMLAttributes, type ReactNode } from "react";
 import { NavigationContext, RouterContext } from "../router.tsx";
 import { prefetchRoute } from "../prefetch.ts";
+import { buildPath } from "../build-path.ts";
+import type { RegisteredRoutes, ParamsFor } from "../registry.ts";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
-interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
-  to: string;
+// `to` accepts any registered route literal (autocomplete + typed `params`) but
+// also any string via `(string & {})`, so existing call sites that build the URL
+// themselves — `to={`/posts/${slug}`}`, `to={item.href}` — keep compiling. Run
+// `bractjs codegen` to register the app's routes and unlock autocomplete; until
+// then `RegisteredRoutes` is `string` and this is just today's loose prop.
+type LinkProps<TTo extends RegisteredRoutes = RegisteredRoutes> = Omit<
+  AnchorHTMLAttributes<HTMLAnchorElement>,
+  "href"
+> & {
+  to: TTo | (string & {});
+  /** Path params for a dynamic `to` (e.g. `params={{ id }}` for `/blog/:id`). */
+  params?: ParamsFor<TTo>;
   prefetch?: "hover" | "none";
   /** Opt in to View Transitions API for this navigation (E1). */
   viewTransition?: boolean;
   children: ReactNode;
-}
+};
 
 // ── Component ──────────────────────────────────────────────────────────────
 
@@ -19,11 +31,22 @@ const supportsViewTransitions =
   typeof document !== "undefined" &&
   typeof (document as Document & { startViewTransition?: unknown }).startViewTransition === "function";
 
-export function Link({ to, prefetch = "none", viewTransition = false, children, ...rest }: LinkProps) {
+export function Link<TTo extends RegisteredRoutes = RegisteredRoutes>({
+  to,
+  params,
+  prefetch = "none",
+  viewTransition = false,
+  children,
+  ...rest
+}: LinkProps<TTo>) {
   const navCtx = useContext(NavigationContext);
   const routerCtx = useContext(RouterContext);
   const isLoading = navCtx?.state === "loading";
 
+  // Resolve the final href once: substitute params into a dynamic pattern, or
+  // pass an already-built string straight through.
+  const href = params ? buildPath(to as string, params as Record<string, string>) : (to as string);
+
   function handleClick(e: React.MouseEvent<HTMLAnchorElement>) {
     if (!navCtx) return; // SSR: let browser handle naturally
     if (e.ctrlKey || e.metaKey || e.shiftKey || e.altKey) return;
@@ -31,20 +54,20 @@ export function Link({ to, prefetch = "none", viewTransition = false, children,
 
     if (viewTransition && supportsViewTransitions) {
       (document as Document & { startViewTransition(cb: () => void): void }).startViewTransition(
-        () => { void navCtx.navigate(to); },
+        () => { void navCtx.navigate(href); },
       );
     } else {
-      void navCtx.navigate(to);
+      void navCtx.navigate(href);
     }
   }
 
   function handleMouseEnter() {
-    if (prefetch === "hover" && routerCtx) prefetchRoute(to, routerCtx.manifest);
+    if (prefetch === "hover" && routerCtx) prefetchRoute(href, routerCtx.manifest);
   }
 
   return (
     <a
-      href={to}
+      href={href}
       onClick={handleClick}
       onMouseEnter={handleMouseEnter}
       aria-disabled={isLoading || undefined}