vinext 1.0.0-beta.1 → 1.0.0-beta.2

package/dist/shims/app.d.ts

@@ -36,7 +36,7 @@ declare function appGetInitialProps({
 declare class App<P = any, CP = any, S = any> extends React.Component<P & AppProps<CP>, S> {
   static origGetInitialProps: typeof appGetInitialProps;
   static getInitialProps: typeof appGetInitialProps;
-  render(): React.ReactNode;
+  render(): React.ReactElement;
 }
 //#endregion
 export { AppContext, AppInitialProps, AppProps, App as default };

package/dist/shims/cache-request-state.d.ts

@@ -26,6 +26,8 @@ type UnstableCacheObservation = Readonly<{
 }>;
 type CacheState = {
   actionRevalidationKind: ActionRevalidationKind;
+  pendingRevalidatedTags: Set<string>;
+  pendingRevalidations: Set<Promise<void>>;
   requestScopedCacheLife: CacheLifeConfig | null;
   unstableCacheObservations: Map<string, UnstableCacheObservation>;
   unstableCacheRevalidation: UnstableCacheRevalidationMode;
@@ -37,6 +39,30 @@ declare function _runWithCacheState<T>(fn: () => T | Promise<T>): T | Promise<T>
 declare function _initRequestScopedCacheState(): void;
 declare function markActionRevalidation(kind: ActionRevalidationKind): void;
 declare function getAndClearActionRevalidationKind(): ActionRevalidationKind;
+/** @internal */
+declare function _markPendingRevalidatedTag(tag: string): void;
+/** @internal */
+declare function _hasPendingRevalidatedTag(tags: readonly string[]): boolean;
+/**
+ * Record a cache invalidation that must finish before the current action or
+ * route-handler request is finalized. The public revalidation APIs remain
+ * synchronous, matching Next.js, while the request boundary owns the await.
+ *
+ * Returns false outside a request-like phase so standalone calls can retain
+ * their historical background-work behavior without accumulating promises in
+ * the process-global fallback state.
+ *
+ * @internal
+ */
+declare function _queuePendingRevalidation(promise: Promise<void>): boolean;
+/**
+ * Await and clear every cache invalidation queued in the current request.
+ * Clearing before awaiting also lets a later drain observe work enqueued by
+ * an async continuation while this batch is settling.
+ *
+ * @internal
+ */
+declare function _drainPendingRevalidations(): Promise<void>;
 declare function _setRequestScopedCacheLife(config: CacheLifeConfig): void;
 declare function _peekRequestScopedCacheLife(): CacheLifeConfig | null;
 declare function _consumeRequestScopedCacheLife(): CacheLifeConfig | null;
@@ -44,4 +70,4 @@ declare function recordUnstableCacheObservation(observation: UnstableCacheObserv
 declare function _peekUnstableCacheObservations(): UnstableCacheObservation[];
 declare function shouldServeStaleUnstableCacheEntry(): boolean;
 //#endregion
-export { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, ActionRevalidationKind, CacheLifeConfig, CacheState, UnstableCacheObservation, UnstableCacheRevalidationMode, _consumeRequestScopedCacheLife, _initRequestScopedCacheState, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, getAndClearActionRevalidationKind, getRegisteredCacheContext, markActionRevalidation, recordUnstableCacheObservation, shouldServeStaleUnstableCacheEntry };
+export { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, ActionRevalidationKind, CacheLifeConfig, CacheState, UnstableCacheObservation, UnstableCacheRevalidationMode, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _queuePendingRevalidation, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, getAndClearActionRevalidationKind, getRegisteredCacheContext, markActionRevalidation, recordUnstableCacheObservation, shouldServeStaleUnstableCacheEntry };

package/dist/shims/cache-request-state.js

@@ -53,6 +53,8 @@ const ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC = 1;
 const ACTION_DID_REVALIDATE_DYNAMIC_ONLY = 2;
 const fallbackState = globalState[FALLBACK_KEY] ??= {
 	actionRevalidationKind: ACTION_DID_NOT_REVALIDATE,
+	pendingRevalidatedTags: /* @__PURE__ */ new Set(),
+	pendingRevalidations: /* @__PURE__ */ new Set(),
 	requestScopedCacheLife: null,
 	unstableCacheObservations: /* @__PURE__ */ new Map(),
 	unstableCacheRevalidation: "foreground"
@@ -70,6 +72,8 @@ function _runWithCacheState(fn) {
 	}, fn);
 	const state = {
 		actionRevalidationKind: ACTION_DID_NOT_REVALIDATE,
+		pendingRevalidatedTags: /* @__PURE__ */ new Set(),
+		pendingRevalidations: /* @__PURE__ */ new Set(),
 		requestScopedCacheLife: null,
 		unstableCacheObservations: /* @__PURE__ */ new Map(),
 		unstableCacheRevalidation: "foreground"
@@ -93,6 +97,61 @@ function getAndClearActionRevalidationKind() {
 	state.actionRevalidationKind = ACTION_DID_NOT_REVALIDATE;
 	return kind;
 }
+function hasRequestScopedCacheState() {
+	if (isInsideUnifiedScope() || cacheAls.getStore() !== void 0) return true;
+	const phase = getHeadersAccessPhase();
+	return phase === "action" || phase === "route-handler";
+}
+/** @internal */
+function _markPendingRevalidatedTag(tag) {
+	if (!hasRequestScopedCacheState()) return;
+	getCacheState().pendingRevalidatedTags.add(tag);
+}
+/** @internal */
+function _hasPendingRevalidatedTag(tags) {
+	if (!hasRequestScopedCacheState()) return false;
+	const pendingTags = getCacheState().pendingRevalidatedTags;
+	return tags.some((tag) => pendingTags.has(tag));
+}
+/**
+* Record a cache invalidation that must finish before the current action or
+* route-handler request is finalized. The public revalidation APIs remain
+* synchronous, matching Next.js, while the request boundary owns the await.
+*
+* Returns false outside a request-like phase so standalone calls can retain
+* their historical background-work behavior without accumulating promises in
+* the process-global fallback state.
+*
+* @internal
+*/
+function _queuePendingRevalidation(promise) {
+	if (!hasRequestScopedCacheState()) return false;
+	getCacheState().pendingRevalidations.add(promise);
+	promise.catch(() => {});
+	return true;
+}
+/**
+* Await and clear every cache invalidation queued in the current request.
+* Clearing before awaiting also lets a later drain observe work enqueued by
+* an async continuation while this batch is settling.
+*
+* @internal
+*/
+async function _drainPendingRevalidations() {
+	const state = getCacheState();
+	let didReject = false;
+	let firstRejection;
+	while (state.pendingRevalidations.size > 0) {
+		const pending = [...state.pendingRevalidations];
+		state.pendingRevalidations.clear();
+		const results = await Promise.allSettled(pending);
+		for (const result of results) if (result.status === "rejected" && !didReject) {
+			didReject = true;
+			firstRejection = result.reason;
+		}
+	}
+	if (didReject) throw firstRejection;
+}
 function _setRequestScopedCacheLife(config) {
 	const state = getCacheState();
 	if (state.requestScopedCacheLife === null) {
@@ -123,4 +182,4 @@ function shouldServeStaleUnstableCacheEntry() {
 	return getCacheState().unstableCacheRevalidation === "background";
 }
 //#endregion
-export { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, _consumeRequestScopedCacheLife, _initRequestScopedCacheState, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, getAndClearActionRevalidationKind, getRegisteredCacheContext, markActionRevalidation, recordUnstableCacheObservation, shouldServeStaleUnstableCacheEntry };
+export { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _queuePendingRevalidation, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, getAndClearActionRevalidationKind, getRegisteredCacheContext, markActionRevalidation, recordUnstableCacheObservation, shouldServeStaleUnstableCacheEntry };

package/dist/shims/cache-runtime.d.ts

@@ -35,6 +35,17 @@ declare const cacheContextStorage: import("node:async_hooks").AsyncLocalStorage<
  * Get the current cache context. Returns null if not inside a "use cache" function.
  */
 declare function getCacheContext(): CacheContext | null;
+/**
+ * Build the shared-cache key for a "use cache" function from its build-scoped
+ * identity and serialized arguments.
+ *
+ * This is a logical handler key, not a storage key. Backend-specific adapters
+ * are responsible for mapping it to their physical key constraints after
+ * applying any storage prefixes.
+ *
+ * Exported for testing.
+ */
+declare function buildUseCacheKey(id: string, keySeed: string | undefined, argsKey?: string): string;
 /**
  * Convert an encodeReply result (string | FormData) to a cache key string.
  * For FormData (binary args), produces a deterministic SHA-256 hash over
@@ -80,4 +91,4 @@ type RegisterCachedFunctionOptions = {
  */
 declare function registerCachedFunction<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => Promise<TResult>, id: string, variant?: string, options?: RegisterCachedFunctionOptions): (...args: TArgs) => Promise<TResult>;
 //#endregion
-export { CacheContext, NestedDynamicUseCacheError, PrivateCacheState, cacheContextStorage, clearPrivateCache, getCacheContext, markAppPagePropsForUseCache, registerCachedFunction, replyToCacheKey, runWithPrivateCache };
+export { CacheContext, NestedDynamicUseCacheError, PrivateCacheState, buildUseCacheKey, cacheContextStorage, clearPrivateCache, getCacheContext, markAppPagePropsForUseCache, registerCachedFunction, replyToCacheKey, runWithPrivateCache };

package/dist/shims/cache-runtime.js

@@ -4,7 +4,7 @@ import { VINEXT_RSC_MARKER_HEADER } from "../server/headers.js";
 import { getDataCacheHandler } from "./cache-handler.js";
 import { trackPprFallbackShellCacheTask } from "./ppr-fallback-shell.js";
 import { markDynamicUsage } from "./headers.js";
-import { _registerCacheContextAccessor, _setRequestScopedCacheLife, cacheLifeProfiles } from "./cache-request-state.js";
+import { _hasPendingRevalidatedTag, _registerCacheContextAccessor, _setRequestScopedCacheLife, cacheLifeProfiles } from "./cache-request-state.js";
 import { addCollectedRequestTags, getCurrentFetchSoftTags } from "./fetch-cache.js";
 import { isMarkedAppPagePropsObject, markAppPagePropsForUseCache } from "./internal/app-page-props-cache-key.js";
 //#region src/shims/cache-runtime.ts
@@ -102,6 +102,16 @@ function getUseCacheBuildIdDefine() {
 function getUseCacheKeySeed() {
 	return getUseCacheDeploymentIdDefine() || getUseCacheBuildIdDefine();
 }
+/**
+* Build the shared-cache key for a "use cache" function from its build-scoped
+* identity and serialized arguments.
+*
+* This is a logical handler key, not a storage key. Backend-specific adapters
+* are responsible for mapping it to their physical key constraints after
+* applying any storage prefixes.
+*
+* Exported for testing.
+*/
 function buildUseCacheKey(id, keySeed, argsKey) {
 	const scopedId = keySeed ? `build:${encodeURIComponent(keySeed)}:${id}` : id;
 	return argsKey === void 0 ? `use-cache:${scopedId}` : `use-cache:${scopedId}:${argsKey}`;
@@ -263,11 +273,16 @@ function registerCachedFunction(fn, id, variant, options = {}) {
 		if (isDev) return executeWithContext(fn, args, cacheVariant);
 		const handler = getDataCacheHandler();
 		const softTags = getCurrentFetchSoftTags();
-		const existing = await handler.get(cacheKey, {
-			kind: "FETCH",
-			softTags
-		});
-		if (existing?.value && existing.value.kind === "FETCH" && existing.cacheState !== "stale") try {
+		let existing = null;
+		if (!_hasPendingRevalidatedTag(softTags)) try {
+			existing = await handler.get(cacheKey, {
+				kind: "FETCH",
+				softTags
+			});
+		} catch (error) {
+			console.error("[vinext] use cache: handler.get failed; treating as a cache miss:", error);
+		}
+		if (existing?.value && existing.value.kind === "FETCH" && existing.cacheState !== "stale" && !_hasPendingRevalidatedTag([...existing.value.tags ?? [], ...softTags])) try {
 			propagateCacheTagsToRequest(existing.value.tags);
 			if (rsc && existing.value.data.headers["x-vinext-rsc"] === "1") {
 				const stream = uint8ToStream(base64ToUint8(existing.value.data.body));
@@ -449,4 +464,4 @@ function stableStringify(value, seen) {
 	return JSON.stringify(value);
 }
 //#endregion
-export { NestedDynamicUseCacheError, cacheContextStorage, clearPrivateCache, getCacheContext, markAppPagePropsForUseCache, registerCachedFunction, replyToCacheKey, runWithPrivateCache };
+export { NestedDynamicUseCacheError, buildUseCacheKey, cacheContextStorage, clearPrivateCache, getCacheContext, markAppPagePropsForUseCache, registerCachedFunction, replyToCacheKey, runWithPrivateCache };

package/dist/shims/cache.d.ts

@@ -1,4 +1,4 @@
-import { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, ActionRevalidationKind, CacheLifeConfig, CacheState, UnstableCacheObservation, UnstableCacheRevalidationMode, _consumeRequestScopedCacheLife, _initRequestScopedCacheState, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, getAndClearActionRevalidationKind, getRegisteredCacheContext, markActionRevalidation, recordUnstableCacheObservation, shouldServeStaleUnstableCacheEntry } from "./cache-request-state.js";
+import { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, ActionRevalidationKind, CacheLifeConfig, CacheState, UnstableCacheObservation, UnstableCacheRevalidationMode, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _queuePendingRevalidation, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, getAndClearActionRevalidationKind, getRegisteredCacheContext, markActionRevalidation, recordUnstableCacheObservation, shouldServeStaleUnstableCacheEntry } from "./cache-request-state.js";
 import { ExecutionContextLike, getRequestExecutionContext, runWithExecutionContext } from "./request-context.js";
 import { CacheControlMetadata, CacheHandler, CacheHandlerContext, CacheHandlerValue, CachedAppPageValue, CachedFetchValue, CachedImageValue, CachedPagesValue, CachedRedirectValue, CachedRouteValue, IncrementalCacheValue, MemoryCacheHandler, NoOpCacheHandler, configureMemoryCacheHandler, getCacheHandler, getDataCacheHandler, setCacheHandler, setDataCacheHandler } from "./cache-handler.js";
 
@@ -18,7 +18,7 @@ import { CacheControlMetadata, CacheHandler, CacheHandlerContext, CacheHandlerVa
  */
 declare function revalidateTag(tag: string, profile?: string | {
   expire?: number;
-}): Promise<void>;
+}): undefined;
 /**
  * Revalidate cached data associated with a specific path.
  *
@@ -34,7 +34,7 @@ declare function revalidateTag(tag: string, profile?: string | {
  * The `type` parameter is App Router only — Pages Router does not generate
  * layout/page hierarchy tags, so only no-type invalidation applies there.
  */
-declare function revalidatePath(path: string, type?: "page" | "layout"): Promise<void>;
+declare function revalidatePath(path: string, type?: "page" | "layout"): undefined;
 /**
  * No-op shim for API compatibility.
  *
@@ -57,7 +57,7 @@ declare function refresh(): void;
  *
  * @see https://nextjs.org/docs/app/api-reference/functions/updateTag
  */
-declare function updateTag(tag: string): Promise<void>;
+declare function updateTag(tag: string): undefined;
 /**
  * Opt out of static rendering and indicate a particular component should not be cached.
  *
@@ -142,4 +142,4 @@ type UnstableCacheOptions = {
  */
 declare function unstable_cache<T extends (...args: any[]) => Promise<any>>(fn: T, keyParts?: string[], options?: UnstableCacheOptions): T;
 //#endregion
-export { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, ActionRevalidationKind, CacheControlMetadata, CacheHandler, CacheHandlerContext, CacheHandlerValue, CacheLifeConfig, CacheState, CachedAppPageValue, CachedFetchValue, CachedImageValue, CachedPagesValue, CachedRedirectValue, CachedRouteValue, type ExecutionContextLike, IncrementalCacheValue, MemoryCacheHandler, NoOpCacheHandler, UnstableCacheObservation, UnstableCacheRevalidationMode, _consumeRequestScopedCacheLife, _initRequestScopedCacheState, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLife, cacheLifeProfiles, cacheTag, configureMemoryCacheHandler, getAndClearActionRevalidationKind, getCacheHandler, getDataCacheHandler, getRegisteredCacheContext, getRequestExecutionContext, io, isInsideUnstableCacheScope, markActionRevalidation, unstable_noStore as noStore, unstable_noStore, recordUnstableCacheObservation, refresh, revalidatePath, revalidateTag, runWithExecutionContext, setCacheHandler, setDataCacheHandler, shouldServeStaleUnstableCacheEntry, unstable_cache, unstable_cacheLife, unstable_cacheTag, unstable_io, updateTag };
+export { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, ActionRevalidationKind, CacheControlMetadata, CacheHandler, CacheHandlerContext, CacheHandlerValue, CacheLifeConfig, CacheState, CachedAppPageValue, CachedFetchValue, CachedImageValue, CachedPagesValue, CachedRedirectValue, CachedRouteValue, type ExecutionContextLike, IncrementalCacheValue, MemoryCacheHandler, NoOpCacheHandler, UnstableCacheObservation, UnstableCacheRevalidationMode, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _queuePendingRevalidation, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLife, cacheLifeProfiles, cacheTag, configureMemoryCacheHandler, getAndClearActionRevalidationKind, getCacheHandler, getDataCacheHandler, getRegisteredCacheContext, getRequestExecutionContext, io, isInsideUnstableCacheScope, markActionRevalidation, unstable_noStore as noStore, unstable_noStore, recordUnstableCacheObservation, refresh, revalidatePath, revalidateTag, runWithExecutionContext, setCacheHandler, setDataCacheHandler, shouldServeStaleUnstableCacheEntry, unstable_cache, unstable_cacheLife, unstable_cacheTag, unstable_io, updateTag };

package/dist/shims/cache.js

@@ -6,9 +6,9 @@ import { getCdnCacheAdapter } from "./cdn-cache.js";
 import { fnv1a64 } from "../utils/hash.js";
 import { makeHangingPromise } from "./internal/make-hanging-promise.js";
 import { getHeadersAccessPhase, isDraftModeEnabled, markDynamicUsage } from "./headers.js";
-import { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, _consumeRequestScopedCacheLife, _initRequestScopedCacheState, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, getAndClearActionRevalidationKind, getRegisteredCacheContext, markActionRevalidation, recordUnstableCacheObservation, shouldServeStaleUnstableCacheEntry } from "./cache-request-state.js";
+import { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _queuePendingRevalidation, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLifeProfiles, getAndClearActionRevalidationKind, getRegisteredCacheContext, markActionRevalidation, recordUnstableCacheObservation, shouldServeStaleUnstableCacheEntry } from "./cache-request-state.js";
 import { encodeCacheTag, encodeCacheTags } from "../utils/encode-cache-tag.js";
-import { addCollectedRequestTags } from "./fetch-cache.js";
+import { addCollectedRequestTags, getCurrentFetchSoftTags } from "./fetch-cache.js";
 import { workUnitAsyncStorage } from "./internal/work-unit-async-storage.js";
 //#region src/shims/cache.ts
 /**
@@ -32,6 +32,14 @@ import { workUnitAsyncStorage } from "./internal/work-unit-async-storage.js";
 * target used by the generated cache-adapter module.
 */
 const _g = globalThis;
+function scheduleRevalidation(promise) {
+	const executionContext = getRequestExecutionContext();
+	const queued = _queuePendingRevalidation(promise);
+	if (executionContext) executionContext.waitUntil(promise);
+	else if (!queued) promise.catch((error) => {
+		console.error("[vinext] cache revalidation failed:", error);
+	});
+}
 /**
 * Revalidate cached data associated with a specific cache tag.
 *
@@ -45,14 +53,16 @@ const _g = globalThis;
 * @param tag - Cache tag to revalidate
 * @param profile - cacheLife profile name (e.g. 'max', 'hours') or inline { expire: number }
 */
-async function revalidateTag(tag, profile) {
+function revalidateTag(tag, profile) {
 	let durations;
 	if (typeof profile === "string") {
 		const resolved = cacheLifeProfiles[profile];
 		if (resolved) durations = { expire: resolved.expire };
 	} else if (profile && typeof profile === "object") durations = profile;
 	if (!profile || !durations || durations.expire === 0) markActionRevalidation(1);
-	await _invalidateEncodedTag(encodeCacheTag(tag), durations);
+	const encodedTag = encodeCacheTag(tag);
+	_markPendingRevalidatedTag(encodedTag);
+	return scheduleRevalidation(_invalidateEncodedTag(encodedTag, durations));
 }
 /**
 * Invalidate one already-encoded tag across both cache layers.
@@ -82,10 +92,12 @@ async function _invalidateEncodedTag(encoded, durations) {
 * The `type` parameter is App Router only — Pages Router does not generate
 * layout/page hierarchy tags, so only no-type invalidation applies there.
 */
-async function revalidatePath(path, type) {
+function revalidatePath(path, type) {
 	markActionRevalidation(1);
 	const stem = path.endsWith("/") ? path.slice(0, -1) : path;
-	await _invalidateEncodedTag(encodeCacheTag(type ? `_N_T_${stem}/${type}` : `_N_T_${stem || "/"}`));
+	const encodedTag = encodeCacheTag(type ? `_N_T_${stem}/${type}` : `_N_T_${stem || "/"}`);
+	_markPendingRevalidatedTag(encodedTag);
+	return scheduleRevalidation(_invalidateEncodedTag(encodedTag));
 }
 /**
 * No-op shim for API compatibility.
@@ -114,7 +126,9 @@ function refresh() {
 function updateTag(tag) {
 	if (getHeadersAccessPhase() !== "action") throw new Error("updateTag can only be called from within a Server Action. To invalidate cache tags in Route Handlers or other contexts, use revalidateTag instead. See more info here: https://nextjs.org/docs/app/api-reference/functions/updateTag");
 	markActionRevalidation(1);
-	return _invalidateEncodedTag(encodeCacheTag(tag));
+	const encodedTag = encodeCacheTag(tag);
+	_markPendingRevalidatedTag(encodedTag);
+	return scheduleRevalidation(_invalidateEncodedTag(encodedTag));
 }
 /**
 * Opt out of static rendering and indicate a particular component should not be cached.
@@ -386,9 +400,11 @@ function unstable_cache(fn, keyParts, options) {
 		});
 		const isDraftMode = isDraftModeEnabled();
 		if (!isDraftMode) {
-			const existing = await getDataCacheHandler().get(cacheKey, {
+			const softTags = getCurrentFetchSoftTags();
+			const existing = _hasPendingRevalidatedTag([...tags, ...softTags]) ? null : await getDataCacheHandler().get(cacheKey, {
 				kind: "FETCH",
-				tags
+				tags,
+				softTags
 			});
 			if (existing?.value && existing.value.kind === "FETCH") {
 				const cached = tryDeserializeUnstableCacheResult(existing.value.data.body);
@@ -406,4 +422,4 @@ function unstable_cache(fn, keyParts, options) {
 	return cachedFn;
 }
 //#endregion
-export { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, MemoryCacheHandler, NoOpCacheHandler, _consumeRequestScopedCacheLife, _initRequestScopedCacheState, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLife, cacheLifeProfiles, cacheTag, configureMemoryCacheHandler, getAndClearActionRevalidationKind, getCacheHandler, getDataCacheHandler, getRegisteredCacheContext, getRequestExecutionContext, io, isInsideUnstableCacheScope, markActionRevalidation, unstable_noStore as noStore, unstable_noStore, recordUnstableCacheObservation, refresh, revalidatePath, revalidateTag, runWithExecutionContext, setCacheHandler, setDataCacheHandler, shouldServeStaleUnstableCacheEntry, unstable_cache, unstable_cacheLife, unstable_cacheTag, unstable_io, updateTag };
+export { ACTION_DID_REVALIDATE_DYNAMIC_ONLY, ACTION_DID_REVALIDATE_STATIC_AND_DYNAMIC, MemoryCacheHandler, NoOpCacheHandler, _consumeRequestScopedCacheLife, _drainPendingRevalidations, _hasPendingRevalidatedTag, _initRequestScopedCacheState, _markPendingRevalidatedTag, _peekRequestScopedCacheLife, _peekUnstableCacheObservations, _queuePendingRevalidation, _registerCacheContextAccessor, _runWithCacheState, _setRequestScopedCacheLife, cacheLife, cacheLifeProfiles, cacheTag, configureMemoryCacheHandler, getAndClearActionRevalidationKind, getCacheHandler, getDataCacheHandler, getRegisteredCacheContext, getRequestExecutionContext, io, isInsideUnstableCacheScope, markActionRevalidation, unstable_noStore as noStore, unstable_noStore, recordUnstableCacheObservation, refresh, revalidatePath, revalidateTag, runWithExecutionContext, setCacheHandler, setDataCacheHandler, shouldServeStaleUnstableCacheEntry, unstable_cache, unstable_cacheLife, unstable_cacheTag, unstable_io, updateTag };

package/dist/shims/document.d.ts

@@ -1,92 +1,51 @@
 import React from "react";
+import { DocumentContext, DocumentInitialProps, DocumentProps } from "@vinext/types/next/upstream/dist/shared/lib/utils";
+import { HtmlProps } from "@vinext/types/next/upstream/dist/shared/lib/html-context.shared-runtime";
 
 //#region src/shims/document.d.ts
-declare function Html({
-  children,
-  lang,
-  ...props
-}: React.HTMLAttributes<HTMLHtmlElement> & {
+type OriginProps = {
+  nonce?: string;
+  crossOrigin?: "anonymous" | "use-credentials" | "" | undefined;
   children?: React.ReactNode;
-}): React.JSX.Element;
-/**
- * Document Head - renders <head> with children.
- * The dev server injects meta tags, styles, etc.
- *
- * Note: charset and viewport are intentionally NOT hardcoded here. Those
- * defaults are seeded by `next/head`'s `defaultHead()` and emitted alongside
- * user `<Head>` tags via `getSSRHeadHTML()`, matching Next.js's canonical
- * ordering (`<meta charset>` first, then `<meta viewport>`, then user tags,
- * all with `data-next-head=""`). See `test/e2e/next-head/index.test.ts`.
- */
-declare function Head({
-  children
-}: {
-  children?: React.ReactNode;
-}): React.JSX.Element;
-/**
- * Main - renders the page content container.
- */
-declare function Main(): React.JSX.Element;
-/**
- * NextScript - renders a placeholder that the dev-server replaces with
- * actual hydration scripts (__NEXT_DATA__ + entry module).
- * Uses dangerouslySetInnerHTML so the HTML comment survives renderToString.
- */
-declare function NextScript(): React.JSX.Element;
-/**
- * Stand-ins for Next.js's `DocumentContext` / `DocumentInitialProps`.
- * The signatures match Next.js so custom `_document.tsx` subclasses can use
- * `ctx.renderPage()` enhancers and delegate through
- * `await Document.getInitialProps(ctx)` with the expected public types.
- *
- * @see https://github.com/vercel/next.js/blob/canary/packages/next/src/shared/lib/utils.ts
- */
-type DocumentContext = {
-  renderPage: (options?: {
-    enhanceApp?: (App: React.ComponentType<{
-      children?: React.ReactNode;
-    }>) => React.ComponentType<{
-      children?: React.ReactNode;
-    }>;
-    enhanceComponent?: (Comp: React.ComponentType<unknown>) => React.ComponentType<unknown>;
-  } | ((Comp: React.ComponentType<unknown>) => React.ComponentType<unknown>)) => DocumentInitialProps | Promise<DocumentInitialProps>;
-  defaultGetInitialProps: (ctx: DocumentContext, options?: {
-    nonce?: string;
-  }) => Promise<DocumentInitialProps>;
-  pathname?: string;
-  query?: Record<string, string | string[] | undefined>;
-  asPath?: string;
-  err?: any;
 };
-type DocumentInitialProps = {
-  html: string;
-  head?: ReadonlyArray<React.ReactElement>;
-  styles?: React.ReactElement[] | Iterable<React.ReactNode> | React.ReactElement;
+type DocumentFiles = {
+  sharedFiles: readonly string[];
+  pageFiles: readonly string[];
+  allFiles: readonly string[];
 };
-/**
- * Default Document component — also the base class user `_document.tsx` files
- * `extend`. Must be a class (not a function) to match Next.js's `next/document`
- * default export so `class MyDocument extends Document` produces a constructible
- * class that React can instantiate during SSR. Returning a function here breaks
- * any user `_document.tsx` that uses the class-based form because `extends`
- * against a non-constructor produces a class that can only be called without
- * `new`, which React refuses to do.
- *
- * @see https://github.com/vercel/next.js/blob/canary/packages/next/src/pages/_document.tsx
- * Ported behavior: Next.js's default `Document` is a `class Document extends
- * React.Component`. Custom documents extend it and override `getInitialProps`
- * and `render`. Generic default matches Next.js (`P = {}`).
- */
-declare class Document<P = {}> extends React.Component<P & {
-  children?: React.ReactNode;
-}> {
-  /**
-   * `getInitialProps` is invoked by the SSR pipeline. The runtime-provided
-   * `ctx.defaultGetInitialProps()` owns the page render and style collection,
-   * matching Next.js's canonical CSS-in-JS integration path.
-   */
+type HeadProps = OriginProps & React.ComponentPropsWithoutRef<"head">;
+declare function Html(props: React.DetailedHTMLProps<React.HtmlHTMLAttributes<HTMLHtmlElement>, HTMLHtmlElement>): React.ReactElement;
+interface Head {
+  context: HtmlProps;
+}
+declare class Head extends React.Component<HeadProps> {
+  static contextType: React.Context<HtmlProps | undefined>;
+  getCssLinks(_files: DocumentFiles): React.ReactElement[] | null;
+  getPreloadDynamicChunks(): Array<React.ReactElement | null>;
+  getPreloadMainLinks(_files: DocumentFiles): React.ReactElement[] | null;
+  getBeforeInteractiveInlineScripts(): React.ReactElement[];
+  getDynamicChunks(_files: DocumentFiles): Array<React.ReactElement | null>;
+  getPreNextScripts(): React.ReactElement;
+  getScripts(_files: DocumentFiles): React.ReactElement[];
+  getPolyfillScripts(): React.ReactElement[];
+  render(): React.ReactElement;
+}
+declare function Main(): React.ReactElement;
+interface NextScript {
+  context: HtmlProps;
+}
+declare class NextScript extends React.Component<OriginProps> {
+  static contextType: React.Context<HtmlProps | undefined>;
+  getDynamicChunks(_files: DocumentFiles): Array<React.ReactElement | null>;
+  getPreNextScripts(): React.ReactElement;
+  getScripts(_files: DocumentFiles): React.ReactElement[];
+  getPolyfillScripts(): React.ReactElement[];
+  static getInlineScriptSource(context: Readonly<HtmlProps>): string;
+  render(): React.ReactElement;
+}
+declare class Document<P = {}> extends React.Component<DocumentProps & P> {
   static getInitialProps(ctx: DocumentContext): Promise<DocumentInitialProps>;
-  render(): React.ReactNode;
+  render(): React.ReactElement;
 }
 //#endregion
-export { DocumentContext, DocumentInitialProps, Head, Html, Main, NextScript, Document as default };
+export { type DocumentContext, type DocumentInitialProps, type DocumentProps, Head, Html, Main, NextScript, OriginProps, Document as default };

package/dist/shims/document.js

@@ -1,70 +1,79 @@
 import React from "react";
-import { jsx, jsxs } from "react/jsx-runtime";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 //#region src/shims/document.tsx
 /**
 * next/document shim
 *
-* Provides Html, Head, Main, NextScript components for custom _document.tsx.
-* During SSR these render placeholder markers that the dev server replaces
-* with actual content.
+* Provides Html, Head, Main, NextScript, and the class-based Document API for
+* custom Pages Router documents. Vinext's renderer replaces the Main and
+* NextScript placeholders with the rendered page and hydration scripts.
 */
-function Html({ children, lang, ...props }) {
-	return /* @__PURE__ */ jsx("html", {
-		lang,
-		...props,
-		children
-	});
-}
-/**
-* Document Head - renders <head> with children.
-* The dev server injects meta tags, styles, etc.
-*
-* Note: charset and viewport are intentionally NOT hardcoded here. Those
-* defaults are seeded by `next/head`'s `defaultHead()` and emitted alongside
-* user `<Head>` tags via `getSSRHeadHTML()`, matching Next.js's canonical
-* ordering (`<meta charset>` first, then `<meta viewport>`, then user tags,
-* all with `data-next-head=""`). See `test/e2e/next-head/index.test.ts`.
-*/
-function Head({ children }) {
-	return /* @__PURE__ */ jsx("head", { children });
+const HtmlContext = React.createContext(void 0);
+function Html(props) {
+	return /* @__PURE__ */ jsx("html", { ...props });
 }
-/**
-* Main - renders the page content container.
-*/
+var Head = class extends React.Component {
+	static contextType = HtmlContext;
+	getCssLinks(_files) {
+		return null;
+	}
+	getPreloadDynamicChunks() {
+		return [];
+	}
+	getPreloadMainLinks(_files) {
+		return null;
+	}
+	getBeforeInteractiveInlineScripts() {
+		return [];
+	}
+	getDynamicChunks(_files) {
+		return [];
+	}
+	getPreNextScripts() {
+		return /* @__PURE__ */ jsx(Fragment$1, {});
+	}
+	getScripts(_files) {
+		return [];
+	}
+	getPolyfillScripts() {
+		return [];
+	}
+	render() {
+		const { children, ...props } = this.props;
+		return /* @__PURE__ */ jsx("head", {
+			...props,
+			children
+		});
+	}
+};
 function Main() {
 	return /* @__PURE__ */ jsx("div", {
 		id: "__next",
 		dangerouslySetInnerHTML: { __html: "__NEXT_MAIN__" }
 	});
 }
-/**
-* NextScript - renders a placeholder that the dev-server replaces with
-* actual hydration scripts (__NEXT_DATA__ + entry module).
-* Uses dangerouslySetInnerHTML so the HTML comment survives renderToString.
-*/
-function NextScript() {
-	return /* @__PURE__ */ jsx("span", { dangerouslySetInnerHTML: { __html: "<!-- __NEXT_SCRIPTS__ -->" } });
-}
-/**
-* Default Document component — also the base class user `_document.tsx` files
-* `extend`. Must be a class (not a function) to match Next.js's `next/document`
-* default export so `class MyDocument extends Document` produces a constructible
-* class that React can instantiate during SSR. Returning a function here breaks
-* any user `_document.tsx` that uses the class-based form because `extends`
-* against a non-constructor produces a class that can only be called without
-* `new`, which React refuses to do.
-*
-* @see https://github.com/vercel/next.js/blob/canary/packages/next/src/pages/_document.tsx
-* Ported behavior: Next.js's default `Document` is a `class Document extends
-* React.Component`. Custom documents extend it and override `getInitialProps`
-* and `render`. Generic default matches Next.js (`P = {}`).
-*/
+var NextScript = class extends React.Component {
+	static contextType = HtmlContext;
+	getDynamicChunks(_files) {
+		return [];
+	}
+	getPreNextScripts() {
+		return /* @__PURE__ */ jsx(Fragment$1, {});
+	}
+	getScripts(_files) {
+		return [];
+	}
+	getPolyfillScripts() {
+		return [];
+	}
+	static getInlineScriptSource(context) {
+		return JSON.stringify(context.__NEXT_DATA__);
+	}
+	render() {
+		return /* @__PURE__ */ jsx("span", { dangerouslySetInnerHTML: { __html: "<!-- __NEXT_SCRIPTS__ -->" } });
+	}
+};
 var Document = class extends React.Component {
-	/**
-	* `getInitialProps` is invoked by the SSR pipeline. The runtime-provided
-	* `ctx.defaultGetInitialProps()` owns the page render and style collection,
-	* matching Next.js's canonical CSS-in-JS integration path.
-	*/
 	static getInitialProps(ctx) {
 		return ctx.defaultGetInitialProps(ctx);
 	}