@rangojs/router 0.4.0 → 0.4.2

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

@@ -0,0 +1,93 @@
+/**
+ * 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;
+/**
+ * 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 {};
+//# sourceMappingURL=scroll-restoration.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-restoration.d.ts","sourceRoot":"","sources":["../../src/browser/scroll-restoration.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA2CH;;GAEG;AACH,KAAK,oBAAoB,GAAG,CAC1B,QAAQ,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,KACtE,MAAM,CAAC;AAIZ;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAU3C;AAED;;;GAGG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAWrC;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE;IAC9C,MAAM,CAAC,EAAE,oBAAoB,CAAC;CAC/B,GAAG,MAAM,IAAI,CAgDb;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAkBhD;AA0CD;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGvE;AAOD;;GAEG;AACH,wBAAgB,8BAA8B,IAAI,IAAI,CAKrD;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE;IAC9C,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC;CAC7B,GAAG,OAAO,CAuDV;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAiBtC;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAElC;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAG5C;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE;IAC3C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC;CAC7B,GAAG,IAAI,CA2BP;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC"}

package/dist/browser/scroll-restoration.js

@@ -0,0 +1,321 @@
+/**
+ * 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
+ */
+const SCROLL_STORAGE_KEY = "rsc-router-scroll-positions";
+/**
+ * Maximum number of scroll position entries to retain.
+ * When exceeded, the oldest entries (by insertion order) are evicted.
+ * 200 entries is well within sessionStorage limits while covering
+ * realistic back/forward navigation depth.
+ */
+const MAX_SCROLL_ENTRIES = 200;
+/**
+ * Interval for polling scroll restoration during streaming (ms).
+ * If content is still loading and we can't scroll to saved position,
+ * keep trying at this interval.
+ */
+const SCROLL_POLL_INTERVAL_MS = 50;
+/**
+ * Maximum time to keep polling for scroll restoration (ms).
+ * After this timeout, stop trying even if streaming continues.
+ */
+const SCROLL_POLL_TIMEOUT_MS = 5000;
+/**
+ * In-memory cache of scroll positions.
+ * Synced with sessionStorage on pagehide.
+ */
+let savedScrollPositions = {};
+/**
+ * Tracks insertion order of scroll position keys for LRU eviction.
+ * Most recent entries are at the end of the array.
+ * When a key is updated, it is moved to the end.
+ */
+let scrollKeyOrder = [];
+/**
+ * Whether scroll restoration has been initialized
+ */
+let initialized = false;
+let customGetKey = null;
+/**
+ * Generate a unique key for the current history entry.
+ * Uses history.state.key if available, otherwise generates and stores a new one.
+ */
+export function getHistoryStateKey() {
+    const state = window.history.state;
+    if (state?.key) {
+        return state.key;
+    }
+    // Generate a new key and store it in history.state
+    const key = Math.random().toString(36).slice(2, 10);
+    window.history.replaceState({ ...state, key }, "");
+    return key;
+}
+/**
+ * Get the scroll restoration key for a location.
+ * Uses custom getKey function if set, otherwise uses history state key.
+ */
+export function getScrollKey() {
+    if (customGetKey) {
+        const loc = window.location;
+        return customGetKey({
+            pathname: loc.pathname,
+            search: loc.search,
+            hash: loc.hash,
+            key: getHistoryStateKey(),
+        });
+    }
+    return getHistoryStateKey();
+}
+/**
+ * Initialize scroll restoration.
+ * Sets manual scroll restoration mode and loads saved positions from sessionStorage.
+ */
+export function initScrollRestoration(options) {
+    if (initialized) {
+        console.warn("[Scroll] Already initialized");
+        return () => { };
+    }
+    initialized = true;
+    customGetKey = options?.getKey ?? null;
+    // Set manual scroll restoration to prevent browser's default behavior
+    window.history.scrollRestoration = "manual";
+    // Load saved positions from sessionStorage
+    try {
+        const stored = sessionStorage.getItem(SCROLL_STORAGE_KEY);
+        if (stored) {
+            savedScrollPositions = JSON.parse(stored);
+            // Rebuild key order from loaded positions.
+            // Exact original order is lost across page loads, but this is
+            // acceptable -- the important invariant is bounded size.
+            scrollKeyOrder = Object.keys(savedScrollPositions);
+        }
+    }
+    catch (e) {
+        // Ignore parse errors, start with empty state
+    }
+    // Ensure current history entry has a key
+    getHistoryStateKey();
+    // Save scroll positions on pagehide (before leaving/refreshing)
+    const handlePageHide = () => {
+        saveCurrentScrollPosition();
+        persistToSessionStorage();
+        // Reset to auto for browser to handle if page is restored from bfcache
+        window.history.scrollRestoration = "auto";
+    };
+    window.addEventListener("pagehide", handlePageHide);
+    console.log("[Scroll] Initialized, loaded positions:", Object.keys(savedScrollPositions).length);
+    return () => {
+        window.removeEventListener("pagehide", handlePageHide);
+        window.history.scrollRestoration = "auto";
+        initialized = false;
+        savedScrollPositions = {};
+        scrollKeyOrder = [];
+    };
+}
+/**
+ * Save the current scroll position for the current history entry.
+ * Maintains bounded size by evicting oldest entries when the limit is exceeded.
+ */
+export function saveCurrentScrollPosition() {
+    const key = getScrollKey();
+    // If this key already exists, remove it from its current position
+    // in the order array so it can be re-appended at the end (most recent).
+    const existingIndex = scrollKeyOrder.indexOf(key);
+    if (existingIndex !== -1) {
+        scrollKeyOrder.splice(existingIndex, 1);
+    }
+    savedScrollPositions[key] = window.scrollY;
+    scrollKeyOrder.push(key);
+    // Evict oldest entries if we exceed the limit
+    while (scrollKeyOrder.length > MAX_SCROLL_ENTRIES) {
+        const oldestKey = scrollKeyOrder.shift();
+        delete savedScrollPositions[oldestKey];
+    }
+}
+/**
+ * Persist scroll positions to sessionStorage.
+ * If the write fails due to quota exceeded, progressively evict the oldest
+ * entries and retry until it succeeds or the store is empty.
+ */
+function persistToSessionStorage() {
+    try {
+        sessionStorage.setItem(SCROLL_STORAGE_KEY, JSON.stringify(savedScrollPositions));
+    }
+    catch (e) {
+        // Likely QuotaExceededError. Evict oldest entries and retry.
+        const evictCount = Math.max(1, Math.floor(scrollKeyOrder.length / 4));
+        for (let i = 0; i < evictCount && scrollKeyOrder.length > 0; i++) {
+            const oldestKey = scrollKeyOrder.shift();
+            delete savedScrollPositions[oldestKey];
+        }
+        try {
+            sessionStorage.setItem(SCROLL_STORAGE_KEY, JSON.stringify(savedScrollPositions));
+        }
+        catch (retryErr) {
+            // Storage still full after eviction. Clear our key entirely so we
+            // don't block other sessionStorage consumers.
+            console.warn("[Scroll] Failed to persist to sessionStorage after eviction, clearing scroll data:", retryErr);
+            try {
+                sessionStorage.removeItem(SCROLL_STORAGE_KEY);
+            }
+            catch {
+                // Nothing more we can do
+            }
+        }
+    }
+}
+/**
+ * Get the saved scroll position for a history key
+ */
+export function getSavedScrollPosition(key) {
+    const lookupKey = key ?? getScrollKey();
+    return savedScrollPositions[lookupKey];
+}
+/**
+ * Pending poll interval for scroll restoration during streaming
+ */
+let pendingPollInterval = null;
+/**
+ * Cancel any pending scroll restoration polling
+ */
+export function cancelScrollRestorationPolling() {
+    if (pendingPollInterval) {
+        clearInterval(pendingPollInterval);
+        pendingPollInterval = null;
+    }
+}
+/**
+ * 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 function restoreScrollPosition(options) {
+    // Clear any pending polling
+    cancelScrollRestorationPolling();
+    const key = getScrollKey();
+    const savedY = savedScrollPositions[key];
+    if (typeof savedY !== "number") {
+        return false;
+    }
+    // Check if page is tall enough to scroll to saved position
+    const maxScrollY = document.documentElement.scrollHeight - window.innerHeight;
+    const canScrollToPosition = savedY <= maxScrollY;
+    if (canScrollToPosition) {
+        window.scrollTo(0, savedY);
+        console.log("[Scroll] Restored position:", savedY, "for key:", key);
+        return true;
+    }
+    // Scroll as far as we can for now
+    window.scrollTo(0, maxScrollY);
+    console.log("[Scroll] Partial restore to:", maxScrollY, "target:", savedY);
+    // Poll while streaming until we can scroll to target position
+    if (options?.retryIfStreaming && options?.isStreaming?.()) {
+        const startTime = Date.now();
+        pendingPollInterval = setInterval(() => {
+            // Stop if we've exceeded the timeout
+            if (Date.now() - startTime > SCROLL_POLL_TIMEOUT_MS) {
+                console.log("[Scroll] Polling timeout, giving up");
+                cancelScrollRestorationPolling();
+                return;
+            }
+            // Stop if streaming ended
+            if (!options.isStreaming?.()) {
+                console.log("[Scroll] Streaming ended, stopping poll");
+                cancelScrollRestorationPolling();
+                return;
+            }
+            // Check if we can now scroll to the target position
+            const currentMaxScrollY = document.documentElement.scrollHeight - window.innerHeight;
+            if (savedY <= currentMaxScrollY) {
+                window.scrollTo(0, savedY);
+                console.log("[Scroll] Poll restored position:", savedY);
+                cancelScrollRestorationPolling();
+            }
+        }, SCROLL_POLL_INTERVAL_MS);
+    }
+    return false;
+}
+/**
+ * Handle hash link scrolling.
+ * Scrolls to element with matching ID if hash is present.
+ * Returns true if scrolled to element, false otherwise.
+ */
+export function scrollToHash() {
+    const hash = window.location.hash;
+    if (!hash)
+        return false;
+    try {
+        const id = decodeURIComponent(hash.slice(1));
+        const element = document.getElementById(id);
+        if (element) {
+            element.scrollIntoView();
+            console.log("[Scroll] Scrolled to hash element:", id);
+            return true;
+        }
+    }
+    catch (e) {
+        console.warn("[Scroll] Failed to decode hash:", hash);
+    }
+    return false;
+}
+/**
+ * Scroll to top of page
+ */
+export function scrollToTop() {
+    window.scrollTo(0, 0);
+}
+/**
+ * Handle scroll for a new navigation.
+ * - Saves current position before navigating
+ * - Ensures new history entry has a key
+ */
+export function handleNavigationStart() {
+    if (!initialized)
+        return;
+    saveCurrentScrollPosition();
+}
+/**
+ * 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 function handleNavigationEnd(options) {
+    if (!initialized) {
+        return;
+    }
+    const { restore = false, scroll = true, isStreaming } = options;
+    // Don't scroll if explicitly disabled
+    if (scroll === false) {
+        return;
+    }
+    // For back/forward (restore), try to restore saved position
+    if (restore) {
+        if (restoreScrollPosition({ retryIfStreaming: true, isStreaming })) {
+            return;
+        }
+        // Fall through to hash or top if no saved position
+    }
+    // Try hash scrolling first
+    if (scrollToHash()) {
+        return;
+    }
+    // Default: scroll to top
+    scrollToTop();
+}
+/**
+ * Update the history state key after pushState/replaceState.
+ * Call this after changing history to ensure new entry has a key.
+ */
+export function ensureHistoryKey() {
+    getHistoryStateKey();
+}
+//# sourceMappingURL=scroll-restoration.js.map

package/dist/browser/scroll-restoration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-restoration.js","sourceRoot":"","sources":["../../src/browser/scroll-restoration.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,17 @@
+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;
+//# sourceMappingURL=segment-structure-assert.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"segment-structure-assert.d.ts","sourceRoot":"","sources":["../../src/browser/segment-structure-assert.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAwBlD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE,eAAe,EACzB,OAAO,EAAE,MAAM,GACd,IAAI,CAiCN"}

package/dist/browser/segment-structure-assert.js

@@ -0,0 +1,59 @@
+function getLoadingCategory(loading) {
+    if (loading === undefined || loading === null)
+        return "none";
+    if (loading === false)
+        return "suppressed";
+    return "active";
+}
+/**
+ * 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 function assertSegmentStructure(cached, incoming, context) {
+    if (process.env.NODE_ENV === "production")
+        return;
+    const cachedCategory = getLoadingCategory(cached.loading);
+    const incomingCategory = getLoadingCategory(incoming.loading);
+    if (cachedCategory !== incomingCategory) {
+        console.warn(`[RSC Router] Tree structure mismatch detected in ${context} ` +
+            `for segment "${cached.id}": loading category changed from ` +
+            `"${cachedCategory}" (${describeLoading(cached.loading)}) to ` +
+            `"${incomingCategory}" (${describeLoading(incoming.loading)}). ` +
+            `This will cause React to remount the component, destroying ` +
+            `useActionState and other client state. ` +
+            `The merge code should preserve the cached loading value.`);
+    }
+    // Check mountPath consistency. MountContextProvider is conditionally added
+    // in renderSegments() when mountPath is truthy, changing tree depth.
+    const cachedHasMount = !!cached.mountPath;
+    const incomingHasMount = !!incoming.mountPath;
+    if (cachedHasMount !== incomingHasMount) {
+        console.warn(`[RSC Router] MountContextProvider mismatch detected in ${context} ` +
+            `for segment "${cached.id}": mountPath changed from ` +
+            `${cachedHasMount ? `"${cached.mountPath}"` : "undefined"} to ` +
+            `${incomingHasMount ? `"${incoming.mountPath}"` : "undefined"}. ` +
+            `This will cause React to remount the component, destroying ` +
+            `useActionState and other client state. ` +
+            `The merge code should preserve the cached mountPath value.`);
+    }
+}
+function describeLoading(loading) {
+    if (loading === undefined)
+        return "undefined";
+    if (loading === null)
+        return "null";
+    if (loading === false)
+        return "false";
+    return "ReactNode";
+}
+//# sourceMappingURL=segment-structure-assert.js.map

package/dist/browser/segment-structure-assert.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"segment-structure-assert.js","sourceRoot":"","sources":["../../src/browser/segment-structure-assert.ts"],"names":[],"mappings":"AAkBA,SAAS,kBAAkB,CAAC,OAAgB;IAC1C,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAC7D,IAAI,OAAO,KAAK,KAAK;QAAE,OAAO,YAAY,CAAC;IAC3C,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAAuB,EACvB,QAAyB,EACzB,OAAe;IAEf,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY;QAAE,OAAO;IAElD,MAAM,cAAc,GAAG,kBAAkB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC1D,MAAM,gBAAgB,GAAG,kBAAkB,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAE9D,IAAI,cAAc,KAAK,gBAAgB,EAAE,CAAC;QACxC,OAAO,CAAC,IAAI,CACV,oDAAoD,OAAO,GAAG;YAC5D,gBAAgB,MAAM,CAAC,EAAE,mCAAmC;YAC5D,IAAI,cAAc,MAAM,eAAe,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO;YAC9D,IAAI,gBAAgB,MAAM,eAAe,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK;YAChE,6DAA6D;YAC7D,yCAAyC;YACzC,0DAA0D,CAC7D,CAAC;IACJ,CAAC;IAED,2EAA2E;IAC3E,qEAAqE;IACrE,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC;IAC1C,MAAM,gBAAgB,GAAG,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC;IAC9C,IAAI,cAAc,KAAK,gBAAgB,EAAE,CAAC;QACxC,OAAO,CAAC,IAAI,CACV,0DAA0D,OAAO,GAAG;YAClE,gBAAgB,MAAM,CAAC,EAAE,4BAA4B;YACrD,GAAG,cAAc,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,WAAW,MAAM;YAC/D,GAAG,gBAAgB,CAAC,CAAC,CAAC,IAAI,QAAQ,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,WAAW,IAAI;YACjE,6DAA6D;YAC7D,yCAAyC;YACzC,4DAA4D,CAC/D,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAS,eAAe,CAAC,OAAgB;IACvC,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,WAAW,CAAC;IAC9C,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IACpC,IAAI,OAAO,KAAK,KAAK;QAAE,OAAO,OAAO,CAAC;IACtC,OAAO,WAAW,CAAC;AACrB,CAAC"}

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

@@ -0,0 +1,26 @@
+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;
+    /** RSC version from initial payload metadata */
+    version?: string;
+}
+/**
+ * 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 };
+//# sourceMappingURL=server-action-bridge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"server-action-bridge.d.ts","sourceRoot":"","sources":["../../src/browser/server-action-bridge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,wBAAwB,EAIzB,MAAM,YAAY,CAAC;AASpB,OAAO,KAAK,EAAE,eAAe,EAAgB,MAAM,uBAAuB,CAAC;AA6B3E;;GAEG;AACH,MAAM,WAAW,sCACf,SAAQ,wBAAwB;IAChC,eAAe,EAAE,eAAe,CAAC;IACjC,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,sCAAsC,GAC7C,kBAAkB,CA8tBpB;AAED,OAAO,EAAE,wBAAwB,IAAI,OAAO,EAAE,CAAC"}