@vertz/ui 0.2.28 → 0.2.29

package/dist/shared/{chunk-e09mdqcx.js → chunk-4jfn3qhq.js}

@@ -1,7 +1,7 @@
 import {
   executeLoaders,
   matchRoute
-} from "./chunk-am9zaw4h.js";
+} from "./chunk-ah86rm07.js";
 import {
   prefetchNavData
 } from "./chunk-jrtrk5z4.js";
@@ -13,6 +13,117 @@ import {
   signal
 } from "./chunk-ppr06jgn.js";
 
+// src/router/reactive-search-params.ts
+function shallowEqual(a, b) {
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+  if (keysA.length !== keysB.length)
+    return false;
+  for (const key of keysA) {
+    if (a[key] !== b[key])
+      return false;
+  }
+  return true;
+}
+function buildMergedSearch(current, pending) {
+  const merged = { ...current };
+  for (const [key, value] of Object.entries(pending)) {
+    if (value === undefined || value === null) {
+      delete merged[key];
+    } else {
+      merged[key] = value;
+    }
+  }
+  return merged;
+}
+function currentPathname() {
+  return typeof window !== "undefined" ? window.location.pathname : "/";
+}
+function createReactiveSearchParams(rawSearchParamsSignal, navigateFn) {
+  let pending = null;
+  let capturedPathname = null;
+  function flush() {
+    if (!pending)
+      return;
+    const merged = buildMergedSearch(rawSearchParamsSignal.value, pending);
+    const pathname = capturedPathname ?? currentPathname();
+    pending = null;
+    capturedPathname = null;
+    if (shallowEqual(merged, rawSearchParamsSignal.value))
+      return;
+    navigateFn({
+      to: pathname,
+      search: merged,
+      replace: true
+    });
+  }
+  function navigateWithOptions(partial, options) {
+    pending = null;
+    capturedPathname = null;
+    const merged = buildMergedSearch(rawSearchParamsSignal.value, partial);
+    navigateFn({
+      to: currentPathname(),
+      search: merged,
+      replace: !options?.push
+    });
+  }
+  return new Proxy({}, {
+    get(_target, key) {
+      if (key === "navigate")
+        return navigateWithOptions;
+      if (typeof key === "symbol")
+        return;
+      if (pending && key in pending)
+        return pending[key];
+      return rawSearchParamsSignal.value[key];
+    },
+    set(_target, key, value) {
+      if (typeof key === "symbol")
+        return false;
+      if (!pending) {
+        pending = {};
+        capturedPathname = currentPathname();
+        queueMicrotask(flush);
+      }
+      pending[key] = value;
+      return true;
+    },
+    deleteProperty(_target, key) {
+      if (typeof key === "symbol")
+        return false;
+      if (!pending) {
+        pending = {};
+        capturedPathname = currentPathname();
+        queueMicrotask(flush);
+      }
+      pending[key] = undefined;
+      return true;
+    },
+    ownKeys() {
+      const current = pending ? buildMergedSearch(rawSearchParamsSignal.value, pending) : rawSearchParamsSignal.value;
+      return Object.keys(current);
+    },
+    getOwnPropertyDescriptor(_target, key) {
+      if (typeof key === "symbol")
+        return;
+      const val = pending && key in pending ? pending[key] : rawSearchParamsSignal.value[key];
+      if (val === undefined || val === null)
+        return;
+      return { configurable: true, enumerable: true, writable: true, value: val };
+    },
+    has(_target, key) {
+      if (typeof key === "symbol")
+        return false;
+      if (key === "navigate")
+        return true;
+      if (pending && key in pending) {
+        return pending[key] !== undefined && pending[key] !== null;
+      }
+      return key in rawSearchParamsSignal.value;
+    }
+  });
+}
+
 // src/router/view-transitions.ts
 var transitionGen = 0;
 async function withViewTransition(update, config) {
@@ -124,7 +235,82 @@ function createRouter(routes, initialUrlOrOptions, maybeOptions) {
     };
     const ssrUrl = initialUrl ?? ssrCtx?.url ?? "/";
     const fallbackMatch = matchRoute(routes, ssrUrl);
+    const ssrSearchParamsSignal = {
+      get value() {
+        const ctx = getSSRContext();
+        if (ctx) {
+          const m = matchRoute(routes, ctx.url);
+          return m?.search ?? {};
+        }
+        return fallbackMatch?.search ?? {};
+      },
+      peek() {
+        const ctx = getSSRContext();
+        if (ctx) {
+          const m = matchRoute(routes, ctx.url);
+          return m?.search ?? {};
+        }
+        return fallbackMatch?.search ?? {};
+      },
+      notify() {}
+    };
+    const ssrReactiveSearchParams = new Proxy({}, {
+      get(_target, key) {
+        if (key === "navigate") {
+          return () => {
+            if (true) {
+              throw new Error("useSearchParams().navigate() is not supported during SSR. " + "Use schema defaults for initial values.");
+            }
+          };
+        }
+        if (typeof key === "symbol")
+          return;
+        const ctx = getSSRContext();
+        if (ctx) {
+          const m = matchRoute(routes, ctx.url);
+          return m?.search?.[key];
+        }
+        return fallbackMatch?.search?.[key];
+      },
+      set() {
+        if (true) {
+          throw new Error("useSearchParams() writes are not supported during SSR. " + "Use schema defaults for initial values.");
+        }
+        return true;
+      },
+      deleteProperty() {
+        if (true) {
+          throw new Error("useSearchParams() writes are not supported during SSR. " + "Use schema defaults for initial values.");
+        }
+        return true;
+      },
+      ownKeys() {
+        const ctx = getSSRContext();
+        const search = ctx ? matchRoute(routes, ctx.url)?.search ?? {} : fallbackMatch?.search ?? {};
+        return Object.keys(search);
+      },
+      getOwnPropertyDescriptor(_target, key) {
+        if (typeof key === "symbol")
+          return;
+        const ctx = getSSRContext();
+        const search = ctx ? matchRoute(routes, ctx.url)?.search ?? {} : fallbackMatch?.search ?? {};
+        const val = search[key];
+        if (val === undefined)
+          return;
+        return { configurable: true, enumerable: true, writable: true, value: val };
+      },
+      has(_target, key) {
+        if (typeof key === "symbol")
+          return false;
+        if (key === "navigate")
+          return true;
+        const ctx = getSSRContext();
+        const search = ctx ? matchRoute(routes, ctx.url)?.search ?? {} : fallbackMatch?.search ?? {};
+        return key in search;
+      }
+    });
     return {
+      _reactiveSearchParams: ssrReactiveSearchParams,
       current: {
         get value() {
           const ctx = getSSRContext();
@@ -142,25 +328,7 @@ function createRouter(routes, initialUrlOrOptions, maybeOptions) {
         },
         notify() {}
       },
-      searchParams: {
-        get value() {
-          const ctx = getSSRContext();
-          if (ctx) {
-            const m = matchRoute(routes, ctx.url);
-            return m?.search ?? {};
-          }
-          return fallbackMatch?.search ?? {};
-        },
-        peek() {
-          const ctx = getSSRContext();
-          if (ctx) {
-            const m = matchRoute(routes, ctx.url);
-            return m?.search ?? {};
-          }
-          return fallbackMatch?.search ?? {};
-        },
-        notify() {}
-      },
+      searchParams: ssrSearchParamsSignal,
       loaderData: { value: [], peek: () => [], notify() {} },
       loaderError: { value: null, peek: () => null, notify() {} },
       navigate: () => Promise.resolve(),
@@ -367,7 +535,9 @@ function createRouter(routes, initialUrlOrOptions, maybeOptions) {
       activePrefetchUrl = null;
     }
   }
+  const _reactiveSearchParams = createReactiveSearchParams(_searchParams, navigate);
   return {
+    _reactiveSearchParams,
     current,
     dispose,
     loaderData,

package/dist/shared/{chunk-am9zaw4h.js → chunk-ah86rm07.js}

@@ -76,8 +76,10 @@ function matchRoute(routes, url) {
     }
   }
   let search = {};
+  let foundSchema = false;
   for (const m of matched) {
     if (m.route.searchParams) {
+      foundSchema = true;
       const raw = {};
       for (const [key, value] of searchParams.entries()) {
         raw[key] = value;
@@ -89,6 +91,11 @@ function matchRoute(routes, url) {
       break;
     }
   }
+  if (!foundSchema) {
+    for (const [key, value] of searchParams.entries()) {
+      search[key] = value;
+    }
+  }
   return {
     matched,
     params: allParams,

package/dist/shared/{chunk-2krx4aqe.js → chunk-kabxty17.js}

@@ -551,8 +551,12 @@ function parseSearchParams(urlParams, schema) {
   }
   return raw;
 }
-function useSearchParams(searchSignal) {
-  return searchSignal.value;
+function useSearchParams() {
+  const router = useContext(RouterContext);
+  if (!router) {
+    throw new Error("useSearchParams() must be called within RouterContext.Provider");
+  }
+  return router._reactiveSearchParams;
 }
 
 export { getCurrentErrorHandler, ErrorBoundary, createLink, Link, OutletContext, Outlet, RouterView, parseSearchParams, useSearchParams };

package/dist/src/index.d.ts

@@ -1423,6 +1423,20 @@ type TypedRoutes<T extends Record<string, RouteConfigLike> = RouteDefinitionMap>
 * Usage: `useRouter<InferRouteMap<typeof routes>>()`
 */
 type InferRouteMap<T> = T extends TypedRoutes<infer R> ? R : T;
+/**
+* Extract the search params type from a route definition map for a given path.
+*
+* If the route at `TPath` has a `searchParams` schema, resolves to the schema's
+* output type `T`. Otherwise resolves to `Record<string, string>` (raw URL params).
+*
+* Parallel to `ExtractParams<TPath>` which extracts path params from the URL pattern.
+*/
+type ExtractSearchParams<
+	TPath extends string,
+	TMap extends Record<string, RouteConfigLike> = RouteDefinitionMap
+> = TPath extends keyof TMap ? TMap[TPath] extends {
+	searchParams: SearchParamSchema<infer T>;
+} ? T : Record<string, string> : Record<string, string>;
 /** Internal compiled route. */
 interface CompiledRoute {
 	/** The original path pattern. */
@@ -1526,6 +1540,13 @@ declare function createLink(currentPath: ReadonlySignal<string>, navigate: (url:
 * Just use `<Link href="/about">About</Link>` inside a router-provided tree.
 */
 declare function Link({ href, children, activeClass, class: classProp, className }: LinkProps): HTMLAnchorElement;
+interface ReactiveSearchParams<T = Record<string, unknown>> {
+	/** Batch-navigate with explicit push/replace option. Merges partial with current params. */
+	navigate(partial: Partial<T>, options?: {
+		push?: boolean;
+	}): void;
+	[key: string]: unknown;
+}
 type NavigateSearchValue = string | number | boolean | null | undefined;
 type NavigateSearch = string | URLSearchParams | Record<string, NavigateSearchValue | readonly NavigateSearchValue[]>;
 /** Options for router.navigate(). */
@@ -1600,6 +1621,8 @@ interface Router<T extends Record<string, RouteConfigLike> = RouteDefinitionMap>
 	loaderError: Signal<Error | null>;
 	/** Parsed search params from the current route (reactive signal). */
 	searchParams: Signal<Record<string, unknown>>;
+	/** @internal Reactive search params proxy — accessed via useSearchParams(). */
+	_reactiveSearchParams: ReactiveSearchParams;
 	/** Navigate to a route pattern, interpolating params and search into the final URL. */
 	navigate<TPath extends RoutePattern<T>>(input: NavigateInput<TPath>): Promise<void>;
 	/** Re-run all loaders for the current route. */
@@ -1688,13 +1711,27 @@ declare function RouterView({ router, fallback, errorFallback }: RouterViewProps
 */
 declare function parseSearchParams<T = Record<string, string>>(urlParams: URLSearchParams, schema?: SearchParamSchema<T>): T;
 /**
-* Read the current search params from a reactive signal.
-* Intended to be called inside a reactive context (effect/computed).
+* Read the current search params as a reactive, writable proxy.
 *
-* @param searchSignal - Signal holding the current parsed search params
-* @returns The current search params value
+* Overload 1: `useSearchParams<'/search'>()` — infers search param types from
+* the route's `searchParams` schema via `ExtractSearchParams`. Requires codegen
+* augmentation or explicit `TMap` generic for full type inference.
+*
+* Overload 2: `useSearchParams<{ q: string; page: number }>()` — explicit type.
+*
+* Overload 3: `useSearchParams()` — no generic, returns `Record<string, string>`.
+*
+* Reads are reactive (trigger signal tracking), writes batch-navigate
+* to update the URL. Must be called within a `RouterContext.Provider`.
+*/
+declare function useSearchParams<
+	TPath extends string = string,
+	TMap extends Record<string, RouteConfigLike> = RouteDefinitionMap
+>(): ReactiveSearchParams<ExtractSearchParams<TPath, TMap>>;
+/**
+* Read the current search params with an explicit type assertion.
 */
-declare function useSearchParams<T>(searchSignal: ReadonlySignal<T>): T;
+declare function useSearchParams<T extends Record<string, unknown>>(): ReactiveSearchParams<T>;
 /**
 * Error thrown when `onCleanup()` is called outside a disposal scope.
 * Similar to React's invalid hook call error — fail-fast so developers
@@ -2074,4 +2111,4 @@ interface RegisterThemeInput {
 * ```
 */
 declare function registerTheme(resolved: RegisterThemeInput): void;
-export { zoomOut, zoomIn, variants, validate, useSearchParams, useRouter, useParams, useDialogStack, useDialog, useContext, untrack, slideOutToTop, slideOutToRight, slideOutToLeft, slideOutToBottom, slideInFromTop, slideInFromRight, slideInFromLeft, slideInFromBottom, signal, setAdapter, s, resolveChildren, resetRelationSchemas_TEST_ONLY, resetInjectedStyles, registerTheme, registerRelationSchema, ref, query, parseSearchParams, palettes, onMount2 as onMount, onCleanup, onAnimationsComplete, mount, keyframes, isRenderNode, isQueryDescriptor, isBrowser, invalidateTenantQueries, invalidate, injectCSS, hydrateIslands, hydrate, globalCss, getRelationSchema, getQueryEnvelopeStore, getInjectedCSS, getEntityStore, getAdapter, formatRelativeTime, formDataToObject, form, font, fadeOut, fadeIn, defineTheme, defineRoutes, css, createTestStore, createRouter, createOptimisticHandler, createLink, createFieldState, createDialogStack, createDOMAdapter, createContext, configureImageOptimizer, computed, compileTheme, compileFonts, children, buildOptimizedUrl, batch, accordionUp, accordionDown, __staticText, __exitChildren, __enterChildren, __element, __append, VariantsConfig, VariantProps, VariantFunction, ValidationResult, UnwrapSignals, TypedRoutes, TypedRouter, ThemeProviderProps, ThemeProvider, ThemeInput, Theme, SuspenseProps, Suspense, StyleValue, StyleEntry, Signal, SerializedStore, SearchParamSchema, SdkMethodWithMeta, SdkMethod, RouterViewProps, RouterView, RouterOptions, RouterContext, Router, RoutePattern, RoutePaths, RouteMatch, RouteDefinitionMap, RouteConfig, RenderText, RenderNode, RenderElement, RenderAdapter, RelativeTimeProps, RelativeTime, RelationSchema, RelationFieldDef, RegisterThemeInput, Ref, ReadonlySignal, RENDER_NODE_BRAND, QueryResult, QueryOptions, QueryEnvelopeStore, QueryEnvelope, QueryDescriptor3 as QueryDescriptor, PresenceProps, Presence, PreloadItem, PathWithParams, ParamSchema, OutletContextValue, OutletContext, Outlet, NavigateOptions, NavigateInput, MountOptions, MountHandle, MergeSelectOptions, MatchedRoute, LoaderData, ListAnimationHooks, ListAnimationContext, LinkProps, LinkFactoryOptions, Link, IslandRegistry, IslandProps, Island, InferRouteMap, ImageProps, Image, GlobalCSSOutput, GlobalCSSInput, FormatRelativeTimeOptions, FormSchema, FormOptions, FormInstance, FormDataOptions, ForeignProps, Foreign, FontSrc, FontOptions, FontFallbackMetrics, FontDescriptor, FieldState, FieldSelectionTracker, FallbackFontName, ExtractParams, ErrorFallbackProps, ErrorBoundaryProps, ErrorBoundary, EntityStoreOptions, EntityStore, DisposeFn, DisposalScopeError, DialogStackProvider, DialogStackContext, DialogStack, DialogResult, DialogOpenOptions, DialogIdContext, DialogHandleContext, DialogHandle, DialogComponent, DefaultErrorFallback, DateInput, Context, ConfirmOptions, Computed, ComponentRegistry, ComponentLoader, ComponentFunction, CompiledTheme, CompiledRoute, CompiledFonts, CompileThemeOptions, CompileFontsOptions, ColorPalette, ChildrenAccessor, ChildValue, CacheStore, CSSOutput, CSSInput, ANIMATION_EASING, ANIMATION_DURATION };
+export { zoomOut, zoomIn, variants, validate, useSearchParams, useRouter, useParams, useDialogStack, useDialog, useContext, untrack, slideOutToTop, slideOutToRight, slideOutToLeft, slideOutToBottom, slideInFromTop, slideInFromRight, slideInFromLeft, slideInFromBottom, signal, setAdapter, s, resolveChildren, resetRelationSchemas_TEST_ONLY, resetInjectedStyles, registerTheme, registerRelationSchema, ref, query, parseSearchParams, palettes, onMount2 as onMount, onCleanup, onAnimationsComplete, mount, keyframes, isRenderNode, isQueryDescriptor, isBrowser, invalidateTenantQueries, invalidate, injectCSS, hydrateIslands, hydrate, globalCss, getRelationSchema, getQueryEnvelopeStore, getInjectedCSS, getEntityStore, getAdapter, formatRelativeTime, formDataToObject, form, font, fadeOut, fadeIn, defineTheme, defineRoutes, css, createTestStore, createRouter, createOptimisticHandler, createLink, createFieldState, createDialogStack, createDOMAdapter, createContext, configureImageOptimizer, computed, compileTheme, compileFonts, children, buildOptimizedUrl, batch, accordionUp, accordionDown, __staticText, __exitChildren, __enterChildren, __element, __append, VariantsConfig, VariantProps, VariantFunction, ValidationResult, UnwrapSignals, TypedRoutes, TypedRouter, ThemeProviderProps, ThemeProvider, ThemeInput, Theme, SuspenseProps, Suspense, StyleValue, StyleEntry, Signal, SerializedStore, SearchParamSchema, SdkMethodWithMeta, SdkMethod, RouterViewProps, RouterView, RouterOptions, RouterContext, Router, RoutePattern, RoutePaths, RouteMatch, RouteDefinitionMap, RouteConfig, RenderText, RenderNode, RenderElement, RenderAdapter, RelativeTimeProps, RelativeTime, RelationSchema, RelationFieldDef, RegisterThemeInput, Ref, ReadonlySignal, ReactiveSearchParams, RENDER_NODE_BRAND, QueryResult, QueryOptions, QueryEnvelopeStore, QueryEnvelope, QueryDescriptor3 as QueryDescriptor, PresenceProps, Presence, PreloadItem, PathWithParams, ParamSchema, OutletContextValue, OutletContext, Outlet, NavigateOptions, NavigateInput, MountOptions, MountHandle, MergeSelectOptions, MatchedRoute, LoaderData, ListAnimationHooks, ListAnimationContext, LinkProps, LinkFactoryOptions, Link, IslandRegistry, IslandProps, Island, InferRouteMap, ImageProps, Image, GlobalCSSOutput, GlobalCSSInput, FormatRelativeTimeOptions, FormSchema, FormOptions, FormInstance, FormDataOptions, ForeignProps, Foreign, FontSrc, FontOptions, FontFallbackMetrics, FontDescriptor, FieldState, FieldSelectionTracker, FallbackFontName, ExtractSearchParams, ExtractParams, ErrorFallbackProps, ErrorBoundaryProps, ErrorBoundary, EntityStoreOptions, EntityStore, DisposeFn, DisposalScopeError, DialogStackProvider, DialogStackContext, DialogStack, DialogResult, DialogOpenOptions, DialogIdContext, DialogHandleContext, DialogHandle, DialogComponent, DefaultErrorFallback, DateInput, Context, ConfirmOptions, Computed, ComponentRegistry, ComponentLoader, ComponentFunction, CompiledTheme, CompiledRoute, CompiledFonts, CompileThemeOptions, CompileFontsOptions, ColorPalette, ChildrenAccessor, ChildValue, CacheStore, CSSOutput, CSSInput, ANIMATION_EASING, ANIMATION_DURATION };

package/dist/src/index.js

@@ -36,7 +36,7 @@ import {
   getCurrentErrorHandler,
   parseSearchParams,
   useSearchParams
-} from "../shared/chunk-2krx4aqe.js";
+} from "../shared/chunk-kabxty17.js";
 import {
   beginDeferringMounts,
   discardDeferredMounts,
@@ -45,10 +45,10 @@ import {
 } from "../shared/chunk-svvqjmyy.js";
 import {
   createRouter
-} from "../shared/chunk-e09mdqcx.js";
+} from "../shared/chunk-4jfn3qhq.js";
 import {
   defineRoutes
-} from "../shared/chunk-am9zaw4h.js";
+} from "../shared/chunk-ah86rm07.js";
 import {
   createFieldState,
   form,

package/dist/src/internals.js

@@ -14,7 +14,7 @@ import {
   executeLoaders,
   matchPath,
   matchRoute
-} from "../shared/chunk-am9zaw4h.js";
+} from "../shared/chunk-ah86rm07.js";
 import {
   EntityStore,
   MemoryCache,

package/dist/src/router/public.d.ts

@@ -161,6 +161,20 @@ type TypedRoutes<T extends Record<string, RouteConfigLike> = RouteDefinitionMap>
 * Usage: `useRouter<InferRouteMap<typeof routes>>()`
 */
 type InferRouteMap<T> = T extends TypedRoutes<infer R> ? R : T;
+/**
+* Extract the search params type from a route definition map for a given path.
+*
+* If the route at `TPath` has a `searchParams` schema, resolves to the schema's
+* output type `T`. Otherwise resolves to `Record<string, string>` (raw URL params).
+*
+* Parallel to `ExtractParams<TPath>` which extracts path params from the URL pattern.
+*/
+type ExtractSearchParams<
+	TPath extends string,
+	TMap extends Record<string, RouteConfigLike> = RouteDefinitionMap
+> = TPath extends keyof TMap ? TMap[TPath] extends {
+	searchParams: SearchParamSchema<infer T>;
+} ? T : Record<string, string> : Record<string, string>;
 /** Internal compiled route. */
 interface CompiledRoute {
 	/** The original path pattern. */
@@ -307,6 +321,13 @@ declare function createLink(currentPath: ReadonlySignal<string>, navigate: (url:
 * Just use `<Link href="/about">About</Link>` inside a router-provided tree.
 */
 declare function Link({ href, children, activeClass, class: classProp, className }: LinkProps): HTMLAnchorElement;
+interface ReactiveSearchParams<T = Record<string, unknown>> {
+	/** Batch-navigate with explicit push/replace option. Merges partial with current params. */
+	navigate(partial: Partial<T>, options?: {
+		push?: boolean;
+	}): void;
+	[key: string]: unknown;
+}
 type NavigateSearchValue = string | number | boolean | null | undefined;
 type NavigateSearch = string | URLSearchParams | Record<string, NavigateSearchValue | readonly NavigateSearchValue[]>;
 /** Options for router.navigate(). */
@@ -381,6 +402,8 @@ interface Router<T extends Record<string, RouteConfigLike> = RouteDefinitionMap>
 	loaderError: Signal<Error | null>;
 	/** Parsed search params from the current route (reactive signal). */
 	searchParams: Signal<Record<string, unknown>>;
+	/** @internal Reactive search params proxy — accessed via useSearchParams(). */
+	_reactiveSearchParams: ReactiveSearchParams;
 	/** Navigate to a route pattern, interpolating params and search into the final URL. */
 	navigate<TPath extends RoutePattern<T>>(input: NavigateInput<TPath>): Promise<void>;
 	/** Re-run all loaders for the current route. */
@@ -497,11 +520,25 @@ declare function RouterView({ router, fallback, errorFallback }: RouterViewProps
 */
 declare function parseSearchParams<T = Record<string, string>>(urlParams: URLSearchParams, schema?: SearchParamSchema<T>): T;
 /**
-* Read the current search params from a reactive signal.
-* Intended to be called inside a reactive context (effect/computed).
+* Read the current search params as a reactive, writable proxy.
+*
+* Overload 1: `useSearchParams<'/search'>()` — infers search param types from
+* the route's `searchParams` schema via `ExtractSearchParams`. Requires codegen
+* augmentation or explicit `TMap` generic for full type inference.
 *
-* @param searchSignal - Signal holding the current parsed search params
-* @returns The current search params value
+* Overload 2: `useSearchParams<{ q: string; page: number }>()` — explicit type.
+*
+* Overload 3: `useSearchParams()` — no generic, returns `Record<string, string>`.
+*
+* Reads are reactive (trigger signal tracking), writes batch-navigate
+* to update the URL. Must be called within a `RouterContext.Provider`.
+*/
+declare function useSearchParams<
+	TPath extends string = string,
+	TMap extends Record<string, RouteConfigLike> = RouteDefinitionMap
+>(): ReactiveSearchParams<ExtractSearchParams<TPath, TMap>>;
+/**
+* Read the current search params with an explicit type assertion.
 */
-declare function useSearchParams<T>(searchSignal: ReadonlySignal<T>): T;
-export { useSearchParams, useRouter, useParams, parseSearchParams, defineRoutes, createRouter, createLink, TypedRoutes, TypedRouter, SearchParamSchema, RouterViewProps, RouterView, RouterContext, Router, RoutePattern, RoutePaths, RouteMatch, RouteDefinitionMap, RouteConfig, PathWithParams, ParamSchema, OutletContextValue, OutletContext, Outlet, NavigateOptions, NavigateInput, MatchedRoute, LoaderData, LinkProps, Link, InferRouteMap, ExtractParams, CompiledRoute };
+declare function useSearchParams<T extends Record<string, unknown>>(): ReactiveSearchParams<T>;
+export { useSearchParams, useRouter, useParams, parseSearchParams, defineRoutes, createRouter, createLink, TypedRoutes, TypedRouter, SearchParamSchema, RouterViewProps, RouterView, RouterContext, Router, RoutePattern, RoutePaths, RouteMatch, RouteDefinitionMap, RouteConfig, ReactiveSearchParams, PathWithParams, ParamSchema, OutletContextValue, OutletContext, Outlet, NavigateOptions, NavigateInput, MatchedRoute, LoaderData, LinkProps, Link, InferRouteMap, ExtractSearchParams, ExtractParams, CompiledRoute };

package/dist/src/router/public.js

@@ -6,14 +6,14 @@ import {
   createLink,
   parseSearchParams,
   useSearchParams
-} from "../../shared/chunk-2krx4aqe.js";
+} from "../../shared/chunk-kabxty17.js";
 import"../../shared/chunk-svvqjmyy.js";
 import {
   createRouter
-} from "../../shared/chunk-e09mdqcx.js";
+} from "../../shared/chunk-4jfn3qhq.js";
 import {
   defineRoutes
-} from "../../shared/chunk-am9zaw4h.js";
+} from "../../shared/chunk-ah86rm07.js";
 import"../../shared/chunk-jrtrk5z4.js";
 import"../../shared/chunk-djvarb8r.js";
 import"../../shared/chunk-h1fsr8kv.js";

package/dist/src/test/index.d.ts

@@ -298,6 +298,13 @@ interface Signal<T> {
 	/** Manually notify all subscribers (useful after mutating the value in place). */
 	notify(): void;
 }
+interface ReactiveSearchParams<T = Record<string, unknown>> {
+	/** Batch-navigate with explicit push/replace option. Merges partial with current params. */
+	navigate(partial: Partial<T>, options?: {
+		push?: boolean;
+	}): void;
+	[key: string]: unknown;
+}
 type NavigateSearchValue = string | number | boolean | null | undefined;
 type NavigateSearch = string | URLSearchParams | Record<string, NavigateSearchValue | readonly NavigateSearchValue[]>;
 /** Options for router.navigate(). */
@@ -345,6 +352,8 @@ interface Router<T extends Record<string, RouteConfigLike> = RouteDefinitionMap>
 	loaderError: Signal<Error | null>;
 	/** Parsed search params from the current route (reactive signal). */
 	searchParams: Signal<Record<string, unknown>>;
+	/** @internal Reactive search params proxy — accessed via useSearchParams(). */
+	_reactiveSearchParams: ReactiveSearchParams;
 	/** Navigate to a route pattern, interpolating params and search into the final URL. */
 	navigate<TPath extends RoutePattern<T>>(input: NavigateInput<TPath>): Promise<void>;
 	/** Re-run all loaders for the current route. */

package/dist/src/test/index.js

@@ -1,9 +1,9 @@
 import {
   createRouter
-} from "../../shared/chunk-e09mdqcx.js";
+} from "../../shared/chunk-4jfn3qhq.js";
 import {
   defineRoutes
-} from "../../shared/chunk-am9zaw4h.js";
+} from "../../shared/chunk-ah86rm07.js";
 import"../../shared/chunk-jrtrk5z4.js";
 import"../../shared/chunk-xs5s8gqe.js";
 import"../../shared/chunk-ppr06jgn.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertz/ui",
-  "version": "0.2.28",
+  "version": "0.2.29",
   "type": "module",
   "license": "MIT",
   "description": "Vertz UI framework — signals, components, JSX runtime",
@@ -74,11 +74,11 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@vertz/fetch": "^0.2.25"
+    "@vertz/fetch": "^0.2.28"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.7.0",
-    "@vertz/schema": "^0.2.25",
+    "@vertz/schema": "^0.2.28",
     "bunup": "^0.16.31",
     "happy-dom": "^20.7.0",
     "typescript": "^5.7.0"

package/reactivity.json

@@ -50,6 +50,12 @@
       "reactivity": {
         "type": "reactive-source"
       }
+    },
+    "useSearchParams": {
+      "kind": "function",
+      "reactivity": {
+        "type": "reactive-source"
+      }
     }
   },
   "filePath": "@vertz/ui",