@paramour-js/next 0.8.0 → 0.10.0

package/dist/app.d.ts

@@ -1,4 +1,4 @@
-import { type AnyAppRoute, type InferRouteParams, type SafeResult, type SearchOutputOf } from "paramour";
+import { type AnyAppRoute, type InferRouteParams, type InferRouteSearch, ParamsDecodeError, type SafeResult, SearchDecodeError } from "paramour";
 import { type SelectOptions } from "./select.js";
 export type { SelectOptions } from "./select.js";
 /**
@@ -30,7 +30,7 @@ export type { SelectOptions } from "./select.js";
  *   render, to the nearest client error boundary.
  *
  * Both read the route's blessed-internal `~search` / `~params` via the core
- * decoders — `@paramour/next` is a sanctioned consumer of those internals.
+ * decoders — `@paramour-js/next` is a sanctioned consumer of those internals.
  *
  * Every hook is gated to `AnyAppRoute`: a pages-branded route at one of
  * these call sites is a compile error, not a runtime surprise — these hooks
@@ -70,8 +70,8 @@ export type { SelectOptions } from "./select.js";
  * Core keeps its loud throw for genuinely non-object sources from plain-JS
  * callers; the null tolerance lives here at the adapter.
  */
-export declare function useRouteParams<R extends AnyAppRoute>(route: R): SafeResult<InferRouteParams<R>>;
-export declare function useRouteParams<R extends AnyAppRoute, U>(route: R, options: SelectOptions<InferRouteParams<R>, U>): SafeResult<U>;
+export declare function useRouteParams<R extends AnyAppRoute>(route: R): SafeResult<InferRouteParams<R>, ParamsDecodeError>;
+export declare function useRouteParams<R extends AnyAppRoute, U>(route: R, options: SelectOptions<InferRouteParams<R>, U>): SafeResult<U, ParamsDecodeError>;
 /**
  * Decoded route params, or a thrown {@link ParamsDecodeError} (→ nearest
  * client error boundary) on a malformed URL. Optionally projected through
@@ -87,12 +87,12 @@ export declare function useRouteParamsOrThrow<R extends AnyAppRoute, U>(route: R
  * Decoded search params as a `SafeResult` (discriminated on `status`),
  * optionally projected through `options.select`.
  */
-export declare function useSearch<R extends AnyAppRoute>(route: R): SafeResult<SearchOutputOf<R["~search"]>>;
-export declare function useSearch<R extends AnyAppRoute, U>(route: R, options: SelectOptions<SearchOutputOf<R["~search"]>, U>): SafeResult<U>;
+export declare function useSearch<R extends AnyAppRoute>(route: R): SafeResult<InferRouteSearch<R>, SearchDecodeError>;
+export declare function useSearch<R extends AnyAppRoute, U>(route: R, options: SelectOptions<InferRouteSearch<R>, U>): SafeResult<U, SearchDecodeError>;
 /**
  * Decoded search params, or a thrown {@link SearchDecodeError} (→ nearest
  * client error boundary) on a malformed URL. Optionally projected through
  * `options.select`.
  */
-export declare function useSearchOrThrow<R extends AnyAppRoute>(route: R): SearchOutputOf<R["~search"]>;
-export declare function useSearchOrThrow<R extends AnyAppRoute, U>(route: R, options: SelectOptions<SearchOutputOf<R["~search"]>, U>): U;
+export declare function useSearchOrThrow<R extends AnyAppRoute>(route: R): InferRouteSearch<R>;
+export declare function useSearchOrThrow<R extends AnyAppRoute, U>(route: R, options: SelectOptions<InferRouteSearch<R>, U>): U;

package/dist/app.js

@@ -2,7 +2,7 @@
 import { useParams, usePathname, useRouter, useSearchParams, } from "next/navigation";
 import { decodeParams, decodeSearch, ParamsDecodeError, safeDecodeParams, safeDecodeSearch, SearchDecodeError, } from "paramour";
 import { useContext } from "react";
-import { searchWireSnapshot } from "./devtools-seam.js";
+import { searchWireSnapshot } from "./devtools-emit.js";
 import { AppNavigationContext, } from "./navigation-adapter.js";
 import { makeAppNavigate, useDevtoolsEmitter, } from "./observe.js";
 import { paramsFingerprint, searchParamsFingerprint, useSelectedResult, useSelectedValue, useStableResult, } from "./select.js";
@@ -127,21 +127,14 @@ export function useSearchOrThrow(route, options) {
             wire: () => searchWireSnapshot(searchParams),
         };
     const value = useStableResult(route, searchParamsFingerprint(route, searchParams), 
-    // decodeSearch is keyed on SearchOutputOf (SS6) — the correct
-    // public type — but AnyAppRoute erases its SC to `any`, so for a still-
-    // generic R the call's SearchOutputOf<R["~search"]> reduces to `unknown`
-    // on the value side while staying deferred on the annotation side. The
-    // cast bridges that inference gap to the SAME (correct) type, so a
-    // rawSearch route now infers its schema output here, not a garbage
-    // {~kind, ~schema} shape. The cast appears in both branches below — the
-    // prod/dev split (and its duplicated decode call) is the price of
+    // The prod/dev split (and its duplicated decode call) is the price of
     // literal-zero prod cost; the bundler keeps exactly one branch.
     () => {
         if (process.env.NODE_ENV === "production") {
-            return decodeSearch(route["~search"], searchParams, route.path);
+            return decodeSearch(route, searchParams);
         }
         try {
-            const data = decodeSearch(route["~search"], searchParams, route.path);
+            const data = decodeSearch(route, searchParams);
             if (spec !== undefined) {
                 emitter.observe(spec, { data, status: "success" });
             }

package/dist/cli-inputs.d.ts

@@ -1,3 +1,4 @@
+import { ParamourError } from "paramour";
 import { type ParamourConfig } from "./config.js";
 import { type GenerateInputs } from "./generate.js";
 /**
@@ -15,7 +16,8 @@ export interface InputFlags {
  * treat it like any other exit-2 error, but `init` downgrades it to a
  * warn-and-skip — a fresh project legitimately has no app/ or pages/ yet.
  */
-export declare class NoRouteDirsError extends Error {
+export declare class NoRouteDirsError extends ParamourError {
+    readonly name: "NoRouteDirsError";
 }
 /**
  * Precedence lives in exactly this function: flags → config file → joint
@@ -26,6 +28,8 @@ export declare class NoRouteDirsError extends Error {
  * exists is that an error: app-only and pages-only projects are both fine.
  *
  * Commands that already loaded the config file (for fields beyond these,
- * e.g. `list`'s routeFiles) pass it as `preloaded` so jiti runs once.
+ * e.g. `list`'s routeFiles) pass it as `preloaded` so jiti runs once. The
+ * `withTypedRoutes` wrapper resolves through here too, with no flags, so
+ * the CLI and `next dev`/`next build` always agree on dirs and artifact.
  */
-export declare function resolveInputs(flags: InputFlags, projectRoot: string, preloaded?: ParamourConfig): Promise<GenerateInputs>;
+export declare function resolveInputs(flags: InputFlags, projectRoot: string, preloaded?: ParamourConfig, pageExtensionsOverride?: readonly string[]): Promise<GenerateInputs>;

package/dist/cli-inputs.js

@@ -1,5 +1,6 @@
 import { statSync } from "node:fs";
 import { resolve } from "node:path";
+import { ParamourError } from "paramour";
 import { loadConfigFile } from "./config.js";
 import {} from "./generate.js";
 import { DEFAULT_PAGE_EXTENSIONS } from "./scan-app.js";
@@ -9,7 +10,8 @@ import { resolveRouteDirs } from "./scan.js";
  * treat it like any other exit-2 error, but `init` downgrades it to a
  * warn-and-skip — a fresh project legitimately has no app/ or pages/ yet.
  */
-export class NoRouteDirsError extends Error {
+export class NoRouteDirsError extends ParamourError {
+    name = "NoRouteDirsError";
 }
 /**
  * Precedence lives in exactly this function: flags → config file → joint
@@ -20,11 +22,16 @@ export class NoRouteDirsError extends Error {
  * exists is that an error: app-only and pages-only projects are both fine.
  *
  * Commands that already loaded the config file (for fields beyond these,
- * e.g. `list`'s routeFiles) pass it as `preloaded` so jiti runs once.
+ * e.g. `list`'s routeFiles) pass it as `preloaded` so jiti runs once. The
+ * `withTypedRoutes` wrapper resolves through here too, with no flags, so
+ * the CLI and `next dev`/`next build` always agree on dirs and artifact.
  */
-export async function resolveInputs(flags, projectRoot, preloaded) {
+export async function resolveInputs(flags, projectRoot, preloaded, pageExtensionsOverride) {
     const file = preloaded ?? (await loadConfigFile(projectRoot))?.config;
-    const pageExtensions = parsePageExtensions(flags["page-extensions"]) ??
+    // The override is withTypedRoutes' Next-authoritative extension list:
+    // inside `next dev`/`next build`, what Next routes on wins over the file.
+    const pageExtensions = pageExtensionsOverride ??
+        parsePageExtensions(flags["page-extensions"]) ??
         file?.pageExtensions ??
         DEFAULT_PAGE_EXTENSIONS;
     const explicitAppDir = flags["app-dir"] ?? file?.appDir;

package/dist/collisions.d.ts

@@ -1,3 +1,4 @@
+import { ParamourError } from "paramour";
 /** A scanned route path labeled with the router that produced it. */
 export interface ScannedRoute {
     path: string;
@@ -11,8 +12,9 @@ export interface ScannedRoute {
  * collision mid-`--watch` is usually a file mid-move, so the last good
  * artifact stays on disk).
  */
-export declare class RouteCollisionError extends Error {
-    name: string;
+export declare class RouteCollisionError extends ParamourError {
+    readonly name: "RouteCollisionError";
+    static [Symbol.hasInstance](value: unknown): value is RouteCollisionError;
 }
 /**
  * Structural collisions — same detection pass, non-equal strings. Two

package/dist/collisions.js

@@ -1,3 +1,5 @@
+import { ParamourError } from "paramour";
+const routeCollisionErrorBrand = Symbol.for("paramour.errors.RouteCollisionError");
 /**
  * Route-collision failure mode: states Next itself refuses to build have no
  * valid artifact, so the scanners throw instead of emitting one. Composition
@@ -6,8 +8,21 @@
  * collision mid-`--watch` is usually a file mid-move, so the last good
  * artifact stays on disk).
  */
-export class RouteCollisionError extends Error {
+export class RouteCollisionError extends ParamourError {
+    static {
+        // Same cross-copy identity brand scheme as core's error classes: a
+        // realm-global Symbol.for() key on the prototype, so `instanceof`
+        // recognizes instances from a second physical copy of this package.
+        Object.defineProperty(this.prototype, routeCollisionErrorBrand, {
+            value: true,
+        });
+    }
     name = "RouteCollisionError";
+    static [Symbol.hasInstance](value) {
+        return (typeof value === "object" &&
+            value !== null &&
+            value[routeCollisionErrorBrand] === true);
+    }
 }
 /**
  * `[[...name]]` → optional catch-all; used for the specificity check below.

package/dist/config.d.ts

@@ -1,7 +1,7 @@
 /**
- * Shape of `paramour.config.{ts,mjs,json}` — the CLI's config file. Every
- * field is optional; the CLI's precedence is flags → this file → inference.
- * `.ts`/`.mjs` files default-export this object.
+ * Shape of `paramour.config.{ts,mjs,json}` — read by the CLI and by
+ * `withTypedRoutes`. Every field is optional; the CLI's precedence is flags →
+ * this file → inference. `.ts`/`.mjs` files default-export this object.
  */
 export interface ParamourConfig {
     /** App dir, relative to the project root; default: joint discovery. */

package/dist/devtools-emit.d.ts

@@ -0,0 +1,40 @@
+import type { ParamsSource } from "paramour";
+import type { ParamourDevtoolsSeam, ParamourObservation, ParamourSearchWire } from "./devtools-seam.js";
+/**
+ * The hooks' side of the devtools seam: the emit helpers behind the
+ * contract in `devtools-seam.ts`. Internal — never exported from the
+ * package; the panel re-implements the attach side against the contract.
+ * The emitted JS here imports NOTHING (every import above is type-only) —
+ * load-bearing for the production erasure described in the contract.
+ */
+/**
+ * 128: replay only needs the pre-panel-mount window. One observation per
+ * decode CHANGE per hook means even a long pre-open session is dozens
+ * of entries, not thousands; the panel keys on route, so depth beyond
+ * "every route seen recently" adds nothing — the cap mostly bounds how many
+ * live route/result references the buffer retains.
+ */
+export declare const OBSERVATION_BUFFER_CAP = 128;
+/**
+ * Pushes one observation and notifies listeners. The internal production
+ * early-return is belt-and-suspenders (every call site is ALSO guarded,
+ * which is what the bundler erases); it makes the guard directly
+ * unit-testable and keeps a future unguarded call site failing safe.
+ */
+export declare function emitObservation(observation: ParamourObservation): void;
+/**
+ * The slot, created on first touch by whichever side (hooks or panel) runs
+ * first.
+ */
+export declare function getParamourSeam(): ParamourDevtoolsSeam;
+/**
+ * Pages `query` record → wire pairs; `string[]` values expand to repeated
+ * keys in array order, `undefined` values are wire absence and are skipped.
+ */
+export declare function recordWireSnapshot(source: ParamsSource): ParamourSearchWire;
+/**
+ * Decode-time freeze of the (live, mutable) `URLSearchParams` into wire
+ * pairs: the observation outlives the render in the ring buffer, so it must
+ * capture what the DECODE saw, not a live view.
+ */
+export declare function searchWireSnapshot(source: URLSearchParams): ParamourSearchWire;

package/dist/devtools-emit.js

@@ -0,0 +1,85 @@
+/**
+ * The hooks' side of the devtools seam: the emit helpers behind the
+ * contract in `devtools-seam.ts`. Internal — never exported from the
+ * package; the panel re-implements the attach side against the contract.
+ * The emitted JS here imports NOTHING (every import above is type-only) —
+ * load-bearing for the production erasure described in the contract.
+ */
+/**
+ * 128: replay only needs the pre-panel-mount window. One observation per
+ * decode CHANGE per hook means even a long pre-open session is dozens
+ * of entries, not thousands; the panel keys on route, so depth beyond
+ * "every route seen recently" adds nothing — the cap mostly bounds how many
+ * live route/result references the buffer retains.
+ */
+export const OBSERVATION_BUFFER_CAP = 128;
+const SEAM_KEY = Symbol.for("paramour.devtools.seam");
+const globalSlots = globalThis;
+/**
+ * Pushes one observation and notifies listeners. The internal production
+ * early-return is belt-and-suspenders (every call site is ALSO guarded,
+ * which is what the bundler erases); it makes the guard directly
+ * unit-testable and keeps a future unguarded call site failing safe.
+ */
+export function emitObservation(observation) {
+    if (process.env.NODE_ENV === "production")
+        return;
+    const seam = getParamourSeam();
+    seam.buffer.push(observation);
+    if (seam.buffer.length > OBSERVATION_BUFFER_CAP)
+        seam.buffer.shift();
+    for (const listener of seam.listeners) {
+        try {
+            listener(observation);
+        }
+        catch {
+            // A panel bug must never break app render — emit runs render-phase.
+        }
+    }
+}
+/**
+ * The slot, created on first touch by whichever side (hooks or panel) runs
+ * first.
+ */
+export function getParamourSeam() {
+    const existing = globalSlots[SEAM_KEY];
+    if (existing !== undefined)
+        return existing;
+    const created = {
+        buffer: [],
+        listeners: new Set(),
+        version: 1,
+    };
+    globalSlots[SEAM_KEY] = created;
+    return created;
+}
+/**
+ * Pages `query` record → wire pairs; `string[]` values expand to repeated
+ * keys in array order, `undefined` values are wire absence and are skipped.
+ */
+export function recordWireSnapshot(source) {
+    const pairs = [];
+    for (const [key, value] of Object.entries(source)) {
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            for (const element of value)
+                pairs.push([key, element]);
+        }
+        else {
+            pairs.push([key, value]);
+        }
+    }
+    return pairs;
+}
+/**
+ * Decode-time freeze of the (live, mutable) `URLSearchParams` into wire
+ * pairs: the observation outlives the render in the ring buffer, so it must
+ * capture what the DECODE saw, not a live view.
+ */
+export function searchWireSnapshot(source) {
+    const pairs = [];
+    for (const [key, value] of source)
+        pairs.push([key, value]);
+    return pairs;
+}

package/dist/devtools-seam.d.ts

@@ -27,9 +27,14 @@ import type { AnyRoute, ParamsSource, RouterKind, SafeResult } from "paramour";
  * - Production: every emit call site sits behind
  *   `process.env.NODE_ENV !== "production"`, which Next's compilers
  *   constant-fold; with the package's `sideEffects: false` the then-dead
- *   import of this module is dropped entirely. The emitted JS here imports
- *   NOTHING (the one `paramour` import is type-only) — load-bearing for
- *   that erasure.
+ *   import of the emitter module (`devtools-emit.ts`) is dropped entirely.
+ * - Stability: this module is the published, semver-covered contract. It
+ *   declares TYPES ONLY — the emit/attach helpers live in the internal
+ *   `devtools-emit.ts`, so a value import through the types-only
+ *   `./devtools-seam` entry can't type-check. Closed-looking unions here
+ *   (`ParamourHookId`, the observation `kind`s) are OPEN by policy: new
+ *   hooks and observation kinds ship in minor releases, so consumers must
+ *   tolerate members they don't recognize.
  */
 /** The `Symbol.for("paramour.devtools.seam")` slot shape — the seam contract. */
 export interface ParamourDevtoolsSeam {
@@ -43,7 +48,10 @@ export interface ParamourDevtoolsSeam {
      */
     readonly version: 1;
 }
-/** Discriminant naming which hook reported. */
+/**
+ * Discriminant naming which hook reported. Open by policy: a new hook adds a
+ * member in a minor release, so switch over it with a default branch.
+ */
 export type ParamourHookId = "app.useRouteParams" | "app.useRouteParamsOrThrow" | "app.useSearch" | "app.useSearchOrThrow" | "pages.useRouteParams" | "pages.useSearch";
 /**
  * Navigation capability captured from the EMITTING hook's router: the panel
@@ -66,32 +74,8 @@ export type ParamourNavigate = (search: string) => void;
  * captured `navigate`/`pathname` never go stale while the hook is mounted.
  */
 export type ParamourObservation = ParamourParamsObservation | ParamourSearchObservation;
-/**
- * Pre-`select` decode result: the hook's full `SafeResult` — the error arm
- * carries the LIVE `ParamsDecodeError`/`SearchDecodeError` with its
- * `issues` — never the user's `select` projection. `pending` is the
- * Pages-only third state. Generic-erased on purpose: the panel treats
- * `data` structurally.
- */
-export type ParamourObservationResult = SafeResult<unknown> | {
-    readonly status: "pending";
-};
-/** Params decode: wire is a decode-time shallow copy of the source record. */
-export interface ParamourParamsObservation extends ParamourObservationBase {
-    readonly kind: "params";
-    readonly wire: Readonly<ParamsSource>;
-}
-/**
- * Search decode: wire is decode-time `[key, value]` pairs in wire order —
- * order is load-bearing for repeated keys (P5/S5), and pairs round-trip
- * losslessly into the panel's raw-wire editing.
- */
-export interface ParamourSearchObservation extends ParamourObservationBase {
-    readonly kind: "search";
-    readonly wire: ParamourSearchWire;
-}
-export type ParamourSearchWire = readonly (readonly [string, string])[];
-interface ParamourObservationBase {
+/** Fields every observation carries, whatever its `kind`. */
+export interface ParamourObservationBase {
     readonly hook: ParamourHookId;
     readonly navigate: ParamourNavigate;
     /**
@@ -114,34 +98,27 @@ interface ParamourObservationBase {
     readonly routerKind: RouterKind;
 }
 /**
- * 128: replay only needs the pre-panel-mount window. One observation per
- * decode CHANGE per hook means even a long pre-open session is dozens
- * of entries, not thousands; the panel keys on route, so depth beyond
- * "every route seen recently" adds nothing — the cap mostly bounds how many
- * live route/result references the buffer retains.
- */
-export declare const OBSERVATION_BUFFER_CAP = 128;
-/**
- * Pushes one observation and notifies listeners. The internal production
- * early-return is belt-and-suspenders (every call site is ALSO guarded,
- * which is what the bundler erases); it makes the guard directly
- * unit-testable and keeps a future unguarded call site failing safe.
- */
-export declare function emitObservation(observation: ParamourObservation): void;
-/**
- * The slot, created on first touch by whichever side (hooks or panel) runs
- * first.
- */
-export declare function getParamourSeam(): ParamourDevtoolsSeam;
-/**
- * Pages `query` record → wire pairs; `string[]` values expand to repeated
- * keys in array order, `undefined` values are wire absence and are skipped.
+ * Pre-`select` decode result: the hook's full `SafeResult` — the error arm
+ * carries the LIVE `ParamsDecodeError`/`SearchDecodeError` with its
+ * `issues` — never the user's `select` projection. `pending` is the
+ * Pages-only third state. Generic-erased on purpose: the panel treats
+ * `data` structurally.
  */
-export declare function recordWireSnapshot(source: ParamsSource): ParamourSearchWire;
+export type ParamourObservationResult = SafeResult<unknown> | {
+    readonly status: "pending";
+};
+/** Params decode: wire is a decode-time shallow copy of the source record. */
+export interface ParamourParamsObservation extends ParamourObservationBase {
+    readonly kind: "params";
+    readonly wire: Readonly<ParamsSource>;
+}
 /**
- * Decode-time freeze of the (live, mutable) `URLSearchParams` into wire
- * pairs: the observation outlives the render in the ring buffer, so it must
- * capture what the DECODE saw, not a live view.
+ * Search decode: wire is decode-time `[key, value]` pairs in wire order —
+ * order is load-bearing for repeated keys (P5/S5), and pairs round-trip
+ * losslessly into the panel's raw-wire editing.
  */
-export declare function searchWireSnapshot(source: URLSearchParams): ParamourSearchWire;
-export {};
+export interface ParamourSearchObservation extends ParamourObservationBase {
+    readonly kind: "search";
+    readonly wire: ParamourSearchWire;
+}
+export type ParamourSearchWire = readonly (readonly [string, string])[];

package/dist/devtools-seam.js

@@ -1,78 +1 @@
-/**
- * 128: replay only needs the pre-panel-mount window. One observation per
- * decode CHANGE per hook means even a long pre-open session is dozens
- * of entries, not thousands; the panel keys on route, so depth beyond
- * "every route seen recently" adds nothing — the cap mostly bounds how many
- * live route/result references the buffer retains.
- */
-export const OBSERVATION_BUFFER_CAP = 128;
-const SEAM_KEY = Symbol.for("paramour.devtools.seam");
-const globalSlots = globalThis;
-/**
- * Pushes one observation and notifies listeners. The internal production
- * early-return is belt-and-suspenders (every call site is ALSO guarded,
- * which is what the bundler erases); it makes the guard directly
- * unit-testable and keeps a future unguarded call site failing safe.
- */
-export function emitObservation(observation) {
-    if (process.env.NODE_ENV === "production")
-        return;
-    const seam = getParamourSeam();
-    seam.buffer.push(observation);
-    if (seam.buffer.length > OBSERVATION_BUFFER_CAP)
-        seam.buffer.shift();
-    for (const listener of seam.listeners) {
-        try {
-            listener(observation);
-        }
-        catch {
-            // A panel bug must never break app render — emit runs render-phase.
-        }
-    }
-}
-/**
- * The slot, created on first touch by whichever side (hooks or panel) runs
- * first.
- */
-export function getParamourSeam() {
-    const existing = globalSlots[SEAM_KEY];
-    if (existing !== undefined)
-        return existing;
-    const created = {
-        buffer: [],
-        listeners: new Set(),
-        version: 1,
-    };
-    globalSlots[SEAM_KEY] = created;
-    return created;
-}
-/**
- * Pages `query` record → wire pairs; `string[]` values expand to repeated
- * keys in array order, `undefined` values are wire absence and are skipped.
- */
-export function recordWireSnapshot(source) {
-    const pairs = [];
-    for (const [key, value] of Object.entries(source)) {
-        if (value === undefined)
-            continue;
-        if (Array.isArray(value)) {
-            for (const element of value)
-                pairs.push([key, element]);
-        }
-        else {
-            pairs.push([key, value]);
-        }
-    }
-    return pairs;
-}
-/**
- * Decode-time freeze of the (live, mutable) `URLSearchParams` into wire
- * pairs: the observation outlives the render in the ring buffer, so it must
- * capture what the DECODE saw, not a live view.
- */
-export function searchWireSnapshot(source) {
-    const pairs = [];
-    for (const [key, value] of source)
-        pairs.push([key, value]);
-    return pairs;
-}
+export {};

package/dist/doctor/checks.js

@@ -206,8 +206,6 @@ function readManifest(projectRoot, name) {
         }
     }
 }
-/** `1.2.3` / `1.2.3-beta.1` — the shape a published `workspace:*` pin takes. */
-const EXACT_VERSION = /^\d+\.\d+\.\d+(?:-[\w.-]+)?$/;
 function versionCheck(projectRoot) {
     const coreManifest = readManifest(projectRoot, "paramour");
     const nextManifest = readManifest(projectRoot, "@paramour-js/next");
@@ -228,27 +226,22 @@ function versionCheck(projectRoot) {
             status: "fail",
         };
     }
-    // The packages version INDEPENDENTLY (changesets); comparing the two
-    // installed versions against each other warns on every correct install.
-    // The real invariant is that the installed core is the one the installed
-    // @paramour-js/next declares — `workspace:*` publishes as an exact pin, so
-    // when the declaration is exact this is string equality. A non-exact
-    // declaration (a range, or `workspace:*` inside this monorepo itself) is
-    // the package manager's to enforce; no claim to check.
-    const declared = nextManifest?.dependencies?.paramour;
-    if (declared !== undefined &&
-        EXACT_VERSION.test(declared) &&
-        core !== declared) {
+    // The paramour packages release in LOCKSTEP (one changesets fixed group),
+    // and @paramour-js/next peers on the app's own `paramour` — so a coherent
+    // install has the two at the same version. The peer range itself is the
+    // package manager's to enforce; lockstep equality is the stronger claim,
+    // and the one that catches a half-upgraded app.
+    if (core !== next) {
         return {
             detail: [
-                "your package manager should have matched these — check for overrides/resolutions or a stale lockfile, then reinstall",
+                "paramour packages release together — upgrade them to the same version (e.g. `pnpm up paramour @paramour-js/next`)",
             ],
-            label: `versions: installed paramour ${core} != ${declared}, the version @paramour-js/next ${next} depends on`,
+            label: `versions: paramour ${core} != @paramour-js/next ${next}`,
             status: "warn",
         };
     }
     return {
-        label: `versions: paramour ${core} satisfies @paramour-js/next ${next}'s declared dependency`,
+        label: `versions: paramour and @paramour-js/next are both ${core}`,
         status: "pass",
     };
 }

package/dist/observe.js

@@ -1,5 +1,5 @@
 import { useRef } from "react";
-import { emitObservation } from "./devtools-seam.js";
+import { emitObservation } from "./devtools-emit.js";
 /**
  * App-flavor navigate capability: `next/navigation`'s `replace` returns void
  * and resolves the basePath-/locale-relative join itself.

package/dist/pages.d.ts

@@ -1,4 +1,4 @@
-import { type AnyPagesRoute, type InferRouteParams, type SafeResult, type SearchOutputOf } from "paramour";
+import { type AnyPagesRoute, type InferRouteParams, type InferRouteSearch, type ParamsDecodeError, type RouteDecodeError, type SafeResult, type SearchDecodeError } from "paramour";
 import { type SelectOptions } from "./select.js";
 export type { SelectOptions } from "./select.js";
 /**
@@ -40,18 +40,18 @@ export type { SelectOptions } from "./select.js";
  * page. Literally `SafeResult<T> | { status: "pending" }`, so both routers'
  * results destructure identically.
  */
-export type RouterResult<T> = SafeResult<T> | {
+export type RouterResult<T, E extends RouteDecodeError = RouteDecodeError> = SafeResult<T, E> | {
     status: "pending";
 };
 /**
  * Decoded route params as a {@link RouterResult}, optionally projected
  * through `options.select`.
  */
-export declare function useRouteParams<R extends AnyPagesRoute>(route: R): RouterResult<InferRouteParams<R>>;
-export declare function useRouteParams<R extends AnyPagesRoute, U>(route: R, options: SelectOptions<InferRouteParams<R>, U>): RouterResult<U>;
+export declare function useRouteParams<R extends AnyPagesRoute>(route: R): RouterResult<InferRouteParams<R>, ParamsDecodeError>;
+export declare function useRouteParams<R extends AnyPagesRoute, U>(route: R, options: SelectOptions<InferRouteParams<R>, U>): RouterResult<U, ParamsDecodeError>;
 /**
  * Decoded search params as a {@link RouterResult}, optionally projected
  * through `options.select`.
  */
-export declare function useSearch<R extends AnyPagesRoute>(route: R): RouterResult<SearchOutputOf<R["~search"]>>;
-export declare function useSearch<R extends AnyPagesRoute, U>(route: R, options: SelectOptions<SearchOutputOf<R["~search"]>, U>): RouterResult<U>;
+export declare function useSearch<R extends AnyPagesRoute>(route: R): RouterResult<InferRouteSearch<R>, SearchDecodeError>;
+export declare function useSearch<R extends AnyPagesRoute, U>(route: R, options: SelectOptions<InferRouteSearch<R>, U>): RouterResult<U, SearchDecodeError>;

package/dist/pages.js

@@ -7,7 +7,7 @@
 import { useRouter } from "next/router.js";
 import { ParamourError, safeDecodeParams, safeDecodeSearch, } from "paramour";
 import { useContext } from "react";
-import { recordWireSnapshot } from "./devtools-seam.js";
+import { recordWireSnapshot } from "./devtools-emit.js";
 import { PagesNavigationContext, } from "./navigation-adapter.js";
 import { makePagesNavigate, useDevtoolsEmitter, } from "./observe.js";
 import { paramsFingerprint, PENDING_FINGERPRINT, queryFingerprint, useSelectedResult, useStableResult, } from "./select.js";

package/dist/select.d.ts

@@ -1,4 +1,4 @@
-import type { AnyRoute, ParamsSource, SafeResult } from "paramour";
+import type { AnyRoute, ParamsSource, RouteDecodeError, SafeResult } from "paramour";
 /**
  * Shared internals of the read hooks' selector surface: the raw-slice
  * stabilization layer and the selector layer. Deliberately NO `"use client"`
@@ -72,10 +72,10 @@ export declare function searchParamsFingerprint(route: AnyRoute, source: URLSear
  * Error and pending arms pass through untouched; they are already
  * reference-stabilized by {@link useStableResult}'s raw-slice layer.
  */
-export declare function useSelectedResult<T, U>(result: SafeResult<T>, options: SelectOptions<T, U> | undefined): SafeResult<U>;
-export declare function useSelectedResult<T, U>(result: SafeResult<T> | {
+export declare function useSelectedResult<T, U, E extends RouteDecodeError>(result: SafeResult<T, E>, options: SelectOptions<T, U> | undefined): SafeResult<U, E>;
+export declare function useSelectedResult<T, U, E extends RouteDecodeError>(result: SafeResult<T, E> | {
     status: "pending";
-}, options: SelectOptions<T, U> | undefined): SafeResult<U> | {
+}, options: SelectOptions<T, U> | undefined): SafeResult<U, E> | {
     status: "pending";
 };
 /**

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

@@ -1,11 +1,9 @@
-/** Options for {@link withTypedRoutes}. */
+/**
+ * Options for {@link withTypedRoutes}. Where routes and the artifact live is
+ * NOT configured here: the wrapper reads `paramour.config.*` exactly as the
+ * CLI does, so the two writers can never produce different artifacts.
+ */
 export interface WithTypedRoutesOptions {
-    /**
-     * Artifact location, for monorepos where the Next app root isn't where 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 — for
      * teams that want the committed artifact to be the law. Default `false`,

package/dist/with-typed-routes.js

@@ -1,9 +1,10 @@
-import { resolve } from "node:path";
+import { NoRouteDirsError, resolveInputs } from "./cli-inputs.js";
 import { RouteCollisionError } from "./collisions.js";
+import { loadConfigFile } from "./config.js";
 import { diffGenerated, formatRouteDiff, generate, } from "./generate.js";
 import { acquireWatcherLock, watcherLockPath, } from "./lock.js";
 import { DEFAULT_PAGE_EXTENSIONS } from "./scan-app.js";
-import { resolveRouteDirs } from "./scan.js";
+import {} from "./scan.js";
 import { watchRouteDirs } from "./watch.js";
 /**
  * Phase constants from `next/constants`, hardcoded so the package stays
@@ -59,20 +60,37 @@ 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; the CLI flags are the home for anything more
-        // configurable than this.
+        // project root as cwd — the same root the CLI resolves against.
         const projectRoot = process.cwd();
-        const artifactPath = resolve(projectRoot, options.outFile ?? "paramour-env.d.ts");
+        // A malformed paramour.config throws here, like the populated-ignored-dir
+        // discovery error: both are configuration mistakes, not incidental
+        // generation failures, so they stay loud (see above).
+        const file = (await loadConfigFile(projectRoot))?.config;
+        // Next's pageExtensions is authoritative inside Next — it decides what is
+        // a page. A config file that disagrees would make the CLI scan a
+        // different route set, so say so once.
         const pageExtensions = resolved.pageExtensions ?? DEFAULT_PAGE_EXTENSIONS;
-        // 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) {
+        if (file?.pageExtensions !== undefined &&
+            file.pageExtensions.join(",") !== pageExtensions.join(",")) {
+            warnOnce(`paramour: paramour.config pageExtensions (${file.pageExtensions.join(", ")}) differ from Next's (${pageExtensions.join(", ")}); generation inside Next uses Next's — align the config file so \`paramour generate\` agrees`);
+        }
+        let inputs;
+        try {
+            inputs = await resolveInputs({}, projectRoot, file, pageExtensions);
+        }
+        catch (error) {
+            if (!(error instanceof NoRouteDirsError))
+                throw error;
             // 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;
         }
+        const { artifactPath } = inputs;
+        const dirs = {
+            appDir: inputs.appDir,
+            pagesDir: inputs.pagesDir,
+        };
         if (phase === PHASE_PRODUCTION_BUILD) {
             generateForBuild(dirs, pageExtensions, artifactPath, options.strict ?? false);
             return resolved;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paramour-js/next",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "type": "module",
   "exports": {
     ".": {
@@ -33,11 +33,11 @@
   "dependencies": {
     "jiti": "^2.7.0",
     "magicast": "^0.3.5",
-    "tinyglobby": "^0.2.15",
-    "paramour": "0.8.0"
+    "tinyglobby": "^0.2.15"
   },
   "peerDependencies": {
     "next": ">=15",
+    "paramour": ">=0.9.0 <1.0.0 || ^1.0.0-rc.0",
     "react": ">=18.2.0"
   },
   "devDependencies": {
@@ -50,7 +50,8 @@
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "typescript": "^6.0.3",
-    "zod": "^4.4.3"
+    "zod": "^4.4.3",
+    "paramour": "0.10.0"
   },
   "description": "Next.js integration for paramour: withTypedRoutes, App and Pages Router hooks, PageProps glue, and the codegen CLI.",
   "author": "Jason Paff <jasonpaff@gmail.com>",

package/skills/paramour/SKILL.md

@@ -12,7 +12,7 @@ Paramour is a type-safe routing companion for Next.js: each route is defined onc
 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.
+   - `.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. On an `.optional()` codec the fallback may be `undefined`, so a bad value reads as absent (`.optional().catch(undefined)`).
    - `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.

package/skills/paramour/references/authoring.md

@@ -18,7 +18,7 @@ Wire grammars are strict and anchored — no `Number()` coercion, no whitespace,
 | `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.timestamp()`      | `Date`           | ISO 8601 (`...T..:..:..[.mmm]` + `Z` or `±HH:MM`; offsets decode to the same instant); always serializes UTC `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  |
@@ -27,18 +27,18 @@ Wire grammars are strict and anchored — no `Number()` coercion, no whitespace,
 
 ## 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                                                                                          |
+| 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. After `.optional()`, the fallback may be `undefined` (bad value → absent). | 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).
+- Legal: `p.integer()`, `.optional()`, `.default(1)`, `.catch(0)`, `.optional().catch(0)`, `.optional().catch(undefined)`, `.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(...)`, `.catch(undefined)` on a required/defaulted codec (apply `.optional()` first), `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.

package/skills/paramour/references/migration.md

@@ -77,7 +77,7 @@ export default async function ProductPage(props: RouteProps) {
 - "May be absent, no fallback" (`typeof sp.x === "string" ? sp.x : undefined`) → `.optional()`. Decoded as `T | undefined`.
 - Silent-coercion tolerance (old code shrugged off garbage, e.g. `Number(...)` producing `NaN` handled downstream) → add `.catch(fallback)` so a malformed PRESENT value falls back instead of failing the decode. `.catch()` never covers absence — combine with `.default()`/`.optional()` for that.
 - Multi-value keys (`sp.tags` handled as `string | string[]`) → `p.array()` for repeated keys (`?tags=a&tags=b`) or `p.csv()` for one comma-joined key (`?tags=a,b`). Match whichever wire form the app already emits.
-- Enumerated strings → `p.enum(["a", "b"])`; numbers → `p.number()`; booleans (`sp.flag === "true"`) → `p.boolean()`; dates → `p.isoDate()` (YYYY-MM-DD) or `p.timestamp()` (ISO UTC).
+- Enumerated strings → `p.enum(["a", "b"])`; numbers → `p.number()`; booleans (`sp.flag === "true"`) → `p.boolean()`; dates → `p.isoDate()` (YYYY-MM-DD) or `p.timestamp()` (ISO instant; emits UTC).
 
 ### Behavior change to decide explicitly
 

package/skills/paramour/references/reference.md

@@ -22,28 +22,28 @@ Runtime values:
 | `encodeParams(route, params)`                                                                        | Encoded path segments as `string[]`                                                                             |
 | `encodeStaticParams(route, params)`                                                                  | Per-param wire-string record for `generateStaticParams` / `getStaticPaths`                                      |
 | `decodeParams(route, source, opts?)`                                                                 | Sync params decode; throws `ParamsDecodeError`; `opts: { percentDecode?: boolean }` (default true — App Router) |
-| `decodeSearch(config, source, routePath?)`                                                           | Sync search decode; throws `SearchDecodeError`; unknown keys ignored                                            |
+| `decodeSearch(routeOrConfig, source)`                                                                | Sync search decode; throws `SearchDecodeError`; unknown keys ignored; a route anchors errors to its path        |
 | `safeDecodeParams` / `safeDecodeSearch`                                                              | `SafeResult`-returning twins of the two decoders                                                                |
-| `encodeSearch(config, input)`                                                                        | Decoded values → ordered wire pairs `[string, string][]` (default elision applied)                              |
+| `encodeSearch(routeOrConfig, input)`                                                                 | Decoded values → ordered wire pairs `[string, string][]` (default elision applied)                              |
 | `buildSearchString(pairs)`                                                                           | Pairs → `?…` string (`%20`, never `+`)                                                                          |
-| `searchToString(config, input)`                                                                      | `encodeSearch` + `buildSearchString`                                                                            |
-| `serializeValue(codec, label, value)`                                                                | One value through a codec's serializer, string contract enforced                                                |
+| `searchToString(routeOrConfig, input)`                                                               | `encodeSearch` + `buildSearchString`                                                                            |
+| `serializeValue(codec, label, value)` / `parseValue(codec, raw)`                                     | One value through a codec's serializer (string contract enforced) / parser (no `.catch()` recovery)             |
 | `rawSearch(schema)` / `isRawSearch(config)`                                                          | Whole-object search escape hatch and its discriminant                                                           |
 | `standardSearchSchema(route)`                                                                        | Export a route's search config as a Standard Schema (tRPC input, TanStack `validateSearch`)                     |
 | `describeCodec(codec)` / `describeRoute(route)` / `formatCodecDescription(desc, style)`              | Reflection over codec/route metadata (powers `paramour list`)                                                   |
 | `ParamourError, ParseError, SerializeError, ParamsDecodeError, SearchDecodeError, SearchSourceError` | Error classes (brand-hardened `instanceof`)                                                                     |
 
-Key types: `Codec`, `AnyCodec`, `OutputOf`, `ParamCodec`, `Presence`, `PresenceOf`, `Arity`; `AppRoute`, `PagesRoute`, `Route`, `AnyRoute`, `AnyAppRoute`, `AnyPagesRoute`, `RouterKind`, `PagesContext`; `RouteProps`, `ParamsProps`, `SearchProps` (+ `*Input` sync-accepting forms) — annotate page/layout props with these; `InferRouteParams`, `SearchOutputOf`, `InferSearchInput`, `InferSearchOutput`, `InferStaticParams`, `InferHrefInput`, `HrefArgs`, `Href`, `StaticHrefOptions`; `SafeResult`, `RouteDecodeError`, `Issue`, `IssueReason`; `ParamsConfig`, `SearchConfig`, `ParamsSource`, `SearchSource`, `RawSearch`, `StandardSearchSchema`; `ParamourRegister` + `Registered*RoutePaths` (codegen augmentation targets); `CodecDescription`, `RouteDescription`, `ParamDescription`, `SearchDescription`, `CodecDefaultDescription`, `CodecFormatStyle`; `DecodeParamsOptions`.
+Key types: `Codec`, `AnyCodec` (optionally narrowed to one output type: any codec state producing it), `CodecKind`, `InferCodecOutput`, `ParamCodec`, `Presence`, `PresenceOf`, `Arity`; `AppRoute`, `PagesRoute`, `Route`, `AnyRoute`, `AnyAppRoute`, `AnyPagesRoute`, `RouterKind`, `PagesContext`, `RouteConfig` + `SearchSlot` (for wrapping `define*Route`); `RouteProps`, `ParamsProps`, `SearchProps` — annotate page/layout props with these — and their sync-accepting parse-input forms `RoutePropsLike`, `ParamsPropsLike`, `SearchPropsLike`; `InferRouteParams`, `InferRouteSearch` (a route's decoded params / search), `InferSearchOutput`, `InferSearchInput` (of a `search:` slot), `InferStaticParams`, `InferHrefInput`, `HrefArgs`, `Href`, `StaticHrefOptions`; `SafeResult` (its optional second parameter narrows the error arm to the params or search decode error on one-sided surfaces), `RouteDecodeError`, `Issue`, `IssueReason`; `ParamsConfig`, `SearchConfig`, `ParamsSource`, `SearchSource`, `RawSearch`, `StandardSearchSchema`; `ParamourRegister` + `Registered*RoutePaths` (codegen augmentation targets); `CodecDescription`, `RouteDescription`, `ParamDescription`, `SearchDescription`, `CodecDefaultDescription`, `CodecFormatStyle`; `DecodeParamsOptions`.
 
 ## `@paramour-js/next` exports
 
-| Entry point                       | Exports                                                                                                                                                                     |
-| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@paramour-js/next`               | `withTypedRoutes(config, options?)` (`options: { outFile?, strict? }`), `RouteCollisionError`, types `WithTypedRoutesOptions`, `ParamourConfig`                             |
-| `@paramour-js/next/app`           | `useRouteParams`, `useRouteParamsOrThrow`, `useSearch`, `useSearchOrThrow` (all `(route, options?)` with `options: { select, equality?: "shallow" }`), type `SelectOptions` |
-| `@paramour-js/next/pages`         | `useRouteParams`, `useSearch` (return `RouterResult` = `SafeResult` + `{ status: "pending" }`), types `RouterResult`, `SelectOptions`                                       |
-| `@paramour-js/next/testing`       | `ParamourTestingProvider`, `withParamourTesting(options?)`, type `ParamourTestingOptions` (`isReady, mounted, onReplace, params, pathname, search`)                         |
-| `@paramour-js/next/devtools-seam` | Types-only seam contract consumed by `@paramour-js/devtools-panel`; not needed in app code                                                                                  |
+| Entry point                       | Exports                                                                                                                                                                             |
+| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@paramour-js/next`               | `withTypedRoutes(config, options?)` (`options: { strict? }`; everything else comes from `paramour.config`), `RouteCollisionError`, types `WithTypedRoutesOptions`, `ParamourConfig` |
+| `@paramour-js/next/app`           | `useRouteParams`, `useRouteParamsOrThrow`, `useSearch`, `useSearchOrThrow` (all `(route, options?)` with `options: { select, equality?: "shallow" }`), type `SelectOptions`         |
+| `@paramour-js/next/pages`         | `useRouteParams`, `useSearch` (return `RouterResult` = `SafeResult` + `{ status: "pending" }`), types `RouterResult`, `SelectOptions`                                               |
+| `@paramour-js/next/testing`       | `ParamourTestingProvider`, `withParamourTesting(options?)`, type `ParamourTestingOptions` (`isReady, mounted, onReplace, params, pathname, search`)                                 |
+| `@paramour-js/next/devtools-seam` | Types-only seam contract consumed by `@paramour-js/devtools-panel`; not needed in app code                                                                                          |
 
 ## CLI (`paramour <command>`, bin shipped by `@paramour-js/next`)
 
@@ -68,7 +68,7 @@ Precedence: CLI flags → config file → discovery. Unknown keys are rejected (
 | ---------------- | --------------------------- | ------------------------------------------------------------------------------------------------------ |
 | `appDir`         | discovered `app/`/`src/app` | App directory, relative to project root                                                                |
 | `pagesDir`       | discovered `pages/`…        | Pages directory                                                                                        |
-| `outFile`        | `paramour-env.d.ts`         | Artifact path (monorepo escape hatch); also settable on `withTypedRoutes`                              |
+| `outFile`        | `paramour-env.d.ts`         | Artifact path (monorepo escape hatch); honored by the CLI and `withTypedRoutes` alike                  |
 | `pageExtensions` | `["tsx","ts","jsx","js"]`   | No leading dots                                                                                        |
 | `routeFiles`     | automatic content scan      | Globs of modules exporting route definitions — used by `list`/`doctor` only; generation never reads it |
 
@@ -89,7 +89,7 @@ Precedence: CLI flags → config file → discovery. Unknown keys are rejected (
 Facts agents trip on:
 
 - Booleans serialize as exactly `true`/`false`; anything else fails to parse.
-- Dates: `p.isoDate` is `YYYY-MM-DD`; `p.timestamp` is full ISO UTC (`Z` only, offsets rejected); both reject impossible calendar dates.
+- Dates: `p.isoDate` is `YYYY-MM-DD`; `p.timestamp` is a full ISO instant (`Z` or `±HH:MM` on input, always UTC on output); both reject impossible calendar dates.
 - Integers reject `1e3`, hex, whitespace, and unsafe-range values.
 - Arrays: `p.array` repeats the key (`?t=a&t=b`); `p.csv` packs one key (`?t=a,b`). Same in-memory `string[]`, two deliberate wire spellings — do not swap them casually.
 - Value-form `.default()` elides: building a URL with the default value emits nothing for that key; decoding the bare URL restores the default. Factory defaults never elide.

package/skills/paramour/references/setup.md

@@ -61,7 +61,7 @@ const nextConfig: NextConfig = {};
 export default withTypedRoutes(nextConfig);
 ```
 
-`withTypedRoutes(config, options?)` regenerates the artifact once per production build (drift warns; `{ strict: true }` fails the build on drift instead) and runs a debounced regeneration watcher during `next dev`. `{ outFile: "..." }` relocates the artifact (monorepo escape hatch). Generation is never load-bearing: a missing route dir or an incidental failure warns and continues with stale types — the two exceptions that throw are an app↔pages route collision and a populated-but-ignored route dir.
+`withTypedRoutes(config, options?)` regenerates the artifact once per production build (drift warns; `{ strict: true }` fails the build on drift instead) and runs a debounced regeneration watcher during `next dev`. It reads `paramour.config` like the CLI does (`outFile` there relocates the artifact for both; Next's own `pageExtensions` wins inside Next, with a warning if the config file disagrees). Generation is never load-bearing: a missing route dir or an incidental failure warns and continues with stale types — the two exceptions that throw are an app↔pages route collision and a populated-but-ignored route dir.
 
 Add the script to `package.json`: