paramour 0.0.0 → 0.2.0

package/dist/codec.d.ts

@@ -0,0 +1,76 @@
+/**
+ * `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.
+ */
+export type AnyCodec = Codec<any, Presence, boolean, Arity>;
+/** "single" = one wire value per key; "many" = repeated keys (arrays). */
+export type Arity = "many" | "single";
+/**
+ * A bidirectional wire codec.
+ *
+ * `Out` is the decoded in-memory type. `P`, `C`, and `A` are type-state:
+ * modifier methods are conditionally `never`, so illegal chains
+ * (`.optional().default()`, double `.catch()`) fail to compile (design-02 D3).
+ * 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).
+ *
+ * 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;
+    readonly "~arity": A;
+    /** Stored as a thunk regardless of the form passed to `.catch()`. */
+    readonly "~catchValue": (() => Out) | undefined;
+    readonly "~caught": C;
+    /**
+     * True when `.default()` received a value (not a factory). Value defaults
+     * participate in D8 elision, compared against the live default
+     * 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.
+     */
+    readonly "~defaultElides": boolean;
+    /** Stored as a thunk regardless of the form passed to `.default()`. */
+    readonly "~defaultValue": (() => Out) | undefined;
+    /** 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.
+     */
+    readonly "~kind": string;
+    /** 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"];
+/** Codecs legal in a `params:` config — no presence modifiers (design-02 D5). */
+export type ParamCodec = Codec<any, "required", boolean>;
+/**
+ * Presence governs absence semantics and property optionality on both the
+ * parse-output and href-input sides (design-02 D4). Catch is orthogonal:
+ * it recovers parse *failures*, never absence (D2).
+ */
+export type Presence = "defaulted" | "optional" | "required";
+export type PresenceOf<C extends AnyCodec> = C["~presence"];
+/** Internal factory used by the `p.*` builders. */
+export declare function createCodec<Out, A extends Arity = "single">(impl: {
+    arity?: A;
+    enumMembers?: readonly string[];
+    kind?: string;
+    parseElement: (raw: string) => unknown;
+    serializeElement: (value: unknown) => string;
+}): Codec<Out, "required", false, A>;

package/dist/codec.js

@@ -0,0 +1,110 @@
+import { foreignMessage, ParamourError, ParseError, rebrandForeign, } from "./errors.js";
+/** Internal factory used by the `p.*` builders. */
+export function createCodec(impl) {
+    return build({
+        arity: impl.arity ?? "single",
+        catchValue: undefined,
+        defaultElides: false,
+        defaultValue: undefined,
+        enumMembers: impl.enumMembers,
+        kind: impl.kind ?? "custom",
+        parseElement: impl.parseElement,
+        presence: "required",
+        serializeElement: impl.serializeElement,
+    });
+}
+function build(state) {
+    const codec = {
+        catch(fallback) {
+            // Runtime guards mirror the type-state for JS consumers.
+            if (state.catchValue !== undefined) {
+                throw new ParamourError(".catch() may only be applied once");
+            }
+            return build({ ...state, catchValue: toThunk(fallback, "catch") });
+        },
+        default(value) {
+            if (state.arity === "many") {
+                throw new ParamourError(".default() is not available on array codecs: absent and [] are the same wire state");
+            }
+            if (state.presence !== "required") {
+                throw new ParamourError(`.default() is not available after .${state.presence === "optional" ? "optional" : "default"}()`);
+            }
+            // Value-form defaults are serialized once, here, so a schema-invalid
+            // or unserializable default fails at config-definition time — not on
+            // every subsequent encode. The wire form is deliberately NOT cached:
+            // D8 elision re-serializes the live default per encode, so mutating a
+            // reference-typed default can never desync encode from decode the way
+            // a stale build-time snapshot would. Factory defaults can't be
+            // pre-validated.
+            if (!isFactory(value)) {
+                serializeDefault(state.serializeElement, value);
+            }
+            return build({
+                ...state,
+                defaultElides: !isFactory(value),
+                defaultValue: toThunk(value, "default"),
+                presence: "defaulted",
+            });
+        },
+        optional() {
+            if (state.arity === "many") {
+                throw new ParamourError(".optional() is not available on array codecs: absent already decodes to []");
+            }
+            if (state.presence !== "required") {
+                throw new ParamourError(`.optional() is not available after .${state.presence === "optional" ? "optional" : "default"}()`);
+            }
+            return build({ ...state, presence: "optional" });
+        },
+        "~arity": state.arity,
+        "~catchValue": state.catchValue,
+        "~caught": state.catchValue !== undefined,
+        "~defaultElides": state.defaultElides,
+        "~defaultValue": state.defaultValue,
+        "~enumMembers": state.enumMembers,
+        "~kind": state.kind,
+        "~parseElement": state.parseElement,
+        "~presence": state.presence,
+        "~serializeElement": state.serializeElement,
+    };
+    // The cast erases the runtime shape into the type-stated interface; the
+    // "~out" phantom is intentionally absent at runtime.
+    return codec;
+}
+/**
+ * Factory-vs-value discrimination for `.default()`/`.catch()` arguments.
+ * Single source of truth: `.default()`'s elision flag and {@link toThunk}
+ * must agree on it for D8 correctness. (An `Out` that is itself a function
+ * is indistinguishable from a factory — such values can't serialize anyway.)
+ */
+function isFactory(stored) {
+    return typeof stored === "function";
+}
+function serializeDefault(serializeElement, value) {
+    return rebrandForeign(() => serializeElement(value), (error) => new ParamourError(".default() value is not serializable by this codec", {
+        cause: error,
+    }));
+}
+/**
+ * Normalizes a `.default()`/`.catch()` argument to a thunk. Factories are
+ * invoked per decode/encode so each call gets a fresh value; the wrapper is
+ * the one chokepoint where a throwing user factory is branded ParamourError.
+ */
+function toThunk(stored, what) {
+    if (!isFactory(stored))
+        return () => stored;
+    return () => {
+        try {
+            return stored();
+        }
+        catch (error) {
+            // ParseError is data-level by contract (recoverable via .catch()); a
+            // factory throwing one is a config-side failure that must not
+            // masquerade as a recoverable parse failure — brand it like a foreign
+            // throw. Every other ParamourError stays loud as-is.
+            if (error instanceof ParamourError && !(error instanceof ParseError)) {
+                throw error;
+            }
+            throw new ParamourError(`.${what}() factory threw: ${foreignMessage(error)}`, { cause: error });
+        }
+    };
+}

package/dist/describe.d.ts

@@ -0,0 +1,63 @@
+import type { AnyCodec, Arity, Presence } from "./codec.js";
+import type { AnyRoute, RouterKind } from "./route.js";
+/**
+ * `.default()` in reflected form. Value-form defaults carry their wire
+ * serialization (the same text D8 elision compares against); factory
+ * defaults have no stable wire form — invoking one per description would
+ * leak time-varying values into what should be static metadata.
+ */
+export type CodecDefaultDescription = {
+    readonly kind: "factory";
+} | {
+    readonly kind: "value";
+    readonly wire: string;
+};
+/**
+ * A codec's reflection surface: everything `paramour list`-style tooling
+ * needs to render a config without executing parse/serialize. Optional
+ * members are ABSENT (not `undefined`) when they don't apply —
+ * exactOptionalPropertyTypes consumers can spread these safely.
+ */
+export interface CodecDescription {
+    readonly arity: Arity;
+    readonly caught: boolean;
+    readonly defaultValue?: CodecDefaultDescription;
+    readonly enumMembers?: readonly string[];
+    readonly kind: string;
+    readonly presence: Presence;
+}
+/** A param codec plus the dynamic-segment kind that hosts it. */
+export interface ParamDescription extends CodecDescription {
+    readonly segmentKind: "catchall" | "optional-catchall" | "single";
+}
+/** Reflected shape of one defined route. */
+export interface RouteDescription {
+    readonly params: Readonly<Record<string, ParamDescription>>;
+    readonly path: string;
+    readonly router: RouterKind;
+    readonly search: SearchDescription;
+}
+/**
+ * The `search:` slot's three shapes: absent config, a codec map, or the
+ * rawSearch escape hatch (whose schema is a black box — Standard Schema
+ * carries no introspectable structure, so `raw` is all there is to say).
+ */
+export type SearchDescription = {
+    readonly keys: Readonly<Record<string, CodecDescription>>;
+    readonly kind: "codecs";
+} | {
+    readonly kind: "none";
+} | {
+    readonly kind: "raw";
+};
+/**
+ * Reflects a codec into plain data. This is the public face of the
+ * `~`-prefixed metadata: user code reads descriptions, never the props.
+ */
+export declare function describeCodec(codec: AnyCodec): CodecDescription;
+/**
+ * Reflects a defined route: params in path order (from `~segments`, the
+ * define-time token cache), search per {@link SearchDescription}. Accepts
+ * both router brands — reflection only needs the data core.
+ */
+export declare function describeRoute(route: AnyRoute): RouteDescription;

package/dist/describe.js

@@ -0,0 +1,75 @@
+/**
+ * Reflects a codec into plain data. This is the public face of the
+ * `~`-prefixed metadata: user code reads descriptions, never the props.
+ */
+export function describeCodec(codec) {
+    const defaultValue = describeDefault(codec);
+    const enumMembers = codec["~enumMembers"];
+    return {
+        arity: codec["~arity"],
+        caught: codec["~caught"],
+        ...(defaultValue === undefined ? {} : { defaultValue }),
+        ...(enumMembers === undefined ? {} : { enumMembers }),
+        kind: codec["~kind"],
+        presence: codec["~presence"],
+    };
+}
+/**
+ * Reflects a defined route: params in path order (from `~segments`, the
+ * define-time token cache), search per {@link SearchDescription}. Accepts
+ * both router brands — reflection only needs the data core.
+ */
+export function describeRoute(route) {
+    const paramsConfig = route["~params"];
+    const params = {};
+    for (const segment of route["~segments"]) {
+        if (segment.kind === "static")
+            continue;
+        const codec = paramsConfig[segment.name];
+        // Unreachable for routes built by the define constructors (RL1 requires
+        // exactly the extracted names); guards hand-assembled objects.
+        if (codec === undefined)
+            continue;
+        params[segment.name] = {
+            ...describeCodec(codec),
+            segmentKind: segment.kind,
+        };
+    }
+    return {
+        params,
+        path: route.path,
+        router: route["~router"],
+        search: describeSearch(route["~search"]),
+    };
+}
+/**
+ * Value-form defaults re-serialize the live value (the D8 ethos — never a
+ * stale snapshot); a throwing serialize here means the default was mutated
+ * into invalidity since define time, in which case the description degrades
+ * to the factory arm rather than throwing from a read-only reflection call.
+ */
+function describeDefault(codec) {
+    const thunk = codec["~defaultValue"];
+    if (thunk === undefined)
+        return undefined;
+    if (!codec["~defaultElides"])
+        return { kind: "factory" };
+    try {
+        return { kind: "value", wire: codec["~serializeElement"](thunk()) };
+    }
+    catch {
+        return { kind: "factory" };
+    }
+}
+function describeSearch(slot) {
+    // RawSearch's brand; codec maps never carry top-level `~` keys (SS2).
+    if ("~kind" in slot && slot["~kind"] === "raw-search")
+        return { kind: "raw" };
+    const entries = Object.entries(slot);
+    if (entries.length === 0)
+        return { kind: "none" };
+    const keys = {};
+    for (const [key, codec] of entries)
+        keys[key] = describeCodec(codec);
+    return { keys, kind: "codecs" };
+}

package/dist/errors.d.ts

@@ -0,0 +1,73 @@
+/** One failed key in an aggregate decode error (shared by both surfaces, RL6). */
+export interface Issue {
+    readonly key: string;
+    readonly message: string;
+}
+/** The single error type surfaced by a full route parse failure (RL6). */
+export type RouteDecodeError = ParamsDecodeError | SearchDecodeError;
+/** Base class for every error paramour throws. */
+export declare class ParamourError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+    static [Symbol.hasInstance](value: unknown): value is ParamourError;
+}
+/** Aggregate failure for a whole route-params decode (RL6). */
+export declare class ParamsDecodeError extends ParamourError {
+    readonly issues: readonly Issue[];
+    constructor(issues: readonly Issue[]);
+    static [Symbol.hasInstance](value: unknown): value is ParamsDecodeError;
+}
+/**
+ * A single wire value failed its codec grammar or schema validation.
+ * Thrown by element-level parsing; recoverable via `.catch()`.
+ */
+export declare class ParseError extends ParamourError {
+    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[];
+    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.
+ */
+export declare function foreignMessage(error: unknown): string;
+/**
+ * Runs user (or platform) code, letting paramour's own errors pass through
+ * and branding any foreign throw via `wrap` — the shared chokepoint for the
+ * "every throw is a ParamourError" contract. Not exported from the package.
+ */
+export declare function rebrandForeign<T>(run: () => T, wrap: (error: unknown) => ParamourError): T;
+/**
+ * String() for error messages: objects without a usable primitive conversion
+ * (null-prototype objects, Symbol.toPrimitive throwers) make String() itself
+ * throw a raw TypeError, which would escape before the guard's branded error
+ * is even constructed. Not exported from the package.
+ */
+export declare function showValue(value: unknown): string;

package/dist/errors.js

@@ -0,0 +1,157 @@
+/**
+ * Cross-copy identity brands (RL6). `Symbol.for()` keys resolve in the
+ * realm-global symbol registry, so a second physical copy of this module
+ * (dual-package hazard, bundler duplication) mints the SAME symbols:
+ * `instanceof` recognizes instances across copies, while a structurally
+ * identical foreign class lacks the brands entirely. Brands sit on the
+ * prototype (non-enumerable), so an instance carries every brand in its
+ * chain and subclass/base checks stay hierarchy-correct across copies.
+ */
+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 {
+    static {
+        brandPrototype(this, paramourErrorBrand);
+    }
+    constructor(message, options) {
+        super(message, options);
+        this.name = new.target.name;
+    }
+    // Each class checks its OWN brand: an inherited base check would make
+    // every ParamourError pass `instanceof ParseError`. The type-predicate
+    // signature is load-bearing — TS narrows `instanceof` from it.
+    static [Symbol.hasInstance](value) {
+        return hasBrand(value, paramourErrorBrand);
+    }
+}
+/** Aggregate failure for a whole route-params decode (RL6). */
+export class ParamsDecodeError extends ParamourError {
+    static {
+        brandPrototype(this, paramsDecodeErrorBrand);
+    }
+    issues;
+    constructor(issues) {
+        super(`Failed to decode route params: ${formatIssues(issues)}`);
+        this.issues = issues;
+    }
+    static [Symbol.hasInstance](value) {
+        return hasBrand(value, paramsDecodeErrorBrand);
+    }
+}
+/**
+ * A single wire value failed its codec grammar or schema validation.
+ * Thrown by element-level parsing; recoverable via `.catch()`.
+ */
+export class ParseError extends ParamourError {
+    static {
+        brandPrototype(this, parseErrorBrand);
+    }
+    static [Symbol.hasInstance](value) {
+        return hasBrand(value, parseErrorBrand);
+    }
+}
+/** Aggregate failure for a whole search-params decode. */
+export class SearchDecodeError extends ParamourError {
+    static {
+        brandPrototype(this, searchDecodeErrorBrand);
+    }
+    issues;
+    constructor(issues) {
+        super(`Failed to decode search params: ${formatIssues(issues)}`);
+        this.issues = issues;
+    }
+    static [Symbol.hasInstance](value) {
+        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 {
+        brandPrototype(this, serializeErrorBrand);
+    }
+    static [Symbol.hasInstance](value) {
+        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.
+ */
+export function foreignMessage(error) {
+    return error instanceof Error ? error.message : showValue(error);
+}
+/**
+ * Runs user (or platform) code, letting paramour's own errors pass through
+ * and branding any foreign throw via `wrap` — the shared chokepoint for the
+ * "every throw is a ParamourError" contract. Not exported from the package.
+ */
+export function rebrandForeign(run, wrap) {
+    try {
+        return run();
+    }
+    catch (error) {
+        if (error instanceof ParamourError)
+            throw error;
+        throw wrap(error);
+    }
+}
+/**
+ * String() for error messages: objects without a usable primitive conversion
+ * (null-prototype objects, Symbol.toPrimitive throwers) make String() itself
+ * throw a raw TypeError, which would escape before the guard's branded error
+ * is even constructed. Not exported from the package.
+ */
+export function showValue(value) {
+    try {
+        return String(value);
+    }
+    catch {
+        return `[unstringifiable ${typeof value}]`;
+    }
+}
+function brandPrototype(ctor, brand) {
+    // defineProperty defaults: non-enumerable, non-writable, non-configurable —
+    // the brand never leaks into JSON/spread and can't be reassigned.
+    Object.defineProperty(ctor.prototype, brand, { value: true });
+}
+function formatIssues(issues) {
+    return issues.map((issue) => `[${issue.key}] ${issue.message}`).join("; ");
+}
+function hasBrand(value, brand) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    return value[brand] === true;
+}

package/dist/href.d.ts

@@ -0,0 +1,79 @@
+import type { AnyRoute, RegisteredStaticRoutePaths } from "./route.js";
+import { type InferParamsInput } from "./path.js";
+import { type SearchInputOf } from "./search.js";
+/**
+ * Type-only brand carrier (RL4): no runtime value ever exists — the brand
+ * is applied by a compile-time cast, so Href costs nothing at runtime.
+ */
+declare const HREF: unique symbol;
+/**
+ * A paramour-built link (RL4). Assignable TO `string`, so `next/link`,
+ * `router.push`, `redirect`, `generateMetadata` consume it unchanged
+ * (DESIGN principle 5); not assignable FROM `string`, which is the enabling
+ * substrate for the v1.x "accept only paramour-built links" narrowing APIs
+ * (RL10.6). Removing the brand later would be breaking; RL4 commits to it.
+ */
+export type Href<P extends string = string> = string & {
+    [HREF]: P;
+};
+/**
+ * href's variadic options tuple (RL4): the entire argument is omittable
+ * when neither half has a required member — `href(aboutRoute)`.
+ */
+export type HrefArgs<R extends AnyRoute> = Record<never, never> extends InferHrefInput<R> ? [options?: InferHrefInput<R>] : [options: InferHrefInput<R>];
+/**
+ * href's options object (RL4): `{ params, search?, hash? }`. Property
+ * optionality is presence-driven on BOTH halves (maintainer ruling,
+ * 2026-07-04, amending RL4's letter): a half may be omitted when its input
+ * type has no required key — for `params` that means static routes and
+ * routes whose only dynamic segment is an optional catch-all; for `search`
+ * it is design-02 D4's rule surfacing at the property level. A half whose
+ * input has no 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"]>> & {
+    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
+ * `object extends` probe). An input with NO keys at all bans the property
+ * outright (`?: never`, maintainer ruling 2026-07-04 amending RL4) — the
+ * bare `Partial<Record<Key, Input>>` form would accept arbitrary junk
+ * there, because the empty object type is exempt from excess-property
+ * checking; `?: never` mirrors RouteConfig's static-path `params?: never`.
+ */
+type PartFor<Key extends string, Input> = keyof Input extends never ? Partial<Record<Key, never>> : Record<never, never> extends Input ? Partial<Record<Key, Input>> : Record<Key, Input>;
+/**
+ * Builds a link for a route: fixed path–`?query`–`#hash` assembly (RL4). A
+ * standalone function, not a route method (DESIGN §4/§8): parse sites sit
+ * next to one route, href sites import `{ href }` once and use it against
+ * many routes. Serialization failures are `SerializeError` at link-build
+ * time (RL5's R-rules); config-contract violations from hand-built routes
+ * (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

@@ -0,0 +1,32 @@
+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
+// the unsoundness lives at this one overload boundary (same move as
+// 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) {
+    // 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}`;
+}