vinext 0.0.49 → 0.0.51

package/dist/shims/navigation.d.ts

@@ -1,4 +1,6 @@
+import { AppRouterInstance } from "./internal/app-router-context.js";
 import { ReadonlyURLSearchParams } from "./readonly-url-search-params.js";
+import { UnrecognizedActionError, unstable_isUnrecognizedActionError } from "./unrecognized-action-error.js";
 import * as React$1 from "react";
 
 //#region src/shims/navigation.d.ts
@@ -55,13 +57,20 @@ declare const MAX_PREFETCH_CACHE_SIZE = 50;
 declare const PREFETCH_CACHE_TTL = 30000;
 /** A buffered RSC response stored as an ArrayBuffer for replay. */
 type CachedRscResponse = {
+  compatibilityIdHeader?: string | null;
   buffer: ArrayBuffer;
   contentType: string;
   mountedSlotsHeader?: string | null;
   paramsHeader: string | null;
   url: string;
 };
+type PrefetchOptions = {
+  kind?: unknown;
+  onInvalidate?: () => void;
+};
 type PrefetchCacheEntry = {
+  invalidationTimer?: ReturnType<typeof setTimeout>;
+  onInvalidateCallbacks?: Set<() => void>;
   outcome: "pending" | "cache-seeded";
   snapshot?: CachedRscResponse;
   pending?: Promise<void>;
@@ -76,6 +85,7 @@ declare function getPrefetchCache(): Map<string, PrefetchCacheEntry>;
  * Keyed by interception-aware cache key so distinct source routes do not alias.
  */
 declare function getPrefetchedUrls(): Set<string>;
+declare function invalidatePrefetchCache(): void;
 /**
  * Store a prefetched RSC response in the cache by snapshotting it to an
  * ArrayBuffer.  The snapshot completes asynchronously; during that window
@@ -92,7 +102,8 @@ declare function getPrefetchedUrls(): Set<string>;
  * NB: Caller is responsible for managing getPrefetchedUrls() — this
  * function only stores the response in the prefetch cache.
  */
-declare function storePrefetchResponse(rscUrl: string, response: Response, interceptionContext?: string | null): void;
+declare function storePrefetchResponse(rscUrl: string, response: Response, interceptionContext?: string | null, options?: PrefetchOptions): void;
+declare function createCachedRscResponseSnapshot(response: Response, buffer: ArrayBuffer, responseUrl?: string | null): CachedRscResponse;
 /**
  * Snapshot an RSC response to an ArrayBuffer for caching and replay.
  * Consumes the response body and stores it with content-type and URL metadata.
@@ -121,7 +132,7 @@ declare function restoreRscResponse(cached: CachedRscResponse, copy?: boolean):
  * Enforces a maximum cache size to prevent unbounded memory growth on
  * link-heavy pages.
  */
-declare function prefetchRscResponse(rscUrl: string, fetchPromise: Promise<Response>, interceptionContext?: string | null, mountedSlotsHeader?: string | null): void;
+declare function prefetchRscResponse(rscUrl: string, fetchPromise: Promise<Response>, interceptionContext?: string | null, mountedSlotsHeader?: string | null, options?: PrefetchOptions): void;
 /**
  * Consume a prefetched response for a given rscUrl.
  * Only returns settled (non-pending) snapshots synchronously.
@@ -213,14 +224,14 @@ declare function replaceHistoryStateWithoutNotify(data: unknown, unused: string,
  */
 declare function navigateClientSide(href: string, mode: "push" | "replace", scroll: boolean, programmaticTransition?: boolean): Promise<void>;
 /**
- * App Router's useRouter — returns push/replace/back/forward/refresh.
- * Different from Pages Router's useRouter (next/router).
+ * Public App Router instance, exposed for the browser entry so it can wire
+ * `window.next.router` to the same singleton returned from `useRouter()`.
  *
- * Returns a stable singleton: the same object reference on every call,
- * matching Next.js behavior so components using referential equality
- * (e.g. useMemo / useEffect deps, React.memo) don't re-render unnecessarily.
+ * Mirrors `publicAppRouterInstance` from Next.js's
+ * `packages/next/src/client/components/app-router-instance.ts` (line 392).
  */
-declare function useRouter(): {
+declare const appRouterInstance: {
+  bfcacheId: string;
   push(href: string, options?: {
     scroll?: boolean;
   }): void;
@@ -230,8 +241,17 @@ declare function useRouter(): {
   back(): void;
   forward(): void;
   refresh(): void;
-  prefetch(href: string): void;
+  prefetch(href: string, options?: PrefetchOptions): void;
 };
+/**
+ * App Router's useRouter — returns push/replace/back/forward/refresh.
+ * Different from Pages Router's useRouter (next/router).
+ *
+ * Returns a stable singleton: the same object reference on every call,
+ * matching Next.js behavior so components using referential equality
+ * (e.g. useMemo / useEffect deps, React.memo) don't re-render unnecessarily.
+ */
+declare function useRouter(): AppRouterInstance;
 /**
  * Returns the active child segment one level below the layout where it's called.
  *
@@ -351,6 +371,148 @@ declare function forbidden(): never;
  * support it unconditionally for maximum compatibility.
  */
 declare function unauthorized(): never;
+type _RedirectErrorShape = Error & {
+  digest: string;
+};
+/**
+ * Check whether an error was produced by `redirect()` or `permanentRedirect()`.
+ *
+ * **Note on vinext public surface:** Next.js does NOT expose `isRedirectError`
+ * from `next/navigation` — it's an internal predicate. vinext exposes it for
+ * symmetry with the already-public `isHTTPAccessFallbackError` and because
+ * `unstable_rethrow` consumers benefit from being able to narrow types.
+ * Treat it as a vinext-only extension.
+ *
+ * **Divergence from Next.js:** Next.js's internal `isRedirectError` performs
+ * full 4-segment validation — it splits the digest on `;`, checks `type` ∈
+ * {push, replace}, requires a non-empty destination, and validates the
+ * status code (303, 307, 308). See:
+ *   https://github.com/vercel/next.js/blob/canary/packages/next/src/client/components/redirect-error.ts
+ *
+ * vinext instead uses a simple prefix check (`startsWith("NEXT_REDIRECT;")`).
+ * Reasons:
+ *   1. vinext emits two digest shapes — 3-part for `redirect()`
+ *      (`NEXT_REDIRECT;{type};{encoded-url}`) and 4-part for
+ *      `permanentRedirect()` (`NEXT_REDIRECT;{type};{encoded-url};308`).
+ *      Strict validation would have to special-case both, and Next.js's
+ *      validator (tuned to its 5-part canary digests) rejects them.
+ *   2. The `type` field is sometimes empty in vinext's redirect digests
+ *      (context-dependent resolution; see `redirect()` above), which the
+ *      strict check disallows.
+ *
+ * **Consequence:** A malformed digest such as `"NEXT_REDIRECT;garbage"`
+ * returns `true` here, whereas Next.js would return `false`. In practice,
+ * the only callers of this predicate are vinext-internal code paths
+ * (`unstable_rethrow`, `unstable_catchError`, the redirect error boundary)
+ * that see digests vinext itself emits — so the divergence does not surface
+ * in normal use. Maintainers extending the prefix logic should keep this
+ * predicate in lockstep with the corresponding `decode*` helpers in
+ * `shims/error-boundary.tsx`.
+ */
+declare function isRedirectError(error: unknown): error is _RedirectErrorShape;
+/**
+ * Returns true if the error is a Next.js navigation signal — either a redirect
+ * or an HTTP access fallback (notFound / forbidden / unauthorized).
+ *
+ * **Note on vinext public surface:** Like `isRedirectError`, Next.js does NOT
+ * expose this from `next/navigation`. vinext exposes it for symmetry — treat
+ * it as a vinext-only extension.
+ *
+ * Ported from Next.js:
+ *   https://github.com/vercel/next.js/blob/canary/packages/next/src/client/components/is-next-router-error.ts
+ */
+declare function isNextRouterError(error: unknown): boolean;
+declare const _BAILOUT_TO_CSR_DIGEST = "BAILOUT_TO_CLIENT_SIDE_RENDERING";
+/**
+ * Error thrown to bail out of server rendering and fall back to client-side
+ * rendering. Used by `next/dynamic` with `ssr: false`.
+ *
+ * vinext does not yet emit this error itself — it's exposed so user code and
+ * third-party libraries that mimic `next/dynamic`'s bailout semantics can
+ * construct an error with the canonical digest that `unstable_rethrow`
+ * recognises.
+ *
+ * Ported 1:1 from Next.js:
+ *   https://github.com/vercel/next.js/blob/canary/packages/next/src/shared/lib/lazy-dynamic/bailout-to-csr.ts
+ */
+declare class BailoutToCSRError extends Error {
+  readonly digest: typeof _BAILOUT_TO_CSR_DIGEST;
+  readonly reason: string;
+  constructor(reason: string);
+}
+/**
+ * Returns true if the error is a `BailoutToCSRError`. Matches Next.js's
+ * digest-based predicate, so any error from a foreign module instance of
+ * the class (or constructed manually with the canonical digest) is also
+ * detected.
+ *
+ * **Note on vinext public surface:** Next.js does NOT expose this from
+ * `next/navigation`. vinext exposes it for symmetry with `isRedirectError`
+ * — treat it as a vinext-only extension. The matching producer
+ * (`BailoutToCSRError`) is the public detection contract; Next.js exposes
+ * neither.
+ *
+ * Ported from Next.js:
+ *   https://github.com/vercel/next.js/blob/canary/packages/next/src/shared/lib/lazy-dynamic/bailout-to-csr.ts
+ */
+declare function isBailoutToCSRError(error: unknown): error is BailoutToCSRError;
+declare const _DYNAMIC_SERVER_USAGE_DIGEST = "DYNAMIC_SERVER_USAGE";
+/**
+ * Error thrown when dynamic server APIs (`cookies()`, `headers()`, etc.) are
+ * used inside a static/prerender context. Carries the `DYNAMIC_SERVER_USAGE`
+ * digest so `unstable_rethrow` can recognise and propagate it.
+ *
+ * vinext does not construct this error itself — exposed for the same
+ * "stable detection contract" reason as `BailoutToCSRError` above.
+ *
+ * Ported 1:1 from Next.js:
+ *   https://github.com/vercel/next.js/blob/canary/packages/next/src/client/components/hooks-server-context.ts
+ */
+declare class DynamicServerError extends Error {
+  readonly digest: typeof _DYNAMIC_SERVER_USAGE_DIGEST;
+  readonly description: string;
+  constructor(description: string);
+}
+/**
+ * Returns true if the error is a `DynamicServerError` (or any error with the
+ * canonical `DYNAMIC_SERVER_USAGE` digest).
+ *
+ * **Note on vinext public surface:** Next.js does NOT expose this from
+ * `next/navigation`. vinext exposes it for symmetry — treat it as a
+ * vinext-only extension.
+ *
+ * Ported from Next.js:
+ *   https://github.com/vercel/next.js/blob/canary/packages/next/src/client/components/hooks-server-context.ts
+ */
+declare function isDynamicServerError(error: unknown): error is DynamicServerError;
+/**
+ * Rethrow internal Next.js errors so they're handled by the framework.
+ *
+ * When wrapping an API that uses errors for control flow (redirect, notFound,
+ * cookies in static render, `next/dynamic` SSR bailout, etc.), call this
+ * inside `catch` blocks before doing your own error handling. If the error
+ * is a Next.js internal error, it's rethrown; otherwise this is a no-op
+ * (apart from recursing through `error.cause`).
+ *
+ * Recognises (matches Next.js's browser build + the subset of the server
+ * build that vinext can realistically encounter):
+ *   - `isNextRouterError`: redirect / notFound / forbidden / unauthorized
+ *   - `isBailoutToCSRError`: `next/dynamic` `ssr: false` bailout
+ *   - `isDynamicServerError`: dynamic API used in static render
+ *
+ * vinext does not yet recognise four additional server-only Next.js
+ * categories — `isDynamicPostpone`, `isPostpone`,
+ * `isHangingPromiseRejectionError`, `isPrerenderInterruptedError` — because
+ * they signal PPR / prerender-controller events that vinext's render
+ * pipeline does not generate. User code cannot construct these in normal
+ * use; they will be added if/when vinext grows PPR support.
+ *
+ * Ported from Next.js:
+ *   https://github.com/vercel/next.js/blob/canary/packages/next/src/client/components/unstable-rethrow.ts
+ *   https://github.com/vercel/next.js/blob/canary/packages/next/src/client/components/unstable-rethrow.server.ts
+ *   https://github.com/vercel/next.js/blob/canary/packages/next/src/client/components/unstable-rethrow.browser.ts
+ */
+declare function unstable_rethrow(error: unknown): void;
 //#endregion
-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, clearPendingPathname, clearServerInsertedHTML, commitClientNavigationState, consumePrefetchResponse, createClientNavigationRenderSnapshot, flushServerInsertedHTML, forbidden, getAccessFallbackHTTPStatus, getClientNavigationRenderContext, getClientNavigationState, getClientParams, getCurrentInterceptionContext, getCurrentNextUrl, getLayoutSegmentContext, getMountedSlotsHeader, getNavigationContext, getPrefetchCache, getPrefetchedUrls, isHTTPAccessFallbackError, navigateClientSide, notFound, permanentRedirect, prefetchRscResponse, pushHistoryStateWithoutNotify, redirect, renderServerInsertedHTML, replaceClientParamsWithoutNotify, replaceHistoryStateWithoutNotify, restoreRscResponse, setClientParams, setMountedSlotsHeader, setNavigationContext, setPendingPathname, snapshotRscResponse, storePrefetchResponse, unauthorized, useParams, usePathname, useRouter, useSearchParams, useSelectedLayoutSegment, useSelectedLayoutSegments, useServerInsertedHTML };
+export { BailoutToCSRError, CachedRscResponse, ClientNavigationRenderSnapshot, DynamicServerError, GLOBAL_ACCESSORS_KEY, HTTP_ERROR_FALLBACK_ERROR_CODE, MAX_PREFETCH_CACHE_SIZE, NavigationContext, PREFETCH_CACHE_TTL, PrefetchCacheEntry, PrefetchOptions, ReadonlyURLSearchParams, RedirectType, SegmentMap, ServerInsertedHTMLContext, UnrecognizedActionError, __basePath, _registerStateAccessors, activateNavigationSnapshot, appRouterInstance, clearPendingPathname, clearServerInsertedHTML, commitClientNavigationState, consumePrefetchResponse, createCachedRscResponseSnapshot, createClientNavigationRenderSnapshot, flushServerInsertedHTML, forbidden, getAccessFallbackHTTPStatus, getClientNavigationRenderContext, getClientNavigationState, getClientParams, getCurrentInterceptionContext, getCurrentNextUrl, getLayoutSegmentContext, getMountedSlotsHeader, getNavigationContext, getPrefetchCache, getPrefetchedUrls, invalidatePrefetchCache, isBailoutToCSRError, isDynamicServerError, isHTTPAccessFallbackError, isNextRouterError, isRedirectError, navigateClientSide, notFound, permanentRedirect, prefetchRscResponse, pushHistoryStateWithoutNotify, redirect, renderServerInsertedHTML, replaceClientParamsWithoutNotify, replaceHistoryStateWithoutNotify, restoreRscResponse, setClientParams, setMountedSlotsHeader, setNavigationContext, setPendingPathname, snapshotRscResponse, storePrefetchResponse, unauthorized, unstable_isUnrecognizedActionError, unstable_rethrow, useParams, usePathname, useRouter, useSearchParams, useSelectedLayoutSegment, useSelectedLayoutSegments, useServerInsertedHTML };
 //# sourceMappingURL=navigation.d.ts.map