paramour 0.2.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jason Paff
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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 (currently `p.csv`) — the
+     * per-segment 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;
+     * currently `p.csv`).
+     */
+    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,15 @@
  */
 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: nested csv is rejected at construction (CV2),
+        // and element codecs are unmodified scalars with no element of their own.
+        ...(element === undefined ? {} : { element: describeCodec(element) }),
         ...(enumMembers === undefined ? {} : { enumMembers }),
         kind: codec["~kind"],
         presence: codec["~presence"],
@@ -42,6 +46,53 @@ 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)})`;
+    let label = description.element === undefined
+        ? kindLabel(description)
+        : `${description.kind}<${kindLabel(description.element)}>`;
+    if (description.arity === "many")
+        label += "[]";
+    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

@@ -6,6 +6,13 @@ import { type Codec } from "./codec.js";
  */
 export declare const p: {
     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
+     * 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;

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.
@@ -86,6 +86,12 @@ 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()` — codecs are immutable, so one
+ * schemaless string codec serves every list. Lazily built: `p` does not
+ * exist yet while the module initializes.
+ */
+let defaultCsvElement;
 /**
  * The `p.*` wire-codec builders (DESIGN §5 layer 1, design-02 D9).
  * Each codec defines how one value crosses the URL boundary, both directions.
@@ -109,6 +115,85 @@ 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
+     * 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());
+        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({
+            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,

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.0",
+  "version": "0.3.0",
   "type": "module",
   "exports": {
     ".": {
@@ -8,10 +8,6 @@
       "default": "./dist/index.js"
     }
   },
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "typecheck": "tsc --noEmit"
-  },
   "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",
@@ -37,6 +33,10 @@
   "files": [
     "dist"
   ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "dependencies": {
     "@standard-schema/spec": "^1.1.0"
   },
@@ -46,5 +46,9 @@
     "fast-check": "^4.8.0",
     "valibot": "^1.4.2",
     "zod": "^4.4.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit"
   }
-}
+}