paramour 0.5.1 → 0.7.0

package/dist/path.js

@@ -1,14 +1,15 @@
-import { describeType, ParamourError, ParamsDecodeError, ParseError, SerializeError, } from "./errors.js";
+import { codecShapeLabel } from "./describe.js";
+import { describeType, ParamourError, ParamsDecodeError, ParseError, parseIssueReason, SerializeError, } from "./errors.js";
 import { encodeComponent, readInputValue, serializeValue } from "./search.js";
-// Anchored per the wire-format spec's regex ethos; name charset excludes
-// brackets so nesting can't smuggle through. Match order mirrors the type
-// grammar: `[[...` before `[...` before `[`.
+// Anchored, like the wire-value grammars; the name charset excludes brackets
+// so nesting can't smuggle through. Match order mirrors the type grammar:
+// `[[...` before `[...` before `[`.
 const OPTIONAL_CATCHALL_TOKEN = /^\[\[\.\.\.([^\][]+)\]\]$/;
 const CATCHALL_TOKEN = /^\[\.\.\.([^\][]+)\]$/;
 const SINGLE_TOKEN = /^\[([^\][]+)\]$/;
 const GROUP_SEGMENT = /^\(.*\)$/;
 /**
- * Builds the path portion of an href (RL5): `/` plus the encoded segments
+ * Builds the path portion of an href: `/` plus the encoded segments
  * joined with `/`. R2's element joining falls out of the same join as
  * everything else; a fully-elided path (an optional catch-all at the root)
  * yields "/".
@@ -17,7 +18,7 @@ export function buildPath(route, params) {
     return `/${encodeParams(route, params).join("/")}`;
 }
 /**
- * Decodes a params source against a route's codecs (RL7), the sync twin of
+ * Decodes a params source against a route's codecs, the sync twin of
  * `route.parseParams` — mirrors decodeSearch: per-key {@link Issue}
  * aggregation into {@link ParamsDecodeError}. Shape validation is strict:
  * `[id]` given an array, a catch-all given a string, a missing required key,
@@ -46,6 +47,12 @@ export function decodeParams(route, source, options) {
         if (segment.kind === "static")
             continue;
         const codec = requireCodec(config, segment.name, route.path);
+        // One "expected" label per param, whatever the failure mode: a
+        // catch-all's codec describes ONE element, but the param's shape is the
+        // array, so every catch-all issue — missing, wrong shape, or a single
+        // failing element — cites the repeated form (integer[]), matching
+        // decodeSearch's array-element issues.
+        const expected = codecShapeLabel(codec, segment.kind !== "single");
         // Own properties only: unknown keys are never read, and inherited
         // Object.prototype members must not count as present values.
         const value = Object.hasOwn(source, segment.name)
@@ -54,16 +61,20 @@ export function decodeParams(route, source, options) {
         if (segment.kind === "single") {
             if (value === undefined) {
                 issues.push({
+                    expected,
                     key: segment.name,
                     message: "required route param is missing",
+                    reason: "missing",
                 });
             }
             else if (typeof value !== "string") {
-                // RL7: shape mismatches are recorded issues, never ParseErrors —
+                // Shape mismatches are recorded issues, never ParseErrors —
                 // .catch() cannot recover them.
                 issues.push({
+                    expected,
                     key: segment.name,
                     message: `expected a single segment value, got ${Array.isArray(value) ? "an array" : typeof value}`,
+                    reason: "shape",
                 });
             }
             else {
@@ -82,7 +93,18 @@ export function decodeParams(route, source, options) {
                         entries.push([segment.name, codec["~catchValue"]()]);
                     }
                     else if (error instanceof ParseError) {
-                        issues.push({ key: segment.name, message: error.message });
+                        issues.push({
+                            expected,
+                            key: segment.name,
+                            message: error.message,
+                            // "parse" vs "validate" comes from the ParseError's own
+                            // selfDescribing flag — structural, never message sniffing.
+                            reason: parseIssueReason(error),
+                            // Issue.wire is the codec-grammar-layer value — the DECODED
+                            // segment, not the raw URL text — matching decodeSearch,
+                            // whose sources arrive platform-decoded.
+                            wire: decoded,
+                        });
                     }
                     else {
                         throw error;
@@ -98,25 +120,33 @@ export function decodeParams(route, source, options) {
             }
             else {
                 issues.push({
+                    expected,
                     key: segment.name,
                     message: "required route param is missing",
+                    reason: "missing",
                 });
             }
             continue;
         }
         if (!Array.isArray(value)) {
             issues.push({
+                expected,
                 key: segment.name,
                 message: `expected catch-all values (an array), got ${typeof value}`,
+                reason: "shape",
             });
             continue;
         }
         if (segment.kind === "catchall" && value.length === 0) {
-            // RL7: no URL produces a present-but-empty required catch-all; only
-            // hand-built props can — mirrors R3's encode-side stance.
+            // No URL produces a present-but-empty required catch-all; only
+            // hand-built props can — mirrors R3's encode-side stance. Reason
+            // "missing", not "shape": the key exists but its VALUES are missing,
+            // so pointing at the expected form is what helps.
             issues.push({
+                expected,
                 key: segment.name,
                 message: "required catch-all received no segment values",
+                reason: "missing",
             });
             continue;
         }
@@ -129,8 +159,10 @@ export function decodeParams(route, source, options) {
         for (const [index, element] of elements.entries()) {
             if (typeof element !== "string") {
                 issues.push({
+                    expected,
                     key: segment.name,
                     message: `element ${String(index)}: expected a string, got ${typeof element}`,
+                    reason: "shape",
                 });
                 failed = true;
                 continue;
@@ -143,7 +175,7 @@ export function decodeParams(route, source, options) {
                 parsed.push(codec["~parseElement"](decoded));
             }
             catch (error) {
-                // Element-wise recovery (RL7, forced by D6): the codec describes ONE
+                // Element-wise recovery (forced by D6): the codec describes ONE
                 // element, so a .catch() fallback is element-typed — each failing
                 // element recovers independently ("1","x","3" → 1, fallback, 3).
                 if (error instanceof ParseError && codec["~catchValue"] !== undefined) {
@@ -151,8 +183,13 @@ export function decodeParams(route, source, options) {
                 }
                 else if (error instanceof ParseError) {
                     issues.push({
+                        expected,
                         key: segment.name,
                         message: `element ${String(index)}: ${error.message}`,
+                        // Classified from the flag, as in the single-param branch.
+                        reason: parseIssueReason(error),
+                        // Grammar-layer (decoded) value, as in the single-param branch.
+                        wire: decoded,
                     });
                     failed = true;
                 }
@@ -165,17 +202,17 @@ export function decodeParams(route, source, options) {
             entries.push([segment.name, parsed]);
     }
     if (issues.length > 0) {
-        throw new ParamsDecodeError(issues);
+        throw new ParamsDecodeError(issues, route.path);
     }
     return Object.fromEntries(entries);
 }
 /**
  * Encodes a params input into ordered, already-percent-encoded URL segment
- * strings (RL5) — ONE entry per emitted URL segment: a static segment is
- * emitted verbatim, a single param contributes one entry (R1), a catch-all
- * one per element (R2), an elided optional catch-all none (R3). Codec
- * serialize errors and schema-refinement failures (N9) propagate unchanged,
- * already branded at their own chokepoints.
+ * strings — ONE entry per emitted URL segment: a static segment is emitted
+ * verbatim, a single param contributes one entry (R1), a catch-all one per
+ * element (R2), an elided optional catch-all none (R3). Codec serialize
+ * errors and schema-refinement failures propagate unchanged, already branded
+ * at their own chokepoints.
  */
 export function encodeParams(route, params) {
     // The TS contract forbids non-object inputs, but plain-JS callers reach
@@ -189,8 +226,8 @@ export function encodeParams(route, params) {
     const segments = [];
     for (const segment of routeSegments(route)) {
         if (segment.kind === "static") {
-            // RL2/RL5: the literal is URL-shaped and emitted as-is — static
-            // segments are never re-encoded.
+            // The path literal is URL-shaped and emitted as-is — static segments
+            // are never re-encoded.
             segments.push(segment.raw);
             continue;
         }
@@ -215,17 +252,17 @@ export function encodeParams(route, params) {
 /**
  * Encodes a params input into the per-param wire-value record the static
  * generation surfaces expect: App Router `generateStaticParams` entries and
- * Pages Router `getStaticPaths` `{ params }` objects (PR10's static story).
- * Same codec serialization and R1–R4 validation as {@link encodeParams},
- * with two deliberate differences: static segments are skipped (Next wants
- * only the dynamic params, keyed by name), and values are NOT percent-encoded
- * — Next percent-encodes static-params values itself when it materializes
- * the concrete URLs, so pre-encoding here would double-encode (the
- * encode-side mirror of R5's decode asymmetry). That also means the S7
- * lone-surrogate brand stays an encodeParams concern: strings are handed to
- * Next verbatim. An elided optional catch-all (R3) OMITS its key — an absent
- * key is the base-path variant on both routers (Pages also accepts
- * undefined/[]; omission is the one spelling valid on both).
+ * Pages Router `getStaticPaths` `{ params }` objects. Same codec
+ * serialization and R1–R4 validation as {@link encodeParams}, with two
+ * deliberate differences: static segments are skipped (Next wants only the
+ * dynamic params, keyed by name), and values are NOT percent-encoded — Next
+ * percent-encodes static-params values itself when it materializes the
+ * concrete URLs, so pre-encoding here would double-encode (the encode-side
+ * mirror of R5's decode asymmetry). That also means the S7 lone-surrogate
+ * brand stays an encodeParams concern: strings are handed to Next verbatim.
+ * An elided optional catch-all (R3) OMITS its key — an absent key is the
+ * base-path variant on both routers (Pages also accepts undefined/[];
+ * omission is the one spelling valid on both).
  */
 export function encodeStaticParams(route, params) {
     // The TS contract forbids non-object inputs, but plain-JS callers reach
@@ -255,12 +292,12 @@ export function encodeStaticParams(route, params) {
 }
 /**
  * Tokenizes a path literal into segments, throwing ParamourError on every
- * RL1 rejection. Shared by the route constructors (define-time validation)
- * and the R-rule runtime here, so encode/decode never re-derive segment
- * kinds.
+ * rejected literal. Shared by the route constructors (define-time
+ * validation) and the R-rule runtime here, so encode/decode never re-derive
+ * segment kinds.
  */
 export function tokenizePath(path) {
-    // RL1: either would corrupt href's fixed path–query–fragment assembly (RL4).
+    // Either would corrupt href's fixed path–query–fragment assembly.
     if (path.includes("?")) {
         throw new ParamourError(`route path must not contain "?": "${path}" (declare search params in the search config)`);
     }
@@ -281,8 +318,8 @@ export function tokenizePath(path) {
         if (raw === "") {
             throw new ParamourError(`route path contains an empty segment: "${path}"`);
         }
-        // RL2: path literals are URL-shaped, so group/slot spellings are
-        // filesystem paths by definition — the most likely migration mistake.
+        // Path literals are URL-shaped, so group/slot spellings are filesystem
+        // paths by definition — the most likely migration mistake.
         if (GROUP_SEGMENT.test(raw)) {
             throw new ParamourError(`route paths are URL-shaped: "${raw}" in "${path}" is a route-group folder name; use the URL path without it`);
         }
@@ -291,7 +328,7 @@ export function tokenizePath(path) {
         }
         const segment = tokenizeSegment(raw, path);
         if (segment.kind !== "static") {
-            // RL1: not expressible as a compile error — the mapped type silently
+            // Not expressible as a compile error — the mapped type silently
             // collapses duplicate keys.
             if (seen.has(segment.name)) {
                 throw new ParamourError(`route path declares param "${segment.name}" more than once: "${path}"`);
@@ -301,7 +338,7 @@ export function tokenizePath(path) {
         segments.push(segment);
     }
     segments.forEach((segment, index) => {
-        // RL1: Next itself requires catch-alls to be final.
+        // Next itself requires catch-alls to be final.
         if ((segment.kind === "catchall" || segment.kind === "optional-catchall") &&
             index < segments.length - 1) {
             throw new ParamourError(`catch-all segment "${segment.raw}" must be the final segment: "${path}"`);
@@ -385,9 +422,8 @@ function serializeDynamicSegment(codec, segment, value) {
     // R2: each element is serialized independently; on the path surface an
     // element containing "/" becomes %2F and round-trips as a single element —
     // core's decodeParams restores it via percentDecodeSegment (R5), since Next
-    // hands the encoded value straight back on the params surface (wire-spec
-    // open item 1). The static surface passes the array whole, so "/" needs no
-    // escaping there.
+    // hands the encoded value straight back on the params surface. The static
+    // surface passes the array whole, so "/" needs no escaping there.
     return {
         kind: "many",
         values: value.map((element) => serializeSegmentValue(codec, segment.name, element)),
@@ -425,7 +461,7 @@ function tokenizeSegment(raw, path) {
     if (!raw.startsWith("[...") && single?.[1] !== undefined) {
         return { kind: "single", name: single[1], raw };
     }
-    // RL1: the type layer lets these fall through as static text (RL3), and
+    // The type layer lets these fall through as static text, and
     // pre-generation there is no registry to catch them; href would otherwise
     // emit the token verbatim.
     if (raw.includes("[") || raw.includes("]")) {

package/dist/route.d.ts

@@ -3,23 +3,23 @@ import { type RouteDecodeError } from "./errors.js";
 import { type ParamsSource, type PathSegment } from "./path.js";
 import { type SearchOutputOf, type SearchSlot } from "./search.js";
 /**
- * `any` is deliberate (RL4, same variance gotcha as AnyCodec): codec configs
+ * `any` is deliberate (same variance gotcha as AnyCodec): codec configs
  * reach contravariant positions through the parse methods and `HrefArgs`;
  * the `unknown` form would reject every concrete route.
  */
 export type AnyAppRoute = AppRoute<string, any, any>;
-/** Pages twin of {@link AnyAppRoute} (PR3). */
+/** Pages twin of {@link AnyAppRoute}. */
 export type AnyPagesRoute = PagesRoute<string, any, any>;
 /**
- * Router-agnostic (PR3): matches both brands. This is the bound for
+ * Router-agnostic: matches both brands. This is the bound for
  * everything that only needs the data core — `href()`, the standalone
  * decoders, `InferRouteParams` — none of which differ by router.
  */
 export type AnyRoute = Route<string, any, any>;
 /**
- * An App Router route (PR3/PR7): the async props-based parse surface —
- * three surfaces × throwing/safe (RL1/RL6). Props may be promised (Next
- * 15/16) and are awaited before any decode runs.
+ * An App Router route: the async props-based parse surface — three surfaces
+ * × throwing/safe. Props may be promised (Next 15/16) and are awaited before
+ * any decode runs.
  */
 export interface AppRoute<Path extends string, PC extends ParamsConfig<Path>, SC extends SearchSlot> extends Route<Path, PC, SC, "app"> {
     /**
@@ -31,9 +31,9 @@ export interface AppRoute<Path extends string, PC extends ParamsConfig<Path>, SC
         params: ParamsOutput<Path, PC>;
         search: SearchOutputOf<SC>;
     }>;
-    /** Bare params object (RL6) — layout props are structurally assignable. */
+    /** Bare params object — layout props are structurally assignable. */
     parseParams(props: ParamsPropsInput): Promise<ParamsOutput<Path, PC>>;
-    /** Bare search object (RL6) — the search half alone. */
+    /** Bare search object — the search half alone. */
     parseSearch(props: SearchPropsInput): Promise<SearchOutputOf<SC>>;
     safeParse(props: RoutePropsInput): Promise<SafeResult<{
         params: ParamsOutput<Path, PC>;
@@ -42,18 +42,18 @@ export interface AppRoute<Path extends string, PC extends ParamsConfig<Path>, SC
     safeParseParams(props: ParamsPropsInput): Promise<SafeResult<ParamsOutput<Path, PC>>>;
     safeParseSearch(props: SearchPropsInput): Promise<SafeResult<SearchOutputOf<SC>>>;
 }
-/** Names of `[...name]` catch-all segments in the path literal (RL3). */
+/** Names of `[...name]` catch-all segments in the path literal. */
 export type CatchAllNames<Path extends string> = Segments<Path> extends infer S extends string ? S extends `[...${infer Name}]` ? NonEmptyName<Name> : never : never;
 /**
- * Exact-key enforcement (RL1): every excess key's value type becomes `never`,
+ * Exact-key enforcement: every excess key's value type becomes `never`,
  * so a misspelled param fails to compile on its own property line while `PC`
  * itself stays the naked inference site for `const` codec-literal retention.
  */
 export type ConformParams<Path extends string, PC> = PC & Record<Exclude<keyof PC, PathParamNames<Path>>, never>;
-/** Decoded params object type for a route (RL3); see {@link ParamsOutput}. */
+/** Decoded params object type for a route; see {@link ParamsOutput}. */
 export type InferRouteParams<R extends AnyRoute> = ParamsOutput<R["path"], R["~params"]>;
 /**
- * Accepts promised props and plain objects alike (RL6). This width lives on
+ * Accepts promised props and plain objects alike. This width lives on
  * the parse INPUT surface ({@link RoutePropsInput} and friends), not on the
  * annotation types: every supported Next (peer `>=15`) delivers page props
  * as promises, and Next 15.5's generated `.next/types` page check requires
@@ -63,32 +63,32 @@ export type InferRouteParams<R extends AnyRoute> = ParamsOutput<R["path"], R["~p
  */
 export type MaybePromise<T> = Promise<T> | T;
 /**
- * RL3: an empty name (`[]`, `[...]`, `[[...]]`) is not a token — it falls
- * through as static text; the runtime malformed-bracket check is the backstop.
+ * An empty name (`[]`, `[...]`, `[[...]]`) is not a token — it falls through
+ * as static text; the runtime malformed-bracket check is the backstop.
  */
 export type NonEmptyName<Name extends string> = Name extends "" ? never : Name;
 /**
- * Names of `[[...name]]` optional catch-all segments (RL3). The `infer S`
+ * Names of `[[...name]]` optional catch-all segments. The `infer S`
  * indirection is load-bearing: conditionals distribute only over naked type
  * parameters, and `Segments<Path>` is an alias application, not a parameter.
  */
 export type OptionalCatchAllNames<Path extends string> = Segments<Path> extends infer S extends string ? S extends `[[...${infer Name}]]` ? NonEmptyName<Name> : never : never;
 /**
- * Structural context contract for the pages parse surface (PR10): the shape
+ * Structural context contract for the pages parse surface: the shape
  * `getServerSideProps` and `getInitialProps` contexts share, with no
  * `next/*` import (the ParamsProps/SearchProps precedent). `query` is
  * REQUIRED: `GetStaticPropsContext` has no query string, so it fails to
  * compose here by design — typed search at build time would be a lie; the
  * static story is core's `decodeParams`/`safeDecodeParams`. Both
  * assignability claims are pinned per supported Next major in
- * `examples/next-compat/src/contexts.ts` (PR13).
+ * `examples/next-compat/src/contexts.ts`.
  */
 export interface PagesContext {
     readonly params?: ParamsSource | undefined;
     readonly query: ParamsSource;
 }
 /**
- * A Pages Router route (PR3/PR10): the sync context-based parse surface.
+ * A Pages Router route: the sync context-based parse surface.
  * `getServerSideProps` / `getInitialProps` hand params and query
  * synchronously and pre-merged, so there is no promised-props machinery
  * here — the context split (params authoritative, query minus path-param
@@ -101,25 +101,25 @@ export interface PagesRoute<Path extends string, PC extends ParamsConfig<Path>,
      * present; when absent (`getInitialProps` — `NextPageContext` has no
      * `params` even on dynamic routes) they are extracted from `query` by
      * segment name, which is sound because Next's own merge gives route
-     * params precedence in `query` (PR10).
+     * params precedence in `query`.
      */
     parseContext(context: PagesContext): {
         params: ParamsOutput<Path, PC>;
         search: SearchOutputOf<SC>;
     };
-    /** {@link parseContext} in the safe shape — `safely`'s taxonomy (PR12). */
+    /** {@link parseContext} in the safe shape — `safely`'s taxonomy. */
     safeParseContext(context: PagesContext): SafeResult<{
         params: ParamsOutput<Path, PC>;
         search: SearchOutputOf<SC>;
     }>;
 }
 /**
- * Augmented by codegen with per-router path unions (RL8/PR9):
+ * Augmented by codegen with per-router path unions:
  * `{ appRoutes: "/a" | …; pagesRoutes: "/x" | … }`. Each member is
- * independently ABSENT when its scan is empty (TR3's absent-not-`never`
- * rule), preserving per-router world-A/B independence. The generated
- * artifact is a pure `.d.ts` module augmentation — no runtime import, so
- * tree-shaking is untouched (spike-01 lock-ins #3/#4).
+ * independently ABSENT when its scan is empty — absent, never `never` —
+ * preserving per-router world-A/B independence. The generated artifact is a
+ * pure `.d.ts` module augmentation — no runtime import, so tree-shaking is
+ * untouched.
  */
 export interface ParamourRegister {
 }
@@ -127,15 +127,15 @@ export interface ParamourRegister {
 export type ParamOutput<PC, K extends PropertyKey> = K extends keyof PC ? PC[K] extends AnyCodec ? OutputOf<PC[K]> : never : never;
 /**
  * Params schema shape for a path: one codec per dynamic segment name. The
- * codec describes ONE segment element (design-02 D5/D6) — arrays come from
- * the segment kind, and presence modifiers are compile errors (`ParamCodec`).
- * RL9 assigned this to path.ts; it stays here instead so the whole path
- * grammar lives in one module — path.ts consumes it via type-only imports,
- * keeping runtime imports one-directional (route.ts → path.ts).
+ * codec describes ONE segment element (D5/D6) — arrays come from the segment
+ * kind, and presence modifiers are compile errors (`ParamCodec`). It lives
+ * here rather than in path.ts so the whole path grammar sits in one module —
+ * path.ts consumes it via type-only imports, keeping runtime imports
+ * one-directional (route.ts → path.ts).
  */
 export type ParamsConfig<Path extends string> = Readonly<Record<PathParamNames<Path>, ParamCodec>>;
 /**
- * Parse-output shape (RL3): `[id]` → `Out`, `[...slug]` → `Out[]`,
+ * Parse-output shape: `[id]` → `Out`, `[...slug]` → `Out[]`,
  * `[[...slug]]` → `Out[]` — every key REQUIRED on the output side; an absent
  * optional catch-all normalizes to `[]` at decode time (D6), so no `?:`
  * split exists here (that split is the href-input side's concern). Keyed by
@@ -146,7 +146,7 @@ export type ParamsOutput<Path extends string, PC> = {
     [K in PathParamNames<Path>]: K extends CatchAllNames<Path> | OptionalCatchAllNames<Path> ? ParamOutput<PC, K>[] : ParamOutput<PC, K>;
 };
 /**
- * Structural props contract for the params half (RL6): layout props are
+ * Structural props contract for the params half: layout props are
  * assignable, and a missing member decodes like an empty source
  * (required-missing issues, never a crash). Deliberately NOT Next's
  * generated `PageProps` global — core stays framework-agnostic, and that
@@ -156,52 +156,52 @@ export interface ParamsProps {
     readonly params?: Promise<ParamsSource>;
 }
 /**
- * What `parseParams` ACCEPTS (RL6): {@link ParamsProps} plus plain sync
+ * What `parseParams` ACCEPTS: {@link ParamsProps} plus plain sync
  * objects — see {@link MaybePromise} for why the annotation type is
  * promise-only while the parse input stays wide.
  */
 export interface ParamsPropsInput {
     readonly params?: MaybePromise<ParamsSource>;
 }
-/** Every dynamic segment name in the path literal (RL3). */
+/** Every dynamic segment name in the path literal. */
 export type PathParamNames<Path extends string> = CatchAllNames<Path> | OptionalCatchAllNames<Path> | SingleParamNames<Path>;
 /**
  * Pre-generation: ParamourRegister has no `appRoutes` member, so this
  * resolves to `string` and any path literal is accepted (unverified).
  * Post-generation it resolves to the union of filesystem-verified app-router
- * paths (RL8, spike-01). Per-router on purpose (PR9): an empty app scan
- * keeps THIS fallback while `pagesRoutes` narrows, and vice versa.
+ * paths. Per-router on purpose: an empty app scan keeps THIS fallback while
+ * `pagesRoutes` narrows, and vice versa.
  */
 export type RegisteredAppRoutePaths = ParamourRegister extends {
     appRoutes: infer R extends string;
 } ? R : string;
-/** Pages twin of {@link RegisteredAppRoutePaths} (PR9). */
+/** Pages twin of {@link RegisteredAppRoutePaths}. */
 export type RegisteredPagesRoutePaths = ParamourRegister extends {
     pagesRoutes: infer R extends string;
 } ? R : string;
 /**
- * Static-only subset of {@link RegisteredAppRoutePaths} (SH2): derived by
+ * Static-only subset of {@link RegisteredAppRoutePaths}: derived by
  * syntactic filter, not emitted — dynamic-ness is a property of the path
  * literal, so the registry format doesn't change. Same world-A `string`
  * fallback as the full union (the filter passes `string` through).
  */
 export type RegisteredStaticAppRoutePaths = StaticPathsOf<RegisteredAppRoutePaths>;
-/** Pages twin of {@link RegisteredStaticAppRoutePaths} (SH2). */
+/** Pages twin of {@link RegisteredStaticAppRoutePaths}. */
 export type RegisteredStaticPagesRoutePaths = StaticPathsOf<RegisteredPagesRoutePaths>;
 /**
  * Every registered STATIC path across both routers — the string form of
- * href's path argument (SH1/SH2). Deliberately NOT the union of the two
- * per-router types (SH3): each falls back to `string` when its registry
- * member is absent, and in a single-router project the absent side's
- * `string` would swallow the union and erase verification for the router
- * that HAS routes. The permissive fallback applies only when NEITHER member
- * is present (world A / TR3's empty merge).
+ * href's path argument. Deliberately NOT the union of the two per-router
+ * types: each falls back to `string` when its registry member is absent, and
+ * in a single-router project the absent side's `string` would swallow the
+ * union and erase verification for the router that HAS routes. The
+ * permissive fallback applies only when NEITHER member is present (world A,
+ * where codegen has merged nothing into the registry).
  */
 export type RegisteredStaticRoutePaths = [PresentRegisteredPaths] extends [
     never
 ] ? string : StaticPathsOf<PresentRegisteredPaths>;
 /**
- * The router-agnostic core of a defined route (PR3): path, configs, and the
+ * The router-agnostic core of a defined route: path, configs, and the
  * define-time token cache. The parse surface is router-specific and lives on
  * {@link AppRoute} / {@link PagesRoute} — gating it via the interface split
  * makes the wrong surface ABSENT, not just ill-typed. `~`-prefixed members
@@ -211,7 +211,7 @@ export type RegisteredStaticRoutePaths = [PresentRegisteredPaths] extends [
 export interface Route<Path extends string, PC extends ParamsConfig<Path>, SC extends SearchSlot, R extends RouterKind = RouterKind> {
     readonly path: Path;
     readonly "~params": PC;
-    /** The router brand (PR3) — type-state, same discipline as Codec's P/C/A. */
+    /** The router brand — type-state, same discipline as Codec's P/C/A. */
     readonly "~router": R;
     readonly "~search": SC;
     /**
@@ -222,10 +222,10 @@ export interface Route<Path extends string, PC extends ParamsConfig<Path>, SC ex
     readonly "~segments": readonly PathSegment[];
 }
 /**
- * Conditional on the path shape (RL1, spike-01 lock-in #2): dynamic paths
- * REQUIRE `params` with exactly the extracted segment names; static paths
- * REJECT it (`?: never` — may be absent, may never be present, which under
- * exactOptionalPropertyTypes holds even for non-fresh objects).
+ * Conditional on the path shape: dynamic paths REQUIRE `params` with exactly
+ * the extracted segment names; static paths REJECT it (`?: never` — may be
+ * absent, may never be present, which under exactOptionalPropertyTypes holds
+ * even for non-fresh objects).
  */
 export type RouteConfig<Path extends string, PC extends ParamsConfig<Path>, SC extends SearchSlot> = [PathParamNames<Path>] extends [never] ? {
     readonly params?: never;
@@ -235,7 +235,7 @@ export type RouteConfig<Path extends string, PC extends ParamsConfig<Path>, SC e
     readonly search?: SC;
 };
 /**
- * Full page-props contract (RL6): the type a page annotates its props with.
+ * Full page-props contract: the type a page annotates its props with.
  * Next's `PageProps` is structurally assignable, and both members are
  * promise-only so the annotation survives Next 15.5's generated page check
  * (see {@link MaybePromise}). Deliberately NOT Next's generated `PageProps`
@@ -243,16 +243,16 @@ export type RouteConfig<Path extends string, PC extends ParamsConfig<Path>, SC e
  */
 export interface RouteProps extends ParamsProps, SearchProps {
 }
-/** What `parse`/`safeParse` ACCEPT (RL6): {@link RouteProps} plus sync props. */
+/** What `parse`/`safeParse` ACCEPT: {@link RouteProps} plus sync props. */
 export interface RoutePropsInput extends ParamsPropsInput, SearchPropsInput {
 }
-/** Which router a route belongs to (PR3) — the value of the `~router` brand. */
+/** Which router a route belongs to — the value of the `~router` brand. */
 export type RouterKind = "app" | "pages";
 /**
- * Status-discriminated result shape (RL6, design-06 PR12 — unified with the
- * pages hooks' `RouterResult`, which extends this union by one `pending`
- * member): `if (result.status === "error")` narrows both arms, and both
- * routers' results destructure identically.
+ * Status-discriminated result shape, unified with the pages hooks'
+ * `RouterResult` (which extends this union by one `pending` member):
+ * `if (result.status === "error")` narrows both arms, and both routers'
+ * results destructure identically.
  */
 export type SafeResult<T> = {
     data: T;
@@ -262,7 +262,7 @@ export type SafeResult<T> = {
     status: "error";
 };
 /**
- * Structural props contract for the search half (RL6). The wire record
+ * Structural props contract for the search half. The wire record
  * shape is the same as the params side's, hence the shared source type.
  */
 export interface SearchProps {
@@ -274,19 +274,19 @@ export interface SearchPropsInput {
 }
 /**
  * Distributes a path literal into the union of its `/`-separated segment
- * literals. Malformed bracket tokens fall through as static text — no
- * type-level path linting (RL3); tokenizePath is the runtime backstop.
+ * literals. Malformed bracket tokens fall through as static text — there is
+ * no type-level path linting; tokenizePath is the runtime backstop.
  */
 export type Segments<S extends string> = S extends `${infer Head}/${infer Rest}` ? Segments<Head> | Segments<Rest> : S;
 /**
- * Names of single `[name]` segments (RL3). Conditional order is load-bearing
+ * Names of single `[name]` segments. Conditional order is load-bearing
  * and mirrors tokenizePath: both catch-all forms must be excluded first or
  * `[...slug]` would extract as a single param named `"...slug"`.
  */
 export type SingleParamNames<Path extends string> = Segments<Path> extends infer S extends string ? S extends `[[...${string}]]` ? never : S extends `[...${string}]` ? never : S extends `[${infer Name}]` ? NonEmptyName<Name> : never : never;
 /**
  * Union of the registry members that are actually PRESENT — `never` when
- * neither router has generated routes. The input to SH3's combined-union
+ * neither router has generated routes. The input to the combined-union
  * fallback rule; see {@link RegisteredStaticRoutePaths}.
  */
 type PresentRegisteredPaths = (ParamourRegister extends {
@@ -295,28 +295,28 @@ type PresentRegisteredPaths = (ParamourRegister extends {
     pagesRoutes: infer P extends string;
 } ? P : never);
 /**
- * Filters a path union to its static members (SH2): any `[` marks a dynamic
+ * Filters a path union to its static members: any `[` marks a dynamic
  * segment. `string` passes through (it doesn't extend the bracket template),
  * which is exactly what keeps the world-A fallback intact. Note reachability
- * ≠ staticness (SH7): `/docs/[[...slug]]` serves `/docs`, but it carries a
- * codec and decode expectations, so it is excluded here.
+ * ≠ staticness: `/docs/[[...slug]]` serves `/docs`, but it carries a codec
+ * and decode expectations, so it is excluded here.
  */
 type StaticPathsOf<P extends string> = P extends `${string}[${string}` ? never : P;
 /**
- * Defines an App Router route: the URL-shaped path literal (RL2) plus its
- * param/search codec configs. Validates the literal eagerly (RL1 —
- * fail-fast at config definition time, same stance as eager `.default()`
- * serialization). The router is a *declaration*, not an inference (PR7):
+ * Defines an App Router route: the URL-shaped path literal plus its
+ * param/search codec configs. Validates the literal eagerly — fail-fast at
+ * config definition time, the same stance as eager `.default()`
+ * serialization. The router is a *declaration*, not an inference:
  * pre-codegen the registry cannot distinguish routers, so an inferred brand
  * would silently degrade in world A — the split constructor is what keeps
  * the brand intact there.
  */
 export declare function defineAppRoute<Path extends RegisteredAppRoutePaths & string, const PC extends ParamsConfig<Path> = ParamsConfig<Path>, const SC extends SearchSlot = Record<never, never>>(path: Path, config: RouteConfig<Path, PC, SC>): AppRoute<Path, PC, SC>;
 /**
- * Defines a Pages Router route (PR7 — neither router is the default; see
+ * Defines a Pages Router route — neither router is the default; see
  * {@link defineAppRoute} for why the constructor is split rather than
- * inferred). Same eager literal validation (RL1); the parse surface is the
- * sync context pair (PR10).
+ * inferred. Same eager literal validation; the parse surface is the sync
+ * context pair.
  */
 export declare function definePagesRoute<Path extends RegisteredPagesRoutePaths & string, const PC extends ParamsConfig<Path> = ParamsConfig<Path>, const SC extends Readonly<Partial<Record<PathParamNames<Path>, never>>> & SearchSlot = Record<never, never>>(path: Path, config: RouteConfig<Path, PC, SC>): PagesRoute<Path, PC, SC>;
 export {};