@paramour-js/next 0.4.0 → 0.5.0

package/dist/watch.d.ts

@@ -9,31 +9,31 @@ export interface WatchRouteDirsOptions {
     debounceMs?: number;
     /**
      * Absolute paths whose events are ignored — the artifact file, so a
-     * regeneration write can't re-trigger the watcher (TR5 feedback loop).
+     * regeneration write can't re-trigger the watcher in a feedback loop.
      */
     ignorePaths?: readonly string[];
     /**
      * Watcher startup/runtime failures and `onRescan` throws land here.
-     * Surfaced, not logged: TR5's "log once, dev continues" behavior belongs
-     * to the composition points (TR4/TR7), not this module.
+     * Surfaced, not logged: the "log once, dev continues" behavior belongs to
+     * the composition points, not this module.
      */
     onError?: (error: unknown) => void;
-    /** The regenerate callback — full rescan → write-if-changed (TR5). */
+    /** The regenerate callback — full rescan → write-if-changed. */
     onRescan: () => void;
 }
-/** TR5: ~100 ms — long enough to coalesce an editor save storm. */
+/** ~100 ms — long enough to coalesce an editor save storm. */
 export declare const DEFAULT_DEBOUNCE_MS = 100;
 /**
  * Debounced full-rescan watcher over the route dirs — both of them in a
- * hybrid project (PR8), sharing one debounce so an editor operation touching
- * both coalesces into a single rescan. Because a scan is milliseconds (TR2),
- * no event fidelity is needed: any event → debounce → `onRescan`. Native
+ * hybrid project, sharing one debounce so an editor operation touching both
+ * coalesces into a single rescan. Because a scan is milliseconds, no event
+ * fidelity is needed: any event → debounce → `onRescan`. Native
  * `fs.watch({ recursive: true })`, no chokidar; this start/close interface
  * is the seam chokidar would drop in behind if a platform hole appears.
  *
- * A missing dir is skipped — not watched, not an error (PR8): callers pass
- * the dirs discovery resolved, so absence here is a raced deletion, and dev
- * continuing in stale-types mode is exactly TR5's posture. Genuine watch
- * startup failures still surface through `onError`.
+ * A missing dir is skipped — not watched, not an error: callers pass the
+ * dirs discovery resolved, so absence here is a raced deletion, and dev
+ * continuing in stale-types mode is exactly the intended posture. Genuine
+ * watch startup failures still surface through `onError`.
  */
 export declare function watchRouteDirs(dirs: readonly string[], options: WatchRouteDirsOptions): RouteDirsWatcher;

package/dist/watch.js

@@ -1,24 +1,24 @@
 import { statSync, watch } from "node:fs";
 import { resolve } from "node:path";
-/** TR5: ~100 ms — long enough to coalesce an editor save storm. */
+/** ~100 ms — long enough to coalesce an editor save storm. */
 export const DEFAULT_DEBOUNCE_MS = 100;
 /**
  * Directory names whose subtrees are ignored if they ever fall under a
- * watched root (TR5).
+ * watched root.
  */
 const IGNORED_SEGMENTS = new Set([".next", "node_modules"]);
 /**
  * Debounced full-rescan watcher over the route dirs — both of them in a
- * hybrid project (PR8), sharing one debounce so an editor operation touching
- * both coalesces into a single rescan. Because a scan is milliseconds (TR2),
- * no event fidelity is needed: any event → debounce → `onRescan`. Native
+ * hybrid project, sharing one debounce so an editor operation touching both
+ * coalesces into a single rescan. Because a scan is milliseconds, no event
+ * fidelity is needed: any event → debounce → `onRescan`. Native
  * `fs.watch({ recursive: true })`, no chokidar; this start/close interface
  * is the seam chokidar would drop in behind if a platform hole appears.
  *
- * A missing dir is skipped — not watched, not an error (PR8): callers pass
- * the dirs discovery resolved, so absence here is a raced deletion, and dev
- * continuing in stale-types mode is exactly TR5's posture. Genuine watch
- * startup failures still surface through `onError`.
+ * A missing dir is skipped — not watched, not an error: callers pass the
+ * dirs discovery resolved, so absence here is a raced deletion, and dev
+ * continuing in stale-types mode is exactly the intended posture. Genuine
+ * watch startup failures still surface through `onError`.
  */
 export function watchRouteDirs(dirs, options) {
     const { debounceMs = DEFAULT_DEBOUNCE_MS, ignorePaths = [], onError, onRescan, } = options;
@@ -31,7 +31,7 @@ export function watchRouteDirs(dirs, options) {
                 onRescan();
             }
             catch (error) {
-                // A throwing regeneration must not kill the watcher (TR5 non-fatal).
+                // A throwing regeneration must not kill the watcher — non-fatal.
                 onError?.(error);
             }
         }, debounceMs);
@@ -50,7 +50,7 @@ export function watchRouteDirs(dirs, options) {
             watcher = watch(dir, { recursive: true }, (_eventType, filename) => {
                 // `filename` can be null (platform-dependent); with nothing to
                 // filter on, err toward rescanning — a spurious pass is a no-op
-                // write (TR3).
+                // write.
                 if (filename !== null) {
                     if (ignored.has(resolve(dir, filename)))
                         return;
@@ -63,8 +63,8 @@ export function watchRouteDirs(dirs, options) {
             });
         }
         catch (error) {
-            // TR5: watcher failure is non-fatal — dev continues in stale-types
-            // mode, and the other dir's watcher (if any) keeps running.
+            // Watcher failure is non-fatal — dev continues in stale-types mode,
+            // and the other dir's watcher (if any) keeps running.
             onError?.(error);
             continue;
         }

package/dist/with-typed-routes.d.ts

@@ -1,15 +1,15 @@
-/** Options for {@link withTypedRoutes} (TR4). */
+/** Options for {@link withTypedRoutes}. */
 export interface WithTypedRoutesOptions {
     /**
      * Artifact location, for monorepos where the Next app root isn't where the
-     * file should live (TR3 escape hatch). Relative paths resolve against the
+     * file should live — the escape hatch. Relative paths resolve against the
      * project root. Default: `paramour-env.d.ts` at the project root.
      */
     outFile?: string;
     /**
-     * Upgrade build-phase drift from a loud warning to a build failure (TR4)
-     * — for teams that want the committed artifact to be the law. Default
-     * `false`, friendly to gitignored-file workflows and CI images.
+     * Upgrade build-phase drift from a loud warning to a build failure — for
+     * teams that want the committed artifact to be the law. Default `false`,
+     * friendly to gitignored-file workflows and CI images.
      */
     strict?: boolean;
 }
@@ -24,21 +24,22 @@ export declare function devWatcherCountForTests(): number;
  */
 export declare function resetDevWatchersForTests(): void;
 /**
- * Wrap a Next config with route-registry generation (TR4). Returns the
+ * Wrap a Next config with route-registry generation. Returns the
  * config-function form; Next's phase argument is the mode discriminator:
  *
  * - production build → one generation pass before the config is returned
  *   (the build type-checks against fresh routes); drift warns loudly, or
  *   fails the build under `strict: true`.
  * - dev server → one immediate generation pass, then the debounced watcher
- *   (TR5) behind both single-writer guards (TR6).
+ *   behind both single-writer guards (the in-process singleton and the
+ *   cross-process pidfile lock).
  * - every other phase → pass-through, no generation.
  *
  * Two states throw during config evaluation instead of degrading to
  * stale-types mode, both phases alike, because Next itself has no valid
- * build for them: an app↔pages route collision (PR9), and discovery's
- * populated-ignored-dir config error (spike-2 ruling — Next is silently
- * serving none of those pages).
+ * build for them: an app↔pages route collision, and discovery's
+ * populated-ignored-dir config error (Next is silently serving none of those
+ * pages).
  */
 export declare function withTypedRoutes<C extends object>(config: C | ConfigFunction<C>, options?: WithTypedRoutesOptions): ConfigFunction<C>;
 export {};

package/dist/with-typed-routes.js

@@ -7,18 +7,18 @@ import { resolveRouteDirs } from "./scan.js";
 import { watchRouteDirs } from "./watch.js";
 /**
  * Phase constants from `next/constants`, hardcoded so the package stays
- * hermetic (TR4 hermeticity ruling): the values are stable, documented
- * public API, and importing them would make `next` a runtime dependency.
+ * hermetic: the values are stable, documented public API, and importing them
+ * would make `next` a runtime dependency.
  */
 const PHASE_DEVELOPMENT_SERVER = "phase-development-server";
 const PHASE_PRODUCTION_BUILD = "phase-production-build";
 /**
- * TR6 guard 1 — the in-process singleton, keyed by route dirs + artifact
- * path. Load-bearing even for a single `next dev`: the spike-#1 census found
- * Turbopack dev invokes the config function twice in the same process.
+ * The in-process single-writer guard — a singleton keyed by route dirs +
+ * artifact path. Load-bearing even for a single `next dev`: Turbopack dev
+ * invokes the config function twice in the same process.
  */
 const devWatcherTeardowns = new Map();
-/** Messages already logged — "log once" (TR5) across repeat evaluations. */
+/** Messages already logged — "log once" across repeat evaluations. */
 const warnedOnce = new Set();
 /** @internal Test seam: the number of live dev-watcher singletons. */
 export function devWatcherCountForTests() {
@@ -36,21 +36,22 @@ export function resetDevWatchersForTests() {
     warnedOnce.clear();
 }
 /**
- * Wrap a Next config with route-registry generation (TR4). Returns the
+ * Wrap a Next config with route-registry generation. Returns the
  * config-function form; Next's phase argument is the mode discriminator:
  *
  * - production build → one generation pass before the config is returned
  *   (the build type-checks against fresh routes); drift warns loudly, or
  *   fails the build under `strict: true`.
  * - dev server → one immediate generation pass, then the debounced watcher
- *   (TR5) behind both single-writer guards (TR6).
+ *   behind both single-writer guards (the in-process singleton and the
+ *   cross-process pidfile lock).
  * - every other phase → pass-through, no generation.
  *
  * Two states throw during config evaluation instead of degrading to
  * stale-types mode, both phases alike, because Next itself has no valid
- * build for them: an app↔pages route collision (PR9), and discovery's
- * populated-ignored-dir config error (spike-2 ruling — Next is silently
- * serving none of those pages).
+ * build for them: an app↔pages route collision, and discovery's
+ * populated-ignored-dir config error (Next is silently serving none of those
+ * pages).
  */
 export function withTypedRoutes(config, options = {}) {
     return async (phase, ctx) => {
@@ -58,16 +59,17 @@ export function withTypedRoutes(config, options = {}) {
         if (phase !== PHASE_DEVELOPMENT_SERVER && phase !== PHASE_PRODUCTION_BUILD)
             return resolved;
         // The dev server and every build worker evaluate the config with the
-        // project root as cwd (spike-#1 census); TR7's CLI flags are the home
-        // for anything more configurable than this.
+        // project root as cwd; the CLI flags are the home for anything more
+        // configurable than this.
         const projectRoot = process.cwd();
         const artifactPath = resolve(projectRoot, options.outFile ?? "paramour-env.d.ts");
         const pageExtensions = resolved.pageExtensions ?? DEFAULT_PAGE_EXTENSIONS;
-        // May throw the spike-2 config error — deliberately not caught (above).
+        // May throw the populated-ignored-dir config error — deliberately not
+        // caught (see above).
         const dirs = resolveRouteDirs(projectRoot, pageExtensions);
         if (dirs.appDir === undefined && dirs.pagesDir === undefined) {
-            // §7.3: codegen is never load-bearing — a config wrapper must not
-            // take down `next dev`/`next build` over a missing route dir.
+            // Codegen is never load-bearing — a config wrapper must not take down
+            // `next dev`/`next build` over a missing route dir.
             warnOnce(`paramour: no route directory (app/, pages/, src/app/, or src/pages/) under ${projectRoot}; route generation skipped`);
             return resolved;
         }
@@ -81,12 +83,12 @@ export function withTypedRoutes(config, options = {}) {
     };
 }
 /**
- * Build-phase pass (TR4): regenerate, then warn loudly on drift — naming the
- * paths that appeared/disappeared and the router they moved in — but
- * continue; `strict` upgrades drift to a thrown error *after* the file is
- * already corrected. A missing artifact counts as drift: that is exactly the
- * CI-degrades-to-world-A scenario the committed file exists to prevent
- * (TR3). A route collision is NOT incidental failure and rethrows (PR9).
+ * Build-phase pass: regenerate, then warn loudly on drift — naming the paths
+ * that appeared/disappeared and the router they moved in — but continue;
+ * `strict` upgrades drift to a thrown error *after* the file is already
+ * corrected. A missing artifact counts as drift: that is exactly the
+ * CI-degrades-to-world-A scenario the committed file exists to prevent. A
+ * route collision is NOT incidental failure and rethrows.
  */
 function generateForBuild(dirs, pageExtensions, artifactPath, strict) {
     let result;
@@ -94,13 +96,13 @@ function generateForBuild(dirs, pageExtensions, artifactPath, strict) {
         result = generate({ ...dirs, artifactPath, pageExtensions });
     }
     catch (error) {
-        // PR9: Next fails this build anyway; surfacing the collision from the
-        // config evaluation names the actual problem instead of leaving a stale
+        // Next fails this build anyway; surfacing the collision from the config
+        // evaluation names the actual problem instead of leaving a stale
         // artifact to confuse the type errors that follow.
         if (error instanceof RouteCollisionError)
             throw error;
-        // §7.3 again: incidental generation failure is stale types, not a
-        // broken build. Only *drift* is allowed to fail a strict build.
+        // Again: incidental generation failure is stale types, not a broken
+        // build. Only *drift* is allowed to fail a strict build.
         console.warn("paramour: route generation failed; building with stale route types", error);
         return;
     }
@@ -119,9 +121,10 @@ function generateForBuild(dirs, pageExtensions, artifactPath, strict) {
     console.warn(message);
 }
 /**
- * Dev-phase generation (TR4): failure warns and continues (§7.3) — except a
- * route collision, which throws from the config evaluation here exactly as
- * in the build phase (PR9; only the running WATCHER treats it non-fatally).
+ * Dev-phase generation: failure warns and continues (codegen is never
+ * load-bearing) — except a route collision, which throws from the config
+ * evaluation here exactly as in the build phase; only the running WATCHER
+ * treats it non-fatally.
  */
 function generateSafely(dirs, pageExtensions, artifactPath) {
     try {
@@ -134,8 +137,8 @@ function generateSafely(dirs, pageExtensions, artifactPath) {
     }
 }
 /**
- * Start the dev watcher behind both TR6 guards. Failure at any layer leaves
- * dev running in stale-types mode — never fatal (TR5).
+ * Start the dev watcher behind both single-writer guards. Failure at any
+ * layer leaves dev running in stale-types mode — never fatal.
  */
 function startDevWatcher(projectRoot, dirs, pageExtensions, artifactPath) {
     const watchedDirs = [dirs.appDir, dirs.pagesDir].filter((dir) => dir !== undefined);
@@ -147,14 +150,14 @@ function startDevWatcher(projectRoot, dirs, pageExtensions, artifactPath) {
         lock = acquireWatcherLock(watcherLockPath(projectRoot));
     }
     catch (error) {
-        // §7.3: a corrupt lock location (e.g. a directory at the pidfile path)
-        // must not take down `next dev` — stale-types mode, like every other
+        // A corrupt lock location (e.g. a directory at the pidfile path) must
+        // not take down `next dev` — stale-types mode, like every other
         // watcher-layer failure.
         warnOnce("paramour: dev watcher failed; dev continues with stale route types", error);
         return;
     }
     if (!lock.acquired) {
-        // TR6: another live process owns the watcher (e.g. `paramour generate
+        // Another live process owns the watcher (e.g. `paramour generate
         // --watch` beside `next dev`). Initial generation above already ran, so
         // dev is still correct from second zero.
         console.warn(`paramour: watcher already running (pid ${String(lock.ownerPid)})`);
@@ -171,13 +174,13 @@ function startDevWatcher(projectRoot, dirs, pageExtensions, artifactPath) {
             }
             catch (error) {
                 if (error instanceof RouteCollisionError) {
-                    // PR9's watch exception: a mid-watch collision is usually a file
-                    // mid-move — log loudly every time (not once: it stays broken
-                    // until fixed), keep the last good artifact, keep running (TR5).
+                    // The collision watch exception: a mid-watch collision is usually
+                    // a file mid-move — log loudly every time (not once: it stays
+                    // broken until fixed), keep the last good artifact, keep running.
                     console.warn(`paramour: ${error.message}; dev continues with the last good artifact`);
                     return;
                 }
-                throw error; // routed to onError by the watcher (TR5 non-fatal)
+                throw error; // routed to onError by the watcher — non-fatal
             }
         },
     });
@@ -188,7 +191,7 @@ function startDevWatcher(projectRoot, dirs, pageExtensions, artifactPath) {
         lock.release?.();
     });
 }
-/** TR5 "log once": repeat evaluations/events don't spam the dev console. */
+/** "Log once": repeat evaluations/events don't spam the dev console. */
 function warnOnce(message, detail) {
     if (warnedOnce.has(message))
         return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paramour-js/next",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "exports": {
     ".": {
@@ -34,7 +34,7 @@
     "jiti": "^2.7.0",
     "magicast": "^0.3.5",
     "tinyglobby": "^0.2.15",
-    "paramour": "0.5.1"
+    "paramour": "0.6.0"
   },
   "peerDependencies": {
     "next": ">=15",
@@ -76,7 +76,8 @@
   },
   "files": [
     "bin",
-    "dist"
+    "dist",
+    "skills"
   ],
   "publishConfig": {
     "access": "public",

package/skills/paramour/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: paramour
+description: Type-safe routing for Next.js using the paramour and @paramour-js/next packages. Covers defining routes as route objects (defineAppRoute, definePagesRoute), typing params and searchParams with p.* codecs and the .optional()/.default()/.catch() modifiers, building typed links with href(), reading route state with typed hooks (useSearch, useRouteParams) and server parse surfaces (route.parse), wrapping next.config with withTypedRoutes, and using the paramour CLI (generate, check, init, list, doctor, skills). Load when working in a Next.js project that depends on paramour, when setting paramour up, or when migrating raw params/searchParams usage in an App Router or Pages Router project to validated, typed route objects.
+---
+
+# paramour
+
+Paramour is a type-safe routing companion for Next.js: each route is defined once as an importable route object whose params and search params are described by bidirectional wire codecs (parse AND serialize — Standard Schema validators plug in for validation, serialization is library-owned). Two packages: `paramour` (validation-agnostic core: `p.*` codec builders, `defineAppRoute`/`definePagesRoute`, `href`, decode/encode helpers) and `@paramour-js/next` (Next integration: `withTypedRoutes` config wrapper, App/Pages Router hooks, the `paramour` CLI).
+
+## Core rules (always apply)
+
+1. Import only from package barrels: `paramour`, `@paramour-js/next`, `@paramour-js/next/app`, `@paramour-js/next/pages`, `@paramour-js/next/testing`. Never import `dist/` or deep source paths.
+2. Codec modifier legality is type-state: illegal chains do not compile (the method's type becomes `never`) and throw at runtime for JS callers. The rules:
+   - `.optional()` and `.default()` apply only to a bare, unmodified single-value codec — at most ONE of the two, at most once. `.optional().default()`, `.default().optional()`, and any repeat are illegal.
+   - `.catch()` applies at most once and combines with either presence modifier in either order. It recovers parse failures of PRESENT wire values only — never absence.
+   - `p.array(...)` codecs take no `.optional()`/`.default()` (an absent key and `[]` are the same wire state). `.catch()` is allowed.
+   - Codecs in a `params:` config take no presence modifiers at all (`.optional()`/`.default()` are illegal there); `.catch()` is allowed.
+   - `p.csv(element)`/`p.array(element)` elements must be bare unmodified scalars: no modifiers, no csv inside csv, no array-arity element.
+   - `.default(value)` rejects values whose type includes a function; a function argument is always a factory (`.default(() => value)`).
+3. `paramour-env.d.ts` is a generated artifact. NEVER hand-edit it. Regenerate with `paramour generate` (dev server and builds wrapped by `withTypedRoutes` also regenerate it) and commit the result.
+4. After adding, renaming, moving, or deleting any route file or `defineAppRoute`/`definePagesRoute` call, run `paramour check`. Exit 1 means drift — run `paramour generate`, then commit the artifact with the route change.
+5. When converting an existing project, migrate ONE route per pass — define, wire, verify, commit — never a big-bang rewrite. See `references/migration.md`.
+6. Route objects are the currency: export them from a module and import them where needed. Never build a central string-keyed route registry.
+
+## Verification loop
+
+- `paramour list` — print every filesystem route with its params/search shape as the library sees it (`--json` for machine output). Warnings (route without a definition, definition without a route) exit 0.
+- `paramour generate` — (re)write `paramour-env.d.ts` from `app/` / `pages/`.
+- `paramour check` — verify the artifact is current. Exit 1 on drift or a missing artifact; never writes.
+- `paramour doctor` — diagnose setup (config validity, artifact freshness, next.config wrapping, version alignment, installed agent skills, tsconfig coverage). Exit 1 on any failing check; warnings exit 0.
+
+Also run the project's type check (`tsc --noEmit` or the build) after route changes — paramour's guarantees are compiler-enforced, so a wrong codec chain or a misspelled param surfaces there.
+
+## Task router
+
+Read exactly the reference file matching the task; each is self-contained.
+
+| Task                                                                                  | Read                      |
+| ------------------------------------------------------------------------------------- | ------------------------- |
+| Install paramour into a project that does not have it yet (init, config, first route) | `references/setup.md`     |
+| Convert existing raw `params`/`searchParams` code to paramour routes                  | `references/migration.md` |
+| Day-to-day work: write codecs, define routes, build links, use hooks                  | `references/authoring.md` |
+| Look up an export, hook, CLI flag, config option, or wire-format rule                 | `references/reference.md` |

package/skills/paramour/references/authoring.md

@@ -0,0 +1,113 @@
+# Authoring: codecs, routes, links, hooks
+
+## `p.*` codec builders (import `{ p }` from `"paramour"`)
+
+Wire grammars are strict and anchored — no `Number()` coercion, no whitespace, no hex, no `1e3` for integers. Every parse failure is a `ParseError` (recoverable per-key with `.catch()`); every serialize failure is a `SerializeError` at link-build time.
+
+<!--
+  The Builder column below is drift-checked against Object.keys(p) by
+  packages/next/test/skill-drift.test.ts — keep each row's first cell a
+  single `p.name(...)` backtick token.
+-->
+
+| Builder              | Decoded type     | Wire behavior                                                                                                                                                                                                                                  | Options                                                                                             |
+| -------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `p.string(schema?)`  | `string`         | Verbatim text. Empty string is a real value (`key=`), not absence.                                                                                                                                                                             | Optional Standard Schema `<string, string>` refinement (runs on parse AND serialize)                |
+| `p.integer(schema?)` | `number`         | `/^-?\d+$/`, safe-integer range.                                                                                                                                                                                                               | Optional Standard Schema `<number, number>`                                                         |
+| `p.number(schema?)`  | `number`         | Decimal/scientific notation, finite only.                                                                                                                                                                                                      | Optional Standard Schema `<number, number>`                                                         |
+| `p.boolean()`        | `boolean`        | Exactly `"true"` / `"false"`.                                                                                                                                                                                                                  | —                                                                                                   |
+| `p.enum(members)`    | union of members | Exact member match. `p.enum(["asc", "desc"])` decodes to `"asc" \| "desc"`.                                                                                                                                                                    | Non-empty readonly string tuple                                                                     |
+| `p.isoDate()`        | `Date`           | `YYYY-MM-DD`, real calendar dates only (rejects `2026-02-30`); serializes UTC date part.                                                                                                                                                       | —                                                                                                   |
+| `p.timestamp()`      | `Date`           | ISO 8601 UTC only (`...T..:..:..[.mmm]Z`, offsets rejected); serializes `Date#toISOString()`.                                                                                                                                                  | —                                                                                                   |
+| `p.json(schema)`     | schema output    | `JSON.parse` then schema; serialize re-validates then `JSON.stringify`.                                                                                                                                                                        | Standard Schema (required)                                                                          |
+| `p.index(schema?)`   | `number`         | 1-based on the wire, 0-based in memory: `?page=1` ↔ `0`. Wire `< 1` is a parse failure; negative in-memory index is a `SerializeError`.                                                                                                        | Optional Standard Schema `<number, number>` (validates the 0-based value)                           |
+| `p.csv(element?)`    | `E[]`            | ONE wire value, comma-joined (`?tags=a,b`). Empty wire string is `[]`; `a,,b` / trailing comma are parse failures; serializing an element that is empty or contains a comma is a `SerializeError`. Arity "single" — full modifier set applies. | Optional element codec (default `p.string()`); element must be an unmodified scalar, no nested csv  |
+| `p.array(element?)`  | `E[]`            | Repeated keys (`?tags=a&tags=b`). Absent ≡ `[]` — so NO `.optional()`/`.default()`; `.catch()` recovers the whole list.                                                                                                                        | Optional element codec (default `p.string()`); element must be an unmodified scalar, not arity-many |
+| `p.custom({ ... })`  | `Out`            | Your bidirectional transform. Thrown foreign errors are rebranded `ParseError`/`SerializeError`.                                                                                                                                               | `{ parse: (raw: string) => Out; serialize: (value: Out) => string; label?: string }`                |
+
+## Modifier chains
+
+| Modifier                        | Effect on decode                                                     | Effect on href input | Effect on URL                                                                                      |
+| ------------------------------- | -------------------------------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------- |
+| (none — required)               | Absent key is a decode issue                                         | Key required         | Always emitted when building                                                                       |
+| `.optional()`                   | Absent → `undefined`; field type `T \| undefined`                    | Key omittable        | Omitted key emits nothing                                                                          |
+| `.default(value)`               | Absent → default; field type stays `T`                               | Key omittable        | Value equal to the default ELIDES (compared by serialized wire form) — one canonical URL per state |
+| `.default(() => value)`         | Absent → factory result; field type stays `T`                        | Key omittable        | NEVER elides (a time-varying factory would swallow explicit values)                                |
+| `.catch(v)` / `.catch(() => v)` | A PRESENT value that fails parsing → fallback. Never covers absence. | No change            | No change                                                                                          |
+
+Legality (compile-time type-state — illegal calls type as `never`; runtime throws for JS):
+
+- Legal: `p.integer()`, `.optional()`, `.default(1)`, `.catch(0)`, `.optional().catch(0)`, `.catch(0).optional()`, `.default(1).catch(0)`, `.catch(0).default(1)`, `p.csv().default([])`, `p.array().catch([])`.
+- Illegal: `.optional().default(...)`, `.default(...).optional()`, `.optional().optional()`, `.default(...).default(...)`, `.catch(...).catch(...)`, `p.array().optional()`, `p.array().default(...)`, any modifier on a csv/array ELEMENT (`p.csv(p.string().optional())`), `p.csv(p.csv())`, `p.array(p.array())`, and `.default(value)` where the value's type includes a function member (use the factory form).
+- `params:` codecs additionally forbid `.optional()`/`.default()` (path optionality comes from `[[...slug]]`); `.catch()` is fine.
+
+Value vs factory `.default()`: value defaults are serialized eagerly at definition time (an invalid default fails immediately) and participate in URL elision; factory defaults are invoked per decode (fresh reference per call — use for mutable objects) and never elide. Array value defaults are handed out as fresh shallow copies per decode.
+
+## Defining routes
+
+```ts
+import { defineAppRoute, definePagesRoute, p } from "paramour";
+
+export const productRoute = defineAppRoute("/product/[id]", {
+  params: { id: p.integer() },
+  search: { page: p.index().default(0), tags: p.csv() },
+});
+
+export const docsRoute = defineAppRoute("/docs/[[...slug]]", {
+  params: { slug: p.string() }, // codec describes ONE segment element
+});
+
+export const aboutRoute = defineAppRoute("/about", {}); // static: params rejected
+
+export const blogRoute = definePagesRoute("/blog/[slug]", {
+  params: { slug: p.string() },
+  search: { preview: p.boolean().optional() },
+});
+```
+
+Rules:
+
+- Path literal is checked against the generated registry (`paramour-env.d.ts`); pre-generation any literal compiles. Exactly one codec per dynamic segment name; extra or misspelled `params:` keys fail to compile.
+- `[...slug]` / `[[...slug]]` decode to `Out[]` (absent optional catch-all → `[]`); the codec is per-element, `.catch()` recovery is element-wise.
+- Pages routes forbid a search key shadowing a path param name (Next merges `query`, path params win).
+- Whole-object escape hatch: `search: rawSearch(zodSchema)` hands the entire search object to one Standard Schema — schema sees every key on decode; encode is a raw pass-through of wire strings (no round-trip, no elision). Prefer codec maps.
+
+## Server-side reads
+
+App Router (async, props-based): `route.parse(props)`, `route.parseParams(props)`, `route.parseSearch(props)` — throw `ParamsDecodeError`/`SearchDecodeError` on malformed URLs (params decode first) — plus `safeParse`/`safeParseParams`/`safeParseSearch` returning `SafeResult` (`status: "success" | "error"`). Annotate page props as `RouteProps` (or `ParamsProps`/`SearchProps` for layouts/halves) from `paramour`; `generateMetadata` takes the same props.
+
+Pages Router (sync, context-based): `route.parseContext(ctx)` / `route.safeParseContext(ctx)` with a `getServerSideProps` or `getInitialProps` context (`{ params?, query }`). NOT `getStaticProps` (no query string) — decode `ctx.params` with `safeDecodeParams(route, ctx.params ?? {})` there.
+
+Standalone sync decoders (middleware, route handlers, anywhere holding a source): `decodeParams`/`decodeSearch` (throwing) and `safeDecodeParams`/`safeDecodeSearch` (SafeResult), all from `paramour`.
+
+## Typed links
+
+```ts
+import { href } from "paramour";
+
+href(productRoute, { params: { id: 42 }, search: { tags: ["a", "b"] } });
+// "/product/42?tags=a,b"
+href(aboutRoute); // "/about" — options omittable when nothing is required
+href(productRoute, { params: { id: 1 }, hash: "reviews" }); // "#reviews" appended verbatim
+href("/about", { hash: "team" }); // string form: registered STATIC paths only
+```
+
+`href` returns `Href` — a string subtype accepted by `next/link`, `router.push`, `redirect` unchanged. Required params/search make the options argument required; defaulted/optional/array keys are omittable. Serialization failures (bad value, empty segment, required catch-all given `[]`) throw `SerializeError` at link-build time. Lower-level pieces: `buildPath(route, params)`, `searchToString(config, input)`, `encodeStaticParams(route, params)` for `generateStaticParams`/`getStaticPaths`.
+
+## Client hooks
+
+App Router — `import { useRouteParams, useRouteParamsOrThrow, useSearch, useSearchOrThrow } from "@paramour-js/next/app"` (client components only; app-branded routes only, compile-enforced):
+
+- `useRouteParams(route)` / `useSearch(route)` → `SafeResult`: branch on `result.status === "error"` before touching `result.data`. No loading state; SSR-consistent.
+- `useRouteParamsOrThrow(route)` / `useSearchOrThrow(route)` → decoded value, throwing the decode error to the nearest error boundary.
+- All four accept optional `{ select: (value) => U, equality?: "shallow" }` — a projection with result-equality stabilization so unrelated URL churn (e.g. `utm_*`) does not produce new references.
+
+Pages Router — `import { useRouteParams, useSearch } from "@paramour-js/next/pages"` (pages-branded routes only):
+
+- Return `RouterResult` = `SafeResult` plus a `{ status: "pending" }` arm for the pre-`isReady` first render of a statically optimized page. Handle all three statuses. No `OrThrow` variants exist, by design. Same `{ select }` option.
+
+Testing — `import { ParamourTestingProvider, withParamourTesting } from "@paramour-js/next/testing"`: overrides the hooks' framework reads without mocking `next/*` modules. `withParamourTesting({ pathname: "/product/42", params: { id: "42" }, search: "?q=hi" })` is testing-library's `wrapper`; options also cover `isReady`, `mounted`, `onReplace`, `params: null`.
+
+## Errors
+
+All library throws are `ParamourError` subclasses (brand-hardened `instanceof`): `ParseError` (one wire value failed its grammar/schema; `.catch()`-recoverable), `SerializeError` (link-build time), `ParamsDecodeError`/`SearchDecodeError` (aggregate, `.issues: Issue[]` with `key`/`message`/`reason`/`expected`/`wire`), `SearchSourceError` (malformed source under a declared key). `safeParse*`/`safeDecode*`/hooks convert only the decode errors into the error arm — contract violations stay thrown.