vinext 0.0.37 → 0.0.39

package/dist/shims/navigation.d.ts

@@ -2,23 +2,34 @@ import { ReadonlyURLSearchParams } from "./readonly-url-search-params.js";
 import * as React$1 from "react";
 
 //#region src/shims/navigation.d.ts
+/**
+ * Map of parallel route key → child segments below the current layout.
+ * The "children" key is always present (the default parallel route).
+ * Named parallel routes add their own keys (e.g., "team", "analytics").
+ *
+ * Arrays are mutable (`string[]`) to match Next.js's public API return type
+ * without requiring `as` casts. The map itself is Readonly — no key addition.
+ */
+type SegmentMap = Readonly<Record<string, string[]>> & {
+  readonly children: string[];
+};
 declare const ServerInsertedHTMLContext: React$1.Context<((callback: () => unknown) => void) | null> | null;
 /**
  * Get or create the layout segment context.
  * Returns null in the RSC environment (createContext unavailable).
  */
-declare function getLayoutSegmentContext(): React$1.Context<string[]> | null;
-interface NavigationContext {
+declare function getLayoutSegmentContext(): React$1.Context<SegmentMap> | null;
+type NavigationContext = {
   pathname: string;
   searchParams: URLSearchParams;
   params: Record<string, string | string[]>;
-}
-interface _StateAccessors {
+};
+type _StateAccessors = {
   getServerContext: () => NavigationContext | null;
   setServerContext: (ctx: NavigationContext | null) => void;
   getInsertedHTMLCallbacks: () => Array<() => unknown>;
   clearInsertedHTMLCallbacks: () => void;
-}
+};
 declare const GLOBAL_ACCESSORS_KEY: unique symbol;
 /**
  * Register ALS-backed state accessors. Called by navigation-state.ts on import.
@@ -36,14 +47,24 @@ declare function getNavigationContext(): NavigationContext | null;
  * Called by the framework entry before rendering each request.
  */
 declare function setNavigationContext(ctx: NavigationContext | null): void;
+/** basePath from next.config.js, injected by the plugin at build time */
+declare const __basePath: string;
 /** Maximum number of entries in the RSC prefetch cache. */
 declare const MAX_PREFETCH_CACHE_SIZE = 50;
 /** TTL for prefetch cache entries in ms (matches Next.js static prefetch TTL). */
 declare const PREFETCH_CACHE_TTL = 30000;
-interface PrefetchCacheEntry {
-  response: Response;
+/** A buffered RSC response stored as an ArrayBuffer for replay. */
+type CachedRscResponse = {
+  buffer: ArrayBuffer;
+  contentType: string;
+  paramsHeader: string | null;
+  url: string;
+};
+type PrefetchCacheEntry = {
+  snapshot?: CachedRscResponse;
+  pending?: Promise<void>;
   timestamp: number;
-}
+};
 /**
  * Convert a pathname (with optional query/hash) to its .rsc URL.
  * Strips trailing slashes before appending `.rsc` so that cache keys
@@ -58,12 +79,71 @@ declare function getPrefetchCache(): Map<string, PrefetchCacheEntry>;
  */
 declare function getPrefetchedUrls(): Set<string>;
 /**
- * Store a prefetched RSC response in the cache.
+ * Store a prefetched RSC response in the cache by snapshotting it to an
+ * ArrayBuffer.  The snapshot completes asynchronously; during that window
+ * the entry is marked `pending` so consumePrefetchResponse() will skip it
+ * (the caller falls back to a fresh fetch, which is acceptable).
+ *
+ * Prefer prefetchRscResponse() for new call-sites — it handles the full
+ * prefetch lifecycle including dedup.  storePrefetchResponse() is kept for
+ * backward compatibility and test helpers.
+ *
+ * NB: Caller is responsible for managing getPrefetchedUrls() — this
+ * function only stores the response in the prefetch cache.
+ */
+declare function storePrefetchResponse(rscUrl: string, response: Response): void;
+/**
+ * Snapshot an RSC response to an ArrayBuffer for caching and replay.
+ * Consumes the response body and stores it with content-type and URL metadata.
+ */
+declare function snapshotRscResponse(response: Response): Promise<CachedRscResponse>;
+/**
+ * Reconstruct a Response from a cached RSC snapshot.
+ * Creates a new Response with the original ArrayBuffer so createFromFetch
+ * can consume the stream from scratch.
+ *
+ * NOTE: The reconstructed Response always has `url === ""` — the Response
+ * constructor does not accept a `url` option, and `response.url` is read-only
+ * set by the fetch infrastructure. Callers that need the original URL should
+ * read it from `cached.url` directly rather than from the restored Response.
+ *
+ * @param copy - When true (default), copies the ArrayBuffer so the cached
+ *   snapshot remains replayable (needed for the visited-response cache).
+ *   Pass false for single-consumption paths (e.g. prefetch cache entries
+ *   that are deleted after consumption) to avoid the extra allocation.
+ */
+declare function restoreRscResponse(cached: CachedRscResponse, copy?: boolean): Response;
+/**
+ * Prefetch an RSC response and snapshot it for later consumption.
+ * Stores the in-flight promise so immediate clicks can await it instead
+ * of firing a duplicate fetch.
  * Enforces a maximum cache size to prevent unbounded memory growth on
  * link-heavy pages.
  */
-declare function storePrefetchResponse(rscUrl: string, response: Response): void;
+declare function prefetchRscResponse(rscUrl: string, fetchPromise: Promise<Response>): void;
+/**
+ * Consume a prefetched response for a given rscUrl.
+ * Only returns settled (non-pending) snapshots synchronously.
+ * Returns null if the entry is still in flight or doesn't exist.
+ */
+declare function consumePrefetchResponse(rscUrl: string): CachedRscResponse | null;
+/**
+ * Mark a navigation snapshot as active. Called before startTransition
+ * in renderNavigationPayload. While active, hooks prefer the snapshot
+ * context value over useSyncExternalStore. Uses a counter (not boolean)
+ * to handle overlapping navigations — rapid clicks can interleave
+ * activate/deactivate if multiple transitions are in flight.
+ */
+declare function activateNavigationSnapshot(): void;
+type ClientNavigationRenderSnapshot = {
+  pathname: string;
+  searchParams: ReadonlyURLSearchParams;
+  params: Record<string, string | string[]>;
+};
+declare function getClientNavigationRenderContext(): React$1.Context<ClientNavigationRenderSnapshot | null> | null;
+declare function createClientNavigationRenderSnapshot(href: string, params: Record<string, string | string[]>): ClientNavigationRenderSnapshot;
 declare function setClientParams(params: Record<string, string | string[]>): void;
+declare function replaceClientParamsWithoutNotify(params: Record<string, string | string[]>): void;
 /** Get the current client params (for testing referential stability). */
 declare function getClientParams(): Record<string, string | string[]>;
 /**
@@ -79,6 +159,13 @@ declare function useSearchParams(): ReadonlyURLSearchParams;
  * Returns the dynamic params for the current route.
  */
 declare function useParams<T extends Record<string, string | string[]> = Record<string, string | string[]>>(): T;
+declare function commitClientNavigationState(): void;
+declare function pushHistoryStateWithoutNotify(data: unknown, unused: string, url?: string | URL | null): void;
+declare function replaceHistoryStateWithoutNotify(data: unknown, unused: string, url?: string | URL | null): void;
+/**
+ * Navigate to a URL, handling external URLs, hash-only changes, and RSC navigation.
+ */
+declare function navigateClientSide(href: string, mode: "push" | "replace", scroll: boolean): Promise<void>;
 /**
  * App Router's useRouter — returns push/replace/back/forward/refresh.
  * Different from Pages Router's useRouter (next/router).
@@ -108,19 +195,17 @@ declare function useRouter(): {
  *
  * @param parallelRoutesKey - Which parallel route to read (default: "children")
  */
-declare function useSelectedLayoutSegment(_parallelRoutesKey?: string): string | null;
+declare function useSelectedLayoutSegment(parallelRoutesKey?: string): string | null;
 /**
  * Returns all active segments below the layout where it's called.
  *
  * Each layout in the App Router tree wraps its children with a
- * LayoutSegmentProvider whose value is the remaining route tree segments
- * (including route groups, with dynamic params resolved to actual values
- * and catch-all segments joined with "/"). This hook reads those segments
- * directly from context.
+ * LayoutSegmentProvider whose value is a map of parallel route key to
+ * segment arrays. The "children" key is the default parallel route.
  *
  * @param parallelRoutesKey - Which parallel route to read (default: "children")
  */
-declare function useSelectedLayoutSegments(_parallelRoutesKey?: string): string[];
+declare function useSelectedLayoutSegments(parallelRoutesKey?: string): string[];
 /**
  * useServerInsertedHTML — inject HTML during SSR from client components.
  *
@@ -197,5 +282,5 @@ declare function forbidden(): never;
  */
 declare function unauthorized(): never;
 //#endregion
-export { GLOBAL_ACCESSORS_KEY, HTTP_ERROR_FALLBACK_ERROR_CODE, MAX_PREFETCH_CACHE_SIZE, NavigationContext, PREFETCH_CACHE_TTL, PrefetchCacheEntry, ReadonlyURLSearchParams, RedirectType, ServerInsertedHTMLContext, _registerStateAccessors, clearServerInsertedHTML, flushServerInsertedHTML, forbidden, getAccessFallbackHTTPStatus, getClientParams, getLayoutSegmentContext, getNavigationContext, getPrefetchCache, getPrefetchedUrls, isHTTPAccessFallbackError, notFound, permanentRedirect, redirect, setClientParams, setNavigationContext, storePrefetchResponse, toRscUrl, unauthorized, useParams, usePathname, useRouter, useSearchParams, useSelectedLayoutSegment, useSelectedLayoutSegments, useServerInsertedHTML };
+export { CachedRscResponse, ClientNavigationRenderSnapshot, GLOBAL_ACCESSORS_KEY, HTTP_ERROR_FALLBACK_ERROR_CODE, MAX_PREFETCH_CACHE_SIZE, NavigationContext, PREFETCH_CACHE_TTL, PrefetchCacheEntry, ReadonlyURLSearchParams, RedirectType, SegmentMap, ServerInsertedHTMLContext, __basePath, _registerStateAccessors, activateNavigationSnapshot, clearServerInsertedHTML, commitClientNavigationState, consumePrefetchResponse, createClientNavigationRenderSnapshot, flushServerInsertedHTML, forbidden, getAccessFallbackHTTPStatus, getClientNavigationRenderContext, getClientParams, getLayoutSegmentContext, getNavigationContext, getPrefetchCache, getPrefetchedUrls, isHTTPAccessFallbackError, navigateClientSide, notFound, permanentRedirect, prefetchRscResponse, pushHistoryStateWithoutNotify, redirect, replaceClientParamsWithoutNotify, replaceHistoryStateWithoutNotify, restoreRscResponse, setClientParams, setNavigationContext, snapshotRscResponse, storePrefetchResponse, toRscUrl, unauthorized, useParams, usePathname, useRouter, useSearchParams, useSelectedLayoutSegment, useSelectedLayoutSegments, useServerInsertedHTML };
 //# sourceMappingURL=navigation.d.ts.map