@paramour-js/next 0.3.1 → 0.4.1

package/dist/devtools-seam.d.ts

@@ -1,6 +1,6 @@
 import type { AnyRoute, ParamsSource, RouterKind, SafeResult } from "paramour";
 /**
- * The devtools observation seam (design-12 DT5): a dependency-free global
+ * The devtools observation seam: a dependency-free global
  * slot the hooks push decode observations into and the devtools panel
  * (`@paramour-js/devtools`) reads out of. This module's JSDoc is the
  * CONTRACT OF RECORD for the slot — the panel never imports runtime code
@@ -10,7 +10,7 @@ import type { AnyRoute, ParamsSource, RouterKind, SafeResult } from "paramour";
  *
  * - Slot key: `Symbol.for("paramour.devtools.seam")` — the realm-global
  *   symbol registry, the same cross-copy identity idiom as core's error
- *   brands (RL6): a second physical copy of this module (dual-package
+ *   brands: a second physical copy of this module (dual-package
  *   hazard, bundler duplication) mints the SAME symbol and lands on the
  *   same slot. Either side — hooks or panel — may create the slot; both
  *   sides are create-if-absent.
@@ -24,14 +24,14 @@ import type { AnyRoute, ParamsSource, RouterKind, SafeResult } from "paramour";
  *   `add` — same JS thread, so nothing can be emitted between the read and
  *   the add. Emitters push to `buffer` (FIFO-capped at
  *   {@link OBSERVATION_BUFFER_CAP}) and then invoke every listener.
- * - Production (DT6): every emit call site sits behind
+ * - 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.
  */
-/** The `Symbol.for("paramour.devtools.seam")` slot shape — the DT5 contract. */
+/** The `Symbol.for("paramour.devtools.seam")` slot shape — the seam contract. */
 export interface ParamourDevtoolsSeam {
     /** Capped FIFO; oldest dropped past the cap. Replay = read it. */
     readonly buffer: ParamourObservation[];
@@ -43,12 +43,12 @@ export interface ParamourDevtoolsSeam {
      */
     readonly version: 1;
 }
-/** Discriminant naming which hook reported (design-12 DT4). */
+/** Discriminant naming which hook reported. */
 export type ParamourHookId = "app.useRouteParams" | "app.useRouteParamsOrThrow" | "app.useSearch" | "app.useSearchOrThrow" | "pages.useRouteParams" | "pages.useSearch";
 /**
- * Navigation capability captured from the EMITTING hook's router (design-12
- * DT8): the panel commits URL edits through this, so it never guesses which
- * router is live and never imports Next. The panel passes ONLY the
+ * Navigation capability captured from the EMITTING hook's router: the panel
+ * commits URL edits through this, so it never guesses which router is live
+ * and never imports Next. The panel passes ONLY the
  * serialized search string (`""` or `"?…"`); the hook resolves it against
  * its OWN current pathname — `usePathname()` (App) / `asPath`'s path part
  * (Pages), both basePath-/locale-relative, which is what `replace()`
@@ -60,18 +60,18 @@ export type ParamourHookId = "app.useRouteParams" | "app.useRouteParamsOrThrow"
  */
 export type ParamourNavigate = (search: string) => void;
 /**
- * One hook decode, reported on decode CHANGE (design-12 DT4) — and
+ * One hook decode, reported on decode CHANGE — and
  * re-reported when the hook's resolution base moves under an unchanged
  * decode (a layout surviving `/product/1?q=a` → `/product/2?q=a`), so the
  * captured `navigate`/`pathname` never go stale while the hook is mounted.
  */
 export type ParamourObservation = ParamourParamsObservation | ParamourSearchObservation;
 /**
- * Pre-`select` decode result (design-12 DT12): 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 (DT11). Generic-erased on purpose: the panel
- * treats `data` structurally.
+ * 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";
@@ -84,7 +84,7 @@ export interface ParamourParamsObservation extends ParamourObservationBase {
 /**
  * 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 (DT8).
+ * losslessly into the panel's raw-wire editing.
  */
 export interface ParamourSearchObservation extends ParamourObservationBase {
     readonly kind: "search";
@@ -106,7 +106,7 @@ interface ParamourObservationBase {
     readonly pathname: string;
     readonly result: ParamourObservationResult;
     /**
-     * The LIVE route object (DT5: same JS context, no serialization) — the
+     * The LIVE route object (same JS context, no serialization) — the
      * panel calls `describeRoute`, the route's own codecs, and
      * `buildSearchString` on it directly.
      */
@@ -115,7 +115,7 @@ interface ParamourObservationBase {
 }
 /**
  * 128: replay only needs the pre-panel-mount window. One observation per
- * decode CHANGE per hook (DT4) means even a long pre-open session is dozens
+ * 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.
@@ -123,8 +123,8 @@ interface ParamourObservationBase {
 export declare const OBSERVATION_BUFFER_CAP = 128;
 /**
  * Pushes one observation and notifies listeners. The internal production
- * early-return is belt-and-suspenders under DT6 (every call site is ALSO
- * guarded, which is what the bundler erases); it makes the guard directly
+ * 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;

package/dist/devtools-seam.js

@@ -1,6 +1,6 @@
 /**
  * 128: replay only needs the pre-panel-mount window. One observation per
- * decode CHANGE per hook (DT4) means even a long pre-open session is dozens
+ * 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.
@@ -10,8 +10,8 @@ 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 under DT6 (every call site is ALSO
- * guarded, which is what the bundler erases); it makes the guard directly
+ * 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) {

package/dist/doctor/checks.js

@@ -34,7 +34,7 @@ export async function runDoctorChecks(projectRoot) {
             status: "fail",
         });
     }
-    // 2. Route directories resolve (PR8 discovery, config dirs honored).
+    // 2. Route directories resolve (joint discovery, config dirs honored).
     let inputs;
     try {
         inputs = await resolveInputs({}, projectRoot, config);

package/dist/emit.d.ts

@@ -2,34 +2,34 @@
 export interface WriteIfChangedResult {
     /**
      * Prior file content, or `null` when the file did not exist — the input
-     * for TR4's drift warning (which paths appeared/disappeared).
+     * for the drift warning (which paths appeared/disappeared).
      */
     previousContent: null | string;
     /**
-     * `false` on a byte-identical no-op — the signal `--check` (TR7) and the
-     * watch loop (TR5) hang off.
+     * `false` on a byte-identical no-op — the signal `--check` and the watch
+     * loop hang off.
      */
     written: boolean;
 }
-/** Input of {@link emitArtifact} — one union per router (PR9). */
+/** Input of {@link emitArtifact} — one union per router. */
 export interface EmitRoutes {
     appRoutes: readonly string[];
     pagesRoutes: readonly string[];
 }
 /**
- * Artifact text for the per-router route unions (TR3/PR9): deterministic —
- * sorted, deduped, LF-only, trailing newline, no timestamps. Sorting/deduping
+ * Artifact text for the per-router route unions: deterministic — sorted,
+ * deduped, LF-only, trailing newline, no timestamps. Sorting/deduping
  * happens here as well as in the scanner so byte-identity never depends on
  * who the caller was. Always the leading-pipe multiline union form, even for
  * one path — one shape, no count-dependent formatting. An empty union omits
- * its member entirely (TR3's absent-not-`never` rule, applied per router in
- * PR9): a pages-only project keeps world-A's permissive `string` fallback
- * for `defineAppRoute`, and vice versa.
+ * its member entirely (absent, not `never`, applied per router): a
+ * pages-only project keeps world-A's permissive `string` fallback for
+ * `defineAppRoute`, and vice versa.
  */
 export declare function emitArtifact(routes: EmitRoutes): string;
 /**
- * Compare-before-write (TR3): a no-op regeneration must not touch the file —
- * that property is what prevents TS-server churn, watch-loop feedback, and
- * concurrent-generator races (TR6).
+ * Compare-before-write: a no-op regeneration must not touch the file — that
+ * property is what prevents TS-server churn, watch-loop feedback, and
+ * concurrent-generator races.
  */
 export declare function writeIfChanged(filePath: string, content: string): WriteIfChangedResult;

package/dist/emit.js

@@ -2,14 +2,14 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 const HEADER = "// Generated by @paramour-js/next. Do not edit — regenerate with `paramour generate`.";
 /**
- * Artifact text for the per-router route unions (TR3/PR9): deterministic —
- * sorted, deduped, LF-only, trailing newline, no timestamps. Sorting/deduping
+ * Artifact text for the per-router route unions: deterministic — sorted,
+ * deduped, LF-only, trailing newline, no timestamps. Sorting/deduping
  * happens here as well as in the scanner so byte-identity never depends on
  * who the caller was. Always the leading-pipe multiline union form, even for
  * one path — one shape, no count-dependent formatting. An empty union omits
- * its member entirely (TR3's absent-not-`never` rule, applied per router in
- * PR9): a pages-only project keeps world-A's permissive `string` fallback
- * for `defineAppRoute`, and vice versa.
+ * its member entirely (absent, not `never`, applied per router): a
+ * pages-only project keeps world-A's permissive `string` fallback for
+ * `defineAppRoute`, and vice versa.
  */
 export function emitArtifact(routes) {
     const members = ["appRoutes", "pagesRoutes"].flatMap((member) => {
@@ -21,22 +21,22 @@ export function emitArtifact(routes) {
         // contain a quote or backslash (Linux/macOS), which unescaped would emit
         // invalid TS or silently declare the wrong route. JSON string escaping is
         // a subset of TS string-literal escaping (output stays valid TS) and is
-        // deterministic, so TR3's byte-identity guarantee holds.
+        // deterministic, so the byte-identity guarantee holds.
         return [
             `    ${member}:`,
             `${sorted.map((path) => `      | ${JSON.stringify(path)}`).join("\n")};`,
         ];
     });
     if (members.length === 0) {
-        // TR3: no routes yet → NO members (explicitly not `never`, which would
+        // No routes yet → NO members (explicitly not `never`, which would
         // make every route-constructor call an error). The empty merge keeps
-        // the documented world-A `string` fallback (RL8).
+        // the documented world-A `string` fallback.
         return [
             HEADER,
             'import "paramour";',
             "",
             'declare module "paramour" {',
-            "  // TR3: empty merge — no routes discovered yet; the pre-generation",
+            "  // Empty merge — no routes discovered yet; the pre-generation",
             "  // `string` fallback stays in effect.",
             "  // eslint-disable-next-line @typescript-eslint/no-empty-object-type",
             "  interface ParamourRegister {}",
@@ -57,9 +57,9 @@ export function emitArtifact(routes) {
     ].join("\n");
 }
 /**
- * Compare-before-write (TR3): a no-op regeneration must not touch the file —
- * that property is what prevents TS-server churn, watch-loop feedback, and
- * concurrent-generator races (TR6).
+ * Compare-before-write: a no-op regeneration must not touch the file — that
+ * property is what prevents TS-server churn, watch-loop feedback, and
+ * concurrent-generator races.
  */
 export function writeIfChanged(filePath, content) {
     const previousContent = existsSync(filePath)
@@ -67,7 +67,7 @@ export function writeIfChanged(filePath, content) {
         : null;
     if (previousContent === content)
         return { previousContent, written: false };
-    // TR3's outFile escape hatch may point into a not-yet-existing directory.
+    // The outFile escape hatch may point into a not-yet-existing directory.
     mkdirSync(dirname(filePath), { recursive: true });
     writeFileSync(filePath, content);
     return { previousContent, written: true };

package/dist/generate.d.ts

@@ -1,11 +1,11 @@
 /**
- * The shared generation engine (TR9): `withTypedRoutes` and the CLI drive
- * these same functions, so wrapper and `paramour generate` cannot drift on
- * what a pass produces. Everything here is @internal — not barrel API.
+ * The shared generation engine: `withTypedRoutes` and the CLI drive these
+ * same functions, so wrapper and `paramour generate` cannot drift on what a
+ * pass produces. Everything here is @internal — not barrel API.
  */
 /** Result of {@link checkArtifact}. */
 export interface CheckResult {
-    /** App-router drift — split per router so the report names it (PR9). */
+    /** App-router drift — split per router so the report names it. */
     app: RouterDrift;
     /** `true` when the artifact file does not exist at all. */
     missingFile: boolean;
@@ -14,7 +14,7 @@ export interface CheckResult {
     /** `true` on a byte-identical artifact — the only non-drift state. */
     upToDate: boolean;
 }
-/** Inputs to one generation/check pass; either dir may be absent (PR1). */
+/** Inputs to one generation/check pass; either dir may be absent. */
 export interface GenerateInputs {
     appDir?: string | undefined;
     artifactPath: string;
@@ -29,10 +29,10 @@ export interface GenerateResult {
     pagesRoutes: string[];
     /** Prior artifact content, `null` when the file did not exist. */
     previousContent: null | string;
-    /** `false` on a byte-identical no-op (TR3 write-if-changed). */
+    /** `false` on a byte-identical no-op (write-if-changed). */
     written: boolean;
 }
-/** One router's appeared/disappeared route paths (TR4/TR7 drift). */
+/** One router's appeared/disappeared route paths. */
 export interface RouterDrift {
     /** Routes on disk (scan) that the artifact lacks. */
     appeared: string[];
@@ -40,25 +40,25 @@ export interface RouterDrift {
     disappeared: string[];
 }
 /**
- * `--check` (TR7): scan to memory and byte-compare against disk — never
- * writes. A missing artifact is drift, not an error: that is exactly the
- * CI-degrades-to-world-A case the committed file exists to prevent (TR3).
+ * `--check`: scan to memory and byte-compare against disk — never writes. A
+ * missing artifact is drift, not an error: that is exactly the
+ * CI-degrades-to-world-A case the committed file exists to prevent.
  */
 export declare function checkArtifact(inputs: GenerateInputs): CheckResult;
 /**
  * Per-router drift of a completed {@link generate} pass against the artifact
- * it replaced — the wrapper's build-phase drift report (TR4).
+ * it replaced — the wrapper's build-phase drift report.
  */
 export declare function diffGenerated(result: GenerateResult): {
     app: RouterDrift;
     pages: RouterDrift;
 };
 /**
- * The `  + /new (app)` / `  - /old (pages)` lines of a drift report
- * (TR4/TR7) — each line names the router its path moved in (PR9).
+ * The `  + /new (app)` / `  - /old (pages)` lines of a drift report — each
+ * line names the router its path moved in.
  */
 export declare function formatRouteDiff(app: RouterDrift, pages: RouterDrift): string[];
-/** One generation pass: scan → emit → write-if-changed (TR3). */
+/** One generation pass: scan → emit → write-if-changed. */
 export declare function generate(inputs: GenerateInputs): GenerateResult;
 /**
  * Per-router route paths in a previously emitted artifact; both empty for a

package/dist/generate.js

@@ -3,17 +3,17 @@ import { emitArtifact, writeIfChanged } from "./emit.js";
 import { scanRoutes } from "./scan.js";
 /**
  * Reads the per-router unions back out of a previously emitted artifact for
- * drift diffs (TR4/TR7). Only ever applied to text this package generated
- * (TR3 deterministic form), so line-anchored matches on the member headers
- * and union members are exact, not heuristic. `\s*$` on both tolerates a
+ * drift diffs. Only ever applied to text this package generated (its
+ * deterministic form), so line-anchored matches on the member headers and
+ * union members are exact, not heuristic. `\s*$` on both tolerates a
  * CRLF-resaved artifact.
  */
 const MEMBER_HEADER = /^\s*(appRoutes|pagesRoutes):\s*$/;
 const UNION_MEMBER = /^\s*\| "(.*)";?\s*$/;
 /**
- * `--check` (TR7): scan to memory and byte-compare against disk — never
- * writes. A missing artifact is drift, not an error: that is exactly the
- * CI-degrades-to-world-A case the committed file exists to prevent (TR3).
+ * `--check`: scan to memory and byte-compare against disk — never writes. A
+ * missing artifact is drift, not an error: that is exactly the
+ * CI-degrades-to-world-A case the committed file exists to prevent.
  */
 export function checkArtifact(inputs) {
     const routes = scanRoutes(inputs, inputs.pageExtensions);
@@ -39,7 +39,7 @@ export function checkArtifact(inputs) {
 }
 /**
  * Per-router drift of a completed {@link generate} pass against the artifact
- * it replaced — the wrapper's build-phase drift report (TR4).
+ * it replaced — the wrapper's build-phase drift report.
  */
 export function diffGenerated(result) {
     const previous = parseArtifactRoutes(result.previousContent);
@@ -49,8 +49,8 @@ export function diffGenerated(result) {
     };
 }
 /**
- * The `  + /new (app)` / `  - /old (pages)` lines of a drift report
- * (TR4/TR7) — each line names the router its path moved in (PR9).
+ * The `  + /new (app)` / `  - /old (pages)` lines of a drift report — each
+ * line names the router its path moved in.
  */
 export function formatRouteDiff(app, pages) {
     return [
@@ -60,7 +60,7 @@ export function formatRouteDiff(app, pages) {
         ...pages.disappeared.map((path) => `  - ${path} (pages)`),
     ];
 }
-/** One generation pass: scan → emit → write-if-changed (TR3). */
+/** One generation pass: scan → emit → write-if-changed. */
 export function generate(inputs) {
     const routes = scanRoutes(inputs, inputs.pageExtensions);
     return {
@@ -92,7 +92,7 @@ export function parseArtifactRoutes(previousContent) {
             continue;
         }
         // Any other line ends the member block — union members are contiguous
-        // in the TR3 deterministic form.
+        // in the deterministic emitted form.
         current = undefined;
     }
     return { appRoutes, pagesRoutes };

package/dist/list/discover-route-defs.d.ts

@@ -37,10 +37,10 @@ export interface RouteDefinition {
  * its text mentions a define constructor (grep-then-load). `routeFiles`
  * config globs replace the default patterns when the heuristic misfires.
  *
- * jiti evaluates matched files (the §7.2 loader carry-over). Known limits,
- * both handled by the per-module degrade: tsconfig `paths` aliases are not
- * resolved (a future improvement could feed them into jiti's `alias`
- * option), and `server-only`-style imports throw outside Next.
+ * jiti evaluates matched files (the loader carry-over from config loading).
+ * Known limits, both handled by the per-module degrade: tsconfig `paths`
+ * aliases are not resolved (a future improvement could feed them into jiti's
+ * `alias` option), and `server-only`-style imports throw outside Next.
  */
 export declare function discoverRouteDefinitions(projectRoot: string, options?: {
     routeFiles?: readonly string[] | undefined;

package/dist/list/discover-route-defs.js

@@ -23,10 +23,10 @@ const MAX_PREFILTER_BYTES = 512 * 1024;
  * its text mentions a define constructor (grep-then-load). `routeFiles`
  * config globs replace the default patterns when the heuristic misfires.
  *
- * jiti evaluates matched files (the §7.2 loader carry-over). Known limits,
- * both handled by the per-module degrade: tsconfig `paths` aliases are not
- * resolved (a future improvement could feed them into jiti's `alias`
- * option), and `server-only`-style imports throw outside Next.
+ * jiti evaluates matched files (the loader carry-over from config loading).
+ * Known limits, both handled by the per-module degrade: tsconfig `paths`
+ * aliases are not resolved (a future improvement could feed them into jiti's
+ * `alias` option), and `server-only`-style imports throw outside Next.
  */
 export async function discoverRouteDefinitions(projectRoot, options = {}) {
     // Dynamic imports, same stance as config.ts: only commands that actually

package/dist/lock.d.ts

@@ -12,18 +12,17 @@ export interface AcquireLockResult {
     release?: () => void;
 }
 /**
- * Cross-process single-writer guard (TR6): a best-effort pidfile lock. On
- * startup: read lock → liveness-probe the owner → decline if alive,
- * (over)write and acquire if dead or absent. Deliberately best-effort, not
- * correct — TR3's deterministic write-if-changed output means two live
- * watchers produce identical bytes; imperfect locking costs a log line, not
- * corruption. Hence no flock semantics, atomic-rename dances, or PID-reuse
- * paranoia. The in-process singleton (TR6 guard 1) lives at the composition
- * points, not here.
+ * Cross-process single-writer guard: a best-effort pidfile lock. On startup:
+ * read lock → liveness-probe the owner → decline if alive, (over)write and
+ * acquire if dead or absent. Deliberately best-effort, not correct — the
+ * deterministic write-if-changed output means two live watchers produce
+ * identical bytes; imperfect locking costs a log line, not corruption. Hence
+ * no flock semantics, atomic-rename dances, or PID-reuse paranoia. The
+ * in-process singleton guard lives at the composition points, not here.
  */
 export declare function acquireWatcherLock(lockPath: string): AcquireLockResult;
 /**
- * The one canonical pidfile location (TR6): CLI-vs-wrapper dedupe only works
+ * The one canonical pidfile location: CLI-vs-wrapper dedupe only works
  * because both paths compute the lock from the same project root.
  */
 export declare function watcherLockPath(projectRoot: string): string;

package/dist/lock.js

@@ -3,14 +3,13 @@ import { dirname, join } from "node:path";
 /** Strict anchored PID parse — anything else is a stale/corrupt lock. */
 const PID_RE = /^\d+$/;
 /**
- * Cross-process single-writer guard (TR6): a best-effort pidfile lock. On
- * startup: read lock → liveness-probe the owner → decline if alive,
- * (over)write and acquire if dead or absent. Deliberately best-effort, not
- * correct — TR3's deterministic write-if-changed output means two live
- * watchers produce identical bytes; imperfect locking costs a log line, not
- * corruption. Hence no flock semantics, atomic-rename dances, or PID-reuse
- * paranoia. The in-process singleton (TR6 guard 1) lives at the composition
- * points, not here.
+ * Cross-process single-writer guard: a best-effort pidfile lock. On startup:
+ * read lock → liveness-probe the owner → decline if alive, (over)write and
+ * acquire if dead or absent. Deliberately best-effort, not correct — the
+ * deterministic write-if-changed output means two live watchers produce
+ * identical bytes; imperfect locking costs a log line, not corruption. Hence
+ * no flock semantics, atomic-rename dances, or PID-reuse paranoia. The
+ * in-process singleton guard lives at the composition points, not here.
  */
 export function acquireWatcherLock(lockPath) {
     const ownerPid = readOwnerPid(lockPath);
@@ -35,8 +34,8 @@ export function acquireWatcherLock(lockPath) {
             }
         }
         catch {
-            // Best-effort (TR6): a leftover lock self-heals via the liveness
-            // probe on the next startup.
+            // Best-effort: a leftover lock self-heals via the liveness probe on
+            // the next startup.
         }
     };
     const reraise = (signal) => {
@@ -57,13 +56,13 @@ export function acquireWatcherLock(lockPath) {
     return { acquired: true, release };
 }
 /**
- * The one canonical pidfile location (TR6): CLI-vs-wrapper dedupe only works
+ * The one canonical pidfile location: CLI-vs-wrapper dedupe only works
  * because both paths compute the lock from the same project root.
  */
 export function watcherLockPath(projectRoot) {
     return join(projectRoot, "node_modules", ".cache", "paramour", "watcher.lock");
 }
-/** `true` when `pid` is a live process (TR6 liveness probe). */
+/** `true` when `pid` is a live process — the liveness probe. */
 function isAlive(pid) {
     try {
         process.kill(pid, 0);

package/dist/navigation-adapter.d.ts

@@ -0,0 +1,59 @@
+import type { ParamsSource } from "paramour";
+/**
+ * Adapter seam for the client hooks' framework reads: each flavor's hooks
+ * resolve Next through a React context so the /testing entry can override
+ * the reads without runner-specific module mocking. Deliberately NO
+ * `"use client"` directive — app.ts (which carries one) and pages.ts (which
+ * must not) both import from here, like observe.ts/select.ts; the directive
+ * belongs on the entry modules, not a shared leaf.
+ *
+ * This module is Next-free on purpose: the contexts default to `null`
+ * and each flavor ENTRY supplies its own real-Next fallback
+ * (`useContext(ctx) ?? realAdapter`), so neither this module nor the
+ * /testing entry ever drags a `next/*` specifier into its graph. The
+ * dist.test.ts bundle-hygiene invariants (/app reaches only
+ * `next/navigation`, /pages only `next/router.js`, /testing neither) depend
+ * on exactly this split — a context whose DEFAULT VALUE were the real
+ * adapter would break all three.
+ */
+/**
+ * App-flavor adapter: EXACTLY the ambient view of `next/navigation` declared
+ * in `src/types/next-navigation.d.ts` — that ambient is the contract of
+ * record, and this interface must stay in lockstep with it (the
+ * `examples/next-compat` pins guard the real-Next side). `useParams()`'s
+ * `null` arm is the outside-App-Router-tree state (Next #48058 family) the
+ * hooks deliberately tolerate; `useRouter().replace`/`usePathname` are the
+ * devtools `navigate` capability's write path and resolution base.
+ */
+export interface AppNavigationAdapter {
+    useParams(): null | ParamsSource;
+    usePathname(): string;
+    useRouter(): {
+        replace(href: string): void;
+    };
+    useSearchParams(): URLSearchParams;
+}
+/**
+ * Pages-flavor adapter: EXACTLY the ambient view of `next/router.js`
+ * declared in `src/types/next-router.d.ts` — that ambient is the contract of
+ * record, and this interface must stay in lockstep with it. The ambient's
+ * throw-on-unmounted behavior under `app/` is part of the contract: adapter
+ * implementations reproduce it by THROWING from `useRouter()`, which
+ * pages.ts translates.
+ */
+export interface PagesNavigationAdapter {
+    useRouter(): {
+        asPath: string;
+        isReady: boolean;
+        query: ParamsSource;
+        replace(url: string): Promise<boolean>;
+    };
+}
+/**
+ * The `null` default is load-bearing: with no provider mounted, app.ts falls
+ * back to its real `next/navigation` adapter — zero markup and zero behavior
+ * change in production.
+ */
+export declare const AppNavigationContext: import("react").Context<AppNavigationAdapter | null>;
+/** The pages twin; its `null` default is load-bearing for the same reasons. */
+export declare const PagesNavigationContext: import("react").Context<PagesNavigationAdapter | null>;

package/dist/navigation-adapter.js

@@ -0,0 +1,9 @@
+import { createContext } from "react";
+/**
+ * The `null` default is load-bearing: with no provider mounted, app.ts falls
+ * back to its real `next/navigation` adapter — zero markup and zero behavior
+ * change in production.
+ */
+export const AppNavigationContext = createContext(null);
+/** The pages twin; its `null` default is load-bearing for the same reasons. */
+export const PagesNavigationContext = createContext(null);

package/dist/observe.d.ts

@@ -1,15 +1,15 @@
 import type { AnyRoute, ParamsSource, RouterKind } from "paramour";
 import type { ParamourHookId, ParamourNavigate, ParamourObservationResult, ParamourSearchWire } from "./devtools-seam.js";
 /**
- * Shared devtools seam wiring for the six read hooks (design-12 DT4/DT8):
- * the navigate builders (one per router flavor) and the per-hook emitter
- * that owns WHEN an observation goes out. Deliberately NO `"use client"`
- * directive — app.ts (which carries one) and pages.ts (which must not,
- * PR2) both import from here, like select.ts.
+ * Shared devtools seam wiring for the six read hooks: the navigate builders
+ * (one per router flavor) and the per-hook emitter that owns WHEN an
+ * observation goes out. Deliberately NO `"use client"` directive — app.ts
+ * (which carries one) and pages.ts (which must not) both import from here,
+ * like select.ts.
  *
  * Emission policy: the hooks call {@link DevtoolsEmitter.observe} from
- * inside the `useStableResult` compute — the SEL4 fingerprint cache miss IS
- * the decode-change dedup (DT4), and only render-phase can report the
+ * inside the `useStableResult` compute — the fingerprint cache miss IS the
+ * decode-change dedup, and only render-phase can report the
  * OrThrow hooks' error observation before the rethrow. `observe` alone
  * would leave one staleness hole: a component that survives a navigation
  * whose decode is unchanged (`/product/1?q=a` → `/product/2?q=a` in a
@@ -18,10 +18,10 @@ import type { ParamourHookId, ParamourNavigate, ParamourObservationResult, Param
  * navigate back to the old resource. {@link DevtoolsEmitter.refresh},
  * called render-phase after the stable result returns, closes it: when the
  * resolution base (or a HMR-reminted route) moved under a cached decode, it
- * re-emits the CACHED result with the fresh spec — decode stability (SEL4)
- * is untouched, only the seam payload is renewed.
+ * re-emits the CACHED result with the fresh spec — decode stability is
+ * untouched, only the seam payload is renewed.
  *
- * Production erasure (DT6): every call site keeps a literal
+ * Production erasure: every call site keeps a literal
  * `process.env.NODE_ENV` guard the bundler constant-folds, and both emitter
  * methods early-return behind the same literal guard, so the
  * `emitObservation` import above is dead in a production bundle and drops
@@ -51,15 +51,15 @@ export interface ObservationSpec {
     readonly wire: () => ParamourSearchWire | Readonly<ParamsSource>;
 }
 /**
- * App-flavor navigate capability (DT8): `next/navigation`'s `replace`
- * returns void and resolves the basePath-/locale-relative join itself.
+ * App-flavor navigate capability: `next/navigation`'s `replace` returns void
+ * and resolves the basePath-/locale-relative join itself.
  */
 export declare function makeAppNavigate(router: {
     replace: (href: string) => void;
 }, pathname: string): ParamourNavigate;
 /**
- * Pages-flavor navigate capability (DT8): `next/router`'s `replace` returns
- * a promise that REJECTS on routine navigation aborts (rapid re-commits
+ * Pages-flavor navigate capability: `next/router`'s `replace` returns a
+ * promise that REJECTS on routine navigation aborts (rapid re-commits
  * from the panel), marked with next's `cancelled` discriminant — those must
  * not surface as unhandled rejections. Anything else is a real failure
  * (render error, route-info error) silently discarding the user's edit, so