react-routes-forge 1.1.3 → 1.3.0

package/README.md

@@ -1,12 +1,14 @@
 # react-routes-forge
 
-**Type-safe route definitions with automatic path builders for React apps.**
+**Type-safe route definitions, automatic path builders, query parameter handling, and active route matching for React applications with zero duplication.**
 
-One source of truth for your routes — templates for `<Route path={...} />` and typed builders for navigation — with no duplication and no manual string concatenation.
+📖 **[Documentation](https://mhsmustafa84.github.io/react-routes-forge)** | 🚀 **[Live Demo (POC)](https://mhsmustafa84.github.io/react-routes-forge-poc)**
 
+[![Documentation](https://img.shields.io/badge/Documentation-VitePress-646cff.svg)](https://mhsmustafa84.github.io/react-routes-forge)
+[![Live Demo](https://img.shields.io/badge/Live%20Demo-POC-brightgreen.svg)](https://mhsmustafa84.github.io/react-routes-forge-poc)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](#license)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](#)
-[![Node.js 24+](https://img.shields.io/badge/Node.js-24+-green.svg)](#requirements)
+[![Node.js 18+](https://img.shields.io/badge/Node.js-18+-green.svg)](#requirements)
 [![Combined CI/CD](https://github.com/mhsmustafa84/react-routes-forge/actions/workflows/ci-security.yml/badge.svg)](https://github.com/mhsmustafa84/react-routes-forge/actions/workflows/ci-security.yml)
 
 ---
@@ -17,20 +19,30 @@ One source of truth for your routes — templates for `<Route path={...} />` and
 - [Installation](#installation)
 - [Quick start](#quick-start)
 - [Cheat sheet](#cheat-sheet)
-- [Core concepts](#core-concepts)
 - [API reference](#api-reference)
   - [`defineRoutes(routeMap)`](#defineroutesroutemap)
   - [`build(template, params, query?, options?)`](#buildtemplate-params-query-options)
   - [`isActivePath(currentPath, template, options?)`](#isactivepathcurrentpath-template-options)
   - [`extractParamsFromPath(template, resolvedPath)`](#extractparamsfrompathtemplate-resolvedpath)
+  - [`matchPath(template, options?)`](#matchpathtemplate-options)
   - [`joinPaths(...segments)`](#joinpathssegments)
   - [`getParamNames(template)`](#getparamnamestemplate)
   - [`flattenRoutes(routes)`](#flattenroutesroutes)
+  - [`getBreadcrumbs(routes, currentPath, options?)`](#getbreadcrumbsroutes-currentpath-options)
+  - [`appendQuery(path, query?, hash?)`](#appendquerypath-query-hash)
+  - [`extractQueryFromPath(path, options?)`](#extractqueryfrompathpath-options)
+  - [`devWarn(message)`](#devwarnmessage)
+  - [`clearPathCache()`](#clearpathcache)
 - [React hooks](#react-hooks)
   - [`useRouteParams<T>()`](#useroutparamst)
   - [`useNavigateTo()`](#usenavigateto)
   - [`useResolvedPath(template, params, query?, options?)`](#useresolvedpathtemplate-params-query-options)
+  - [`useActivePath(template, options?)`](#useactivepathtemplate-options)
+  - [`useTypedSearchParams(options?)`](#usetypedsearchparamsoptions)
+- [Splat (`/*`) segments](#splat--segments)
+- [Route validation](#route-validation)
 - [Query string support](#query-string-support)
+- [Hash fragment support](#hash-fragment-support)
 - [Strict mode](#strict-mode)
 - [Migrating from the old pattern](#migrating-from-the-old-pattern)
 - [Known behaviours & gotchas](#known-behaviours--gotchas)
@@ -79,7 +91,7 @@ You get:
 - **Single source of truth** — no duplicate template/builder pairs to keep in sync
 - **Compile-time param safety** — `.build()` is typed from the path string itself; missing or misspelled params are TypeScript errors
 - **Query string support** — built into `.build()`, no manual `URLSearchParams` wrangling
-- **Zero runtime dependencies** for the core API — React Router is an optional peer dependency, only required if you use the hooks
+- **Zero runtime dependencies** for the core API
 - **Deep nesting supported out of the box** — organize routes into as many nested groups as your app needs
 
 ---
@@ -96,19 +108,7 @@ yarn add react-routes-forge
 bun add react-routes-forge
 ```
 
-React Router is an **optional** peer dependency — only needed if you use the bundled hooks (`useRouteParams`, `useNavigateTo`, `useResolvedPath`).
-
-```bash
-npm install react-router-dom   # only if you're using the hooks
-# or
-pnpm add react-router-dom
-# or
-yarn add react-router-dom
-# or
-bun add react-router-dom
-```
-
-> **Note:** this package ships ESM-only. See [Known behaviours & gotchas](#known-behaviours--gotchas) for details.
+> **Note:** this package ships dual **ESM + CommonJS** builds. See [Known behaviours & gotchas](#known-behaviours--gotchas) for details.
 
 ---
 
@@ -133,6 +133,8 @@ export const PATHS = defineRoutes({
 } as const);
 ```
 
+> **Always pass `as const`** — it preserves the literal string types that power `.build()`'s compile-time param checking. Without it, TypeScript widens your path strings to generic `string` and you lose type safety.
+
 ```tsx
 // App.tsx — static paths and dynamic templates both work directly as strings
 import { Routes, Route } from "react-router-dom";
@@ -146,46 +148,76 @@ import { PATHS } from "./paths";
 </Routes>;
 ```
 
-```ts
+```tsx
 // Navigating — call .build() to resolve a dynamic path into a real URL
-navigate(PATHS.USERS.EDIT.build({ id: 42 })); // '/users/edit/42'
-navigate(PATHS.ROLES.PERMISSIONS.build({ name: "admin" })); // '/roles/permissions/admin'
-navigate(PATHS.HOME); // '/'
+import { useNavigate } from "react-router-dom";
+
+function MyComponent() {
+  const navigate = useNavigate();
+  //                    ↓ Param type-checked from the template ":id"
+  navigate(PATHS.USERS.EDIT.build({ id: 42 })); // → '/users/edit/42'
+  navigate(PATHS.ROLES.PERMISSIONS.build({ name: "admin" })); // → '/roles/permissions/admin'
+  navigate(PATHS.HOME); // → '/'  (static paths work directly)
+}
 ```
 
 That's the entire API surface you need for most apps. Everything below covers the rest of the toolkit.
 
----
+### Route types
 
-## Cheat sheet
+| Route type  | Example                 | Behaves as                              | Gains                                                                 |
+| ----------- | ----------------------- | --------------------------------------- | --------------------------------------------------------------------- |
+| **Static**  | `HOME: '/'`             | String-like (coercible to its template) | `.build(query?, options?)` — attach query/hash, no params to fill      |
+| **Dynamic** | `DETAILS: '/users/:id'` | String-like (coercible to its template) | `.build(params, query?, options?)` and `.paramNames`                  |
+| **Splat**   | `FILES: '/files/*'`     | String-like (coercible to its template) | `.build(params, query?, options?)` and `.paramNames`                  |
 
-Quick reference for everything the package exports. Click through to the full section for details and examples.
+`defineRoutes()` walks your route object recursively, wrapping every path in a string-coercible object and attaching a `.build()` helper so both static and dynamic routes can carry a query string or hash. Dynamic paths (containing a `:param` segment or a trailing `/*` splat) additionally gain `.paramNames`.
 
-| Export                                                                                         | Kind     | Purpose                                                   |
-| ---------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------- |
-| [`defineRoutes(routeMap)`](#defineroutesroutemap)                                              | function | Builds the typed `PATHS` object from a nested route map   |
-| [`build(template, params, query?, options?)`](#buildtemplate-params-query-options)             | function | Resolve a template into a URL without `defineRoutes`      |
-| [`isActivePath(currentPath, template, options?)`](#isactivepathcurrentpath-template-options)   | function | Check if a path matches a template (nav-highlighting)     |
-| [`extractParamsFromPath(template, resolvedPath)`](#extractparamsfrompathtemplate-resolvedpath) | function | Pull param values back out of a resolved URL              |
-| [`joinPaths(...segments)`](#joinpathssegments)                                                 | function | Join and normalize path segments                          |
-| [`getParamNames(template)`](#getparamnamestemplate)                                            | function | List the `:param` names in a template                     |
-| [`flattenRoutes(routes)`](#flattenroutesroutes)                                                | function | Flatten a `PATHS` tree for sitemaps / duplicate detection |
-| [`useRouteParams<T>()`](#useroutparamst)                                                       | hook     | Typed wrapper around React Router's `useParams`           |
-| [`useNavigateTo()`](#usenavigateto)                                                            | hook     | Typed wrapper around React Router's `useNavigate`         |
-| [`useResolvedPath(...)`](#useresolvedpathtemplate-params-query-options)                        | hook     | Resolve a template to a string without navigating         |
-| `.build(params, query?, options?)`                                                             | method   | On every dynamic route — resolves to a concrete URL       |
-| `.paramNames`                                                                                  | property | On every dynamic route — the param names it expects       |
+Param names are `[A-Za-z0-9_]` only (matching React Router), so a static suffix after a param stays literal — `/files/:name.json` builds `{ name: "report" }` → `/files/report.json`, and `:name.json` is **not** treated as a single param name.
 
----
+> `defineRoutes()` also validates your templates in development — missing leading `/`, non-trailing `*`, and duplicate path templates all produce a `console.warn`. See [Route validation](#route-validation).
 
-## Core concepts
+---
 
-| Route type  | Example                 | Behaves as                              | Gains                                                |
-| ----------- | ----------------------- | --------------------------------------- | ---------------------------------------------------- |
-| **Static**  | `HOME: '/'`             | Plain string primitive                  | Nothing extra — use it directly                      |
-| **Dynamic** | `DETAILS: '/users/:id'` | String-like (coercible to its template) | `.build(params, query?, options?)` and `.paramNames` |
+## Cheat sheet
 
-`defineRoutes()` walks your route object recursively, leaving static paths untouched and wrapping any path containing a `:param` segment so it can carry a builder alongside its template string.
+Quick reference for everything the package exports — grouped by kind. Click through to the full section for details and examples.
+
+### Route definition
+
+| Export                                            | Purpose                                                 |
+| ------------------------------------------------- | ------------------------------------------------------- |
+| [`defineRoutes(routeMap)`](#defineroutesroutemap) | Builds the typed `PATHS` object from a nested route map |
+| `.build(query?, options?)`                        | On every **static** route — attach query string / hash  |
+| `.build(params, query?, options?)`                | On every **dynamic** route — resolves to a concrete URL |
+| `.paramNames`                                     | On every dynamic route — the param names it expects     |
+
+### Utilities
+
+| Export                                                                                         | Purpose                                                    |
+| ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| [`build(template, params, query?, options?)`](#buildtemplate-params-query-options)             | Resolve a template into a URL without `defineRoutes`       |
+| [`isActivePath(currentPath, template, options?)`](#isactivepathcurrentpath-template-options)   | Check if a path matches a template (nav-highlighting)      |
+| [`extractParamsFromPath(template, resolvedPath)`](#extractparamsfrompathtemplate-resolvedpath) | Pull param values back out of a resolved URL               |
+| [`matchPath(template, options?)`](#matchpathtemplate-options)                                 | Convert a route template into an anchored `RegExp`         |
+| [`joinPaths(...segments)`](#joinpathssegments)                                                 | Join and normalize path segments                           |
+| [`getParamNames(template)`](#getparamnamestemplate)                                            | List the `:param` names in a template                      |
+| [`flattenRoutes(routes)`](#flattenroutesroutes)                                                | Flatten a `PATHS` tree for sitemaps / duplicate detection  |
+| [`getBreadcrumbs(routes, currentPath, options?)`](#getbreadcrumbsroutes-currentpath-options)   | Build a breadcrumb trail from a route tree and current URL |
+| [`appendQuery(path, query?, hash?)`](#appendquerypath-query-hash)                              | Append query params / hash to an existing path             |
+| [`extractQueryFromPath(path, options?)`](#extractqueryfrompathpath-options)                    | Parse a query string back into an object                   |
+| [`devWarn(message)`](#devwarnmessage)                                                          | Emit a `console.warn` in non-production builds             |
+| [`clearPathCache()`](#clearpathcache)                                                         | Reset internal regex caches (mainly for tests)             |
+
+### React hooks
+
+| Export                                                                  | Purpose                                                       |
+| ----------------------------------------------------------------------- | ------------------------------------------------------------- |
+| [`useRouteParams<T>()`](#useroutparamst)                                | Typed wrapper around React Router's `useParams`               |
+| [`useNavigateTo()`](#usenavigateto)                                     | Typed wrapper around React Router's `useNavigate`             |
+| [`useResolvedPath(...)`](#useresolvedpathtemplate-params-query-options) | Resolve a template to a string without navigating             |
+| [`useActivePath(template, options?)`](#useactivepathtemplate-options)   | Check if the current location matches a route template        |
+| [`useTypedSearchParams(options?)`](#usetypedsearchparamsoptions)        | Typed `useSearchParams` with boolean/number coercion          |
 
 ---
 
@@ -195,10 +227,11 @@ Quick reference for everything the package exports. Click through to the full se
 
 Creates a fully typed route object from a nested plain object.
 
-- Static paths are returned as-is — use them directly anywhere a string is expected (e.g. `<Route path={...} />`).
-- Dynamic paths (containing `:param`) gain:
+- Every path is string-coercible — use it directly anywhere a string is expected (e.g. `<Route path={...} />`).
+- Static paths gain **`.build(query?, options?)`** — attach a query string and/or hash fragment without params.
+- Dynamic paths (containing `:param`) and splat paths (trailing `/*`) gain:
   - **`.build(params, query?, options?)`** — resolves the template into a concrete URL
-  - **`.paramNames`** — array of the param names extracted from the template, e.g. `['id']`
+  - **`.paramNames`** — array of the param names extracted from the template, e.g. `['id']` (a splat is reported as `['*']`)
 
 Nesting is unlimited — organize routes into as many groups and sub-groups as your app needs.
 
@@ -206,16 +239,21 @@ Nesting is unlimited — organize routes into as many groups and sub-groups as y
 const PATHS = defineRoutes({
   SERVICES: {
     ROOT: "/services",
-    BENEFICIARY_CARE_CENTER: {
-      DETAILS: "/services/beneficiary-care-center/:id",
-      EDIT: "/services/beneficiary-care-center/edit/:id",
+    SUPPORT_CENTER: {
+      DETAILS: "/services/support-center/:id",
+      EDIT: "/services/support-center/edit/:id",
     },
   },
 } as const);
 
 PATHS.SERVICES.ROOT; // '/services'
-PATHS.SERVICES.BENEFICIARY_CARE_CENTER.EDIT.build({ id: 7 }); // '/services/beneficiary-care-center/edit/7'
-PATHS.SERVICES.BENEFICIARY_CARE_CENTER.EDIT.paramNames; // ['id']
+PATHS.SERVICES.SUPPORT_CENTER.EDIT.build({ id: 7 }); // '/services/support-center/edit/7'
+PATHS.SERVICES.SUPPORT_CENTER.EDIT.build(
+  { id: 7 },
+  { tab: "info" },
+  { hash: "details" },
+); // → '/services/support-center/edit/7?tab=info#details'
+PATHS.SERVICES.SUPPORT_CENTER.EDIT.paramNames; // ['id']
 ```
 
 > Always pass `as const` to `defineRoutes()` — it preserves the literal string types that power `.build()`'s compile-time param checking.
@@ -224,7 +262,7 @@ PATHS.SERVICES.BENEFICIARY_CARE_CENTER.EDIT.paramNames; // ['id']
 
 ### `build(template, params, query?, options?)`
 
-Standalone path resolver — for building a URL without going through `defineRoutes`, or for adding a query string to a **static** path (which has no `.build()` of its own).
+Standalone path resolver — for building a URL without going through `defineRoutes`, or for resolving a raw template string (rather than a route from a `PATHS` tree).
 
 ```ts
 import { build } from "react-routes-forge";
@@ -239,13 +277,40 @@ build("/users", {}, { sort: "asc" });
 // Strict mode — throw instead of warn when a param is missing
 build("/users/:id", {}, undefined, { strict: true });
 // ✗ throws RangeError: [route-forge] Missing required param(s) ":id" in template "/users/:id".
+
+// Hash fragment — appended after the query string
+build("/users/:id", { id: 42 }, { tab: "info" }, { hash: "details" });
+// → '/users/42?tab=info#details'
+build("/page", {}, undefined, { hash: "section" });
+// → '/page#section'
+```
+
+**Param values are URL-encoded by default** (`encodeURIComponent`), so characters like `/`, `?`, `#`, or `%` in a value can't break the URL structure:
+
+```ts
+build("/search/:query", { query: "a/b" });
+// → '/search/a%2Fb'
+
+// Pass { encode: false } if a value is already encoded
+build("/search/:query", { query: "a%2Fb" }, undefined, { encode: false });
+// → '/search/a%2Fb'
+
+// Splat segments capture a path-like remainder, preserving `/` separators
+build("/files/*", { "*": "reports/2026/q1" });
+// → '/files/reports/2026/q1'
 ```
 
+See [Splat (`/*`) segments](#splat--segments) for details.
+
 ---
 
 ### `isActivePath(currentPath, template, options?)`
 
-Checks whether a resolved path matches a route template — the building block for nav-highlighting ("is this link active?"). Query strings on `currentPath` are ignored automatically.
+Checks whether a resolved path matches a route template — the building block for nav-highlighting ("is this link active?"). Query strings on `currentPath` are ignored automatically. It mirrors React Router's `NavLink` matching semantics:
+
+- **Case-insensitive by default** — pass `{ caseSensitive: true }` to opt out.
+- **Trailing slashes are tolerated** — `/users/` matches `/users`.
+- **`exact: true` (default)** requires a full match; **`exact: false`** matches any path that starts with the template (so `/` matches every path as a prefix).
 
 ```ts
 import { isActivePath } from "react-routes-forge";
@@ -254,6 +319,9 @@ isActivePath("/users/42", "/users/:id"); // true
 isActivePath("/users/42/posts", "/users/:id"); // false (exact match by default)
 isActivePath("/users/42/posts", "/users/:id", { exact: false }); // true  (prefix match)
 isActivePath("/users/42?tab=profile", "/users/:id"); // true  (query string ignored)
+isActivePath("/Users/42", "/users/:id"); // true  (case-insensitive by default)
+isActivePath("/Users/42", "/users/:id", { caseSensitive: true }); // false
+isActivePath("/users/42/", "/users/:id"); // true  (trailing slash tolerated)
 ```
 
 A common real-world use — highlighting the active nav link:
@@ -289,6 +357,33 @@ extractParamsFromPath("/a/:x/b/:y", "/a/foo/b/bar");
 
 ---
 
+### `matchPath(template, options?)`
+
+Converts a route template string into an anchored `RegExp` — useful when you need custom matching logic beyond [`isActivePath`](#isactivepathcurrentpath-template-options) or [`extractParamsFromPath`](#extractparamsfrompathtemplate-resolvedpath). Query strings are **not** stripped; split on `"?"` first if needed.
+
+```ts
+import { matchPath } from "react-routes-forge";
+
+const re = matchPath("/users/:id");
+re.test("/users/42"); // true
+re.exec("/users/42"); // ['/users/42', '42']
+re.test("/users/42/posts"); // false (exact match only)
+```
+
+**Options:**
+
+- **`end?: boolean`** (default `true`) — anchor the pattern to the end of the path. Pass `false` to match a prefix at a segment boundary (`/users` matches `/users/42` but not `/usersettings`).
+- **`caseSensitive?: boolean`** (default `false`) — match case-insensitively by default; pass `true` to opt out.
+
+```ts
+matchPath("/users/:id", { end: false }).test("/users/42/posts"); // true
+matchPath("/Users/42", { caseSensitive: true }).test("/users/42"); // false
+```
+
+This is the building block used internally by `isActivePath` and `extractParamsFromPath`.
+
+---
+
 ### `joinPaths(...segments)`
 
 Safely joins path segments, normalizing duplicate/missing slashes.
@@ -310,6 +405,7 @@ Returns the list of param names present in a template string.
 import { getParamNames } from "react-routes-forge";
 
 getParamNames("/users/:id/posts/:postId"); // → ['id', 'postId']
+getParamNames("/files/*"); // → ['*']  (the splat param)
 getParamNames("/users"); // → []
 ```
 
@@ -362,16 +458,148 @@ it("has no duplicate route paths", () => {
 
 ---
 
+### `getBreadcrumbs(routes, currentPath, options?)`
+
+Walks a route tree (or a pre-flattened array from `flattenRoutes()`) and returns every route that is an ancestor of (or an exact match to) the current URL. Dynamic params in ancestor paths are automatically resolved from the matched portion of the URL. Query strings on `currentPath` are ignored.
+
+Each breadcrumb entry contains:
+
+- **`key`** — the dot-joined key from the route tree (e.g. `"USERS.EDIT"`)
+- **`label`** — a human-readable label derived from the key (e.g. `"USERS.ROOT"` → `"Users"`, `"USERS.EDIT"` → `"Edit"`)
+- **`path`** — the resolved breadcrumb path with params filled in (e.g. `"/users/edit/42"`)
+- **`isCurrent`** — `true` only for the deepest (exact) match
+
+```ts
+import { defineRoutes, getBreadcrumbs } from "react-routes-forge";
+
+const PATHS = defineRoutes({
+  HOME: "/",
+  USERS: {
+    ROOT: "/users",
+    EDIT: "/users/edit/:id",
+  },
+  SERVICES: {
+    BCC: {
+      EDIT: "/services/bcc/edit/:id",
+    },
+  },
+} as const);
+
+getBreadcrumbs(PATHS, "/users/edit/42");
+// →
+// [
+//   { key: "HOME",       label: "Home",  path: "/",             isCurrent: false },
+//   { key: "USERS.ROOT", label: "Users", path: "/users",        isCurrent: false },
+//   { key: "USERS.EDIT", label: "Edit",  path: "/users/edit/42", isCurrent: true  },
+// ]
+```
+
+**Custom label resolver** — override the default key-to-label conversion:
+
+```ts
+getBreadcrumbs(PATHS, "/users/edit/42", {
+  labelResolver: (key) =>
+    key.split(".").pop()!.replace(/_/g, " ").toUpperCase(),
+});
+// → [{ label: "HOME" }, { label: "ROOT" }, { label: "EDIT" }]
+```
+
+**Label map** — the ergonomic alternative for a handful of overrides. Keys are dot-joined route keys; matching keys take precedence over `labelResolver`:
+
+```ts
+getBreadcrumbs(PATHS, "/users/edit/42", {
+  labels: { "USERS.ROOT": "Members", "USERS.EDIT": "Edit member" },
+});
+// → [{ label: "Home" }, { label: "Members" }, { label: "Edit member" }]
+```
+
+**Pre-flattened input** — pass a cached `flattenRoutes()` result instead of the tree:
+
+```ts
+const flat = flattenRoutes(PATHS);
+getBreadcrumbs(flat, "/users/edit/42"); // same result as passing the tree
+```
+
+---
+
+### `appendQuery(path, query?, hash?)`
+
+Appends a query string and/or hash fragment to a path that may already contain a query or hash. Existing query pairs are preserved, the query is inserted before any hash, and an existing hash is kept unless a new one is given.
+
+```ts
+import { appendQuery } from "react-routes-forge";
+
+appendQuery("/users?tab=list", { page: 2 }); // → '/users?tab=list&page=2'
+appendQuery("/users#top", { tab: "list" }); // → '/users?tab=list#top'
+appendQuery("/users", { active: true }); // → '/users?active=true'
+appendQuery("/users", { tag: ["a", "b"] }); // → '/users?tag=a&tag=b'
+```
+
+This is the same helper every path-resolving function uses internally.
+
+---
+
+### `extractQueryFromPath(path, options?)`
+
+Parses the query string out of a path (or bare query string) back into a plain object. Repeated keys become arrays; single keys are scalar strings.
+
+**Options:**
+
+- **`coerceBooleans?: boolean`** — convert the strings `"true"`/`"false"` to real booleans.
+- **`coerceNumbers?: boolean`** — convert numeric strings (`"42"`, `"3.14"`) to real numbers.
+
+```ts
+import { extractQueryFromPath } from "react-routes-forge";
+
+extractQueryFromPath("/users/42?tab=profile&tag=a&tag=b");
+// → { tab: "profile", tag: ["a", "b"] }
+
+extractQueryFromPath("/search?active=true", { coerceBooleans: true });
+// → { active: true }
+
+extractQueryFromPath("/search?page=2&limit=10", { coerceNumbers: true });
+// → { page: 2, limit: 10 }
+```
+
+---
+
+### `devWarn(message)`
+
+Emits a `console.warn` in non-production environments. Shared by the core utilities and `defineRoutes()` so the production check lives in one place.
+
+```ts
+import { devWarn } from "react-routes-forge";
+
+devWarn("[route-forge] Something looks wrong.");
+// → console.warn in dev/test, silent in production bundles
+```
+
+---
+
+### `clearPathCache()`
+
+Clears the internal regex caches used by `matchPath()` / prefix matching. Primarily useful in test suites to prevent cached patterns from leaking across test cases.
+
+```ts
+import { clearPathCache } from "react-routes-forge";
+
+beforeEach(() => {
+  clearPathCache();
+});
+```
+
+---
+
 ## React hooks
 
-Import these only if you're using React Router — they're tree-shakeable and won't be bundled unless imported.
+Import these only if you're using React Router — they live in a separate `react-routes-forge/hooks` entry, so the core package never pulls in `react-router-dom`.
 
 ### `useRouteParams<T>()`
 
-Typed wrapper around React Router's `useParams`. Pass the route's template string as a generic to get a correctly typed params object back — no casting, and it works for any number of `:param` segments.
+Typed wrapper around React Router's `useParams`. Pass the route's template string as a generic to get a correctly typed params object back — no casting, and it works for any number of `:param` segments. Alternatively, pass a **dynamic route value from your `PATHS` tree** and the params are inferred from it automatically:
 
 ```tsx
-import { useRouteParams } from "react-routes-forge";
+import { useRouteParams } from "react-routes-forge/hooks";
 
 // Route: '/users/edit/:id'
 function EditUser() {
@@ -386,6 +614,13 @@ function Comment() {
     useRouteParams<"/posts/:postId/comments/:commentId">();
   // ...
 }
+
+// Or pass a route from your PATHS tree — types are inferred:
+const PATHS = defineRoutes({ USERS: { EDIT: "/users/edit/:id" } } as const);
+function EditUserInferred() {
+  const { id } = useRouteParams(PATHS.USERS.EDIT);
+  // ...
+}
 ```
 
 ---
@@ -395,7 +630,7 @@ function Comment() {
 Thin, typed wrapper around `useNavigate()` that accepts a resolved path (the output of `.build()`) along with the usual navigation options.
 
 ```tsx
-import { useNavigateTo } from "react-routes-forge";
+import { useNavigateTo } from "react-routes-forge/hooks";
 import { PATHS } from "./paths";
 
 function Component() {
@@ -416,10 +651,10 @@ navigateTo(PATHS.USERS.ROOT, { state: { from: "settings" } });
 
 ### `useResolvedPath(template, params, query?, options?)`
 
-Resolves a path template to a concrete URL string without navigating — useful for `<Link to={...} />`, preloading, or building a URL for something other than `navigate()`. Backed by React Router's `generatePath`, so it correctly supports splat (`*`) and optional (`:param?`) segments. Accepts the same `query` and `options` as [`build()`](#buildtemplate-params-query-options).
+Resolves a path template to a concrete URL string without navigating — useful for `<Link to={...} />`, preloading, or building a URL for something other than `navigate()`. It mirrors the library's own [`build()`](#buildtemplate-params-query-options), so splat (`*`) and optional (`:param?`) segments work identically to the core API — and the encoding/`strict` behaviour is consistent across React Router v6 and v7. Accepts the same `query` and `options` as [`build()`](#buildtemplate-params-query-options).
 
 ```tsx
-import { useResolvedPath } from "react-routes-forge";
+import { useResolvedPath } from "react-routes-forge/hooks";
 
 const path = useResolvedPath("/users/:id", { id: 42 });
 // → '/users/42'
@@ -427,8 +662,117 @@ const path = useResolvedPath("/users/:id", { id: 42 });
 const path = useResolvedPath("/users/:id", { id: 42 }, { tab: "info" });
 // → '/users/42?tab=info'
 
+// Splat segments are preserved
+const path = useResolvedPath("/files/*", { "*": "a/b/c" });
+// → '/files/a/b/c'
+
 // Strict mode — throws RangeError instead of warning on missing params
 const path = useResolvedPath("/users/:id", {}, undefined, { strict: true });
+
+// With hash fragment
+const path = useResolvedPath("/page", {}, undefined, { hash: "section" });
+// → '/page#section'
+```
+
+---
+
+### `useActivePath(template, options?)`
+
+A hook that checks whether the current location matches a route template or path — a thin wrapper around [`isActivePath()`](#isactivepathcurrentpath-template-options) that reads the location from the router. Same matching semantics: case-insensitive by default, trailing slashes tolerated, `exact: true` by default.
+
+```tsx
+import { useActivePath } from "react-routes-forge/hooks";
+
+function Nav() {
+  const isUsersActive = useActivePath(PATHS.USERS.ROOT, { exact: false });
+  const isProfileActive = useActivePath("/users/:id", { caseSensitive: true });
+
+  return (
+    <Link className={isUsersActive ? "active" : ""} to={PATHS.USERS.ROOT}>
+      Users
+    </Link>
+  );
+}
+```
+
+---
+
+### `useTypedSearchParams(options?)`
+
+A typed wrapper around React Router's `useSearchParams`. Returns a parsed query params object (using [`extractQueryFromPath()`](#extractqueryfrompathpath-options)) and a setter that updates the query string. The same coercion options are supported: `{ coerceBooleans: true }` and `{ coerceNumbers: true }`.
+
+```tsx
+import { useTypedSearchParams } from "react-routes-forge/hooks";
+
+function Filters() {
+  const [query, setQuery] = useTypedSearchParams({
+    coerceBooleans: true,
+    coerceNumbers: true,
+  });
+
+  // query.page is a number when the URL is '/search?page=2'
+  const nextPage = (query.page ?? 0) + 1;
+  setQuery({ ...query, page: nextPage });
+
+  // Clear a filter by omitting it (or pass null/undefined)
+  setQuery({ page: 1, sort: "asc" });
+}
+```
+
+---
+
+## Splat (`/*`) segments
+
+Splat routes (`/files/*`) capture the rest of the path — including slashes — into a single `*` param, matching React Router semantics. Supported across the entire core API, not just the hooks.
+
+```ts
+import { defineRoutes, build, isActivePath, extractParamsFromPath } from "react-routes-forge";
+
+const PATHS = defineRoutes({
+  FILES: "/files/*",
+} as const);
+
+PATHS.FILES.build({ "*": "reports/2026/q1" }); // → '/files/reports/2026/q1'
+String(PATHS.FILES); // → '/files/*'
+PATHS.FILES.paramNames; // → ['*']
+```
+
+Behaviour notes:
+
+- **Slashes in the value are preserved** (they're path separators); other special characters are still URL-encoded — `"/files/*"` with `"a b/c?d"` → `"/files/a%20b/c%3Fd"`.
+- **A missing splat value drops the `/*` suffix** — `/files/*` resolves to `/files` (matching React Router, where the splat route also matches the base path).
+- `isActivePath("/files/a/b", "/files/*")` → `true`; `extractParamsFromPath("/files/*", "/files/a/b")` → `{ "*": "a/b" }`.
+- A splat must be **trailing** (`/files/*`). A `*` in the middle of a path is invalid and produces a dev warning (see below).
+
+---
+
+## Route validation
+
+`defineRoutes()` validates every template in development (no-op in production) and warns via `console.warn` about likely mistakes:
+
+| Problem | Example | Warning |
+| ------- | ------- | ------- |
+| Missing leading `/` | `"users/:id"` | `does not start with "/"` |
+| Non-trailing splat | `"/files/*/extra"` | `*` outside a trailing `"/*"` |
+| Duplicate path template | `FOO: "/foo"` and `BAR: "/foo"` | `Duplicate route path "/foo"` (names both keys) |
+| Static route shadowed by a dynamic route above it | `DETAILS: "/users/:id"` defined before `ME: "/users/me"` | `"ME" is shadowed by dynamic route "DETAILS"` |
+
+```ts
+// duplicate route paths are caught at startup instead of as a routing bug later
+defineRoutes({
+  A: { FOO: "/foo" },
+  B: { FOO: "/foo" },
+} as const);
+// ⚠ console.warn: [route-forge] Duplicate route path "/foo" for "A.FOO" and "B.FOO". Only one of them will be reachable.
+```
+
+These are warnings, not errors — invalid routes still build, so a broken definition can't crash your app at import time. Run a stricter check once in tests if you want duplicates to fail the build:
+
+```ts
+it("has no duplicate route paths", () => {
+  const paths = flattenRoutes(PATHS).map((r) => r.path);
+  expect(paths).toEqual([...new Set(paths)]);
+});
 ```
 
 ---
@@ -451,6 +795,13 @@ build("/search", {}, { tags: ["admin", "moderator"] });
 // → '/search?tags=admin&tags=moderator'
 ```
 
+**Boolean values** serialize to `"true"`/`"false"`:
+
+```ts
+build("/search", {}, { active: true, draft: false });
+// → '/search?active=true&draft=false'
+```
+
 **`null` and `undefined` values are dropped**, so you can pass optional filters without conditionally building the object:
 
 ```ts
@@ -458,15 +809,51 @@ build("/users", {}, { sort: "asc", filter: undefined });
 // → '/users?sort=asc'
 ```
 
-Static routes don't have a fluent `.build()` (there's nothing to interpolate), so use the standalone `build()` util to attach a query string to them:
+Static routes have a `.build()` too — there are no params to interpolate, but you can still attach a query string or hash:
 
 ```ts
-import { build } from "react-routes-forge";
+PATHS.USERS.ROOT.build({ sort: "asc", page: 2 });
+// → '/users?sort=asc&page=2'
 
+// The standalone build() util works the same way for raw templates:
+import { build } from "react-routes-forge";
 build(PATHS.USERS.ROOT, {}, { sort: "asc", page: 2 });
 // → '/users?sort=asc&page=2'
 ```
 
+Reading query params back out is handled by [`extractQueryFromPath(path, options?)`](#extractqueryfrompathpath-options), and appending to an existing URL (e.g. a link with pre-set filters) by [`appendQuery(path, query?, hash?)`](#appendquerypath-query-hash).
+
+---
+
+## Hash fragment support
+
+URL hash fragments (`#section`) are supported in every path-resolving function — `.build()`, `build()`, and `useResolvedPath()` — via the `hash` option. The hash is appended after the query string, if any.
+
+```ts
+// Via fluent .build() on a dynamic route
+PATHS.USERS.DETAILS.build({ id: 42 }, undefined, { hash: "profile" });
+// → '/users/42#profile'
+
+// With query + hash
+PATHS.USERS.DETAILS.build({ id: 42 }, { tab: "info" }, { hash: "details" });
+// → '/users/42?tab=info#details'
+
+// Via standalone build()
+build("/page", {}, undefined, { hash: "section" });
+// → '/page#section'
+
+// Via useResolvedPath
+useResolvedPath(
+  "/users/:id",
+  { id: 5 },
+  { tab: "billing" },
+  { hash: "invoice" },
+);
+// → '/users/5?tab=billing#invoice'
+```
+
+The leading `#` is added automatically — pass just the fragment name (e.g. `"details"`, not `"#details"`).
+
 ---
 
 ## Strict mode
@@ -543,30 +930,30 @@ Everywhere the template string itself was used (e.g. `<Route path={PATHS.SERVICE
 
 ## Known behaviours & gotchas
 
-### Dynamic routes are `String` objects, not primitives
+### Routes are `String` objects, not primitives
 
-`defineRoutes` wraps dynamic paths in [`String` objects](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/String) so that `.build()` and `.paramNames` can be attached as properties. This means:
+`defineRoutes` wraps **every** path — static, dynamic, and splat — in [`String` objects](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/String) so that `.build()` (and `.paramNames` on dynamic routes) can be attached as properties. This means:
 
 ```ts
 // ✓ These all work as expected
-String(PATHS.USERS.EDIT); // '/users/edit/:id'
+String(PATHS.HOME); // '/'
 `${PATHS.USERS.EDIT}`; // '/users/edit/:id'
 PATHS.USERS.EDIT == "/users/edit/:id"; // true  (loose equality)
 
 // ✗ Watch out for these
-typeof PATHS.USERS.EDIT; // 'object' ← not 'string'
-PATHS.USERS.EDIT === "/users/edit/:id"; // false    ← strict equality fails
+typeof PATHS.HOME; // 'object' ← not 'string'
+PATHS.HOME === "/"; // false    ← strict equality fails
 ```
 
-Prefer template literals or explicit `String()` coercion when comparing dynamic route values, and avoid using them as plain object/`Map` keys. Static routes (`HOME`, `USERS.ROOT`, …) remain genuine string primitives and are unaffected.
+Prefer template literals or explicit `String()` coercion when comparing route values, and avoid using them as plain object/`Map` keys.
 
 ### `useResolvedPath` vs. the library's own `buildPath`
 
-`useResolvedPath` delegates to React Router's `generatePath` when all params are present, which correctly handles splat (`*`) and optional (`:param?`) segments that the library's own regex-based substitution does not. If params are missing, it falls back to the same `buildPath`/strict-mode behaviour described above — so failure modes stay consistent, but full splat/optional support is only guaranteed via the hook, not via `.build()`.
+`useResolvedPath` is a thin wrapper around the library's own `buildPath`, so splat (`*`), optional (`:param?`) and encoding behaviour are identical across every entry point — and consistent across React Router v6 and v7 (v7's `generatePath` URL-encodes values itself, which would otherwise double-encode).
 
-### ESM-only package
+### ESM + CommonJS builds
 
-This package ships **ESM only** (`"type": "module"`, no `require` export condition). Consumers on a plain CommonJS setup (`require('react-routes-forge')`) are not supported. All modern bundlers (Vite, Webpack ≥ 5, esbuild, Rollup) handle ESM packages transparently. If you're in a CJS-only environment, you'll need a bundler transform or a compatibility shim.
+This package ships both **ESM and CommonJS** bundles (`dist/index.js` for ESM, `dist/index.cjs` for CJS), with `exports` conditions routing each environment to the right format. Modern bundlers use the ESM build; Node.js `require()` gets the CommonJS build automatically. Consumers on plain CommonJS are fully supported.
 
 ---
 
@@ -582,15 +969,29 @@ PATHS.USERS.EDIT.build({ userId: 42 }); // ✗ compile error — 'id' expected,
 
 `.paramNames` is similarly typed as a literal array of the exact param names in the template, not a generic `string[]`.
 
+To annotate a plain route object (e.g. a shared constant used by `defineRoutes()`), import the `RouteTree` type:
+
+```ts
+import type { RouteTree } from "react-routes-forge";
+
+const routes: RouteTree = {
+  HOME: "/",
+  USERS: { ROOT: "/users", EDIT: "/users/edit/:id" },
+};
+```
+
+The result of `defineRoutes()` is typed as `ResolvedRoutes`, and individual leaves are `StaticRoute<T>` (static paths, with `.build(query?, options?)`) or `DynamicRoute<T>` (dynamic/splat paths, with `.build(params, ...)` and `.paramNames`) — all exported as types if you need to reference them. `MatchPathOptions` types the [`matchPath()`](#matchpathtemplate-options) options bag.
+
 ---
 
 ## Testing
 
-The package ships with a full test suite covering the core builder/utility functions and the React hooks, including strict-mode behaviour, query string edge cases (arrays, `null`/`undefined` filtering), nested route groups, and duplicate-path detection via `flattenRoutes`.
+The package ships with a full test suite covering the core builder/utility functions and the React hooks, including strict-mode behaviour, query string edge cases (arrays, booleans, `null`/`undefined` filtering), splat segments, route validation, nested route groups, and duplicate-path detection.
 
 ```bash
-npm test            # run the full suite once
-npm run test:watch  # watch mode
+npm test                # run the full suite once (bun test)
+npm run test:watch      # watch mode
+npm run test:coverage   # run with coverage (vitest + v8, outputs lcov.info)
 
 # equivalent with other package managers
 pnpm test / pnpm test:watch
@@ -598,6 +999,8 @@ yarn test / yarn test:watch
 bun test / bun test:watch
 ```
 
+CI runs the suite across a **matrix of Node.js versions (18 / 20 / 22 / 24)** and **React Router v6 and v7**, plus lint, a production build, and a coverage job that uploads `lcov.info` as a build artifact (see `.github/workflows/ci-security.yml`).
+
 If you're contributing, new behaviour should come with a matching test — the existing suite is organized by function/hook, so add cases alongside the relevant `describe` block rather than starting a new file.
 
 ---
@@ -605,7 +1008,7 @@ If you're contributing, new behaviour should come with a matching test — the e
 ## Requirements
 
 - **React** ≥ 17 (peer dependency)
-- **react-router-dom** ≥ 6 (optional peer dependency — required only for the bundled hooks)
+- **react-router-dom** ≥ 6 (optional peer dependency — required only for the `react-routes-forge/hooks` entry)
 - **Node.js** ≥ 18
 - **TypeScript** ≥ 5 recommended for full type inference (the package works with plain JavaScript too, just without compile-time param checking)