@agent-native/core 0.75.4 → 0.76.0

package/corpus/core/src/deploy/build.ts

@@ -1510,61 +1510,57 @@ export function isDurableBackgroundDeployEnabled(): boolean {
  * 15-min async function instead of the synchronous `/*` catch-all.
  * Additive + flag-gated (see `isDurableBackgroundDeployEnabled`).
  *
- * GROUNDED IN THE REAL NETLIFY BUILD OUTPUT (verified from a local Nitro build):
+ * GROUNDED IN THE REAL NETLIFY BUILD OUTPUT (verified from a local Nitro build)
+ * AND THE NETLIFY DOCS DEFAULT-URL RULE:
  *   - Nitro's `netlify` preset emits exactly ONE function source at
  *     `.netlify/functions-internal/server/`. `server.mjs` re-exports `main.mjs`
  *     and declares `export const config = { path: "/*", excludedPath:
- *     ["/.netlify/*"], preferStatic: true, ... }`. Nitro writes NO `netlify.toml`
- *     and NO `[[redirects]]`; the `/*` catch-all is an IN-CODE Functions-API-v2
- *     `config.path`.
+ *     ["/.netlify/*"], preferStatic: true, ... }`. The `/*` catch-all is an
+ *     IN-CODE Functions-API-v2 `config.path` and it ALREADY EXCLUDES
+ *     `/.netlify/*`.
  *   - The generated `.netlify/netlify.toml` sets
  *     `functionsDirectory = ".netlify/functions-internal"`. Netlify scans EXACTLY
  *     that dir; functions placed anywhere else (e.g. `.netlify/functions/`, which
  *     is the BUILD OUTPUT dir where `@netlify/build` later writes the zipped
  *     functions + `manifest.json`) are NEVER deployed.
- *   - On Netlify CI, `@netlify/build` reads each scanned function's
- *     `export const config`, zips it, and materializes
- *     `.netlify/functions/manifest.json` with `routes` derived from each
- *     `config.path`. So per-file `export const config` (including `background` and
- *     `path`) IS honored — the `server` manifest entry's `routes: [{ pattern:
- *     "/*" }]` came straight from `server.mjs`'s `config.path`.
+ *   - Every scanned function is reachable at its DEFAULT url
+ *     `/.netlify/functions/<name>` BY DEFAULT. A custom `config.path` REMOVES
+ *     that default url; declaring NO custom `config.path` KEEPS it.
  *
  * THEREFORE we:
  *   1. Emit the background function INTO the scanned dir
  *      (`.netlify/functions-internal/server-agent-background/`), sharing the same
  *      built `main.mjs` bundle, so Netlify discovers it and honors its config.
- *   2. Give its `export const config` BOTH `background: true` (→ async invoke,
- *      immediate 202, 15-min budget) AND `path: AGENT_CHAT_PROCESS_RUN_PATH` (so
- *      it claims that exact path at function-matching time, which Netlify
- *      evaluates BEFORE redirects — step 10 vs 11 in the request chain).
- *   3. PATCH the Nitro `server` function's own `server.mjs` so its catch-all
- *      `config.path: "/*"` EXCLUDES `AGENT_CHAT_PROCESS_RUN_PATH` (append it to
- *      `excludedPath`). Netlify does NOT define a winner when two serverless
- *      functions both match a path; rather than rely on that undocumented order,
- *      we make the match UNAMBIGUOUS — only the background function matches
- *      `_process-run`, and `server` matches everything else exactly as before.
+ *   2. Give its `export const config` `background: true` (→ async invoke,
+ *      immediate 202, 15-min budget) and NO custom `config.path`. With no custom
+ *      path the function keeps its DEFAULT url
+ *      `/.netlify/functions/server-agent-background`, and because the Nitro
+ *      `server` function's `/*` catch-all already excludes `/.netlify/*`, that
+ *      default-url namespace is NEVER shadowed by the synchronous function — no
+ *      catch-all patch is needed.
+ *   3. The entry NORMALIZES/rewrites the incoming request pathname to
+ *      `AGENT_CHAT_PROCESS_RUN_PATH` before delegating to `./main.mjs`. The
+ *      function is reached at its default url
+ *      (`/.netlify/functions/server-agent-background`), so the Nitro router needs
+ *      the path rewritten to the framework `_process-run` route, preserving the
+ *      method, ALL headers (the HMAC `Authorization: Bearer` MUST survive), and
+ *      the body.
  *   4. Set `globalThis.__AGENT_NATIVE_BACKGROUND_RUNTIME__ = true` at cold start
  *      (read back by `isInBackgroundFunctionRuntime()` so the worker takes the
  *      ~13-min soft-timeout). A `globalThis` flag — NOT `process.env` — keeps the
  *      no-env-mutation guard satisfied and carries no cross-request state.
  *
- * With a real `config.path` the function is reachable at that path directly, so
- * the foreground POSTs to `AGENT_CHAT_PROCESS_RUN_PATH`
- * (`resolveAgentChatProcessRunDispatchPath`) and the request entry no longer
- * needs to rewrite the path — it already arrives at the framework route. We keep
- * a defensive normalize-to-PROCESS_RUN_PATH in the entry anyway (cheap, and it
- * makes the function correct even if reached via its default function url).
+ * The foreground dispatches to this DEFAULT url on hosted Netlify
+ * (`resolveAgentChatProcessRunDispatchPath` → `AGENT_BACKGROUND_FUNCTION_URL_PATH`).
  *
- * WHY THIS BEATS ALL THREE PRIOR FAILURES:
- *   - Attempts 1 & 2 emitted into `functions-internal` (correct dir) with a
- *     `config.path` but did NOT exclude that path from the `server` `/*`
- *     catch-all. Two functions matched `_process-run`; the order is undocumented
- *     and the catch-all `server` (priority 0, synchronous) won → SYNC 401, not a
- *     202. We now exclude the path from `server`, so only the async function
- *     matches.
- *   - Attempt 3 emitted a standalone function into `.netlify/functions/` — the
- *     OUTPUT dir, which Netlify does not scan — so it never entered the manifest
- *     → 404. We now emit into the SCANNED `functions-internal` dir.
+ * WHY THIS IS THE DOC-CORRECT FIX: a prior attempt gave the function a custom
+ * `config.path` (= the framework route) plus a catch-all `excludedPath` patch.
+ * The custom `config.path` was NOT honored as a route in prod — a probe of
+ * `POST /_agent-native/agent-chat/_process-run` returned 404. The doc-correct
+ * approach (confirmed against the Netlify docs) is to use the DEFAULT function
+ * url with no custom path: the function stays reachable at
+ * `/.netlify/functions/<name>` and is never shadowed because `/.netlify/*` is
+ * already excluded from the `server` catch-all.
  *
  * Safety net regardless of Netlify routing nuance: if the dispatch fast-fails
  * (e.g. the function was not emitted), the foreground handler degrades to an
@@ -1596,11 +1592,6 @@ export function emitSingleTemplateNetlifyBackgroundFunction(
   // copied bundle does NOT re-register the catch-all `config.path`.
   fs.rmSync(path.join(dest, "server.mjs"), { force: true });
 
-  // Make the `server` `/*` catch-all NOT match the process-run path, so only the
-  // async background function matches it (function-vs-function path order is
-  // undocumented on Netlify — don't rely on it).
-  excludeProcessRunPathFromServerCatchAll(serverDir);
-
   const processRunPath = JSON.stringify(AGENT_CHAT_PROCESS_RUN_PATH);
   const entry = `// Mark this isolate as the durable background runtime BEFORE the handler
 // bundle is imported, so isInBackgroundFunctionRuntime() reliably returns true
@@ -1618,11 +1609,10 @@ let cachedHandler;
 
 // Netlify v2 invokes this as (request, context). The Nitro netlify handler is a
 // Web-standard \`async (Request) => Response\` (see nitro/presets/netlify/runtime).
-// Because this function declares \`config.path = PROCESS_RUN_PATH\`, Netlify routes
-// that exact path here and the request already arrives as PROCESS_RUN_PATH — no
-// rewrite is needed. We still NORMALIZE the pathname to PROCESS_RUN_PATH so the
-// function stays correct even if it is ever reached via its default function url
-// (/.netlify/functions/${backgroundName}). Method, ALL headers (the HMAC
+// This function declares NO custom \`config.path\`, so it is reached at its
+// DEFAULT url (/.netlify/functions/${backgroundName}). The Nitro router only
+// knows the framework route, so we REWRITE the incoming pathname to
+// PROCESS_RUN_PATH before delegating. Method, ALL headers (the HMAC
 // Authorization: Bearer MUST survive — the plugin verifies it) and the body are
 // preserved by cloning the incoming Request with only its URL pathname set.
 export default async function handler(request) {
@@ -1646,13 +1636,12 @@ export const config = {
   generator: "agent-native build",
   // background: true makes Netlify invoke this ASYNCHRONOUSLY (immediate HTTP
   // 202 ack) with the 15-minute budget (Netlify docs:
-  // build/functions/background-functions + build/functions/api). path claims the
-  // process-run route directly; Netlify evaluates serverless functions BEFORE
-  // redirects (request-chain step 10 vs 11), and we exclude this path from the
-  // \`server\` /* catch-all so only THIS function matches it — no ambiguous
-  // function-vs-function order.
+  // build/functions/background-functions + build/functions/api). We declare NO
+  // custom path, so the function keeps its DEFAULT url
+  // /.netlify/functions/${backgroundName}; the Nitro \`server\` /* catch-all
+  // already excludes /.netlify/* so that default url is never shadowed by the
+  // synchronous function. The foreground dispatches to that default url.
   background: true,
-  path: PROCESS_RUN_PATH,
   nodeBundler: "none",
   includedFiles: ["**"],
   preferStatic: false,
@@ -1661,67 +1650,12 @@ export const config = {
   fs.writeFileSync(path.join(dest, `${backgroundName}.mjs`), entry);
   console.log(
     `[build] Emitted durable-background function "${backgroundName}" into the ` +
-      `scanned dir .netlify/functions-internal with config { background:true, ` +
-      `path:"${AGENT_CHAT_PROCESS_RUN_PATH}" } and excluded that path from the ` +
-      `server /* catch-all. REQUIRES real-deploy verification of Netlify async ` +
-      `(202) invocation — see docs/design/durable-agent-runs.md.`,
-  );
-}
-
-/**
- * Append `AGENT_CHAT_PROCESS_RUN_PATH` to the Nitro `server` function's
- * `config.excludedPath` so its `/*` catch-all does NOT match the process-run
- * path. That guarantees the async background function (which declares
- * `config.path = AGENT_CHAT_PROCESS_RUN_PATH`) is the ONLY function that matches
- * that path — Netlify does not define a winner when two serverless functions
- * both match, so we make the match unambiguous instead of relying on order.
- *
- * The Nitro-generated `server/server.mjs` is small and deterministic:
- *   export { default } from "./main.mjs";
- *   export const config = { ... excludedPath: ["/.netlify/*"], ... };
- * We parse the `excludedPath: [...]` array literal and add our path if absent.
- * If the shape ever changes and we can't find/parse it, we log and leave the
- * file untouched (the inline-40s fallback still keeps chat working).
- */
-function excludeProcessRunPathFromServerCatchAll(serverDir: string): void {
-  const serverEntry = path.join(serverDir, "server.mjs");
-  if (!fs.existsSync(serverEntry)) {
-    console.warn(
-      "[build] Durable-background: server/server.mjs not found; cannot exclude " +
-        `${AGENT_CHAT_PROCESS_RUN_PATH} from the /* catch-all.`,
-    );
-    return;
-  }
-  const original = fs.readFileSync(serverEntry, "utf8");
-  if (original.includes(AGENT_CHAT_PROCESS_RUN_PATH)) {
-    // Already excluded (idempotent — emit may run on a re-used output tree).
-    return;
-  }
-  const excludedPathRe = /excludedPath:\s*\[([^\]]*)\]/;
-  const match = original.match(excludedPathRe);
-  const quotedPath = JSON.stringify(AGENT_CHAT_PROCESS_RUN_PATH);
-  if (match) {
-    const existing = match[1].trim();
-    const next = existing
-      ? `excludedPath: [${existing.replace(/,\s*$/, "")}, ${quotedPath}]`
-      : `excludedPath: [${quotedPath}]`;
-    fs.writeFileSync(serverEntry, original.replace(excludedPathRe, next));
-    return;
-  }
-  // No existing `excludedPath` — inject one into the config object. Match the
-  // `path: "/*"` line and add `excludedPath` right after it.
-  const pathLineRe = /(path:\s*("\/\*"|'\/\*'),?)/;
-  if (pathLineRe.test(original)) {
-    fs.writeFileSync(
-      serverEntry,
-      original.replace(pathLineRe, `$1\n  excludedPath: [${quotedPath}],`),
-    );
-    return;
-  }
-  console.warn(
-    "[build] Durable-background: could not locate excludedPath/path in " +
-      "server/server.mjs; leaving the /* catch-all unchanged (the background " +
-      "function may be shadowed — the inline-40s fallback still applies).",
+      `scanned dir .netlify/functions-internal with config { background:true } ` +
+      `and NO custom path — reachable at its default url ` +
+      `/.netlify/functions/${backgroundName} (never shadowed; the server /* ` +
+      `catch-all already excludes /.netlify/*). REQUIRES real-deploy ` +
+      `verification of Netlify async (202) invocation — see ` +
+      `docs/design/durable-agent-runs.md.`,
   );
 }
 

package/corpus/core/src/deploy/workspace-deploy.ts

@@ -696,24 +696,30 @@ function isDurableBackgroundDeployEnabled(): boolean {
 /**
  * Emit a SECOND Netlify function for `app` whose name ends in `-background`,
  * re-exporting the SAME `main.mjs` handler bundle. Netlify invokes any function
- * whose deployed name ends in `-background` asynchronously (202 immediately, up
- * to 15-min budget), which is exactly what the durable-background chat
- * dispatch (`fireInternalDispatch` → AGENT_CHAT_PROCESS_RUN_PATH) needs.
+ * with `config.background: true` asynchronously (202 immediately, up to 15-min
+ * budget), which is exactly what the durable-background chat dispatch
+ * (`fireInternalDispatch` → the function's default url) needs.
  *
- * The function is given a `config.path` of the chat process-run route so
- * Netlify routes that POST to this async function instead of the synchronous
- * `<app>-server` function. It shares the same bundle (`includedFiles: ["**"]`)
- * so `A2A_SECRET`, the DB URL, and the rest of the env/bundle are present.
+ * DOC-CORRECT DEFAULT-URL APPROACH (mirrors the single-template emit in
+ * deploy/build.ts): the function declares NO custom `config.path`, so it keeps
+ * its DEFAULT url `/.netlify/functions/<app>-agent-background`. The `<app>-server`
+ * function's catch-all already excludes `/.netlify/*`, so that default-url
+ * namespace is NEVER shadowed by the synchronous function — no overlapping
+ * `config.path` and no catch-all patch are needed. The foreground dispatches to
+ * that default url (`resolveAgentChatProcessRunDispatchPath` resolves the per-app
+ * name from `AGENT_NATIVE_WORKSPACE_APP_ID`); `fireInternalDispatch` strips the
+ * app base path for `/.netlify/*` targets so the request reaches the host-root
+ * function url. The entry then REWRITES the incoming pathname to the
+ * base-path-prefixed `_process-run` route before delegating to the Nitro router.
  *
- * ⚠️ REAL-DEPLOY VERIFICATION REQUIRED. The exact Netlify routing/precedence
- * between this `-background` function's `config.path` and the synchronous
- * `<app>-server` function's broader `config.path` (which also matches
- * `/_agent-native/*` for the dispatch app, or `/<app>/*` otherwise) cannot be
- * verified in this environment. It is emitted additively and only under the
- * flag; if Netlify resolves the overlap to the wrong function, the dispatch
- * would land on the synchronous function (no 15-min budget) — the run would
- * still work via the existing 40s soft-timeout path, just without the durable
- * win. See packages/core/docs/design/durable-agent-runs.md.
+ * It shares the same bundle (`includedFiles: ["**"]`) so `A2A_SECRET`, the DB
+ * URL, and the rest of the env/bundle are present. A prior attempt gave the
+ * function a custom `config.path` (the framework route) that overlapped the
+ * synchronous `<app>-server` catch-all; that path was not honored as a route in
+ * prod (probe → 404). The default url is the doc-correct fix.
+ *
+ * Safety net: if the dispatch fast-fails the foreground degrades to an inline
+ * 40s synchronous run (see production-agent.ts).
  */
 function emitNetlifyBackgroundFunction(
   workspaceRoot: string,
@@ -721,7 +727,9 @@ function emitNetlifyBackgroundFunction(
   srcServerDir: string,
   workspaceApps: WorkspaceAppManifestEntry[],
 ): void {
-  // Name MUST end in `-background` for Netlify async invocation.
+  // Name MUST end in `-background` (Netlify async convention + the runtime guard
+  // reads the -background Lambda-name suffix as a fallback). It is reached at its
+  // DEFAULT url /.netlify/functions/<app>-agent-background.
   const backgroundName = `${app}-agent-background`;
   const dest = path.join(netlifyFunctionsDir(workspaceRoot), backgroundName);
   fs.rmSync(dest, { recursive: true, force: true });
@@ -733,14 +741,20 @@ function emitNetlifyBackgroundFunction(
     workspaceApps,
     app,
   );
-  // Only the chat process-run route needs the async function. Keeping the path
-  // narrow avoids stealing any other traffic from the synchronous function.
-  // The dispatch URL is app-base-path-prefixed (same as the agent-teams
-  // processor dispatch), so the route Netlify must map to this async function
-  // is `/<app>/_agent-native/agent-chat/_process-run`.
+  // The Nitro router for this app expects the base-path-prefixed framework route.
+  // The function is reached at its default url, so the entry rewrites the
+  // incoming pathname to `/<app>/_agent-native/agent-chat/_process-run`.
   const processRunPath = `${basePath}${AGENT_CHAT_PROCESS_RUN_PATH}`;
-  const pathConfig = [processRunPath];
-  const server = `const basePath = ${JSON.stringify(basePath)};
+  const server = `// Mark this isolate as the durable background runtime BEFORE the handler bundle
+// is imported, so isInBackgroundFunctionRuntime() reliably returns true in this
+// function (the deployed Lambda name is not guaranteed to end in -background). A
+// globalThis flag (NOT process.env) avoids the no-env-mutation guard and carries
+// no cross-request state.
+globalThis.__AGENT_NATIVE_BACKGROUND_RUNTIME__ = true;
+
+const basePath = ${JSON.stringify(basePath)};
+// The base-path-prefixed framework route the Nitro router dispatches to.
+const PROCESS_RUN_PATH = ${JSON.stringify(processRunPath)};
 
 function setBasePathEnv() {
   const processRef = globalThis.process ??= { env: {} };
@@ -767,16 +781,33 @@ setBasePathEnv();
 
 let cachedHandler;
 
-export default async function handler(...args) {
+// Reached at the DEFAULT url /.netlify/functions/${backgroundName}; REWRITE the
+// incoming pathname to the base-path-prefixed _process-run route so the Nitro
+// router runs the plugin. Method, ALL headers (the HMAC Authorization: Bearer
+// MUST survive) and the body are preserved.
+export default async function handler(request) {
   setBasePathEnv();
   cachedHandler ??= (await import("./main.mjs")).default;
-  return cachedHandler(...args);
+  const url = new URL(request.url);
+  url.pathname = PROCESS_RUN_PATH;
+  const method = request.method || "POST";
+  const hasBody = method !== "GET" && method !== "HEAD";
+  const body = hasBody ? await request.text() : undefined;
+  const rewritten = new Request(url.toString(), {
+    method,
+    headers: request.headers,
+    body,
+  });
+  return cachedHandler(rewritten);
 }
 
 export const config = {
   name: ${JSON.stringify(`${app} agent background handler`)},
   generator: "agent-native workspace deploy",
-  path: ${JSON.stringify(pathConfig)},
+  // background: true → async invoke (202, 15-min budget). NO custom path: the
+  // function keeps its default url /.netlify/functions/${backgroundName}, which
+  // the <app>-server catch-all never shadows (it excludes /.netlify/*).
+  background: true,
   nodeBundler: "none",
   includedFiles: ["**"],
   preferStatic: false,
@@ -788,9 +819,10 @@ export const config = {
   fs.writeFileSync(path.join(dest, `${backgroundName}.mjs`), server);
   console.log(
     `[workspace-deploy] Emitted durable-background function "${backgroundName}" ` +
-      `for app "${app}" (path ${processRunPath}). ` +
-      `REQUIRES real-deploy verification of Netlify async routing — see ` +
-      `docs/design/durable-agent-runs.md.`,
+      `for app "${app}" with config { background:true } and NO custom path — ` +
+      `reachable at its default url /.netlify/functions/${backgroundName} ` +
+      `(rewrites to ${processRunPath}). REQUIRES real-deploy verification of ` +
+      `Netlify async (202) invocation — see docs/design/durable-agent-runs.md.`,
   );
 }
 

package/corpus/core/src/index.browser.ts

@@ -25,6 +25,23 @@ export {
   updateMcpAppModelContext,
   useMcpAppHostContext,
   CodeRequiredDialog,
+  AgentNativeI18nProvider,
+  LanguagePicker,
+  getLocaleInitScript,
+  localeDirection,
+  normalizeLocaleCode,
+  normalizeLocalePreference,
+  normalizeLocalizationPreference,
+  resolveLocaleFromCandidates,
+  resolveLocaleFromPreference,
+  useFormatters,
+  useLocale,
+  useT,
+  DEFAULT_LOCALE,
+  LOCALE_HYDRATION_GLOBAL,
+  LOCALE_METADATA,
+  LOCALE_STORAGE_KEY,
+  SUPPORTED_LOCALES,
   useDbSync,
   useFileWatcher,
   useSession,
@@ -48,6 +65,14 @@ export {
   type CodeRequiredDialogProps,
   type AuthSession,
   type UseAgentChatContextResult,
+  type AgentNativeI18nCatalog,
+  type AgentNativeI18nProviderProps,
+  type LocaleCode,
+  type LocaleHydrationPayload,
+  type LocaleMessages,
+  type LocaleMetadata,
+  type LocalePreference,
+  type LocalizationPreference,
 } from "./client/index.js";
 
 // Shared (isomorphic)

package/corpus/core/src/localization/actions/get-localization-preference.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import { defineAction } from "../../action.js";
+import { getUserSetting } from "../../settings/user-settings.js";
+import {
+  LOCALIZATION_SETTING_KEY,
+  normalizeLocalizationPreference,
+  type LocalizationPreference,
+} from "../shared.js";
+
+export default defineAction({
+  description:
+    "Get the current user's interface language preference. Returns { locale }, where locale is 'system' or a supported BCP-47 locale.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  run: async (_args, ctx): Promise<LocalizationPreference> => {
+    if (!ctx?.userEmail) throw new Error("Not authenticated.");
+    const stored = await getUserSetting(
+      ctx.userEmail,
+      LOCALIZATION_SETTING_KEY,
+    );
+    return normalizeLocalizationPreference(stored);
+  },
+});

package/corpus/core/src/localization/actions/set-localization-preference.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import { defineAction } from "../../action.js";
+import { putUserSetting } from "../../settings/user-settings.js";
+import {
+  LOCALIZATION_SETTING_KEY,
+  normalizeLocalePreference,
+  type LocalizationPreference,
+} from "../shared.js";
+
+export default defineAction({
+  description:
+    "Set the current user's interface language preference to 'system' or a supported BCP-47 locale.",
+  schema: z.object({
+    locale: z
+      .string()
+      .describe("Language preference: 'system' or a supported BCP-47 locale."),
+  }),
+  run: async (args, ctx): Promise<LocalizationPreference> => {
+    if (!ctx?.userEmail) throw new Error("Not authenticated.");
+    const locale = normalizeLocalePreference(args.locale);
+    if (!locale) {
+      throw new Error(
+        "Unsupported locale. Use system, en-US, zh-CN, es-ES, fr-FR, de-DE, ja-JP, ko-KR, pt-BR, hi-IN, or ar-SA.",
+      );
+    }
+    const value: LocalizationPreference & Record<string, unknown> = { locale };
+    await putUserSetting(ctx.userEmail, LOCALIZATION_SETTING_KEY, value);
+    return value;
+  },
+});

package/corpus/core/src/localization/index.ts

@@ -0,0 +1,2 @@
+export * from "./shared.js";
+export * from "./server.js";

package/corpus/core/src/localization/server.ts

@@ -0,0 +1,131 @@
+import {
+  DEFAULT_LOCALE,
+  LOCALE_HYDRATION_GLOBAL,
+  LOCALE_STORAGE_KEY,
+  SUPPORTED_LOCALES,
+  localeDirection,
+  normalizeLocaleCode,
+  normalizeLocalizationPreference,
+  resolveLocaleFromPreference,
+  type LocaleCode,
+  type LocalePreference,
+  type LocalizationPreference,
+} from "./shared.js";
+
+interface RequestLike {
+  headers?: Headers | Record<string, string | string[] | undefined> | null;
+}
+
+type HeaderMap = Headers | Record<string, string | string[] | undefined>;
+
+export interface ResolvedRequestLocale {
+  locale: LocaleCode;
+  preference: LocalizationPreference;
+  dir: "ltr" | "rtl";
+}
+
+export interface ResolveLocaleFromRequestOptions {
+  request?: Request | RequestLike | null;
+  acceptLanguage?: string | null;
+  preference?: LocalizationPreference | LocalePreference | null;
+  fallback?: LocaleCode;
+}
+
+export interface LocaleInitScriptOptions {
+  locale?: LocaleCode;
+  preference?: LocalizationPreference | LocalePreference;
+  messages?: Record<string, unknown> | null;
+}
+
+function readHeader(
+  headers: HeaderMap | undefined | null,
+  key: string,
+): string | null {
+  if (!headers) return null;
+  if (typeof (headers as Headers).get === "function") {
+    return (headers as Headers).get(key);
+  }
+  const lowerKey = key.toLowerCase();
+  for (const [name, value] of Object.entries(headers)) {
+    if (name.toLowerCase() !== lowerKey) continue;
+    if (Array.isArray(value)) return value.join(",");
+    return value ?? null;
+  }
+  return null;
+}
+
+export function parseAcceptLanguage(header: string | null | undefined) {
+  if (!header) return [];
+  return header
+    .split(",")
+    .map((part) => {
+      const [tag, ...params] = part.trim().split(";");
+      const q = params
+        .map((param) => param.trim())
+        .find((param) => param.startsWith("q="));
+      const weight = q ? Number.parseFloat(q.slice(2)) : 1;
+      return {
+        tag,
+        weight: Number.isFinite(weight) ? weight : 0,
+      };
+    })
+    .filter((entry) => entry.tag && entry.weight > 0)
+    .sort((a, b) => b.weight - a.weight)
+    .map((entry) => entry.tag);
+}
+
+export function resolveLocaleFromRequest(
+  options: ResolveLocaleFromRequestOptions = {},
+): ResolvedRequestLocale {
+  const header =
+    options.acceptLanguage ??
+    readHeader(options.request?.headers, "accept-language");
+  const candidates = parseAcceptLanguage(header);
+  const preference = normalizeLocalizationPreference(
+    options.preference ?? { locale: "system" },
+  );
+  const locale =
+    preference.locale === "system"
+      ? resolveLocaleFromPreference(preference, [
+          ...candidates,
+          options.fallback ?? DEFAULT_LOCALE,
+        ])
+      : (normalizeLocaleCode(preference.locale) ??
+        options.fallback ??
+        DEFAULT_LOCALE);
+  return {
+    locale,
+    preference,
+    dir: localeDirection(locale),
+  };
+}
+
+export function getLocaleInitScript(options: LocaleInitScriptOptions = {}) {
+  const safeLocale = normalizeLocaleCode(options.locale) ?? DEFAULT_LOCALE;
+  const shouldStorePreference = options.preference !== undefined;
+  const safePreference = normalizeLocalizationPreference(
+    options.preference ?? { locale: "system" },
+  );
+  const payload = {
+    locale: safeLocale,
+    preference: safePreference,
+    dir: localeDirection(safeLocale),
+    messages: options.messages ?? undefined,
+  };
+
+  return `(function(){try{var supported=${JSON.stringify(
+    SUPPORTED_LOCALES,
+  )};var payload=${JSON.stringify(
+    payload,
+  )};var shouldStorePreference=${JSON.stringify(
+    shouldStorePreference,
+  )};function valid(x){return supported.indexOf(x)>=0}function canon(x){if(typeof x!=='string'||!x)return null;try{var c=Intl.getCanonicalLocales(x)[0];if(valid(c))return c;var lang=c&&c.split('-')[0].toLowerCase();for(var i=0;i<supported.length;i++){if(supported[i].split('-')[0].toLowerCase()===lang)return supported[i]}}catch(e){}return null}function storageGet(k){try{return window.localStorage.getItem(k)}catch(e){return null}}function storageSet(k,v){try{window.localStorage.setItem(k,v)}catch(e){}}var stored=storageGet(${JSON.stringify(
+    LOCALE_STORAGE_KEY,
+  )});var pref=payload.preference&&payload.preference.locale;var locale=payload.locale;if(!valid(locale)){locale=null}if(!locale&&stored&&stored!=='system'){locale=canon(stored)}if(!locale&&pref&&pref!=='system'){locale=canon(pref)}if(!locale){var langs=navigator.languages&&navigator.languages.length?navigator.languages:[navigator.language];for(var j=0;j<langs.length&&!locale;j++){locale=canon(langs[j])}}if(!locale)locale=${JSON.stringify(
+    DEFAULT_LOCALE,
+  )};var root=document.documentElement;root.setAttribute('lang',locale);root.setAttribute('dir',locale==='ar-SA'?'rtl':'ltr');root.setAttribute('data-locale',locale);payload.locale=locale;payload.dir=locale==='ar-SA'?'rtl':'ltr';window[${JSON.stringify(
+    LOCALE_HYDRATION_GLOBAL,
+  )}]=payload;if(shouldStorePreference&&pref){storageSet(${JSON.stringify(
+    LOCALE_STORAGE_KEY,
+  )},pref)}}catch(e){}})();`;
+}