@loozo/angular-router 0.0.3 → 0.0.4

package/README.md

@@ -1,12 +1,12 @@
 # @loozo/angular-router
 
-Typed routes for Angular's own router. You declare each route once with `defineRoute`: its path, its parent, and codecs for its path params, search params and fragments. A build step turns those declarations into an ordinary Angular `Routes` array plus a small typed module next to each route. Pages read parsed inputs as Angular Resources and build links and navigations that TypeScript checks against the target route.
+Typed routes for Angular's own router. Each route is a directory holding a `defineRoute` declaration and, usually, a page. The declaration holds the route's path, its parent, and codecs for its path params, search params and fragments; the directories give the path and parent, and a build step keeps them in step. The build step then turns the declarations into an ordinary Angular `Routes` array plus a small typed module next to each route. Pages read parsed inputs as Angular signals and build links and navigations that TypeScript checks against the target route.
 
 Angular still does all the routing: matching, activation, guards, resolvers, redirects, history and lazy loading. This package doesn't add a second router; it generates the configuration Angular consumes.
 
 Use it when you want route params, query params and links to be type-checked end to end in an Angular 22 application, and you're happy to run generation through the provided Angular builders.
 
-**Status:** experimental and not yet broadly battle-tested. Version `0.0.3`, MIT license.
+**Status:** experimental and not yet broadly battle-tested. Version `0.0.4`, MIT license.
 
 ## Install
 
@@ -30,23 +30,37 @@ Generation runs inside two Angular builders that replace your project's `build`
 
 In `angular.json`:
 
+`snippets/angular.json`
+
 ```json
-"build": {
-  "builder": "@loozo/angular-router:application",
-  "options": {
-    "tsconfig": "tsconfig.routes.json",
-    "scanDirectories": ["src/routes"],
-    "outDirectory": "generated",
-    "browser": "src/main.ts",
-    "index": "src/index.html",
-    "tsConfig": "tsconfig.app.json",
-    "outputPath": "dist/app"
-  },
-  "configurations": { "ci": { "check": true } }
-},
-"serve": {
-  "builder": "@loozo/angular-router:serve",
-  "options": { "buildTarget": "app:build" }
+{
+  "version": 1,
+  "projects": {
+    "app": {
+      "projectType": "application",
+      "root": "",
+      "sourceRoot": "src",
+      "architect": {
+        "build": {
+          "builder": "@loozo/angular-router:application",
+          "options": {
+            "tsconfig": "tsconfig.routes.json",
+            "scanDirectories": ["src/routes"],
+            "outDirectory": "generated",
+            "browser": "src/main.ts",
+            "index": "src/index.html",
+            "tsConfig": "tsconfig.app.json",
+            "outputPath": "dist/app"
+          },
+          "configurations": { "ci": { "check": true } }
+        },
+        "serve": {
+          "builder": "@loozo/angular-router:serve",
+          "options": { "buildTarget": "app:build" }
+        }
+      }
+    }
+  }
 }
 ```
 
@@ -54,6 +68,8 @@ The application builder takes the router options (`tsconfig`, `scanDirectories`,
 
 Note that `tsconfig` and `tsConfig` are different options. `tsconfig` is the TypeScript config used to find route declarations; `tsConfig` is Angular's own compilation config. The example app uses a small `tsconfig.routes.json` that extends the app config:
 
+`snippets/tsconfig.routes.json`
+
 ```json
 {
   "extends": "./tsconfig.app.json",
@@ -62,10 +78,31 @@ Note that `tsconfig` and `tsConfig` are different options. `tsconfig` is the Typ
 }
 ```
 
-Your app's `tsconfig.app.json` must include the generated files, for example `"include": ["src/**/*.ts", "generated/**/*.ts"]`.
+Your app's `tsconfig.app.json` must include the generated files, as its `"include"` does here:
+
+`snippets/tsconfig.app.json`
+
+```json
+{
+  "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"]
+}
+```
 
 Then install the generated routes with Angular's `provideRouter`:
 
+`snippets/src/main.ts`
+
 ```ts
 import { bootstrapApplication } from "@angular/platform-browser";
 import { provideRouter } from "@angular/router";
@@ -87,21 +124,23 @@ Commit the generated files along with your route declarations, and run the `ci`
 
 ## Quick start
 
-A route is a directory under the scan directory with a declaration file and, optionally, a page. In explicit mode (the default) the file names are up to you: the builder finds declarations by their `export default defineRoute(...)` and pages by their default-exported standalone component, not by name.
+A route is a directory under the scan directory with a page, a `route.ts` declaration, or both. The directories give the path: a page in `src/routes/products/$productId/` is the route `products/$productId`, where `$productId` is a path param. Add the page, and the first `ng build` or `ng serve` creates its declaration with a `stringParam` codec for `productId`. The declaration is yours to edit; here the codec is now `numberParam`, with a search param and fragments added:
+
+`snippets/src/routes/products/$productId/route.ts`
 
 ```ts
-// src/routes/product/definition.ts
-import { defineRoute, enumParam, numberParam, optionalSearchParam } from "@loozo/angular-router";
+import { defineRoute, enumParam, numberParam, withFallback } from "@loozo/angular-router";
 
 export default defineRoute("products/$productId", {
   params: { productId: numberParam },
-  search: { tab: optionalSearchParam(enumParam(["details", "reviews"])) },
+  search: { tab: withFallback(enumParam(["details", "reviews"]), "details") },
   fragments: ["summary", "reviews"],
 });
 ```
 
+`snippets/src/routes/products/$productId/page.ts`
+
 ```ts
-// src/routes/product/page.ts
 import { Component } from "@angular/core";
 import { RouterLink } from "@angular/router";
 import { injectRoute } from "./route.generated.js";
@@ -109,14 +148,8 @@ import { injectRoute } from "./route.generated.js";
 @Component({
   imports: [RouterLink],
   template: `
-    @if (route.params.hasValue() && route.search.hasValue()) {
-      <h1>Product {{ route.params.value().productId }}</h1>
-      <p>Tab: {{ route.search.value().tab ?? "details" }}</p>
-    } @else if (route.params.error()) {
-      <p>This product link isn't valid.</p>
-    } @else {
-      <p>Loading…</p>
-    }
+    <h1>Product {{ route.params().productId }}</h1>
+    <p>Tab: {{ route.search().tab }}</p>
     <a [routerLink]="reviews">Reviews</a>
   `,
 })
@@ -130,9 +163,9 @@ export default class Product {
 }
 ```
 
-Running `ng build` or `ng serve` writes `generated/routes.generated.ts`, `generated/destinations.generated.ts` and `src/routes/product/route.generated.ts`. The page is lazy-loaded with `loadComponent`.
+Running `ng build` or `ng serve` also writes `generated/routes.generated.ts`, `generated/destinations.generated.ts` and `src/routes/products/$productId/route.generated.ts`. The page is lazy-loaded with `loadComponent`. See [Filesystem route definitions](#filesystem-route-definitions) for how directories map to paths and parents, and [Explicit authoring](#explicit-authoring) to write every path and parent yourself instead.
 
-The template checks `hasValue()` before reading values. A URL such as `/products/abc` still activates this route, because it has no guards or resolvers to reject it first, and then the params fail to parse. Reading `value()` in that error state throws.
+The template reads the signals directly: they hold the activated route's values from the moment the page is created. A URL such as `/products/abc` doesn't match this route at all: a path param that fails to parse makes Angular try its next route, such as a `$segments[]` not-found route. A missing, repeated or unknown `tab` reads as its fallback, `"details"`.
 
 ## Declaring routes
 
@@ -140,7 +173,7 @@ The template checks `hasValue()` before reading values. A URL such as `/products
 defineRoute(path, config);
 ```
 
-`path` must be a string literal; TypeScript infers everything else without generic arguments.
+`path` must be a string literal; TypeScript infers everything else without generic arguments. By default the builder writes `path` and `parent` from the directories, and you write the rest.
 
 ### Paths
 
@@ -154,42 +187,51 @@ Paths are decoded segment text, not URLs:
 | `"docs/$segments[]"`    | A terminal catchall: zero or more remaining segments, parsed as an array |
 | `"$id/compare/$id"`     | A repeated param uses the same value in every position                   |
 
-No leading, trailing or repeated slashes. A catchall must be the last segment, a route can have at most one, and a catchall route can't have children. A root `$segments[]` route works as a not-found fallback; ordinary routes still match before it.
+No leading, trailing or repeated slashes. A catchall must be the last segment, a route can have at most one, and a catchall route can't have children. A root `$segments[]` route works as a not-found fallback; ordinary routes still match before it, unless their path params fail to parse.
 
 ### Config
 
-| Key                                                                    | Purpose                                                                                 |
-| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
-| `parent`                                                               | The parent route, imported as the parent declaration's default export                   |
-| `params`                                                               | One codec per path param, keyed by bare name. Required exactly when the path has params |
-| `search`                                                               | Codecs for query params                                                                 |
-| `fragments`                                                            | The fragment names this route accepts                                                   |
-| `resolve`                                                              | Resolvers that receive parsed inputs                                                    |
-| `canActivate`, `canActivateChild`, `canMatch`                          | Guards that receive parsed inputs                                                       |
-| `canDeactivate`, `providers`, `title`, `data`, `runGuardsAndResolvers` | Passed to Angular unchanged                                                             |
-| `redirect`                                                             | A typed redirect to another route                                                       |
+| Key                                                           | Purpose                                                                                 |
+| ------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `parent`                                                      | The parent route, imported as the parent declaration's default export                   |
+| `params`                                                      | One codec per path param, keyed by bare name. Required exactly when the path has params |
+| `search`                                                      | Codecs for query params                                                                 |
+| `fragments`                                                   | The fragment names this route accepts                                                   |
+| `resolve`                                                     | Resolvers that receive parsed inputs                                                    |
+| `canActivate`, `canActivateChild`, `canMatch`                 | Guards that receive parsed inputs                                                       |
+| `onInvalidParams`                                             | What happens when this route's own path params fail to parse, instead of not matching   |
+| `title`                                                       | A string, or a callback that receives parsed inputs                                     |
+| `canDeactivate`, `providers`, `data`, `runGuardsAndResolvers` | Passed to Angular unchanged                                                             |
+| `redirect`                                                    | A typed redirect to another route                                                       |
 
 Structural keys such as `path`, `children`, `component`, `loadComponent`, `redirectTo`, `pathMatch`, `matcher` and `outlet` are rejected: generation owns them.
 
 ### Parents
 
+`snippets/src/routes/teams/$teamId/route.ts`
+
 ```ts
-// src/routes/team/definition.ts
+import { defineRoute, numberParam } from "@loozo/angular-router";
+
 export default defineRoute("teams/$teamId", {
   params: { teamId: numberParam },
-  search: { score: optionalSearchParam(numberParam) },
+  search: { score: numberParam },
 });
+```
 
-// src/routes/item/definition.ts
-import team from "../team/definition.js";
+`snippets/src/routes/teams/$teamId/members/$memberId/route.ts`
 
-export default defineRoute("items/$id", {
+```ts
+import { defineRoute, numberParam } from "@loozo/angular-router";
+import team from "../../route.js";
+
+export default defineRoute("members/$memberId", {
   parent: team,
-  params: { id: numberParam },
+  params: { memberId: numberParam },
 });
 ```
 
-A child declares only its own params; it inherits its ancestors' params and search params, so the item route above has `params: { teamId, id }` and `search: { score }`. A child can't redeclare a param or search key its ancestors own. Pathless routes (`""` with a parent) add no URL segment but still contribute their inputs to descendants. A route with neither a page nor children is an error, unless it's a redirect.
+The member directory is inside the team directory, so the team route is its parent. The team directory has no page, so the team route is componentless: it groups its children and their shared inputs. A child declares only its own params; it inherits its ancestors' params and search params, so the member route above has `params: { teamId, memberId }` and `search: { score }`. A child can't redeclare a param or search key its ancestors own. Pathless routes (`""` with a parent) add no URL segment but still contribute their inputs to descendants. A route with neither a page nor children is an error, unless it's a redirect.
 
 ### Codecs
 
@@ -199,12 +241,29 @@ A child declares only its own params; it inherits its ancestors' params and sear
 | `numberParam`                | A finite number (`" 42 "`, `"1e3"` and `"0x10"` parse; blank and `NaN` fail) |
 | `booleanParam`               | Exactly `true` or `false`                                                    |
 | `enumParam(values)`          | One of the listed strings, typed as their union                              |
-| `optionalSearchParam(codec)` | Search only: the key may be absent                                           |
-| `nullableSearchParam(codec)` | Search only: the literal value `null` maps to `null`                         |
+| `withFallback(codec, value)` | Search only: reads `value` when the key is missing, repeated or invalid      |
+
+For a catchall, the codec applies to each segment, so `$segments[]` with `stringParam` produces `readonly string[]`.
+
+Search params never stop a route from matching, and they never fail. Every search key is optional:
+
+```ts
+search: {
+  page: withFallback(numberParam, 1),
+  sort: enumParam(["asc", "desc"]),
+}
+```
 
-Search params are required unless wrapped in `optionalSearchParam`. `optionalSearchParam(nullableSearchParam(codec))` distinguishes absent, `null` and a value. For a catchall, the codec applies to each segment, so `$segments[]` with `stringParam` produces `readonly string[]`.
+| Search key           | Missing      | Repeated or invalid |
+| -------------------- | ------------ | ------------------- |
+| Plain codec (`sort`) | Absent       | Absent              |
+| `withFallback`       | The fallback | The fallback        |
 
-A custom codec implements `ParamCodec<Value>`. `parse` receives the already-decoded text and may be async; `stringify` must be synchronous:
+`sort` reads as `"asc" | "desc" | undefined`. A key with a fallback always reads a value (`page` is a `number`, never `undefined`). Links, `createUrl`, navigation and redirects can leave out any search key.
+
+A custom codec implements `ParamCodec<Value>`. Both methods are synchronous: `parse` receives the already-decoded text and returns the value, and `stringify` returns the text:
+
+`snippets/src/slug.ts`
 
 ```ts
 import type { ParamCodec } from "@loozo/angular-router";
@@ -223,9 +282,11 @@ export const slug: ParamCodec<string> = {
 };
 ```
 
+Parsing should be pure and deterministic. A path codec runs twice per navigation: once while Angular matches routes and again for the activated route. A codec whose `parse` returns a Promise is a type error where you declare it; if one slips through (from JavaScript, say), the navigation fails with a `TypeError` rather than treating the value as invalid. Codecs don't run in an injection context and don't need one: load data in resolvers or guards instead.
+
 `defineRoute` never calls parsers, guards, resolvers or other callbacks; it only records them.
 
-The package root exports exactly `defineRoute`, `createUrl`, `stringParam`, `numberParam`, `booleanParam`, `enumParam`, `optionalSearchParam` and `nullableSearchParam`, plus the types `Route` and `ParamCodec`. The `_core`, `_generated` and `_generation` subpaths are internal coupling for generated code and `@loozo/angular-launch`, not application APIs.
+The package root exports exactly `defineRoute`, `createUrl`, `stringParam`, `numberParam`, `booleanParam`, `enumParam` and `withFallback`, plus the types `Route` and `ParamCodec`. The `_core`, `_generated` and `_generation` subpaths are internal coupling for generated code and `@loozo/angular-launch`, not application APIs.
 
 ### Fragments
 
@@ -235,9 +296,11 @@ The package root exports exactly `defineRoute`, `createUrl`, `stringParam`, `num
 
 `createUrl` builds a root-relative URL from a declaration, synchronously and without running any parsers:
 
+`snippets/src/product-url.ts`
+
 ```ts
 import { createUrl } from "@loozo/angular-router";
-import product from "./routes/product/definition.js";
+import product from "./routes/products/$productId/route.js";
 
 createUrl(product, {
   params: { productId: 42 },
@@ -246,7 +309,9 @@ createUrl(product, {
 }); // "/products/42?tab=reviews#summary"
 ```
 
-All path params are required, including inherited ones. Search params follow their codecs (required, optional or nullable). Query keys are sorted, values are percent-encoded, and a `/` inside a param value becomes `%2F`. Catchall values are arrays:
+All path params are required, including inherited ones. Search params are all optional: an omitted or `undefined` value leaves the key out. Query keys are sorted, values are percent-encoded, and a `/` inside a param value becomes `%2F`. Catchall values are arrays:
+
+`snippets/src/docs-url.ts`
 
 ```ts
 const docs = defineRoute("docs/$segments[]", { params: { segments: stringParam } });
@@ -264,36 +329,47 @@ Each route that has a page or descendants with pages gets a colocated `route.gen
 - `injectRoute()`: call it in an injection context (a field initializer or constructor) to get the handle for this route.
 - `destination`: an inert reference to this route that other routes can link to.
 
+`snippets/src/routes/teams/$teamId/items/$id/inputs.ts`
+
 ```ts
 import { injectRoute } from "./route.generated.js";
 
-const route = injectRoute();
+// injectRoute() needs an injection context, such as a component field initializer.
+export function readInputs() {
+  const route = injectRoute();
 
-route.params; // Resource<{ teamId: number; id: number } | undefined>
-route.search; // Resource<{ score?: number } | undefined>
-route.data; // Resource<{ item: Item } | undefined>, local resolver results only
+  route.params(); // { teamId: number; id: number }
+  route.search(); // { score?: number }
+  route.data(); // { item: Item }, local resolver results only
+}
 ```
 
-`params`, `search` and `data` are read-only Angular Resources, so `status()`, `isLoading()`, `hasValue()`, `value()` and `error()` all work. Check `hasValue()` before reading `value()`: reading the value of a Resource in the error state throws. While a navigation is in progress they're loading with `undefined` values rather than showing stale ones.
-
-`params` and `search` are parsed together and settle together. If a codec fails after the route has activated, both are in the error state, and the error has `source` (`"path"` or `"search"`), `key` and `reason` (`"missing"`, `"repeated"` or `"invalid"`). `data` settles on its own and isn't affected by that failure, so check `params` or `search` for parsing errors, not `data`. A failed navigation is different: when a guard or resolver throws, for example, the routes still on screen report that error in all three Resources instead of stale values.
+`params`, `search` and `data` are read-only Angular signals holding the activated route's values. They have a value from the first read, even in the page's constructor, so there's no loading state to check. While a navigation is in progress they keep the values of the page that's still on screen. When a navigation reuses this route with new values (a new id, or new search params), all three change together. When a navigation is cancelled or fails, they keep their values; handle the error where Angular reports it: the rejected `navigate` promise, the `NavigationError` event or `withNavigationErrorHandler`. To show that a navigation is pending, read Angular's `Router.currentNavigation()` signal.
 
 `data` holds this route's own resolver results only, not static `data`, parent data or the title.
 
-Parsing keeps Angular's stability pending until the values are published, so server rendering waits for async codecs.
+Reading `params` or `search` throws only if a path codec rejects a value it accepted while matching, which a pure codec never does.
 
 ### Links and navigation
 
 `link` returns an Angular `UrlTree` for `RouterLink`; `navigate` calls `Router.navigateByUrl` and returns Angular's own promise. Both take the same arguments:
 
+`snippets/src/routes/teams/$teamId/items/$id/links.ts`
+
 ```ts
-import { destination as report } from "../report/route.generated.js";
+import { destination as report } from "../../../../reports/$reportId/route.generated.js";
+import { injectRoute } from "./route.generated.js";
 
-route.link({ params: { teamId: 7, id: 8 } }); // this route
-route.link(".", { params: { teamId: 7, id: 8 } }); // same as above
-route.link("/teams/$teamId/items/$id", { params: { teamId: 7, id: 9 } }); // absolute
-route.link("../..", { params: { teamId: 7 } }); // relative
-route.navigate(report, { params: { reportId: 42 } }); // another route's destination
+// injectRoute() needs an injection context, such as a component field initializer.
+export function itemLinks() {
+  const route = injectRoute();
+
+  route.link({ params: { teamId: 7, id: 8 } }); // this route
+  route.link(".", { params: { teamId: 7, id: 8 } }); // same as above
+  route.link("/teams/$teamId/items/$id", { params: { teamId: 7, id: 9 } }); // absolute
+  route.link("../..", { params: { teamId: 7 } }); // relative
+  void route.navigate(report, { params: { reportId: 42 } }); // another route's destination
+}
 ```
 
 The first argument, when given, is a string literal selecting a route by its full authored path, never a concrete URL. Absolute selectors start with `/`. Relative selectors start with `.`, `./` or `..`; each `..` removes one segment of the path template, not one directory or parent. TypeScript only offers selectors that resolve to a known route, and the values are always typed for the selected route.
@@ -306,10 +382,14 @@ A `destination` must come from the same generated route set as the handle. Desti
 
 `canActivate`, `canActivateChild` and `canMatch` take arrays of functions whose first argument is the parsed inputs. Angular's native arguments follow:
 
+`snippets/src/routes/reports/$reportId/route.ts`
+
 ```ts
-export default defineRoute("teams/$teamId", {
-  params: { teamId: numberParam },
-  canActivate: [({ params }) => params.teamId > 0],
+import { defineRoute, numberParam } from "@loozo/angular-router";
+
+export default defineRoute("reports/$reportId", {
+  params: { reportId: numberParam },
+  canActivate: [({ params }) => params.reportId > 0],
 });
 ```
 
@@ -320,20 +400,37 @@ export default defineRoute("teams/$teamId", {
 | `canMatch`         | This route's own path params plus all search params; no ancestor path params |
 | `canDeactivate`    | Angular's native form, unchanged; no parsing                                 |
 
-Guards return anything Angular accepts (`boolean`, `UrlTree`, `RedirectCommand`, or a Promise or Observable of those). If a codec fails, the navigation fails with that error before the guard runs.
+Guards return anything Angular accepts (`boolean`, `UrlTree`, `RedirectCommand`, or a Promise or Observable of those). Search values recover before any guard runs (absent, or the fallback). Path params that fail to parse decide whether a route matches, so a guard only sees valid ones. Every callback (guards, resolvers, `title` and `onInvalidParams`) is called synchronously in the injection context Angular provides, so `inject()` works at its start, before any `await`.
 
-Resolvers get the parsed inputs too, and `inject()` works at the start of the callback:
+Every route with path params of its own or with search params gets a generated `canMatch` that parses them, search after the path. Search never decides the match. If a path param fails, the route doesn't match and Angular tries its next route, ending at the closest `$segments[]` catchall, so guards, resolvers and pages never see a value their codec rejects. Your own `canMatch` guards aren't called then. `onInvalidParams` replaces that outcome:
+
+```ts
+export default defineRoute("items/$id", {
+  params: { id: numberParam },
+  onInvalidParams: (error, routeConfig, segments, partialSnapshot) =>
+    new RedirectCommand(inject(Router).parseUrl("/items")),
+});
+```
+
+It receives the parse error (`source: "path"`, `key`, `reason`, and the codec's error as `cause`) and Angular's `canMatch` arguments, runs in the route's injection context, and returns `false` (try the next route), a `UrlTree` or a `RedirectCommand`, or a Promise or Observable of one. It can't return `true`: that, or throwing, fails the navigation. Write `async () => false as const` rather than `async () => false`, which TypeScript widens to `boolean`.
+
+A value that parses but doesn't exist, such as an unknown slug, is still yours to handle, for example with a `canActivate` that returns `new RedirectCommand(notFoundUrl, { browserUrl: state.url })`: Angular renders your not-found route while the address bar keeps the requested URL. The not-found URL must not match the guarded route again, or the redirect loops.
+
+Resolvers get the parsed inputs too:
+
+`snippets/src/routes/teams/$teamId/items/$id/route.ts`
 
 ```ts
 import { inject } from "@angular/core";
 import { defineRoute, numberParam } from "@loozo/angular-router";
-import team from "../team/definition.js";
-import { ItemCatalog } from "../../catalog.js";
+import team from "../../route.js";
+import { ItemCatalog } from "../../../../../catalog.js";
 
 export default defineRoute("items/$id", {
   parent: team,
   params: { id: numberParam },
   runGuardsAndResolvers: "paramsOrQueryParamsChange",
+  title: ({ params }) => `Item ${params.id}`,
   resolve: {
     item: ({ params, search }) => {
       const catalog = inject(ItemCatalog);
@@ -344,14 +441,18 @@ export default defineRoute("items/$id", {
 });
 ```
 
-Angular's default rerun policy, `paramsChange`, reruns resolvers when the path or its path/matrix params change, but not when only search params change. Set `runGuardsAndResolvers` when a resolver reads search params, as above.
+`title` is a string or a callback like a resolver's that returns the title (or a Promise or Observable of it). Angular runs a title callback alongside the route's resolvers, so it can't read their results.
+
+Angular's default rerun policy, `paramsChange`, reruns resolvers and the title callback when the path or its path/matrix params change, but not when only search params change. Set `runGuardsAndResolvers` when a resolver reads search params, as above.
 
 A redirect targets another declaration and must say what happens to search and fragment:
 
+`snippets/src/routes/teams/$teamId/old-items/$id/route.ts`
+
 ```ts
 import { defineRoute, numberParam } from "@loozo/angular-router";
-import team from "../team/definition.js";
-import item from "../item/definition.js";
+import team from "../../route.js";
+import item from "../../items/$id/route.js";
 
 export default defineRoute("old-items/$id", {
   parent: team,
@@ -364,50 +465,71 @@ export default defineRoute("old-items/$id", {
 });
 ```
 
-Params with the same name and compatible types are forwarded automatically; otherwise map them with `params: { targetKey: "sourceKey" }`. Values are parsed with the source codecs and written with the target's codecs. A redirect route can't have a page, children, `canActivate` or `canMatch`.
+Params with the same name and compatible types are forwarded automatically; otherwise map them with `params: { targetKey: "sourceKey" }`. Values are parsed with the source codecs and written with the target's codecs. A redirect route can't have a page, children, `canActivate`, `canMatch` or `onInvalidParams`; an invalid param in a redirect's source URL fails the navigation.
 
 ## Filesystem route definitions
 
-By default you write every declaration, including its path and parent. If you'd rather derive them from directories, set `autoDefineRoutes` on the application target:
-
-```json
-"options": {
-  "tsconfig": "tsconfig.routes.json",
-  "scanDirectories": ["src/routes"],
-  "outDirectory": "generated",
-  "autoDefineRoutes": {}
-}
+By default, directories give each route its path and parent. A directory becomes a route when it has a page or a declaration. The builder creates an editable `route.ts` in each directory that has a page but no declaration yet. Every other directory, the scan directory included, isn't a route: it adds its name to the paths of the routes below it. Each route's parent is the nearest route above it.
+
+| Directory          | Path contribution                                                           |
+| ------------------ | --------------------------------------------------------------------------- |
+| `products`, `$id`  | Its name                                                                    |
+| `+layout`          | `""`: a pathless route when it has a page or declaration, otherwise nothing |
+| The scan directory | `""`: the root route when it has a page or declaration, otherwise nothing   |
+| `-helpers`         | Nothing, and never a route; routes inside attach to the nearest route above |
+
+For example, with pages in `src/routes/$package/` and `src/routes/$package/guide/$guide/` but none in `guide/`:
+
+```text
+src/routes/
+  $package/
+    page.ts
+    route.ts          defineRoute("$package", …): no parent
+    guide/            no page: adds "guide" to the path below
+      $guide/
+        page.ts
+        route.ts      defineRoute("guide/$guide", …): parent is $package
 ```
 
-The builder then creates an editable `route.ts` in each directory that has a page but no declaration yet, and in the directories above it that need one. Directory names map to paths like this:
-
-| Directory          | Path contribution                                                       |
-| ------------------ | ----------------------------------------------------------------------- |
-| The scan directory | `""`                                                                    |
-| `products`, `$id`  | Its name                                                                |
-| `+layout`          | `""`: a pathless route                                                  |
-| `-helpers`         | Nothing: no route; directories inside attach to the nearest route above |
-
-For `src/routes/products/$productId/page.ts`, the generated declaration looks like this:
+The generated declaration for `$package/guide/$guide/page.ts` looks like this:
 
 ```ts
 import { defineRoute, stringParam } from "@loozo/angular-router";
-import parent from "../route.js";
+import parent from "../../route.js";
 
-export default defineRoute("$productId", { parent, params: { productId: stringParam } });
+export default defineRoute("guide/$guide", { parent, params: { guide: stringParam } });
 ```
 
-These files are yours. Change the codecs, add search params, guards and resolvers; the builder leaves them alone. When you move or rename a directory, it updates only the path literal, the `parent` import, and a param key it can rename unambiguously. When it can't make an edit safely (for example, a removed param whose codec you customized), generation fails and asks you to fix the file. It never deletes declarations.
+Angular gets `{ path: ":package", children: [{ path: "guide/:guide" }] }`, the same routes as writing those two declarations by hand, so `/angular-router/guide` on its own matches neither of them. If a directory without a page needs behavior of its own, such as a guard or resolver shared by the routes below it, add a declaration to it. It then becomes a componentless route and the parent of the routes below it. Angular also matches its bare URL (`/angular-router/guide`) when no child does, and SSR prerendering lists it as a route.
+
+These files are yours. Change the codecs, add search params, guards and resolvers; the builder leaves them alone. When you move or rename a directory, or a route above it appears or disappears, the builder updates only the path literal, the `parent` property and its import, and the local params where the change is unambiguous: it renames a single changed param key and keeps its codec, and when params are only added (for example, a declaration moved under a page-less `$team` directory) it keeps every existing codec and adds a `stringParam` codec per new param, also to a declaration that had no params. It reuses your `stringParam` import when the file has one, and otherwise imports it as `stringParam`, or `filesystemStringParam` when the file already uses that name. When it can't make an edit safely (for example, a removed param whose codec you customized, or params spread from another object), generation fails before writing anything. The error names the file, the path the directories give and the params it can't reconcile. Make that file's `params` match the directories, with one key per param in that path (or no `params` at all when the path has none), and the next run updates only the path; or move or rename the directory. Params spread from another object, kept in a shared variable or written as shorthand (`{ id }`) must first be written as plain `name: codec` properties. The builder never removes a param's codec itself, and the path always follows the directories. It never deletes declarations.
+
+A new import goes on its own line after the file's last import and any comment on that import's line. When that comment spans lines or carries a directive for the next line (such as `// @ts-expect-error`), the new import goes before the comment instead, so the directive keeps its target. A new parent import is named `parent`, or `filesystemParent` when the file already uses that name. When an existing parent import still points at a route that's no longer the parent, for example because you added a declaration between them, it's repointed and renamed to `parent`. When it no longer resolves, because its file moved or its target was deleted, it's repointed and keeps its name. An import that's used for more than the `parent` property is left alone, and a new parent import is added beside it.
+
+A `-` directory can't contain a page or a declaration with behavior.
 
-Directories without pages or declarations, like helper or empty directories, get no route. A `-` directory can't contain a page or a declaration with behavior.
+Set `"autoDefineRoutes": { "filename": "definition.ts" }` on the application target to seed a different file name. It must be a plain `.ts` file name that isn't a generated file name. That only affects new files; existing declarations are found by content, whatever their name.
+
+### Explicit authoring
+
+To write every path and parent yourself, turn filesystem definitions off:
+
+```json
+"options": {
+  "tsconfig": "tsconfig.routes.json",
+  "scanDirectories": ["src/routes"],
+  "outDirectory": "generated",
+  "autoDefineRoutes": false
+}
+```
 
-Use `{ "filename": "definition.ts" }` to seed a different file name. It must be a plain `.ts` file name that isn't a generated file name. That only affects new files; existing declarations are found by content, whatever their name.
+Declarations look the same, but the builder never creates or edits them, and directory names don't affect paths or parents. File names are up to you: the builder finds declarations by their `export default defineRoute(...)` and pages by their default-exported standalone component, not by name. A page still needs a declaration in its own directory; a page without one fails generation.
 
 ## Server rendering and hydration
 
-The generated routes work with Angular SSR and `provideClientHydration` without extra setup; there's no transfer cache or custom renderer. Parsing and resolvers keep Angular's stability pending, so server-rendered HTML contains parsed values. A codec whose promise never settles keeps rendering pending; the package adds no timeout.
+The generated routes work with Angular SSR and `provideClientHydration` without extra setup; there's no transfer cache or custom renderer. Parsing is synchronous and resolvers keep Angular's stability pending, so server-rendered HTML contains parsed values and resolved data.
 
-[`examples/angular-router/ssr-proof`](../../examples/angular-router/ssr-proof/README.md) is a working SSR app with async codecs, a resolver, a redirect and hydration.
+[`examples/angular-router/ssr-proof`](../../examples/angular-router/ssr-proof/README.md) is a working SSR app with a search fallback, a resolver, a redirect and hydration.
 
 ## What gets generated
 
@@ -431,26 +553,26 @@ Generation checks route structure, not your whole program. Type errors elsewhere
 
 All `@angular/build:application` options, plus:
 
-| Option             | Type                    | Default  | Description                                                                                                                         |
-| ------------------ | ----------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `tsconfig`         | `string`                | required | TypeScript config used to find route declarations. Relative to the workspace root.                                                  |
-| `scanDirectories`  | `string[]`              | required | Exactly one directory containing your routes. Relative to the `tsconfig` file's directory.                                          |
-| `outDirectory`     | `string`                | required | Where `routes.generated.ts` and `destinations.generated.ts` go. Relative to the workspace root; must be outside the scan directory. |
-| `check`            | `boolean`               | `false`  | Verify generated files without writing them. Fails on any drift.                                                                    |
-| `autoDefineRoutes` | `{ filename?: string }` | omitted  | Enable [filesystem route definitions](#filesystem-route-definitions). `filename` defaults to `route.ts`.                            |
+| Option             | Type                             | Default  | Description                                                                                                                                                        |
+| ------------------ | -------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `tsconfig`         | `string`                         | required | TypeScript config used to find route declarations. Relative to the workspace root.                                                                                 |
+| `scanDirectories`  | `string[]`                       | required | Exactly one directory containing your routes. Relative to the `tsconfig` file's directory.                                                                         |
+| `outDirectory`     | `string`                         | required | Where `routes.generated.ts` and `destinations.generated.ts` go. Relative to the workspace root; must be outside the scan directory.                                |
+| `check`            | `boolean`                        | `false`  | Verify generated files without writing them. Fails on any drift.                                                                                                   |
+| `autoDefineRoutes` | `false \| { filename?: string }` | `{}`     | [Filesystem route definitions](#filesystem-route-definitions), seeding `filename` (default `route.ts`). `false` selects [explicit authoring](#explicit-authoring). |
 
-The builder runs generation once, then the official application build. Invalid options stop the build before generation starts, and generation errors stop it before the Angular build runs. `watch: true` is rejected; use the serve builder for watching.
+The builder runs generation once, then the official application build. Invalid options stop the build before generation starts. Generation errors, including drift in check mode, are logged and fail the build before the Angular build runs. `watch: true` is rejected; use the serve builder for watching.
 
 ### `@loozo/angular-router:serve`
 
-All `@angular/build:dev-server` options, plus:
+All `@angular/build:dev-server` options, set in `angular.json` or on the command line (`ng serve --port 4300`), plus:
 
 | Option        | Type              | Default  | Description                                                                          |
 | ------------- | ----------------- | -------- | ------------------------------------------------------------------------------------ |
 | `buildTarget` | `string`          | required | A target that uses `@loozo/angular-router:application`. Router options come from it. |
 | `poll`        | `number \| false` | `1000`   | File-watch polling interval in milliseconds, or `false` for no default.              |
 
-The serve builder validates its dev-server options and the build target before generating anything. It watches the scan directory and regenerates when files are added, changed or removed. The initial generation must succeed before the dev server starts; later errors are logged, and the server keeps running until you fix them. The build target must not resolve `check: true`, because serving always writes generated files.
+Invalid options stop the serve builder before it generates anything, and so does an invalid build target. It watches the scan directory and regenerates when files are added, changed or removed. The initial generation must succeed before the dev server starts; if it fails, the error is logged and the builder reports a failed build. Later errors are logged, and the server keeps running until you fix them. The build target must not resolve `check: true`, because serving always writes generated files.
 
 Polling is on by default because Angular 22.2.2's native file watcher misses edits to files inside a renamed directory, which leaves the dev server serving stale output. Polling costs some idle CPU (about 3% of one core on the example app at 1000 ms, against under 0.1% without), and more on larger workspaces.