@paramour-js/next 0.1.0

package/dist/scan-pages.js

@@ -0,0 +1,102 @@
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+import { assertNoStructuralCollisions, RouteCollisionError, } from "./collisions.js";
+import { DEFAULT_PAGE_EXTENSIONS, resolvesToFile } from "./scan-app.js";
+/**
+ * Pages Router scanner (PR4). Deliberately a separate walker from
+ * `scan-app.ts` — the rule sets barely overlap (routes live on FILES here,
+ * and none of TR2's skip rules apply), and a shared walker would have to
+ * take its rule set as a parameter to be worth having (PR8).
+ */
+/**
+ * Names special to Next at the TOP level of the pages dir only (PR4):
+ * `_app`/`_document`/`_error` are framework files, `404`/`500` are error
+ * pages, not navigation targets — `href("/404")` should not type-check.
+ * Nested twins (`pages/blog/404.tsx`) are ordinary pages and route.
+ * Every other `_`-prefixed file routes too (spike 1: co-location under
+ * `pages/` was requested, vercel/next.js#8454, and never implemented).
+ */
+const TOP_LEVEL_EXCLUDED = new Set([
+    "404",
+    "500",
+    "_app",
+    "_document",
+    "_error",
+]);
+/**
+ * Walk a pages dir and return the sorted union of URL-shaped route paths —
+ * exactly the strings `definePagesRoute` accepts (PR4). A route is any file
+ * whose extension is in `pageExtensions`, mapped by its path relative to the
+ * dir; `index.<ext>` maps to its directory. Two files resolving to one URL
+ * path — folder/file spelling (`blog.tsx` + `blog/index.tsx`) or extension
+ * twins (`about.tsx` + `about.jsx`) — throw a {@link RouteCollisionError},
+ * never dedupe: both are Next's own build errors (PR9).
+ */
+export function scanPagesRoutes(pagesDir, pageExtensions = DEFAULT_PAGE_EXTENSIONS) {
+    // Path → the fs path (relative to pagesDir) that produced it, so a
+    // collision can name both files.
+    const out = new Map();
+    walk(pagesDir, [], pageExtensions, out, true);
+    // Code-unit sort, never localeCompare — locale independence feeds TR3's
+    // byte-identical-on-every-OS guarantee.
+    const paths = [...out.keys()].sort();
+    // PR9 structural collisions (different slug names, optional-catch-all
+    // specificity) — non-equal strings the Map above cannot catch.
+    assertNoStructuralCollisions(paths.map((path) => ({ path, router: "pages" })));
+    return paths;
+}
+/**
+ * The extension a file name matches, or `undefined` — first match in the
+ * caller's order, mirroring how Next builds its page matcher from
+ * `pageExtensions`. Requires a non-empty base name so a bare `.tsx` file is
+ * not a route to `/`.
+ */
+function matchExtension(name, pageExtensions) {
+    return pageExtensions.find((ext) => name.length > ext.length + 1 && name.endsWith(`.${ext}`));
+}
+function walk(dir, urlSegments, pageExtensions, out, isTopLevel) {
+    // Sorted traversal: readdir order is platform-dependent, and which of two
+    // colliding files gets named first in the error must not be.
+    const entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+    for (const entry of entries) {
+        const name = entry.name;
+        // A real file, or a symlink whose target is a file: Next resolves and
+        // serves symlinked page files, so a file symlink routes exactly like a
+        // real file (Bug 4, TR2 shared posture). Directory symlinks fall through
+        // to the directory guard below and stay not-followed.
+        if (resolvesToFile(entry, dir)) {
+            // Declaration files match `.ts` but are never pages (PR11 §1).
+            if (name.endsWith(".d.ts"))
+                continue;
+            const ext = matchExtension(name, pageExtensions);
+            if (ext === undefined)
+                continue;
+            const base = name.slice(0, -(ext.length + 1));
+            if (isTopLevel && TOP_LEVEL_EXCLUDED.has(base))
+                continue;
+            // `index.<ext>` maps to its directory; everything else — dynamic
+            // segments included — is a path segment of its own (PR4).
+            const segments = base === "index" ? urlSegments : [...urlSegments, base];
+            const path = segments.length === 0 ? "/" : `/${segments.join("/")}`;
+            const file = [...urlSegments, name].join("/");
+            const existing = out.get(path);
+            if (existing !== undefined) {
+                throw new RouteCollisionError(`pages route collision at "${path}": ${existing} and ${file} resolve to the same path (PR9)`);
+            }
+            out.set(path, file);
+            continue;
+        }
+        // Symlinked directories are deliberately not followed (TR2 v1 stance,
+        // shared posture): `resolvesToFile` returned false and `isDirectory()` is
+        // false for the link Dirent, so the subtree is skipped here.
+        if (!entry.isDirectory())
+            continue;
+        // `pages/api/**` is excluded — top level only, so `pages/foo/api/bar.tsx`
+        // routes (API-route typing is deferred to v1.x, PR4/§14). NO app-style
+        // skip rules beyond this: `(group)`, `@slot`, `(.)x`, and `_`-prefixed
+        // dirs are ordinary literal segments in the Pages Router (PR4).
+        if (isTopLevel && name === "api")
+            continue;
+        walk(join(dir, name), [...urlSegments, name], pageExtensions, out, false);
+    }
+}

package/dist/scan.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The thin orchestrator over the two scanners (PR8): joint directory
+ * discovery, delegation, and the cross-router collision checks (PR9).
+ */
+/** The two route dirs of a project; either may be absent (PR1 hybrid). */
+export interface RouteDirs {
+    appDir?: string | undefined;
+    pagesDir?: string | undefined;
+}
+/** Result of {@link scanRoutes} — the input shape of the PR9 artifact. */
+export interface ScanRoutesResult {
+    appRoutes: string[];
+    pagesRoutes: string[];
+}
+/**
+ * Joint route-dir discovery (spike-2 ruling). Next's documented rule is one
+ * decision, not two probes: `src/app` AND `src/pages` are both ignored
+ * whenever `app/` OR `pages/` exists at the project root. An ignored src dir
+ * that contains page files is a hard config error — Next silently serves
+ * none of those pages (and has shipped bugs in the mixed case,
+ * vercel/next.js#58728), so there is no valid state to warn about.
+ */
+export declare function resolveRouteDirs(projectRoot: string, pageExtensions?: readonly string[]): RouteDirs;
+/**
+ * Scan whichever route dirs exist and return both route unions (PR1). After
+ * each scanner's own intra-router checks, two cross-router passes run (PR9):
+ * a path in BOTH unions is Next's "Conflicting app and page file" build
+ * error, and the structural pass re-runs over the merged, labeled union so
+ * shared-prefix slug conflicts and cross-router optional-catch-all
+ * specificity are caught too.
+ */
+export declare function scanRoutes(dirs: RouteDirs, pageExtensions?: readonly string[]): ScanRoutesResult;

package/dist/scan.js

@@ -0,0 +1,77 @@
+import { statSync } from "node:fs";
+import { join } from "node:path";
+import { assertNoStructuralCollisions, RouteCollisionError, } from "./collisions.js";
+import { DEFAULT_PAGE_EXTENSIONS, scanAppRoutes } from "./scan-app.js";
+import { scanPagesRoutes } from "./scan-pages.js";
+/**
+ * Joint route-dir discovery (spike-2 ruling). Next's documented rule is one
+ * decision, not two probes: `src/app` AND `src/pages` are both ignored
+ * whenever `app/` OR `pages/` exists at the project root. An ignored src dir
+ * that contains page files is a hard config error — Next silently serves
+ * none of those pages (and has shipped bugs in the mixed case,
+ * vercel/next.js#58728), so there is no valid state to warn about.
+ */
+export function resolveRouteDirs(projectRoot, pageExtensions = DEFAULT_PAGE_EXTENSIONS) {
+    const rootApp = dirIfExists(join(projectRoot, "app"));
+    const rootPages = dirIfExists(join(projectRoot, "pages"));
+    const srcApp = dirIfExists(join(projectRoot, "src", "app"));
+    const srcPages = dirIfExists(join(projectRoot, "src", "pages"));
+    if (rootApp === undefined && rootPages === undefined) {
+        return { appDir: srcApp, pagesDir: srcPages };
+    }
+    const winner = rootApp === undefined ? "pages/" : "app/";
+    const probes = [
+        [srcApp, (dir) => scanAppRoutes(dir, pageExtensions), "src/app"],
+        [srcPages, (dir) => scanPagesRoutes(dir, pageExtensions), "src/pages"],
+    ];
+    for (const [dir, scan, label] of probes) {
+        if (dir === undefined)
+            continue;
+        let populated;
+        try {
+            populated = scan(dir).length > 0;
+        }
+        catch (error) {
+            // Only a RouteCollisionError proves the ignored dir has page files —
+            // which is the fact the probe needs. Any other throw (EACCES/EPERM,
+            // a dir removed mid-scan, …) is a real I/O failure that must not be
+            // masked by the "silently unreachable" config diagnosis; rethrow it.
+            if (!(error instanceof RouteCollisionError))
+                throw error;
+            populated = true;
+        }
+        if (populated) {
+            throw new Error(`${label} contains page files, but Next ignores src/ route directories whenever app/ or pages/ exists at the project root (here: ${winner}) — those pages are silently unreachable. Move ${label} to the project root, or the root ${winner} directory under src/; explicit --app-dir/--pages-dir flags bypass this discovery.`);
+        }
+    }
+    return { appDir: rootApp, pagesDir: rootPages };
+}
+/**
+ * Scan whichever route dirs exist and return both route unions (PR1). After
+ * each scanner's own intra-router checks, two cross-router passes run (PR9):
+ * a path in BOTH unions is Next's "Conflicting app and page file" build
+ * error, and the structural pass re-runs over the merged, labeled union so
+ * shared-prefix slug conflicts and cross-router optional-catch-all
+ * specificity are caught too.
+ */
+export function scanRoutes(dirs, pageExtensions = DEFAULT_PAGE_EXTENSIONS) {
+    const appRoutes = dirs.appDir === undefined ? [] : scanAppRoutes(dirs.appDir, pageExtensions);
+    const pagesRoutes = dirs.pagesDir === undefined
+        ? []
+        : scanPagesRoutes(dirs.pagesDir, pageExtensions);
+    const appSet = new Set(appRoutes);
+    const shared = pagesRoutes.filter((path) => appSet.has(path));
+    if (shared.length > 0) {
+        throw new RouteCollisionError(`route collision between app/ and pages/: ${shared.map((path) => `"${path}"`).join(", ")} — Next fails the build on conflicting app and page files (PR9)`);
+    }
+    assertNoStructuralCollisions([
+        ...appRoutes.map((path) => ({ path, router: "app" })),
+        ...pagesRoutes.map((path) => ({ path, router: "pages" })),
+    ]);
+    return { appRoutes, pagesRoutes };
+}
+function dirIfExists(path) {
+    return statSync(path, { throwIfNoEntry: false })?.isDirectory()
+        ? path
+        : undefined;
+}

package/dist/select.d.ts

@@ -0,0 +1,94 @@
+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.
+ *
+ * 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.
+ */
+/**
+ * Options bag accepted by every read hook (design-07 SEL1).
+ */
+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.
+     */
+    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.
+     */
+    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.
+ */
+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 —
+ * 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
+ * `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.
+ */
+export declare function queryFingerprint(route: AnyRoute, query: ParamsSource): string;
+/**
+ * Raw slice of an app `useSearchParams()` source (SEL4): 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_*`
+ * churn between them stays invisible. A `rawSearch` route's schema sees
+ * every key (P8 does not apply there), so its slice is all pairs.
+ */
+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
+ * 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.
+ */
+export declare function useSelectedResult<T, U>(result: SafeResult<T>, options: SelectOptions<T, U> | undefined): SafeResult<U>;
+export declare function useSelectedResult<T, U>(result: SafeResult<T> | {
+    status: "pending";
+}, options: SelectOptions<T, U> | undefined): SafeResult<U> | {
+    status: "pending";
+};
+/**
+ * {@link useSelectedResult}'s twin for the `*OrThrow` hooks (SEL2): 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
+ * 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.
+ */
+export declare function useStableResult<T>(route: AnyRoute, fingerprint: string, compute: () => T): T;

package/dist/select.js

@@ -0,0 +1,195 @@
+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.
+ */
+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 —
+ * e.g. a parallel route's params in the same `useParams()` bag — never bust
+ * the fingerprint, because the decode never reads them.
+ */
+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
+ * `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.
+ */
+export function queryFingerprint(route, query) {
+    const declared = declaredSearchKeys(route);
+    if (declared !== null)
+        return recordFingerprint(declared, query);
+    const paramNames = new Set(dynamicSegmentNames(route));
+    const keys = Object.keys(query)
+        .filter((key) => !paramNames.has(key))
+        .sort();
+    return recordFingerprint(keys, query);
+}
+/**
+ * Raw slice of an app `useSearchParams()` source (SEL4): 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_*`
+ * churn between them stays invisible. A `rawSearch` route's schema sees
+ * every key (P8 does not apply there), so its slice is all pairs.
+ */
+export function searchParamsFingerprint(route, source) {
+    const declared = declaredSearchKeys(route);
+    const declaredSet = declared === null ? null : new Set(declared);
+    const pairs = [];
+    for (const [key, value] of source) {
+        if (declaredSet === null || declaredSet.has(key))
+            pairs.push([key, value]);
+    }
+    return JSON.stringify(pairs);
+}
+export function useSelectedResult(result, options) {
+    const cache = useRef(null);
+    if (options === undefined) {
+        // No selector: the raw-slice layer already stabilized `result`, and the
+        // public overloads pin U = T for this arity.
+        return result;
+    }
+    if (result.status !== "success")
+        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.
+        return previous.wrapped;
+    }
+    const selected = options.select(result.data); // a throw propagates (SEL5)
+    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.
+        previous.input = result.data;
+        return previous.wrapped;
+    }
+    const wrapped = {
+        data: selected,
+        status: "success",
+    };
+    cache.current = { input: result.data, wrapped };
+    return wrapped;
+}
+/**
+ * {@link useSelectedResult}'s twin for the `*OrThrow` hooks (SEL2): same
+ * layering, no wrapper — the hook's return IS the (selected) value.
+ */
+export function useSelectedValue(value, options) {
+    const cache = useRef(null);
+    if (options === undefined)
+        return value;
+    const previous = cache.current;
+    if (previous !== null && Object.is(previous.input, value)) {
+        return previous.selected; // SEL6: selector purity, not re-run
+    }
+    const selected = options.select(value); // a throw propagates (SEL5)
+    if (previous !== null &&
+        selectedEquals(options.equality, previous.selected, selected)) {
+        previous.input = value;
+        return previous.selected;
+    }
+    cache.current = { input: value, selected };
+    return selected;
+}
+/**
+ * The raw-slice stabilization layer (SEL4): 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.
+ */
+export function useStableResult(route, fingerprint, compute) {
+    const cache = useRef(null);
+    const cached = cache.current;
+    if (cached !== null &&
+        cached.route === route &&
+        cached.fingerprint === fingerprint) {
+        return cached.value;
+    }
+    // Cleared BEFORE computing (SEL8): a throwing decode must not strand the
+    // previous entry, or the rerender after an error boundary reset would
+    // serve a stale value under the new fingerprint.
+    cache.current = null;
+    const value = compute();
+    cache.current = { fingerprint, route, value };
+    return value;
+}
+/**
+ * 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).
+ */
+function declaredSearchKeys(route) {
+    const config = route["~search"];
+    if (typeof config !== "object" || config === null)
+        return [];
+    if (config["~kind"] === "raw-search")
+        return null;
+    return Object.keys(config);
+}
+/** Dynamic segment names from the define-time `~segments` token cache. */
+function dynamicSegmentNames(route) {
+    const names = [];
+    for (const segment of route["~segments"]) {
+        if (segment.kind !== "static")
+            names.push(segment.name);
+    }
+    return names;
+}
+/**
+ * `JSON.stringify`'d `[key, value]` slice of a record source — unambiguous
+ * against concatenation collisions; absent and explicit-`undefined` keys
+ * both fingerprint as `null`, matching the decode's absence semantics.
+ * `Object.hasOwn` mirrors the core readers: an inherited member (a declared
+ * key named `"constructor"`) is absence to the decode, so it must be absence
+ * to the fingerprint too.
+ */
+function recordFingerprint(keys, source) {
+    return JSON.stringify(keys.map((key) => [
+        key,
+        Object.hasOwn(source, key) ? (source[key] ?? null) : null,
+    ]));
+}
+/** SEL3: `Object.is`, widened one level by the `"shallow"` opt-in. */
+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).
+ */
+function shallowEqual(a, b) {
+    if (typeof a !== "object" ||
+        a === null ||
+        typeof b !== "object" ||
+        b === null) {
+        return false;
+    }
+    if (Array.isArray(a) || Array.isArray(b)) {
+        return (Array.isArray(a) &&
+            Array.isArray(b) &&
+            a.length === b.length &&
+            a.every((element, index) => Object.is(element, b[index])));
+    }
+    const aRecord = a;
+    const bRecord = b;
+    const aKeys = Object.keys(aRecord);
+    return (aKeys.length === Object.keys(bRecord).length &&
+        aKeys.every((key) => Object.hasOwn(bRecord, key) && Object.is(aRecord[key], bRecord[key])));
+}

package/dist/watch.d.ts

@@ -0,0 +1,39 @@
+/** Handle returned by {@link watchRouteDirs}. */
+export interface RouteDirsWatcher {
+    /** Stop watching and drop any pending debounced rescan. Idempotent. */
+    close(): void;
+}
+/** Options for {@link watchRouteDirs}. */
+export interface WatchRouteDirsOptions {
+    /** Debounce window in milliseconds; defaults to {@link DEFAULT_DEBOUNCE_MS}. */
+    debounceMs?: number;
+    /**
+     * Absolute paths whose events are ignored — the artifact file, so a
+     * regeneration write can't re-trigger the watcher (TR5 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.
+     */
+    onError?: (error: unknown) => void;
+    /** The regenerate callback — full rescan → write-if-changed (TR5). */
+    onRescan: () => void;
+}
+/** TR5: ~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
+ * `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`.
+ */
+export declare function watchRouteDirs(dirs: readonly string[], options: WatchRouteDirsOptions): RouteDirsWatcher;

package/dist/watch.js

@@ -0,0 +1,87 @@
+import { statSync, watch } from "node:fs";
+import { resolve } from "node:path";
+/** TR5: ~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).
+ */
+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
+ * `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`.
+ */
+export function watchRouteDirs(dirs, options) {
+    const { debounceMs = DEFAULT_DEBOUNCE_MS, ignorePaths = [], onError, onRescan, } = options;
+    const ignored = new Set(ignorePaths.map((path) => resolve(path)));
+    let timer;
+    const schedule = () => {
+        clearTimeout(timer);
+        timer = setTimeout(() => {
+            try {
+                onRescan();
+            }
+            catch (error) {
+                // A throwing regeneration must not kill the watcher (TR5 non-fatal).
+                onError?.(error);
+            }
+        }, debounceMs);
+    };
+    const watchers = [];
+    for (const dir of dirs) {
+        let watcher;
+        try {
+            // Linux's userland recursive watcher (Node <= 24.18.0,
+            // internal/fs/recursive_watch.js) swallows ENOENT under the default
+            // throwIfNoEntry — a missing dir silently never watches, with no throw
+            // and no 'error' event. Stat first so the missing-dir skip is
+            // synchronous and identical on every platform.
+            if (statSync(dir, { throwIfNoEntry: false }) === undefined)
+                continue;
+            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).
+                if (filename !== null) {
+                    if (ignored.has(resolve(dir, filename)))
+                        return;
+                    // Windows reports backslash-joined relative paths; split on both.
+                    const segments = filename.split(/[/\\]/);
+                    if (segments.some((segment) => IGNORED_SEGMENTS.has(segment)))
+                        return;
+                }
+                schedule();
+            });
+        }
+        catch (error) {
+            // TR5: watcher failure is non-fatal — dev continues in stale-types
+            // mode, and the other dir's watcher (if any) keeps running.
+            onError?.(error);
+            continue;
+        }
+        watcher.on("error", (error) => {
+            onError?.(error);
+        });
+        watchers.push(watcher);
+    }
+    let closed = false;
+    return {
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            clearTimeout(timer);
+            for (const watcher of watchers)
+                watcher.close();
+        },
+    };
+}

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

@@ -0,0 +1,44 @@
+/** Options for {@link withTypedRoutes} (TR4). */
+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
+     * 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.
+     */
+    strict?: boolean;
+}
+/** Next config-function form: `(phase, ctx) => config`, possibly async. */
+type ConfigFunction<C> = (phase: string, ctx: unknown) => C | Promise<C>;
+/** @internal Test seam: the number of live dev-watcher singletons. */
+export declare function devWatcherCountForTests(): number;
+/**
+ * @internal Test seam: close every dev watcher, release the pidfile locks,
+ * and clear the log-once state. Also required between tests on Windows —
+ * an open watch handle blocks temp-dir removal.
+ */
+export declare function resetDevWatchersForTests(): void;
+/**
+ * Wrap a Next config with route-registry generation (TR4). 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).
+ * - 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).
+ */
+export declare function withTypedRoutes<C extends object>(config: C | ConfigFunction<C>, options?: WithTypedRoutesOptions): ConfigFunction<C>;
+export {};