@loozo/angular-router 0.0.7 → 0.0.9

package/README.md

@@ -6,7 +6,7 @@ Angular still does all the routing: matching, activation, guards, resolvers, red
 
 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. MIT license.
+**Status:** pre-1.0: breaking changes come only in minor releases (see [Versions](#versions)). MIT license.
 
 ## Install
 
@@ -22,7 +22,23 @@ Peer dependencies:
 | `@angular/router` | `^22.0.0` |
 | `@angular/build`  | `~22.2.0` |
 
-The package is tested against Angular 22.2.2. The `@angular/build` range is narrow on purpose: the application builder's options schema is Angular's own application schema at the version the package was built against. An option added in a later Angular minor is rejected until the package is rebuilt against that minor.
+## Versions
+
+Releases are numbered `0.MINOR.PATCH` until 1.0. [`SPEC.md`](https://github.com/theo-matzavinos/loozo/blob/angular-router@0.0.9/packages/angular-router/SPEC.md) is the contract: the exports and their types, the builder names and options, the generated file names and what they export, and the behavior it specifies.
+
+- A patch (0.1.0 → 0.1.1) doesn't break the contract. It fixes bugs, improves the docs or adds something, such as an export, an option or a codec.
+- A minor (0.1.x → 0.2.0) may break it. Every move to a new Angular minor is also a minor release (see [Angular versions](#angular-versions)), so a `^0.1.0` range never picks up a release that needs a different Angular.
+- Generated files aren't part of the contract byte for byte, so any release may change them. After upgrading, run `ng build` once and commit the regenerated files; until then, the CI check (`ng build --configuration ci`) fails on them.
+
+Each release's breaking changes, features and fixes are listed in its [GitHub release](https://github.com/theo-matzavinos/loozo/releases?q=angular-router&expanded=true).
+
+## Angular versions
+
+Each release supports one Angular minor: the latest stable one when it was published, named by the `@angular/build` range. This release supports Angular 22.2 and is tested against 22.2.2. One release can't serve two minors: the application builder's options schema is Angular's own application schema at the version the package was built against, so an option added in a later Angular minor is rejected until the package is rebuilt against that minor.
+
+When Angular ships a new minor or major, a release built against it follows within a week. Earlier minors stay on the release that supported them; fixes aren't backported. [`@loozo/angular-launch`](https://github.com/theo-matzavinos/loozo/blob/angular-router@0.0.9/packages/angular-launch/README.md) pins the router exactly and releases in lockstep: each router release is followed by a Launch release that pins it.
+
+A weekly canary builds and tests the package against Angular's `latest` and `next` releases, so the release for a new minor is usually ready when Angular ships it.
 
 ## Setup
 
@@ -216,6 +232,9 @@ import { defineRoute, numberParam } from "@loozo/angular-router";
 export default defineRoute("teams/$teamId", {
   params: { teamId: numberParam },
   search: { score: numberParam },
+  resolve: {
+    team: ({ params }) => ({ id: params.teamId, name: `Team ${params.teamId}` }),
+  },
 });
 ```
 
@@ -235,13 +254,14 @@ The member directory is inside the team directory, so the team route is its pare
 
 ### Codecs
 
-| Codec                        | Value                                                                        |
-| ---------------------------- | ---------------------------------------------------------------------------- |
-| `stringParam`                | Any string, including `""`                                                   |
-| `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                              |
-| `withFallback(codec, value)` | Search only: reads `value` when the key is missing, repeated or invalid      |
+| Codec                        | Value                                                                         |
+| ---------------------------- | ----------------------------------------------------------------------------- |
+| `stringParam`                | Any string, including `""`                                                    |
+| `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                               |
+| `withFallback(codec, value)` | Search only: reads `value` when the key is missing, repeated or invalid       |
+| `arrayParam(codec)`          | Search only: reads every value of a repeated key (`?tag=a&tag=b`) as an array |
 
 For a catchall, the codec applies to each segment, so `$segments[]` with `stringParam` produces `readonly string[]`.
 
@@ -251,15 +271,17 @@ Search params never stop a route from matching, and they never fail. Every searc
 search: {
   page: withFallback(numberParam, 1),
   sort: enumParam(["asc", "desc"]),
+  tag: arrayParam(enumParam(["news", "guides"])),
 }
 ```
 
-| Search key           | Missing      | Repeated or invalid |
-| -------------------- | ------------ | ------------------- |
-| Plain codec (`sort`) | Absent       | Absent              |
-| `withFallback`       | The fallback | The fallback        |
+| Search key           | Missing      | Repeated     | Invalid                       |
+| -------------------- | ------------ | ------------ | ----------------------------- |
+| Plain codec (`sort`) | Absent       | Absent       | Absent                        |
+| `withFallback`       | The fallback | The fallback | The fallback                  |
+| `arrayParam` (`tag`) | `[]`         | Every value  | `[]`, if any value is invalid |
 
-`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.
+`sort` reads as `"asc" | "desc" | undefined`. A key with a fallback always reads a value (`page` is a `number`, never `undefined`). An array key always reads a readonly array: `?tag=news&tag=guides` reads `["news", "guides"]`, `?tag=news` reads `["news"]`, and `?tag=news&tag=other` reads `[]`. Values keep their URL order, duplicates included. Links, `createUrl`, navigation and redirects can leave out any search key. An array key takes an array and writes one `tag=` pair per element; `[]` writes nothing, so an empty list and a missing key are the same URL. For the same reason an array key can't have a fallback: to default to some tags, check `tag.length` in the page.
 
 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:
 
@@ -286,7 +308,7 @@ Parsing should be pure and deterministic. A path codec runs twice per navigation
 
 `defineRoute` never calls parsers, guards, resolvers or other callbacks; it only records them.
 
-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.
+The package root exports exactly `defineRoute`, `createUrl`, `stringParam`, `numberParam`, `booleanParam`, `enumParam`, `withFallback` and `arrayParam`, 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
 
@@ -309,7 +331,7 @@ createUrl(product, {
 }); // "/products/42?tab=reviews#summary"
 ```
 
-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:
+All path params are required, including inherited ones. Search params are all optional: an omitted or `undefined` value leaves the key out, and an `arrayParam` key repeats once per element (`tag: ["a", "b"]` writes `tag=a&tag=b`). 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`
 
@@ -340,19 +362,22 @@ export function readInputs() {
 
   route.params(); // { teamId: number; id: number }
   route.search(); // { score?: number }
-  route.data(); // { item: Item }, local resolver results only
+  route.data(); // { team: { id: number; name: string }; item: Item }, ancestors' resolver results too
+  route.title(); // string: this route's title, or the nearest ancestor's
 }
 ```
 
-`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.
+`params`, `search`, `data` and `title` 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), they change together. When a navigation is cancelled or fails before activation (in matching, a guard or a resolver), they keep their values. When a routed component's constructor throws during activation, the pages above it that stay on screen already have the new values, and keep them until the next navigation completes. 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 the resolver results of this route and its ancestors, pathless and page-less ones included: the outermost ancestor's first, then nearer ones, then this route's own. As in Angular's own data inheritance, a nearer route's key hides an ancestor's key of the same name, and the hidden value isn't reachable through the handle. The merge is the same whatever `paramsInheritanceStrategy` you set, so under `'emptyOnly'` a route below a parent with a page still has that parent's resolver results, which Angular's own `snapshot.data` leaves out. Static `data` and the title aren't included; to read a static value through the handle, return it from a resolver, such as `resolve: { label: () => "Teams" }`.
 
-`data` holds this route's own resolver results only, not static `data`, parent data or the title.
+`title` is the resolved title of this route, or of its nearest ancestor that has one, and changes with the other signals. It's typed `string` when this route or an ancestor declares `title`, and `undefined` otherwise. Like resolver data, it only changes when Angular reruns the title: with the default `runGuardsAndResolvers`, a navigation that changes only search params keeps the old title, so a title that reads search needs `'paramsOrQueryParamsChange'`. Only generated routes count; a hand-written Angular route above them with its own title isn't read.
 
 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:
+`link` returns an Angular `UrlTree` for `RouterLink`; `navigate` calls `Router.navigateByUrl` and returns Angular's own promise. Both take one object: `to` picks the route, and `params`, `search` and `fragment` are its URL values:
 
 `snippets/src/routes/teams/$teamId/items/$id/links.ts`
 
@@ -365,19 +390,89 @@ 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 } }); // parent route
-  void route.navigate(report, { params: { reportId: 42 } }); // another route's destination
+  route.link({ to: "/teams/$teamId/items/$id", params: { teamId: 7, id: 9 } }); // absolute
+  route.link({ to: "..", params: { teamId: 7 } }); // parent route
+  void route.navigate({ to: report, params: { reportId: 42 } }); // another route's destination
+
+  // Angular's navigation behavior options go in the same object, for navigate only.
+  void route.navigate({ params: { teamId: 7, id: 8 }, search: { score: 10 }, replaceUrl: true });
 }
 ```
 
-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 `/`. `"."` selects this route, and `".."` its parent route: the nearest route above it with a shorter path, or the root route for a top-level route. There are no other relative selectors. TypeScript only offers selectors that resolve to a known route, and the values are always typed for the selected route.
+Without `to`, the call targets this route. Otherwise `to` is a string literal selecting a route by its full authored path, never a concrete URL, or another route's `destination`. Absolute selectors start with `/`, and `".."` selects the parent route: the nearest route above it with a shorter path, or the root route for a top-level route. There are no other relative selectors. TypeScript only offers selectors that resolve to a known route, and the values are always typed for the selected route.
+
+Values are never carried over from the current URL. Pass every required param and search value explicitly, and pass `fragment` only when the target declares it.
 
-Values are never carried over from the current URL. Pass every required param and search value explicitly, and pass `fragment` only when the target declares it. There is no extras argument; use `RouterLink` inputs such as `replaceUrl` or `state` for those.
+The rest of a `navigate` object is Angular's `NavigationBehaviorOptions`, such as `replaceUrl`, `state`, `info` or `skipLocationChange`, passed to `navigateByUrl` as given. The last call above uses `replaceUrl` to replace the current history entry instead of adding one, as a filter input that updates the search on every keystroke would. `link` takes no behavior options; set them as `RouterLink` inputs instead, such as `[replaceUrl]` or `[state]`.
 
 A `destination` must come from the same generated route set as the handle. Destinations are for `link` and `navigate` only; `createUrl` takes declarations.
 
+### The active route
+
+Code outside a route's page, such as a shell, breadcrumbs or a nav bar, reads the active route with `injectActiveRoute()` from `destinations.generated.ts`:
+
+`snippets/src/shell.ts`
+
+```ts
+import { Component, computed } from "@angular/core";
+import { RouterOutlet } from "@angular/router";
+import { injectActiveRoute } from "../generated/destinations.generated.js";
+import { destination as team } from "./routes/teams/$teamId/route.generated.js";
+import { destination as item } from "./routes/teams/$teamId/items/$id/route.generated.js";
+
+@Component({
+  selector: "app-shell",
+  imports: [RouterOutlet],
+  template: `
+    @if (teamId() !== undefined) {
+      <nav>Team {{ teamId() }} <button (click)="next()">Next item</button></nav>
+    }
+    <router-outlet />
+  `,
+})
+export default class Shell {
+  // The deepest active route, or undefined before the first navigation.
+  readonly active = injectActiveRoute();
+
+  // An ancestor's params: number | undefined.
+  readonly teamId = computed(
+    () =>
+      this.active()
+        ?.chain.find((route) => route.is(team))
+        ?.params().teamId,
+  );
+
+  // Before narrowing, params, search and data read as a union over every route.
+  readonly params = computed(() => this.active()?.params());
+
+  // Whether this route or one of its ancestors is the team route.
+  readonly inTeam = computed(() => this.active()?.contains(team) ?? false);
+
+  next() {
+    const route = this.active();
+
+    // is() narrows to the item's handle, so link and navigate are typed for it.
+    if (route?.is(item)) {
+      const { teamId, id } = route.params();
+
+      void route.navigate({ params: { teamId, id: id + 1 }, replaceUrl: true });
+    }
+  }
+}
+```
+
+`injectActiveRoute()` needs an injection context and returns a signal of the deepest active route. It's `undefined` before the first navigation, and when no generated route is active. A route with children is the deepest at its own URL: on `/teams/7` it's the team route.
+
+Until you narrow it, the active route has `params`, `search`, `data` and `title`, typed as the union of every route's values, and:
+
+- `is(destination)`: whether it's exactly that route, not one of its ancestors. It narrows the route to that route's handle, with its `link` and `navigate`.
+- `contains(destination)`: whether that route is this one or one of its ancestors.
+- `chain`: the active routes, from the top-level one down to this one. `chain.find((route) => route.is(team))` finds an ancestor, already narrowed. For breadcrumbs, `chain.map((route) => route.title())` reads each route's title; a route without its own title repeats its ancestor's.
+
+The value changes only when a navigation completes. It stays the same while a navigation is pending, and when one is cancelled or fails. If it fails during activation, the routes above the failing one that stay active already have the new values, so `chain` can mix a parent's new params with the active route's old ones until the next navigation completes. While a route stays active it keeps its handle, so going from item 9 to item 10 changes that handle's `params`, not the active route. Each `injectActiveRoute()` call has its own handles, separate from the page's `injectRoute()` handle; their values are the same. A handle that's no longer active keeps its last values. Routes are told apart by their declaration file's path relative to the tsconfig, so two generated route sets with declarations at the same paths can't share one router.
+
+Use it outside the page. In the constructor of a page being activated it reads `undefined` until the navigation ends, while the page's own `injectRoute()` has its values right away. On a server-rendered page it's `undefined` from hydration until the browser's first navigation completes, so the shell shows what it shows for `undefined` in between.
+
 ## Guards, resolvers and redirects
 
 `canActivate`, `canActivateChild` and `canMatch` take arrays of functions whose first argument is the parsed inputs. Angular's native arguments follow:
@@ -400,7 +495,7 @@ export default defineRoute("reports/$reportId", {
 | `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). 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`.
+Guards return anything Angular accepts (`boolean`, `UrlTree`, `RedirectCommand`, or a Promise or Observable of those). Search values recover before any guard runs (absent, the fallback, or `[]` for an array key). 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`.
 
 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:
 
@@ -465,7 +560,7 @@ 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`, `canMatch` or `onInvalidParams`; an invalid param in a redirect's source URL fails the navigation.
+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. Search `preserve` keeps the incoming query text, repeated keys included, so the target's array keys read every value; `replace` writes an array key's values like `createUrl` does. 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
 
@@ -529,7 +624,7 @@ Declarations look the same, but the builder never creates or edits them, and dir
 
 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`](https://github.com/theo-matzavinos/loozo/blob/angular-router@0.0.7/examples/angular-router/ssr-proof/README.md) is a working SSR app with a search fallback, a resolver, a redirect and hydration.
+[`examples/angular-router/ssr-proof`](https://github.com/theo-matzavinos/loozo/blob/angular-router@0.0.9/examples/angular-router/ssr-proof/README.md) is a working SSR app with a search fallback, a resolver, a redirect and hydration.
 
 ## Unit tests and i18n extraction
 
@@ -552,15 +647,59 @@ Neither builder runs generation; both use the generated files already on disk. A
 
 The rest is the usual Angular setup. Give specs their own `tsconfig.spec.json` with `"types": ["vitest/globals"]`, and exclude `src/**/*.spec.ts` from the application tsconfig. For `i18n` attributes, add `@angular/localize/init` to the build target's `polyfills`.
 
+### Testing pages
+
+`injectRoute()` throws unless the component's `ActivatedRoute` is the route it was generated for, so `TestBed.createComponent` on a page fails with `Generated route wiring identity mismatch`. Navigate to the page through the generated routes instead, with Angular's `RouterTestingHarness`:
+
+`snippets/src/routes/teams/$teamId/items/$id/page.spec.ts`
+
+```ts
+import { TestBed } from "@angular/core/testing";
+import { provideRouter } from "@angular/router";
+import { RouterTestingHarness } from "@angular/router/testing";
+import { describe, expect, it } from "vitest";
+import { routes } from "../../../../../../generated/routes.generated.js";
+import { ItemCatalog, type Item, type ItemQuery } from "../../../../../catalog.js";
+import ItemPage from "./page.js";
+
+async function stubCatalog(query: ItemQuery): Promise<Item> {
+  return { ...query, name: "Stub item" };
+}
+
+describe("ItemPage", () => {
+  it("renders the item from the route's resolvers", async () => {
+    TestBed.configureTestingModule({
+      providers: [provideRouter(routes), { provide: ItemCatalog, useValue: stubCatalog }],
+    });
+
+    const harness = await RouterTestingHarness.create();
+    const page = await harness.navigateByUrl("/teams/7/items/3?score=5", ItemPage);
+
+    expect(page.route.params()).toEqual({ teamId: 7, id: 3 });
+    expect(page.route.search()).toEqual({ score: 5 });
+    // The parent route's resolver result, merged into this route's data.
+    expect(page.route.data().team).toEqual({ id: 7, name: "Team 7" });
+    expect(page.route.data().item.name).toBe("Stub item");
+    expect(harness.routeNativeElement?.querySelector("h1")?.textContent).toBe("Stub item");
+  });
+});
+```
+
+The navigation runs the real codecs, guards and resolvers. `navigateByUrl` resolves once the page is on screen, with its instance, so the handle already holds the parsed values. Replace what a resolver injects with a provider, as `ItemCatalog` is here. `data` includes the ancestors' resolver results: `team` comes from the `teams/$teamId` route's resolver. With `vitest/globals`, the import from `vitest` is optional.
+
+A component inside the page's template gets the page's `ActivatedRoute`, so the same applies to it: render it through the page's route.
+
+A component that calls `injectActiveRoute()`, such as a shell, doesn't need a route of its own: `TestBed.createComponent` works, and the active route is `undefined` until a navigation, such as the harness's, completes.
+
 ## What gets generated
 
-| File                                       | Contents                                                      |
-| ------------------------------------------ | ------------------------------------------------------------- |
-| `<outDirectory>/routes.generated.ts`       | `routes: Routes` for `provideRouter`                          |
-| `<outDirectory>/destinations.generated.ts` | Shared typing and navigation data (when any route has a page) |
-| `route.generated.ts` beside each route     | `injectRoute()` and `destination`; none for redirect routes   |
+| File                                       | Contents                                                                                 |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------- |
+| `<outDirectory>/routes.generated.ts`       | `routes: Routes` for `provideRouter`                                                     |
+| `<outDirectory>/destinations.generated.ts` | Shared typing and navigation data, and `injectActiveRoute()` (when any route has a page) |
+| `route.generated.ts` beside each route     | `injectRoute()` and `destination`; none for redirect routes                              |
 
-Each generated file starts with an ownership marker comment such as `// @loozo/angular-router routegen: owned route.generated.ts`. The builder only replaces or deletes marked files with those exact names. It never overwrites an unmarked file in their place, and it removes stale marked files when their routes disappear. Hand edits to generated files are overwritten.
+Each generated file starts with an ownership marker comment such as `// @loozo/angular-router routegen: owned route.generated.ts`. The builder only replaces or deletes marked files with those exact names. It never overwrites an unmarked file in their place, and it removes stale marked files when their routes disappear. Hand edits to generated files are overwritten. Generated files are written with LF line endings; a copy that Git checked out with CRLF line endings, as it does on Windows by default, counts as up to date.
 
 Generation reads your source without importing or running it. It validates everything (declarations, overlapping routes, redirects, file ownership) before writing anything, so a run that fails validation leaves your files as they were. Files are then written one at a time, with no rollback: if writing fails partway, for example on a file that isn't writable, or the run is interrupted, some files may already be updated. The next successful run repairs them. Unchanged files aren't rewritten, so their modification times stay the same.
 
@@ -606,15 +745,15 @@ To go back to native file events, set `"poll": false` in the serve target or one
 - Primary outlet only: no named outlets, custom matchers or `loadChildren`.
 - One scan directory per application.
 - No data, URL or transfer caches. Resolver data lives in Angular.
-- Relative navigation from a catchall route isn't supported; use `"."` or an absolute selector.
+- Relative navigation from a catchall route isn't supported; omit `to` or use an absolute selector.
 - Angular 22.2.2 drops a resolver result named `__proto__`, so a resolver with that name has no value in `data`.
 - Writes are individual file replacements. A write error or an interrupted run can leave mixed output; the next successful run repairs it.
 
 ## Further reading
 
-- [`SPEC.md`](https://github.com/theo-matzavinos/loozo/blob/angular-router@0.0.7/packages/angular-router/SPEC.md): the full contract, including every edge case
-- [`examples/angular-router`](https://github.com/theo-matzavinos/loozo/tree/angular-router@0.0.7/examples/angular-router): a minimal app using the builders
-- [`examples/angular-router/ssr-proof`](https://github.com/theo-matzavinos/loozo/blob/angular-router@0.0.7/examples/angular-router/ssr-proof/README.md): SSR and hydration
+- [`SPEC.md`](https://github.com/theo-matzavinos/loozo/blob/angular-router@0.0.9/packages/angular-router/SPEC.md): the full contract, including every edge case
+- [`examples/angular-router`](https://github.com/theo-matzavinos/loozo/tree/angular-router@0.0.9/examples/angular-router): a minimal app using the builders
+- [`examples/angular-router/ssr-proof`](https://github.com/theo-matzavinos/loozo/blob/angular-router@0.0.9/examples/angular-router/ssr-proof/README.md): SSR and hydration
 
 ## Developing this package
 

package/fesm2022/loozo-angular-router-_core.mjs

@@ -1,7 +1,11 @@
 const fallbacks = /* @__PURE__ */ new WeakMap();
+const arrays = /* @__PURE__ */ new WeakSet();
 function codecFallback(codec) {
 	return fallbacks.get(codec);
 }
+function isArrayCodec(codec) {
+	return arrays.has(codec);
+}
 function validateCodec(codec) {
 	if (codec === null || typeof codec !== "object" && typeof codec !== "function" || typeof codec.parse !== "function" || typeof codec.stringify !== "function") throw new TypeError("Codec must have callable parse and stringify methods");
 }
@@ -58,6 +62,7 @@ function enumParam(values) {
 function withFallback(codec, fallback) {
 	validateCodec(codec);
 	if (codecFallback(codec)) throw new TypeError("withFallback cannot wrap a codec that already has a fallback");
+	if (arrays.has(codec)) throw new TypeError("withFallback cannot wrap an arrayParam codec");
 	const wrapper = {
 		parse(raw) {
 			return codec.parse(raw);
@@ -69,6 +74,21 @@ function withFallback(codec, fallback) {
 	fallbacks.set(wrapper, Object.freeze({ value: fallback }));
 	return wrapper;
 }
+function arrayParam(codec) {
+	validateCodec(codec);
+	if (codecFallback(codec)) throw new TypeError("arrayParam cannot wrap a codec that has a fallback");
+	if (arrays.has(codec)) throw new TypeError("arrayParam cannot wrap another arrayParam codec");
+	const wrapper = {
+		parse(raw) {
+			return codec.parse(raw);
+		},
+		stringify(value) {
+			return codec.stringify(value);
+		}
+	};
+	arrays.add(wrapper);
+	return wrapper;
+}
 function parsePath(path) {
 	if (typeof path !== "string") throw new TypeError("Path must be a string");
 	if (path === "") return Object.freeze([]);
@@ -152,6 +172,7 @@ function copyCodecs(value, path) {
 		const codec = record[key];
 		validateCodec(codec);
 		if (path && codecFallback(codec)) throw new TypeError("withFallback codecs are search-only");
+		if (path && isArrayCodec(codec)) throw new TypeError("arrayParam codecs are search-only");
 		result[key] = codec;
 	}
 	return Object.freeze(result);
@@ -184,6 +205,7 @@ function snapshotRedirect(value, source) {
 		checkKeys(search, /* @__PURE__ */ new Set(["mode", "values"]), "redirect search");
 		const values = ownRecord(search.values, "Redirect replacement");
 		checkKeys(values, new Set(Object.keys(target.search)), "search values");
+		for (const key of Object.keys(values)) if (isArrayCodec(target.search[key]) && values[key] !== void 0 && !Array.isArray(values[key])) throw new TypeError(`Redirect search array requires an array: ${key}`);
 		searchSnapshot = {
 			mode: "replace",
 			values: Object.freeze({ ...values })
@@ -350,6 +372,11 @@ function createUrl(route, values) {
 		if (typeof options.fragment !== "string" || !metadata.fragments.includes(options.fragment)) throw new TypeError("Fragment must belong to this declaration");
 	}
 	for (const segment of metadata.segments) if (segment.kind === "catchall" && !Array.isArray(params[segment.name])) throw new TypeError(`Catchall requires an array: ${segment.name}`);
+	for (const key of searchKeys) {
+		if (!isArrayCodec(metadata.search[key]) || !has(search, key)) continue;
+		const value = search[key];
+		if (value !== void 0 && !Array.isArray(value)) throw new TypeError(`Search array requires an array: ${key}`);
+	}
 	const parts = [];
 	for (const segment of metadata.segments) if (segment.kind === "static") parts.push(encode(segment.text));
 	else if (segment.kind === "scalar") parts.push(stringify(metadata.params[segment.name], params[segment.name], true));
@@ -359,12 +386,16 @@ function createUrl(route, values) {
 	for (const key of searchKeys) {
 		const value = search[key];
 		if (!has(search, key) || value === void 0) continue;
-		query.push(`${encode(key)}=${stringify(metadata.search[key], value, false)}`);
+		if (!isArrayCodec(metadata.search[key])) {
+			query.push(`${encode(key)}=${stringify(metadata.search[key], value, false)}`);
+			continue;
+		}
+		for (const element of value) query.push(`${encode(key)}=${stringify(metadata.search[key], element, false)}`);
 	}
 	if (query.length > 0) url = `${url}?${query.join("&")}`;
 	if (has(options, "fragment")) url = `${url}#${encode(options.fragment)}`;
 	return url;
 }
-export { booleanParam, codecFallback, createUrl, defineRoute, enumParam, numberParam, routeMetadata, stringParam, withFallback };
+export { arrayParam, booleanParam, codecFallback, createUrl, defineRoute, enumParam, isArrayCodec, numberParam, routeMetadata, stringParam, withFallback };
 
 //# sourceMappingURL=loozo-angular-router-_core.mjs.map