@bractjs/bractjs 0.1.26 → 0.1.27

package/README.md

@@ -34,7 +34,7 @@ This README is a **step-by-step guide to every function and feature** BractJS ex
 15. [Sessions: `createCookieSession`](#15-sessions)
 16. [Lifecycle hooks: `defineLifecycle`](#16-lifecycle-hooks)
 17. [Environment variables & `*.server.ts`](#17-environment-variables)
-18. [Typed routes codegen](#18-typed-routes-codegen)
+18. [Typed routes](#18-typed-routes)
 19. [Internationalization (i18n) utilities](#19-internationalization-utilities)
 20. [Image optimization (`<Image>` + `/_image`)](#20-image-optimization)
 21. [Build & run: CLI + programmatic API (`createDevServer`, `runBuild`, `loadUserConfig`)](#21-build--run)
@@ -353,10 +353,12 @@ const result = useActionData<{ error?: string }>();
 ```
 
 ### `useParams<T>()` → `T`
-URL dynamic params. Pass a generic for typed params.
+URL dynamic params. Pass the **route pattern** as a generic to type the result against your codegen'd routes (see §18); an object shape also works.
 ```ts
-const { id } = useParams<{ id: string }>();
+const { id } = useParams<"/blog/:id">();        // { id: string } — typed from routes
+const { id } = useParams<{ id: string }>();     // or a hand-written shape
 ```
+> The pattern is supplied by the caller because the framework can't infer the active route at the type level (React Router's `useParams` works the same way).
 
 ### `useNavigation()` → `{ state }`
 `"idle" | "loading" | "submitting"`.
@@ -365,12 +367,21 @@ const { state } = useNavigation();
 if (state === "loading") return <Spinner />;
 ```
 
+### `useNavigate()` → `(to, { params? }) => Promise<void>`
+Imperative soft navigation — the counterpart to `<Link>`. `to` autocompletes your routes (after codegen, §18) and `params` is typed per route; any string is still accepted.
+```ts
+const navigate = useNavigate();
+await navigate("/blog/:id", { params: { id: "42" } });   // typed
+await navigate("/about");                                  // static
+await navigate(`/blog/${id}`);                             // built string (also fine)
+```
+
 ### `useSearchParams<T>()` → `{ searchParams, getParam, setSearchParams }`
-Read/write URL query params; writing triggers a soft-nav loader re-run.
+Read/write URL query params; writing triggers a soft-nav loader re-run. Pass the route pattern as a generic to type the result against `RouteSearchParamsMap` (augment it per route, §18); an object shape also works.
 ```ts
-const { searchParams, getParam, setSearchParams } = useSearchParams<{ q: string }>();
-const q = getParam("q");                       // string | null
-setSearchParams({ q: "bun" });                 // replace all params
+const { searchParams, getParam, setSearchParams } = useSearchParams<"/blog/:id">();
+const q = getParam("q");                        // string | null
+setSearchParams({ q: "bun" });                  // replace all params
 setSearchParams((prev) => { prev.set("page", "2"); return prev; }); // update
 ```
 
@@ -415,12 +426,13 @@ export default function BlogLayout() {
 }
 ```
 
-### `<Link to prefetch? viewTransition?>`
-Soft-navigates without a full reload.
+### `<Link to params? prefetch? viewTransition?>`
+Soft-navigates without a full reload. After codegen (§18), `to` autocompletes your routes; for a dynamic route pass typed `params`. Building the URL yourself still works, so existing links need no changes.
 ```tsx
-<Link to="/blog/42">Read</Link>
-<Link to="/about" prefetch="hover">About</Link>   {/* preload chunk + loader on hover */}
-<Link to="/gallery" viewTransition>Gallery</Link> {/* use View Transitions API */}
+<Link to="/blog/:id" params={{ id: "42" }}>Read</Link>  {/* typed route + params */}
+<Link to={`/blog/${id}`}>Read</Link>                    {/* built string — also fine */}
+<Link to="/about" prefetch="hover">About</Link>         {/* preload chunk + loader on hover */}
+<Link to="/gallery" viewTransition>Gallery</Link>       {/* use View Transitions API */}
 ```
 Modifier-clicks (ctrl/cmd/shift/alt) fall back to native browser navigation.
 
@@ -738,48 +750,55 @@ On the server, read env via `Bun.env.*` directly.
 
 ---
 
-## 18. Typed routes codegen
+## 18. Typed routes
 
-Generate per-route param types and a type-safe URL builder from your route files.
+Generate type-safe routing from your route files — one command wires `<Link>`, `useNavigate`, `useParams`, and `useSearchParams` to your actual routes.
 
 ```sh
 bractjs codegen                       # ./app → ./app/route-types.gen.ts
 bractjs codegen ./app ./app/types.ts  # explicit paths
 ```
 
-Runs automatically during `bractjs build`. The generated file provides:
+Runs automatically during `bractjs build`. Make sure the generated file is part of your TypeScript program (it is, if your `tsconfig.json` `include`s `app/`). It augments BractJS's `Register` interface, after which the runtime components and hooks become type-safe — **no per-route imports needed**:
 
-```ts
-export type AppRoutes = "/" | "/blog/:id" | "/org/:orgId/repo/:repoId";
-
-export type RouteParams<T extends AppRoutes> =
-  T extends "/blog/:id" ? { id: string } : Record<never, never>;
+```tsx
+<Link to="/blog/:id" params={{ id }} />     // ✅ "/blog/:id" autocompletes; params typed
+<Link to="/blgo/:id" params={{ id }} />     // ❌ typo'd route — compile error
+<Link to="/blog/:id" params={{ x: id }} />  // ❌ wrong param key — compile error
 
-export type TypedLoaderArgs<T extends AppRoutes> = { request: Request; params: RouteParams<T>; context: Record<string, unknown> };
-export type TypedActionArgs<T extends AppRoutes> = TypedLoaderArgs<T> & { formData: FormData };
+const navigate = useNavigate();
+navigate("/blog/:id", { params: { id } });  // ✅ same typing as <Link>
 
-export const routes = {
-  "/": () => "/",
-  "/blog/:id": (p: { id: string }) => `/blog/${p.id}`,
-} as const;
+const { id } = useParams<"/blog/:id">();     // id: string
 ```
 
-Use them for typed loaders and safe navigation:
+Building the URL yourself (`<Link to={`/blog/${id}`}>`) still type-checks, so adopting codegen never breaks existing links.
+
+The generated file also exports types/helpers for typed loaders and explicit URL building:
 
 ```ts
-import type { TypedLoaderArgs, RouteParams } from "../route-types.gen.ts";
+import type { TypedLoaderArgs } from "../route-types.gen.ts";
 import { routes } from "../route-types.gen.ts";
 
 export async function loader({ params }: TypedLoaderArgs<"/blog/:id">) {
-  return db.post.findById(params.id); // params.id: string
+  return db.post.findById(params.id);          // params.id: string
 }
+routes["/blog/:id"]({ id: "123" });            // → "/blog/123"  (typo'd routes won't compile)
+```
+
+**Type a route's search params or context** by augmenting the package interfaces — `SearchParams<T>` / `Context<T>` and `useSearchParams<T>()` pick it up:
 
-const { id } = useParams<RouteParams<"/blog/:id">>();
-routes["/blog/:id"]({ id: "123" }); // → "/blog/123"  (typo'd routes won't compile)
+```ts
+declare module "@bractjs/bractjs" {
+  interface RouteSearchParamsMap { "/blog": { page: string; sort: string } }
+  interface RouteContextMap { "/admin": { user: { id: string; role: "admin" } } }
+}
 ```
 
 You can also call `writeRouteTypes(appDir, outPath?)` / `generateRouteTypes(appDir)` programmatically.
 
+> **Heads up:** earlier versions documented `useParams<RouteParams<"/blog/:id">>()` and untyped `<Link to={string}>`. The route-literal form (`useParams<"/blog/:id">()`) and typed `<Link>`/`useNavigate` are the current API; the old forms still compile.
+
 ---
 
 ## 19. Internationalization utilities
@@ -1098,7 +1117,7 @@ See [CHANGELOG.md](CHANGELOG.md) for release history.
 - **Streaming SSR** — `renderToReadableStream()` with `defer()` and `<Await>`.
 - **File-based routing** — drop a file in `app/routes/`.
 - **Full-stack** — loaders, actions, sessions, server actions, typed API routes, middleware.
-- **Typed routes** — codegen produces per-route params and a type-safe URL builder.
+- **Typed routes** — codegen wires `<Link>`, `useNavigate`, and `useParams` to your routes (autocompleted paths, typed params), plus a type-safe URL builder.
 - **Single-binary** — `bun build --compile` to one executable.
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bractjs/bractjs",
-  "version": "0.1.26",
+  "version": "0.1.27",
   "description": "Production-grade SSR framework for Bun + React 19. File-based routing, streaming SSR, server actions, typed routes.",
   "license": "MIT",
   "homepage": "https://github.com/bractjs/bractjs#readme",

package/src/__tests__/build-path.test.ts

@@ -0,0 +1,29 @@
+import { test, expect, describe } from "bun:test";
+import { buildPath } from "../client/build-path.ts";
+
+describe("buildPath", () => {
+  test("substitutes a single :param", () => {
+    expect(buildPath("/blog/:id", { id: "42" })).toBe("/blog/42");
+  });
+
+  test("substitutes multiple params", () => {
+    expect(buildPath("/u/:user/post/:post", { user: "ann", post: "7" })).toBe("/u/ann/post/7");
+  });
+
+  test("passes static patterns through untouched", () => {
+    expect(buildPath("/about", {})).toBe("/about");
+    expect(buildPath("/", {})).toBe("/");
+  });
+
+  test("URL-encodes param values", () => {
+    expect(buildPath("/search/:q", { q: "a b/c" })).toBe("/search/a%20b%2Fc");
+  });
+
+  test("coerces numbers to strings", () => {
+    expect(buildPath("/n/:id", { id: 7 })).toBe("/n/7");
+  });
+
+  test("leaves an absent param's segment intact (surfaces as an obvious bad URL)", () => {
+    expect(buildPath("/blog/:id", {})).toBe("/blog/:id");
+  });
+});

package/src/__tests__/codegen.test.ts

@@ -29,6 +29,42 @@ describe("route-codegen — output shape", () => {
     expect(out).toMatch(/\| "\/users\/:id"/);
   });
 
+  test("wires the Register augmentation for typed routing", async () => {
+    const regApp = join(tmpdir(), `bract-codegen-register-${Date.now()}`);
+    await mkdir(join(regApp, "routes", "users"), { recursive: true });
+    await writeFile(join(regApp, "routes", "about.tsx"), "export default () => null;");
+    await writeFile(join(regApp, "routes", "users", "[id].tsx"), "export default () => null;");
+
+    const out = await generateRouteTypes(regApp);
+
+    // Bug 1 regression: the augmentation must target the real package name.
+    expect(out).toContain('declare module "@bractjs/bractjs"');
+    expect(out).not.toMatch(/declare module ['"]bractjs['"]/);
+
+    // Bug 2 regression: the customization maps are AUGMENTED on the package, not
+    // re-declared as bare top-level interfaces in the app file.
+    expect(out).not.toMatch(/^export interface RouteSearchParamsMap/m);
+    expect(out).not.toMatch(/^export interface RouteContextMap/m);
+    expect(out).toContain('import type { RouteSearchParamsMap, RouteContextMap } from "@bractjs/bractjs"');
+
+    // The Register seam carries the route union and a per-route params map.
+    expect(out).toContain("interface Register {");
+    expect(out).toContain("routes: AppRoutes;");
+    expect(out).toMatch(/"\/users\/:id": \{ id: string \};/); // dynamic route → typed params
+    expect(out).toMatch(/"\/about": \{\};/);                   // static route → no params
+
+    await rm(regApp, { recursive: true, force: true });
+  });
+
+  test("emits no Register augmentation when there are no routes", async () => {
+    const emptyApp = join(tmpdir(), `bract-codegen-empty-${Date.now()}`);
+    await mkdir(join(emptyApp, "routes"), { recursive: true });
+    const out = await generateRouteTypes(emptyApp);
+    expect(out).toContain("export type AppRoutes =\n  never;");
+    expect(out).not.toContain("interface Register {");
+    await rm(emptyApp, { recursive: true, force: true });
+  });
+
   test("rejects hostile filenames at codegen time", async () => {
     const hostileApp = join(tmpdir(), `bract-codegen-hostile-${Date.now()}`);
     await mkdir(join(hostileApp, "routes"), { recursive: true });

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/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/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}

package/src/client/hooks/useNavigate.ts

@@ -0,0 +1,46 @@
+import { useContext, useCallback } from "react";
+import { NavigationContext } from "../router.tsx";
+import { buildPath } from "../build-path.ts";
+import type { RegisteredRoutes, ParamsFor } from "../registry.ts";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export interface NavigateOptions<TTo extends RegisteredRoutes = RegisteredRoutes> {
+  /** Path params for a dynamic `to` (e.g. `{ params: { id } }` for `/blog/:id`). */
+  params?: ParamsFor<TTo>;
+}
+
+export interface NavigateFn {
+  <TTo extends RegisteredRoutes>(
+    to: TTo | (string & {}),
+    options?: NavigateOptions<TTo>,
+  ): Promise<void>;
+}
+
+// ── Hook ───────────────────────────────────────────────────────────────────
+
+/**
+ * Returns a typed `navigate(to, { params })` for programmatic soft navigation —
+ * the imperative counterpart to `<Link>`. Mirrors `<Link>`'s `to`/`params` API:
+ * `to` autocompletes registered routes (after `bractjs codegen`) while still
+ * accepting any string, and `params` is typed per route.
+ *
+ * SSR-safe and safe outside a `ClientRouter`: with no NavigationContext it
+ * resolves to a no-op (same guard as `<Link>`), so it never throws during render.
+ *
+ * Note: navigation always pushes a history entry today; a `replace` option will
+ * follow once the underlying navigate contract supports it.
+ */
+export function useNavigate(): NavigateFn {
+  const navCtx = useContext(NavigationContext);
+  return useCallback<NavigateFn>(
+    (to, options) => {
+      const href = options?.params
+        ? buildPath(to as string, options.params as Record<string, string>)
+        : (to as string);
+      if (!navCtx) return Promise.resolve();
+      return navCtx.navigate(href);
+    },
+    [navCtx],
+  );
+}

package/src/client/hooks/useParams.ts

@@ -1,14 +1,25 @@
 import { useContext } from "react";
 import { RouterContext } from "../router.tsx";
 import { BractJSContext } from "../../shared/context.ts";
+import type { ParamsFor } from "../registry.ts";
 
 /**
- * Returns the current route's URL params (e.g. { id: "42" }).
- * Pass a RouteParams<T> generic for typed params: useParams<RouteParams<"/blog/:id">>()
+ * Returns the current route's URL params (e.g. `{ id: "42" }`).
+ *
+ * Pass the route pattern as a generic to type the result against your codegen'd
+ * routes: `useParams<"/blog/:id">()` → `{ id: string }`. The pattern is supplied
+ * by the caller because the framework can't infer the active route at the type
+ * level (React Router's `useParams` has the same limitation). An object generic
+ * — `useParams<{ id: string }>()` — also works for hand-typed shapes.
+ *
  * Works in both SSR and client contexts.
  */
-export function useParams<T extends Record<string, string> = Record<string, string>>(): T {
+// Overload 1: a route literal → params resolved from the registry.
+export function useParams<TTo extends string>(): ParamsFor<TTo>;
+// Overload 2: an explicit object shape (back-compat with the old generic form).
+export function useParams<T extends Record<string, string> = Record<string, string>>(): T;
+export function useParams(): Record<string, string> {
   const router = useContext(RouterContext);
   const bract = useContext(BractJSContext);
-  return (router?.params ?? bract?.params ?? {}) as T;
+  return router?.params ?? bract?.params ?? {};
 }

package/src/client/hooks/useSearchParams.ts

@@ -1,6 +1,7 @@
 import { useState, useCallback, useEffect, useRef, startTransition } from "react";
 import { NavigationContext } from "../router.tsx";
 import { useContext } from "react";
+import type { SearchFor } from "../registry.ts";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -17,13 +18,22 @@ export interface SearchParamsResult<T extends Record<string, string>> {
 // ── Hook ───────────────────────────────────────────────────────────────────
 
 /**
- * Reads and writes URL search params, typed per-route via generic T.
- * Triggers a loader re-run (soft-nav fetch) when params change.
+ * Reads and writes URL search params. Triggers a loader re-run (soft-nav fetch)
+ * when params change.
+ *
+ * Pass the route pattern as a generic to type the result against your codegen'd
+ * routes: `useSearchParams<"/posts">()`. Augment `RouteSearchParamsMap` to give a
+ * route a concrete shape (defaults to `Record<string, string>`). The pattern is
+ * supplied by the caller — the framework can't infer the active route at the type
+ * level. An object generic — `useSearchParams<{ page: string }>()` — also works.
  *
- * T is the route's SearchParams shape (e.g. { page: string; sort: string }).
  * This hook is SSR-safe: on the server window is absent, so it returns empty params.
  */
-export function useSearchParams<T extends Record<string, string> = Record<string, string>>(): SearchParamsResult<T> {
+// Overload 1: a route literal → search shape resolved from the registry.
+export function useSearchParams<TTo extends string>(): SearchParamsResult<SearchFor<TTo>>;
+// Overload 2: an explicit object shape (back-compat with the old generic form).
+export function useSearchParams<T extends Record<string, string> = Record<string, string>>(): SearchParamsResult<T>;
+export function useSearchParams(): SearchParamsResult<Record<string, string>> {
   const navCtx = useContext(NavigationContext);
 
   function readCurrent(): URLSearchParams {
@@ -66,8 +76,8 @@ export function useSearchParams<T extends Record<string, string> = Record<string
     }
   }, [navCtx]);
 
-  const getParam = useCallback(<K extends keyof T & string>(key: K): T[K] | null => {
-    return (searchParams.get(key) as T[K] | null);
+  const getParam = useCallback((key: string): string | null => {
+    return searchParams.get(key);
   }, [searchParams]);
 
   return { searchParams, getParam, setSearchParams };

package/src/client/registry.ts

@@ -0,0 +1,107 @@
+// Type-registration seam for end-to-end typed routing (TanStack-Router style).
+//
+// This file is RUNTIME-FREE — it contributes only types. The runtime helpers
+// (`<Link>`, `useNavigate`, `useParams`, `useSearchParams`) resolve their route
+// types from `Register` declared here.
+//
+// HOW IT WORKS
+// ------------
+// `Register` is an empty, augmentable interface. Running `bractjs codegen`
+// writes `app/route-types.gen.ts`, which augments it:
+//
+//   declare module "@bractjs/bractjs" {
+//     interface Register {
+//       routes: {
+//         routes: "/" | "/blog/:id";
+//         params: { "/blog/:id": { id: string } };
+//         search: RouteSearchParamsMap;
+//       };
+//     }
+//   }
+//
+// Once augmented, `<Link to="...">` autocompletes the app's routes and type-
+// checks `params`; `useNavigate`, `useParams`, `useSearchParams` follow suit.
+//
+// GRACEFUL FALLBACK
+// -----------------
+// Un-augmented (no codegen, or codegen not yet run), `Register` is `{}`, so the
+// `Register extends { routes: ... } ? ... : <loose>` conditionals below resolve
+// to the loose `string` / `Record<string, string>` types BractJS used before.
+// Existing apps therefore keep compiling unchanged — the typed surface only
+// activates after the generated augmentation lands.
+//
+// NOTE: this seam is mirrored verbatim in `types/index.d.ts` (the published
+// declaration surface). Keep the two in sync — a divergence silently disables
+// typed routing for either monorepo or published consumers.
+
+// ── The augmentable seam ─────────────────────────────────────────────────────
+
+/**
+ * Augmentable registration interface. Empty by default; `route-types.gen.ts`
+ * augments it with this app's `RouteRegistry`. See file header.
+ */
+export interface Register {}
+
+/** The shape the generated file plugs into `Register["routes"]`. */
+export interface RouteRegistry {
+  /** Union of all route patterns, colon-style — e.g. `"/" | "/blog/:id"`. */
+  routes: string;
+  /** Map of pattern → params object — e.g. `{ "/blog/:id": { id: string } }`. */
+  params: Record<string, Record<string, string>>;
+  /** Map of pattern → search-params object. */
+  search: Record<string, Record<string, string>>;
+}
+
+// ── Package-level customization maps (stable augmentation targets) ───────────
+//
+// Users type search params / context per route by augmenting THESE interfaces
+// on the package, e.g.:
+//
+//   declare module "@bractjs/bractjs" {
+//     interface RouteSearchParamsMap { "/posts": { page: string } }
+//   }
+//
+// The generated file seeds every route with a permissive default; user
+// augmentations merge on top.
+
+/** Per-route search-params shapes. Augment to type a route's search params. */
+export interface RouteSearchParamsMap {}
+
+/** Per-route context shapes. Augment to type a route's `context`. */
+export interface RouteContextMap {}
+
+// ── Resolution helpers (drive the runtime hooks/components) ──────────────────
+
+// NOTE: these conditionals deliberately do NOT use `infer R extends RouteRegistry`.
+// A constrained `infer` here silently fails to match the generated registry (its
+// `search` member is an empty interface, which trips the constraint check) and
+// falls back to the loose branch — defeating the whole feature. We instead infer
+// each member's shape directly. `RouteRegistry` remains the documented contract
+// the generated file targets.
+
+/**
+ * The app's route union when registered, else `string`. The fallback is what
+ * keeps un-codegen'd apps compiling: every `to` still accepts any string.
+ */
+export type RegisteredRoutes =
+  Register extends { routes: { routes: infer R } } ? R : string;
+
+/** Pattern → params map when registered, else a permissive map. */
+export type RegisteredParamsMap =
+  Register extends { routes: { params: infer P } } ? P : Record<string, Record<string, string>>;
+
+/** Pattern → search map when registered, else a permissive map. */
+export type RegisteredSearchMap =
+  Register extends { routes: { search: infer S } } ? S : Record<string, Record<string, string>>;
+
+/** Params object for a specific route literal (`{}` for static routes). */
+export type ParamsFor<TTo> =
+  TTo extends keyof RegisteredParamsMap ? RegisteredParamsMap[TTo] : Record<string, string>;
+
+/** Search-params object for a specific route literal. */
+export type SearchFor<TTo> =
+  TTo extends keyof RegisteredSearchMap ? RegisteredSearchMap[TTo] : Record<string, string>;
+
+/** Whether a route literal carries any path params. Reserved for a future strict `<Link>` mode. */
+export type HasParams<TTo> =
+  keyof ParamsFor<TTo> extends never ? false : true;

package/src/codegen/route-codegen.ts

@@ -78,29 +78,32 @@ const HEADER =
   "\n" +
   "/* eslint-disable */\n";
 
+// `RouteSearchParamsMap` / `RouteContextMap` are owned by the package
+// (`@bractjs/bractjs`) so users have a single stable module to augment. We do
+// NOT seed per-route keys here: seeding `"/posts": Record<string,string>` would
+// conflict with a user augmentation declaring `"/posts": { page: string }`
+// (duplicate-property error). Instead `SearchParams<T>` / `Context<T>` fall back
+// to the permissive default for any route the user hasn't augmented.
 function searchParamsTypeLines(routes: Array<{ pattern: string }>): string {
-  // Route files may declare `export type SearchParams = { page: string }`.
-  // We emit a mapped type that falls back to Record<string,string> per route.
-  // Users augment via module augmentation or via their route file's export.
   if (routes.length === 0) {
     return "export type SearchParams<_T extends AppRoutes> = Record<string, string>;";
   }
   const branches = routes
     .map((r) => {
       assertSafePattern(r.pattern);
-      return "  T extends " + JSON.stringify(r.pattern) + " ? RouteSearchParamsMap[" + JSON.stringify(r.pattern) + "] :";
+      const key = JSON.stringify(r.pattern);
+      // Use `extends Record<K, infer V>` rather than `keyof` + index access:
+      // RouteSearchParamsMap may be `{}` (no user augmentation), and indexing an
+      // empty interface — even inside a `K extends keyof M` guard — trips
+      // TS2538 "cannot be used as an index type". The Record-infer form resolves
+      // V only when the route is augmented, and falls back otherwise.
+      return "  T extends " + key +
+        " ? (RouteSearchParamsMap extends Record<" + key + ", infer V> ? V : Record<string, string>) :";
     })
     .join("\n");
-  const mapEntries = routes
-    .map((r) => "  " + JSON.stringify(r.pattern) + ": Record<string, string>;")
-    .join("\n");
   return [
-    "// Augment RouteSearchParamsMap to type search params per route:",
-    "// declare module 'bractjs' { interface RouteSearchParamsMap { '/blog': { page: string } } }",
-    "export interface RouteSearchParamsMap {",
-    mapEntries,
-    "}",
-    "",
+    "// Augment RouteSearchParamsMap (on the package) to type a route's search params:",
+    "//   declare module \"@bractjs/bractjs\" { interface RouteSearchParamsMap { \"/blog\": { page: string } } }",
     "export type SearchParams<T extends AppRoutes> =",
     branches,
     "  Record<string, string>;",
@@ -114,25 +117,51 @@ function contextTypeLines(routes: Array<{ pattern: string }>): string {
   const branches = routes
     .map((r) => {
       assertSafePattern(r.pattern);
-      return "  T extends " + JSON.stringify(r.pattern) + " ? RouteContextMap[" + JSON.stringify(r.pattern) + "] :";
+      const key = JSON.stringify(r.pattern);
+      // See SearchParams above for why this uses `extends Record<K, infer V>`.
+      return "  T extends " + key +
+        " ? (RouteContextMap extends Record<" + key + ", infer V> ? V : Record<string, unknown>) :";
     })
     .join("\n");
-  const mapEntries = routes
-    .map((r) => "  " + JSON.stringify(r.pattern) + ": Record<string, unknown>;")
-    .join("\n");
   return [
-    "// Augment RouteContextMap to type context per route:",
-    "// declare module 'bractjs' { interface RouteContextMap { '/blog': { user: User } } }",
-    "export interface RouteContextMap {",
-    mapEntries,
-    "}",
-    "",
+    "// Augment RouteContextMap (on the package) to type a route's context:",
+    "//   declare module \"@bractjs/bractjs\" { interface RouteContextMap { \"/blog\": { user: User } } }",
     "export type Context<T extends AppRoutes> =",
     branches,
     "  Record<string, unknown>;",
   ].join("\n");
 }
 
+// The `Register` augmentation: this is what wires the app's routes into the
+// package's runtime helpers (<Link>, useNavigate, useParams, useSearchParams).
+function registerAugmentationLines(routes: Array<{ pattern: string; params: string[] }>): string {
+  const paramEntries = routes
+    .map((r) => {
+      assertSafePattern(r.pattern);
+      r.params.forEach(assertSafeParam);
+      const shape = r.params.length === 0
+        ? "{}"
+        : "{ " + r.params.map((p) => p + ": string").join("; ") + " }";
+      return "      " + JSON.stringify(r.pattern) + ": " + shape + ";";
+    })
+    .join("\n");
+  return [
+    "// Registers this app's routes with BractJS. After this augmentation, <Link>,",
+    "// useNavigate, useParams, and useSearchParams are type-safe against AppRoutes.",
+    "declare module \"@bractjs/bractjs\" {",
+    "  interface Register {",
+    "    routes: {",
+    "      routes: AppRoutes;",
+    "      params: {",
+    paramEntries,
+    "      };",
+    "      search: RouteSearchParamsMap;",
+    "    };",
+    "  }",
+    "}",
+  ].join("\n");
+}
+
 export async function generateRouteTypes(appDir: string): Promise<string> {
   const routeFiles = await scanRoutes(appDir);
   const routes = routeFiles.map((r) => ({
@@ -149,8 +178,15 @@ export async function generateRouteTypes(appDir: string): Promise<string> {
 
   const builderEntries = routes.map((r) => builderEntry(r.pattern, r.params)).join("\n");
 
+  // `RouteSearchParamsMap` / `RouteContextMap` are imported from the package so
+  // the local `SearchParams<T>` / `Context<T>` reference the same interfaces the
+  // user augments via `declare module "@bractjs/bractjs"`.
+  const IMPORTS = 'import type { RouteSearchParamsMap, RouteContextMap } from "@bractjs/bractjs";';
+
   return [
     HEADER,
+    IMPORTS,
+    "",
     "export type AppRoutes =",
     union + ";",
     "",
@@ -175,6 +211,9 @@ export async function generateRouteTypes(appDir: string): Promise<string> {
     builderEntries,
     "} as const;",
     "",
+    // No routes → AppRoutes is `never`; nothing to register.
+    routes.length > 0 ? registerAugmentationLines(routes) : "",
+    "",
   ].join("\n");
 }
 

package/src/index.ts

@@ -108,6 +108,8 @@ export { useLoaderData } from "./client/hooks/useLoaderData.ts";
 export { useActionData } from "./client/hooks/useActionData.ts";
 export { useParams } from "./client/hooks/useParams.ts";
 export { useNavigation } from "./client/hooks/useNavigation.ts";
+export { useNavigate } from "./client/hooks/useNavigate.ts";
+export type { NavigateFn, NavigateOptions } from "./client/hooks/useNavigate.ts";
 export { useFetcher } from "./client/hooks/useFetcher.ts";
 export { useSearchParams } from "./client/hooks/useSearchParams.ts";
 export type { SearchParamsResult } from "./client/hooks/useSearchParams.ts";
@@ -115,6 +117,21 @@ export { useBlocker } from "./client/hooks/useBlocker.ts";
 export { useLocale } from "./client/hooks/useLocale.ts";
 export { useLocalizedLink } from "./client/hooks/useLocalizedLink.ts";
 
+// Typed-routing registration seam. Augment `Register` (done by `bractjs codegen`
+// in app/route-types.gen.ts) to make <Link>, useNavigate, useParams, and
+// useSearchParams type-safe. Augment RouteSearchParamsMap / RouteContextMap to
+// type a route's search params / context.
+export type {
+  Register,
+  RouteRegistry,
+  RegisteredRoutes,
+  ParamsFor,
+  SearchFor,
+  RouteSearchParamsMap,
+  RouteContextMap,
+} from "./client/registry.ts";
+export { buildPath } from "./client/build-path.ts";
+
 // i18n utilities (server-side)
 export { wrapRoutesWithLocale, stripLocale, localizedDataPath } from "./server/i18n.ts";
 export type { I18nConfig } from "./server/serve.ts";

package/types/index.d.ts

@@ -129,13 +129,49 @@ export declare function validate<T>(
   input: FormData | Record<string, unknown>,
 ): Promise<T>;
 
+// ── Typed-routing registration seam ───────────────────────────────────────
+// Mirror of src/client/registry.ts. Augment `Register` (done by `bractjs codegen`
+// in app/route-types.gen.ts) to make <Link>/useNavigate/useParams/useSearchParams
+// type-safe. Un-augmented, everything falls back to loose `string` / Record so
+// apps that never run codegen keep compiling. Keep in sync with registry.ts.
+export interface Register {}
+export interface RouteRegistry {
+  routes: string;
+  params: Record<string, Record<string, string>>;
+  search: Record<string, Record<string, string>>;
+}
+export interface RouteSearchParamsMap {}
+export interface RouteContextMap {}
+// Infer each member directly (NOT `infer R extends RouteRegistry` — a constrained
+// infer fails to match the generated registry and falls back to loose). Keep in
+// sync with src/client/registry.ts.
+export type RegisteredRoutes =
+  Register extends { routes: { routes: infer R } } ? R : string;
+export type RegisteredParamsMap =
+  Register extends { routes: { params: infer P } } ? P : Record<string, Record<string, string>>;
+export type RegisteredSearchMap =
+  Register extends { routes: { search: infer S } } ? S : Record<string, Record<string, string>>;
+export type ParamsFor<TTo> =
+  TTo extends keyof RegisteredParamsMap ? RegisteredParamsMap[TTo] : Record<string, string>;
+export type SearchFor<TTo> =
+  TTo extends keyof RegisteredSearchMap ? RegisteredSearchMap[TTo] : Record<string, string>;
+export declare function buildPath(pattern: string, params: Record<string, string | number>): string;
+
 // ── Client components ─────────────────────────────────────────────────────
 export declare function Scripts(): null;
 export declare function LiveReload(): ReactNode;
 export declare function Outlet(): ReactNode;
 
-export interface LinkProps { to: string; prefetch?: "hover" | "none"; viewTransition?: boolean; children?: ReactNode; className?: string; [key: string]: unknown; }
-export declare function Link(props: LinkProps): ReactNode;
+export type LinkProps<TTo extends RegisteredRoutes = RegisteredRoutes> = {
+  to: TTo | (string & {});
+  params?: ParamsFor<TTo>;
+  prefetch?: "hover" | "none";
+  viewTransition?: boolean;
+  children?: ReactNode;
+  className?: string;
+  [key: string]: unknown;
+};
+export declare function Link<TTo extends RegisteredRoutes = RegisteredRoutes>(props: LinkProps<TTo>): ReactNode;
 
 export interface FormProps { method?: "post" | "put" | "delete"; action?: string; children?: ReactNode; [key: string]: unknown; }
 export declare function Form(props: FormProps): ReactNode;
@@ -163,9 +199,16 @@ export declare function Image(props: ImageProps): ReactNode;
 // ── Client hooks ──────────────────────────────────────────────────────────
 export declare function useLoaderData<T = unknown>(): T;
 export declare function useActionData<T = unknown>(): T | null;
-export declare function useParams(): Record<string, string>;
+export declare function useParams<TTo extends string>(): ParamsFor<TTo>;
+export declare function useParams<T extends Record<string, string> = Record<string, string>>(): T;
 export type NavigationState = "idle" | "loading" | "submitting";
 export declare function useNavigation(): { state: NavigationState };
+
+export interface NavigateOptions<TTo extends RegisteredRoutes = RegisteredRoutes> { params?: ParamsFor<TTo>; }
+export interface NavigateFn {
+  <TTo extends RegisteredRoutes>(to: TTo | (string & {}), options?: NavigateOptions<TTo>): Promise<void>;
+}
+export declare function useNavigate(): NavigateFn;
 export interface FetcherResult {
   data: unknown;
   state: NavigationState;
@@ -184,6 +227,7 @@ export interface SearchParamsResult<T extends Record<string, string> = Record<st
   getParam<K extends keyof T & string>(key: K): T[K] | null;
   setSearchParams(updater: Record<string, string> | ((prev: URLSearchParams) => URLSearchParams)): void;
 }
+export declare function useSearchParams<TTo extends string>(): SearchParamsResult<SearchFor<TTo>>;
 export declare function useSearchParams<T extends Record<string, string> = Record<string, string>>(): SearchParamsResult<T>;
 
 // ── Typed route context ───────────────────────────────────────────────────