@real-router/search-schema-plugin 0.0.1

package/README.md

@@ -0,0 +1,183 @@
+# @real-router/search-schema-plugin
+
+[![npm](https://img.shields.io/npm/v/@real-router/search-schema-plugin.svg?style=flat-square)](https://www.npmjs.com/package/@real-router/search-schema-plugin)
+[![npm downloads](https://img.shields.io/npm/dm/@real-router/search-schema-plugin.svg?style=flat-square)](https://www.npmjs.com/package/@real-router/search-schema-plugin)
+[![bundle size](https://deno.bundlejs.com/?q=@real-router/search-schema-plugin&treeshake=[*]&badge=detailed)](https://bundlejs.com/?q=@real-router/search-schema-plugin&treeshake=[*])
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](../../LICENSE)
+
+> Validate and sanitize route search parameters at runtime using any [Standard Schema V1](https://github.com/standard-schema/standard-schema)-compatible library in [Real-Router](https://github.com/greydragon888/real-router).
+
+```typescript
+// Without plugin — tampered URL params reach your app unvalidated:
+// User visits: /products?page=-1&limit=99999
+router.getState().params; // { page: -1, limit: 99999 } — crashes pagination
+
+// With plugin — invalid params stripped, route defaults restored automatically:
+router.usePlugin(searchSchemaPlugin());
+// User visits: /products?page=-1&limit=99999
+router.getState().params; // { page: 1, limit: 20 } — safe defaults from defaultParams
+```
+
+## Installation
+
+```bash
+npm install @real-router/search-schema-plugin
+```
+
+**Peer dependency:** `@real-router/core`
+
+## Quick Start
+
+```typescript
+import { createRouter } from "@real-router/core";
+import { searchSchemaPlugin } from "@real-router/search-schema-plugin";
+import { z } from "zod"; // any Standard Schema V1 library — Zod 3.24+, Valibot 1.0+, ArkType
+
+const routes = [
+  {
+    name: "products",
+    path: "/products?page&limit&sortBy",
+    defaultParams: { page: 1, limit: 20, sortBy: "price" },
+    searchSchema: z.object({
+      page: z.number().int().positive(),
+      limit: z.number().int().min(1).max(100),
+      sortBy: z.enum(["price", "name", "date"]),
+    }),
+  },
+];
+
+const router = createRouter(routes, {
+  queryParams: { numberFormat: "auto" },
+});
+router.usePlugin(searchSchemaPlugin({ mode: "development" }));
+```
+
+> **Schema libraries:** Any library implementing [Standard Schema V1](https://github.com/standard-schema/standard-schema) works — Zod 3.24+, Valibot 1.0+, ArkType. Install and configure your chosen library separately; the plugin has no schema-library dependency.
+
+## Configuration
+
+| Option    | Type                                    | Default         | Description                                                                                                                                                                                    |
+| --------- | --------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mode`    | `"development" \| "production"`         | `"development"` | In development mode, logs invalid params with `console.error`. In production mode, strips silently without logging.                                                                            |
+| `strict`  | `boolean`                               | `false`         | When `false`, unknown params pass through alongside schema output. When `true`, only params present in the schema output are kept — unknown keys are removed.                                  |
+| `onError` | `(routeName, params, issues) => Params` | `undefined`     | Custom error handler. When set, overrides both `mode` logging and the built-in strip+merge recovery. Receives the raw validation issues; returned params are used as-is without re-validation. |
+
+## Behavior
+
+### Valid params
+
+When schema validation succeeds, the resolved params are merged back based on `strict`:
+
+```typescript
+// strict: false (default) — schema output merged over original, unknown keys preserved
+// Original params: { page: 1, filter: "electronics", utm_source: "google" }
+// Schema output:   { page: 1, filter: "electronics" }  (Zod strip mode removes unknowns)
+// Result:          { page: 1, filter: "electronics", utm_source: "google" }
+
+// strict: true — schema output used directly, unknown keys removed
+// Result: { page: 1, filter: "electronics" }
+```
+
+### Invalid params + recovery
+
+When schema validation fails, the plugin strips only the keys with validation issues and restores their `defaultParams` values:
+
+```typescript
+// Route defaultParams: { page: 1, sortBy: "price" }
+// URL: /products?page=foo&sortBy=price
+// Schema fails: page is not a valid number
+// Step 1 — strip invalid: { sortBy: "price" }
+// Step 2 — merge defaults: { page: 1, sortBy: "price" }  ← page restored from defaultParams
+// Result: { page: 1, sortBy: "price" }
+```
+
+In `mode: "development"`, a `console.error` is emitted with the route name and validation issues before the recovery happens.
+
+### Strict mode
+
+```typescript
+router.usePlugin(searchSchemaPlugin({ strict: true }));
+// Unknown params (not described in schema) are removed on every navigation
+```
+
+Per-route schema configuration (e.g., Zod's `.passthrough()` or `.strip()`) controls which keys appear in the schema output and effectively overrides the `strict` option for that route.
+
+## Use Cases
+
+### Form Validation — Pagination and Filters
+
+```typescript
+const routes = [
+  {
+    name: "users",
+    path: "/users?page&pageSize&status",
+    defaultParams: { page: 1, pageSize: 25, status: "active" },
+    searchSchema: z.object({
+      page: z.number().int().positive(),
+      pageSize: z.number().int().min(1).max(100),
+      status: z.enum(["active", "inactive", "all"]),
+    }),
+  },
+];
+
+const router = createRouter(routes, {
+  queryParams: { numberFormat: "auto" },
+});
+router.usePlugin(searchSchemaPlugin());
+// /users?page=0&status=deleted → { page: 1, pageSize: 25, status: "active" }
+```
+
+### Search Params with Automatic Type Coercion
+
+```typescript
+const searchSchema = z.object({
+  q: z.string().min(1),
+  page: z.number().int().positive().default(1),
+});
+
+const routes = [{ name: "search", path: "/search?q&page", searchSchema }];
+
+// numberFormat: "auto" handles string→number coercion at the search-params layer,
+// so schemas validate already-typed values (not raw URL strings)
+const router = createRouter(routes, {
+  queryParams: { numberFormat: "auto" },
+});
+router.usePlugin(searchSchemaPlugin());
+```
+
+### Custom Error Reporting
+
+```typescript
+router.usePlugin(
+  searchSchemaPlugin({
+    onError: (routeName, params, issues) => {
+      analytics.track("invalid_search_params", { routeName, issues });
+      return {}; // empty params — let defaultParams fill in from the route
+    },
+  }),
+);
+```
+
+## Documentation
+
+Full documentation: [Wiki — search-schema-plugin](https://github.com/greydragon888/real-router/wiki/search-schema-plugin)
+
+- [Standard Schema V1 compatibility](https://github.com/greydragon888/real-router/wiki/search-schema-plugin#standard-schema)
+- [Error recovery](https://github.com/greydragon888/real-router/wiki/search-schema-plugin#error-recovery)
+- [Strict mode](https://github.com/greydragon888/real-router/wiki/search-schema-plugin#strict-mode)
+
+## Related Packages
+
+| Package                                                                                                      | Description                                 |
+| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------- |
+| [@real-router/core](https://www.npmjs.com/package/@real-router/core)                                         | Core router (required peer dependency)      |
+| [@real-router/persistent-params-plugin](https://www.npmjs.com/package/@real-router/persistent-params-plugin) | Persist query parameters across navigations |
+| [@real-router/validation-plugin](https://www.npmjs.com/package/@real-router/validation-plugin)               | Runtime argument validation for development |
+
+## Contributing
+
+See [contributing guidelines](../../CONTRIBUTING.md) for development setup and PR process.
+
+## License
+
+[MIT](../../LICENSE) © [Oleg Ivanov](https://github.com/greydragon888)

package/dist/cjs/index.d.ts

@@ -0,0 +1,81 @@
+import { Params, PluginFactory } from "@real-router/core";
+
+//#region src/types.d.ts
+/** A single validation issue from Standard Schema V1. */
+interface StandardSchemaV1Issue {
+  readonly message: string;
+  readonly path?: readonly (PropertyKey | {
+    readonly key: PropertyKey;
+  })[] | undefined;
+}
+/** Validation result — either success or failure. */
+type StandardSchemaV1Result<Output = unknown> = {
+  readonly value: Output;
+} | {
+  readonly issues: readonly StandardSchemaV1Issue[];
+};
+/**
+ * Standard Schema V1 interface.
+ *
+ * Supported by Zod 3.24+, Valibot 1.0+, ArkType.
+ * The plugin doesn't depend on any specific schema library.
+ */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+  readonly "~standard": {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (value: unknown) => StandardSchemaV1Result<Output> | Promise<StandardSchemaV1Result<Output>>;
+    readonly types?: {
+      readonly input: Input;
+      readonly output: Output;
+    } | undefined;
+  };
+}
+interface SearchSchemaPluginOptions {
+  /**
+   * Error handling mode.
+   * - "development" (default): strip invalid + console.error
+   * - "production": silent strip
+   *
+   * For recovery of invalid params use defaultParams (strip + merge + diagnostics).
+   * For filling absent params use .default() in schema (no diagnostics).
+   * .catch() is not recommended — suppresses errors, mode: "development" won't see the issue.
+   */
+  readonly mode?: "development" | "production";
+  /**
+   * Strip search params not described in schema.
+   * - false (default): unknown params pass through
+   * - true: unknown params are removed
+   *
+   * Per-route override: .strict() / .passthrough() in Zod schema.
+   */
+  readonly strict?: boolean;
+  /**
+   * Custom error handler (overrides mode completely).
+   * Must return cleaned params.
+   *
+   * Contract:
+   * - Returned params are used as-is, without re-validation.
+   *   Responsibility for correctness is on the callback author.
+   *   (Re-validation would risk infinite loops.)
+   * - Exceptions from onError propagate up without suppression.
+   *   Consistent with interceptor behavior in core.
+   * - When onError is set, neither console.error (mode: "development"),
+   *   nor silent strip (mode: "production") are executed.
+   *   All responsibility for diagnostics and recovery is on the callback.
+   */
+  readonly onError?: (routeName: string, params: Params, issues: readonly StandardSchemaV1Issue[]) => Params;
+}
+//#endregion
+//#region src/factory.d.ts
+declare function searchSchemaPlugin(options?: SearchSchemaPluginOptions): PluginFactory;
+//#endregion
+//#region src/index.d.ts
+declare module "@real-router/core" {
+  interface Route {
+    searchSchema?: StandardSchemaV1;
+  }
+}
+//#endregion
+export { type SearchSchemaPluginOptions, type StandardSchemaV1, type StandardSchemaV1Issue, type StandardSchemaV1Result, searchSchemaPlugin };
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/index.js

@@ -0,0 +1,2 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require(`@real-router/core/api`);const t=`[search-schema-plugin]`;function n(e){let t=new Set;for(let n of e)if(n.path&&n.path.length>0){let e=n.path[0],r=typeof e==`object`&&`key`in e?e.key:e;t.add(String(r))}return t}function r(e,t){let n={};for(let r of Object.keys(e))t.has(r)||(n[r]=e[r]);return n}var i=class{#e;#t;#n;#r;#i;#a;#o;constructor(e,t,n){this.#e=e,this.#t=t,this.#n=n.mode??`development`,this.#r=n.strict??!1,this.#i=n.onError,this.#l(),this.#a=this.#e.addInterceptor(`forwardState`,(e,t,n)=>{let r=e(t,n);return this.#c(r)}),this.#o=this.#e.addInterceptor(`add`,(e,t,n)=>{e(t,n),this.#f(t,n?.parent)})}getPlugin(){return{teardown:()=>{this.#a(),this.#o()}}}#s(e){return this.#e.getRouteConfig(e)?.searchSchema}#c(e){let i=this.#s(e.name);if(!i)return e;let a=i[`~standard`].validate(e.params);if(a instanceof Promise)throw TypeError(`${t} Async schema validation is not supported. Route "${e.name}" returned a Promise from ~standard.validate().`);if(`value`in a){let t=this.#r?a.value:{...e.params,...a.value};return{...e,params:t}}if(this.#i)return{...e,params:this.#i(e.name,e.params,a.issues)};this.#n===`development`&&console.error(`${t} Route "${e.name}": invalid search params`,a.issues);let o=n(a.issues),s=r(e.params,o),c=this.#t.get(e.name)?.defaultParams,l=c?{...c,...s}:s;return{...e,params:l}}#l(){if(this.#n!==`development`)return;let e=this.#e.getTree();e&&this.#u(e)}#u(e){if(e.fullName&&this.#d(e.fullName),e.children instanceof Map)for(let t of e.children.values())t&&typeof t==`object`&&this.#u(t)}#d(e){let n=this.#s(e);if(!n)return;let r=this.#t.get(e)?.defaultParams;if(!r)return;let i=n[`~standard`].validate(r);i instanceof Promise||`issues`in i&&console.warn(`${t} Route "${e}": defaultParams do not pass searchSchema`,i.issues)}#f(e,t=``){if(this.#n===`development`){for(let n of e)if(n.name){let e=t?`${t}.${n.name}`:n.name;this.#d(e),n.children&&this.#f(n.children,e)}}}};const a=new Set([`development`,`production`]);function o(e){if(e.mode!==void 0&&!a.has(e.mode))throw TypeError(`${t} Invalid mode: "${e.mode}". Must be "development" or "production".`);if(e.strict!==void 0&&typeof e.strict!=`boolean`)throw TypeError(`${t} Invalid strict option: expected boolean, got ${typeof e.strict}.`);if(e.onError!==void 0&&typeof e.onError!=`function`)throw TypeError(`${t} Invalid onError: expected function, got ${typeof e.onError}.`)}function s(t={}){o(t);let n=Object.freeze({...t});return t=>new i((0,e.getPluginApi)(t),(0,e.getRoutesApi)(t),n).getPlugin()}exports.searchSchemaPlugin=s;
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["#pluginApi","#routesApi","#mode","#strict","#onError","#removeForwardStateInterceptor","#removeAddInterceptor","#validateExistingDefaultParams","#validateState","#validateRoutesDefaultParams","#getSchema","#walkTree","#validateSingleRouteDefaultParams"],"sources":["../../src/constants.ts","../../src/helpers.ts","../../src/plugin.ts","../../src/validation.ts","../../src/factory.ts"],"sourcesContent":["// packages/search-schema-plugin/src/constants.ts\n\nexport const ERROR_PREFIX = \"[search-schema-plugin]\";\n","// packages/search-schema-plugin/src/helpers.ts\n\nimport type { StandardSchemaV1Issue } from \"./types\";\nimport type { Params } from \"@real-router/core\";\n\n/**\n * Extract top-level keys from validation issues.\n * Only processes issues with a non-empty path — issues without path\n * affect the whole object and can't be stripped by key.\n */\nexport function getInvalidKeys(\n  issues: readonly StandardSchemaV1Issue[],\n): Set<string> {\n  const keys = new Set<string>();\n\n  for (const issue of issues) {\n    if (issue.path && issue.path.length > 0) {\n      const segment = issue.path[0];\n      const key =\n        typeof segment === \"object\" && \"key\" in segment ? segment.key : segment;\n\n      keys.add(String(key));\n    }\n  }\n\n  return keys;\n}\n\n/** Create a shallow copy of params without the specified keys. */\nexport function omitKeys(params: Params, keys: Set<string>): Params {\n  const result: Params = {};\n\n  for (const key of Object.keys(params)) {\n    if (!keys.has(key)) {\n      result[key] = params[key];\n    }\n  }\n\n  return result;\n}\n","import { ERROR_PREFIX } from \"./constants\";\nimport { getInvalidKeys, omitKeys } from \"./helpers\";\n\nimport type {\n  SearchSchemaPluginOptions,\n  StandardSchemaV1,\n  StandardSchemaV1Issue,\n} from \"./types\";\nimport type { Params, Plugin, Route } from \"@real-router/core\";\nimport type { PluginApi, RoutesApi } from \"@real-router/core/api\";\n\nexport class SearchSchemaPlugin {\n  readonly #pluginApi: PluginApi;\n  readonly #routesApi: RoutesApi;\n  readonly #mode: \"development\" | \"production\";\n  readonly #strict: boolean;\n  readonly #onError:\n    | ((\n        routeName: string,\n        params: Params,\n        issues: readonly StandardSchemaV1Issue[],\n      ) => Params)\n    | undefined;\n  readonly #removeForwardStateInterceptor: () => void;\n  readonly #removeAddInterceptor: () => void;\n\n  constructor(\n    pluginApi: PluginApi,\n    routesApi: RoutesApi,\n    options: SearchSchemaPluginOptions,\n  ) {\n    this.#pluginApi = pluginApi;\n    this.#routesApi = routesApi;\n    this.#mode = options.mode ?? \"development\";\n    this.#strict = options.strict ?? false;\n    this.#onError = options.onError;\n\n    this.#validateExistingDefaultParams();\n\n    this.#removeForwardStateInterceptor = this.#pluginApi.addInterceptor(\n      \"forwardState\",\n      (next, routeName, routeParams) => {\n        const result = next(routeName, routeParams);\n\n        return this.#validateState(result);\n      },\n    );\n\n    this.#removeAddInterceptor = this.#pluginApi.addInterceptor(\n      \"add\",\n      (next, routes, addOptions) => {\n        next(routes, addOptions);\n        this.#validateRoutesDefaultParams(routes, addOptions?.parent);\n      },\n    );\n  }\n\n  getPlugin(): Plugin {\n    return {\n      teardown: () => {\n        this.#removeForwardStateInterceptor();\n        this.#removeAddInterceptor();\n      },\n    };\n  }\n\n  #getSchema(routeName: string): StandardSchemaV1 | undefined {\n    return this.#pluginApi.getRouteConfig(routeName)?.searchSchema as\n      | StandardSchemaV1\n      | undefined;\n  }\n\n  #validateState(result: { name: string; params: Params }): {\n    name: string;\n    params: Params;\n  } {\n    const schema = this.#getSchema(result.name);\n\n    if (!schema) {\n      return result;\n    }\n\n    const validation = schema[\"~standard\"].validate(result.params);\n\n    if (validation instanceof Promise) {\n      throw new TypeError(\n        `${ERROR_PREFIX} Async schema validation is not supported. Route \"${result.name}\" returned a Promise from ~standard.validate().`,\n      );\n    }\n\n    if (\"value\" in validation) {\n      const params = this.#strict\n        ? (validation.value as Params)\n        : { ...result.params, ...(validation.value as Params) };\n\n      return { ...result, params };\n    }\n\n    if (this.#onError) {\n      return {\n        ...result,\n        params: this.#onError(result.name, result.params, validation.issues),\n      };\n    }\n\n    if (this.#mode === \"development\") {\n      console.error(\n        `${ERROR_PREFIX} Route \"${result.name}\": invalid search params`,\n        validation.issues,\n      );\n    }\n\n    const invalidKeys = getInvalidKeys(validation.issues);\n    const stripped = omitKeys(result.params, invalidKeys);\n    const route = this.#routesApi.get(result.name);\n    const defaults = route?.defaultParams;\n    const restored = defaults ? { ...defaults, ...stripped } : stripped;\n\n    return { ...result, params: restored };\n  }\n\n  #validateExistingDefaultParams(): void {\n    if (this.#mode !== \"development\") {\n      return;\n    }\n\n    const tree = this.#pluginApi.getTree() as unknown as\n      | { fullName?: string; children?: ReadonlyMap<string, unknown> }\n      | undefined;\n\n    /* v8 ignore next -- @preserve: getTree() always returns a RouteTree, defensive check */\n    if (!tree) {\n      return;\n    }\n\n    this.#walkTree(tree);\n  }\n\n  #walkTree(node: {\n    fullName?: string;\n    children?: ReadonlyMap<string, unknown>;\n  }): void {\n    if (node.fullName) {\n      this.#validateSingleRouteDefaultParams(node.fullName);\n    }\n\n    /* v8 ignore next 3 -- @preserve: children is always a Map in RouteTree */\n    if (node.children instanceof Map) {\n      for (const child of node.children.values()) {\n        if (child && typeof child === \"object\") {\n          this.#walkTree(\n            child as {\n              fullName?: string;\n              children?: ReadonlyMap<string, unknown>;\n            },\n          );\n        }\n      }\n    }\n  }\n\n  #validateSingleRouteDefaultParams(routeName: string): void {\n    const schema = this.#getSchema(routeName);\n\n    if (!schema) {\n      return;\n    }\n\n    const route = this.#routesApi.get(routeName);\n    const defaultParams = route?.defaultParams;\n\n    if (!defaultParams) {\n      return;\n    }\n\n    const validation = schema[\"~standard\"].validate(defaultParams);\n\n    if (validation instanceof Promise) {\n      return;\n    }\n\n    if (\"issues\" in validation) {\n      console.warn(\n        `${ERROR_PREFIX} Route \"${routeName}\": defaultParams do not pass searchSchema`,\n        validation.issues,\n      );\n    }\n  }\n\n  #validateRoutesDefaultParams(routes: Route[], prefix = \"\"): void {\n    if (this.#mode !== \"development\") {\n      return;\n    }\n\n    for (const route of routes) {\n      /* v8 ignore next -- @preserve: Route.name is always a non-empty string */\n      if (route.name) {\n        const fullName = prefix ? `${prefix}.${route.name}` : route.name;\n\n        this.#validateSingleRouteDefaultParams(fullName);\n\n        if (route.children) {\n          this.#validateRoutesDefaultParams(route.children, fullName);\n        }\n      }\n    }\n  }\n}\n","import { ERROR_PREFIX } from \"./constants\";\n\nimport type { SearchSchemaPluginOptions } from \"./types\";\n\nconst VALID_MODES = new Set([\"development\", \"production\"]);\n\nexport function validateOptions(options: SearchSchemaPluginOptions): void {\n  if (options.mode !== undefined && !VALID_MODES.has(options.mode)) {\n    throw new TypeError(\n      `${ERROR_PREFIX} Invalid mode: \"${options.mode}\". Must be \"development\" or \"production\".`,\n    );\n  }\n\n  if (options.strict !== undefined && typeof options.strict !== \"boolean\") {\n    throw new TypeError(\n      `${ERROR_PREFIX} Invalid strict option: expected boolean, got ${typeof options.strict}.`,\n    );\n  }\n\n  if (options.onError !== undefined && typeof options.onError !== \"function\") {\n    throw new TypeError(\n      `${ERROR_PREFIX} Invalid onError: expected function, got ${typeof options.onError}.`,\n    );\n  }\n}\n","import { getPluginApi, getRoutesApi } from \"@real-router/core/api\";\n\nimport { SearchSchemaPlugin } from \"./plugin\";\nimport { validateOptions } from \"./validation\";\n\nimport type { SearchSchemaPluginOptions } from \"./types\";\nimport type { PluginFactory, Plugin } from \"@real-router/core\";\n\nexport function searchSchemaPlugin(\n  options: SearchSchemaPluginOptions = {},\n): PluginFactory {\n  validateOptions(options);\n\n  const frozenOptions: SearchSchemaPluginOptions = Object.freeze({\n    ...options,\n  });\n\n  return (router): Plugin => {\n    const pluginApi = getPluginApi(router);\n    const routesApi = getRoutesApi(router);\n    const plugin = new SearchSchemaPlugin(pluginApi, routesApi, frozenOptions);\n\n    return plugin.getPlugin();\n  };\n}\n"],"mappings":"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"}

package/dist/esm/index.d.mts

@@ -0,0 +1,81 @@
+import { Params, PluginFactory } from "@real-router/core";
+
+//#region src/types.d.ts
+/** A single validation issue from Standard Schema V1. */
+interface StandardSchemaV1Issue {
+  readonly message: string;
+  readonly path?: readonly (PropertyKey | {
+    readonly key: PropertyKey;
+  })[] | undefined;
+}
+/** Validation result — either success or failure. */
+type StandardSchemaV1Result<Output = unknown> = {
+  readonly value: Output;
+} | {
+  readonly issues: readonly StandardSchemaV1Issue[];
+};
+/**
+ * Standard Schema V1 interface.
+ *
+ * Supported by Zod 3.24+, Valibot 1.0+, ArkType.
+ * The plugin doesn't depend on any specific schema library.
+ */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+  readonly "~standard": {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (value: unknown) => StandardSchemaV1Result<Output> | Promise<StandardSchemaV1Result<Output>>;
+    readonly types?: {
+      readonly input: Input;
+      readonly output: Output;
+    } | undefined;
+  };
+}
+interface SearchSchemaPluginOptions {
+  /**
+   * Error handling mode.
+   * - "development" (default): strip invalid + console.error
+   * - "production": silent strip
+   *
+   * For recovery of invalid params use defaultParams (strip + merge + diagnostics).
+   * For filling absent params use .default() in schema (no diagnostics).
+   * .catch() is not recommended — suppresses errors, mode: "development" won't see the issue.
+   */
+  readonly mode?: "development" | "production";
+  /**
+   * Strip search params not described in schema.
+   * - false (default): unknown params pass through
+   * - true: unknown params are removed
+   *
+   * Per-route override: .strict() / .passthrough() in Zod schema.
+   */
+  readonly strict?: boolean;
+  /**
+   * Custom error handler (overrides mode completely).
+   * Must return cleaned params.
+   *
+   * Contract:
+   * - Returned params are used as-is, without re-validation.
+   *   Responsibility for correctness is on the callback author.
+   *   (Re-validation would risk infinite loops.)
+   * - Exceptions from onError propagate up without suppression.
+   *   Consistent with interceptor behavior in core.
+   * - When onError is set, neither console.error (mode: "development"),
+   *   nor silent strip (mode: "production") are executed.
+   *   All responsibility for diagnostics and recovery is on the callback.
+   */
+  readonly onError?: (routeName: string, params: Params, issues: readonly StandardSchemaV1Issue[]) => Params;
+}
+//#endregion
+//#region src/factory.d.ts
+declare function searchSchemaPlugin(options?: SearchSchemaPluginOptions): PluginFactory;
+//#endregion
+//#region src/index.d.ts
+declare module "@real-router/core" {
+  interface Route {
+    searchSchema?: StandardSchemaV1;
+  }
+}
+//#endregion
+export { type SearchSchemaPluginOptions, type StandardSchemaV1, type StandardSchemaV1Issue, type StandardSchemaV1Result, searchSchemaPlugin };
+//# sourceMappingURL=index.d.mts.map

package/dist/esm/index.mjs

@@ -0,0 +1,2 @@
+import{getPluginApi as e,getRoutesApi as t}from"@real-router/core/api";const n=`[search-schema-plugin]`;function r(e){let t=new Set;for(let n of e)if(n.path&&n.path.length>0){let e=n.path[0],r=typeof e==`object`&&`key`in e?e.key:e;t.add(String(r))}return t}function i(e,t){let n={};for(let r of Object.keys(e))t.has(r)||(n[r]=e[r]);return n}var a=class{#e;#t;#n;#r;#i;#a;#o;constructor(e,t,n){this.#e=e,this.#t=t,this.#n=n.mode??`development`,this.#r=n.strict??!1,this.#i=n.onError,this.#l(),this.#a=this.#e.addInterceptor(`forwardState`,(e,t,n)=>{let r=e(t,n);return this.#c(r)}),this.#o=this.#e.addInterceptor(`add`,(e,t,n)=>{e(t,n),this.#f(t,n?.parent)})}getPlugin(){return{teardown:()=>{this.#a(),this.#o()}}}#s(e){return this.#e.getRouteConfig(e)?.searchSchema}#c(e){let t=this.#s(e.name);if(!t)return e;let a=t[`~standard`].validate(e.params);if(a instanceof Promise)throw TypeError(`${n} Async schema validation is not supported. Route "${e.name}" returned a Promise from ~standard.validate().`);if(`value`in a){let t=this.#r?a.value:{...e.params,...a.value};return{...e,params:t}}if(this.#i)return{...e,params:this.#i(e.name,e.params,a.issues)};this.#n===`development`&&console.error(`${n} Route "${e.name}": invalid search params`,a.issues);let o=r(a.issues),s=i(e.params,o),c=this.#t.get(e.name)?.defaultParams,l=c?{...c,...s}:s;return{...e,params:l}}#l(){if(this.#n!==`development`)return;let e=this.#e.getTree();e&&this.#u(e)}#u(e){if(e.fullName&&this.#d(e.fullName),e.children instanceof Map)for(let t of e.children.values())t&&typeof t==`object`&&this.#u(t)}#d(e){let t=this.#s(e);if(!t)return;let r=this.#t.get(e)?.defaultParams;if(!r)return;let i=t[`~standard`].validate(r);i instanceof Promise||`issues`in i&&console.warn(`${n} Route "${e}": defaultParams do not pass searchSchema`,i.issues)}#f(e,t=``){if(this.#n===`development`){for(let n of e)if(n.name){let e=t?`${t}.${n.name}`:n.name;this.#d(e),n.children&&this.#f(n.children,e)}}}};const o=new Set([`development`,`production`]);function s(e){if(e.mode!==void 0&&!o.has(e.mode))throw TypeError(`${n} Invalid mode: "${e.mode}". Must be "development" or "production".`);if(e.strict!==void 0&&typeof e.strict!=`boolean`)throw TypeError(`${n} Invalid strict option: expected boolean, got ${typeof e.strict}.`);if(e.onError!==void 0&&typeof e.onError!=`function`)throw TypeError(`${n} Invalid onError: expected function, got ${typeof e.onError}.`)}function c(n={}){s(n);let r=Object.freeze({...n});return n=>new a(e(n),t(n),r).getPlugin()}export{c as searchSchemaPlugin};
+//# sourceMappingURL=index.mjs.map

package/dist/esm/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":["#pluginApi","#routesApi","#mode","#strict","#onError","#removeForwardStateInterceptor","#removeAddInterceptor","#validateExistingDefaultParams","#validateState","#validateRoutesDefaultParams","#getSchema","#walkTree","#validateSingleRouteDefaultParams"],"sources":["../../src/constants.ts","../../src/helpers.ts","../../src/plugin.ts","../../src/validation.ts","../../src/factory.ts"],"sourcesContent":["// packages/search-schema-plugin/src/constants.ts\n\nexport const ERROR_PREFIX = \"[search-schema-plugin]\";\n","// packages/search-schema-plugin/src/helpers.ts\n\nimport type { StandardSchemaV1Issue } from \"./types\";\nimport type { Params } from \"@real-router/core\";\n\n/**\n * Extract top-level keys from validation issues.\n * Only processes issues with a non-empty path — issues without path\n * affect the whole object and can't be stripped by key.\n */\nexport function getInvalidKeys(\n  issues: readonly StandardSchemaV1Issue[],\n): Set<string> {\n  const keys = new Set<string>();\n\n  for (const issue of issues) {\n    if (issue.path && issue.path.length > 0) {\n      const segment = issue.path[0];\n      const key =\n        typeof segment === \"object\" && \"key\" in segment ? segment.key : segment;\n\n      keys.add(String(key));\n    }\n  }\n\n  return keys;\n}\n\n/** Create a shallow copy of params without the specified keys. */\nexport function omitKeys(params: Params, keys: Set<string>): Params {\n  const result: Params = {};\n\n  for (const key of Object.keys(params)) {\n    if (!keys.has(key)) {\n      result[key] = params[key];\n    }\n  }\n\n  return result;\n}\n","import { ERROR_PREFIX } from \"./constants\";\nimport { getInvalidKeys, omitKeys } from \"./helpers\";\n\nimport type {\n  SearchSchemaPluginOptions,\n  StandardSchemaV1,\n  StandardSchemaV1Issue,\n} from \"./types\";\nimport type { Params, Plugin, Route } from \"@real-router/core\";\nimport type { PluginApi, RoutesApi } from \"@real-router/core/api\";\n\nexport class SearchSchemaPlugin {\n  readonly #pluginApi: PluginApi;\n  readonly #routesApi: RoutesApi;\n  readonly #mode: \"development\" | \"production\";\n  readonly #strict: boolean;\n  readonly #onError:\n    | ((\n        routeName: string,\n        params: Params,\n        issues: readonly StandardSchemaV1Issue[],\n      ) => Params)\n    | undefined;\n  readonly #removeForwardStateInterceptor: () => void;\n  readonly #removeAddInterceptor: () => void;\n\n  constructor(\n    pluginApi: PluginApi,\n    routesApi: RoutesApi,\n    options: SearchSchemaPluginOptions,\n  ) {\n    this.#pluginApi = pluginApi;\n    this.#routesApi = routesApi;\n    this.#mode = options.mode ?? \"development\";\n    this.#strict = options.strict ?? false;\n    this.#onError = options.onError;\n\n    this.#validateExistingDefaultParams();\n\n    this.#removeForwardStateInterceptor = this.#pluginApi.addInterceptor(\n      \"forwardState\",\n      (next, routeName, routeParams) => {\n        const result = next(routeName, routeParams);\n\n        return this.#validateState(result);\n      },\n    );\n\n    this.#removeAddInterceptor = this.#pluginApi.addInterceptor(\n      \"add\",\n      (next, routes, addOptions) => {\n        next(routes, addOptions);\n        this.#validateRoutesDefaultParams(routes, addOptions?.parent);\n      },\n    );\n  }\n\n  getPlugin(): Plugin {\n    return {\n      teardown: () => {\n        this.#removeForwardStateInterceptor();\n        this.#removeAddInterceptor();\n      },\n    };\n  }\n\n  #getSchema(routeName: string): StandardSchemaV1 | undefined {\n    return this.#pluginApi.getRouteConfig(routeName)?.searchSchema as\n      | StandardSchemaV1\n      | undefined;\n  }\n\n  #validateState(result: { name: string; params: Params }): {\n    name: string;\n    params: Params;\n  } {\n    const schema = this.#getSchema(result.name);\n\n    if (!schema) {\n      return result;\n    }\n\n    const validation = schema[\"~standard\"].validate(result.params);\n\n    if (validation instanceof Promise) {\n      throw new TypeError(\n        `${ERROR_PREFIX} Async schema validation is not supported. Route \"${result.name}\" returned a Promise from ~standard.validate().`,\n      );\n    }\n\n    if (\"value\" in validation) {\n      const params = this.#strict\n        ? (validation.value as Params)\n        : { ...result.params, ...(validation.value as Params) };\n\n      return { ...result, params };\n    }\n\n    if (this.#onError) {\n      return {\n        ...result,\n        params: this.#onError(result.name, result.params, validation.issues),\n      };\n    }\n\n    if (this.#mode === \"development\") {\n      console.error(\n        `${ERROR_PREFIX} Route \"${result.name}\": invalid search params`,\n        validation.issues,\n      );\n    }\n\n    const invalidKeys = getInvalidKeys(validation.issues);\n    const stripped = omitKeys(result.params, invalidKeys);\n    const route = this.#routesApi.get(result.name);\n    const defaults = route?.defaultParams;\n    const restored = defaults ? { ...defaults, ...stripped } : stripped;\n\n    return { ...result, params: restored };\n  }\n\n  #validateExistingDefaultParams(): void {\n    if (this.#mode !== \"development\") {\n      return;\n    }\n\n    const tree = this.#pluginApi.getTree() as unknown as\n      | { fullName?: string; children?: ReadonlyMap<string, unknown> }\n      | undefined;\n\n    /* v8 ignore next -- @preserve: getTree() always returns a RouteTree, defensive check */\n    if (!tree) {\n      return;\n    }\n\n    this.#walkTree(tree);\n  }\n\n  #walkTree(node: {\n    fullName?: string;\n    children?: ReadonlyMap<string, unknown>;\n  }): void {\n    if (node.fullName) {\n      this.#validateSingleRouteDefaultParams(node.fullName);\n    }\n\n    /* v8 ignore next 3 -- @preserve: children is always a Map in RouteTree */\n    if (node.children instanceof Map) {\n      for (const child of node.children.values()) {\n        if (child && typeof child === \"object\") {\n          this.#walkTree(\n            child as {\n              fullName?: string;\n              children?: ReadonlyMap<string, unknown>;\n            },\n          );\n        }\n      }\n    }\n  }\n\n  #validateSingleRouteDefaultParams(routeName: string): void {\n    const schema = this.#getSchema(routeName);\n\n    if (!schema) {\n      return;\n    }\n\n    const route = this.#routesApi.get(routeName);\n    const defaultParams = route?.defaultParams;\n\n    if (!defaultParams) {\n      return;\n    }\n\n    const validation = schema[\"~standard\"].validate(defaultParams);\n\n    if (validation instanceof Promise) {\n      return;\n    }\n\n    if (\"issues\" in validation) {\n      console.warn(\n        `${ERROR_PREFIX} Route \"${routeName}\": defaultParams do not pass searchSchema`,\n        validation.issues,\n      );\n    }\n  }\n\n  #validateRoutesDefaultParams(routes: Route[], prefix = \"\"): void {\n    if (this.#mode !== \"development\") {\n      return;\n    }\n\n    for (const route of routes) {\n      /* v8 ignore next -- @preserve: Route.name is always a non-empty string */\n      if (route.name) {\n        const fullName = prefix ? `${prefix}.${route.name}` : route.name;\n\n        this.#validateSingleRouteDefaultParams(fullName);\n\n        if (route.children) {\n          this.#validateRoutesDefaultParams(route.children, fullName);\n        }\n      }\n    }\n  }\n}\n","import { ERROR_PREFIX } from \"./constants\";\n\nimport type { SearchSchemaPluginOptions } from \"./types\";\n\nconst VALID_MODES = new Set([\"development\", \"production\"]);\n\nexport function validateOptions(options: SearchSchemaPluginOptions): void {\n  if (options.mode !== undefined && !VALID_MODES.has(options.mode)) {\n    throw new TypeError(\n      `${ERROR_PREFIX} Invalid mode: \"${options.mode}\". Must be \"development\" or \"production\".`,\n    );\n  }\n\n  if (options.strict !== undefined && typeof options.strict !== \"boolean\") {\n    throw new TypeError(\n      `${ERROR_PREFIX} Invalid strict option: expected boolean, got ${typeof options.strict}.`,\n    );\n  }\n\n  if (options.onError !== undefined && typeof options.onError !== \"function\") {\n    throw new TypeError(\n      `${ERROR_PREFIX} Invalid onError: expected function, got ${typeof options.onError}.`,\n    );\n  }\n}\n","import { getPluginApi, getRoutesApi } from \"@real-router/core/api\";\n\nimport { SearchSchemaPlugin } from \"./plugin\";\nimport { validateOptions } from \"./validation\";\n\nimport type { SearchSchemaPluginOptions } from \"./types\";\nimport type { PluginFactory, Plugin } from \"@real-router/core\";\n\nexport function searchSchemaPlugin(\n  options: SearchSchemaPluginOptions = {},\n): PluginFactory {\n  validateOptions(options);\n\n  const frozenOptions: SearchSchemaPluginOptions = Object.freeze({\n    ...options,\n  });\n\n  return (router): Plugin => {\n    const pluginApi = getPluginApi(router);\n    const routesApi = getRoutesApi(router);\n    const plugin = new SearchSchemaPlugin(pluginApi, routesApi, frozenOptions);\n\n    return plugin.getPlugin();\n  };\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@real-router/search-schema-plugin",
+  "version": "0.0.1",
+  "type": "commonjs",
+  "description": "Runtime search parameter validation via Standard Schema for Real-Router",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.mjs",
+  "types": "./dist/esm/index.d.mts",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": {
+        "import": "./dist/esm/index.d.mts",
+        "require": "./dist/cjs/index.d.ts"
+      },
+      "import": "./dist/esm/index.mjs",
+      "require": "./dist/cjs/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/greydragon888/real-router.git"
+  },
+  "keywords": [
+    "real-router",
+    "search-params",
+    "validation",
+    "schema",
+    "standard-schema",
+    "zod",
+    "valibot"
+  ],
+  "author": {
+    "name": "Oleg Ivanov",
+    "email": "greydragon888@gmail.com",
+    "url": "https://github.com/greydragon888"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/greydragon888/real-router/issues"
+  },
+  "homepage": "https://github.com/greydragon888/real-router",
+  "scripts": {
+    "test": "vitest",
+    "test:properties": "vitest run --config vitest.config.properties.mts",
+    "build": "tsdown --config-loader unrun",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint --cache --ext .ts src/ tests/ --fix --max-warnings 0",
+    "lint:package": "publint",
+    "lint:types": "attw --pack .",
+    "build:dist-only": "tsdown --config-loader unrun"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@real-router/core": "workspace:^"
+  }
+}

package/src/constants.ts

@@ -0,0 +1,3 @@
+// packages/search-schema-plugin/src/constants.ts
+
+export const ERROR_PREFIX = "[search-schema-plugin]";

package/src/factory.ts

@@ -0,0 +1,25 @@
+import { getPluginApi, getRoutesApi } from "@real-router/core/api";
+
+import { SearchSchemaPlugin } from "./plugin";
+import { validateOptions } from "./validation";
+
+import type { SearchSchemaPluginOptions } from "./types";
+import type { PluginFactory, Plugin } from "@real-router/core";
+
+export function searchSchemaPlugin(
+  options: SearchSchemaPluginOptions = {},
+): PluginFactory {
+  validateOptions(options);
+
+  const frozenOptions: SearchSchemaPluginOptions = Object.freeze({
+    ...options,
+  });
+
+  return (router): Plugin => {
+    const pluginApi = getPluginApi(router);
+    const routesApi = getRoutesApi(router);
+    const plugin = new SearchSchemaPlugin(pluginApi, routesApi, frozenOptions);
+
+    return plugin.getPlugin();
+  };
+}

package/src/helpers.ts

@@ -0,0 +1,40 @@
+// packages/search-schema-plugin/src/helpers.ts
+
+import type { StandardSchemaV1Issue } from "./types";
+import type { Params } from "@real-router/core";
+
+/**
+ * Extract top-level keys from validation issues.
+ * Only processes issues with a non-empty path — issues without path
+ * affect the whole object and can't be stripped by key.
+ */
+export function getInvalidKeys(
+  issues: readonly StandardSchemaV1Issue[],
+): Set<string> {
+  const keys = new Set<string>();
+
+  for (const issue of issues) {
+    if (issue.path && issue.path.length > 0) {
+      const segment = issue.path[0];
+      const key =
+        typeof segment === "object" && "key" in segment ? segment.key : segment;
+
+      keys.add(String(key));
+    }
+  }
+
+  return keys;
+}
+
+/** Create a shallow copy of params without the specified keys. */
+export function omitKeys(params: Params, keys: Set<string>): Params {
+  const result: Params = {};
+
+  for (const key of Object.keys(params)) {
+    if (!keys.has(key)) {
+      result[key] = params[key];
+    }
+  }
+
+  return result;
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+import type { StandardSchemaV1 } from "./types";
+
+export { searchSchemaPlugin } from "./factory";
+
+declare module "@real-router/core" {
+  interface Route {
+    searchSchema?: StandardSchemaV1;
+  }
+}
+
+export type {
+  SearchSchemaPluginOptions,
+  StandardSchemaV1,
+  StandardSchemaV1Issue,
+  StandardSchemaV1Result,
+} from "./types";

package/src/plugin.ts

@@ -0,0 +1,208 @@
+import { ERROR_PREFIX } from "./constants";
+import { getInvalidKeys, omitKeys } from "./helpers";
+
+import type {
+  SearchSchemaPluginOptions,
+  StandardSchemaV1,
+  StandardSchemaV1Issue,
+} from "./types";
+import type { Params, Plugin, Route } from "@real-router/core";
+import type { PluginApi, RoutesApi } from "@real-router/core/api";
+
+export class SearchSchemaPlugin {
+  readonly #pluginApi: PluginApi;
+  readonly #routesApi: RoutesApi;
+  readonly #mode: "development" | "production";
+  readonly #strict: boolean;
+  readonly #onError:
+    | ((
+        routeName: string,
+        params: Params,
+        issues: readonly StandardSchemaV1Issue[],
+      ) => Params)
+    | undefined;
+  readonly #removeForwardStateInterceptor: () => void;
+  readonly #removeAddInterceptor: () => void;
+
+  constructor(
+    pluginApi: PluginApi,
+    routesApi: RoutesApi,
+    options: SearchSchemaPluginOptions,
+  ) {
+    this.#pluginApi = pluginApi;
+    this.#routesApi = routesApi;
+    this.#mode = options.mode ?? "development";
+    this.#strict = options.strict ?? false;
+    this.#onError = options.onError;
+
+    this.#validateExistingDefaultParams();
+
+    this.#removeForwardStateInterceptor = this.#pluginApi.addInterceptor(
+      "forwardState",
+      (next, routeName, routeParams) => {
+        const result = next(routeName, routeParams);
+
+        return this.#validateState(result);
+      },
+    );
+
+    this.#removeAddInterceptor = this.#pluginApi.addInterceptor(
+      "add",
+      (next, routes, addOptions) => {
+        next(routes, addOptions);
+        this.#validateRoutesDefaultParams(routes, addOptions?.parent);
+      },
+    );
+  }
+
+  getPlugin(): Plugin {
+    return {
+      teardown: () => {
+        this.#removeForwardStateInterceptor();
+        this.#removeAddInterceptor();
+      },
+    };
+  }
+
+  #getSchema(routeName: string): StandardSchemaV1 | undefined {
+    return this.#pluginApi.getRouteConfig(routeName)?.searchSchema as
+      | StandardSchemaV1
+      | undefined;
+  }
+
+  #validateState(result: { name: string; params: Params }): {
+    name: string;
+    params: Params;
+  } {
+    const schema = this.#getSchema(result.name);
+
+    if (!schema) {
+      return result;
+    }
+
+    const validation = schema["~standard"].validate(result.params);
+
+    if (validation instanceof Promise) {
+      throw new TypeError(
+        `${ERROR_PREFIX} Async schema validation is not supported. Route "${result.name}" returned a Promise from ~standard.validate().`,
+      );
+    }
+
+    if ("value" in validation) {
+      const params = this.#strict
+        ? (validation.value as Params)
+        : { ...result.params, ...(validation.value as Params) };
+
+      return { ...result, params };
+    }
+
+    if (this.#onError) {
+      return {
+        ...result,
+        params: this.#onError(result.name, result.params, validation.issues),
+      };
+    }
+
+    if (this.#mode === "development") {
+      console.error(
+        `${ERROR_PREFIX} Route "${result.name}": invalid search params`,
+        validation.issues,
+      );
+    }
+
+    const invalidKeys = getInvalidKeys(validation.issues);
+    const stripped = omitKeys(result.params, invalidKeys);
+    const route = this.#routesApi.get(result.name);
+    const defaults = route?.defaultParams;
+    const restored = defaults ? { ...defaults, ...stripped } : stripped;
+
+    return { ...result, params: restored };
+  }
+
+  #validateExistingDefaultParams(): void {
+    if (this.#mode !== "development") {
+      return;
+    }
+
+    const tree = this.#pluginApi.getTree() as unknown as
+      | { fullName?: string; children?: ReadonlyMap<string, unknown> }
+      | undefined;
+
+    /* v8 ignore next -- @preserve: getTree() always returns a RouteTree, defensive check */
+    if (!tree) {
+      return;
+    }
+
+    this.#walkTree(tree);
+  }
+
+  #walkTree(node: {
+    fullName?: string;
+    children?: ReadonlyMap<string, unknown>;
+  }): void {
+    if (node.fullName) {
+      this.#validateSingleRouteDefaultParams(node.fullName);
+    }
+
+    /* v8 ignore next 3 -- @preserve: children is always a Map in RouteTree */
+    if (node.children instanceof Map) {
+      for (const child of node.children.values()) {
+        if (child && typeof child === "object") {
+          this.#walkTree(
+            child as {
+              fullName?: string;
+              children?: ReadonlyMap<string, unknown>;
+            },
+          );
+        }
+      }
+    }
+  }
+
+  #validateSingleRouteDefaultParams(routeName: string): void {
+    const schema = this.#getSchema(routeName);
+
+    if (!schema) {
+      return;
+    }
+
+    const route = this.#routesApi.get(routeName);
+    const defaultParams = route?.defaultParams;
+
+    if (!defaultParams) {
+      return;
+    }
+
+    const validation = schema["~standard"].validate(defaultParams);
+
+    if (validation instanceof Promise) {
+      return;
+    }
+
+    if ("issues" in validation) {
+      console.warn(
+        `${ERROR_PREFIX} Route "${routeName}": defaultParams do not pass searchSchema`,
+        validation.issues,
+      );
+    }
+  }
+
+  #validateRoutesDefaultParams(routes: Route[], prefix = ""): void {
+    if (this.#mode !== "development") {
+      return;
+    }
+
+    for (const route of routes) {
+      /* v8 ignore next -- @preserve: Route.name is always a non-empty string */
+      if (route.name) {
+        const fullName = prefix ? `${prefix}.${route.name}` : route.name;
+
+        this.#validateSingleRouteDefaultParams(fullName);
+
+        if (route.children) {
+          this.#validateRoutesDefaultParams(route.children, fullName);
+        }
+      }
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,91 @@
+// packages/search-schema-plugin/src/types.ts
+
+import type { Params } from "@real-router/core";
+
+// =============================================================================
+// Standard Schema V1 (inline — zero external deps)
+// https://github.com/standard-schema/standard-schema
+// =============================================================================
+
+/** A single validation issue from Standard Schema V1. */
+export interface StandardSchemaV1Issue {
+  readonly message: string;
+  readonly path?:
+    | readonly (PropertyKey | { readonly key: PropertyKey })[]
+    | undefined;
+}
+
+/** Validation result — either success or failure. */
+export type StandardSchemaV1Result<Output = unknown> =
+  | { readonly value: Output }
+  | { readonly issues: readonly StandardSchemaV1Issue[] };
+
+/**
+ * Standard Schema V1 interface.
+ *
+ * Supported by Zod 3.24+, Valibot 1.0+, ArkType.
+ * The plugin doesn't depend on any specific schema library.
+ */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+  readonly "~standard": {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (
+      value: unknown,
+    ) =>
+      | StandardSchemaV1Result<Output>
+      | Promise<StandardSchemaV1Result<Output>>;
+    readonly types?:
+      | {
+          readonly input: Input;
+          readonly output: Output;
+        }
+      | undefined;
+  };
+}
+
+// =============================================================================
+// Plugin Options
+// =============================================================================
+
+export interface SearchSchemaPluginOptions {
+  /**
+   * Error handling mode.
+   * - "development" (default): strip invalid + console.error
+   * - "production": silent strip
+   *
+   * For recovery of invalid params use defaultParams (strip + merge + diagnostics).
+   * For filling absent params use .default() in schema (no diagnostics).
+   * .catch() is not recommended — suppresses errors, mode: "development" won't see the issue.
+   */
+  readonly mode?: "development" | "production";
+
+  /**
+   * Strip search params not described in schema.
+   * - false (default): unknown params pass through
+   * - true: unknown params are removed
+   *
+   * Per-route override: .strict() / .passthrough() in Zod schema.
+   */
+  readonly strict?: boolean;
+
+  /**
+   * Custom error handler (overrides mode completely).
+   * Must return cleaned params.
+   *
+   * Contract:
+   * - Returned params are used as-is, without re-validation.
+   *   Responsibility for correctness is on the callback author.
+   *   (Re-validation would risk infinite loops.)
+   * - Exceptions from onError propagate up without suppression.
+   *   Consistent with interceptor behavior in core.
+   * - When onError is set, neither console.error (mode: "development"),
+   *   nor silent strip (mode: "production") are executed.
+   *   All responsibility for diagnostics and recovery is on the callback.
+   */
+  readonly onError?: (
+    routeName: string,
+    params: Params,
+    issues: readonly StandardSchemaV1Issue[],
+  ) => Params;
+}

package/src/validation.ts

@@ -0,0 +1,25 @@
+import { ERROR_PREFIX } from "./constants";
+
+import type { SearchSchemaPluginOptions } from "./types";
+
+const VALID_MODES = new Set(["development", "production"]);
+
+export function validateOptions(options: SearchSchemaPluginOptions): void {
+  if (options.mode !== undefined && !VALID_MODES.has(options.mode)) {
+    throw new TypeError(
+      `${ERROR_PREFIX} Invalid mode: "${options.mode}". Must be "development" or "production".`,
+    );
+  }
+
+  if (options.strict !== undefined && typeof options.strict !== "boolean") {
+    throw new TypeError(
+      `${ERROR_PREFIX} Invalid strict option: expected boolean, got ${typeof options.strict}.`,
+    );
+  }
+
+  if (options.onError !== undefined && typeof options.onError !== "function") {
+    throw new TypeError(
+      `${ERROR_PREFIX} Invalid onError: expected function, got ${typeof options.onError}.`,
+    );
+  }
+}