@levo-so/site-runtime 0.3.7 → 0.3.9

package/index.d.ts

@@ -1,9 +1,19 @@
 import { ILemaCollection } from '@levo-so/core';
 import { ILevoClient } from '@levo-so/core';
 import { ILevoInsights } from '@levo-so/insights';
+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";
 
@@ -39,7 +49,7 @@ export declare const ColorModeProvider: React.FC<IColorModeProviderProps>;
 export declare const createLevoHead: (site: ISiteJson) => (meta?: IPlatformMetaFile, dynamic?: ILevoDynamicHead) => (ctx?: IHeadCtx) => IComposedHead;
 
 /**
- * Build the one-line route loader (`loader: levoLoader(dataSources)`): prefetch the
+ * Build the one-line route loader (`loader: levoLoader(dataSources, meta)`): prefetch the
  * page's declared data sources on the server so SSR ships fully-rendered HTML, and
  * return them keyed by source key — that map is the route's `loaderData`, which
  * `levoHead`'s dynamic config reads for per-record heads. An empty `dataSources` ({})
@@ -48,14 +58,43 @@ export declare const createLevoHead: (site: ISiteJson) => (meta?: IPlatformMetaF
  *
  * Takes the raw `site.json` — same single input as `createLevoHead` and
  * `LevoSiteProvider` — and derives the client config itself.
+ *
+ * GATED PAGES PREFETCH NOTHING. Pass the page's meta file (the same one `levoHead` gets)
+ * and a page with enabled `access` rules skips prefetch entirely. The prefetch runs on the
+ * SERVER, where the visitor's session cookie isn't available — so it would fetch as an
+ * anonymous caller and stream the result into the SSR payload of a page that has not been
+ * cleared to show it. Per-collection visibility means a truly private collection returns
+ * nothing to that caller, but a members-only page over public content would still have
+ * shipped its records to anyone who viewed source. The page's hooks fetch client-side once
+ * the gate opens, which is the only point at which we know who is asking.
+ *
+ * `meta` is optional so sites generated before this shipped keep working unchanged — they
+ * simply prefetch as they always did (and have no gates to protect).
  */
-export declare const createLevoLoader: (site: ISiteJson) => (sources: ILevoDataSources) => ({ context, params, }: {
+export declare const createLevoLoader: (site: ISiteJson) => (sources: ILevoDataSources, meta?: IPlatformMetaFile) => ({ context, params, }: {
     context: {
         queryClient: IQueryClientLike;
     };
     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.
@@ -65,6 +104,95 @@ export declare const createLevoLoader: (site: ISiteJson) => (sources: ILevoDataS
  */
 export declare const createSiteClient: (config?: ILevoSiteConfig) => ILevoClient | null;
 
+/**
+ * Three layers, cheapest first:
+ *
+ *   1. NO GATES — granted synchronously, on the server too, with zero network. The path
+ *      ~every page takes, so an ungated site pays nothing for the gate existing.
+ *   2. NOT SIGNED IN — decided locally from the session. Every gate kind implies a login
+ *      (authentication by definition, profile explicitly, gating because entries are matched
+ *      by their `_account`), so a signed-out visitor gets the sign-in card immediately rather
+ *      than after a round-trip that could only have said the same thing.
+ *   3. SIGNED IN — the server's verdict. It reads the rules from the page ROW, never from
+ *      anything the client sends, so collection lookups and profile conditions are evaluated
+ *      where they can be trusted.
+ */
+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.
+ *
+ * Split from `useLevoAccess` on purpose: this is the most safety-critical logic in the
+ * feature — it decides whether a page renders — and as a hook it could only ever be
+ * exercised through React. Here it is a table of inputs to a verdict, readable top to bottom
+ * and testable without a renderer. The hook's remaining job is gathering the inputs.
+ *
+ * FAIL CLOSED. Every path that cannot produce a definite "yes" resolves to `blocked`. A
+ * gated page never falls open because something upstream was having a bad minute.
+ */
+/** What the check-access endpoint returns. */
+export declare interface IAccessCheckResponse {
+    has_access: boolean;
+    code?: ILevoAccessServerCode;
+    message?: string;
+}
+
+export declare interface IAccessDecision {
+    state: ILevoAccessState;
+    code: ILevoAccessCode | null;
+    message: string | null;
+    rule: ILevoAccessRule | null;
+}
+
+export declare interface IAccessDecisionInput {
+    /** Enabled, parseable rules on this page. Empty = ungated. */
+    rules: ILevoAccessRule[];
+    /** The page declared rules, but none of them parsed. */
+    invalid: boolean;
+    /** The platform page id from the meta file; `""` when unstamped. */
+    pageId: string;
+    /** The site is wired to a Levo backend. */
+    hasClient: boolean;
+    /** Hydrated AND the session question has been answered. False = undecided. */
+    isReady: boolean;
+    isLoggedIn: boolean;
+    /** The server check, passed through from the query. */
+    check: {
+        isError: boolean;
+        isSuccess: boolean;
+        data: IAccessCheckResponse | null;
+    };
+}
+
+/**
+ * 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. */
@@ -92,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";
@@ -178,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;
@@ -191,6 +388,168 @@ export declare interface ILayersNode {
     children: ILayersNode[];
 }
 
+/**
+ * `kind: "authentication"` — the visitor must be signed in, via one of `methods`.
+ * `primary_method` picks which passwordless form the login card leads with; the OAuth
+ * entries in `methods` become the buttons above it.
+ */
+export declare interface ILevoAccessAuthenticationOptions {
+    methods?: ILevoAuthMethod[];
+    primary_method?: ILevoPrimaryAuthMethod;
+}
+
+export declare type ILevoAccessCode = ILevoAccessServerCode | ILevoAccessRuntimeCode;
+
+/** The `access` array in a page's `meta/<route>.json`. Every enabled rule must pass. */
+export declare type ILevoAccessConfig = ILevoAccessRule[];
+
+/**
+ * `kind: "gating"` — the visitor must own an entry in `collection` that satisfies
+ * `condition`. Ownership is by the entry's `_account`, so this is always login-implying.
+ * No entry → the site shows its entry form; entry that fails the condition → the
+ * "under review" message.
+ */
+export declare interface ILevoAccessGatingOptions {
+    /** Collection key the visitor's entry must live in. */
+    collection: string;
+    /** LevoQuery `where` the entry must satisfy. Absent/empty = any entry passes. */
+    condition?: LevoQuery.Where;
+    /** Field keys hidden in the entry form the site renders when no entry exists. */
+    hidden?: string[];
+}
+
+/**
+ * `kind: "profile"` — account access: signed in AND the visitor's OWN membership account
+ * satisfies `condition`. There is no collection here (the membership account is resolved
+ * server-side); failing accounts get the profile-completion form.
+ */
+export declare interface ILevoAccessProfileOptions {
+    /** "Profile is complete when" — a LevoQuery `where` over the account. Empty = always passes. */
+    condition?: LevoQuery.Where;
+    /** Extra account field keys to hide in the profile-completion form. */
+    hidden?: string[];
+}
+
+/** What `useLevoAccess` hands a page. */
+export declare interface ILevoAccessResult {
+    state: ILevoAccessState;
+    /** Null only while `checking` (and on a page with no gates). */
+    code: ILevoAccessCode | null;
+    /** The server's human-readable reason, when it produced one. Cards may use it as a fallback. */
+    message: string | null;
+    /** The rule that blocked — the card reads its `options` (collection, hidden fields, …). */
+    rule: ILevoAccessRule | null;
+    /** Login methods for the sign-in card, resolved from this page's config. */
+    authMethods: ILevoAuthMethods;
+    /** Re-run the gate — pass as `onSuccess` to any card that can change the outcome. */
+    recheck: () => void;
+    /** A `recheck()` (or the very first check) is in flight. */
+    isChecking: boolean;
+}
+
+/**
+ * One gate. `enabled` defaults to true when the key is absent — an author writing a rule
+ * down means it should apply; only an explicit `false` parks it.
+ */
+export declare type ILevoAccessRule = {
+    kind: "authentication";
+    enabled?: boolean;
+    options?: ILevoAccessAuthenticationOptions;
+} | {
+    kind: "gating";
+    enabled?: boolean;
+    options: ILevoAccessGatingOptions;
+} | {
+    kind: "profile";
+    enabled?: boolean;
+    options?: ILevoAccessProfileOptions;
+};
+
+/**
+ * Codes the RUNTIME raises without asking the server. Namespaced `access.*` so they can
+ * never collide with a server code, present or future.
+ *
+ * - `CONFIG_INVALID` — the page has an `access` array we could not parse into a single
+ *   valid rule. Fail-closed: a typo in hand-edited JSON must not silently un-gate a page.
+ * - `PAGE_NOT_IDENTIFIED` — the meta file carries no platform `id`, so there is nothing to
+ *   ask the server about (a page whose row hasn't been stamped yet).
+ * - `UNWIRED` — the site has no Levo backend at all (`site.json` without `api_url`).
+ * - `CHECK_FAILED` — the check-access call itself failed (network, 5xx).
+ */
+export declare type ILevoAccessRuntimeCode = "access.CONFIG_INVALID" | "access.PAGE_NOT_IDENTIFIED" | "access.UNWIRED" | "access.CHECK_FAILED";
+
+/** Codes returned by the server's check-access evaluation. */
+export declare type ILevoAccessServerCode = "authentication.NOT_CONFIGURED" | "authentication.NOT_LOGGED_IN" | "authentication.SUCCESS" | "gating.NOT_CONFIGURED" | "gating.IDENTIFIER_NOT_FOUND" | "gating.ENTRY_NOT_FOUND" | "gating.ENTRY_CONDITION_NOT_FULFILLED" | "gating.SUCCESS" | "profile.NOT_LOGGED_IN" | "profile.CONDITION_NOT_FULFILLED" | "profile.SUCCESS";
+
+/**
+ * The gate: reads a page's own `meta/<route>.json` and answers whether this visitor may see
+ * this page. The page hands the result to whichever card matches the code — this renders
+ * nothing itself.
+ *
+ * This hook only GATHERS (session, config, server check); the verdict is `decideAccess`, a
+ * pure function next door. Keeping them apart is what makes the policy readable and testable
+ * on its own.
+ */
+/**
+ * The page identity + gates this hook needs. A route's imported `meta/<route>.json`
+ * satisfies it as-is — `access` is typed `unknown` on purpose, because a JSON import widens
+ * string literals (`kind: string`, not `kind: "gating"`) and would never structurally match
+ * the rule union. Validation happens at runtime in `parseAccess`, which is where a
+ * hand-edited file has to be checked anyway.
+ */
+export declare interface ILevoAccessSource {
+    /** The platform page id, stamped into the meta file. Empty on a page whose row is unstamped. */
+    id?: string;
+    /** The page's `access` array, straight from the meta file. */
+    access?: unknown;
+}
+
+/**
+ * Where the gate currently stands.
+ *
+ * - `checking` — undecided. Always the state during SSR and the first client frame for a
+ *   gated page, which is what keeps gated content out of the server-rendered HTML.
+ * - `granted` — render the page.
+ * - `blocked` — render the card for `code`.
+ *
+ * There is no fourth "errored" state on purpose: every way a check can fail resolves to
+ * `blocked` with an `access.*` code, so a caller that handles the three states handles
+ * everything.
+ */
+export declare type ILevoAccessState = "checking" | "granted" | "blocked";
+
+export declare type ILevoAuthMethod = ILevoPrimaryAuthMethod | ILevoOAuthMethod;
+
+/**
+ * The login methods a card should offer, resolved from the page's OWN config (never from
+ * the server response) so the card renders identically whether the block was decided
+ * locally or server-side.
+ */
+export declare interface ILevoAuthMethods {
+    /** The passwordless form to lead with. Falls back to `otp` when a page configures none. */
+    primary: ILevoPrimaryAuthMethod;
+    /** OAuth providers to offer above the primary form. Empty when none are configured. */
+    oauth: ILevoOAuthMethod[];
+}
+
+export declare interface ILevoAuthState {
+    /** The signed-in membership account, or null. */
+    account: ILevoMembership.Account | null;
+    isLoggedIn: boolean;
+    /**
+     * The session question has been answered. False during SSR, the first client frame, and
+     * while the first `getMe()` is in flight — treat it as "don't know yet", never as
+     * "signed out".
+     */
+    isLoaded: boolean;
+    /** A session request is in flight (first load or a refresh). */
+    isLoading: boolean;
+    /** Re-read the session — call after any sign-in that happened outside this hook. */
+    refresh: () => Promise<void>;
+    signOut: () => Promise<void>;
+    isSigningOut: boolean;
+}
+
 export declare interface ILevoChatProps {
     /** The site's root `site.json` — all chat props are derived from it. */
     site: ISiteJson;
@@ -211,6 +570,9 @@ export declare interface ILevoChatProps {
     path?: string;
 }
 
+/** How the verification code reaches the visitor. */
+export declare type ILevoCodeMedium = "email" | "whatsapp";
+
 /** The shape a page exports so its route loader can prefetch every binding it renders. */
 export declare type ILevoDataSources = Record<string, ILevoSourceDef>;
 
@@ -232,6 +594,19 @@ export declare interface ILevoDynamicHead {
     image?: string;
 }
 
+export declare interface ILevoEntryFormProps {
+    /** The gated collection's key — take it from the blocking rule's `options.collection`. */
+    collection: string;
+    /** Field keys to hide — the rule's `options.hidden`. */
+    hidden?: string[];
+    submitLabel?: string;
+    /** Called once the entry is saved. Wire it to the gate's `recheck` so the page re-evaluates. */
+    onSuccess?: () => void;
+    /** Per-form color/radius overrides. Rarely needed — the form already follows the site theme. */
+    theme?: ILevoFormTheme;
+    className?: string;
+}
+
 /**
  * A form binding — the fields + submit for a collection. `LevoForm` renders it (the schema
  * drives which inputs appear); submissions go to the collection. Forms only bind to
@@ -278,12 +653,18 @@ export declare interface ILevoFormResult {
     };
 }
 
+/**
+ * The bridge between the collection form renderer's color contract and the generated site's
+ * semantic theme tokens. Shared by every form the runtime renders — the page's `<LevoForm>`,
+ * and the access cards' entry + profile forms — so a `theme.css` edit re-skins all of them
+ * together and none of them can drift into looking like a different product.
+ */
 /**
  * Per-form color/radius overrides. Every value is any CSS color/length — pass a site token
  * (`"var(--color-brand)"`) or a literal (`"#0ea5e9"`). Omitted keys fall through to the site
  * theme (see `DEFAULT_FORM_TOKENS`), so a form auto-matches the brand without any theme prop.
  */
-declare interface ILevoFormTheme {
+export declare interface ILevoFormTheme {
     colors?: Partial<{
         /** Buttons, focus accents. */
         primary: string;
@@ -306,6 +687,120 @@ declare interface ILevoFormTheme {
     gap?: string;
 }
 
+export declare interface ILevoLoginActions {
+    /**
+     * Send a verification code. `identifier` is the email address (medium `"email"`) or the
+     * E.164 phone number (medium `"whatsapp"`) — normalize it with `normalizePhone` first.
+     */
+    sendCode: (params: {
+        identifier: string;
+        medium?: ILevoCodeMedium;
+    }) => Promise<ILevoLoginOutcome>;
+    /** Same call as `sendCode`; separate so a form can show "Resending…" without touching the send button. */
+    resendCode: (params: {
+        identifier: string;
+        medium?: ILevoCodeMedium;
+    }) => Promise<ILevoLoginOutcome>;
+    /** Exchange the code for a session. On success the shared session cache updates immediately. */
+    verifyCode: (params: {
+        identifier: string;
+        code: string;
+    }) => Promise<ILevoLoginOutcome<ILevoMembership.Account | null>>;
+    /** Email a magic link back to the current URL. */
+    sendMagicLink: (email: string) => Promise<ILevoLoginOutcome>;
+    isSendingCode: boolean;
+    isResendingCode: boolean;
+    isVerifying: boolean;
+    isSendingMagicLink: boolean;
+}
+
+/** A failed action, flattened to what a form can render without knowing about LevoError. */
+export declare interface ILevoLoginError {
+    code: string;
+    title: string;
+    message: string;
+    /** Per-field validation messages, keyed by field name. Empty when the error isn't a validation one. */
+    fieldErrors: Record<string, string>;
+    /** True when the visitor's account is awaiting approval — show the pending screen, not an error. */
+    isPendingApproval: boolean;
+}
+
+export declare type ILevoLoginOutcome<T = void> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: ILevoLoginError;
+};
+
+export declare interface ILevoOAuthHandle {
+    provider: ILevoOAuthMethod;
+    /** Opens the provider's popup. Must be called straight from a click — browsers block otherwise. */
+    signIn: () => void;
+}
+
+export declare type ILevoOAuthMethod = (typeof LEVO_OAUTH_METHODS)[number];
+
+export declare interface ILevoOAuthState {
+    /**
+     * One handle per provider that is BOTH configured on the page and enabled in the
+     * workspace. Empty while the URLs load, so buttons appear only once they can work.
+     */
+    providers: ILevoOAuthHandle[];
+    isLoading: boolean;
+    /** The provider whose popup is open, if any — for a per-button spinner. */
+    pendingProvider: ILevoOAuthMethod | null;
+    /** Last failure (loading the URLs, or the provider rejecting the sign-in). */
+    error: ILevoLoginError | null;
+    clearError: () => void;
+}
+
+export declare interface ILevoOtpInputState {
+    slots: ILevoOtpSlot[];
+    /** Spread onto the element wrapping the boxes — announces them as one field. */
+    containerProps: {
+        role: "group";
+        "aria-label": string;
+    };
+    /** Clear every box and return focus to the first — for a "wrong code, try again" reset. */
+    clear: () => void;
+}
+
+/**
+ * A segmented verification-code input, minus the markup.
+ *
+ * The site owns how the boxes LOOK; this owns how they BEHAVE — and the behaviour is where
+ * these go wrong. Auto-advance, backspace stepping back, arrow keys, paste, and the browser
+ * dropping an entire autofilled code into the first box are five separate bugs waiting to
+ * happen, and none of them are visible when you restyle a box. So they live here, where a
+ * design change can't reach them.
+ *
+ * The value is always LEFT-PACKED: `"12"` means boxes 1–2 are filled and 3–4 are empty, and
+ * there is no way to represent a gap. Focusing a box beyond the end snaps back to the first
+ * empty one, which is what keeps that invariant true no matter where the visitor clicks.
+ */
+export declare interface ILevoOtpSlot {
+    /** The digit in this box, or `""`. */
+    char: string;
+    /** This box has focus — for a ring or a caret bar. */
+    isActive: boolean;
+    /** Spread onto the box's `<input>`. Includes the ref, so don't set your own. */
+    inputProps: {
+        ref: (element: HTMLInputElement | null) => void;
+        value: string;
+        inputMode: "numeric";
+        autoComplete: "one-time-code" | "off";
+        type: "text";
+        "aria-label": string;
+        onChange: (event: React.ChangeEvent<HTMLInputElement>) => void;
+        onKeyDown: (event: React.KeyboardEvent<HTMLInputElement>) => void;
+        onPaste: (event: React.ClipboardEvent<HTMLInputElement>) => void;
+        onFocus: () => void;
+        onBlur: () => void;
+        disabled?: boolean;
+    };
+}
+
 export declare interface ILevoPopupsProps {
     /**
      * The site's id (`site.json` `id`) — scopes the active-popups fetch. Absent → the
@@ -320,6 +815,21 @@ export declare interface ILevoPopupsProps {
     pageId?: string;
 }
 
+export declare type ILevoPrimaryAuthMethod = (typeof LEVO_PRIMARY_AUTH_METHODS)[number];
+
+export declare interface ILevoProfileFormProps {
+    /** Extra account field keys to hide — the blocking rule's `options.hidden`. */
+    hidden?: string[];
+    submitLabel?: string;
+    /** Called after the account updates. Wire it to the gate's `recheck`. */
+    onSuccess?: () => void;
+    /** Class for the inline submit-error line. Defaults to the theme's danger color. */
+    errorClassName?: string;
+    /** Per-form color/radius overrides. Rarely needed — the form already follows the site theme. */
+    theme?: ILevoFormTheme;
+    className?: string;
+}
+
 /** A single-record binding — one collection record / blog post / event by `slug` (a detail page). */
 export declare interface ILevoRecordConfig {
     module: "collection" | "blog" | "event";
@@ -399,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. */
@@ -450,6 +1096,24 @@ export declare interface IPageSource {
     label: string;
 }
 
+/** What `parseAccess` decided about a page's `access` block. */
+export declare interface IParsedAccess {
+    /** Every enabled, usable rule. Empty when the page is ungated. */
+    rules: ILevoAccessRule[];
+    /**
+     * True when `access` held entries but not one of them parsed — a malformed block.
+     * The gate treats this as BLOCKED, never as ungated: silently serving a page whose
+     * author wrote a gate for it is the one failure mode worth being loud about.
+     */
+    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;
@@ -468,6 +1132,16 @@ export declare interface IPlatformMetaFile {
     title?: string;
     description?: string;
     meta?: IPlatformPageMeta;
+    /**
+     * The page's access gates — see `./access/types`. FILE-owned like `meta`: the AI writes
+     * it, and the platform mirrors it into the page row, which is what the server evaluates.
+     *
+     * Typed `unknown` deliberately. A JSON import widens string literals (`kind: string`, not
+     * `kind: "gating"`), so a precise type here would reject every real meta file; the block
+     * is validated at runtime by `parseAccess` instead, which is where a hand-edited file has
+     * to be checked regardless.
+     */
+    access?: unknown;
 }
 
 /** The platform's per-page SEO object — the `meta` key of `meta/<route>.json`. */
@@ -593,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;
@@ -672,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`. */
@@ -685,6 +1432,14 @@ export declare interface ISiteMeta extends IPageMeta {
     icon?: string;
 }
 
+/**
+ * Pending approval is not a failure to show in a red box — it means "your request landed,
+ * a human has to act". The sign-in card swaps to its own screen for it, so every entry
+ * point (OTP, magic link, OAuth) has to recognise it the same way. Matched loosely because
+ * the code has been namespaced differently across services.
+ */
+export declare const isPendingApprovalError: (code?: string | null) => boolean;
+
 export declare type IStagedEntry = IStagedStyleEntry | IStagedTextEntry | IStagedImageEntry;
 
 declare interface IStagedImageEntry {
@@ -710,6 +1465,18 @@ export declare interface IStagedTextEntry {
     value: string;
 }
 
+/**
+ * Deliberately permissive: `something@something.tld`, no attempt to enumerate valid TLDs or
+ * implement RFC 5322. The address is proven by the visitor receiving the code — the only
+ * job here is catching a typo before we spend a round-trip on it.
+ */
+export declare const isValidEmail: (value: string) => boolean;
+
+export declare const isValidOtp: (value: string) => boolean;
+
+/** E.164 shape: a country code that can't start with 0, then 7–14 more digits. */
+export declare const isValidPhone: (value: string) => boolean;
+
 /** The element-text-changed payload — see `commit`. */
 export declare interface ITextChangedElement {
     source: string | null;
@@ -720,6 +1487,62 @@ export declare interface ITextChangedElement {
     occurrences: number;
 }
 
+export declare interface IUseLevoOAuthParams {
+    /** Providers this page offers, from its access config. Anything else is ignored. */
+    methods: ILevoOAuthMethod[];
+    /** Popup window title — usually the site name. */
+    title?: string;
+    /** Fired after a successful sign-in; the session cache is already refreshed by then. */
+    onSuccess?: () => void;
+    /** Fired on failure. Check `error.isPendingApproval` before rendering it as an error. */
+    onError?: (error: ILevoLoginError) => void;
+}
+
+export declare interface IUseLevoOtpInputParams {
+    value: string;
+    onChange: (value: string) => void;
+    /** Digits in the code. Defaults to the platform's length. */
+    length?: number;
+    /**
+     * Fired the moment the last box fills, with the complete code. Use it to submit — waiting
+     * for a button press after the final digit is a step nobody wants. The code is passed as an
+     * argument because the caller's state hasn't re-rendered yet when this runs.
+     */
+    onComplete?: (code: string) => void;
+    /** Focus the first box on mount. */
+    autoFocus?: boolean;
+    disabled?: boolean;
+}
+
+/** Every method a page may list in `options.methods`. */
+export declare const LEVO_AUTH_METHODS: ILevoAuthMethod[];
+
+/**
+ * The visitor's session, shared across every component on the page.
+ *
+ * Backed by TanStack Query rather than a provider: the site already mounts a QueryClient
+ * for data sources, so one cache entry gives every card, navbar, and gate the same account
+ * with one request — and any of them can invalidate it after a sign-in.
+ *
+ * CLIENT-ONLY BY CONSTRUCTION. The session lives in a cookie the SSR pass cannot see, so a
+ * server-side `getMe()` would resolve "signed out" for a signed-in visitor and bake that
+ * into the HTML. Gating it on `useMounted` means a gated page renders its `checking` state
+ * on the server — which is also what keeps gated content out of the server-rendered HTML.
+ */
+export declare const LEVO_AUTH_QUERY_KEY: readonly ["levo-auth", "session"];
+
+/** OAuth providers — rendered as buttons ALONGSIDE the primary form, any number of them. */
+export declare const LEVO_OAUTH_METHODS: readonly ["google", "microsoft", "linkedin"];
+
+/** Digits in the verification code the platform sends. */
+export declare const LEVO_OTP_LENGTH = 4;
+
+/** The error code the platform returns when the account exists but awaits admin approval. */
+export declare const LEVO_PENDING_APPROVAL_CODE = "membership.account.ACCOUNT_PENDING_APPROVAL";
+
+/** Passwordless methods — exactly one of these is the login card's PRIMARY form. */
+export declare const LEVO_PRIMARY_AUTH_METHODS: readonly ["otp", "magiclink", "whatsapp"];
+
 /**
  * Drops the site's AI chat widget onto every page, wired from `site.json`. Mounted once
  * from the scaffold's `__root` (via the `SiteChat` shim) alongside `<Inspector />`. Self-
@@ -729,6 +1552,22 @@ export declare interface ITextChangedElement {
  */
 export declare const LevoChat: React.FC<ILevoChatProps>;
 
+/**
+ * The "request access" form for a `gating` rule — the collection's own fields, submitted as
+ * an entry owned by the signed-in visitor.
+ *
+ * Ownership is what makes the gate work: the server matches entries by `_account`, so this
+ * form only ever renders for a signed-in visitor and the submission carries their session.
+ * The visitor's email/mobile prefill the schema's designated contact fields, which is both a
+ * convenience and what keeps the entry findable by a human reviewing the collection.
+ *
+ * Distinct from the page-level `<LevoForm>` in one way that matters: the schema is fetched
+ * client-side, because a gated page's route loader never prefetches it — the form only
+ * exists on the blocked path, and prefetching it on every visit would tell the SSR pass
+ * something about a page it is not allowed to render.
+ */
+export declare const LevoEntryForm: React.FC<ILevoEntryFormProps>;
+
 /**
  * Self-contained event registration widget for generated Studio v3 sites — ticket
  * selection, coupons, attendee details, payment (Razorpay by default; Stripe Embedded
@@ -776,6 +1615,20 @@ export declare const LevoForm: React.FC<ILevoFormProps>;
  */
 export declare const LevoPopups: React.FC<ILevoPopupsProps>;
 
+/**
+ * The profile-completion form for a `profile` rule.
+ *
+ * Submits through `membership.updateMe` — it edits the visitor's OWN account, and never
+ * creates a collection entry (that's what `gating` does). Only visible, non-readonly fields
+ * are sent: echoing back the whole form would push system fields and the locked identity
+ * fields through an endpoint that has no reason to receive them.
+ *
+ * Renders its own submit error inline rather than handing it upward, because an error that
+ * depends on a site component remembering to display it is an error that eventually isn't
+ * displayed.
+ */
+export declare const LevoProfileForm: React.FC<ILevoProfileFormProps>;
+
 /**
  * Mounts the Levo client + insights for a generated site, and the site-wide overlays that
  * ride on top of it (AI chat + popups). Rendered once from the scaffold's `__root` (via the
@@ -793,6 +1646,69 @@ 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
+ * expects, and the one Studio's phone widget emits.
+ */
+export declare const normalizePhone: (value: string) => string;
+
 /** `name` of the head tag carrying the page id. Written by `levoHead`, read by `readPageId`. */
 export declare const PAGE_ID_META = "levo:page-id";
 
@@ -821,6 +1737,22 @@ export declare function PageHead({ meta, site }: {
  */
 export declare const pageHead: (meta?: IPageMeta, site?: ISiteMeta) => IComposedHead;
 
+/**
+ * Read a page's `access` block defensively.
+ *
+ * The three outcomes are deliberately distinct:
+ *   - absent / `[]` / every rule `enabled: false` → `{rules: [], invalid: false}` = ungated.
+ *     All three are an author SAYING "no gate", so the page renders with no network call.
+ *   - at least one usable rule                    → `{rules: [...], invalid: false}` = gated.
+ *   - entries present, none usable                → `{rules: [], invalid: true}`  = blocked.
+ *     A typo (`kind: "athentication"`, a gating rule missing its collection) must not read
+ *     the same as "no gate" — that would turn one wrong character into a public page.
+ *
+ * Note that a rule explicitly disabled is NOT invalid: it parsed fine, the author just
+ * turned it off. Only entries that fail to parse at all count toward `invalid`.
+ */
+export declare const parseAccess: (raw: unknown) => IParsedAccess;
+
 /**
  * Tolerant extraction of `<script>` / `<meta>` / `<link>` tags from a raw head snippet.
  * Unsupported tags are DROPPED (documented v1 limitation) — silently at runtime; the
@@ -850,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 —
@@ -857,9 +1792,54 @@ export declare const prefetchLevoSources: ({ queryClient, config, sources, param
  */
 export declare const readPageId: () => string | null;
 
+/**
+ * The login methods the sign-in card should offer for this page.
+ *
+ * Resolved from the page's own rules rather than the server's response so the card looks
+ * the same whether the block was decided locally (not signed in) or server-side. A page
+ * that gates on `profile` alone still needs a sign-in card — hence the fallback to email
+ * OTP when no authentication rule names any method.
+ */
+export declare const resolveAuthMethods: (rules: ILevoAccessConfig) => ILevoAuthMethods;
+
 /** 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.
@@ -869,9 +1849,69 @@ 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;
+
 /**
  * Load a collection's SCHEMA so `LevoForm` can render its fields. Like the other hooks the
  * config is a static literal (the editor binding); it reads the warm cache the route loader
@@ -883,6 +1923,12 @@ export declare const useLevoForm: (config: ILevoFormConfig) => ILevoFormResult;
 /** The site's insights (analytics/track), or `null` on an unwired site. */
 export declare const useLevoInsights: () => ILevoInsights | null;
 
+export declare const useLevoLogin: () => ILevoLoginActions;
+
+export declare const useLevoOAuth: ({ methods, title, onSuccess, onError, }: IUseLevoOAuthParams) => ILevoOAuthState;
+
+export declare const useLevoOtpInput: ({ value, onChange, length, onComplete, autoFocus, disabled, }: IUseLevoOtpInputParams) => ILevoOtpInputState;
+
 /**
  * Render ONE record by slug — a detail page. `slug` is a RUNTIME arg (the page's route
  * param), kept OUT of the config literal so the binding stays static and editable. No slug
@@ -911,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 { }