@qzsy/vinext 0.1.7

package/dist/server/image-optimization.js

@@ -0,0 +1,247 @@
+import { badRequestResponse } from "./http-error-responses.js";
+//#region src/server/image-optimization.ts
+/**
+* Image optimization request handler.
+*
+* Handles `/_next/image?url=...&w=...&q=...` requests. In production
+* on Cloudflare Workers, uses the Images binding (`env.IMAGES`) to
+* resize and transcode on the fly. On other runtimes (Node.js dev/prod
+* server), serves the original file as a passthrough with appropriate
+* Cache-Control headers.
+*
+* Format negotiation: inspects the `Accept` header and serves AVIF, WebP,
+* or JPEG depending on client support.
+*
+* Security: All image responses include Content-Security-Policy and
+* X-Content-Type-Options headers to prevent XSS via SVG or Content-Type
+* spoofing. SVG content is blocked by default (following Next.js behavior).
+* When `dangerouslyAllowSVG` is enabled in next.config.js, SVGs are served
+* as-is (no transformation) with security headers applied.
+*/
+/** The pathname that triggers image optimization (matches Next.js). */
+const IMAGE_OPTIMIZATION_PATH = "/_next/image";
+/**
+* Vinext-prefixed alias for the image optimization endpoint. Accepted
+* alongside IMAGE_OPTIMIZATION_PATH so apps that wire image URLs to the
+* vinext-prefixed path continue to work; emit IMAGE_OPTIMIZATION_PATH
+* for any newly generated URLs.
+*/
+const VINEXT_IMAGE_OPTIMIZATION_PATH = "/_vinext/image";
+/** Returns true when `pathname` is either supported image optimization endpoint. */
+function isImageOptimizationPath(pathname) {
+	return pathname === "/_next/image" || pathname === "/_vinext/image";
+}
+/**
+* Next.js default device sizes and image sizes.
+* These are the allowed widths for image optimization when no custom
+* config is provided. Matches Next.js defaults exactly.
+*/
+const DEFAULT_DEVICE_SIZES = [
+	640,
+	750,
+	828,
+	1080,
+	1200,
+	1920,
+	2048,
+	3840
+];
+const DEFAULT_IMAGE_SIZES = [
+	16,
+	32,
+	48,
+	64,
+	96,
+	128,
+	256,
+	384
+];
+const DEV_BLUR_MAX_WIDTH = 8;
+const DEV_BLUR_QUALITY = 70;
+/**
+* Pick the allowed width numerically closest to the requested value.
+* On a tie, prefer the larger width so the served image is not undersized.
+*/
+function snapToNearestAllowedWidth(requestedWidth, allowedWidths) {
+	if (allowedWidths.length === 0) return requestedWidth;
+	let closest = allowedWidths[0];
+	let minDiff = Math.abs(requestedWidth - closest);
+	for (const candidate of allowedWidths) {
+		const diff = Math.abs(requestedWidth - candidate);
+		if (diff < minDiff || diff === minDiff && candidate > closest) {
+			minDiff = diff;
+			closest = candidate;
+		}
+	}
+	return closest;
+}
+function resolveDevImageRedirect(requestUrl, allowedWidths = [...DEFAULT_DEVICE_SIZES, ...DEFAULT_IMAGE_SIZES], allowedQualities, options = { isDev: true }) {
+	const params = parseImageParams(requestUrl, allowedWidths, allowedQualities, options);
+	if (!params) return null;
+	if (params.imageUrl.startsWith("/@") || params.imageUrl.startsWith("/__vite") || params.imageUrl.startsWith("/node_modules")) return null;
+	const resolved = new URL(params.imageUrl, requestUrl.origin);
+	if (resolved.origin !== requestUrl.origin) return null;
+	return resolved.pathname + resolved.search;
+}
+/**
+* Parse and validate image optimization query parameters.
+* Returns null if the request is malformed.
+*
+* Ported from Next.js:
+* test/integration/image-optimizer/test/index.test.ts
+* https://github.com/vercel/next.js/blob/canary/test/integration/image-optimizer/test/index.test.ts
+*/
+function parseImageParams(url, allowedWidths = [...DEFAULT_DEVICE_SIZES, ...DEFAULT_IMAGE_SIZES], allowedQualities, options = {}) {
+	const allowedParamNames = new Set([
+		"url",
+		"w",
+		"q"
+	]);
+	for (const name of url.searchParams.keys()) if (!allowedParamNames.has(name) || url.searchParams.getAll(name).length !== 1) return null;
+	const imageUrl = url.searchParams.get("url");
+	if (!imageUrl) return null;
+	if (imageUrl.length > 3072) return null;
+	const widthParam = url.searchParams.get("w");
+	const qualityParam = url.searchParams.get("q");
+	if (!widthParam || !/^[0-9]+$/.test(widthParam)) return null;
+	if (!qualityParam || !/^[0-9]+$/.test(qualityParam)) return null;
+	const width = Number.parseInt(widthParam, 10);
+	const quality = Number.parseInt(qualityParam, 10);
+	if (String(width) !== widthParam || String(quality) !== qualityParam) return null;
+	const isDevBlurWidth = options.isDev && width <= DEV_BLUR_MAX_WIDTH;
+	const isDevBlurQuality = options.isDev && quality === DEV_BLUR_QUALITY;
+	if (width <= 0) return null;
+	const resolvedWidth = isDevBlurWidth || allowedWidths.includes(width) ? width : snapToNearestAllowedWidth(width, allowedWidths);
+	if (quality < 1 || quality > 100) return null;
+	if (allowedQualities && !allowedQualities.includes(quality) && !isDevBlurQuality) return null;
+	const normalizedUrl = imageUrl.replaceAll("\\", "/");
+	if (!normalizedUrl.startsWith("/") || normalizedUrl.startsWith("//")) return null;
+	try {
+		const base = "https://localhost";
+		if (new URL(normalizedUrl, base).origin !== base) return null;
+	} catch {
+		return null;
+	}
+	return {
+		imageUrl: normalizedUrl,
+		width: resolvedWidth,
+		quality
+	};
+}
+/**
+* Negotiate the best output format based on the Accept header.
+* Returns an IANA media type.
+*/
+function negotiateImageFormat(acceptHeader) {
+	if (!acceptHeader) return "image/jpeg";
+	if (acceptHeader.includes("image/avif")) return "image/avif";
+	if (acceptHeader.includes("image/webp")) return "image/webp";
+	return "image/jpeg";
+}
+/**
+* Standard Cache-Control header for optimized images.
+* Optimized images are immutable because the URL encodes the transform params.
+*/
+const IMAGE_CACHE_CONTROL = "public, max-age=31536000, immutable";
+/**
+* Content-Security-Policy for image optimization responses.
+* Blocks script execution and framing to prevent XSS via SVG or other
+* active content that might be served through the image endpoint.
+* Matches Next.js default: script-src 'none'; frame-src 'none'; sandbox;
+*/
+const IMAGE_CONTENT_SECURITY_POLICY = "script-src 'none'; frame-src 'none'; sandbox;";
+/**
+* Allowlist of Content-Types that are safe to serve from the image endpoint.
+* SVG is intentionally excluded — it can contain embedded JavaScript and is
+* essentially an XML document, not a safe raster image format.
+*/
+const SAFE_IMAGE_CONTENT_TYPES = new Set([
+	"image/jpeg",
+	"image/png",
+	"image/gif",
+	"image/webp",
+	"image/avif",
+	"image/x-icon",
+	"image/vnd.microsoft.icon",
+	"image/bmp",
+	"image/tiff"
+]);
+/**
+* Check if a Content-Type header value is a safe image type.
+* Returns false for SVG (unless dangerouslyAllowSVG is true), HTML, or any non-image type.
+*/
+function isSafeImageContentType(contentType, dangerouslyAllowSVG = false) {
+	if (!contentType) return false;
+	const mediaType = contentType.split(";")[0].trim().toLowerCase();
+	if (SAFE_IMAGE_CONTENT_TYPES.has(mediaType)) return true;
+	if (dangerouslyAllowSVG && mediaType === "image/svg+xml") return true;
+	return false;
+}
+/**
+* Apply security headers to an image optimization response.
+* These headers are set on every response from the image endpoint,
+* regardless of whether the image was transformed or served as-is.
+* When an ImageConfig is provided, uses its values for CSP and Content-Disposition.
+*/
+function setImageSecurityHeaders(headers, config) {
+	headers.set("Content-Security-Policy", config?.contentSecurityPolicy ?? "script-src 'none'; frame-src 'none'; sandbox;");
+	headers.set("X-Content-Type-Options", "nosniff");
+	headers.set("Content-Disposition", config?.contentDispositionType === "attachment" ? "attachment" : "inline");
+}
+function createPassthroughImageResponse(source, config) {
+	const headers = new Headers(source.headers);
+	headers.set("Cache-Control", IMAGE_CACHE_CONTROL);
+	headers.set("Vary", "Accept");
+	setImageSecurityHeaders(headers, config);
+	return new Response(source.body, {
+		status: 200,
+		headers
+	});
+}
+/**
+* Handle image optimization requests.
+*
+* Parses and validates the request, fetches the source image via the provided
+* handlers, optionally transforms it, and returns the response with appropriate
+* cache headers.
+*/
+async function handleImageOptimization(request, handlers, allowedWidths, imageConfig) {
+	const params = parseImageParams(new URL(request.url), allowedWidths, imageConfig?.qualities);
+	if (!params) return badRequestResponse();
+	const { imageUrl, width, quality } = params;
+	const source = await handlers.fetchAsset(imageUrl, request);
+	if (!source.ok || !source.body) return new Response("Image not found", { status: 404 });
+	const format = negotiateImageFormat(request.headers.get("Accept"));
+	const sourceContentType = source.headers.get("Content-Type");
+	if (!isSafeImageContentType(sourceContentType, imageConfig?.dangerouslyAllowSVG)) return new Response("The requested resource is not an allowed image type", { status: 400 });
+	if (sourceContentType?.split(";")[0].trim().toLowerCase() === "image/svg+xml") return createPassthroughImageResponse(source, imageConfig);
+	if (handlers.transformImage) try {
+		const transformed = await handlers.transformImage(source.body, {
+			width,
+			format,
+			quality
+		});
+		const headers = new Headers(transformed.headers);
+		headers.set("Cache-Control", IMAGE_CACHE_CONTROL);
+		headers.set("Vary", "Accept");
+		setImageSecurityHeaders(headers, imageConfig);
+		if (!isSafeImageContentType(headers.get("Content-Type"), imageConfig?.dangerouslyAllowSVG)) headers.set("Content-Type", format);
+		return new Response(transformed.body, {
+			status: 200,
+			headers
+		});
+	} catch (e) {
+		console.error("[vinext] Image optimization error:", e);
+	}
+	try {
+		return createPassthroughImageResponse(source, imageConfig);
+	} catch (e) {
+		console.error("[vinext] Image fallback error, refetching source image:", e);
+		const refetchedSource = await handlers.fetchAsset(imageUrl, request);
+		if (!refetchedSource.ok || !refetchedSource.body) return new Response("Image not found", { status: 404 });
+		if (!isSafeImageContentType(refetchedSource.headers.get("Content-Type"), imageConfig?.dangerouslyAllowSVG)) return new Response("The requested resource is not an allowed image type", { status: 400 });
+		return createPassthroughImageResponse(refetchedSource, imageConfig);
+	}
+}
+//#endregion
+export { DEFAULT_DEVICE_SIZES, DEFAULT_IMAGE_SIZES, IMAGE_CACHE_CONTROL, IMAGE_CONTENT_SECURITY_POLICY, IMAGE_OPTIMIZATION_PATH, VINEXT_IMAGE_OPTIMIZATION_PATH, handleImageOptimization, isImageOptimizationPath, isSafeImageContentType, negotiateImageFormat, parseImageParams, resolveDevImageRedirect, snapToNearestAllowedWidth };

package/dist/server/implicit-tags.d.ts

@@ -0,0 +1,6 @@
+//#region src/server/implicit-tags.d.ts
+type AppCacheLeafKind = "page" | "route";
+declare function buildAppPageTags(cleanPathname: string, extraTags: string[], routeSegments: readonly string[]): string[];
+declare function buildPageCacheTags(pathname: string, extraTags: string[], routeSegments: string[], leafKind: AppCacheLeafKind): string[];
+//#endregion
+export { buildAppPageTags, buildPageCacheTags };

package/dist/server/implicit-tags.js

@@ -0,0 +1,44 @@
+import { encodeCacheTag } from "../utils/encode-cache-tag.js";
+//#region src/server/implicit-tags.ts
+const NEXT_CACHE_IMPLICIT_TAG_ID = "_N_T_";
+function appendUnique(tags, tag) {
+	if (!tags.includes(tag)) tags.push(tag);
+}
+function normalizeRouteSegment(segment) {
+	if (!segment || segment === "." || segment.startsWith("@")) return null;
+	return segment;
+}
+function buildRouteCachePath(routeSegments, leafKind) {
+	const parts = [];
+	for (const segment of routeSegments) {
+		const normalized = normalizeRouteSegment(segment);
+		if (normalized) parts.push(normalized);
+	}
+	parts.push(leafKind);
+	return `/${parts.join("/")}`;
+}
+function appendDerivedTags(tags, routePath) {
+	appendUnique(tags, `${NEXT_CACHE_IMPLICIT_TAG_ID}/layout`);
+	if (!routePath.startsWith("/")) return;
+	const routeParts = routePath.split("/");
+	const leafIndex = routeParts.length - 1;
+	for (let i = 1; i <= routeParts.length; i++) {
+		let currentPathname = routeParts.slice(0, i).join("/");
+		if (!currentPathname) continue;
+		if (!(i - 1 === leafIndex)) currentPathname = `${currentPathname}/layout`;
+		appendUnique(tags, `${NEXT_CACHE_IMPLICIT_TAG_ID}${currentPathname}`);
+	}
+}
+function buildAppPageTags(cleanPathname, extraTags, routeSegments) {
+	return buildPageCacheTags(cleanPathname, extraTags, [...routeSegments], "page");
+}
+function buildPageCacheTags(pathname, extraTags, routeSegments, leafKind) {
+	const tags = [pathname, `${NEXT_CACHE_IMPLICIT_TAG_ID}${pathname}`];
+	if (pathname === "/") appendUnique(tags, `${NEXT_CACHE_IMPLICIT_TAG_ID}/index`);
+	if (pathname === "/index") appendUnique(tags, `${NEXT_CACHE_IMPLICIT_TAG_ID}/`);
+	appendDerivedTags(tags, buildRouteCachePath(routeSegments, leafKind));
+	for (const tag of extraTags) appendUnique(tags, tag);
+	return tags.map(encodeCacheTag);
+}
+//#endregion
+export { buildAppPageTags, buildPageCacheTags };

package/dist/server/instrumentation-runtime.d.ts

@@ -0,0 +1,49 @@
+//#region src/server/instrumentation-runtime.d.ts
+/**
+ * Lazy, idempotent instrumentation initialisation.
+ *
+ * The generated App Router RSC entry calls this on the first request instead
+ * of embedding the bookkeeping directly in codegen. This keeps the entry
+ * module thin (it only describes the app shape) while the actual runtime
+ * behaviour lives in a normal typed module that can be unit-tested.
+ *
+ * ## Why lazy?
+ *
+ * A top-level `await` at module evaluation time blocks the entire V8 isolate
+ * startup phase. On Cloudflare Workers that latency is added to every cold
+ * start. Moving the `register()` call into the first request handler keeps
+ * module evaluation synchronous while still guaranteeing that instrumentation
+ * runs before any request is handled.
+ *
+ * ## Why idempotent?
+ *
+ * The same handler may be invoked concurrently (e.g. on a warm Worker).
+ * A module-level `initialized` flag + a shared promise ensure that
+ * `register()` is called exactly once even when multiple requests race.
+ *
+ * ## Next.js semantics
+ *
+ * Next.js calls `register()` once when the server process starts, before any
+ * request handling. Our lazy init preserves that guarantee because the first
+ * request cannot proceed past this call until `register()` has resolved.
+ *
+ * References:
+ * - https://nextjs.org/docs/app/building-your-application/optimizing/instrumentation
+ */
+/**
+ * Ensure the instrumentation module's `register()` and `onRequestError`
+ * hooks have been applied exactly once.
+ *
+ * After `register()` runs, we extend the OTel tracer provider so that spans
+ * created inside Cache Component renders (warmup / fallback-resume phases) use
+ * a fresh OTel context rather than inheriting the prerender work unit store.
+ * This mirrors Next.js's `afterRegistration()` call in
+ * `instrumentation-node-extensions.ts`.
+ *
+ * @param instrumentationModule - The imported `instrumentation.ts` module.
+ *   Passed as an argument so the generated entry can import it normally
+ *   without this helper needing to know the module path.
+ */
+declare function ensureInstrumentationRegistered(instrumentationModule: Record<string, unknown>): Promise<void>;
+//#endregion
+export { ensureInstrumentationRegistered };

package/dist/server/instrumentation-runtime.js

@@ -0,0 +1,35 @@
+import { extendTracerProviderForCacheComponents } from "./otel-tracer-extension.js";
+//#region src/server/instrumentation-runtime.ts
+let initialized = false;
+let initPromise = null;
+function isOnRequestErrorHandler(value) {
+	return typeof value === "function";
+}
+/**
+* Ensure the instrumentation module's `register()` and `onRequestError`
+* hooks have been applied exactly once.
+*
+* After `register()` runs, we extend the OTel tracer provider so that spans
+* created inside Cache Component renders (warmup / fallback-resume phases) use
+* a fresh OTel context rather than inheriting the prerender work unit store.
+* This mirrors Next.js's `afterRegistration()` call in
+* `instrumentation-node-extensions.ts`.
+*
+* @param instrumentationModule - The imported `instrumentation.ts` module.
+*   Passed as an argument so the generated entry can import it normally
+*   without this helper needing to know the module path.
+*/
+async function ensureInstrumentationRegistered(instrumentationModule) {
+	if (process.env.VINEXT_PRERENDER === "1") return;
+	if (initialized) return;
+	if (initPromise) return initPromise;
+	initPromise = (async () => {
+		if (typeof instrumentationModule.register === "function") await instrumentationModule.register();
+		extendTracerProviderForCacheComponents();
+		if (isOnRequestErrorHandler(instrumentationModule.onRequestError)) globalThis.__VINEXT_onRequestErrorHandler__ = instrumentationModule.onRequestError;
+		initialized = true;
+	})();
+	return initPromise;
+}
+//#endregion
+export { ensureInstrumentationRegistered };

package/dist/server/instrumentation.d.ts

@@ -0,0 +1,85 @@
+import { ValidFileMatcher } from "../routing/file-matcher.js";
+
+//#region src/server/instrumentation.d.ts
+/**
+ * Minimal duck-typed interface for the module runner passed to
+ * `runInstrumentation`. Only `.import()` is used — this avoids requiring
+ * callers (including tests) to provide a full `ModuleRunner` instance.
+ */
+type ModuleImporter = {
+  import(id: string): Promise<unknown>;
+};
+/**
+ * Import a module via the runner and cast the result to `Record<string, any>`.
+ *
+ * Centralises the `as Record<string, any>` cast so callers don't need
+ * per-call oxlint-disable comments.
+ */
+declare function importModule(runner: ModuleImporter, id: string): Promise<Record<string, any>>;
+/**
+ * Find the instrumentation file in the project root.
+ */
+declare function findInstrumentationFile(root: string, fileMatcher: ValidFileMatcher): string | null;
+/**
+ * Find the instrumentation-client file in the project root.
+ */
+declare function findInstrumentationClientFile(root: string, fileMatcher: ValidFileMatcher): string | null;
+/**
+ * The onRequestError handler type from Next.js instrumentation.
+ *
+ * Called when an unhandled error occurs during request handling.
+ * Provides the error, the request info, and an error context.
+ */
+type OnRequestErrorContext = {
+  /** The route path (e.g., '/blog/[slug]') */routerKind: "Pages Router" | "App Router"; /** The matched route pattern */
+  routePath: string; /** The route type */
+  routeType: "render" | "route" | "action" | "middleware"; /** HTTP status code that will be sent */
+  revalidateReason?: "on-demand" | "stale" | undefined;
+};
+type OnRequestErrorHandler = (error: Error, request: {
+  path: string;
+  method: string;
+  headers: Record<string, string>;
+}, context: OnRequestErrorContext) => void | Promise<void>;
+/**
+ * Get the registered onRequestError handler (if any).
+ *
+ * Reads from globalThis so it works across Vite environment boundaries.
+ */
+declare function getOnRequestErrorHandler(): OnRequestErrorHandler | null;
+/**
+ * Load and execute the instrumentation file via a ModuleRunner.
+ *
+ * Called once during Pages Router server startup (`configureServer`). It:
+ * 1. Loads the instrumentation module via `runner.import()`.
+ * 2. Calls the `register()` function if exported.
+ * 3. Stores the `onRequestError()` handler on `globalThis` so it is visible
+ *    to all Vite environment module graphs (SSR and the host process share
+ *    the same Node.js `globalThis`).
+ *
+ * **App Router** does not use this function. For App Router, `register()` is
+ * emitted as a top-level `await` inside the generated RSC entry module so it
+ * runs in the same Worker/environment as request handling.
+ *
+ * @param runner - A ModuleRunner created via `createDirectRunner()`. Must be
+ *   the same long-lived runner used for middleware and SSR so the module graph
+ *   is shared. Safe with all Vite plugin combinations, including
+ *   `@cloudflare/vite-plugin`, because it never touches the hot channel.
+ * @param instrumentationPath - Absolute path to the instrumentation file
+ */
+declare function runInstrumentation(runner: ModuleImporter, instrumentationPath: string): Promise<void>;
+/**
+ * Report a request error via the instrumentation handler.
+ *
+ * No-op if no onRequestError handler is registered.
+ *
+ * Reads the handler from globalThis so this function works correctly regardless
+ * of which environment it is called from.
+ */
+declare function reportRequestError(error: Error, request: {
+  path: string;
+  method: string;
+  headers: Record<string, string>;
+}, context: OnRequestErrorContext): Promise<void>;
+//#endregion
+export { ModuleImporter, OnRequestErrorContext, OnRequestErrorHandler, findInstrumentationClientFile, findInstrumentationFile, getOnRequestErrorHandler, importModule, reportRequestError, runInstrumentation };

package/dist/server/instrumentation.js

@@ -0,0 +1,130 @@
+import { getRequestExecutionContext } from "../shims/request-context.js";
+import fs from "node:fs";
+import path from "node:path";
+//#region src/server/instrumentation.ts
+/**
+* instrumentation.ts support
+*
+* Next.js supports an `instrumentation.ts` file at the project root that
+* exports a `register()` function. This function is called once when the
+* server starts, before any request handling. It's the recommended way to
+* set up observability tools (Sentry, Datadog, OpenTelemetry, etc.).
+*
+* Optionally, it can also export `onRequestError()` which is called when
+* an unhandled error occurs during request handling.
+*
+* References:
+* - https://nextjs.org/docs/app/building-your-application/optimizing/instrumentation
+*
+* ## App Router
+*
+* For App Router, `register()` is baked directly into the generated RSC entry
+* as a top-level `await` at module evaluation time (see `entries/app-rsc-entry.ts`
+* `generateRscEntry`). This means it runs inside the Worker process (or RSC
+* Vite environment) — the same process that handles requests — before any
+* request is served. `runInstrumentation()` is NOT called from `configureServer`
+* for App Router.
+*
+* The `onRequestError` handler is stored on `globalThis` so it is visible across
+* the RSC and SSR Vite environments (separate module graphs, same Node.js process).
+* With `@cloudflare/vite-plugin` it runs entirely inside the Worker, so
+* `globalThis` is the Worker's global — also correct.
+*
+* ## Pages Router
+*
+* Pages Router has no RSC entry, so `configureServer()` is the right place to
+* call `register()`. `runInstrumentation()` accepts a `ModuleRunner` (created
+* via `createDirectRunner()`) rather than `server.ssrLoadModule()` so it is
+* safe when `@cloudflare/vite-plugin` is present — that plugin replaces the
+* SSR environment's hot channel, causing `ssrLoadModule()` to crash with
+* `TypeError: Cannot read properties of undefined (reading 'outsideEmitter')`.
+*/
+/**
+* Import a module via the runner and cast the result to `Record<string, any>`.
+*
+* Centralises the `as Record<string, any>` cast so callers don't need
+* per-call oxlint-disable comments.
+*/
+async function importModule(runner, id) {
+	return await runner.import(id);
+}
+const INSTRUMENTATION_LOCATIONS = ["", "src/"];
+function findInstrumentationHookFile(root, basename, fileMatcher) {
+	for (const dir of INSTRUMENTATION_LOCATIONS) for (const ext of fileMatcher.dottedExtensions) {
+		const fullPath = path.posix.join(root, dir, `${basename}${ext}`);
+		if (fs.existsSync(fullPath)) return fullPath;
+	}
+	return null;
+}
+/**
+* Find the instrumentation file in the project root.
+*/
+function findInstrumentationFile(root, fileMatcher) {
+	return findInstrumentationHookFile(root, "instrumentation", fileMatcher);
+}
+/**
+* Find the instrumentation-client file in the project root.
+*/
+function findInstrumentationClientFile(root, fileMatcher) {
+	return findInstrumentationHookFile(root, "instrumentation-client", fileMatcher);
+}
+/**
+* Get the registered onRequestError handler (if any).
+*
+* Reads from globalThis so it works across Vite environment boundaries.
+*/
+function getOnRequestErrorHandler() {
+	return globalThis.__VINEXT_onRequestErrorHandler__ ?? null;
+}
+/**
+* Load and execute the instrumentation file via a ModuleRunner.
+*
+* Called once during Pages Router server startup (`configureServer`). It:
+* 1. Loads the instrumentation module via `runner.import()`.
+* 2. Calls the `register()` function if exported.
+* 3. Stores the `onRequestError()` handler on `globalThis` so it is visible
+*    to all Vite environment module graphs (SSR and the host process share
+*    the same Node.js `globalThis`).
+*
+* **App Router** does not use this function. For App Router, `register()` is
+* emitted as a top-level `await` inside the generated RSC entry module so it
+* runs in the same Worker/environment as request handling.
+*
+* @param runner - A ModuleRunner created via `createDirectRunner()`. Must be
+*   the same long-lived runner used for middleware and SSR so the module graph
+*   is shared. Safe with all Vite plugin combinations, including
+*   `@cloudflare/vite-plugin`, because it never touches the hot channel.
+* @param instrumentationPath - Absolute path to the instrumentation file
+*/
+async function runInstrumentation(runner, instrumentationPath) {
+	try {
+		const mod = await runner.import(instrumentationPath);
+		if (typeof mod.register === "function") await mod.register();
+		if (typeof mod.onRequestError === "function") globalThis.__VINEXT_onRequestErrorHandler__ = mod.onRequestError;
+	} catch (err) {
+		console.error("[vinext] Failed to load instrumentation:", err instanceof Error ? err.message : String(err));
+	}
+}
+/**
+* Report a request error via the instrumentation handler.
+*
+* No-op if no onRequestError handler is registered.
+*
+* Reads the handler from globalThis so this function works correctly regardless
+* of which environment it is called from.
+*/
+function reportRequestError(error, request, context) {
+	const handler = getOnRequestErrorHandler();
+	if (!handler) return Promise.resolve();
+	const promise = (async () => {
+		try {
+			await handler(error, request, context);
+		} catch (reportErr) {
+			console.error("[vinext] onRequestError handler threw:", reportErr instanceof Error ? reportErr.message : String(reportErr));
+		}
+	})();
+	getRequestExecutionContext()?.waitUntil(promise);
+	return promise;
+}
+//#endregion
+export { findInstrumentationClientFile, findInstrumentationFile, getOnRequestErrorHandler, importModule, reportRequestError, runInstrumentation };