@qzsy/vinext 0.1.7

package/dist/shims/image.js

@@ -0,0 +1,582 @@
+"use client";
+import { useMergedRef } from "./use-merged-ref.js";
+import { hasRemoteMatch, isPrivateIp } from "./image-config.js";
+import { forwardRef, useEffect, useLayoutEffect, useRef, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+import * as ReactDOM from "react-dom";
+import { Image as Image$1 } from "@unpic/react";
+//#region src/shims/image.tsx
+/**
+* next/image shim
+*
+* Translates Next.js Image props to @unpic/react Image component.
+* @unpic/react auto-detects CDN from URL and uses native transforms.
+* For local images (relative paths), routes through `/_next/image`
+* for server-side optimization (resize, format negotiation, quality).
+*
+* Remote images are validated against `images.remotePatterns` and
+* `images.domains` from next.config.js. Unmatched URLs are blocked
+* in production and warn in development, matching Next.js behavior.
+*/
+/**
+* Image config injected at build time via Vite define.
+* Serialized as JSON — parsed once at module level.
+*/
+const __imageRemotePatterns = (() => {
+	try {
+		return JSON.parse(process.env.__VINEXT_IMAGE_REMOTE_PATTERNS ?? "[]");
+	} catch {
+		return [];
+	}
+})();
+const __imageDomains = (() => {
+	try {
+		return JSON.parse(process.env.__VINEXT_IMAGE_DOMAINS ?? "[]");
+	} catch {
+		return [];
+	}
+})();
+const __hasImageConfig = __imageRemotePatterns.length > 0 || __imageDomains.length > 0;
+const __isDev = process.env.NODE_ENV !== "production";
+const __imageDeviceSizes = (() => {
+	try {
+		return JSON.parse(process.env.__VINEXT_IMAGE_DEVICE_SIZES ?? "[640,750,828,1080,1200,1920,2048,3840]");
+	} catch {
+		return [
+			640,
+			750,
+			828,
+			1080,
+			1200,
+			1920,
+			2048,
+			3840
+		];
+	}
+})();
+/**
+* Whether dangerouslyAllowSVG is enabled in next.config.js.
+* When false (default), .svg sources auto-skip the optimization endpoint
+* and are served directly, matching Next.js behavior.
+* When true, .svg sources are routed through the optimizer (served as-is
+* with security headers).
+*/
+const __dangerouslyAllowSVG = process.env.__VINEXT_IMAGE_DANGEROUSLY_ALLOW_SVG === "true";
+/**
+* Whether dangerouslyAllowLocalIP is enabled in next.config.js.
+* When false (default), remote image URLs with literal private-IP hostnames
+* are blocked to mitigate SSRF risk.
+*/
+const __dangerouslyAllowLocalIP = process.env.__VINEXT_IMAGE_DANGEROUSLY_ALLOW_LOCAL_IP === "true";
+/**
+* Validate that a remote URL is allowed by the configured remote patterns.
+* Returns true if the URL is allowed, false otherwise.
+*
+* When no remotePatterns/domains are configured, all remote URLs are allowed
+* (backwards-compatible — user hasn't opted into restriction).
+*
+* When patterns ARE configured, only matching URLs are allowed.
+* In development, non-matching URLs produce a console warning.
+* In production, non-matching URLs are blocked (src replaced with empty string).
+*
+* Private-IP hostnames are additionally rejected unless dangerouslyAllowLocalIP
+* is set, mirroring Next.js's fetchExternalImage guard.
+*/
+function validateRemoteUrl(src) {
+	let url;
+	try {
+		url = new URL(src, "http://n");
+	} catch {
+		return {
+			allowed: false,
+			reason: `Invalid URL: ${src}`
+		};
+	}
+	if (!__dangerouslyAllowLocalIP && isPrivateIp(url.hostname)) return {
+		allowed: false,
+		reason: `Image URL "${src}" resolved to private IP. If this is expected and you understand SSRF risk, use images.dangerouslyAllowLocalIP = true to continue.`
+	};
+	if (!__hasImageConfig) return { allowed: true };
+	if (hasRemoteMatch(__imageDomains, __imageRemotePatterns, url)) return { allowed: true };
+	return {
+		allowed: false,
+		reason: `Image URL "${src}" is not configured in images.remotePatterns or images.domains in next.config.js. See: https://nextjs.org/docs/messages/next-image-unconfigured-host`
+	};
+}
+/**
+* A version of useLayoutEffect that doesn't warn during SSR.
+* Do not rename this to "isomorphic layout effect". There is no such thing as
+* an isomorphic Layout Effect since there is no Layout on the server.
+* Ported from Next.js: https://github.com/vercel/next.js/pull/93209
+*/
+const useNonWarningLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+/**
+* Create a synthetic React load event for replaying onLoad/onLoadingComplete
+* during hydration when the image already completed loading.
+*
+* This function creates a native Event("load") via the DOM Event constructor
+* and must only be called in a browser context (client-side layout effect).
+* It mirrors the pattern used in Next.js `handleLoading`.
+*/
+function createSyntheticLoadEvent(img) {
+	const nativeEvent = new Event("load");
+	Object.defineProperty(nativeEvent, "target", {
+		writable: false,
+		value: img
+	});
+	let prevented = false;
+	let stopped = false;
+	return {
+		bubbles: nativeEvent.bubbles,
+		cancelable: nativeEvent.cancelable,
+		currentTarget: img,
+		defaultPrevented: false,
+		eventPhase: nativeEvent.eventPhase,
+		isTrusted: false,
+		nativeEvent,
+		target: img,
+		timeStamp: nativeEvent.timeStamp,
+		type: "load",
+		isDefaultPrevented: () => prevented,
+		isPropagationStopped: () => stopped,
+		persist: () => {},
+		preventDefault: () => {
+			prevented = true;
+			nativeEvent.preventDefault();
+		},
+		stopPropagation: () => {
+			stopped = true;
+			nativeEvent.stopPropagation();
+		}
+	};
+}
+/**
+* Sanitize a blurDataURL to prevent CSS injection.
+*
+* A crafted data URL containing `)` can break out of the `url()` CSS function,
+* allowing injection of arbitrary CSS properties or rules. Characters like `{`,
+* `}`, and `\` can also assist in crafting injection payloads.
+*
+* This validates the URL starts with `data:image/` and rejects characters that
+* could escape the `url()` context. Semicolons are allowed since they're part
+* of valid data URLs (`data:image/png;base64,...`) and harmless inside `url()`.
+*
+* Returns undefined for invalid URLs, which causes the blur placeholder to be
+* skipped gracefully.
+*/
+function sanitizeBlurDataURL(url) {
+	if (!url.startsWith("data:image/")) return void 0;
+	if (/[)(}{\\'"\n\r]/.test(url)) return void 0;
+	return url;
+}
+/**
+* Determine if a src is a remote URL (CDN-optimizable) or local.
+*/
+function isRemoteUrl(src) {
+	return src.startsWith("http://") || src.startsWith("https://") || src.startsWith("//");
+}
+function isSvgUrl(src) {
+	try {
+		return new URL(src, "http://vinext.local").pathname.toLowerCase().endsWith(".svg");
+	} catch {
+		return false;
+	}
+}
+function getFillStyle(style, backgroundStyle) {
+	return {
+		position: "absolute",
+		inset: 0,
+		width: "100%",
+		height: "100%",
+		objectFit: "cover",
+		...backgroundStyle,
+		...style
+	};
+}
+/**
+* Resolve src, width, height, blurDataURL from Image props (string or StaticImageData).
+* Shared by the Image component and getImageProps to keep behavior in sync.
+*/
+function resolveImageSource(v) {
+	return {
+		src: typeof v.src === "string" ? v.src : v.src.src,
+		width: v.width ?? (typeof v.src === "object" ? v.src.width : void 0),
+		height: v.height ?? (typeof v.src === "object" ? v.src.height : void 0),
+		blurDataURL: v.blurDataURL ?? (typeof v.src === "object" ? v.src.blurDataURL : void 0)
+	};
+}
+/**
+* Responsive image widths matching Next.js's device sizes config.
+* These are the breakpoints used for srcSet generation.
+* Configurable via `images.deviceSizes` in next.config.js.
+*/
+const RESPONSIVE_WIDTHS = __imageDeviceSizes;
+/**
+* Build a `/_next/image` optimization URL.
+*
+* In production (Cloudflare Workers), the worker intercepts this path and uses
+* the Images binding to resize/transcode on the fly. In dev, the Vite dev
+* server handles it as a passthrough (serves the original file).
+*/
+function imageOptimizationUrl(src, width, quality = 75) {
+	return `/_next/image?url=${encodeURIComponent(src)}&w=${width}&q=${quality}`;
+}
+function preloadImageResource(input) {
+	if (!input.shouldPreload) return;
+	if (typeof ReactDOM.preload !== "function") return;
+	ReactDOM.preload(input.src, {
+		as: "image",
+		imageSrcSet: input.srcSet,
+		imageSizes: input.sizes,
+		fetchPriority: input.fetchPriority
+	});
+}
+/**
+* Generate a srcSet string for responsive images.
+*
+* Each width points to the `/_next/image` optimization endpoint so the
+* server can resize and transcode the image. Only includes widths that are
+* <= 2x the original image width to avoid pointless upscaling.
+*/
+function generateSrcSet(src, originalWidth, quality = 75) {
+	const widths = RESPONSIVE_WIDTHS.filter((w) => w <= originalWidth * 2);
+	if (widths.length === 0) return `${imageOptimizationUrl(src, originalWidth, quality)} ${originalWidth}w`;
+	return widths.map((w) => `${imageOptimizationUrl(src, w, quality)} ${w}w`).join(", ");
+}
+const Image = forwardRef(function Image({ src: srcProp, alt, width, height, fill, preload, priority, quality, placeholder, blurDataURL, loader, sizes, className, style, onLoad, onLoadingComplete, onError, unoptimized: _unoptimized, overrideSrc, loading, ...rest }, ref) {
+	const lastLoadedSrcRef = useRef(void 0);
+	const lastErrorSrcRef = useRef(void 0);
+	const didInsertRef = useRef(false);
+	const imgElementRef = useRef(null);
+	const mergedRef = useMergedRef(ref, imgElementRef);
+	const onLoadRef = useRef(onLoad);
+	useEffect(() => {
+		onLoadRef.current = onLoad;
+	}, [onLoad]);
+	const onErrorRef = useRef(onError);
+	useEffect(() => {
+		onErrorRef.current = onError;
+	}, [onError]);
+	const onLoadingCompleteRef = useRef(onLoadingComplete);
+	useEffect(() => {
+		onLoadingCompleteRef.current = onLoadingComplete;
+	}, [onLoadingComplete]);
+	const { src, width: imgWidth, height: imgHeight, blurDataURL: imgBlurDataURL } = resolveImageSource({
+		src: srcProp,
+		width,
+		height,
+		blurDataURL
+	});
+	const shouldPreload = preload === true || priority === true;
+	const priorityFetchPriority = priority ? "high" : void 0;
+	const imageLoading = priority ? "eager" : shouldPreload ? loading : loading ?? "lazy";
+	const [completedBlurSrc, setCompletedBlurSrc] = useState(void 0);
+	const blurComplete = completedBlurSrc === src;
+	const markBlurComplete = () => {
+		if (placeholder !== "blur") return;
+		setCompletedBlurSrc((current) => current === src ? current : src);
+	};
+	useNonWarningLayoutEffect(() => {
+		if (!didInsertRef.current && imgElementRef.current !== null) {
+			const img = imgElementRef.current;
+			if (onErrorRef.current) img.src = img.src;
+			if (img.complete && img.naturalWidth > 0) {
+				markBlurComplete();
+				const currentOnLoad = onLoadRef.current;
+				const currentOnLoadingComplete = onLoadingCompleteRef.current;
+				if (currentOnLoad || currentOnLoadingComplete) {
+					if (lastLoadedSrcRef.current !== src) {
+						lastLoadedSrcRef.current = src;
+						const syntheticEvent = createSyntheticLoadEvent(img);
+						currentOnLoad?.(syntheticEvent);
+						currentOnLoadingComplete?.(img);
+					}
+				}
+			}
+			didInsertRef.current = true;
+		}
+	}, [
+		placeholder,
+		sizes,
+		_unoptimized
+	]);
+	const handleLoad = onLoadingComplete ? (e) => {
+		if (lastLoadedSrcRef.current === src) return;
+		lastLoadedSrcRef.current = src;
+		markBlurComplete();
+		onLoad?.(e);
+		onLoadingComplete(e.currentTarget);
+	} : onLoad ? (e) => {
+		if (lastLoadedSrcRef.current === src) return;
+		lastLoadedSrcRef.current = src;
+		markBlurComplete();
+		onLoad(e);
+	} : placeholder === "blur" ? () => {
+		if (lastLoadedSrcRef.current === src) return;
+		lastLoadedSrcRef.current = src;
+		markBlurComplete();
+	} : void 0;
+	const handleError = onError ? (e) => {
+		if (lastErrorSrcRef.current === src) return;
+		lastErrorSrcRef.current = src;
+		markBlurComplete();
+		onError(e);
+	} : placeholder === "blur" ? () => {
+		if (lastErrorSrcRef.current === src) return;
+		lastErrorSrcRef.current = src;
+		markBlurComplete();
+	} : void 0;
+	if (_unoptimized === true) {
+		const renderedSrc = overrideSrc || src;
+		const sanitizedBlur = imgBlurDataURL ? sanitizeBlurDataURL(imgBlurDataURL) : void 0;
+		const blurStyle = !blurComplete && placeholder === "blur" && sanitizedBlur ? {
+			backgroundImage: `url(${sanitizedBlur})`,
+			backgroundSize: "cover",
+			backgroundRepeat: "no-repeat",
+			backgroundPosition: "center"
+		} : void 0;
+		preloadImageResource({
+			shouldPreload,
+			src: renderedSrc,
+			fetchPriority: priorityFetchPriority
+		});
+		return /* @__PURE__ */ jsx("img", {
+			ref: mergedRef,
+			src: renderedSrc,
+			alt,
+			width: fill ? void 0 : imgWidth,
+			height: fill ? void 0 : imgHeight,
+			loading: imageLoading,
+			fetchPriority: priorityFetchPriority,
+			decoding: "async",
+			className,
+			"data-nimg": fill ? "fill" : "1",
+			onLoad: handleLoad,
+			onError: handleError,
+			style: fill ? getFillStyle(style, blurStyle) : {
+				...blurStyle,
+				...style
+			},
+			...rest
+		});
+	}
+	if (loader) {
+		const resolvedSrc = loader({
+			src,
+			width: imgWidth ?? 0,
+			quality: quality ?? 75
+		});
+		preloadImageResource({
+			shouldPreload,
+			src: resolvedSrc,
+			sizes,
+			fetchPriority: priorityFetchPriority
+		});
+		return /* @__PURE__ */ jsx("img", {
+			ref: mergedRef,
+			src: resolvedSrc,
+			alt,
+			width: fill ? void 0 : imgWidth,
+			height: fill ? void 0 : imgHeight,
+			loading: imageLoading,
+			decoding: "async",
+			sizes,
+			className,
+			onLoad: handleLoad,
+			onError: handleError,
+			style: fill ? getFillStyle(style) : style,
+			...rest
+		});
+	}
+	if (isRemoteUrl(src)) {
+		const validation = validateRemoteUrl(src);
+		if (!validation.allowed) if (__isDev) console.warn(`[next/image] ${validation.reason}`);
+		else {
+			console.error(`[next/image] ${validation.reason}`);
+			return null;
+		}
+		const sanitizedBlur = imgBlurDataURL ? sanitizeBlurDataURL(imgBlurDataURL) : void 0;
+		const showBlur = !blurComplete && placeholder === "blur" && sanitizedBlur;
+		const blurStyle = showBlur ? {
+			backgroundImage: `url(${sanitizedBlur})`,
+			backgroundSize: "cover",
+			backgroundRepeat: "no-repeat",
+			backgroundPosition: "center"
+		} : void 0;
+		const bg = showBlur ? `url(${sanitizedBlur})` : void 0;
+		if (fill) {
+			const imageSizes = sizes ?? "100vw";
+			preloadImageResource({
+				shouldPreload,
+				src,
+				sizes: imageSizes,
+				fetchPriority: priorityFetchPriority
+			});
+			return /* @__PURE__ */ jsx("img", {
+				ref: mergedRef,
+				src,
+				alt,
+				loading: imageLoading,
+				fetchPriority: priorityFetchPriority,
+				decoding: "async",
+				sizes: imageSizes,
+				className,
+				"data-nimg": "fill",
+				onLoad: handleLoad,
+				onError: handleError,
+				style: getFillStyle(style, blurStyle),
+				...rest
+			});
+		}
+		if (imgWidth && imgHeight) {
+			const unpicRuntimeStyleProps = { style };
+			preloadImageResource({
+				shouldPreload,
+				src,
+				sizes,
+				fetchPriority: priorityFetchPriority
+			});
+			return /* @__PURE__ */ jsx(Image$1, {
+				src,
+				alt,
+				width: imgWidth,
+				height: imgHeight,
+				layout: "constrained",
+				loading: imageLoading,
+				fetchPriority: priorityFetchPriority,
+				sizes,
+				className,
+				...unpicRuntimeStyleProps,
+				background: bg,
+				onLoad: handleLoad,
+				onError: handleError,
+				ref: mergedRef
+			});
+		}
+	}
+	const imgQuality = quality ?? 75;
+	const skipOptimization = isSvgUrl(src) && !__dangerouslyAllowSVG;
+	const srcSet = imgWidth && !fill && !skipOptimization ? generateSrcSet(src, imgWidth, imgQuality) : imgWidth && !fill ? RESPONSIVE_WIDTHS.filter((w) => w <= imgWidth * 2).map((w) => `${src} ${w}w`).join(", ") || `${src} ${imgWidth}w` : void 0;
+	const optimizedSrc = skipOptimization ? src : imgWidth ? imageOptimizationUrl(src, imgWidth, imgQuality) : imageOptimizationUrl(src, RESPONSIVE_WIDTHS[0], imgQuality);
+	const sanitizedLocalBlur = imgBlurDataURL ? sanitizeBlurDataURL(imgBlurDataURL) : void 0;
+	const blurStyle = !blurComplete && placeholder === "blur" && sanitizedLocalBlur ? {
+		backgroundImage: `url(${sanitizedLocalBlur})`,
+		backgroundSize: "cover",
+		backgroundRepeat: "no-repeat",
+		backgroundPosition: "center"
+	} : void 0;
+	const imageSizes = sizes ?? (fill ? "100vw" : void 0);
+	preloadImageResource({
+		shouldPreload,
+		src: optimizedSrc,
+		srcSet,
+		sizes: imageSizes,
+		fetchPriority: priorityFetchPriority
+	});
+	return /* @__PURE__ */ jsx("img", {
+		ref: mergedRef,
+		src: optimizedSrc,
+		alt,
+		width: fill ? void 0 : imgWidth,
+		height: fill ? void 0 : imgHeight,
+		loading: imageLoading,
+		fetchPriority: priorityFetchPriority,
+		decoding: "async",
+		srcSet,
+		sizes: imageSizes,
+		className,
+		"data-nimg": fill ? "fill" : "1",
+		onLoad: handleLoad,
+		onError: handleError,
+		style: fill ? getFillStyle(style, blurStyle) : {
+			...blurStyle,
+			...style
+		},
+		...rest
+	});
+});
+/**
+* getImageProps — for advanced use cases (picture elements, background images).
+* Returns the props that would be passed to the underlying <img> element.
+*/
+function getImageProps(props) {
+	const { src: srcProp, alt, width, height, fill, preload: _preload, priority, quality: _quality, placeholder, blurDataURL: blurDataURLProp, loader, sizes, className, style, onLoad: _onLoad, onLoadingComplete: _onLoadingComplete, unoptimized: _unoptimized, overrideSrc, loading, ...rest } = props;
+	const { src, width: imgWidth, height: imgHeight, blurDataURL: imgBlurDataURL } = resolveImageSource({
+		src: srcProp,
+		width,
+		height,
+		blurDataURL: blurDataURLProp
+	});
+	const shouldPreload = _preload === true || priority === true;
+	if (_unoptimized === true) {
+		const renderedSrc = overrideSrc || src;
+		const sanitizedBlurURL = imgBlurDataURL ? sanitizeBlurDataURL(imgBlurDataURL) : void 0;
+		const blurStyle = placeholder === "blur" && sanitizedBlurURL ? {
+			backgroundImage: `url(${sanitizedBlurURL})`,
+			backgroundSize: "cover",
+			backgroundRepeat: "no-repeat",
+			backgroundPosition: "center"
+		} : void 0;
+		return { props: {
+			src: renderedSrc,
+			alt,
+			width: fill ? void 0 : imgWidth,
+			height: fill ? void 0 : imgHeight,
+			loading: priority ? "eager" : shouldPreload ? loading : loading ?? "lazy",
+			fetchPriority: priority ? "high" : void 0,
+			decoding: "async",
+			className,
+			"data-nimg": fill ? "fill" : "1",
+			style: fill ? getFillStyle(style, blurStyle) : {
+				...blurStyle,
+				...style
+			},
+			...rest
+		} };
+	}
+	let blockedInProd = false;
+	if (isRemoteUrl(src)) {
+		const validation = validateRemoteUrl(src);
+		if (!validation.allowed) if (__isDev) console.warn(`[next/image] ${validation.reason}`);
+		else {
+			console.error(`[next/image] ${validation.reason}`);
+			blockedInProd = true;
+		}
+	}
+	const imgQuality = _quality ?? 75;
+	const resolvedSrc = blockedInProd ? "" : loader ? loader({
+		src,
+		width: imgWidth ?? 0,
+		quality: imgQuality
+	}) : src;
+	const skipOpt = isSvgUrl(resolvedSrc) && !__dangerouslyAllowSVG || blockedInProd || !!loader || isRemoteUrl(resolvedSrc);
+	const optimizedSrc = skipOpt ? resolvedSrc : imgWidth ? imageOptimizationUrl(resolvedSrc, imgWidth, imgQuality) : imageOptimizationUrl(resolvedSrc, RESPONSIVE_WIDTHS[0], imgQuality);
+	const srcSet = imgWidth && !fill && !isRemoteUrl(resolvedSrc) && !loader && !skipOpt ? generateSrcSet(resolvedSrc, imgWidth, imgQuality) : void 0;
+	const sanitizedBlurURL = imgBlurDataURL ? sanitizeBlurDataURL(imgBlurDataURL) : void 0;
+	const blurStyle = placeholder === "blur" && sanitizedBlurURL ? {
+		backgroundImage: `url(${sanitizedBlurURL})`,
+		backgroundSize: "cover",
+		backgroundRepeat: "no-repeat",
+		backgroundPosition: "center"
+	} : void 0;
+	return { props: {
+		src: optimizedSrc,
+		alt,
+		width: fill ? void 0 : imgWidth,
+		height: fill ? void 0 : imgHeight,
+		loading: priority ? "eager" : shouldPreload ? loading : loading ?? "lazy",
+		fetchPriority: priority ? "high" : void 0,
+		decoding: "async",
+		srcSet,
+		sizes: sizes ?? (fill ? "100vw" : void 0),
+		className,
+		"data-nimg": fill ? "fill" : "1",
+		style: fill ? getFillStyle(style, blurStyle) : {
+			...blurStyle,
+			...style
+		},
+		...rest
+	} };
+}
+//#endregion
+export { Image as default, getImageProps, imageOptimizationUrl };

package/dist/shims/internal/als-registry.d.ts

@@ -0,0 +1,14 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+//#region src/shims/internal/als-registry.d.ts
+/**
+ * Get (or lazily create) the AsyncLocalStorage registered on `globalThis`
+ * under `Symbol.for(key)`. Multiple callers — including callers in different
+ * module instances — that pass the same `key` receive the same ALS instance.
+ *
+ * @param key - String key fed to `Symbol.for(...)`. By convention vinext
+ *   shims use a dotted namespace such as `"vinext.cache.als"`.
+ */
+declare function getOrCreateAls<T>(key: string): AsyncLocalStorage<T>;
+//#endregion
+export { getOrCreateAls };

package/dist/shims/internal/als-registry.js

@@ -0,0 +1,80 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/shims/internal/als-registry.ts
+/**
+* Shared helper for registering AsyncLocalStorage instances on `globalThis`
+* via `Symbol.for(...)` so that they survive multiple module instances.
+*
+* Why this helper exists
+* ----------------------
+* Vite's multi-environment setup (RSC / SSR / client) and HMR can load a
+* single source module under several different specifiers, producing more
+* than one module instance at runtime. If each instance kept its own
+* module-local `new AsyncLocalStorage()`, request-scoped state would silently
+* fork across instances — `headers()` in one environment wouldn't see what
+* `connection()` registered in another, concurrent requests would stomp each
+* other, etc.
+*
+* The fix every shim was applying inline:
+*
+*   const _ALS_KEY = Symbol.for("vinext.foo.als");
+*   const _g = globalThis as unknown as Record<PropertyKey, unknown>;
+*   const _als = (_g[_ALS_KEY] ??=
+*     new AsyncLocalStorage<T>()) as AsyncLocalStorage<T>;
+*
+* This helper packages that pattern.
+*
+* Cross-bundle singleton property — preserved
+* -------------------------------------------
+* - `Symbol.for(key)` consults the global symbol registry and returns the
+*   same symbol regardless of which module instance calls it.
+* - `globalThis[sym]` is a single slot shared by every module instance.
+* - `??=` only assigns when the slot is empty, so the first caller wins and
+*   every subsequent caller (in any module instance) reads the same ALS.
+*
+* The helper module itself never holds the ALS by reference — it always
+* round-trips through `globalThis`. So even if this helper file is itself
+* loaded under multiple module instances, every copy still hands back the
+* one true ALS for a given key.
+*/
+const _g = globalThis;
+/**
+* No-op AsyncLocalStorage used when the runtime does not provide a usable
+* `AsyncLocalStorage` constructor.
+*
+* In browser/client bundles `node:async_hooks` can resolve to a stub without a
+* usable constructor (e.g. Vite's `__vite-browser-external`). Constructing such
+* a value with `new` throws `TypeError: AsyncLocalStorage is not a constructor`
+* at module-eval time, crashing every client-reachable shim that calls
+* `getOrCreateAls` on import (request-context, headers, cache, …).
+*
+* Mirrors Next.js' `FakeAsyncLocalStorage` (and this repo's
+* `async-hooks-stub.ts` client virtual module): `getStore()` returns
+* `undefined` so shims fall back to their non-ALS code path, and the mutating
+* methods are best-effort no-ops that still invoke the callback.
+* See: https://github.com/vercel/next.js/blob/canary/packages/next/src/server/app-render/async-local-storage.ts
+*/
+var NoopAsyncLocalStorage = class {
+	getStore() {}
+	run(_store, fn, ...args) {
+		return fn(...args);
+	}
+	exit(fn, ...args) {
+		return fn(...args);
+	}
+	enterWith(_store) {}
+	disable() {}
+};
+/**
+* Get (or lazily create) the AsyncLocalStorage registered on `globalThis`
+* under `Symbol.for(key)`. Multiple callers — including callers in different
+* module instances — that pass the same `key` receive the same ALS instance.
+*
+* @param key - String key fed to `Symbol.for(...)`. By convention vinext
+*   shims use a dotted namespace such as `"vinext.cache.als"`.
+*/
+function getOrCreateAls(key) {
+	const sym = Symbol.for(key);
+	return _g[sym] ??= typeof AsyncLocalStorage === "function" ? new AsyncLocalStorage() : new NoopAsyncLocalStorage();
+}
+//#endregion
+export { getOrCreateAls };

package/dist/shims/internal/api-utils.d.ts

@@ -0,0 +1,14 @@
+//#region src/shims/internal/api-utils.d.ts
+/**
+ * Shim for next/dist/server/api-utils
+ *
+ * Used by: @clerk/nextjs (type-only import of NextApiRequestCookies).
+ */
+type NextApiRequestCookies = Partial<{
+  [key: string]: string;
+}>;
+type NextApiRequestQuery = Partial<{
+  [key: string]: string | string[];
+}>;
+//#endregion
+export { NextApiRequestCookies, NextApiRequestQuery };

package/dist/shims/internal/api-utils.js

@@ -0,0 +1 @@
+export {};

package/dist/shims/internal/app-page-props-cache-key.d.ts

@@ -0,0 +1,5 @@
+//#region src/shims/internal/app-page-props-cache-key.d.ts
+declare function markAppPagePropsForUseCache<T extends object>(props: T): T;
+declare function isMarkedAppPagePropsObject(value: object): boolean;
+//#endregion
+export { isMarkedAppPagePropsObject, markAppPagePropsForUseCache };