vinext 0.0.54 → 0.1.0

package/dist/shims/fetch-cache.js

@@ -2,7 +2,7 @@ import { getOrCreateAls } from "./internal/als-registry.js";
 import { getRequestContext, isInsideUnifiedScope, runWithUnifiedStateMutation } from "./unified-request-context.js";
 import { getRequestExecutionContext } from "./request-context.js";
 import { encodeCacheTags } from "../utils/encode-cache-tag.js";
-import { getCacheHandler } from "./cache.js";
+import { getDataCacheHandler } from "./cache.js";
 //#region src/shims/fetch-cache.ts
 /**
 * Extended fetch() with Next.js caching semantics.
@@ -288,6 +288,7 @@ if (globalThis.FinalizationRegistry) _responseBodyRegistry = new FinalizationReg
 	if (stream && !stream.locked) stream.cancel("Response object has been garbage collected").then(_noop, _noop);
 });
 const _fallbackState = _g[_FALLBACK_KEY] ??= {
+	cacheableFetchUrls: /* @__PURE__ */ new Set(),
 	currentRequestTags: [],
 	currentFetchSoftTags: [],
 	currentFetchCacheMode: null,
@@ -304,6 +305,7 @@ function _getState() {
 * in single-threaded contexts where ALS.run() isn't used.
 */
 function _resetFallbackState(isFetchDedupeActive) {
+	_fallbackState.cacheableFetchUrls = /* @__PURE__ */ new Set();
 	_fallbackState.currentRequestTags = [];
 	_fallbackState.currentFetchSoftTags = [];
 	_fallbackState.currentFetchCacheMode = null;
@@ -317,6 +319,12 @@ function getFetchObservationUrl(input) {
 function recordDynamicFetchObservation(input) {
 	_getState().dynamicFetchUrls.add(getFetchObservationUrl(input));
 }
+function recordCacheableFetchObservation(input) {
+	_getState().cacheableFetchUrls.add(getFetchObservationUrl(input));
+}
+function peekCacheableFetchObservations() {
+	return [..._getState().cacheableFetchUrls].sort();
+}
 function peekDynamicFetchObservations() {
 	return [..._getState().dynamicFetchUrls].sort();
 }
@@ -496,7 +504,12 @@ function createPatchedFetch() {
 			recordDynamicFetchObservation(input);
 			return dedupeFetch(input, cleanInit);
 		}
+		recordCacheableFetchObservation(input);
+		const reqTags = _getState().currentRequestTags;
 		const tags = encodeCacheTags(nextOpts?.tags ?? []);
+		if (tags.length > 0) {
+			for (const tag of tags) if (!reqTags.includes(tag)) reqTags.push(tag);
+		}
 		const softTags = _getState().currentFetchSoftTags;
 		let fetchInit = stripNextFromInit(init, cacheDirective);
 		let cacheKey;
@@ -511,11 +524,7 @@ function createPatchedFetch() {
 			}
 			throw err;
 		}
-		const handler = getCacheHandler();
-		const reqTags = _getState().currentRequestTags;
-		if (tags.length > 0) {
-			for (const tag of tags) if (!reqTags.includes(tag)) reqTags.push(tag);
-		}
+		const handler = getDataCacheHandler();
 		try {
 			const cached = await handler.get(cacheKey, {
 				kind: "FETCH",
@@ -652,6 +661,7 @@ function withFetchCache() {
 async function runWithFetchCache(fn) {
 	_ensurePatchInstalled();
 	if (isInsideUnifiedScope()) return await runWithUnifiedStateMutation((uCtx) => {
+		uCtx.cacheableFetchUrls = /* @__PURE__ */ new Set();
 		uCtx.currentRequestTags = [];
 		uCtx.currentFetchSoftTags = [];
 		uCtx.dynamicFetchUrls = /* @__PURE__ */ new Set();
@@ -659,6 +669,7 @@ async function runWithFetchCache(fn) {
 		uCtx.currentFetchDedupeEntries = /* @__PURE__ */ new Map();
 	}, fn);
 	return _als.run({
+		cacheableFetchUrls: /* @__PURE__ */ new Set(),
 		currentRequestTags: [],
 		currentFetchSoftTags: [],
 		currentFetchCacheMode: null,
@@ -700,6 +711,4 @@ function getOriginalFetch() {
 	return originalFetch;
 }
 //#endregion
-export { _resetPendingRefetches, consumeDynamicFetchObservations, ensureFetchPatch, getCollectedFetchTags, getOriginalFetch, peekDynamicFetchObservations, runWithFetchCache, runWithFetchDedupe, setCurrentFetchCacheMode, setCurrentFetchSoftTags, withFetchCache };
-
-//# sourceMappingURL=fetch-cache.js.map
+export { _resetPendingRefetches, consumeDynamicFetchObservations, ensureFetchPatch, getCollectedFetchTags, getOriginalFetch, peekCacheableFetchObservations, peekDynamicFetchObservations, runWithFetchCache, runWithFetchDedupe, setCurrentFetchCacheMode, setCurrentFetchSoftTags, withFetchCache };

package/dist/shims/font-google-base.d.ts

@@ -79,5 +79,4 @@ type FontLoader = (options?: FontLoaderOptions) => FontResult;
 declare function createFontLoader(family: string): FontLoader;
 declare const googleFonts: Record<string, FontLoader>;
 //#endregion
-export { FontLoader, FontOptions, FontResult, buildGoogleFontsUrl, createFontLoader, googleFonts as default, getSSRFontLinks, getSSRFontPreloads, getSSRFontStyles };
-//# sourceMappingURL=font-google-base.d.ts.map
+export { FontLoader, FontOptions, FontResult, buildGoogleFontsUrl, createFontLoader, googleFonts as default, getSSRFontLinks, getSSRFontPreloads, getSSRFontStyles };

package/dist/shims/font-google-base.js

@@ -1,4 +1,4 @@
-import { escapeCSSString, formatFontClassRule, resolveSingleFaceStyle, sanitizeCSSVarName, sanitizeFallback } from "./font-utils.js";
+import { escapeCSSString, formatFontClassRule, getFontMimeType, resolveSingleFaceStyle, sanitizeCSSVarName, sanitizeFallback } from "./font-utils.js";
 import { buildGoogleFontsUrl as buildGoogleFontsUrl$1 } from "../build/google-fonts/build-url.js";
 //#region src/shims/font-google-base.ts
 /**
@@ -206,16 +206,6 @@ function getSSRFontPreloads() {
 	return [...ssrFontPreloads];
 }
 /**
-* Determine the MIME type for a font file based on its extension.
-*/
-function getFontMimeType(pathOrUrl) {
-	if (pathOrUrl.endsWith(".woff2")) return "font/woff2";
-	if (pathOrUrl.endsWith(".woff")) return "font/woff";
-	if (pathOrUrl.endsWith(".ttf")) return "font/ttf";
-	if (pathOrUrl.endsWith(".otf")) return "font/opentype";
-	return "font/woff2";
-}
-/**
 * Extract font file URLs from @font-face CSS rules.
 * Parses url('...') references from the CSS text.
 */
@@ -313,5 +303,3 @@ const googleFonts = new Proxy({}, { get(_target, prop) {
 } });
 //#endregion
 export { buildGoogleFontsUrl, createFontLoader, googleFonts as default, getSSRFontLinks, getSSRFontPreloads, getSSRFontStyles };
-
-//# sourceMappingURL=font-google-base.js.map

package/dist/shims/font-local.d.ts

@@ -47,5 +47,4 @@ declare function getSSRFontPreloads(): Array<{
 }>;
 declare function localFont(options: LocalFontOptions): FontResult;
 //#endregion
-export { localFont as default, getSSRFontPreloads, getSSRFontStyles };
-//# sourceMappingURL=font-local.d.ts.map
+export { localFont as default, getSSRFontPreloads, getSSRFontStyles };

package/dist/shims/font-local.js

@@ -1,4 +1,4 @@
-import { escapeCSSString, formatFontClassRule, resolveSingleFaceStyle, sanitizeCSSVarName, sanitizeFallback, sanitizeFontDescriptorValue } from "./font-utils.js";
+import { escapeCSSString, formatFontClassRule, getFontMimeType, resolveSingleFaceStyle, sanitizeCSSVarName, sanitizeFallback, sanitizeFontDescriptorValue } from "./font-utils.js";
 //#region src/shims/font-local.ts
 /**
 * next/font/local shim
@@ -151,18 +151,6 @@ function normalizeSources(options) {
 	return [options.src];
 }
 /**
-* Determine the MIME type for a font file based on its extension.
-* Uses endsWith() only — matching the approach in generateFontFaceCSS —
-* to avoid false positives from substring matches (e.g. ".woff" matching ".woff2").
-*/
-function getFontMimeType(pathOrUrl) {
-	if (pathOrUrl.endsWith(".woff2")) return "font/woff2";
-	if (pathOrUrl.endsWith(".woff")) return "font/woff";
-	if (pathOrUrl.endsWith(".ttf")) return "font/ttf";
-	if (pathOrUrl.endsWith(".otf")) return "font/opentype";
-	return "font/woff2";
-}
-/**
 * Collect font source URLs for preload link generation.
 * Only collects on the server (SSR). Deduplicates by href using a Set for O(1) lookups.
 */
@@ -205,5 +193,3 @@ function localFont(options) {
 }
 //#endregion
 export { localFont as default, getSSRFontPreloads, getSSRFontStyles };
-
-//# sourceMappingURL=font-local.js.map

package/dist/shims/font-utils.d.ts

@@ -46,6 +46,11 @@ declare function resolveFontStyle(style: string | string[] | undefined): string
 declare function resolveGoogleFontStyle(style: string | string[] | undefined): string | undefined;
 declare function resolveSingleFaceStyle(input: FontFaceStyleInput): FontStyle;
 declare function formatFontClassRule(className: string, style: FontStyle): string;
+/**
+ * Determine the MIME type for a font file based on its extension.
+ * Uses endsWith() only to avoid false positives from substring matches
+ * (e.g. ".woff" matching ".woff2").
+ */
+declare function getFontMimeType(pathOrUrl: string): string;
 //#endregion
-export { FontFaceStyleInput, FontStyle, escapeCSSString, formatFontClassRule, resolveFontStyle, resolveFontWeight, resolveGoogleFontStyle, resolveSingleFaceStyle, sanitizeCSSVarName, sanitizeFallback, sanitizeFontDescriptorValue, singleFontOptionValue };
-//# sourceMappingURL=font-utils.d.ts.map
+export { FontFaceStyleInput, FontStyle, escapeCSSString, formatFontClassRule, getFontMimeType, resolveFontStyle, resolveFontWeight, resolveGoogleFontStyle, resolveSingleFaceStyle, sanitizeCSSVarName, sanitizeFallback, sanitizeFontDescriptorValue, singleFontOptionValue };

package/dist/shims/font-utils.js

@@ -91,7 +91,17 @@ function formatFontClassRule(className, style) {
 		...fontStyle ? [`font-style: ${fontStyle}`] : []
 	].join("; ")}; }\n`;
 }
+/**
+* Determine the MIME type for a font file based on its extension.
+* Uses endsWith() only to avoid false positives from substring matches
+* (e.g. ".woff" matching ".woff2").
+*/
+function getFontMimeType(pathOrUrl) {
+	if (pathOrUrl.endsWith(".woff2")) return "font/woff2";
+	if (pathOrUrl.endsWith(".woff")) return "font/woff";
+	if (pathOrUrl.endsWith(".ttf")) return "font/ttf";
+	if (pathOrUrl.endsWith(".otf")) return "font/opentype";
+	return "font/woff2";
+}
 //#endregion
-export { escapeCSSString, formatFontClassRule, resolveFontStyle, resolveFontWeight, resolveGoogleFontStyle, resolveSingleFaceStyle, sanitizeCSSVarName, sanitizeFallback, sanitizeFontDescriptorValue, singleFontOptionValue };
-
-//# sourceMappingURL=font-utils.js.map
+export { escapeCSSString, formatFontClassRule, getFontMimeType, resolveFontStyle, resolveFontWeight, resolveGoogleFontStyle, resolveSingleFaceStyle, sanitizeCSSVarName, sanitizeFallback, sanitizeFontDescriptorValue, singleFontOptionValue };

package/dist/shims/form.d.ts

@@ -1,12 +1,19 @@
-import * as _$react from "react";
 import { FormHTMLAttributes, useActionState } from "react";
 
 //#region src/shims/form.d.ts
-declare const Form: _$react.ForwardRefExoticComponent<{
+declare const Form: import("react").ForwardRefExoticComponent<{
   /** Target URL for GET forms, or server action for POST forms */action: string | ((formData: FormData) => void | Promise<void>); /** Replace instead of push in history (default: false) */
   replace?: boolean; /** Scroll to top after navigation (default: true) */
   scroll?: boolean;
-} & FormHTMLAttributes<HTMLFormElement> & _$react.RefAttributes<HTMLFormElement>>;
+  /**
+   * Controls whether the form's target URL is prefetched when the form enters
+   * the viewport. Only applies to App Router with a string `action`.
+   * - `null` (default): prefetch automatically (production only)
+   * - `false`: disable prefetching
+   *
+   * In pages dir, prefetch is not supported and the prop has no effect.
+   */
+  prefetch?: false | null;
+} & Omit<FormHTMLAttributes<HTMLFormElement>, "method" | "encType" | "target"> & import("react").RefAttributes<HTMLFormElement>>;
 //#endregion
-export { Form as default, useActionState };
-//# sourceMappingURL=form.d.ts.map
+export { Form as default, useActionState };

package/dist/shims/form.js

@@ -1,9 +1,14 @@
 "use client";
+import { VINEXT_MOUNTED_SLOTS_HEADER } from "../server/headers.js";
 import { isDangerousScheme } from "./url-safety.js";
+import { AppElementsWire } from "../server/app-elements-wire.js";
+import "../server/app-elements.js";
 import { toSameOriginPath, withBasePath } from "./url-utils.js";
 import { hasAppNavigationRuntime } from "../client/navigation-runtime.js";
-import { navigateClientSide } from "./navigation.js";
-import { forwardRef, useActionState } from "react";
+import { createRscRequestHeaders, createRscRequestUrl } from "../server/app-rsc-cache-busting.js";
+import { getMountedSlotsHeader, getPrefetchInterceptionContext, getPrefetchedUrls, hasPrefetchCacheEntryForNavigation, navigateClientSide, prefetchRscResponse } from "./navigation.js";
+import { useMergedRef } from "./use-merged-ref.js";
+import { forwardRef, useActionState, useCallback, useEffect, useRef } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/shims/form.tsx
 /**
@@ -24,6 +29,11 @@ import { jsx } from "react/jsx-runtime";
 *   </Form>
 */
 const __basePath = process.env.__NEXT_ROUTER_BASEPATH ?? "";
+const DISALLOWED_FORM_PROPS = [
+	"method",
+	"encType",
+	"target"
+];
 const SUPPORTED_FORM_ENCTYPE = "application/x-www-form-urlencoded";
 const SUPPORTED_FORM_METHOD = "GET";
 const SUPPORTED_FORM_TARGET = "_self";
@@ -45,8 +55,13 @@ function getSubmitter(nativeEvent) {
 	if (submitter instanceof HTMLButtonElement || submitter instanceof HTMLInputElement) return submitter;
 	return null;
 }
-function getEffectiveMethod(submitter, formMethod) {
-	return (submitter?.getAttribute("formmethod") ?? formMethod ?? "GET").toUpperCase();
+function hasReactServerActionAttributes(submitter) {
+	const name = submitter.getAttribute("name");
+	return Boolean(name && (name.startsWith("$ACTION_ID_") || name.startsWith("$ACTION_REF_")));
+}
+function hasReactClientActionAttributes(submitter) {
+	const action = submitter.getAttribute("formAction");
+	return Boolean(action && /\s*javascript:/i.test(action));
 }
 function getEffectiveAction(submitter, formAction) {
 	return submitter?.getAttribute("formaction") ?? formAction;
@@ -65,17 +80,17 @@ function checkFormActionUrl(action, source) {
 function hasUnsupportedSubmitterAttributes(submitter) {
 	const formEncType = submitter.getAttribute("formenctype");
 	if (formEncType !== null && formEncType !== SUPPORTED_FORM_ENCTYPE) {
-		console.error(`<Form>'s \`encType\` was set to an unsupported value via \`formEncType="${formEncType}"\`. This will disable <Form>'s navigation functionality. If you need this, use a native <form> element instead.`);
+		if (process.env.NODE_ENV !== "production") console.error(`<Form>'s \`encType\` was set to an unsupported value via \`formEncType="${formEncType}"\`. This will disable <Form>'s navigation functionality. If you need this, use a native <form> element instead.`);
 		return true;
 	}
 	const formMethod = submitter.getAttribute("formmethod");
 	if (formMethod !== null && formMethod.toUpperCase() !== SUPPORTED_FORM_METHOD) {
-		console.error(`<Form>'s \`method\` was set to an unsupported value via \`formMethod="${formMethod}"\`. This will disable <Form>'s navigation functionality. If you need this, use a native <form> element instead.`);
+		if (process.env.NODE_ENV !== "production") console.error(`<Form>'s \`method\` was set to an unsupported value via \`formMethod="${formMethod}"\`. This will disable <Form>'s navigation functionality. If you need this, use a native <form> element instead.`);
 		return true;
 	}
 	const formTarget = submitter.getAttribute("formtarget");
 	if (formTarget !== null && formTarget !== SUPPORTED_FORM_TARGET) {
-		console.error(`<Form>'s \`target\` was set to an unsupported value via \`formTarget="${formTarget}"\`. This will disable <Form>'s navigation functionality. If you need this, use a native <form> element instead.`);
+		if (process.env.NODE_ENV !== "production") console.error(`<Form>'s \`target\` was set to an unsupported value via \`formTarget="${formTarget}"\`. This will disable <Form>'s navigation functionality. If you need this, use a native <form> element instead.`);
 		return true;
 	}
 	return false;
@@ -84,7 +99,10 @@ function createFormSubmitDestinationUrl(action, form, submitter) {
 	const targetUrl = new URL(action, window.location.href);
 	if (targetUrl.searchParams.size) targetUrl.search = "";
 	const formData = buildFormData(form, submitter);
-	for (const [name, value] of formData) targetUrl.searchParams.append(name, typeof value === "string" ? value : value.name);
+	for (const [name, value] of formData) if (typeof value !== "string") {
+		if (process.env.NODE_ENV !== "production") console.warn("<Form> only supports file inputs if `action` is a function. File inputs cannot be used if `action` is a string, because files cannot be encoded as search params.");
+		targetUrl.searchParams.append(name, value.name);
+	} else targetUrl.searchParams.append(name, value);
 	return toSameOriginPath(targetUrl.href) ?? targetUrl.href;
 }
 function buildFormData(form, submitter) {
@@ -98,31 +116,92 @@ function buildFormData(form, submitter) {
 	}
 }
 const Form = forwardRef(function Form(props, ref) {
-	const { action, replace = false, scroll = true, onSubmit, ...rest } = props;
+	const { action, replace = false, scroll = true, prefetch = null, onSubmit, ...rest } = props;
+	const isNavigatingForm = typeof action === "string";
+	if (process.env.NODE_ENV !== "production") {
+		if (typeof action === "string") checkFormActionUrl(action, "action");
+		if (!(props.prefetch === void 0 || props.prefetch === false || props.prefetch === null)) console.error("The `prefetch` prop of <Form> must be `false` or `null`");
+		if (props.prefetch !== void 0 && !isNavigatingForm) console.error("Passing `prefetch` to a <Form> whose `action` is a function has no effect.");
+		if (!isNavigatingForm && (props.replace !== void 0 || props.scroll !== void 0)) console.error("Passing `replace` or `scroll` to a <Form> whose `action` is a function has no effect.\nSee the relevant docs to learn how to control this behavior for navigations triggered from actions:\n  `redirect()`       - https://nextjs.org/docs/app/api-reference/functions/redirect#parameters\n  `router.replace()` - https://nextjs.org/docs/app/api-reference/functions/use-router#userouter\n");
+	}
+	const cleanRest = { ...rest };
+	for (const key of DISALLOWED_FORM_PROPS) if (key in cleanRest) {
+		if (process.env.NODE_ENV !== "production") console.error(`<Form> does not support changing \`${key}\`. ` + (isNavigatingForm ? "If you'd like to use it to perform a mutation, consider making `action` a function instead.\nLearn more: https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations" : ""));
+		delete cleanRest[key];
+	}
+	const formRef = useRef(null);
+	const setRefs = useMergedRef(useCallback((node) => {
+		formRef.current = node;
+	}, []), ref ?? null);
+	const actionHref = typeof action === "string" ? withBasePath(action, __basePath) : "";
+	useEffect(() => {
+		if (typeof action !== "string") return;
+		if (prefetch === false || process.env.NODE_ENV !== "production") return;
+		if (!isSafeAction(action)) return;
+		if (!hasAppNavigationRuntime()) return;
+		const node = formRef.current;
+		if (!node) return;
+		if (typeof IntersectionObserver === "undefined") return;
+		const observer = new IntersectionObserver((entries) => {
+			for (const entry of entries) if (entry.isIntersecting || entry.intersectionRatio > 0) {
+				(async () => {
+					const interceptionContext = getPrefetchInterceptionContext(actionHref);
+					const mountedSlotsHeader = getMountedSlotsHeader();
+					const headers = createRscRequestHeaders({ interceptionContext });
+					if (mountedSlotsHeader) headers.set(VINEXT_MOUNTED_SLOTS_HEADER, mountedSlotsHeader);
+					const rscUrl = await createRscRequestUrl(actionHref, headers);
+					const cacheKey = AppElementsWire.encodeCacheKey(rscUrl, interceptionContext);
+					const prefetched = getPrefetchedUrls();
+					if (prefetched.has(cacheKey)) return;
+					if (hasPrefetchCacheEntryForNavigation(rscUrl, interceptionContext, mountedSlotsHeader)) return;
+					prefetched.add(cacheKey);
+					prefetchRscResponse(rscUrl, fetch(rscUrl, {
+						headers,
+						credentials: "include",
+						priority: "low",
+						purpose: "prefetch"
+					}), interceptionContext, mountedSlotsHeader, void 0, {
+						cacheForNavigation: true,
+						optimisticRouteShell: false
+					});
+				})();
+				observer.unobserve(node);
+			}
+		}, { rootMargin: "200px" });
+		observer.observe(node);
+		return () => {
+			observer.unobserve(node);
+		};
+	}, [
+		action,
+		prefetch,
+		actionHref
+	]);
 	if (typeof action === "function") return /* @__PURE__ */ jsx("form", {
-		ref,
+		ref: setRefs,
 		action,
 		onSubmit,
-		...rest
+		...cleanRest
 	});
-	if (process.env.NODE_ENV !== "production") checkFormActionUrl(action, "action");
 	if (!isSafeAction(action)) {
 		if (process.env.NODE_ENV !== "production") console.warn(`<Form> blocked unsafe action: ${action}`);
 		return /* @__PURE__ */ jsx("form", {
-			ref,
+			ref: setRefs,
 			onSubmit,
-			...rest
+			...cleanRest
 		});
 	}
-	const actionHref = withBasePath(action, __basePath);
 	async function handleSubmit(e) {
 		if (onSubmit) {
 			onSubmit(e);
 			if (e.defaultPrevented) return;
 		}
 		const submitter = getSubmitter(e.nativeEvent);
-		if (submitter && hasUnsupportedSubmitterAttributes(submitter)) return;
-		if (getEffectiveMethod(submitter, rest.method) !== "GET") return;
+		if (submitter) {
+			if (process.env.NODE_ENV !== "production" && hasReactServerActionAttributes(submitter)) return;
+			if (hasUnsupportedSubmitterAttributes(submitter)) return;
+			if (hasReactClientActionAttributes(submitter)) return;
+		}
 		const effectiveAction = getEffectiveAction(submitter, actionHref);
 		if (process.env.NODE_ENV !== "production" && submitter?.getAttribute("formaction") !== null) checkFormActionUrl(effectiveAction, "formAction");
 		if (!isSafeAction(effectiveAction)) {
@@ -145,15 +224,13 @@ const Form = forwardRef(function Form(props, ref) {
 		}
 	}
 	return /* @__PURE__ */ jsx("form", {
-		ref,
+		ref: setRefs,
 		action: actionHref,
 		onSubmit: (event) => {
 			handleSubmit(event);
 		},
-		...rest
+		...cleanRest
 	});
 });
 //#endregion
 export { Form as default, useActionState };
-
-//# sourceMappingURL=form.js.map

package/dist/shims/hash-scroll.d.ts

@@ -2,6 +2,8 @@
 declare function decodeHashFragment(fragment: string): string;
 declare function scrollToHashTarget(hash: string): void;
 declare function scrollToHashTargetOnNextFrame(hash: string): void;
+declare function retryScrollTo(x: number, y: number, opts?: {
+  shouldContinue?: () => boolean;
+}): void;
 //#endregion
-export { decodeHashFragment, scrollToHashTarget, scrollToHashTargetOnNextFrame };
-//# sourceMappingURL=hash-scroll.d.ts.map
+export { decodeHashFragment, retryScrollTo, scrollToHashTarget, scrollToHashTargetOnNextFrame };

package/dist/shims/hash-scroll.js

@@ -24,7 +24,17 @@ function scrollToHashTargetOnNextFrame(hash) {
 		scrollToHashTarget(hash);
 	});
 }
+function retryScrollTo(x, y, opts) {
+	const shouldContinue = opts?.shouldContinue ?? (() => true);
+	let attempts = 0;
+	const restore = () => {
+		if (!shouldContinue()) return;
+		window.scrollTo(x, y);
+		if (!shouldContinue() || Math.abs(window.scrollY - y) <= 1 || attempts >= 60) return;
+		attempts += 1;
+		requestAnimationFrame(restore);
+	};
+	restore();
+}
 //#endregion
-export { decodeHashFragment, scrollToHashTarget, scrollToHashTargetOnNextFrame };
-
-//# sourceMappingURL=hash-scroll.js.map
+export { decodeHashFragment, retryScrollTo, scrollToHashTarget, scrollToHashTargetOnNextFrame };

package/dist/shims/head-state.d.ts

@@ -3,6 +3,7 @@ import React from "react";
 //#region src/shims/head-state.d.ts
 type HeadState = {
   ssrHeadChildren: React.ReactNode[];
+  documentInitialHead: React.ReactNode[];
 };
 /**
  * Run a function within a head state ALS scope.
@@ -12,5 +13,4 @@ type HeadState = {
 declare function runWithHeadState<T>(fn: () => Promise<T>): Promise<T>;
 declare function runWithHeadState<T>(fn: () => T | Promise<T>): T | Promise<T>;
 //#endregion
-export { HeadState, runWithHeadState };
-//# sourceMappingURL=head-state.d.ts.map
+export { HeadState, runWithHeadState };

package/dist/shims/head-state.js

@@ -5,7 +5,10 @@ import { _registerHeadStateAccessors } from "./head.js";
 const _FALLBACK_KEY = Symbol.for("vinext.head.fallback");
 const _g = globalThis;
 const _als = getOrCreateAls("vinext.head.als");
-const _fallbackState = _g[_FALLBACK_KEY] ??= { ssrHeadChildren: [] };
+const _fallbackState = _g[_FALLBACK_KEY] ??= {
+	ssrHeadChildren: [],
+	documentInitialHead: []
+};
 function _getState() {
 	if (isInsideUnifiedScope()) return getRequestContext();
 	return _als.getStore() ?? _fallbackState;
@@ -13,18 +16,28 @@ function _getState() {
 function runWithHeadState(fn) {
 	if (isInsideUnifiedScope()) return runWithUnifiedStateMutation((uCtx) => {
 		uCtx.ssrHeadChildren = [];
+		uCtx.documentInitialHead = [];
+	}, fn);
+	return _als.run({
+		ssrHeadChildren: [],
+		documentInitialHead: []
 	}, fn);
-	return _als.run({ ssrHeadChildren: [] }, fn);
 }
 _registerHeadStateAccessors({
 	getSSRHeadChildren() {
 		return _getState().ssrHeadChildren;
 	},
 	resetSSRHead() {
-		_getState().ssrHeadChildren = [];
+		const s = _getState();
+		s.ssrHeadChildren = [];
+		s.documentInitialHead = [];
+	},
+	getDocumentInitialHead() {
+		return _getState().documentInitialHead;
+	},
+	setDocumentInitialHead(head) {
+		_getState().documentInitialHead = head;
 	}
 });
 //#endregion
 export { runWithHeadState };
-
-//# sourceMappingURL=head-state.js.map

package/dist/shims/head.d.ts

@@ -4,6 +4,8 @@ import React from "react";
 type HeadProps = {
   children?: React.ReactNode;
 };
+/** @internal — exposed for unit tests of the client head projection. */
+declare const _clientHeadChildren: Map<symbol, React.ReactNode>;
 /**
  * Register ALS-backed state accessors. Called by head-state.ts on import.
  * @internal
@@ -11,9 +13,21 @@ type HeadProps = {
 declare function _registerHeadStateAccessors(accessors: {
   getSSRHeadChildren: () => React.ReactNode[];
   resetSSRHead: () => void;
+  getDocumentInitialHead?: () => React.ReactNode[];
+  setDocumentInitialHead?: (head: React.ReactNode[]) => void;
 }): void;
 /** Reset the SSR head collector. Call before render. */
 declare function resetSSRHead(): void;
+/**
+ * Register head tags returned by a user `_document.getInitialProps()` call.
+ * Mirrors Next.js: `_document` may extend the head array passed to its render,
+ * and those tags are merged into the final `<head>` output. We treat them the
+ * same as `next/head` children — they go through the same dedupe pipeline so
+ * later tags (by key or meta-type) win, matching Next.js semantics.
+ *
+ * Pass an empty array (or simply don't call this) to skip the merge.
+ */
+declare function setDocumentInitialHead(head: React.ReactNode[]): void;
 /** Get collected head HTML. Call after render. */
 declare function getSSRHeadHTML(): string;
 type HeadDOMElement = Pick<HTMLElement, "innerHTML" | "setAttribute" | "textContent">;
@@ -32,9 +46,28 @@ declare function escapeAttr(s: string): string;
  */
 declare function escapeInlineContent(content: string, tag: string): string;
 declare function _applyHeadPropsToElement(domEl: HeadDOMElement, props: Record<string, unknown>): void;
+/**
+ * Reconcile the document <head> against the desired projection.
+ *
+ * Mirrors Next.js's client `head-manager.ts` `updateElements()`: rather than
+ * wiping every [data-next-head] node and re-appending (which reorders the
+ * SSR-emitted tags to the end of <head> and causes flicker on each update),
+ * we diff the desired tags against the existing ones with isEqualNode(). Tags
+ * that already match are left untouched in their original DOM position, only
+ * genuinely new tags are inserted, and stale tags are removed.
+ *
+ * The desired list seeds defaultHead() (charset + viewport) ahead of user
+ * tags — matching the SSR path in getSSRHeadHTML() and Next.js's
+ * reduceComponents(), which always concatenates defaultHead() on both server
+ * and client. Without it the first <Head> mount after hydration would drop the
+ * server-rendered defaults. Users can still override via key="charset" /
+ * key="viewport" through the dedupe pipeline.
+ *
+ * @internal — exported for unit tests; called from the Head client effect.
+ */
+declare function _syncClientHead(): void;
 declare function Head({
   children
 }: HeadProps): null;
 //#endregion
-export { _applyHeadPropsToElement, _registerHeadStateAccessors, Head as default, escapeAttr, escapeInlineContent, getSSRHeadHTML, isSafeAttrName, reduceHeadChildren, resetSSRHead };
-//# sourceMappingURL=head.d.ts.map
+export { _applyHeadPropsToElement, _clientHeadChildren, _registerHeadStateAccessors, _syncClientHead, Head as default, escapeAttr, escapeInlineContent, getSSRHeadHTML, isSafeAttrName, reduceHeadChildren, resetSSRHead, setDocumentInitialHead };