@paramour-js/next 0.1.0

package/dist/list/render.js

@@ -0,0 +1,132 @@
+/**
+ * `--json` payload. Keys are alphabetical; a route with no definition
+ * carries `definition: null` rather than an absent member — friendlier to
+ * both `jq` and exactOptionalPropertyTypes consumers.
+ */
+export function buildListJson(report) {
+    return {
+        appRoutes: report.appRoutes.map(routeJson),
+        duplicates: report.duplicates,
+        loadFailures: report.loadFailures,
+        orphanDefinitions: report.orphans.map(definitionJson),
+        pagesRoutes: report.pagesRoutes.map(routeJson),
+    };
+}
+/**
+ * `integer`, `enum(a, b)`, `string[]`, with annotations in fixed order:
+ * presence, default, catch.
+ */
+export function formatCodec(description) {
+    let base = description.enumMembers === undefined
+        ? description.kind
+        : `enum(${description.enumMembers.join(", ")})`;
+    if (description.arity === "many")
+        base += "[]";
+    const notes = [];
+    if (description.presence === "optional")
+        notes.push("(optional)");
+    if (description.defaultValue !== undefined) {
+        notes.push(description.defaultValue.kind === "value"
+            ? `(default: ${description.defaultValue.wire})`
+            : "(default: factory)");
+    }
+    if (description.caught)
+        notes.push("(catch)");
+    return [base, ...notes].join(" ");
+}
+/** Human report; one string per output line. */
+export function renderListReport(report) {
+    const lines = [
+        ...renderGroup("app", report.appRoutes),
+        ...renderGroup("pages", report.pagesRoutes),
+    ];
+    if (lines.length === 0)
+        lines.push("no routes found");
+    if (report.orphans.length > 0) {
+        lines.push("", "definitions with no filesystem route:");
+        for (const orphan of report.orphans) {
+            lines.push(`  ⚠ ${orphan.description.path} (${orphan.description.router})  ${orphan.file}`);
+        }
+    }
+    if (report.duplicates.length > 0) {
+        lines.push("", "duplicate definitions (first wins):");
+        for (const duplicate of report.duplicates) {
+            lines.push(`  ⚠ ${duplicate.path} (${duplicate.router})  ${duplicate.file} (already defined in ${duplicate.firstFile})`);
+        }
+    }
+    if (report.loadFailures.length > 0) {
+        lines.push("", `${String(report.loadFailures.length)} module${report.loadFailures.length === 1 ? "" : "s"} failed to load (definitions in them are not shown):`);
+        for (const failure of report.loadFailures) {
+            lines.push(`  ⚠ ${failure.file}: ${failure.message}`);
+        }
+    }
+    return lines;
+}
+function definitionJson(definition) {
+    return {
+        exportName: definition.exportName,
+        file: definition.file,
+        params: definition.description.params,
+        path: definition.description.path,
+        router: definition.description.router,
+        search: definition.description.search,
+    };
+}
+/**
+ * A param's codec is per-element (D5/D6) — the array-ness comes from the
+ * segment kind, so catch-all params render with the `[]` suffix plus a
+ * segment note.
+ */
+function formatParam(param) {
+    if (param.segmentKind === "single")
+        return formatCodec(param);
+    const note = param.segmentKind === "catchall" ? "(catch-all)" : "(optional catch-all)";
+    return `${formatCodec({ ...param, arity: "many" })} ${note}`;
+}
+function renderGroup(router, routes) {
+    if (routes.length === 0)
+        return [];
+    const lines = [`${router} routes (${String(routes.length)}):`];
+    const width = Math.max(...routes.map((route) => route.path.length));
+    for (const route of routes) {
+        const annotation = route.definition === null
+            ? "⚠ filesystem only (no route definition found)"
+            : route.definition.file;
+        lines.push(`  ${route.path.padEnd(width)}  ${annotation}`);
+        if (route.definition !== null) {
+            lines.push(...renderShape(route.definition.description));
+        }
+    }
+    lines.push("");
+    return lines;
+}
+function renderKeys(keys, indent) {
+    const names = Object.keys(keys);
+    const width = Math.max(...names.map((name) => name.length)) + 1;
+    return names.map((name) => `${indent}${`${name}:`.padEnd(width)} ${keys[name] ?? ""}`);
+}
+function renderShape(description) {
+    const lines = [];
+    const params = Object.entries(description.params);
+    if (params.length > 0) {
+        lines.push("    params:");
+        lines.push(...renderKeys(Object.fromEntries(params.map(([name, param]) => [name, formatParam(param)])), "      "));
+    }
+    if (description.search.kind === "raw") {
+        lines.push("    search: (rawSearch schema)");
+    }
+    else if (description.search.kind === "codecs") {
+        lines.push("    search:");
+        lines.push(...renderKeys(Object.fromEntries(Object.entries(description.search.keys).map(([name, codec]) => [
+            name,
+            formatCodec(codec),
+        ])), "      "));
+    }
+    return lines;
+}
+function routeJson(route) {
+    return {
+        definition: route.definition === null ? null : definitionJson(route.definition),
+        path: route.path,
+    };
+}

package/dist/lock.d.ts

@@ -0,0 +1,29 @@
+/** Result of {@link acquireWatcherLock}. */
+export interface AcquireLockResult {
+    /** `false` when a live owner holds the lock — do not start a watcher. */
+    acquired: boolean;
+    /** The live owner's PID, set only when declined — for the caller's log. */
+    ownerPid?: number;
+    /**
+     * Set only when acquired: remove the lock and deregister the process
+     * cleanup handlers. Idempotent; safe to call from the caller's own signal
+     * handling.
+     */
+    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.
+ */
+export declare function acquireWatcherLock(lockPath: string): AcquireLockResult;
+/**
+ * The one canonical pidfile location (TR6): 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

@@ -0,0 +1,88 @@
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+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.
+ */
+export function acquireWatcherLock(lockPath) {
+    const ownerPid = readOwnerPid(lockPath);
+    if (ownerPid !== undefined && ownerPid !== process.pid && isAlive(ownerPid)) {
+        return { acquired: false, ownerPid };
+    }
+    mkdirSync(dirname(lockPath), { recursive: true });
+    writeFileSync(lockPath, String(process.pid));
+    let released = false;
+    const release = () => {
+        if (released)
+            return;
+        released = true;
+        process.removeListener("exit", release);
+        process.removeListener("SIGINT", onSigint);
+        process.removeListener("SIGTERM", onSigterm);
+        try {
+            // Only remove a lock that is still ours — a successor may have taken
+            // over after our probe found this process dead (it wasn't).
+            if (readOwnerPid(lockPath) === process.pid) {
+                rmSync(lockPath, { force: true });
+            }
+        }
+        catch {
+            // Best-effort (TR6): a leftover lock self-heals via the liveness
+            // probe on the next startup.
+        }
+    };
+    const reraise = (signal) => {
+        release();
+        // Re-raise so the default termination — or Next's own handlers — still
+        // apply; `once` already removed this listener.
+        process.kill(process.pid, signal);
+    };
+    const onSigint = () => {
+        reraise("SIGINT");
+    };
+    const onSigterm = () => {
+        reraise("SIGTERM");
+    };
+    process.once("exit", release);
+    process.once("SIGINT", onSigint);
+    process.once("SIGTERM", onSigterm);
+    return { acquired: true, release };
+}
+/**
+ * The one canonical pidfile location (TR6): 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). */
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM: the process exists but isn't ours to signal — alive.
+        return error.code === "EPERM";
+    }
+}
+/** The PID in the lock file, or `undefined` when absent/unparseable. */
+function readOwnerPid(lockPath) {
+    let content;
+    try {
+        content = readFileSync(lockPath, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const trimmed = content.trim();
+    return PID_RE.test(trimmed) ? Number(trimmed) : undefined;
+}

package/dist/pages.d.ts

@@ -0,0 +1,49 @@
+import { type AnyPagesRoute, type InferRouteParams, type SafeResult, type SearchOutputOf } from "paramour";
+import { type SelectOptions } from "./select.js";
+export type { SelectOptions } from "./select.js";
+/**
+ * Pages Router hooks (design-06 PR5/PR6, design-07). Deliberately NO
+ * `"use client"` directive on this module: the directive is an App Router
+ * (RSC graph) concept, meaningless in a `pages/` bundle (PR2).
+ *
+ * `useRouter().query` is one merged bag (route params + search), and on a
+ * statically-optimized page it is `{}` until `router.isReady` flips after
+ * hydration — a platform fact the result type admits as a third state
+ * instead of papering over (PR5). On `getServerSideProps` pages the FIRST
+ * render is already `isReady: true` with a populated query (design-06
+ * spike 3), so the `pending` arm never surfaces there.
+ *
+ * Deliberately NO `OrThrow` variants (PR6): throwing on `pending` would
+ * flash the error boundary on every statically-optimized page's first
+ * render, and returning `T | undefined` would make the name a lie. The
+ * three-state union forcing the check IS the feature — and users who know
+ * their page has `getServerSideProps` should be reading typed props from
+ * `route.parseContext(ctx)` (PR10) rather than reaching for a client hook.
+ *
+ * Both hooks are gated to `AnyPagesRoute` (PR3) and share the /app hooks'
+ * design-07 layering: raw-slice stabilization keyed on the declared slice of
+ * `query` (+ `isReady`), then an optional `{ select }` projection with
+ * result-equality checking — the `pending` arm passes through the selector
+ * untouched (SEL2), and `PENDING` itself is one referentially stable object.
+ */
+/**
+ * Three-state result for the pages hooks (PR5): core's `SafeResult` plus a
+ * `pending` member for the pre-`isReady` render of a statically-optimized
+ * page. Literally `SafeResult<T> | { status: "pending" }` (PR12), so both
+ * routers' results destructure identically.
+ */
+export type RouterResult<T> = SafeResult<T> | {
+    status: "pending";
+};
+/**
+ * Decoded route params as a {@link RouterResult} (PR5), optionally projected
+ * through `options.select` (design-07 SEL1/SEL2).
+ */
+export declare function useRouteParams<R extends AnyPagesRoute>(route: R): RouterResult<InferRouteParams<R>>;
+export declare function useRouteParams<R extends AnyPagesRoute, U>(route: R, options: SelectOptions<InferRouteParams<R>, U>): RouterResult<U>;
+/**
+ * Decoded search params as a {@link RouterResult} (PR5), optionally projected
+ * through `options.select` (design-07 SEL1/SEL2).
+ */
+export declare function useSearch<R extends AnyPagesRoute>(route: R): RouterResult<SearchOutputOf<R["~search"]>>;
+export declare function useSearch<R extends AnyPagesRoute, U>(route: R, options: SelectOptions<SearchOutputOf<R["~search"]>, U>): RouterResult<U>;

package/dist/pages.js

@@ -0,0 +1,62 @@
+import { useRouter } from "next/router";
+import { ParamourError, safeDecodeParams, safeDecodeSearch, } from "paramour";
+import { paramsFingerprint, PENDING_FINGERPRINT, queryFingerprint, useSelectedResult, useStableResult, } from "./select.js";
+/** Referentially stable across every pending render. */
+const PENDING = { status: "pending" };
+export function useRouteParams(route, options) {
+    const { isReady, query } = usePagesRouter();
+    const result = useStableResult(route, isReady ? paramsFingerprint(route, query) : PENDING_FINGERPRINT, () => {
+        if (!isReady)
+            return PENDING;
+        // The merged query is a legal params source as-is: decodeParams reads
+        // only the route's own segment names, never unknown keys. R5: next/router
+        // has already percent-decoded `query`, so skip core's decode to avoid a
+        // double-decode (`/product/a%2520b` → `"a%20b"` must survive as-is).
+        return safeDecodeParams(route, query, { percentDecode: false });
+    });
+    return useSelectedResult(result, options);
+}
+export function useSearch(route, options) {
+    const { isReady, query } = usePagesRouter();
+    const result = useStableResult(route, isReady ? queryFingerprint(route, query) : PENDING_FINGERPRINT, () => {
+        if (!isReady)
+            return PENDING;
+        return safeDecodeSearch(route, omitPathParams(query, route));
+    });
+    return useSelectedResult(result, options);
+}
+/**
+ * `query` minus the route's own path-param names (PR5) — the client twin of
+ * `parseContext`'s server-side subtraction (core route.ts, PR10). Entries →
+ * fromEntries so a hostile `?__proto__=` key stays an ordinary own property
+ * (decodeParams's ethos). Names come from the define-time `~segments` token
+ * cache, so nothing re-tokenizes per render.
+ */
+function omitPathParams(query, route) {
+    const names = new Set();
+    for (const segment of route["~segments"]) {
+        if (segment.kind !== "static")
+            names.add(segment.name);
+    }
+    return Object.fromEntries(Object.entries(query).filter(([key]) => !names.has(key)));
+}
+/**
+ * `useRouter` with the one failure the brand cannot catch translated (PR5):
+ * in a hybrid project a component rendered under `app/` can legally hold a
+ * pages-branded route, but `next/router` has no mount there and throws
+ * "NextRouter was not mounted" — a message pointing at the wrong fix
+ * (component placement is invisible to the type system). Rethrow a
+ * `ParamourError` naming the actual mistake; everything else propagates.
+ */
+function usePagesRouter() {
+    try {
+        return useRouter();
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            error.message.includes("NextRouter was not mounted")) {
+            throw new ParamourError('pages hooks were rendered under the App Router, where next/router is never mounted — import this component\'s hooks from "@paramour-js/next/app" and pass it an app route instead (PR5)', { cause: error });
+        }
+        throw error;
+    }
+}

package/dist/run-cli.d.ts

@@ -0,0 +1,11 @@
+import { type CliIo } from "./cli-io.js";
+export { type CliIo } from "./cli-io.js";
+/**
+ * @internal The CLI dispatcher (TR7), in-process testable: returns the exit
+ * code instead of exiting. The exit-code contract holds across every
+ * command: 0 success, 1 "the thing you asked me to verify is not true"
+ * (`check`/`generate --check` drift, `doctor` failures) ONLY, 2
+ * usage/config/operational errors. Each command owns its flags parse and
+ * usage text; this layer only routes the first positional.
+ */
+export declare function runCli(argv: readonly string[], io?: CliIo): Promise<number>;

package/dist/run-cli.js

@@ -0,0 +1,53 @@
+import { resolveIo } from "./cli-io.js";
+import { runDoctor } from "./commands/doctor.js";
+import { runGenerate } from "./commands/generate.js";
+import { runInit } from "./commands/init.js";
+import { runList } from "./commands/list.js";
+export {} from "./cli-io.js";
+// Alphabetical; the unknown-command message derives from these keys.
+const COMMANDS = {
+    check: (argv, io) => runGenerate(argv, io, "check"),
+    doctor: runDoctor,
+    generate: (argv, io) => runGenerate(argv, io, "generate"),
+    init: runInit,
+    list: runList,
+};
+const USAGE = [
+    "Usage: paramour <command> [options]",
+    "",
+    "Commands:",
+    "  check     verify the artifact is current; exit 1 on drift, never writes",
+    "  doctor    diagnose the project's paramour setup",
+    "  generate  generate paramour-env.d.ts from the app and pages directories",
+    "  init      set up paramour in this project",
+    "  list      print every route with its params/search shape",
+    "",
+    "Run `paramour <command> --help` for that command's options.",
+].join("\n");
+/**
+ * @internal The CLI dispatcher (TR7), in-process testable: returns the exit
+ * code instead of exiting. The exit-code contract holds across every
+ * command: 0 success, 1 "the thing you asked me to verify is not true"
+ * (`check`/`generate --check` drift, `doctor` failures) ONLY, 2
+ * usage/config/operational errors. Each command owns its flags parse and
+ * usage text; this layer only routes the first positional.
+ */
+export async function runCli(argv, io = {}) {
+    const { stderr, stdout } = resolveIo(io);
+    const [command, ...rest] = argv;
+    if (command === undefined) {
+        stderr(USAGE);
+        return 2;
+    }
+    if (command === "--help" || command === "-h" || command === "help") {
+        stdout(USAGE);
+        return 0;
+    }
+    const run = COMMANDS[command];
+    if (run === undefined) {
+        stderr(`paramour: unknown command "${command}" (expected one of: ${Object.keys(COMMANDS).join(", ")})`);
+        stderr(USAGE);
+        return 2;
+    }
+    return run(rest, io);
+}

package/dist/scan-app.d.ts

@@ -0,0 +1,30 @@
+import type { Dirent } from "node:fs";
+/** Next's default `pageExtensions` — extensions only, no leading dot (TR2). */
+export declare const DEFAULT_PAGE_EXTENSIONS: readonly ["tsx", "ts", "jsx", "js"];
+/**
+ * Whether a directory entry should be treated as a FILE for routing: a real
+ * file, or a symlink whose target is a regular file. `Dirent.isFile()` is
+ * false for a symlink even when it points at a file, yet Next resolves and
+ * serves symlinked `page`/`route` files (common in pnpm-linked monorepos), so
+ * dropping them would omit routes that Next actually serves (Bug 4, TR2). A
+ * symlink to a DIRECTORY returns false — directory symlinks stay not-followed,
+ * the existing v1 stance — and a broken link (statSync throws ENOENT) also
+ * returns false, i.e. is skipped silently, matching Next's own tolerance of
+ * broken links.
+ */
+export declare function resolvesToFile(entry: Dirent, dir: string): boolean;
+/**
+ * Walk an app dir and return the sorted union of URL-shaped route paths —
+ * exactly the strings `defineAppRoute` accepts (TR2, RL2). Pure `fs.readdir`
+ * recursion; no dependency on Next internals. Two page files resolving to
+ * one URL path — `(a)/x` + `(b)/x` group twins, or `page.tsx` + `page.jsx`
+ * extension twins — throw a {@link RouteCollisionError} instead of being
+ * deduped (PR4/PR9 alignment ruling): that state is Next's own build error,
+ * and deduping would emit an artifact for a project that cannot build.
+ *
+ * `route.<ext>` handlers are scanned but never emitted (handler typing is
+ * deferred, §14). They exist only to catch the states Next refuses to build:
+ * a page and a route handler at the same URL path ("conflicting route and
+ * page"), and two route handlers at the same path — both throw (PR9).
+ */
+export declare function scanAppRoutes(appDir: string, pageExtensions?: readonly string[]): string[];

package/dist/scan-app.js

@@ -0,0 +1,149 @@
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { assertNoStructuralCollisions, RouteCollisionError, } from "./collisions.js";
+/** Next's default `pageExtensions` — extensions only, no leading dot (TR2). */
+export const DEFAULT_PAGE_EXTENSIONS = ["tsx", "ts", "jsx", "js"];
+/**
+ * Interception markers `(.)`/`(..)`/`(...)` (TR2, RL2 / §15.5). A prefix
+ * match, so chained forms like `(..)(..)segment` are caught too; tested
+ * BEFORE the route-group test so `(.)foo` is never misread as a group.
+ */
+const INTERCEPTION_PREFIX = /^\(\.{1,3}\)/;
+/**
+ * Next's documented `%5F` escape (Next "Project Organization" → Private
+ * Folders): a folder whose name begins with a percent-encoded underscore
+ * serves a URL segment beginning with a literal `_`, opting that segment out
+ * of the private-folder convention — `app/%5Fsettings/page.tsx` serves
+ * `/_settings`. The escape is defined for the LEADING position only. Because
+ * RFC 3986 percent-encoding is case-insensitive on its hex digits (and this
+ * could not be pinned against Next's source from here), both `%5F` and `%5f`
+ * are decoded defensively (Bug 8, TR2). The fs name stays raw for error
+ * messages; only the emitted URL segment is decoded.
+ */
+const LEADING_ESCAPED_UNDERSCORE = /^%5[Ff]/;
+/** Route groups `(group)` — stripped from the emitted path (TR2, RL2). */
+const ROUTE_GROUP = /^\(.*\)$/;
+/**
+ * Whether a directory entry should be treated as a FILE for routing: a real
+ * file, or a symlink whose target is a regular file. `Dirent.isFile()` is
+ * false for a symlink even when it points at a file, yet Next resolves and
+ * serves symlinked `page`/`route` files (common in pnpm-linked monorepos), so
+ * dropping them would omit routes that Next actually serves (Bug 4, TR2). A
+ * symlink to a DIRECTORY returns false — directory symlinks stay not-followed,
+ * the existing v1 stance — and a broken link (statSync throws ENOENT) also
+ * returns false, i.e. is skipped silently, matching Next's own tolerance of
+ * broken links.
+ */
+export function resolvesToFile(entry, dir) {
+    if (entry.isFile())
+        return true;
+    if (!entry.isSymbolicLink())
+        return false;
+    try {
+        // statSync follows the link (unlike the withFileTypes Dirent, which
+        // reflects the link itself).
+        return statSync(join(dir, entry.name)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Walk an app dir and return the sorted union of URL-shaped route paths —
+ * exactly the strings `defineAppRoute` accepts (TR2, RL2). Pure `fs.readdir`
+ * recursion; no dependency on Next internals. Two page files resolving to
+ * one URL path — `(a)/x` + `(b)/x` group twins, or `page.tsx` + `page.jsx`
+ * extension twins — throw a {@link RouteCollisionError} instead of being
+ * deduped (PR4/PR9 alignment ruling): that state is Next's own build error,
+ * and deduping would emit an artifact for a project that cannot build.
+ *
+ * `route.<ext>` handlers are scanned but never emitted (handler typing is
+ * deferred, §14). They exist only to catch the states Next refuses to build:
+ * a page and a route handler at the same URL path ("conflicting route and
+ * page"), and two route handlers at the same path — both throw (PR9).
+ */
+export function scanAppRoutes(appDir, pageExtensions = DEFAULT_PAGE_EXTENSIONS) {
+    // Path → the fs path (relative to appDir) that produced it, so a collision
+    // can name both files. `out` holds page routes (emitted); `routeOut` holds
+    // route-handler paths (never emitted — collision detection only).
+    const out = new Map();
+    const routeOut = new Map();
+    const pageFileNames = new Set(pageExtensions.map((ext) => `page.${ext}`));
+    const routeFileNames = new Set(pageExtensions.map((ext) => `route.${ext}`));
+    walk(appDir, [], [], pageFileNames, routeFileNames, out, routeOut);
+    // PR9: a page and a route handler resolving to one URL path is Next's
+    // "conflicting route and page" build error — no valid artifact exists, so
+    // throw rather than emit the page and silently drop the handler. Sorted so
+    // the reported pair is deterministic across platforms.
+    for (const [path, routeFile] of [...routeOut].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) {
+        const pageFile = out.get(path);
+        if (pageFile !== undefined) {
+            throw new RouteCollisionError(`app route collision at "${path}": page ${pageFile} and route handler ${routeFile} resolve to the same path, which Next refuses to build (conflicting route and page) (PR9)`);
+        }
+    }
+    // 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: "app" })));
+    return paths;
+}
+function walk(dir, urlSegments, fsSegments, pageFileNames, routeFileNames, out, routeOut) {
+    // 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 (Bug 4). Directory
+        // symlinks fall through to the directory guard below, which is false for
+        // a symlink Dirent, so their subtree is skipped — not followed (TR2).
+        if (resolvesToFile(entry, dir)) {
+            // Exact, case-sensitive `page.<ext>` / `route.<ext>` match (TR2). Pages
+            // are emitted; route handlers are tracked separately (never emitted —
+            // handler typing is §14) purely to detect the build errors above (PR9).
+            const isPage = pageFileNames.has(name);
+            const isRoute = !isPage && routeFileNames.has(name);
+            if (isPage || isRoute) {
+                const path = urlSegments.length === 0 ? "/" : `/${urlSegments.join("/")}`;
+                const file = [...fsSegments, name].join("/");
+                const target = isPage ? out : routeOut;
+                const existing = target.get(path);
+                if (existing !== undefined) {
+                    throw new RouteCollisionError(isPage
+                        ? `app route collision at "${path}": ${existing} and ${file} resolve to the same path (PR9)`
+                        : `app route collision at "${path}": ${existing} and ${file} both declare a route handler at the same path, which Next refuses to build (PR9)`);
+                }
+                target.set(path, file);
+            }
+            continue;
+        }
+        // Symlinked directories are deliberately not followed (TR2 v1 stance):
+        // `resolvesToFile` returned false and `isDirectory()` is false for the
+        // link Dirent, so the subtree is skipped here.
+        if (!entry.isDirectory())
+            continue;
+        // TR2 skip rules: private folders, parallel slots, interception routes —
+        // each skips the entire subtree, pages at any depth included. The `_`
+        // test reads the raw fs name, so `%5F`-escaped folders (which do NOT
+        // start with `_`) are correctly NOT skipped (Bug 8).
+        if (name.startsWith("_"))
+            continue;
+        if (name.startsWith("@"))
+            continue;
+        if (INTERCEPTION_PREFIX.test(name))
+            continue;
+        if (ROUTE_GROUP.test(name)) {
+            // Group stripped: recurse with the SAME url segments (TR2).
+            walk(join(dir, name), urlSegments, [...fsSegments, name], pageFileNames, routeFileNames, out, routeOut);
+            continue;
+        }
+        // Dynamic segments `[id]` / `[...slug]` / `[[...slug]]` pass through
+        // verbatim (TR2, RL2 URL-shaped literals). A leading `%5F` decodes to `_`
+        // for the emitted URL segment so it string-matches the served URL; the fs
+        // name stays raw for error messages, and the decoded form participates in
+        // collision detection via the `out` Map key (Bug 8).
+        const urlSegment = name.replace(LEADING_ESCAPED_UNDERSCORE, "_");
+        walk(join(dir, name), [...urlSegments, urlSegment], [...fsSegments, name], pageFileNames, routeFileNames, out, routeOut);
+    }
+}

package/dist/scan-pages.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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 declare function scanPagesRoutes(pagesDir: string, pageExtensions?: readonly string[]): string[];