@paramour-js/next 0.4.0 → 0.5.0

package/dist/lock.d.ts

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

package/dist/lock.js

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

package/dist/navigation-adapter.d.ts

@@ -1,14 +1,13 @@
 import type { ParamsSource } from "paramour";
 /**
- * Adapter seam for the client hooks' framework reads (design-16 TA1): each
- * flavor's hooks resolve Next through a React context so the /testing entry
- * can override the reads without runner-specific module mocking.
- * Deliberately NO `"use client"` directive — app.ts (which carries one) and
- * pages.ts (which must not, PR2) both import from here, like
- * observe.ts/select.ts; the directive belongs on the entry modules, not a
- * shared leaf.
+ * Adapter seam for the client hooks' framework reads: each flavor's hooks
+ * resolve Next through a React context so the /testing entry can override
+ * the reads without runner-specific module mocking. Deliberately NO
+ * `"use client"` directive — app.ts (which carries one) and pages.ts (which
+ * must not) both import from here, like observe.ts/select.ts; the directive
+ * belongs on the entry modules, not a shared leaf.
  *
- * This module is Next-free on purpose (TA3): the contexts default to `null`
+ * This module is Next-free on purpose: the contexts default to `null`
  * and each flavor ENTRY supplies its own real-Next fallback
  * (`useContext(ctx) ?? realAdapter`), so neither this module nor the
  * /testing entry ever drags a `next/*` specifier into its graph. The
@@ -20,11 +19,11 @@ import type { ParamsSource } from "paramour";
 /**
  * App-flavor adapter: EXACTLY the ambient view of `next/navigation` declared
  * in `src/types/next-navigation.d.ts` — that ambient is the contract of
- * record, and this interface must stay in lockstep with it (TA2; the
+ * record, and this interface must stay in lockstep with it (the
  * `examples/next-compat` pins guard the real-Next side). `useParams()`'s
  * `null` arm is the outside-App-Router-tree state (Next #48058 family) the
  * hooks deliberately tolerate; `useRouter().replace`/`usePathname` are the
- * devtools `navigate` capability's write path and resolution base (DT8).
+ * devtools `navigate` capability's write path and resolution base.
  */
 export interface AppNavigationAdapter {
     useParams(): null | ParamsSource;
@@ -37,10 +36,10 @@ export interface AppNavigationAdapter {
 /**
  * Pages-flavor adapter: EXACTLY the ambient view of `next/router.js`
  * declared in `src/types/next-router.d.ts` — that ambient is the contract of
- * record, and this interface must stay in lockstep with it (TA2). The
- * ambient's throw-on-unmounted behavior under `app/` (PR5) is part of the
- * contract: adapter implementations reproduce it by THROWING from
- * `useRouter()`, which pages.ts translates.
+ * record, and this interface must stay in lockstep with it. The ambient's
+ * throw-on-unmounted behavior under `app/` is part of the contract: adapter
+ * implementations reproduce it by THROWING from `useRouter()`, which
+ * pages.ts translates.
  */
 export interface PagesNavigationAdapter {
     useRouter(): {
@@ -51,10 +50,10 @@ export interface PagesNavigationAdapter {
     };
 }
 /**
- * The `null` default is load-bearing (TA3): with no provider mounted,
- * app.ts falls back to its real `next/navigation` adapter — zero markup and
- * zero behavior change in production (TA4).
+ * The `null` default is load-bearing: with no provider mounted, app.ts falls
+ * back to its real `next/navigation` adapter — zero markup and zero behavior
+ * change in production.
  */
 export declare const AppNavigationContext: import("react").Context<AppNavigationAdapter | null>;
-/** The pages twin; `null` default load-bearing for the same TA3 reasons. */
+/** The pages twin; its `null` default is load-bearing for the same reasons. */
 export declare const PagesNavigationContext: import("react").Context<PagesNavigationAdapter | null>;

package/dist/navigation-adapter.js

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

package/dist/observe.d.ts

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

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,9 @@
 import { type CliIo } from "./cli-io.js";
 export { type CliIo } from "./cli-io.js";
+type Command = (argv: readonly string[], io: CliIo) => Promise<number>;
+export declare const COMMANDS: Record<string, Command>;
 /**
- * @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

@@ -3,14 +3,17 @@ import { runDoctor } from "./commands/doctor.js";
 import { runGenerate } from "./commands/generate.js";
 import { runInit } from "./commands/init.js";
 import { runList } from "./commands/list.js";
+import { runSkills } from "./commands/skills.js";
 export {} from "./cli-io.js";
-// Alphabetical; the unknown-command message derives from these keys.
-const COMMANDS = {
+// Alphabetical; the unknown-command message derives from these keys, and the
+// skill-drift test pins them against the skill's CLI table.
+export const COMMANDS = {
     check: (argv, io) => runGenerate(argv, io, "check"),
     doctor: runDoctor,
     generate: (argv, io) => runGenerate(argv, io, "generate"),
     init: runInit,
     list: runList,
+    skills: (argv, io) => Promise.resolve(runSkills(argv, io)),
 };
 const USAGE = [
     "Usage: paramour <command> [options]",
@@ -21,11 +24,12 @@ const USAGE = [
     "  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",
+    "  skills    install or verify the bundled agent skill for detected agent tools",
     "",
     "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).