diff --git a/packages/esroute/README.md b/packages/esroute/README.md
index 32110ab..54e5d97 100644
--- a/packages/esroute/README.md
+++ b/packages/esroute/README.md
@@ -125,24 +125,36 @@ router.go("/foo"); // ✓
 router.go("/baz"); // TS Error: Argument of type '"/baz"' is not assignable
 ```
 
-#### Typed state
+#### Typed state and search
 
-Route handlers can declare the history state type they require by typing the `NavOpts` parameter. When navigating to such a route, TypeScript enforces that you provide the correct state — and inside the handler, `state` is typed directly without null checks:
+Route handlers can declare the history state and search params they require with `route()`. When navigating to such a route, TypeScript enforces that you provide the correct metadata:
 
 ```ts
 const routes = {
-  profile: (navOpts: NavOpts<{ userId: string }>) =>
-    loadProfile(navOpts.state.userId),
+  profile: route<{
+    state: { userId: string };
+    search: { tab: string };
+  }>(({ state, search }) => loadProfile(state.userId, search.tab)),
 } satisfies Routes<string>;
 
 const router = createRouter({ routes });
 
-router.go("/profile");                                  // TS Error: state required
-router.go("/profile", { state: { userId: "123" } });    // ✓
-router.go("/profile", { state: { userId: 42 } });       // TS Error: number is not string
+router.go("/profile"); // TS Error: state and search required
+router.go("/profile", {
+  state: { userId: "123" },
+  search: { tab: "settings" },
+}); // ✓
+router.go("/profile", { state: { userId: 42 } }); // TS Error
 ```
 
-State defaults to `null` when not provided, consistent with the History API. Routes without an explicit state type leave it as `null`.
+The equivalent explicit handler type is:
+
+```ts
+profile: ({ state, search }: NavOpts<{ userId: string }, { tab: string }>) =>
+  loadProfile(state.userId, search.tab),
+```
+
+At runtime, state defaults to `null` when not provided, consistent with the History API.
 
 ### 🏎 Fast startup and runtime
 
diff --git a/packages/esroute/src/nav-opts.ts b/packages/esroute/src/nav-opts.ts
index f6f2f51..6740e41 100644
--- a/packages/esroute/src/nav-opts.ts
+++ b/packages/esroute/src/nav-opts.ts
@@ -1,8 +1,11 @@
 export type PathOrHref = string | string[];
 
-export interface NavMeta<S = any> {
+export interface NavMeta<
+  S = never,
+  Search extends Record<string, string> = Record<never, never>
+> {
   /** The search query object. */
-  search?: Record<string, string>;
+  search?: Search;
   /** The state to push. */
   state?: S | null;
   /** The location hash. */
@@ -19,7 +22,10 @@ export interface NavMeta<S = any> {
   skipRender?: boolean;
 }
 
-export type StrictNavMeta<S = any> = NavMeta<S> &
+export type StrictNavMeta<
+  S = never,
+  Search extends Record<string, string> = Record<never, never>
+> = NavMeta<S, Search> &
   (
     | {
         path: string[];
@@ -29,20 +35,26 @@ export type StrictNavMeta<S = any> = NavMeta<S> &
       }
   );
 
-export class NavOpts<S = null> implements NavMeta<S> {
+export class NavOpts<
+  S = never,
+  Search extends Record<string, string> = Record<never, never>
+> implements NavMeta<S, Search> {
   readonly state: S;
   readonly params: string[] = [];
   readonly hash?: string;
   readonly replace?: boolean;
   readonly skipRender?: boolean;
   readonly path: string[];
-  readonly search: Record<string, string>;
+  readonly search: Search;
   readonly pop?: boolean;
   private _h?: string;
 
-  constructor(target: StrictNavMeta<S>);
-  constructor(target: PathOrHref, opts?: NavMeta<S>);
-  constructor(target: PathOrHref | StrictNavMeta<S>, opts: NavMeta<S> = {}) {
+  constructor(target: StrictNavMeta<S, Search>);
+  constructor(target: PathOrHref, opts?: NavMeta<S, Search>);
+  constructor(
+    target: PathOrHref | StrictNavMeta<S, Search>,
+    opts: NavMeta<S, Search> = {}
+  ) {
     let { path, href, hash, pop, replace, search, state, skipRender } =
       typeof target === "string" || Array.isArray(target) ? opts : target;
     if (path) this.path = path;
@@ -57,7 +69,7 @@ export class NavOpts<S = null> implements NavMeta<S> {
       if (searchString)
         this.search = Object.fromEntries(
           new URLSearchParams(searchString).entries()
-        );
+        ) as Search;
       if (parsedHash) this.hash = parsedHash;
     } else this.path = target as string[];
     if (hash != null) this.hash = hash;
@@ -66,7 +78,7 @@ export class NavOpts<S = null> implements NavMeta<S> {
     this.state = (state ?? null) as S;
     if (replace != null) this.replace = replace;
     if (skipRender != null) this.skipRender = skipRender;
-    this.search ??= {};
+    this.search ??= {} as Search;
   }
 
   get href() {
@@ -79,8 +91,8 @@ export class NavOpts<S = null> implements NavMeta<S> {
   }
 
   get go() {
-    return (path: PathOrHref, opts: NavMeta<S> = {}) =>
-      new NavOpts<S>(path, {
+    return (path: PathOrHref, opts: NavMeta<S, Search> = {}) =>
+      new NavOpts<S, Search>(path, {
         search: opts.search,
         state: opts.state,
         replace: opts.replace ?? this.replace,
diff --git a/packages/esroute/src/route-resolver.ts b/packages/esroute/src/route-resolver.ts
index 95e7b08..1ac7fe8 100644
--- a/packages/esroute/src/route-resolver.ts
+++ b/packages/esroute/src/route-resolver.ts
@@ -1,28 +1,40 @@
 import { NavOpts } from "./nav-opts.js";
 import { Resolve, Routes } from "./routes.js";
 
-export interface Resolved<T, S = any> {
+export interface Resolved<
+  T,
+  S = never,
+  Search extends Record<string, string> = Record<never, never>
+> {
   /** The resolved value of the route. */
   value: T;
   /** The final navigation options after all redirecting. */
-  opts: NavOpts<S>;
+  opts: NavOpts<S, Search>;
 }
 
-export type RouteResolver<T, S = any> = (
-  routes: Routes<T, S>,
-  opts: NavOpts<S>,
-  notFound: Resolve<T, S>
-) => Promise<Resolved<T, S>>;
+export type RouteResolver<
+  T,
+  S = never,
+  Search extends Record<string, string> = Record<never, never>
+> = (
+  routes: Routes<T, S, Search>,
+  opts: NavOpts<S, Search>,
+  notFound: Resolve<T, S, Search>
+) => Promise<Resolved<T, S, Search>>;
 
 const MAX_REDIRECTS = 10;
 
-export const resolve = async <T, S = any>(
-  routes: Routes<T, S>,
-  opts: NavOpts<S>,
-  notFound: Resolve<T, S>
-): Promise<Resolved<T, S>> => {
-  let value: NavOpts<S> | T = opts;
-  const navPath: NavOpts<S>[] = [];
+export const resolve = async <
+  T,
+  S = never,
+  Search extends Record<string, string> = Record<never, never>
+>(
+  routes: Routes<T, S, Search>,
+  opts: NavOpts<S, Search>,
+  notFound: Resolve<T, S, Search>
+): Promise<Resolved<T, S, Search>> => {
+  let value: NavOpts<S, Search> | T = opts;
+  const navPath: NavOpts<S, Search>[] = [];
   while (value instanceof NavOpts && navPath.length <= MAX_REDIRECTS) {
     opts = value;
     navPath.push(opts);
@@ -44,18 +56,25 @@ export const resolve = async <T, S = any>(
 };
 
 const getResolves = async (
-  root: Routes,
-  opts: NavOpts<any>
-): Promise<Resolve[] | null> => {
+  root: Routes<any, any, any>,
+  opts: NavOpts<any, any>
+): Promise<Resolve<any, any, any>[] | null> => {
   const { path, params } = opts;
-  const resolves: Resolve[] = [];
-  let routes: Routes | Resolve | null | undefined = root;
+  const resolves: Resolve<any, any, any>[] = [];
+  let routes:
+    | Routes<any, any, any>
+    | Resolve<any, any, any>
+    | null
+    | undefined = root;
   for (let i = 0; i < path.length; i++) {
     const part = path[i];
     if (!routes || typeof routes === "function") return null;
     const redirect = await checkGuard(routes, opts);
     if (redirect) return [() => redirect];
-    const virtual: Routes | Resolve | undefined = routes[""];
+    const virtual:
+      | Routes<any, any, any>
+      | Resolve<any, any, any>
+      | undefined = routes[""];
     if (typeof virtual === "function") resolves.unshift(virtual);
     if (part in routes) routes = routes[part];
     else if ("*" in routes) {
@@ -80,7 +99,10 @@ const getResolves = async (
   return null;
 };
 
-const checkGuard = async (routes: Routes, opts: NavOpts<any>) => {
+const checkGuard = async (
+  routes: Routes<any, any, any>,
+  opts: NavOpts<any, any>
+) => {
   if (typeof routes["?"] === "function") {
     const guardResult = await routes["?"](opts);
     if (guardResult instanceof NavOpts) return guardResult;
diff --git a/packages/esroute/src/router.spec.ts b/packages/esroute/src/router.spec.ts
index 9dee536..bd4a922 100644
--- a/packages/esroute/src/router.spec.ts
+++ b/packages/esroute/src/router.spec.ts
@@ -1,6 +1,6 @@
 import { beforeEach, describe, expect, it, vi, type Mock } from "vitest";
 import { NavOpts } from "./nav-opts.js";
-import { Routes } from "./routes.js";
+import { route, Routes } from "./routes.js";
 import { createRouter } from "./router.js";
 
 // Define routes with proper typing to verify RoutePaths inference
@@ -10,9 +10,15 @@ const routes = {
   foo: () => "foo",
   fail: () => Promise.reject(new Error("test")),
   bar: () => "bar",
+  "some-route": route<{
+    state: { foo: number };
+    search: { bar: string };
+  }>(({ state: { foo }, search: { bar } }) => `${foo}:${bar}`),
+  baz: ({ go }) => go("/non-existing"), // should fail
   x: {
     "": ({ state }: NavOpts<{ a: boolean }>) => (state.a ? "b" : "c"),
-    y: () => "x",
+    y: ({ state }: NavOpts<number>) => state.toString(),
+    "*": ({ state }: NavOpts<string>) => state,
   },
 } satisfies Routes<string>;
 
@@ -130,7 +136,7 @@ describe("Router", () => {
     });
 
     it("should replace the state by default, if target is a mapping funciton", async () => {
-      await router.go("/foo", { search: { a: "b" } });
+      await router.go(["foo"], { search: { a: "b" } });
       await router.go(() => ({ search: { a: "c" } }));
 
       expect(history.replaceState).toHaveBeenCalledWith(null, "", "/foo?a=c");
@@ -229,12 +235,39 @@ describe("Router", () => {
       // /x requires state: { a: boolean } — omitting state is a type error (see go() test above)
       // Providing the required state is valid:
       await router.go("/x", { state: { a: true } });
+      await router.go("/x/y", { state: 32 });
+      await router.go("/x/ntesr", { state: "4" });
     });
 
-    it("should not allow state when the route handler declares no state type", async () => {
+    it("should type route() state and search contracts", async () => {
       router.init();
-      // @ts-expect-error - /foo has no state type, passing state should be a type error
-      await router.go("/foo", { state: { a: true } });
+
+      await router.go("/some-route", {
+        state: { foo: 1 },
+        search: { bar: "baz" },
+      });
+
+      if (false) {
+        // @ts-expect-error - search is required by route()
+        await router.go("/some-route", { state: { foo: 1 } });
+        // @ts-expect-error - state is required by route()
+        await router.go("/some-route", { search: { bar: "baz" } });
+        // @ts-expect-error - search.bar must be a string
+        await router.go("/some-route", {
+          state: { foo: 1 },
+          search: { bar: 1 },
+        });
+      }
+    });
+
+    it("should not allow state or search when the route handler declares no meta type", async () => {
+      router.init();
+      if (false) {
+        // @ts-expect-error - /foo has no state type, passing state should be a type error
+        await router.go("/foo", { state: { a: true } });
+        // @ts-expect-error - /foo has no search type, passing search should be a type error
+        await router.go("/foo", { search: { a: "b" } });
+      }
     });
   });
 });
diff --git a/packages/esroute/src/router.ts b/packages/esroute/src/router.ts
index c53bdb3..82b194d 100644
--- a/packages/esroute/src/router.ts
+++ b/packages/esroute/src/router.ts
@@ -6,23 +6,32 @@ import {
   RoutePaths,
   RawRoutes,
   HandlerFor,
-  StateOf,
-  NeedsState,
+  NavMetaFor,
+  NeedsNavMeta,
 } from "./routes.js";
 
-export type OnResolveListener<T, S = any> = (resolved: Resolved<T, S>) => void;
-export interface Router<T = any, S = any, R extends RawRoutes = RawRoutes> {
+export type OnResolveListener<
+  T,
+  S = never,
+  Search extends Record<string, string> = Record<string, string>
+> = (resolved: Resolved<T, S, Search>) => void;
+export interface Router<
+  T = any,
+  S = never,
+  R extends RawRoutes = RawRoutes,
+  Search extends Record<string, string> = Record<string, string>
+> {
   /**
    * The routes configuration.
    * You may modify this object to change the routes.
    * Be sure to call `router.init()` after the current route is configured.
    */
-  routes: Routes<T, S>;
+  routes: Routes<T, S, Search>;
   /**
    * The current resolved route.
    * It is updated after each route resolution.
    */
-  readonly current: NavOpts<S>;
+  readonly current: NavOpts<S, Search>;
   /**
    * Triggers a navigation.
    * You can modify the navigation options by passing in a second argument.
@@ -35,22 +44,25 @@ export interface Router<T = any, S = any, R extends RawRoutes = RawRoutes> {
    * @param opts The navigation metadata.
    */
   go(
-    target: number | StrictNavMeta<S> | ((prev: NavOpts<S>) => NavMeta<S>)
+    target:
+      | number
+      | StrictNavMeta<S, Search>
+      | ((prev: NavOpts<S, Search>) => NavMeta<S, Search>)
   ): Promise<void>;
-  /** Navigate to a typed route path, enforcing the required state type for that route. */
+  /** Navigate to a typed route path, enforcing the required meta for that route. */
   go<P extends RoutePaths<R>>(
     target: P,
-    ...opts: NeedsState<HandlerFor<R, P>> extends true
-      ? [opts: NavMeta<StateOf<HandlerFor<R, P>>> & { state: StateOf<HandlerFor<R, P>> }]
-      : [opts?: Omit<NavMeta<StateOf<HandlerFor<R, P>>>, "state">]
+    ...opts: NeedsNavMeta<HandlerFor<R, P>> extends true
+      ? [opts: NavMetaFor<HandlerFor<R, P>>]
+      : [opts?: NavMetaFor<HandlerFor<R, P>>]
   ): Promise<void>;
-  go(target: string[], opts?: NavMeta<S>): Promise<void>;
+  go(target: string[], opts?: NavMeta<S, Search>): Promise<void>;
   /**
    * Use this to listen for route changes.
    * Returns an unsubscribe function.
    * @param listener The listener that receives a Resolved object.
    */
-  onResolve(listener: OnResolveListener<T, S>): () => void;
+  onResolve(listener: OnResolveListener<T, S, Search>): () => void;
   /**
    * Initializes the router: Starts listening for events, resolves the current
    * route and calls the `onResolve` listeners.
@@ -63,7 +75,7 @@ export interface Router<T = any, S = any, R extends RawRoutes = RawRoutes> {
   /**
    * Use this to wait for the current navigation to complete.
    */
-  resolution?: Promise<Resolved<T, S>>;
+  resolution?: Promise<Resolved<T, S, Search>>;
   /**
    * Use this to render the current route (history and location).
    * @param defer A function that defers rendering and can be used to trigger multiple successive
@@ -72,17 +84,22 @@ export interface Router<T = any, S = any, R extends RawRoutes = RawRoutes> {
   render(defer?: () => Promise<void>): Promise<void>;
 }
 
-export interface RouterConf<T = any, S = any, R extends RawRoutes = RawRoutes> {
+export interface RouterConf<
+  T = any,
+  S = never,
+  R extends RawRoutes = RawRoutes,
+  Search extends Record<string, string> = Record<string, string>
+> {
   /**
    * The routes configuration. You can modify this object later.
    * Make sure, the current route is in place before you call `router.init()`.
    */
-  routes?: R & Routes<T, S>;
+  routes?: R & Routes<T, S, Search>;
   /**
    * A fallback resolve funuction to use, if a route could not be found.
    * By default it redirects to the root path '/'.
    */
-  notFound?: Resolve<T, S>;
+  notFound?: Resolve<T, S, Search>;
   /**
    * Whether the click handler for anchor elements shall not be installed.
    * This might make sense, if you want to take more control over how anchor
@@ -92,22 +109,27 @@ export interface RouterConf<T = any, S = any, R extends RawRoutes = RawRoutes> {
   /**
    * A callback that is invoked whenever a route is resolved.
    */
-  onResolve?: OnResolveListener<T, S>;
+  onResolve?: OnResolveListener<T, S, Search>;
 }
 
-export const createRouter = <T = any, S = any, R extends RawRoutes = RawRoutes>({
-  routes = {} as R & Routes<T, S>,
-  notFound = ({ go }: NavOpts<S>) => go([]),
+export const createRouter = <
+  T = any,
+  S = never,
+  R extends RawRoutes = RawRoutes,
+  Search extends Record<string, string> = Record<string, string>
+>({
+  routes = {} as R & Routes<T, S, Search>,
+  notFound = ({ go }: NavOpts<S, Search>) => go([]),
   noClick = false,
   onResolve,
-}: RouterConf<T, S, R> = {}): Router<T, S, R> => {
-  let _current: Resolved<T, S>;
-  const _listeners = new Set<OnResolveListener<T, S>>(
+}: RouterConf<T, S, R, Search> = {}): Router<T, S, R, Search> => {
+  let _current: Resolved<T, S, Search>;
+  const _listeners = new Set<OnResolveListener<T, S, Search>>(
     onResolve ? [onResolve] : []
   );
-  let resolution: Promise<Resolved<T, S>>;
+  let resolution: Promise<Resolved<T, S, Search>>;
   let skipRender = false;
-  const r: Router<T, S, R> = {
+  const r: Router<T, S, R, Search> = {
     routes,
     get current() {
       return _current.opts;
@@ -127,11 +149,11 @@ export const createRouter = <T = any, S = any, R extends RawRoutes = RawRoutes>(
     async go(
       target:
         | number
-        | StrictNavMeta<S>
-        | ((prev: NavOpts<S>) => NavMeta<S>)
+        | StrictNavMeta<S, Search>
+        | ((prev: NavOpts<S, Search>) => NavMeta<S, Search>)
         | RoutePaths<R>
         | PathOrHref,
-      opts?: NavMeta<any>
+      opts?: NavMeta<any, any>
     ): Promise<void> {
       // Serialize all navigaton requests
       const prevRes = await this.resolution;
@@ -163,13 +185,13 @@ export const createRouter = <T = any, S = any, R extends RawRoutes = RawRoutes>(
         resolvedTarget instanceof NavOpts
           ? resolvedTarget
           : typeof resolvedTarget === "string" || Array.isArray(resolvedTarget)
-          ? new NavOpts<S>(resolvedTarget as PathOrHref, opts)
-          : new NavOpts<S>(resolvedTarget as StrictNavMeta<S>);
+          ? new NavOpts<S, Search>(resolvedTarget as PathOrHref, opts)
+          : new NavOpts<S, Search>(resolvedTarget as StrictNavMeta<S, Search>);
       if (navOpts.skipRender || skipRender) return updateState(navOpts);
       const res = await applyResolution(resolve(r.routes, navOpts, notFound));
       updateState(res.opts);
     },
-    onResolve(listener: OnResolveListener<T, S>) {
+    onResolve(listener: OnResolveListener<T, S, Search>) {
       _listeners.add(listener);
       if (_current) listener(_current);
       return () => _listeners.delete(listener);
@@ -220,7 +242,7 @@ export const createRouter = <T = any, S = any, R extends RawRoutes = RawRoutes>(
   const resolveCurrent = async (e?: PopStateEvent) => {
     const { href, origin } = window.location;
 
-    const initialOpts = new NavOpts<S>(href.substring(origin.length), {
+    const initialOpts = new NavOpts<S, Search>(href.substring(origin.length), {
       state: e ? e.state : history.state,
       pop: !!e,
     });
@@ -230,7 +252,7 @@ export const createRouter = <T = any, S = any, R extends RawRoutes = RawRoutes>(
 
     if (opts !== initialOpts) {
       updateState(
-        new NavOpts<S>(opts.path, {
+        new NavOpts<S, Search>(opts.path, {
           replace: true,
           search: opts.search,
           state: opts.state,
@@ -240,7 +262,7 @@ export const createRouter = <T = any, S = any, R extends RawRoutes = RawRoutes>(
     }
   };
 
-  const applyResolution = async (res: Promise<Resolved<T, S>>) => {
+  const applyResolution = async (res: Promise<Resolved<T, S, Search>>) => {
     resolution = res;
     try {
       const resolved = await res;
@@ -252,7 +274,7 @@ export const createRouter = <T = any, S = any, R extends RawRoutes = RawRoutes>(
     }
   };
 
-  const updateState = ({ state, replace, href }: NavOpts<S>) => {
+  const updateState = ({ state, replace, href }: NavOpts<S, Search>) => {
     if (replace) history.replaceState(state, "", href);
     else history.pushState(state, "", href);
   };
diff --git a/packages/esroute/src/routes.ts b/packages/esroute/src/routes.ts
index f9822a7..fff8416 100644
--- a/packages/esroute/src/routes.ts
+++ b/packages/esroute/src/routes.ts
@@ -1,17 +1,70 @@
-import { NavOpts } from "./nav-opts.js";
+import { NavMeta, NavOpts } from "./nav-opts.js";
 
 export type RawRoutes = {
   [k: string]: RawRoutes | ((...args: any[]) => any);
 };
 
-export type Resolve<T = any, S = any> = (
-  navOpts: NavOpts<S>,
+export interface RouteContract {
+  state?: any;
+  search?: Record<string, string>;
+}
+
+declare const routeContract: unique symbol;
+
+type ContractState<C> = C extends { state?: infer S } ? S : never;
+type ContractSearch<C> = C extends {
+  search?: infer Search extends Record<string, string>;
+}
+  ? Search
+  : Record<never, never>;
+
+type HasContract<F> = typeof routeContract extends keyof F ? true : false;
+type ContractOf<F> = F extends { readonly [routeContract]?: infer C }
+  ? C
+  : never;
+type HasContractState<F> = HasContract<F> extends true
+  ? "state" extends keyof ContractOf<F>
+    ? true
+    : false
+  : false;
+type HasContractSearch<F> = HasContract<F> extends true
+  ? "search" extends keyof ContractOf<F>
+    ? true
+    : false
+  : false;
+type FirstArg<F> = F extends (...args: infer Args) => any
+  ? Args extends [infer First, ...any[]]
+    ? First
+    : never
+  : never;
+
+export type Resolve<
+  T = any,
+  S = never,
+  Search extends Record<string, string> = Record<never, never>
+> = (
+  navOpts: NavOpts<S, Search>,
   next?: T
-) => T | NavOpts<S> | Promise<T | NavOpts<S>>;
+) => T | NavOpts<S, Search> | Promise<T | NavOpts<S, Search>>;
+
+export type Route<
+  T = any,
+  C extends RouteContract = RouteContract
+> = Resolve<T, ContractState<C>, ContractSearch<C>> & {
+  readonly [routeContract]?: C;
+};
 
-export interface Routes<T = any, S = any> {
-  "?"?: Resolve<T, S>;
-  [k: string]: Routes<T, S> | Resolve<T, S> | undefined;
+export const route = <C extends RouteContract = {}, T = any>(
+  resolve: Resolve<T, ContractState<C>, ContractSearch<C>>
+): Route<T, C> => resolve as Route<T, C>;
+
+export interface Routes<
+  T = any,
+  S = never,
+  Search extends Record<string, string> = Record<never, never>
+> {
+  "?"?: Resolve<T, S, Search>;
+  [k: string]: Routes<T, any, any> | Resolve<T, any, any> | undefined;
 }
 
 // Depth counter using a string to track recursion depth (max 10 levels)
@@ -22,7 +75,9 @@ export type RoutePaths<
   R extends RawRoutes,
   Prefix extends string = "",
   D extends string = ""
-> = IsMaxDepth<D> extends true
+> = string extends keyof R
+  ? string
+  : IsMaxDepth<D> extends true
   ? string
   : {
       [K in keyof R & string]: K extends "?"
@@ -65,35 +120,78 @@ type _NavigateRoutes<R extends RawRoutes, Parts extends string[]> =
         : Rest extends []
         ? R[First]
         : never
+      : "*" extends keyof R
+      ? R["*"] extends RawRoutes
+        ? _NavigateRoutes<R["*"], Rest>
+        : Rest extends []
+        ? R["*"]
+        : never
       : never
     : never;
 
 /** Resolves to the route handler function for a given path string. */
-export type HandlerFor<R extends RawRoutes, P extends string> = _NavigateRoutes<
-  R,
-  _PathParts<P>
->;
+export type HandlerFor<R extends RawRoutes, P extends string> = string extends keyof R
+  ? () => any
+  : _NavigateRoutes<R, _PathParts<P>>;
 
 /**
- * Extracts the state type S from a route handler typed as
- * `(navOpts: NavOpts<S>, ...) => any`.
+ * Extracts the state type S from either a route() contract or a route handler
+ * typed as `(navOpts: NavOpts<S>, ...) => any`.
  */
-export type StateOf<F> = F extends (
-  navOpts: NavOpts<infer S>,
-  ...rest: any[]
-) => any
+export type StateOf<F> = HasContract<F> extends true
+  ? ContractState<ContractOf<F>>
+  : [FirstArg<F>] extends [never]
+  ? never
+  : [FirstArg<F>] extends [NavOpts<infer S, any>]
   ? S
-  : any;
+  : never;
+
+/**
+ * Extracts the search type from either a route() contract or a route handler
+ * typed as `(navOpts: NavOpts<S, Search>, ...) => any`.
+ */
+export type SearchOf<F> = HasContract<F> extends true
+  ? ContractSearch<ContractOf<F>>
+  : [FirstArg<F>] extends [never]
+  ? Record<never, never>
+  : [FirstArg<F>] extends [
+      NavOpts<any, infer Search extends Record<string, string>>
+    ]
+  ? Search
+  : Record<never, never>;
 
 /**
- * True when the route handler specifies a concrete (non-`any`, non-`unknown`,
- * non-`undefined`) state type, indicating callers must provide `state` when
- * navigating to it.
+ * True when the route handler specifies a concrete state type, indicating
+ * callers must provide `state` when navigating to it.
  *
- * Uses `unknown extends T` which is only true when T is `any` or `unknown`.
+ * route() contracts require state when the contract contains a `state` key.
+ * Legacy NavOpts-typed handlers use `unknown extends T` which is only true
+ * when T is `any` or `unknown`.
  */
-export type NeedsState<F> = unknown extends StateOf<F>
+export type NeedsState<F> = HasContractState<F> extends true
+  ? true
+  : unknown extends StateOf<F>
   ? false
   : StateOf<F> extends null | undefined
   ? false
   : true;
+
+/** True when a route declares non-empty search metadata. */
+export type NeedsSearch<F> = HasContractSearch<F> extends true
+  ? true
+  : keyof SearchOf<F> extends never
+  ? false
+  : true;
+
+export type NavMetaFor<F> = Omit<
+  NavMeta<StateOf<F>, SearchOf<F>>,
+  "state" | "search"
+> &
+  (NeedsState<F> extends true ? { state: StateOf<F> } : { state?: never }) &
+  (NeedsSearch<F> extends true ? { search: SearchOf<F> } : { search?: never });
+
+export type NeedsNavMeta<F> = NeedsState<F> extends true
+  ? true
+  : NeedsSearch<F> extends true
+  ? true
+  : false;