@levo-so/site-runtime 0.3.8 → 0.3.9

package/index.d.ts

@@ -5,6 +5,15 @@ import { ILevoMembership } from '@levo-so/core';
 import { JSX } from 'react/jsx-runtime';
 import { LevoQuery } from '@levo-so/core';
 
+/**
+ * Build the canonical + hreflang link set for one page.
+ *
+ * The canonical is ALWAYS self-referential — a page canonicals to its own URL, never to a
+ * different variant. That single rule is what stops the variants fragmenting into
+ * duplicate content, which is the problem the whole design exists to avoid.
+ */
+export declare const buildHreflangLinks: (options: IBuildHreflangOptions) => IHreflangLink[];
+
 /** Color-mode preference. `system` follows the OS `prefers-color-scheme`. */
 export declare type ColorMode = "dark" | "light" | "system";
 
@@ -69,6 +78,23 @@ export declare const createLevoLoader: (site: ISiteJson) => (sources: ILevoDataS
     params?: Record<string, string>;
 }) => Promise<Record<string, unknown>>;
 
+/**
+ * Build a route-existence matcher from a generated `routeTree`.
+ *
+ * LAZY on purpose — the walk runs on the first lookup, not here — and the reason is import
+ * order, not router construction. `__root.tsx` is imported BY `routeTree.gen.ts`, so anything
+ * it evaluates at module scope runs while the tree is still half-built: walk it there and the
+ * list comes back short or empty. Deferring to the first lookup (inside a request middleware
+ * or a `beforeLoad`, both of which run long after every module has evaluated) sidesteps that
+ * entirely.
+ *
+ * Two bugs of this exact shape have already shipped, and both presented identically: the server
+ * render was correct, the client fell back to the default language, and the visitor watched the
+ * page flip a second after load. Before making this eager, confirm where the starter calls it
+ * from — at module scope in `__root.tsx`, eager is wrong.
+ */
+export declare const createRouteTreeMatcher: (routeTree: unknown) => ((pathname: string) => boolean);
+
 /**
  * Build the site's core Levo client from config, or `null` when the site isn't wired to a
  * backend yet (no `apiUrl`). SSR-safe — `createLevoClient` guards its window/document reads.
@@ -93,6 +119,15 @@ export declare const createSiteClient: (config?: ILevoSiteConfig) => ILevoClient
  */
 export declare const decideAccess: ({ rules, invalid, pageId, hasClient, isReady, isLoggedIn, check, }: IAccessDecisionInput) => IAccessDecision;
 
+/**
+ * Main entry: extract visitor country + language preferences.
+ * Accepts any header carrier — normalization is internal.
+ */
+export declare const extractGeoAndLanguageData: (headers: Record<string, string | string[]> | Headers | null | undefined) => {
+    bestCountry: ICountryInfo | null;
+    languageData: IParsedLanguageData;
+};
+
 /**
  * The gate's policy, as a pure function.
  *
@@ -138,6 +173,26 @@ export declare interface IAccessDecisionInput {
     };
 }
 
+/**
+ * Everything needed to annotate ONE page. Describes that page across all languages, so the path
+ * is the language-neutral one and the locale list is the site's, not the page's.
+ */
+export declare interface IBuildHreflangOptions {
+    /** Neutral path, no locale prefix — `/pricing`. */
+    neutralPath: string;
+    /** Site origin, e.g. `https://acme.com`. hreflang requires absolute URLs. */
+    origin: string;
+    locales: string[];
+    /**
+     * The locale prefix currently in the URL, or null on a neutral URL. Decides which URL is
+     * canonical: a prefixed visitor self-canonicals to their prefixed URL, a neutral visitor
+     * self-canonicals to the neutral one.
+     */
+    activePrefix?: string | null;
+    /** Route-existence check — a locale with no route file for this page gets no alternate. */
+    hasRoute?: (pathname: string) => boolean;
+}
+
 export declare interface IColorModeProviderProps {
     children: React.ReactNode;
     /** Fallback when nothing is stored yet. */
@@ -165,6 +220,33 @@ export declare interface IComposedHead {
     scripts: IHeadEntry[];
 }
 
+/**
+ * GeoIP header extractor.
+ *
+ * Pulls visitor country + language from HTTP headers across CDN providers
+ * (Cloudflare, Vercel, AWS CloudFront, Azure, BunnyCDN), nginx-ingress, and
+ * Traefik GeoIP2. Only surfaces `bestCountry` + `languageData` — the helpers
+ * that were historically exported (client IPs, provider-specific getters,
+ * raw header maps) are no longer used by any consumer.
+ *
+ * DELIBERATE DUPLICATE of `external/next-middleware/src/geoIp.ts`. The two must not be
+ * merged: next-middleware is a Next.js package serving V2 slate apps, and having a V2 app
+ * depend on the V3 site runtime (or vice versa) would couple two release trains that ship
+ * independently. The file has no framework imports, so copying is cheap — but a header
+ * added to ONE copy is a silent gap in the other. Change both.
+ *
+ * On v3 the live providers are nginx-ingress (`x-country-code`) and, on paper, Traefik
+ * (`x-geoip2-country`); our ingress sets both. See docs/studio-v3/site-localization.md.
+ */
+export declare interface ICountryInfo {
+    countryCode: string;
+    city?: string;
+    region?: string;
+    latitude?: string;
+    longitude?: string;
+    source: string;
+}
+
 /** Editor → preview (received by `onMessage`; dashboard's `IOutboundMessage`). */
 export declare type IEditorToPreview = {
     type: "set-inspect";
@@ -251,6 +333,48 @@ declare interface IHeadEntry {
 
 export declare type IHistoryFn = History["pushState"];
 
+/**
+ * hreflang + canonical link generation for a localized site.
+ *
+ * These are the `<head>` annotations that tell Google which URL serves which language.
+ * They need NO database: the site knows its locale list (`site.json`) and which variants
+ * exist (the route tree), so correct annotations ship from day one — ahead of the sibling-row
+ * DB sync that the SITEMAP hreflang depends on.
+ *
+ * Known gap until that sync lands: these tags declare the relationships, but nothing points
+ * a crawler AT the prefixed URLs, so variants won't be indexed yet. See
+ * docs/studio-v3/site-localization.md.
+ */
+/** One `<link>` to render into `<head>` — either this page's canonical or one language alternate. */
+export declare interface IHreflangLink {
+    rel: "alternate" | "canonical";
+    href: string;
+    hrefLang?: string;
+}
+
+export declare interface ILanguageInfo {
+    locale: string;
+    language: string;
+    region?: string;
+    quality: number;
+}
+
+/** One selectable language, with the props a switcher needs to render it correctly. */
+export declare interface ILanguageOption {
+    /** The locale tag, e.g. `fr-FR`. Label it however you like. */
+    locale: string;
+    isActive: boolean;
+    /**
+     * Spread onto an `<a>`. Contains the canonical `href`, the click interception, and
+     * `aria-current` — see `useLanguageOptions` for why each matters.
+     */
+    linkProps: {
+        href: string;
+        "aria-current": "true" | undefined;
+        onClick: (event: React.MouseEvent<HTMLAnchorElement>) => void;
+    };
+}
+
 export declare interface ILayersNode {
     tag: string;
     source?: string;
@@ -785,6 +909,142 @@ export declare interface ILevoSourceResult<T = Record<string, unknown>> {
     };
 }
 
+export declare interface ILocaleConfig {
+    /** Every locale the site publishes. Empty or single-entry on a non-localized site. */
+    locales: string[];
+    /** The locale served at unprefixed URLs. */
+    defaultLocale: string;
+    /**
+     * Whether this site does localization at all. Every site is single-locale until a workspace
+     * adds a second one, and the whole mechanism is inert while this is false.
+     */
+    isLocalized: boolean;
+    /**
+     * Absolute origin for hreflang, or null when the site has no domain stamped yet. hreflang
+     * requires absolute URLs, so an unstamped `site.json` means no tags rather than broken ones.
+     */
+    origin: string | null;
+}
+
+export declare type ILocaleDecision = ILocaleRender | ILocaleRedirect;
+
+/** Mount once in `<head>`; the current page comes from router state, not from props. */
+export declare interface ILocaleHreflangProps {
+    config: ILocaleConfig;
+    /**
+     * The generated route tree. Supplying it drops alternates for variants that have no route
+     * file, so an advertised URL never 404s. Omit and every locale is advertised.
+     */
+    routeTree?: unknown;
+}
+
+/**
+ * What the provider needs to expose a language to page code. Everything except `locale` is
+ * site-wide config; prefer `<SiteLocaleProvider>`, which derives all of it from `ILocaleConfig`.
+ */
+export declare interface ILocaleProviderProps {
+    children: React.ReactNode;
+    /** The locale being rendered, from the server's resolution. */
+    locale: string;
+    /** Every locale the site publishes. */
+    locales?: string[];
+    /** Locale served at unprefixed URLs. */
+    defaultLocale?: string;
+    /** How `locale` was chosen — `"prefix"` means the visitor is on a canonical URL. */
+    source?: LocaleSource;
+    /**
+     * Does a route file exist at this path? Supplying it stops the switcher offering a language
+     * this page was never translated into — see `useLanguageOptions`.
+     */
+    hasRoute?: (pathname: string) => boolean;
+}
+
+/** Send the visitor to their language's URL. */
+export declare interface ILocaleRedirect {
+    kind: "redirect";
+    locale: string;
+    source: LocaleSource;
+    /** Path only — `localeRedirectResponse` appends the request's own `search`/`hash`. */
+    path: string;
+    status: 302;
+    /**
+     * Every header the redirect must carry: `location`, the load-bearing `cache-control`, and
+     * `set-cookie` when the choice is worth remembering. Send them as-is; nothing is missing.
+     */
+    headers: Record<string, string>;
+}
+
+/** Serve the URL the visitor asked for. */
+export declare interface ILocaleRender {
+    kind: "render";
+    locale: string;
+    source: LocaleSource;
+}
+
+export declare interface ILocaleRequestOptions {
+    /** The pathname the visitor asked for, e.g. `/pricing` or `/fr-FR/pricing`. */
+    pathname: string;
+    /** Every locale the site publishes, from `site.json`. */
+    locales: string[];
+    /** The locale served at unprefixed URLs. */
+    defaultLocale: string;
+    /**
+     * Request headers. Server path only — an in-app navigation never reaches the server, so the
+     * client path has none and negotiates from the cookie alone.
+     */
+    headers?: Record<string, string | string[]> | Headers | null;
+    /**
+     * A raw cookie string. Omit on the server, where it is read out of `headers`; pass
+     * `document.cookie` on the client, which has no headers to read it from.
+     */
+    cookie?: string | null;
+    /**
+     * Does a route file exist at this path? Without it a visitor can be sent to a translation
+     * nobody wrote. Build it with `createRouteTreeMatcher(routeTree)`.
+     */
+    hasRoute?: (pathname: string) => boolean;
+}
+
+/**
+ * What `useLocale()` returns: the language being rendered, the site's full list, and the one
+ * mutation page code may perform. Read-only apart from `setLocale` — the URL, not this object,
+ * is what decides the language.
+ */
+export declare interface ILocaleState {
+    locale: string;
+    locales: string[];
+    defaultLocale: string;
+    source: LocaleSource;
+    /** True once the site publishes more than one locale — gate switcher UI on this. */
+    isMultiLocale: boolean;
+    /**
+     * Switch language: remember the choice and go to that language's URL for this page.
+     *
+     * It NAVIGATES rather than swapping content in place, because with the redirect model a
+     * language IS a URL — `/hi-IN/pricing` is the Hindi page and the only place it exists. That
+     * also means the result is shareable and cacheable, which staying on a neutral URL could
+     * not give you.
+     */
+    setLocale: (locale: string) => void;
+    /**
+     * Route-existence check for this site, when the provider was given one. Consumed by
+     * `useLanguageOptions`; page code should not need it.
+     */
+    hasRoute?: (pathname: string) => boolean;
+    /**
+     * Prefix a path with a locale. For the LANGUAGE SWITCHER only — the one place a visitor is
+     * explicitly choosing a variant.
+     *
+     * Do NOT use it in shared chrome (navbar, footer, logo). Those render on every variant, and
+     * building their links from the current page's language traps a visitor in the wrong one:
+     * someone who landed on `/en` because no Hindi home exists then gets `/en/...` links
+     * everywhere, and never finds their way back to `/hi/about` even though it exists. Shared
+     * components link to the NEUTRAL path and let the doorway route them — it knows the cookie
+     * and which translations exist, and a component knows neither.
+     */
+    pathFor: (path: string, locale: string) => string;
+}
+
 export declare function Inspector(): null;
 
 /** One page's head metadata. Every field optional — site defaults fill gaps per-field. */
@@ -848,6 +1108,12 @@ export declare interface IParsedAccess {
     invalid: boolean;
 }
 
+export declare interface IParsedLanguageData {
+    languages: ILanguageInfo[];
+    primaryLanguage: string;
+    inferredRegions: string[];
+}
+
 export declare interface IPatchedHistoryFn {
     (this: History, ...args: Parameters<IHistoryFn>): ReturnType<IHistoryFn>;
     __inspectorPatched?: boolean;
@@ -1001,6 +1267,63 @@ export declare interface IRegionElement {
     text?: string;
 }
 
+export declare interface IResolvedLocale {
+    /** The locale to render, always a member of `locales` (or the default). */
+    locale: string;
+    source: LocaleSource;
+    /**
+     * The locale prefix stripped off the incoming pathname, if any — `/fr-FR/pricing` →
+     * `fr-FR`. Null on a neutral URL. This is what tells the caller the visitor is on a
+     * canonical URL rather than a negotiated one.
+     */
+    prefix: string | null;
+    /** The pathname with any locale prefix removed — `/fr-FR/pricing` → `/pricing`. */
+    neutralPath: string;
+}
+
+export declare interface IResolveLocaleOptions {
+    /** Full locale list from `site.json` (`workspace.locales`). */
+    locales?: string[];
+    /** Locale served at unprefixed URLs (`workspace.default_locale`). */
+    defaultLocale?: string;
+    /** The request pathname, e.g. `/fr-FR/pricing`. */
+    pathname: string;
+    /** Request headers. Server-side only; omit on the client. */
+    headers?: Record<string, string | string[]> | Headers | null;
+    /** Value of the `levo_locale` cookie, if the visitor has one. */
+    cookieLocale?: string | null;
+    /**
+     * Skip cookie/header/geo negotiation and pin to the default. Set for crawlers, so a
+     * neutral URL genuinely IS its canonical language from Google's point of view.
+     */
+    forceDefault?: boolean;
+}
+
+export declare interface IResolveLocaleRedirectOptions {
+    /** The locale the visitor should see, from `resolveLocale`. */
+    locale: string;
+    /** Locale served at unprefixed URLs. */
+    defaultLocale: string;
+    /** The locale prefix already present in the URL, or null on a neutral URL. */
+    prefix: string | null;
+    /** The request path with any locale prefix removed. */
+    neutralPath: string;
+    /** Every locale the site publishes. */
+    locales: string[];
+    /**
+     * Does a route file exist at this path? Prevents redirecting to a translation that was
+     * never written: `/hi-IN/careers` absent means the visitor stays on `/careers` and reads
+     * the default language, rather than being bounced to a 404.
+     */
+    hasRoute?: (pathname: string) => boolean;
+    /**
+     * The pathname exactly as the visitor asked for it. Only used to detect a prefix whose
+     * spelling differs from the site's own, e.g. `/EN/pricing` for a site publishing `en`.
+     * Omit and that correction is skipped.
+     */
+    currentPath?: string;
+}
+
 /** The element-selected payload — see `selectedPayload`. */
 export declare interface ISelectedElement {
     tag: string;
@@ -1080,6 +1403,22 @@ export declare interface ISiteJson {
         insights_url?: string | null;
         app_mode?: string;
     };
+    /**
+     * Every locale the site publishes, as dash-form full locales (`en-GB`, `fr-FR`, `ar-AE`)
+     * to match how `page.language` stores them. Projected from `workspace.locales` — locales
+     * are a WORKSPACE-level setting, so every site in a workspace shares this list.
+     *
+     * Absent or length <= 1 → localization is entirely inert: no rewrite, no hreflang, no
+     * cookie. That is every site today, which is what lets the mechanism ship before the
+     * builder learns to generate `/fr-FR/*` routes.
+     */
+    locales?: string[];
+    /**
+     * The locale served at UNPREFIXED URLs. `/pricing` is this locale's canonical home, and
+     * it deliberately has no `/en-GB/pricing` twin — a prefixed default would be a duplicate
+     * needing its own canonical. Projected from `workspace.default_locale`.
+     */
+    default_locale?: string;
 }
 
 /** Site-wide defaults + site-wide raw head, from `src/pages/_site.meta.ts`. */
@@ -1307,6 +1646,62 @@ export declare const LevoSiteProvider: React.FC<{
     children: React.ReactNode;
 }>;
 
+/** Cookie the resolved locale is persisted under. Readable by JS — the switcher writes it. */
+export declare const LOCALE_COOKIE = "levo_locale";
+
+/** Cache-Control for the doorway redirect. Never let a shared cache store this — see above. */
+export declare const LOCALE_REDIRECT_CACHE_CONTROL = "private, no-store";
+
+/**
+ * Build the `beforeLoad` guard for a site's root route.
+ *
+ * `routeTree` is passed here rather than carried on the config because `__root.tsx` is imported
+ * by the generated tree; the matcher it produces reads the tree lazily, on the first navigation,
+ * which is what keeps that circular import safe.
+ */
+export declare const localeBeforeLoad: (config: ILocaleConfig, routeTree: unknown) => ({ location }: {
+    location: {
+        pathname: string;
+        searchStr?: string;
+    };
+}) => void;
+
+export declare const LocaleHreflang: React.FC<ILocaleHreflangProps>;
+
+/**
+ * The URL a page has in a given variant.
+ *
+ * On a multi-variant site EVERY variant is prefixed — including the site's default. That is
+ * what makes each page cacheable: `/en/pricing` is always English and `/fr-FR/pricing` is
+ * always French, so a plain URL-keyed cache is correct with no configuration. The unprefixed
+ * `/pricing` is not a page at all under this model; it is the doorway that redirects.
+ *
+ * A single-variant site gets no prefixes — `/en/` on every URL of a site that only speaks
+ * English is noise, and there is nothing to disambiguate.
+ *
+ * The default locale takes a prefix like every other, so this needs no knowledge of which one
+ * it is. (It did while the default was unprefixed; that inverted on 2026-08-18.)
+ */
+export declare const localePath: (path: string, locale: string, locales: string[]) => string;
+
+export declare const LocaleProvider: React.FC<ILocaleProviderProps>;
+
+/**
+ * Build the HTTP response for a redirect decision.
+ *
+ * Exists so the server path cannot assemble it wrongly: status and headers come straight off the
+ * decision, and `302` (never `301`) is fixed here — the target depends on who is asking, so a
+ * browser must never remember it as permanent.
+ */
+export declare const localeRedirectResponse: (decision: ILocaleRedirect, search?: string, hash?: string) => Response;
+
+/**
+ * How a locale was chosen. Surfaced so callers can act on provenance rather than re-deriving
+ * it: `prefix` means the visitor is on a canonical locale URL (don't redirect, don't restamp
+ * the cookie), and `default` on a multi-locale site means nothing matched.
+ */
+export declare type LocaleSource = "prefix" | "cookie" | "header" | "geo" | "default";
+
 /**
  * To E.164: strip every separator, keep one leading `+`. `"+91 98765 43210"` and
  * `"0091-98765-43210"` both normalize to `"+919876543210"` — the format the OTP endpoint
@@ -1387,6 +1782,9 @@ export declare const prefetchLevoSources: ({ queryClient, config, sources, param
     params?: Record<string, string>;
 }) => Promise<Record<string, unknown>>;
 
+/** Read the locale config out of a site's `site.json`. */
+export declare const readLocaleConfig: (site: ISiteJson) => ILocaleConfig;
+
 /**
  * The id the currently matched route stamped into the head, or null when the site's
  * platform hasn't stamped ids into its meta files yet (the field ships empty). Client-only —
@@ -1407,6 +1805,41 @@ export declare const resolveAuthMethods: (rules: ILevoAccessConfig) => ILevoAuth
 /** What `system` resolves to — the class actually on `<html>`. */
 export declare type ResolvedColorMode = "dark" | "light";
 
+/**
+ * Resolve which locale to serve.
+ *
+ * Precedence: explicit URL prefix → cookie → `Accept-Language` → GeoIP country → default.
+ *
+ * The prefix wins over the cookie deliberately: a `/fr-FR/pricing` link shared with someone
+ * whose cookie says `de-DE` must render French, or shared links stop meaning anything.
+ *
+ * GeoIP sits BELOW `Accept-Language` because country is a weaker signal for language than
+ * the visitor's own stated browser preference — someone in Belgium may want either Dutch or
+ * French, and their browser already answered that.
+ */
+export declare const resolveLocale: (options: IResolveLocaleOptions) => IResolvedLocale;
+
+/**
+ * The path to redirect a visitor to, or `null` to serve the current URL as-is.
+ *
+ * Returns null — meaning "no redirect" — in every one of these cases:
+ *   - the visitor is already on a prefixed URL (they asked for that language explicitly)
+ *   - the site publishes one locale or none
+ *   - no route file exists for this page in the visitor's language
+ */
+export declare const resolveLocaleRedirect: (options: IResolveLocaleRedirectOptions) => string | null;
+
+/**
+ * Decide what to do with one request to a possibly-unprefixed URL.
+ *
+ * Bot detection is derived here rather than asked of the caller. Crawlers must always see the
+ * default language at a neutral URL — it is what makes that URL genuinely *be* its canonical
+ * language — and that is a property of the design, not a decision each doorway should be making
+ * for itself. `resolveLocale`'s `forceDefault` stays available for anything that needs to pin it
+ * directly.
+ */
+export declare const resolveLocaleRequest: (options: ILocaleRequestOptions) => ILocaleDecision;
+
 /**
  * The site's Levo client config from its `site.json` — the only place that mapping lives, so
  * the provider and the SSR route loader can't drift apart.
@@ -1416,9 +1849,65 @@ export declare type ResolvedColorMode = "dark" | "light";
  */
 export declare const siteConfigFromJson: (site: ISiteJson) => ILevoSiteConfig;
 
+/**
+ * Mount the locale context from a site's config.
+ *
+ * Prefer this over `<LocaleProvider>` in a generated site: it derives the active language from
+ * the URL itself, so there is no second copy of that derivation to fall out of step with the
+ * `<html lang>` or the hreflang tags.
+ */
+export declare const SiteLocaleProvider: React.FC<{
+    config: ILocaleConfig;
+    children: React.ReactNode;
+    /**
+     * The generated route tree. Supplying it lets the switcher hide languages this page has no
+     * translation into — the difference between offering a link and offering a 404.
+     */
+    routeTree?: unknown;
+}>;
+
+/**
+ * Split a locale prefix off a pathname. Only strips a segment that is a KNOWN locale, so a
+ * site with a page genuinely named `/fr-FR` (or any other collision) is unaffected — the
+ * segment has to be in the site's own locale list to count.
+ */
+export declare const splitLocalePrefix: (pathname: string, locales: string[]) => {
+    prefix: string | null;
+    neutralPath: string;
+};
+
 /** Read/set the current color mode. Throws outside a `<ColorModeProvider>`. */
 export declare function useColorMode(): IColorModeState;
 
+/**
+ * The behaviour half of a language switcher, so the starter only owns the look.
+ *
+ * Three things here are load-bearing and were previously comments in a starter component asking
+ * not to be "simplified":
+ *
+ * 1. `href` is a real canonical URL, so a crawler can follow it. A switcher built from buttons
+ *    and a click handler is invisible to search, and the site's own hreflang tags then point at
+ *    pages nothing links to.
+ * 2. A plain left-click is intercepted into a cookie write plus a navigation, so the choice is
+ *    remembered. Modifier and middle clicks are deliberately NOT intercepted, so "open in new
+ *    tab" lands on the real URL like any other link.
+ * 3. The path is stripped back to its neutral form before each variant's URL is built, or the
+ *    hrefs come out doubled (`/de-DE/fr-FR/pricing`).
+ *
+ * Render `options` however you want; drop `linkProps` onto an `<a>` and none of the above can
+ * be lost.
+ *
+ * Languages this page has no translation into are OMITTED, when the provider was given a route
+ * tree. Their URL would be a real 404: a prefixed URL is an explicit request, so the doorway
+ * correctly declines to redirect it, and there is no page behind it. This is the same rule the
+ * hreflang tags follow — a switcher offering what hreflang refuses to advertise is the two
+ * halves disagreeing about which pages exist.
+ *
+ * Returns an empty list when fewer than two languages remain, so a switcher self-hides on a
+ * single-locale site and on a page that only exists in one language.
+ */
+export declare function useLanguageOptions(): ILanguageOption[];
+
 export declare const useLevoAccess: (source: ILevoAccessSource) => ILevoAccessResult;
 
 export declare const useLevoAuth: () => ILevoAuthState;
@@ -1468,4 +1957,26 @@ export declare const useLevoSite: () => ILevoClient | null;
  */
 export declare const useLevoSource: <T = Record<string, unknown>>(config: ILevoSourceConfig) => ILevoSourceResult<T>;
 
+/**
+ * Read the active locale and switch languages.
+ *
+ * Returns an inert single-locale state outside a `<LocaleProvider>` rather than throwing —
+ * unlike `useColorMode`, which throws. A switcher is page content the AI may drop onto a
+ * site whose provider was never wired, and crashing the whole page over a language picker is
+ * a worse failure than rendering nothing.
+ */
+export declare function useLocale(): ILocaleState;
+
+/**
+ * The language the current URL serves.
+ *
+ * Read off the URL, not negotiated: every variant is a prefixed URL under the redirect model,
+ * so `/hi-IN/pricing` is Hindi and nothing else, and server and browser cannot disagree about
+ * it. (When locales were applied as a rewrite they could, and did — three separate bugs where
+ * the page rendered in one language and hydrated in another.)
+ *
+ * For `<html lang>`, which sits above the provider and so cannot use `useLocale()`.
+ */
+export declare function useUrlLocale(config: ILocaleConfig): string;
+
 export { }