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

package/dist/types/client.d.ts

@@ -0,0 +1,191 @@
+import { Component, type ReactNode } from "react";
+import { type ClientErrorBoundaryFallbackProps } from "./types";
+/**
+ * Outlet component - renders child content in layouts
+ *
+ * If the current segment defines a loading component, the outlet content
+ * is wrapped in Suspense with the loading component as fallback.
+ * This means during navigation/streaming, React's Suspense will automatically
+ * show the loading skeleton until the content is ready.
+ *
+ * When a name prop is provided (e.g., "@modal"), renders content from
+ * the parallel segment with that slot name instead of the default content.
+ * This is used for parallel routes and intercepting routes.
+ *
+ * For a named slot, `<Outlet name="@x" />` is equivalent to
+ * `<ParallelOutlet name="@x" />` — both run the same resolution + wrapping
+ * pipeline. Convention: use bare `<Outlet />` for default content and
+ * `<ParallelOutlet name="@x" />` for named slots.
+ *
+ * @param name - Optional slot name for parallel/intercept content (must start with @)
+ *
+ * @example
+ * ```tsx
+ * function BlogLayout() {
+ *   return (
+ *     <div>
+ *       <h1>Blog</h1>
+ *       <Outlet />
+ *     </div>
+ *   );
+ * }
+ *
+ * // With named slot for modal/parallel content:
+ * function KanbanLayout() {
+ *   return (
+ *     <div>
+ *       <KanbanBoard />
+ *       <Outlet name="@modal" />
+ *       <Outlet />
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function Outlet({ name, fallback, }?: {
+    name?: `@${string}`;
+    fallback?: ReactNode;
+}): ReactNode;
+/**
+ * ParallelOutlet component - renders content for a named parallel slot
+ *
+ * If the parallel segment defines a loading component, the content
+ * is wrapped in Suspense with the loading component as fallback.
+ * This enables streaming and navigation loading states for parallels.
+ *
+ * Equivalent to `<Outlet name="@x" />` for a named slot; ParallelOutlet
+ * requires `name` and is named-slot-only, which reads clearer at the call site.
+ *
+ * @param name - The slot name (must start with @, e.g., "@modal", "@sidebar")
+ *
+ * @example
+ * ```tsx
+ * function DashboardLayout() {
+ *   return (
+ *     <div>
+ *       <h1>Dashboard</h1>
+ *       <ParallelOutlet name="@sidebar" />
+ *       <ParallelOutlet name="@modal" />
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function ParallelOutlet({ name }: {
+    name: `@${string}`;
+}): ReactNode;
+/**
+ * Hook to access outlet content and descendant pending state programmatically.
+ *
+ * Alternative to using <Outlet /> component. Useful when you need
+ * direct access to the outlet content in your logic.
+ *
+ * @example
+ * ```tsx
+ * function BlogLayout() {
+ *   const outlet = useOutlet();
+ *   return <div aria-busy={outlet.pending}><h1>Blog</h1>{outlet.content}</div>;
+ * }
+ * ```
+ */
+export interface OutletState {
+    readonly content: ReactNode;
+    readonly pending: boolean;
+}
+export declare function useOutlet(): OutletState;
+export { useLoader, useFetchLoader, useRefreshLoaders, type LoadFunction, type UseLoaderResult, type UseFetchLoaderResult, type UseLoaderOptions, } from "./use-loader.js";
+export { clientUrls } from "./client-urls/client-urls.js";
+export type { ClientUrlPatterns, ClientUrlRouteRecord, } from "./client-urls/client-urls.js";
+/**
+ * Props for the ErrorBoundary component
+ */
+export interface ErrorBoundaryProps {
+    /** Fallback UI to show when an error is caught */
+    fallback: ReactNode | ((props: ClientErrorBoundaryFallbackProps) => ReactNode);
+    /** Children to render */
+    children: ReactNode;
+    /** Optional callback when an error is caught */
+    onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
+}
+interface ErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+}
+/**
+ * Client-side ErrorBoundary component
+ *
+ * Catches JavaScript errors in child components during rendering,
+ * in lifecycle methods, and in constructors of the whole tree below them.
+ * Displays a fallback UI instead of the component tree that crashed.
+ *
+ * Use this to wrap client components that might throw during hydration
+ * or user interaction. For server-side errors (middleware, loaders, handlers),
+ * use the errorBoundary() helper in route definitions instead.
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { ErrorBoundary } from "rsc-router/client";
+ *
+ * function MyComponent() {
+ *   return (
+ *     <ErrorBoundary fallback={<div>Something went wrong</div>}>
+ *       <ComponentThatMightThrow />
+ *     </ErrorBoundary>
+ *   );
+ * }
+ *
+ * // Or with a function fallback for more control:
+ * function MyComponent() {
+ *   return (
+ *     <ErrorBoundary
+ *       fallback={({ error, reset }) => (
+ *         <div>
+ *           <p>Error: {error.message}</p>
+ *           <button onClick={reset}>Try again</button>
+ *         </div>
+ *       )}
+ *     >
+ *       <ComponentThatMightThrow />
+ *     </ErrorBoundary>
+ *   );
+ * }
+ * ```
+ */
+export declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    constructor(props: ErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void;
+    reset: () => void;
+    render(): ReactNode;
+}
+export { useNavigation } from "./browser/react/use-navigation.js";
+export { useRouter } from "./browser/react/use-router.js";
+export { usePathname } from "./browser/react/use-pathname.js";
+export { useSearchParams } from "./browser/react/use-search-params.js";
+export { useParams } from "./browser/react/use-params.js";
+export { useNonce } from "./browser/react/nonce-context.js";
+export type { RouterInstance, RouterNavigateOptions, ReadonlyURLSearchParams, ActionState, ActionLifecycleState, } from "./browser/types.js";
+export { useAction, type ServerActionFunction, } from "./browser/react/use-action.js";
+export { useSegments, type SegmentsState, } from "./browser/react/use-segments.js";
+export { NavigationProvider, type NavigationProviderProps, } from "./browser/react/NavigationProvider.js";
+export { Link, type LinkProps, type PrefetchStrategy, type StateOrGetter, type LinkState, } from "./browser/react/Link.js";
+export { useLinkStatus, type LinkStatus, } from "./browser/react/use-link-status.js";
+export { ScrollRestoration, useScrollRestoration, type ScrollRestorationProps, } from "./browser/react/ScrollRestoration.js";
+export { type Handle } from "./handle.js";
+export { useHandle } from "./browser/react/use-handle.js";
+export { Meta } from "./handles/meta.js";
+export { MetaTags } from "./handles/MetaTags.js";
+export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
+export { Script, type ScriptConfig, type ScriptAttributes, } from "./handles/script.js";
+export { Scripts } from "./handles/Scripts.js";
+export { Breadcrumbs, type BreadcrumbItem } from "./handles/breadcrumbs.js";
+export { createLocationState, useLocationState, type LocationStateDefinition, type LocationStateEntry, type LocationStateOptions, } from "./browser/react/location-state.js";
+export { href, type PatternToPath } from "./href-client.js";
+export type { ProblemDetails } from "./urls.js";
+export { useMount } from "./browser/react/use-mount.js";
+export { MountContext } from "./browser/react/mount-context.js";
+export { useHref } from "./browser/react/use-href.js";
+export { useReverse } from "./browser/react/use-reverse.js";
+export type { ScopedReverseFunction, LocalReverseFunction } from "./reverse.js";
+export type { LoaderDefinition } from "./types.js";

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

@@ -0,0 +1,41 @@
+/**
+ * RSC-environment version of client exports
+ *
+ * This file is used when importing "rsc-router/client" from RSC (server components).
+ * It re-exports the server's createLoader so that loader definitions work in both
+ * environments with the same import.
+ *
+ * The bundler uses the "react-server" export condition to select this file
+ * in RSC context, while the regular client.tsx is used in client components.
+ */
+export { Outlet, ParallelOutlet, useOutlet, type OutletState, useLoader, ErrorBoundary, type ErrorBoundaryProps, } from "./client.js";
+export { useFetchLoader, useRefreshLoaders, type LoadFunction, type UseLoaderResult, type UseFetchLoaderResult, type UseLoaderOptions, } from "./use-loader.js";
+export { createLoader } from "./route-definition.js";
+export { clientUrls } from "./client-urls/client-urls.js";
+export type { ClientUrlPatterns, ClientUrlRouteRecord, } from "./client-urls/client-urls.js";
+export { useRouter } from "./browser/react/use-router.js";
+export { usePathname } from "./browser/react/use-pathname.js";
+export { useSearchParams } from "./browser/react/use-search-params.js";
+export { useParams } from "./browser/react/use-params.js";
+export { useNonce } from "./browser/react/nonce-context.js";
+export { useMount } from "./browser/react/use-mount.js";
+export { useSegments, type SegmentsState, } from "./browser/react/use-segments.js";
+export { useLinkStatus, type LinkStatus, } from "./browser/react/use-link-status.js";
+export { useScrollRestoration } from "./browser/react/ScrollRestoration.js";
+export { Link, type LinkProps, type PrefetchStrategy, } from "./browser/react/Link.js";
+export { ScrollRestoration, type ScrollRestorationProps, } from "./browser/react/ScrollRestoration.js";
+export { NavigationProvider, type NavigationProviderProps, } from "./browser/react/NavigationProvider.js";
+export { href } from "./href-client.js";
+export { MountContext } from "./browser/react/mount-context.js";
+export { createHandle, isHandle, type Handle } from "./handle.js";
+export { Meta } from "./handles/meta.js";
+export { MetaTags } from "./handles/MetaTags.js";
+export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
+export { Script, type ScriptConfig, type ScriptAttributes, } from "./handles/script.js";
+export { Scripts } from "./handles/Scripts.js";
+export { Breadcrumbs, type BreadcrumbItem } from "./handles/breadcrumbs.js";
+export { createLocationState, type LocationStateDefinition, type LocationStateEntry, type LocationStateOptions, } from "./browser/react/location-state-shared.js";
+export { useHref } from "./browser/react/use-href.js";
+export { useReverse } from "./browser/react/use-reverse.js";
+export { useHandle } from "./browser/react/use-handle.js";
+export { useLocationState } from "./browser/react/location-state.js";

package/dist/types/cloudflare/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Cloudflare preset integration surface for @rangojs/router.
+ *
+ * Imported via `@rangojs/router/cloudflare`. Cloudflare-only helpers live here
+ * so Node/other-platform consumers never pull them in.
+ */
+export { createCloudflareTracing, type CloudflareTracingOptions, } from "./tracing.js";

package/dist/types/cloudflare/tracing.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Cloudflare custom-spans integration.
+ *
+ * Bridges the router's observable phases (request, middleware, action, loaders,
+ * handler, render, ssr, response, background) onto Cloudflare Workers custom
+ * spans so they show up in the trace waterfall and OpenTelemetry exports next
+ * to the platform's automatic spans (KV reads, D1 queries, fetch calls), with
+ * correct nesting.
+ *
+ * Usage (Cloudflare preset only):
+ *
+ *   import { createRouter } from "@rangojs/router";
+ *   import { createCloudflareTracing } from "@rangojs/router/cloudflare";
+ *
+ *   export const router = createRouter({
+ *     tracing: createCloudflareTracing(),
+ *   });
+ *
+ * The runner reads `executionContext.tracing` (the same object as
+ * `import { tracing } from "cloudflare:workers"`) at call time. It is therefore
+ * dependency-free: no `cloudflare:workers` import and no hard dependency on
+ * `@cloudflare/workers-types`, matching the convention in cache/cf. When the
+ * worker is not running on a tracing-enabled Cloudflare runtime — Node, dev
+ * without a tracing destination, an older runtime — `executionContext.tracing`
+ * is undefined and every span call falls through to the work directly, so the
+ * request behaves exactly as if tracing were off. Whether spans are actually
+ * recorded is governed by the `observability`/tracing block in wrangler config.
+ *
+ * Span duration note: enterSpan ends a span when its callback's returned value
+ * (or promise) settles. For the streaming phases (request/render/ssr) that is at
+ * stream CONSTRUCTION, not body-drain; rango.response marks that handoff
+ * boundary explicitly (it wraps only response finalization, never the body).
+ * Instrumentation is best-effort and never wraps or buffers the response body,
+ * so it cannot regress streaming or latency. A loader/Suspense child that
+ * resolves mid-stream therefore keeps a rango.loader span that can extend past
+ * its render parent — overlapping spans are valid. Uses only the typed enterSpan
+ * API; spans bound work up to stream-handoff, matching the co-emitted perf
+ * metric. On deployed Workers a rango.response span may report 0 ms (non-I/O
+ * timers are frozen); its position and attributes are the value.
+ */
+import { type RouterTracingConfig, type TracingToggleOptions } from "../router/tracing.js";
+/**
+ * Options for createCloudflareTracing. Alias of the shared
+ * {@link TracingToggleOptions} (`enabled` master switch + per-phase `spans`
+ * toggles); the name is public API.
+ */
+export type CloudflareTracingOptions = TracingToggleOptions;
+/**
+ * Create the tracing config for a Cloudflare router. Pass the result to
+ * `createRouter({ tracing })`. Spans are emitted for the request, middleware,
+ * action, loaders, handler, render, ssr, response, and background phases; pass
+ * `spans` to turn individual phases off.
+ *
+ * @see createOTelTracing (`@rangojs/router`) for the same slot on any platform
+ *   with an OpenTelemetry SDK.
+ */
+export declare function createCloudflareTracing(options?: CloudflareTracingOptions): RouterTracingConfig;

package/dist/types/component-utils.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Component utilities for RSC
+ *
+ * Helpers for working with React Server Components and client components.
+ */
+import type { ComponentType } from "react";
+/**
+ * Check if a component is a client component (has "use client" directive).
+ *
+ * Client components are marked by the bundler with:
+ * - $$typeof: Symbol.for("react.client.reference")
+ * - $$id: string (module identifier)
+ *
+ * @param component - The component to check
+ * @returns true if the component has client reference marker
+ *
+ * @example
+ * ```typescript
+ * import { MyComponent } from "./my-component"; // has "use client"
+ *
+ * if (!isClientComponent(MyComponent)) {
+ *   throw new Error("MyComponent must be a client component");
+ * }
+ * ```
+ */
+export declare function isClientComponent(component: ComponentType<unknown> | unknown): boolean;
+/**
+ * Assert that a component is a client component.
+ * Throws a descriptive error if not.
+ *
+ * @param component - The component to check
+ * @param name - Name to use in error message (e.g., "document")
+ * @param opts.allowServerInTest - When true AND running under a test runner
+ *   (`isUnderTestRunner()`), relax ONLY the "use client" requirement: a server
+ *   component is accepted. The plugin's "use client" transform does not run in a
+ *   bare unit test, so a real exported `document` (almost every app sets one) has
+ *   no client marker and would otherwise throw at `createRouter`, blocking
+ *   `dispatch`/`assertGeneratedRoutesMatch` against the real router. The document
+ *   reference is irrelevant to those (no Flight render). The "not a JSX element"
+ *   guard still fires, and a real dev/build still throws (mirrors the runtime
+ *   fallback-id gating in handle.ts/loader.ts).
+ * @throws Error if the component is not a client component
+ */
+export declare function assertClientComponent(component: ComponentType<unknown> | unknown, name: string, opts?: {
+    allowServerInTest?: boolean;
+}): asserts component is ComponentType<unknown>;

package/dist/types/components/DefaultDocument.d.ts

@@ -0,0 +1,13 @@
+import type { ReactNode, ReactElement } from "react";
+/**
+ * Default document component that provides a basic HTML structure.
+ * Used when no custom document is provided to createRouter.
+ * Includes MetaTags for automatic charset, viewport, and route meta support,
+ * and Scripts (head + body sites) so the Script handle works out of the box.
+ *
+ * Uses suppressHydrationWarning on <html> because the theme script
+ * may modify class/style attributes before React hydrates.
+ */
+export declare function DefaultDocument({ children, }: {
+    children: ReactNode;
+}): ReactElement;

package/dist/types/context-var.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Typed context variables for ctx.set() / ctx.get().
+ *
+ * createVar<T>() produces a typed token that handlers set and layouts/middleware
+ * read. The token carries a unique Symbol used as the property key on the
+ * per-request variables object — no build-time processing, no IDs.
+ *
+ * @example
+ * ```ts
+ * import { createVar } from "@rangojs/router";
+ *
+ * interface PaginationData { current: number; total: number }
+ * export const Pagination = createVar<PaginationData>();
+ *
+ * // Non-cacheable var — ctx.get(User) throws inside a cache() boundary
+ * export const User = createVar<UserData>({ cache: false });
+ *
+ * // handler
+ * ctx.set(Pagination, { current: 1, total: 4 });
+ *
+ * // layout
+ * const pg = ctx.get(Pagination); // PaginationData | undefined
+ * ```
+ */
+export interface ContextVar<T> {
+    readonly __brand: "context-var";
+    readonly key: symbol;
+    /** When false, ctx.get(var) throws inside a cache() boundary. */
+    readonly cache: boolean;
+    /** Phantom field to carry the type parameter. Never set at runtime. */
+    readonly __type?: T;
+}
+export interface ContextVarOptions {
+    /**
+     * When false, marks this variable as non-cacheable.
+     * Reading this var with ctx.get() inside a cache() boundary throws. Use for
+     * inherently request-specific data (user sessions, auth tokens, etc.) that
+     * must never be baked into cached segments.
+     *
+     * @default true
+     */
+    cache?: boolean;
+}
+/**
+ * Create a typed context variable token.
+ *
+ * The returned object is used with ctx.set(token, value) and ctx.get(token)
+ * for compile-time-checked data flow between handlers, layouts, and middleware.
+ */
+export declare function createVar<T>(options?: ContextVarOptions): ContextVar<T>;
+/**
+ * Type guard: is the value a ContextVar token?
+ */
+export declare function isContextVar(value: unknown): value is ContextVar<unknown>;
+/**
+ * Does a variables object hold any entries? Counts both string keys and the
+ * symbol-keyed entries (context vars are stored under symbols), so an object
+ * carrying only symbol-keyed vars is still reported as non-empty.
+ */
+export declare function hasContextVars(variables: object): boolean;
+/**
+ * Check if a variable value is non-cacheable (either var-level or write-level).
+ */
+export declare function isNonCacheable(variables: any, keyOrVar: string | ContextVar<any>): boolean;
+/**
+ * Read a variable from the variables store.
+ * Accepts either a string key (legacy) or a ContextVar token (typed).
+ */
+export declare function contextGet(variables: any, keyOrVar: string | ContextVar<any>): any;
+export interface ContextSetOptions {
+    /**
+     * When false, marks this specific write as non-cacheable.
+     * "Least cacheable wins" — if either the var definition or this option
+     * says cache: false, the value is non-cacheable.
+     *
+     * @default true (inherits from createVar)
+     */
+    cache?: boolean;
+}
+/**
+ * Write a variable to the variables store.
+ * Accepts either a string key (legacy) or a ContextVar token (typed).
+ */
+export declare function contextSet(variables: any, keyOrVar: string | ContextVar<any>, value: any, options?: ContextSetOptions): void;

package/dist/types/debug.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Debug utilities for manifest inspection and comparison
+ */
+import { type EntryData } from "./server/context";
+/**
+ * Serialized entry for debug output
+ */
+export interface SerializedEntry {
+    id: string;
+    shortCode: string;
+    type: string;
+    parentShortCode: string | null;
+    pattern?: string;
+    hasLoader: boolean;
+    hasMiddleware: boolean;
+    hasErrorBoundary: boolean;
+    parallelCount: number;
+    interceptCount: number;
+}
+/**
+ * Serialized manifest structure
+ */
+export interface SerializedManifest {
+    routes: Record<string, SerializedEntry>;
+    layouts: Record<string, SerializedEntry>;
+    totalRoutes: number;
+    totalLayouts: number;
+}
+/**
+ * Serialize a manifest Map into a JSON-friendly structure
+ */
+export declare function serializeManifest(manifest: Map<string, EntryData>): SerializedManifest;
+/**
+ * Compare two manifests and return differences
+ */
+export declare function compareManifests(oldManifest: SerializedManifest, newManifest: SerializedManifest): {
+    addedRoutes: string[];
+    removedRoutes: string[];
+    changedRoutes: Array<{
+        key: string;
+        field: string;
+        old: any;
+        new: any;
+    }>;
+    addedLayouts: string[];
+    removedLayouts: string[];
+    changedLayouts: Array<{
+        key: string;
+        field: string;
+        old: any;
+        new: any;
+    }>;
+};
+/**
+ * Format manifest diff as a human-readable string
+ */
+export declare function formatManifestDiff(diff: ReturnType<typeof compareManifests>): string;

package/dist/types/decode-loader-results.d.ts

@@ -0,0 +1,42 @@
+import type { ReactNode } from "react";
+/**
+ * Markers for loader-thrown AUTHORITY SIGNALS (notFound()/redirect()) on the
+ * reconstructed read-site error. Siblings of LOADER_ERROR_FALLBACK, routed
+ * differently by StreamedLoaderErrorBoundary: NOT_FOUND renders the
+ * server-rendered not-found UI riding the envelope; REDIRECT triggers a
+ * client replace-navigation to the (server-resolved, same-origin-guarded)
+ * target. Signals are control flow, not failures — they take precedence over
+ * the plain error-fallback path.
+ *
+ * Only decodeLoaderEntry (the read-site path — client components, so the
+ * throw lands in the router-owned boundary; during document SSR, Fizz emits
+ * the Suspense fallback and replays the throw at hydration) throws these.
+ * decodeLoaderResults runs during the SERVER tree build on forceAwait/action
+ * lanes, where a throw would collapse the whole payload — it routes signals
+ * through the errorFallback slot instead (same visual: the slot replaces the
+ * children under OutletProvider).
+ */
+export declare const LOADER_NOT_FOUND_FALLBACK: unique symbol;
+export declare const LOADER_REDIRECT: unique symbol;
+export declare function decodeLoaderResults(resolvedData: any[], loaderIds: string[]): {
+    loaderData: Record<string, any>;
+    errorFallback: ReactNode;
+};
+/**
+ * Marker property carrying the errorBoundary() fallback on a read-site loader
+ * error. decodeLoaderEntry attaches the pre-rendered boundary node (produced
+ * server-side by loader-resolution) to the thrown error; the router-owned
+ * StreamedLoaderErrorBoundary above the readers (segment-system wires it for
+ * every loader-bearing segment) catches by this marker and renders the
+ * fallback — restoring the build-time errorFallback-swap contract for
+ * streamed loaders. Errors without the marker rethrow to the app's boundaries.
+ */
+export declare const LOADER_ERROR_FALLBACK: unique symbol;
+/**
+ * Streaming useLoader: single-entry decode for read-site resolution. Mirrors
+ * decodeLoaderResults for one result. An error entry throws the reconstructed
+ * error (name/stack/code/cause preserved); when the entry carries an
+ * errorBoundary() fallback, the node rides the throw via
+ * LOADER_ERROR_FALLBACK for the boundary above the readers to render.
+ */
+export declare function decodeLoaderEntry(result: any): any;

package/dist/types/default-error-boundary.d.ts

@@ -0,0 +1,10 @@
+import type { ReactNode } from "react";
+import type { ErrorBoundaryFallbackProps } from "./types.js";
+/**
+ * Default error boundary fallback component
+ *
+ * This is rendered when an error occurs and no custom error boundary
+ * is defined in the route tree. Shows a simple "Internal Server Error"
+ * message with the error details in development.
+ */
+export declare function DefaultErrorFallback({ error, }: ErrorBoundaryFallbackProps): ReactNode;

package/dist/types/defer.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Deferred handle values — "decide synchronously, resolve late".
+ *
+ * A handle is pushed from code that holds `ctx` (a route/layout handler), so the
+ * decision to push lands before the handles stream seals. But the value often
+ * isn't known there — it may come from a deep async component far from the
+ * handler. `ctx.use(Handle).defer()` reserves the handle's slot now (synchronous,
+ * so ordering and the pre-seal timing hold) and returns a resolver with the SAME
+ * signature as the push: you call it later, anywhere in the render, with the same
+ * value you would have passed to the push.
+ *
+ *   const breadcrumb = ctx.use(Breadcrumbs);   // (item) => void  &  .defer()
+ *   const resolve = breadcrumb.defer({ timeoutMs: 5000, else: null });
+ *   // deep async component, far from ctx:
+ *   resolve({ label, href, content });          // identical call, just deferred
+ *
+ * Under the hood the reserved slot is a Promise. Handle values are resolved
+ * before any consumer sees them (resolve-by-default: the full render resolves
+ * server-side, navigation resolves client-side before apply), so `useHandle`
+ * receives the resolved value, never the Promise. The hazard that guards against
+ * bugs: a deferred slot whose resolver is never called would keep the render —
+ * and the HTTP response — waiting forever. So a deferred auto-resolves to `else`
+ * after `timeoutMs` (default {@link DEFAULT_DEFER_TIMEOUT_MS}) if the resolver is
+ * never called, degrading gracefully (and warning in dev) instead of hanging.
+ */
+/** Default auto-resolve window. Long enough for genuine deep async work, short
+ *  enough that a forgotten resolve does not hang the response indefinitely. */
+export declare const DEFAULT_DEFER_TIMEOUT_MS = 10000;
+/** Options for `ctx.use(Handle).defer()`. */
+export interface DeferOptions<TData> {
+    /**
+     * Auto-resolve to `else` after this many ms if the resolver is never called,
+     * so a forgotten resolve cannot hold the Flight stream — and thus the HTTP
+     * response — open. Defaults to {@link DEFAULT_DEFER_TIMEOUT_MS}. `0` or
+     * `Infinity` disable the timeout intentionally (not recommended on a request
+     * path). Any other non-finite or negative value is treated as a mistake and
+     * falls back to the default rather than silently disabling the safety net.
+     * Named `timeoutMs` to match the router's `*Ms` duration convention.
+     */
+    timeoutMs?: number;
+    /**
+     * Value the slot resolves to if the timeout fires before the resolver is
+     * called. Defaults to `undefined` (the deferred item is skipped/empty). For
+     * renderable handle content, `null` is the usual graceful fallback, so the
+     * type admits `null` even when `TData` does not.
+     */
+    else?: TData | null;
+}
+/**
+ * The call signature shared by a handle push and the resolver returned by
+ * `.defer()`: a concrete value, a `Promise` of the value (Flight streams it as a
+ * late row), or a thunk returning a `Promise` (called immediately).
+ */
+export type HandlePushFn<TData> = (data: TData | Promise<TData> | (() => Promise<TData>)) => void;
+/**
+ * The push function returned by `ctx.use(Handle)`. Call it to push a value now,
+ * or call `.defer()` to reserve the slot now and resolve the value later (e.g.
+ * from a deep async component) with a timeout safety net.
+ */
+export type HandlePush<TData> = HandlePushFn<TData> & {
+    /**
+     * Reserve this handle's slot synchronously and return a resolver that is
+     * push-equal: it takes the same argument shapes as the push (value, Promise, or
+     * thunk) and behaves identically. Two things the resolver adds over a direct
+     * push: a timeout (if the resolver is never called, the slot auto-resolves to
+     * `options.else` after `options.timeoutMs`; calling the resolver cancels it),
+     * and — on the action/revalidation path only — a thunk it runs does NOT
+     * re-enter the deadlock-guard push-callback scope a direct push thunk gets,
+     * because a deferred resolver fires after the handler phase has closed.
+     *
+     * The reserved slot is resolved before any consumer reads it
+     * (resolve-by-default), so `useHandle` receives the resolved value (or the
+     * `else` fallback on timeout), never a Promise.
+     */
+    defer(options?: DeferOptions<TData>): HandlePushFn<TData>;
+};
+export declare function createDeferred<T>(options?: {
+    timeoutMs?: number;
+    fallback?: T | null;
+}): {
+    promise: Promise<T | null | undefined>;
+    resolve: (value: T | null | undefined) => void;
+};
+/**
+ * Attach `.defer()` to a handle push function. The deferred slot is reserved by
+ * pushing the deferred promise through the same push (so ordering, sealing, and
+ * Flight streaming all reuse the existing path); the returned resolver settles it.
+ */
+export declare function withDefer<TData>(push: HandlePushFn<TData>): HandlePush<TData>;

package/dist/types/deps/browser.d.ts

@@ -0,0 +1 @@
+export { createFromReadableStream, createFromFetch, setServerCallback, encodeReply, createTemporaryReferenceSet, } from "@vitejs/plugin-rsc/browser";

package/dist/types/deps/html-stream-client.d.ts

@@ -0,0 +1 @@
+export { rscStream } from "rsc-html-stream/client";

package/dist/types/deps/html-stream-server.d.ts

@@ -0,0 +1 @@
+export { injectRSCPayload } from "rsc-html-stream/server";

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

@@ -0,0 +1 @@
+export { renderToReadableStream, decodeReply, createTemporaryReferenceSet, loadServerAction, decodeAction, decodeFormState, } from "@vitejs/plugin-rsc/rsc";

package/dist/types/deps/ssr.d.ts

@@ -0,0 +1 @@
+export { createFromReadableStream, setOnClientReference, } from "@vitejs/plugin-rsc/ssr";