@plumile/router 0.1.11 → 0.1.13

package/README.md

@@ -37,6 +37,9 @@ import { Route, getResourcePage } from '@plumile/router';
 const routes: Route<any, any>[] = [
   {
     path: '/',
+
+  ## Advanced Hooks Deep Dive & Combined Examples
+
     resourcePage: getResourcePage('Home', () => import('./pages/Home')),
   },
   {
@@ -111,13 +114,15 @@ function Navigation() {
 
 ### Core Components
 
-#### `createRouter(routes: Route[])`
+#### `createRouter(routes: Route[], options?)`
 
 Creates a router instance with the given route configuration.
 
 **Parameters:**
 
 - `routes`: Array of route definitions
+- `options?`: Optional object
+  - `devtools?: boolean` Force enable/disable the global inspector. Defaults to enabled when `NODE_ENV !== 'production'`, disabled otherwise.
 
 **Returns:**
 
@@ -142,6 +147,9 @@ Navigation component that handles client-side routing.
 
 - `to`: string - Destination path
 - `exact?`: boolean - Exact path matching for active state
+
+### Combined Example: Products Listing Page
+
 - `activeClassName?`: string - CSS class when link is active
 - `className?`: string - Base CSS class
 - `preload?`: boolean - Preload route on hover
@@ -228,6 +236,669 @@ Type helper for strongly-typed route definitions.
 
 ## Advanced Usage
 
+### Typed Query Parameters (DSL)
+
+The router provides a lightweight schema DSL for parsing, typing, normalizing and serializing query strings.
+
+#### 1. Define a schema on the deepest route
+
+```ts
+import { q, r } from '@plumile/router';
+
+const routes = [
+  r({
+    path: '/items',
+    // Schema: page = number (default 1), tag(s) = array of strings, flag = optional boolean
+    query: {
+      page: q.default(q.number(), 1),
+      tags: q.array(q.string()),
+      flag: q.optional(q.boolean()),
+    },
+    prepare: ({ query }) => {
+      // query is typed: { page: number; tags: string[]; flag?: boolean }
+      return { page: query.page };
+    },
+    render: () => null,
+  }),
+];
+```
+
+#### 2. Access parsed & typed queries
+
+```tsx
+import { useQuery, useTypedQuery } from '@plumile/router';
+
+function List() {
+  const raw = useQuery(); // Record<string, string | string[]>
+  const typed = useTypedQuery(); // Auto‑inferred from deepest route schema (no generic needed)
+  const [page, setPage] = useQueryState<number>('page'); // Bidirectional state ↔ URL for one param
+  return <pre>{JSON.stringify({ raw, typed }, null, 2)}</pre>;
+}
+```
+
+Referential stability: both `raw` (from `useQuery()`) and `typed` (from `useTypedQuery()`) are memoized per canonical search string. If the URL search part doesn't change semantically (including key order canonicalization), the hook returns the exact same object reference. You can safely list either in React dependency arrays without extra `useMemo` or a hypothetical `useStableQuery` helper (not needed).
+
+Type inference:
+
+- If the matched deepest route has a `query` schema, `useTypedQuery()` returns the inferred `InferQuery<typeof schema>` shape automatically.
+- If no schema exists, it returns the raw parsed object (record of string | string[]) so you can still read values safely.
+- You can still supply a generic manually (`useTypedQuery<MyShape>()`) in edge cases (e.g. incremental migration) but it is usually unnecessary now.
+
+#### 3. Programmatic navigation with typed query
+
+```tsx
+import { useNavigate } from '@plumile/router';
+
+function Pager({ page }: { page: number }) {
+  const navigate = useNavigate();
+  return (
+    <button
+      onClick={() => {
+        navigate({ query: { page: page + 1 } });
+      }}
+    >
+      Next page
+    </button>
+  );
+}
+```
+
+#### 4. Link component with query
+
+```tsx
+import { Link } from '@plumile/router';
+
+<Link to="/items" query={{ page: 2, tags: ['a', 'b'], flag: true }}>
+  Filter
+</Link>;
+```
+
+`Link` & `navigate` automatically serialize using the route schema, applying:
+
+- Schema key order
+- Array repetition (`?tags=a&tags=b`)
+- Omission of default values when `omitDefaults` optimization applies internally
+
+#### 5. Normalization
+
+Built‑in simple normalization currently clamps `page < 1` to `1` and issues a `replaceState` to avoid polluting history.
+
+#### 6. Serialization utility
+
+```ts
+import { buildSearch, q } from '@plumile/router';
+
+const schema = {
+  page: q.default(q.number(), 1),
+  tag: q.array(q.string()),
+} as const;
+const search = buildSearch({ page: 1, tag: ['x', 'y'] }, schema, {
+  omitDefaults: true,
+});
+// => '?tag=x&tag=y'
+```
+
+#### 7. Parsing utility / alias
+
+```ts
+import { parseSearch, q } from '@plumile/router';
+
+const schema = { flag: q.boolean() } as const;
+const typed = parseSearch(schema, '?flag=1'); // { flag: true }
+```
+
+#### 8. Performance and stability
+
+There are two coordinated caching layers:
+
+1. Raw query cache: A process-wide Map keyed by a canonicalized search string (sorted keys, ordered value emission). Produces a frozen empty object for the empty search and reuses prior parsed objects, yielding stable references for unchanged search state.
+2. Typed query cache: A WeakMap keyed by (schema reference → canonical search signature) that parses once and reuses the typed value. Structural deep-equality canonicalization means semantically equivalent searches (e.g. reordered keys) reuse object identity.
+
+Effects:
+
+- Stable object identity for both raw and typed queries eliminates needless renders and removes the need for an extra `useStableQuery` hook.
+- Safe to put `useQuery()` / `useTypedQuery()` results directly in dependency arrays (`useEffect`, `useMemo`, selectors, etc.).
+- Empty query allocations are avoided (shared frozen object).
+
+Guideline: If you need to derive lightweight projections (e.g. `const { page } = typed`), you can still destructure; but avoid spreading into a new object if you rely on reference equality downstream.
+
+#### Devtools / Inspection
+
+In development (`NODE_ENV !== 'production'` by default, or when `createRouter(..., { devtools: true })` is passed), the router exposes a lightweight global inspector.
+
+Optionally you can enable an in‑page overlay panel for quick visual inspection:
+
+```ts
+createRouter(routes, {
+  devtools: { panel: true, global: true, shortcut: 'Alt+Shift+R' },
+});
+```
+
+Devtools option forms:
+
+- `devtools: true | false` (boolean) – legacy form, controls global only.
+- `devtools: { global?: boolean; panel?: boolean; shortcut?: string }` – granular.
+  - `global` (default: NODE_ENV !== 'production') exposes `window.__PLUMILE_ROUTER__`.
+  - `panel` (default: false) mounts an overlay; closed with the close button or page reload.
+  - `shortcut` (default: `Alt+Shift+R`) toggles panel visibility.
+
+The panel displays current path+search, variables, raw query and typed query. It is intentionally framework‑agnostic (no React runtime cost) and uses a shadow root to minimize style collisions.
+
+```js
+window.__PLUMILE_ROUTER__.get(); // current RouteEntry
+const unsub = window.__PLUMILE_ROUTER__.subscribe((entry) =>
+  console.log(entry.typedQuery),
+);
+```
+
+This lets you introspect parsed queries & variables without adding debug code. Neither global nor panel is present in production unless explicitly forced with `devtools: { global: true, panel: true }` (discouraged).
+
+##### Detailed Usage
+
+The global is intentionally tiny to avoid coupling and bundle weight. It only appears when the devtools flag resolves truthy:
+
+1. Explicit: `createRouter(routes, { devtools: true })`
+2. Implicit heuristic: `NODE_ENV !== 'production'`
+3. Disabled explicitly: `createRouter(routes, { devtools: false })`
+
+Always guard in snippets that might be copied to production code:
+
+```js
+if (window.__PLUMILE_ROUTER__) {
+  console.log(window.__PLUMILE_ROUTER__.get());
+}
+```
+
+`get()` returns the current `RouteEntry` (simplified shape):
+
+```ts
+type RouteEntry = {
+  location: Location; // window.location snapshot
+  route: { match; params; path } | null; // current matched route (or null)
+  preparedMatch: { routes: { prepared; render?; resourcePage? }[]; match }; // internal prepared tree
+  forceRerender: boolean; // indicates forced re-render situations
+  rawSearch: string; // '?page=2&tag=a'
+  query: Record<string, string | string[]>; // raw aggregated query params
+  typedQuery: any; // typed query if schema present
+};
+```
+
+Common console patterns:
+
+1. Log every navigation with typed query & params:
+
+```js
+const dev = window.__PLUMILE_ROUTER__;
+if (dev) {
+  const off = dev.subscribe((e) => {
+    console.log('[router]', e.location.pathname + e.location.search, {
+      vars: e.route?.params,
+      typed: e.typedQuery,
+    });
+  });
+  // later: off();
+}
+```
+
+2. Inspect prepared data for the deepest route (last element):
+
+```js
+const entry = window.__PLUMILE_ROUTER__?.get();
+const deepest = entry?.preparedMatch.routes.at(-1);
+deepest?.prepared; // Prepared data returned by deepest prepare()
+```
+
+3. Quick diff watcher for query changes only:
+
+```js
+let last = window.__PLUMILE_ROUTER__?.get().rawSearch;
+const off = window.__PLUMILE_ROUTER__?.subscribe((e) => {
+  if (e.rawSearch !== last) {
+    console.log('query changed', last, '=>', e.rawSearch, e.typedQuery);
+    last = e.rawSearch;
+  }
+});
+```
+
+4. Measuring parse performance (rough dev-only micro‑benchmark):
+
+```js
+const { get } = window.__PLUMILE_ROUTER__;
+const before = performance.now();
+for (let i = 0; i < 200; i++) get().typedQuery; // use cache; ensures no GC
+console.log('elapsed ms', performance.now() - before);
+```
+
+5. Safe optional chaining helper (copy/paste):
+
+```js
+const R = window.__PLUMILE_ROUTER__;
+R && R.subscribe((e) => console.debug('[typedQuery]', e.typedQuery));
+```
+
+Unsubscribing: every `subscribe` returns a disposer function. Always call it if you set up long‑lived listeners in a debugging session to avoid memory leaks during hot reloads.
+
+Extending: if you need more (e.g. trigger navigations) you can wrap `createRouter` in your app and attach additional methods to `window.__PLUMILE_ROUTER__` (e.g. `navigate: context.navigate`) — omitted by default to avoid accidental production reliance.
+
+Production: the symbol is not defined; accessing it will yield `undefined`. Never ship logic depending on it; keep usage inside `if (process.env.NODE_ENV !== 'production')` blocks or guarded optional checks.
+
+### ESLint Rule: no-direct-window-location-search
+
+To encourage consistent usage of the query hooks, a custom rule is provided inside the router package to flag raw `window.location.search` access.
+
+Add to your flat ESLint config:
+
+````js
+import noDirectWindowLocationSearch from '@plumile/router/lib/eslint-rules/no-direct-window-location-search.js';
+
+export default [
+  {
+
+## Batched Navigation & Provisional typedQuery Contract
+
+The router supports two batching modes:
+
+- Manual batching: pass `batch: true` in successive `navigate` calls within the same microtask.
+- Auto batching: enable `createRouter(routes, { autoBatch: true })` and omit `immediate: true` to coalesce navigations scheduled in the same microtask.
+
+During a batched sequence, the final history update (a single `push`/`set`) is deferred to a queued microtask. Some code (tests, imperative flows) may need to synchronously observe the merged query state before the flush occurs. To support this, the router performs a provisional in‑memory update of the current route entry on each batched `navigate`:
+
+Guarantees (provisional phase):
+
+1. `context.get()` returns an entry whose `location.search`, `rawSearch`, `query` (raw parsed) and `typedQuery` reflect the merged state of all batched calls so far.
+2. Each additional batched call merges query keys (last write wins) and overwrites the entire filters object (they are considered atomic state) before recomputing `typedQuery`.
+3. The provisional `typedQuery` uses the deepest route schema of the eventual target pathname (if a batched navigation changes pathname, subsequent calls resolve the schema for that new path).
+4. Normalization (e.g. clamping `page < 1`) is only applied at the final flush listener step; the provisional `typedQuery` may briefly contain unnormalized values until flush.
+5. Subscribers (`context.subscribe`) are **not** notified until the actual history update fires (asynchronously). Reading inside the same tick requires using `context.get()` directly, not relying on subscription callbacks.
+
+Non‑guarantees / caveats:
+
+- If you read `window.location.search` directly (discouraged) during a batch it will still show the pre‑batch URL; use the entry returned by `context.get()`.
+- If later batched calls change the pathname, earlier provisional `typedQuery` objects become stale; always re‑read after your final batched mutation if you need the merged result.
+- Filters batching (from `useFilters` helpers) coalesces multiple `set/patch/clear` calls in the same microtask via an internal microtask queue. These feed into the outer navigation batching so a burst of filter helper calls plus other `navigate` calls still produce a single history entry.
+
+Edge cases:
+
+- Calling `navigate({ immediate: true })` inside an active batch forces an immediate flush, bypassing batching for that specific call.
+- Interleaving manual `batch: true` and autoBatch calls: if autoBatch is enabled and you explicitly pass `batch: false`, that call flushes immediately; otherwise the presence of any manual `batch: true` call within the tick keeps coalescing active until flush.
+
+Recommended usage pattern inside effects or event handlers:
+
+```ts
+// Multiple logical updates unified into 1 URL change
+context.navigate({ query: { page: 1 }, batch: true });
+context.navigate({ filters: { status: { in: ['active'] } }, filterSchema, batch: true });
+context.navigate({ query: { tag: 'green' }, batch: true });
+// Synchronous inspection (provisional)
+const merged = context.get().typedQuery; // already includes page=1, tag=green, status filter
+````
+
+Testing note: tests asserting final URL should poll or await a microtask / tick rather than expecting synchronous `window.location.search` updates when batching is involved.
+
+Future evolution: if normalization or additional query transformations grow more complex, the provisional recompute will remain a best‑effort mirror; code relying on _final_ normalized values should subscribe or await the flush boundary.
+
+Summary: Provisional batching gives synchronous, allocation‑minimal read access to the in‑flight merged query & typedQuery without sacrificing a single history entry – use `context.get()` for immediate reads, and rely on subscriptions or hooks for React render updates.
+
+## Route-Level Filter Schemas
+
+Attach a `filterSchema` to routes to progressively declare filterable fields along the hierarchy. Parent → child schemas are shallow merged; fields defined later override earlier ones by name.
+
+Example:
+
+```ts
+import { r, defineFilters, numberFilter, stringFilter } from '@plumile/router';
+
+export const routes = [
+  r({
+    path: '/products',
+    filterSchema: defineFilters({
+      price: numberFilter({ operators: ['gte', 'lte'] }),
+    }),
+    children: [
+      r({
+        path: '/:id',
+        filterSchema: defineFilters({
+          name: stringFilter({ operators: ['contains'] }),
+        }),
+      }),
+    ],
+  }),
+];
+```
+
+Merged result for `/products/123` is `{ price, name }` definitions. Currently, implicit serialization of new filter values still requires passing `{ filters, filterSchema }` in a navigate/helper call; the route-level merged schema is used for parsing existing keys. This keeps mutations explicit. A future enhancement may allow omitting `filterSchema` when adding new filter values on a route that already declares one.
+
+Rules:
+
+- Order: shallow override by field name.
+- No deep merge inside a field definition.
+- Omitted routes: ignored.
+
+Limitations / current behavior:
+
+- Initial merged schema is internal; helpers still need explicit schema to serialize new filter state.
+- Empty filters object with route-level schema is treated as “no change” (no extra keys added).
+
+Planned: implicit mode & devtools visualization of merged filter schema chain.
+plugins: {
+'@plumile-router/dx': {
+rules: {
+'no-direct-window-location-search': noDirectWindowLocationSearch,
+},
+},
+},
+rules: {
+'@plumile-router/dx/no-direct-window-location-search': 'warn',
+},
+},
+];
+
+````
+
+Optional configuration:
+
+```js
+// allow some files (e.g. legacy bootstrap) to keep direct access
+rules: {
+  '@plumile-router/dx/no-direct-window-location-search': [
+    'warn',
+    { allowInFiles: ['legacy-entry.ts'] },
+  ],
+},
+````
+
+When triggered, replace patterns like:
+
+```ts
+const qs = window.location.search;
+```
+
+with:
+
+```ts
+const query = useQuery(); // or useTypedQuery()
+```
+
+### Migration Guide (Phases 1 → 5)
+
+1. Phase 1/2: Upgrade — no schema needed. Use `useQuery()` for raw params.
+2. Phase 3: Add `query` schema to your deepest route; adopt `useTypedQuery()` where type safety is desirable.
+3. Phase 4: Replace manual URL building with `navigate({ query })` or `<Link query={...} />`. Remove ad‑hoc serialization logic.
+4. Phase 5: Move lightweight data loading logic that depends on query into `prepare({ query })` (now typed). Rely on built‑in normalization (e.g. page clamp) or add custom normalization inside `prepare` followed by a `navigate({ replace: true, query: normalized })` if needed.
+5. Optional: Use `buildSearch` / `parseSearch` for unit tests & utilities.
+
+### Query Descriptor Reference
+
+| Descriptor                       | Description                                         | Serialize Example                    |
+| -------------------------------- | --------------------------------------------------- | ------------------------------------ |
+| `q.string()`                     | Last occurrence string                              | `{ q: 'x' } -> ?q=x`                 |
+| `q.number()`                     | Number (invalid => undefined)                       | `{ n: 2 } -> ?n=2`                   |
+| `q.boolean()`                    | Presence / true/false/1/0                           | `{ f: true } -> ?f=1`                |
+| `q.enum('a','b')`                | Restricted string                                   | `{ e: 'a' } -> ?e=a`                 |
+| `q.array(inner)`                 | Repeated key multi-values                           | `{ tag: ['x','y'] } -> ?tag=x&tag=y` |
+| `q.optional(d)`                  | Marks descriptor optional                           | omitted if undefined                 |
+| `q.default(d, v)`                | Supplies default + omit on serialize (omitDefaults) | default skipped                      |
+| `q.emptyAsUndefined(q.string())` | Maps empty string '' to undefined                   | omitted                              |
+| `q.custom({ parse, serialize })` | Custom parse/serialize logic                        | depends                              |
+
+Custom: `q.custom({ parse(values), serialize(value) })` lets you wire bespoke formats. Ensure `serialize` outputs an array of raw string values. Use sparingly to keep schemas readable.
+
+### useQueryState Hook
+
+`useQueryState(key, opts?)` creates a controlled binding between a single query parameter and component state.
+
+```tsx
+const [page, setPage] = useQueryState<number>('page');
+// Increment page without pushing a new history entry
+setPage(page! + 1, { replace: true });
+```
+
+Behavior:
+
+- Reads from typedQuery if schema present, else raw query.
+- Respects schema defaults (and `defaultValue` override in options) and omits key when value equals default (with `omitIfDefault: true`).
+- Pass `{ raw: true }` to force raw (string) source for incremental migrations.
+- Uses existing navigation serialization (ordering, omit defaults, arrays).
+
+Options:
+`{ defaultValue?, omitIfDefault?: boolean = true, replace?: boolean, raw?: boolean }`
+
+### Filters DSL (Experimental Advanced Filtering)
+
+Structured multi‑operator filtering can be expressed via query keys using the pattern `field.operator`.
+
+1. Define a schema
+
+```ts
+import { defineFilters, numberFilter, stringFilter } from '@plumile/router';
+
+export const filters = defineFilters({
+  price: numberFilter(), // numeric: eq, neq, gt, gte, lt, lte, in, nin, between, exists
+  status: stringFilter({ operators: ['eq', 'in', 'nin'] }),
+  name: stringFilter({ operators: ['contains', 'starts', 'ends'] }),
+  // Provide default operator values to omit them from serialization when matched
+  availability: numberFilter({
+    operators: ['exists'],
+    defaults: { exists: true },
+  }),
+  priceRange: numberFilter({
+    operators: ['between'],
+    defaults: { between: [[0, 100]] },
+  }),
+});
+```
+
+2. Read & update filters
+
+```tsx
+import { useFilters } from '@plumile/router';
+
+function Products() {
+  const [f, { patch, clear }] = useFilters(filters);
+  // f.price.gt => number[] | undefined
+  // f.status.in => string[] | undefined
+  return (
+    <button
+      onClick={() => {
+        patch({ price: { gt: [10] } });
+      }}
+    >
+      Price &gt; 10
+    </button>
+  );
+}
+```
+
+3. Narrow to a single operator
+
+```tsx
+import { useFilterState } from '@plumile/router';
+
+function PriceGt() {
+  const [gt, setGt] = useFilterState(filters, 'price', 'gt');
+  return (
+    <input
+      value={gt?.[0] ?? ''}
+      onChange={(e) => setGt([Number(e.target.value)])}
+    />
+  );
+}
+```
+
+4. Supported operators
+
+| Kind   | Operators                                                                            |
+| ------ | ------------------------------------------------------------------------------------ |
+| number | eq, neq, gt, gte, lt, lte, in, nin, between (tuples), exists                         |
+| string | eq, neq, in, nin, between (tuples of strings), exists, contains, starts, ends, regex |
+
+`exists` expects a boolean; presence of key defaults to `true` if value unrecognized.
+
+5. Query string format
+
+```
+?price.gt=10&price.between=10&price.between=20&price.between=30&price.between=40&status.in=active&status.in=pending
+```
+
+6. Between operator
+
+Pairs of values create ranges: four values → two ranges. Odd final value is ignored.
+
+7. Clearing
+
+`clear()` → remove all filters. `clear(['price'])` → remove only price.\* keys.
+
+8. Patching
+
+`patch({ price: { gt: [20], between: [[10,20]] } })` merges at field level, replacing individual operator arrays.
+
+9. Serialization rules
+
+- Previous filter keys (`field.op`) are dropped before adding new ones.
+- Multiple values produce repeated keys (same as existing query arrays).
+- Boolean `exists` serialized as `1` / `0`.
+- Optional omission of default operator values: if a filter definition supplies a `defaults` object
+  (e.g. `{ defaults: { gt: [10] } }` or `{ defaults: { exists: true } }`), and the current operator
+  value is shallow‑equal to that default, the `field.operator` key is skipped during serialization.
+  Applies to array operators (exact ordered match) and `exists` boolean. `between` defaults compare
+  tuple pairs (`[[a,b]]`) element-wise.
+
+10. Type inference
+
+`InferFilters<typeof filters.schema>` gives `{ price: { gt?: number[]; between?: [number, number][]; ... } }`.
+
+11. Opt‑in / Backward Compatible
+
+No change to existing query parameter behavior. Filter keys are just additional query entries; legacy code reading raw `useQuery()` continues to function.
+
+12. Limitations / Future
+
+- Sorting deliberately excluded (would be separate DSL).
+- No date operator specialization yet.
+- Regex values are passed through verbatim (URL decoding handled upstream).
+- Default omission currently uses shallow equality (ordered array match). For number arrays
+  canonicalization (sorting + optional dedupe) happens prior to comparison, ensuring stable omission.
+
+Tests cover parsing (including multiple ranges) and building; extend as needed for your domain.
+
+### New Hooks (Phase 4)
+
+#### `useQueryObject(opts?)`
+
+High-level accessor returning the entire current query object (typed when the matched deepest route declares a `query` schema). It also returns a stable setter that merges partial updates.
+
+```tsx
+import { useQueryObject } from '@plumile/router';
+
+function Panel() {
+  const [query, setQuery] = useQueryObject({ omitDefaults: true });
+  // query: typed (if schema) else raw record
+  return (
+    <button
+      onClick={() => {
+        setQuery({ page: (query.page ?? 1) + 1 });
+      }}
+    >
+      Next page
+    </button>
+  );
+}
+```
+
+Options:
+
+- `raw?: boolean` Use aggregated raw query even if a schema exists.
+- `replace?: boolean` Default navigation mode for all subsequent `setQuery` calls.
+- `omitDefaults?: boolean` When true, schema keys whose value equals their declared default are omitted from the URL.
+
+Setter semantics:
+
+- Accepts an object or function `(prev) => next`.
+- Keys set to `undefined` are removed from the URL.
+- Partial objects are shallow‑merged with previous query state (post-merge omission rules are applied if `omitDefaults` is enabled).
+
+#### `useActiveFilters(filterSchema)`
+
+Returns a flat array of currently active filter operator entries derived from the structured filters state returned by `useFilters`.
+
+```tsx
+import { useActiveFilters } from '@plumile/router';
+import { filters } from './filters-schema';
+
+function ActiveChips() {
+  const active = useActiveFilters(filters);
+  return (
+    <ul>
+      {active.map((f) => (
+        <li key={f.field + f.operator}>
+          {f.field}.{f.operator}: {f.values.join(', ')}
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+Each entry: `{ field: string; operator: string; values: any[] }` where `values` is the already normalized array (for non‑array primitives a singleton array is produced). Empty arrays / undefined operators are skipped.
+
+#### `useNavigateWithQuery(opts?)`
+
+Convenience wrapper combining current query (typed if possible) with partial updates before invoking `navigate`.
+
+```tsx
+import { useNavigateWithQuery } from '@plumile/router';
+
+function Incrementer() {
+  const update = useNavigateWithQuery({ omitDefaults: true });
+  return (
+    <button
+      onClick={() => {
+        update((prev) => ({ page: (prev.page ?? 1) + 1 }));
+      }}
+    >
+      Next
+    </button>
+  );
+}
+```
+
+Behavior:
+
+- Reads existing (typed or raw) query as base.
+- Accepts object or functional update.
+- Keys set to `undefined` are removed.
+- `omitDefaults` removes schema-default valued keys.
+- `raw` forces ignoring the schema (raw aggregation base).
+- `replace` option (global or per call) controls history mode.
+
+#### `useStableRefEquality(value, areEqual?)`
+
+Utility hook that preserves the reference of the latest value (object or array) as long as shallow equality holds. When a new value is passed whose own enumerable keys (and their primitive or reference-equal values) match the previous one, the previous stable reference is returned. If they differ, the new value becomes the stored reference.
+
+Designed for niche interop cases (e.g. passing derived objects to dependency arrays of third-party hooks) where you can't or don't want the upstream producer to handle memoization. Most consumers of the router do NOT need this because `useQuery`, `useTypedQuery`, `useFilters` already return stable references.
+
+```ts
+import { useStableRefEquality } from '@plumile/router';
+
+function Chart({ data }) {
+  // Avoid re-renders in a heavy child when parent recreates equivalent arrays
+  const stableData = useStableRefEquality(data);
+  return <ExpensiveChart data={stableData} />;
+}
+```
+
+Custom comparator:
+
+```ts
+const value = useStableRefEquality(complex, (a, b) => deepCustomCompare(a, b));
+```
+
+Notes:
+
+- Only shallow by default (no deep traversal) for perf.
+- Non-object/array inputs are returned as-is (no caching layer needed).
+- Avoid overuse; prefer structuring code so sources themselves are stable.
+
 ### Data Preloading
 
 ```typescript
@@ -275,6 +946,89 @@ function MyComponent() {
 }
 ```
 
+### Navigation With Filters & Batching (Phase 5)
+
+You can atomically update query parameters and structured filters via the extended `navigate` API and related hooks.
+
+```tsx
+import {
+  useNavigate,
+  useFilters,
+  defineFilters,
+  numberFilter,
+} from '@plumile/router';
+
+const filterSchema = defineFilters({ price: numberFilter() });
+
+function PriceBump() {
+  const navigate = useNavigate();
+  const [filters, { patch }] = useFilters(filterSchema);
+  return (
+    <button
+      onClick={() => {
+        // Update both query & filters in a single URL change
+        navigate({
+          query: { page: 1 },
+          filters: { price: { gt: [10] } },
+          filterSchema,
+        });
+      }}
+    >
+      Apply
+    </button>
+  );
+}
+```
+
+Batch multiple navigations issued during the same micro‑task into _one_ history update by passing `batch: true`:
+
+```tsx
+function ComplexMutation() {
+  const navigate = useNavigate();
+  return (
+    <button
+      onClick={() => {
+        navigate({ query: { page: 1 }, batch: true });
+        navigate({
+          filters: { price: { gt: [20] } },
+          filterSchema,
+          batch: true,
+        });
+        navigate({
+          filters: { price: {} /* clear price */ },
+          filterSchema,
+          batch: true,
+        });
+        // All three coalesce into one push
+      }}
+    >
+      Run sequence
+    </button>
+  );
+}
+```
+
+Hooks `useQueryObject` and `useFilters` also accept a `batch` flag in their nav options:
+
+```tsx
+const [query, setQuery] = useQueryObject();
+const [f, { patch, clear }] = useFilters(filterSchema);
+
+// Coalesce three operations
+setQuery({ page: 2 }, { batch: true });
+patch({ price: { gt: [30] } }, { batch: true });
+clear(['price'], { batch: true });
+```
+
+Notes:
+
+- Batching is opt‑in: default behavior is immediate navigation (backward compatible).
+- The last non‑undefined `replace` flag wins inside a batch group.
+- The last provided `query` object and `filters` snapshot in the batch are used for serialization.
+- Provide `filterSchema` whenever you include `filters`.
+
+`buildSearch(query, schema, { filters, filterSchema })` merges filters deterministically with query keys (schema‑ordered keys first, then extras).
+
 ### Route Preloading
 
 ```tsx