@withl5e/l5e 0.2.7 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withl5e/l5e",
-  "version": "0.2.7",
+  "version": "0.3.1",
   "description": "HTML-first SSR MPA framework with loaders, middleware, islands, actions, swap, SEO and cache controls.",
   "type": "module",
   "license": "MIT",
@@ -82,6 +82,10 @@
     "./router": {
       "types": "./src/router/index.ts",
       "default": "./dist/router.js"
+    },
+    "./i18n": {
+      "types": "./src/i18n/index.ts",
+      "default": "./dist/i18n.js"
     }
   },
   "dependencies": {

package/src/core/bundler.ts

@@ -4,7 +4,7 @@ import fs from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
-import type { OutputOptions, RollupOptions } from 'rollup';
+import type { OutputOptions, Plugin, RollupOptions } from 'rollup';
 
 let rollupModulePromise: Promise<typeof import('rollup')> | null = null;
 
@@ -34,12 +34,40 @@ interface BundledFile {
   mimeType: string;
 }
 
+interface BundleResult {
+  hash: string;
+  filename: string;
+  content: string;
+}
+
+const EMPTY_RESULT: BundleResult = { hash: '', filename: '', content: '' };
+
 // Memory map để lưu bundled files
 const bundledFilesMap = new Map<string, BundledFile>();
 
-// Cache map để deduplicate bundling requests (cacheKey → entry chunk fileName)
-const bundleCache = new Map<string, string>();
-const cssCache = new Map<string, string>();
+/**
+ * Single-flight map: cacheKey → promise của lần bundle đang chạy (hoặc đã xong).
+ * Vì promise được giữ lại sau khi resolve, map này vừa là in-flight dedup vừa là
+ * result cache. Bundle lỗi bị xoá khỏi map để request sau được thử lại.
+ */
+const bundlePromises = new Map<string, Promise<BundleResult>>();
+
+/**
+ * Chạy `work` đúng một lần cho mỗi cacheKey, kể cả khi nhiều request đến đồng thời.
+ */
+function dedupe(cacheKey: string, work: () => Promise<BundleResult>): Promise<BundleResult> {
+  const pending = bundlePromises.get(cacheKey);
+  if (pending) {
+    return pending;
+  }
+
+  const promise = work().catch((error) => {
+    bundlePromises.delete(cacheKey);
+    throw error;
+  });
+  bundlePromises.set(cacheKey, promise);
+  return promise;
+}
 
 /**
  * Generate hash từ content
@@ -48,167 +76,184 @@ function generateHash(content: string): string {
   return createHash('sha256').update(content).digest('hex').substring(0, 16);
 }
 
+// Rollup coi id bắt đầu bằng \0 là virtual — nó sẽ không cố đọc từ đĩa.
+const VIRTUAL_ENTRY_ID = '\0l5e:bundle-entry';
+
 /**
- * Bundle JavaScript files từ dist/client thành 1 file
- * Trong production, các file đã được build sẵn trong dist/client
+ * Entry của mỗi lần bundle chỉ là một danh sách import. Giữ nó trong memory thay
+ * vì ghi ra đĩa: hai request đồng thời cùng một tập script sinh ra cùng nội dung
+ * entry, nên file tạm dùng chung path sẽ bị request này xoá trong lúc rollup của
+ * request kia còn đang đọc.
  */
-export async function bundleScripts(
-  scriptPaths: string[],
-  rootDir: string,
+function virtualEntryPlugin(entryContent: string): Plugin {
+  return {
+    name: 'l5e-virtual-entry',
+    resolveId(source) {
+      return source === VIRTUAL_ENTRY_ID ? VIRTUAL_ENTRY_ID : null;
+    },
+    load(id) {
+      return id === VIRTUAL_ENTRY_ID ? entryContent : null;
+    },
+  };
+}
+
+/**
+ * Rewrite vendor/chunk/global imports thành web path và để chúng external.
+ * Global files (*.global.*) đã được client.global.ts load — bundle lại sẽ tạo
+ * module instance trùng (vd nanostores).
+ */
+function vendorPathRewriterPlugin(distClientDir: string): Plugin {
+  const toWebPath = (absolutePath: string) =>
+    '/' + path.relative(distClientDir, absolutePath).replace(/\\/g, '/');
+
+  return {
+    name: 'vendor-path-rewriter',
+    resolveId(source, importer) {
+      if (
+        !source.includes('vendor-') &&
+        !source.includes('chunk-') &&
+        !source.includes('.global')
+      ) {
+        return null;
+      }
+
+      if (path.isAbsolute(source)) {
+        // e.g. C:\...\dist\client\assets\vendor-react-XXX.js -> /assets/vendor-react-XXX.js
+        return { id: toWebPath(source), external: true };
+      }
+
+      if (importer && source.startsWith('.')) {
+        // Relative path như ./auth.global-BOVr81Z5.js — resolve từ importer
+        return { id: toWebPath(path.resolve(path.dirname(importer), source)), external: true };
+      }
+
+      return null;
+    },
+  };
+}
+
+async function runScriptBundle(
+  uniquePaths: string[],
   distClientDir: string,
-): Promise<{ hash: string; filename: string; content: string }> {
-  if (scriptPaths.length === 0) {
-    return { hash: '', filename: '', content: '' };
+): Promise<BundleResult> {
+  const entryContent = uniquePaths
+    .map((p) => {
+      const filePath = p.startsWith('/')
+        ? path.join(distClientDir, p.substring(1))
+        : path.join(distClientDir, p);
+      return `import ${JSON.stringify(filePath)};`;
+    })
+    .join('\n');
+
+  const rollupOptions: RollupOptions = {
+    input: VIRTUAL_ENTRY_ID,
+    plugins: [virtualEntryPlugin(entryContent), vendorPathRewriterPlugin(distClientDir)],
+    external: (id) => {
+      // External node_modules
+      if (!id.startsWith('.') && !path.isAbsolute(id) && id !== VIRTUAL_ENTRY_ID) {
+        return true;
+      }
+
+      // Vendor/chunk/global do plugin resolveId lo phần rewrite path
+      return false;
+    },
+  };
+
+  const outputOptions: OutputOptions = {
+    format: 'es',
+    inlineDynamicImports: false,
+    entryFileNames: 'bundle-[hash].js',
+    chunkFileNames: 'bundle-[hash].js',
+  };
+
+  const { rollup } = await loadRollup();
+  const bundle = await rollup(rollupOptions);
+  let output;
+  try {
+    ({ output } = await bundle.generate(outputOptions));
+  } finally {
+    await bundle.close();
   }
 
-  // Dedupe paths (remove duplicates)
-  const uniquePaths = [...new Set(scriptPaths)];
-
-  // Tạo cache key từ sorted unique paths
-  const cacheKey = `scripts:${uniquePaths.sort().join(',')}`;
-
-  // Kiểm tra cache - return entry chunk info if already bundled
-  const cachedEntryFileName = bundleCache.get(cacheKey);
-  if (cachedEntryFileName) {
-    const entryFile = bundledFilesMap.get(cachedEntryFileName);
-    if (entryFile) {
-      return {
-        hash: entryFile.hash,
-        filename: entryFile.filename,
-        content: entryFile.content,
-      };
+  for (const chunk of output) {
+    if (chunk.type !== 'chunk') {
+      continue;
     }
+    bundledFilesMap.set(chunk.fileName, {
+      content: chunk.code || '',
+      hash: generateHash(chunk.code || ''),
+      filename: chunk.fileName,
+      mimeType: 'application/javascript',
+    });
   }
 
-  // Temp file path for cleanup
-  let entryFile: string | null = null;
-
-  try {
-    // Sử dụng rollup để bundle nếu cần (resolve imports, etc)
-    // Tạo temp entry file
-    const hash = generateHash(uniquePaths.join('\n'));
-    const tempDir = path.join(rootDir, '.temp-bundle');
-    await fs.mkdir(tempDir, { recursive: true }).catch(() => {});
-
-    entryFile = path.join(tempDir, `entry-${hash}.js`);
-    // Tạo entry file import tất cả scripts
-    const entryContent = uniquePaths
-      .map((p, i) => {
-        const filePath = p.startsWith('/')
-          ? path.join(distClientDir, p.substring(1))
-          : path.join(distClientDir, p);
-        return `import ${JSON.stringify(filePath)};`;
-      })
-      .join('\n');
-
-    await fs.writeFile(entryFile, entryContent, 'utf-8');
-    console.log(`[bundler] Wrote entry file to ${entryFile}`);
-    console.log(`[bundler] Entry content: ${entryContent}`);
-    // Rollup config để bundle
-    const rollupOptions: RollupOptions = {
-      input: entryFile,
-      plugins: [
-        {
-          name: 'vendor-path-rewriter',
-          resolveId(source, importer, _options) {
-            // Handle vendor/chunk/global files: convert absolute paths to web paths
-            // Global files (*.global.*) are already loaded by client.global.ts —
-            // re-bundling them would create duplicate module instances (e.g. nanostores)
-            if (
-              source.includes('vendor-') ||
-              source.includes('chunk-') ||
-              source.includes('.global')
-            ) {
-              console.log(`[bundler] Resolving source: ${source}`);
-              if (path.isAbsolute(source)) {
-                console.log(`[bundler] Resolving absolute path: ${source}`);
-                // e.g., C:\...\dist\client\assets\vendor-react-XXX.js -> /assets/vendor-react-XXX.js
-                const relativePath = path.relative(distClientDir, source);
-                const webPath = '/' + relativePath.replace(/\\/g, '/');
-                return { id: webPath, external: true };
-              } else if (importer && source.startsWith('.')) {
-                console.log(
-                  `[bundler] Resolving relative path: ${source} from importer: ${importer}`,
-                );
-                // Relative path like ./auth.global-BOVr81Z5.js — resolve from importer
-                const resolved = path.resolve(path.dirname(importer), source);
-                const relativePath = path.relative(distClientDir, resolved);
-                const webPath = '/' + relativePath.replace(/\\/g, '/');
-                return { id: webPath, external: true };
-              } else {
-                console.log(`[bundler] Resolving source: ${source}`);
-              }
-            }
-            return null; // Let other plugins/external handle
-          },
-        },
-      ],
-      external: (id) => {
-        // External node_modules
-        if (!id.startsWith('.') && !path.isAbsolute(id)) {
-          return true;
-        }
-
-        // Let plugin handle vendor/chunk/global files (don't mark external here)
-        if (id.includes('vendor-') || id.includes('chunk-') || id.includes('.global')) {
-          return false; // Let plugin's resolveId handle path rewriting
-        }
-
-        return false;
-      },
-    };
-
-    const outputOptions: OutputOptions = {
-      format: 'es',
-      inlineDynamicImports: false,
-      entryFileNames: 'bundle-[hash].js',
-      chunkFileNames: 'bundle-[hash].js',
-    };
-
-    const { rollup } = await loadRollup();
-    const bundle = await rollup(rollupOptions);
-    const { output } = await bundle.generate(outputOptions);
-    await bundle.close();
+  const entryChunk = output[0];
+  if (entryChunk?.type !== 'chunk') {
+    throw new Error('[bundler] rollup produced no entry chunk');
+  }
 
-    // Lấy bundled content từ rollup
+  return {
+    hash: generateHash(entryChunk.code || ''),
+    filename: entryChunk.fileName,
+    content: entryChunk.code || '',
+  };
+}
 
-    output.forEach((o) => {
-      if (o.type !== 'chunk') {
-        return;
-      }
-      // Lưu vào map với key = fileName
-      const bundledFile: BundledFile = {
-        content: o.code || '',
-        hash: generateHash(o.code || ''),
-        filename: o.fileName,
-        mimeType: 'application/javascript',
-      };
-      bundledFilesMap.set(o.fileName, bundledFile);
-    });
+/**
+ * Bundle JavaScript files từ dist/client thành 1 file
+ * Trong production, các file đã được build sẵn trong dist/client
+ */
+export async function bundleScripts(
+  scriptPaths: string[],
+  distClientDir: string,
+): Promise<BundleResult> {
+  if (scriptPaths.length === 0) {
+    return EMPTY_RESULT;
+  }
 
-    // Cache entry chunk fileName for deduplication
-    const entryChunk = output[0];
-    if (entryChunk?.type === 'chunk') {
-      bundleCache.set(cacheKey, entryChunk.fileName);
-    }
+  const uniquePaths = [...new Set(scriptPaths)].sort();
+  const cacheKey = `scripts:${uniquePaths.join(',')}`;
 
-    // Return entry chunk info
-    return {
-      hash: generateHash(output[0]?.code || ''),
-      filename: output[0]?.fileName || '',
-      content: output[0]?.code || '',
-    };
+  try {
+    return await dedupe(cacheKey, () => runScriptBundle(uniquePaths, distClientDir));
   } catch (error) {
     console.error('[bundler] Error bundling scripts:', error);
-    return { hash: '', filename: '', content: '' };
-  } finally {
-    // Cleanup temp entry file
-    if (entryFile) {
-      await fs.unlink(entryFile).catch(() => {
-        // Ignore cleanup errors
-      });
+    return EMPTY_RESULT;
+  }
+}
+
+async function runCssBundle(
+  uniquePaths: string[],
+  distClientDir: string,
+): Promise<BundleResult> {
+  const cssContents: string[] = [];
+
+  for (const cssPath of uniquePaths) {
+    // cssPath có thể là "/assets/xxx.css" hoặc từ manifest
+    const filePath = cssPath.startsWith('/')
+      ? path.join(distClientDir, cssPath.substring(1))
+      : path.join(distClientDir, cssPath);
+
+    try {
+      const content = await fs.readFile(filePath, 'utf-8');
+      cssContents.push(`/* ${cssPath} */\n${content}\n`);
+    } catch (err) {
+      console.warn(`[bundler] Failed to read CSS file: ${cssPath}`, err);
     }
   }
+
+  const bundledContent = cssContents.join('\n\n');
+  const hash = generateHash(bundledContent);
+  const filename = `bundle-${hash}.css`;
+
+  bundledFilesMap.set(filename, {
+    content: bundledContent,
+    hash,
+    filename,
+    mimeType: 'text/css',
+  });
+
+  return { hash, filename, content: bundledContent };
 }
 
 /**
@@ -217,70 +262,20 @@ export async function bundleScripts(
  */
 export async function bundleCss(
   cssPaths: string[],
-  rootDir: string,
   distClientDir: string,
-): Promise<{ hash: string; filename: string; content: string }> {
+): Promise<BundleResult> {
   if (cssPaths.length === 0) {
-    return { hash: '', filename: '', content: '' };
+    return EMPTY_RESULT;
   }
 
-  // Dedupe paths (remove duplicates)
-  const uniquePaths = [...new Set(cssPaths)];
-
-  // Tạo cache key từ sorted unique paths
-  const cacheKey = `css:${uniquePaths.sort().join(',')}`;
-
-  // Kiểm tra cache - return cached file if already bundled
-  const cachedFileName = cssCache.get(cacheKey);
-  if (cachedFileName) {
-    const cachedFile = bundledFilesMap.get(cachedFileName);
-    if (cachedFile) {
-      return {
-        hash: cachedFile.hash,
-        filename: cachedFile.filename,
-        content: cachedFile.content,
-      };
-    }
-  }
+  const uniquePaths = [...new Set(cssPaths)].sort();
+  const cacheKey = `css:${uniquePaths.join(',')}`;
 
   try {
-    // Đọc và gộp tất cả CSS files từ dist/client
-    const cssContents: string[] = [];
-
-    for (const cssPath of uniquePaths) {
-      // cssPath có thể là "/assets/xxx.css" hoặc từ manifest
-      const filePath = cssPath.startsWith('/')
-        ? path.join(distClientDir, cssPath.substring(1))
-        : path.join(distClientDir, cssPath);
-
-      try {
-        const content = await fs.readFile(filePath, 'utf-8');
-        cssContents.push(`/* ${cssPath} */\n${content}\n`);
-      } catch (err) {
-        console.warn(`[bundler] Failed to read CSS file: ${cssPath}`, err);
-      }
-    }
-
-    const bundledContent = cssContents.join('\n\n');
-    const hash = generateHash(bundledContent);
-    const filename = `bundle-${hash}.css`;
-
-    // Lưu vào map với key = filename
-    const bundledFile: BundledFile = {
-      content: bundledContent,
-      hash,
-      filename,
-      mimeType: 'text/css',
-    };
-    bundledFilesMap.set(filename, bundledFile);
-
-    // Cache filename for deduplication
-    cssCache.set(cacheKey, filename);
-
-    return { hash, filename, content: bundledContent };
+    return await dedupe(cacheKey, () => runCssBundle(uniquePaths, distClientDir));
   } catch (error) {
     console.error('[bundler] Error bundling CSS:', error);
-    return { hash: '', filename: '', content: '' };
+    return EMPTY_RESULT;
   }
 }
 
@@ -296,4 +291,5 @@ export function getBundledFile(filename: string): BundledFile | undefined {
  */
 export function clearBundledFiles(): void {
   bundledFilesMap.clear();
+  bundlePromises.clear();
 }

package/src/core/jsx-types.d.ts

@@ -460,6 +460,7 @@ declare global {
         media?: string;
         sizes?: string;
         crossorigin?: string;
+        hreflang?: string;
       };
       style: HTMLAttributes & { type?: string; media?: string };
       script: HTMLAttributes & {

package/src/core/server.ts

@@ -285,12 +285,12 @@ async function createPageResponse({
     }
 
     if (mappedScripts.length > 0) {
-      const bundledScript = await bundleScripts(mappedScripts, root, distClientDir);
+      const bundledScript = await bundleScripts(mappedScripts, distClientDir);
       scriptSrcList = bundledScript.filename ? [`/${bundledScript.filename}`] : mappedScripts;
     }
 
     if (mappedCssFiles.length > 0) {
-      const bundledCss = await bundleCss(mappedCssFiles, root, distClientDir);
+      const bundledCss = await bundleCss(mappedCssFiles, distClientDir);
       if (bundledCss.filename) {
         cssSrcList = [`/${bundledCss.filename}`];
       }
@@ -574,24 +574,22 @@ export async function createServer(options: ServerOptions = {}): Promise<ServerC
         return res.status(405).set('Allow', allowedMethod).send('Method Not Allowed');
       }
 
-      // Build RequestInfo (same pattern as HTML handler)
-      const fullUrl = `${req.protocol}://${req.get('host')}${req.originalUrl}`;
-      const urlObject = new URL(fullUrl);
-
-      const requestInfo = {
-        url: urlObject,
-        path: req.originalUrl,
-        pathname: urlObject.pathname,
-        method: req.method,
-        headers: req.headers,
-        cookies: parseCookies(req.headers.cookie as string),
-        query: req.query || {},
-        body: req.body,
-        ip: requestIp.getClientIp(req),
-      };
-
-      // Import render utilities from entry-server (bundled in SSR build)
+      // Run the request through the middleware chain first — same as the HTML
+      // handler — so `locals` (locale, country, preview flags, ...) is
+      // populated for actions too. Previously this endpoint built its own
+      // bare `requestInfo` and never invoked middleware at all, so `locals`
+      // (and thus `getLocale()`) was always empty inside an action handler.
+      //
+      // Crucially, the action must run *inside* the `next` callback passed to
+      // the middleware — not after `await`ing the middleware call — because a
+      // middleware like `fromFetchMiddleware(paraglideMiddleware)` calls
+      // `next()` synchronously inside a library-owned `AsyncLocalStorage.run()`
+      // scope. Running the action afterward, once that scope has already
+      // closed, would silently lose the library's own ambient `getLocale()`.
       const entryServerPath = path.join(root, './dist/server/entry-server.js');
+      const entryServerModule: EntryServerModule = isProduction
+        ? await import(pathToFileURL(entryServerPath).href)
+        : await vite!.ssrLoadModule('@withl5e/l5e/entry-server');
       const { runInRenderContext } = await (isProduction
         ? import(pathToFileURL(entryServerPath).href)
         : vite!.ssrLoadModule('@withl5e/l5e/jsx-runtime'));
@@ -599,17 +597,42 @@ export async function createServer(options: ServerOptions = {}): Promise<ServerC
         ? import(pathToFileURL(entryServerPath).href)
         : vite!.ssrLoadModule('@withl5e/l5e'));
 
-      // Run action handler in render context (needed for JSX)
-      const html = await runInRenderContext(
-        async () => {
-          const jsx = await action.handler(requestInfo);
-          return renderJsxToHtmlString(jsx);
-        },
-        requestInfo,
-        modulePath,
-      );
+      const locals: Record<string, unknown> = {};
+      const initialRequest = createWebRequestFromExpress(req);
+      const middlewareContext = createContext({
+        request: initialRequest,
+        locals,
+        clientAddress: requestIp.getClientIp(req) ?? undefined,
+      });
+
+      const loadedMiddleware = await entryServerModule.loadMiddleware?.();
+      const middlewareHandler: MiddlewareHandler =
+        typeof loadedMiddleware === 'function' ? loadedMiddleware : (_ctx, dummyNext) => dummyNext();
+
+      // If middleware short-circuits (returns its own Response — a redirect, a
+      // 403, ...) instead of calling `next`, this callback never runs and that
+      // response wins, same as it would for a page request.
+      const response = await middlewareHandler(middlewareContext, async (payload) => {
+        const nextRequest = createRewriteRequest(payload, middlewareContext.request, middlewareContext.url);
+        const requestInfo = {
+          ...createRequestInfo(req, nextRequest, base, locals),
+          path: req.originalUrl,
+          body: req.body,
+        };
+
+        const html = await runInRenderContext(
+          async () => {
+            const jsx = await action.handler(requestInfo);
+            return renderJsxToHtmlString(jsx);
+          },
+          requestInfo,
+          modulePath,
+        );
 
-      res.set('Content-Type', 'text/html').send(html);
+        return new Response(html, { headers: { 'Content-Type': 'text/html' } });
+      });
+
+      await sendWebResponse(req, res, response);
     } catch (e: any) {
       vite?.ssrFixStacktrace?.(e);
       console.error('[l5e] Action error:', e.stack || e);

package/src/i18n/index.ts

@@ -0,0 +1,2 @@
+export { fromFetchMiddleware } from './middleware';
+export type { FetchLocaleMiddleware } from './types';

package/src/i18n/middleware.ts

@@ -0,0 +1,50 @@
+import { defineMiddleware } from '../middleware/defineMiddleware';
+import type { MiddlewareHandler } from '../middleware/types';
+import type { FetchLocaleMiddleware } from './types';
+
+/**
+ * Adapt a fetch-based locale middleware — e.g. Paraglide's own
+ * `paraglideMiddleware` — into an l5e `MiddlewareHandler`.
+ *
+ * l5e doesn't ship its own locale-detection/URL-localization logic (strip
+ * prefix, cookie, redirect) or its own `getLocale()`: libraries like
+ * Paraglide already do both well, including an ambient `getLocale()` backed
+ * by their own `AsyncLocalStorage`. This adapter is only the bridge — it
+ * hands `context.request` to the library's middleware and, once resolved,
+ * (1) continues the chain by calling `next(request)` *synchronously inside*
+ * the library's own resolve callback, so the library's `AsyncLocalStorage`
+ * scope (already wrapping that callback) naturally extends over the rest of
+ * the request — loaders, route handler, every component — meaning the
+ * library's own `getLocale()` just works, no bridging needed; and (2) writes
+ * the resolved locale onto `context.locals.locale` too, since that's the
+ * idiomatic place other l5e code (global-loader's `lang`, cache tags, ...)
+ * already reads request-scoped values from — see the `locals` docs.
+ *
+ * @example
+ * ```ts
+ * // src/middleware.ts
+ * import { sequence } from '@withl5e/l5e/middleware';
+ * import { fromFetchMiddleware } from '@withl5e/l5e/i18n';
+ * import { paraglideMiddleware } from '~/paraglide/server.js';
+ *
+ * export const onRequest = sequence(fromFetchMiddleware(paraglideMiddleware));
+ *
+ * // Anywhere in the app — loaders, components, plain utils:
+ * import { getLocale } from '~/paraglide/runtime.js'; // Paraglide's own, ambient
+ * ```
+ */
+export function fromFetchMiddleware<TLocale extends string = string, TOptions = unknown>(
+  middleware: FetchLocaleMiddleware<TLocale, TOptions>,
+  options?: TOptions,
+): MiddlewareHandler {
+  return defineMiddleware((context, next) => {
+    return middleware(
+      context.request,
+      ({ request, locale }) => {
+        context.locals.locale = locale;
+        return next(request);
+      },
+      options,
+    );
+  });
+}

package/src/i18n/types.ts

@@ -0,0 +1,13 @@
+/**
+ * The shape shared by fetch-based locale middleware — Paraglide's own
+ * `paraglideMiddleware(request, resolve, options?)` matches this exactly, so
+ * `fromFetchMiddleware(paraglideMiddleware)` works with zero glue code. Any
+ * other library (or hand-written function) exposing the same shape works too.
+ */
+export interface FetchLocaleMiddleware<TLocale extends string = string, TOptions = unknown> {
+  (
+    request: Request,
+    resolve: (args: { request: Request; locale: TLocale }) => Response | Promise<Response>,
+    options?: TOptions,
+  ): Response | Promise<Response>;
+}