paramour 0.3.0 → 0.5.0

package/dist/codec.d.ts

@@ -66,8 +66,8 @@ export interface Codec<Out, P extends Presence = "required", C extends boolean =
     /** Stored as a thunk regardless of the form passed to `.default()`. */
     readonly "~defaultValue": (() => Out) | undefined;
     /**
-     * Element codec of a composite list codec (currently `p.csv`) — the
-     * per-segment scalar; undefined for every non-composite kind (CV6).
+     * Element codec of a composite list codec (`p.csv`, `p.array`) — the
+     * per-segment/per-key scalar; undefined for every non-composite kind (CV6).
      */
     readonly "~element": AnyCodec | undefined;
     /** Members of a `p.enum` codec; undefined for every other kind. */

package/dist/describe.d.ts

@@ -24,7 +24,7 @@ export interface CodecDescription {
     readonly defaultValue?: CodecDefaultDescription;
     /**
      * Nested description of a composite list codec's element scalar (CV6;
-     * currently `p.csv`).
+     * `p.csv` and `p.array`).
      */
     readonly element?: CodecDescription;
     readonly enumMembers?: readonly string[];

package/dist/describe.js

@@ -10,8 +10,9 @@ export function describeCodec(codec) {
         arity: codec["~arity"],
         caught: codec["~caught"],
         ...(defaultValue === undefined ? {} : { defaultValue }),
-        // Recursion terminates: nested csv is rejected at construction (CV2),
-        // and element codecs are unmodified scalars with no element of their own.
+        // Recursion terminates: composite nesting is bounded at construction —
+        // csv rejects nested csv (CV2) and array rejects arity-many inners
+        // (PP1), so the deepest legal chain is array<csv<scalar>>.
         ...(element === undefined ? {} : { element: describeCodec(element) }),
         ...(enumMembers === undefined ? {} : { enumMembers }),
         kind: codec["~kind"],
@@ -63,11 +64,22 @@ export function formatCodecDescription(description, style) {
     const kindLabel = (part) => part.enumMembers === undefined
         ? part.kind
         : `enum(${part.enumMembers.join(memberSeparator)})`;
-    let label = description.element === undefined
-        ? kindLabel(description)
-        : `${description.kind}<${kindLabel(description.element)}>`;
-    if (description.arity === "many")
-        label += "[]";
+    // Composite labels: a one-key list wraps its element (`csv<integer>`); a
+    // repeated-key list IS its element, pluralized (`integer[]`) — the
+    // "array" kind never appears in a label, the `[]` carries it. The elision
+    // keys on the kind, NOT arity: consumers force arity "many" onto
+    // non-array descriptions (render.ts's catch-all params), where a csv
+    // wrapper must survive as `csv<integer>[]`. Recursive so `array<csv<E>>`
+    // renders `csv<E>[]`.
+    const shapeLabel = (part) => {
+        const base = part.element === undefined
+            ? kindLabel(part)
+            : part.kind === "array"
+                ? shapeLabel(part.element)
+                : `${part.kind}<${shapeLabel(part.element)}>`;
+        return part.arity === "many" ? `${base}[]` : base;
+    };
+    let label = shapeLabel(description);
     if (style === "compact") {
         if (description.presence === "optional")
             label += "?";

package/dist/errors.d.ts

@@ -57,9 +57,10 @@ export declare function describeType(value: unknown): string;
  * Best-effort human-readable message for a foreign (non-paramour) throw:
  * an `Error`'s message, else a {@link showValue}-hardened `String()` — safe
  * even for values whose primitive conversion itself throws (null-prototype
- * objects, `Symbol.toPrimitive` throwers). Public via the barrel so derived
- * tooling that catches user-code throws (the devtools panel's edit preview)
- * shares the hardening instead of re-implementing it minus the guard.
+ * objects, `Symbol.toPrimitive` throwers). Public via `paramour/internal` so
+ * derived tooling that catches user-code throws (the devtools panel's edit
+ * preview) shares the hardening instead of re-implementing it minus the
+ * guard.
  */
 export declare function foreignMessage(error: unknown): string;
 /**

package/dist/errors.js

@@ -110,9 +110,10 @@ export function describeType(value) {
  * Best-effort human-readable message for a foreign (non-paramour) throw:
  * an `Error`'s message, else a {@link showValue}-hardened `String()` — safe
  * even for values whose primitive conversion itself throws (null-prototype
- * objects, `Symbol.toPrimitive` throwers). Public via the barrel so derived
- * tooling that catches user-code throws (the devtools panel's edit preview)
- * shares the hardening instead of re-implementing it minus the guard.
+ * objects, `Symbol.toPrimitive` throwers). Public via `paramour/internal` so
+ * derived tooling that catches user-code throws (the devtools panel's edit
+ * preview) shares the hardening instead of re-implementing it minus the
+ * guard.
  */
 export function foreignMessage(error) {
     return error instanceof Error ? error.message : showValue(error);

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 export { type AnyCodec, type Arity, type Codec, type OutputOf, type ParamCodec, type Presence, type PresenceOf, } from "./codec.js";
 export { type CodecDefaultDescription, type CodecDescription, type CodecFormatStyle, describeCodec, describeRoute, formatCodecDescription, type ParamDescription, type RouteDescription, type SearchDescription, } from "./describe.js";
-export { foreignMessage, type Issue, ParamourError, ParamsDecodeError, ParseError, type RouteDecodeError, SearchDecodeError, SearchSourceError, SerializeError, } from "./errors.js";
+export { type Issue, ParamourError, ParamsDecodeError, ParseError, type RouteDecodeError, SearchDecodeError, SearchSourceError, SerializeError, } from "./errors.js";
 export { href, type Href, type HrefArgs, type InferHrefInput, type StaticHrefOptions, } from "./href.js";
 export { p } from "./p.js";
 export { buildPath, decodeParams, type DecodeParamsOptions, encodeParams, encodeStaticParams, type InferStaticParams, type ParamsSource, } from "./path.js";
-export { type AnyAppRoute, type AnyPagesRoute, type AnyRoute, type AppRoute, defineAppRoute, definePagesRoute, type InferRouteParams, type PagesContext, type PagesRoute, type ParamourRegister, type ParamsConfig, type ParamsProps, type RegisteredAppRoutePaths, type RegisteredPagesRoutePaths, type RegisteredStaticAppRoutePaths, type RegisteredStaticPagesRoutePaths, type RegisteredStaticRoutePaths, type Route, type RouteProps, type RouterKind, type SafeResult, type SearchProps, } from "./route.js";
+export { type AnyAppRoute, type AnyPagesRoute, type AnyRoute, type AppRoute, defineAppRoute, definePagesRoute, type InferRouteParams, type PagesContext, type PagesRoute, type ParamourRegister, type ParamsConfig, type ParamsProps, type ParamsPropsInput, type RegisteredAppRoutePaths, type RegisteredPagesRoutePaths, type RegisteredStaticAppRoutePaths, type RegisteredStaticPagesRoutePaths, type RegisteredStaticRoutePaths, type Route, type RouteProps, type RoutePropsInput, type RouterKind, type SafeResult, type SearchProps, type SearchPropsInput, } from "./route.js";
 export { safeDecodeParams, safeDecodeSearch } from "./safe-decode.js";
-export { buildSearchString, decodeSearch, encodeSearch, type InferSearchInput, type InferSearchOutput, isRawSearch, parseValue, rawSearch, type RawSearch, type SearchConfig, type SearchOutputOf, type SearchSource, searchToString, serializeValue, } from "./search.js";
+export { buildSearchString, decodeSearch, encodeSearch, type InferSearchInput, type InferSearchOutput, isRawSearch, rawSearch, type RawSearch, type SearchConfig, type SearchOutputOf, type SearchSource, searchToString, serializeValue, } from "./search.js";
 export { standardSearchSchema, type StandardSearchSchema, } from "./standard-schema.js";

package/dist/index.js

@@ -1,10 +1,10 @@
 export {} from "./codec.js";
 export { describeCodec, describeRoute, formatCodecDescription, } from "./describe.js";
-export { foreignMessage, ParamourError, ParamsDecodeError, ParseError, SearchDecodeError, SearchSourceError, SerializeError, } from "./errors.js";
+export { ParamourError, ParamsDecodeError, ParseError, SearchDecodeError, SearchSourceError, SerializeError, } from "./errors.js";
 export { href, } from "./href.js";
 export { p } from "./p.js";
 export { buildPath, decodeParams, encodeParams, encodeStaticParams, } from "./path.js";
 export { defineAppRoute, definePagesRoute, } from "./route.js";
 export { safeDecodeParams, safeDecodeSearch } from "./safe-decode.js";
-export { buildSearchString, decodeSearch, encodeSearch, isRawSearch, parseValue, rawSearch, searchToString, serializeValue, } from "./search.js";
+export { buildSearchString, decodeSearch, encodeSearch, isRawSearch, rawSearch, searchToString, serializeValue, } from "./search.js";
 export { standardSearchSchema, } from "./standard-schema.js";

package/dist/internal.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The `paramour/internal` entry: unstable helpers for derived tooling
+ * (devtools, adapters), NOT for app authors and NOT covered by the public
+ * API's stability expectations. These live off the main barrel on purpose —
+ * the docs' Reference section documents the app-author surface, and these
+ * two exist solely so reflection-driven consumers (the devtools panel's
+ * catch-attribution probe and edit preview, design-12 DT7) share core's
+ * implementation instead of re-deriving it.
+ */
+export { foreignMessage } from "./errors.js";
+export { parseValue } from "./search.js";

package/dist/internal.js

@@ -0,0 +1,11 @@
+/**
+ * The `paramour/internal` entry: unstable helpers for derived tooling
+ * (devtools, adapters), NOT for app authors and NOT covered by the public
+ * API's stability expectations. These live off the main barrel on purpose —
+ * the docs' Reference section documents the app-author surface, and these
+ * two exist solely so reflection-driven consumers (the devtools panel's
+ * catch-attribution probe and edit preview, design-12 DT7) share core's
+ * implementation instead of re-deriving it.
+ */
+export { foreignMessage } from "./errors.js";
+export { parseValue } from "./search.js";

package/dist/p.d.ts

@@ -5,10 +5,17 @@ import { type Codec } from "./codec.js";
  * Each codec defines how one value crosses the URL boundary, both directions.
  */
 export declare const p: {
+    /**
+     * A repeated-key list (`?tags=a&tags=b`, design-13 PP1): arity "many", so
+     * presence modifiers are unavailable — absent and `[]` are the same wire
+     * state (S6/P6) — unlike `p.csv`'s one-key packing (CV7). Elements are
+     * strings unless an element codec is given.
+     */
+    array<E = string>(element?: Codec<E>): Codec<E[], "required", false, "many">;
     boolean(): Codec<boolean>;
     /**
      * A comma-separated scalar list in ONE wire value (design-11 CV1): arity
-     * "single", so the full modifier set applies — unlike `p.stringArray`'s
+     * "single", so the full modifier set applies — unlike `p.array`'s
      * repeated-key format (CV7: both are first-class; csv is the one-key
      * packing). Elements are strings unless an element codec is given.
      */
@@ -20,11 +27,21 @@ export declare const p: {
         serialize: (value: Out) => string;
     }): Codec<Out>;
     enum<const M extends readonly [string, ...string[]]>(members: M): Codec<M[number]>;
+    /**
+     * A 1-based-on-wire / 0-based-in-memory integer for pagination-style
+     * params (`?page=1` ↔ index 0, design-13 PP5). Deliberately stricter than
+     * nuqs's `parseAsIndex`, whose below-floor behavior is unspecified: wire
+     * values below 1 are a ParseError (recoverable via `.catch()`, like any
+     * other malformed input), and a negative in-memory index — which cannot
+     * round-trip through the 1-based wire floor — is a SerializeError at
+     * link-build time (the RL1 ethos). The optional schema validates the
+     * in-memory (0-based) value on both sides.
+     */
+    index<S extends StandardSchemaV1<number, number>>(schema?: S): Codec<S extends undefined ? number : StandardSchemaV1.InferOutput<S>>;
     integer<S extends StandardSchemaV1<number, number>>(schema?: S): Codec<S extends undefined ? number : StandardSchemaV1.InferOutput<S>>;
     isoDate(): Codec<Date>;
     json<S extends StandardSchemaV1>(schema: S): Codec<StandardSchemaV1.InferOutput<S>>;
     number<S extends StandardSchemaV1<number, number>>(schema?: S): Codec<S extends undefined ? number : StandardSchemaV1.InferOutput<S>>;
     string<S extends StandardSchemaV1<string, string>>(schema?: S): Codec<S extends undefined ? string : StandardSchemaV1.InferOutput<S>>;
-    stringArray(): Codec<string[], "required", false, "many">;
     timestamp(): Codec<Date>;
 };

package/dist/p.js

@@ -73,12 +73,46 @@ function refineForSerialize(schema, value) {
     }
     return result.value;
 }
+/**
+ * Shared element admission for `p.array`/`p.csv` (PP1/CV2): resolves the
+ * no-arg default and mirrors the type-state exclusions — presence, catch,
+ * and arity-many inners — for JS consumers (the RL1 ethos). Only the
+ * element's parse/serialize functions are captured by the list builders, so
+ * an accepted modifier would be silently dropped, not applied; one guard
+ * keeps that runtime mirror of the type-state in a single place.
+ */
+function resolveListElement(element, builder) {
+    const inner = element ?? (defaultListElement ??= p.string());
+    if (inner["~arity"] === "many" ||
+        inner["~caught"] ||
+        inner["~presence"] !== "required") {
+        throw new ParamourError(`${builder}() elements cannot carry modifiers (.optional()/.default()/.catch()) or be array codecs`);
+    }
+    return inner;
+}
 function serializeFiniteNumber(value) {
     if (typeof value !== "number" || !Number.isFinite(value)) {
         throw new SerializeError(`Expected a finite number, got ${showValue(value)}`);
     }
     return String(value);
 }
+/**
+ * Serialize-side twin of {@link parseIntegerElement}, shared by `p.integer`
+ * and `p.index`: schema refinement plus the finite and safe-integer guards.
+ * Returns the refined NUMBER — `p.integer` stringifies it as-is, `p.index`
+ * shifts it into the 1-based wire form first — so the happy path pays no
+ * throwaway stringification.
+ */
+function serializeIntegerElement(schema, value) {
+    const refined = schema ? refineForSerialize(schema, value) : value;
+    if (typeof refined !== "number" || !Number.isFinite(refined)) {
+        throw new SerializeError(`Expected a finite number, got ${showValue(refined)}`);
+    }
+    if (!Number.isSafeInteger(refined)) {
+        throw new SerializeError(`${String(refined)} is not a safe integer`);
+    }
+    return refined;
+}
 /**
  * JSON.stringify throws raw TypeErrors (circular refs, BigInt) and lets
  * toJSON() exceptions escape; wrap them so the ParamourError contract holds.
@@ -87,16 +121,43 @@ function stringifyJson(value) {
     return rebrandForeign(() => JSON.stringify(value), (error) => new SerializeError("Value is not JSON-serializable", { cause: error }));
 }
 /**
- * Shared element for no-arg `p.csv()` — codecs are immutable, so one
- * schemaless string codec serves every list. Lazily built: `p` does not
+ * Shared element for no-arg `p.csv()`/`p.array()` — codecs are immutable, so
+ * one schemaless string codec serves every list. Lazily built: `p` does not
  * exist yet while the module initializes.
  */
-let defaultCsvElement;
+let defaultListElement;
 /**
  * The `p.*` wire-codec builders (DESIGN §5 layer 1, design-02 D9).
  * Each codec defines how one value crosses the URL boundary, both directions.
  */
 export const p = {
+    /**
+     * A repeated-key list (`?tags=a&tags=b`, design-13 PP1): arity "many", so
+     * presence modifiers are unavailable — absent and `[]` are the same wire
+     * state (S6/P6) — unlike `p.csv`'s one-key packing (CV7). Elements are
+     * strings unless an element codec is given.
+     */
+    array(element) {
+        // PP1: same element-by-composition shape as p.csv (CV2) — presence,
+        // catch, and arity-many inners are excluded by the parameter type;
+        // resolveListElement mirrors that type-state for JS consumers. Unlike
+        // csv there is no nested-composite special case: a csv element is a
+        // legal whole-value scalar per repeated key (?m=a,b&m=c,d), and
+        // repeated-key values have no separator for element serializations to
+        // collide with, so no CV4 twin is needed either.
+        const inner = resolveListElement(element, "p.array");
+        // The element functions already have the arity-"many" per-element
+        // contract (one wire value per array item), so they pass through as-is;
+        // the string-return contract on custom serializers is enforced at the
+        // search.ts/path.ts call sites, same as using the element directly.
+        return createCodec({
+            arity: "many",
+            element: inner,
+            kind: "array",
+            parseElement: inner["~parseElement"],
+            serializeElement: inner["~serializeElement"],
+        });
+    },
     boolean() {
         return createCodec({
             kind: "boolean",
@@ -117,28 +178,26 @@ export const p = {
     },
     /**
      * A comma-separated scalar list in ONE wire value (design-11 CV1): arity
-     * "single", so the full modifier set applies — unlike `p.stringArray`'s
+     * "single", so the full modifier set applies — unlike `p.array`'s
      * repeated-key format (CV7: both are first-class; csv is the one-key
      * packing). Elements are strings unless an element codec is given.
      */
     csv(element) {
         // CV2: presence, catch, and arity-many inners are excluded by the
-        // parameter type (the D3 philosophy); these guards mirror that
-        // type-state for JS consumers (the RL1 ethos) — only the element
-        // functions are captured below, so an accepted modifier would be
-        // silently dropped, not applied. Nesting is detected structurally via
-        // ~element (never via ~kind, which is reflection-only and free-form for
-        // p.custom labels). Comma-emitting p.custom inners are undetectable
-        // here and are caught by the CV4 serialize guard instead.
-        const inner = element ?? (defaultCsvElement ??= p.string());
+        // parameter type (the D3 philosophy); resolveListElement mirrors that
+        // type-state for JS consumers (the RL1 ethos). Nesting is detected
+        // structurally via ~element (never via ~kind, which is reflection-only
+        // and free-form for p.custom labels). Comma-emitting p.custom inners
+        // are undetectable here and are caught by the CV4 serialize guard
+        // instead.
+        const inner = resolveListElement(element, "p.csv");
+        // The shared guard ran first: p.array also carries ~element (PP1), and
+        // the arity guard owns the "array codecs" wording — the ~element guard
+        // here is then specifically the nested-csv (arity-"single" composite)
+        // case.
         if (inner["~element"] !== undefined) {
             throw new ParamourError("p.csv() elements cannot themselves be csv lists");
         }
-        if (inner["~arity"] === "many" ||
-            inner["~caught"] ||
-            inner["~presence"] !== "required") {
-            throw new ParamourError("p.csv() elements cannot carry modifiers (.optional()/.default()/.catch()) or be array codecs");
-        }
         const parseInner = inner["~parseElement"];
         const serializeInner = inner["~serializeElement"];
         return createCodec({
@@ -226,21 +285,48 @@ export const p = {
             },
         });
     },
-    integer(schema) {
+    /**
+     * A 1-based-on-wire / 0-based-in-memory integer for pagination-style
+     * params (`?page=1` ↔ index 0, design-13 PP5). Deliberately stricter than
+     * nuqs's `parseAsIndex`, whose below-floor behavior is unspecified: wire
+     * values below 1 are a ParseError (recoverable via `.catch()`, like any
+     * other malformed input), and a negative in-memory index — which cannot
+     * round-trip through the 1-based wire floor — is a SerializeError at
+     * link-build time (the RL1 ethos). The optional schema validates the
+     * in-memory (0-based) value on both sides.
+     */
+    index(schema) {
         return createCodec({
-            kind: "integer",
+            kind: "index",
             parseElement: (raw) => {
-                const value = parseIntegerElement(raw);
+                const wire = parseIntegerElement(raw);
+                if (wire < 1) {
+                    throw new ParseError(`"${raw}" is below the 1-based wire floor of 1`);
+                }
+                const value = wire - 1;
                 return schema ? refine(schema, value) : value;
             },
             serializeElement: (value) => {
-                const refined = schema ? refineForSerialize(schema, value) : value;
-                const serialized = serializeFiniteNumber(refined);
-                if (!Number.isSafeInteger(refined)) {
-                    throw new SerializeError(`${serialized} is not a safe integer`);
+                const index = serializeIntegerElement(schema, value);
+                if (index < 0) {
+                    throw new SerializeError(`${String(index)} is negative and cannot round-trip through the 1-based wire form`);
                 }
-                return serialized;
+                const wire = index + 1;
+                if (!Number.isSafeInteger(wire)) {
+                    throw new SerializeError(`${String(index)} is outside the 1-based wire form's safe integer range`);
+                }
+                return String(wire);
+            },
+        });
+    },
+    integer(schema) {
+        return createCodec({
+            kind: "integer",
+            parseElement: (raw) => {
+                const value = parseIntegerElement(raw);
+                return schema ? refine(schema, value) : value;
             },
+            serializeElement: (value) => String(serializeIntegerElement(schema, value)),
         });
     },
     isoDate() {
@@ -311,19 +397,6 @@ export const p = {
             },
         });
     },
-    stringArray() {
-        return createCodec({
-            arity: "many",
-            kind: "string",
-            parseElement: (raw) => raw,
-            serializeElement: (value) => {
-                if (typeof value !== "string") {
-                    throw new SerializeError("Expected an array of strings");
-                }
-                return value;
-            },
-        });
-    },
     timestamp() {
         return createCodec({
             kind: "timestamp",

package/dist/route.d.ts

@@ -27,20 +27,20 @@ export interface AppRoute<Path extends string, PC extends ParamsConfig<Path>, SC
      * FIRST — a params grammar failure means the URL doesn't denote this
      * route at all (morally a 404), so it throws before search is decoded.
      */
-    parse(props: RouteProps): Promise<{
+    parse(props: RoutePropsInput): Promise<{
         params: ParamsOutput<Path, PC>;
         search: SearchOutputOf<SC>;
     }>;
     /** Bare params object (RL6) — layout props are structurally assignable. */
-    parseParams(props: ParamsProps): Promise<ParamsOutput<Path, PC>>;
+    parseParams(props: ParamsPropsInput): Promise<ParamsOutput<Path, PC>>;
     /** Bare search object (RL6) — the search half alone. */
-    parseSearch(props: SearchProps): Promise<SearchOutputOf<SC>>;
-    safeParse(props: RouteProps): Promise<SafeResult<{
+    parseSearch(props: SearchPropsInput): Promise<SearchOutputOf<SC>>;
+    safeParse(props: RoutePropsInput): Promise<SafeResult<{
         params: ParamsOutput<Path, PC>;
         search: SearchOutputOf<SC>;
     }>>;
-    safeParseParams(props: ParamsProps): Promise<SafeResult<ParamsOutput<Path, PC>>>;
-    safeParseSearch(props: SearchProps): Promise<SafeResult<SearchOutputOf<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). */
 export type CatchAllNames<Path extends string> = Segments<Path> extends infer S extends string ? S extends `[...${infer Name}]` ? NonEmptyName<Name> : never : never;
@@ -52,7 +52,15 @@ export type CatchAllNames<Path extends string> = Segments<Path> extends infer S
 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}. */
 export type InferRouteParams<R extends AnyRoute> = ParamsOutput<R["path"], R["~params"]>;
-/** Accepts Next 15/16's promised props and plain objects alike (RL6). */
+/**
+ * Accepts promised props and plain objects alike (RL6). 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
+ * a page's `params` prop to be `Promise<any> | undefined` — a sync arm in
+ * {@link RouteProps} fails `next build` there. Hand-built sync props (tests,
+ * server code calling `parse` directly) stay legal via the input types.
+ */
 export type MaybePromise<T> = Promise<T> | T;
 /**
  * RL3: an empty name (`[]`, `[...]`, `[[...]]`) is not a token — it falls
@@ -145,6 +153,14 @@ export type ParamsOutput<Path extends string, PC> = {
  * global doesn't exist in fresh clones before `next dev` first runs.
  */
 export interface ParamsProps {
+    readonly params?: Promise<ParamsSource>;
+}
+/**
+ * What `parseParams` ACCEPTS (RL6): {@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). */
@@ -218,9 +234,18 @@ export type RouteConfig<Path extends string, PC extends ParamsConfig<Path>, SC e
     readonly params: ConformParams<Path, PC>;
     readonly search?: SC;
 };
-/** Full page-props contract (RL6): Next's `PageProps` is structurally assignable. */
+/**
+ * Full page-props contract (RL6): 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`
+ * global — core stays framework-agnostic.
+ */
 export interface RouteProps extends ParamsProps, SearchProps {
 }
+/** What `parse`/`safeParse` ACCEPT (RL6): {@link RouteProps} plus sync props. */
+export interface RoutePropsInput extends ParamsPropsInput, SearchPropsInput {
+}
 /** Which router a route belongs to (PR3) — the value of the `~router` brand. */
 export type RouterKind = "app" | "pages";
 /**
@@ -241,6 +266,10 @@ export type SafeResult<T> = {
  * shape is the same as the params side's, hence the shared source type.
  */
 export interface SearchProps {
+    readonly searchParams?: Promise<ParamsSource>;
+}
+/** Sync-accepting twin of {@link SearchProps} — see {@link ParamsPropsInput}. */
+export interface SearchPropsInput {
     readonly searchParams?: MaybePromise<ParamsSource>;
 }
 /**

package/package.json

@@ -1,13 +1,20 @@
 {
   "name": "paramour",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "type": "module",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "default": "./dist/internal.js"
     }
   },
+  "engines": {
+    "node": ">=22.13.0"
+  },
   "description": "Type-safe routing companion for the Next.js App Router: validated route params and search params, typed path building, and explicit URL serialization.",
   "keywords": [
     "nextjs",
@@ -49,6 +56,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
+    "check:publish": "publint --strict && attw --pack . --profile esm-only",
     "typecheck": "tsc --noEmit"
   }
 }