paramour 0.8.0 → 0.9.0

package/dist/codec.d.ts

@@ -1,9 +1,13 @@
 /**
- * `any` is deliberate: `~out` appears in inferred method parameter positions
- * (`.default(value: Out)`), which are contravariant under strictFunctionTypes;
- * the `unknown` form would reject every concrete codec.
+ * Any codec, optionally narrowed to one output type: `AnyCodec<number>` is
+ * the supported spelling of "a codec producing numbers" in any presence,
+ * catch, or arity state — only `Codec`'s first type parameter is public API;
+ * the type-state parameters after it may change in minor releases. The
+ * `any` default is deliberate: `~out` appears in inferred method parameter
+ * positions (`.default(value: Out)`), which are contravariant under
+ * strictFunctionTypes; the `unknown` form would reject every concrete codec.
  */
-export type AnyCodec = Codec<any, Presence, boolean, Arity>;
+export type AnyCodec<Out = any> = Codec<Out, Presence, boolean, Arity>;
 /** "single" = one wire value per key; "many" = repeated keys (arrays). */
 export type Arity = "many" | "single";
 /**
@@ -71,18 +75,26 @@ export interface Codec<Out, P extends Presence = "required", C extends boolean =
     /** Members of a `p.enum` codec; undefined for every other kind. */
     readonly "~enumMembers": readonly string[] | undefined;
     /**
-     * Which builder produced the codec (`"integer"`, `"enum"`, …; `p.custom`
-     * uses its `label` or `"custom"`). Reflection metadata for describeCodec —
-     * never consulted by parse/serialize.
+     * Which builder produced the codec. Reflection metadata for describeCodec
+     * — never consulted by parse/serialize. `p.custom` is always `"custom"`,
+     * so a custom codec can never pass itself off as a built-in; its
+     * user-chosen name lives in `~label`.
      */
-    readonly "~kind": string;
+    readonly "~kind": CodecKind;
+    /** `p.custom`'s display label; undefined for every other codec. */
+    readonly "~label": string | undefined;
     /** phantom — carries `Out` for inference; never set at runtime */
     readonly "~out": Out;
     readonly "~parseElement": (raw: string) => unknown;
     readonly "~presence": P;
     readonly "~serializeElement": (value: unknown) => string;
 }
-export type OutputOf<C extends AnyCodec> = C["~out"];
+/**
+ * Which builder produced a codec. New builders add members in minor
+ * releases, so exhaustive switches over it need a default branch.
+ */
+export type CodecKind = "array" | "boolean" | "csv" | "custom" | "enum" | "index" | "integer" | "isoDate" | "json" | "number" | "string" | "timestamp";
+export type InferCodecOutput<C extends AnyCodec> = C["~out"];
 /** Codecs legal in a `params:` config — no presence modifiers (D5). */
 export type ParamCodec = Codec<any, "required", boolean>;
 /**
@@ -108,7 +120,8 @@ export declare function createCodec<Out, A extends Arity = "single">(impl: {
     arity?: A;
     element?: AnyCodec;
     enumMembers?: readonly string[];
-    kind?: string;
+    kind?: CodecKind;
+    label?: string;
     parseElement: (raw: string) => unknown;
     serializeElement: (value: unknown) => string;
 }): Codec<Out, "required", false, A>;

package/dist/codec.js

@@ -9,6 +9,7 @@ export function createCodec(impl) {
         element: impl.element,
         enumMembers: impl.enumMembers,
         kind: impl.kind ?? "custom",
+        label: impl.label,
         parseElement: impl.parseElement,
         presence: "required",
         serializeElement: impl.serializeElement,
@@ -64,6 +65,7 @@ function build(state) {
         "~element": state.element,
         "~enumMembers": state.enumMembers,
         "~kind": state.kind,
+        "~label": state.label,
         "~parseElement": state.parseElement,
         "~presence": state.presence,
         "~serializeElement": state.serializeElement,

package/dist/describe.d.ts

@@ -1,4 +1,4 @@
-import type { AnyCodec, Arity, Presence } from "./codec.js";
+import type { AnyCodec, Arity, CodecKind, Presence } from "./codec.js";
 import type { AnyRoute, RouterKind } from "./route.js";
 /**
  * `.default()` in reflected form. Value-form defaults carry their wire
@@ -28,7 +28,9 @@ export interface CodecDescription {
      */
     readonly element?: CodecDescription;
     readonly enumMembers?: readonly string[];
-    readonly kind: string;
+    readonly kind: CodecKind;
+    /** A `p.custom` codec's display label, when it was given one. */
+    readonly label?: string;
     readonly presence: Presence;
 }
 /** Rendering styles accepted by {@link formatCodecDescription}. */

package/dist/describe.js

@@ -28,6 +28,7 @@ export function describeCodec(codec) {
         ...(element === undefined ? {} : { element: describeCodec(element) }),
         ...(enumMembers === undefined ? {} : { enumMembers }),
         kind: codec["~kind"],
+        ...(codec["~label"] === undefined ? {} : { label: codec["~label"] }),
         presence: codec["~presence"],
     };
 }
@@ -76,8 +77,9 @@ export function describeRoute(route) {
  */
 export function formatCodecDescription(description, style) {
     const memberSeparator = style === "verbose" ? ", " : "|";
+    // A custom codec renders its label when it has one; otherwise its kind.
     const kindLabel = (part) => part.enumMembers === undefined
-        ? part.kind
+        ? (part.label ?? 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

package/dist/errors.d.ts

@@ -57,6 +57,7 @@ export declare class ParamourError extends Error {
 /** Aggregate failure for a whole route-params decode. */
 export declare class ParamsDecodeError extends ParamourError {
     readonly issues: readonly Issue[];
+    readonly name: "ParamsDecodeError";
     /** The failed route's path pattern; null when decoded outside a route. */
     readonly route: null | string;
     constructor(issues: readonly Issue[], route?: null | string);
@@ -68,7 +69,14 @@ export declare class ParamsDecodeError extends ParamourError {
  */
 export declare class ParseError extends ParamourError {
     /**
-     * True when the message follows core's grammar-authoring convention —
+     * Literal per class, so the decode errors stay structurally distinct
+     * (the `SafeResult` error parameter relies on it) and `error.name`
+     * survives minification.
+     */
+    readonly name: "ParseError";
+    /**
+     * Internal, outside semver: true when the message follows core's
+     * grammar-authoring convention —
      * it quotes the offending wire value and names the grammar it failed
      * (`'"x" is not an integer'`). Only core's own grammar throw sites set
      * it (via {@link grammarParseError}); schema-validation failures and
@@ -77,16 +85,13 @@ export declare class ParseError extends ParamourError {
      * expected-shape context themselves. This flag — never message sniffing
      * — is what issue producers key `reason: "parse" | "validate"` on.
      */
-    readonly selfDescribing: boolean;
-    constructor(message: string, options?: {
-        cause?: unknown;
-        selfDescribing?: boolean;
-    });
+    readonly "~selfDescribing": boolean;
     static [Symbol.hasInstance](value: unknown): value is ParseError;
 }
 /** Aggregate failure for a whole search-params decode. */
 export declare class SearchDecodeError extends ParamourError {
     readonly issues: readonly Issue[];
+    readonly name: "SearchDecodeError";
     /** The failed route's path pattern; null when decoded outside a route. */
     readonly route: null | string;
     constructor(issues: readonly Issue[], route?: null | string);
@@ -102,11 +107,13 @@ export declare class SearchDecodeError extends ParamourError {
 export declare class SearchSourceError extends ParamourError {
     /** The offending source key, or null when the source itself is malformed. */
     readonly key: null | string;
+    readonly name: "SearchSourceError";
     constructor(message: string, key: null | string);
     static [Symbol.hasInstance](value: unknown): value is SearchSourceError;
 }
 /** A value could not be serialized to the wire (bad type, non-finite, etc.). */
 export declare class SerializeError extends ParamourError {
+    readonly name: "SerializeError";
     static [Symbol.hasInstance](value: unknown): value is SerializeError;
 }
 /**
@@ -137,7 +144,7 @@ export declare function grammarParseError(message: string): ParseError;
  * Maps a caught {@link ParseError} to its {@link Issue} reason: core's
  * grammar-authored messages are `"parse"`, everything else — schema
  * validators, rebranded custom-codec throws — is `"validate"`. Keyed on the
- * structural `selfDescribing` flag, never on message sniffing; shared by
+ * structural `~selfDescribing` flag, never on message sniffing; shared by
  * search.ts and path.ts so both surfaces classify identically. Not exported
  * from the package.
  */

package/dist/errors.js

@@ -20,7 +20,12 @@ export class ParamourError extends Error {
     }
     constructor(message, options) {
         super(message, options);
-        this.name = new.target.name;
+        // Paramour's own classes pin a literal `name` field (which runs after
+        // this and wins) — a minifier that drops class names would otherwise
+        // rename them in production. User subclasses fall back to their class
+        // name.
+        this.name =
+            new.target === ParamourError ? "ParamourError" : new.target.name;
     }
     // Each class checks its OWN brand: an inherited base check would make
     // every ParamourError pass `instanceof ParseError`. The type-predicate
@@ -35,6 +40,7 @@ export class ParamsDecodeError extends ParamourError {
         brandPrototype(this, paramsDecodeErrorBrand);
     }
     issues;
+    name = "ParamsDecodeError";
     /** The failed route's path pattern; null when decoded outside a route. */
     route;
     constructor(issues, route = null) {
@@ -55,7 +61,14 @@ export class ParseError extends ParamourError {
         brandPrototype(this, parseErrorBrand);
     }
     /**
-     * True when the message follows core's grammar-authoring convention —
+     * Literal per class, so the decode errors stay structurally distinct
+     * (the `SafeResult` error parameter relies on it) and `error.name`
+     * survives minification.
+     */
+    name = "ParseError";
+    /**
+     * Internal, outside semver: true when the message follows core's
+     * grammar-authoring convention —
      * it quotes the offending wire value and names the grammar it failed
      * (`'"x" is not an integer'`). Only core's own grammar throw sites set
      * it (via {@link grammarParseError}); schema-validation failures and
@@ -64,11 +77,7 @@ export class ParseError extends ParamourError {
      * expected-shape context themselves. This flag — never message sniffing
      * — is what issue producers key `reason: "parse" | "validate"` on.
      */
-    selfDescribing;
-    constructor(message, options) {
-        super(message, options);
-        this.selfDescribing = options?.selfDescribing ?? false;
-    }
+    "~selfDescribing" = false;
     static [Symbol.hasInstance](value) {
         return hasBrand(value, parseErrorBrand);
     }
@@ -79,6 +88,7 @@ export class SearchDecodeError extends ParamourError {
         brandPrototype(this, searchDecodeErrorBrand);
     }
     issues;
+    name = "SearchDecodeError";
     /** The failed route's path pattern; null when decoded outside a route. */
     route;
     constructor(issues, route = null) {
@@ -103,6 +113,7 @@ export class SearchSourceError extends ParamourError {
     }
     /** The offending source key, or null when the source itself is malformed. */
     key;
+    name = "SearchSourceError";
     constructor(message, key) {
         super(message);
         this.key = key;
@@ -116,6 +127,7 @@ export class SerializeError extends ParamourError {
     static {
         brandPrototype(this, serializeErrorBrand);
     }
+    name = "SerializeError";
     static [Symbol.hasInstance](value) {
         return hasBrand(value, serializeErrorBrand);
     }
@@ -148,18 +160,21 @@ export function foreignMessage(error) {
  * Not exported from the package.
  */
 export function grammarParseError(message) {
-    return new ParseError(message, { selfDescribing: true });
+    const error = new ParseError(message);
+    // The one setter: the flag is readonly to everyone else.
+    error["~selfDescribing"] = true;
+    return error;
 }
 /**
  * Maps a caught {@link ParseError} to its {@link Issue} reason: core's
  * grammar-authored messages are `"parse"`, everything else — schema
  * validators, rebranded custom-codec throws — is `"validate"`. Keyed on the
- * structural `selfDescribing` flag, never on message sniffing; shared by
+ * structural `~selfDescribing` flag, never on message sniffing; shared by
  * search.ts and path.ts so both surfaces classify identically. Not exported
  * from the package.
  */
 export function parseIssueReason(error) {
-    return error.selfDescribing ? "parse" : "validate";
+    return error["~selfDescribing"] ? "parse" : "validate";
 }
 /**
  * Runs user (or platform) code, letting paramour's own errors pass through

package/dist/href.d.ts

@@ -1,6 +1,6 @@
 import type { AnyRoute, RegisteredStaticRoutePaths } from "./route.js";
 import { type InferParamsInput } from "./path.js";
-import { type SearchInputOf } from "./search.js";
+import { type InferSearchInput } from "./search.js";
 /**
  * Type-only brand carrier: no runtime value ever exists — the brand is
  * applied by a compile-time cast, so Href costs nothing at runtime.
@@ -30,7 +30,7 @@ export type HrefArgs<R extends AnyRoute> = Record<never, never> extends InferHre
  * keys AT ALL may not be passed even empty (see PartFor). `hash` implements
  * S10 — fragments come only from an explicit caller option.
  */
-export type InferHrefInput<R extends AnyRoute> = PartFor<"params", InferParamsInput<R>> & PartFor<"search", SearchInputOf<R["~search"]>> & {
+export type InferHrefInput<R extends AnyRoute> = PartFor<"params", InferParamsInput<R>> & PartFor<"search", InferSearchInput<R["~search"]>> & {
     hash?: string;
 };
 /**

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 AnyCodec, type Arity, type Codec, type CodecKind, type InferCodecOutput, 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 { type Issue, type IssueReason, 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 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 { type AnyAppRoute, type AnyPagesRoute, type AnyRoute, type AppRoute, defineAppRoute, definePagesRoute, type InferRouteParams, type InferRouteSearch, type PagesContext, type PagesRoute, type ParamourRegister, type ParamsConfig, type ParamsProps, type ParamsPropsLike, type RegisteredAppRoutePaths, type RegisteredPagesRoutePaths, type RegisteredStaticAppRoutePaths, type RegisteredStaticPagesRoutePaths, type RegisteredStaticRoutePaths, type Route, type RouteConfig, type RouteProps, type RoutePropsLike, type RouterKind, type SafeResult, type SearchProps, type SearchPropsLike, } from "./route.js";
 export { safeDecodeParams, safeDecodeSearch } from "./safe-decode.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 { buildSearchString, decodeSearch, encodeSearch, type InferSearchInput, type InferSearchOutput, isRawSearch, parseValue, rawSearch, type RawSearch, type SearchConfig, type SearchSlot, type SearchSource, searchToString, serializeValue, } from "./search.js";
 export { standardSearchSchema, type StandardSearchSchema, } from "./standard-schema.js";

package/dist/index.js

@@ -6,5 +6,5 @@ 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, rawSearch, searchToString, serializeValue, } from "./search.js";
+export { buildSearchString, decodeSearch, encodeSearch, isRawSearch, parseValue, rawSearch, searchToString, serializeValue, } from "./search.js";
 export { standardSearchSchema, } from "./standard-schema.js";

package/dist/internal.d.ts

@@ -1,12 +1,13 @@
 /**
- * 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
- * exist solely so reflection-driven consumers (the devtools panel's
- * catch-attribution probe, edit preview, and synthesized-issue labels)
- * share core's implementation instead of re-deriving it.
+ * The `paramour/internal` entry: helpers for derived tooling (devtools,
+ * adapters), NOT for app authors — they live off the main barrel so the
+ * docs' Reference section stays the app-author surface. Covered by semver
+ * within a major all the same (additions only until the next major): the
+ * devtools panel peers on `paramour` with a caret range, so a newer core
+ * must never break an installed panel that imports from here. These exist
+ * so reflection-driven consumers (the panel's synthesized-issue labels and
+ * foreign-error rendering) share core's implementation instead of
+ * re-deriving it.
  */
 export { codecShapeLabel } from "./describe.js";
 export { foreignMessage } from "./errors.js";
-export { parseValue } from "./search.js";

package/dist/internal.js

@@ -1,12 +1,13 @@
 /**
- * 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
- * exist solely so reflection-driven consumers (the devtools panel's
- * catch-attribution probe, edit preview, and synthesized-issue labels)
- * share core's implementation instead of re-deriving it.
+ * The `paramour/internal` entry: helpers for derived tooling (devtools,
+ * adapters), NOT for app authors — they live off the main barrel so the
+ * docs' Reference section stays the app-author surface. Covered by semver
+ * within a major all the same (additions only until the next major): the
+ * devtools panel peers on `paramour` with a caret range, so a newer core
+ * must never break an installed panel that imports from here. These exist
+ * so reflection-driven consumers (the panel's synthesized-issue labels and
+ * foreign-error rendering) share core's implementation instead of
+ * re-deriving it.
  */
 export { codecShapeLabel } from "./describe.js";
 export { foreignMessage } from "./errors.js";
-export { parseValue } from "./search.js";

package/dist/p.js

@@ -6,9 +6,11 @@ import { runStandardSchemaSync } from "./schema.js";
 const INTEGER_RE = /^-?\d+$/;
 const NUMBER_RE = /^-?\d+(\.\d+)?([eE][+-]?\d+)?$/;
 const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
-// Canonical emit is Date#toISOString (milliseconds always); parse tolerates
-// missing milliseconds. UTC (`Z`) only — offsets are rejected in v0.1.
-const TIMESTAMP_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?Z$/;
+// Canonical emit is Date#toISOString (UTC, milliseconds always); parse
+// tolerates missing milliseconds and accepts a `Z` or `±HH:MM` offset, so
+// links from systems that emit local-offset timestamps decode to the same
+// instant. The emit side never produces an offset: one instant, one URL.
+const TIMESTAMP_RE = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,3}))?(?:Z|([+-])(\d{2}):(\d{2}))$/;
 /**
  * Serialize-side Date guard. Years outside 0000–9999 are rejected:
  * toISOString switches to the expanded ±6-digit-year form there, which the
@@ -190,8 +192,8 @@ export const p = {
         // CV2: presence, catch, and arity-many inners are excluded by the
         // parameter type (the same type-state philosophy); resolveListElement
         // mirrors that type-state for JS consumers. 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
+        // structurally via ~element (never via ~kind, which is reflection-only).
+        // 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
@@ -264,7 +266,7 @@ export const p = {
         // aggregation. .catch() recovers foreign parse failures only, which
         // rebrandForeign normalizes to ParseError so recovery sees them.
         return createCodec({
-            ...(codec.label === undefined ? {} : { kind: codec.label }),
+            ...(codec.label === undefined ? {} : { label: codec.label }),
             parseElement: (raw) => rebrandForeign(() => codec.parse(raw), 
             // Not grammarParseError: foreign prose may name neither the value
             // nor the grammar, so decode issues classify it "validate" and
@@ -409,20 +411,43 @@ export const p = {
         return createCodec({
             kind: "timestamp",
             parseElement: (raw) => {
-                if (!TIMESTAMP_RE.test(raw)) {
-                    throw grammarParseError(`"${raw}" is not an ISO 8601 UTC timestamp`);
+                const match = TIMESTAMP_RE.exec(raw);
+                if (!match) {
+                    throw grammarParseError(`"${raw}" is not an ISO 8601 timestamp`);
                 }
-                const date = new Date(raw);
-                if (Number.isNaN(date.getTime())) {
-                    throw grammarParseError(`"${raw}" is not a real instant`);
+                const [year, month, day, hour, minute, second] = match
+                    .slice(1, 7)
+                    .map(Number);
+                const millis = Number((match[7] ?? "").padEnd(3, "0"));
+                const sign = match[8] === "-" ? -1 : 1;
+                const offsetHours = Number(match[9] ?? "0");
+                const offsetMinutes = Number(match[10] ?? "0");
+                if (offsetHours > 23 || offsetMinutes > 59) {
+                    throw grammarParseError(`"${raw}" has an impossible UTC offset`);
                 }
-                // The engine silently normalizes impossible fields (Feb 30 → Mar 1,
-                // 24:00 → next day). Pad the input to canonical millisecond form and
-                // require an exact round-trip instead.
-                const canonical = raw.replace(/(?:\.(\d{1,3}))?Z$/, (_match, ms) => `.${(ms ?? "").padEnd(3, "0")}Z`);
-                if (date.toISOString() !== canonical) {
+                // Built field by field — Date.UTC maps years 0–99 to 1900–1999 —
+                // then checked field by field: the engine silently normalizes
+                // impossible fields (Feb 30 → Mar 1, 24:00 → next day), which must
+                // be rejected, not reinterpreted.
+                const local = new Date(0);
+                local.setUTCFullYear(year, month - 1, day);
+                local.setUTCHours(hour, minute, second, millis);
+                if (local.getUTCFullYear() !== year ||
+                    local.getUTCMonth() !== month - 1 ||
+                    local.getUTCDate() !== day ||
+                    local.getUTCHours() !== hour ||
+                    local.getUTCMinutes() !== minute ||
+                    local.getUTCSeconds() !== second) {
                     throw grammarParseError(`"${raw}" is not a real instant`);
                 }
+                const date = new Date(local.getTime() - sign * (offsetHours * 60 + offsetMinutes) * 60_000);
+                // An offset can push the instant outside what the canonical UTC form
+                // can represent (0000-01-01T00:30+01:00 is year -1); every decoded
+                // value must re-serialize, so reject it here rather than at encode.
+                const utcYear = date.getUTCFullYear();
+                if (utcYear < 0 || utcYear > 9999) {
+                    throw grammarParseError(`"${raw}" is outside the representable 0000-9999 range in UTC`);
+                }
                 return date;
             },
             serializeElement: (value) => expectSerializableDate(value).toISOString(),

package/dist/path.js

@@ -98,7 +98,7 @@ export function decodeParams(route, source, options) {
                             key: segment.name,
                             message: error.message,
                             // "parse" vs "validate" comes from the ParseError's own
-                            // selfDescribing flag — structural, never message sniffing.
+                            // ~selfDescribing flag — structural, never message sniffing.
                             reason: parseIssueReason(error),
                             // Issue.wire is the codec-grammar-layer value — the DECODED
                             // segment, not the raw URL text — matching decodeSearch,

package/dist/route.d.ts

@@ -1,7 +1,7 @@
-import type { AnyCodec, OutputOf, ParamCodec } from "./codec.js";
-import { type RouteDecodeError } from "./errors.js";
+import type { AnyCodec, InferCodecOutput, ParamCodec } from "./codec.js";
+import { ParamsDecodeError, type RouteDecodeError, SearchDecodeError } from "./errors.js";
 import { type ParamsSource, type PathSegment } from "./path.js";
-import { type SearchOutputOf, type SearchSlot } from "./search.js";
+import { type InferSearchOutput, type SearchSlot } from "./search.js";
 /**
  * `any` is deliberate (same variance gotcha as AnyCodec): codec configs
  * reach contravariant positions through the parse methods and `HrefArgs`;
@@ -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: RoutePropsInput): Promise<{
+    parse(props: RoutePropsLike): Promise<{
         params: ParamsOutput<Path, PC>;
-        search: SearchOutputOf<SC>;
+        search: InferSearchOutput<SC>;
     }>;
     /** Bare params object — layout props are structurally assignable. */
-    parseParams(props: ParamsPropsInput): Promise<ParamsOutput<Path, PC>>;
+    parseParams(props: ParamsPropsLike): Promise<ParamsOutput<Path, PC>>;
     /** Bare search object — the search half alone. */
-    parseSearch(props: SearchPropsInput): Promise<SearchOutputOf<SC>>;
-    safeParse(props: RoutePropsInput): Promise<SafeResult<{
+    parseSearch(props: SearchPropsLike): Promise<InferSearchOutput<SC>>;
+    safeParse(props: RoutePropsLike): Promise<SafeResult<{
         params: ParamsOutput<Path, PC>;
-        search: SearchOutputOf<SC>;
+        search: InferSearchOutput<SC>;
     }>>;
-    safeParseParams(props: ParamsPropsInput): Promise<SafeResult<ParamsOutput<Path, PC>>>;
-    safeParseSearch(props: SearchPropsInput): Promise<SafeResult<SearchOutputOf<SC>>>;
+    safeParseParams(props: ParamsPropsLike): Promise<SafeResult<ParamsOutput<Path, PC>, ParamsDecodeError>>;
+    safeParseSearch(props: SearchPropsLike): Promise<SafeResult<InferSearchOutput<SC>, SearchDecodeError>>;
 }
 /** Names of `[...name]` catch-all segments in the path literal. */
 export type CatchAllNames<Path extends string> = Segments<Path> extends infer S extends string ? S extends `[...${infer Name}]` ? NonEmptyName<Name> : never : never;
@@ -52,9 +52,14 @@ 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; see {@link ParamsOutput}. */
 export type InferRouteParams<R extends AnyRoute> = ParamsOutput<R["path"], R["~params"]>;
+/**
+ * Decoded search object type for a route — the {@link InferRouteParams}
+ * twin, and the public spelling that keeps `~search` out of user code.
+ */
+export type InferRouteSearch<R extends AnyRoute> = InferSearchOutput<R["~search"]>;
 /**
  * Accepts promised props and plain objects alike. This width lives on
- * the parse INPUT surface ({@link RoutePropsInput} and friends), not on the
+ * the parse INPUT surface ({@link RoutePropsLike} 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
@@ -105,12 +110,12 @@ export interface PagesRoute<Path extends string, PC extends ParamsConfig<Path>,
      */
     parseContext(context: PagesContext): {
         params: ParamsOutput<Path, PC>;
-        search: SearchOutputOf<SC>;
+        search: InferSearchOutput<SC>;
     };
     /** {@link parseContext} in the safe shape — `safely`'s taxonomy. */
     safeParseContext(context: PagesContext): SafeResult<{
         params: ParamsOutput<Path, PC>;
-        search: SearchOutputOf<SC>;
+        search: InferSearchOutput<SC>;
     }>;
 }
 /**
@@ -124,7 +129,7 @@ export interface PagesRoute<Path extends string, PC extends ParamsConfig<Path>,
 export interface ParamourRegister {
 }
 /** The decoded output type of the codec at key `K`, if one is declared. */
-export type ParamOutput<PC, K extends PropertyKey> = K extends keyof PC ? PC[K] extends AnyCodec ? OutputOf<PC[K]> : never : never;
+export type ParamOutput<PC, K extends PropertyKey> = K extends keyof PC ? PC[K] extends AnyCodec ? InferCodecOutput<PC[K]> : never : never;
 /**
  * Params schema shape for a path: one codec per dynamic segment name. The
  * codec describes ONE segment element (D5/D6) — arrays come from the segment
@@ -160,7 +165,7 @@ export interface ParamsProps {
  * objects — see {@link MaybePromise} for why the annotation type is
  * promise-only while the parse input stays wide.
  */
-export interface ParamsPropsInput {
+export interface ParamsPropsLike {
     readonly params?: MaybePromise<ParamsSource>;
 }
 /** Every dynamic segment name in the path literal. */
@@ -206,7 +211,8 @@ export type RegisteredStaticRoutePaths = [PresentRegisteredPaths] extends [
  * {@link AppRoute} / {@link PagesRoute} — gating it via the interface split
  * makes the wrong surface ABSENT, not just ill-typed. `~`-prefixed members
  * are runtime-internal, not public API — same convention as codecs;
- * `@paramour/next` is a blessed consumer, user code is not.
+ * the lockstep `@paramour-js/*` packages are blessed consumers, user code is
+ * not — and these members are outside semver.
  */
 export interface Route<Path extends string, PC extends ParamsConfig<Path>, SC extends SearchSlot, R extends RouterKind = RouterKind> {
     readonly path: Path;
@@ -244,7 +250,7 @@ export type RouteConfig<Path extends string, PC extends ParamsConfig<Path>, SC e
 export interface RouteProps extends ParamsProps, SearchProps {
 }
 /** What `parse`/`safeParse` ACCEPT: {@link RouteProps} plus sync props. */
-export interface RoutePropsInput extends ParamsPropsInput, SearchPropsInput {
+export interface RoutePropsLike extends ParamsPropsLike, SearchPropsLike {
 }
 /** Which router a route belongs to — the value of the `~router` brand. */
 export type RouterKind = "app" | "pages";
@@ -252,13 +258,15 @@ export type RouterKind = "app" | "pages";
  * Status-discriminated result shape, unified with the pages hooks'
  * `RouterResult` (which extends this union by one `pending` member):
  * `if (result.status === "error")` narrows both arms, and both routers'
- * results destructure identically.
+ * results destructure identically. `E` narrows the error arm on surfaces
+ * that can only fail one way — params-only surfaces carry
+ * `ParamsDecodeError`, search-only ones `SearchDecodeError`.
  */
-export type SafeResult<T> = {
+export type SafeResult<T, E extends RouteDecodeError = RouteDecodeError> = {
     data: T;
     status: "success";
 } | {
-    error: RouteDecodeError;
+    error: E;
     status: "error";
 };
 /**
@@ -268,8 +276,8 @@ export type SafeResult<T> = {
 export interface SearchProps {
     readonly searchParams?: Promise<ParamsSource>;
 }
-/** Sync-accepting twin of {@link SearchProps} — see {@link ParamsPropsInput}. */
-export interface SearchPropsInput {
+/** Sync-accepting twin of {@link SearchProps} — see {@link ParamsPropsLike}. */
+export interface SearchPropsLike {
     readonly searchParams?: MaybePromise<ParamsSource>;
 }
 /**

package/dist/route.js

@@ -1,6 +1,6 @@
 import { describeType, foreignMessage, ParamourError, ParamsDecodeError, SearchDecodeError, } from "./errors.js";
 import { decodeParams, tokenizePath, } from "./path.js";
-import { decodeSearch, } from "./search.js";
+import { decodeSearchSlot, } from "./search.js";
 /**
  * Defines an App Router route: the URL-shaped path literal plus its
  * param/search codec configs. Validates the literal eagerly — fail-fast at
@@ -19,7 +19,7 @@ export function defineAppRoute(path, config) {
             const decodedParams = decodeParams(route, paramsSource ?? {});
             return {
                 params: decodedParams,
-                search: decodeSearch(route["~search"], searchSource ?? {}, route.path),
+                search: decodeSearchSlot(route["~search"], searchSource ?? {}, route.path),
             };
         },
         async parseParams(props) {
@@ -28,7 +28,7 @@ export function defineAppRoute(path, config) {
         },
         async parseSearch(props) {
             const source = await awaitProp(props.searchParams);
-            return decodeSearch(route["~search"], source ?? {}, route.path);
+            return decodeSearchSlot(route["~search"], source ?? {}, route.path);
         },
         safeParse(props) {
             return safely(() => route.parse(props));
@@ -71,7 +71,7 @@ export function definePagesRoute(path, config) {
             });
             return {
                 params: decodedParams,
-                search: decodeSearch(route["~search"], searchSource, route.path),
+                search: decodeSearchSlot(route["~search"], searchSource, route.path),
             };
         },
         safeParseContext(context) {
@@ -173,7 +173,9 @@ function routeData(router, path, config) {
 /**
  * Wraps a throwing parse into the status-discriminated shape.
  * Only decode failures become the `error` arm; source-contract violations
- * and rebranded foreign errors stay loud.
+ * and rebranded foreign errors stay loud. `E` is the caller's claim about
+ * which decode error `run` can throw — params-only runs never throw
+ * `SearchDecodeError` and vice versa, which is what makes the cast sound.
  */
 async function safely(run) {
     try {
@@ -182,7 +184,7 @@ async function safely(run) {
     catch (error) {
         if (error instanceof ParamsDecodeError ||
             error instanceof SearchDecodeError) {
-            return { error, status: "error" };
+            return { error: error, status: "error" };
         }
         throw error;
     }

package/dist/safe-decode.d.ts

@@ -1,6 +1,7 @@
 import type { AnyRoute, InferRouteParams, SafeResult } from "./route.js";
+import { ParamsDecodeError, SearchDecodeError } from "./errors.js";
 import { type DecodeParamsOptions, type ParamsSource } from "./path.js";
-import { type SearchOutputOf, type SearchSource } from "./search.js";
+import { type InferSearchOutput, type SearchSlot, type SearchSource, type SlotOf } from "./search.js";
 /**
  * Sync `SafeResult` twins of {@link decodeParams} / {@link decodeSearch},
  * carrying the route methods' safe-parse stance down to the
@@ -12,6 +13,9 @@ import { type SearchOutputOf, type SearchSource } from "./search.js";
  * unchanged.
  */
 /** Decoded route params as a `SafeResult` (discriminated on `status`). */
-export declare function safeDecodeParams<R extends AnyRoute>(route: R, source: ParamsSource, options?: DecodeParamsOptions): SafeResult<InferRouteParams<R>>;
-/** Decoded search params as a `SafeResult` (discriminated on `status`). */
-export declare function safeDecodeSearch<R extends AnyRoute>(route: R, source: SearchSource): SafeResult<SearchOutputOf<R["~search"]>>;
+export declare function safeDecodeParams<R extends AnyRoute>(route: R, source: ParamsSource, options?: DecodeParamsOptions): SafeResult<InferRouteParams<R>, ParamsDecodeError>;
+/**
+ * Decoded search params as a `SafeResult` (discriminated on `status`).
+ * `target` is a route or a bare `search:` slot, as for {@link decodeSearch}.
+ */
+export declare function safeDecodeSearch<T extends AnyRoute | SearchSlot>(target: T, source: SearchSource): SafeResult<InferSearchOutput<SlotOf<T>>, SearchDecodeError>;

package/dist/safe-decode.js

@@ -22,18 +22,13 @@ export function safeDecodeParams(route, source, options) {
         throw error;
     }
 }
-/** Decoded search params as a `SafeResult` (discriminated on `status`). */
-export function safeDecodeSearch(route, source) {
+/**
+ * Decoded search params as a `SafeResult` (discriminated on `status`).
+ * `target` is a route or a bare `search:` slot, as for {@link decodeSearch}.
+ */
+export function safeDecodeSearch(target, source) {
     try {
-        // decodeSearch is keyed on SearchOutputOf (SS6) — the correct
-        // public type — but AnyRoute erases its SC to `any`, so for a still-
-        // generic R the call's value side reduces to `unknown` while the
-        // annotation side stays deferred. The cast bridges that inference gap to
-        // the SAME (correct) type.
-        return {
-            data: decodeSearch(route["~search"], source, route.path),
-            status: "success",
-        };
+        return { data: decodeSearch(target, source), status: "success" };
     }
     catch (error) {
         if (error instanceof SearchDecodeError)

package/dist/search.d.ts

@@ -1,28 +1,27 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
-import type { AnyCodec, OutputOf, PresenceOf } from "./codec.js";
-/**
- * href-input side (D4): required presence stays required;
- * optional and defaulted keys may be omitted. Array (arity-"many") keys may
- * also be omitted: absent and [] are the same wire state (S6/P6), so
- * requiring `tags: []` ceremony would be pure noise. Omittable keys also
- * admit an EXPLICIT `undefined` — encodeSearch already treats that value as
- * absent (S3), and without the `| undefined` widening a decoded
- * {@link InferSearchOutput} (every key present, optional presence as
- * `| undefined`) could not flow back into href under
- * `exactOptionalPropertyTypes` without key-by-key reassembly.
- */
-export type InferSearchInput<S extends SearchConfig> = {
-    [K in Exclude<keyof S, OptionalInputKeys<S>>]: OutputOf<S[K]>;
-} & {
-    [K in OptionalInputKeys<S>]?: OutputOf<S[K]> | undefined;
-};
-/**
- * Parse-output side (D4): every declared key is PRESENT on the
- * object; optional presence contributes `| undefined` to the value type.
- */
-export type InferSearchOutput<S extends SearchConfig> = {
-    [K in keyof S]: PresenceOf<S[K]> extends "optional" ? OutputOf<S[K]> | undefined : OutputOf<S[K]>;
-};
+import type { AnyCodec, InferCodecOutput, PresenceOf } from "./codec.js";
+import type { AnyRoute } from "./route.js";
+/**
+ * href / encode input of a `search:` slot (SS6). A codec map: required
+ * presence stays required; optional and defaulted keys may be omitted
+ * (D4). Array (arity-"many") keys may also be omitted: absent and [] are
+ * the same wire state (S6/P6), so requiring `tags: []` ceremony would be
+ * pure noise. Omittable keys also admit an EXPLICIT `undefined` —
+ * encodeSearch already treats that value as absent (S3), and without the
+ * `| undefined` widening a decoded {@link InferSearchOutput} could not flow
+ * back into href under `exactOptionalPropertyTypes` without key-by-key
+ * reassembly. A `RawSearch` slot accepts the raw wire record instead (SS5 —
+ * the schema never runs on encode, so there's no encode-side type to infer
+ * from it).
+ */
+export type InferSearchInput<SC extends SearchSlot> = SC extends RawSearch<StandardSchemaV1> ? Record<string, string | string[]> : SC extends SearchConfig ? CodecMapInput<SC> : never;
+/**
+ * Decoded output of a `search:` slot (SS6). A codec map: every declared key
+ * is PRESENT on the object; optional presence contributes `| undefined` to
+ * the value type (D4). A `RawSearch` slot's output is the schema's own
+ * inferred output.
+ */
+export type InferSearchOutput<SC extends SearchSlot> = SC extends RawSearch<infer S> ? StandardSchemaV1.InferOutput<S> : SC extends SearchConfig ? CodecMapOutput<SC> : never;
 /**
  * The whole-object search escape hatch (SS1/SS2): wraps a bare
  * Standard Schema in a branded marker so `search:` config discrimination is
@@ -37,25 +36,9 @@ export interface RawSearch<S extends StandardSchemaV1> {
 /** A search-params schema: key → codec. */
 export type SearchConfig = Record<string, AnyCodec>;
 /**
- * href / encode side of a `search:` config (SS6): a `RawSearch`
- * route accepts the raw wire record (SS5 — the schema never runs on encode,
- * so there's no encode-side type to infer from it); a codec map keeps its
- * existing `InferSearchInput` behavior. Module-exported for route.ts/href.ts,
- * not barrel-exported — same precedent as `encodeComponent`/`readInputValue`.
- */
-export type SearchInputOf<SC> = SC extends RawSearch<StandardSchemaV1> ? Record<string, string | string[]> : SC extends SearchConfig ? InferSearchInput<SC> : never;
-/**
- * Parse-output side of a `search:` config (SS6): a `RawSearch`
- * route's output is the schema's own inferred output; a codec map keeps its
- * existing `InferSearchOutput` behavior. Module-exported for
- * route.ts/href.ts, not barrel-exported.
- */
-export type SearchOutputOf<SC> = SC extends RawSearch<infer S> ? StandardSchemaV1.InferOutput<S> : SC extends SearchConfig ? InferSearchOutput<SC> : never;
-/**
- * The `search:` config slot's full type (SS2): a codec map (the
- * main road) or a `RawSearch` marker (the escape hatch). Internal — not
- * barrel-exported; `Route`/`RouteConfig`/`HrefArgs` consume it as their `SC`
- * bound.
+ * The `search:` config slot's full type (SS2): a codec map (the main road)
+ * or a `RawSearch` marker (the escape hatch). Public so route wrappers can
+ * bound their own `SC` parameter the way `define*Route` does.
  */
 export type SearchSlot = RawSearch<StandardSchemaV1> | SearchConfig;
 /**
@@ -64,6 +47,21 @@ export type SearchSlot = RawSearch<StandardSchemaV1> | SearchConfig;
  * platform.
  */
 export type SearchSource = Record<string, string | string[] | undefined> | URLSearchParams;
+/**
+ * The `search:` slot a search-function target resolves to: a route's own
+ * slot, or the slot itself. Every standalone search function accepts either
+ * form (the `nuqsParsers` precedent), so route users never reach for
+ * `~search`. Module-exported for safe-decode.ts, not barrel-exported.
+ */
+export type SlotOf<T extends AnyRoute | SearchSlot> = T extends AnyRoute ? T["~search"] : T;
+type CodecMapInput<S extends SearchConfig> = {
+    [K in Exclude<keyof S, OptionalInputKeys<S>>]: InferCodecOutput<S[K]>;
+} & {
+    [K in OptionalInputKeys<S>]?: InferCodecOutput<S[K]> | undefined;
+};
+type CodecMapOutput<S extends SearchConfig> = {
+    [K in keyof S]: PresenceOf<S[K]> extends "optional" ? InferCodecOutput<S[K]> | undefined : InferCodecOutput<S[K]>;
+};
 type OptionalInputKeys<S extends SearchConfig> = {
     [K in keyof S]: S[K]["~arity"] extends "many" ? K : PresenceOf<S[K]> extends "required" ? never : K;
 }[keyof S];
@@ -84,11 +82,18 @@ export declare function buildSearchString(pairs: readonly (readonly [string, str
  * path instead: every source key reaches the schema (P8 does not apply
  * there — the schema owns stripping or passing through extras).
  *
- * `routePath` anchors a thrown {@link SearchDecodeError} to the owning
- * route's path pattern — route-level surfaces pass `route.path`; standalone
- * callers (nuqs, devtools) omit it and the error stays route-less.
+ * `target` is a route or a bare `search:` slot. A route anchors a thrown
+ * {@link SearchDecodeError} to its path pattern; a bare slot (nuqs,
+ * devtools, middleware snippets) leaves the error route-less.
+ */
+export declare function decodeSearch<T extends AnyRoute | SearchSlot>(target: T, source: SearchSource): InferSearchOutput<SlotOf<T>>;
+/**
+ * {@link decodeSearch} on an already-resolved slot. Module-exported for the
+ * route methods, whose generic `SC` is the slot itself — going through the
+ * route-or-slot entry would re-derive it as `SlotOf<AppRoute<…>>`, which
+ * doesn't reduce back to `SC` inside a generic body.
  */
-export declare function decodeSearch<S extends SearchSlot>(config: S, source: SearchSource, routePath?: string): SearchOutputOf<S>;
+export declare function decodeSearchSlot<S extends SearchSlot>(config: S, source: SearchSource, routePath: null | string): InferSearchOutput<S>;
 /**
  * encodeURIComponent throws a raw URIError on lone surrogates; wrap it so
  * the documented "every error is a ParamourError" contract holds (S7).
@@ -114,7 +119,7 @@ export declare function encodeComponent(text: string): string;
  * serializer exists for a whole-object schema, so the caller's record goes
  * straight to the byte layer and the schema never runs on encode.
  */
-export declare function encodeSearch<S extends SearchSlot>(config: S, input: SearchInputOf<S>): [string, string][];
+export declare function encodeSearch<T extends AnyRoute | SearchSlot>(target: T, input: InferSearchInput<SlotOf<T>>): [string, string][];
 /**
  * Runtime discriminant for the `search:` slot (SS2): probes the
  * `~kind` marker's VALUE, which is unambiguous against a codec map — a map
@@ -171,7 +176,7 @@ 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;
+export declare function searchToString<T extends AnyRoute | SearchSlot>(target: T, input: InferSearchInput<SlotOf<T>>): string;
 /**
  * Invokes a codec's serializer and enforces its string contract: a custom
  * codec written in plain JS can return undefined, which would otherwise

package/dist/search.js

@@ -24,14 +24,24 @@ export function buildSearchString(pairs) {
  * path instead: every source key reaches the schema (P8 does not apply
  * there — the schema owns stripping or passing through extras).
  *
- * `routePath` anchors a thrown {@link SearchDecodeError} to the owning
- * route's path pattern — route-level surfaces pass `route.path`; standalone
- * callers (nuqs, devtools) omit it and the error stays route-less.
+ * `target` is a route or a bare `search:` slot. A route anchors a thrown
+ * {@link SearchDecodeError} to its path pattern; a bare slot (nuqs,
+ * devtools, middleware snippets) leaves the error route-less.
  */
-export function decodeSearch(config, source, routePath) {
+export function decodeSearch(target, source) {
+    const [config, routePath] = resolveSearchTarget(target);
+    return decodeSearchSlot(config, source, routePath);
+}
+/**
+ * {@link decodeSearch} on an already-resolved slot. Module-exported for the
+ * route methods, whose generic `SC` is the slot itself — going through the
+ * route-or-slot entry would re-derive it as `SlotOf<AppRoute<…>>`, which
+ * doesn't reduce back to `SC` inside a generic body.
+ */
+export function decodeSearchSlot(config, source, routePath) {
     requireSearchConfig(config);
     if (isRawSearch(config)) {
-        return decodeRawSearch(config, source, routePath ?? null);
+        return decodeRawSearch(config, source, routePath);
     }
     // The conditional SearchSlot doesn't narrow inside the generic body once
     // the RawSearch branch returns (S stays a generic type parameter); this
@@ -132,7 +142,7 @@ export function decodeSearch(config, source, routePath) {
         }
     }
     if (issues.length > 0) {
-        throw new SearchDecodeError(issues, routePath ?? null);
+        throw new SearchDecodeError(issues, routePath);
     }
     return Object.fromEntries(entries);
 }
@@ -163,7 +173,8 @@ export function encodeComponent(text) {
  * serializer exists for a whole-object schema, so the caller's record goes
  * straight to the byte layer and the schema never runs on encode.
  */
-export function encodeSearch(config, input) {
+export function encodeSearch(target, input) {
+    const [config] = resolveSearchTarget(target);
     requireSearchConfig(config);
     if (isRawSearch(config)) {
         return encodeRawSearch(input);
@@ -302,8 +313,8 @@ export function requireSearchConfig(config) {
     }
 }
 /** Convenience: encode + build in one step. */
-export function searchToString(config, input) {
-    return buildSearchString(encodeSearch(config, input));
+export function searchToString(target, input) {
+    return buildSearchString(encodeSearch(target, input));
 }
 /**
  * Invokes a codec's serializer and enforces its string contract: a custom
@@ -533,3 +544,21 @@ function requireRawSearchString(key, value) {
     }
     return value;
 }
+/**
+ * Splits a search-function target into its slot and the path that anchors
+ * errors. Routes are recognized by their `~search`/`~segments` members —
+ * `~`-prefixed keys are reserved, so no codec map or `RawSearch` marker can
+ * carry both. Anything else passes through for `requireSearchConfig` to
+ * validate.
+ */
+function resolveSearchTarget(target) {
+    const untrusted = target;
+    if (typeof untrusted === "object" &&
+        untrusted !== null &&
+        "~search" in untrusted &&
+        "~segments" in untrusted) {
+        const route = target;
+        return [route["~search"], route.path];
+    }
+    return [target, null];
+}

package/dist/standard-schema.d.ts

@@ -1,6 +1,5 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
-import type { AnyRoute } from "./route.js";
-import { type SearchOutputOf } from "./search.js";
+import type { AnyRoute, InferRouteSearch } from "./route.js";
 /**
  * Standard Schema generate-OUT: exports a route's `search:` config as a
  * spec-compliant Standard Schema. The mirror of schema.ts, which runs
@@ -14,7 +13,7 @@ import { type SearchOutputOf } from "./search.js";
  * shape. `types` is carried by this annotation alone; the spec reads it at
  * the type level only, so no runtime key exists.
  */
-export type StandardSearchSchema<SC> = StandardSchemaV1<Record<string, string | string[] | undefined>, SearchOutputOf<SC>>;
+export type StandardSearchSchema<R extends AnyRoute> = StandardSchemaV1<Record<string, string | string[] | undefined>, InferRouteSearch<R>>;
 /**
  * Exports a route's `search:` config as the URL wire contract in Standard
  * Schema form, for consumers like tRPC inputs or TanStack `validateSearch`.
@@ -24,4 +23,4 @@ export type StandardSearchSchema<SC> = StandardSchemaV1<Record<string, string |
  * reject (P5). No coercion, ever: the schema accepts wire strings (`"42"`),
  * not decoded values (`42`).
  */
-export declare function standardSearchSchema<R extends AnyRoute>(route: R): StandardSearchSchema<R["~search"]>;
+export declare function standardSearchSchema<R extends AnyRoute>(route: R): StandardSearchSchema<R>;

package/package.json

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