@qzsy/vinext 0.1.7

package/dist/shims/slot.d.ts

@@ -0,0 +1,45 @@
+import { AppElementValue, AppElements, UNMATCHED_SLOT } from "../server/app-elements-wire.js";
+import * as React$1 from "react";
+
+//#region src/shims/slot.d.ts
+/**
+ * Holds resolved AppElements (not a Promise). React 19's use(Promise) during
+ * hydration triggers "async Client Component" for native Promises that lack
+ * React's internal .status property. Storing resolved values sidesteps this.
+ */
+declare const ElementsContext: React$1.Context<Readonly<Record<string, AppElementValue>>>;
+declare const ChildrenContext: React$1.Context<React$1.ReactNode>;
+declare const ParallelSlotsContext: React$1.Context<Readonly<Record<string, React$1.ReactNode>> | null>;
+declare const BfcacheStateKeyMapContext: React$1.Context<Readonly<Record<string, string>>>;
+type BfcacheSlotEntry = {
+  content: React$1.ReactNode;
+  elements?: AppElements;
+  segmentId?: string;
+  stateKey: string;
+  stateKeyMap?: Readonly<Record<string, string>>;
+};
+type MergeElementsOptions = {
+  clearAbsentSlots?: boolean;
+  preserveAbsentSlots?: boolean;
+  preserveElementIds?: readonly string[];
+  preservePreviousSlotIds?: readonly string[];
+};
+declare function updateBfcacheSlotEntryOrder(previousOrder: readonly string[], activeStateKey: string, maxEntries?: number): string[];
+declare function mergeElements(prev: AppElements, next: AppElements, options?: MergeElementsOptions | boolean): AppElements;
+declare function Slot({
+  id,
+  children,
+  parallelSlots
+}: {
+  id: string;
+  children?: React$1.ReactNode;
+  parallelSlots?: Readonly<Record<string, React$1.ReactNode>>;
+}): React$1.JSX.Element | null;
+declare function Children(): React$1.ReactNode;
+declare function ParallelSlot({
+  name
+}: {
+  name: string;
+}): string | number | bigint | boolean | React$1.ReactElement<unknown, string | React$1.JSXElementConstructor<any>> | Iterable<React$1.ReactNode> | Promise<string | number | bigint | boolean | React$1.ReactPortal | React$1.ReactElement<unknown, string | React$1.JSXElementConstructor<any>> | Iterable<React$1.ReactNode> | null | undefined> | null;
+//#endregion
+export { BfcacheSlotEntry, BfcacheStateKeyMapContext, Children, ChildrenContext, ElementsContext, ParallelSlot, ParallelSlotsContext, Slot, UNMATCHED_SLOT, mergeElements, updateBfcacheSlotEntryOrder };

package/dist/shims/slot.js

@@ -0,0 +1,230 @@
+"use client";
+import { AppElementsWire, UNMATCHED_SLOT } from "../server/app-elements-wire.js";
+import "../server/app-elements.js";
+import { getBfcacheIdMapContext, getBfcacheSegmentIdContext } from "./navigation-context-state.js";
+import { notFound } from "./navigation-errors.js";
+import "./navigation-server.js";
+import * as React$1 from "react";
+import { Fragment as Fragment$1, jsx } from "react/jsx-runtime";
+//#region src/shims/slot.tsx
+const EMPTY_ELEMENTS = Object.freeze({});
+const warnedMissingEntryIds = /* @__PURE__ */ new Set();
+const warnedTransportMetadataEntryIds = /* @__PURE__ */ new Set();
+/**
+* Holds resolved AppElements (not a Promise). React 19's use(Promise) during
+* hydration triggers "async Client Component" for native Promises that lack
+* React's internal .status property. Storing resolved values sidesteps this.
+*/
+const ElementsContext = React$1.createContext(EMPTY_ELEMENTS);
+const ChildrenContext = React$1.createContext(null);
+const ParallelSlotsContext = React$1.createContext(null);
+const BfcacheIdMapContext = getBfcacheIdMapContext();
+const BfcacheSegmentIdContext = getBfcacheSegmentIdContext();
+const EMPTY_BFCACHE_STATE_KEYS = Object.freeze({});
+const MAX_BFCACHE_SLOT_ENTRIES_WITH_CACHE_COMPONENTS = 3;
+const MAX_BFCACHE_SLOT_ENTRIES_WITHOUT_CACHE_COMPONENTS = 1;
+const BfcacheStateKeyMapContext = React$1.createContext(EMPTY_BFCACHE_STATE_KEYS);
+function isCacheComponentsEnabled() {
+	return String(process.env.__NEXT_CACHE_COMPONENTS) === "true";
+}
+function getBfcacheSlotEntryLimit() {
+	return isCacheComponentsEnabled() ? MAX_BFCACHE_SLOT_ENTRIES_WITH_CACHE_COMPONENTS : MAX_BFCACHE_SLOT_ENTRIES_WITHOUT_CACHE_COMPONENTS;
+}
+function normalizeBfcacheSlotEntryLimit(maxEntries) {
+	if (!Number.isFinite(maxEntries)) return 1;
+	return Math.max(1, Math.trunc(maxEntries));
+}
+function updateBfcacheSlotEntryOrder(previousOrder, activeStateKey, maxEntries = getBfcacheSlotEntryLimit()) {
+	const entryLimit = normalizeBfcacheSlotEntryLimit(maxEntries);
+	const nextOrder = [activeStateKey];
+	for (const stateKey of previousOrder) {
+		if (nextOrder.length >= entryLimit) break;
+		if (stateKey === activeStateKey) continue;
+		nextOrder.push(stateKey);
+	}
+	return nextOrder;
+}
+function pruneBfcacheSlotEntrySnapshots(snapshotsByStateKey, retainedOrder) {
+	const retainedKeys = new Set(retainedOrder);
+	for (const stateKey of snapshotsByStateKey.keys()) if (!retainedKeys.has(stateKey)) snapshotsByStateKey.delete(stateKey);
+}
+function haveSameBfcacheSlotEntryOrder(left, right) {
+	if (left.length !== right.length) return false;
+	for (let index = 0; index < left.length; index++) if (left[index] !== right[index]) return false;
+	return true;
+}
+function isLayoutFlagsValue(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const entries = Object.values(value);
+	return entries.length > 0 && entries.every((entry) => entry === "s" || entry === "d");
+}
+function isArtifactCompatibilityEnvelopeValue(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	return "schemaVersion" in value && "appElementsSchemaVersion" in value && "rscPayloadSchemaVersion" in value && "graphVersion" in value && "deploymentVersion" in value && "rootBoundaryId" in value && "renderEpoch" in value;
+}
+function isSlotBindingValue(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	return "ownerLayoutId" in value && "slotId" in value && "state" in value;
+}
+function isSlotBindingListValue(value) {
+	return Array.isArray(value) && value.length > 0 && value.every(isSlotBindingValue);
+}
+function isSkippedLayoutIdsMetadataValue(id, value) {
+	return id === "__skippedLayoutIds" && Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+function isInterceptionMetadataValue(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	return "sourceMatchedUrl" in value && typeof value.sourceMatchedUrl === "string" && "sourceRouteId" in value && typeof value.sourceRouteId === "string" && "slotId" in value && typeof value.slotId === "string" && "targetMatchedUrl" in value && typeof value.targetMatchedUrl === "string" && "targetRouteId" in value && typeof value.targetRouteId === "string";
+}
+function isCacheEntryReuseProofValue(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	return "kind" in value && value.kind === "runtime-cache-entry" && "decision" in value;
+}
+function isTransportMetadataValue(id, value) {
+	return isLayoutFlagsValue(value) || isArtifactCompatibilityEnvelopeValue(value) || isCacheEntryReuseProofValue(value) || isInterceptionMetadataValue(value) || isSkippedLayoutIdsMetadataValue(id, value) || isSlotBindingListValue(value);
+}
+function warnTransportMetadataEntry(id) {
+	if (process.env.NODE_ENV === "production") return;
+	if (warnedTransportMetadataEntryIds.has(id)) return;
+	warnedTransportMetadataEntryIds.add(id);
+	console.warn("[vinext] Transport metadata value found under App Router render entry: " + id);
+}
+/**
+* Provider stack for Activity-retained BFCache entries. Each retained entry
+* re-provides the elements, state-key map, and segment id it was captured with,
+* falling back to the live boundary values for entries that predate per-entry
+* capture.
+*/
+function BfcacheEntryProviders({ entry, fallbackElements, fallbackSegmentId, fallbackStateKeyMap, SegmentContext }) {
+	return /* @__PURE__ */ jsx(BfcacheStateKeyMapContext.Provider, {
+		value: entry.stateKeyMap ?? fallbackStateKeyMap,
+		children: /* @__PURE__ */ jsx(ElementsContext.Provider, {
+			value: entry.elements ?? fallbackElements,
+			children: /* @__PURE__ */ jsx(SegmentContext.Provider, {
+				value: entry.segmentId ?? fallbackSegmentId,
+				children: entry.content
+			})
+		})
+	});
+}
+function useBfcacheSlotEntries(activeEntry) {
+	const snapshotsByStateKey = React$1.useRef(/* @__PURE__ */ new Map());
+	const [entryOrder, setEntryOrder] = React$1.useState(() => [activeEntry.stateKey]);
+	snapshotsByStateKey.current.set(activeEntry.stateKey, activeEntry);
+	const nextOrder = updateBfcacheSlotEntryOrder(entryOrder, activeEntry.stateKey);
+	const orderChanged = !haveSameBfcacheSlotEntryOrder(entryOrder, nextOrder);
+	const renderOrder = orderChanged ? nextOrder : entryOrder;
+	pruneBfcacheSlotEntrySnapshots(snapshotsByStateKey.current, renderOrder);
+	if (process.env.NODE_ENV !== "production" && !snapshotsByStateKey.current.has(activeEntry.stateKey)) throw new Error("BFCache Activity slot is missing the active entry snapshot");
+	if (orderChanged) setEntryOrder(nextOrder);
+	return renderOrder.map((stateKey) => snapshotsByStateKey.current.get(stateKey)).filter((entry) => entry !== void 0);
+}
+function BfcacheActivitySlotBoundary({ activeStateKey, content, elements, id, SegmentContext, stateKeyMap }) {
+	return /* @__PURE__ */ jsx(Fragment$1, { children: useBfcacheSlotEntries({
+		content,
+		elements,
+		segmentId: id,
+		stateKey: activeStateKey,
+		stateKeyMap
+	}).map((entry) => /* @__PURE__ */ jsx(React$1.Activity, {
+		mode: entry.stateKey === activeStateKey ? "visible" : "hidden",
+		children: /* @__PURE__ */ jsx(BfcacheEntryProviders, {
+			entry,
+			fallbackElements: elements,
+			fallbackSegmentId: id,
+			fallbackStateKeyMap: stateKeyMap,
+			SegmentContext
+		})
+	}, entry.stateKey)) });
+}
+function BfcacheSlotBoundary({ content, id }) {
+	const SegmentContext = BfcacheSegmentIdContext;
+	const elements = React$1.useContext(ElementsContext);
+	const stateKeyMap = React$1.useContext(BfcacheStateKeyMapContext);
+	const activeStateKey = stateKeyMap[id];
+	if (!SegmentContext) return /* @__PURE__ */ jsx(Fragment$1, { children: content });
+	if (activeStateKey === void 0) return /* @__PURE__ */ jsx(SegmentContext.Provider, {
+		value: id,
+		children: content
+	});
+	if (!isCacheComponentsEnabled()) return /* @__PURE__ */ jsx(SegmentContext.Provider, {
+		value: id,
+		children: content
+	});
+	return /* @__PURE__ */ jsx(BfcacheActivitySlotBoundary, {
+		activeStateKey,
+		content,
+		elements,
+		id,
+		SegmentContext,
+		stateKeyMap
+	});
+}
+function mergeElements(prev, next, options = {}) {
+	const clearAbsentSlots = typeof options === "boolean" ? options : options.clearAbsentSlots ?? false;
+	const preserveAbsentSlots = typeof options === "boolean" ? !options : options.preserveAbsentSlots ?? true;
+	const preserveElementIds = typeof options === "boolean" ? [] : options.preserveElementIds ?? [];
+	const preservePreviousSlotIds = typeof options === "boolean" ? [] : options.preservePreviousSlotIds ?? [];
+	const merged = { ...next };
+	for (const id of preserveElementIds) {
+		if (Object.hasOwn(merged, id)) continue;
+		if (Object.hasOwn(prev, id)) {
+			const value = prev[id];
+			if (value !== void 0) merged[id] = value;
+		}
+	}
+	const slotKeys = new Set([...Object.keys(prev), ...Object.keys(next)].filter((key) => AppElementsWire.isSlotId(key)));
+	if (clearAbsentSlots) {
+		for (const key of slotKeys) if (!Object.hasOwn(next, key)) delete merged[key];
+	} else if (preserveAbsentSlots) {
+		for (const key of slotKeys) if (!Object.hasOwn(merged, key) && Object.hasOwn(prev, key)) {
+			const value = prev[key];
+			if (value !== void 0) merged[key] = value;
+		}
+	}
+	for (const id of preservePreviousSlotIds) {
+		if (!AppElementsWire.isSlotId(id)) continue;
+		if (!Object.hasOwn(prev, id)) continue;
+		const value = prev[id];
+		if (value !== void 0 && value !== UNMATCHED_SLOT) merged[id] = value;
+	}
+	return merged;
+}
+function Slot({ id, children, parallelSlots }) {
+	const elements = React$1.useContext(ElementsContext);
+	if (!Object.hasOwn(elements, id)) {
+		if (process.env.NODE_ENV !== "production" && !AppElementsWire.isSlotId(id)) {
+			if (!warnedMissingEntryIds.has(id)) {
+				warnedMissingEntryIds.add(id);
+				console.warn("[vinext] Missing App Router element entry during render: " + id);
+			}
+		}
+		return null;
+	}
+	const element = elements[id];
+	if (isTransportMetadataValue(id, element)) {
+		warnTransportMetadataEntry(id);
+		return null;
+	}
+	if (element === UNMATCHED_SLOT) notFound();
+	if (element === null) return null;
+	const content = /* @__PURE__ */ jsx(ParallelSlotsContext.Provider, {
+		value: parallelSlots ?? null,
+		children: /* @__PURE__ */ jsx(ChildrenContext.Provider, {
+			value: children ?? null,
+			children: element
+		})
+	});
+	return BfcacheIdMapContext && BfcacheSegmentIdContext ? /* @__PURE__ */ jsx(BfcacheSlotBoundary, {
+		id,
+		content
+	}) : content;
+}
+function Children() {
+	return React$1.useContext(ChildrenContext);
+}
+function ParallelSlot({ name }) {
+	return React$1.useContext(ParallelSlotsContext)?.[name] ?? null;
+}
+//#endregion
+export { BfcacheStateKeyMapContext, Children, ChildrenContext, ElementsContext, ParallelSlot, ParallelSlotsContext, Slot, UNMATCHED_SLOT, mergeElements, updateBfcacheSlotEntryOrder };

package/dist/shims/thenable-params.d.ts

@@ -0,0 +1,11 @@
+//#region src/shims/thenable-params.d.ts
+declare const WELL_KNOWN_PROPERTIES: readonly ["hasOwnProperty", "isPrototypeOf", "propertyIsEnumerable", "toString", "valueOf", "toLocaleString", "then", "catch", "finally", "status", "value", "error", "displayName", "_debugInfo", "toJSON", "$$typeof", "__esModule", "@@iterator"];
+type WellKnownProperty = (typeof WELL_KNOWN_PROPERTIES)[number];
+type ThenableParams<T extends Record<string, unknown>> = Promise<T> & Omit<T, WellKnownProperty>;
+type ThenableParamsObserver = Readonly<{
+  observeParamAccess: (keys: readonly string[]) => void;
+  observeReactPromiseStatus?: boolean;
+}>;
+declare function makeThenableParams<T extends Record<string, unknown>>(obj: T, observer?: ThenableParamsObserver): ThenableParams<T>;
+//#endregion
+export { ThenableParams, ThenableParamsObserver, makeThenableParams };

package/dist/shims/thenable-params.js

@@ -0,0 +1,176 @@
+import { createPprFallbackShellSuspensePromiseForState, getPprFallbackShellState } from "./ppr-fallback-shell.js";
+//#region src/shims/thenable-params.ts
+function hasParamProperty(obj, prop) {
+	return Object.prototype.hasOwnProperty.call(obj, prop);
+}
+const wellKnownProperties = new Set([
+	"hasOwnProperty",
+	"isPrototypeOf",
+	"propertyIsEnumerable",
+	"toString",
+	"valueOf",
+	"toLocaleString",
+	"then",
+	"catch",
+	"finally",
+	"status",
+	"value",
+	"error",
+	"displayName",
+	"_debugInfo",
+	"toJSON",
+	"$$typeof",
+	"__esModule",
+	"@@iterator"
+]);
+function isWellKnownProperty(prop) {
+	return wellKnownProperties.has(prop);
+}
+function observeParamKeys(observer, keys) {
+	if (observer) observer.observeParamAccess(keys);
+}
+function observeAllParamKeys(observer, plain) {
+	observeParamKeys(observer, Object.keys(plain));
+}
+function observeReadableParamKeys(observer, plain) {
+	observeParamKeys(observer, Object.keys(plain).filter((key) => !isWellKnownProperty(key)));
+}
+function isPromiseContinuation(prop) {
+	return prop === "then" || prop === "catch" || prop === "finally";
+}
+/**
+* Build a proxy around `plain` that preserves fallback-key suspension.
+* This is the value `await params` resolves to during fallback-shell
+* prerendering. Known params are readable synchronously; fallback params
+* suspend (throw a hanging promise) only when actually accessed.
+*
+* The handler is typed as `ProxyHandler<T>` and no cast is needed because
+* the target is already `plain: T`.
+*/
+function createResolvedParamsProxy(plain, fallbackParamNames, observer, getFallbackShellPromise) {
+	if (!fallbackParamNames || fallbackParamNames.size === 0) return plain;
+	function isFallbackParam(prop) {
+		return typeof prop === "string" && fallbackParamNames !== null && fallbackParamNames.has(prop);
+	}
+	return new Proxy(plain, {
+		get(_target, prop, _receiver) {
+			if (typeof prop === "string" && !isWellKnownProperty(prop)) observeParamKeys(observer, [prop]);
+			if (!isWellKnownProperty(prop) && hasParamProperty(plain, prop)) {
+				if (isFallbackParam(prop)) {
+					const p = getFallbackShellPromise();
+					if (p) throw p;
+				}
+				return Reflect.get(plain, prop);
+			}
+			return Reflect.get(plain, prop);
+		},
+		getOwnPropertyDescriptor(_target, prop) {
+			if (typeof prop === "string" && !isWellKnownProperty(prop)) observeParamKeys(observer, [prop]);
+			if (!isWellKnownProperty(prop) && hasParamProperty(plain, prop)) {
+				if (isFallbackParam(prop)) return {
+					configurable: true,
+					enumerable: true,
+					get() {
+						const p = getFallbackShellPromise();
+						if (p) throw p;
+					}
+				};
+				return {
+					configurable: true,
+					enumerable: true,
+					value: Reflect.get(plain, prop),
+					writable: true
+				};
+			}
+			return Reflect.getOwnPropertyDescriptor(plain, prop);
+		},
+		has(_target, prop) {
+			if (typeof prop === "string" && !isWellKnownProperty(prop)) observeParamKeys(observer, [prop]);
+			return Reflect.has(plain, prop) || !isWellKnownProperty(prop) && hasParamProperty(plain, prop);
+		},
+		ownKeys() {
+			observeReadableParamKeys(observer, plain);
+			return Reflect.ownKeys(plain).filter((prop) => !isWellKnownProperty(prop));
+		}
+	});
+}
+/**
+* Wrap a `Promise<T>` with a proxy that also exposes param properties for
+* synchronous access. TypeScript cannot prove this hybrid shape statically,
+* so the single `as ThenableParams<T>` cast is isolated here.
+*/
+function createThenableParamsProxy(promise, handler) {
+	return new Proxy(promise, handler);
+}
+function makeThenableParams(obj, observer) {
+	const plain = { ...obj };
+	const fallbackShellState = getPprFallbackShellState();
+	const fallbackParamNames = fallbackShellState && Object.keys(plain).some((key) => fallbackShellState.fallbackParamNames.has(key)) ? fallbackShellState.fallbackParamNames : null;
+	let fallbackShellPromise = null;
+	let fallbackShellPromiseController = null;
+	function getFallbackShellPromise() {
+		if (!fallbackParamNames || !fallbackShellState) return null;
+		if (fallbackShellPromise && fallbackShellPromiseController === fallbackShellState.abortController) return fallbackShellPromise;
+		fallbackShellPromiseController = fallbackShellState.abortController;
+		fallbackShellPromise = createPprFallbackShellSuspensePromiseForState(fallbackShellState, "`params`");
+		return fallbackShellPromise;
+	}
+	const resolvedParams = createResolvedParamsProxy(plain, fallbackParamNames, observer, getFallbackShellPromise);
+	const promise = Promise.resolve(resolvedParams);
+	function isFallbackParam(prop) {
+		return typeof prop === "string" && (fallbackParamNames?.has(prop) ?? false);
+	}
+	return createThenableParamsProxy(promise, {
+		get(target, prop, receiver) {
+			if (isPromiseContinuation(prop)) {
+				const value = Reflect.get(target, prop, receiver);
+				if (typeof value !== "function") return value;
+				return (...args) => {
+					if (!fallbackParamNames) observeAllParamKeys(observer, plain);
+					return Reflect.apply(value, target, args);
+				};
+			}
+			if (prop === "status" && observer?.observeReactPromiseStatus === true) observeAllParamKeys(observer, plain);
+			if (typeof prop === "string" && !isWellKnownProperty(prop)) observeParamKeys(observer, [prop]);
+			if (!isWellKnownProperty(prop) && hasParamProperty(plain, prop)) {
+				if (isFallbackParam(prop)) {
+					const p = getFallbackShellPromise();
+					if (p) throw p;
+				}
+				return Reflect.get(plain, prop);
+			}
+			const value = Reflect.get(target, prop, receiver);
+			return typeof value === "function" ? value.bind(target) : value;
+		},
+		getOwnPropertyDescriptor(target, prop) {
+			if (typeof prop === "string" && !isWellKnownProperty(prop)) observeParamKeys(observer, [prop]);
+			if (!isWellKnownProperty(prop) && hasParamProperty(plain, prop)) {
+				if (isFallbackParam(prop)) return {
+					configurable: true,
+					enumerable: true,
+					get() {
+						const p = getFallbackShellPromise();
+						if (p) throw p;
+					}
+				};
+				return {
+					configurable: true,
+					enumerable: true,
+					value: Reflect.get(plain, prop),
+					writable: true
+				};
+			}
+			return Reflect.getOwnPropertyDescriptor(target, prop);
+		},
+		has(target, prop) {
+			if (typeof prop === "string" && !isWellKnownProperty(prop)) observeParamKeys(observer, [prop]);
+			return Reflect.has(target, prop) || !isWellKnownProperty(prop) && hasParamProperty(plain, prop);
+		},
+		ownKeys() {
+			observeReadableParamKeys(observer, plain);
+			return Reflect.ownKeys(plain).filter((prop) => !isWellKnownProperty(prop));
+		}
+	});
+}
+//#endregion
+export { makeThenableParams };

package/dist/shims/unified-request-context.d.ts

@@ -0,0 +1,68 @@
+import { CacheState } from "./cache-request-state.js";
+import { ExecutionContextLike } from "./request-context.js";
+import { RootParamsState } from "./root-params.js";
+import { FetchCacheState } from "./fetch-cache.js";
+import { VinextHeadersShimState } from "./headers.js";
+import { RouterState } from "./router-state.js";
+import { PrivateCacheState } from "./cache-runtime.js";
+import { HeadState } from "./head-state.js";
+import { I18nState } from "./i18n-state.js";
+import { NavigationState } from "./navigation-state.js";
+//#region src/shims/unified-request-context.d.ts
+/**
+ * Flat union of all per-request state previously spread across
+ * VinextHeadersShimState, NavigationState, CacheState, PrivateCacheState,
+ * FetchCacheState, and ExecutionContextLike.
+ *
+ * Each field group is documented with its source shim module.
+ */
+type UnifiedRequestContext = {
+  /** Cloudflare Workers ExecutionContext, or null on Node.js dev. */executionContext: ExecutionContextLike | null; /** Per-request cache for cacheForRequest(). Keyed by factory function reference. */
+  requestCache: WeakMap<(...args: any[]) => any, unknown>;
+} & VinextHeadersShimState & I18nState & NavigationState & CacheState & PrivateCacheState & FetchCacheState & RouterState & HeadState & RootParamsState;
+/**
+ * Create a fresh `UnifiedRequestContext` with defaults for all fields.
+ * Pass partial overrides for the fields you need to pre-populate.
+ */
+declare function createRequestContext(opts?: Partial<UnifiedRequestContext>): UnifiedRequestContext;
+/**
+ * Run `fn` within a unified request context scope.
+ * All shim modules will read/write their state from `ctx` for the
+ * duration of the call, including async continuations.
+ */
+declare function runWithRequestContext<T>(ctx: UnifiedRequestContext, fn: () => Promise<T>): Promise<T>;
+declare function runWithRequestContext<T>(ctx: UnifiedRequestContext, fn: () => T | Promise<T>): T | Promise<T>;
+/**
+ * Run `fn` in a nested unified scope derived from the current request context.
+ * Used by legacy runWith* wrappers to reset or override one sub-state while
+ * preserving proper async isolation for continuations created inside `fn`.
+ * The child scope is a shallow clone of the parent store, so untouched fields
+ * keep sharing their existing references while overridden slices can be reset.
+ *
+ * @internal
+ */
+declare function runWithUnifiedStateMutation<T>(mutate: (ctx: UnifiedRequestContext) => void, fn: () => Promise<T>): Promise<T>;
+declare function runWithUnifiedStateMutation<T>(mutate: (ctx: UnifiedRequestContext) => void, fn: () => T | Promise<T>): T | Promise<T>;
+/**
+ * Get the current unified request context.
+ * Returns the ALS store when inside a `runWithRequestContext()` scope,
+ * or a fresh detached context otherwise. Unlike the legacy per-shim fallback
+ * singletons, this detached value is ephemeral — mutations do not persist
+ * across calls. This is intentional to prevent state leakage outside request
+ * scopes.
+ *
+ * Only direct callers observe this detached fallback. Shim `_getState()`
+ * helpers should continue to gate on `isInsideUnifiedScope()` and fall back
+ * to their standalone ALS/fallback singletons outside the unified scope.
+ * If called inside a standalone `runWithExecutionContext()` scope, the
+ * detached context still reflects that inherited `executionContext`.
+ */
+declare function getRequestContext(): UnifiedRequestContext;
+/**
+ * Check whether the current execution is inside a `runWithRequestContext()` scope.
+ * Shim modules use this to decide whether to read from the unified store
+ * or fall back to their own standalone ALS.
+ */
+declare function isInsideUnifiedScope(): boolean;
+//#endregion
+export { UnifiedRequestContext, createRequestContext, getRequestContext, isInsideUnifiedScope, runWithRequestContext, runWithUnifiedStateMutation };

package/dist/shims/unified-request-context.js

@@ -0,0 +1,86 @@
+import { getOrCreateAls } from "./internal/als-registry.js";
+//#region src/shims/unified-request-context.ts
+const _REQUEST_CONTEXT_ALS_KEY = Symbol.for("vinext.requestContext.als");
+const _g = globalThis;
+const _als = getOrCreateAls("vinext.unifiedRequestContext.als");
+function _getInheritedExecutionContext() {
+	const unifiedStore = _als.getStore();
+	if (unifiedStore) return unifiedStore.executionContext;
+	return _g[_REQUEST_CONTEXT_ALS_KEY]?.getStore() ?? null;
+}
+/**
+* Create a fresh `UnifiedRequestContext` with defaults for all fields.
+* Pass partial overrides for the fields you need to pre-populate.
+*/
+function createRequestContext(opts) {
+	return {
+		headersContext: null,
+		actionRevalidationKind: 0,
+		dynamicUsageDetected: false,
+		renderRequestApiUsage: /* @__PURE__ */ new Set(),
+		connectionProbe: null,
+		invalidDynamicUsageError: null,
+		pendingSetCookies: [],
+		draftModeCookieHeader: null,
+		phase: "render",
+		i18nContext: null,
+		serverContext: null,
+		serverInsertedHTMLCallbacks: [],
+		requestScopedCacheLife: null,
+		unstableCacheObservations: /* @__PURE__ */ new Map(),
+		unstableCacheRevalidation: "foreground",
+		_privateCache: null,
+		cacheableFetchUrls: /* @__PURE__ */ new Set(),
+		currentRequestTags: [],
+		currentFetchSoftTags: [],
+		currentFetchCacheMode: null,
+		currentForceDynamicFetchDefault: false,
+		dynamicFetchUrls: /* @__PURE__ */ new Set(),
+		isFetchDedupeActive: false,
+		currentFetchDedupeEntries: /* @__PURE__ */ new Map(),
+		executionContext: _getInheritedExecutionContext(),
+		requestCache: /* @__PURE__ */ new WeakMap(),
+		ssrContext: null,
+		ssrHeadChildren: [],
+		documentInitialHead: [],
+		rootParams: null,
+		...opts
+	};
+}
+function runWithRequestContext(ctx, fn) {
+	return _als.run(ctx, fn);
+}
+function runWithUnifiedStateMutation(mutate, fn) {
+	const parentCtx = _als.getStore();
+	if (!parentCtx) return fn();
+	const childCtx = { ...parentCtx };
+	mutate(childCtx);
+	return _als.run(childCtx, fn);
+}
+/**
+* Get the current unified request context.
+* Returns the ALS store when inside a `runWithRequestContext()` scope,
+* or a fresh detached context otherwise. Unlike the legacy per-shim fallback
+* singletons, this detached value is ephemeral — mutations do not persist
+* across calls. This is intentional to prevent state leakage outside request
+* scopes.
+*
+* Only direct callers observe this detached fallback. Shim `_getState()`
+* helpers should continue to gate on `isInsideUnifiedScope()` and fall back
+* to their standalone ALS/fallback singletons outside the unified scope.
+* If called inside a standalone `runWithExecutionContext()` scope, the
+* detached context still reflects that inherited `executionContext`.
+*/
+function getRequestContext() {
+	return _als.getStore() ?? createRequestContext();
+}
+/**
+* Check whether the current execution is inside a `runWithRequestContext()` scope.
+* Shim modules use this to decide whether to read from the unified store
+* or fall back to their own standalone ALS.
+*/
+function isInsideUnifiedScope() {
+	return _als.getStore() != null;
+}
+//#endregion
+export { createRequestContext, getRequestContext, isInsideUnifiedScope, runWithRequestContext, runWithUnifiedStateMutation };

package/dist/shims/unrecognized-action-error.d.ts

@@ -0,0 +1,34 @@
+//#region src/shims/unrecognized-action-error.d.ts
+/**
+ * Unrecognized server-action errors.
+ *
+ * When a server action call fails because the server did not recognize the
+ * action id, the client bundle and the server are typically from different
+ * deployments and a hard reload is required.
+ *
+ * This module is intentionally dependency-free: both the `next/navigation`
+ * shim (which re-exports these for user code) and vinext's client
+ * server-action dispatcher import `UnrecognizedActionError` from here, so the
+ * `instanceof` check inside `unstable_isUnrecognizedActionError` resolves
+ * against a single shared class.
+ *
+ * Ported 1:1 from Next.js:
+ *   https://github.com/vercel/next.js/blob/canary/packages/next/src/client/components/unrecognized-action-error.ts
+ */
+/**
+ * Error class for unrecognized server-action calls. Thrown by vinext's client
+ * server-action dispatcher when the server reports the requested action id as
+ * unknown (the `x-nextjs-action-not-found` response header).
+ */
+declare class UnrecognizedActionError extends Error {
+  constructor(...args: ConstructorParameters<typeof Error>);
+}
+/**
+ * Returns true if the error came from a server action whose id was not
+ * recognized by the server. Useful inside `catch` blocks that surround
+ * `await myAction(...)` calls; reloading the page generally fixes the
+ * underlying client/server deployment mismatch.
+ */
+declare function unstable_isUnrecognizedActionError(error: unknown): error is UnrecognizedActionError;
+//#endregion
+export { UnrecognizedActionError, unstable_isUnrecognizedActionError };