@rangojs/router 0.5.1 → 0.6.0

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

@@ -1,141 +0,0 @@
-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.backup/browser/scroll-restoration.d.ts

@@ -1,103 +0,0 @@
-/**
- * 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.backup/browser/segment-reconciler.d.ts

@@ -1,74 +0,0 @@
-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.backup/browser/segment-structure-assert.d.ts

@@ -1,16 +0,0 @@
-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.backup/browser/server-action-bridge.d.ts

@@ -1,29 +0,0 @@
-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 };