@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.1

package/dist/types/cache/vercel/vercel-cache-store.d.ts

@@ -0,0 +1,268 @@
+/**
+ * Vercel Runtime Cache Store
+ *
+ * A SegmentCacheStore backed by Vercel's Runtime Cache (`getCache()` from
+ * `@vercel/functions`). It is the production store analogue to CFCacheStore, but
+ * far smaller: Vercel's Runtime Cache already IS a distributed, tag-aware cache
+ * (regional storage, global tag-expire within ~300ms), so none of CFCacheStore's
+ * L1/L2 tiering, KV tag-marker comparison, marker memoization, or per-tier
+ * timeout budgets are needed here - the platform does that work. What this store
+ * adds on top of the raw primitive is the parts Vercel does NOT give us:
+ *
+ *   1. Stale-while-revalidate. `getCache` has no stale-but-serve: a TTL'd entry
+ *      simply becomes a miss. We store our own {staleAt, expiresAt} envelope and
+ *      set the Vercel ttl to (ttl + swr) so the entry survives its SWR window,
+ *      computing staleness ourselves via the shared cache-policy helpers.
+ *   2. A single-keyspace family split. `getCache` is one flat keyspace, whereas
+ *      the interface has three value families (segments, "use cache" items, full
+ *      responses). The memory store keeps three separate Maps; here they must be
+ *      namespaced by a prefix or a set() of a response would clobber a segment
+ *      cached under the same router key.
+ *   3. The platform guardrails: the 2 MB per-item ceiling (oversized writes
+ *      silently no-op on Vercel, so we skip + report), the per-item tag cap, and
+ *      cross-deploy non-reconciliation (TTL/tag updates are not reconciled across
+ *      deployments - bake a build id into `version` or the getCache namespace).
+ *
+ * Dependency stance: this module imports NOTHING from `@vercel/functions`. The
+ * runtime cache handle (and `waitUntil`) are injected through the constructor and
+ * typed against the local VercelRuntimeCache shape below, exactly as CFCacheStore
+ * takes its `kv`/`ctx` bindings by injection. The consumer passes the real
+ * `getCache(...)` result, which satisfies the shape structurally. That keeps the
+ * router free of a hard Vercel dependency.
+ */
+import type { SegmentCacheStore, CachedEntryData, CacheDefaults, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry } from "../types.js";
+import type { RequestContext } from "../../server/request-context.js";
+/**
+ * Minimal structural shape of the Vercel Runtime Cache returned by `getCache()`
+ * from `@vercel/functions`. Declared locally so @rangojs/router carries no hard
+ * dependency on `@vercel/functions`; the real handle satisfies it structurally.
+ *
+ * @see https://vercel.com/docs/functions/functions-api-reference/vercel-functions-package#getcache
+ */
+export interface VercelRuntimeCache {
+    /** Returns the stored value, or a nullish value on miss. Never throws on miss. */
+    get(key: string): Promise<unknown>;
+    /** Stores a value with optional TTL (seconds), tags, and observability name. */
+    set(key: string, value: unknown, options?: {
+        ttl?: number;
+        tags?: string[];
+        name?: string;
+    }): Promise<void>;
+    /** Removes a value by key. */
+    delete(key: string): Promise<void>;
+    /** Expires every entry tagged with any of `tag`. Global, ~300ms propagation. */
+    expireTag(tag: string | string[]): Promise<void>;
+}
+/**
+ * Vercel Runtime Cache hard per-item ceiling: 2 MB. Writes above this silently
+ * no-op on the platform, so the store measures the serialized envelope and skips
+ * (fail-open) entries at or above this size.
+ */
+export declare const VERCEL_MAX_ITEM_BYTES: number;
+/**
+ * Per-item tag ceiling. Vercel's getCache API reference lists 128 tags per item
+ * (https://vercel.com/docs/functions/functions-api-reference/vercel-functions-package#getcache).
+ * Tags beyond this are dropped with a warning at write time. Does NOT cap
+ * invalidateTags() - an invalidation must reach every requested tag.
+ */
+export declare const VERCEL_MAX_TAGS_PER_ITEM: number;
+/** Max tag length in UTF-8 bytes accepted by Vercel; longer tags are skipped. */
+export declare const VERCEL_MAX_TAG_BYTES: number;
+/** Read-path outcome for the debug sink. */
+export type VercelCacheReadOutcome = "miss" | "fresh" | "stale-revalidate" | "expired" | "corrupt" | "error";
+/** Diagnostic event emitted on every read when `debug` is set. */
+export interface VercelCacheReadDebugEvent {
+    op: "get" | "getItem" | "getResponse" | "getShell";
+    key: string;
+    outcome: VercelCacheReadOutcome;
+    staleAt?: number;
+    expiresAt?: number;
+    shouldRevalidate?: boolean;
+    /** Wall-clock ms spent in the backing cache.get(). */
+    readMs?: number;
+}
+/** `true` logs each read outcome; a function receives the structured event. */
+export type VercelCacheDebug = boolean | ((event: VercelCacheReadDebugEvent) => void);
+/**
+ * Options for VercelCacheStore.
+ */
+export interface VercelCacheStoreOptions<TEnv = unknown> {
+    /**
+     * The Vercel Runtime Cache handle - `getCache()` from `@vercel/functions`.
+     * Required. Construct it with a build-hash namespace to bust stale-shaped
+     * entries across deployments, since Vercel does not reconcile TTL/tags between
+     * deploys:
+     *
+     * ```ts
+     * import { getCache } from "@vercel/functions";
+     * new VercelCacheStore({ cache: getCache({ namespace: BUILD_ID }) });
+     * ```
+     */
+    cache: VercelRuntimeCache;
+    /**
+     * `waitUntil` from `@vercel/functions`. Used only to run the stale-read lock
+     * write (herd dampening) off the response path - the router already
+     * backgrounds the actual writes. When omitted, the lock write runs detached
+     * (fire-and-forget) instead.
+     */
+    waitUntil?: (promise: Promise<unknown>) => void;
+    /**
+     * Default ttl/swr for cache() boundaries when not explicitly specified.
+     */
+    defaults?: CacheDefaults;
+    /**
+     * Custom key generator applied to all cache operations (region/locale/user
+     * segmentation). Receives the request context and the default key.
+     */
+    keyGenerator?: (ctx: RequestContext<TEnv>, defaultKey: string) => string | Promise<string>;
+    /**
+     * Build/version id folded into every stored key as `v/{version}/...`. A second
+     * cross-deploy busting layer in addition to (or instead of) the getCache
+     * namespace. Changing it invalidates everything this store wrote previously.
+     */
+    version?: string;
+    /**
+     * Max serialized entry size in bytes before a write is skipped. Defaults to
+     * VERCEL_MAX_ITEM_BYTES (2 MB - the platform's hard cap).
+     */
+    maxItemBytes?: number;
+    /**
+     * Human-readable label passed as the Vercel `set({ name })` option for
+     * observability in the Vercel dashboard.
+     */
+    name?: string;
+    /**
+     * Read diagnostics. `true` logs each read outcome to the console; a function
+     * receives the structured VercelCacheReadDebugEvent.
+     */
+    debug?: VercelCacheDebug;
+}
+/**
+ * Vercel Runtime Cache-backed segment cache store.
+ *
+ * Suitable for production deployments on Vercel Functions (Node runtime). The
+ * store is best-effort: every read failure degrades to a miss and every write
+ * failure to a no-op (reported, never thrown) - the sole exception is
+ * invalidateTags(), which rejects when the injected cache's expireTag() rejects
+ * so an awaited updateTag() can surface the failure.
+ *
+ * Read-your-own-writes caveat: this honesty is only as strong as the cache
+ * handle. The official `@vercel/functions` cache (`BuildCache.expireTag`)
+ * CATCHES backend failures and resolves, so with the official client a failed
+ * expireTag is invisible here and an awaited updateTag() can report success that
+ * did not happen. Treat tag invalidation on the official Vercel client as
+ * best-effort, not a hard read-your-own-writes guarantee. (A custom cache handle
+ * that propagates expireTag rejections does get the strict guarantee, which is
+ * what the unit suite exercises.)
+ *
+ * Key hashing / family isolation. The store namespaces its three value tiers as
+ * `rg:{s|i|r}:{key}` so segment, `"use cache"`, and response entries occupy
+ * disjoint keyspaces. That separation is only as strong as the cache's
+ * `keyHashFunction`: `getCache`'s default is djb2, which folds every key to 32
+ * bits (8 hex chars), so at a large live-key count a collision can let one
+ * entry's body be served for another key (same-family) or be misread as corrupt
+ * (cross-family). For deployments with many cached keys, pass a wider hash so
+ * the family split is real isolation, e.g. `getCache({ keyHashFunction })` with
+ * a sha256-based function.
+ *
+ * @example
+ * ```ts
+ * import { getCache, waitUntil } from "@vercel/functions";
+ * import { VercelCacheStore } from "@rangojs/router/cache";
+ *
+ * export const router = createRouter({
+ *   cache: () => ({
+ *     store: new VercelCacheStore({
+ *       // `process.env` (not `import.meta.env`, which needs a VITE_ prefix and
+ *       // would be undefined here) so cross-deploy busting via `version` works.
+ *       cache: getCache({ namespace: process.env.VERCEL_DEPLOYMENT_ID }),
+ *       waitUntil,
+ *       defaults: { ttl: 60, swr: 300 },
+ *     }),
+ *   }),
+ * });
+ * ```
+ */
+export declare class VercelCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
+    readonly supportsPassiveShellReads: true;
+    readonly defaults?: CacheDefaults;
+    readonly keyGenerator?: (ctx: RequestContext<TEnv>, defaultKey: string) => string | Promise<string>;
+    private readonly cache;
+    private readonly waitUntil?;
+    private readonly version?;
+    private readonly maxItemBytes;
+    private readonly name?;
+    private readonly debug?;
+    constructor(options: VercelCacheStoreOptions<TEnv>);
+    get(key: string): Promise<CacheGetResult | null>;
+    set(key: string, data: CachedEntryData, ttl: number, swr?: number): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    getResponse(key: string): Promise<{
+        response: Response;
+        shouldRevalidate: boolean;
+    } | null>;
+    putResponse(key: string, response: Response, ttl: number, swr?: number, tags?: string[]): Promise<void>;
+    getItem(key: string): Promise<CacheItemResult | null>;
+    setItem(key: string, value: string, options?: CacheItemOptions): Promise<void>;
+    getShell(key: string, options?: {
+        claimRevalidation?: boolean;
+    }): Promise<{
+        entry: ShellCacheEntry;
+        shouldRevalidate?: boolean;
+    } | null>;
+    putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | void>;
+    /**
+     * Shell tag-generation gate (SegmentCacheStore.isTagsInvalidatedSince).
+     * expireTag() keeps no queryable history, so invalidateTags() writes "tm"
+     * markers for runtime capture races and immutable build shells. Marker >=
+     * generation start wins; read errors fail open like the CF marker check.
+     */
+    isTagsInvalidatedSince(tags: string[], sinceMs: number): Promise<boolean>;
+    invalidateTags(tags: string[]): Promise<void>;
+    private toStoreKey;
+    private write;
+    /**
+     * Normalize a value read back from the cache. Entries written by this store
+     * are pre-serialized JSON strings (see write()); legacy entries (written
+     * before that change, or by a client that deserializes for us) come back as
+     * objects. Parse strings, pass objects through, and treat a non-JSON string
+     * as corrupt (returns undefined, so the caller reports + evicts).
+     */
+    private decodeRaw;
+    /**
+     * Stale-read herd dampening via a tiny companion lock key. On a stale read,
+     * check `{storeKey}:lock`; if absent, claim it (write a short-TTL marker) and
+     * return true so THIS reader triggers revalidation. If present, another
+     * same-region reader already claimed it, so return false and serve the stale
+     * entry as fresh without piling on. Best-effort and non-blocking; never throws.
+     *
+     * Only the STALE path pays the extra lock read; the fresh-hit path takes no
+     * lock round trip. Unlike the prior whole-envelope re-stamp, a stale read now
+     * writes only the tiny lock, never the (potentially large) payload.
+     *
+     * Non-atomic (getCache has no compare-and-set): two readers can both find no
+     * lock and both revalidate. The window is REVALIDATION_LOCK_MS wide, after
+     * which the lock expires and the entry is re-claimed (or a fresh write has
+     * superseded it). A read-compare would not close the race without CAS.
+     */
+    private claimRevalidation;
+    /** Measure a pre-serialized entry against the per-item size cap (see write). */
+    private withinSizeLimit;
+    /**
+     * Drop tags Vercel cannot round-trip: over-length tags, and tags carrying a
+     * URL metacharacter the `@vercel/functions` client does not encode (see
+     * VERCEL_UNSAFE_TAG_CHARS). Runs on BOTH paths - the write path
+     * (clampTagsForWrite) and invalidateTags - so a tag that would silently fail
+     * invalidation is never stored in the first place. `category` reports the
+     * drop under the caller's real operation (write vs invalidate).
+     */
+    private validateTags;
+    /** validateTags + the per-item tag cap. Used on the write path. */
+    private clampTagsForWrite;
+    private safeDelete;
+    private emitDebug;
+    private asSegmentEnvelope;
+    private asItemEnvelope;
+    private asShellEnvelope;
+    private asResponseEnvelope;
+}

package/dist/types/client.d.ts

@@ -0,0 +1,184 @@
+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 }?: {
+    name?: `@${string}`;
+}): 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 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><h1>Blog</h1>{outlet}</div>;
+ * }
+ * ```
+ */
+export declare function useOutlet(): ReactNode;
+export { useLoader, useFetchLoader, useRefreshLoaders, type LoadFunction, type UseLoaderResult, type UseFetchLoaderResult, type UseLoaderOptions, } from "./use-loader.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,39 @@
+/**
+ * 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, 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 { 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,53 @@
+/**
+ * Cloudflare custom-spans integration.
+ *
+ * Bridges the router's performance phases (request, middleware, action,
+ * loaders, handler, render, ssr) 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. 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.
+ */
+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, and ssr 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;