@frontmcp/ui 1.2.1 → 1.4.0

package/auth/AuthPageWrapper.d.ts

@@ -0,0 +1,56 @@
+/**
+ * `<AuthPageWrapper>` — outer chrome for a FrontMCP `@AuthUi` component.
+ *
+ * Responsibilities (client side):
+ * - Reads the server-injected {@link AuthFlowState} once and exposes it via
+ *   React context so the `useAuthFlow*` hooks can consume it.
+ * - Provides the in-memory `update` so a successful `submitExtra` can refresh
+ *   `addedItems` without a full reload.
+ * - Renders children inside a `<form>` whose `action`/`method` already point at
+ *   the server's submit target (and which carries the `pending_auth_id` + `csrf`
+ *   hidden fields), so a no-JS submit still works.
+ *
+ * CSP, anti-clickjacking headers, and minting the CSRF token are the SERVER's
+ * responsibility at SSR time (stage 2). The wrapper only consumes the injected
+ * `csrfToken` and posts it back correctly.
+ *
+ * @packageDocumentation
+ */
+import { type ReactElement, type ReactNode } from 'react';
+import { type AuthFlowState } from './contract';
+/**
+ * Props for {@link AuthPageWrapper}.
+ */
+export interface AuthPageWrapperProps {
+    /** The developer's auth UI. */
+    children: ReactNode;
+    /**
+     * Override the flow state instead of reading the injected global. Primarily
+     * for tests and storybook; production pages omit this and let the server
+     * injection drive the wrapper.
+     */
+    state?: AuthFlowState;
+    /**
+     * When false, render children WITHOUT an enclosing `<form>` (the developer
+     * supplies their own forms and drives submits via the hooks). Defaults to
+     * true so a no-JS finish submit works out of the box.
+     */
+    renderForm?: boolean;
+    /** Extra class name applied to the wrapper element. */
+    className?: string;
+}
+/**
+ * Standalone provider (no chrome) — useful when the developer wants full
+ * control of layout but still needs the hooks. {@link AuthPageWrapper} builds
+ * on this.
+ */
+export declare function AuthFlowProvider({ children, state: stateOverride, }: {
+    children: ReactNode;
+    state?: AuthFlowState;
+}): ReactElement;
+/**
+ * The outer chrome. By default wraps children in a `<form>` that posts to the
+ * server's submit target with the control fields pre-populated.
+ */
+export declare function AuthPageWrapper({ children, state: stateOverride, renderForm, className, }: AuthPageWrapperProps): ReactElement;
+//# sourceMappingURL=AuthPageWrapper.d.ts.map

package/auth/AuthPageWrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AuthPageWrapper.d.ts","sourceRoot":"","sources":["../../src/auth/AuthPageWrapper.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAiC,KAAK,YAAY,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAGzF,OAAO,EAAoE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAGlH;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,+BAA+B;IAC/B,QAAQ,EAAE,SAAS,CAAC;IACpB;;;;OAIG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,QAAQ,EACR,KAAK,EAAE,aAAa,GACrB,EAAE;IACD,QAAQ,EAAE,SAAS,CAAC;IACpB,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB,GAAG,YAAY,CAef;AAoBD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,EAC9B,QAAQ,EACR,KAAK,EAAE,aAAa,EACpB,UAAiB,EACjB,SAAS,GACV,EAAE,oBAAoB,GAAG,YAAY,CAQrC"}

package/auth/context.d.ts

@@ -0,0 +1,23 @@
+import type { AuthFlowState } from './contract';
+/**
+ * The value provided by {@link AuthPageWrapper} / {@link AuthFlowProvider}.
+ */
+export interface AuthFlowContextValue {
+    /** The current flow state (injected by the server, mutated client-side on extra success). */
+    state: AuthFlowState;
+    /**
+     * Merge a partial update into the in-memory flow state (e.g. refreshed
+     * `addedItems` returned by a `submitExtra`). Does not touch the server.
+     */
+    update: (patch: Partial<AuthFlowState>) => void;
+}
+/**
+ * Context handle. `null` outside a provider so hooks can throw a clear error.
+ */
+export declare const AuthFlowContext: import("react").Context<AuthFlowContextValue | null>;
+/**
+ * Internal accessor used by the hooks; throws when used outside
+ * {@link AuthPageWrapper} / {@link AuthFlowProvider}.
+ */
+export declare function useAuthFlowContext(): AuthFlowContextValue;
+//# sourceMappingURL=context.d.ts.map

package/auth/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/auth/context.tsx"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,6FAA6F;IAC7F,KAAK,EAAE,aAAa,CAAC;IACrB;;;OAGG;IACH,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,aAAa,CAAC,KAAK,IAAI,CAAC;CACjD;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,sDAAmD,CAAC;AAEhF;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,oBAAoB,CAMzD"}

package/auth/contract.d.ts

@@ -0,0 +1,276 @@
+/**
+ * Framework-free Auth-UI contract (no React).
+ *
+ * This module is the SINGLE SOURCE OF TRUTH for the CLIENT side of the bridge
+ * between a FrontMCP authorization page (a thin server shell) and the client
+ * code that renders + drives it. It is the canonical client API, so it lives in
+ * `@frontmcp/ui/auth` (this package) co-located with the vanilla helpers + React
+ * hooks/mount that consume it. It has ZERO React dependency on purpose so the
+ * vanilla helpers (and a non-React page) can use it directly.
+ *
+ * The SERVER side (`@frontmcp/sdk`'s `auth-ui` module) does NOT import this
+ * file — it owns its own minimal write-shape types + the two runtime protocol
+ * constants as local literals, kept in sync with the values declared here. That
+ * JSON-serialization boundary (server-owned write-shape, client-owned
+ * read-shape) is intentional and deliberately avoids an `sdk → ui` dependency;
+ * the local-auth e2e asserts the `window.__FRONTMCP_AUTH__` wire shape to guard
+ * against drift.
+ *
+ * ## How the bridge works
+ *
+ * 1. When serving the shell the server serializes an {@link AuthFlowState} into
+ *    a `<script>` that assigns it to the global named by
+ *    {@link AUTH_FLOW_GLOBAL_KEY} (`window.__FRONTMCP_AUTH__`). This mirrors the
+ *    `window.__mcp*` / `window.FrontMcpBridge` injection pattern used by
+ *    `@frontmcp/uipack` and `@frontmcp/ui` for tool widgets.
+ * 2. The client bundle (the developer's `@AuthUi` component, client-rendered via
+ *    `mountAuthPage` from `@frontmcp/ui/auth`) reads that global through
+ *    `getAuthFlow()` and drives the OAuth flow with `submitFinish` /
+ *    `submitExtra`.
+ *
+ * The server owns CSP, anti-clickjacking headers, and minting the
+ * {@link AuthFlowState.csrfToken}; the client only consumes the token and posts
+ * it back. No PII is part of the required contract — identity values the user
+ * types are carried by the developer's own form fields, not by this state.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Which built-in authorization page slot a component renders.
+ *
+ * Mirrors the server-side `@AuthUi({ slot })` slots from issue #469 and the
+ * existing in-tree pages produced by the OAuth authorize/callback flows:
+ *
+ * - `login`       — the local sign-in page (`renderLocalLoginPage`).
+ * - `consent`     — the tool-consent screen (`buildToolConsentPage`).
+ * - `incremental` — single-app incremental authorization (`buildIncrementalAuthPage`).
+ * - `federated`   — multi-provider selection (`buildFederatedLoginPage`).
+ * - `error`       — the OAuth error page.
+ */
+export type AuthSlot = 'login' | 'consent' | 'incremental' | 'federated' | 'error';
+/**
+ * The HTTP method the auth submit/extra requests use.
+ *
+ * The in-tree pages today POST the consent app-cards but GET the login,
+ * federated, consent, and incremental forms back to `/oauth/callback` (a GET
+ * round-trip mirroring the federated page). The contract carries the method so
+ * stage 2 can pick per-slot without the client hardcoding it; it defaults to
+ * `GET` to match the current callback flow.
+ */
+export type AuthSubmitMethod = 'GET' | 'POST';
+/**
+ * A selectable authentication provider surfaced on the federated-login slot.
+ *
+ * Derived from the `ProviderCard` the authorize flow builds for
+ * `buildFederatedLoginPage`. Only display + selection fields are exposed to the
+ * client; nothing secret (client secrets, provider tokens) is ever included.
+ */
+export interface AuthProvider {
+    /** Stable provider id submitted back as a `providers` value. */
+    id: string;
+    /** Human-readable provider name for display. */
+    name: string;
+    /** Optional provider authorize URL (transparent/remote providers only). */
+    url?: string;
+    /** Auth mode label (e.g. `local`, `transparent`, `remote`). */
+    mode?: string;
+    /** App ids associated with this provider (filtered of internal sentinels). */
+    appIds?: string[];
+    /** Whether this is the primary/parent provider (pre-checked by default). */
+    primary?: boolean;
+}
+/**
+ * A selectable tool surfaced on the consent slot.
+ *
+ * Derived from the `ToolCard` the callback flow builds for
+ * `buildToolConsentPage`. The `id` is the effective runtime tool id submitted
+ * back as a `tools` value and enforced at call time.
+ */
+export interface AuthTool {
+    /** Effective runtime tool id (submitted back as a `tools` value). */
+    id: string;
+    /** Display name. */
+    name: string;
+    /** Optional description. */
+    description?: string;
+    /** Owning app id (for grouping). */
+    appId?: string;
+    /** Owning app display name (for grouping). */
+    appName?: string;
+    /** Whether the tool is pre-selected. */
+    defaultSelected?: boolean;
+}
+/**
+ * The serialized authorization-flow state the server injects and the client
+ * reads. Field names map to what `oauth.authorize.flow.ts` /
+ * `oauth.callback.flow.ts` already compute for the built-in pages, so stage 2
+ * can populate this from existing flow state without new plumbing.
+ *
+ * NO PII is part of the contract. `clientName`/`clientId` are OAuth client
+ * identifiers (not end-user identity), and identity values the user enters are
+ * carried by the developer's own form fields — never serialized here.
+ */
+export interface AuthFlowState {
+    /** Which page slot this state is for. */
+    slot: AuthSlot;
+    /**
+     * The pending authorization id (`pending_auth_id`). Round-tripped on every
+     * submit/extra request so the server can correlate the flow. Optional only
+     * for the `error` slot, which may render before a pending record exists.
+     */
+    pendingAuthId?: string;
+    /** OAuth client display name (CIMD `client_name` or the raw client id). */
+    clientName?: string;
+    /** OAuth `client_id`. */
+    clientId?: string;
+    /** Requested OAuth scopes (split from the `scope` param). */
+    scopes?: string[];
+    /** Validated OAuth `redirect_uri` (where the server sends the code). */
+    redirectUri?: string;
+    /** RFC 8707 `resource` indicator, when supplied. */
+    resource?: string;
+    /** Human-readable error text for the `error` slot (or a failed submit re-render). */
+    error?: string;
+    /**
+     * Anti-CSRF token the server minted at SSR time. The client posts it back in
+     * the `csrf` field on every submit/extra. Minting + verifying it is the
+     * SERVER's responsibility (stage 2); the client only echoes it.
+     */
+    csrfToken?: string;
+    /**
+     * Absolute or app-relative URL the finish submit posts to. The in-tree pages
+     * use `${scope.fullPath}/oauth/callback`. Required for any interactive slot.
+     */
+    submitUrl?: string;
+    /**
+     * HTTP method for the finish submit. Defaults to {@link DEFAULT_SUBMIT_METHOD}
+     * (`GET`) to match the current callback round-trip.
+     */
+    submitMethod?: AuthSubmitMethod;
+    /**
+     * Optional dedicated URL for `submitExtra` (the `@AuthExtra` validated-field
+     * endpoint, issue #469). When omitted, extras post to {@link submitUrl} with
+     * an {@link AUTH_EXTRA_FIELD action} field naming the extra. Stage 2 may
+     * expose a separate endpoint and set this.
+     */
+    extraUrl?: string;
+    /** Providers offered on the `federated` slot. */
+    providers?: AuthProvider[];
+    /** Tools offered on the `consent` slot. */
+    tools?: AuthTool[];
+    /**
+     * Server-side accumulators for multi-step inputs, keyed by extra name. Each
+     * value is the list of items the server has accepted so far (e.g. the
+     * `envs` a user added). Read by `getAddedItems(name)` / `useAddedItems(name)`.
+     * The server replaces this on each re-render / extra response.
+     */
+    addedItems?: Record<string, unknown[]>;
+    /**
+     * Free-form, slot-specific extras the server wants to pass to the component
+     * (e.g. logo URI, custom messages, incremental target app). Kept open so
+     * stage 2 can extend per-slot without a contract change.
+     */
+    extras?: Record<string, unknown>;
+}
+/**
+ * The global property name the server injects the {@link AuthFlowState} under.
+ *
+ * Analogous to `window.FrontMcpBridge` (the tool-widget bridge) but for auth:
+ * `window.__FRONTMCP_AUTH__: AuthFlowState`. The double-underscore form matches
+ * the `window.__mcp*` data-injection convention in `@frontmcp/uipack`.
+ *
+ * The server declares this same literal locally (`@frontmcp/sdk`'s `auth-ui`
+ * module) — keep the two in sync.
+ */
+export declare const AUTH_FLOW_GLOBAL_KEY: "__FRONTMCP_AUTH__";
+/**
+ * Default HTTP method for the finish submit when the state omits one. `GET`
+ * matches the current `/oauth/callback` round-trip used by the in-tree login,
+ * consent, federated, and incremental pages.
+ */
+export declare const DEFAULT_SUBMIT_METHOD: AuthSubmitMethod;
+/**
+ * Canonical wire field names shared by the server flows and the client helpers.
+ *
+ * These mirror the exact params the OAuth callback flow reads today
+ * (`oauth.callback.flow.ts`), so the client posts what the server already
+ * understands and stage 2 does not have to invent a new vocabulary.
+ */
+export declare const AUTH_WIRE_FIELDS: {
+    /** Pending authorization id. */
+    readonly pendingAuthId: "pending_auth_id";
+    /** Anti-CSRF token. */
+    readonly csrf: "csrf";
+    /** Marks a consent-form submission (distinguishes empty-select from first visit). */
+    readonly consentSubmitted: "consent_submitted";
+    /** Repeated checkbox field carrying selected tool ids on the consent slot. */
+    readonly tools: "tools";
+    /** Marks a federated submission. */
+    readonly federated: "federated";
+    /** Repeated checkbox field carrying selected provider ids on the federated slot. */
+    readonly providers: "providers";
+    /** Marks an incremental authorization. */
+    readonly incremental: "incremental";
+    /** Target app id for incremental authorization. */
+    readonly appId: "app_id";
+    /** Generic action discriminator (e.g. consent `authorize`/`skip`, or an extra name). */
+    readonly action: "action";
+};
+/**
+ * The value placed in the {@link AUTH_WIRE_FIELDS.consentSubmitted} field to
+ * mark a consent submission (the callback flow checks for the literal `'1'`).
+ */
+export declare const CONSENT_SUBMITTED_VALUE: "1";
+/**
+ * The value placed in the {@link AUTH_WIRE_FIELDS.federated} /
+ * {@link AUTH_WIRE_FIELDS.incremental} markers (the callback flow checks for
+ * the literal `'true'`).
+ */
+export declare const WIRE_TRUE: "true";
+/**
+ * The field name used to carry the extra/action name when `submitExtra` posts
+ * to the shared {@link AuthFlowState.submitUrl} (no dedicated `extraUrl`). The
+ * server's `@AuthExtra(name)` handler reads this to route the validated field.
+ */
+export declare const AUTH_EXTRA_FIELD: "action";
+/**
+ * Default mount id the server SSRs the auth component into (and the client
+ * hydrates onto). The server declares this same literal locally (`@frontmcp/sdk`'s
+ * `auth-ui` module) — keep the two in sync.
+ */
+export declare const DEFAULT_AUTH_MOUNT_ID = "frontmcp-auth-root";
+/**
+ * Result of a `submitExtra` call (a validated `@AuthExtra` field round-trip).
+ *
+ * Mirrors the server-side `@AuthExtra(name)` return shape from issue #469
+ * (`{ ok, error?, sideEffects? }`). `addedItems` lets a successful extra hand
+ * back the updated accumulator so the client can refresh without a full reload.
+ */
+export interface AuthExtraResult {
+    /** Whether the server accepted the field. */
+    ok: boolean;
+    /** Human-readable validation error when `ok` is false. */
+    error?: string;
+    /** Updated server-side accumulators (keyed by extra name) after a successful add. */
+    addedItems?: Record<string, unknown[]>;
+    /** Free-form side-effect data the server chooses to return. */
+    sideEffects?: Record<string, unknown>;
+}
+/**
+ * Form data accepted by `submitFinish` / `submitExtra`. Either a real
+ * `FormData`, a plain record, or a form `EventTarget` (so a React/DOM
+ * `onSubmit` handler can pass `event.currentTarget` directly).
+ */
+export type AuthFormInput = FormData | Record<string, unknown> | HTMLFormElement;
+/**
+ * Augment the global object so `window.__FRONTMCP_AUTH__` is typed wherever the
+ * contract is in scope. Declared on both `Window` and `globalThis` so it works
+ * in the browser and under jsdom/node test environments.
+ */
+declare global {
+    interface Window {
+        [AUTH_FLOW_GLOBAL_KEY]?: AuthFlowState;
+    }
+    var __FRONTMCP_AUTH__: AuthFlowState | undefined;
+}
+//# sourceMappingURL=contract.d.ts.map

package/auth/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/auth/contract.ts"],"names":[],"mappings":"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"}

package/auth/hooks.d.ts

@@ -0,0 +1,83 @@
+/**
+ * React hooks for FrontMCP `@AuthUi` components, built on the framework-free
+ * vanilla core. They read the injected {@link AuthFlowState} via context (set
+ * up by {@link AuthPageWrapper}) and expose typed accessors + submit handlers.
+ *
+ * @packageDocumentation
+ */
+import { type FormEvent } from 'react';
+import type { AuthExtraResult, AuthFlowState, AuthFormInput, AuthProvider, AuthSlot, AuthTool } from './contract';
+/**
+ * The shape returned by {@link useAuthFlow}: the injected state fields plus the
+ * `submitFinish` handler. `submitFinish` accepts a React form event or explicit
+ * data, so `<form onSubmit={submitFinish}>` works directly.
+ */
+export interface UseAuthFlowResult {
+    /** Which page slot is being rendered. */
+    slot: AuthSlot;
+    /** Pending authorization id. */
+    pendingAuthId?: string;
+    /** OAuth client display name. */
+    clientName?: string;
+    /** OAuth client id. */
+    clientId?: string;
+    /** Requested scopes. */
+    scopes: string[];
+    /** Validated redirect URI. */
+    redirectUri?: string;
+    /** RFC 8707 resource indicator. */
+    resource?: string;
+    /** Error text (error slot or a failed-submit re-render). */
+    error?: string;
+    /** Providers offered on the federated slot. */
+    providers: AuthProvider[];
+    /** Tools offered on the consent slot. */
+    tools: AuthTool[];
+    /** Free-form slot extras the server passed through. */
+    extras: Record<string, unknown>;
+    /** The full raw state (escape hatch). */
+    state: AuthFlowState;
+    /**
+     * Finish the flow. Pass nothing to submit the enclosing wrapper form, a React
+     * `FormEvent` (it will `preventDefault` and serialize `event.currentTarget`),
+     * or explicit form data.
+     */
+    submitFinish: (formOrEvent?: FormEvent<HTMLFormElement> | AuthFormInput) => Promise<Response>;
+}
+/**
+ * Primary auth hook: returns the injected flow state plus a `submitFinish`
+ * handler. Everything OAuth (pending id, csrf, submit target, slot markers) is
+ * already wired by the vanilla core — the developer only renders UI.
+ */
+export declare function useAuthFlow(): UseAuthFlowResult;
+/**
+ * Return the server-side accumulator for a named multi-step input, reactively.
+ * Reads from context so it re-renders when {@link AuthPageWrapper} updates the
+ * state after a successful {@link useExtraField} submit.
+ */
+export declare function useAddedItems<T = unknown>(name: string): T[];
+/**
+ * The handle returned by {@link useExtraField}: an `onSubmit` you bind to a
+ * `<form>`, plus the last result and a pending flag.
+ */
+export interface UseExtraFieldResult {
+    /**
+     * Form submit handler. Calls `submitExtra(name, ...)`, surfaces the
+     * `{ ok, error }` result, and merges any returned `addedItems` back into the
+     * flow state so {@link useAddedItems} updates.
+     */
+    onSubmit: (formOrEvent?: FormEvent<HTMLFormElement> | AuthFormInput) => Promise<AuthExtraResult>;
+    /** The most recent result (`undefined` until the first submit). */
+    result?: AuthExtraResult;
+    /** Whether a submit is in flight. */
+    pending: boolean;
+}
+/**
+ * Declare a custom validated field (a `@AuthExtra(name)` round-trip). Returns
+ * an `onSubmit` handler for the field's form; on success it refreshes the
+ * matching `addedItems` accumulator in context.
+ *
+ * @param name The extra's name (must match the server's `@AuthExtra(name)`).
+ */
+export declare function useExtraField(name: string): UseExtraFieldResult;
+//# sourceMappingURL=hooks.d.ts.map

package/auth/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/auth/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAyB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAG9D,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGlH;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,yCAAyC;IACzC,IAAI,EAAE,QAAQ,CAAC;IACf,gCAAgC;IAChC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iCAAiC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uBAAuB;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wBAAwB;IACxB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,8BAA8B;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mCAAmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,yCAAyC;IACzC,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,yCAAyC;IACzC,KAAK,EAAE,aAAa,CAAC;IACrB;;;;OAIG;IACH,YAAY,EAAE,CAAC,WAAW,CAAC,EAAE,SAAS,CAAC,eAAe,CAAC,GAAG,aAAa,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC/F;AAgBD;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,iBAAiB,CAwB/C;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,EAAE,CAI5D;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,QAAQ,EAAE,CAAC,WAAW,CAAC,EAAE,SAAS,CAAC,eAAe,CAAC,GAAG,aAAa,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;IACjG,mEAAmE;IACnE,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,qCAAqC;IACrC,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,CAgC/D"}

package/auth/hydrate.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Client mount entry for a FrontMCP auth page.
+ *
+ * The server serves a thin HTML shell with an EMPTY `#frontmcp-auth-root` mount
+ * node, the injected {@link AuthFlowState} global, and a bundle that calls
+ * {@link mountAuthPage} to render the developer's `@AuthUi` component into that
+ * node in the BROWSER (pure client render — no server-side React, no
+ * hydration). The component is wrapped in {@link AuthPageWrapper} so the
+ * `useAuthFlow*` hooks have their context, and the injected state is read
+ * automatically.
+ *
+ * @packageDocumentation
+ */
+import { type ComponentType } from 'react';
+import { type Root } from 'react-dom/client';
+import { type AuthFlowState } from './contract';
+/** Re-export the framework-free mount id (single source of truth in `./contract`). */
+export { DEFAULT_AUTH_MOUNT_ID } from './contract';
+/**
+ * Options for {@link mountAuthPage}.
+ */
+export interface MountAuthPageOptions {
+    /**
+     * The container to render into. Accepts an element or a selector; defaults to
+     * `#frontmcp-auth-root` (the empty mount node the server shell ships).
+     */
+    container?: Element | string;
+    /**
+     * Override the flow state instead of reading the injected global (tests /
+     * preview). Production omits this.
+     */
+    state?: AuthFlowState;
+    /**
+     * Whether the wrapper renders its enclosing `<form>`. Mirrors
+     * {@link AuthPageWrapper}'s `renderForm` (default true).
+     */
+    renderForm?: boolean;
+}
+/**
+ * Render `Component` (a developer `@AuthUi` page) into the (empty) mount node in
+ * the browser, wrapping it in {@link AuthPageWrapper}. This is a PURE client
+ * render via `createRoot(...).render(...)` — the server ships no component
+ * markup, so there is nothing to hydrate.
+ *
+ * @param Component The page component to render.
+ * @param options   Container / state / form overrides.
+ * @returns The React {@link Root} (so callers can `unmount()` in tests).
+ */
+export declare function mountAuthPage(Component: ComponentType, options?: MountAuthPageOptions): Root;
+//# sourceMappingURL=hydrate.d.ts.map

package/auth/hydrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydrate.d.ts","sourceRoot":"","sources":["../../src/auth/hydrate.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,OAAO,CAAC;AAC3C,OAAO,EAAc,KAAK,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAGzD,OAAO,EAAyB,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAEvE,sFAAsF;AACtF,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAEnD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC7B;;;OAGG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAkBD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,aAAa,EAAE,OAAO,GAAE,oBAAyB,GAAG,IAAI,CAShG"}

package/auth/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `@frontmcp/ui/auth` — client-side primitives for FrontMCP custom
+ * authorization UIs (issue #469): the framework-free contract (no React) plus
+ * React hooks + chrome built on the framework-free vanilla core.
+ *
+ * This subpath is the SINGLE SOURCE OF TRUTH for the client-side auth contract
+ * (`AuthFlowState`, `AuthSlot`, the wire constants, …). It imports ONLY `react`
+ * / `react-dom` (peer) — NEVER `@mui/material` / `@emotion` — so the auth page
+ * loads a lean module from esm.sh.
+ *
+ * Entry points:
+ * - `@frontmcp/ui/auth`          — contract + vanilla helpers + React hooks/wrapper/mount.
+ * - `@frontmcp/ui/auth/vanilla`  — framework-free flow helpers (`getAuthFlow`, `submitFinish`, `submitExtra`, `getAddedItems`).
+ *
+ * @packageDocumentation
+ */
+export * from './contract';
+export { getAddedItems, getAuthFlow, setAuthNavigator, submitExtra, submitFinish, tryGetAuthFlow, type AuthNavigator, type SubmitFinishOptions, } from './vanilla/auth-flow';
+export { AuthFlowContext, type AuthFlowContextValue } from './context';
+export { AuthFlowProvider, AuthPageWrapper, type AuthPageWrapperProps } from './AuthPageWrapper';
+export { useAddedItems, useAuthFlow, useExtraField, type UseAuthFlowResult, type UseExtraFieldResult } from './hooks';
+export { DEFAULT_AUTH_MOUNT_ID, mountAuthPage, type MountAuthPageOptions } from './hydrate';
+//# sourceMappingURL=index.d.ts.map

package/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,cAAc,YAAY,CAAC;AAG3B,OAAO,EACL,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,cAAc,EACd,KAAK,aAAa,EAClB,KAAK,mBAAmB,GACzB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,eAAe,EAAE,KAAK,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACvE,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,KAAK,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACjG,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,KAAK,iBAAiB,EAAE,KAAK,mBAAmB,EAAE,MAAM,SAAS,CAAC;AACtH,OAAO,EAAE,qBAAqB,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,WAAW,CAAC"}