@paramour-js/next 0.4.0 → 0.4.1

package/dist/observe.js

@@ -1,8 +1,8 @@
 import { useRef } from "react";
 import { emitObservation } from "./devtools-seam.js";
 /**
- * App-flavor navigate capability (DT8): `next/navigation`'s `replace`
- * returns void and resolves the basePath-/locale-relative join itself.
+ * App-flavor navigate capability: `next/navigation`'s `replace` returns void
+ * and resolves the basePath-/locale-relative join itself.
  */
 export function makeAppNavigate(router, pathname) {
     return (search) => {
@@ -10,8 +10,8 @@ export function makeAppNavigate(router, pathname) {
     };
 }
 /**
- * Pages-flavor navigate capability (DT8): `next/router`'s `replace` returns
- * a promise that REJECTS on routine navigation aborts (rapid re-commits
+ * Pages-flavor navigate capability: `next/router`'s `replace` returns a
+ * promise that REJECTS on routine navigation aborts (rapid re-commits
  * from the panel), marked with next's `cancelled` discriminant — those must
  * not surface as unhandled rejections. Anything else is a real failure
  * (render error, route-info error) silently discarding the user's edit, so

package/dist/pages.d.ts

@@ -2,57 +2,56 @@ import { type AnyPagesRoute, type InferRouteParams, type SafeResult, type Search
 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).
+ * Pages Router hooks. Deliberately NO `"use client"` directive on this
+ * module: the directive is an App Router (RSC graph) concept, meaningless in
+ * a `pages/` bundle.
  *
  * `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.
+ * instead of papering over. On `getServerSideProps` pages the FIRST render
+ * is already `isReady: true` with a populated query, 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.
+ * Deliberately NO `OrThrow` variants: 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)` 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
+ * Both hooks are gated to `AnyPagesRoute` and share the /app hooks'
+ * 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.
+ * untouched, and `PENDING` itself is one referentially stable object.
  *
- * Devtools instrumentation (design-12): each hook reports through the
- * shared emitter in observe.ts — `observe` from inside the `useStableResult`
- * compute callback (DT4 — the fingerprint cache miss IS the decode-change
- * dedup; see app.ts's fuller account), `refresh` after it for pathname
- * moves under an unchanged decode (DT8). The `pending` arm emits as a
- * first-class observation (DT11), keyed by `PENDING_FINGERPRINT` so the
- * pre-`isReady` render reports exactly once. Every emit sits behind
- * `process.env.NODE_ENV !== "production"` (DT6).
+ * Devtools instrumentation: each hook reports through the shared emitter in
+ * observe.ts — `observe` from inside the `useStableResult` compute callback
+ * (the fingerprint cache miss IS the decode-change dedup; see app.ts's
+ * fuller account), `refresh` after it for pathname moves under an unchanged
+ * decode. The `pending` arm emits as a first-class observation, keyed by
+ * `PENDING_FINGERPRINT` so the pre-`isReady` render reports exactly once.
+ * Every emit sits behind `process.env.NODE_ENV !== "production"`.
  */
 /**
- * Three-state result for the pages hooks (PR5): core's `SafeResult` plus a
+ * Three-state result for the pages hooks: 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.
+ * page. Literally `SafeResult<T> | { status: "pending" }`, 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).
+ * Decoded route params as a {@link RouterResult}, optionally projected
+ * through `options.select`.
  */
 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).
+ * Decoded search params as a {@link RouterResult}, optionally projected
+ * through `options.select`.
  */
 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

@@ -80,15 +80,15 @@ export function useSearch(route, options) {
 }
 /**
  * `asPath`'s path part: basePath-/locale-relative — exactly what
- * `replace()` expects back — so the panel's search-only string (DT8)
- * resolves without doubling a configured basePath.
+ * `replace()` expects back — so the panel's search-only string resolves
+ * without doubling a configured basePath.
  */
 function asPathPathname(asPath) {
     return asPath.split(/[#?]/)[0] ?? "/";
 }
 /**
- * `query` minus the route's own path-param names (PR5) — the client twin of
- * `parseContext`'s server-side subtraction (core route.ts, PR10). Entries →
+ * `query` minus the route's own path-param names — the client twin of
+ * `parseContext`'s server-side subtraction (core route.ts). 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.
@@ -102,19 +102,19 @@ function omitPathParams(query, route) {
     return Object.fromEntries(Object.entries(query).filter(([key]) => !names.has(key)));
 }
 /**
- * Real-Next fallback for the adapter seam (design-16 TA3): the /testing
- * provider overrides the read through {@link PagesNavigationContext}; with
+ * Real-Next fallback for the adapter seam: the /testing provider overrides
+ * the read through {@link PagesNavigationContext}; with
  * no provider mounted the context's `null` default resolves here, so
  * production behavior (and this module's `next/router.js`-only bundle
  * graph, per dist.test.ts) is unchanged. The adapter is resolved via an
  * unconditional `useContext` BEFORE the try below, exactly where the direct
  * call previously sat, keeping hook call order identical across renders and
- * across provider presence (TA4).
+ * across provider presence.
  */
 const realPagesAdapter = { useRouter };
 /**
- * `useRouter` with the one failure the brand cannot catch translated (PR5):
- * in a hybrid project a component rendered under `app/` can legally hold a
+ * `useRouter` with the one failure the brand cannot catch translated: 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
@@ -130,7 +130,7 @@ function usePagesRouter() {
     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 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', { cause: error });
         }
         throw error;
     }

package/dist/run-cli.d.ts

@@ -1,7 +1,7 @@
 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
+ * @internal The CLI dispatcher, 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

package/dist/run-cli.js

@@ -25,7 +25,7 @@ const USAGE = [
     "Run `paramour <command> --help` for that command's options.",
 ].join("\n");
 /**
- * @internal The CLI dispatcher (TR7), in-process testable: returns the exit
+ * @internal The CLI dispatcher, 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

package/dist/scan-app.d.ts

@@ -1,12 +1,12 @@
 import type { Dirent } from "node:fs";
-/** Next's default `pageExtensions` — extensions only, no leading dot (TR2). */
+/** Next's default `pageExtensions` — extensions only, no leading dot. */
 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
+ * dropping them would omit routes that Next actually serves (Bug 4). 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
@@ -15,16 +15,16 @@ export declare const DEFAULT_PAGE_EXTENSIONS: readonly ["tsx", "ts", "jsx", "js"
 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,
+ * exactly the strings `defineAppRoute` accepts. 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, the
+ * same stance the pages scanner takes: 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).
+ * deferred). 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.
  */
 export declare function scanAppRoutes(appDir: string, pageExtensions?: readonly string[]): string[];

package/dist/scan-app.js

@@ -1,12 +1,12 @@
 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). */
+/** Next's default `pageExtensions` — extensions only, no leading dot. */
 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.
+ * Interception markers `(.)`/`(..)`/`(...)`. 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}\)/;
 /**
@@ -17,18 +17,18 @@ const INTERCEPTION_PREFIX = /^\(\.{1,3}\)/;
  * `/_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.
+ * are decoded defensively (Bug 8). 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). */
+/** Route groups `(group)` — stripped from the emitted path. */
 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
+ * dropping them would omit routes that Next actually serves (Bug 4). 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
@@ -50,17 +50,17 @@ export function resolvesToFile(entry, dir) {
 }
 /**
  * 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,
+ * exactly the strings `defineAppRoute` accepts. 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, the
+ * same stance the pages scanner takes: 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).
+ * deferred). 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.
  */
 export function scanAppRoutes(appDir, pageExtensions = DEFAULT_PAGE_EXTENSIONS) {
     // Path → the fs path (relative to appDir) that produced it, so a collision
@@ -71,20 +71,20 @@ export function scanAppRoutes(appDir, pageExtensions = DEFAULT_PAGE_EXTENSIONS)
     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
+    // 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)`);
+            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)`);
         }
     }
-    // Code-unit sort, never localeCompare — locale independence feeds TR3's
+    // Code-unit sort, never localeCompare — locale independence feeds the
     // byte-identical-on-every-OS guarantee.
     const paths = [...out.keys()].sort();
-    // PR9 structural collisions (different slug names, optional-catch-all
+    // 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;
@@ -97,11 +97,11 @@ function walk(dir, urlSegments, fsSegments, pageFileNames, routeFileNames, out,
         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).
+        // a symlink Dirent, so their subtree is skipped — not followed.
         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).
+            // Exact, case-sensitive `page.<ext>` / `route.<ext>` match. Pages are
+            // emitted; route handlers are tracked separately (never emitted —
+            // handler typing is deferred) purely to detect the build errors above.
             const isPage = pageFileNames.has(name);
             const isRoute = !isPage && routeFileNames.has(name);
             if (isPage || isRoute) {
@@ -111,19 +111,19 @@ function walk(dir, urlSegments, fsSegments, pageFileNames, routeFileNames, out,
                 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)`);
+                        ? `app route collision at "${path}": ${existing} and ${file} resolve to the same path`
+                        : `app route collision at "${path}": ${existing} and ${file} both declare a route handler at the same path, which Next refuses to build`);
                 }
                 target.set(path, file);
             }
             continue;
         }
-        // Symlinked directories are deliberately not followed (TR2 v1 stance):
+        // Symlinked directories are deliberately not followed (the 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 —
+        // 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).
@@ -134,12 +134,12 @@ function walk(dir, urlSegments, fsSegments, pageFileNames, routeFileNames, out,
         if (INTERCEPTION_PREFIX.test(name))
             continue;
         if (ROUTE_GROUP.test(name)) {
-            // Group stripped: recurse with the SAME url segments (TR2).
+            // Group stripped: recurse with the SAME url segments.
             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 `_`
+        // verbatim as 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).

package/dist/scan-pages.d.ts

@@ -1,10 +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).
+ * exactly the strings `definePagesRoute` accepts. 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.
  */
 export declare function scanPagesRoutes(pagesDir: string, pageExtensions?: readonly string[]): string[];

package/dist/scan-pages.js

@@ -3,18 +3,18 @@ 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).
+ * Pages Router scanner. Deliberately a separate walker from `scan-app.ts` —
+ * the rule sets barely overlap (routes live on FILES here, and none of the
+ * app scanner's skip rules apply), and a shared walker would have to take
+ * its rule set as a parameter to be worth having.
  */
 /**
- * Names special to Next at the TOP level of the pages dir only (PR4):
+ * Names special to Next at the TOP level of the pages dir only:
  * `_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).
+ * Every other `_`-prefixed file routes too — co-location under `pages/` was
+ * requested (vercel/next.js#8454) and never implemented.
  */
 const TOP_LEVEL_EXCLUDED = new Set([
     "404",
@@ -25,22 +25,22 @@ const TOP_LEVEL_EXCLUDED = new Set([
 ]);
 /**
  * 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).
+ * exactly the strings `definePagesRoute` accepts. 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.
  */
 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
+    // Code-unit sort, never localeCompare — locale independence feeds the
     // byte-identical-on-every-OS guarantee.
     const paths = [...out.keys()].sort();
-    // PR9 structural collisions (different slug names, optional-catch-all
+    // 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;
@@ -62,10 +62,11 @@ function walk(dir, urlSegments, pageExtensions, out, isTopLevel) {
         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.
+        // real file (Bug 4, the same posture the app scanner takes). 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).
+            // Declaration files match `.ts` but are never pages.
             if (name.endsWith(".d.ts"))
                 continue;
             const ext = matchExtension(name, pageExtensions);
@@ -75,26 +76,27 @@ function walk(dir, urlSegments, pageExtensions, out, isTopLevel) {
             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).
+            // segments included — is a path segment of its own.
             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)`);
+                throw new RouteCollisionError(`pages route collision at "${path}": ${existing} and ${file} resolve to the same path`);
             }
             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.
+        // Symlinked directories are deliberately not followed (the v1 stance,
+        // shared with the app scanner): `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).
+        // routes (API-route typing is deferred to v1.x). NO app-style skip rules
+        // beyond this: `(group)`, `@slot`, `(.)x`, and `_`-prefixed dirs are
+        // ordinary literal segments in the Pages Router.
         if (isTopLevel && name === "api")
             continue;
         walk(join(dir, name), [...urlSegments, name], pageExtensions, out, false);

package/dist/scan.d.ts

@@ -1,20 +1,23 @@
 /**
- * The thin orchestrator over the two scanners (PR8): joint directory
- * discovery, delegation, and the cross-router collision checks (PR9).
+ * The thin orchestrator over the two scanners: joint directory discovery,
+ * delegation, and the cross-router collision checks.
+ */
+/**
+ * The two route dirs of a project; either may be absent — hybrid app/pages
+ * projects are supported, as are app-only and pages-only ones.
  */
-/** 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. */
+/** Result of {@link scanRoutes} — the input shape of the 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
+ * Joint route-dir discovery. 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,
@@ -22,10 +25,10 @@ export interface ScanRoutesResult {
  */
 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
+ * Scan whichever route dirs exist and return both route unions. After each
+ * scanner's own intra-router checks, two cross-router passes run: 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.
  */

package/dist/scan.js

@@ -4,8 +4,8 @@ import { assertNoStructuralCollisions, RouteCollisionError, } from "./collisions
 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
+ * Joint route-dir discovery. 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,
@@ -47,10 +47,10 @@ export function resolveRouteDirs(projectRoot, pageExtensions = DEFAULT_PAGE_EXTE
     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
+ * Scan whichever route dirs exist and return both route unions. After each
+ * scanner's own intra-router checks, two cross-router passes run: 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.
  */
@@ -62,7 +62,7 @@ export function scanRoutes(dirs, pageExtensions = DEFAULT_PAGE_EXTENSIONS) {
     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)`);
+        throw new RouteCollisionError(`route collision between app/ and pages/: ${shared.map((path) => `"${path}"`).join(", ")} — Next fails the build on conflicting app and page files`);
     }
     assertNoStructuralCollisions([
         ...appRoutes.map((path) => ({ path, router: "app" })),