@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.1

package/dist/types/browser/react/use-mount.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Returns the current include() mount path.
+ *
+ * Inside `include("/articles", blogPatterns)`, returns "/articles".
+ * For nested includes, returns the nearest mount path.
+ * At root level (no include), returns "/".
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { useMount, href } from "@rangojs/router/client";
+ *
+ * function BlogNav({ slug }: { slug: string }) {
+ *   const mount = useMount(); // "/articles"
+ *   return (
+ *     <>
+ *       <Link to={href("/", mount)}>Blog Home</Link>
+ *       <Link to={href(`/${slug}`, mount)}>Post</Link>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export declare function useMount(): string;

package/dist/types/browser/react/use-navigation.d.ts

@@ -0,0 +1,15 @@
+import type { PublicNavigationState } from "../types.js";
+/**
+ * Hook to access reactive navigation state with optional selector for performance.
+ *
+ * Returns state only. For actions (push, replace, refresh, prefetch),
+ * use useRouter() instead.
+ *
+ * @example
+ * ```tsx
+ * const { state, location } = useNavigation();
+ * const isLoading = useNavigation(nav => nav.state === 'loading');
+ * ```
+ */
+export declare function useNavigation(): PublicNavigationState;
+export declare function useNavigation<T>(selector: (state: PublicNavigationState) => T): T;

package/dist/types/browser/react/use-params.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Hook to access the current route params.
+ *
+ * Returns the merged route params from the matched route.
+ * Updates when navigation completes, not during pending navigation.
+ *
+ * @example
+ * ```tsx
+ * // Route: /products/:productId
+ * const params = useParams();
+ * // { productId: "123" }
+ *
+ * // Annotate the expected shape via a generic
+ * const { productId } = useParams<{ productId: string }>();
+ *
+ * // With selector
+ * const productId = useParams(p => p.productId);
+ * ```
+ */
+export declare function useParams<T extends object = Record<string, string | undefined>>(): Readonly<T>;
+export declare function useParams<T>(selector: (params: Record<string, string | undefined>) => T): T;

package/dist/types/browser/react/use-pathname.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Hook to access the current pathname.
+ *
+ * Returns the committed pathname string (excludes search params and hash).
+ * Updates when navigation completes, not during pending navigation.
+ *
+ * @example
+ * ```tsx
+ * const pathname = usePathname();
+ * // "/products/123"
+ * ```
+ */
+export declare function usePathname(): string;

package/dist/types/browser/react/use-reverse.d.ts

@@ -0,0 +1,40 @@
+import type { LocalReverseFunction } from "../../reverse.js";
+type RouteEntry = string | {
+    readonly path: string;
+};
+type LocalRouteMap = Readonly<Record<string, RouteEntry>>;
+/**
+ * Mount-aware reverse function for a locally-imported `routes` map.
+ *
+ * The `routes` map you pass IS the scope: `reverse("name")` looks the name up
+ * in that map (verbatim), prefixes the result with the surrounding `include()`
+ * mount path via `useMount()`, and substitutes params — auto-filling from the
+ * current matched route's params, with explicit params overriding. A module's
+ * components can therefore reverse their own routes without knowing where the
+ * module is mounted: include it under any prefix and the URLs resolve correctly.
+ *
+ * The leading dot is optional and cosmetic: `reverse("post")` and
+ * `reverse(".post")` resolve identically. The dot exists only as a readability
+ * convention and for parity with `ctx.reverse(".name")` on the server; here the
+ * passed map is the scope, so there is no separate global namespace to
+ * disambiguate and the dot carries no meaning.
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ * import { Link, useReverse } from "@rangojs/router/client";
+ * import { routes as blogRoutes } from "../urls/blog.gen.js";
+ *
+ * function BlogNav() {
+ *   const reverse = useReverse(blogRoutes);
+ *   return (
+ *     <>
+ *       <Link to={reverse("index")}>Blog</Link>
+ *       <Link to={reverse("post", { postId: "hello" })}>Post</Link>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export declare function useReverse<const TRoutes extends LocalRouteMap>(routes: TRoutes): LocalReverseFunction<TRoutes>;
+export {};

package/dist/types/browser/react/use-router.d.ts

@@ -0,0 +1,23 @@
+import type { RouterInstance } from "../types.js";
+/**
+ * Hook to access router actions (push, replace, refresh, prefetch, back, forward).
+ *
+ * Returns a STABLE reference that never changes, so components using
+ * useRouter() do not re-render on navigation state changes.
+ * For reactive navigation state, use useNavigation() instead.
+ *
+ * Methods read `basename` from the context on each call. It is set once from
+ * the initial payload and is stable within a session — a cross-app navigation
+ * is a full document load (X-RSC-Reload), so the target app mounts fresh with
+ * its own basename.
+ *
+ * @example
+ * ```tsx
+ * const router = useRouter();
+ * router.push("/products");
+ * router.replace("/login", { scroll: false });
+ * router.prefetch("/dashboard");
+ * router.back();
+ * ```
+ */
+export declare function useRouter(): RouterInstance;

package/dist/types/browser/react/use-search-params.d.ts

@@ -0,0 +1,19 @@
+import type { ReadonlyURLSearchParams } from "../types.js";
+/**
+ * Hook to access the current URL search params.
+ *
+ * Returns a read-only URLSearchParams object from the committed location.
+ * Updates when navigation completes, not during pending navigation.
+ *
+ * Note: During SSR the search params are not available (the server only sends
+ * the pathname). The hook returns empty params during SSR and syncs from
+ * the browser URL on mount.
+ *
+ * @example
+ * ```tsx
+ * const searchParams = useSearchParams();
+ * const query = searchParams.get("q"); // "react"
+ * const page = searchParams.get("page"); // "2"
+ * ```
+ */
+export declare function useSearchParams(): ReadonlyURLSearchParams;

package/dist/types/browser/react/use-segments.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Segments state returned by useSegments hook
+ */
+export interface SegmentsState {
+    /** URL path segments (e.g., /shop/products/123 → ["shop", "products", "123"]) */
+    path: readonly string[];
+    /** Matched segment IDs in order (layouts and routes only, e.g., ["L0", "L0L1", "L0L1R0"]) */
+    segmentIds: readonly string[];
+    /** Current URL location */
+    location: URL;
+}
+/**
+ * Hook to access current route segments with optional selector for performance
+ *
+ * Provides information about the current URL path and matched route segments.
+ * Uses the event controller for reactive state management.
+ *
+ * @example
+ * ```tsx
+ * // Get full segments state
+ * const { path, segmentIds, location } = useSegments();
+ *
+ * // Use selector for specific values (better performance)
+ * const path = useSegments(s => s.path);
+ * const isShopRoute = useSegments(s => s.path[0] === "shop");
+ * ```
+ */
+export declare function useSegments(): SegmentsState;
+export declare function useSegments<T>(selector: (state: SegmentsState) => T): T;

package/dist/types/browser/response-adapter.d.ts

@@ -0,0 +1,58 @@
+type HeaderResult = {
+    url: string;
+} | "blocked" | null;
+/**
+ * Extract and validate an RSC response header URL (X-RSC-Reload, X-RSC-Redirect).
+ * Returns { url } if valid, "blocked" if present but invalid origin, null if absent.
+ */
+export declare function extractRscHeaderUrl(response: Response, header: string): HeaderResult;
+/**
+ * Empty 200 response that won't choke Flight parsing.
+ * Used when a header URL is blocked by origin validation.
+ */
+export declare function emptyResponse(): Response;
+/**
+ * Whether an RSC content response carries a server-stamped router identity
+ * (`X-RSC-Router-Id`) that DIFFERS from the id this client expects (its own
+ * routerId, also sent as `_rsc_rid`). Pre-decode integrity check: lets a caller
+ * refuse a foreign app's payload before `createFromFetch` imports its chunks.
+ *
+ * True ONLY when both the header and the expected id are present and differ. An
+ * absent header (control-only reload/redirect responses are not stamped) or an
+ * absent expected id (e.g. before the client is seeded) is a pass-through —
+ * never a false reject.
+ */
+export declare function isForeignRouterId(response: Response, expectedId: string | undefined): boolean;
+/**
+ * Handle the X-RSC-Reload control header (server requests a full page reload on
+ * a version mismatch). Returns a short-circuit response when the header is
+ * present -- emptyResponse() if the URL was blocked by origin validation, or a
+ * never-resolving promise while the page reloads -- and null when absent, so
+ * the caller continues processing (e.g. the X-RSC-Redirect check). Scoped to
+ * X-RSC-Reload only; redirect handling differs between callers.
+ */
+export declare function handleReloadHeader(response: Response, opts: {
+    onBlocked: () => void;
+    onReload: (url: string) => void;
+}): Response | Promise<Response> | null;
+/**
+ * Tee a response body for RSC parsing and stream completion tracking.
+ * Returns a new Response with one branch; the other is consumed to detect
+ * end-of-stream, calling onComplete when done.
+ *
+ * `onComplete` receives `endedCleanly`: true only on a normal EOF drain, false
+ * on a read error or an abort (the signal cancelled the reader). Callers that
+ * gate a "fully complete" fast path (e.g. prefetch's `entry.complete`) must
+ * treat a non-clean end as incomplete — a broken stream is not complete data.
+ *
+ * If the response has no body, onComplete fires synchronously with `true`
+ * (an empty body is a clean, complete stream).
+ * If signal is provided, an abort cancels the tracking reader.
+ *
+ * `silent` suppresses the stream-error log. Prefetch passes it: a speculative,
+ * low-priority prefetch that is aborted or never consumed can error its stream
+ * benignly, which is not worth surfacing. The fresh-navigation path keeps the
+ * log (default), where a stream error reflects a real failed navigation.
+ */
+export declare function teeWithCompletion(response: Response, onComplete: (endedCleanly: boolean) => void, signal?: AbortSignal, silent?: boolean): Response;
+export {};

package/dist/types/browser/rsc-router.d.ts

@@ -0,0 +1,141 @@
+import React from "react";
+import type { RscPayload, RscBrowserDependencies, NavigationStore, NavigationBridge } from "./types.js";
+import type { EventController } from "./event-controller.js";
+import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
+/**
+ * Options for initializing the browser app
+ */
+export interface InitBrowserAppOptions {
+    /**
+     * RSC stream containing the initial payload (from rsc-html-stream/client)
+     */
+    rscStream: ReadableStream<Uint8Array>;
+    /**
+     * RSC browser dependencies from @vitejs/plugin-rsc/browser
+     */
+    deps: RscBrowserDependencies;
+    /**
+     * Optional store configuration
+     */
+    storeOptions?: {
+        /**
+         * Maximum number of history entries to cache
+         * @default 10
+         */
+        cacheSize?: number;
+    };
+    /**
+     * Enable global link interception for SPA navigation.
+     * When enabled, clicks on same-origin anchor elements are intercepted
+     * and handled via client-side navigation instead of full page loads.
+     *
+     * Links rendered with the Link component handle their own navigation
+     * regardless of this setting.
+     *
+     * Set to false to disable global interception and rely solely on
+     * Link components for SPA navigation.
+     *
+     * @default true
+     */
+    linkInterception?: boolean;
+    /**
+     * Theme configuration from router.
+     * When provided, enables theme support via useTheme hook.
+     * Pass router.themeConfig here to enable theme features.
+     *
+     * @example
+     * ```tsx
+     * import { router } from "./router.js";
+     *
+     * await initBrowserApp({
+     *   rscStream,
+     *   deps: rscBrowser,
+     *   themeConfig: router.themeConfig,
+     *   initialTheme: document.documentElement.className.includes("dark") ? "dark" : "light",
+     * });
+     * ```
+     */
+    themeConfig?: ResolvedThemeConfig | null;
+    /**
+     * Initial theme from server (typically read from cookie).
+     * Only used when themeConfig is provided.
+     */
+    initialTheme?: Theme;
+}
+/**
+ * Result from initializing the browser app
+ */
+export interface BrowserAppContext {
+    store: NavigationStore;
+    eventController: EventController;
+    bridge: NavigationBridge;
+    initialPayload: RscPayload;
+    initialTree: React.ReactNode | Promise<React.ReactNode>;
+    /** Theme configuration (null if theme not enabled) */
+    themeConfig?: ResolvedThemeConfig | null;
+    /** Initial theme from server */
+    initialTheme?: Theme;
+    /** Whether connection warmup is enabled */
+    warmupEnabled?: boolean;
+    /** Whether the hydrated tree should be wrapped in React.StrictMode */
+    strictMode?: boolean;
+    /** App version for prefetch version mismatch detection */
+    version?: string;
+    /**
+     * App-shell ref, read through on each render so renderSegments and the
+     * NavigationProvider see rootLayout/basename/version without closing over a
+     * stale snapshot. Set once from the initial payload and not swapped within a
+     * session: a cross-app navigation is a full document load (X-RSC-Reload), so
+     * the target app establishes its own shell on load. Theme, warmup, and
+     * prefetch TTL are document-lifetime too (see AppShell).
+     */
+    appShellRef?: import("./app-shell.js").AppShellRef;
+}
+/**
+ * Initialize the browser app. Must be called before rendering Rango.
+ *
+ * This function:
+ * - Loads the initial RSC payload from the stream
+ * - Creates the navigation store and event controller
+ * - Sets up action and navigation bridges
+ * - Configures HMR support
+ */
+export declare function initBrowserApp(options: InitBrowserAppOptions): Promise<BrowserAppContext>;
+/**
+ * Get the browser app context. Throws if initBrowserApp hasn't been called.
+ */
+export declare function getBrowserAppContext(): BrowserAppContext;
+/**
+ * Reset the browser app context (for testing)
+ */
+export declare function resetBrowserAppContext(): void;
+/**
+ * Props for the Rango component
+ */
+export interface RangoProps {
+}
+/**
+ * Rango component - renders the RSC router with all internal wiring.
+ *
+ * Must be called after initBrowserApp() has completed.
+ *
+ * @example
+ * ```tsx
+ * import { initBrowserApp, Rango } from "rsc-router/browser";
+ * import { rscStream } from "rsc-html-stream/client";
+ * import * as rscBrowser from "@vitejs/plugin-rsc/browser";
+ *
+ * async function main() {
+ *   await initBrowserApp({ rscStream, deps: rscBrowser });
+ *
+ *   hydrateRoot(
+ *     document,
+ *     <React.StrictMode>
+ *       <Rango />
+ *     </React.StrictMode>
+ *   );
+ * }
+ * main();
+ * ```
+ */
+export declare function Rango(_props: RangoProps): React.ReactElement;

package/dist/types/browser/scroll-restoration.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Scroll Restoration Module
+ *
+ * Provides scroll position persistence across navigations, following React Router v7 patterns:
+ * - Saves scroll positions to sessionStorage keyed by unique history entry key
+ * - Restores scroll on back/forward navigation
+ * - Scrolls to top on new navigation (unless scroll: false)
+ * - Supports hash link scrolling
+ */
+/**
+ * Custom getKey function for determining scroll restoration key
+ */
+type GetScrollKeyFunction = (location: {
+    pathname: string;
+    search: string;
+    hash: string;
+    key: string;
+}) => string;
+/**
+ * Generate a unique key for the current history entry.
+ * Uses history.state.key if available, otherwise generates and stores a new one.
+ */
+export declare function getHistoryStateKey(): string;
+/**
+ * Get the scroll restoration key for a location.
+ * Uses custom getKey function if set, otherwise uses history state key.
+ */
+export declare function getScrollKey(): string;
+/**
+ * Initialize scroll restoration.
+ * Sets manual scroll restoration mode and loads saved positions from sessionStorage.
+ */
+export declare function initScrollRestoration(options?: {
+    getKey?: GetScrollKeyFunction;
+}): () => void;
+/**
+ * Save the current scroll position for the current history entry.
+ * Maintains bounded size by evicting oldest entries when the limit is exceeded.
+ */
+export declare function saveCurrentScrollPosition(): void;
+/**
+ * Persist scroll positions to sessionStorage.
+ * If the write fails (typically QuotaExceededError), evict the oldest ~1/4 of
+ * entries ONCE and retry the write a single time; if that still fails, remove
+ * our storage key entirely so we don't block other sessionStorage consumers.
+ * This is a single evict-then-retry-then-clear ladder, not a loop.
+ *
+ * Exported so that single eviction/retry/clear ladder is unit-testable directly.
+ * The browser drives it from the `pagehide` handler.
+ */
+export declare function persistToSessionStorage(): void;
+/**
+ * Get the saved scroll position for a history key
+ */
+export declare function getSavedScrollPosition(key?: string): number | undefined;
+/**
+ * Cancel any pending scroll restoration polling
+ */
+export declare function cancelScrollRestorationPolling(): void;
+/**
+ * Restore scroll position for the current history entry.
+ * Returns true if position was fully restored, false otherwise.
+ *
+ * @param options.retryIfStreaming - If true, poll while streaming until we can scroll to target
+ * @param options.isStreaming - Function to check if streaming is in progress
+ */
+export declare function restoreScrollPosition(options?: {
+    retryIfStreaming?: boolean;
+    isStreaming?: () => boolean;
+}): boolean;
+/**
+ * Handle hash link scrolling.
+ * Scrolls to element with matching ID if hash is present.
+ * Returns true if scrolled to element, false otherwise.
+ */
+export declare function scrollToHash(): boolean;
+/**
+ * Scroll to top of page
+ */
+export declare function scrollToTop(): void;
+/**
+ * Handle scroll for a new navigation.
+ * - Saves current position before navigating
+ * - Ensures new history entry has a key
+ */
+export declare function handleNavigationStart(): void;
+/**
+ * Handle scroll after navigation completes.
+ * @param options.restore - If true, restore saved position (for popstate)
+ * @param options.scroll - If false, don't scroll at all
+ * @param options.isStreaming - Function to check if streaming is in progress (for retry logic)
+ */
+export declare function handleNavigationEnd(options: {
+    restore?: boolean;
+    scroll?: boolean;
+    isStreaming?: () => boolean;
+}): void;
+/**
+ * Update the history state key after pushState/replaceState.
+ * Call this after changing history to ensure new entry has a key.
+ */
+export declare function ensureHistoryKey(): void;
+export {};

package/dist/types/browser/segment-reconciler.d.ts

@@ -0,0 +1,74 @@
+import type { ResolvedSegment } from "./types.js";
+/**
+ * Determines the merging behavior for segment reconciliation.
+ *
+ * - 'action': From server-action-bridge's own merge. Always merges loaders,
+ *   always preserves cached loading (even undefined), never clears cached
+ *   segment loading.
+ * - 'navigation': From partial-update during normal navigation. Does NOT merge
+ *   loaders, preserves cached loading only when defined, clears truthy loading
+ *   on cached segments not in server diff.
+ * - 'stale-revalidation': From partial-update during stale revalidation or
+ *   action-triggered refetch. Merges loaders, always preserves cached loading
+ *   (same as action), clears truthy loading on cached segments not in server diff.
+ */
+export type ReconcileActor = "navigation" | "action" | "stale-revalidation";
+export interface ReconcileInput {
+    actor: ReconcileActor;
+    /** All segment IDs the server expects the client to have (matched array) */
+    matched: string[];
+    /** Segment IDs that changed (diff array) */
+    diff: string[];
+    /** Segments returned from server (raw array, keyed internally by ID) */
+    serverSegments: ResolvedSegment[];
+    /** Cached segments from current page (raw array, keyed internally by ID) */
+    cachedSegments: ResolvedSegment[];
+    /** When true, diff segments not in matched are inserted after their parent
+     *  layout. Used during navigation when consolidation fetch returns loader
+     *  segments that aren't in the matched array. */
+    insertMissingDiff?: boolean;
+}
+export interface ReconcileResult {
+    /** All merged segments in matched order (for caching and committing) */
+    segments: ResolvedSegment[];
+    /** Main segments excluding intercepts (for rendering) */
+    mainSegments: ResolvedSegment[];
+    /** Intercept segments only (passed via render options) */
+    interceptSegments: ResolvedSegment[];
+}
+/**
+ * Single source of truth for merging server segments with cached segments.
+ *
+ * Replaces the duplicated merge loops in server-action-bridge.ts and
+ * partial-update.ts. The actor parameter controls the subtle behavioral
+ * differences between action and navigation merging:
+ *
+ * Loading preservation:
+ * - action/stale-revalidation: Always preserves cached loading value when it
+ *   differs from server (even when cached is undefined). This prevents tree
+ *   structure changes that would remount components and destroy useActionState
+ *   during action revalidation or action-triggered refetch.
+ * - navigation: Preserves cached loading only when the cached value is defined
+ *   (not undefined). When cached is undefined, lets server value through
+ *   because we're building a new tree.
+ *
+ * Loader merging:
+ * - action/stale-revalidation: Merges partial loader data when server returns
+ *   fewer loaders than cached (revalidation only updated some loaders).
+ * - navigation: Does not merge (full navigation fetches complete data).
+ *
+ * Cached segment handling (segments in matched but not in server response):
+ * - action: Returns cached segment as-is (preserve tree structure).
+ * - navigation/stale-revalidation: Clears truthy loading to undefined
+ *   (prevents showing stale skeletons), but preserves loading=false
+ *   (suppressed boundary is structural).
+ */
+export declare function reconcileSegments(input: ReconcileInput): ReconcileResult;
+/**
+ * Reconcile error segments with cached segments.
+ *
+ * For error responses, the server returns the error boundary segment.
+ * This function overlays error segments onto the full cached tree,
+ * preserving sibling layouts that aren't in the error parent chain.
+ */
+export declare function reconcileErrorSegments(cachedSegments: ResolvedSegment[], errorSegments: ResolvedSegment[]): ReconcileResult;

package/dist/types/browser/segment-structure-assert.d.ts

@@ -0,0 +1,16 @@
+import type { ResolvedSegment } from "./types.js";
+/**
+ * Assert that merging a server segment with a cached segment won't change
+ * the React tree structure. Logs a warning in development when a mismatch
+ * is detected.
+ *
+ * This catches the class of bugs where `loading()` with `{ ssr: false }`
+ * produces `loading=false` on SSR but `loading=<skeleton>` on actions,
+ * causing React to remount LoaderBoundary/RouteContentWrapper and destroy
+ * client state (useActionState, refs, etc.).
+ *
+ * @param cached - The currently cached segment
+ * @param incoming - The new segment from server
+ * @param context - Where this merge is happening (for the warning message)
+ */
+export declare function assertSegmentStructure(cached: ResolvedSegment, incoming: ResolvedSegment, context: string): void;

package/dist/types/browser/server-action-bridge.d.ts

@@ -0,0 +1,29 @@
+import type { ServerActionBridge, ServerActionBridgeConfig } from "./types.js";
+import type { EventController } from "./event-controller.js";
+/**
+ * Extended configuration for server action bridge with event controller
+ */
+export interface ServerActionBridgeConfigWithController extends ServerActionBridgeConfig {
+    eventController: EventController;
+    /** Callback to trigger SPA navigation (for action redirects) */
+    onNavigate?: (url: string, options?: {
+        state?: unknown;
+        replace?: boolean;
+        _skipCache?: boolean;
+    }) => Promise<void>;
+}
+/**
+ * Create a server action bridge for handling RSC server actions
+ *
+ * The bridge registers a callback with the RSC runtime that handles:
+ * - Encoding action arguments
+ * - Sending action requests to the server
+ * - Processing responses and updating UI
+ * - Managing concurrent action requests via event controller
+ * - HMR resilience (refetching if segments are missing)
+ *
+ * @param config - Bridge configuration
+ * @returns ServerActionBridge instance
+ */
+export declare function createServerActionBridge(config: ServerActionBridgeConfigWithController): ServerActionBridge;
+export { createServerActionBridge as default };