vinext 1.0.0-beta.1 → 1.0.0-beta.3

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));
@@ -319,10 +334,13 @@ function registerCachedFunction(fn, id, variant, options = {}) {
 		configurable: true
 	});
 	cachedFn[USE_CACHE_FUNCTION_SYMBOL] = true;
+	if (options.acceptsSecondArgument !== void 0) Reflect.set(cachedFn, USE_CACHE_ACCEPTS_SECOND_ARGUMENT_SYMBOL, options.acceptsSecondArgument);
 	return cachedFn;
 }
 /** @internal Symbol used to identify "use cache" wrapper functions. */
 const USE_CACHE_FUNCTION_SYMBOL = Symbol.for("vinext.useCacheFunction");
+/** @internal Symbol carrying transform-derived cached function argument metadata. */
+const USE_CACHE_ACCEPTS_SECOND_ARGUMENT_SYMBOL = Symbol.for("vinext.useCacheAcceptsSecondArgument");
 function throwPrivateUseCacheInsidePublicUseCacheError() {
 	const error = /* @__PURE__ */ new Error("\"use cache: private\" must not be used within \"use cache\". It can only be nested inside of another \"use cache: private\".");
 	const ctx = getRequestContext();
@@ -332,7 +350,7 @@ function throwPrivateUseCacheInsidePublicUseCacheError() {
 function recordRequestScopedCacheControl(cacheControl) {
 	if (cacheControl === void 0) return;
 	_setRequestScopedCacheLife({
-		revalidate: cacheControl.revalidate,
+		revalidate: cacheControl.revalidate === false ? void 0 : cacheControl.revalidate,
 		expire: cacheControl.expire
 	});
 }
@@ -449,4 +467,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

@@ -4,11 +4,11 @@ import { getRequestExecutionContext, runWithExecutionContext } from "./request-c
 import { MemoryCacheHandler, NoOpCacheHandler, configureMemoryCacheHandler, getCacheHandler, getDataCacheHandler, setCacheHandler, setDataCacheHandler } from "./cache-handler.js";
 import { getCdnCacheAdapter } from "./cdn-cache.js";
 import { fnv1a64 } from "../utils/hash.js";
+import { encodeCacheTag, encodeCacheTags } from "../utils/encode-cache-tag.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 { encodeCacheTag, encodeCacheTags } from "../utils/encode-cache-tag.js";
-import { addCollectedRequestTags } from "./fetch-cache.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 { 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);
 	}

package/dist/shims/dynamic.d.ts

@@ -1,28 +1,7 @@
-import { ComponentType } from "react";
+import React, { ComponentType } from "react";
+import { DynamicOptions, DynamicOptionsLoadingProps, LoadableComponent, LoadableFn, LoadableGeneratedOptions, LoadableOptions, Loader, LoaderComponent, LoaderMap } from "@vinext/types/next/upstream/dynamic";
 
 //#region src/shims/dynamic.d.ts
-type DynamicLoadingProps = {
-  error?: Error | null;
-  isLoading?: boolean;
-  pastDelay?: boolean;
-  retry?: () => void;
-  timedOut?: boolean;
-};
-type ComponentModule<P> = {
-  default: ComponentType<P>;
-};
-type LoaderComponent<P> = Promise<ComponentModule<P> | ComponentType<P>>;
-type LoaderFn<P> = () => LoaderComponent<P>;
-type DynamicOptions<P> = {
-  loading?: ComponentType<DynamicLoadingProps>;
-  loader?: Loader<P>;
-  loadableGenerated?: {
-    modules?: readonly string[];
-  };
-  modules?: readonly string[];
-  ssr?: boolean;
-};
-type Loader<P> = LoaderFn<P> | LoaderComponent<P>;
 type DynamicInput<P> = DynamicOptions<P> | Loader<P>;
 /**
  * Wait for all pending dynamic() preloads to resolve, then clear the queue.
@@ -30,6 +9,7 @@ type DynamicInput<P> = DynamicOptions<P> | Loader<P>;
  * No-op for the App Router path which uses React.lazy + Suspense.
  */
 declare function flushPreloads(): Promise<void[]>;
-declare function dynamic<P extends object = object>(dynamicInput: DynamicInput<P>, options?: DynamicOptions<P>): ComponentType<P>;
+declare function dynamic<P = {}>(dynamicInput: DynamicInput<P>, options?: DynamicOptions<P>): ComponentType<P>;
+declare function noSSR<P = {}>(LoadableInitializer: LoadableFn<P>, loadableOptions: DynamicOptions<P>): React.ComponentType<P>;
 //#endregion
-export { dynamic as default, flushPreloads };
+export { type DynamicOptions, type DynamicOptionsLoadingProps, type LoadableComponent, type LoadableFn, type LoadableGeneratedOptions, type LoadableOptions, type Loader, type LoaderComponent, type LoaderMap, dynamic as default, flushPreloads, noSSR };

package/dist/shims/dynamic.js

@@ -68,6 +68,9 @@ function useRetryableLazyComponent(loader, initialLazyComponent) {
 		retryKey
 	};
 }
+function createElementWithProps(Component, props) {
+	return React.createElement(Component, props);
+}
 /**
 * Lightweight error boundary that renders the loading component with the error
 * when a dynamic() loader rejects. Without this, loader failures would propagate
@@ -122,9 +125,14 @@ function flushPreloads() {
 	return Promise.all(pending);
 }
 function dynamic(dynamicInput, options) {
-	const { loader: dynamicLoader, loadableGenerated, loading: LoadingComponent, modules, ssr = true } = normalizeDynamicOptions(dynamicInput, options);
+	const normalizedOptions = normalizeDynamicOptions(dynamicInput, options);
+	const { loader: dynamicLoader, loadableGenerated, loading: LoadingComponent, ssr = true } = normalizedOptions;
+	if (dynamicLoader && typeof dynamicLoader === "object" && !(dynamicLoader instanceof Promise)) throw new Error("next/dynamic loader maps are not supported by vinext");
 	const loader = dynamicLoader ? normalizeLoader(dynamicLoader) : () => Promise.resolve(() => null);
-	const preloadModuleIds = loadableGenerated?.modules ?? modules;
+	const generatedModules = loadableGenerated?.modules;
+	const optionModules = normalizedOptions.modules;
+	const configuredModules = generatedModules ?? optionModules;
+	const preloadModuleIds = typeof configuredModules === "function" ? Object.keys(configuredModules()) : configuredModules;
 	if (!ssr) {
 		if (isServer) {
 			const SSRFalse = (_props) => LoadingComponent ? React.createElement(LoadingComponent, createDynamicLoadingProps()) : null;
@@ -138,7 +146,7 @@ function dynamic(dynamicInput, options) {
 			React.useEffect(() => setMounted(true), []);
 			if (!mounted) return LoadingComponent ? React.createElement(LoadingComponent, createDynamicLoadingProps({ retry })) : null;
 			const fallback = LoadingComponent ? React.createElement(LoadingComponent, createDynamicLoadingProps({ retry })) : null;
-			const lazyElement = React.createElement(LazyComponent, props);
+			const lazyElement = createElementWithProps(LazyComponent, props);
 			let content = lazyElement;
 			if (LoadingComponent) {
 				const ErrorBoundary = getDynamicErrorBoundary();
@@ -157,8 +165,7 @@ function dynamic(dynamicInput, options) {
 		if (typeof React.lazy !== "function") {
 			const AsyncServerDynamic = async (props) => {
 				const mod = await loader();
-				const Component = "default" in mod ? mod.default : mod;
-				return React.createElement(Component, props);
+				return createElementWithProps("default" in mod ? mod.default : mod, props);
 			};
 			AsyncServerDynamic.displayName = "DynamicAsyncServer";
 			return AsyncServerDynamic;
@@ -166,7 +173,7 @@ function dynamic(dynamicInput, options) {
 		const LazyServer = createLazyComponent(loader);
 		const ServerDynamic = (props) => {
 			const fallback = LoadingComponent ? React.createElement(LoadingComponent, createDynamicLoadingProps()) : null;
-			const lazyElement = React.createElement(LazyServer, props);
+			const lazyElement = createElementWithProps(LazyServer, props);
 			let content = lazyElement;
 			if (LoadingComponent) {
 				const ErrorBoundary = getDynamicErrorBoundary();
@@ -185,7 +192,7 @@ function dynamic(dynamicInput, options) {
 	const ClientDynamic = (props) => {
 		const { LazyComponent, retry, retryKey } = useRetryableLazyComponent(loader, InitialLazyComponent);
 		const fallback = LoadingComponent ? React.createElement(LoadingComponent, createDynamicLoadingProps({ retry })) : null;
-		const lazyElement = React.createElement(LazyComponent, props);
+		const lazyElement = createElementWithProps(LazyComponent, props);
 		let content = lazyElement;
 		if (LoadingComponent) {
 			const ErrorBoundary = getDynamicErrorBoundary();
@@ -200,5 +207,19 @@ function dynamic(dynamicInput, options) {
 	ClientDynamic.displayName = "DynamicClient";
 	return ClientDynamic;
 }
+function noSSR(LoadableInitializer, loadableOptions) {
+	delete loadableOptions.webpack;
+	delete loadableOptions.modules;
+	if (!isServer) return LoadableInitializer(loadableOptions);
+	const Loading = loadableOptions.loading;
+	const NoSSR = () => React.createElement(Loading, {
+		error: null,
+		isLoading: true,
+		pastDelay: false,
+		timedOut: false
+	});
+	NoSSR.displayName = "NoSSR";
+	return NoSSR;
+}
 //#endregion
-export { dynamic as default, flushPreloads };
+export { dynamic as default, flushPreloads, noSSR };

package/dist/shims/error.d.ts

@@ -27,7 +27,7 @@ declare class ErrorComponent<P = {}> extends React.Component<P & ErrorProps> {
   render(): React.ReactElement;
 }
 type ErrorInfo = {
-  error: unknown;
+  error: Error;
   reset: () => void;
   unstable_retry: () => void;
 };

package/dist/shims/error.js

@@ -1,8 +1,8 @@
 import { AppRouterContext } from "./internal/app-router-context.js";
 import { RouterContext } from "./internal/router-context.js";
-import Head from "./head.js";
 import { isNextRouterError } from "./navigation-errors.js";
 import "./navigation.js";
+import Head from "./head.js";
 import { useUntrackedPathname } from "./internal/navigation-untracked.js";
 import React from "react";
 //#region src/shims/error.tsx
@@ -119,7 +119,7 @@ var _CatchError = class extends React.Component {
 		if (this.state.error) {
 			const Fallback = this.props.fallback;
 			const errorInfo = {
-				error: this.state.error.thrownValue,
+				error: this.state.error.thrownValue instanceof Error ? this.state.error.thrownValue : new Error(String(this.state.error.thrownValue)),
 				reset: this.reset,
 				unstable_retry: this.unstable_retry
 			};