paramour 0.1.0 → 0.2.1

package/dist/errors.d.ts

@@ -31,10 +31,28 @@ export declare class SearchDecodeError extends ParamourError {
     constructor(issues: readonly Issue[]);
     static [Symbol.hasInstance](value: unknown): value is SearchDecodeError;
 }
+/**
+ * A search source violated its wire-shape contract (design-08 STD7): a
+ * non-object source, or a non-string / non-string[] value under a read key.
+ * Thrown by search.ts's source readers; distinct from {@link ParamourError}
+ * so the Standard Schema adapter can soften exactly these throws to issues
+ * while config-contract violations and rebranded validator throws stay loud.
+ */
+export declare class SearchSourceError extends ParamourError {
+    /** The offending source key, or null when the source itself is malformed. */
+    readonly key: null | string;
+    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 {
     static [Symbol.hasInstance](value: unknown): value is SerializeError;
 }
+/**
+ * Renders a value's type for "…, got X" error messages, distinguishing null
+ * from typeof's "object". Not exported from the package.
+ */
+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.

package/dist/errors.js

@@ -11,6 +11,7 @@ const paramourErrorBrand = Symbol.for("paramour.errors.ParamourError");
 const paramsDecodeErrorBrand = Symbol.for("paramour.errors.ParamsDecodeError");
 const parseErrorBrand = Symbol.for("paramour.errors.ParseError");
 const searchDecodeErrorBrand = Symbol.for("paramour.errors.SearchDecodeError");
+const searchSourceErrorBrand = Symbol.for("paramour.errors.SearchSourceError");
 const serializeErrorBrand = Symbol.for("paramour.errors.SerializeError");
 /** Base class for every error paramour throws. */
 export class ParamourError extends Error {
@@ -68,6 +69,27 @@ export class SearchDecodeError extends ParamourError {
         return hasBrand(value, searchDecodeErrorBrand);
     }
 }
+/**
+ * A search source violated its wire-shape contract (design-08 STD7): a
+ * non-object source, or a non-string / non-string[] value under a read key.
+ * Thrown by search.ts's source readers; distinct from {@link ParamourError}
+ * so the Standard Schema adapter can soften exactly these throws to issues
+ * while config-contract violations and rebranded validator throws stay loud.
+ */
+export class SearchSourceError extends ParamourError {
+    static {
+        brandPrototype(this, searchSourceErrorBrand);
+    }
+    /** The offending source key, or null when the source itself is malformed. */
+    key;
+    constructor(message, key) {
+        super(message);
+        this.key = key;
+    }
+    static [Symbol.hasInstance](value) {
+        return hasBrand(value, searchSourceErrorBrand);
+    }
+}
 /** A value could not be serialized to the wire (bad type, non-finite, etc.). */
 export class SerializeError extends ParamourError {
     static {
@@ -77,6 +99,13 @@ export class SerializeError extends ParamourError {
         return hasBrand(value, serializeErrorBrand);
     }
 }
+/**
+ * Renders a value's type for "…, got X" error messages, distinguishing null
+ * from typeof's "object". Not exported from the package.
+ */
+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.

package/dist/href.d.ts

@@ -1,4 +1,4 @@
-import type { AnyRoute } from "./route.js";
+import type { AnyRoute, RegisteredStaticRoutePaths } from "./route.js";
 import { type InferParamsInput } from "./path.js";
 import { type SearchInputOf } from "./search.js";
 /**
@@ -35,6 +35,19 @@ export type HrefArgs<R extends AnyRoute> = Record<never, never> extends InferHre
 export type InferHrefInput<R extends AnyRoute> = PartFor<"params", InferParamsInput<R>> & PartFor<"search", SearchInputOf<R["~search"]>> & {
     hash?: string;
 };
+/**
+ * The string form's options (SH4): hash only. `params` is meaningless on a
+ * static path, and a query string comes only from a defined route's search
+ * codecs — a raw-search escape hatch here would be an untyped side door
+ * around library-owned serialization. Both are banned outright (`?: never`,
+ * the 2026-07-04 ruling's move) rather than merely omitted, so a non-fresh
+ * options object can't smuggle them past excess-property checking.
+ */
+export interface StaticHrefOptions {
+    hash?: string;
+    params?: never;
+    search?: never;
+}
 /**
  * One options property whose presence follows its input type: required iff
  * the input has at least one required key (the design-02 D4
@@ -54,6 +67,13 @@ type PartFor<Key extends string, Input> = keyof Input extends never ? Partial<Re
  * (a missing param codec or `~search` config) are base `ParamourError` — a
  * JS caller omitting a required `search` half falls through to
  * encodeSearch's own required-missing error.
+ *
+ * The string form (SH1): a registered STATIC path stands in for the route
+ * object — same brand, same hash assembly, no route definition needed. The
+ * string overload sits first so the route-object overload is last (SH8):
+ * TS's "the last overload gave the following error" heuristic keeps
+ * route-object misuse diagnostics prominent.
  */
+export declare function href<P extends RegisteredStaticRoutePaths>(path: P, options?: StaticHrefOptions): Href<P>;
 export declare function href<R extends AnyRoute>(route: R, ...args: HrefArgs<R>): Href<R["path"]>;
 export {};

package/dist/href.js

@@ -1,3 +1,4 @@
+import { ParamourError } from "./errors.js";
 import { buildPath } from "./path.js";
 import { searchToString, } from "./search.js";
 // The conditional HrefArgs tuple is unresolvable inside a generic body, so
@@ -5,12 +6,27 @@ import { searchToString, } from "./search.js";
 // routeData's config cast) instead of per-expression casts: the
 // implementation sees each option half at its loosest honest type.
 export function href(route, options) {
-    const path = buildPath(route, options?.params ?? {});
-    const query = searchToString(route["~search"], options?.search ?? {});
     // S10: the fragment is appended VERBATIM — no encoding, the caller owns
     // escaping (a value already starting with "#" yields "##…"). The empty
     // string emits no "#".
     const hash = options?.hash;
     const fragment = hash === undefined || hash === "" ? "" : `#${hash}`;
+    if (typeof route === "string") {
+        // SH6: fail-fast backstop for JS callers and world-A typos of the
+        // dynamic-path variety — a bracket means "you need a route object", and
+        // query/hash never ride in the path string (query comes only from
+        // search codecs, hash only from the option).
+        if (!route.startsWith("/") || /[#?[\]]/.test(route)) {
+            throw new ParamourError(`href(path) requires a static route path, got ${JSON.stringify(route)}: dynamic segments need a route object, and query/hash never ride in the path string`);
+        }
+        // SH6: silently dropping a half a JS caller passed would build a wrong
+        // link — contract violations stay loud (never the safe-parse error arm).
+        if (options?.params !== undefined || options?.search !== undefined) {
+            throw new ParamourError(`href(path) takes no params/search — a static path has no params, and a query string needs a route with search codecs`);
+        }
+        return `${route}${fragment}`;
+    }
+    const path = buildPath(route, options?.params ?? {});
+    const query = searchToString(route["~search"], options?.search ?? {});
     return `${path}${query}${fragment}`;
 }

package/dist/index.d.ts

@@ -1,9 +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, SerializeError, } from "./errors.js";
-export { href, type Href, type HrefArgs, type InferHrefInput } from "./href.js";
+export { type Issue, ParamourError, ParamsDecodeError, ParseError, type RouteDecodeError, SearchDecodeError, SearchSourceError, SerializeError, } from "./errors.js";
+export { href, type Href, type HrefArgs, type InferHrefInput, type StaticHrefOptions, } from "./href.js";
 export { p } from "./p.js";
 export { buildPath, decodeParams, type DecodeParamsOptions, encodeParams, encodeStaticParams, type InferStaticParams, type ParamsSource, } from "./path.js";
-export { type AnyAppRoute, type AnyPagesRoute, type AnyRoute, type AppRoute, defineAppRoute, definePagesRoute, type InferRouteParams, type PagesContext, type PagesRoute, type ParamourRegister, type ParamsConfig, type ParamsProps, type RegisteredAppRoutePaths, type RegisteredPagesRoutePaths, type Route, type RouteProps, type RouterKind, type SafeResult, type SearchProps, } from "./route.js";
+export { type AnyAppRoute, type AnyPagesRoute, type AnyRoute, type AppRoute, defineAppRoute, definePagesRoute, type InferRouteParams, type PagesContext, type PagesRoute, type ParamourRegister, type ParamsConfig, type ParamsProps, type 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 { standardSearchSchema, type StandardSearchSchema, } from "./standard-schema.js";

package/dist/index.js

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

package/dist/path.js

@@ -1,4 +1,4 @@
-import { ParamourError, ParamsDecodeError, ParseError, SerializeError, } from "./errors.js";
+import { describeType, ParamourError, ParamsDecodeError, ParseError, SerializeError, } from "./errors.js";
 import { encodeComponent, readInputValue } 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
@@ -32,7 +32,7 @@ export function decodeParams(route, source, options) {
     // a per-key decode issue.
     const untrusted = source;
     if (typeof untrusted !== "object" || untrusted === null) {
-        throw new ParamourError(`params source must be an object, got ${untrusted === null ? "null" : typeof untrusted}`);
+        throw new ParamourError(`params source must be an object, got ${describeType(untrusted)}`);
     }
     // R5: App-Router surfaces arrive percent-encoded (decode by default); pages
     // surfaces arrive already-decoded and opt out via `{ percentDecode: false }`.
@@ -182,7 +182,7 @@ export function encodeParams(route, params) {
     // here; a null input must fail loud, not read as every-param-absent.
     const untrusted = params;
     if (typeof untrusted !== "object" || untrusted === null) {
-        throw new SerializeError(`params input must be an object, got ${untrusted === null ? "null" : typeof untrusted}`);
+        throw new SerializeError(`params input must be an object, got ${describeType(untrusted)}`);
     }
     const values = untrusted;
     const config = route["~params"];
@@ -232,7 +232,7 @@ export function encodeStaticParams(route, params) {
     // here; a null input must fail loud, not read as every-param-absent.
     const untrusted = params;
     if (typeof untrusted !== "object" || untrusted === null) {
-        throw new SerializeError(`params input must be an object, got ${untrusted === null ? "null" : typeof untrusted}`);
+        throw new SerializeError(`params input must be an object, got ${describeType(untrusted)}`);
     }
     const values = untrusted;
     const config = route["~params"];

package/dist/route.d.ts

@@ -163,6 +163,27 @@ export type RegisteredAppRoutePaths = ParamourRegister extends {
 export type RegisteredPagesRoutePaths = ParamourRegister extends {
     pagesRoutes: infer R extends string;
 } ? R : string;
+/**
+ * Static-only subset of {@link RegisteredAppRoutePaths} (SH2): derived by
+ * syntactic filter, not emitted — dynamic-ness is a property of the path
+ * literal, so the registry format doesn't change. Same world-A `string`
+ * fallback as the full union (the filter passes `string` through).
+ */
+export type RegisteredStaticAppRoutePaths = StaticPathsOf<RegisteredAppRoutePaths>;
+/** Pages twin of {@link RegisteredStaticAppRoutePaths} (SH2). */
+export type RegisteredStaticPagesRoutePaths = StaticPathsOf<RegisteredPagesRoutePaths>;
+/**
+ * Every registered STATIC path across both routers — the string form of
+ * href's path argument (SH1/SH2). Deliberately NOT the union of the two
+ * per-router types (SH3): each falls back to `string` when its registry
+ * member is absent, and in a single-router project the absent side's
+ * `string` would swallow the union and erase verification for the router
+ * that HAS routes. The permissive fallback applies only when NEITHER member
+ * is present (world A / TR3's empty merge).
+ */
+export type RegisteredStaticRoutePaths = [PresentRegisteredPaths] extends [
+    never
+] ? string : StaticPathsOf<PresentRegisteredPaths>;
 /**
  * The router-agnostic core of a defined route (PR3): path, configs, and the
  * define-time token cache. The parse surface is router-specific and lives on
@@ -234,6 +255,24 @@ export type Segments<S extends string> = S extends `${infer Head}/${infer Rest}`
  * `[...slug]` would extract as a single param named `"...slug"`.
  */
 export type SingleParamNames<Path extends string> = Segments<Path> extends infer S extends string ? S extends `[[...${string}]]` ? never : S extends `[...${string}]` ? never : S extends `[${infer Name}]` ? NonEmptyName<Name> : never : never;
+/**
+ * Union of the registry members that are actually PRESENT — `never` when
+ * neither router has generated routes. The input to SH3's combined-union
+ * fallback rule; see {@link RegisteredStaticRoutePaths}.
+ */
+type PresentRegisteredPaths = (ParamourRegister extends {
+    appRoutes: infer A extends string;
+} ? A : never) | (ParamourRegister extends {
+    pagesRoutes: infer P extends string;
+} ? P : never);
+/**
+ * Filters a path union to its static members (SH2): any `[` marks a dynamic
+ * segment. `string` passes through (it doesn't extend the bracket template),
+ * which is exactly what keeps the world-A fallback intact. Note reachability
+ * ≠ staticness (SH7): `/docs/[[...slug]]` serves `/docs`, but it carries a
+ * codec and decode expectations, so it is excluded here.
+ */
+type StaticPathsOf<P extends string> = P extends `${string}[${string}` ? never : P;
 /**
  * Defines an App Router route: the URL-shaped path literal (RL2) plus its
  * param/search codec configs. Validates the literal eagerly (RL1 —
@@ -251,3 +290,4 @@ export declare function defineAppRoute<Path extends RegisteredAppRoutePaths & st
  * sync context pair (PR10).
  */
 export declare function definePagesRoute<Path extends RegisteredPagesRoutePaths & string, const PC extends ParamsConfig<Path> = ParamsConfig<Path>, const SC extends Readonly<Partial<Record<PathParamNames<Path>, never>>> & SearchSlot = Record<never, never>>(path: Path, config: RouteConfig<Path, PC, SC>): PagesRoute<Path, PC, SC>;
+export {};

package/dist/route.js

@@ -1,4 +1,4 @@
-import { foreignMessage, ParamourError, ParamsDecodeError, SearchDecodeError, } from "./errors.js";
+import { describeType, foreignMessage, ParamourError, ParamsDecodeError, SearchDecodeError, } from "./errors.js";
 import { decodeParams, tokenizePath, } from "./path.js";
 import { decodeSearch, } from "./search.js";
 /**
@@ -199,12 +199,12 @@ async function safely(run) {
 function splitPagesContext(context, paramNames) {
     const untrusted = context;
     if (typeof untrusted !== "object" || untrusted === null) {
-        throw new ParamourError(`pages context must be an object, got ${untrusted === null ? "null" : typeof untrusted}`);
+        throw new ParamourError(`pages context must be an object, got ${describeType(untrusted)}`);
     }
     const { params, query } = untrusted;
     const untrustedQuery = query;
     if (typeof untrustedQuery !== "object" || untrustedQuery === null) {
-        throw new ParamourError(`pages context has no query object (got ${untrustedQuery === null ? "null" : typeof untrustedQuery}): getStaticProps contexts carry no query string — decode ctx.params with safeDecodeParams instead (PR10)`);
+        throw new ParamourError(`pages context has no query object (got ${describeType(untrustedQuery)}): getStaticProps contexts carry no query string — decode ctx.params with safeDecodeParams instead (PR10)`);
     }
     return [params ?? pickOwn(query, paramNames), omitOwn(query, paramNames)];
 }

package/dist/search.d.ts

@@ -111,6 +111,13 @@ export declare function encodeComponent(text: string): string;
  * 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][];
+/**
+ * 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.
+ */
+export declare function isRawSearch(config: SearchSlot): config is RawSearch<StandardSchemaV1>;
 /**
  * The whole-object search escape hatch (design-04 SS1, maintainer ruling):
  * an explicit, greppable wrapper around a bare Standard Schema so a route's
@@ -134,6 +141,15 @@ export declare function rawSearch<S extends StandardSchemaV1>(schema: S): RawSea
  * members too.
  */
 export declare function readInputValue(values: Record<string, unknown>, key: string): unknown;
+/**
+ * The TS contract makes a non-object config unrepresentable, but a
+ * hand-built route missing `~search` reaches both codecs' entry points via
+ * href/parseSearch in plain JS; fail branded — a missing config is a
+ * config-contract violation (requireCodec's precedent), never a raw
+ * TypeError out of Object.entries/Object.keys. Module-exported for
+ * standard-schema.ts, not barrel-exported.
+ */
+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 {};

package/dist/search.js

@@ -1,4 +1,4 @@
-import { foreignMessage, ParamourError, ParseError, rebrandForeign, SearchDecodeError, SerializeError, } from "./errors.js";
+import { describeType, foreignMessage, ParamourError, ParseError, rebrandForeign, SearchDecodeError, SearchSourceError, SerializeError, } from "./errors.js";
 import { runStandardSchemaSync } from "./schema.js";
 /**
  * Builds the byte-layer query string from decoded pairs. Hand-rolled on
@@ -147,7 +147,7 @@ export function encodeSearch(config, input) {
     // here; a null input must fail loud, not read as every-key-absent.
     const untrusted = input;
     if (typeof untrusted !== "object" || untrusted === null) {
-        throw new SerializeError(`search input must be an object, got ${untrusted === null ? "null" : typeof untrusted}`);
+        throw new SerializeError(`search input must be an object, got ${describeType(untrusted)}`);
     }
     const pairs = [];
     const values = untrusted;
@@ -187,6 +187,15 @@ 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.
+ */
+export function isRawSearch(config) {
+    return "~kind" in config && config["~kind"] === "raw-search";
+}
 /**
  * The whole-object search escape hatch (design-04 SS1, maintainer ruling):
  * an explicit, greppable wrapper around a bare Standard Schema so a route's
@@ -228,6 +237,20 @@ export function readInputValue(values, key) {
     }
     return undefined;
 }
+/**
+ * The TS contract makes a non-object config unrepresentable, but a
+ * hand-built route missing `~search` reaches both codecs' entry points via
+ * href/parseSearch in plain JS; fail branded — a missing config is a
+ * config-contract violation (requireCodec's precedent), never a raw
+ * TypeError out of Object.entries/Object.keys. Module-exported for
+ * standard-schema.ts, not barrel-exported.
+ */
+export function requireSearchConfig(config) {
+    const untrusted = config;
+    if (typeof untrusted !== "object" || untrusted === null) {
+        throw new ParamourError(`search config must be an object, got ${describeType(untrusted)}`);
+    }
+}
 /** Convenience: encode + build in one step. */
 export function searchToString(config, input) {
     return buildSearchString(encodeSearch(config, input));
@@ -276,7 +299,7 @@ function decodeRawSearch(config, source) {
 function encodeRawSearch(input) {
     const untrusted = input;
     if (typeof untrusted !== "object" || untrusted === null) {
-        throw new SerializeError(`search input must be an object, got ${untrusted === null ? "null" : typeof untrusted}`);
+        throw new SerializeError(`search input must be an object, got ${describeType(untrusted)}`);
     }
     const values = untrusted;
     const pairs = [];
@@ -294,14 +317,6 @@ function encodeRawSearch(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.
- */
-function isRawSearch(config) {
-    return "~kind" in config && config["~kind"] === "raw-search";
-}
 /**
  * Snapshots EVERY source key's wire values, before any user code (the
  * whole-object schema's `validate`) runs — sibling of
@@ -317,7 +332,7 @@ function readAllValues(source) {
     // here; fail branded, not with a raw TypeError out of Object.keys.
     const untrusted = source;
     if (typeof untrusted !== "object" || untrusted === null) {
-        throw new ParamourError(`search source must be an object, got ${untrusted === null ? "null" : typeof untrusted}`);
+        throw new SearchSourceError(`search source must be an object, got ${describeType(untrusted)}`, null);
     }
     const grouped = new Map();
     if (source instanceof URLSearchParams) {
@@ -326,7 +341,7 @@ function readAllValues(source) {
         // Record branch below.
         for (const [key, value] of source) {
             if (typeof value !== "string") {
-                throw new ParamourError(`search source values for "${key}" must be strings, got ${typeof value}`);
+                throw new SearchSourceError(`search source values for "${key}" must be strings, got ${typeof value}`, key);
             }
             const list = grouped.get(key);
             if (list === undefined)
@@ -363,15 +378,15 @@ function readAllValues(source) {
  * user code runs. Declared keys only, on purpose: unknown keys are never
  * validated, so malformed junk under keys paramour doesn't own (qs bracket
  * params, numbers) can't fail a decode (P8). Malformed values under a
- * DECLARED key are a loud {@link ParamourError} — the source doesn't match
- * its stated contract — never a silent key drop.
+ * DECLARED key are a loud {@link SearchSourceError} — the source doesn't
+ * match its stated contract — never a silent key drop.
  */
 function readDeclaredValues(config, source) {
     // The TS contract forbids non-object sources, but plain-JS callers reach
     // here; fail branded, not with a raw TypeError out of Object.hasOwn.
     const untrusted = source;
     if (typeof untrusted !== "object" || untrusted === null) {
-        throw new ParamourError(`search source must be an object, got ${untrusted === null ? "null" : typeof untrusted}`);
+        throw new SearchSourceError(`search source must be an object, got ${describeType(untrusted)}`, null);
     }
     const values = new Map();
     if (source instanceof URLSearchParams) {
@@ -383,7 +398,7 @@ function readDeclaredValues(config, source) {
             if (!Object.hasOwn(config, key))
                 continue;
             if (typeof value !== "string") {
-                throw new ParamourError(`search source values for "${key}" must be strings, got ${typeof value}`);
+                throw new SearchSourceError(`search source values for "${key}" must be strings, got ${typeof value}`, key);
             }
             const list = values.get(key);
             if (list === undefined)
@@ -417,12 +432,12 @@ function readRecordValues(source, key) {
         const copy = [...value];
         for (const element of copy) {
             if (typeof element !== "string") {
-                throw new ParamourError(`search source values for "${key}" must be strings, got ${typeof element}`);
+                throw new SearchSourceError(`search source values for "${key}" must be strings, got ${typeof element}`, key);
             }
         }
         return copy;
     }
-    throw new ParamourError(`search source value for "${key}" must be a string or string[], got ${typeof value}`);
+    throw new SearchSourceError(`search source value for "${key}" must be a string or string[], got ${typeof value}`, key);
 }
 /**
  * Property reads run user getters (the class-instance shape
@@ -444,19 +459,6 @@ function requireRawSearchString(key, value) {
     }
     return value;
 }
-/**
- * The TS contract makes a non-object config unrepresentable, but a
- * hand-built route missing `~search` reaches both codecs' entry points via
- * href/parseSearch in plain JS; fail branded — a missing config is a
- * config-contract violation (requireCodec's precedent), never a raw
- * TypeError out of Object.entries/Object.keys.
- */
-function requireSearchConfig(config) {
-    const untrusted = config;
-    if (typeof untrusted !== "object" || untrusted === null) {
-        throw new ParamourError(`search config must be an object, got ${untrusted === null ? "null" : typeof untrusted}`);
-    }
-}
 /**
  * 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/standard-schema.d.ts

@@ -0,0 +1,27 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { AnyRoute } from "./route.js";
+import { type SearchOutputOf } from "./search.js";
+/**
+ * Standard Schema generate-OUT (design-08): exports a route's `search:`
+ * config as a spec-compliant Standard Schema. The mirror of schema.ts, which
+ * runs Standard Schemas coming IN.
+ */
+/**
+ * The schema {@link standardSearchSchema} returns (STD1/STD3): input is
+ * advertised as the wire-shaped record only — `URLSearchParams` is accepted
+ * at runtime but kept out of the type, so client-side inference (tRPC) never
+ * sees a shape that cannot serialize over JSON. Output is the route's decoded
+ * search 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>>;
+/**
+ * Exports a route's `search:` config as the URL wire contract in Standard
+ * Schema form (design-08 STD1/STD5), for consumers like tRPC inputs or
+ * TanStack `validateSearch`. Semantics are byte-identical to `decodeSearch`
+ * (STD6): defaults apply, `.catch()` recovers parse failures — invalid API
+ * input silently coerces to the fallback — unknown keys strip (P8), and
+ * duplicate values on a scalar codec reject (P5). No coercion, ever (STD2):
+ * the schema accepts wire strings (`"42"`), not decoded values (`42`).
+ */
+export declare function standardSearchSchema<R extends AnyRoute>(route: R): StandardSearchSchema<R["~search"]>;

package/dist/standard-schema.js

@@ -0,0 +1,77 @@
+import { SearchSourceError } from "./errors.js";
+import { safeDecodeSearch } from "./safe-decode.js";
+import { isRawSearch, requireSearchConfig, } from "./search.js";
+/**
+ * Exports a route's `search:` config as the URL wire contract in Standard
+ * Schema form (design-08 STD1/STD5), for consumers like tRPC inputs or
+ * TanStack `validateSearch`. Semantics are byte-identical to `decodeSearch`
+ * (STD6): defaults apply, `.catch()` recovers parse failures — invalid API
+ * input silently coerces to the fallback — unknown keys strip (P8), and
+ * duplicate values on a scalar codec reject (P5). No coercion, ever (STD2):
+ * the schema accepts wire strings (`"42"`), not decoded values (`42`).
+ */
+export function standardSearchSchema(route) {
+    const config = route["~search"];
+    // A missing/malformed config is a programming error and stays loud (STD7);
+    // checking eagerly fails at construction, not at first validate().
+    requireSearchConfig(config);
+    // A config's raw/codec-map shape is fixed at construction; hoisted so the
+    // sentinel un-mapping below never touches a codec map's keyed issues.
+    const raw = isRawSearch(config);
+    return {
+        "~standard": {
+            validate: (value) => {
+                try {
+                    const result = safeDecodeSearch(route, value);
+                    if (result.status === "error") {
+                        return {
+                            issues: result.error.issues.map((issue) => toStandardIssue(issue, raw)),
+                        };
+                    }
+                    return { value: result.data };
+                }
+                catch (error) {
+                    // STD7: validate() receives genuinely untrusted input, so the
+                    // source-shape contract the read layer enforces with loud throws
+                    // softens to issues at this one boundary — SearchSourceError exists
+                    // as its own branded class exactly so this catch can't swallow
+                    // config-contract violations or rebranded validator throws.
+                    if (error instanceof SearchSourceError) {
+                        return { issues: [toSourceIssue(error)] };
+                    }
+                    // Async raw schema (design-02 D7), throwing raw validators, and
+                    // throwing .default()/.catch() factories are true programming
+                    // errors: loud (STD7).
+                    throw error;
+                }
+            },
+            vendor: "paramour",
+            version: 1,
+        },
+    };
+}
+/**
+ * Maps a source-shape violation to spec shape (STD7): keyed where the read
+ * layer could attribute it, root-level (absent path) for a malformed source.
+ */
+function toSourceIssue(error) {
+    return error.key === null
+        ? { message: error.message }
+        : { message: error.message, path: [error.key] };
+}
+/**
+ * Maps a decode issue to spec shape. decodeRawSearch collapses a root-level
+ * schema issue to the "<search>" sentinel key (SS3/SS4); a Standard Schema
+ * expresses "root" as an ABSENT path, so the sentinel un-maps here (STD7
+ * "root-level otherwise") — for raw configs only, since a codec map's issues
+ * are always keyed and a param may literally be named "<search>". (A raw
+ * vendor issue whose real path is ["<search>"] still collides with the
+ * sentinel — indistinguishable after the flat-key collapse.) Nested
+ * raw-schema paths were already dot-joined into the key and re-emit as ONE
+ * segment — keys may contain dots, so splitting back would be unsound.
+ */
+function toStandardIssue(issue, raw) {
+    return raw && issue.key === "<search>"
+        ? { message: issue.message }
+        : { message: issue.message, path: [issue.key] };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paramour",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "type": "module",
   "exports": {
     ".": {
@@ -33,6 +33,10 @@
   "files": [
     "dist"
   ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "dependencies": {
     "@standard-schema/spec": "^1.1.0"
   },