@levo-so/site-runtime 0.3.1 → 0.3.8

package/index.d.ts

@@ -1,6 +1,7 @@
 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';
 
@@ -39,7 +40,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,8 +49,20 @@ 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;
     };
@@ -65,6 +78,66 @@ 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;
+
+/**
+ * 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;
+    };
+}
+
 export declare interface IColorModeProviderProps {
     children: React.ReactNode;
     /** Fallback when nothing is stored yet. */
@@ -191,11 +264,191 @@ 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;
+    /**
+     * The visitor's current URL path, sourced from TanStack Router in
+     * `LevoSiteProvider` (`useRouterState` → `state.location.pathname`). Forwarded
+     * to the widget's boot call so a multi-agent v3 site resolves the agent bound
+     * to this path, and RE-resolves it when the path changes on client navigation
+     * — the launcher mounts once at `__root` and never remounts across route
+     * changes, so this prop is the only signal that the URL moved. A v3 site is
+     * code-routed (no `[visitor]/[workspace]` rewrite), so the router pathname is
+     * already the visitor-facing URL. Omitted → the BE treats the path as "/" and
+     * the whole-site catch-all agent answers.
+     *
+     * Example: land on /pricing → path="/pricing" → Sales. Client-navigate to
+     * /help → path="/help" → Support. One mount, agent swapped.
+     */
+    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>;
 
@@ -217,6 +470,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
@@ -263,12 +529,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;
@@ -291,6 +563,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
@@ -305,6 +691,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";
@@ -435,6 +836,18 @@ 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 IPatchedHistoryFn {
     (this: History, ...args: Parameters<IHistoryFn>): ReturnType<IHistoryFn>;
     __inspectorPatched?: boolean;
@@ -453,6 +866,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`. */
@@ -670,6 +1093,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 {
@@ -695,6 +1126,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;
@@ -705,6 +1148,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-
@@ -714,6 +1213,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
@@ -761,6 +1276,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
@@ -778,6 +1307,13 @@ export declare const LevoSiteProvider: React.FC<{
     children: React.ReactNode;
 }>;
 
+/**
+ * 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";
 
@@ -806,6 +1342,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
@@ -842,6 +1394,16 @@ 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";
 
@@ -857,6 +1419,10 @@ export declare const siteConfigFromJson: (site: ISiteJson) => ILevoSiteConfig;
 /** Read/set the current color mode. Throws outside a `<ColorModeProvider>`. */
 export declare function useColorMode(): IColorModeState;
 
+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
@@ -868,6 +1434,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