@rangojs/router 0.0.0-experimental.f3c21dba → 0.0.0-experimental.f4a8e8de

package/dist/types/rsc/ssr-setup.d.ts

@@ -0,0 +1,73 @@
+/**
+ * SSR Setup Utilities
+ *
+ * Manages early kickoff and retrieval of SSR module loading and stream mode
+ * resolution. Both operations are request-scoped but independent of route
+ * matching, so they can run in parallel with segment resolution.
+ */
+import type { HandlerContext } from "./handler-context.js";
+import type { SSRModule, SSRRenderOptions } from "./types.js";
+import type { SSRStreamMode } from "../router/router-options.js";
+import type { MetricsStore } from "../server/context.js";
+import type { RscFlightStage, RscPreparedHtmlRender } from "./render-pipeline.js";
+export type SSRSetup = readonly [SSRModule, SSRStreamMode];
+/**
+ * Key used to stash the early SSR setup promise on request variables.
+ * Read back via `getSSRSetup`.
+ */
+export declare const SSR_SETUP_VAR = "__ssrSetup";
+/**
+ * Start loading the SSR module and resolving the stream mode in parallel.
+ * When a `getMetricsStore` getter is provided, records individual
+ * `ssr:module-load` and `ssr:stream-mode` metrics (the getter is called
+ * lazily so stores created after kickoff are still captured). Without a
+ * getter the promises run bare — no `.then()` microtasks, no
+ * `performance.now()` calls — keeping the non-debug hot path lean.
+ */
+export declare function startSSRSetup<TEnv>(ctx: HandlerContext<TEnv>, request: Request, env: TEnv, url: URL, getMetricsStore?: () => MetricsStore | undefined): Promise<SSRSetup>;
+export interface SsrHtmlStageOptions<TEnv> {
+    ctx: HandlerContext<TEnv>;
+    request: Request;
+    env: TEnv;
+    url: URL;
+    /** Metrics store for ssr:module-load / ssr:stream-mode timing (per call site). */
+    metricsStore: MetricsStore | undefined;
+    /**
+     * renderHTML options minus streamMode (the stage resolves streamMode). Carries
+     * the per-site nonce and, for the PE action re-render, formState. Spread
+     * verbatim so each call site's exact key set is preserved.
+     */
+    render: Omit<SSRRenderOptions, "streamMode">;
+    /** ResponseInit merged into the prepared render (e.g. content-type). */
+    init?: ResponseInit;
+}
+/**
+ * Build the `html` stage callback renderRscResponse drives: await the (possibly
+ * early-kicked-off) SSR setup, then renderHTML over the Flight stream. The four
+ * render paths (rsc-rendering full/partial, 404, PE, PE-error) differ only in
+ * metricsStore, render options (nonce/formState), and init — threaded here so
+ * the getSSRSetup + renderHTML wiring lives in one place.
+ */
+export declare function createSsrHtmlStage<TEnv>(options: SsrHtmlStageOptions<TEnv>): (flight: RscFlightStage) => Promise<RscPreparedHtmlRender>;
+/**
+ * Retrieve the SSR setup result. Returns the early-kicked-off promise
+ * when available (stashed on request variables), otherwise starts a
+ * fresh setup.
+ */
+export declare function getSSRSetup<TEnv>(ctx: HandlerContext<TEnv>, request: Request, env: TEnv, url: URL, metricsStore: MetricsStore | undefined): Promise<SSRSetup>;
+/**
+ * Classify whether a request may require SSR (HTML rendering).
+ *
+ * Returns false for requests that are definitively RSC-only: transport
+ * params (partial/action/loader/__rsc), prerender collection, or an explicit
+ * Accept: text/x-component. Must never return false for a request whose
+ * render-time decision (isRscRequest) will be HTML — the two share
+ * acceptsFlightExplicitly so the Accept rule cannot drift. document-cache.ts
+ * keys its HTML/RSC response slots off this function, so any divergence from
+ * the render decision poisons a cache slot with the wrong representation.
+ *
+ * Note: response/mime routes are excluded by the caller — this function
+ * runs after classifyRequest() determines the request mode.
+ */
+export declare function mayNeedSSR(request: Request, url: URL): boolean;
+export declare function isRscRequest(request: Request, url: URL, isPartial: boolean): boolean;

package/dist/types/rsc/stream-idle.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Stream-idle timeout — the enforcement for `timeouts.streamIdleMs` (the
+ * "stream-idle" TimeoutPhase, reserved since the timeout API landed).
+ *
+ * WHY: nothing else bounds a streaming response body's lifetime.
+ * `renderStartMs` only bounds time-to-Response-construction; once the body is
+ * streaming, a single never-settling promise embedded in the payload (a
+ * deferred loader that never resolves, an orphaned ctx.rendered() barrier)
+ * holds the Flight/HTML stream — and the client's connection — open forever.
+ * Deferred HANDLES have a 10s auto-resolve net (defer.ts); loader promises
+ * and everything else have none. Field-observed as multi-second dead
+ * connections only closed by client cancellation.
+ *
+ * SEMANTICS — end-to-end idle flow, deliberately: the watchdog re-arms on
+ * every chunk that flows THROUGH to the client, so "idle" means "no bytes
+ * reached the wire for N ms". A stalled slow client counts as idle the same
+ * as a wedged producer — the two are indistinguishable here without buffering,
+ * and buffering is banned on the streaming path. Pick budgets accordingly
+ * (generous, seconds not millis); the feature is OPT-IN (unset = today's
+ * unbounded behavior, and the `timeout` shorthand deliberately does not apply
+ * to streamIdleMs — see resolveTimeouts).
+ *
+ * ON TRIP: the client-facing stream is errored with a RouterTimeoutError
+ * ("stream-idle") — the host terminates the response visibly (truncated
+ * chunked encoding), which is debuggable, unlike a silent clean close that
+ * would present a half-document as complete. Erroring the transform makes the
+ * pipe cancel its SOURCE, which aborts React's fizz/flight render — but only
+ * when the watchdog's branch is the sole consumer. When an upstream layer
+ * teed or cloned the body first (the document-cache MISS drain,
+ * response-cache clones), the watchdog holds one tee branch: tee semantics
+ * cancel the underlying source only once EVERY branch cancels, so the cache
+ * branch keeps the wedged render alive, bounded only by the platform's
+ * waitUntil budget — exactly as it was before this feature. The client-facing
+ * bound is unconditional; source teardown is best-effort. `onTimeout` does
+ * NOT apply: the response already left the handler, so no replacement
+ * Response can be served — the trip is reported via onError + the
+ * request.timeout telemetry event instead.
+ *
+ * COST: one identity TransformStream hop per chunk, only when the timeout is
+ * enabled. Never buffers, never reads ahead, adds no work when disabled.
+ */
+import { RouterTimeoutError } from "../router/timeout.js";
+/** What the watchdog observed when it tripped. */
+export interface StreamIdleTrip {
+    /** ms since the watchdog armed (response handoff) — the stream's lifetime. */
+    totalMs: number;
+    /** Chunks forwarded before the trip. */
+    chunks: number;
+    /** The error the client-facing stream was terminated with. */
+    error: RouterTimeoutError;
+}
+/**
+ * Wrap `response`'s body in an idle watchdog. Returns a NEW Response with the
+ * same status/headers whose body errors (and cancels the source) once no chunk
+ * has flowed for `idleMs`. Callers gate on isTimeoutEnabled + body presence +
+ * NOT a websocket upgrade (a 101/webSocket response must never be
+ * reconstructed); this function assumes those checks were made. `onTrip` fires
+ * at most once, after the client-facing stream has been errored.
+ */
+export declare function applyStreamIdleTimeout(response: Response, idleMs: number, onTrip: (trip: StreamIdleTrip) => void): Response;

package/dist/types/rsc/transition-gate.d.ts

@@ -0,0 +1,23 @@
+import type { MatchResult } from "../types.js";
+import type { getRequestContext } from "../server/request-context.js";
+import type { OnErrorCallback } from "../types/error-types.js";
+/**
+ * Apply transition({ when }) gates to a payload's segments.
+ *
+ * PPR predicates were evaluated from the manifest before cache lookup and route
+ * handlers; their request-specific decisions are projected onto a copy so they
+ * never mutate reusable cache/prerender/shell records. Ordinary-route predicates
+ * were collected during fresh resolution and are evaluated here after handlers.
+ * Both paths drop the segment transition when the predicate does not hold.
+ *
+ * Mutating the segments here is safe: the segment cache stores a serialized copy
+ * (segment-codec), written during match() BEFORE this gate runs, so dropping a
+ * transition never corrupts a cache entry. On an ordinary route, a cache hit
+ * skips resolution, collects no predicate, and replays the cached transition
+ * as-is (it was serialized before the gate). PPR routes are the exception: their
+ * manifest predicates were evaluated before lookup and apply to replayed data.
+ *
+ * Returns the same array for the ordinary post-handler path. A PPR drop returns a
+ * copy containing only the request-specific transition changes.
+ */
+export declare function gateTransitions(segments: MatchResult["segments"], ctx: ReturnType<typeof getRequestContext>, onError?: OnErrorCallback): MatchResult["segments"];

package/dist/types/rsc/types.d.ts

@@ -0,0 +1,328 @@
+/**
+ * RSC Handler Types
+ *
+ * Type definitions for the RSC request handler, payload structures,
+ * and SSR integration.
+ */
+import type { ResolvedSegment, SlotState } from "../types.js";
+import type { HandleData } from "../server/handle-store.js";
+import type { RangoInternal } from "../router/router-interfaces.js";
+import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
+/**
+ * RSC payload sent to the client.
+ * The tree is always reconstructed from metadata.segments by consumers
+ * (SSR via renderSegments, browser via renderSegments in bridges).
+ */
+export interface RscPayload {
+    metadata?: {
+        pathname: string;
+        segments: ResolvedSegment[];
+        /** Router instance ID. When this changes between navigations, the client
+         *  discards cached segments and does a full tree replacement (app switch). */
+        routerId?: string;
+        isPartial?: boolean;
+        isError?: boolean;
+        matched?: string[];
+        diff?: string[];
+        /**
+         * All segment ids re-resolved on the server, including null-component
+         * ones excluded from `segments`/`diff`. Drives client-side handle-bucket
+         * cleanup. Superset of `diff`. See MatchResult.resolvedIds.
+         */
+        resolvedIds?: string[];
+        /** Merged route params from the matched route */
+        params?: Record<string, string>;
+        slots?: Record<string, SlotState>;
+        /**
+         * Intercept TARGET route names reachable from this location as a
+         * navigation origin (see MatchResult.interceptTargets). The browser-local
+         * clientUrls matcher declines optimistic presentation for these.
+         */
+        interceptTargets?: string[];
+        /** Root layout component for browser-side re-renders (client component reference) */
+        rootLayout?: React.ComponentType<{
+            children: React.ReactNode;
+        }>;
+        /** Handle data accumulated across route segments (async generator that yields on each push) */
+        handles?: AsyncGenerator<HandleData, void, unknown>;
+        /**
+         * Document-lane late handle channel: full-state updates for pushes landing
+         * AFTER the handler barrier (streaming loader bodies writing handles
+         * mid-body). `handles` above is drained to completion in blocking
+         * positions (SSR seed, pre-hydration), so late pushes need this separate
+         * generator, consumed non-blocking post-hydration (rsc-router.tsx).
+         * Empty/instantly-complete when no auxiliary-lane work is pending at the
+         * handler barrier. Full payloads only — partial payloads' `handles`
+         * generator streams to full settle already.
+         */
+        handlesLate?: AsyncGenerator<HandleData, void, unknown>;
+        /** RSC version string for cache invalidation */
+        version?: string;
+        /** Cloudflare dev worker generation used for stale-document convergence. */
+        devDiscoveryEpoch?: number;
+        /** TTL in milliseconds for the client-side in-memory prefetch cache */
+        prefetchCacheTTL?: number;
+        /** Max entries in the client-side in-memory prefetch cache (FIFO eviction) */
+        prefetchCacheSize?: number;
+        /** Max concurrent speculative prefetch requests on the client */
+        prefetchConcurrency?: number;
+        /** Router-wide default prefetch strategy for Links without a `prefetch` prop */
+        defaultPrefetch?: import("../router/prefetch-default.js").PrefetchStrategy;
+        /** Server-resolved rango state cookie name; the client reads it verbatim. */
+        stateCookieName?: string;
+        /** Theme configuration for FOUC prevention */
+        themeConfig?: ResolvedThemeConfig | null;
+        /** Initial theme from cookie (for SSR hydration) */
+        initialTheme?: Theme;
+        /** URL prefix for all routes (from createRouter({ basename })). */
+        basename?: string;
+        /** Whether connection warmup is enabled */
+        warmupEnabled?: boolean;
+        /**
+         * Whether the client should hydrate inside React.StrictMode. Carried on
+         * the initial full-render payload only; the browser entry reads it once at
+         * hydration. Absent on partial (navigation) payloads. Defaults to true on
+         * the client when omitted.
+         */
+        strictMode?: boolean;
+        /**
+         * Server-side redirect with optional state (for partial requests).
+         * `external: true` (from redirect(url, { external: true })) tells the client
+         * to hard-navigate to an off-host target instead of validating same-origin.
+         */
+        redirect?: {
+            url: string;
+            external?: boolean;
+        };
+        /** Server-set location state to include in history.pushState */
+        locationState?: Record<string, unknown>;
+    };
+    returnValue?: {
+        ok: boolean;
+        data: unknown;
+    };
+}
+/**
+ * React form state type for useActionState progressive enhancement
+ */
+export type ReactFormState = unknown;
+/**
+ * RSC dependencies from @vitejs/plugin-rsc/rsc
+ */
+export interface RSCDependencies {
+    /**
+     * renderToReadableStream from @vitejs/plugin-rsc/rsc
+     */
+    renderToReadableStream: <T>(payload: T, options?: {
+        temporaryReferences?: unknown;
+        onError?: (error: unknown) => string | void;
+    }) => ReadableStream<Uint8Array>;
+    /**
+     * decodeReply from @vitejs/plugin-rsc/rsc
+     */
+    decodeReply: (body: FormData | string, options?: {
+        temporaryReferences?: unknown;
+    }) => Promise<unknown[]>;
+    /**
+     * createTemporaryReferenceSet from @vitejs/plugin-rsc/rsc
+     */
+    createTemporaryReferenceSet: () => unknown;
+    /**
+     * loadServerAction from @vitejs/plugin-rsc/rsc
+     */
+    loadServerAction: (actionId: string) => Promise<Function>;
+    /**
+     * decodeAction from @vitejs/plugin-rsc/rsc
+     * Decodes a FormData into a bound action function (for useActionState forms)
+     */
+    decodeAction: (body: FormData) => Promise<() => Promise<unknown>>;
+    /**
+     * decodeFormState from @vitejs/plugin-rsc/rsc
+     * Decodes the action result into a ReactFormState for useActionState progressive enhancement
+     */
+    decodeFormState: (actionResult: unknown, body: FormData) => Promise<ReactFormState | null>;
+}
+/**
+ * Options for SSR HTML rendering
+ */
+export interface SSRRenderOptions {
+    /**
+     * Form state for useActionState progressive enhancement.
+     * This is the result of decodeFormState() and should be passed to
+     * react-dom's renderToReadableStream to enable useActionState to
+     * receive the action result during SSR.
+     */
+    formState?: ReactFormState | null;
+    /**
+     * Nonce for Content Security Policy (CSP)
+     */
+    nonce?: string;
+    /**
+     * SSR stream mode.
+     *
+     * - `"stream"` (default) — start flushing HTML immediately.
+     * - `"allReady"` — await `stream.allReady` before returning.
+     */
+    streamMode?: import("../router/router-options.js").SSRStreamMode;
+}
+/**
+ * SSR module interface for HTML rendering
+ */
+export interface SSRModule {
+    renderHTML: (rscStream: ReadableStream<Uint8Array>, options?: SSRRenderOptions) => Promise<ReadableStream<Uint8Array>>;
+    /**
+     * PPR shell CAPTURE strategy (Axis 2). Prerenders the loader-masked shell over
+     * the Flight stream, aborts once quiescent, and returns the prelude bytes plus
+     * the postponed resume state — or null when the prelude degraded and must not
+     * be stored. Present only when the SSR virtual entry wires
+     * createShellCaptureHandler; the render layer feature-detects it. See
+     * docs/design/ppr-shell-resume.md.
+     */
+    captureShellHTML?: (rscStream: ReadableStream<Uint8Array>, options: {
+        quiesce: Promise<void>;
+        maxWaitMs?: number;
+    }) => Promise<{
+        prelude: Uint8Array;
+        postponed: string | null;
+    } | null>;
+    /**
+     * PPR shell RESUME strategy (Axis 2). Produces the per-request live portion of
+     * the document: resumes fizz over a fresh SsrRoot to emit only the postponed
+     * holes (or, for the DATA variant with postponed === null, just the fresh Flight
+     * payload scripts). The caller prepends the stored prelude bytes to form the
+     * composite response. Present only when the SSR virtual entry wires
+     * createShellResumeHandler; the render layer feature-detects it.
+     */
+    resumeShellHTML?: (rscStream: ReadableStream<Uint8Array>, options: {
+        postponed: string | null;
+        nonce?: string;
+    }) => Promise<ReadableStream<Uint8Array>>;
+}
+/**
+ * Function to load SSR module dynamically
+ */
+export type LoadSSRModule = () => Promise<SSRModule>;
+/**
+ * Cache configuration for handler.
+ * TTL is configured via store.defaults or cache() boundaries.
+ */
+export interface HandlerCacheConfig {
+    /** Cache store implementation */
+    store: import("../cache/types.js").SegmentCacheStore;
+    /** Enable/disable caching (default: true) */
+    enabled?: boolean;
+    /**
+     * Which query params key the cache (default: `"all"`). Affects cache keys
+     * ONLY -- handlers and loaders still see the full query string. Global by
+     * design: the per-route case is already reachable through `cache({ key })`.
+     *
+     * Excluding a param is a promise that rendered output does not depend on
+     * it; if it does, the first variant is cached and served to everyone.
+     *
+     * @example
+     * ```typescript
+     * cache: {
+     *   store: cacheStore,
+     *   searchParams: { exclude: TRACKING_SEARCH_PARAMS },
+     * }
+     * ```
+     */
+    searchParams?: import("../cache/search-params-filter.js").CacheSearchParams;
+}
+/**
+ * Nonce provider function type.
+ * Can return a nonce string, or true to auto-generate one.
+ */
+export type NonceProvider<TEnv = unknown> = (request: Request, env: TEnv) => string | true | Promise<string | true>;
+/**
+ * Options for creating an RSC handler
+ */
+export interface CreateRSCHandlerOptions<TEnv = unknown, TRoutes extends Record<string, string> = Record<string, string>> {
+    /**
+     * The RSC router instance
+     */
+    router: RangoInternal<TEnv, TRoutes>;
+    /**
+     * RSC dependencies from @vitejs/plugin-rsc/rsc.
+     * Defaults to the exports from @vitejs/plugin-rsc/rsc.
+     */
+    deps?: RSCDependencies;
+    /**
+     * Function to load the SSR module for HTML rendering.
+     * Defaults to: () => import.meta.viteRsc.loadModule("ssr", "index")
+     */
+    loadSSRModule?: LoadSSRModule;
+    /**
+     * Cache configuration for segment caching.
+     *
+     * Can be a static config object or a function that receives the env
+     * (useful for accessing Cloudflare bindings).
+     *
+     * If not provided, caching is disabled. TTL is configured via store.defaults
+     * or cache() boundaries in the route definition.
+     *
+     * @example Static config
+     * ```typescript
+     * cache: {
+     *   store: new MemorySegmentCacheStore({ defaults: { ttl: 60 } }),
+     * }
+     * ```
+     *
+     * @example Dynamic config with env
+     * ```typescript
+     * cache: (env) => ({
+     *   store: new KVSegmentCacheStore(env.Bindings.MY_CACHE, { defaults: { ttl: 60 } }),
+     * })
+     * ```
+     */
+    cache?: HandlerCacheConfig | ((env: TEnv) => HandlerCacheConfig);
+    /**
+     * RSC version string included in metadata.
+     * The browser sends this back on partial requests to detect version mismatches.
+     *
+     * Defaults to the auto-generated VERSION from `rsc-router:version` virtual module.
+     * Only set this if you need a custom versioning strategy.
+     *
+     * @default VERSION from rsc-router:version
+     */
+    version?: string;
+    /**
+     * Nonce provider for Content Security Policy (CSP).
+     *
+     * Can be:
+     * - A function that returns a nonce string
+     * - A function that returns `true` to auto-generate a nonce
+     * - Undefined to disable nonce (default)
+     *
+     * The nonce will be applied to inline scripts injected by the RSC payload.
+     * It's also available to middleware via the typed `nonce` token:
+     * `import { nonce } from "@rangojs/router"; ctx.get(nonce)`
+     *
+     * @example Auto-generate nonce
+     * ```tsx
+     * createRSCHandler({
+     *   router,
+     *   nonce: () => true,
+     * });
+     * ```
+     *
+     * @example Custom nonce from request context
+     * ```tsx
+     * createRSCHandler({
+     *   router,
+     *   nonce: (request, env) => env.nonce,
+     * });
+     * ```
+     *
+     * @example Access nonce in middleware
+     * ```tsx
+     * import { nonce } from "@rangojs/router";
+     *
+     * const cspMiddleware: Middleware = async (ctx, next) => {
+     *   const value = ctx.get(nonce); // string | undefined
+     *   await next();
+     * };
+     * ```
+     */
+    nonce?: NonceProvider<TEnv>;
+}

package/dist/types/runtime-env.d.ts

@@ -0,0 +1 @@
+export declare function isUnderTestRunner(): boolean;

package/dist/types/search-params.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Search parameter schema types and runtime utilities.
+ *
+ * Provides a lightweight schema system for typed query parameters.
+ * When a route defines a `search` schema, ctx.search provides a typed
+ * object with parsed values. ctx.searchParams always remains a standard
+ * URLSearchParams instance.
+ */
+/** Supported scalar types for search params (append ? for optional). */
+export type SearchSchemaValue = "string" | "number" | "boolean" | "string?" | "number?" | "boolean?";
+/** A search schema maps param names to their type descriptors. */
+export type SearchSchema = Record<string, SearchSchemaValue>;
+/** Strip trailing `?` from a schema value to get the base type. */
+type BaseType<T extends string> = T extends `${infer B}?` ? B : T;
+/** Map a base type string to its TypeScript type. */
+type ResolveBaseType<T extends string> = T extends "string" ? string : T extends "number" ? number : T extends "boolean" ? boolean : never;
+/** Keys whose schema value does NOT end with `?`. */
+type RequiredKeys<T extends SearchSchema> = {
+    [K in keyof T]: T[K] extends `${string}?` ? never : K;
+}[keyof T];
+/** Keys whose schema value ends with `?`. */
+type OptionalKeys<T extends SearchSchema> = {
+    [K in keyof T]: T[K] extends `${string}?` ? K : never;
+}[keyof T];
+/** Flatten an intersection type into a single object type. */
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+};
+/**
+ * Resolve a SearchSchema to its typed object.
+ *
+ * Both required and optional params resolve to `T | undefined` at the handler
+ * level. The required/optional distinction is a consumer-facing contract
+ * (e.g., for href() and reverse() autocomplete) — it tells callers which
+ * params the route expects, but the handler must still check for undefined
+ * since the framework cannot trust the client to send all required params.
+ *
+ * @example
+ * type S = { q: "string"; page: "number?"; sort: "string?" };
+ * type R = ResolveSearchSchema<S>;
+ * // { q: string | undefined; page?: number; sort?: string }
+ */
+export type ResolveSearchSchema<T extends SearchSchema> = Simplify<{
+    [K in RequiredKeys<T> & string]: ResolveBaseType<BaseType<T[K]>> | undefined;
+} & {
+    [K in OptionalKeys<T> & string]?: ResolveBaseType<BaseType<T[K]>>;
+}>;
+/** Resolve the global route map from RegisteredRoutes or GeneratedRouteMap. */
+type GlobalRouteMap = keyof Rango.RegisteredRoutes extends never ? keyof Rango.GeneratedRouteMap extends never ? Record<string, string> : Rango.GeneratedRouteMap : Rango.RegisteredRoutes;
+/**
+ * Extract the resolved search params type for a named route.
+ * Looks up the search schema from the route map and resolves it.
+ *
+ * @example
+ * ```typescript
+ * // Given: path("/search", handler, { name: "search", search: { q: "string", page: "number?" } })
+ * type Params = RouteSearchParams<"search">;
+ * // { q: string; page?: number }
+ * ```
+ */
+export type RouteSearchParams<TName extends string, TRouteMap = never> = [
+    TRouteMap
+] extends [never] ? ExtractAndResolveSearch<GlobalRouteMap, TName> : ExtractAndResolveSearch<TRouteMap, TName>;
+type ExtractAndResolveSearch<TRouteMap, TName> = TName extends keyof TRouteMap ? TRouteMap[TName] extends {
+    readonly search: infer S extends SearchSchema;
+} ? ResolveSearchSchema<S> : {} : {};
+/**
+ * Extract the route params type for a named route.
+ * Looks up the path pattern from the route map and extracts params.
+ *
+ * @example
+ * ```typescript
+ * // Given: path("/blog/:slug", handler, { name: "blogPost" })
+ * type Params = RouteParams<"blogPost">;
+ * // { slug: string }
+ * ```
+ */
+export type RouteParams<TName extends string, TRouteMap = never> = [
+    TRouteMap
+] extends [never] ? ExtractRouteParamsFromMap<GlobalRouteMap, TName> : ExtractRouteParamsFromMap<TRouteMap, TName>;
+type ExtractRouteParamsFromMap<TRouteMap, TName> = TName extends keyof TRouteMap ? TRouteMap[TName] extends string ? ExtractParamsFromPattern<TRouteMap[TName]> : TRouteMap[TName] extends {
+    readonly path: infer P extends string;
+} ? ExtractParamsFromPattern<P> : {} : {};
+/** Parse "a|b|c" into "a" | "b" | "c" */
+type ParseConstraint<T extends string> = T extends `${infer First}|${infer Rest}` ? First | ParseConstraint<Rest> : T;
+/** Minimal inline param extraction (avoids importing from types.ts to prevent circular deps). */
+type ExtractParamsFromPattern<T extends string> = T extends `${string}:${infer Param}/${infer Rest}` ? Param extends `${infer Name}(${infer C})?` ? {
+    [K in Name]?: ParseConstraint<C>;
+} & ExtractParamsFromPattern<`/${Rest}`> : Param extends `${infer Name}(${infer C})` ? {
+    [K in Name]: ParseConstraint<C>;
+} & ExtractParamsFromPattern<`/${Rest}`> : Param extends `${infer Name}?` ? {
+    [K in Name]?: string;
+} & ExtractParamsFromPattern<`/${Rest}`> : {
+    [K in Param]: string;
+} & ExtractParamsFromPattern<`/${Rest}`> : T extends `${string}:${infer Param}` ? Param extends `${infer Name}(${infer C})?` ? {
+    [K in Name]?: ParseConstraint<C>;
+} : Param extends `${infer Name}(${infer C})` ? {
+    [K in Name]: ParseConstraint<C>;
+} : Param extends `${infer Name}?` ? {
+    [K in Name]?: string;
+} : {
+    [K in Param]: string;
+} : {};
+/**
+ * Parse URLSearchParams into a typed object using the given schema.
+ *
+ * - `"string"` / `"string?"` - kept as-is
+ * - `"number"` / `"number?"` - parsed as a finite decimal number. Accepts an
+ *   optional sign, digits with optional fraction, and optional exponent
+ *   (e.g. `42`, `-3.5`, `1e3`). Empty/whitespace-only, non-decimal forms
+ *   (`0x10`), and non-finite (`Infinity`) are treated as missing (omitted),
+ *   NOT coerced to `0`/`16`/`Infinity`.
+ * - `"boolean"` / `"boolean?"` - `"true"` / `"1"` -> true, `"false"` / `"0"` / `""` -> false
+ *
+ * Missing params (both required and optional) are omitted from the result
+ * (undefined). The required/optional distinction is a consumer-facing contract
+ * only — the handler must check for undefined.
+ */
+export declare function parseSearchParams<T extends SearchSchema>(searchParams: URLSearchParams, schema: T): ResolveSearchSchema<T>;
+/**
+ * Serialize a typed search params object to a query string (without leading `?`).
+ * Skips `undefined` and `null` values. Preserves insertion order (no sort).
+ */
+export declare function serializeSearchParams(params: Record<string, unknown>): string;
+export {};

package/dist/types/segment-content-promise.d.ts

@@ -0,0 +1,13 @@
+import type { ReactNode } from "react";
+/**
+ * Return a stable Promise wrapping `component`, memoized on the component ref.
+ *
+ * A fresh `Promise.resolve(component)` each render would suspend for one
+ * microtask and briefly commit the loading fallback inside Suspender — the
+ * intercept / parallel-slot flicker this indirection prevents. Reusing the
+ * same Promise ref keeps React's `use()` in "known fulfilled" state after
+ * the first observation.
+ *
+ * @internal
+ */
+export declare function getMemoizedContentPromise(component: ReactNode): Promise<ReactNode>;