@secmia/openui-flow 4.0.1 → 4.2.0

package/AGENTS.md

@@ -30,14 +30,23 @@ Core evaluation APIs:
 - createRequirementGraph(...)
 - createDefaultRequirementGraph(...)
 
+Graph safety guarantees:
+
+- Dependency-aware topological ordering
+- Deterministic tie-breaking for equal priority nodes
+- Cycle and invalid dependency detection at graph creation
+
 ## Public API Surface (Current)
 
 Primary component and types:
 
 - AdaptiveFlow
+- useAdaptiveFlow
 - AdaptiveFlowProps
 - AdaptiveFlowAdapter
 - AdaptiveFlowValidators
+- AdaptiveFlowSchemas
+- AdaptiveFlowFieldErrors
 - AdaptiveFlowPersistence
 - AdaptiveFlowStyles
 - AdaptiveFlowClassNames
@@ -67,6 +76,7 @@ Level 1: style/class slot overrides
 
 - Use styles and classNames
 - Use unstyled to disable built-in inline style defaults
+- Configure default OAuth button list with oauthProviders
 
 Level 2: per-step custom rendering
 
@@ -111,12 +121,26 @@ Persistence:
 - Configure via persistence prop
 - Supports session, local, or custom storage driver
 - Use versioned keys (example: flow-state:v1)
+- Use persistence.onError to capture read/write/clear failures
+
+Retry policy:
+
+- Configure via retryPolicy prop
+- Supports maxAttempts, initialDelayMs, factor, maxDelayMs, jitter, delay, and shouldRetry
+- Adapter calls use retryPolicy backoff; validation errors are not retried unless explicitly allowed
+
+Context patching:
+
+- mergeContext now recursively merges plain nested objects
+- Arrays are replaced, not merged
 
 Validation:
 
 - Configure via validators prop
 - Supports email, otp, password, profile, tos validators
 - Validators may be sync or async
+- Validators can return string or { field, message } for field-level error mapping
+- Optional schemas prop supports schema objects with safeParse/parse (Zod-friendly)
 
 ## Recommended Agent Workflow
 

package/README.md

@@ -422,6 +422,18 @@ Keep built-in UI structure, but override styles/classes for all slots.
 />
 ```
 
+Configure OAuth button list in default footer:
+
+```tsx
+<AdaptiveFlow
+  oauthProviders={[
+    { id: 'google', label: 'Continue with Google' },
+    { id: 'github', label: 'Continue with GitHub' },
+    { id: 'microsoft', label: 'Continue with Microsoft' },
+  ]}
+/>
+```
+
 Use `unstyled` to disable built-in inline defaults.
 
 ```tsx
@@ -462,6 +474,14 @@ Use `stepRegistry` to replace selected steps with your own components while leav
 />
 ```
 
+`run(job)` semantics in custom renderers:
+- sets `busy=true` during the async job
+- clears previous global/field errors before execution
+- catches and normalizes thrown errors into flow error state
+- reverts `busy=false` on completion
+
+Use it for custom step actions to keep consistent loading/error behavior.
+
 ### Level 3: custom renderer for all steps
 
 Use `renderStep` for full step-body ownership. You can still reuse `defaultView` when useful.
@@ -489,7 +509,97 @@ Use `renderStep` for full step-body ownership. You can still reuse `defaultView`
 
 ### Level 4: fully custom UI for everything (headless mode)
 
-If you want total control over shell, header, footer, button layout, and every interaction, use engine APIs directly.
+If you want total control over shell, header, footer, button layout, and every interaction, use `useAdaptiveFlow` (or engine APIs directly).
+
+### Headless hook (`useAdaptiveFlow`)
+
+`useAdaptiveFlow` exposes the flow lifecycle without rendering any UI.
+
+```tsx
+'use client';
+
+import { useAdaptiveFlow, type AdaptiveContextBase } from '@secmia/openui-flow';
+
+type Ctx = AdaptiveContextBase & {
+  selectedPlan: 'starter' | 'pro' | null;
+};
+
+export default function FullyCustomFlow() {
+  const {
+    step,
+    context,
+    missingRequirements,
+    busy,
+    fieldErrors,
+    handleEmail,
+    handleOtp,
+    handlePassword,
+    handleProfile,
+    handleTos,
+    setContextPatch,
+  } = useAdaptiveFlow<Ctx>({
+    requirements: ['has_email', 'email_verified', 'has_password', 'has_first_name', 'accepted_tos', 'selected_plan'],
+    completeStep: 'COMPLETE',
+    initialValue: { selectedPlan: null },
+  });
+
+  return (
+    <div>
+      <h2>Step: {step}</h2>
+      <p>Pending: {missingRequirements.length}</p>
+      {fieldErrors.email ? <p>{fieldErrors.email}</p> : null}
+
+      <button disabled={busy} onClick={() => handleEmail('user@company.com')}>Submit Email</button>
+      <button disabled={busy} onClick={() => handleOtp('123456')}>Submit OTP</button>
+      <button disabled={busy} onClick={() => handlePassword('secure-password')}>Submit Password</button>
+      <button disabled={busy} onClick={() => handleProfile({ firstName: 'A', lastName: 'B', jobTitle: null })}>Save Profile</button>
+      <button disabled={busy} onClick={() => handleTos()}>Accept TOS</button>
+      <button onClick={() => setContextPatch({ selectedPlan: 'pro' })}>Select Plan</button>
+      <pre>{JSON.stringify(context, null, 2)}</pre>
+    </div>
+  );
+}
+```
+
+You can still bypass the hook and use pure engine APIs if you need lower-level control.
+
+### Optional schema validation (Zod-friendly)
+
+`AdaptiveFlow` and `useAdaptiveFlow` accept a `schemas` object. Any schema with `safeParse` or `parse` is supported (including Zod schemas).
+
+```tsx
+import { z } from 'zod';
+
+const emailSchema = z.string().email();
+const profileSchema = z.object({
+  firstName: z.string().min(1),
+  lastName: z.string().min(1),
+  jobTitle: z.string().nullable(),
+});
+
+<AdaptiveFlow
+  schemas={{
+    email: emailSchema,
+    profile: profileSchema,
+  }}
+/>
+```
+
+### Field-level validation errors
+
+Validators can return either a string or `{ field, message }`.
+
+```ts
+const validators = {
+  password: (value: string) => {
+    if (value.length < 12) {
+      return { field: 'password', message: 'Password must be at least 12 characters.' };
+    }
+  },
+};
+```
+
+Default UI now binds field errors to the matching input and sets `aria-invalid` automatically.
 
 ```tsx
 'use client';
@@ -735,6 +845,11 @@ const missing = await getMissingRequirements(context, graph);
 - Step: current UI state for unmet requirement.
 - RequirementGraph: graph nodes with optional priority, condition, and dependency metadata.
 
+Graph behavior:
+- Dependency-aware ordering uses topological sorting.
+- Priority is used as tie-breaker among currently available nodes.
+- Circular dependencies and unknown dependencies are rejected during graph creation.
+
 Evaluation loop:
 1. Build graph.
 2. Evaluate active nodes.
@@ -749,6 +864,7 @@ Evaluation loop:
 
 Primary exports:
 - `AdaptiveFlow`
+- `useAdaptiveFlow`
 - `defaultRequirements`
 - `initialContext`
 - `defaultRequirementResolvers`
@@ -762,8 +878,16 @@ Primary exports:
 Important types:
 - `AdaptiveFlowProps`
 - `AdaptiveFlowAdapter`
+- `UseAdaptiveFlowOptions`
+- `UseAdaptiveFlowResult`
 - `AdaptiveFlowValidators`
+- `AdaptiveFlowValidationResult`
+- `AdaptiveFlowValidationIssue`
+- `AdaptiveFlowFieldErrors`
+- `AdaptiveFlowSchemas`
+- `AdaptiveFlowSchema`
 - `AdaptiveFlowPersistence`
+- `AdaptiveFlowOAuthProvider`
 - `AdaptiveStepRegistry`
 - `AdaptiveStepRendererArgs`
 - `AdaptiveStepRenderArgs`
@@ -776,6 +900,49 @@ Important types:
 
 ---
 
+## SSR and hydration notes
+
+- Storage persistence only runs in the browser (`window` guard).
+- On SSR, the flow starts from `initialValue`/defaults and then hydrates persisted browser state on mount.
+- For App Router and other SSR setups, pass server-known session hints in `initialValue` to minimize client-side step flash.
+
+Example:
+
+```tsx
+<AdaptiveFlow
+  initialValue={{
+    email: user.email ?? null,
+    isVerified: Boolean(user.emailVerifiedAt),
+    hasPassword: Boolean(user.hasPassword),
+  }}
+  persistence={{ key: 'flow-state:v1', storage: 'session' }}
+/>
+```
+
+### Retry policy
+
+Use `retryPolicy` to retry transient adapter failures with configurable backoff.
+
+```tsx
+<AdaptiveFlow
+  retryPolicy={{
+    maxAttempts: 4,
+    initialDelayMs: 200,
+    factor: 2,
+    maxDelayMs: 2000,
+    jitter: true,
+    shouldRetry: (error) => error.name !== 'FlowValidationError',
+  }}
+/>
+```
+
+Default behavior:
+- adapter calls are retried with exponential backoff
+- non-adapter validation errors are not retried unless `shouldRetry` allows them
+- retries use the browser/Node timer API, so no extra dependency is required
+
+---
+
 ## Release checklist
 
 - Ensure adapter methods return clear, user-safe errors.
@@ -801,6 +968,26 @@ OAuth return does not resume:
 - Cause: missing `completeOAuth` or persistence disabled.
 - Fix: implement `completeOAuth` and enable persistence.
 
+Persistence write/read failures:
+- Cause: storage quota, blocked storage, malformed persisted payload.
+- Fix: pass `persistence.onError` to capture and report storage failures.
+
+Custom nested context fields collapsing after patch:
+- Cause: patching with a shallow object update.
+- Fix: the flow now performs a recursive object merge for plain nested objects. Arrays are replaced, not merged.
+
+```tsx
+<AdaptiveFlow
+  persistence={{
+    key: 'flow-state:v1',
+    storage: 'local',
+    onError: (error, phase) => {
+      console.error('persistence failure', phase, error);
+    },
+  }}
+/>
+```
+
 ---
 
 ## License

package/dist/index.d.mts

@@ -1,6 +1,9 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React from 'react';
 
+/**
+ * Built-in requirement keys that cover the default flow states supported by the package.
+ */
 declare const DefaultAppRequirements: {
     readonly HAS_EMAIL: "has_email";
     readonly EMAIL_VERIFIED: "email_verified";
@@ -10,6 +13,9 @@ declare const DefaultAppRequirements: {
     readonly ACCEPTED_TOS: "accepted_tos";
     readonly HAS_JOB_TITLE: "has_job_title";
 };
+/**
+ * Built-in step keys used by the default flow UI and default requirement resolvers.
+ */
 declare const DefaultAdaptiveSteps: {
     readonly COLLECT_EMAIL: "COLLECT_EMAIL";
     readonly VERIFY_OTP: "VERIFY_OTP";
@@ -18,10 +24,15 @@ declare const DefaultAdaptiveSteps: {
     readonly COLLECT_TOS: "COLLECT_TOS";
     readonly COMPLETE: "COMPLETE";
 };
+/** Requirement key from the built-in default requirement set. */
 type DefaultAppRequirement = (typeof DefaultAppRequirements)[keyof typeof DefaultAppRequirements];
+/** Step key from the built-in default step set. */
 type DefaultAdaptiveStep = (typeof DefaultAdaptiveSteps)[keyof typeof DefaultAdaptiveSteps];
+/** Requirement key used by the engine, including custom app-specific requirements. */
 type AppRequirement = DefaultAppRequirement | (string & {});
+/** Step key used by the engine, including custom app-specific steps. */
 type AdaptiveStep = DefaultAdaptiveStep | (string & {});
+/** Base context shape managed by the default flow helpers and UI. */
 type AdaptiveContextBase = {
     email: string | null;
     isVerified: boolean;
@@ -33,14 +44,23 @@ type AdaptiveContextBase = {
     };
     agreedToTos: boolean;
 };
+/** Alias for the default context shape used by the built-in component and hook. */
 type AdaptiveContext = AdaptiveContextBase;
+/** Default set of requirements used when a flow does not provide its own list. */
 declare const defaultRequirements: DefaultAppRequirement[];
+/** Default initial context used by the component and hook when no initialValue is provided. */
 declare const initialContext: AdaptiveContextBase;
+/** Utility type for APIs that may return either a synchronous or asynchronous value. */
 type MaybePromise<T> = T | Promise<T>;
+/** Resolver contract that maps one requirement to the step shown when it is unmet. */
 type RequirementResolver<TContext = AdaptiveContextBase, TStep extends string = AdaptiveStep> = {
     isMet: (context: TContext) => MaybePromise<boolean>;
     step: TStep;
 };
+/**
+ * Single requirement node in the requirement graph.
+ * The engine evaluates nodes by priority, dependency readiness, and custom conditions.
+ */
 type RequirementGraphNode<TContext, TRequirement extends string, TStep extends string> = {
     requirement: TRequirement;
     step: TStep;
@@ -49,13 +69,24 @@ type RequirementGraphNode<TContext, TRequirement extends string, TStep extends s
     priority?: number;
     dependsOn?: readonly TRequirement[];
 };
+/** Ordered requirement graph consumed by the engine evaluation helpers. */
 type RequirementGraph<TContext, TRequirement extends string, TStep extends string> = readonly RequirementGraphNode<TContext, TRequirement, TStep>[];
+/** Default requirement-to-step resolvers used by the built-in flow UI. */
 declare const defaultRequirementResolvers: Record<DefaultAppRequirement, RequirementResolver<AdaptiveContextBase, AdaptiveStep>>;
+/**
+ * Build a requirement graph from a requirement list, resolver map, and optional graph metadata.
+ *
+ * The function validates that dependencies refer to known resolver-backed requirements and
+ * rejects circular dependency chains at graph creation time.
+ */
 declare function createRequirementGraph<TContext, TRequirement extends string, TStep extends string>(requirements: readonly TRequirement[], resolvers: Partial<Record<TRequirement, RequirementResolver<TContext, TStep>>>, options?: {
     priorities?: Partial<Record<TRequirement, number>>;
     conditions?: Partial<Record<TRequirement, (context: TContext) => MaybePromise<boolean>>>;
     dependencies?: Partial<Record<TRequirement, readonly TRequirement[]>>;
 }): RequirementGraph<TContext, TRequirement, TStep>;
+/**
+ * Build a requirement graph using the built-in default resolvers plus any app-specific overrides.
+ */
 declare function createDefaultRequirementGraph<TContext extends AdaptiveContextBase = AdaptiveContextBase, TRequirement extends string = DefaultAppRequirement, TStep extends string = AdaptiveStep>(options?: {
     requirements?: readonly TRequirement[];
     resolvers?: Partial<Record<TRequirement, RequirementResolver<TContext, TStep>>>;
@@ -63,10 +94,25 @@ declare function createDefaultRequirementGraph<TContext extends AdaptiveContextB
     conditions?: Partial<Record<TRequirement, (context: TContext) => MaybePromise<boolean>>>;
     dependencies?: Partial<Record<TRequirement, readonly TRequirement[]>>;
 }): RequirementGraph<TContext, TRequirement, TStep>;
+/**
+ * Evaluate the graph against the current context and return the next unmet step.
+ *
+ * Nodes are evaluated in dependency-aware order with deterministic tie-breaking.
+ */
 declare function evaluateNextStep<TContext, TRequirement extends string, TStep extends string>(context: TContext, graph: RequirementGraph<TContext, TRequirement, TStep>, completeStep: TStep): Promise<TStep>;
+/**
+ * Return every unmet requirement for the current context in graph evaluation order.
+ */
 declare function getMissingRequirements<TContext, TRequirement extends string, TStep extends string>(context: TContext, graph: RequirementGraph<TContext, TRequirement, TStep>): Promise<TRequirement[]>;
 
-type OAuthProvider = "google" | "apple";
+/** Supported OAuth provider identifiers accepted by the adapter and default UI. */
+type OAuthProvider = "google" | "apple" | (string & {});
+/** Configurable OAuth provider label/id pair used by the default footer buttons. */
+type AdaptiveFlowOAuthProvider = {
+    id: OAuthProvider | (string & {});
+    label: string;
+};
+/** Result returned by lookupByEmail to seed the flow with backend identity state. */
 type IdentityResolution = {
     accountExists: boolean;
     hasPassword?: boolean;
@@ -74,6 +120,7 @@ type IdentityResolution = {
     agreedToTos?: boolean;
     profile?: Partial<AdaptiveContextBase["profile"]>;
 };
+/** Backend adapter contract used by the flow to delegate all side effects. */
 type AdaptiveFlowAdapter<TContext extends AdaptiveContextBase = AdaptiveContextBase> = {
     lookupByEmail?: (email: string) => Promise<IdentityResolution | null>;
     requestOtp?: (email: string) => Promise<void>;
@@ -85,47 +132,100 @@ type AdaptiveFlowAdapter<TContext extends AdaptiveContextBase = AdaptiveContextB
     startOAuth?: (provider: OAuthProvider, context: TContext) => Promise<void>;
     completeOAuth?: (provider: OAuthProvider | null, context: TContext) => Promise<Partial<TContext> | void>;
 };
+/** Named style slots used by the built-in component shell and step renderers. */
 type AdaptiveFlowStyleSlot = "shell" | "headerRow" | "eyebrow" | "title" | "badge" | "success" | "error" | "info" | "caption" | "formRow" | "formColumn" | "input" | "button" | "checkboxRow" | "complete" | "footer" | "oauthButton";
+/** Inline style overrides keyed by the built-in style slots. */
 type AdaptiveFlowStyles = Partial<Record<AdaptiveFlowStyleSlot, React.CSSProperties>>;
+/** CSS class overrides keyed by the built-in style slots. */
 type AdaptiveFlowClassNames = Partial<Record<AdaptiveFlowStyleSlot, string>>;
+/** Minimal storage interface used by persistence drivers. */
 type AdaptiveFlowStorageDriver = Pick<Storage, "getItem" | "setItem" | "removeItem">;
+/** Persistence settings for storing and restoring flow state across reloads. */
 type AdaptiveFlowPersistence<TContext extends AdaptiveContextBase = AdaptiveContextBase> = {
     key: string;
     storage?: "session" | "local" | AdaptiveFlowStorageDriver;
     serialize?: (state: PersistedAdaptiveFlowState<TContext>) => string;
     deserialize?: (value: string) => PersistedAdaptiveFlowState<TContext>;
     clearOnComplete?: boolean;
+    onError?: (error: Error, phase: "read" | "write" | "clear") => void;
 };
+/** Persisted flow payload written to session/local/custom storage. */
 type PersistedAdaptiveFlowState<TContext extends AdaptiveContextBase = AdaptiveContextBase> = {
     context: TContext;
     oauthPendingProvider: OAuthProvider | null;
 };
+/** Context wrapper passed into validators so they can inspect the current flow state. */
 type AdaptiveFlowValidationContext<TContext extends AdaptiveContextBase = AdaptiveContextBase> = {
     context: TContext;
 };
+/** Validator failure payload that can target a specific field or the whole form. */
+type AdaptiveFlowValidationIssue = {
+    message: string;
+    field?: string;
+};
+/** Validator return type supported by the component and hook. */
+type AdaptiveFlowValidationResult = string | AdaptiveFlowValidationIssue | void | Promise<string | AdaptiveFlowValidationIssue | void>;
+/** Schema adapter contract used for optional Zod-friendly validation. */
+type AdaptiveFlowSchema<TValue> = {
+    safeParse?: (value: TValue) => {
+        success: boolean;
+        error?: {
+            message?: string;
+            issues?: Array<{
+                message?: string;
+                path?: Array<string | number>;
+            }>;
+        };
+    };
+    parse?: (value: TValue) => unknown;
+};
+/** Optional schema map for built-in step fields. */
+type AdaptiveFlowSchemas = {
+    email?: AdaptiveFlowSchema<string>;
+    otp?: AdaptiveFlowSchema<string>;
+    password?: AdaptiveFlowSchema<string>;
+    profile?: AdaptiveFlowSchema<AdaptiveContextBase["profile"]>;
+    tos?: AdaptiveFlowSchema<boolean>;
+};
+/** Backoff settings used to retry transient adapter calls and OAuth completion. */
+type AdaptiveFlowRetryPolicy = {
+    maxAttempts?: number;
+    initialDelayMs?: number;
+    factor?: number;
+    maxDelayMs?: number;
+    jitter?: boolean;
+    shouldRetry?: (error: Error, attempt: number) => boolean;
+    delay?: (attempt: number) => number;
+};
+/** Field error bag keyed by field path or logical field name. */
+type AdaptiveFlowFieldErrors = Partial<Record<string, string>>;
+/** Validator map for the built-in flow fields. */
 type AdaptiveFlowValidators<TContext extends AdaptiveContextBase = AdaptiveContextBase> = {
-    email?: (input: string, payload: AdaptiveFlowValidationContext<TContext>) => string | void | Promise<string | void>;
+    email?: (input: string, payload: AdaptiveFlowValidationContext<TContext>) => AdaptiveFlowValidationResult;
     otp?: (input: string, payload: AdaptiveFlowValidationContext<TContext> & {
         email: string;
-    }) => string | void | Promise<string | void>;
+    }) => AdaptiveFlowValidationResult;
     password?: (input: string, payload: AdaptiveFlowValidationContext<TContext> & {
         hasPassword: boolean;
-    }) => string | void | Promise<string | void>;
-    profile?: (input: AdaptiveContextBase["profile"], payload: AdaptiveFlowValidationContext<TContext>) => string | void | Promise<string | void>;
-    tos?: (accepted: boolean, payload: AdaptiveFlowValidationContext<TContext>) => string | void | Promise<string | void>;
+    }) => AdaptiveFlowValidationResult;
+    profile?: (input: AdaptiveContextBase["profile"], payload: AdaptiveFlowValidationContext<TContext>) => AdaptiveFlowValidationResult;
+    tos?: (accepted: boolean, payload: AdaptiveFlowValidationContext<TContext>) => AdaptiveFlowValidationResult;
 };
+/** Transition record emitted whenever the evaluated step changes. */
 type AdaptiveStepTransition<TStep extends string = AdaptiveStep> = {
     from: TStep | null;
     to: TStep;
     at: number;
     attempt: number;
 };
+/** Arguments supplied to a stepRegistry renderer for a specific step. */
 type AdaptiveStepRendererArgs<TContext extends AdaptiveContextBase, TRequirement extends string, TStep extends string> = {
     step: TStep;
     context: TContext;
     busy: boolean;
     message: string | null;
     errorMessage: string | null;
+    fieldErrors: AdaptiveFlowFieldErrors;
     missingRequirements: TRequirement[];
     requirements: readonly TRequirement[];
     setContextPatch: (patch: Partial<TContext>) => void;
@@ -133,13 +233,16 @@ type AdaptiveStepRendererArgs<TContext extends AdaptiveContextBase, TRequirement
     adapter?: AdaptiveFlowAdapter<TContext>;
     transitions: AdaptiveStepTransition<TStep>[];
 };
+/** Registry that overrides the UI for selected steps. */
 type AdaptiveStepRegistry<TContext extends AdaptiveContextBase, TRequirement extends string, TStep extends string> = Partial<Record<TStep, (args: AdaptiveStepRendererArgs<TContext, TRequirement, TStep>) => React.ReactNode>>;
+/** Arguments supplied to renderStep for full step-body customization. */
 type AdaptiveStepRenderArgs<TContext extends AdaptiveContextBase = AdaptiveContextBase, TRequirement extends string = AppRequirement, TStep extends string = AdaptiveStep> = {
     step: TStep;
     context: TContext;
     busy: boolean;
     message: string | null;
     errorMessage: string | null;
+    fieldErrors: AdaptiveFlowFieldErrors;
     missingRequirements: TRequirement[];
     requirements: readonly TRequirement[];
     defaultView: React.ReactNode;
@@ -148,6 +251,7 @@ type AdaptiveStepRenderArgs<TContext extends AdaptiveContextBase = AdaptiveConte
     adapter?: AdaptiveFlowAdapter<TContext>;
     transitions: AdaptiveStepTransition<TStep>[];
 };
+/** Props accepted by the AdaptiveFlow component. */
 type AdaptiveFlowProps<TContext extends AdaptiveContextBase = AdaptiveContext, TRequirement extends string = AppRequirement, TStep extends string = AdaptiveStep> = {
     adapter?: AdaptiveFlowAdapter<TContext>;
     requirements?: readonly TRequirement[];
@@ -172,7 +276,36 @@ type AdaptiveFlowProps<TContext extends AdaptiveContextBase = AdaptiveContext, T
     unstyled?: boolean;
     persistence?: AdaptiveFlowPersistence<TContext>;
     validators?: AdaptiveFlowValidators<TContext>;
+    schemas?: AdaptiveFlowSchemas;
+    oauthProviders?: readonly AdaptiveFlowOAuthProvider[];
+    retryPolicy?: AdaptiveFlowRetryPolicy;
+};
+/** Options accepted by the headless useAdaptiveFlow hook. */
+type UseAdaptiveFlowOptions<TContext extends AdaptiveContextBase = AdaptiveContext, TRequirement extends string = AppRequirement, TStep extends string = AdaptiveStep> = Omit<AdaptiveFlowProps<TContext, TRequirement, TStep>, "stepTitles" | "renderStep" | "stepRegistry" | "className" | "classNames" | "styles" | "unstyled">;
+/** Result object returned by useAdaptiveFlow. */
+type UseAdaptiveFlowResult<TContext extends AdaptiveContextBase, TRequirement extends string, TStep extends string> = {
+    context: TContext;
+    step: TStep;
+    completeStep: TStep;
+    requirements: readonly TRequirement[];
+    missingRequirements: TRequirement[];
+    transitions: AdaptiveStepTransition<TStep>[];
+    busy: boolean;
+    message: string | null;
+    errorMessage: string | null;
+    fieldErrors: AdaptiveFlowFieldErrors;
+    setContextPatch: (patch: Partial<TContext>) => void;
+    run: (job: () => Promise<void>) => Promise<void>;
+    handleEmail: (emailInput: string) => void;
+    handleOtp: (code: string) => void;
+    handlePassword: (password: string) => void;
+    handleProfile: (profile: AdaptiveContextBase["profile"]) => void;
+    handleTos: () => void;
+    handleOAuth: (provider: OAuthProvider) => void;
 };
-declare function AdaptiveFlow<TContext extends AdaptiveContextBase = AdaptiveContext, TRequirement extends string = AppRequirement, TStep extends string = AdaptiveStep>({ adapter, requirements, requirementGraph, requirementGraphConfig, requirementResolvers, completeStep, stepTitles, renderStep, stepRegistry, initialValue, onComplete, onError, onStepTransition, className, classNames, styles, unstyled, persistence, validators, }: AdaptiveFlowProps<TContext, TRequirement, TStep>): react_jsx_runtime.JSX.Element;
+/** Headless flow hook that owns state, evaluation, persistence, retries, and adapter wiring. */
+declare function useAdaptiveFlow<TContext extends AdaptiveContextBase = AdaptiveContext, TRequirement extends string = AppRequirement, TStep extends string = AdaptiveStep>({ adapter, requirements, requirementGraph, requirementGraphConfig, requirementResolvers, completeStep, initialValue, onComplete, onError, onStepTransition, persistence, validators, schemas, oauthProviders, retryPolicy, }: UseAdaptiveFlowOptions<TContext, TRequirement, TStep>): UseAdaptiveFlowResult<TContext, TRequirement, TStep>;
+/** Default UI wrapper around useAdaptiveFlow that renders the built-in flow shell and step UI. */
+declare function AdaptiveFlow<TContext extends AdaptiveContextBase = AdaptiveContext, TRequirement extends string = AppRequirement, TStep extends string = AdaptiveStep>({ adapter, requirements, requirementGraph, requirementGraphConfig, requirementResolvers, completeStep, stepTitles, renderStep, stepRegistry, initialValue, onComplete, onError, onStepTransition, className, classNames, styles, unstyled, persistence, validators, schemas, oauthProviders, retryPolicy, }: AdaptiveFlowProps<TContext, TRequirement, TStep>): react_jsx_runtime.JSX.Element;
 
-export { type AdaptiveContext, type AdaptiveContextBase, AdaptiveFlow, type AdaptiveFlowAdapter, type AdaptiveFlowClassNames, type AdaptiveFlowPersistence, type AdaptiveFlowProps, type AdaptiveFlowStorageDriver, type AdaptiveFlowStyleSlot, type AdaptiveFlowStyles, type AdaptiveFlowValidationContext, type AdaptiveFlowValidators, type AdaptiveStep, type AdaptiveStepRegistry, type AdaptiveStepRenderArgs, type AdaptiveStepRendererArgs, type AdaptiveStepTransition, type AppRequirement, type DefaultAdaptiveStep, DefaultAdaptiveSteps, type DefaultAppRequirement, DefaultAppRequirements, type IdentityResolution, type MaybePromise, type OAuthProvider, type PersistedAdaptiveFlowState, type RequirementGraph, type RequirementGraphNode, type RequirementResolver, createDefaultRequirementGraph, createRequirementGraph, defaultRequirementResolvers, defaultRequirements, evaluateNextStep, getMissingRequirements, initialContext };
+export { type AdaptiveContext, type AdaptiveContextBase, AdaptiveFlow, type AdaptiveFlowAdapter, type AdaptiveFlowClassNames, type AdaptiveFlowFieldErrors, type AdaptiveFlowOAuthProvider, type AdaptiveFlowPersistence, type AdaptiveFlowProps, type AdaptiveFlowRetryPolicy, type AdaptiveFlowSchema, type AdaptiveFlowSchemas, type AdaptiveFlowStorageDriver, type AdaptiveFlowStyleSlot, type AdaptiveFlowStyles, type AdaptiveFlowValidationContext, type AdaptiveFlowValidationIssue, type AdaptiveFlowValidationResult, type AdaptiveFlowValidators, type AdaptiveStep, type AdaptiveStepRegistry, type AdaptiveStepRenderArgs, type AdaptiveStepRendererArgs, type AdaptiveStepTransition, type AppRequirement, type DefaultAdaptiveStep, DefaultAdaptiveSteps, type DefaultAppRequirement, DefaultAppRequirements, type IdentityResolution, type MaybePromise, type OAuthProvider, type PersistedAdaptiveFlowState, type RequirementGraph, type RequirementGraphNode, type RequirementResolver, type UseAdaptiveFlowOptions, type UseAdaptiveFlowResult, createDefaultRequirementGraph, createRequirementGraph, defaultRequirementResolvers, defaultRequirements, evaluateNextStep, getMissingRequirements, initialContext, useAdaptiveFlow };