tera-system-ui 0.1.41 → 0.1.61

package/dist/paraglide/runtime.js

@@ -1,4 +1,4 @@
-// eslint-disable
+/* eslint-disable */
 
 /** @type {any} */
 const URLPattern = {}
@@ -245,6 +245,9 @@ export let serverAsyncLocalStorage = undefined;
 export const disableAsyncLocalStorage = false;
 export const experimentalMiddlewareLocaleSplitting = false;
 export const isServer = import.meta.env?.SSR ?? typeof window === 'undefined';
+/** @type {Locale | undefined} */
+// @ts-ignore - injected by bundlers at compile time
+export const experimentalStaticLocale = undefined;
 /**
  * Sets the server side async local storage.
  *
@@ -281,6 +284,12 @@ let localeInitiallySet = false;
 /**
  * Get the current locale.
  *
+ * The locale is resolved using your configured strategies (URL, cookie, localStorage, etc.)
+ * in the order they are defined. In SSR contexts, the locale is retrieved from AsyncLocalStorage
+ * which is set by the `paraglideMiddleware()`.
+ *
+ * @see https://inlang.com/m/gerre34r/library-inlang-paraglideJs/strategy - Configure locale detection strategies
+ *
  * @example
  *   if (getLocale() === 'de') {
  *     console.log('Germany 🇩🇪');
@@ -291,6 +300,9 @@ let localeInitiallySet = false;
  * @type {() => Locale}
  */
 export let getLocale = () => {
+    if (experimentalStaticLocale !== undefined) {
+        return assertIsLocale(experimentalStaticLocale);
+    }
     /** @type {string | undefined} */
     let locale;
     // if running in a server-side rendering context
@@ -331,7 +343,15 @@ export let getLocale = () => {
         }
         else if (isCustomStrategy(strat) && customClientStrategies.has(strat)) {
             const handler = customClientStrategies.get(strat);
-            locale = handler.getLocale();
+            if (handler) {
+                const result = handler.getLocale();
+                // Handle both sync and async results - skip async in sync getLocale
+                if (result instanceof Promise) {
+                    // Can't await in sync function, skip async strategies
+                    continue;
+                }
+                locale = result;
+            }
         }
         // check if match, else continue loop
         if (locale !== undefined) {
@@ -348,17 +368,17 @@ export let getLocale = () => {
     throw new Error("No locale found. Read the docs https://inlang.com/m/gerre34r/library-inlang-paraglideJs/errors#no-locale-found");
 };
 /**
- * Overwrite the \`getLocale()\` function.
+ * Overwrite the `getLocale()` function.
  *
- * Use this function to overwrite how the locale is resolved. For example,
- * you can resolve the locale from the browser's preferred language,
- * a cookie, env variable, or a user's preference.
+ * Use this function to overwrite how the locale is resolved. This is useful
+ * for custom locale resolution or advanced use cases like SSG with concurrent rendering.
+ *
+ * @see https://inlang.com/m/gerre34r/library-inlang-paraglideJs/strategy
  *
  * @example
  *   overwriteGetLocale(() => {
- *     // resolve the locale from a cookie. fallback to the base locale.
  *     return Cookies.get('locale') ?? baseLocale
- *   }
+ *   });
  *
  * @type {(fn: () => Locale) => void}
  */
@@ -366,13 +386,37 @@ export const overwriteGetLocale = (fn) => {
     getLocale = fn;
 };
 
+/**
+ * Navigates to the localized URL, or reloads the current page
+ *
+ * @param {string} [newLocation] The new location
+ * @return {undefined}
+ */
+const navigateOrReload = (newLocation) => {
+    if (newLocation) {
+        // reload the page by navigating to the new url
+        window.location.href = newLocation;
+    }
+    else {
+        // reload the page to reflect the new locale
+        window.location.reload();
+    }
+};
+/**
+ * @typedef {(newLocale: Locale, options?: { reload?: boolean }) => void | Promise<void>} SetLocaleFn
+ */
 /**
  * Set the locale.
  *
- * Set locale reloads the site by default on the client. Reloading
- * can be disabled by passing \`reload: false\` as an option. If
- * reloading is disabled, you need to ensure that the UI is updated
- * to reflect the new locale.
+ * Updates the locale using your configured strategies (cookie, localStorage, URL, etc.).
+ * By default, this reloads the page on the client to reflect the new locale. Reloading
+ * can be disabled by passing `reload: false` as an option, but you'll need to ensure
+ * the UI updates to reflect the new locale.
+ *
+ * If any custom strategy's `setLocale` function is async, then this function
+ * will become async as well.
+ *
+ * @see https://inlang.com/m/gerre34r/library-inlang-paraglideJs/strategy
  *
  * @example
  *   setLocale('en');
@@ -380,7 +424,7 @@ export const overwriteGetLocale = (fn) => {
  * @example
  *   setLocale('en', { reload: false });
  *
- * @type {(newLocale: Locale, options?: { reload?: boolean }) => void}
+ * @type {SetLocaleFn}
  */
 export let setLocale = (newLocale, options) => {
     const optionsWithDefaults = {
@@ -389,6 +433,7 @@ export let setLocale = (newLocale, options) => {
     };
     // locale is already set
     // https://github.com/opral/inlang-paraglide-js/issues/430
+    /** @type {Locale | undefined} */
     let currentLocale;
     try {
         currentLocale = getLocale();
@@ -396,6 +441,8 @@ export let setLocale = (newLocale, options) => {
     catch {
         // do nothing, no locale has been set yet.
     }
+    /** @type {Array<Promise<any>>} */
+    const customSetLocalePromises = [];
     /** @type {string | undefined} */
     let newLocation = undefined;
     for (const strat of strategy) {
@@ -411,9 +458,11 @@ export let setLocale = (newLocale, options) => {
                 typeof window === "undefined") {
                 continue;
             }
-            const domain = cookieDomain || window.location.hostname;
             // set the cookie
-            document.cookie = `${cookieName}=${newLocale}; path=/; max-age=${cookieMaxAge}; domain=${domain}`;
+            const cookieString = `${cookieName}=${newLocale}; path=/; max-age=${cookieMaxAge}`;
+            document.cookie = cookieDomain
+                ? `${cookieString}; domain=${cookieDomain}`
+                : cookieString;
         }
         else if (strat === "baseLocale") {
             // nothing to be set here. baseLocale is only a fallback
@@ -442,22 +491,34 @@ export let setLocale = (newLocale, options) => {
         }
         else if (isCustomStrategy(strat) && customClientStrategies.has(strat)) {
             const handler = customClientStrategies.get(strat);
-            handler.setLocale(newLocale);
+            if (handler) {
+                let result = handler.setLocale(newLocale);
+                // Handle async setLocale
+                if (result instanceof Promise) {
+                    result = result.catch((error) => {
+                        throw new Error(`Custom strategy "${strat}" setLocale failed.`, {
+                            cause: error,
+                        });
+                    });
+                    customSetLocalePromises.push(result);
+                }
+            }
         }
     }
-    if (!isServer &&
-        optionsWithDefaults.reload &&
-        window.location &&
-        newLocale !== currentLocale) {
-        if (newLocation) {
-            // reload the page by navigating to the new url
-            window.location.href = newLocation;
-        }
-        else {
-            // reload the page to reflect the new locale
-            window.location.reload();
+    const runReload = () => {
+        if (!isServer &&
+            optionsWithDefaults.reload &&
+            window.location &&
+            newLocale !== currentLocale) {
+            navigateOrReload(newLocation);
         }
+    };
+    if (customSetLocalePromises.length) {
+        return Promise.all(customSetLocalePromises).then(() => {
+            runReload();
+        });
     }
+    runReload();
     return;
 };
 /**
@@ -472,10 +533,10 @@ export let setLocale = (newLocale, options) => {
  *     return Cookies.set('locale', newLocale)
  *   });
  *
- * @param {(newLocale: Locale) => void} fn
+ * @param {SetLocaleFn} fn
  */
 export const overwriteSetLocale = (fn) => {
-    setLocale = fn;
+    setLocale = /** @type {SetLocaleFn} */ (fn);
 };
 
 /**
@@ -522,7 +583,11 @@ export let overwriteGetUrlOrigin = (fn) => {
  * @returns {locale is Locale}
  */
 export function isLocale(locale) {
-    return !locale ? false : locales.includes(locale);
+    if (typeof locale !== "string")
+        return false;
+    return !locale
+        ? false
+        : locales.some((item) => item.toLowerCase() === locale.toLowerCase());
 }
 
 /**
@@ -533,10 +598,15 @@ export function isLocale(locale) {
  * @throws {Error} If the input is not a locale.
  */
 export function assertIsLocale(input) {
-    if (isLocale(input) === false) {
+    if (typeof input !== "string") {
+        throw new Error(`Invalid locale: ${input}. Expected a string.`);
+    }
+    const lowerInput = input.toLowerCase();
+    const matchedLocale = locales.find((item) => item.toLowerCase() === lowerInput);
+    if (!matchedLocale) {
         throw new Error(`Invalid locale: ${input}. Expected one of: ${locales.join(", ")}`);
     }
-    return input;
+    return matchedLocale;
 }
 
 /**
@@ -549,6 +619,9 @@ export function assertIsLocale(input) {
  * they are defined. If a strategy returns an invalid locale,
  * it will fall back to the next strategy.
  *
+ * Note: Custom server strategies are not supported in this synchronous version.
+ * Use `extractLocaleFromRequestAsync` if you need custom server strategies with async getLocale methods.
+ *
  * @example
  *   const locale = extractLocaleFromRequest(request);
  *
@@ -581,9 +654,10 @@ export const extractLocaleFromRequest = (request) => {
         else if (strat === "localStorage") {
             continue;
         }
-        else if (isCustomStrategy(strat) && customServerStrategies.has(strat)) {
-            const handler = customServerStrategies.get(strat);
-            locale = handler.getLocale(request);
+        else if (isCustomStrategy(strat)) {
+            // Custom strategies are not supported in sync version
+            // Use extractLocaleFromRequestAsync for custom server strategies
+            continue;
         }
         if (locale !== undefined) {
             if (!isLocale(locale)) {
@@ -597,6 +671,57 @@ export const extractLocaleFromRequest = (request) => {
     throw new Error("No locale found. There is an error in your strategy. Try adding 'baseLocale' as the very last strategy. Read more here https://inlang.com/m/gerre34r/library-inlang-paraglideJs/errors#no-locale-found");
 };
 
+/**
+ * Asynchronously extracts a locale from a request.
+ *
+ * This function supports async custom server strategies, unlike the synchronous
+ * `extractLocaleFromRequest`. Use this function when you have custom server strategies
+ * that need to perform asynchronous operations (like database calls) in their getLocale method.
+ *
+ * The function first processes any custom server strategies asynchronously, then falls back
+ * to the synchronous `extractLocaleFromRequest` for all other strategies.
+ *
+ * @see {@link https://github.com/opral/inlang-paraglide-js/issues/527#issuecomment-2978151022}
+ *
+ * @example
+ *   // Basic usage
+ *   const locale = await extractLocaleFromRequestAsync(request);
+ *
+ * @example
+ *   // With custom async server strategy
+ *   defineCustomServerStrategy("custom-database", {
+ *     getLocale: async (request) => {
+ *       const userId = extractUserIdFromRequest(request);
+ *       return await getUserLocaleFromDatabase(userId);
+ *     }
+ *   });
+ *
+ *   const locale = await extractLocaleFromRequestAsync(request);
+ *
+ * @type {(request: Request) => Promise<Locale>}
+ */
+export const extractLocaleFromRequestAsync = async (request) => {
+    /** @type {string|undefined} */
+    let locale;
+    // Process custom strategies first, in order
+    for (const strat of strategy) {
+        if (isCustomStrategy(strat) && customServerStrategies.has(strat)) {
+            const handler = customServerStrategies.get(strat);
+            if (handler) {
+                /** @type {string|undefined} */
+                locale = await handler.getLocale(request);
+            }
+            // If we got a valid locale from this custom strategy, use it
+            if (locale !== undefined && isLocale(locale)) {
+                return assertIsLocale(locale);
+            }
+        }
+    }
+    // If no custom strategy provided a valid locale, fall back to sync version
+    locale = extractLocaleFromRequest(request);
+    return assertIsLocale(locale);
+};
+
 /**
  * Extracts a cookie from the document.
  *
@@ -768,6 +893,8 @@ function defaultUrlPatternExtractLocale(url) {
  * For client-side UI components, use `localizeHref()` instead, which provides
  * a more convenient API with relative paths and automatic locale detection.
  *
+ * @see https://inlang.com/m/gerre34r/library-inlang-paraglideJs/i18n-routing
+ *
  * @example
  * ```typescript
  * // Server middleware example
@@ -874,6 +1001,8 @@ function localizeUrlDefaultPattern(url, options) {
  * For client-side UI components, use `deLocalizeHref()` instead, which provides
  * a more convenient API with relative paths.
  *
+ * @see https://inlang.com/m/gerre34r/library-inlang-paraglideJs/i18n-routing
+ *
  * @example
  * ```typescript
  * // Server middleware example
@@ -1065,6 +1194,122 @@ export function aggregateGroups(match) {
     };
 }
 
+/**
+ * @typedef {object} ShouldRedirectServerInput
+ * @property {Request} request
+ * @property {string | URL} [url]
+ * @property {ReturnType<typeof assertIsLocale>} [locale]
+ *
+ * @typedef {object} ShouldRedirectClientInput
+ * @property {undefined} [request]
+ * @property {string | URL} [url]
+ * @property {ReturnType<typeof assertIsLocale>} [locale]
+ *
+ * @typedef {ShouldRedirectServerInput | ShouldRedirectClientInput} ShouldRedirectInput
+ *
+ * @typedef {object} ShouldRedirectResult
+ * @property {boolean} shouldRedirect - Indicates whether the consumer should perform a redirect.
+ * @property {ReturnType<typeof assertIsLocale>} locale - Locale resolved using the configured strategies.
+ * @property {URL | undefined} redirectUrl - Destination URL when a redirect is required.
+ */
+/**
+ * Determines whether a redirect is required to align the current URL with the active locale.
+ *
+ * This helper mirrors the logic that powers `paraglideMiddleware`, but works in both server
+ * and client environments. It evaluates the configured strategies in order, computes the
+ * canonical localized URL, and reports when the current URL does not match.
+ *
+ * When called in the browser without arguments, the current `window.location.href` is used.
+ *
+ * @see https://inlang.com/m/gerre34r/library-inlang-paraglideJs/i18n-routing#client-side-redirects
+ *
+ * @example
+ * // Client side usage (e.g. TanStack Router beforeLoad hook)
+ * async function beforeLoad({ location }) {
+ *   const decision = await shouldRedirect({ url: location.href });
+ *
+ *   if (decision.shouldRedirect) {
+ *     throw redirect({ to: decision.redirectUrl.href });
+ *   }
+ * }
+ *
+ * @example
+ * // Server side usage with a Request
+ * export async function handle(request) {
+ *   const decision = await shouldRedirect({ request });
+ *
+ *   if (decision.shouldRedirect) {
+ *     return Response.redirect(decision.redirectUrl, 307);
+ *   }
+ *
+ *   return render(request, decision.locale);
+ * }
+ *
+ * @param {ShouldRedirectInput} [input]
+ * @returns {Promise<ShouldRedirectResult>}
+ */
+export async function shouldRedirect(input = {}) {
+    const locale = /** @type {ReturnType<typeof assertIsLocale>} */ (await resolveLocale(input));
+    if (!strategy.includes("url")) {
+        return { shouldRedirect: false, locale, redirectUrl: undefined };
+    }
+    const currentUrl = resolveUrl(input);
+    const localizedUrl = localizeUrl(currentUrl.href, { locale });
+    const shouldRedirectToLocalizedUrl = normalizeUrl(localizedUrl.href) !== normalizeUrl(currentUrl.href);
+    return {
+        shouldRedirect: shouldRedirectToLocalizedUrl,
+        locale,
+        redirectUrl: shouldRedirectToLocalizedUrl ? localizedUrl : undefined,
+    };
+}
+/**
+ * Resolves the locale either from the provided input or by using the configured strategies.
+ *
+ * @param {ShouldRedirectInput} input
+ * @returns {Promise<ReturnType<typeof assertIsLocale>>}
+ */
+async function resolveLocale(input) {
+    if (input.locale) {
+        return assertIsLocale(input.locale);
+    }
+    if (input.request) {
+        return extractLocaleFromRequestAsync(input.request);
+    }
+    return getLocale();
+}
+/**
+ * Resolves the current URL from the provided input or runtime context.
+ *
+ * @param {ShouldRedirectInput} input
+ * @returns {URL}
+ */
+function resolveUrl(input) {
+    if (input.request) {
+        return new URL(input.request.url);
+    }
+    if (input.url instanceof URL) {
+        return new URL(input.url.href);
+    }
+    if (typeof input.url === "string") {
+        return new URL(input.url, getUrlOrigin());
+    }
+    if (typeof window !== "undefined" && window?.location?.href) {
+        return new URL(window.location.href);
+    }
+    throw new Error("shouldRedirect() requires either a request, an absolute URL, or must run in a browser environment.");
+}
+/**
+ * Normalize url for comparison by stripping the trailing slash.
+ *
+ * @param {string} url
+ * @returns {string}
+ */
+function normalizeUrl(url) {
+    const urlObj = new URL(url);
+    urlObj.pathname = urlObj.pathname.replace(/\/$/, "");
+    return urlObj.href;
+}
+
 /**
  * High-level URL localization function optimized for client-side UI usage.
  *
@@ -1076,6 +1321,8 @@ export function aggregateGroups(match) {
  * - Automatically detects current locale if not specified
  * - Handles string input/output instead of URL objects
  *
+ * @see https://inlang.com/m/gerre34r/library-inlang-paraglideJs/i18n-routing
+ *
  * @example
  * ```typescript
  * // In a React/Vue/Svelte component
@@ -1134,6 +1381,8 @@ export function localizeHref(href, options) {
  * - Returns relative paths when possible
  * - Handles string input/output instead of URL objects
  *
+ * @see https://inlang.com/m/gerre34r/library-inlang-paraglideJs/i18n-routing
+ *
  * @example
  * ```typescript
  * // In a React/Vue/Svelte component
@@ -1161,7 +1410,6 @@ export function localizeHref(href, options) {
  *
  * @param {string} href - The href to de-localize (can be relative or absolute)
  * @returns {string} The de-localized href, relative if input was relative
- * @see deLocalizeUrl - For low-level URL de-localization in server contexts
  */
 export function deLocalizeHref(href) {
     const url = new URL(href, getUrlOrigin());
@@ -1188,26 +1436,47 @@ export function trackMessageCall(safeModuleId, locale) {
 }
 
 /**
- * Generates a list of localized URLs for all provided URLs.
+ * Generates localized URL variants for all provided URLs based on your configured locales and URL patterns.
  *
- * This is useful for SSG (Static Site Generation) and sitemap generation.
- * NextJS and other frameworks use this function for SSG.
+ * This function is essential for Static Site Generation (SSG) where you need to tell your framework
+ * which pages to pre-render at build time. It's also useful for generating sitemaps and
+ * `<link rel="alternate" hreflang>` tags for SEO.
+ *
+ * The function respects your `urlPatterns` configuration - if you have translated pathnames
+ * (e.g., `/about` → `/ueber-uns` for German), it will generate the correct localized paths.
+ *
+ * @see https://inlang.com/m/gerre34r/library-inlang-paraglideJs/static-site-generation
  *
  * @example
- * ```typescript
- * const urls = generateStaticLocalizedUrls([
- *   "https://example.com/about",
- *   "https://example.com/blog",
+ * // Basic usage - generate all locale variants for a list of paths
+ * const localizedUrls = generateStaticLocalizedUrls([
+ *   "/",
+ *   "/about",
+ *   "/blog/post-1",
  * ]);
- * urls[0].href // => "https://example.com/about"
- * urls[1].href // => "https://example.com/blog"
- * urls[2].href // => "https://example.com/de/about"
- * urls[3].href // => "https://example.com/de/blog"
- * ...
- * ```
+ * // Returns URL objects for each locale:
+ * // ["/en/", "/de/", "/en/about", "/de/about", "/en/blog/post-1", "/de/blog/post-1"]
  *
- * @param {(string | URL)[]} urls - List of URLs to generate localized versions for. Can be absolute URLs or paths.
- * @returns {URL[]} List of localized URLs as URL objects
+ * @example
+ * // Use with framework SSG APIs
+ * // SvelteKit
+ * export function entries() {
+ *   const paths = ["/", "/about", "/contact"];
+ *   return generateStaticLocalizedUrls(paths).map(url => ({
+ *     locale: extractLocaleFromUrl(url)
+ *   }));
+ * }
+ *
+ * @example
+ * // Sitemap generation
+ * const allPages = ["/", "/about", "/blog"];
+ * const sitemapUrls = generateStaticLocalizedUrls(allPages);
+ *
+ * @param {(string | URL)[]} urls - List of canonical URLs or paths to generate localized versions for.
+ *   Can be absolute URLs (`https://example.com/about`) or paths (`/about`).
+ *   Paths are resolved against `http://localhost` internally.
+ * @returns {URL[]} Array of URL objects representing all localized variants.
+ *   The order follows each input URL with all its locale variants before moving to the next URL.
  */
 export function generateStaticLocalizedUrls(urls) {
     const localizedUrls = new Set();
@@ -1290,52 +1559,54 @@ export function generateStaticLocalizedUrls(urls) {
  * @typedef {Array<Strategy>} Strategies
  */
 /**
- * @typedef {{ getLocale: (request?: Request) => string | undefined }} CustomServerStrategyHandler
+ * @typedef {{ getLocale: (request?: Request) => Promise<string | undefined> | (string | undefined) }} CustomServerStrategyHandler
  */
 /**
- * @typedef {{ getLocale: () => string | undefined, setLocale: (locale: string) => void }} CustomClientStrategyHandler
+ * @typedef {{ getLocale: () => Promise<string|undefined> | (string | undefined), setLocale: (locale: string) => Promise<void> | void }} CustomClientStrategyHandler
  */
+/** @type {Map<string, CustomServerStrategyHandler>} */
 export const customServerStrategies = new Map();
+/** @type {Map<string, CustomClientStrategyHandler>} */
 export const customClientStrategies = new Map();
 /**
  * Checks if the given strategy is a custom strategy.
  *
  * @param {any} strategy The name of the custom strategy to validate.
- * Must be a string that starts with "custom-" followed by alphanumeric characters.
+ * Must be a string that starts with "custom-" followed by alphanumeric characters, hyphens, or underscores.
  * @returns {boolean} Returns true if it is a custom strategy, false otherwise.
  */
 export function isCustomStrategy(strategy) {
-    return typeof strategy === "string" && /^custom-[A-Za-z0-9]+$/.test(strategy);
+    return (typeof strategy === "string" && /^custom-[A-Za-z0-9_-]+$/.test(strategy));
 }
 /**
  * Defines a custom strategy that is executed on the server.
  *
- * @param {any} strategy The name of the custom strategy to define. Must follow the pattern `custom-<name>` where
- * `<name>` contains only alphanumeric characters.
+ * @see https://inlang.com/m/gerre34r/library-inlang-paraglideJs/strategy#write-your-own-strategy
+ *
+ * @param {any} strategy The name of the custom strategy to define. Must follow the pattern custom-name with alphanumeric characters, hyphens, or underscores.
  * @param {CustomServerStrategyHandler} handler The handler for the custom strategy, which should implement
- * the method `getLocale`.
+ * the method getLocale.
  * @returns {void}
  */
 export function defineCustomServerStrategy(strategy, handler) {
     if (!isCustomStrategy(strategy)) {
-        throw new Error(`Invalid custom strategy: "${strategy}". Must be a custom strategy following the pattern custom-<name>` +
-            " where <name> contains only alphanumeric characters.");
+        throw new Error(`Invalid custom strategy: "${strategy}". Must be a custom strategy following the pattern custom-name.`);
     }
     customServerStrategies.set(strategy, handler);
 }
 /**
  * Defines a custom strategy that is executed on the client.
  *
- * @param {any} strategy The name of the custom strategy to define. Must follow the pattern `custom-<name>` where
- * `<name>` contains only alphanumeric characters.
+ * @see https://inlang.com/m/gerre34r/library-inlang-paraglideJs/strategy#write-your-own-strategy
+ *
+ * @param {any} strategy The name of the custom strategy to define. Must follow the pattern custom-name with alphanumeric characters, hyphens, or underscores.
  * @param {CustomClientStrategyHandler} handler The handler for the custom strategy, which should implement the
- * methods `getLocale` and `setLocale`.
+ * methods getLocale and setLocale.
  * @returns {void}
  */
 export function defineCustomClientStrategy(strategy, handler) {
     if (!isCustomStrategy(strategy)) {
-        throw new Error(`Invalid custom strategy: "${strategy}". Must be a custom strategy following the pattern custom-<name>` +
-            " where <name> contains only alphanumeric characters.");
+        throw new Error(`Invalid custom strategy: "${strategy}". Must be a custom strategy following the pattern custom-name.`);
     }
     customClientStrategies.set(strategy, handler);
 }
@@ -1351,3 +1622,45 @@ export function defineCustomClientStrategy(strategy, handler) {
  * @typedef {(typeof locales)[number]} Locale
  */
 
+/**
+ * A branded type representing a localized string.
+ *
+ * Message functions return this type instead of `string`, enabling TypeScript
+ * to distinguish translated strings from regular strings at compile time.
+ * This allows you to enforce that only properly localized content is used
+ * in your UI components.
+ *
+ * Since `LocalizedString` is a branded subtype of `string`, it remains fully
+ * backward compatible—you can pass it anywhere a `string` is expected.
+ *
+ * @example
+ *   // Enforce localized strings in your components
+ *   function PageTitle(props: { title: LocalizedString }) {
+ *     return <h1>{props.title}</h1>
+ *   }
+ *
+ *   // ✅ Correct: using a message function
+ *   <PageTitle title={m.welcome_title()} />
+ *
+ *   // ❌ Type error: raw strings are not LocalizedString
+ *   <PageTitle title="Welcome" />
+ *
+ * @example
+ *   // LocalizedString is assignable to string (backward compatible)
+ *   const localized: LocalizedString = m.greeting()
+ *   const str: string = localized  // ✅ works fine
+ *
+ *   // But string is not assignable to LocalizedString
+ *   const raw: LocalizedString = "Hello"  // ❌ Type error
+ *
+ * @example
+ *   // Catches accidental string concatenation
+ *   function showMessage(msg: LocalizedString) { ... }
+ *
+ *   showMessage(m.hello())                    // ✅
+ *   showMessage("Hello " + userName)          // ❌ Type error
+ *   showMessage(m.hello_user({ name: userName }))  // ✅ use params instead
+ *
+ * @typedef {string & { readonly __brand: 'LocalizedString' }} LocalizedString
+ */
+