@paramour-js/next 0.3.1 → 0.4.1

package/dist/app.d.ts

@@ -2,67 +2,66 @@ import { type AnyAppRoute, type InferRouteParams, type SafeResult, type SearchOu
 import { type SelectOptions } from "./select.js";
 export type { SelectOptions } from "./select.js";
 /**
- * Client hooks (DESIGN §9, design-07). Each layers over Next's
- * `useSearchParams()` / `useParams()` — App-Router params are synchronous on
- * the client, so there is no loading state, no `useEffect`/`useState`, and
- * the result is SSR-consistent. Two layers per hook (design-07):
+ * Client hooks. Each layers over Next's `useSearchParams()` / `useParams()`
+ * — App-Router params are synchronous on the client, so there is no loading
+ * state, no `useEffect`/`useState`, and the result is SSR-consistent. Two
+ * layers per hook:
  *
- * - Raw-slice stabilization (SEL4): the decode is keyed on the DECLARED
- *   slice of the raw source, not on Next's object reference — a URL change
- *   that only touches keys the route doesn't own (`?utm_source=` churn)
- *   returns the previous result by identity, without re-decoding. Next still
- *   re-renders every subscriber on any URL change (it owns the subscription
- *   — SEL7: selectors stabilize slices, they cannot skip renders); this
- *   layer makes that render cheap and downstream-invisible.
- * - Selection (SEL1–SEL3): every hook takes an optional `{ select }` that
- *   projects the decoded value, with result-equality checking (`Object.is`,
+ * - Raw-slice stabilization: the decode is keyed on the DECLARED slice of
+ *   the raw source, not on Next's object reference — a URL change that only
+ *   touches keys the route doesn't own (`?utm_source=` churn) returns the
+ *   previous result by identity, without re-decoding. Next still re-renders
+ *   every subscriber on any URL change (it owns the subscription; selectors
+ *   stabilize slices, they cannot skip renders); this layer makes that
+ *   render cheap and downstream-invisible.
+ * - Selection: every hook takes an optional `{ select }` that projects the
+ *   decoded value, with result-equality checking (`Object.is`,
  *   `equality: "shallow"` opt-in) so an unchanged selection keeps its
  *   previous reference when OTHER params change.
  *
- * Both layers are render-phase ref caches (SEL8) — the one sanctioned
- * departure from the pure-`useMemo` discipline these hooks previously held.
+ * Both layers are render-phase ref caches — the one sanctioned departure
+ * from the pure-`useMemo` discipline these hooks previously held.
  *
  * Two surfaces per half, mirroring core's server `parse` vs `safeParse`:
  * - `useSearch` / `useRouteParams` return the `SafeResult` union
- *   (discriminated on `status`, PR12) — a user editing the URL never crashes
- *   the component. The selector runs on the success arm only (SEL2).
+ *   (discriminated on `status`) — a user editing the URL never crashes the
+ *   component. The selector runs on the success arm only.
  * - `useSearchOrThrow` / `useRouteParamsOrThrow` throw the decode error in
  *   render, to the nearest client error boundary.
  *
  * Both read the route's blessed-internal `~search` / `~params` via the core
- * decoders (design-03 RL6 — `@paramour/next` is a sanctioned consumer).
+ * decoders — `@paramour/next` is a sanctioned consumer of those internals.
  *
- * Every hook is gated to `AnyAppRoute` (design-06 PR3): a pages-branded route
- * at one of these call sites is a compile error, not a runtime surprise —
- * these hooks read Next's App-Router navigation hooks, whose pages twin has
- * different state cardinality (`@paramour-js/next/pages`).
+ * 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
+ * read Next's App-Router navigation hooks, whose pages twin has different
+ * state cardinality (`@paramour-js/next/pages`).
  *
- * Devtools instrumentation (design-12): each hook reports through the shared
- * emitter in observe.ts — `observe` from inside the `useStableResult`
- * compute callback, which runs exactly on a `(route, fingerprint)` cache
- * miss, so the SEL4 fingerprint layer IS the decode-change dedup (DT4;
- * StrictMode's dev double render reuses the ref cache and cannot
- * double-emit), and `refresh` after the stable result returns, re-emitting
- * the CACHED result when the pathname moved under an unchanged decode so
- * the seam's `navigate`/`pathname` never go stale (DT8). Observations carry
- * the full pre-`select` result (DT12), and the `OrThrow` hooks report the
- * error observation BEFORE rethrowing — only render-phase can, since an
- * effect never runs for a throwing render. Every emit sits behind
- * `process.env.NODE_ENV !== "production"`, which bundlers constant-fold and
- * erase along with the seam module (DT6); the spec each hook hands the
- * emitter is built behind the same literal guard, so prod allocates
- * nothing. `useRouter` and `usePathname` are called unconditionally in
- * every hook (rules of hooks — a build-constant-guarded call would make
- * hook order differ between dev and prod bundles); their cost is a
- * referentially-stable context read each, and only the dev-only spec
- * captures them. The `navigate` capability receives the panel's SEARCH
+ * Devtools instrumentation: each hook reports through the shared emitter in
+ * observe.ts — `observe` from inside the `useStableResult` compute callback,
+ * which runs exactly on a `(route, fingerprint)` cache miss, so the
+ * fingerprint layer IS the decode-change dedup (StrictMode's dev double
+ * render reuses the ref cache and cannot double-emit), and `refresh` after
+ * the stable result returns, re-emitting the CACHED result when the pathname
+ * moved under an unchanged decode so the seam's `navigate`/`pathname` never
+ * go stale. Observations carry the full pre-`select` result, and the
+ * `OrThrow` hooks report the error observation BEFORE rethrowing — only
+ * render-phase can, since an effect never runs for a throwing render. Every
+ * emit sits behind `process.env.NODE_ENV !== "production"`, which bundlers
+ * constant-fold and erase along with the seam module; the spec each hook
+ * hands the emitter is built behind the same literal guard, so prod
+ * allocates nothing. `useRouter` and `usePathname` are called
+ * unconditionally in every hook (rules of hooks — a build-constant-guarded
+ * call would make hook order differ between dev and prod bundles); their
+ * cost is a referentially-stable context read each, and only the dev-only
+ * spec captures them. The `navigate` capability receives the panel's SEARCH
  * STRING only and resolves it against `usePathname()` — basePath-/locale-
- * relative, exactly what `router.replace` expects back (DT8; the live hash
- * is preserved at call time).
+ * relative, exactly what `router.replace` expects back (the live hash is
+ * preserved at call time).
  */
 /**
- * Decoded route params as a `SafeResult` (discriminated on `status`, PR12),
- * optionally projected through `options.select` (design-07 SEL1/SEL2).
+ * Decoded route params as a `SafeResult` (discriminated on `status`),
+ * optionally projected through `options.select`.
  *
  * `useParams()` returns `null` outside an App-Router tree — including the
  * initial render of every pages-router page in a hybrid app — so a `null`
@@ -76,7 +75,7 @@ export declare function useRouteParams<R extends AnyAppRoute, U>(route: R, optio
 /**
  * Decoded route params, or a thrown {@link ParamsDecodeError} (→ nearest
  * client error boundary) on a malformed URL. Optionally projected through
- * `options.select` (design-07 SEL1/SEL2).
+ * `options.select`.
  *
  * A `null` `useParams()` (outside an App-Router tree, e.g. a hybrid app's
  * pages-router initial render) degrades to `{}` so required params throw the
@@ -85,15 +84,15 @@ export declare function useRouteParams<R extends AnyAppRoute, U>(route: R, optio
 export declare function useRouteParamsOrThrow<R extends AnyAppRoute>(route: R): InferRouteParams<R>;
 export declare function useRouteParamsOrThrow<R extends AnyAppRoute, U>(route: R, options: SelectOptions<InferRouteParams<R>, U>): U;
 /**
- * Decoded search params as a `SafeResult` (discriminated on `status`, PR12),
- * optionally projected through `options.select` (design-07 SEL1/SEL2).
+ * 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>;
 /**
  * Decoded search params, or a thrown {@link SearchDecodeError} (→ nearest
  * client error boundary) on a malformed URL. Optionally projected through
- * `options.select` (design-07 SEL1/SEL2).
+ * `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;

package/dist/app.js

@@ -1,13 +1,16 @@
 "use client";
 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 { AppNavigationContext, } from "./navigation-adapter.js";
 import { makeAppNavigate, useDevtoolsEmitter, } from "./observe.js";
 import { paramsFingerprint, searchParamsFingerprint, useSelectedResult, useSelectedValue, useStableResult, } from "./select.js";
 export function useRouteParams(route, options) {
-    const params = useParams() ?? {};
-    const router = useRouter();
-    const pathname = usePathname();
+    const nav = useAppNavigation();
+    const params = nav.useParams() ?? {};
+    const router = nav.useRouter();
+    const pathname = nav.usePathname();
     const emitter = useDevtoolsEmitter();
     const spec = process.env.NODE_ENV === "production"
         ? undefined
@@ -33,9 +36,10 @@ export function useRouteParams(route, options) {
     return useSelectedResult(result, options);
 }
 export function useRouteParamsOrThrow(route, options) {
-    const params = useParams() ?? {};
-    const router = useRouter();
-    const pathname = usePathname();
+    const nav = useAppNavigation();
+    const params = nav.useParams() ?? {};
+    const router = nav.useRouter();
+    const pathname = nav.usePathname();
     const emitter = useDevtoolsEmitter();
     const spec = process.env.NODE_ENV === "production"
         ? undefined
@@ -50,7 +54,7 @@ export function useRouteParamsOrThrow(route, options) {
         };
     const value = useStableResult(route, paramsFingerprint(route, params), () => {
         // The duplicated decode call across the prod/dev branches is the price
-        // of literal-zero prod cost — the bundler keeps exactly one branch (DT6).
+        // of literal-zero prod cost — the bundler keeps exactly one branch.
         if (process.env.NODE_ENV === "production") {
             return decodeParams(route, params);
         }
@@ -62,7 +66,7 @@ export function useRouteParamsOrThrow(route, options) {
             return data;
         }
         catch (error) {
-            // Report BEFORE the throw reaches the error boundary (DT4). Only the
+            // Report BEFORE the throw reaches the error boundary. Only the
             // decode-error class is observed — foreign errors are not URL facts
             // the panel explains, matching safeDecode*'s taxonomy.
             if (error instanceof ParamsDecodeError && spec !== undefined) {
@@ -77,9 +81,10 @@ export function useRouteParamsOrThrow(route, options) {
     return useSelectedValue(value, options);
 }
 export function useSearch(route, options) {
-    const searchParams = useSearchParams();
-    const router = useRouter();
-    const pathname = usePathname();
+    const nav = useAppNavigation();
+    const searchParams = nav.useSearchParams();
+    const router = nav.useRouter();
+    const pathname = nav.usePathname();
     const emitter = useDevtoolsEmitter();
     const spec = process.env.NODE_ENV === "production"
         ? undefined
@@ -105,9 +110,10 @@ export function useSearch(route, options) {
     return useSelectedResult(result, options);
 }
 export function useSearchOrThrow(route, options) {
-    const searchParams = useSearchParams();
-    const router = useRouter();
-    const pathname = usePathname();
+    const nav = useAppNavigation();
+    const searchParams = nav.useSearchParams();
+    const router = nav.useRouter();
+    const pathname = nav.usePathname();
     const emitter = useDevtoolsEmitter();
     const spec = process.env.NODE_ENV === "production"
         ? undefined
@@ -121,7 +127,7 @@ export function useSearchOrThrow(route, options) {
             wire: () => searchWireSnapshot(searchParams),
         };
     const value = useStableResult(route, searchParamsFingerprint(route, searchParams), 
-    // decodeSearch is keyed on SearchOutputOf (design-04 SS6) — the correct
+    // 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
@@ -129,22 +135,21 @@ export function useSearchOrThrow(route, options) {
     // 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
-    // literal-zero prod cost; the bundler keeps exactly one branch (DT6).
+    // literal-zero prod cost; the bundler keeps exactly one branch.
     () => {
         if (process.env.NODE_ENV === "production") {
-            return decodeSearch(route["~search"], searchParams);
+            return decodeSearch(route["~search"], searchParams, route.path);
         }
         try {
-            const data = decodeSearch(route["~search"], searchParams);
+            const data = decodeSearch(route["~search"], searchParams, route.path);
             if (spec !== undefined) {
                 emitter.observe(spec, { data, status: "success" });
             }
             return data;
         }
         catch (error) {
-            // Report BEFORE the throw reaches the error boundary (DT4); only
-            // the decode-error class is observed, matching safeDecode*'s
-            // taxonomy.
+            // Report BEFORE the throw reaches the error boundary; only the
+            // decode-error class is observed, matching safeDecode*'s taxonomy.
             if (error instanceof SearchDecodeError && spec !== undefined) {
                 emitter.observe(spec, { error, status: "error" });
             }
@@ -156,3 +161,25 @@ export function useSearchOrThrow(route, options) {
     }
     return useSelectedValue(value, options);
 }
+/**
+ * Real-Next fallback for the adapter seam: the /testing provider overrides
+ * these reads through {@link AppNavigationContext}; with
+ * no provider mounted the context's `null` default resolves here, so
+ * production behavior (and this module's `next/navigation`-only bundle
+ * graph, per dist.test.ts) is unchanged.
+ */
+const realAppAdapter = {
+    useParams,
+    usePathname,
+    useRouter,
+    useSearchParams,
+};
+/**
+ * Every hook resolves the adapter ONCE at its top and calls the adapter's
+ * reads unconditionally, exactly where the direct Next calls previously sat
+ * — hook call order is identical across renders and across provider
+ * presence.
+ */
+function useAppNavigation() {
+    return useContext(AppNavigationContext) ?? realAppAdapter;
+}

package/dist/cli-args.d.ts

@@ -15,10 +15,10 @@ type ParsedValues<T extends ParseArgsOptionsConfig> = ReturnType<typeof parseArg
     options: T;
 }>>["values"];
 /**
- * The shared command prologue (TR7): parse flags, print usage on a parse
- * error (exit 2) or `--help` (exit 0), and reject positionals — no command
- * takes one. Callers branch on `"exit" in result`; anything past the
- * prologue (mode merging, flag exclusivity) stays per-command.
+ * The shared command prologue: parse flags, print usage on a parse error
+ * (exit 2) or `--help` (exit 0), and reject positionals — no command takes
+ * one. Callers branch on `"exit" in result`; anything past the prologue
+ * (mode merging, flag exclusivity) stays per-command.
  */
 export declare function parseCommandFlags<const T extends HelpOption & ParseArgsOptionsConfig>(argv: readonly string[], options: T, usage: string, { stderr, stdout }: ResolvedIo): {
     exit: 0 | 2;

package/dist/cli-args.js

@@ -1,10 +1,10 @@
 import { parseArgs } from "node:util";
 import { message } from "./cli-io.js";
 /**
- * The shared command prologue (TR7): parse flags, print usage on a parse
- * error (exit 2) or `--help` (exit 0), and reject positionals — no command
- * takes one. Callers branch on `"exit" in result`; anything past the
- * prologue (mode merging, flag exclusivity) stays per-command.
+ * The shared command prologue: parse flags, print usage on a parse error
+ * (exit 2) or `--help` (exit 0), and reject positionals — no command takes
+ * one. Callers branch on `"exit" in result`; anything past the prologue
+ * (mode merging, flag exclusivity) stays per-command.
  */
 export function parseCommandFlags(argv, options, usage, { stderr, stdout }) {
     let parsed;

package/dist/cli-inputs.d.ts

@@ -18,13 +18,12 @@ export interface InputFlags {
 export declare class NoRouteDirsError extends Error {
 }
 /**
- * Precedence lives in exactly this function (TR7 / §7.2): flags → config
- * file → joint discovery (PR8). Paths resolve against the project root
- * (= cwd, where `next` itself would run). Discovery only runs for dirs not
- * explicitly given — passing both bypasses it (and its populated-ignored-dir
- * config error) entirely, which is the documented escape hatch. Only when
- * NEITHER dir exists is that an error (PR8): app-only and pages-only
- * projects are both fine.
+ * Precedence lives in exactly this function: flags → config file → joint
+ * discovery. Paths resolve against the project root (= cwd, where `next`
+ * itself would run). Discovery only runs for dirs not explicitly given —
+ * passing both bypasses it (and its populated-ignored-dir config error)
+ * entirely, which is the documented escape hatch. Only when NEITHER dir
+ * 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.

package/dist/cli-inputs.js

@@ -12,13 +12,12 @@ import { resolveRouteDirs } from "./scan.js";
 export class NoRouteDirsError extends Error {
 }
 /**
- * Precedence lives in exactly this function (TR7 / §7.2): flags → config
- * file → joint discovery (PR8). Paths resolve against the project root
- * (= cwd, where `next` itself would run). Discovery only runs for dirs not
- * explicitly given — passing both bypasses it (and its populated-ignored-dir
- * config error) entirely, which is the documented escape hatch. Only when
- * NEITHER dir exists is that an error (PR8): app-only and pages-only
- * projects are both fine.
+ * Precedence lives in exactly this function: flags → config file → joint
+ * discovery. Paths resolve against the project root (= cwd, where `next`
+ * itself would run). Discovery only runs for dirs not explicitly given —
+ * passing both bypasses it (and its populated-ignored-dir config error)
+ * entirely, which is the documented escape hatch. Only when NEITHER dir
+ * 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.

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
 import { runCli } from "./run-cli.js";
-// The bin entry (TR7): all logic lives in run-cli.ts so tests never execute
+// The bin entry: all logic lives in run-cli.ts so tests never execute
 // this statement. exitCode, not exit() — pending stdio writes must flush.
 process.exitCode = await runCli(process.argv.slice(2));

package/dist/collisions.d.ts

@@ -1,21 +1,21 @@
-/** A scanned route path labeled with the router that produced it (PR9). */
+/** A scanned route path labeled with the router that produced it. */
 export interface ScannedRoute {
     path: string;
     router: "app" | "pages";
 }
 /**
- * Route-collision failure mode (PR9): states Next itself refuses to build
- * have no valid artifact, so the scanners throw instead of emitting one.
- * Composition points map this error to their ruled exits — CLI exit 2,
- * `withTypedRoutes` throw during config evaluation, and a non-fatal loud
- * log under watch (the TR5 exception: a collision mid-`--watch` is usually
- * a file mid-move, so the last good artifact stays on disk).
+ * Route-collision failure mode: states Next itself refuses to build have no
+ * valid artifact, so the scanners throw instead of emitting one. Composition
+ * points map this error to their own exits — CLI exit 2, `withTypedRoutes`
+ * throw during config evaluation, and a non-fatal loud log under watch (a
+ * 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;
 }
 /**
- * PR9's structural collisions — same detection pass, non-equal strings. Two
+ * Structural collisions — same detection pass, non-equal strings. Two
  * states Next also refuses to build that plain string equality misses:
  *
  * - **Different slug names at one level**: `/x/[id]` + `/x/[slug]` — Next:

package/dist/collisions.js

@@ -1,10 +1,10 @@
 /**
- * Route-collision failure mode (PR9): states Next itself refuses to build
- * have no valid artifact, so the scanners throw instead of emitting one.
- * Composition points map this error to their ruled exits — CLI exit 2,
- * `withTypedRoutes` throw during config evaluation, and a non-fatal loud
- * log under watch (the TR5 exception: a collision mid-`--watch` is usually
- * a file mid-move, so the last good artifact stays on disk).
+ * Route-collision failure mode: states Next itself refuses to build have no
+ * valid artifact, so the scanners throw instead of emitting one. Composition
+ * points map this error to their own exits — CLI exit 2, `withTypedRoutes`
+ * throw during config evaluation, and a non-fatal loud log under watch (a
+ * collision mid-`--watch` is usually a file mid-move, so the last good
+ * artifact stays on disk).
  */
 export class RouteCollisionError extends Error {
     name = "RouteCollisionError";
@@ -22,7 +22,7 @@ const OPTIONAL_CATCH_ALL = /^\[\[\.\.\..+\]\]$/;
  */
 const DYNAMIC_SEGMENT = /^(?:\[\[\.\.\.(?<optional>.+)\]\]|\[\.\.\.(?<catchAll>.+)\]|\[(?<plain>[^[\]]+)\])$/;
 /**
- * PR9's structural collisions — same detection pass, non-equal strings. Two
+ * Structural collisions — same detection pass, non-equal strings. Two
  * states Next also refuses to build that plain string equality misses:
  *
  * - **Different slug names at one level**: `/x/[id]` + `/x/[slug]` — Next:
@@ -56,7 +56,7 @@ export function assertNoStructuralCollisions(routes) {
             const key = `${segments.slice(0, index).join("/")}#${String(index)}#${kind}`;
             const existing = dynamicAt.get(key);
             if (existing !== undefined && existing.segment !== segment) {
-                throw new RouteCollisionError(`route collision: "${existing.path}" (${existing.router}) and "${route.path}" (${route.router}) declare conflicting dynamic segments (${existing.segment} vs ${segment}) at the same position — Next refuses different slug names for the same dynamic path (PR9)`);
+                throw new RouteCollisionError(`route collision: "${existing.path}" (${existing.router}) and "${route.path}" (${route.router}) declare conflicting dynamic segments (${existing.segment} vs ${segment}) at the same position — Next refuses different slug names for the same dynamic path`);
             }
             if (existing === undefined) {
                 dynamicAt.set(key, { ...route, segment });
@@ -67,7 +67,7 @@ export function assertNoStructuralCollisions(routes) {
             const base = segments.length === 1 ? "/" : `/${segments.slice(0, -1).join("/")}`;
             const baseRoute = byPath.get(base);
             if (baseRoute !== undefined) {
-                throw new RouteCollisionError(`route collision: "${route.path}" (${route.router}) also matches "${base}" (${baseRoute.router}) — an optional catch-all has the same specificity as its base path, which Next refuses to build (PR9)`);
+                throw new RouteCollisionError(`route collision: "${route.path}" (${route.router}) also matches "${base}" (${baseRoute.router}) — an optional catch-all has the same specificity as its base path, which Next refuses to build`);
             }
         }
     }

package/dist/commands/generate.d.ts

@@ -1,11 +1,11 @@
 import { type CliIo } from "../cli-io.js";
 /**
- * @internal `paramour generate` and its `check` alias (TR7), in-process
- * testable: returns the exit code instead of exiting. Codes are grep-style
- * so CI can tell drift from breakage: 0 success, 1 check-drift ONLY, 2
- * usage/config/operational errors — route collisions included (PR9: Next
- * itself fails that build, so there is no artifact to emit). Unlike the
- * wrapper's never-load-bearing stance (§7.3), the CLI fails loudly —
- * running it is explicit user intent.
+ * @internal `paramour generate` and its `check` alias, in-process testable:
+ * returns the exit code instead of exiting. Codes are grep-style so CI can
+ * tell drift from breakage: 0 success, 1 check-drift ONLY, 2
+ * usage/config/operational errors — route collisions included (Next itself
+ * fails that build, so there is no artifact to emit). Unlike the wrapper,
+ * which is never load-bearing, the CLI fails loudly — running it is explicit
+ * user intent.
  */
 export declare function runGenerate(argv: readonly string[], io: CliIo, mode: "check" | "generate"): Promise<number>;

package/dist/commands/generate.js

@@ -38,13 +38,13 @@ const CHECK_USAGE = [
     ...SHARED_OPTION_LINES,
 ].join("\n");
 /**
- * @internal `paramour generate` and its `check` alias (TR7), in-process
- * testable: returns the exit code instead of exiting. Codes are grep-style
- * so CI can tell drift from breakage: 0 success, 1 check-drift ONLY, 2
- * usage/config/operational errors — route collisions included (PR9: Next
- * itself fails that build, so there is no artifact to emit). Unlike the
- * wrapper's never-load-bearing stance (§7.3), the CLI fails loudly —
- * running it is explicit user intent.
+ * @internal `paramour generate` and its `check` alias, in-process testable:
+ * returns the exit code instead of exiting. Codes are grep-style so CI can
+ * tell drift from breakage: 0 success, 1 check-drift ONLY, 2
+ * usage/config/operational errors — route collisions included (Next itself
+ * fails that build, so there is no artifact to emit). Unlike the wrapper,
+ * which is never load-bearing, the CLI fails loudly — running it is explicit
+ * user intent.
  */
 export async function runGenerate(argv, io, mode) {
     const { stderr, stdout } = resolveIo(io);
@@ -105,7 +105,7 @@ function describeRoutes(result) {
     ];
     return parts.length === 0 ? "0 routes" : parts.join(", ");
 }
-/** `--check` (TR7): exit 1 on any drift, including a missing artifact. */
+/** `--check`: exit 1 on any drift, including a missing artifact. */
 function runCheck(inputs, stdout, stderr) {
     let result;
     try {
@@ -132,7 +132,7 @@ function runCheck(inputs, stdout, stderr) {
     stderr("Run `paramour generate` and commit the result.");
     return 1;
 }
-/** One-shot `paramour generate` (TR7). */
+/** One-shot `paramour generate`. */
 function runOnce(inputs, stdout, stderr) {
     let result;
     try {
@@ -149,8 +149,8 @@ function runOnce(inputs, stdout, stderr) {
     return 0;
 }
 /**
- * `--watch` (TR7): TR5 watcher behind the TR6 lock, over both route dirs
- * (PR8). A declined lock exits 0 — another live watcher (usually `next dev`)
+ * `--watch`: the watcher behind the cross-process lock, over both route
+ * dirs. A declined lock exits 0 — another live watcher (usually `next dev`)
  * is the designed dedupe case, and the initial generation already ran.
  * Without an abort signal the returned promise stays pending; the process
  * lives via the FSWatcher refs and dies with the standard signal exits
@@ -172,7 +172,7 @@ function runWatch(inputs, projectRoot, io, stdout, stderr) {
     }
     catch (error) {
         // A corrupt lock location (e.g. a directory at the pidfile path) is an
-        // operational error, not a crash: exit 2 like every other one (TR7).
+        // operational error, not a crash: exit 2 like every other one.
         stderr(`paramour: ${message(error)}`);
         return 2;
     }
@@ -196,13 +196,13 @@ function runWatch(inputs, projectRoot, io, stdout, stderr) {
             }
             catch (error) {
                 if (error instanceof RouteCollisionError) {
-                    // PR9's watch exception: a collision mid-watch is usually a file
-                    // mid-move — log loudly every time, keep the last good artifact
-                    // on disk, keep running (TR5).
+                    // The collision watch exception: a collision mid-watch is usually
+                    // a file mid-move — log loudly every time, keep the last good
+                    // artifact on disk, keep running.
                     stderr(`paramour: ${message(error)}; keeping the last good artifact and watching for the fix`);
                     return;
                 }
-                throw error; // routed to onError by the watcher (TR5 non-fatal)
+                throw error; // routed to onError by the watcher — non-fatal
             }
         },
     });

package/dist/commands/init.js

@@ -67,7 +67,7 @@ export async function runInit(argv, io) {
         }
         else {
             // A .mjs/.json left behind would be shadowed by the scaffold under the
-            // ts-first discovery order (§7.2) — --force must truly replace it.
+            // ts-first discovery order — --force must truly replace it.
             if (existing !== undefined && existing !== "paramour.config.ts" && !dry) {
                 unlinkSync(join(projectRoot, existing));
             }

package/dist/config.d.ts

@@ -1,16 +1,16 @@
 /**
- * Shape of `paramour.config.{ts,mjs,json}` (§7.2 / TR7) — 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}` — 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.
  */
 export interface ParamourConfig {
-    /** App dir, relative to the project root; default: joint discovery (PR8). */
+    /** App dir, relative to the project root; default: joint discovery. */
     appDir?: string;
-    /** Artifact path, relative to the project root (TR3 escape hatch). */
+    /** Artifact path, relative to the project root — the escape hatch. */
     outFile?: string;
     /** Page extensions, no leading dot; default: Next's four. */
     pageExtensions?: string[];
-    /** Pages dir, relative to the project root; default: joint discovery (PR8). */
+    /** Pages dir, relative to the project root; default: joint discovery. */
     pagesDir?: string;
     /**
      * Globs (relative to the project root) of modules exporting route
@@ -20,14 +20,14 @@ export interface ParamourConfig {
      */
     routeFiles?: string[];
 }
-/** @internal Discovery order at the project root (TR7) — first match wins. */
+/** @internal Discovery order at the project root — first match wins. */
 export declare const CONFIG_FILE_NAMES: readonly ["paramour.config.ts", "paramour.config.mjs", "paramour.config.json"];
 /**
  * @internal Load and validate the project's config file, or `undefined`
  * when none exists. No upward traversal — the documented contract is three
- * filenames at the project root (TR7). jiti (the §7.2 loader carry-over) is
- * imported dynamically so only CLI runs that actually have a `.ts`/`.mjs`
- * config pay for it; `withTypedRoutes` users never execute it.
+ * filenames at the project root. jiti is imported dynamically so only CLI
+ * runs that actually have a `.ts`/`.mjs` config pay for it;
+ * `withTypedRoutes` users never execute it.
  */
 export declare function loadConfigFile(projectRoot: string): Promise<undefined | {
     config: ParamourConfig;

package/dist/config.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-/** @internal Discovery order at the project root (TR7) — first match wins. */
+/** @internal Discovery order at the project root — first match wins. */
 export const CONFIG_FILE_NAMES = [
     "paramour.config.ts",
     "paramour.config.mjs",
@@ -9,9 +9,9 @@ export const CONFIG_FILE_NAMES = [
 /**
  * @internal Load and validate the project's config file, or `undefined`
  * when none exists. No upward traversal — the documented contract is three
- * filenames at the project root (TR7). jiti (the §7.2 loader carry-over) is
- * imported dynamically so only CLI runs that actually have a `.ts`/`.mjs`
- * config pay for it; `withTypedRoutes` users never execute it.
+ * filenames at the project root. jiti is imported dynamically so only CLI
+ * runs that actually have a `.ts`/`.mjs` config pay for it;
+ * `withTypedRoutes` users never execute it.
  */
 export async function loadConfigFile(projectRoot) {
     for (const name of CONFIG_FILE_NAMES) {