@paramour-js/next 0.4.0 → 0.4.1

package/dist/select.d.ts

@@ -1,63 +1,63 @@
 import type { AnyRoute, ParamsSource, SafeResult } from "paramour";
 /**
- * Shared internals of the read hooks' selector surface (design-07): the
- * raw-slice stabilization layer (SEL4) and the selector layer (SEL2/SEL3).
- * Deliberately NO `"use client"` directive: app.ts (which carries one) and
- * pages.ts (which must not carry one, design-06 PR2) both import from here,
- * and the directive belongs on the entry modules, not a shared leaf.
+ * Shared internals of the read hooks' selector surface: the raw-slice
+ * stabilization layer and the selector layer. Deliberately NO `"use client"`
+ * directive: app.ts (which carries one) and pages.ts (which must not carry
+ * one) both import from here, and the directive belongs on the entry
+ * modules, not a shared leaf.
  *
- * Both layers are `useRef` caches mutated during render (SEL8) — the
- * Redux/TanStack selector pattern, and the one sanctioned departure from the
- * hooks' pure-`useMemo` discipline: result equality needs memory across
- * renders, which no pure memo can provide. Every cache is cleared BEFORE a
- * compute that can throw, so a throwing decode or selector never strands a
- * stale entry.
+ * Both layers are `useRef` caches mutated during render — the Redux/TanStack
+ * selector pattern, and the one sanctioned departure from the hooks'
+ * pure-`useMemo` discipline: result equality needs memory across renders,
+ * which no pure memo can provide. Every cache is cleared BEFORE a compute
+ * that can throw, so a throwing decode or selector never strands a stale
+ * entry.
  */
 /**
- * Options bag accepted by every read hook (design-07 SEL1).
+ * Options bag accepted by every read hook.
  */
 export interface SelectOptions<T, U> {
     /**
-     * Result-equality mode for the selected value (SEL3): `Object.is` by
-     * default — free and correct for primitive selections — with one-level
-     * `"shallow"` as the opt-in for tuple/object selections.
+     * Result-equality mode for the selected value: `Object.is` by default —
+     * free and correct for primitive selections — with one-level `"shallow"`
+     * as the opt-in for tuple/object selections.
      */
     readonly equality?: "shallow";
     /**
-     * Pure projection of the decoded value; runs only on the success arm
-     * (SEL2). Identity is never compared, so inline arrows are fine — and when
-     * the underlying result is reference-stable the selector is NOT re-run
-     * (SEL6), so it must not read changing outside state. A throw propagates to
-     * the nearest error boundary (SEL5): a selector bug is a code bug, never
-     * the `SafeResult` error arm, which is reserved for URL data problems.
+     * Pure projection of the decoded value; runs only on the success arm.
+     * Identity is never compared, so inline arrows are fine — and when the
+     * underlying result is reference-stable the selector is NOT re-run, so it
+     * must not read changing outside state. A throw propagates to the nearest
+     * error boundary: a selector bug is a code bug, never the `SafeResult`
+     * error arm, which is reserved for URL data problems.
      */
     readonly select: (value: T) => U;
 }
 /**
- * Fingerprint of the pages hooks' pre-`isReady` state (design-06 PR5). Every
- * real fingerprint is a `JSON.stringify`'d array (starts with `[`), so this
- * can never collide with one.
+ * Fingerprint of the pages hooks' pre-`isReady` state. Every real
+ * fingerprint is a `JSON.stringify`'d array (starts with `[`), so this can
+ * never collide with one.
  */
 export declare const PENDING_FINGERPRINT = "pending";
 /**
- * Raw slice of a params source (SEL4): the route's dynamic segment names'
- * raw values, from the define-time `~segments` token cache. Unknown keys —
+ * Raw slice of a params source: the route's dynamic segment names' raw
+ * values, from the define-time `~segments` token cache. Unknown keys —
  * e.g. a parallel route's params in the same `useParams()` bag — never bust
  * the fingerprint, because the decode never reads them.
  */
 export declare function paramsFingerprint(route: AnyRoute, source: ParamsSource): string;
 /**
- * Raw slice of a pages `router.query` bag for the search half (SEL4). A
- * codec-map route reads exactly its declared keys (query junk and the
- * route's own path params are invisible to the decode, PR9 disjointness); a
+ * Raw slice of a pages `router.query` bag for the search half. A codec-map
+ * route reads exactly its declared keys (query junk and the route's own path
+ * params are invisible to the decode — the two namespaces are disjoint); a
  * `rawSearch` route has no enumerable declared-key set — the schema sees
- * every key except the route's path params (design-06 PR5 subtraction), so
- * exactly that slice is fingerprinted, in sorted-key order for record-order
- * independence.
+ * every key except the route's path params (by subtracting them from the
+ * bag), so exactly that slice is fingerprinted, in sorted-key order for
+ * record-order independence.
  */
 export declare function queryFingerprint(route: AnyRoute, query: ParamsSource): string;
 /**
- * Raw slice of an app `useSearchParams()` source (SEL4): the declared keys'
+ * Raw slice of an app `useSearchParams()` source: the declared keys'
  * `[key, value]` pairs in wire order — order is load-bearing for repeated
  * keys (array codecs decode in wire order, P5/S5), and iterating the live
  * pairs preserves the relative order of declared entries while `?utm_*`
@@ -66,8 +66,8 @@ export declare function queryFingerprint(route: AnyRoute, query: ParamsSource):
  */
 export declare function searchParamsFingerprint(route: AnyRoute, source: URLSearchParams): string;
 /**
- * The selector layer for the safe hooks (SEL2): projects the success arm and
- * reference-stabilizes the projected WRAPPER by result equality (SEL3) — a
+ * The selector layer for the safe hooks: projects the success arm and
+ * reference-stabilizes the projected WRAPPER by result equality — a
  * stable `data` inside a fresh wrapper would still churn every consumer.
  * Error and pending arms pass through untouched; they are already
  * reference-stabilized by {@link useStableResult}'s raw-slice layer.
@@ -79,16 +79,16 @@ export declare function useSelectedResult<T, U>(result: SafeResult<T> | {
     status: "pending";
 };
 /**
- * {@link useSelectedResult}'s twin for the `*OrThrow` hooks (SEL2): same
- * layering, no wrapper — the hook's return IS the (selected) value.
+ * {@link useSelectedResult}'s twin for the `*OrThrow` hooks: same layering,
+ * no wrapper — the hook's return IS the (selected) value.
  */
 export declare function useSelectedValue<T, U>(value: T, options: SelectOptions<T, U> | undefined): T | U;
 /**
- * The raw-slice stabilization layer (SEL4): while `route` and `fingerprint`
- * are unchanged from the previous render, the previous result — success OR
+ * The raw-slice stabilization layer: while `route` and `fingerprint` are
+ * unchanged from the previous render, the previous result — success OR
  * error arm — is returned without recomputing, so a fresh `useSearchParams()`
  * / `query` object whose DECLARED slice is unchanged (`?utm_source=` churn)
  * costs neither a decode nor anyone's referential equality. This replaces
- * the pre-design-07 "memo keyed on Next's object reference" behavior.
+ * the earlier "memo keyed on Next's object reference" behavior.
  */
 export declare function useStableResult<T>(route: AnyRoute, fingerprint: string, compute: () => T): T;

package/dist/select.js

@@ -1,13 +1,13 @@
 import { useRef } from "react";
 /**
- * Fingerprint of the pages hooks' pre-`isReady` state (design-06 PR5). Every
- * real fingerprint is a `JSON.stringify`'d array (starts with `[`), so this
- * can never collide with one.
+ * Fingerprint of the pages hooks' pre-`isReady` state. Every real
+ * fingerprint is a `JSON.stringify`'d array (starts with `[`), so this can
+ * never collide with one.
  */
 export const PENDING_FINGERPRINT = "pending";
 /**
- * Raw slice of a params source (SEL4): the route's dynamic segment names'
- * raw values, from the define-time `~segments` token cache. Unknown keys —
+ * Raw slice of a params source: the route's dynamic segment names' raw
+ * values, from the define-time `~segments` token cache. Unknown keys —
  * e.g. a parallel route's params in the same `useParams()` bag — never bust
  * the fingerprint, because the decode never reads them.
  */
@@ -15,13 +15,13 @@ export function paramsFingerprint(route, source) {
     return recordFingerprint(dynamicSegmentNames(route), source);
 }
 /**
- * Raw slice of a pages `router.query` bag for the search half (SEL4). A
- * codec-map route reads exactly its declared keys (query junk and the
- * route's own path params are invisible to the decode, PR9 disjointness); a
+ * Raw slice of a pages `router.query` bag for the search half. A codec-map
+ * route reads exactly its declared keys (query junk and the route's own path
+ * params are invisible to the decode — the two namespaces are disjoint); a
  * `rawSearch` route has no enumerable declared-key set — the schema sees
- * every key except the route's path params (design-06 PR5 subtraction), so
- * exactly that slice is fingerprinted, in sorted-key order for record-order
- * independence.
+ * every key except the route's path params (by subtracting them from the
+ * bag), so exactly that slice is fingerprinted, in sorted-key order for
+ * record-order independence.
  */
 export function queryFingerprint(route, query) {
     const declared = declaredSearchKeys(route);
@@ -34,7 +34,7 @@ export function queryFingerprint(route, query) {
     return recordFingerprint(keys, query);
 }
 /**
- * Raw slice of an app `useSearchParams()` source (SEL4): the declared keys'
+ * Raw slice of an app `useSearchParams()` source: the declared keys'
  * `[key, value]` pairs in wire order — order is load-bearing for repeated
  * keys (array codecs decode in wire order, P5/S5), and iterating the live
  * pairs preserves the relative order of declared entries while `?utm_*`
@@ -62,15 +62,15 @@ export function useSelectedResult(result, options) {
         return result;
     const previous = cache.current;
     if (previous !== null && Object.is(previous.input, result.data)) {
-        // Reference-stable input ⇒ equal output by selector purity (SEL6); the
-        // selector is deliberately not re-run.
+        // Reference-stable input ⇒ equal output by selector purity; the selector
+        // is deliberately not re-run.
         return previous.wrapped;
     }
-    const selected = options.select(result.data); // a throw propagates (SEL5)
+    const selected = options.select(result.data); // a throw propagates
     if (previous !== null &&
         selectedEquals(options.equality, previous.wrapped.data, selected)) {
-        // Same selection out of a new decode: keep the previous wrapper (SEL2)
-        // and re-key the cache so the next render takes the reference fast path.
+        // Same selection out of a new decode: keep the previous wrapper and
+        // re-key the cache so the next render takes the reference fast path.
         previous.input = result.data;
         return previous.wrapped;
     }
@@ -82,8 +82,8 @@ export function useSelectedResult(result, options) {
     return wrapped;
 }
 /**
- * {@link useSelectedResult}'s twin for the `*OrThrow` hooks (SEL2): same
- * layering, no wrapper — the hook's return IS the (selected) value.
+ * {@link useSelectedResult}'s twin for the `*OrThrow` hooks: same layering,
+ * no wrapper — the hook's return IS the (selected) value.
  */
 export function useSelectedValue(value, options) {
     const cache = useRef(null);
@@ -91,9 +91,9 @@ export function useSelectedValue(value, options) {
         return value;
     const previous = cache.current;
     if (previous !== null && Object.is(previous.input, value)) {
-        return previous.selected; // SEL6: selector purity, not re-run
+        return previous.selected; // selector purity: not re-run
     }
-    const selected = options.select(value); // a throw propagates (SEL5)
+    const selected = options.select(value); // a throw propagates
     if (previous !== null &&
         selectedEquals(options.equality, previous.selected, selected)) {
         previous.input = value;
@@ -103,12 +103,12 @@ export function useSelectedValue(value, options) {
     return selected;
 }
 /**
- * The raw-slice stabilization layer (SEL4): while `route` and `fingerprint`
- * are unchanged from the previous render, the previous result — success OR
+ * The raw-slice stabilization layer: while `route` and `fingerprint` are
+ * unchanged from the previous render, the previous result — success OR
  * error arm — is returned without recomputing, so a fresh `useSearchParams()`
  * / `query` object whose DECLARED slice is unchanged (`?utm_source=` churn)
  * costs neither a decode nor anyone's referential equality. This replaces
- * the pre-design-07 "memo keyed on Next's object reference" behavior.
+ * the earlier "memo keyed on Next's object reference" behavior.
  */
 export function useStableResult(route, fingerprint, compute) {
     const cache = useRef(null);
@@ -120,7 +120,7 @@ export function useStableResult(route, fingerprint, compute) {
             throw cached.outcome.thrown;
         return cached.outcome.value;
     }
-    // Cleared BEFORE computing (SEL8): no half-computed state may survive a
+    // Cleared BEFORE computing: no half-computed state may survive a
     // throw, and a NEW fingerprint always recomputes — an error boundary
     // reset after the URL is fixed can never be served a stale entry.
     cache.current = null;
@@ -152,7 +152,7 @@ export function useStableResult(route, fingerprint, compute) {
  * Declared search keys of a route's `~search` slot, or `null` for a
  * `rawSearch` route (whose schema owns every key, so no declared subset
  * exists). The `~kind` marker is unambiguous against a codec map, which
- * never carries a top-level `~`-prefixed key (design-04 SS2).
+ * never carries a top-level `~`-prefixed key (SS2).
  */
 function declaredSearchKeys(route) {
     const config = route["~search"];
@@ -185,16 +185,16 @@ function recordFingerprint(keys, source) {
         Object.hasOwn(source, key) ? (source[key] ?? null) : null,
     ]));
 }
-/** SEL3: `Object.is`, widened one level by the `"shallow"` opt-in. */
+/** Result equality: `Object.is`, widened one level by `"shallow"`. */
 function selectedEquals(equality, a, b) {
     if (Object.is(a, b))
         return true;
     return equality === "shallow" && shallowEqual(a, b);
 }
 /**
- * One-level equality for the `"shallow"` opt-in (SEL3): arrays element-wise,
- * plain objects by own enumerable keys — `Object.is` at each leaf, nothing
- * recursive (deep comparison in a render path is a non-goal, design-07).
+ * One-level equality for the `"shallow"` opt-in: arrays element-wise, plain
+ * objects by own enumerable keys — `Object.is` at each leaf, nothing
+ * recursive (deep comparison in a render path is a non-goal).
  */
 function shallowEqual(a, b) {
     if (typeof a !== "object" ||

package/dist/testing.d.ts

@@ -1,46 +1,42 @@
 import type { ParamsSource } from "paramour";
 import type { ReactElement, ReactNode } from "react";
 /**
- * `@paramour-js/next/testing` (design-16): a provider that overrides the
- * hooks' framework reads through the adapter seam (TA1), so client
- * components calling `useSearch`/`useRouteParams` (either flavor) can be
- * unit-tested without runner-specific `next/*` module mocking. One provider
- * feeds BOTH flavor contexts (TA5) — hybrid apps and pages components need
- * no second import. Server code needs none of this: `parse`/`safeParse` and
- * server components are pure functions over props (TA8).
+ * `@paramour-js/next/testing`: a provider that overrides the hooks'
+ * framework reads through the adapter seam, so client components calling
+ * `useSearch`/`useRouteParams` (either flavor) can be unit-tested without
+ * runner-specific `next/*` module mocking. One provider feeds BOTH flavor
+ * contexts — hybrid apps and pages components need no second import. Server
+ * code needs none of this: `parse`/`safeParse` and server components are
+ * pure functions over props.
  *
  * This module imports ONLY react and the (Next-free) adapter-seam module —
- * no `next/*` specifier and no `@testing-library/*` (TA5; dist.test.ts pins
- * the bundle graph, and the hermeticity check there is why these docs never
- * spell out the two Next specifiers). It carries `"use client"` like
- * app.ts.
+ * no `next/*` specifier and no `@testing-library/*`; dist.test.ts pins the
+ * bundle graph, and the hermeticity check there is why these docs never
+ * spell out the two Next specifiers. It carries `"use client"` like app.ts.
  *
- * Stability contract (TA4): the provider holds ONE adapter pair for its
- * lifetime, created once and closing over a latest-props ref that is
- * reassigned every render — prop changes mutate what the stable adapters
- * RETURN, they never mint new adapters, so the hooks' context reads stay
- * identity-stable and mid-test URL changes are driven by ordinary rerenders
- * with new props.
+ * Stability contract: the provider holds ONE adapter pair for its lifetime,
+ * created once and closing over a latest-props ref that is reassigned every
+ * render — prop changes mutate what the stable adapters RETURN, they never
+ * mint new adapters, so the hooks' context reads stay identity-stable and
+ * mid-test URL changes are driven by ordinary rerenders with new props.
  */
 /**
- * Input shape mirrors what Next hands the hooks (TA6) — no `url`
- * reverse-matching in v1 (deferred: needs a core matcher). `params: null`
- * and `mounted: false` are first-class because they are the two states
- * nobody hand-rolling a mock models.
+ * Input shape mirrors what Next hands the hooks — no `url` reverse-matching
+ * in v1 (deferred: needs a core matcher). `params: null` and
+ * `mounted: false` are first-class because they are the two states nobody
+ * hand-rolling a mock models.
  */
 export interface ParamourTestingOptions {
     /**
      * Pages flavor only: `false` is the pre-hydration state of a
-     * statically-optimized page (`query` not yet populated — the PR5
-     * `pending` arm). Defaults to `true`. design-16 listed this as deferred,
-     * but TA7 migrates the whole pages suite — which pins the pending arm —
-     * to this provider, so it was promoted from the deferred list.
+     * statically-optimized page (`query` not yet populated — the hooks'
+     * `pending` arm). Defaults to `true`.
      */
     isReady?: boolean;
     /**
      * Pages flavor only: `false` reproduces the pages router's
-     * throw-on-unmounted state under `app/` (PR5) — pages.ts translates it to
-     * a `ParamourError` naming the actual mistake.
+     * throw-on-unmounted state under `app/` — pages.ts translates it to a
+     * `ParamourError` naming the actual mistake.
      */
     mounted?: boolean;
     /** Captures `replace(href)` from either flavor's router. */
@@ -56,16 +52,16 @@ export interface ParamourTestingOptions {
     search?: string | URLSearchParams;
 }
 /**
- * Renders BOTH flavor contexts' providers around `children` (TA5). Exported
- * for people composing their own wrappers (Storybook decorators, custom
- * render helpers); testing-library users want {@link withParamourTesting}.
+ * Renders BOTH flavor contexts' providers around `children`. Exported for
+ * people composing their own wrappers (Storybook decorators, custom render
+ * helpers); testing-library users want {@link withParamourTesting}.
  */
 export declare function ParamourTestingProvider(props: ParamourTestingOptions & {
     children?: ReactNode;
 }): ReactElement;
 /**
- * Wrapper-component form for testing-library's `wrapper` option (TA5,
- * mirroring `withNuqsTestingAdapter`).
+ * Wrapper-component form for testing-library's `wrapper` option, mirroring
+ * `withNuqsTestingAdapter`.
  */
 export declare function withParamourTesting(options?: ParamourTestingOptions): (props: {
     children?: ReactNode;

package/dist/testing.js

@@ -3,21 +3,21 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useRef, useState } from "react";
 import { AppNavigationContext, PagesNavigationContext, } from "./navigation-adapter.js";
 /**
- * Renders BOTH flavor contexts' providers around `children` (TA5). Exported
- * for people composing their own wrappers (Storybook decorators, custom
- * render helpers); testing-library users want {@link withParamourTesting}.
+ * Renders BOTH flavor contexts' providers around `children`. Exported for
+ * people composing their own wrappers (Storybook decorators, custom render
+ * helpers); testing-library users want {@link withParamourTesting}.
  */
 export function ParamourTestingProvider(props) {
-    // Latest-ref pattern (TA4): reassigned every render so the stable
-    // adapters below always read the CURRENT render's props.
+    // Latest-ref pattern: reassigned every render so the stable adapters
+    // below always read the CURRENT render's props.
     const latest = useRef(props);
     latest.current = props;
     const [adapters] = useState(() => createAdapters(latest));
     return (_jsx(AppNavigationContext.Provider, { value: adapters.app, children: _jsx(PagesNavigationContext.Provider, { value: adapters.pages, children: props.children }) }));
 }
 /**
- * Wrapper-component form for testing-library's `wrapper` option (TA5,
- * mirroring `withNuqsTestingAdapter`).
+ * Wrapper-component form for testing-library's `wrapper` option, mirroring
+ * `withNuqsTestingAdapter`.
  */
 export function withParamourTesting(options = {}) {
     return function ParamourTestingWrapper({ children, }) {
@@ -25,10 +25,10 @@ export function withParamourTesting(options = {}) {
     };
 }
 /**
- * The one adapter pair a provider instance ever holds (TA4). Every read
- * defers to `latest.current`, so the adapters are stable while their
- * answers track prop updates. Fresh `URLSearchParams` per call is fine —
- * the hooks fingerprint the declared slice (SEL4), not the instance.
+ * The one adapter pair a provider instance ever holds. Every read defers to
+ * `latest.current`, so the adapters are stable while their answers track
+ * prop updates. Fresh `URLSearchParams` per call is fine — the hooks
+ * fingerprint the declared slice, not the instance.
  */
 function createAdapters(latest) {
     const app = {
@@ -57,20 +57,20 @@ function createAdapters(latest) {
             const options = latest.current;
             if (options.mounted === false) {
                 // Verbatim prefix of next/router's real unmounted error — pages.ts
-                // matches on the message to translate it (PR5).
+                // matches on the message to translate it.
                 throw new Error("NextRouter was not mounted. https://nextjs.org/docs/messages/next-router-not-mounted");
             }
             const search = normalizeSearch(options.search);
             return {
-                // asPath derives from pathname + normalized search (TA6) —
+                // asPath derives from pathname + normalized search —
                 // basePath-relative, what the devtools navigate capability resolves
-                // against (DT8).
+                // against.
                 asPath: (options.pathname ?? "/") + (search === "" ? "" : `?${search}`),
                 isReady: options.isReady ?? true,
                 query: mergedQuery(options),
                 replace(url) {
                     latest.current.onReplace?.(url);
-                    // Real next/router resolves `true` on a completed replace (TA6).
+                    // Real next/router resolves `true` on a completed replace.
                     return Promise.resolve(true);
                 },
             };

package/dist/watch.d.ts

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

package/dist/watch.js

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

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

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