paramour 0.2.1 → 0.4.0

package/dist/codec.d.ts

@@ -9,25 +9,41 @@ export type Arity = "many" | "single";
 /**
  * A bidirectional wire codec.
  *
- * `Out` is the decoded in-memory type. `P`, `C`, and `A` are type-state:
+ * `Out` is the decoded in-memory type. `P`, `C`, `A`, and `E` are type-state:
  * modifier methods are conditionally `never`, so illegal chains
  * (`.optional().default()`, double `.catch()`) fail to compile (design-02 D3).
+ * `E` carries `~defaultElides` as a literal after `.default()` (NQ6a).
  * Presence modifiers are also `never` for arity-"many" codecs: absent and `[]`
  * are the same wire state (S6/P6), so `.default()`/`.optional()` could never
  * round-trip there.
  *
  * `.default()` and `.catch()` accept either a value or a zero-arg factory;
  * factories are invoked per decode/encode, so reference-typed defaults can be
- * isolated per call (plain object values are returned by reference).
+ * isolated per call. Array values are shallow-copied per call for the same
+ * isolation; other plain object values are returned by reference.
  *
  * Properties prefixed `~` are internal machinery, not public API. For
  * arity-"many" codecs the element functions operate on single elements of
  * `Out` (which is an array type).
  */
-export interface Codec<Out, P extends Presence = "required", C extends boolean = false, A extends Arity = "single"> {
-    readonly catch: C extends false ? (fallback: (() => Out) | Out) => Codec<Out, P, true, A> : never;
-    readonly default: A extends "single" ? P extends "required" ? (value: (() => Out) | Out) => Codec<Out, "defaulted", C, A> : never : never;
-    readonly optional: A extends "single" ? P extends "required" ? () => Codec<Out, "optional", C, A> : never : never;
+export interface Codec<Out, P extends Presence = "required", C extends boolean = false, A extends Arity = "single", E extends boolean = boolean> {
+    readonly catch: C extends false ? (fallback: (() => Out) | Out) => Codec<Out, P, true, A, E> : never;
+    /**
+     * Overloaded so the value/factory split is visible in type-state (NQ6a):
+     * the factory overload comes FIRST and must stay first. The runtime
+     * {@link isFactory} check treats ANY function as a factory, so a function
+     * argument must either match the factory overload or fail to compile
+     * ({@link NonFactoryValue}) — E=true is only ever inferred for arguments
+     * the runtime will also treat as values. The one statically-invisible
+     * residue: an argument whose static type is not a function (e.g.
+     * `unknown`) but holds one at runtime lands on the runtime's factory
+     * branch anyway; no type-level check can see that.
+     */
+    readonly default: A extends "single" ? P extends "required" ? {
+        (value: () => Out): Codec<Out, "defaulted", C, A, false>;
+        <V extends Out>(value: NonFactoryValue<V> & V): Codec<Out, "defaulted", C, A, true>;
+    } : never : never;
+    readonly optional: A extends "single" ? P extends "required" ? () => Codec<Out, "optional", C, A, E> : never : never;
     readonly "~arity": A;
     /** Stored as a thunk regardless of the form passed to `.catch()`. */
     readonly "~catchValue": (() => Out) | undefined;
@@ -38,10 +54,22 @@ export interface Codec<Out, P extends Presence = "required", C extends boolean =
      * re-serialized per encode. Factory defaults never elide: a time-varying
      * factory would elide an explicitly-passed value that later decodes as a
      * different one.
+     *
+     * Literal-typed via `E` (NQ6a) so derived surfaces (`@paramour-js/nuqs`)
+     * can give value-defaulted keys non-nullable reads while keeping
+     * factory-defaulted keys honestly nullable. A hand-written
+     * `Codec<…, "defaulted">` leaves `E` at its `boolean` default, which
+     * consumers must treat as the factory (nullable) branch — the safe
+     * reading.
      */
-    readonly "~defaultElides": boolean;
+    readonly "~defaultElides": E;
     /** Stored as a thunk regardless of the form passed to `.default()`. */
     readonly "~defaultValue": (() => Out) | undefined;
+    /**
+     * 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. */
     readonly "~enumMembers": readonly string[] | undefined;
     /**
@@ -66,11 +94,24 @@ export type ParamCodec = Codec<any, "required", boolean>;
  */
 export type Presence = "defaulted" | "optional" | "required";
 export type PresenceOf<C extends AnyCodec> = C["~presence"];
+/**
+ * Rejects value-form `.default()` arguments whose static type includes any
+ * function member: runtime {@link isFactory} would treat them as factories,
+ * so letting them infer the value branch would let type-state assert an
+ * elision (`E = true`) the runtime never performs (NQ6a). Non-distributive
+ * on purpose — a union with a function member is rejected whole, since its
+ * runtime branch is unknowable at compile time.
+ */
+type NonFactoryValue<V> = [Extract<V, (...args: never[]) => unknown>] extends [
+    never
+] ? unknown : never;
 /** Internal factory used by the `p.*` builders. */
 export declare function createCodec<Out, A extends Arity = "single">(impl: {
     arity?: A;
+    element?: AnyCodec;
     enumMembers?: readonly string[];
     kind?: string;
     parseElement: (raw: string) => unknown;
     serializeElement: (value: unknown) => string;
 }): Codec<Out, "required", false, A>;
+export {};

package/dist/codec.js

@@ -6,6 +6,7 @@ export function createCodec(impl) {
         catchValue: undefined,
         defaultElides: false,
         defaultValue: undefined,
+        element: impl.element,
         enumMembers: impl.enumMembers,
         kind: impl.kind ?? "custom",
         parseElement: impl.parseElement,
@@ -60,6 +61,7 @@ function build(state) {
         "~caught": state.catchValue !== undefined,
         "~defaultElides": state.defaultElides,
         "~defaultValue": state.defaultValue,
+        "~element": state.element,
         "~enumMembers": state.enumMembers,
         "~kind": state.kind,
         "~parseElement": state.parseElement,
@@ -90,8 +92,15 @@ function serializeDefault(serializeElement, value) {
  * the one chokepoint where a throwing user factory is branded ParamourError.
  */
 function toThunk(stored, what) {
-    if (!isFactory(stored))
+    if (!isFactory(stored)) {
+        // Array values are handed out as fresh shallow copies: a consumer
+        // mutating a decoded fallback must not pollute later decodes or shift
+        // D8 elision (p.csv makes array defaults idiomatic — CV5). Non-array
+        // reference values stay by-reference; use a factory to isolate those.
+        if (Array.isArray(stored))
+            return () => stored.slice();
         return () => stored;
+    }
     return () => {
         try {
             return stored();

package/dist/describe.d.ts

@@ -22,10 +22,17 @@ export interface CodecDescription {
     readonly arity: Arity;
     readonly caught: boolean;
     readonly defaultValue?: CodecDefaultDescription;
+    /**
+     * Nested description of a composite list codec's element scalar (CV6;
+     * `p.csv` and `p.array`).
+     */
+    readonly element?: CodecDescription;
     readonly enumMembers?: readonly string[];
     readonly kind: string;
     readonly presence: Presence;
 }
+/** Rendering styles accepted by {@link formatCodecDescription}. */
+export type CodecFormatStyle = "compact" | "verbose";
 /** A param codec plus the dynamic-segment kind that hosts it. */
 export interface ParamDescription extends CodecDescription {
     readonly segmentKind: "catchall" | "optional-catchall" | "single";
@@ -61,3 +68,16 @@ export declare function describeCodec(codec: AnyCodec): CodecDescription;
  * both router brands — reflection only needs the data core.
  */
 export declare function describeRoute(route: AnyRoute): RouteDescription;
+/**
+ * One-line label for a {@link CodecDescription} — THE shared walk over the
+ * description's fields, so every consumer (the devtools panel's shape
+ * column, `paramour list`'s annotations) renders the same structure and a
+ * future field lands everywhere at once. Two skins over one walk:
+ *
+ * - `"compact"`: `enum(asc|desc)? =asc catch`, `csv<enum(a|b)>`, `string[]`
+ *   — `?` for optional presence, the default's wire form (`=3`) or `=ƒ()`
+ *   for a factory default, bare `catch`.
+ * - `"verbose"`: `enum(asc, desc) (optional) (default: asc) (catch)` —
+ *   parenthesized annotations in fixed order: presence, default, catch.
+ */
+export declare function formatCodecDescription(description: CodecDescription, style: CodecFormatStyle): string;

package/dist/describe.js

@@ -4,11 +4,16 @@
  */
 export function describeCodec(codec) {
     const defaultValue = describeDefault(codec);
+    const element = codec["~element"];
     const enumMembers = codec["~enumMembers"];
     return {
         arity: codec["~arity"],
         caught: codec["~caught"],
         ...(defaultValue === undefined ? {} : { defaultValue }),
+        // 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"],
         presence: codec["~presence"],
@@ -42,6 +47,64 @@ export function describeRoute(route) {
         search: describeSearch(route["~search"]),
     };
 }
+/**
+ * One-line label for a {@link CodecDescription} — THE shared walk over the
+ * description's fields, so every consumer (the devtools panel's shape
+ * column, `paramour list`'s annotations) renders the same structure and a
+ * future field lands everywhere at once. Two skins over one walk:
+ *
+ * - `"compact"`: `enum(asc|desc)? =asc catch`, `csv<enum(a|b)>`, `string[]`
+ *   — `?` for optional presence, the default's wire form (`=3`) or `=ƒ()`
+ *   for a factory default, bare `catch`.
+ * - `"verbose"`: `enum(asc, desc) (optional) (default: asc) (catch)` —
+ *   parenthesized annotations in fixed order: presence, default, catch.
+ */
+export function formatCodecDescription(description, style) {
+    const memberSeparator = style === "compact" ? "|" : ", ";
+    const kindLabel = (part) => part.enumMembers === undefined
+        ? part.kind
+        : `enum(${part.enumMembers.join(memberSeparator)})`;
+    // 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 += "?";
+        if (description.defaultValue !== undefined) {
+            label +=
+                description.defaultValue.kind === "value"
+                    ? ` =${description.defaultValue.wire}`
+                    : " =ƒ()";
+        }
+        if (description.caught)
+            label += " catch";
+        return label;
+    }
+    const notes = [];
+    if (description.presence === "optional")
+        notes.push("(optional)");
+    if (description.defaultValue !== undefined) {
+        notes.push(description.defaultValue.kind === "value"
+            ? `(default: ${description.defaultValue.wire})`
+            : "(default: factory)");
+    }
+    if (description.caught)
+        notes.push("(catch)");
+    return [label, ...notes].join(" ");
+}
 /**
  * Value-form defaults re-serialize the live value (the D8 ethos — never a
  * stale snapshot); a throwing serialize here means the default was mutated

package/dist/errors.d.ts

@@ -54,8 +54,12 @@ export declare class SerializeError extends ParamourError {
  */
 export declare function describeType(value: unknown): string;
 /**
- * Best-effort human-readable message for a foreign (non-paramour) throw.
- * Not exported from the package — internal to error branding.
+ * 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.
  */
 export declare function foreignMessage(error: unknown): string;
 /**

package/dist/errors.js

@@ -107,8 +107,12 @@ export function describeType(value) {
     return value === null ? "null" : typeof value;
 }
 /**
- * Best-effort human-readable message for a foreign (non-paramour) throw.
- * Not exported from the package — internal to error branding.
+ * 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.
  */
 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, describeCodec, describeRoute, type ParamDescription, type RouteDescription, type SearchDescription, } from "./describe.js";
-export { type Issue, ParamourError, ParamsDecodeError, ParseError, type RouteDecodeError, SearchDecodeError, SearchSourceError, SerializeError, } from "./errors.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 { 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 { safeDecodeParams, safeDecodeSearch } from "./safe-decode.js";
-export { buildSearchString, decodeSearch, encodeSearch, type InferSearchInput, type InferSearchOutput, rawSearch, type RawSearch, type SearchConfig, type SearchOutputOf, type SearchSource, searchToString, } from "./search.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 { standardSearchSchema, type StandardSearchSchema, } from "./standard-schema.js";

package/dist/index.js

@@ -1,10 +1,10 @@
 export {} from "./codec.js";
-export { describeCodec, describeRoute, } from "./describe.js";
-export { ParamourError, ParamsDecodeError, ParseError, SearchDecodeError, SearchSourceError, SerializeError, } from "./errors.js";
+export { describeCodec, describeRoute, formatCodecDescription, } from "./describe.js";
+export { foreignMessage, 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, rawSearch, searchToString, } from "./search.js";
+export { buildSearchString, decodeSearch, encodeSearch, isRawSearch, parseValue, rawSearch, searchToString, serializeValue, } from "./search.js";
 export { standardSearchSchema, } from "./standard-schema.js";

package/dist/p.d.ts

@@ -5,7 +5,21 @@ 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.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<E = string>(element?: Codec<E>): Codec<E[]>;
     custom<Out>(codec: {
         /** Reflection name shown by describeCodec/`paramour list` (default "custom"). */
         label?: string;
@@ -13,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

@@ -1,5 +1,5 @@
 import { createCodec } from "./codec.js";
-import { foreignMessage, ParseError, rebrandForeign, SerializeError, showValue, } from "./errors.js";
+import { foreignMessage, ParamourError, ParseError, rebrandForeign, SerializeError, showValue, } from "./errors.js";
 import { runStandardSchemaSync } from "./schema.js";
 // Wire grammars per wire-format spec §4. `Number()` alone is too loose
 // (accepts hex, trims whitespace), hence explicit anchored patterns.
@@ -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.
@@ -86,11 +120,44 @@ function serializeFiniteNumber(value) {
 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()`/`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 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",
@@ -109,6 +176,83 @@ 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.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); 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");
+        }
+        const parseInner = inner["~parseElement"];
+        const serializeInner = inner["~serializeElement"];
+        return createCodec({
+            element: inner,
+            kind: "csv",
+            parseElement: (raw) => {
+                // CV3: the empty wire string is [] — checked before split, because
+                // "".split(",") is [""], which the strict grammar would reject.
+                if (raw === "")
+                    return [];
+                const result = [];
+                for (const segment of raw.split(",")) {
+                    // CV3: strict grammar — "a,,b", trailing "a,", and a lone "," are
+                    // ParseErrors, recoverable via the LIST's .catch() (D2).
+                    if (segment === "") {
+                        throw new ParseError(`"${raw}" contains an empty list element`);
+                    }
+                    // CV3: the first element failure aborts the list parse — the
+                    // element codec's own ParseError propagates unwrapped.
+                    result.push(parseInner(segment));
+                }
+                return result;
+            },
+            serializeElement: (value) => {
+                if (!Array.isArray(value)) {
+                    throw new SerializeError(`Expected an array, got ${showValue(value)}`);
+                }
+                const parts = [];
+                for (const item of value) {
+                    const serialized = serializeInner(item);
+                    // A plain-JS custom element serializer can return a non-string;
+                    // enforce the string contract here — as search.ts/path.ts do at
+                    // their ~serializeElement call sites — so the CV4 guards below
+                    // cannot throw raw TypeErrors.
+                    if (typeof serialized !== "string") {
+                        throw new SerializeError(`List element serializer must return a string, got ${typeof serialized}`);
+                    }
+                    // CV4: an empty segment on re-parse; [""] is deliberately
+                    // unrepresentable — the empty wire string already means [].
+                    if (serialized === "") {
+                        throw new SerializeError(`List element ${showValue(item)} serializes to the empty string`);
+                    }
+                    // CV4: would mis-split on re-parse.
+                    if (serialized.includes(",")) {
+                        throw new SerializeError(`List element serialization "${serialized}" contains a comma`);
+                    }
+                    parts.push(serialized);
+                }
+                // [] joins to "" (CV5) — which is also why .default([])'s
+                // define-time pre-serialization succeeds and D8 elision compares
+                // [] against the empty wire form.
+                return parts.join(",");
+            },
+        });
+    },
     custom(codec) {
         // Paramour's own errors are never downgraded: ANY ParamourError thrown
         // by user parse/serialize code — config-level failures (async schema,
@@ -141,23 +285,50 @@ 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() {
         return createCodec({
             kind: "isoDate",
@@ -226,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/path.js

@@ -1,5 +1,5 @@
 import { describeType, ParamourError, ParamsDecodeError, ParseError, SerializeError, } from "./errors.js";
-import { encodeComponent, readInputValue } from "./search.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 `[`.
@@ -394,18 +394,14 @@ function serializeDynamicSegment(codec, segment, value) {
     };
 }
 /**
- * Serializes one segment value into its wire-string form. Enforces the
- * serializer's string contract exactly as search.ts's serializeValue does —
- * a plain-JS custom codec returning a non-string must never reach the byte
- * layer as the literal text "undefined". Percent-encoding is deliberately
- * NOT applied here: that is encodeParams' byte-layer step (S7), and the
- * static surfaces must skip it.
+ * Serializes one segment value into its wire-string form. The string
+ * contract is search.ts's shared {@link serializeValue}; the path surface
+ * layers R4 on top (a segment additionally can't be empty).
+ * Percent-encoding is deliberately NOT applied here: that is encodeParams'
+ * byte-layer step (S7), and the static surfaces must skip it.
  */
 function serializeSegmentValue(codec, name, value) {
-    const serialized = codec["~serializeElement"](value);
-    if (typeof serialized !== "string") {
-        throw new SerializeError(`serializer for route param "${name}" must return a string, got ${typeof serialized}`);
-    }
+    const serialized = serializeValue(codec, `route param "${name}"`, value);
     if (serialized === "") {
         // R4: "" would produce "//" or a vanishing segment — same rationale as R3.
         throw new SerializeError(`route param "${name}" serialized to an empty string, which cannot form a path segment`);

package/dist/search.d.ts

@@ -112,12 +112,28 @@ export declare function encodeComponent(text: string): string;
  */
 export declare function encodeSearch<S extends SearchSlot>(config: S, input: SearchInputOf<S>): [string, string][];
 /**
- * Runtime discriminant for the `search:` slot (design-04 SS2): the reserved
- * `~kind` marker is unambiguous against a codec map, which never carries a
- * top-level `~`-prefixed key. Module-exported for standard-schema.ts, not
- * barrel-exported.
+ * Runtime discriminant for the `search:` slot (design-04 SS2): probes the
+ * `~kind` marker's VALUE, which is unambiguous against a codec map — a map
+ * key literally named "~kind" would hold a codec object, never the marker
+ * string. Exported from the package barrel so derived surfaces
+ * (`@paramour-js/nuqs`) share the discriminant instead of duplicating the
+ * literal.
  */
 export declare function isRawSearch(config: SearchSlot): config is RawSearch<StandardSchemaV1>;
+/**
+ * Invokes a codec's element parser on one wire string — the parse twin of
+ * {@link serializeValue}, and the ONE sanctioned way to run a parse WITHOUT
+ * the codec's `.catch()` recovery applied (decodeSearch always recovers a
+ * caught failure, so a probe through it cannot tell "parsed cleanly" from
+ * "failed and was caught"). Exists for reflection-driven tooling — the
+ * devtools panel's catch-attribution probe (design-12 DT7) — and any other
+ * derived surface that must observe the raw parse outcome. A parse failure
+ * throws the codec's own {@link ParseError}; foreign throws from a custom
+ * codec propagate unwrapped, matching decodeSearch's taxonomy. For
+ * arity-"many" codecs this parses ONE element of the repeated-key array,
+ * not the whole array (the same contract as `~parseElement` itself).
+ */
+export declare function parseValue(codec: AnyCodec, raw: string): unknown;
 /**
  * The whole-object search escape hatch (design-04 SS1, maintainer ruling):
  * an explicit, greppable wrapper around a bare Standard Schema so a route's
@@ -152,4 +168,16 @@ export declare function readInputValue(values: Record<string, unknown>, key: str
 export declare function requireSearchConfig(config: SearchSlot): void;
 /** Convenience: encode + build in one step. */
 export declare function searchToString<S extends SearchSlot>(config: S, input: SearchInputOf<S>): string;
+/**
+ * Invokes a codec's serializer and enforces its string contract: a custom
+ * codec written in plain JS can return undefined, which would otherwise
+ * reach the byte layer as the literal text "undefined" — or, worse, match
+ * an absent default and silently drop the param. `label` names the value's
+ * site in the error (`search param "q"`, `route param "id"`, …). Exported
+ * from the package barrel as the ONE implementation of this contract:
+ * path.ts segments and derived surfaces (`@paramour-js/nuqs` eq/
+ * clearOnDefault) share it so their judgment stays identical to D8
+ * elision's by construction, not by parallel copies.
+ */
+export declare function serializeValue(codec: AnyCodec, label: string, value: unknown): string;
 export {};

package/dist/search.js

@@ -164,7 +164,10 @@ export function encodeSearch(config, input) {
             }
             // Array codecs cannot carry defaults, so no elision applies.
             for (const element of value) {
-                pairs.push([key, serializeValue(codec, key, element)]);
+                pairs.push([
+                    key,
+                    serializeValue(codec, `search param "${key}"`, element),
+                ]);
             }
             continue;
         }
@@ -174,13 +177,14 @@ export function encodeSearch(config, input) {
             }
             continue; // absent optional/defaulted param → key omitted (S3)
         }
-        const serialized = serializeValue(codec, key, value);
+        const serialized = serializeValue(codec, `search param "${key}"`, value);
         // D8 elision, gated on an elidable default existing — an ungated
         // comparison would let a (contract-violating) serialize that returns
         // undefined match undefined and silently drop the param.
         if (codec["~defaultElides"] &&
             codec["~defaultValue"] !== undefined &&
-            serialized === serializeValue(codec, key, codec["~defaultValue"]())) {
+            serialized ===
+                serializeValue(codec, `search param "${key}"`, codec["~defaultValue"]())) {
             continue;
         }
         pairs.push([key, serialized]);
@@ -188,14 +192,32 @@ export function encodeSearch(config, input) {
     return pairs;
 }
 /**
- * Runtime discriminant for the `search:` slot (design-04 SS2): the reserved
- * `~kind` marker is unambiguous against a codec map, which never carries a
- * top-level `~`-prefixed key. Module-exported for standard-schema.ts, not
- * barrel-exported.
+ * Runtime discriminant for the `search:` slot (design-04 SS2): probes the
+ * `~kind` marker's VALUE, which is unambiguous against a codec map — a map
+ * key literally named "~kind" would hold a codec object, never the marker
+ * string. Exported from the package barrel so derived surfaces
+ * (`@paramour-js/nuqs`) share the discriminant instead of duplicating the
+ * literal.
  */
 export function isRawSearch(config) {
     return "~kind" in config && config["~kind"] === "raw-search";
 }
+/**
+ * Invokes a codec's element parser on one wire string — the parse twin of
+ * {@link serializeValue}, and the ONE sanctioned way to run a parse WITHOUT
+ * the codec's `.catch()` recovery applied (decodeSearch always recovers a
+ * caught failure, so a probe through it cannot tell "parsed cleanly" from
+ * "failed and was caught"). Exists for reflection-driven tooling — the
+ * devtools panel's catch-attribution probe (design-12 DT7) — and any other
+ * derived surface that must observe the raw parse outcome. A parse failure
+ * throws the codec's own {@link ParseError}; foreign throws from a custom
+ * codec propagate unwrapped, matching decodeSearch's taxonomy. For
+ * arity-"many" codecs this parses ONE element of the repeated-key array,
+ * not the whole array (the same contract as `~parseElement` itself).
+ */
+export function parseValue(codec, raw) {
+    return codec["~parseElement"](raw);
+}
 /**
  * The whole-object search escape hatch (design-04 SS1, maintainer ruling):
  * an explicit, greppable wrapper around a bare Standard Schema so a route's
@@ -255,6 +277,24 @@ export function requireSearchConfig(config) {
 export function searchToString(config, input) {
     return buildSearchString(encodeSearch(config, input));
 }
+/**
+ * Invokes a codec's serializer and enforces its string contract: a custom
+ * codec written in plain JS can return undefined, which would otherwise
+ * reach the byte layer as the literal text "undefined" — or, worse, match
+ * an absent default and silently drop the param. `label` names the value's
+ * site in the error (`search param "q"`, `route param "id"`, …). Exported
+ * from the package barrel as the ONE implementation of this contract:
+ * path.ts segments and derived surfaces (`@paramour-js/nuqs` eq/
+ * clearOnDefault) share it so their judgment stays identical to D8
+ * elision's by construction, not by parallel copies.
+ */
+export function serializeValue(codec, label, value) {
+    const serialized = codec["~serializeElement"](value);
+    if (typeof serialized !== "string") {
+        throw new SerializeError(`serializer for ${label} must return a string, got ${typeof serialized}`);
+    }
+    return serialized;
+}
 /**
  * The `RawSearch` decode path (design-04 SS3/SS4). The schema receives EVERY
  * source key, normalized to Next's own `searchParams` shape — P8's
@@ -459,16 +499,3 @@ function requireRawSearchString(key, value) {
     }
     return value;
 }
-/**
- * Invokes a codec's serializer and enforces its string contract: a custom
- * codec written in plain JS can return undefined, which would otherwise
- * reach the byte layer as the literal text "undefined" — or, worse, match
- * an absent default and silently drop the param.
- */
-function serializeValue(codec, key, value) {
-    const serialized = codec["~serializeElement"](value);
-    if (typeof serialized !== "string") {
-        throw new SerializeError(`serializer for search param "${key}" must return a string, got ${typeof serialized}`);
-    }
-    return serialized;
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paramour",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "type": "module",
   "exports": {
     ".": {