@djangocfg/ui-core 2.1.292 → 2.1.294

package/README.md

@@ -83,7 +83,7 @@ Default **`TooltipContent`** styling uses semantic **popover** tokens (`bg-popov
 ### Specialized (7)
 `Kbd` `TokenIcon` `Item` `Portal` `ImageWithFallback` `CopyButton` `CopyField`
 
-## Hooks (17)
+## Hooks (28+)
 
 | Hook | Description |
 |------|-------------|
@@ -118,6 +118,53 @@ const isNarrow = useMediaQuery(`(max-width: ${BREAKPOINTS.sm - 1}px)`)
 const isDark   = useMediaQuery('(prefers-color-scheme: dark)')
 ```
 
+## Router Hooks
+
+Framework-agnostic navigation primitives — work on plain History API by default, plug into any router via the adapter pattern. Full docs in [`src/hooks/router/README.md`](./src/hooks/router/README.md).
+
+| Hook | Purpose |
+|------|---------|
+| `useLocation()` | Reactive `{ pathname, search, hash, href }`. |
+| `useLocationProperty(get, getSsr)` | Subscribe to ONE field — skip re-renders on unrelated changes. |
+| `useNavigate()` | `navigate`, `navigateExternal`, `push`, `replace`, `back`, `forward`. |
+| `useQueryParams()` | Record-style read/write of `?key=value` URL state. |
+| `useQueryState(key, parser)` | Typed `useState`-style hook bound to one URL key (with `clearOnDefault`). |
+| `useBackOrFallback()` | Smart Back that falls back to a route when there's no in-app history. |
+| `useUrlBuilder()` | Pure URL assembly: `build`, `withCurrentParams`. |
+| `useSmartLink(href)` | Make any element a link (cmd-click, middle-click, Enter, Space). |
+| `useIsActive(href)` | Boolean for nav-item highlighting. |
+| `useRouter()` | Convenience facade composing everything. |
+| `RouterAdapterProvider` | Swap the navigation backend. |
+| `parseAsString` / `parseAsInteger` / `parseAsFloat` / `parseAsBoolean` / `parseAsIsoDate` / `parseAsStringEnum` / `parseAsArrayOf` / `parseAsJson` | Parsers for `useQueryState`. Each has `.withDefault(value)`. |
+
+```tsx
+import {
+  useNavigate,
+  useQueryState,
+  parseAsInteger,
+} from '@djangocfg/ui-core/hooks';
+
+const { navigate } = useNavigate();
+const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1));
+
+navigate('/products');
+setPage((p) => p + 1);  // ?page=2 — `page=1` is dropped (clearOnDefault)
+```
+
+### Next.js adapter
+
+In Next apps, mount the adapter once near the root so navigation flows through `next/navigation` (server components + prefetch keep working):
+
+```tsx
+import { NextRouterAdapter } from '@djangocfg/ui-core/adapters/nextjs';
+
+<NextRouterAdapter>
+  <App />
+</NextRouterAdapter>
+```
+
+`next` is an **optional peer dependency** — Wails / Electron / Vite consumers don't pull it in.
+
 ## Theme Palette Hooks
 
 Hooks for accessing theme colors from CSS variables (useful for Canvas, SVG, charts, diagrams, etc.):
@@ -290,7 +337,8 @@ import '@djangocfg/ui-core/styles/globals';
 |------|---------|
 | `@djangocfg/ui-core` | All components & hooks |
 | `@djangocfg/ui-core/components` | Components only |
-| `@djangocfg/ui-core/hooks` | Hooks only |
+| `@djangocfg/ui-core/hooks` | Hooks only (incl. router hooks) |
+| `@djangocfg/ui-core/adapters/nextjs` | `<NextRouterAdapter>` for Next.js apps (optional peer: `next`) |
 | `@djangocfg/ui-core/lib` | Utilities (cn, etc.) |
 | `@djangocfg/ui-core/lib/dialog-service` | Dialog service |
 | `@djangocfg/ui-core/utils` | Runtime utilities (emitRuntimeError) |
@@ -322,7 +370,6 @@ These features require Next.js or browser storage APIs:
 - `DropdownMenu` — uses next/link
 - `DownloadButton` — uses localStorage
 - `useTheme` — uses next-themes
-- `useQueryParams`, `useCfgRouter` — uses next/router
 
 ## Requirements
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.292",
+  "version": "2.1.294",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -48,6 +48,11 @@
       "import": "./src/hooks/index.ts",
       "require": "./src/hooks/index.ts"
     },
+    "./adapters/nextjs": {
+      "types": "./src/hooks/router/adapters/nextjs.tsx",
+      "import": "./src/hooks/router/adapters/nextjs.tsx",
+      "require": "./src/hooks/router/adapters/nextjs.tsx"
+    },
     "./lib": {
       "types": "./src/lib/index.ts",
       "import": "./src/lib/index.ts",
@@ -86,10 +91,11 @@
     "playground": "playground dev"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.292",
+    "@djangocfg/i18n": "^2.1.294",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
+    "next": ">=14.0.0",
     "react": "^19.1.0",
     "react-device-detect": "^2.2.3",
     "react-dom": "^19.1.0",
@@ -98,6 +104,11 @@
     "zod": "^4.3.6",
     "zustand": "^5.0.0"
   },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
+  },
   "dependencies": {
     "@hookform/resolvers": "^5.2.2",
     "@radix-ui/react-accordion": "^1.2.12",
@@ -148,13 +159,14 @@
     "vaul": "1.1.2"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.292",
+    "@djangocfg/i18n": "^2.1.294",
     "@djangocfg/playground": "workspace:*",
-    "@djangocfg/typescript-config": "^2.1.292",
+    "@djangocfg/typescript-config": "^2.1.294",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",
     "lucide-react": "^0.545.0",
+    "next": "^16.2.4",
     "typescript": "^5.9.3"
   },
   "publishConfig": {

package/src/hooks/index.ts

@@ -31,3 +31,70 @@ export { useBrowserDetect } from './useBrowserDetect';
 export type { BrowserInfo } from './useBrowserDetect';
 export { useDeviceDetect } from './useDeviceDetect';
 export type { DeviceDetectResult } from './useDeviceDetect';
+
+// ----------------------------------------------------------------------------
+// Router — framework-agnostic navigation primitives.
+// See ./router/README.md for design notes and the Next.js adapter example.
+// ----------------------------------------------------------------------------
+export {
+  // Adapter
+  RouterAdapterContext,
+  RouterAdapterProvider,
+  defaultAdapter,
+  useRouterAdapter,
+  // useLocation
+  useLocation,
+  NAVIGATE_EVENT,
+  // useNavigate
+  useNavigate,
+  // useQueryParams
+  useQueryParams,
+  // useBackOrFallback
+  useBackOrFallback,
+  // useUrlBuilder
+  useUrlBuilder,
+  buildUrl,
+  buildQueryString,
+  // useSmartLink
+  useSmartLink,
+  // useIsActive
+  useIsActive,
+  // useQueryState (typed single-key URL state)
+  useQueryState,
+  // Parsers
+  parseAsString,
+  parseAsInteger,
+  parseAsFloat,
+  parseAsBoolean,
+  parseAsIsoDate,
+  parseAsStringEnum,
+  parseAsArrayOf,
+  parseAsJson,
+  // useRouter (composite facade)
+  useRouter,
+} from './router';
+export type {
+  RouterAdapter,
+  RouterAdapterProviderProps,
+  RouterLocation,
+  LocationSnapshot,
+  NavigateOptions,
+  UseNavigateReturn,
+  QueryParamsSnapshot,
+  QueryParamValue,
+  QueryParamUpdates,
+  SetQueryParamsOptions,
+  UseQueryParamsReturn,
+  UseBackOrFallbackReturn,
+  QueryValue,
+  QueryParamsInput,
+  UseUrlBuilderReturn,
+  UseSmartLinkOptions,
+  SmartLinkHandlers,
+  UseIsActiveOptions,
+  UseQueryStateOptions,
+  QueryStateUpdater,
+  QueryParser,
+  QueryParserBuilder,
+  UseRouterReturn,
+} from './router';

package/src/hooks/router/README.md

@@ -0,0 +1,119 @@
+# Router hooks
+
+Framework-agnostic navigation primitives for `@djangocfg/ui-core`. Built on plain browser APIs (`window.history`, `window.location`, `URLSearchParams`, `popstate`). No `next/*`, no `react-router`, no third-party deps.
+
+## Surface
+
+| Hook | Purpose |
+| --- | --- |
+| `useLocation` | Reactive snapshot of `window.location` (`pathname`, `search`, `hash`, `href`). |
+| `useNavigate` | Programmatic navigation: `navigate`, `navigateExternal`, `push`, `replace`, `back`, `forward`. |
+| `useQueryParams` | Read/write `?key=value` URL state with typed coercion (`get`, `getNumber`, `getBoolean`, `set`, `remove`, `clear`). |
+| `useBackOrFallback` | Smart "back" that falls back to a route when there's no in-app history. |
+| `useUrlBuilder` | Pure URL/querystring assembly: `build`, `withCurrentParams`. |
+| `useSmartLink` | Click + keyboard handlers that turn any element into a proper link (cmd-click, middle-click, Enter, Space). |
+| `useIsActive` | `boolean` for "current pathname matches this href" — for nav-item highlighting. |
+| `useQueryState` | Typed `useState`-style hook bound to ONE URL key (with parsers + `clearOnDefault`). |
+| `useLocationProperty` | Subscribe to ONE derived field of `window.location` (avoids re-renders on unrelated fields). |
+| `useRouter` | Convenience facade composing the above. |
+| `RouterAdapterProvider` | Swap the navigation backend (e.g. Next.js's router). |
+| `parseAsString` / `parseAsInteger` / `parseAsFloat` / `parseAsBoolean` / `parseAsIsoDate` / `parseAsStringEnum` / `parseAsArrayOf` / `parseAsJson` | Parser builders for `useQueryState`. Each has `.withDefault(value)`. |
+
+## Decomposition rationale
+
+Each atomic hook subscribes to exactly what it needs. A component that only calls `navigate(...)` shouldn't re-render every time the querystring changes — `useNavigate` doesn't subscribe to location, so it doesn't. Same for `useUrlBuilder` (only re-renders on `search` change), `useQueryParams` (same), and so on.
+
+`useRouter` exists for convenience and ergonomic familiarity. Use it when you want everything in one return; use the atomic hooks for fewer re-renders and better tree-shaking.
+
+## Adapter pattern
+
+Default behavior uses `window.history.pushState` + `window.location` and works in any browser (Wails / Electron / Vite / CRA — nothing to mount, it just works).
+
+For Next.js — mount the built-in adapter once near the root. It bridges every hook to `next/navigation` so server components, route loaders, and prefetch fire correctly:
+
+```tsx
+// app/[locale]/layout.tsx (or wherever your client provider stack lives)
+import { NextRouterAdapter } from '@djangocfg/ui-core/adapters/nextjs';
+
+<I18nProvider locale={locale} messages={messages}>
+  <NextRouterAdapter>
+    <AppLayout>{children}</AppLayout>
+  </NextRouterAdapter>
+</I18nProvider>
+```
+
+`next` is an **optional peer dependency** — the package never imports from `next/*` from the main entry. The Next adapter lives behind the `/adapters/nextjs` sub-path entry, so non-Next consumers don't pull `next` into their bundle.
+
+For other routers (TanStack Router, wouter, Remix, custom transports) — write a ~20-line custom adapter:
+
+```tsx
+'use client';
+
+import { useMemo } from 'react';
+import { RouterAdapterProvider, type RouterAdapter } from '@djangocfg/ui-core/hooks';
+
+export function MyRouterAdapter({ children }: { children: React.ReactNode }) {
+  const myRouter = useMyRouter();
+  const adapter = useMemo<RouterAdapter>(() => ({
+    push:    (url) => myRouter.push(url),
+    replace: (url) => myRouter.replace(url),
+    back:    () => myRouter.back(),
+    forward: () => myRouter.forward(),
+    getLocation: () => ({
+      pathname: window.location.pathname,
+      search:   window.location.search,
+      hash:     window.location.hash,
+    }),
+  }), [myRouter]);
+
+  return <RouterAdapterProvider value={adapter}>{children}</RouterAdapterProvider>;
+}
+```
+
+**Adapter contract gotcha:** custom `push` / `replace` implementations should ultimately route through `window.history.pushState` (Next does, so does react-router). If yours doesn't, dispatch `'djc:navigate'` after each navigation manually so `useLocation` re-reads.
+
+## `useQueryState` (typed URL state)
+
+Bound to one query key with a typed parser. Inspired by `nuqs` but framework-agnostic via the same adapter context.
+
+```tsx
+import {
+  useQueryState,
+  parseAsInteger,
+  parseAsStringEnum,
+} from '@djangocfg/ui-core/hooks';
+
+const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1));
+const [tab,  setTab]  = useQueryState('tab',  parseAsStringEnum(['list', 'grid']).withDefault('list'));
+
+setPage((prev) => prev + 1); // functional updater, just like useState
+setPage(null);               // clears the key from the URL
+```
+
+`clearOnDefault` (default `true`) drops the key from the URL when the value equals the parser default — keeps URLs short. Pass `{ clearOnDefault: false }` to keep explicit `?page=1` for shareable links.
+
+Parsers: `parseAsString`, `parseAsInteger`, `parseAsFloat`, `parseAsBoolean`, `parseAsIsoDate`, `parseAsStringEnum([...])`, `parseAsArrayOf(item)`, `parseAsJson<T>()`. Each has `.withDefault(value)`. Build your own by satisfying the `QueryParser<T>` interface — it's three functions (`parse`, `serialize`, `eq`).
+
+## How `useLocation` knows about `pushState`
+
+Browsers don't fire `popstate` for programmatic `pushState` / `replaceState`. We monkey-patch both methods once (idempotent, module-level guard) on first mount and dispatch a custom `'djc:navigate'` event after each call. Anyone calling history APIs anywhere in the page will trigger an update — including the consumer's own router, third-party scripts, and our default adapter.
+
+## SSR
+
+- All hooks return safe defaults on the server (`pathname: '/'`, etc.).
+- `useSyncExternalStore`'s `getServerSnapshot` is wired up correctly.
+- Mutating methods (`push`, `replace`, `navigate`, `navigateExternal`) no-op when `window` is undefined.
+- No hydration mismatches — first client render reads real `window.location` after mount via `useSyncExternalStore`'s `getSnapshot`.
+
+## Trade-offs vs. `next/navigation`
+
+| Concern | `next/navigation` | This library |
+| --- | --- | --- |
+| Server components fire | yes (built-in) | only if you mount the Next adapter |
+| Pending state (`useTransition`) | bundled in | wrap calls yourself |
+| Locale-prefix handling | yes | no — wrap if needed |
+| Route matching / dynamic segments | yes | no — out of scope |
+| Works outside Next | no | yes — anywhere React runs |
+| `<Link>` component | yes | not yet (use `useSmartLink` on any element) |
+
+Out of scope: locale prefixes, route matching, dynamic segments, transitions, `<Link>`. Add them in consumer code or in higher-level packages.

package/src/hooks/router/adapter.tsx

@@ -0,0 +1,139 @@
+'use client';
+
+/**
+ * Router adapter — pluggable navigation backend.
+ *
+ * WHY:
+ *   `@djangocfg/ui-core` is framework-agnostic, but consumers using Next.js,
+ *   TanStack Router, wouter, etc. need SPA navigations to flow through their
+ *   own router so server components / data loaders / route guards fire
+ *   correctly. The adapter pattern lets the consumer swap the implementation
+ *   without changing call-sites inside library components.
+ *
+ * Default behavior uses `window.history.pushState` + `window.location` (works
+ * in any browser, zero deps). When no provider is mounted, the default is
+ * silently used.
+ *
+ * @example
+ * // In a Next.js app:
+ * import { useRouter as useNextRouter } from 'next/navigation';
+ * import { RouterAdapterProvider } from '@djangocfg/ui-core/hooks';
+ *
+ * function NextAdapter({ children }: { children: React.ReactNode }) {
+ *   const next = useNextRouter();
+ *   const adapter = useMemo(() => ({
+ *     push: (url: string) => next.push(url),
+ *     replace: (url: string) => next.replace(url),
+ *     back: () => next.back(),
+ *     forward: () => next.forward(),
+ *     getLocation: () => ({
+ *       pathname: window.location.pathname,
+ *       search: window.location.search,
+ *       hash: window.location.hash,
+ *     }),
+ *   }), [next]);
+ *   return <RouterAdapterProvider value={adapter}>{children}</RouterAdapterProvider>;
+ * }
+ */
+
+import { createContext, useContext, useMemo, type ReactNode } from 'react';
+
+/**
+ * Snapshot of the current URL location.
+ * Mirrors the parts of `window.location` we actually use.
+ */
+export interface RouterLocation {
+  pathname: string;
+  search: string;
+  hash: string;
+}
+
+/**
+ * Pluggable navigation backend. Implementations must be SSR-safe
+ * (mutations should no-op when `typeof window === 'undefined'`).
+ */
+export interface RouterAdapter {
+  /** Push a new entry onto the history stack. */
+  push: (url: string) => void;
+  /** Replace the current history entry. */
+  replace: (url: string) => void;
+  /** Go back one entry. */
+  back: () => void;
+  /** Go forward one entry. */
+  forward: () => void;
+  /** Read the current location (synchronous). */
+  getLocation: () => RouterLocation;
+}
+
+const SSR_LOCATION: RouterLocation = Object.freeze({
+  pathname: '/',
+  search: '',
+  hash: '',
+});
+
+/**
+ * Default adapter — uses History API + window.location.
+ * No-ops on the server. Triggers our internal `djc:navigate` event so
+ * `useLocation` reflects the change (see `useLocation.ts`).
+ */
+export const defaultAdapter: RouterAdapter = Object.freeze({
+  push(url: string) {
+    if (typeof window === 'undefined') return;
+    window.history.pushState(null, '', url);
+  },
+  replace(url: string) {
+    if (typeof window === 'undefined') return;
+    window.history.replaceState(null, '', url);
+  },
+  back() {
+    if (typeof window === 'undefined') return;
+    window.history.back();
+  },
+  forward() {
+    if (typeof window === 'undefined') return;
+    window.history.forward();
+  },
+  getLocation(): RouterLocation {
+    if (typeof window === 'undefined') return SSR_LOCATION;
+    return {
+      pathname: window.location.pathname,
+      search: window.location.search,
+      hash: window.location.hash,
+    };
+  },
+});
+
+/**
+ * React context carrying the active adapter. `null` means "use default".
+ * Kept intentionally nullable so we don't burn a Provider for the default case.
+ */
+export const RouterAdapterContext = createContext<RouterAdapter | null>(null);
+
+export interface RouterAdapterProviderProps {
+  /** Adapter implementation. Will be used by every router hook in subtree. */
+  value: RouterAdapter;
+  children: ReactNode;
+}
+
+/**
+ * Wrap a subtree to override the navigation backend used by router hooks.
+ */
+export function RouterAdapterProvider({ value, children }: RouterAdapterProviderProps) {
+  // Memoizing here is the consumer's job (the value usually comes from another hook).
+  // We don't double-memo — that just adds noise.
+  return (
+    <RouterAdapterContext.Provider value={value}>
+      {children}
+    </RouterAdapterContext.Provider>
+  );
+}
+
+/**
+ * Read the active router adapter. Returns the default History API adapter
+ * if no provider is mounted.
+ */
+export function useRouterAdapter(): RouterAdapter {
+  const ctx = useContext(RouterAdapterContext);
+  // useMemo so consumers can put the returned value in deps without churn.
+  return useMemo(() => ctx ?? defaultAdapter, [ctx]);
+}

package/src/hooks/router/adapters/index.ts

@@ -0,0 +1,5 @@
+// Adapters live behind sub-path imports so framework-specific peer
+// deps (next, react-router, etc.) load only when the consumer asks
+// for them. Do NOT re-export adapters from the package barrel — that
+// would force every consumer to resolve all peer deps.
+export type {} from '../adapter';

package/src/hooks/router/adapters/nextjs.tsx

@@ -0,0 +1,100 @@
+'use client';
+
+/**
+ * Next.js adapter — bridges our framework-agnostic router hooks
+ * to `next/navigation` so server components, route loaders, and
+ * `prefetch` all fire correctly.
+ *
+ * USAGE:
+ *   Mount once near the root of the App Router tree, e.g. inside
+ *   the locale layout's client provider stack:
+ *
+ *   ```tsx
+ *   import { NextRouterAdapter } from '@djangocfg/ui-core/adapters/nextjs';
+ *
+ *   <I18nProvider locale={locale} messages={messages}>
+ *     <NextRouterAdapter>
+ *       <AppLayout>{children}</AppLayout>
+ *     </NextRouterAdapter>
+ *   </I18nProvider>
+ *   ```
+ *
+ *   Without this provider, our hooks fall back to the History API
+ *   adapter — which works in plain SPAs (Wails, Electron, Vite, CRA)
+ *   but in Next.js means: no server component refetch on navigation,
+ *   no route loader, no prefetch. So always mount it in Next apps.
+ *
+ * PEER DEPENDENCY:
+ *   `next` is an OPTIONAL peer of @djangocfg/ui-core. The base package
+ *   never imports from `next/*`. This sub-path entry does — so it only
+ *   loads when the consumer explicitly imports `/adapters/nextjs`.
+ *   Wails / Electron consumers: don't import this file and `next` is
+ *   never resolved.
+ */
+
+import { useMemo, type ReactNode } from 'react';
+import { useRouter as useNextRouter } from 'next/navigation';
+
+import {
+  RouterAdapterProvider,
+  type RouterAdapter,
+  type RouterLocation,
+} from '../adapter';
+
+const SSR_LOCATION: RouterLocation = Object.freeze({
+  pathname: '/',
+  search: '',
+  hash: '',
+});
+
+export interface NextRouterAdapterProps {
+  children: ReactNode;
+  /**
+   * Pass `scroll: false` to every Next router call by default.
+   * Useful for filter/pagination apps where the page should never
+   * jump on URL changes. Default: undefined (use Next's own default).
+   */
+  defaultScroll?: boolean;
+}
+
+/**
+ * Wraps a subtree so all `@djangocfg/ui-core/hooks` router calls go
+ * through Next's App Router. Server components, loaders, and prefetch
+ * keep working as if you used `next/navigation` directly.
+ */
+export function NextRouterAdapter({
+  children,
+  defaultScroll,
+}: NextRouterAdapterProps) {
+  const next = useNextRouter();
+
+  const adapter = useMemo<RouterAdapter>(
+    () => ({
+      push(url) {
+        next.push(url, defaultScroll === undefined ? undefined : { scroll: defaultScroll });
+      },
+      replace(url) {
+        next.replace(url, defaultScroll === undefined ? undefined : { scroll: defaultScroll });
+      },
+      back() {
+        next.back();
+      },
+      forward() {
+        next.forward();
+      },
+      getLocation() {
+        if (typeof window === 'undefined') return SSR_LOCATION;
+        return {
+          pathname: window.location.pathname,
+          search: window.location.search,
+          hash: window.location.hash,
+        };
+      },
+    }),
+    [next, defaultScroll]
+  );
+
+  return (
+    <RouterAdapterProvider value={adapter}>{children}</RouterAdapterProvider>
+  );
+}

package/src/hooks/router/index.ts

@@ -0,0 +1,90 @@
+// ============================================================================
+// Router hooks — framework-agnostic navigation primitives.
+// See ./README.md for design rationale and Next.js adapter example.
+// ============================================================================
+
+'use client';
+
+// Adapter (context + provider + default + types)
+export {
+  RouterAdapterContext,
+  RouterAdapterProvider,
+  defaultAdapter,
+  useRouterAdapter,
+} from './adapter';
+export type {
+  RouterAdapter,
+  RouterAdapterProviderProps,
+  RouterLocation,
+} from './adapter';
+
+// useLocation (+ per-property subscription)
+export {
+  useLocation,
+  useLocationProperty,
+  NAVIGATE_EVENT,
+  PUSH_STATE_EVENT,
+  REPLACE_STATE_EVENT,
+} from './useLocation';
+export type { LocationSnapshot } from './useLocation';
+
+// useNavigate
+export { useNavigate } from './useNavigate';
+export type { NavigateOptions, UseNavigateReturn } from './useNavigate';
+
+// useQueryParams
+export { useQueryParams } from './useQueryParams';
+export type {
+  QueryParamsSnapshot,
+  QueryParamValue,
+  QueryParamUpdates,
+  SetQueryParamsOptions,
+  UseQueryParamsReturn,
+} from './useQueryParams';
+
+// useBackOrFallback
+export { useBackOrFallback } from './useBackOrFallback';
+export type { UseBackOrFallbackReturn } from './useBackOrFallback';
+
+// useUrlBuilder (+ pure helpers)
+export { useUrlBuilder, buildUrl, buildQueryString } from './useUrlBuilder';
+export type {
+  QueryValue,
+  QueryParamsInput,
+  UseUrlBuilderReturn,
+} from './useUrlBuilder';
+
+// useSmartLink
+export { useSmartLink } from './useSmartLink';
+export type {
+  UseSmartLinkOptions,
+  SmartLinkHandlers,
+} from './useSmartLink';
+
+// useIsActive
+export { useIsActive } from './useIsActive';
+export type { UseIsActiveOptions } from './useIsActive';
+
+// useQueryState (typed single-key URL state, nuqs-style)
+export { useQueryState } from './useQueryState';
+export type {
+  UseQueryStateOptions,
+  QueryStateUpdater,
+} from './useQueryState';
+
+// Parsers (typed marshalling between URL strings and JS values)
+export {
+  parseAsString,
+  parseAsInteger,
+  parseAsFloat,
+  parseAsBoolean,
+  parseAsIsoDate,
+  parseAsStringEnum,
+  parseAsArrayOf,
+  parseAsJson,
+} from './parsers';
+export type { QueryParser, QueryParserBuilder } from './parsers';
+
+// useRouter (composite facade)
+export { useRouter } from './useRouter';
+export type { UseRouterReturn } from './useRouter';