@loozo/angular-router 0.0.3 → 0.0.5

package/snippets/src/routes/teams/$teamId/members/$memberId/page.ts

@@ -0,0 +1,9 @@
+import { Component } from "@angular/core";
+import { injectRoute } from "./route.generated.js";
+
+@Component({
+  template: `<h1>Member {{ route.params().memberId }} of team {{ route.params().teamId }}</h1>`,
+})
+export default class Member {
+  readonly route = injectRoute();
+}

package/snippets/src/routes/teams/$teamId/members/$memberId/route.generated.ts

@@ -0,0 +1,24 @@
+// @loozo/angular-router routegen: owned route.generated.ts
+import { createDestination, injectGeneratedRoute } from '@loozo/angular-router/_generated';
+import { getRouteSet, type Destination, type Handle } from "../../../../../../generated/destinations.generated.js";
+export { defineRoute } from '@loozo/angular-router';
+/**
+ * Inert reference to this exact declaration for same-set handle link/navigate calls.
+ * No injection context is required; copies and foreign-set references are invalid.
+ * This is not an authored route and cannot be passed to the root createUrl function.
+ */
+export const destination: Destination<"src/routes/teams/$teamId/members/$memberId/route.ts"> = createDestination(() => getRouteSet(), "src/routes/teams/$teamId/members/$memberId/route.ts");
+/**
+ * Injects a typed handle bound to this exact generated activated route record.
+ *
+ * @remarks
+ * Call in an Angular injection context. The handle exposes readonly native
+ * params/search/data Signals and destination-typed link/navigate methods.
+ * Data includes local resolver results only, not static or inherited data.
+ * All navigation values are explicit; current inputs are never reused implicitly.
+ *
+ * @returns A noncallable handle for this declaration.
+ * @throws A synchronous wiring error outside an injection context or when the
+ * activated record does not carry this declaration's own generated identity.
+ */
+export function injectRoute(): Handle<"src/routes/teams/$teamId/members/$memberId/route.ts"> { return injectGeneratedRoute(getRouteSet(), "src/routes/teams/$teamId/members/$memberId/route.ts"); }

package/snippets/src/routes/teams/$teamId/members/$memberId/route.ts

@@ -0,0 +1,7 @@
+import { defineRoute, numberParam } from "@loozo/angular-router";
+import team from "../../route.js";
+
+export default defineRoute("members/$memberId", {
+  parent: team,
+  params: { memberId: numberParam },
+});

package/snippets/src/routes/teams/$teamId/old-items/$id/route.ts

@@ -0,0 +1,13 @@
+import { defineRoute, numberParam } from "@loozo/angular-router";
+import team from "../../route.js";
+import item from "../../items/$id/route.js";
+
+export default defineRoute("old-items/$id", {
+  parent: team,
+  params: { id: numberParam },
+  redirect: {
+    to: item,
+    search: { mode: "drop" }, // or "preserve", or { mode: "replace", values }
+    fragment: { mode: "drop" }, // or "preserve", or { mode: "replace", value }
+  },
+});

package/snippets/src/routes/teams/$teamId/route.generated.ts

@@ -0,0 +1,24 @@
+// @loozo/angular-router routegen: owned route.generated.ts
+import { createDestination, injectGeneratedRoute } from '@loozo/angular-router/_generated';
+import { getRouteSet, type Destination, type Handle } from "../../../../generated/destinations.generated.js";
+export { defineRoute } from '@loozo/angular-router';
+/**
+ * Inert reference to this exact declaration for same-set handle link/navigate calls.
+ * No injection context is required; copies and foreign-set references are invalid.
+ * This is not an authored route and cannot be passed to the root createUrl function.
+ */
+export const destination: Destination<"src/routes/teams/$teamId/route.ts"> = createDestination(() => getRouteSet(), "src/routes/teams/$teamId/route.ts");
+/**
+ * Injects a typed handle bound to this exact generated activated route record.
+ *
+ * @remarks
+ * Call in an Angular injection context. The handle exposes readonly native
+ * params/search/data Signals and destination-typed link/navigate methods.
+ * Data includes local resolver results only, not static or inherited data.
+ * All navigation values are explicit; current inputs are never reused implicitly.
+ *
+ * @returns A noncallable handle for this declaration.
+ * @throws A synchronous wiring error outside an injection context or when the
+ * activated record does not carry this declaration's own generated identity.
+ */
+export function injectRoute(): Handle<"src/routes/teams/$teamId/route.ts"> { return injectGeneratedRoute(getRouteSet(), "src/routes/teams/$teamId/route.ts"); }

package/snippets/src/routes/teams/$teamId/route.ts

@@ -0,0 +1,6 @@
+import { defineRoute, numberParam } from "@loozo/angular-router";
+
+export default defineRoute("teams/$teamId", {
+  params: { teamId: numberParam },
+  search: { score: numberParam },
+});

package/snippets/src/shell.ts

@@ -0,0 +1,9 @@
+import { Component } from "@angular/core";
+import { RouterOutlet } from "@angular/router";
+
+@Component({
+  selector: "app-shell",
+  imports: [RouterOutlet],
+  template: "<router-outlet />",
+})
+export default class Shell {}

package/snippets/src/slug.ts

@@ -0,0 +1,14 @@
+import type { ParamCodec } from "@loozo/angular-router";
+
+export const slug: ParamCodec<string> = {
+  parse(raw) {
+    if (!/^[a-z0-9-]+$/.test(raw)) {
+      throw new Error("invalid slug");
+    }
+
+    return raw;
+  },
+  stringify(value) {
+    return value;
+  },
+};

package/snippets/tsconfig.app.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "lib": ["ES2022", "DOM"],
+    "types": []
+  },
+  "angularCompilerOptions": { "strictTemplates": true },
+  "files": ["src/main.ts"],
+  "include": ["src/**/*.ts", "generated/**/*.ts"]
+}

package/snippets/tsconfig.routes.json

@@ -0,0 +1,5 @@
+{
+  "extends": "./tsconfig.app.json",
+  "files": [],
+  "include": ["src/**/*.ts"]
+}

package/types/loozo-angular-router-_core.d.ts

@@ -1,15 +1,16 @@
-import { ActivatedRouteSnapshot, GuardResult, MaybeAsync, PartialMatchRouteSnapshot, RedirectCommand, Route as Route$1, RouterStateSnapshot, RunGuardsAndResolvers, UrlSegment } from "@angular/router";
+import { ActivatedRouteSnapshot, GuardResult, MaybeAsync, PartialMatchRouteSnapshot, RedirectCommand, Route as Route$1, RouterStateSnapshot, RunGuardsAndResolvers, UrlSegment, UrlTree } from "@angular/router";
 import { Observable } from "rxjs";
 /**
  * Converts one decoded path or search value to and from an application value.
  *
  * @remarks
- * Parsing may be asynchronous; stringification must be synchronous. Neither
- * method performs URL encoding. Codecs have no Angular injection-context
- * guarantee, and their returned objects are not recursively frozen.
+ * Both methods are synchronous, and parsing should be pure and deterministic:
+ * like Angular's matching callbacks, it runs once while matching and again for
+ * the activated route. Neither method performs URL encoding. Codecs have no
+ * Angular injection context, and their returned objects are not recursively frozen.
  * For a terminal `$name[]` path, this codec applies to each element separately.
  *
- * @typeParam Value - The logical value, not a promise of that value.
+ * @typeParam Value - The logical value, never a promise of that value.
  *
  * @example
  * ```ts
@@ -24,11 +25,12 @@ interface ParamCodec<Value> {
    * Parses one already percent-decoded value; do not decode it again.
    *
    * @param raw - A single logical string from Angular's URL inputs.
-   * @returns The logical value or a promise for it.
-   * @throws An application error for invalid input; generated input parsing
-   * reports throws and rejections as invalid path/search values with a cause.
+   * @returns The logical value, synchronously. Returning a promise or other
+   * thenable is a programming error that fails the navigation with a TypeError.
+   * @throws An application error for invalid input: an invalid path value makes
+   * the route not match, and an invalid search value reads as absent or as its fallback.
    */
-  parse(raw: string): Value | Promise<Value>;
+  parse(raw: string): Value;
   /**
    * Serializes one logical value without percent-encoding it.
    *
@@ -38,23 +40,34 @@ interface ParamCodec<Value> {
    */
   stringify(value: Value): string;
 }
-declare const searchPresence: unique symbol;
-/** A search-only codec whose key may be omitted or supplied as `undefined`. */
-type OptionalCodec<Value> = ParamCodec<Value | undefined> & {
-  readonly [searchPresence]: "optional";
-};
-/** A search-only codec that represents explicit `null` as the text `"null"`. */
-type NullableCodec<Value> = ParamCodec<Value | null> & {
-  readonly [searchPresence]: "nullable";
+declare const searchFallback: unique symbol;
+/**
+ * A search-only codec whose key reads a fallback value when it is missing,
+ * repeated or invalid, while URL creation may still omit it.
+ */
+type FallbackCodec<Value> = ParamCodec<Value> & {
+  readonly [searchFallback]: true;
 };
 type PathCodec = ParamCodec<any> & {
-  readonly [searchPresence]?: never;
+  readonly [searchFallback]?: never;
 };
 type CodecValue<Codec> = Codec extends ParamCodec<infer Value> ? Value : never;
-type IsOptional<Codec> = Codec extends {
-  readonly [searchPresence]: "optional";
+type HasFallback<Codec> = Codec extends {
+  readonly [searchFallback]: true;
 } ? true : false;
-export declare function codecPresence(codec: object): "optional" | "nullable" | undefined;
+/** Type-only marker: a codec whose parse returns a promise fails where it is declared. */
+interface SynchronousParse {
+  /** Never present: `parse` must return its value synchronously, not a Promise. */
+  readonly "ParamCodec.parse must return its value synchronously, not a Promise": never;
+}
+type ParseResult<Codec> = Codec extends {
+  parse(raw: string): infer Result;
+} ? Result : never;
+type SyncValue<Value> = Extract<Value, PromiseLike<unknown>> extends never ? unknown : SynchronousParse;
+type SyncCodecs<Codecs> = { [Key in keyof Codecs]: SyncValue<ParseResult<Codecs[Key]>>; };
+export declare function codecFallback(codec: object): {
+  readonly value: unknown;
+} | undefined;
 declare function validateCodec(codec: unknown): asserts codec is ParamCodec<any>;
 /**
  * Preserves strings verbatim, including empty strings and literal percent text.
@@ -94,44 +107,30 @@ export declare const booleanParam: ParamCodec<boolean>;
  */
 export declare function enumParam<const Values extends readonly string[]>(values: Values): ParamCodec<Values[number]>;
 /**
- * Makes a search key optional without changing the handling of present values.
- *
- * @remarks
- * Generated parsing omits absent keys; URL creation omits absent or `undefined`
- * values. The wrapper's parser delegates present strings unchanged, preserving
- * promises and failures. Its stringifier cannot serialize `undefined` directly.
- * This wrapper is not a path codec. For optional nullable values, wrap
- * {@link nullableSearchParam} with this function, not the other way around.
- *
- * @typeParam Value - The wrapped codec's logical value.
- * @param codec - The codec used for present search values.
- * @returns A search-only codec allowing omission.
- * @throws TypeError if the codec lacks callable parse/stringify methods.
- */
-export declare function optionalSearchParam<Value>(codec: ParamCodec<Value>): OptionalCodec<Value>;
-/**
- * Adds explicit null to a search codec, represented by the decoded text `"null"`.
+ * Gives a search key a value read in place of a missing, repeated or invalid one.
  *
  * @remarks
- * The key remains required unless wrapped with {@link optionalSearchParam}.
- * Non-null values delegate unchanged, including promise/failure identity. The
- * text `"null"` is reserved by this wrapper even if the inner codec accepts it.
- * This wrapper is not a path codec and cannot wrap an optional search codec.
- *
- * @typeParam Value - The wrapped codec's non-null logical value.
- * @param codec - The codec used for values other than null.
- * @returns A search-only codec accepting and serializing null.
- * @throws TypeError if the codec is malformed or is an optional search wrapper.
+ * Every search key is optional: a plain codec's key reads as absent when its
+ * value is missing, repeated or invalid. With a fallback, the key always reads a
+ * value of the codec's type, while URL creation, links, navigation and redirect
+ * replacements may still omit it. The fallback is returned as is: it is neither
+ * parsed nor copied. Present values delegate to the wrapped codec unchanged.
+ * Fallback codecs are search-only: a path param can't use one.
  *
  * @example
  * ```ts
- * const score = optionalSearchParam(nullableSearchParam(numberParam));
- * // Omission, null, and a present number remain distinct.
+ * search: { page: withFallback(numberParam, 1) }
+ * // ?page=abc, ?page=1&page=2 and no page all read as 1.
  * ```
+ *
+ * @typeParam Value - The wrapped codec's logical value.
+ * @param codec - The codec used for present search values.
+ * @param fallback - The value read when the key is missing, repeated or invalid.
+ * @returns A search-only codec that reads the fallback in place of an absent value.
+ * @throws TypeError if the codec lacks callable parse/stringify methods or already
+ * has a fallback.
  */
-export declare function nullableSearchParam<Value>(codec: ParamCodec<Value> & {
-  readonly [searchPresence]?: "nullable";
-}): NullableCodec<Value>;
+export declare function withFallback<Value>(codec: ParamCodec<Value> & SyncValue<NoInfer<Value>>, fallback: NoInfer<Value>): FallbackCodec<Value>;
 type ValidName<Name extends string> = Name extends "" | "__proto__" | `...${string}` | `${string}?${string}` | `${string}*${string}` | `${string}[]${string}` ? false : true;
 type SegmentValid<Segment extends string> = Segment extends `$${infer Name}` ? ValidName<Name> : Segment extends "" | "." | ".." | "*" | "**" | `:${string}` ? false : true;
 type ValidateSegments<Path extends string, Scalars extends string = never> = Path extends `${infer Head}/${infer Tail}` ? Head extends `$${string}[]` ? false : SegmentValid<Head> extends true ? ValidateSegments<Tail, Scalars | ScalarName<Head>> : false : Path extends `$${infer Name}[]` ? ValidName<Name> extends true ? Name extends Scalars ? false : true : false : SegmentValid<Path>;
@@ -160,15 +159,19 @@ declare const routeBrand: unique symbol;
  *
  * @typeParam Path - The local authored path literal, not the effective URL path.
  * @typeParam Params - Effective inherited and local logical path values.
- * @typeParam Search - Effective inherited and local logical search values.
+ * @typeParam Search - Effective inherited and local logical search values; keys
+ * without a fallback are optional. URL creation accepts every key as optional.
  * @typeParam Resolvers - Local resolver callbacks; data unwraps Promise/Observable
  * results and excludes Angular RedirectCommand values.
  * @typeParam Fragments - This declaration's own allowed fragment-name union.
  * @typeParam Catchall - Whether the declaration is a terminal catchall leaf.
  */
 interface Route<Path extends string, Params, Search, Resolvers = {}, Fragments extends string = string, Catchall extends boolean = CatchallName<Path> extends never ? false : true> {
+  /** Type-only nominal brand carrying fragment and catchall metadata; not populated at runtime. */
   readonly [routeBrand]: {
+    /** Type-only: this declaration's own allowed fragment-name union. */
     readonly fragments: Fragments;
+    /** Type-only: whether this declaration is a terminal catchall leaf. */
     readonly catchall: Catchall;
   };
   /** The exact local authored path supplied to `defineRoute`. */
@@ -189,13 +192,18 @@ type Resolved<Callback> = Callback extends ((...args: any[]) => infer Value) ? E
 type AnyRoute = Route<string, any, any, any, any, boolean>;
 /** Extracts a declaration's effective inherited and local path-value types. */
 type ParamsOf<Target> = Target extends Route<string, infer Params, any, any, any, boolean> ? Params : {};
-/** Extracts effective search-value types, retaining optional/nullable modifiers. */
+/** Extracts effective parsed search-value types; keys without a fallback are optional. */
 type SearchOf<Target> = Target extends Route<string, any, infer Search, any, any, boolean> ? Search : {};
+/**
+ * Effective search values accepted by URL creation: every key may be omitted or
+ * `undefined`, and a supplied value has the key's codec type.
+ */
+type SearchInputOf<Target> = { readonly [Key in keyof SearchOf<Target>]?: SearchOf<Target>[Key] | undefined; };
 /** Extracts only the selected declaration's own allowed fragment-name union. */
 type FragmentsOf<Target> = Target extends Route<string, any, any, any, infer Fragments, boolean> ? Fragments : never;
 type CodecMap = Record<string, ParamCodec<any>>;
 type LocalParams<Path extends string, Codecs> = { readonly [Key in keyof Codecs]: Key extends CatchallName<Path> ? readonly CodecValue<Codecs[Key]>[] : CodecValue<Codecs[Key]>; };
-type SearchValues<Codecs> = { readonly [Key in keyof Codecs as IsOptional<Codecs[Key]> extends true ? never : Key]: CodecValue<Codecs[Key]>; } & { readonly [Key in keyof Codecs as IsOptional<Codecs[Key]> extends true ? Key : never]?: CodecValue<Codecs[Key]>; };
+type SearchValues<Codecs> = { readonly [Key in keyof Codecs as HasFallback<Codecs[Key]> extends true ? Key : never]: CodecValue<Codecs[Key]>; } & { readonly [Key in keyof Codecs as HasFallback<Codecs[Key]> extends true ? never : Key]?: CodecValue<Codecs[Key]>; };
 type EffectiveParams<Path extends string, Codecs, Parent> = ParamsOf<Parent> & LocalParams<Path, Codecs>;
 type EffectiveSearch<Codecs, Parent> = SearchOf<Parent> & SearchValues<Codecs>;
 /**
@@ -205,7 +213,7 @@ type EffectiveSearch<Codecs, Parent> = SearchOf<Parent> & SearchValues<Codecs>;
 type Inputs<Params, Search> = {
   /** Logical positional path values, not Angular's matrix-merged params. */
   readonly params: Readonly<Params>;
-  /** Logical declared search values; absent optional keys are omitted. */
+  /** Logical declared search values; keys without a value or fallback are absent. */
   readonly search: Readonly<Search>;
 };
 /**
@@ -219,6 +227,16 @@ type Inputs<Params, Search> = {
  * @returns A scalar, Promise, Observable or RedirectCommand result.
  */
 type Resolver<Params, Search> = (inputs: Inputs<Params, Search>, snapshot: ActivatedRouteSnapshot, state: RouterStateSnapshot) => unknown;
+/**
+ * A title callback, run by Angular as a resolver: entered in Angular's injection context
+ * after successful effective input parsing, alongside the route's local resolvers.
+ *
+ * @param inputs - Effective inherited and local parsed values.
+ * @param snapshot - The declaring route's native snapshot.
+ * @param state - The native router state being resolved.
+ * @returns The page title, synchronously or via Promise/Observable.
+ */
+type TitleResolver<Params, Search> = (inputs: Inputs<Params, Search>, snapshot: ActivatedRouteSnapshot, state: RouterStateSnapshot) => MaybeAsync<string>;
 /**
  * An activation callback entered in Angular's injection context after parsing.
  * Parse failures prevent entry and propagate as navigation errors, not false.
@@ -232,7 +250,9 @@ type Resolver<Params, Search> = (inputs: Inputs<Params, Search>, snapshot: Activ
 type ActivationGuard<Params, Search> = (inputs: Inputs<Params, Search>, snapshot: ActivatedRouteSnapshot, state: RouterStateSnapshot) => MaybeAsync<GuardResult>;
 /**
  * A candidate matching callback entered in Angular's injection context after parsing.
- * Unlike activation callbacks, it has no ancestor positional path values.
+ * Unlike activation callbacks, it has no ancestor positional path values. It isn't
+ * entered when the candidate's own path params fail to parse; the route then
+ * doesn't match, or its onInvalidParams handler decides.
  *
  * @param inputs - Local positional params plus effective inherited/local search.
  * @param routeConfig - Angular's native candidate configuration.
@@ -241,13 +261,37 @@ type ActivationGuard<Params, Search> = (inputs: Inputs<Params, Search>, snapshot
  * @returns A native guard result; false permits Angular's next candidate.
  */
 type MatchingGuard<Params, Search> = (inputs: Inputs<Params, Search>, routeConfig: Route$1, segments: UrlSegment[], partialSnapshot: PartialMatchRouteSnapshot) => MaybeAsync<GuardResult>;
-type RequiredKeys<Value> = { [Key in keyof Value]-?: Pick<Value, Key> extends Required<Pick<Value, Key>> ? Key : never; }[keyof Value];
-type SearchInput<Schema, Keys extends keyof Schema> = keyof Schema extends never ? Record<string, never> : Pick<Schema, RequiredKeys<Schema> | Keys>;
+/**
+ * The error passed to onInvalidParams: the first of the candidate's own path
+ * params that failed to parse. The error class is not exported.
+ */
+type PathInputError = Error & {
+  /** Always `"path"`: search never takes part in matching. */
+  readonly source: "path";
+  /** The failed param's name. */
+  readonly key: string;
+  /** Why the raw value was rejected; the codec failure is the error's `cause`. */
+  readonly reason: "missing" | "repeated" | "invalid";
+};
+/**
+ * Decides what a candidate whose own path params fail to parse does instead of
+ * not matching. Entered in Angular's injection context; throwing or rejecting
+ * fails the navigation.
+ *
+ * @param error - The path input error, with the codec failure as its cause.
+ * @param routeConfig - Angular's native candidate configuration.
+ * @param segments - Angular's candidate URL segments.
+ * @param partialSnapshot - Angular's native partial matching snapshot.
+ * @returns `false` to try Angular's next candidate, or a UrlTree/RedirectCommand
+ * to redirect; `true` is rejected because the params are invalid.
+ */
+type InvalidParamsHandler = (error: PathInputError, routeConfig: Route$1, segments: UrlSegment[], partialSnapshot: PartialMatchRouteSnapshot) => MaybeAsync<false | UrlTree | RedirectCommand>;
+type SearchInput<Schema, Keys extends keyof Schema> = keyof Schema extends never ? Record<string, never> : Pick<Schema, Keys>;
 /**
  * Explicit values for URL creation and generated link/navigation calls.
- * Effective path and required search keys must be present; optional search may
- * be omitted. Paramless/searchless routes forbid those fields. Fragment names
- * come only from the destination's own declaration.
+ * Effective path keys must be present; every search key may be omitted.
+ * Paramless/searchless routes forbid those fields. Fragment names come only
+ * from the destination's own declaration.
  *
  * @typeParam Target - The selected route declaration.
  * @typeParam SearchKeys - Supplied search keys inferred by each call to preserve
@@ -259,15 +303,12 @@ type UrlValues<Target extends AnyRoute, SearchKeys extends keyof SearchOf<Target
 } : {
   /** All effective path values; catchalls are readonly element-value arrays. */
   params: ParamsOf<Target>;
-}) & (keyof SearchOf<Target> extends never ? {
+}) & (keyof SearchInputOf<Target> extends never ? {
   /** Forbidden when the destination has no search declarations. */
   search?: never;
-} : RequiredKeys<SearchOf<Target>> extends never ? {
-  /** Optional-only search; absent or undefined optional values are omitted. */
-  search?: SearchInput<SearchOf<Target>, SearchKeys>;
 } : {
-  /** All required search values plus any supplied optional values. */
-  search: SearchInput<SearchOf<Target>, SearchKeys>;
+  /** Any declared search values; absent or undefined values are omitted. */
+  search?: SearchInput<SearchInputOf<Target>, SearchKeys & keyof SearchInputOf<Target>>;
 }) & (FragmentsOf<Target> extends never ? {
   /** Forbidden when this declaration has no fragment names. */
   fragment?: never;
@@ -278,35 +319,30 @@ type UrlValues<Target extends AnyRoute, SearchKeys extends keyof SearchOf<Target
 type CompatibleKeys<Source, Value> = { [Key in keyof Source]: Source[Key] extends Value ? Key : never; }[keyof Source];
 type Mapping<Source, Destination> = { [Key in keyof Destination]: CompatibleKeys<Source, Destination[Key]>; };
 type Forwardable<Source, Destination> = { [Key in keyof Destination]: Key extends keyof Source ? Source[Key] extends Destination[Key] ? never : Key : Key; }[keyof Destination] extends never ? true : false;
-type Preservable<Source, Destination> = { [Key in RequiredKeys<Destination>]: Key extends RequiredKeys<Source> ? Source[Key & keyof Source] extends Destination[Key] ? never : Key : Key; }[RequiredKeys<Destination>] extends never ? true : false;
 /**
  * A typed redirect to a genuine authored declaration, not a concrete URL.
  *
  * @remarks
  * Params map destination keys to compatible effective source path keys. Omission
  * forwards by name only when all target keys are compatible. Search and fragment
- * policies are mandatory. Search preserve validates destination-declared values
- * but retains original query text and unknown keys; drop requires no required
- * target search keys; replace uses explicit target-typed values (`{}` is allowed
- * for searchless targets). Fragment preserve retains the incoming raw name,
- * whereas replace requires a target-declared name. Angular executes the redirect.
+ * policies are mandatory. Search preserve retains the original query text, drop
+ * removes it, and replace serializes explicit target-typed values (`{}` removes
+ * the query). Fragment preserve retains the incoming raw name, whereas replace
+ * requires a target-declared name. Angular executes the redirect.
  */
-type Redirect<SourceParams, SourceSearch, Target extends AnyRoute, SearchKeys extends keyof SearchOf<Target>> = {
+type Redirect<SourceParams, Target extends AnyRoute, SearchKeys extends keyof SearchOf<Target>> = {
   /** The already constructed target; generation requires a direct default import. */
   to: Target;
   /** Explicit query policy: preserve incoming text, drop it, or replace with values. */
   search: {
     /** Discard incoming queries and serialize explicit target-typed values. */
     mode: "replace";
-    /** Required target search keys plus selected optional keys; unknown keys fail. */
-    values: SearchInput<SearchOf<NoInfer<Target>>, SearchKeys>;
-  } | (RequiredKeys<SearchOf<Target>> extends never ? {
-    /** Remove all incoming query values; target required keys are forbidden. */
-    mode: "drop";
-  } : never) | (Preservable<SourceSearch, SearchOf<Target>> extends true ? {
-    /** Keep original query text, validating destination-declared cardinality/values. */
-    mode: "preserve";
-  } : never);
+    /** Any target search keys; unknown keys fail. */
+    values: SearchInput<SearchInputOf<NoInfer<Target>>, SearchKeys & keyof SearchInputOf<NoInfer<Target>>>;
+  } | {
+    /** Keep the original query text, or remove all incoming query values. */
+    mode: "preserve" | "drop";
+  };
   /** Explicit hash policy; preserved incoming names need not be declared. */
   fragment: {
     /** Keep the raw incoming hash, or remove it entirely. */
@@ -331,8 +367,8 @@ type Redirect<SourceParams, SourceSearch, Target extends AnyRoute, SearchKeys ex
 type RouteConfig<Path extends string, Parent extends AnyRoute | undefined, Params extends Record<string, PathCodec>, Search extends CodecMap, Resolvers, Fragments extends readonly string[], Target extends AnyRoute | undefined, ReplacementKeys extends keyof SearchOf<Target>> = {
   /** Genuine authored parent; pathless nodes retain inherited input ownership. */
   parent?: Parent & (Parent extends Route<string, any, any, any, any, true> ? never : unknown);
-  /** Local search codecs; keys are required unless wrapped with optionalSearchParam. */
-  search?: Search & Record<Extract<keyof Search, keyof SearchOf<Parent>>, never>;
+  /** Local search codecs; a key is absent unless present and valid, or wrapped withFallback. */
+  search?: Search & Record<Extract<keyof Search, keyof SearchOf<Parent>>, never> & SyncCodecs<NoInfer<Search>>;
   /** Local parsed-input resolvers; not snapshot-first native ResolveFn callbacks. */
   resolve?: Resolvers & Record<PropertyKey, Resolver<EffectiveParams<Path, Params, Parent>, EffectiveSearch<Search, Parent>>> & {
     __loozoAngularRouterRouteId?: never;
@@ -347,8 +383,8 @@ type RouteConfig<Path extends string, Parent extends AnyRoute | undefined, Param
   canDeactivate?: Route$1["canDeactivate"];
   /** Native route-scoped providers; provider factories are not run at declaration. */
   providers?: Route$1["providers"];
-  /** Native static title or title resolver, not a parsed-input callback. */
-  title?: Route$1["title"];
+  /** A static title, or a parsed-input callback; not a snapshot-first native ResolveFn. */
+  title?: string | TitleResolver<EffectiveParams<Path, Params, Parent>, EffectiveSearch<Search, Parent>>;
   /** Native static data; cannot set the reserved __loozoAngularRouterRouteId key. */
   data?: Route$1["data"] & {
     __loozoAngularRouterRouteId?: never;
@@ -358,14 +394,21 @@ type RouteConfig<Path extends string, Parent extends AnyRoute | undefined, Param
   params?: never;
 } : {
   /** Exactly the local placeholder names; catchall codecs apply per element. */
-  params: Params & Record<PathNames<Path>, PathCodec> & Record<Exclude<keyof Params, PathNames<Path>> | Extract<keyof Params, keyof ParamsOf<Parent>>, never>;
+  params: Params & Record<PathNames<Path>, PathCodec> & Record<Exclude<keyof Params, PathNames<Path>> | Extract<keyof Params, keyof ParamsOf<Parent>>, never> & SyncCodecs<NoInfer<Params>>;
 }) & (Target extends AnyRoute ? {
-  /** Typed native redirect, incompatible with own canActivate/canMatch fields. */
-  redirect: Redirect<EffectiveParams<Path, Params, Parent>, EffectiveSearch<Search, Parent>, Target, ReplacementKeys>;
+  /** Typed native redirect, incompatible with own canActivate/canMatch/onInvalidParams fields. */
+  redirect: Redirect<EffectiveParams<Path, Params, Parent>, Target, ReplacementKeys>;
   canActivate?: never;
   canMatch?: never;
+  onInvalidParams?: never;
 } : {
   redirect?: never;
+  /**
+   * Decides what happens when this route's own path params fail to parse;
+   * without it the route doesn't match and Angular tries its next candidate.
+   * Only routes with local path params accept it.
+   */
+  onInvalidParams?: PathNames<Path> extends never ? never : InvalidParamsHandler;
   /** Activation guards with effective inherited and local parsed inputs. */
   canActivate?: readonly ActivationGuard<EffectiveParams<Path, Params, Parent>, EffectiveSearch<Search, Parent>>[];
   /** Matching guards with local path params and effective search only. */
@@ -383,7 +426,6 @@ interface RouteMetadata {
   readonly config: Readonly<Record<string, unknown>>;
 }
 export declare function routeMetadata(route: unknown): RouteMetadata;
-declare function validateSearchValues(codecs: Readonly<Record<string, ParamCodec<any>>>, values: Record<string, unknown>): void;
 /**
  * Declares a nominal typed route without executing codecs or native callbacks.
  *
@@ -410,13 +452,14 @@ declare function validateSearchValues(codecs: Readonly<Record<string, ParamCodec
  * generator-owned and cannot be overridden.
  * @returns A frozen route preserving inferred effective input and local data types.
  * @throws TypeError for invalid paths/configuration, missing or extra local
- * codecs, inherited key conflicts, or nongenuine parent/redirect routes.
+ * codecs, fallback codecs in path params, inherited key conflicts, or
+ * nongenuine parent/redirect routes.
  *
  * @example
  * ```ts
  * const product = defineRoute("products/$productId", {
  *   params: { productId: numberParam },
- *   search: { tab: optionalSearchParam(enumParam(["details", "reviews"])) },
+ *   search: { tab: withFallback(enumParam(["details", "reviews"]), "details") },
  *   fragments: ["summary", "reviews"],
  * });
  * ```
@@ -427,15 +470,14 @@ export declare function defineRoute<const Path extends string, Parent extends An
  *
  * @remarks
  * Includes inherited path/search declarations, but only this route's fragment
- * names. Every effective path value and required search key must be supplied.
- * Optional-only search may be omitted; searchless/paramless routes forbid those
- * records. Catchalls require readonly arrays, including a valid empty array.
+ * names. Every effective path value must be supplied; any search key may be
+ * omitted. Searchless/paramless routes forbid those records. Catchalls require readonly arrays, including a valid empty array.
  * Values are never taken from a current navigation.
  *
  * Stringifies without calling parsers, guards, resolvers or redirects. Static
  * segments and logical values are component-encoded (also escaping parentheses),
- * so a dynamic slash becomes `%2F`. Search keys are globally sorted; optional
- * `undefined` values are omitted. An empty effective path produces `/`.
+ * so a dynamic slash becomes `%2F`. Search keys are globally sorted; omitted
+ * and `undefined` values are left out. An empty effective path produces `/`.
  * Redirect declarations serialize their source URL, not their redirect target.
  *
  * @param route - A genuine declaration from this physical package instance,